Document Phast v0 product contract

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.