docs(plans): re-cast Phase 4-7 to stateless scraper-APIs, flatten subplans

plans/backend/05-access.md

@@ -0,0 +1,85 @@
+# Phase 5 — Access / Surfaces (REST · MCP · chat doors)
+
+> Build after `04`. Together `04 + 05` ship the scraper-API product.
+> Reuses shipped infra: Identity/Tenancy, API keys, the chat agent + tool registry, the streaming layer,
+> Metering (`03c`), and Rocicorp Zero reactive sync. Locate code by symbol/grep.
+
+## Objective
+
+Expose the `04` capability registry through three doors — REST + API keys, an MCP server, and chat tools —
+each generated from the one registry so the I/O contract can't drift. Every door is the same thin adapter
+with no business logic.
+
+## Adapter shape (identical on every door)
+
+```
+parse input → validate against verb.input_schema → authn/authz → meter-gate (03c)
+  → call the SAME executor (04) → serialize verb.output_schema → return cleaned data
+```
+
+The executor returns directly (`04`).
+
+## The three doors
+
+| Door | Who | Auth | Status |
+|------|-----|------|--------|
+| REST + API keys | external developers | existing API-key infra | public day one |
+| MCP server | external agents (Cursor/ChatGPT/Claude) | OAuth 2.1 or bearer (at implementation) | fast-follow |
+| Chat tools | the in-app agent (`07`) | existing session + workspace | seed exists (`scrape_webpage`) |
+
+Routes are generated, so public REST on day one costs nothing extra.
+
+## Chat surface
+
+The in-app product is the conversation: the user describes a need in plain language and the agent (`07`)
+picks and fills verbs. Raw typed verbs are exposed on REST/MCP for devs and external agents. The chat
+door classifies intent and routes:
+
+```
+"find / compare / what is / pull / right now"          → ONE-SHOT      → call verbs, answer now
+"watch / track / notify me / keep an eye / over time"  → KEEP-WATCHING → hand to the ongoing mode (06)
+```
+
+## MCP — two directions
+
+- **Serve MCP** (new door): our capabilities as a remote MCP server — Streamable-HTTP `/mcp`, stateless,
+  bounded/paginated outputs, read-only verbs (least privilege).
+- **Consume MCP** (reuse): the BYO-`MCP_CONNECTOR` — the user's own external MCP tools inside our chat
+  agent. Fix its routing-map gap here.
+
+## Result delivery
+
+A chat tool call returns its data inline in the turn. Asynchronous results (e.g. the `06` ongoing mode
+writing between turns) reach the client via write-then-sync / stream: the worker writes rows and the
+client receives them over the existing SSE stream or a Zero-published table.
+
+## Work items
+
+1. Door generator: from the `04` registry emit (a) REST routes + models, (b) MCP tool schemas + handlers,
+   (c) chat tool defs + handlers.
+2. REST surface: public routes + API-key auth (reuse) + `03c` meter-gate.
+3. Chat tools: generalize `scrape_webpage` into the registry-backed set (direct-return).
+4. Intent routing: classify one-shot vs keep-watching; hand keep-watching to `06`.
+5. MCP server (fast-follow): Streamable-HTTP `/mcp`, least-privilege; auth depth at implementation.
+6. Consume-MCP fix: repair the BYO-`MCP_CONNECTOR` routing-map gap.
+
+## Tests
+
+- A verb added to the registry appears on REST + MCP + chat with identical I/O.
+- REST without a valid key → 401; an over-budget call → blocked by the `03c` gate; a success charges once.
+- A chat scrape returns cleaned data inline in the same turn.
+- "compare X and Y" → one-shot; "watch X weekly" → routed to `06`.
+- A configured BYO MCP tool is reachable by the chat agent.
+
+## Out of scope
+
+- Verbs, executors, billing units → `04`.
+- Keep-watching mechanism + its delivery channel → `06`.
+- The CI subagent + its prompt → `07`.
+- Legacy branded connectors (backward-compat hygiene, separate task).
+
+## Open questions
+
+- MCP auth depth (decide at implementation).
+- Public REST rate-limiting / abuse posture.
+- Async delivery channel for `06` outputs: SSE stream vs Zero-published messages table (settled with `06`).