From a84b96f1dcfb1ecbf83d8472b306b4f2cf857507 Mon Sep 17 00:00:00 2001 From: matcha Date: Sun, 4 Oct 2026 03:23:55 +0000 Subject: [PATCH] Document Phast v0 product contract --- README.md | 39 +++++++++++++++++++++++++++++++++------ 1 file changed, 33 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 4cda70a..8540fbd 100644 --- a/README.md +++ b/README.md @@ -2,10 +2,37 @@ Canonical source of truth for Phast. -- `phast.app` is the public product surface. -- `my.phast.app` is the owner/control surface. -- This repository owns Phast product source and web assets. -- Phast does not own a standalone Fly app and must not be embedded in the Boring runtime. -- Public web bytes are served from the Teahub Gitea/Pages machine, following the same source-owned pattern as `matcha/persimmons`. +> **Connect your tools once. Bring your tool belt anywhere.** -The Python control-plane source is retained here as product source. Live backend publication is a separate concern from static site publication and must not silently couple Phast back into Boring. +Phast gives a person one portable MCP plus a programmable Prefab home. Connect `my.phast.app/mcp` to an agent to create and manage Phasts. A created Phast has two matching surfaces: + +- `user.phast.app` — human / Prefab home +- `user.phast.app/mcp` — the user's portable MCP tool belt + +## V0 contract + +`phast.json` is deliberately boring. It is mostly: + +1. the MCP tool list and provider connections; +2. references to delegated credential authority (Persimmons, never raw secrets); +3. Prefab home/widget settings. + +The browser and chat are two editors for the same declaration. + +### Browser flow + +Home → Edit Home → Add Widget → provider search → connect if necessary → place/configure widget. + +### Agent flow + +Connect once to `my.phast.app/mcp` → create/manage `user.phast.app` → search providers → add tools/widgets → stream/taste-test Prefab in chat → persist accepted UI to the same `phast.json`. + +## Boundaries + +- **Phast composes.** It owns the portable MCP/tool belt and Prefab composition. +- **Oracle discovers.** Provider/MCP/OAuth discovery comes from the capability graph, not a hard-coded Phast directory. +- **Persimmons holds secrets.** Phast stores connection/authority references, not secret values. +- **Factory builds/operates.** Provisioning uses bounded deterministic infrastructure routes. +- **Clients are replaceable.** ChatGPT, Claude, Codex, or another MCP client should be able to use the same Phast without recollecting the user's tools. + +V0 is intentionally not arbitrary app generation. Prove the portable-tool-belt + editable-home loop first.