@terreno/mcp 57.19.2 → 57.20.0

package/dist/docs/versioned/next/how-to/create-a-terreno-app.md

@@ -37,7 +37,7 @@ Optional flags:
 | `appName` (positional) | yes | — kebab-case directory and package name (`^[a-z][a-z0-9-]*$`) |
 | `--display-name` | unless `--yes` | derived from `appName` when `--yes` |
 | `--description` | no | empty |
-| `--mcp-server-url` | no | `https://mcp.terreno.app` |
+| `--mcp-server-url` | no | `https://mcp.terreno.app` (base URL; the CLI appends `/mcp`) |
 | `--yes` | no | off |
 
 The CLI creates `<cwd>/<appName>/`. Package source: [`create-terreno-app/`](https://github.com/TerrenoLabs/terreno/tree/master/create-terreno-app) in the Terreno monorepo.
@@ -61,11 +61,11 @@ cd .. && bunx create-terreno-app my-app --yes
 | `frontend/` | Expo universal app (`@terreno/ui`, `@terreno/syncdb`, `@terreno/rtk`) |
 | `Dockerfile` | Consumer backend image (`backend/` only — not the Terreno monorepo) |
 | `.dockerignore` | Excludes local env secrets, dependencies, and build output from the image context |
-| `backend/.env`, `frontend/.env` | Gitignored local-dev defaults (written on scaffold) |
+| `backend/.env`, `frontend/.env` | Gitignored local-dev defaults (written on scaffold). `backend/.env` sets `NODE_ENV=development`, which turns on the dev-only `POST /__terreno/browser-logs` route |
 | `backend/.env.example`, `frontend/.env.example` | Committed templates for production and export |
 | `.github/workflows/` | Backend and frontend CI |
-| `.cursor/mcp.json`, `.cursorrules`, `CLAUDE.md` | Agent tooling |
-| `README.md` | App-specific next steps and deploy links |
+| `.cursor/mcp.json`, `.mcp.json`, `.cursorrules`, `CLAUDE.md` | Agent tooling ([Set up Terreno MCP](set-up-terreno-mcp.md)) |
+| `README.md` | App-specific next steps, deploy links, and a link to [Set up Terreno MCP](set-up-terreno-mcp.md) |
 
 Generated `@terreno/*` dependencies pin to `^<create-terreno-app version>` at scaffold time.
 
@@ -130,6 +130,8 @@ Open `http://localhost:8082` and sign in as `test@example.com` / `testpassword12
 
 `frontend/.env` defaults `EXPO_PUBLIC_API_URL` to `http://localhost:4000`. For production web builds, set it **before** export — see [Build for web](build-for-web.md).
 
+In development, `frontend/app/_layout.tsx` calls `installTerrenoDevConsoleLogger({baseUrl})` from `@terreno/syncdb` at startup. It sends console errors, warnings, and uncaught errors to the backend's `POST /__terreno/browser-logs`, which writes `backend/.terreno/logs/browser.log`. `terreno-mcp-local` reads that file for `read_logs` and `last_error` with the `browser` source. The call does nothing in production builds. See [Set up Terreno MCP](set-up-terreno-mcp.md).
+
 ## Deploy
 
 Read the [deployment baseline](../explanation/deployment-baseline.md) first.
@@ -142,10 +144,11 @@ docker run --rm -p 8080:8080 \
   -e MONGO_URI='mongodb+srv://...' \
   -e BETTER_AUTH_SECRET='...' \
   -e BETTER_AUTH_URL='https://api.example.com' \
+  -e FRONTEND_URL='https://app.example.com' \
   my-app-backend
 ```
 
-Cloud Run concepts and commands: [Deploy backend to Cloud Run](deploy-backend-to-cloud-run.md). That guide targets Terreno's monorepo example; for a generated app, keep the root `Dockerfile`, port `8080`, and Better Auth variables shown here. The generated backend throws if `BETTER_AUTH_SECRET` is unset. `GET /users` list and read require an admin.
+Cloud Run concepts and commands: [Deploy backend to Cloud Run](deploy-backend-to-cloud-run.md). That guide targets Terreno's monorepo example; for a generated app, keep the root `Dockerfile`, port `8080`, and Better Auth variables shown here. The generated backend throws if `BETTER_AUTH_SECRET` is unset. Set `FRONTEND_URL` to the web app's URL: until it is set, a production backend leaves passkeys off (see [Auth features in generated apps](configure-better-auth.md#auth-features-in-generated-apps)). `GET /users` list and read require an admin.
 
 **Frontend:** [Build for web](build-for-web.md) — set `EXPO_PUBLIC_API_URL` at export time.
 

package/dist/docs/versioned/next/how-to/debug-with-mcp.md

@@ -1,18 +1,378 @@
 # Debug a Terreno app with MCP
 
-Start the backend and frontend, reproduce the failure once, then inspect the merged runtime evidence
-instead of copying logs into the agent chat.
+Use the local MCP server (`terreno-mcp-local`) to go from a symptom to a verified fix without
+pasting logs into the chat. This guide follows one real failure from start to finish, then lists
+what each tool does. Every tool output below was copied unchanged from a real run against
+`example-backend` and `example-frontend` on web.
+
+## Which tool for which symptom
+
+| Symptom | Start with | Then |
+|---------|------------|------|
+| API returns 500 | `last_error` with `sources: ["backend"]`. The stack is inside `message`. | `read_logs` with `sources: ["backend"]` and `since` to see the requests around it. |
+| API returns 403 (or another 4xx) | `read_logs` with `sources: ["backend"]` and `level: "warn"`. Every `APIError` under 500 is logged at `warn` as `ForbiddenError(403): <title> — <detail>`, so `last_error` does not show it. | `database_query` to compare the document's `ownerId` with the user in the log line. |
+| App crashes on a screen | Web: `last_error` with `sources: ["browser"]`. An uncaught error carries a separate `stack` field. A render error caught by an error boundary has no `stack`; its `message` names the component instead (see [A screen crashes on web](#a-screen-crashes-on-web)). Native: `last_error` with `sources: ["app"]`. | Native: `navigate` to the screen and call `last_error` again. Web: the `browser` tool. |
+| Data looks wrong | `database_query` to read what the server stored. | `get_client_state` (RTK cache) or `get_syncdb_state` (SyncDB) to compare the client's copy. |
+| Screen renders empty | `get_client_state` or `get_syncdb_state` on native. On web, `browser` with `snapshot`. | `read_logs` with `sources: ["backend"]` to check that the list request ran and returned 200. |
+| Bundler fails | The terminal that runs `expo start`. The `metro` source is always empty under Expo CLI 57: the `/events` socket connects but Expo never sends on it. | On native, `read_logs` with `sources: ["app"]` once the app loads again. |
+
+`level` matches one level exactly. `level: "error"` does not include `warn`.
+
+## Walkthrough: a malformed request body returns 500
+
+The run used the example backend on port 4200 with `NODE_ENV=development`, the web app on port
+8282, and the seeded user `test@example.com`. The MCP server was started with
+`TERRENO_PROJECT_ROOT` set to the repository and `TERRENO_METRO_URL=http://localhost:8282`.
+
+### 1. See the symptom
+
+A client sent a JSON body with a typo (`fals`). The server answered 500. A malformed body is the
+client's mistake, so it should be a 400 that says what is wrong.
+
+```text
+$ curl -s -i -b cookies.txt -X POST localhost:4200/todos -H 'Content-Type: application/json' --data '{"title": "Buy milk", "completed": fals}'
+HTTP/1.1 500 Internal Server Error
+X-Powered-By: Express
+X-Request-ID: 5ccfb98c-f592-42ce-9503-415c0c75f32f
+Vary: Origin
+Access-Control-Allow-Credentials: true
+Content-Type: application/json; charset=utf-8
+Content-Length: 46
+Date: Mon, 12 Oct 2026 02:45:16 GMT
+Connection: keep-alive
+Keep-Alive: timeout=5
+
+{"status":500,"title":"Internal server error"}
+```
+
+### 2. Locate it with `last_error`
+
+```json
+{"name":"last_error","arguments":{"sources":["backend","browser"]}}
+```
+
+```json
+{"level":"error","message":"Fallthrough error: SyntaxError: JSON Parse error: Unexpected identifier \"fals\"\nSyntaxError: JSON Parse error: Unexpected identifier \"fals\"\n    at <parse> (:0)\n    at parse (unknown)\n    at parse (/workspace/.claude/worktrees/agent-a4ec9221d12c64054/node_modules/body-parser/lib/types/json.js:91:21)\n    at <anonymous> (/workspace/.claude/worktrees/agent-a4ec9221d12c64054/node_modules/body-parser/lib/read.js:162:18)\n    at runInAsyncScope (node:async_hooks:207:23)\n    at invokeCallback (/workspace/.claude/worktrees/agent-a4ec9221d12c64054/node_modules/raw-body/index.js:238:16)\n    at done (/workspace/.claude/worktrees/agent-a4ec9221d12c64054/node_modules/raw-body/index.js:227:7)\n    at onEnd (/workspace/.claude/worktrees/agent-a4ec9221d12c64054/node_modules/raw-body/index.js:287:7)\n    at emit (node:events:97:22)\n    at endReadableNT (internal:streams/readable:901:50)\n    at processTicksAndRejections (native:7:39)","requestId":"5ccfb98c-f592-42ce-9503-415c0c75f32f","terrenoRequestLog":{"requestId":"5ccfb98c-f592-42ce-9503-415c0c75f32f","userId":null},"timestamp":"2026-10-12T02:45:16.902Z"}
+```
+
+What this tells you:
+
+- `requestId` matches the `X-Request-ID` header from step 1, so this is the same request.
+- `Fallthrough error` comes from `apiFallthroughErrorMiddleware`. That handler only sees errors
+  that `apiErrorMiddleware` could not turn into an `APIError`, and it always answers 500.
+- The top frame is `body-parser/lib/types/json.js`. The body failed to parse before any route ran.
+- `userId` is `null` even though the request sent a session cookie. Authentication runs after body
+  parsing, so the request never got that far.
+
+### 3. Read the surrounding context with `read_logs`
+
+Filter to the backend and start from a time just before the failure. A valid request for the same
+route was sent afterwards to compare.
+
+```json
+{"name":"read_logs","arguments":{"sources":["backend"],"since":"2026-10-12T02:45:02.876Z","entries":20}}
+```
+
+```json
+{
+  "connection": "CDP: not connected; Metro events: not connected",
+  "entries": [
+    {
+      "level": "error",
+      "message": "Fallthrough error: SyntaxError: JSON Parse error: Unexpected identifier \"fals\"\nSyntaxError: JSON Parse error: Unexpected identifier \"fals\"\n    at <parse> (:0)\n    at parse (unknown)\n    at parse (/workspace/.claude/worktrees/agent-a4ec9221d12c64054/node_modules/body-parser/lib/types/json.js:91:21)\n    at <anonymous> (/workspace/.claude/worktrees/agent-a4ec9221d12c64054/node_modules/body-parser/lib/read.js:162:18)\n    at runInAsyncScope (node:async_hooks:207:23)\n    at invokeCallback (/workspace/.claude/worktrees/agent-a4ec9221d12c64054/node_modules/raw-body/index.js:238:16)\n    at done (/workspace/.claude/worktrees/agent-a4ec9221d12c64054/node_modules/raw-body/index.js:227:7)\n    at onEnd (/workspace/.claude/worktrees/agent-a4ec9221d12c64054/node_modules/raw-body/index.js:287:7)\n    at emit (node:events:97:22)\n    at endReadableNT (internal:streams/readable:901:50)\n    at processTicksAndRejections (native:7:39)",
+      "raw": "{\"level\":\"error\",\"message\":\"Fallthrough error: SyntaxError: JSON Parse error: Unexpected identifier \\\"fals\\\"\\nSyntaxError: JSON Parse error: Unexpected identifier \\\"fals\\\"\\n    at <parse> (:0)\\n    at parse (unknown)\\n    at parse (/workspace/.claude/worktrees/agent-a4ec9221d12c64054/node_modules/body-parser/lib/types/json.js:91:21)\\n    at <anonymous> (/workspace/.claude/worktrees/agent-a4ec9221d12c64054/node_modules/body-parser/lib/read.js:162:18)\\n    at runInAsyncScope (node:async_hooks:207:23)\\n    at invokeCallback (/workspace/.claude/worktrees/agent-a4ec9221d12c64054/node_modules/raw-body/index.js:238:16)\\n    at done (/workspace/.claude/worktrees/agent-a4ec9221d12c64054/node_modules/raw-body/index.js:227:7)\\n    at onEnd (/workspace/.claude/worktrees/agent-a4ec9221d12c64054/node_modules/raw-body/index.js:287:7)\\n    at emit (node:events:97:22)\\n    at endReadableNT (internal:streams/readable:901:50)\\n    at processTicksAndRejections (native:7:39)\",\"requestId\":\"5ccfb98c-f592-42ce-9503-415c0c75f32f\",\"terrenoRequestLog\":{\"requestId\":\"5ccfb98c-f592-42ce-9503-415c0c75f32f\",\"userId\":null},\"timestamp\":\"2026-10-12T02:45:16.902Z\"}",
+      "source": "backend",
+      "timestamp": "2026-10-12T02:45:16.902Z"
+    },
+    {
+      "level": "debug",
+      "message": "POST <- /todos <User:6acc4989b98fcbeba02df577> Body: {\"title\":\"Buy milk\",\"completed\":false}",
+      "raw": "{\"level\":\"debug\",\"message\":\"POST <- /todos <User:6acc4989b98fcbeba02df577> Body: {\\\"title\\\":\\\"Buy milk\\\",\\\"completed\\\":false}\",\"requestId\":\"91b0a231-17d7-42ef-8794-570410c99fc7\",\"sessionId\":\"6acc49aed7ff6fef9a4a80c9\",\"terrenoRequestLog\":{\"requestId\":\"91b0a231-17d7-42ef-8794-570410c99fc7\",\"userId\":\"6acc4989b98fcbeba02df577\"},\"timestamp\":\"2026-10-12T02:45:26.017Z\",\"userId\":\"6acc4989b98fcbeba02df577\"}",
+      "source": "backend",
+      "timestamp": "2026-10-12T02:45:26.017Z"
+    },
+    {
+      "level": "info",
+      "message": "[comms:mail] recipients=1 subjectLength=10",
+      "raw": "{\"level\":\"info\",\"message\":\"[comms:mail] recipients=1 subjectLength=10\",\"requestId\":\"91b0a231-17d7-42ef-8794-570410c99fc7\",\"sessionId\":\"6acc49aed7ff6fef9a4a80c9\",\"terrenoRequestLog\":{\"requestId\":\"91b0a231-17d7-42ef-8794-570410c99fc7\",\"userId\":\"6acc4989b98fcbeba02df577\"},\"timestamp\":\"2026-10-12T02:45:26.101Z\",\"userId\":\"6acc4989b98fcbeba02df577\"}",
+      "source": "backend",
+      "timestamp": "2026-10-12T02:45:26.101Z"
+    },
+    {
+      "level": "debug",
+      "message": "POST -> /todos 201 108.791011ms",
+      "raw": "{\"level\":\"debug\",\"message\":\"POST -> /todos 201 108.791011ms\",\"requestId\":\"91b0a231-17d7-42ef-8794-570410c99fc7\",\"sessionId\":\"6acc49aed7ff6fef9a4a80c9\",\"terrenoRequestLog\":{\"requestId\":\"91b0a231-17d7-42ef-8794-570410c99fc7\",\"userId\":\"6acc4989b98fcbeba02df577\"},\"timestamp\":\"2026-10-12T02:45:26.126Z\",\"userId\":\"6acc4989b98fcbeba02df577\"}",
+      "source": "backend",
+      "timestamp": "2026-10-12T02:45:26.126Z"
+    }
+  ],
+  "projectRoot": "/workspace/.claude/worktrees/agent-a4ec9221d12c64054"
+}
+```
+
+The valid request logs `POST <- /todos` with the user and `POST -> /todos 201`. The malformed one
+has neither line, only the error. That confirms it never reached request logging, auth, or the
+`/todos` router. The fix belongs in the app-level error handling, not in the todo route.
+
+`raw` is the log line exactly as the backend wrote it. `connection` reports the Metro and Hermes
+sources; it does not affect `backend` entries.
+
+### 4. Check the data with `database_query`
+
+Did the failed request write anything?
+
+```json
+{"name":"database_query","arguments":{"collection":"todos","operation":"find","filter":{"title":"Buy milk"},"limit":5}}
+```
+
+```json
+{
+  "collection": "todos",
+  "count": 1,
+  "rows": [
+    {
+      "_id": "6acc49c6d7ff6fef9a4a80ca",
+      "completed": false,
+      "ownerId": "6acc4989b98fcbeba02df577",
+      "tags": [],
+      "title": "Buy milk",
+      "updated": "2026-10-12T02:45:26.060Z",
+      "created": "2026-10-12T02:45:26.060Z",
+      "deleted": false,
+      "_syncPrevStream": null,
+      "_syncSeq": 3,
+      "__v": 0
+    }
+  ]
+}
+```
+
+One row, created at `02:45:26` by the valid request. The malformed request at `02:45:16` wrote
+nothing, so there is no bad data to clean up.
+
+### 5. Check the client with `get_client_state`
+
+```json
+{"name":"get_client_state","arguments":{"slice":"rtk"}}
+```
+
+On web this returns `layer: "none"`:
+
+```json
+{
+  "connection": "CDP: Error: No debuggable Hermes/React Native target with webSocketDebuggerUrl (is the app running?); Metro events: not connected",
+  "hint": "No client data layer found. For RTK Query, call `registerTerrenoDevStore(store)` from @terreno/rtk in __DEV__. For SyncDB, create the client with `createSyncDb({debug: true})`. Keep the app running; when the MCP process cannot see the app heap, start Metro so CDP can reach Hermes (see `connection`).",
+  "layer": "none",
+  "reasons": {
+    "rtk": "Error: No debuggable Hermes/React Native target with webSocketDebuggerUrl (is the app running?)",
+    "syncdb": "Error: Error: No debuggable Hermes/React Native target with webSocketDebuggerUrl (is the app running?)\nCDP: Error: No debuggable Hermes/React Native target with webSocketDebuggerUrl (is the app running?); Metro events: not connected"
+  }
+}
+```
+
+`get_client_state` reads the client through Hermes over CDP. A web page runs in the browser, not
+Hermes, so there is no target even though the store is registered. To check client state on web,
+use the `browser` tool (step 8). On iOS or Android, run a development build attached to Metro and
+the same call returns the RTK or SyncDB state.
 
-## 1. Read the latest error
+This failure is server-side, so the client check only confirms there is nothing to fix there.
 
-Call the local MCP tool:
+### 6. Fix it
+
+`apiErrorMiddleware` already converts Mongoose validation and cast errors to `APIError`s. It now
+also converts body-parser client errors through a new `bodyParserErrorToAPIError` helper in
+`api/src/errors.ts`:
+
+```typescript
+const apiError = isAPIError(err)
+  ? err
+  : (mongooseErrorToAPIError(err) ?? bodyParserErrorToAPIError(err));
+```
+
+The helper keeps the parser's own 4xx status and message. A malformed body becomes 400
+`Malformed request body`, an oversized body 413 `Request body too large`, and an unsupported
+charset 415 `Unsupported request body encoding`. Errors body-parser marks as server faults still
+fall through to 500. Regression tests in `api/src/errors.test.ts` build an app with the same
+middleware order as `TerrenoApp` and fail without the change:
+
+```bash
+cd api && bun test src/errors.test.ts
+```
+
+Rebuild `@terreno/api` (`bun run compile`) and restart the backend. Check that the old process
+has exited first. In this run, the first restart printed
+`Server start failed: Error: Failed to start server. Is port 4200 in use?` and the old server kept
+answering 500.
+
+### 7. Re-run the symptom
+
+Same request against the restarted backend:
+
+```text
+$ curl -s -i -b cookies.txt -X POST localhost:4200/todos -H 'Content-Type: application/json' --data '{"title": "Buy milk", "completed": fals}'
+HTTP/1.1 400 Bad Request
+X-Powered-By: Express
+X-Request-ID: b81e4036-1243-4b0d-a3b4-9e2ec9807664
+Vary: Origin
+Access-Control-Allow-Credentials: true
+Content-Type: application/json; charset=utf-8
+Content-Length: 143
+Date: Mon, 12 Oct 2026 02:47:11 GMT
+Connection: keep-alive
+Keep-Alive: timeout=5
+
+{"status":400,"title":"Malformed request body","detail":"JSON Parse error: Unexpected identifier \"fals\"","disableExternalErrorTracking":true}
+```
+
+`last_error` has no `since` argument, so it keeps returning the newest error even after a fix. To
+prove nothing new failed, ask `read_logs` for error-level backend entries since the restart:
+
+```json
+{"name":"read_logs","arguments":{"sources":["backend"],"level":"error","since":"2026-10-12T02:47:10.183Z"}}
+```
+
+```json
+{
+  "connection": "CDP: Error: No debuggable Hermes/React Native target with webSocketDebuggerUrl (is the app running?); Metro events: connected ws://localhost:8282/events",
+  "entries": [],
+  "projectRoot": "/workspace/.claude/worktrees/agent-a4ec9221d12c64054"
+}
+```
+
+The request is now logged at `warn` as
+`BadRequestError(400): Malformed request body — JSON Parse error: Unexpected identifier "fals"`,
+followed by the parser's stack. Query with `level: "warn"` to see it.
+
+### 8. Confirm in the running app
+
+`navigate` drives Expo Router through Hermes, so it has no target on web:
+
+```json
+{"name":"navigate","arguments":{"path":"/"}}
+```
+
+```json
+{
+  "error": "Error: No debuggable Hermes/React Native target with webSocketDebuggerUrl (is the app running?)",
+  "status": "CDP: Error: No debuggable Hermes/React Native target with webSocketDebuggerUrl (is the app running?); Metro events: not connected"
+}
+```
+
+On web, use the local `browser` tool instead (it needs `TERRENO_MCP_EVAL=1` for `evaluate`). Open
+the app and log in:
+
+```json
+{"name":"browser","arguments":{"action":"open","url":"http://localhost:8282/login","width":1280,"height":800}}
+{"name":"browser","arguments":{"action":"type","selector":"#login-screen-email-input","text":"test@example.com"}}
+{"name":"browser","arguments":{"action":"type","selector":"#login-screen-password-input","text":"testpassword123"}}
+{"name":"browser","arguments":{"action":"click","selector":"[data-testid=\"login-screen-submit-button\"]"}}
+```
+
+Each step returns the page state, for example the click:
+
+```json
+{
+  "action": "click",
+  "ok": true,
+  "selector": "[data-testid=\"login-screen-submit-button\"]",
+  "title": "",
+  "url": "http://localhost:8282/login"
+}
+```
+
+On a user's first login, the example app shows one-time Terms of Service and Privacy Policy
+consent forms before the Todos screen. The Terms form needs a drawn signature, which `browser`
+cannot draw. For a scripted run, sign in with `POST /api/auth/sign-in/email`, list the forms with
+`GET /consents/pending`, and accept each one with `POST /consents/respond` and the body
+`{"consentFormId": "<id>", "agreed": true, "locale": "en", "signature": "<data URL>"}`. Then
+`reload` the page.
+
+Send the same malformed body from the page, the way a web client would:
+
+```json
+{"name":"browser","arguments":{"action":"evaluate","code":"fetch(\"http://localhost:4200/todos\", {method: \"POST\", credentials: \"include\", headers: {\"Content-Type\": \"application/json\"}, body: \"{\\\"title\\\": \\\"Buy milk\\\", \\\"completed\\\": fals}\"}).then(async (r) => ({status: r.status, body: await r.json()}))"}}
+```
+
+```json
+{
+  "action": "evaluate",
+  "ok": true,
+  "result": {
+    "status": 400,
+    "body": {
+      "status": 400,
+      "title": "Malformed request body",
+      "detail": "JSON Parse error: Unexpected identifier \"fals\"",
+      "disableExternalErrorTracking": true
+    }
+  },
+  "title": "",
+  "url": "http://localhost:8282/"
+}
+```
+
+Then take a screenshot of the todo list:
+
+```json
+{"name":"browser","arguments":{"action":"screenshot","output":".terreno/pipeline/screens/todos-after-fix.png"}}
+```
+
+```json
+{
+  "action": "screenshot",
+  "ok": true,
+  "output": "/workspace/.claude/worktrees/agent-a4ec9221d12c64054/.terreno/pipeline/screens/todos-after-fix.png",
+  "title": "",
+  "url": "http://localhost:8282/"
+}
+```
+
+The screenshot shows My Todos with `3 todos · 3 remaining · 0 completed`: the seeded todos plus the
+single `Buy milk`, with no extra row from the rejected requests. A final `read_logs` for
+backend errors since the restart still returned `"entries": []`. The fix is verified.
+
+## A screen crashes on web
+
+A second run used the same setup on ports 4400 and 8482. A new priority badge on each todo row
+read `data.priority.toUpperCase()`, and todos created before the field existed have no
+`priority`. The Todos screen showed `Something went wrong` with
+`Cannot read properties of undefined (reading 'toUpperCase')`.
+
+```json
+{"name":"last_error","arguments":{"sources":["backend","browser"]}}
+```
+
+```json
+{"level":"error","message":"%o\n\n%s\n\n%s\n TypeError: Cannot read properties of undefined (reading 'toUpperCase') The above error occurred in the <SyncTodoItem> component. React will try to recreate this component tree from scratch using the error boundary you provided, Try.","source":"browser","timestamp":"2026-10-12T03:30:28.321+00:00"}
+```
+
+React caught the error in an error boundary and reported it with `console.error`, so:
+
+- There is no `stack` field. Only uncaught errors carry one.
+- The message starts with React's unformatted `%o` and `%s` placeholders. Read past them.
+- The component is named: `<SyncTodoItem>`. Search the code for it and for the property in the
+  error, here `toUpperCase`.
+
+`database_query` with `{"priority": {"$exists": false}}` on `todos` returned three rows, which
+confirmed that the data, not the server, triggers the crash. `read_logs` with
+`sources: ["backend"]` and `level: "error"` returned no entries. Restoring the guard
+(`data.priority ? <Badge …/> : null`) fixed it. `navigate` returned the same
+`No debuggable Hermes/React Native target` error as in step 8, so the check used `browser`:
+`open`, `scroll` to a todo row, then `screenshot`. The row with a priority showed its badge, and the
+rows without one rendered.
+
+A later `last_error` may return an unrelated older error, because it has no `since`. Use
+`read_logs` with `level: "error"` and `since` set to the time of the fix instead.
+
+## Tool reference
+
+### Read errors and logs
 
 ```json
 {"name":"last_error","arguments":{"sources":["backend","browser","metro","app"]}}
 ```
 
-It returns the newest error-level JSONL/CDP entry. Use `read_logs` when the failure needs surrounding
-events:
+`last_error` returns the newest error-level entry from the selected sources.
 
 ```json
 {
@@ -20,14 +380,15 @@ events:
   "arguments": {
     "entries": 100,
     "level": "error",
+    "since": "2026-10-12T02:45:02.876Z",
     "sources": ["backend", "browser", "metro", "app"]
   }
 }
 ```
 
-`backend` and `browser` read durable JSONL; `metro` and `app` read in-memory rings populated from
-Metro `/events` and CDP. Connection status in the response explains when either live source is
-unavailable.
+`backend` and `browser` read durable JSONL files under `.terreno/logs/`. `metro` and `app` read
+in-memory rings filled from Metro `/events` and Hermes CDP. `connection` explains when a live
+source is unavailable.
 
 CLI equivalents:
 
@@ -36,26 +397,31 @@ terreno logs last-error --sources backend,browser,metro,app
 terreno logs --entries 100 --level error --sources backend,browser,metro,app
 ```
 
-## 2. Inspect client state
+### Inspect client state
 
 Check authentication and non-synced RTK Query cache state:
 
 ```json
-{"name":"get_rtk_state","arguments":{"slice":"rtk","query":"todos"}}
+{"name":"get_client_state","arguments":{"slice":"rtk","query":"todos"}}
 ```
 
 The tool reads `globalThis.__TERRENO_STORE__` registered by the app, using CDP when the MCP process
-cannot access the app heap directly. `slice: "auth"` prefers the Better Auth slice and falls back to
-legacy JWT auth; pass `betterAuth` to request that exact slice. The CLI equivalent is:
+cannot access the app heap directly. It also detects a SyncDB client created with `debug: true`, and
+its `layer` field reports what it found: `rtk`, `syncdb`, `syncdb+rtk` (both payloads returned), or
+`none` (with a setup hint). On web it returns `none`, as shown in step 5. `get_rtk_state` is a
+deprecated alias for one release. `slice: "auth"` prefers the Better Auth slice and falls back to
+legacy JWT auth; pass `betterAuth` to request that exact slice.
 
 Sensitive fields whose names include `password`, `token`, `secret`, `authorization`, or `cookie` are
 returned as `[REDACTED]`; use this summary to inspect cache state, never to retrieve credentials.
 
+The CLI equivalent is:
+
 ```bash
 terreno state --slice rtk --query todos
 ```
 
-## 3. Inspect and change SyncDB state
+### Inspect and change SyncDB state
 
 Create the app client with `debug: true`, then inspect the same state that powers
 the SyncDB debugger:
@@ -85,7 +451,7 @@ use `setLocalEntity` from `syncdb_snapshot` `get`.
 State changes require an explicit local opt-in:
 
 ```bash
-TERRENO_MCP_EVAL=1 bunx terreno-mcp-local
+TERRENO_MCP_EVAL=1 bunx -p @terreno/mcp terreno-mcp-local
 ```
 
 Then use `syncdb_action`. Normal writes should use `mutate`; `flush` drains the
@@ -104,9 +470,9 @@ semantics. `mergeSnapshot` CRDT-merges the captured TinyBase content into the
 live store (later HLCs win) instead of replacing it. Capture a baseline first
 and use these only for fault injection or repair.
 
-## 4. Prove the web fix
+### Drive the web app
 
-Use Bun 1.4's built-in WebView through the local `browser` tool:
+The local `browser` tool uses Bun 1.4's built-in WebView:
 
 ```json
 {"name":"browser","arguments":{"action":"open","url":"http://localhost:8082"}}
@@ -118,8 +484,10 @@ Use Bun 1.4's built-in WebView through the local `browser` tool:
 ```
 
 The session persists between MCP calls. `snapshot` returns visible text and up to 200 interactive
-elements so the agent can choose selectors and verify state without image guessing. `screenshot`
-saves the viewport for the PR or walkthrough.
+elements so the agent can choose selectors and verify state without image guessing. `wait` sleeps
+for `timeout` milliseconds; it does not wait for a selector. `screenshot` saves the viewport, and
+its `output` must be under the project root or `/opt/cursor/artifacts`. `evaluate` requires
+`TERRENO_MCP_EVAL=1`.
 WebView console output is not added to `browser.log`; call `read_logs` alongside this flow when the
 running app posts browser logs to the backend collector. The collector accepts local-loopback
 traffic before login; devices or remote browsers must send the app's normal authentication.
@@ -133,12 +501,12 @@ terreno web http://localhost:8082 \
   --screenshot /opt/cursor/artifacts/save-result.png
 ```
 
-## 5. Verify the native fix in the running app
+### Verify a native fix in the running app
 
 Navigation and arbitrary evaluation are disabled by default. Opt in only for local debugging:
 
 ```bash
-TERRENO_MCP_EVAL=1 bunx terreno-mcp-local
+TERRENO_MCP_EVAL=1 bunx -p @terreno/mcp terreno-mcp-local
 ```
 
 Then call `navigate` with `{"path":"/profile"}` or run:
@@ -147,8 +515,8 @@ Then call `navigate` with `{"path":"/profile"}` or run:
 TERRENO_MCP_EVAL=1 terreno navigate /profile
 ```
 
-Confirm the target screen renders, then call `last_error` again. A successful fix has no new
-error-level entry after the navigation timestamp.
+Confirm the target screen renders, then call `read_logs` with `level: "error"` and `since` set to
+the navigation time. A successful fix returns no entries.
 
 ## Connection problems
 
@@ -158,3 +526,5 @@ error-level entry after the navigation timestamp.
 - Set `TERRENO_METRO_URL` if Metro is not on the frontend script's `--port`.
 - Close React Native DevTools when Hermes reports another debugger connection.
 - Use only `backend,browser` sources when Metro is intentionally stopped.
+- Expect `No debuggable Hermes/React Native target` from `get_client_state`, `navigate`, and
+  `evaluate` on web. Those tools need an iOS or Android build attached to Metro.

package/dist/docs/versioned/next/how-to/enable-mcp-oauth.md

@@ -1,8 +1,8 @@
 # Enable MCP OAuth for a JWT app
 
-Let Claude.ai custom connectors, ChatGPT apps, and other remote MCP clients connect to your app's `POST /mcp` through OAuth 2.1, when your app signs users in with Terreno JWTs. Terreno runs the authorization server; your app hosts one consent screen.
+Let Claude.ai custom connectors, ChatGPT apps, and other remote MCP clients connect to your app's `POST /mcp` through OAuth 2.1. Terreno runs the authorization server; your app hosts one consent screen. A Terreno JWT is the usual way to approve that screen. An app with its own session sets `req.user` first. See [Apps without a Terreno JWT](#apps-without-a-terreno-jwt).
 
-Use [a service token](connect-mcp-service-token.md) instead for clients that take a static Bearer key (Perplexity, Cursor, Claude Code).
+Use [a service token](connect-mcp-service-token.md) when the client can only hold a static Bearer key (Perplexity, Cursor, Claude Code). For a headless client that can perform a token request, use [client credentials](#headless-clients-client-credentials) instead.
 
 ## Prerequisites
 
@@ -46,6 +46,8 @@ Dynamic client registration (`POST /oauth/register`) is a separate opt-in and st
   });
   ```
 
+  A loopback redirect (`localhost`, `127.0.0.1`, or `[::1]`) matches any port. Register one URI, for example `http://127.0.0.1:33418/callback`, and a native client can send `http://127.0.0.1:<ephemeral>/callback` with the same scheme, host, path, and query. The authorization code is sent to the port the client used. `localhost` and `127.0.0.1` do not match each other. Every other redirect URI must match exactly. There is no per-client opt-out. Another process on that host can listen on a different port and receive the code. PKCE `S256` is what stops that process from exchanging it.
+
 - **Registration on.** Turn it on only when clients you cannot pre-register must connect. Set `dynamicClientRegistration: true` and list `allowedRedirectHosts`, which limits where a registered client may send codes. Claude.ai redirects to `claude.ai`, ChatGPT to `chatgpt.com`. Use `*.example.com` for subdomains, and add `localhost` only if you want local clients with loopback `http://` redirects. Keep rate limiting on.
 
   ```typescript
@@ -88,6 +90,29 @@ The client sends the user's browser to `/oauth/authorize`. Terreno checks the cl
 
 The three endpoints are in OpenAPI (`getMcpOAuthRequest`, `approveMcpOAuthRequest`, `denyMcpOAuthRequest`), so `bun run sdk` generates hooks for them. A request expires after 10 minutes (400 `Authorization request expired`), and a decided request cannot be decided again (409). The endpoints refuse `mcp_` and OAuth bearers, so an agent cannot approve itself.
 
+### Apps without a Terreno JWT
+
+`authenticateMiddleware()` calls `next()` when `req.user` is already set, so the consent routes do not require a JWT or a Better Auth session. Set the approving user in `addMiddleware`, which runs before these routes. Limit that to the consent paths. `GET /oauth/authorize` stays the unauthenticated redirect that starts the flow.
+
+The user object needs `_id`. Approve issues the grant to that id and records that user's `tokenEpoch`. `userForThisRequest` must resolve a session the app has already verified, such as a signed session cookie. Do not set `req.user` from an unverified header or query parameter. That user becomes the subject of the grant.
+
+```typescript
+new TerrenoApp({userModel: User, mcpOAuth: {consentUrl, enabled: true, issuer}})
+  .addMiddleware(async (req, _res, next) => {
+    if (!req.path.startsWith("/oauth/authorize/")) {
+      next();
+      return;
+    }
+    const user = await userForThisRequest(req);
+    if (user) {
+      req.user = user;
+    }
+    next();
+  });
+```
+
+Call `GET /oauth/authorize/<request>` and `POST .../approve` or `.../deny` with no `Authorization` header. `mcp_` and `mcpat_` bearers are still rejected on those routes.
+
 ## 3. Connect a client
 
 Give the client the MCP URL, `https://api.example.com/mcp`. It discovers the rest:
@@ -98,6 +123,32 @@ Give the client the MCP URL, `https://api.example.com/mcp`. It discovers the res
 
 For Claude.ai: **Settings → Connectors → Add custom connector**, paste the MCP URL, and connect. For ChatGPT: create a connector with the MCP URL and choose OAuth.
 
+## Headless clients (client credentials)
+
+A sandbox or another server has no browser, so it cannot run the authorization-code flow. Create a confidential client bound to a service-account user. The helper returns the secret once. Store it, then exchange it at `POST /oauth/token`. Dynamic registration stays public-only and still rejects client secrets.
+
+```typescript
+import {McpOAuthClient} from "@terreno/api";
+
+const {client, clientSecret} = await McpOAuthClient.issueConfidential({
+  clientName: "Sandbox agent",
+  tokenEndpointAuthMethod: "client_secret_basic", // or "client_secret_post"
+  userId: serviceAccount._id,
+});
+```
+
+`client_secret_basic` sends `Authorization: Basic` with the form-encoded `client_id:client_secret`. `client_secret_post` sends `client_id` and `client_secret` in the form body. The client must use the method it was created with.
+
+```bash
+# Form-encode the id and secret before base64. A raw colon join breaks when either value contains '%' or ':'.
+AUTH=$(node -e 'const [id, secret] = process.argv.slice(1); process.stdout.write(Buffer.from(`${encodeURIComponent(id)}:${encodeURIComponent(secret)}`).toString("base64"))' "$CLIENT_ID" "$CLIENT_SECRET")
+curl -X POST https://api.example.com/oauth/token \
+  -H "Authorization: Basic $AUTH" \
+  -d grant_type=client_credentials
+```
+
+The response is an `mcpat_…` access token and no refresh token. It acts as `userId`, with `credential: "oauth"`. Disabling that user, or bumping `tokenEpoch`, ends the token the same way it ends an authorization-code token. `McpOAuthClient.revoke(clientId)` ends every token that client holds, and a revoked client cannot start a new authorization or token grant. `deleteOne`, `findOneAndDelete`, and `deleteMany` do the same. `bulkWrite` skips those hooks, so use `revoke` when a bulk write removes clients.
+
 ## 4. Check it
 
 ```bash
@@ -128,7 +179,7 @@ Refresh tokens rotate on every use. If an old refresh token comes back, Terreno
 
 ## Security notes
 
-- Only public clients with PKCE `S256` are supported. `plain` PKCE and client secrets are rejected.
+- Public clients use PKCE `S256` only. `plain` PKCE is rejected. Confidential clients use `client_credentials` with `client_secret_basic` or `client_secret_post`. `private_key_jwt` is not supported. Dynamic registration cannot create a confidential client.
 - Tokens, codes, and refresh tokens are stored as SHA-256 hashes.
 - Registration, authorize, token, and revoke count against the `auth` [rate-limit](rate-limiting.md) bucket. Turn rate limiting on in production, since registration is unauthenticated.
 - If a browser-based client (such as the MCP Inspector) runs discovery from another origin, allow that origin in `corsOrigin`.