@terreno/mcp 57.18.0 → 57.20.0

package/dist/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/dist/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/dist/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/dist/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/dist/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/dist/docs/versioned/next/explanation/loop-engineering.md

@@ -119,6 +119,7 @@ include:
 | --- | --- |
 | Backend/API/data | `terreno-backend-api`, `mongoose-schema-safety`, `backend-test-env`, `generate-sdk`, `terreno-data-fetching` |
 | UI/app | `terreno-ui`, `building-terreno-apps`, `verify-ui-changes` |
+| Testing | `terreno-test-setup`, `terreno-backend-tests`, `terreno-frontend-tests`, `terreno-mobile-tests` |
 | AI/prompts | `ai-prompt-governance` — new features also follow [Develop an AI feature](../how-to/ai-feature-development.md) |
 | Docs/submission | `update-docs`, Brew, `fix-conflicts` |
 | GitHub issues | `create-github-issue`, `work-github-issues`, `implement-ready-for-dev` (Pick plan comment is the Roast contract; unattended Grow may also write an IP) |

package/dist/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/dist/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

package/dist/docs/versioned/next/explanation/responsive-design.md

@@ -0,0 +1,143 @@
+# Responsive design
+
+Terreno apps run on desktop web and native mobile. Responsive behavior follows the workflow, the available viewport, and how important that workflow is on that surface.
+
+The goal is not to make every screen work everywhere. The goal is the best experience on the devices and workflows people actually use. Design specs name the supported breakpoints and the support level for each feature. Implement and test only those behaviors.
+
+Breakpoints are viewport width in points, not a device model and not a physical screen resolution. Browser chrome, a resized window, split screen, and display scaling all change the available width.
+
+## Surfaces
+
+Primary devices define the design target. Support for other devices comes from the breakpoint system.
+
+| Surface | Who it is for | Where it runs | Design target | Role |
+| --- | --- | --- | --- | --- |
+| Desktop web | People doing data-heavy work | Web, validated in Chrome | 13" laptop at `xl` (≥ 1280pt), such as a MacBook Air 13" | Primary experience. Full functionality, including complex review and multi-panel workflows. |
+| Primary mobile | People whose main experience is the phone or tablet | iOS and Android | Large phone / small tablet at native `lg` (600–1023pt), such as a Samsung A11 | Full supported mobile workflows. |
+| Reduced mobile | People who need emergency or lightweight access | iOS and Android | Common phones | A reduced set of workflows. Not a replacement for desktop. |
+
+Other browsers are outside the desktop support contract. Do not create a layout for an individual phone or tablet model.
+
+## Support levels
+
+Every feature names one of these levels at each breakpoint it claims.
+
+| Level | Definition | Example |
+| --- | --- | --- |
+| Fully supported | Designed and tested at this breakpoint. Intended workflows work. | A filter with search, groups, saved filters, and bulk actions on desktop `lg` and `xl`. |
+| Supported with adaptation | Still fully usable. Layout or interaction is simpler so it fits. | The same filter on a tighter width becomes one category at a time, or moves advanced options behind an "Advanced filters" action. |
+| Functionally available | Essential workflows can be finished. Complexity is intentionally omitted. | On reduced mobile, the filter keeps search and one or two high-value filters. |
+| Not supported | Not available, not optimized, or not guaranteed. | The advanced filter below the minimum supported breakpoint. The app may still open. Layout and functionality are not guaranteed. |
+
+### What a feature spec must define
+
+| Item | Required? |
+| --- | --- |
+| Supported surfaces (desktop web, primary mobile, reduced mobile) | Yes |
+| Supported breakpoints (`sm`, `md`, `lg`, `xl`) | Yes |
+| Support level at each of those breakpoints | Yes |
+| Behavior when a breakpoint is not supported | Yes |
+| Layout changes at supported breakpoints | When the layout changes |
+
+## Breakpoints
+
+Tokens are platform-specific. `lg` is not the same width on web and native. The tables and the constants `WEB_BREAKPOINT_MIN_WIDTH` and `NATIVE_BREAKPOINT_MIN_WIDTH` are the same contract. API details: [Media query helpers](../reference/ui.md#media-query-helpers).
+
+### Desktop web
+
+The desktop web app is optimized for desktop. The minimum supported desktop breakpoint is `lg`.
+
+| Category | Token | Viewport | Meaning |
+| --- | --- | --- | --- |
+| Primary desktop | `xl` | ≥ 1280pt | Full desktop layouts, multi-panel workflows, dense data. |
+| Smaller desktop | `lg` | 1024–1279pt | Minimum supported desktop. Collapse secondary content, adjust panels, or simplify controls. Keep core workflows. |
+| Below supported desktop | below `lg` | < 1024pt | Not a supported desktop experience. The app may stay reachable. Layouts are not guaranteed. |
+
+On web, `sm` (320) and `md` (375) still classify widths below 1024 so a layout can stay reachable.
+
+Test `xl` fully, including complex layouts and multi-panel interactions. Test `lg` to confirm critical workflows stay usable when space shrinks. Do not do breakpoint-specific testing below `lg`. Degrade gracefully there when it is cheap.
+
+### Native mobile
+
+| Category | Token | Viewport | Meaning |
+| --- | --- | --- | --- |
+| Extra large | `xl` | ≥ 1024pt | Not a supported mobile layout. Use desktop web where it exists. |
+| Large mobile / tablet | `lg` | 600–1023pt | Primary tablet experience. Optimize supported mobile workflows here. |
+| Standard mobile | `md` | 375–599pt | Common phone. Supported workflows stay usable. |
+| Small mobile | `sm` | 320–374pt | Small phone. Critical workflows stay functional. Extra scrolling or a simpler layout is expected. |
+| Below supported mobile | below `sm` | < 320pt | Not supported. The app may stay reachable. Layouts are not guaranteed. |
+
+Test native `lg`, `md`, and `sm` unless the spec says otherwise. Do not do breakpoint-specific testing below `sm`.
+
+A larger mobile screen does not automatically get the desktop layout. Use a breakpoint only when the layout actually changes.
+
+`isSupportedDesktopWidth({width})` is the desktop floor: web `lg` and native `xl`, both 1024pt. Below that, do not ship a desktop multi-panel layout.
+
+## Adapting a layout
+
+### Desktop
+
+Support a primary laptop display, a resized browser window, split screen, and a smaller window that is still inside `lg` or `xl`. Keep the workflow as width drops inside that range.
+
+When width drops:
+
+- Collapse secondary panels.
+- Allow horizontal scrolling for a dense table.
+- Move secondary actions into an overflow menu.
+- Reduce spacing before removing content.
+
+Do not shrink content until it is unreadable, compress a layout into a strip, or hide a critical workflow with no other way to reach it.
+
+### Native
+
+Mobile layouts favor finishing the task over matching desktop feature parity.
+
+Reduced mobile, when a desktop workflow is too complex:
+
+- Simplify the workflow.
+- Reduce the available actions.
+- Keep the high-value, time-sensitive tasks.
+- Send people to desktop when the workflow needs it.
+
+Do not recreate a desktop layout on mobile, support every desktop workflow, show a dense table or a multi-panel layout, or require a lot of horizontal scrolling.
+
+Primary mobile should stay clear, readable, touch-friendly, and focused on the supported workflows.
+
+## Checklist
+
+Before building a new experience, answer these:
+
+1. Is this desktop-only, mobile-only, or both? Is the workflow required on reduced mobile, or only on primary mobile?
+2. What is the minimum supported width? When space decreases, does content collapse, stack, scroll, or hide?
+3. What is the primary goal, which information is essential, and which actions are secondary?
+4. Does this need a breakpoint, or a mobile variant of a component? Does it match an existing responsive pattern?
+
+## Framework component audit
+
+Audited against this policy. Pixel cutoffs that were not a breakpoint token were moved onto `isSupportedDesktopWidth`.
+
+| Component | Result |
+| --- | --- |
+| `Box` responsive props (`sm` / `md` / `lg` / `xl`) | Compliant. One shared dimension listener. The largest matching token wins. |
+| `DashboardGrid` | Compliant. Column counts follow `sm`, `md`, and `lg` (`xl` uses the `lg` count). |
+| `SplitPage` (web) | Compliant. Side-by-side layout follows `isNarrowViewport()` unless the caller passes `narrowBelowWidth`. |
+| `SplitPage` (native) | Compliant. Stacked list/detail at every native width, including tablet `lg`. Native tablets do not inherit the desktop split. |
+| `Modal` | Compliant. Action sheet on native, centered dialog on web. |
+| `DataTable` | Partial. Web keeps inline filters. Native collapses filters into one sheet. Horizontal scroll stays on for wide tables, including native, which is more scrolling than reduced mobile should require. |
+| `Text` / `Heading` | Compliant. Separate web and native type scales. Type does not shrink again inside `sm`. |
+| `Card` | Fixed. Container and display variants used a 768pt cutoff. They now follow the desktop floor. |
+| `MarkdownEditor` | Fixed. Side-by-side edit/preview used a 768pt cutoff. It now follows the desktop floor. |
+| `AdminShell` | Fixed. The sidebar became a hamburger drawer below 768pt. It now does that below the desktop floor. |
+| `AdminFilterDrawer` | Fixed. The bottom sheet used the same 768pt cutoff. It now follows the desktop floor. `ADMIN_FILTER_MOBILE_BREAKPOINT` is 1024. |
+| `AdminHome` | Fixed. Main and sidebar stay side by side only at or above the desktop floor, and only when the dashboard is not embedded. Below the floor they stack. |
+| Admin SPA shell | Compliant. It wraps `AdminShell`, so it uses the same floor. |
+| Example app screens | Compliant. `maxWidth={800}` is a content measure. Toolbars that sit in a row also wrap. No second pixel cutoff. |
+| Sync debugger | Fixed. The event list and JSON inspector stack below the desktop floor. The screen still uses raw `View` and `Text` on purpose. |
+| Demo headers | Fixed. Back-button visibility and header margin followed `isNarrowViewport()` once at module load. They now follow the desktop floor and update when the window resizes. |
+| Demo stories (Tooltip, Multiselect, Accordion) | Fixed. Width switches followed a one-time `isNarrowViewport()` read. They now follow the desktop floor and update on resize. |
+| Admin action rows | Partial. Some rows (`ConsentHistory`, consent editors) stay in one row without `wrap`. They are not a second breakpoint. |
+| `DateTimeField` | Partial. Inline controls switch to an action sheet when the parent is narrower than 395pt, and also when `isNarrowViewport()` is true. 395pt is the field's own minimum, not a viewport token. |
+| `Image` (`fullWidth`) | Gap. Width is read from `Dimensions` once at module load, so it does not track resize or rotation. |
+| `SideDrawer` | Partial. Width is 40% on web and 95% on native, by platform rather than by breakpoint token. |
+
+Do not add a new raw pixel cutoff. Use `Box` breakpoint props, `useResponsiveBreakpoint`, or `isSupportedDesktopWidth`.

package/dist/docs/versioned/next/explanation/roadmap-process.md

@@ -402,7 +402,7 @@ do not claim completion until done.
 | Workflow | Trigger | Purpose |
 | -------- | ------- | ------- |
 | [`.github/workflows/triage.yml`](https://github.com/TerrenoLabs/terreno/blob/master/.github/workflows/triage.yml) | Issue opened | `status:needs-triage` + `area:*` from package dropdown + `type:*` from Kind when present; `area:*` / `type:*` labels the issue was opened with win, so `roadmap:sync` issues are not asked for an area |
-| [`.github/workflows/roadmap-generate.yml`](https://github.com/TerrenoLabs/terreno/blob/master/.github/workflows/roadmap-generate.yml) | Daily + manual | `roadmap:sync --check` for board drift, then regenerate `ROADMAP.md` from the board and open a pull request when roadmap content changes. A new **Last updated** timestamp alone does not open a pull request |
+| [`.github/workflows/roadmap-generate.yml`](https://github.com/TerrenoLabs/terreno/blob/master/.github/workflows/roadmap-generate.yml) | Daily + manual | `roadmap:sync --check` for board drift, then regenerate `ROADMAP.md` from the board and open a pull request when roadmap content changes; [Bot merge](../how-to/release-automation.md) merges it once CI is green. A new **Last updated** timestamp alone does not open a pull request |
 | [`.github/workflows/roadmap-sync.yml`](https://github.com/TerrenoLabs/terreno/blob/master/.github/workflows/roadmap-sync.yml) | Taxonomy files change on `master` + manual | Apply labels and reconcile the board's fields and items |
 | [`.github/workflows/roadmap-reconcile.yml`](https://github.com/TerrenoLabs/terreno/blob/master/.github/workflows/roadmap-reconcile.yml) | IP or task files change on `master` + manual | Advance status from IP headers, add an entry for every new IP, open its tracking issue, push to the board, regenerate `ROADMAP.md` |
 All three share the `roadmap` concurrency group. They write the same board, and interleaving