@terreno/mcp 57.19.2 → 57.20.0

package/src/docs/versioned/next/how-to/set-up-terreno-mcp.md

@@ -1,65 +1,264 @@
 # Set up Terreno MCP
 
-Configure both Terreno servers: the hosted server supplies documentation and generators; the local
-stdio server inspects the app, database, logs, Metro, and Redux state.
+Connect your editor to both Terreno MCP servers:
 
-Install Bun 1.4 or newer to enable the local server's built-in WebView browser automation.
+- **`terreno`** (hosted, Streamable HTTP) supplies documentation search and code generators.
+- **`terreno-local`** (stdio, runs in your repository) reads the app's packages, database, logs,
+  Metro, and client state.
 
-## Cursor
+Apps made with `create-terreno-app` already contain both configurations. Use this guide to check
+them, to add them to an older app, or to fix a server that does not connect.
 
-Add `.cursor/mcp.json` at the app repository root:
+Prerequisites: Bun 1.4 or newer. The local server's bin is `#!/usr/bin/env bun`, and its `browser`
+tool needs Bun 1.4.
+
+## 1. Configure Cursor
+
+Create `.cursor/mcp.json` at the app repository root. This is the file `create-terreno-app` writes:
 
 ```json
 {
   "mcpServers": {
+    "expo": {
+      "type": "http",
+      "url": "https://mcp.expo.dev/mcp"
+    },
+    "playwright": {
+      "args": [
+        "-y",
+        "@playwright/mcp@0.0.76"
+      ],
+      "command": "npx"
+    },
     "terreno": {
       "type": "http",
-      "url": "https://mcp.terreno.flourish.health/mcp"
+      "url": "https://mcp.terreno.app/mcp"
     },
     "terreno-local": {
-      "command": "bunx",
-      "args": ["terreno-mcp-local"]
+      "args": [
+        "-p",
+        "@terreno/mcp",
+        "terreno-mcp-local"
+      ],
+      "command": "bunx"
     }
   }
 }
 ```
 
