@terreno/mcp 57.19.2 → 57.20.0

package/src/docs/versioned/next/explanation/agent-guidelines.md

@@ -0,0 +1,173 @@
+# Agent guidelines
+
+An agent writes Terreno-shaped code only when Terreno's conventions are in its context.
+Those conventions reach it through four channels. Each one has a single source of truth,
+and every other copy is generated from it.
+
+| Channel | Source of truth | How the agent gets it | Status |
+| --- | --- | --- | --- |
+| Hosted MCP docs | `docs/`, `website/versioned_docs/`, `mcp-server/src/docs/resources/` | `terreno_search_docs`, `terreno_get_component_docs`, `terreno://docs/*` resources | Shipped |
+| Per-package guidelines | `<package>/.ai/guidelines/core.md` | Merged into the files `terreno_bootstrap_ai_rules` returns | Shipped |
+| App rule files | The app's `.rulesync/rules/` | Generated per editor by `rulesync generate` | Shipped |
+| Agent skills | `plugins/terreno-planning/skills/`, `plugins/terreno-scan/skills/`, `.rulesync/skills/` | `npx skills add TerrenoLabs/terreno` or a host plugin | Shipped |
+
+The runtime side of the loop, meaning what the agent can see in a running app, is covered
+in [AI development loop](ai-development-loop.md). This page covers only conventions.
+
+## Hosted docs and search
+
+The hosted server (`terreno-mcp`) bundles the docs at build time. `sync-versioned-docs`
+copies `docs/` as the `next` version and each `website/versioned_docs/version-*` tree as a
+released version. `sync-ui-docs` copies the component type data.
+
+`terreno_search_docs` runs BM25 over that corpus and the resource pages. It takes several
+queries in one call, an optional package filter, and an optional lockstep `version`. With a
+version, it answers from the nearest retained snapshot, so an app on an older release gets
+that release's guidance.
+
+Resources are the fixed entry points: `terreno://docs/overview`, `api`, `ui`, `syncdb`,
+`rtk`, `patterns`, plus one page per `@terreno/ui` component. A client can read them
+without a tool call.
+
+Search is pull-based. The agent sees nothing until it asks. That is why the search tool's
+own description tells the agent to call it before guessing at Terreno APIs.
+
+## Per-package `.ai/` guidelines
+
+Each core package keeps a short `.ai/guidelines/core.md` next to its code, so a change to
+the package and a change to its guidance land in the same PR. Two packages also carry skill
+copies under `.ai/skills/`.
+
+| Package | `.ai/` contents | In the npm tarball |
+| --- | --- | --- |
+| `@terreno/api` | `guidelines/core.md`, `skills/mongoose-schema-safety/` | Yes (no `files` field) |
+| `@terreno/ui` | `guidelines/core.md` | Yes (`.ai/**/*` in `files`) |
+| `@terreno/rtk` | `guidelines/core.md` | Yes (`.ai/**/*` in `files`) |
+| `@terreno/syncdb` | `guidelines/core.md`, `skills/debug-syncdb-with-mcp/` | No (`files` is `dist` and `src` only) |
+| `@terreno/admin-backend` | `guidelines/core.md` | Yes (no `files` field) |
+| `@terreno/admin-frontend` | `guidelines/core.md` | Yes (`.ai/**/*` in `files`) |
+
+The path that matters today runs through the MCP server, not `node_modules`.
+`mcp-server/scripts/sync-package-guidelines.ts` copies every `.ai/` tree into
+`mcp-server/src/docs/guidelines/<package>/`. `@terreno/mcp` publishes that directory, and
+`terreno_bootstrap_ai_rules` reads it.
+
+Nothing in Terreno reads `node_modules/@terreno/*/.ai/` in a consumer project yet; the
+tarball copies are available to any tool that looks for vendor guidelines there.
+
+Planned (from the per-package guidelines phase of the MCP parity plan, not built):
+
+- Versioned guidelines (`.ai/guidelines/<major>/core.md`) picked by the app's installed
+  version. Guidelines are a single flat `core.md` per package today.
+- Shipping `@terreno/syncdb`'s `.ai/` in its tarball. Its `files` field leaves it out.
+
+## `terreno_bootstrap_ai_rules`
+
+This hosted tool turns the package guidelines into rule files for one app. It does not
+write files. It returns their contents and instructions, and the agent writes them.
+
+| File | Contents |
+| --- | --- |
+| `.rulesync/rules/00-root.md` | The one root rule, for Cursor, Claude Code, Copilot, and `AGENTS.md`: app description, code style, and the merged `core.md` of `api`, `ui`, `rtk`, `syncdb` |
+| `backend/AGENTS.md`, `backend/CLAUDE.md` | Backend conventions, plus the `admin-backend` guidelines when requested |
+| `frontend/AGENTS.md`, `frontend/CLAUDE.md` | Frontend conventions, the MCP servers to use, plus the `admin-frontend` guidelines when requested |
+| `rulesync.jsonc` | rulesync config: `rules` feature, targets `cursor`, `claudecode`, `copilot`, `agentsmd`, `delete: true` |
+
+`packages` narrows the merge. Pass the app's `@terreno/*` dependencies so a project without
+the admin panel gets no admin guidance. Unknown ids are dropped, and an empty result falls
+back to all six packages.
+
+The root rules go through rulesync. The `backend/` and `frontend/` files do not: they are
+direct output, written as-is.
+
+`bunx create-terreno-app` writes its own `.cursorrules` and `CLAUDE.md`. The
+`terreno_bootstrap` prompt tells the agent to run `create-terreno-app` first and this tool
+second.
+
+The returned instructions run `bunx rulesync@9 generate`, the major this repository pins.
+A test in `mcp-server` runs `rulesync generate` on the returned files. From `00-root.md`,
+rulesync writes `.cursor/rules/00-root.mdc`, `CLAUDE.md`, `.github/copilot-instructions.md`,
+and `AGENTS.md`. Windsurf, Codex, and other agents read
+`AGENTS.md`; rulesync 9 has no `windsurf` target. The generated `CLAUDE.md` replaces the
+one `create-terreno-app` wrote, and `.cursor/rules/00-root.mdc` supersedes its
+`.cursorrules`, so delete that file. The root rule contains everything both files said,
+including the "Adding Features" steps.
+
+Earlier versions of the tool also returned `.rulesync/rules/01-claudecode-root.md`, a
+`localRoot` rule that rulesync 9 rejects without a Claude Code `root` rule. Delete that file
+when you re-bootstrap. The root rule now covers Claude Code.
+
+## The `.rulesync/` pattern
+
+This repository and the apps the tool bootstraps follow the same rule. Agent instructions
+are written once under `.rulesync/`, and every editor-specific file is generated from them.
+
+In this repository:
+
+| Source | Generated targets |
+| --- | --- |
+| `.rulesync/rules/**` | `CLAUDE.md`, `.claude/rules/`, `AGENTS.md`, `.cursor/rules/`, `.github/copilot-instructions.md`, `.github/instructions/`, `.devin/rules/` |
+| `.rulesync/skills/`, `.rulesync/subagents/`, `.rulesync/hooks.json` | Per-host skill, subagent, and hook directories (`.claude/`, `.cursor/`, `.github/`, `.devin/`, `.agents/`) |
+| `plugins/terreno-planning/skills/`, `plugins/terreno-scan/skills/`, plus `.rulesync/skills/` | `skills/` (installable set), `plugins/terreno-claude/` and `plugins/terreno-scan-claude/` (Claude Code plugins) |
+
+`rulesync.jsonc` maps each target to its features. `bun run rules` regenerates the rulesync
+targets. `bun run skills:sync` regenerates `skills/` and the Claude plugin. The
+`rulesync-check` workflow regenerates and fails on any diff, and `bun run skills:check` does
+the same for skills.
+
+The config sets `delete: true`. rulesync removes stale generated files before it writes, so
+a generated file holds only what its source says. A hand edit to a generated file is lost
+on the next run.
+
+## Extending the rules in your app
+
+Regeneration replaces two kinds of file. rulesync replaces every generated editor file. A
+re-run of `terreno_bootstrap_ai_rules` returns fresh copies of everything in its table,
+including `00-root.md`, `rulesync.jsonc`, and the `backend/`/`frontend/` agent files. Anything you add to those files is lost.
+
+`rulesync generate` runs with `delete: true`. It overwrites the root `CLAUDE.md`,
+`AGENTS.md`, and `.github/copilot-instructions.md`. It deletes every file under
+`.claude/rules/`, `.cursor/rules/`, `.github/instructions/`, and `.agents/memories/` that
+it did not generate. Before the first `rulesync generate`, and before every later one,
+move any edits to those root files and any hand-written files in those directories into
+`.rulesync/rules/10-project.md` or another `.rulesync/rules/*.md` source. Otherwise they
+are lost.
+
+Keep your conventions in rulesync sources the tool never emits:
+
+1. Leave `00-root.md` untouched. Treat it as Terreno-owned.
+2. Add one or more files such as `.rulesync/rules/10-project.md`. Use a number above `00`
+   and a name the tool does not use.
+3. Scope with `globs` instead of editing `backend/AGENTS.md` or `frontend/AGENTS.md`. A rule
+   with `globs: ["backend/**"]` applies to backend files in every editor.
+4. Run `bunx rulesync@9 generate` and commit the sources and the output together.
+
+```markdown
+---
+targets: ["*"]
+description: "Acme backend conventions"
+globs: ["backend/**"]
+---
+
+# Acme backend
+
+- Store money as integer cents in fields named `*Cents`.
+- Every tenant-scoped model has an `orgId` index.
+```
+
+From one source, rulesync 9 writes `.cursor/rules/10-project.mdc` (`globs`),
+`.claude/rules/10-project.md` (`paths`), `.github/instructions/10-project.instructions.md`
+(`applyTo`), and `.agents/memories/10-project.md` (linked from `AGENTS.md`). A re-bootstrap
+followed by `rulesync generate` leaves these files in place and
+replaces only the Terreno-owned ones.
+
+If you changed `rulesync.jsonc`, for example to add a target, reapply that change after a
+re-bootstrap. The tool returns the default config.
+
+## Related
+
+- [AI development loop](ai-development-loop.md): what the agent sees at runtime
+- [Set up Terreno MCP](../how-to/set-up-terreno-mcp.md): connect both servers to your editor
+- [MCP server reference](../reference/mcp-server.md#terreno_bootstrap_ai_rules): tool parameters
+- [Install agent skills](../how-to/install-agent-skills.md): the skills channel
+- [Planning plugins](planning-plugins.md): how the lifecycle skills are packaged

package/src/docs/versioned/next/explanation/ai-development-loop.md

@@ -0,0 +1,196 @@
+# AI development loop
+
+A coding agent working on a Terreno app runs the same five-stage loop on every change:
+it asks how something should be done, generates the code, runs the app, observes what the
+app did, and fixes what it finds. Terreno's two MCP servers supply a tool for each stage.
+
+- **`terreno-mcp`** is the hosted server. It holds the docs, the code generators, and the
+  convention validators. It knows Terreno but not your app.
+- **`terreno-mcp-local`** runs in your project over stdio. It reads your app's logs,
+  client state, and database, and drives the running app. It knows your app but not the
+  docs.
+
+```mermaid
+flowchart LR
+  ASK["1. Ask<br/>terreno_search_docs<br/>terreno_get_component_docs<br/>application_info"]
+  GEN["2. Generate<br/>terreno_generate_*<br/>terreno_validate_model_schema"]
+  RUN["3. Run<br/>backend dev server<br/>Metro (Expo)"]
+  OBS["4. Observe<br/>read_logs (backend / browser / metro / app)<br/>last_error<br/>get_client_state"]
+  FIX["5. Fix<br/>edit, then navigate<br/>browser snapshot + screenshot"]
+  ASK --> GEN --> RUN --> OBS --> FIX
+  FIX -->|"iterate"| ASK
+```
+
+This page covers what the agent can see and do at each stage, and where that stops. How
+Terreno's conventions reach the agent in the first place is in
+[Agent guidelines](agent-guidelines.md).
+
+## The five stages
+
+### 1. Ask
+
+The agent looks up the current way to do something before it writes code.
+
+| Tool | Server | Contributes |
+| --- | --- | --- |
+| `application_info` | local | The app's `@terreno/*`, Expo, React Native, and Mongoose versions, so later answers match the installed release |
+| `terreno_search_docs` | hosted | BM25 search over the bundled docs, several queries per call, filtered by package and lockstep `version` |
+| `terreno_get_component_docs` | hosted | The full props table for one `@terreno/ui` component |
+| `terreno_get_upgrade_guide`, `terreno_search_update_notes`, `terreno_get_update_note`, `terreno_ask_update_help` | hosted | Upgrade notes for a version range, and questions against them |
+| `terreno://docs/*` resources | hosted | Fixed entry pages a client can read without a tool call |
+
+Version matters here. An agent that passes the app's version to `terreno_search_docs` gets
+the guidance for the release the app is on, not for the newest one.
+
+### 2. Generate
+
+The agent produces code in Terreno's shape instead of inventing it.
+
+| Tool | Server | Contributes |
+| --- | --- | --- |
+| `terreno_generate_model`, `terreno_generate_route`, `terreno_generate_screen`, `terreno_generate_form_fields` | hosted | A Mongoose model with the standard plugins and types, a `modelRouter` with permissions, an Expo screen, form fields |
+| `terreno_validate_model_schema` | hosted | Checks a schema against the conventions, such as a `description` on every field |
+| `terreno_validate_ui_blocks` | hosted | Checks an agent reply document against the blocks catalog |
+| `terreno_install_admin` | hosted | Admin panel integration snippets |
+| `terreno_bootstrap_ai_rules` | hosted | Rule files for the app's editors |
+
+The generators return file contents and instructions. They do not write files, so the agent
+stays in control of where code lands. A new app is scaffolded by `create-terreno-app`, not by
+an MCP tool.
+
+### 3. Run
+
+The app runs the way a developer runs it: the backend dev server, and Expo's Metro dev
+server for the web, simulator, or device build. There is no special agent runtime. The
+local server attaches to what is already running.
+
+Two pieces of development-only instrumentation make the running app observable:
+
+- The backend's logger writes JSONL to `.terreno/logs/app.log`. By default this is on
+  whenever `NODE_ENV` is not `production`.
+- On web, `installTerrenoDevConsoleLogger` (from `@terreno/syncdb`) forwards `console.error`,
+  `console.warn`, and uncaught errors and rejections to the backend's `POST /__terreno/browser-logs` route, which writes
+  `.terreno/logs/browser.log`. The route exists only in development and is never registered
+  in production. See [Development browser-log ingestion](../reference/api.md#development-browser-log-ingestion).
+
+### 4. Observe
+
+The agent reads what the app did.
+
+| Tool | Contributes |
+| --- | --- |
+| `read_logs` | One merged, time-ordered tail from four sources: `backend` (server JSONL), `browser` (web errors and warnings JSONL), `metro` (bundler events), and `app` (the Hermes console over the Chrome DevTools Protocol). Its `connection` field says which live sources are attached. |
+| `last_error` | The newest error-level entry across the same sources, as the raw line. It includes a stack when the entry carries one. |
+| `get_client_state` | The client data layer in the running app. It reports which `layer` it found (`rtk`, `syncdb`, both, or `none`) and returns the RTK Query cache and auth state, the SyncDB state, or both. `get_rtk_state` is a deprecated alias. |
+| `get_syncdb_state`, `syncdb_snapshot` | SyncDB entities, outbox, conflicts, cursors, and debug events, plus snapshots to compare before and after a change |
+| `database_schema`, `database_query` | The app's MongoDB collections and documents, through a read-only allowlist |
+
+All of these are reads. None of them needs an opt-in.
+
+### 5. Fix
+
+The agent edits code in its own editor, then reproduces the path that failed and checks the
+result.
+
+| Tool | Contributes |
+| --- | --- |
+| `navigate` | Moves a native app to an expo-router path over the same CDP connection the logs use |
+| `browser` | Drives the web app in a headless WebView: open, click, type, scroll, then `snapshot` the rendered page and save a `screenshot` as proof |
+| `evaluate` | Runs a JavaScript expression in the app's Hermes runtime |
+| `syncdb_action` | Changes a live SyncDB client: mutate, flush, resync, resolve conflicts, go offline |
+
+`evaluate`, `navigate`, `syncdb_action`, and the `browser` tool's `evaluate` action run code
+or change state inside the app, so they refuse unless the local server was started with
+`TERRENO_MCP_EVAL=1`. Generated editor configuration never sets it. The other `browser`
+actions do not need it.
+
+After the fix, the loop goes back to Observe. A change is done when the logs and state show
+the new behavior, not when the edit compiles.
+
+## Tool layer versus process layer
+
+The loop is half of how Terreno works with agents. This page covers the tool layer. The
+`/terreno-*` lifecycle skills are the process layer, described in
+[Planning plugins](planning-plugins.md).
+
+| Layer | Answers | Delivered by |
+| --- | --- | --- |
+| **Tool** | What can the agent see and do? | MCP servers: docs search, codegen, merged logs, client state, navigation |
+| **Process** | In what order should the agent work, and who checks it? | `/terreno-*`: question-first planning, TDD, fresh-context independent review, evidence gates, reactive review loop |
+
+The two compose. The lifecycle's build and prove stages use the loop's tools to gather their
+evidence, and the tools are most useful when the lifecycle decides when to call them.
+
+## What makes this different
+
+The agent observes what the app actually did, not a description of it.
+
+Without these tools, an agent learns about a failure from a person's summary, a pasted stack
+trace, or its own guess about what the code should do. With them, it reads the 500 from the
+server log, the uncaught error from the browser console, and the cache entry the screen
+rendered from. It reads them from the same run it just changed.
+
+The rest is table stakes. Docs search, generators, and rule files exist for other frameworks
+too, and Terreno does not claim otherwise.
+
+## What the agent cannot see
+
+The loop ends at the edge of the local development session, and some sources have gaps
+inside it.
+
+- **Production.** The backend log file is off in production by default, the browser-log
+  route is never registered there, and no tool reads a hosted log service. Production errors
+  reach the agent only if a person brings them in.
+- **Native crash reports.** A native crash outside the dev loop, such as an iOS crash report
+  or an Android tombstone, never reaches the JavaScript console, so no log source carries it.
+- **Devices not attached to a dev server.** The `app` source, `navigate`, and `evaluate` reach
+  a runtime only through Metro's inspector. A phone running a release build, or one not
+  connected to Metro, is invisible.
+- **The `app` source on web.** The web build has no Hermes target, so `app` returns nothing
+  there. On web, errors, warnings, and uncaught exceptions arrive through the `browser` source
+  instead; `console.log` and `console.info` reach no source. `app` needs a native
+  development build or Expo Go attached to Metro.
+- **Metro events under Expo CLI.** The `metro` source reads Metro's `/events` socket. In Expo
+  CLI 57 that socket accepts connections but never sends events, so `metro` stays empty even
+  when its status reads connected.
+- **The Hermes debugger connection.** The local server holds one CDP session to the app. On a
+  default `expo start` with current React Native, that session and React Native DevTools
+  coexist. On a target that allows a single debugger, or when Expo runs headless, opening
+  DevTools disconnects the local server. The next call that reads the app reconnects and
+  disconnects DevTools in turn, and console entries logged in between are lost. The
+  `connection` field reports the close reason.
+- **Missing stacks.** `last_error` returns the line as it was logged. If the code logged a
+  message without a stack, there is no stack to return.
+
+## How this composes
+
+Terreno does not build its own simulator or browser automation. It composes with three tools
+that already do it well, and keeps to the part they lack: reading the app's logs, client
+state, and data.
+
+| Tool | Use it for | Lives |
+| --- | --- | --- |
+| `expo-mcp` | Interacting with the iOS simulator or Android emulator: screenshots and taps on the native app | Agent session |
+| Playwright MCP | Interacting with the web app in a full browser while working | Agent session |
+| Maestro | Flows worth keeping, such as login, signup, and creating a todo, committed and run in CI | Repository |
+
+The division of labor:
+
+- **Interaction is the composed servers' job.** `expo-mcp` and Playwright MCP move the app
+  and show what is on screen. Terreno's `browser` tool covers the same ground on web when a
+  lightweight headless session is enough.
+- **Observation is Terreno's job.** After a tap or a click, `read_logs`, `last_error`, and
+  `get_client_state` show what the app did behind the screen.
+- **Durability is Maestro's job.** An agent session ends. A flow that proved a fix and should
+  keep proving it becomes a Maestro flow, so CI repeats the check on every change.
+
+`create-terreno-app` writes `expo` and `playwright` entries next to the two Terreno servers
+in the app's `.cursor/mcp.json` and `.mcp.json`, so a new app starts with all four.
+
+## Related
+
+- [Set up Terreno MCP](../how-to/set-up-terreno-mcp.md): connect the servers to your editor
+- [Debug a Terreno app with MCP](../how-to/debug-with-mcp.md): the loop on a real failure
+- [MCP server reference](../reference/mcp-server.md): every tool, prompt, resource, and variable
+- [Agent guidelines](agent-guidelines.md): how Terreno's conventions reach the agent
+- [Planning plugins](planning-plugins.md): the process layer

package/src/docs/versioned/next/explanation/authentication.md

@@ -37,11 +37,55 @@ Modern session-based authentication with built-in social OAuth support.
 3. Backend redirects to OAuth provider or validates credentials
 4. Better Auth creates session in MongoDB
 5. Frontend receives a session cookie (web, default), a bearer session token (native), or, on web with `webAuth: "bearer"`, a bearer token from the `set-auth-token` header. Bearer on web is the option when the web app and the API are on different sites, where browsers block the third-party session cookie. See [Frontend and API on different sites](../how-to/configure-better-auth.md#frontend-and-api-on-different-sites)
-6. On the first authenticated request or socket handshake, Terreno looks up the app `User` by `betterAuthId` and creates it if missing (`syncBetterAuthUser`). An email alone does not prove someone owns an existing account, so an existing app `User` with the same email is linked only after Better Auth verifies that email, and never when the row already belongs to another Better Auth account. Linking removes a legacy password the row never proved with a verified email. `RealtimeApp` uses the registered `BetterAuthApp` instance for socket sessions without extra wiring
+6. As the session is created, Terreno looks up the app `User` by `betterAuthId` and creates it if missing (`syncBetterAuthUser`), recording the OAuth provider in `oauthProvider`. An email alone does not prove someone owns an existing account, so a Better Auth user claims an existing `User` with the same email only when Better Auth verified that email or its sign-up password matches that `User`'s passport hash; otherwise the sign-up answers 409 "Verify your email to use this account" before any Better Auth user is created. A `User` that already belongs to another Better Auth account is never relinked (409 `ACCOUNT_ALREADY_EXISTS`). Linking through a verified email removes a legacy password the row never proved with a verified email, and bumps `tokenEpoch`. See [Account linking](account-linking.md). The first authenticated request or socket handshake retries the sync if it did not run. `RealtimeApp` uses the registered `BetterAuthApp` instance for socket sessions without extra wiring
 7. `req.user` is that app document for subsequent `modelRouter` permissions. A session whose app `User` has `disabled: true` no longer authenticates: `req.user` stays unset, so protected routes answer 401 and disabling an account ends its live sessions. Better Auth's own routes, such as sign-out, still work
 
 Email/password create omits `oauthProvider`. Apps that never use social login can keep `strict: "throw"` without declaring that field. OAuth create sets `oauthProvider` and the User schema must declare it.
 
+#### Challenges without cookies
+
+Bearer mode sends no cookies, but Better Auth keeps three short-lived values in signed cookies:
+the two-factor challenge set when a sign-in needs a second factor, the trust-device token set
+when the user ticks "trust this device", and the passkey challenge set by the WebAuthn options
+endpoints. A cross-site bearer client never sends them back, so without help it could not finish
+a 2FA or passkey sign-in.
+
+When `twoFactor` or `passkey` is configured, Terreno adds a plugin that carries those cookies in
+the `X-Terreno-Auth-Challenge` header instead:
+
+1. A bearer client sends the header on every `{basePath}/two-factor/*`, `/passkey/*`, and
+   `/sign-in/*` call. It sends `-` when it holds nothing, which opts it in.
+2. For a request that sent the header, the response copies each challenge cookie it sets into
+   the header as `name=value` pairs (URL search params), still signed with the auth secret. Only
+   values that response sets are copied, never cookies the request already had. An expired
+   cookie comes back with an empty value. A `rememberMe: false` sign-in's `dont_remember` cookie
+   rides along with the two-factor challenge, so the verified session stays short. The header is
+   added to `Access-Control-Expose-Headers`, the same way `bearer()` exposes `set-auth-token`.
+   A sign-in answered with a two-factor challenge loses its `set-auth-token`, which named the
+   session two-factor had just deleted.
+3. On those paths the server turns the header back into cookies before Better Auth reads them.
+   A real cookie always wins, and only the challenge cookies (plus `dont_remember`) are accepted. The header can
+   never set a session cookie, and a tampered value fails Better Auth's signature check (the 2FA
+   verify answers 401, a passkey verify 400 `CHALLENGE_NOT_FOUND`, and a tampered trust value
+   just asks for the second factor).
+4. rtk's bearer mode stores the header under `${storagePrefix}_auth_challenge` in the same
+   `bearerStorage` as the bearer token. It never stores a token from a response that asks for a
+   second factor. It drops the 2FA challenge and `dont_remember` after a successful verify, and
+   everything but the trust-device value on sign-out. The trust-device value stays until the server
+   expires it or `trustDeviceDays` runs out, so the device stays trusted across sign-outs.
+
+Clients that do not send the header (cookie mode, native) never receive it, so their challenge
+cookies stay httpOnly. That holds only for requests the page's own code does not send with the
+header: a script on the page that adds it to a sign-in or verify call can read the challenge
+values that call's response sets.
+
+Exposure: in bearer mode the trust-device token lives in web storage beside the bearer token.
+Any XSS on the frontend's origin can read both, and a stolen trust value skips the second factor
+for that account until it expires (it is still useless without the password). Apps that handle
+PHI should pass `bearerStorage: window.sessionStorage`, which ends trust with the tab, and serve
+a strict Content-Security-Policy. See
+[Frontend and API on different sites](../how-to/configure-better-auth.md#frontend-and-api-on-different-sites).
+
 **Key properties:**
 - Session-based (cookies / bearer session) vs. stateless JWT
 - A session cookie is sent with requests other sites start, so a cookie-authenticated write counts only when it comes from a trusted origin. Bearer tokens are never sent automatically, so they need no such check

package/src/docs/versioned/next/explanation/consent-forms.md

@@ -0,0 +1,105 @@
+# Consent forms
+
+`ConsentApp` gives an app versioned consent forms (terms, privacy, HIPAA, research, and
+custom agreements), a record of every response, and a gate that keeps a user out of the app
+until they have answered every form that applies to them.
+
+## Forms and versions
+
+A `ConsentForm` has a `slug`, a `version`, localized markdown `content`, and options such as
+required checkboxes, a drawn signature, and whether the user may decline. Publishing
+(`POST /consent-forms/:id/publish`) copies the form to `version + 1`, activates the copy, and
+deactivates every other version of the same slug. Only active forms are shown to users. Publish a new version rather than editing
+a form users have already answered, so each response still points at the text the user saw.
+
+An app can narrow which active forms apply to a user with `resolveConsentForms(user, forms)`,
+for example to show a research consent only to enrolled members. Every consent endpoint that
+asks "which forms apply to this user" runs the same resolver.
+
+## Responses
+
+A `ConsentResponse` records one answer to one form version: `agreed`, `agreedAt`, the locale
+shown, checkbox values, an optional signature, and `formVersionSnapshot`. With
+`auditTrail: true`, it also keeps the user's IP address and user agent and a snapshot of the
+exact content they saw. Responses are append-only. A user who answers again gets a new
+record, so the history of what they agreed to, and when, is never rewritten.
+
+## The gate
+
+`GET /consents/pending` returns the forms that apply to the user and that the user has not
+answered at the form's current version. The client (`ConsentNavigator` in `@terreno/ui`)
+shows them one at a time until the list is empty. A decline also clears the form from the
+list: the user has answered it.
+
+When a form is republished, every user's earlier answer is for an older version, so the new
+version reappears in their gate.
+
+## Provisional signatures
+
+Some consent is given before the user ever opens the app. A guardian may agree on the phone
+at intake, or staff may record verbal consent during a visit. For compliance the form must
+count as signed from that moment, but the user should still read the form and sign it
+themselves.
+
+A provisional signature is a `ConsentResponse` with `provisional: true`. Staff create it with
+`POST /consent-responses/provisional`, naming the target user, the form, and a required note
+that explains how consent was obtained. The response records:
+
+- `agreed: true` and `agreedAt` (server time)
+- `provisionalSignedBy`: the staff member who recorded it
+- `provisionalNote`: the note (trimmed, at most 2000 characters)
+- `formVersionSnapshot`, plus `contentSnapshot`, `provisionalSignerIp`, and
+  `provisionalSignerUserAgent` when `auditTrail` is on
+
+`ipAddress`, `userAgent`, `signature`, and `signedAt` stay empty. Those fields describe the
+user's own device and signature, and the user did not sign.
+
+### Why a provisional signature does not clear the gate
+
+Only the user's own responses remove a form from `/consents/pending`. A provisional signature
+is a record that someone else vouched for the user's consent. It is not the user's consent in
+their own words. Keeping the form in the gate means the user still meets it, reads it, and
+agrees or declines. The gate tells them who signed on their behalf and when, but not the
+signer's note: that stays in the admin audit history. The user's own answer is stored as a separate response, so both records
+stay for audit.
+
+A separate `ProvisionalConsent` model was rejected. A field on `ConsentResponse` keeps one
+audit trail per user and reuses the existing admin screens, populate paths, and PDF code.
+
+### Voiding a provisional signature
+
+A provisional signature recorded in error (the wrong member, the wrong form) is voided with
+`POST /consent-responses/:id/void` and a required reason. Voiding sets `voidedAt`,
+`voidedBy`, and `voidReason`; it never deletes the record, so the audit history shows both
+the signature and its void. A voided signature no longer counts as consent, and the user's
+gate no longer mentions it. Only provisional signatures can be voided: the user's own
+answers are theirs to change by answering again.
+
+### What counts as signed
+
+`getConsentStatuses` (and `GET /consent-responses/status`) is the "considered signed"
+contract. For each form that applies to the user, only non-voided responses to the current
+version count. The user's own latest answer always wins: agreeing makes the form `signed`, declining
+makes it `declined`. Without one, a provisional signature makes it `provisional`, which
+counts as consented. Otherwise it is `pending`. App code that needs to know whether a user
+may proceed (for example before scheduling a visit) checks `isConsented` on these rows
+instead of reading responses directly.
+
+### Who may sign for another user
+
+Pass `accessControl` to `ConsentApp` to use RBAC. Any authenticated user whose roles grant
+`consentResponse:signOnBehalf` may then sign for others. The built-in `admin` role includes
+that action, and existing unsealed admin roles gain it the next time roles are seeded. The
+merge runs on every seed, so removing `signOnBehalf` from the `admin` role does not stick.
+To keep admins from signing, give them a custom role instead of `admin`.
+Without `accessControl`, only users with `admin: true` may sign, and `ConsentApp` logs a
+warning at register.
+
+There is no relationship check: a permitted signer may sign for any user. A signer cannot
+sign for themselves, and the form must be active and must apply to the target user under
+`resolveConsentForms`. The same permission covers reading another user's consent statuses.
+When `AuditApp` is registered, every provisional signature, void, and status read writes an
+`AuditEvent` naming the actor and the target user. Audit events gain a `read` operation and
+a `viewed` verb for these reads.
+
+Reference: [ConsentApp](../reference/api.md#consent-forms-consentapp).

package/src/docs/versioned/next/explanation/example-coverage.md

@@ -27,6 +27,7 @@ that file (and its imports) to a working example. Gaps stay explicit.
 | File upload / GCS | yes — `example-backend/src/api/settings.ts`, AI file routes in `example-backend/src/api/ai.ts`, `file-uploads` flag in `example-backend/src/api/fileUploads.ts` | yes — `example-frontend/app/(tabs)/documents.tsx` (Files section, every signed-in user, 1 upload / IP / min), `example-frontend/app/(tabs)/ai.tsx`, `example-frontend/app/gcs-settings.tsx` | The `file-uploads` feature flag hides upload controls and rejects uploads when off. A missing flag leaves uploads enabled. Deployed bucket is terraform-managed (`google_storage_bucket.example_documents`). |
 | Better Auth | yes — `example-backend/src/utils/betterAuthConfig.ts`, `BetterAuthApp` in `example-backend/src/server.ts` | yes — `example-frontend/app/login.tsx`, `example-frontend/lib/betterAuth.ts` | Default `AUTH_PROVIDER` is `better-auth`. |
 | syncdb local-first | yes — `SyncApp` in `example-backend/src/server.ts` | yes — `example-frontend/store/syncdb.ts`, `example-frontend/app/(tabs)/index.tsx` | PR #869 closed without merge; `@terreno/syncdb` shipped on the launch line and is the example todos path. |
+| List/detail layout | n/a — reuses the synced todos | yes — `example-frontend/app/todo-browser/` (`ListDetailLayout` group, opened from the todos screen's Browse button), list in `example-frontend/components/TodoBrowserList.tsx` | Phones push each todo; at 768px and wider the list stays on the left. e2e: `example-frontend/e2e/todo-browser.spec.ts` (phone, tablet, deep link, resize, keyboard). The demo inbox at `demo/app/demo/list-detail/` shows the same layout with static data. Steps: [build-list-detail-screens.md](../how-to/build-list-detail-screens.md). |
 | SyncDB diagnostics | n/a | yes — `debug` registration in `example-frontend/store/syncdb.ts`, debugger UI at `example-frontend/app/syncdb-debug.tsx` | `terreno-mcp-local` can inspect, snapshot/compare/merge, mutate, flush, reconcile/resync, and exercise offline/conflict paths against the running development client. |
 | RBAC | yes — `example-backend/src/rbacRoles.ts` (including optional `aiObservabilityViewer` / `aiObservabilityOperator` roles), `access.ts`, `accessControl: access` on `ObservabilityApp` / `AdminApp`, `access: {resource: "todo"}` on the todo router | yes — `example-frontend/app/admin/roles.tsx` | Shipped. Plan: [rbac-permissions.md](../implementationPlans/rbac-permissions.md). |
 | Organizations | yes — `createAccess({organizations: true})`, `organizationSettingsSchema`, `orgScopedPlugin` on projects | yes — admin org directory/settings at `example-frontend/app/admin/orgs/` | Settings live on `Organization.settings`; example registers a nested timezone schema. |

package/src/docs/versioned/next/explanation/local-first-data.md

@@ -35,7 +35,7 @@ Terreno 57.
 ## What you start doing
 
 1. **Conflict resolution UI** — When the server rejects a mutation (409 / `sync:nack`), the user must choose a strategy (`useServer` or `keepMine`). Use `ConflictSheet` from `@terreno/ui` or build your own with `useConflicts`.
-2. **Sync-status UX** — Surface offline state, queued mutations, and drain progress with `useSyncStatus` (and optionally `SyncStatusBanner`).
+2. **Sync-status UX** — Surface offline state, queued mutations, and drain progress with `useSyncStatus` (and optionally `SyncStatusBanner`, which waits `offlineGraceMs` — 3s by default — before showing "Offline" so startup and brief socket drops do not flash it).
 3. **Encryption at rest (web)** — Web persistence uses AES-GCM via the default `createServerKeyProvider`; understand key fetch and `onDecryptFailure` for support flows.
 4. **Key lifecycle on logout** — Call `syncDb.stop()` and consider `wipeLocalData` when the authenticated user changes so one account does not read another's local store.
 5. **Backend sync registration** — Every synced collection needs `syncPlugin`, `isDeletedPlugin`, and a `sync` block on `modelRouter`, plus `SyncApp` and `RealtimeApp` on the server. Optional `sync.adminBroadcast: true` also emits `sync:delta` to `{collection}|admin`. Admin clients subscribe with `mode: "window"` (`createSyncDb({windowCollections})`) so they do not snapshot or reconcile that collection; they call `hydrateWindow` (REST membership ids + `GET /sync/entities`). Pass the same `accessControl` into `SyncApp` that `AdminApp` uses so `{collection}|admin` requires `admin:access`. `AdminApp.register` also installs that model's admin list/read/`queryFilter` on the admin window so hydrate and live `|admin` deltas match `/admin` REST. Without RBAC, `user.admin` is enough for the shell gate. Live deltas on that stream apply only to ids already in the window; Refresh is a REST re-query plus `hydrateWindow`.

package/src/docs/versioned/next/explanation/organizations.md

@@ -47,6 +47,13 @@ Tenant isolation uses multiple checks rather than one convention:
 admin models whose schema contains `organizationId`. Models without that path
 remain platform-scoped.
 
+Adding, changing, or removing a membership through `POST` / `PATCH` / `DELETE
+/orgs/:id/members` clears that user's cached permissions, so a new org-admin can open the
+admin page (and a demoted or removed one loses it) on their next request instead of after
+the permission cache's 30-second TTL. Disabling (`PATCH /orgs/:id` with `disabled: true`) or
+deleting (`DELETE /orgs/:id`) an organization suspends all of its memberships and clears the
+cached permissions of every member the same way.
+
 ## Disabled organizations
 
 When `Organization.disabled` is `true`, tenant context and membership mutations
@@ -64,6 +71,35 @@ stop, but operators can still manage the organization record itself:
 Disabling or deleting an organization suspends its memberships. Re-enabling does
 not automatically reactivate them.
 
+## Member recovery
+
+When the app registers `AccountSecurityApp`, an org-admin can help a locked-out member without
+platform staff. `OrgsApp` mounts the same recovery handlers the platform uses at
+`/orgs/:orgId/members/:userId/security/*`, behind an org authorizer.
+
+- **Reach.** An org-admin may act on any active member of their org, even one who also belongs
+  to other orgs (D2). A suspended member, or a user outside the org, answers `404`, so the routes
+  do not reveal who exists elsewhere.
+- **Guards.** Platform staff (`superadmin`, `operator`) and `admin: true` users are never reachable
+  through an org (D3). Neither is anyone who holds a permission the org-admin lacks, nor the
+  org-admin themselves (D9). Disabled orgs answer `403`.
+- **Disable means suspend.** One org must not lock a user out of every other org, so the org
+  path has no account disable. It offers `suspend-membership` instead, which suspends the
+  membership in that org only (Q8). The user still signs in and keeps their other orgs.
+  `User.disabled` and `issue-sign-in-link` stay platform-only.
+- **Attach-then-act.** An org-admin can attach any existing user by email
+  (`POST /orgs/:id/members`). Every org-admin action is audited with the org's id and emails the
+  user, so they learn about it ([notifications](../reference/account-security.md#notifications);
+  the org is named only with `notifications.includeOrgName`). Apps that want more can set
+  `orgRecovery.minMembershipDays` to refuse members who joined too recently.
+- **Platform staff** holding `user:manageSecurity` pass the org checks. The target must still be
+  an active member of the org in the path. Their reach check is the platform one: both sides are
+  resolved outside the organization, so an org-only grant does not put the member out of reach.
+
+See [Recover a locked-out user](../how-to/recover-locked-out-user.md) for who can do what, and
+the [account security reference](../reference/account-security.md#org-admin-routes) for every
+response.
+
 ## Why organizations are optional
 
 Automatically registering routes, roles, or Mongoose models would change
@@ -83,6 +119,7 @@ multi-tenant-ready apps.
 ## Related
 
 - [Add organizations](../how-to/add-organizations.md)
+- [Recover a locked-out user](../how-to/recover-locked-out-user.md)
 - [API reference](../reference/api.md#organizations)
 - [Admin backend reference](../reference/admin-backend.md#organization-scoping)
 - [Admin frontend reference](../reference/admin-frontend.md#orgdirectoryscreen)

package/src/docs/versioned/next/explanation/planning-plugins.md

@@ -112,3 +112,7 @@ Install both from the marketplaces described in
 [install agent skills](../how-to/install-agent-skills.md). Claude Code resolves a plugin
 skill's command from its frontmatter `name`, which is why the two `*-claude/` trees are
 generated with shortened names by `bun run skills:sync`.
+
+## Related
+
+- [AI development loop](ai-development-loop.md): the tool layer these stages use to see the running app