@terreno/mcp 57.21.0 → 58.0.0-beta.2

package/src/docs/versioned/57.21.0/regression/README.md

@@ -0,0 +1,87 @@
+# Regression suites
+
+Run `bun run check:regression-suites` after you edit any file here. CI runs the same check in
+the `repo-policies` job.
+
+These files hold a minimal manual pass a developer or QA walks before a release: a short check
+that the app works as intended, plus the behavior no unit test, smoke, or e2e spec can reach,
+such as push notifications, real email delivery, other hardware or operating-system behavior,
+full flows across devices, and how the app feels. Keep them small. Most features add no case
+here, and anything an e2e spec can drive and assert belongs in an e2e spec instead. Each area
+has one living file. Implementation plans
+propose cases under `## Regression cases`, and Brew writes them here with real IDs before it
+opens the pull request. See [Where regression suites live](../testing/e2e.md#where-regression-suites-live)
+for how this tier fits with the automated ones.
+
+## Areas
+
+| File | Area | Covers |
+| --- | --- | --- |
+| [planning.md](planning.md) | `PLAN` | Retired: planning-stage checks, kept so their IDs are never reused |
+| [auth.md](auth.md) | `AUTH` | Email delivery for password reset and verification, and native session storage |
+| [admin.md](admin.md) | `ADMIN` | Admin edits and announcements seen live on a phone |
+| [syncdb.md](syncdb.md) | `SYNC` | Offline writes, persistence across an app kill, and account switches on a device |
+| [ui-native.md](ui-native.md) | `NATIVE` | Notification permission prompts, finger-drawn signatures, and keyboard behavior on iOS and Android |
+
+## Suite format
+
+Every file follows the same shape:
+
+```markdown
+# Auth regression suite
+
+Area: AUTH
+Owner: <team or person>
+Last full run: 2026-01-15 (<who>, <short sha>)
+
+| ID | Case | Steps | Expected | Platforms | Automated by | Added |
+| --- | --- | --- | --- | --- | --- | --- |
+| AUTH-001 | ... | ... | ... | ... | manual | <IP slug> |
+```
+
+- **Title** is the first line, a `#` heading.
+- **`Area:`** declares the ID prefix: uppercase letters and digits. Find a suite by this line,
+  not by its file name. No two files declare the same area.
+- **`Owner:`** names the team or person who keeps the file current.
+- **`Last full run:`** is `never`, or the date, who walked it, and the short commit SHA. Change
+  it only after a person walks every case in the file.
+- **IDs** are `<AREA>-NNN`, zero-padded to three digits, and never reused. The next free ID is
+  one past the highest the file has ever held. A retired case keeps its row with `Retired` in
+  `Expected`. Provisional IP IDs such as `AUTH-new-1` never appear here.
+- **Steps** name a concrete starting state (who is signed in, what data exists, which build or
+  device), then an action a person can follow without guessing.
+- **Expected** is observable: what is on screen, in the inbox, or in the response. "It works"
+  or a restatement of the action does not count.
+- **Automated by** is `manual` or the path of the spec that covers the case. It never names an
+  IP-local `E<n>` row.
+- **Added** is the slug of the implementation plan that added the case.
+
+Escape a literal pipe inside a cell as `\|`.
+
+## What the check enforces
+
+`scripts/regression/checkSuites.ts` reads every `.md` file here except this README and fails
+when a file:
+
+- lacks the title, `Area:`, `Owner:`, or `Last full run:` line, or one of them is malformed
+- has a table whose columns differ from the seven above, or more than one table
+- has a row with the wrong number of cells, an ID that is not `<AREA>-NNN`, a `-new-` ID, or a
+  duplicate ID
+- has an empty cell, including Steps and Expected
+- names an `E<n>` row in Automated by
+
+It also fails when two files declare the same area. It does not judge whether a step meets the
+bar above; reviewers do.
+
+## Add a case
+
+1. Open the area's file, or create `<area>.md` with `Last full run: never` and an `Owner:`.
+2. Add a row with the next free ID.
+3. Run `bun run check:regression-suites`.
+
+## Backfill the suites
+
+To find cases an older feature should have had, run the `backfill-regression` skill. It
+surveys the app for behavior automation cannot reach, proposes cases one area at a time, and
+writes only the sets you approve. It records denied cases in
+`.terreno/regression-backfill.json` (not committed) so it never proposes them again.

package/src/docs/versioned/57.21.0/regression/admin.md

@@ -0,0 +1,13 @@
+# Admin regression suite
+
+Area: ADMIN
+Owner: Josh Gachnang
+Last full run: never
+
+Walk these cases with an admin account on web and a second, non-admin account signed in on a
+phone. Both run against the same deployed example-backend.
+
+| ID | Case | Steps | Expected | Platforms | Automated by | Added |
+| --- | --- | --- | --- | --- | --- | --- |
+| ADMIN-001 | An admin edit reaches the owner's phone live | A non-admin user is signed in on a phone with the Todos tab open and one todo titled "Buy milk". On web, an admin opens the Admin Panel, opens that todo, changes its title to "Buy oat milk", and saves | Within 10 seconds, without pulling to refresh or reopening the app, the phone's Todos list shows "Buy oat milk" | iOS, Android | manual | e2e-and-regression-testing |
+| ADMIN-002 | A published announcement shows on a phone | A non-admin user is signed in on a phone. On web, an admin creates and publishes an announcement from the Admin Panel, then the user force quits and reopens the app | The announcement shows once on the phone with the admin's title and body, and does not show again after it is dismissed and the app is reopened | iOS, Android | manual | e2e-and-regression-testing |

package/src/docs/versioned/57.21.0/regression/auth.md

@@ -0,0 +1,15 @@
+# Auth regression suite
+
+Area: AUTH
+Owner: Josh Gachnang
+Last full run: never
+
+Walk these cases against example-frontend and example-backend on a deployed environment whose
+backend sends real email. Use an inbox you can open, not a seeded `@example.com` address.
+
+| ID | Case | Steps | Expected | Platforms | Automated by | Added |
+| --- | --- | --- | --- | --- | --- | --- |
+| AUTH-001 | Password reset email reaches a real inbox | Signed out, with an account whose email is a real inbox you can open: on the login screen tap the forgot-password link, enter that email, tap "Send reset link", open the email, follow its link, enter a new password, tap "Save new password", then sign in with the new password | One reset email arrives within 2 minutes from the configured sender. Its link opens the "Reset password" screen in the app. Sign-in with the new password lands on Todos, and sign-in with the old password shows an error | Web, iOS, Android | manual | e2e-and-regression-testing |
+| AUTH-002 | Verification email confirms the account | Signed in as a new account with a real inbox that has not verified its email: open Profile, tap "Resend" on the verify-email banner, open the email, follow its link, tap "Confirm email", then reopen Profile | One verification email arrives within 2 minutes. After confirming, Profile no longer shows the "Verify your email" banner | Web, iOS, Android | manual | e2e-and-regression-testing |
+| AUTH-003 | Session survives a force quit on a device | Signed in on a release build on a phone, with at least one todo: force quit the app from the app switcher, wait 10 seconds, then open it again | The app opens on Todos with the same todos and no login screen, because the session is read back from the device's secure storage | iOS, Android | manual | e2e-and-regression-testing |
+| AUTH-004 | Logout clears the stored session on a device | Signed in on a release build on a phone: open Profile, tap "Logout", force quit the app, then open it again | The app opens on the login screen, and no data from the previous account shows before sign-in | iOS, Android | manual | e2e-and-regression-testing |

package/src/docs/versioned/57.21.0/regression/planning.md

@@ -0,0 +1,16 @@
+# Planning regression suite
+
+Area: PLAN
+Owner: Josh Gachnang
+Last full run: never
+
+Every case here is retired: they checked agent behavior, not the app, which the minimal
+regression rule leaves out. The rows stay so their IDs are never reused.
+
+| ID | Case | Steps | Expected | Platforms | Automated by | Added |
+| --- | --- | --- | --- | --- | --- | --- |
+| PLAN-001 | Grow plans e2e and regression | In a fresh session in a repo that has `docs/testing/e2e.md`, run Grow on "add a due date to todos" and approve it | Retired: an agent-behavior check, not an app check | Claude Code, Cursor, Codex | manual | e2e-and-regression-testing |
+| PLAN-002 | Grow without a guide | Repeat PLAN-001 in a repo with no `docs/testing/e2e.md` and no Testing conventions table | Retired: an agent-behavior check, not an app check | Claude Code | manual | e2e-and-regression-testing |
+| PLAN-003 | Brew writes the suite | Take an approved IP with one regression case through Brew | Retired: an agent-behavior check, not an app check | Claude Code | manual | e2e-and-regression-testing |
+| PLAN-004 | Pick writes, Roast enforces a planned spec | Run Pick on a PLAN-001 task that owns an `## E2E tests` row. Then delete the spec file and run Roast | Retired: an agent-behavior check, not an app check | Claude Code | manual | e2e-and-regression-testing |
+| PLAN-005 | Taste renumbers a collision | On a branch that added `AUTH-00N`, merge a master commit that also added `AUTH-00N`, then run Taste | Retired: an agent-behavior check, not an app check | Claude Code | manual | e2e-and-regression-testing |

package/src/docs/versioned/57.21.0/regression/syncdb.md

@@ -0,0 +1,15 @@
+# SyncDB regression suite
+
+Area: SYNC
+Owner: Josh Gachnang
+Last full run: never
+
+Walk these cases on a release build on a physical phone, against a deployed example-backend.
+Turn the network off with airplane mode, not by stopping the backend, so the operating system
+reports the device as offline.
+
+| ID | Case | Steps | Expected | Platforms | Automated by | Added |
+| --- | --- | --- | --- | --- | --- | --- |
+| SYNC-001 | An offline edit replays after airplane mode | Signed in on a phone with the Todos tab open and one todo, and the same account open on web: turn on airplane mode, mark the todo complete, wait 30 seconds, then turn airplane mode off | The phone shows the todo complete at once while offline. Within 10 seconds of reconnecting, web shows it complete without a reload, and the phone shows no conflict | iOS, Android | manual | e2e-and-regression-testing |
+| SYNC-002 | An offline create survives a force quit | Signed in on a phone in airplane mode: create a todo titled "Offline note", force quit the app, reopen it still in airplane mode, then turn airplane mode off | After reopening offline the list still shows "Offline note". After reconnecting it appears on web for the same account within 10 seconds, exactly once | iOS, Android | manual | e2e-and-regression-testing |
+| SYNC-003 | Switching accounts on one phone leaks no rows | Signed in on a phone as user A with at least two todos: open Profile, tap "Logout", then sign in as user B, who has no todos | User B's Todos tab is empty, both before and after the first sync completes. None of user A's todos appear at any point | iOS, Android | manual | e2e-and-regression-testing |

package/src/docs/versioned/57.21.0/regression/ui-native.md

@@ -0,0 +1,16 @@
+# Native UI regression suite
+
+Area: NATIVE
+Owner: Josh Gachnang
+Last full run: never
+
+Walk these cases on a fresh install on a physical phone. Delete the app first so the operating
+system asks for each permission again. NATIVE-001 and NATIVE-002 need a development build,
+because Profile shows "Send test push" only in development builds; the others run on either.
+
+| ID | Case | Steps | Expected | Platforms | Automated by | Added |
+| --- | --- | --- | --- | --- | --- | --- |
+| NATIVE-001 | Allowing notifications enables push | On a fresh install of a development build, sign in, tap Allow on the system notification prompt, open Profile, tap "Send test push", then lock the phone | The system prompt appears once, right after sign-in. A test notification shows on the lock screen within 1 minute | iOS, Android | manual | e2e-and-regression-testing |
+| NATIVE-002 | Denying notifications registers no device | On a fresh install of a development build, sign in as an account with no other signed-in devices, tap Don't Allow on the system notification prompt, then open Profile and tap "Send test push" | The app keeps working on Todos. Profile shows "No registered push tokens for this account." under the push button, and the prompt does not reappear on the next launch | iOS, Android | manual | e2e-and-regression-testing |
+| NATIVE-003 | A consent signature can be drawn with a finger | On a fresh install, sign in as an account that has never accepted the consent forms. On each consent screen that asks for a signature, draw a signature with one finger, then accept every form | The stroke follows the finger and the screen does not scroll while drawing. After the last form the app opens on Todos, and after a force quit and reopen no consent screen shows again | iOS, Android | manual | e2e-and-regression-testing |
+| NATIVE-004 | The keyboard does not cover a focused field | Signed in on a phone in portrait: open Profile, scroll to the "API Key" field in the Gemini API Key card, and tap it | The keyboard opens and the focused field stays visible above it, with its "API Key" label on screen | iOS, Android | manual | e2e-and-regression-testing |

package/src/docs/versioned/57.21.0/tasks/ai-dev-loop-boost.md

@@ -0,0 +1,132 @@
+# Task List: The AI Development Loop (Boost)
+
+See: [`docs/implementationPlans/ai-dev-loop-boost.md`](../implementationPlans/ai-dev-loop-boost.md)
+
+**RTK deprecation flag:** **Partial.** Tasks marked `[RTK]` rename `get_rtk_state` and relocate `installTerrenoDevConsoleLogger`; they require PR #869 merged in addition to PR #802. Unmarked tasks require only #802.
+
+## Instructions for the implementing agent
+
+- **Phase 1 gates everything.** PR #802 was in draft when this IP was written. Verify every tool name, parameter, and environment variable against the merged source in `mcp-server/src/local/` and `mcp-server/src/tools.ts` before documenting anything.
+- Every tool output shown in documentation must be real output from a real run, not a plausible-looking example.
+- Do not add new MCP tools. This IP documents and renames; it does not expand the surface.
+- Run `bun run mcp:build`, `bun run lint`, and `bun run compile` before each commit. Run `bun run rules:check` after touching `.rulesync/`.
+
+## Phase 1: Reconcile with merged #802
+
+- [x] **Task 1.1**: Inventory the actual MCP surface
+  - Description: Read `mcp-server/src/tools.ts`, `mcp-server/src/prompts.ts`, `mcp-server/src/resources.ts`, `mcp-server/src/local/localTools.ts`, and every file under `mcp-server/src/local/tools/`. Produce a table of every tool with its exact name, input schema, and which server hosts it. Separately list every environment variable the servers read (`TERRENO_MCP_EVAL`, `TERRENO_METRO_URL`, `TERRENO_PROJECT_ROOT`, `TERRENO_LOG_FILE`, `TERRENO_BROWSER_LOGS`, and any others found). Compare against the tool table in the IP and correct the IP where it is wrong. Put the deltas in the PR body.
+  - Files: `docs/implementationPlans/ai-dev-loop-boost.md`
+  - Depends on: PR #802 merged
+  - Acceptance: every tool in the corrected table is greppable in the source; every environment variable cites its reading file; the PR body lists what differed from the pre-merge IP.
+
+- [x] **Task 1.2**: Verify the log pipeline end to end
+  - Description: Start the example backend and frontend, then exercise each `read_logs` source and record real output: `backend` (winston JSONL file transport), `app` (console output over Metro CDP), `metro` (bundler events), and `browser` (POST fallback). Deliberately break something to produce an error and confirm `last_error` returns it with a stack. Note which sources required extra setup and what happens when Metro is not running. Save the real outputs for use in the documentation tasks.
+  - Files: none (findings recorded for later tasks)
+  - Depends on: Task 1.1
+  - Acceptance: all four sources produced output, or any that did not is documented with the reason; `last_error` output captured verbatim including a stack trace.
+
+- [x] **Task 1.3**: Reproduce the Hermes CDP contention symptom
+  - Description: With `read_logs` connected and streaming `app` source entries, open React Native DevTools (press `j` in Metro) and observe what happens to the log tool. Record the exact status message or failure the tool reports. Then close DevTools and confirm whether the tool recovers automatically. This becomes the documented symptom and workaround.
+  - Files: none (findings recorded for later tasks)
+  - Depends on: Task 1.2
+  - Acceptance: the symptom is recorded verbatim; recovery behavior (automatic or requiring a retry) is confirmed by observation.
+
+## Phase 2: Reference completeness
+
+- [x] **Task 2.1**: Update `docs/reference/mcp-server.md`
+  - Description: Rewrite the tool sections to match the Task 1.1 inventory exactly. Split clearly into "Hosted server (`terreno-mcp`)" and "Local server (`terreno-mcp-local`)" sections. For each tool: name, purpose, input schema table, example call, and example output. Add an "Environment variables" section listing every variable from Task 1.1 with its effect and default. Add a "What the local server can and cannot see" section — it reads `package.json`/lockfiles, connects to Mongo via the consumer's `.env`, tails log files, and attaches over CDP; it never imports consumer code. Document the Hermes limitation from Task 1.3. Update the hosted URL per IP question AI6 if the domain decision has been made.
+  - Files: `docs/reference/mcp-server.md`
+  - Depends on: Task 1.1, Task 1.3
+  - Acceptance: tool list matches the inventory one-to-one; every environment variable documented; the can/cannot-see section is present; the Hermes symptom is quoted from Task 1.3.
+
+- [x] **Task 2.2**: Sync `mcp-server/README.md`
+  - Description: Bring the package README's tool list in line with the reference page (it is known to omit `terreno_search_docs`, `terreno_get_component_docs`, and `terreno_get_upgrade_guide`). Keep the README short — the six-section template from [`docs-reference-coverage`](../implementationPlans/docs-reference-coverage.md) — and link the reference page for full detail.
+  - Files: `mcp-server/README.md`
+  - Depends on: Task 2.1
+  - Acceptance: the README and reference page list identical tool sets; the README follows the standard template; all links absolute.
+
+- [x] **Task 2.3**: Document the browser-log route
+  - Description: Add `POST /__terreno/browser-logs` to `docs/reference/api.md` (or the appropriate reference page) documenting: that it is registered only when `NODE_ENV !== "production"`, that it 404s in production, the `TERRENO_BROWSER_LOGS=false` override, the JSONL file it appends to, and the payload shape. Verify all of this against `api/src/browserLogsRoute.ts` in the merged tree.
+  - Files: `docs/reference/api.md`, `docs/reference/environment-variables.md`
+  - Depends on: Task 1.1
+  - Acceptance: every behavior claimed matches `api/src/browserLogsRoute.ts`; the production 404 behavior is stated; the env var appears in the environment reference.
+
+## Phase 3: The loop explainer
+
+- [x] **Task 3.1**: Write `docs/explanation/ai-development-loop.md`
+  - Description: Explainer covering the five stages (Ask, Generate, Run, Observe, Fix) with the mermaid diagram from the IP. For each stage, name the tools involved and what they contribute. Then a "Tool layer versus process layer" section using the table from the IP, stating that this page covers the tool layer and that the `/terreno-*` SDLC pipeline is the process layer, with a link to `docs/explanation/agentic-sdlc.md` — do not duplicate that page's content. Then a "What makes this different" section built on one narrow, defensible claim: the agent observes what the app actually did rather than a description of it. Then a "What the agent cannot see" section — production logs, native crash reports outside the dev loop, anything requiring a physical device not attached to a dev server, and the Hermes single-connection limitation. Then a "How this composes" section covering `expo-mcp` for simulator interaction, Playwright MCP for web, and Maestro for durable E2E flows, with the division of labor. No commands — this is conceptual.
+  - Files: `docs/explanation/ai-development-loop.md` (new), `docs/explanation/README.md`
+  - Depends on: Task 2.1
+  - Acceptance: all five stages present with real tool names from the inventory; the tool/process table is present and links the companion page; the cannot-see section has at least four honest limitations; no shell commands; listed in the explanation index.
+
+- [x] **Task 3.2**: Write `docs/explanation/agent-guidelines.md`
+  - Description: Explainer on how conventions reach an agent: the hosted server's docs resources and search, per-package `.ai/guidelines/` shipped in npm tarballs (verify whether #802 Phase 2 shipped this before documenting it — if not, describe only what exists and note the rest as planned), `terreno_bootstrap_ai_rules` for generating editor-specific rule files, and the `.rulesync/` source-of-truth pattern with its generated targets. Add a section for consumers on extending the generated rules with their own project conventions without losing them on regeneration.
+  - Files: `docs/explanation/agent-guidelines.md` (new), `docs/explanation/README.md`
+  - Depends on: Task 1.1
+  - Acceptance: every mechanism described is verified present in the merged tree, with anything unshipped clearly labeled as planned; the consumer-extension section gives a concrete pattern.
+
+## Phase 4: Setup and debug how-tos
+
+- [x] **Task 4.1**: Write `docs/how-to/set-up-terreno-mcp.md`
+  - Description: Per-editor setup for both Terreno servers. Cover at minimum Cursor (`.cursor/mcp.json`) and Claude Code, with the exact JSON for each including the hosted HTTP entry and the `bunx terreno-mcp-local` stdio entry. Then: what `terreno-mcp-local` needs to work (project root discovery and the `TERRENO_PROJECT_ROOT` override, a reachable `MONGO_URI`, the backend log file, Metro running for app logs); an optional section on adding `expo-mcp` and Playwright MCP with the division of labor from Task 3.1; and a verification section — ask the agent to call `application_info` and confirm it reports the project's `@terreno/*` versions. Compare the JSON against what `terreno_bootstrap_app` actually generates and make them identical.
+  - Files: `docs/how-to/set-up-terreno-mcp.md` (new), `docs/how-to/README.md`
+  - Depends on: Task 2.1
+  - Acceptance: configuration for at least two editors, each verified by actually loading it; the JSON matches bootstrap output byte-for-byte in structure; the `application_info` verification step works.
+
+- [x] **Task 4.2**: Write `docs/how-to/debug-with-mcp.md`
+  - Description: Task-focused guide using the real failure and real outputs captured in Task 1.2. Structure: the symptom; `last_error` to locate it; `read_logs` with source filtering to see the surrounding context; `database_query` to check the data; `get_client_state` to check the client; `navigate` plus a screenshot from the composed server to confirm the fix. Include a "which tool for which symptom" table (app crashes on a screen; API returns 403; data looks wrong; screen renders empty; bundler fails). Use verbatim tool output.
+  - Files: `docs/how-to/debug-with-mcp.md` (new), `docs/how-to/README.md`
+  - Depends on: Task 1.2, Task 4.1
+  - Acceptance: all tool outputs are verbatim from Task 1.2; the symptom-to-tool table has at least five rows; the walkthrough ends with a verified fix.
+
+- [x] **Task 4.3**: Add discovery paths for the local server
+  - Description: Nothing currently tells a developer that `terreno-mcp-local` exists. Add links to `docs/how-to/set-up-terreno-mcp.md` from: the README's MCP section, `docs/README.md` quick links, `docs/tutorials/README.md`, and the `terreno://docs/overview` MCP resource. Also confirm `terreno_bootstrap_app` output includes a comment or README line pointing at the setup guide.
+  - Files: `README.md`, `docs/README.md`, `docs/tutorials/README.md`, `mcp-server/src/docs/resources/overview.md`, `mcp-server/src/docs/templates/bootstrap/**`
+  - Depends on: Task 4.1
+  - Acceptance: at least four discovery paths link the setup guide; bootstrap output references it; `bun run mcp:build` succeeds.
+
+## Phase 5: Gap fixes
+
+- [x] **Task 5.1**: `[RTK]` Rename `get_rtk_state` to `get_client_state`
+  - Description: Per IP question AI1, rename the tool to `get_client_state` and extend it to detect either store type, returning a field identifying which layer it found (RTK Query cache versus syncdb store). Keep `get_rtk_state` registered as an alias whose description marks it deprecated and names the replacement. Update the tool description to explain what it returns for each layer. Add tests covering: syncdb store present, RTK store present, neither present, and the alias resolving to the same handler.
+  - Files: `mcp-server/src/local/tools/runtime.ts`, `mcp-server/src/local/localTools.ts`, tests under `mcp-server/src/local/`
+  - Depends on: Task 1.1, PR #869 merged
+  - Acceptance: both names work; the response identifies the detected layer; the alias description marks it deprecated; all four test cases pass; `bun run mcp:build` succeeds.
+
+- [x] **Task 5.2**: `[RTK]` Relocate the dev console logger
+  - Description: Per IP question AI2, move `installTerrenoDevConsoleLogger` from `rtk/src/devConsoleLogger.ts` to the syncdb package, keeping a re-export from `@terreno/rtk` for the deprecation window so existing consumers are unaffected. Move its tests with it. Update the bootstrap `_layout` template and `example-frontend/app/_layout.tsx` to import from the new location. Add the re-export to the RTK deprecation notes.
+  - Files: `syncdb/src/devConsoleLogger.ts` (moved), `rtk/src/devConsoleLogger.ts` (re-export), `rtk/src/index.ts`, `syncdb/src/index.ts`, `mcp-server/src/docs/templates/bootstrap/frontend/app/_layout.template.tsx`, `example-frontend/app/_layout.tsx`, tests
+  - Depends on: Task 5.1
+  - Acceptance: both import paths work; tests pass from the new location; `bun run compile` succeeds across the workspace; the example app still ships browser logs to the backend route (verify by producing a `console.error` and reading it back with `read_logs`).
+
+- [x] **Task 5.3**: Add rate limiting to the hosted MCP server
+  - Description: Per IP question AI5 — a launch prerequisite. Add per-IP rate limiting to the hosted server's JSON-RPC endpoint. Choose limits appropriate to the workload (search and codegen are cheap per call; the index is built once at startup) and make them configurable by environment variable with a sensible default. Return a clear JSON-RPC error when exceeded, naming the limit and the retry window. Add tests for under-limit, at-limit, and over-limit behavior. Document the limit in `docs/reference/mcp-server.md`.
+  - Files: `mcp-server/src/index.ts`, tests under `mcp-server/src/`, `docs/reference/mcp-server.md`, `docs/reference/environment-variables.md`
+  - Depends on: Task 2.1
+  - Acceptance: exceeding the limit returns a structured error naming the limit and retry window; the limit is configurable by environment variable; three test cases pass; the limit is documented.
+
+- [x] **Task 5.4**: Handle the MCP domain change
+  - Description: If program question P4 / IP question AI6 was answered in favor of moving off `mcp.terreno.flourish.health`, update every occurrence of the URL: `README.md`, `docs/reference/mcp-server.md`, `mcp-server/README.md`, `mcp-server/src/**` defaults, bootstrap templates, and `infra/flourish/` deployment config. Keep the old hostname serving with a redirect or CNAME for at least one release and document the cutover. If the decision was to keep the current domain, make no change and record that.
+  - Files: various (grep `rg -n "mcp\.terreno"`)
+  - Depends on: Task 2.1
+  - Acceptance: `rg -n "mcp\.terreno\.flourish\.health"` returns only intentional legacy references; a bootstrapped app's `mcp.json` uses the new URL; the cutover plan is documented; or the no-change decision is recorded in the PR body.
+
+- [x] **Task 5.5**: Let `terreno-mcp-local` attach to Metro's inspector proxy
+  - Description: Found by Task 1.3. `@react-native/dev-middleware` 0.86 (Expo 57) rejects debugger WebSocket upgrades that carry no `Origin` header (`InspectorProxy.js` `verifyClient`), and neither Bun nor Node sends one, so the `app` log source and every CDP-backed tool fail with `CDP websocket error: ... Expected 101 status code`. Send an `Origin` matching the Metro base URL's loopback origin on the CDP socket, and surface Metro's close code and reason (for example `[NEW_DEBUGGER_OPENED]`) in the status hint instead of the bare `CDP disconnected`. Add tests at the session seam.
+  - Files: `mcp-server/src/local/metro/metroDevSession.ts`, its tests
+  - Depends on: Task 1.3
+  - Acceptance: against a real Metro, `read_logs` with source `app` connects to a debuggable target without a preload shim; when another debugger takes the session, the status names Metro's close reason; tests cover the header and the close-reason hint; `bun run mcp:build` succeeds.
+
+- [x] **Task 5.6**: Make the local database tools load Mongoose under Bun
+  - Description: Found by Task 2.1. `database_schema` and `database_query` call `await import("mongoose")` and read `.connection` on the namespace object; under Bun with Mongoose 9 that property is undefined, so both tools fail with `undefined is not an object (evaluating 'mongoose.connection.readyState')` whenever a Mongo URI is found. Use the module's default export, and add a test that exercises the real import path against the in-memory Mongo used by the package tests.
+  - Files: `mcp-server/src/local/tools/databaseSchema.ts`, `mcp-server/src/local/tools/databaseQuery.ts`, their tests
+  - Depends on: Task 2.1
+  - Acceptance: against the running example database, `database_schema` and `database_query` return real results through `terreno-mcp-local`; tests fail before the fix and pass after; `bun run mcp:build` succeeds.
+
+## Phase 6: Verification
+
+- [x] **Task 6.1**: Run the loop end to end and capture evidence
+  - Description: In a fresh agent session with both MCP servers configured per `docs/how-to/set-up-terreno-mcp.md`, complete a full loop: ask for a small feature, let the agent generate it, run the app, introduce a bug, use `last_error` and `read_logs` to find it, fix it, and verify with `navigate` plus a screenshot. Capture the transcript highlights and screenshots to `/opt/cursor/artifacts/`. Fix any documentation gap the run exposed.
+  - Files: any documentation needing correction
+  - Depends on: Task 4.2, Task 5.1, Task 5.3
+  - Acceptance: the full loop completed in one session using only the public docs; artifacts captured showing the `last_error` output and the verified fix; every gap fixed.

package/src/docs/versioned/57.21.0/tasks/deploy-to-gcp.md

@@ -0,0 +1,100 @@
+# Task List: Deploy to GCP (Generalized) + `deploy-gcp` Skill
+
+See: [`docs/implementationPlans/deploy-to-gcp.md`](../implementationPlans/deploy-to-gcp.md)
+
+**RTK deprecation flag:** None. The only client-side surface is `EXPO_PUBLIC_API_URL`, which is unchanged by PR #869. Safe to implement before #869 merges.
+
+## Instructions for the implementing agent
+
+- Use placeholder variables in all documentation: `$PROJECT_ID`, `$REGION`, `$SERVICE_NAME`, `$WEB_BUCKET`, `$UPLOADS_BUCKET`. Never hardcode a real project ID, bucket, or URL.
+- Grep for `flourish` in every file you write or edit before committing: `rg -i flourish <file>`. The only permitted matches are inside `infra/flourish/`.
+- Do **not** run `gcloud` commands that create or modify resources unless the user has explicitly named a target project in the request.
+- Verify every `gcloud` flag you document against `gcloud run deploy --help` before writing it. Do not guess flag names.
+- Run `bun run lint` before each commit; run `bun run rules:check` after touching `.rulesync/`.
+
+## Phase 1: Generalize the how-to guides
+
+- [x] **Task 1.1**: Write `docs/how-to/deploy-backend-to-cloud-run.md`
+  - Description: New guide covering: prerequisites (gcloud installed and authenticated, billing enabled, required APIs — `run`, `artifactregistry`, `secretmanager`, `compute`); creating an Artifact Registry repo; building and pushing the backend image; creating Secret Manager secrets for `MONGO_URI`, `TOKEN_SECRET`, `TOKEN_ISSUER`, `REFRESH_TOKEN_SECRET`, `SESSION_SECRET`, and `BETTER_AUTH_SECRET`; creating the runtime service account with least-privilege roles; the `gcloud run deploy` invocation with `--session-affinity`, `--timeout`, `--min-instances`, `--set-secrets`, and `--set-env-vars`; and verification via `curl $SERVICE_URL/health`. Use placeholder variables throughout. Read `example-backend/src/server.ts` and `docs/reference/environment-variables.md` to get the env var list right — do not copy it from this task description without checking.
+  - Files: `docs/how-to/deploy-backend-to-cloud-run.md` (new)
+  - Depends on: none
+  - Acceptance: `rg -i flourish docs/how-to/deploy-backend-to-cloud-run.md` returns nothing; every env var named exists in `docs/reference/environment-variables.md` or the backend source; every `gcloud` flag used appears in `gcloud run deploy --help`.
+
+- [x] **Task 1.2**: Add the production constraints section
+  - Description: Add a "Production constraints" section to the backend guide as a symptom → cause → fix table covering at minimum: (a) websockets disconnect every few requests → no session affinity → add `--session-affinity`; (b) long-lived socket connections drop at 5 minutes → default request timeout → raise `--timeout`; (c) realtime and live feature flags stop working → MongoDB is not a replica set → use Atlas or a replica set, because change streams require one; (d) first request after idle is slow and sockets churn → scaled to zero → `--min-instances=1`; (e) browser requests fail CORS → `corsOrigin` in `setupServer` and Better Auth `trustedOrigins` do not include the web origin. Verify claim (c) against `feature-flags` live-update code before writing it.
+  - Files: `docs/how-to/deploy-backend-to-cloud-run.md`
+  - Depends on: Task 1.1
+  - Acceptance: all five rows present with a concrete symptom; the change-streams claim is verified against the source and the source path is cited in the guide.
+
+- [x] **Task 1.3**: Write `docs/how-to/deploy-web-to-gcs-cdn.md`
+  - Description: New guide covering: building the web bundle (`bunx expo export -p web` — confirm the exact command against `example-frontend/package.json` scripts), the requirement to set `EXPO_PUBLIC_API_URL` at build time because it is inlined into the bundle, creating and configuring the GCS bucket with public read and `notFoundPage=index.html` for client-side routing, the five CDN resources (backend bucket, URL map, static IP, HTTP(S) proxy, forwarding rule), pointing DNS at the IP, and cache invalidation after each deploy. Include a note that this is a static-only path and link [`web-ssr-and-admin-spa`](../implementationPlans/web-ssr-and-admin-spa.md) for the SSR future.
+  - Files: `docs/how-to/deploy-web-to-gcs-cdn.md` (new)
+  - Depends on: none
+  - Acceptance: no Flourish strings; the export command matches an actual script in `example-frontend/package.json`; the guide explains why `EXPO_PUBLIC_API_URL` must be set before building, not after.
+
+- [x] **Task 1.4**: Write the architecture explainer
+  - Description: Create `docs/explanation/deployment-architecture-gcp.md` explaining the reference topology (reuse the mermaid diagram from the IP), what each component is responsible for, why Cloud Run rather than App Engine or GKE, why Atlas rather than self-hosted Mongo, and the tradeoffs of static web hosting versus a server-rendered deployment. Keep it conceptual — no commands.
+  - Files: `docs/explanation/deployment-architecture-gcp.md` (new)
+  - Depends on: Task 1.1, Task 1.3
+  - Acceptance: contains the topology diagram; contains no shell commands; explains at least three explicit tradeoffs.
+
+- [x] **Task 1.5**: Rewire the existing GCP how-to and index
+  - Description: Replace `docs/how-to/deploy-to-gcp.md` with a short index page linking the two new guides and the explainer, preserving the old anchor names where practical so existing links do not break. Update `docs/how-to/README.md` to list the new guides. Check `website/` for any hardcoded reference to the old page path and update it.
+  - Files: `docs/how-to/deploy-to-gcp.md`, `docs/how-to/README.md`, `website/` (as needed)
+  - Depends on: Task 1.1, Task 1.3, Task 1.4
+  - Acceptance: `bun run website:build` succeeds with no new broken-link warnings introduced by this change.
+
+## Phase 2: Terraform module and Flourish separation
+
+- [x] **Task 2.1**: Extract the generic backend module
+  - Description: Create `terraform/modules/terreno-backend/` with `main.tf`, `variables.tf`, `outputs.tf`, and `README.md`. Resources: Artifact Registry repository, Cloud Run v2 service (session affinity, timeout, min/max instances, secret env refs), Secret Manager secrets (created empty, values supplied out-of-band), runtime service account with `secretmanager.secretAccessor` and object admin on a supplied uploads bucket, and optional Workload Identity Federation pool for CI. Every value that could differ between users must be a variable with a description and no Flourish default. Outputs: service URL, service account email, registry path.
+  - Files: `terraform/modules/terreno-backend/main.tf`, `variables.tf`, `outputs.tf`, `README.md` (all new)
+  - Depends on: Task 1.1
+  - Acceptance: `terraform init && terraform validate` passes in the module directory; `rg -i flourish terraform/modules/` returns nothing; every variable has a `description`.
+  - Implementation note: secrets start empty, and Cloud Run rejects a revision that references a versionless secret, so the module does not mount secret env refs at creation. The `set_secrets_flag` output supplies the `--set-secrets` flag for the first real `gcloud run deploy`, consistent with the existing "Terraform owns structure, deploy owns payload" split (`lifecycle.ignore_changes` on env).
+
+- [x] **Task 2.2**: Relocate Flourish-specific terraform
+  - Description: Move Flourish's environment configuration from `terraform/` to `infra/flourish/`, leaving only `terraform/modules/` behind. Update every path reference: `.github/workflows/cd.yml`, `terraform/README.md` (split into a generic module README and `infra/flourish/README.md`), `AGENTS.md` / `CLAUDE.md` if they reference `terraform/README.md`, and any script under `scripts/`. Use `git mv` so history is preserved.
+  - Files: `infra/flourish/**` (moved), `terraform/README.md`, `.github/workflows/cd.yml`, `AGENTS.md`, `CLAUDE.md`, `scripts/**`
+  - Depends on: Task 2.1
+  - Acceptance: `rg -n "terraform/" --glob '!infra/**' --glob '!terraform/**'` shows no stale paths pointing at moved files; the `cd.yml` workflow references the new location; `bun run rules:check` exits 0 after regenerating rules.
+
+- [x] **Task 2.3**: Parameterize the GCS hosting script
+  - Description: Rewrite `scripts/setup-gcs-hosting.sh` to require `--project`, `--site-name`, `--bucket`, and `--domain` arguments (or positional equivalents) with a usage message and a check that all are present. Remove every hardcoded Flourish project, bucket, and service-account value. Keep the resource-creation logic intact, with HTTPS as the only public serving path. Add a `--dry-run` flag that prints commands without executing them.
+  - Files: `scripts/setup-gcs-hosting.sh`
+  - Depends on: Task 1.3
+  - Acceptance: running with no arguments prints usage and exits non-zero; `--dry-run` produces HTTPS commands containing the supplied values, no port 80 forwarding rule, and no Flourish strings; `rg -i flourish scripts/setup-gcs-hosting.sh` returns nothing.
+
+## Phase 3: The `deploy-gcp` skill
+
+- [x] **Task 3.1**: Author the skill
+  - Description: Create `.rulesync/skills/deploy-gcp/SKILL.md` with frontmatter (`name: deploy-gcp`, a `description` that names the trigger phrases "deploy to GCP", "deploy to Cloud Run", "ship the backend", and `targets: ['*']`). Body sections in this order: When to use / When not to use; Preflight checks (project layout detection, `gcloud config get-value project`, required APIs, replica-set verification of `MONGO_URI`); **Plan and confirm** — print target project, region, service name, and every resource to be created or updated, then stop and require explicit user confirmation before any mutating command; Backend deploy steps; Frontend deploy steps; Verification (`curl $SERVICE_URL/health` expecting `"healthy":true`, fetch web root); Troubleshooting (link the reference file). Include an explicit prohibition: never deploy to a project the user did not name in the request, and never create or modify secrets without echoing which secret names will change.
+  - Files: `.rulesync/skills/deploy-gcp/SKILL.md` (new)
+  - Depends on: Task 1.1, Task 1.3
+  - Acceptance: frontmatter has `name`, `description`, and `targets`; the confirmation gate appears before the first mutating command; every command in the skill also appears in the how-to guides (no skill-only knowledge).
+
+- [x] **Task 3.2**: Add the troubleshooting reference
+  - Description: Create `.rulesync/skills/deploy-gcp/references/troubleshooting.md` containing the symptom → cause → fix table from Task 1.2 plus deploy-time failures: image push permission denied, secret access denied at cold start, Cloud Run revision failing health checks because `PORT` is not read from the environment, and CDN serving a stale bundle after deploy. For each, give the exact log line or error message the user will see.
+  - Files: `.rulesync/skills/deploy-gcp/references/troubleshooting.md` (new)
+  - Depends on: Task 3.1
+  - Acceptance: at least nine rows; each row quotes an actual error string rather than paraphrasing.
+
+- [x] **Task 3.3**: Generate skill mirrors
+  - Description: Run `bun run rules` and commit every generated file under `.cursor/skills/`, `.claude/skills/`, `.devin/skills/`, `.github/skills/`, and `.agents/skills/`. Do not hand-edit generated files.
+  - Files: generated skill mirrors
+  - Depends on: Task 3.1, Task 3.2
+  - Acceptance: `bun run rules:check` exits 0; `deploy-gcp` appears under each configured target directory.
+
+## Phase 4: Validation
+
+- [ ] **Task 4.1**: Dry-run the guide end to end
+  - Description: Following **only** `docs/how-to/deploy-backend-to-cloud-run.md` and `docs/how-to/deploy-web-to-gcs-cdn.md` (no internal knowledge, no `infra/flourish/`), deploy `example-backend` and `example-frontend` to a scratch GCP project. Record every point where the guide was wrong, incomplete, or required outside knowledge. Fix the guides. Capture the successful `curl $SERVICE_URL/health` output and the loaded web app as artifacts under `/opt/cursor/artifacts/`.
+  - Files: `docs/how-to/deploy-backend-to-cloud-run.md`, `docs/how-to/deploy-web-to-gcs-cdn.md`
+  - Depends on: Task 1.1, Task 1.3, Task 2.3
+  - Acceptance: the deploy succeeds; `/health` returns `"healthy":true`; the web app loads and can log in against the deployed backend; every guide correction is committed.
+
+- [ ] **Task 4.2**: Exercise the skill against the validated guide
+  - Description: Run the `deploy-gcp` skill in a fresh agent session against the same scratch project and confirm it reaches the same result, including the confirmation gate firing before any mutation. Note any step where the skill needed information the guide did not provide and fix the skill.
+  - Files: `.rulesync/skills/deploy-gcp/SKILL.md` plus mirrors
+  - Depends on: Task 3.3, Task 4.1
+  - Acceptance: the skill run produces a working deploy; the confirmation gate is observed in the transcript; `bun run rules:check` exits 0 after any skill edits.

package/src/docs/versioned/57.21.0/tasks/deploy-to-vercel.md

@@ -0,0 +1,116 @@
+# Task List: Deploy to Vercel + `deploy-vercel` Skill
+
+See: [`docs/implementationPlans/deploy-to-vercel.md`](../implementationPlans/deploy-to-vercel.md)
+
+**RTK deprecation flag:** **Partial.** Tasks marked `[RTK]` cover client configuration, auth origins, and websocket verification, all of which change shape with PR #869 (syncdb uses a websocket delta transport, so the websocket verification step becomes more load-bearing, not less). Re-verify marked tasks after #869.
+
+## Instructions for the implementing agent
+
+- Verify every Vercel configuration key against the current Expo documentation at `https://docs.expo.dev/guides/publishing-websites` and `https://docs.expo.dev/router/web/api-routes` before writing it. Vercel's config schema has changed across versions (`routes`/`builds` versus `rewrites`/`functions`) — document the current one and note the legacy form only if the repo's Expo version requires it.
+- Confirm the repo's Expo SDK version from the root `package.json` catalog before writing anything about server output or SSR. If it is below 55, the server-output section must be clearly marked as unavailable-until-upgrade and link PR #779.
+- Never write `corsOrigin: true` as a recommendation.
+- Run `bun run lint` before each commit; `bun run rules:check` after touching `.rulesync/`.
+
+## Phase 0: Vercel topology spike (blocks Phase 1)
+
+Close every **Open TODO** in the IP before writing the how-to guide.
+
+- [x] **Task 0.1**: Spike `@terreno/api` on Vercel
+  - Description: Prototype whether Socket.io, MongoDB change streams, and `@terreno/ai` SSE can run on Vercel (all-in-one candidate). Treat [Vercel Functions WebSockets (Public Beta)](https://vercel.com/docs/functions/websockets) as the vendor contract. Record Fluid compute, max-duration disconnects, instance pinning (not affinity across reconnects), Redis for cross-instance fan-out, Function billing while sockets are open, cold starts, and SSE buffering. Compare against split topology (Vercel web + long-running backend).
+  - Files: spike notes in PR / IP update; optional scratch `example-backend/vercel.json`
+  - Depends on: none
+  - Acceptance: IP questions **V1**, **V2**, and **V3** updated with a recorded decision; all IP Open TODO checkboxes checked or explicitly deferred with owner.
+
+- [x] **Task 0.2**: Write Vercel Functions WebSocket operator docs
+  - Description: Create `docs/how-to/vercel-function-websockets.md` from the IP section **Vercel Functions WebSockets (Public Beta)**. Cite `https://vercel.com/docs/functions/websockets`; do not copy Vercel examples. Cover Fluid compute, HTTP Upgrade + Firewall/rate limits, websocket-only Socket.IO, `export default` HTTP server vs `TerrenoApp.start()`, instance pinning, max-duration reconnects, Redis (`RealtimeApp` adapter), Function billing while connected, and verification (`WEBSOCKETS_DEBUG`, DevTools WS, no polling fallback). Mark **beta**. Do not recommend all-in-one topology until V1 is decided. Link from `docs/how-to/README.md` and later from `docs/how-to/deploy-web-to-vercel.md` and `docs/how-to/websocket-integration.md`.
+  - Files: `docs/how-to/vercel-function-websockets.md` (new), `docs/how-to/README.md`, `docs/how-to/websocket-integration.md`
+  - Depends on: none (may ship before Task 0.1 closes; must re-verify against the Vercel page at ship time)
+  - Acceptance: every required operator section from the IP is present; the Vercel URL is cited; Next.js `experimental_upgradeWebSocket`, Bun, and Python examples are out of scope; `corsOrigin: true` is not recommended; listed in the how-to index.
+
+## Phase 1: Core how-to guide
+
+- [x] **Task 1.1**: Write the Vercel deployment guide for `single` output
+  - Description: Create `docs/how-to/deploy-web-to-vercel.md`. Open with a "What goes where" section using the **topology decided in Phase 0** (interim split layout until spike closes; do not document all-in-one until V1 is decided). Then: prerequisites; backend host setup per V1 outcome; `vercel.json` for `single` output; `EXPO_PUBLIC_API_URL`; deploy + verify. Link `docs/explanation/deployment-baseline.md` instead of restating baseline requirements. Link `docs/how-to/vercel-function-websockets.md` wherever sockets on Functions are mentioned.
+  - Files: `docs/how-to/deploy-web-to-vercel.md` (new), `docs/how-to/README.md`
+  - Depends on: `deployment-foundation` Phase 4, Task 0.2
+  - Acceptance: every config key verified against current Expo docs; the "what goes where" reasoning is present in the first section; the guide links rather than duplicates the baseline explainer; listed in the how-to index; websocket Functions page is linked, not duplicated.
+
+- [x] **Task 1.2**: `[RTK]` Add the verification section
+  - Description: Add a "Verify the deployment" section with four checks, each with the expected result and what failure means: (1) the root URL loads the app; (2) a deep link loads directly on refresh (proves the SPA rewrite works); (3) login succeeds, proving the API call reaches the backend and CORS is configured; (4) the websocket connects, proving realtime and live feature flags work. For check 4, give a concrete way to verify — browser devtools Network tab filtered to WS, or the client's debug logging flag (find the actual flag name in the client package, `WEBSOCKETS_DEBUG` at time of writing) — and explain that the app looks fine when this is broken, which is why it must be checked explicitly.
+  - Files: `docs/how-to/deploy-web-to-vercel.md`
+  - Depends on: Task 1.1
+  - Acceptance: all four checks present with expected results; the websocket check names a real debug flag verified in the client source; the "looks fine while broken" warning is present.
+
+- [x] **Task 1.3**: Add the reference `vercel.json`
+  - Description: Per IP question V3 (after Phase 0), add `vercel.json` to `example-frontend` and optionally `example-backend` if all-in-one wins. Wire to a real deployment only if V3 decision is **A**.
+  - Files: `example-frontend/vercel.json` (new), `example-frontend/README.md`
+  - Depends on: Task 1.1
+  - Acceptance: the file is valid JSON and matches the guide's configuration exactly; the README explains its status; no new deploy workflow was added.
+
+## Phase 2: Preview deployments and origins
+
+- [x] **Task 2.1**: `[RTK]` Document the preview-origin problem
+  - Description: Add a "Preview deployments" section covering: how Vercel assigns a unique origin per deployment; why that breaks CORS and Better Auth; a concrete `corsOrigin` pattern accepting production plus preview origins (write it as a function or regex matching the project's preview hostname shape — read `api/src/expressServer.ts` to confirm what shapes `corsOrigin` actually accepts before writing the example); the equivalent `trustedOrigins` configuration for Better Auth including native deep-link schemes; and OAuth redirect-URI registration per provider, noting that most providers do not support wildcards so preview OAuth needs either a fixed proxy origin or provider-specific handling. State that `corsOrigin: true` must not be used in production and explain the risk.
+  - Files: `docs/how-to/deploy-web-to-vercel.md`
+  - Depends on: Task 1.2
+  - Acceptance: the `corsOrigin` example is a shape actually supported by `setupServer`, cited to source; `trustedOrigins` guidance matches `api/src/betterAuth.ts`; the OAuth wildcard limitation is stated; the `corsOrigin: true` warning explains the risk rather than just prohibiting it.
+
+- [x] **Task 2.2**: `[RTK]` Document per-environment client configuration
+  - Description: Add a short section on Vercel's three environment scopes (production, preview, development) and how `EXPO_PUBLIC_API_URL` should differ across them — typically a production backend and a staging backend. Explain the consequence that follows from build-time inlining: each environment produces a different bundle, so a promoted preview build points at the preview backend unless rebuilt. Cross-reference the multi-environment checklist in `docs/explanation/deployment-baseline.md`. Add a note to `docs/reference/environment-variables.md` about Vercel's per-environment scoping.
+  - Files: `docs/how-to/deploy-web-to-vercel.md`, `docs/reference/environment-variables.md`
+  - Depends on: Task 2.1
+  - Acceptance: the promotion pitfall is stated explicitly; the reference page notes Vercel scoping; both link the baseline checklist.
+
+## Phase 3: Advanced — server output
+
+- [x] **Task 3.1**: Determine and record server-output availability
+  - Description: Read the `expo` version in the root `package.json` catalog and the state of PR #779 (Expo SDK 56 upgrade). Record in the guide whether `server` output is available today. If the SDK is below 55, the section must open with a clear "not available on the current Terreno Expo version" note plus a link to PR #779 and [`web-ssr-and-admin-spa`](../implementationPlans/web-ssr-and-admin-spa.md).
+  - Files: `docs/how-to/deploy-web-to-vercel.md`
+  - Depends on: Task 1.1
+  - Acceptance: the stated Expo version matches the catalog exactly; availability is stated unambiguously; PR #779 is linked if applicable.
+
+- [x] **Task 3.2**: Write the server-output section
+  - Description: Document the server-output path as advanced: setting `web.output` to `server` in the app config, the server entry file using `expo-server/adapter/vercel`, the `vercel.json` with `outputDirectory` pointing at the client output and a function including `dist/server/**`, and the `vercel-build` script. Verify the exact adapter import path, function config keys, and required file locations against the current Expo API-routes documentation. Add a clearly-marked caveat: responses through the Vercel adapter may be buffered rather than streamed, which breaks the SSE streaming used by `@terreno/ai`'s `/gpt/prompt` endpoint — link the upstream issue and state the workaround (keep AI streaming on the `@terreno/api` backend rather than routing it through Expo API routes on Vercel).
+  - Files: `docs/how-to/deploy-web-to-vercel.md`
+  - Depends on: Task 3.1
+  - Acceptance: every config key and import path verified against current Expo docs with the doc URL cited; the streaming caveat names the affected Terreno endpoint and gives a workaround; the section is labeled advanced.
+
+- [x] **Task 3.3**: Disambiguate "Vercel AI SDK" across the repo
+  - Description: Grep for `Vercel` across `docs/`, package READMEs, and `.rulesync/rules/` (`rg -n "Vercel"`). For every occurrence referring to the AI library, ensure it reads "the Vercel AI SDK" and never bare "Vercel". Add a one-line note to `docs/reference/ai.md` clarifying that `@terreno/ai` is provider-agnostic via the Vercel AI SDK and that this is unrelated to Vercel hosting. Add the same clarification to the new deployment guide.
+  - Files: `docs/reference/ai.md`, `docs/how-to/deploy-web-to-vercel.md`, `.rulesync/rules/ai/00-ai.md`, `ai/README.md`, generated mirrors
+  - Depends on: Task 1.1
+  - Acceptance: `rg -n "Vercel" docs/ */README.md .rulesync/` shows every hit is either "the Vercel AI SDK" or a hosting context; `bun run rules:check` exits 0.
+
+## Phase 4: The `deploy-vercel` skill
+
+- [x] **Task 4.1**: Author the skill
+  - Description: Create `.rulesync/skills/deploy-vercel/SKILL.md` with frontmatter (`name`, a `description` naming trigger phrases "deploy to Vercel", "deploy the web app", "put this online", and `targets: ['*']`). Body: When to use / when not to use (explicitly: not for the backend); Detect (Expo Router app, `web.output` value, existing `vercel.json`, backend URL); Configure (`vercel.json` per output mode, `vercel-build` script for server output); Wire the backend (set `EXPO_PUBLIC_API_URL` per Vercel environment; print the exact `corsOrigin` and `trustedOrigins` changes the user must apply on the backend and stop until they confirm, since the agent cannot safely edit a deployed backend's config); Deploy (`vercel`, then `vercel --prod` behind a confirmation gate); Verify (the four checks from Task 1.2); Troubleshoot (link the reference). Include a prohibition on deploying to production without explicit confirmation and on setting `corsOrigin: true`.
+  - Files: `.rulesync/skills/deploy-vercel/SKILL.md` (new)
+  - Depends on: Task 2.1, Task 3.2
+  - Acceptance: frontmatter complete; the production-deploy confirmation gate is present; the verification step includes the websocket check; no command appears in the skill that is absent from the how-to guide.
+
+- [x] **Task 4.2**: Add the troubleshooting reference
+  - Description: Create `.rulesync/skills/deploy-vercel/references/troubleshooting.md` covering at least these six, each with the literal symptom the user sees: blank white page after deploy (missing rewrites); 404 on refreshing a deep link (same root cause, different symptom); network requests going to `localhost:4000` in production (`EXPO_PUBLIC_API_URL` absent at build time); CORS error text quoted verbatim from a browser console; websocket connection failing while the rest of the app works (Fluid off, long-polling fallback, or max-duration close — link `docs/how-to/vercel-function-websockets.md`); and SSE responses arriving all at once on server output (the buffering caveat). For each, give the fix and the file or setting to change.
+  - Files: `.rulesync/skills/deploy-vercel/references/troubleshooting.md` (new)
+  - Depends on: Task 4.1
+  - Acceptance: at least six entries; each quotes a real error string or describes a precisely observable symptom; each names the file or setting to change.
+
+- [x] **Task 4.3**: Generate skill mirrors
+  - Description: Run `bun run rules` and commit all generated files. Do not hand-edit generated output.
+  - Files: generated skill mirrors
+  - Depends on: Task 4.1, Task 4.2
+  - Acceptance: `bun run rules:check` exits 0; `deploy-vercel` appears under every configured target directory.
+
+## Phase 5: Validation
+
+- [x] **Task 5.1**: Deploy the example frontend to a scratch Vercel project
+  - Description: Following only `docs/how-to/deploy-web-to-vercel.md`, deploy `example-frontend` to a scratch Vercel project pointed at a real deployed backend. Run all four verification checks. Record and fix every gap in the guide. Capture screenshots of the deployed app (logged in, with a deep link loaded directly) and the devtools websocket connection, saved under `/opt/cursor/artifacts/`.
+  - Files: `docs/how-to/deploy-web-to-vercel.md`
+  - Depends on: Task 1.3, Task 2.2
+  - Acceptance: all four verification checks pass on the deployed app; every guide gap found is fixed; screenshots captured including the websocket evidence.
+
+- [ ] **Task 5.2**: Exercise the skill in a fresh session
+  - Description: Run the `deploy-vercel` skill in a fresh agent session against a second scratch project and confirm it reaches a working deployment, that the production confirmation gate fires, and that it correctly stops to ask the user to apply backend CORS changes. Fix any step where the skill needed information it did not have.
+  - Files: `.rulesync/skills/deploy-vercel/SKILL.md` plus mirrors
+  - Depends on: Task 4.3, Task 5.1
+  - Acceptance: the skill run produces a working deployment; both stop-and-confirm points are observed in the transcript; `bun run rules:check` exits 0 after any edits.

package/src/docs/versioned/57.21.0/tasks/infra-mcp.md

@@ -0,0 +1,44 @@
+# Tasks: Infrastructure MCP server (`@terreno/infra-mcp`)
+
+Plan: [docs/implementationPlans/infra-mcp.md](../implementationPlans/infra-mcp.md)
+Status: Blocked — Phase 1 RBAC wiring depends on the RBAC module PR ([rbac-permissions.md](../implementationPlans/rbac-permissions.md)). Scaffold/adapter tasks marked (unblocked) can start now.
+
+## Phase 1 — Read-only core
+
+- [ ] (unblocked) Scaffold `infra-mcp/` workspace package: package.json (catalog deps), tsconfig, biome, bun test setup, root workspace + catalog entries (zod 4, `@modelcontextprotocol/server`, `@better-auth/oauth-provider`, `@better-auth/mcp`)
+- [ ] (unblocked) `src/config.ts`: `defineInfraMcp` config schema (zod), secret resolution (env/Secret Manager), boot validation
+- [ ] (unblocked) `src/server.ts`: Express/TerrenoApp server with SDK v2 `/mcp` endpoint (`createMcpHandler`, `legacy: "stateless"`, `toNodeHandler`) + `/health`
+- [ ] (unblocked) `src/auth.ts`: Better Auth OAuth 2.1 setup — authorization server, RFC 9728 protected-resource metadata, bearer verification middleware; login page flow verified with Cursor and Claude Code
+- [ ] `src/access.ts`: `infraStatements`, default roles (`infra-readonly`, `infra-operator`), `createAccess` wiring, `Mcp-Name`-keyed authz middleware, per-user filtered `tools/list` (**blocked on RBAC PR**)
+- [ ] `src/models/infraAuditLog.ts` + audit middleware around `tools/call` (statuses: allowed/denied/confirmed/rejected/error; per-tool arg redaction)
+- [ ] (unblocked) Integration adapter types + registry (`src/integrations/types.ts`, `registry.ts`)
+- [ ] (unblocked) GCP native adapter (ADC): `gcp_query_logs`, `gcp_list_log_names`, `gcp_query_metrics`, `gcp_list_error_groups`, `gcp_list_cloud_run_services`, `gcp_get_cloud_run_service`
+- [ ] (unblocked) Sentry native adapter (REST + static token): `sentry_search_issues`, `sentry_get_issue`, `sentry_list_issue_events`, `sentry_get_event`
+- [ ] (unblocked) Mongo native adapter (read URI): `mongo_list_collections`, `mongo_collection_schema`, `mongo_find`, `mongo_aggregate` (reject `$out`/`$merge`). Extract the shared read-query/schema logic from `mcp-server/src/local/tools/databaseQuery.ts` + `databaseSchema.ts` into a reusable module both packages import — do not fork copies into infra-mcp (per architectural review)
+- [ ] Admin panel registration (`@terreno/admin-backend`): Users, InfraAuditLog (read-only)
+- [ ] Terraform: `infra_mcp_service` Cloud Run module instance, Artifact Registry, runtime SA with viewer/logging IAM only
+- [ ] Tests: authz matrix (role × tool × tools/list filtering), adapter handlers, audit records, legacy-client fallback
+- [ ] Deploy + end-to-end verification from a real MCP client; docs: `.cursor/rules/infra-mcp/00-infra-mcp.mdc`, AGENTS.md/CLAUDE.md package lists
+- [ ] Roadmap: open the tracking issue from [roadmap-seed-issues.md](../explanation/roadmap-seed-issues.md#infra-mcp) once the IP is Approved, add it to the Terreno Roadmap board, and register `@terreno/infra-mcp` → `area:mcp` in `scripts/issueAreaLabels.ts` + the bug-report package dropdown when the package lands
+
+## Phase 2 — Write tier + machine callers
+
+- [ ] `confirmWrite` elicitation wrapper; fail-closed behavior for clients without elicitation support
+- [ ] Config override (`confirmWrites: false`) gated by `infra:writeUnconfirmed`; tests for both paths
+- [ ] Write tools: `sentry_resolve_issue`, `sentry_assign_issue`, `gcp_rollback_cloud_run_revision`, `gcp_update_cloud_run_traffic`, `mongo_update_one`, `mongo_delete_one`; widen runtime SA IAM minimally
+- [ ] Service tokens: spike Better Auth `apiKey` plugin; fallback `ServiceToken` model; machine users (`isServiceAccount`) with role assignment; admin surface (token shown once)
+- [ ] Cloud agent migration: `INFRA_MCP_URL` + service token in agent environments; verify log-digging flows; remove `GCP_SA_*` injection; update AGENTS.md Cursor Cloud instructions
+
+## Phase 3 — Proxied adapters + remaining vendors
+
+- [ ] `ProxiedAdapter`: `@modelcontextprotocol/client` (stdio + HTTP), deny-by-default `allowedTools` with mandatory tier annotations, tool name prefixing, upstream lifecycle management
+- [ ] Reference proxied integration (`@sentry/mcp-server` stdio or `@google-cloud/observability-mcp`) with parity tests against native tools
+- [ ] Expo/EAS native adapter (`EXPO_TOKEN`): build status, update status, submission status (read); trigger tools deferred to write expansion
+- [ ] Vercel native adapter (one team token per team, project→team by lookup): `vercel_list_projects`, `vercel_list_deployments`, `vercel_runtime_logs` via `POST /v1/observability/events` (read); `vercel.read` RBAC scope limiting machine users to their own projects. Port from the hive dogfood implementation
+- [ ] Per-sandbox machine users for orchestrated agents: mint user + service token at sandbox create, revoke at teardown; per-resource allow-list consumed by integration scopes
+
+## Phase 4 — OSS packaging
+
+- [ ] `defineInfraMcp` config reference + quickstart docs (website); one-man-shop deploy path (container anywhere)
+- [ ] Publish `@terreno/infra-mcp`; changelog + upgrade notes
+- [ ] Dogfood writeup: our deployment as the reference architecture