-## Claude Code
+Only `terreno` and `terreno-local` are required. `expo` and `playwright` are optional; see
+[step 5](#5-optional-add-expo-mcp-and-playwright-mcp).
+
+Keep `-p @terreno/mcp` in the `terreno-local` args. The bin is named `terreno-mcp-local`, but the
+npm package is `@terreno/mcp`. Without `-p`, `bunx` looks for an npm package named
+`terreno-mcp-local`, gets a 404, and the server never starts.
+
+Open the app repository root as the Cursor workspace. Then open Cursor's MCP settings and confirm
+each server is enabled and lists its tools. If `terreno-local` reports the wrong project root, set
+`TERRENO_PROJECT_ROOT` in its entry (step 4).
+
+## 2. Configure Claude Code
+
+Claude Code reads project servers from `.mcp.json` at the repository root. `create-terreno-app`
+writes the same content there as in `.cursor/mcp.json`, so the two files are byte-for-byte
+identical:
+
+```json
+{
+  "mcpServers": {
+    "expo": {
+      "type": "http",
+      "url": "https://mcp.expo.dev/mcp"
+    },
+    "playwright": {
+      "args": [
+        "-y",
+        "@playwright/mcp@0.0.76"
+      ],
+      "command": "npx"
+    },
+    "terreno": {
+      "type": "http",
+      "url": "https://mcp.terreno.app/mcp"
+    },
+    "terreno-local": {
+      "args": [
+        "-p",
+        "@terreno/mcp",
+        "terreno-mcp-local"
+      ],
+      "command": "bunx"
+    }
+  }
+}
+```
+
+Run `claude` from the repository root. On the first run, Claude Code asks you to approve the
+project's servers. Approve them. Then check the servers:
+
+```bash
+claude mcp list
+```
+
+A server you have not approved yet is listed as `⏸ Pending approval`. After approval, each server
+reports `✔ Connected`.
+
+To register the two Terreno servers without editing the file, run these commands from the
+repository root. `--scope project` writes the servers to `.mcp.json`:
+
+```bash
+claude mcp add --scope project --transport http terreno https://mcp.terreno.app/mcp
+claude mcp add --scope project terreno-local -- bunx -p @terreno/mcp terreno-mcp-local
+```
+
+## 3. Check the hosted endpoint
+
+The hosted server's URL is `https://mcp.terreno.app/mcp`. It speaks MCP Streamable HTTP
+(`"type": "http"`). `POST /` is accepted as an alias, but configure the `/mcp` path. Requests must
+send `Accept: application/json, text/event-stream`; MCP clients do this for you.
+`create-terreno-app` writes this URL into `.cursor/mcp.json` and `.mcp.json`. Use
+`--mcp-server-url` to point a new app at a different deployment.
+
+Check that the host answers:
+
+```bash
+curl -s https://mcp.terreno.app/
+```
+
+A working host returns `{"mcpEndpoint":"/mcp","service":"terreno-mcp","status":"ok"}`. If the
+command prints `Could not resolve host: mcp.terreno.app`, or the editor reports
+`getaddrinfo ENOTFOUND mcp.terreno.app`, that hostname does not resolve yet. Until it does, set the
+`terreno` URL to `https://mcp.terreno.flourish.health/mcp` in `.cursor/mcp.json` and `.mcp.json`. It
+serves the same service and tools.
+
+### Moving off `mcp.terreno.flourish.health`
+
+Earlier docs and scaffolds used `https://mcp.terreno.flourish.health/mcp`. That hostname serves the
+same Cloud Run service and keeps working for at least one release after the release that announces
+`mcp.terreno.app`. Replace the old URL in `.cursor/mcp.json`, `.mcp.json`, and any
+`claude mcp add` registration:
 
-Use the same project-scoped `.mcp.json`, or register the servers from the repository root:
+For a project `.mcp.json`, edit the `url` in the file. For a registration you added with
+`claude mcp add` outside the project file, re-add it in the same scope:
 
 ```bash
-claude mcp add --transport http terreno https://mcp.terreno.flourish.health/mcp
-claude mcp add terreno-local -- bunx terreno-mcp-local
+claude mcp remove --scope local terreno
+claude mcp add --scope local --transport http terreno https://mcp.terreno.app/mcp
 ```
 
-## Configure local discovery
+The operator cutover (domain mapping, DNS, retiring the old hostname) is in the
+[infra/flourish README](https://github.com/TerrenoLabs/terreno/blob/master/infra/flourish/README.md#hosted-mcp-hostname).
 
-Run the local server from the app root. It discovers bootstrap apps with `backend/` and `frontend/`,
-and this monorepo's `example-backend/` logs. Set these variables only when discovery needs help:
+## 4. Give the local server what it needs
 
-| Variable | Use |
+`terreno-local` starts without any of the items below, but each tool reads only what it can find.
+The full rules are in the
+[local server reference](../reference/mcp-server.md#local-server-terreno-mcp-local).
+
+| Need | What to do |
 | --- | --- |
-| `TERRENO_PROJECT_ROOT` | Absolute app/monorepo root |
-| `TERRENO_METRO_URL` | Metro origin when the frontend script does not expose `--port` |
-| `MONGO_URI` | MongoDB used by `database_schema` and read-only `database_query` |
-| `TERRENO_MCP_EVAL=1` | Explicitly enable `evaluate`, `navigate`, and SyncDB state changes |
-| `BUN_CHROME_PATH` | Chrome/Chromium/Edge binary when Bun cannot auto-discover one |
-
-Backend and browser JSONL normally live under `<backend cwd>/.terreno/logs/`. Keep Metro running to
-collect Metro `/events` and app console output over CDP. Hermes accepts one debugger connection, so
-close React Native DevTools if the local MCP reports that CDP is unavailable.
-
-## Verify
-
-Restart the editor's MCP clients, then ask it to call `application_info`. Confirm the result lists
-the app's installed `@terreno/*` versions. Next call `read_logs` with
-`{"sources":["backend","browser"]}`; an empty `entries` array is valid before the app logs anything.
-Call `browser` with `{"action":"open","url":"http://localhost:8082"}`, then `{"action":"snapshot"}`
-to confirm the agent can inspect the running web app. Finish with `{"action":"close"}`.
-If the app creates a SyncDB client with `debug: true`, call
-`get_syncdb_state` and confirm it returns the client name, status, collections,
-outbox, conflicts, cursors, and debug events.
+| Project root | Start the editor in the app repository root. The server walks up from its working directory looking for a `package.json` with `backend/` and `frontend/` workspaces, and otherwise uses the working directory itself. Apps from `create-terreno-app` have no root `package.json`, so the walk-up never matches from a subfolder: start the editor at the app root or set `TERRENO_PROJECT_ROOT`. |
+| A reachable MongoDB | Put `MONGO_URI` in `backend/.env` (`create-terreno-app` does this) or export it. `database_schema` and `database_query` use it. |
+| Backend log file | Run the backend with `bun run dev`. Outside production the `@terreno/api` logger writes `backend/.terreno/logs/app.log`, which `read_logs` and `last_error` read. |
+| Metro for app logs | Keep `bun run web` (or `start`, `ios`, `android`) running in `frontend/`. The server reads Metro on the script's `--port` (8082 in generated apps). Set `TERRENO_METRO_URL` for another origin. |
+
+Set environment variables for the server in its config entry with `env`. For example, to point the
+server at a root and allow the gated tools:
+
+```json
+"terreno-local": {
+  "args": [
+    "-p",
+    "@terreno/mcp",
+    "terreno-mcp-local"
+  ],
+  "command": "bunx",
+  "env": {
+    "TERRENO_MCP_EVAL": "1",
+    "TERRENO_PROJECT_ROOT": "/absolute/path/to/my-app"
+  }
+}
+```
+
+`TERRENO_MCP_EVAL=1` enables `evaluate`, `navigate`, and SyncDB state changes; leave it out unless
+you need them. Every variable is listed under
+[Environment variables](../reference/mcp-server.md#environment-variables).
+
+Hermes accepts one debugger connection. Close React Native DevTools if the local server reports
+that CDP is unavailable.
+
+## 5. Optional: add expo-mcp and Playwright MCP
+
+`create-terreno-app` adds two more servers next to the Terreno ones. Keep them when you want the
+agent to drive the app, or delete their entries from both files:
+
+- **`expo`** (`https://mcp.expo.dev/mcp`) takes screenshots and taps in the iOS simulator or
+  Android emulator. It asks you to sign in with your Expo account the first time it connects. Its
+  simulator tools also need the `expo-mcp` dev package in the app
+  (`cd frontend && bunx expo install expo-mcp --dev`) and a dev server started with
+  `EXPO_UNSTABLE_MCP_SERVER=1`, which the generated frontend scripts already set. See
+  [Expo MCP Server](https://docs.expo.dev/eas/ai/mcp/).
+- **`playwright`** (`npx -y @playwright/mcp@0.0.76`) drives the web app in a full browser. The
+  version is pinned so `npx` does not resolve a moving `@latest`.
+
+These servers interact with the app. Terreno's servers observe what the app did behind the screen.
+Read [How this composes](../explanation/ai-development-loop.md#how-this-composes) for the division
+of labor, including when a flow should become a Maestro test.
+
+## 6. Verify
+
+1. Restart the editor's MCP clients.
+2. Ask the agent: "Call the `application_info` tool from `terreno-local`."
+3. Confirm the result lists your app's `@terreno/*` packages. For an app generated with
+   `create-terreno-app` and no `bun install` yet, the result is (project root shortened):
+
+   ```markdown
+   # Application info
+
+   - **projectRoot**: `…/setup-check`
+   - **root package**: (none) @ ?
+   - **bun.lock present**: no
+
+   ## Backend workspace (backend/)
+   - **name**: @setup-check/backend
+   - **version**: 1.0.0
+   - @terreno/admin-backend: ^57.14.0
+   - @terreno/api: ^57.14.0
+   - @terreno/api-health: ^57.14.0
+   - **mongoose**: 9.7.4
+   - **@types/bun**: ^1.4.0
+
+   ## Frontend workspace (frontend/)
+   - **name**: @setup-check/frontend
+   - **version**: 1.0.0
+   - @terreno/admin-frontend: ^57.14.0
+   - @terreno/rtk: ^57.14.0
+   - @terreno/syncdb: ^57.14.0
+   - @terreno/ui: ^57.14.0
+   - **expo**: ~57.0.14
+   - **react**: 19.2.3
+   - **react-native**: 0.86.2
+   - **@types/bun**: ^1.4.0
+   ```
+
+   The versions are the ranges declared in each `package.json`, not resolved versions. If
+   `projectRoot` is not your app, set `TERRENO_PROJECT_ROOT` (step 4).
+4. Ask the agent to call `terreno_search_docs` from `terreno` with any query. A list of doc results
+   confirms the hosted server.
+
+With the backend and frontend running, check the runtime tools too:
+
+- Call `read_logs` with `{"sources":["backend","browser"]}`. An empty `entries` array is valid
+  before the app logs anything. A `create-terreno-app` app sends web console errors and warnings
+  to the backend with `installTerrenoDevConsoleLogger({baseUrl})` in `frontend/app/_layout.tsx`.
+  Its `backend/.env` sets `NODE_ENV=development`, which the backend needs to accept them. In
+  another app, add the same call at startup and run the backend with `NODE_ENV=development` or
+  `TERRENO_BROWSER_LOGS=true`.
+- Call `browser` with `{"action":"open","url":"http://localhost:8082"}`, then
+  `{"action":"snapshot"}`, to confirm the agent can inspect the web app. Finish with
+  `{"action":"close"}`.
+- If the app creates its SyncDB client with `debug: true`, call `get_syncdb_state` and confirm it
+  returns the client name, status, collections, outbox, conflicts, cursors, and debug events.
 
 The CLI exposes the same local tools without MCP:
 
@@ -67,3 +266,9 @@ The CLI exposes the same local tools without MCP:
 terreno info
 terreno logs --sources backend,browser
 ```
+
+## Related
+
+- [MCP server reference](../reference/mcp-server.md): every tool, variable, and discovery rule
+- [Debug a Terreno app with MCP](debug-with-mcp.md): the loop on a real failure
+- [AI development loop](../explanation/ai-development-loop.md): how the servers fit together

package/src/docs/versioned/next/how-to/sign-consent-on-behalf.md

@@ -0,0 +1,139 @@
+# Sign consent on a user's behalf
+
+Let staff record consent for a user ahead of time, for example after a guardian agrees by
+phone at intake. The form counts as signed from then on, and the user still sees it and signs
+it themselves. Concepts: [Consent forms](../explanation/consent-forms.md#provisional-signatures).
+
+## 1. Pass access control to ConsentApp
+
+Add `userSchema.plugin(rbacUserPlugin)` (from `@terreno/api`) to your User schema so users
+have a `roles` field and role assignments are saved. Then wire RBAC into the app:
+
+```typescript
+import {
+  backfillAdmins,
+  ConsentApp,
+  createAccess,
+  rbacRouter,
+  TerrenoApp,
+  terrenoStatements,
+} from "@terreno/api";
+
+const access = createAccess({
+  connection: mongoose.connection,
+  statements: terrenoStatements,
+  userModel: User,
+});
+
+// After connecting to MongoDB: create or update the built-in roles.
+await access.roles.seedDefaults();
+// Give existing `admin: true` users the superadmin role, so they keep their access.
+await backfillAdmins({access, userModel: User, wetRun: true});
+
+new TerrenoApp({accessControl: access, userModel: User})
+  .register(rbacRouter({access, userModel: User}))
+  .register(new ConsentApp({accessControl: access, auditTrail: true}))
+  .start();
+```
+
+With `accessControl`, any authenticated user whose roles grant
+`consentResponse:signOnBehalf` may sign, read statuses, and void for other users. Without it,
+only `user.admin` users may, and `ConsentApp` logs a warning at startup. With
+`accessControl`, `user.admin` alone no longer grants signing: the user needs a role that
+grants it. Turn on
+`auditTrail` to keep the signer's IP address and user agent and a snapshot of the content they
+signed. `rbacRouter` mounts the `/rbac` role API used in step 2.
+
+Register `AuditApp` too if you want every provisional signature, status read, and void in the
+audit log.
+
+## 2. Grant the permission
+
+The built-in `admin` role includes `consentResponse: ["signOnBehalf"]`. Databases created
+before this release get it the next time roles are seeded (`access.roles.seedDefaults()`),
+without losing other grants on an unsealed `admin` role. `superadmin` has every action.
+
+For staff who are not admins, create a role and assign it. `$TOKEN` must belong to a user
+whose roles grant `rbac:manageRoles` and `rbac:assignRoles`, such as `superadmin`; the
+built-in `admin` role has neither.
+
+```bash
+curl -X POST "$API/rbac/roles" -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "intake-staff", "displayName": "Intake staff",
+       "permissions": {"consentResponse": ["signOnBehalf"]}}'
+
+curl -X PUT "$API/rbac/users/$STAFF_USER_ID/roles" -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" -d '{"roleNames": ["intake-staff"]}'
+```
+
+There is no relationship check: a permitted signer can sign for any user. Give the role only
+to staff who should have that reach.
+
+## 3. Mount the signer screen
+
+```tsx
+import {Page, ProvisionalConsentSigner} from "@terreno/ui";
+import {useLocalSearchParams} from "expo-router";
+import {terrenoApi} from "@/store/sdk";
+
+const ConsentSignScreen: React.FC = () => {
+  const {userId} = useLocalSearchParams<{userId: string}>();
+  return (
+    <Page backButton title="Sign consent on behalf">
+      <ProvisionalConsentSigner api={terrenoApi} userId={userId} />
+    </Page>
+  );
+};
+```
+
+Put the route outside your admin area if non-admin staff use it. The component lists every
+form that applies to the user with its status. Staff open a pending form, read it,
+write a note saying how consent was obtained, and sign. The user then sees "Signed on your
+behalf by <name> on <date>" above the form in their consent gate, but not the note.
+
+Build your own UI with `useProvisionalConsent({api, userId})` instead, which returns
+`statuses`, `sign`, and `voidSignature`.
+
+## 4. Check whether a user is considered signed
+
+```typescript
+import {getConsentStatuses} from "@terreno/api";
+
+const rows = await getConsentStatuses({resolveConsentForms, userId});
+const canSchedule = rows.filter((row) => row.form.required).every((row) => row.isConsented);
+```
+
+`isConsented` is true for `signed` and `provisional`. The user's own answer always wins: once
+they agree the row is `signed`, and once they decline it is `declined`. Pass the same
+`resolveConsentForms` you gave `ConsentApp`. Clients call `GET /consent-responses/status?userId=`
+for the same rows.
+
+## 5. Void a signature made in error
+
+In `ProvisionalConsentSigner`, press "Void" on a provisional row and give a reason. Over HTTP:
+
+```bash
+curl -X POST "$API/consent-responses/$RESPONSE_ID/void" -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" -d '{"reason": "Signed for the wrong member"}'
+```
+
+The record stays, with `voidedAt`, `voidedBy`, and `voidReason` set. The form returns to
+`pending` and the user's notice disappears.
+
+## 6. Print a consent record
+
+- `ProvisionalConsentSigner`: "Print" on a provisional, signed, or declined row, or on the
+  confirmation after signing.
+- Admin: the "Print" button on `ConsentResponseViewer` (`@terreno/admin-frontend`).
+- The user's own history: the print icon on a `ConsentHistory` entry
+  (`@terreno/admin-frontend`).
+
+When the record is provisional, the printout includes a "Provisional signature" section with
+the signer and date. Staff and
+admin printouts also show the note; the user's own printout never does. To print your own
+HTML, call `printConsentHtml({html: buildConsentPdfHtml(data)})` from `@terreno/ui`.
+
+Reference: [ConsentApp](../reference/api.md#consent-forms-consentapp),
+[consent components](../reference/ui.md#consent-components),
+[consent records and PDFs](../reference/admin-frontend.md#consent-records-and-pdfs).

package/src/docs/versioned/next/how-to/upgrade-terreno.md

@@ -80,3 +80,7 @@ bun install
 ```
 
 If you already committed, `git revert` the upgrade commit or reset the branch to the pre-upgrade SHA before it was pushed. Do not leave a half-upgraded lockfile on `master`.
+
+## 8. Automate it
+
+To have an agent open the upgrade pull request on a schedule, see [Automate Terreno upgrades](automate-terreno-upgrades.md).

package/src/docs/versioned/next/implementationPlans/ai-dev-loop-boost.md

@@ -7,19 +7,19 @@
 **Owner:** unassigned
 **Created:** 2026-07-27
 **Program:** [OSS launch](oss-launch-program.md)
-**Depends on:** PR [#802](https://github.com/TerrenoLabs/terreno/pull/802) merging (assumed)
-**RTK deprecation flag:** **Partial** — `get_rtk_state` and `installTerrenoDevConsoleLogger` are RTK-named surfaces delivered by #802 that must be renamed or relocated after #869. Marked tasks are blocked on both PRs.
+**Depends on:** PR [#802](https://github.com/TerrenoLabs/terreno/pull/802) merging (assumed). **Reconciled 2026-10-12:** #802 and #869 were both closed unmerged, but their substance is on `master` through later PRs (CDP log tools, Metro sessions, the browser-log route, `@terreno/syncdb`, and `get_syncdb_state`; mainly #1128). Read "merged #802" in this plan as "current `master`".
+**RTK deprecation flag:** **Partial** — `get_rtk_state` and `installTerrenoDevConsoleLogger` are RTK-named surfaces that must be renamed or relocated now that `@terreno/syncdb` exists (the #869 substance). Both are on `master`, so the marked tasks are no longer blocked on unmerged PRs.
 
 ## Goal
 
-Turn Terreno's AI-native pillar from a claim into a documented, demonstrable loop. The machinery mostly exists after PR #802 lands: an agent can search current docs, generate conventional code, run the app, read merged logs from four sources, see the last error with a stack, inspect client state, and drive navigation. What does not exist is any document that explains this as a single workflow, so nobody outside the team knows it is there.
+Turn Terreno's AI-native pillar from a claim into a documented, demonstrable loop. The machinery exists on `master`: an agent can search current docs, generate conventional code, run the app, read merged logs from four sources, see the last error with a stack, inspect client state, and drive navigation. What does not exist is any document that explains this as a single workflow, so nobody outside the team knows it is there.
 
 This IP writes the story and closes the gaps that become obvious once the story is written down.
 
 ## Non-Goals
 
 - Building new MCP tools beyond renames and small gap-fillers.
-- Re-implementing UI automation — #802 deliberately composes `expo-mcp`, Playwright MCP, and Maestro rather than building tap/screenshot tooling.
+- Re-implementing UI automation — #802 deliberately composes `expo-mcp`, Playwright MCP, and Maestro rather than building tap/screenshot tooling. (Fact check 2026-10-12: `master` has since added a web-only `browser` tool to `terreno-mcp-local`, built on Bun's WebView, with `snapshot` and `screenshot` actions. Native simulator interaction still comes from `expo-mcp`.)
 - The tutorial itself (that is [`docs-tutorials-ai-first`](docs-tutorials-ai-first.md), which depends on this IP's reference content).
 - Langfuse/observability for AI features inside consumer apps (that is `terreno-langfuse-integration.md`).
 
@@ -43,10 +43,10 @@ This IP writes the story and closes the gaps that become obvious once the story
 ```mermaid
 flowchart LR
   ASK["1. Ask<br/>terreno_search_docs<br/>terreno_get_component_docs"]
-  GEN["2. Generate<br/>generate_model / route / screen<br/>validate_model_schema"]
+  GEN["2. Generate<br/>terreno_generate_model / _route / _screen<br/>terreno_validate_model_schema"]
   RUN["3. Run<br/>bun run backend:dev<br/>expo start"]
   OBS["4. Observe<br/>read_logs (backend/app/metro/browser)<br/>last_error<br/>get_client_state"]
-  FIX["5. Fix<br/>navigate + screenshot<br/>regenerate typed client"]
+  FIX["5. Fix<br/>navigate + browser screenshot<br/>regenerate typed client"]
   ASK --> GEN --> RUN --> OBS --> FIX
   FIX -->|"iterate"| ASK
 ```
@@ -64,46 +64,61 @@ This loop is only half the AI story, and documenting it alone undersells it. The
 
 Every document produced by this IP must name both and explain that they compose: the pipeline's implement stage uses the loop's tools, and the loop's tools are most useful when driven by the pipeline's sequencing. `docs/explanation/ai-development-loop.md` and `docs/explanation/agentic-sdlc.md` are companion pages and must cross-link.
 
-### Tool surface after #802
+### Tool surface (reconciled with master, 2026-10-12)
+
+Every name below is registered in source. The hosted server (`terreno-mcp`, `mcp-server/src/index.ts`) registers tools from `mcp-server/src/tools.ts` and `mcp-server/src/bootstrap.ts`. The local stdio server (`terreno-mcp-local`, `mcp-server/src/local/`) registers tools only, from `mcp-server/src/local/localTools.ts`. Full input schemas and every environment variable, with the file that reads it, are in the Task 1.1 evidence (`.terreno/pipeline/ai-dev-loop-boost-evidence/inventory.md`).
 
 | Tool | Server | Purpose |
 |------|--------|---------|
-| `terreno_search_docs` | hosted | BM25 search over the docs corpus, multi-query |
-| `terreno_get_component_docs` | hosted | Full props table for a `@terreno/ui` component |
+| `terreno_search_docs` | hosted | BM25 search over the docs corpus, multi-query, optional `packages` and lockstep `version` |
+| `terreno_get_component_docs` | hosted | Full props table for a `@terreno/ui` component, optional `version` |
 | `terreno_get_upgrade_guide` | hosted | Concatenated upgrade notes for a version range |
-| `terreno_bootstrap_app` / `terreno_bootstrap_ai_rules` | hosted | Scaffold an app / agent rules |
-| `terreno_generate_*`, `terreno_validate_model_schema`, `terreno_install_admin` | hosted | Codegen |
+| `terreno_search_update_notes` / `terreno_get_update_note` / `terreno_ask_update_help` | hosted | Search, fetch, and question bundled upgrade notes, plus help-API announcements when `TERRENO_HELP_API_URL` is set |
+| `terreno_bootstrap_ai_rules` | hosted | Agent rule files for Cursor, Windsurf, Claude Code, and Copilot. App scaffolding moved to `bunx create-terreno-app`, and `terreno_bootstrap_app` no longer exists. |
+| `terreno_generate_model` / `terreno_generate_route` / `terreno_generate_screen` / `terreno_generate_form_fields` | hosted | Codegen |
+| `terreno_validate_model_schema` / `terreno_validate_ui_blocks` | hosted | Convention and block-document validation |
+| `terreno_install_admin` | hosted | Admin panel integration snippets |
 | `application_info` | local | `@terreno/*` and toolchain versions |
-| `database_schema` / `database_query` | local | Mongo introspection, read-only allowlist |
-| `read_logs` | local | Merged backend + app (CDP) + Metro + browser logs |
-| `last_error` | local | Most recent error with stack across sources |
-| `get_rtk_state` → `get_client_state` | local | Store and cache inspection |
-| `evaluate` / `navigate` | local | CDP runtime, `TERRENO_MCP_EVAL=1` gated |
+| `database_schema` / `database_query` | local | Mongo introspection with a read-only allowlist, using `MONGO_URI` or `backend/.env` |
+| `read_logs` | local | Merged logs from `backend` (JSONL), `browser` (JSONL), `metro` (`/events`), and `app` (Hermes console over CDP) |
+| `last_error` | local | Raw JSONL line of the newest error-level entry across the same four sources. A stack is included only when the entry carries one. |
+| `get_rtk_state` | local | Redux auth and RTK Query cache inspection (in-process or CDP). It is not gated. This is the tool that AI1 renames to `get_client_state`; `get_client_state` does not exist yet. |
+| `get_syncdb_state` / `syncdb_snapshot` / `syncdb_action` | local | SyncDB inspection, snapshots, and actions. `syncdb_action` is gated by `TERRENO_MCP_EVAL=1`. |
+| `evaluate` / `navigate` | local | CDP `Runtime.evaluate` and expo-router navigation, both gated by `TERRENO_MCP_EVAL=1` |
+| `browser` | local | Headless web driving through Bun 1.4 WebView: open, click, type, snapshot, and screenshot. Only its `evaluate` action is gated by `TERRENO_MCP_EVAL=1`. |
+
+Prompts (hosted only): `terreno_bootstrap`, `terreno_create_crud_feature`, `terreno_create_api_endpoint`, `terreno_create_ui_component`, `terreno_create_form_screen`, `terreno_add_authentication`, `terreno_style_guide`, `terreno_migrate_to_terreno_app`, `terreno_upgrade`. Resources (hosted only): `terreno://docs/{overview,api,ui,syncdb,rtk,patterns}`, plus `terreno://docs/ui/components` and one `terreno://docs/ui/components/<slug>` per component.
 
 ### Gaps that surface once the story is written
 
-1. **Naming**: `get_rtk_state` is named after a package being deprecated (AI1).
-2. **Discovery**: nothing tells a developer to install `terreno-mcp-local`. `docs/reference/mcp-server.md` documents it, but no getting-started path mentions it.
-3. **Hermes single-connection contention**: opening React Native DevTools steals the CDP connection the log tools need. #802 mitigates with lazy connect/release and status reporting; users need to know the symptom.
-4. **No end-to-end setup guide**: MCP configuration is scattered across the README and the reference page, per-editor, with no single how-to.
-5. **Hosted server has no rate limiting** (AI5) — a launch risk.
-6. **Composition is undocumented**: `expo-mcp` and Playwright MCP wiring exists in bootstrap output but is not explained (AI4).
+1. **Naming**: `get_rtk_state` is named after a package being deprecated (AI1). It reads Redux only. SyncDB state has its own tool (`get_syncdb_state`), so `get_client_state` must decide whether to reuse that bridge or report the SyncDB layer itself.
+2. **Discovery**: `docs/how-to/set-up-terreno-mcp.md` now exists. It is linked from `docs/README.md`, `docs/how-to/README.md`, `docs/reference/mcp-server.md`, and the `terreno://docs/overview` resource, but not from the root `README.md` or `docs/tutorials/README.md`. `create-terreno-app` writes `terreno-local` into `.cursor/mcp.json` but does not point at the guide.
+3. **Hermes single-connection contention**: opening React Native DevTools steals the CDP connection the log tools need. `master` connects lazily and holds the socket for the life of the MCP process; there is no release. On close it reports `CDP disconnected` and reconnects on the next call. Status reaches the agent in `read_logs`' `connection` field (`CDP: …; Metro events: …`). Users need to know the symptom.
+4. **Setup guide is incomplete and inconsistent**: `docs/how-to/set-up-terreno-mcp.md` covers Cursor and Claude Code for both servers. It uses `https://mcp.terreno.flourish.health/mcp`, while `create-terreno-app` and the root README use `https://mcp.terreno.app` (AI6). It also omits `expo-mcp` and Playwright MCP.
+5. **Hosted server has no rate limiting** (AI5), which is a launch risk. Neither `mcp-server/src/index.ts` nor the `mcp_service` Cloud Run module in `terraform/main.tf` limits requests, and the service allows unauthenticated access. `@terreno/api`'s opt-in `rateLimit` does not apply, because the hosted server uses `createMcpExpressApp`, not `TerrenoApp`.
+6. **Composition is undocumented**: `create-terreno-app` writes `expo` (`https://mcp.expo.dev/mcp`) and `playwright` (`@playwright/mcp`) entries into `.cursor/mcp.json` (`create-terreno-app/src/generate.ts`), but no doc explains them (AI4).
+7. **Reference drift**: `docs/reference/mcp-server.md` has no sections for `application_info`, `database_schema`, `database_query`, `read_logs`, `last_error`, `get_rtk_state`, `evaluate`, `navigate`, or the three update-note tools. Its env table omits `TERRENO_HELP_API_URL`, `TERRENO_HELP_API_TOKEN`, `MONGO_URI`, `TERRENO_LOG_FILE`, and the Sentry variables. `mcp-server/README.md` omits `terreno_validate_ui_blocks` and lists only the SyncDB local tools.
 
 ### Documentation to produce
 
 | Document | Purpose |
 |----------|---------|
 | `docs/explanation/ai-development-loop.md` | The five-stage loop, why it is different, what the agent can and cannot see |
-| `docs/how-to/set-up-terreno-mcp.md` | Per-editor configuration for both Terreno servers plus composed servers |
-| `docs/how-to/debug-with-mcp.md` | Using `read_logs`, `last_error`, `get_client_state`, `navigate` on a real failure |
-| `docs/reference/mcp-server.md` | Updated with the complete post-#802 tool surface and every environment variable |
+| `docs/how-to/set-up-terreno-mcp.md` | Per-editor configuration for both Terreno servers plus composed servers. This page already exists on `master`, so update it rather than create it. |
+| `docs/how-to/debug-with-mcp.md` | Using `read_logs`, `last_error`, `get_client_state`, `navigate` on a real failure. This page already exists on `master` and covers `get_rtk_state` and the SyncDB tools; update it. |
+| `docs/reference/mcp-server.md` | Updated with the complete tool surface on `master` and every environment variable |
 | `docs/explanation/agent-guidelines.md` | How per-package `.ai/` guidelines and `.rulesync/` rules reach an agent, and how consumers extend them |
 
 Companion page owned elsewhere: `docs/explanation/agentic-sdlc.md` (the process layer) from [`agentic-sdlc-plugin`](agentic-sdlc-plugin.md). Neither page should duplicate the other; each links the other as the missing half.
 
 ## Models / APIs
 
-No new models. `POST /__terreno/browser-logs` (dev-only, from #802) needs documenting including its production-disabled behavior and the `TERRENO_BROWSER_LOGS` override.
+No new models. `POST /__terreno/browser-logs` (dev-only, `api/src/browserLogsRoute.ts`) needs documenting, including its production-disabled behavior and the `TERRENO_BROWSER_LOGS` override. Facts on `master`:
+
+- Only `TerrenoApp` registers the route, not legacy `setupServer`.
+- By default it is on only when `NODE_ENV === "development"`. An unset `NODE_ENV` leaves it off unless `TERRENO_BROWSER_LOGS=true`.
+- It is never registered in `production`, so requests there get a 404.
+- It returns 403 to clients that are neither loopback nor authenticated.
 
 ## Notifications
 
@@ -115,17 +130,18 @@ None. `installTerrenoDevConsoleLogger` is invisible instrumentation.
 
 ## Phases
 
-1. **Reconcile with merged #802** — verify the actual tool names, parameters, and environment variables.
+1. **Reconcile with `master`** (#802 and #869 closed unmerged; their substance landed through later PRs): verify the actual tool names, parameters, and environment variables.
 2. **Reference completeness** — update `docs/reference/mcp-server.md` to the real surface.
 3. **The loop explainer** — `ai-development-loop.md`.
 4. **Setup and debug how-tos** — including composed servers.
-5. **Gap fixes** — the `get_client_state` rename (post-#869), logger relocation, hosted rate limiting, discovery paths.
+5. **Gap fixes** — the `get_client_state` rename (`@terreno/syncdb` is on `master`), logger relocation, hosted rate limiting, discovery paths, and the CDP `Origin` header fix that Task 1.3 found (Task 5.5).
 6. **Agent guidelines explainer** — how guidelines reach agents and how consumers extend them.
 
 ## Feature Flags & Migrations
 
-- `TERRENO_MCP_EVAL=1` gates `evaluate` and `navigate`; never enabled by bootstrap defaults.
-- `TERRENO_BROWSER_LOGS` and `NODE_ENV` gate the browser-log route.
+- `TERRENO_MCP_EVAL=1` (or `true`) gates `evaluate`, `navigate`, `syncdb_action`, and the `browser` tool's `evaluate` action. It does not gate `get_rtk_state`, `get_syncdb_state`, or `syncdb_snapshot`, which read app state over CDP with fixed expressions. The `.cursor/mcp.json` that `create-terreno-app` generates never sets it.
+- `TERRENO_BROWSER_LOGS` and `NODE_ENV` gate the browser-log route (`api/src/browserLogsRoute.ts`). By default it is on only when `NODE_ENV=development`.
+- `TERRENO_LOG_FILE` and `NODE_ENV` gate the backend JSONL file that `read_logs` reads (`api/src/logger.ts`). By default it is on whenever `NODE_ENV !== "production"`.
 - Renaming `get_rtk_state` to `get_client_state` is a breaking MCP tool change: keep the old name as an alias for one release with a deprecation note in its description.
 
 ## Not Included / Future Work
@@ -140,12 +156,11 @@ None. `installTerrenoDevConsoleLogger` is invisible instrumentation.
 **Create**
 
 - `docs/explanation/ai-development-loop.md`
-- `docs/how-to/set-up-terreno-mcp.md`
-- `docs/how-to/debug-with-mcp.md`
 - `docs/explanation/agent-guidelines.md`
 
 **Modify**
 
+- `docs/how-to/set-up-terreno-mcp.md`, `docs/how-to/debug-with-mcp.md` (both already on `master`)
 - `docs/reference/mcp-server.md`, `mcp-server/README.md`
 - `mcp-server/src/local/tools/runtime.ts` (tool rename + alias)
 - `mcp-server/src/local/localTools.ts` (tool registration)