@terreno/mcp 57.3.0 → 57.6.0

package/dist/docs/versioned/next/reference/mcp-server.md

@@ -3,9 +3,12 @@
 Published npm package for the Terreno Model Context Protocol (MCP) server. The monorepo directory is still `mcp-server/`. The package exposes:
 
 - **`terreno-mcp`** — HTTP server used in Cloud Run and local debugging (`src/index.ts`)
-- **`terreno-mcp-local`** — stdio server for project runtime tools (`src/local/index.ts`): `application_info`, `database_schema`, `database_query`, `read_logs`, `last_error`, `get_rtk_state`, `evaluate` (gated by `TERRENO_MCP_EVAL`), `navigate` (CDP wiring planned). `application_info` reads bootstrap `backend/` + `frontend/`, or this monorepo's `example-backend/` + `example-frontend/` (bootstrap names win when both exist).
+- **`terreno-mcp-local`** — stdio server for project runtime tools (`src/local/index.ts`): app/database/log/browser diagnostics, Redux/RTK inspection, and SyncDB state/action/snapshot tools. `evaluate`, `navigate`, and SyncDB state changes are gated by `TERRENO_MCP_EVAL`. Metro URL defaults from `frontend/package.json` `--port` or `TERRENO_METRO_URL`. `application_info` reads bootstrap `backend/` + `frontend/`, or this monorepo's `example-backend/` + `example-frontend/` (bootstrap names win when both exist).
 
 It provides AI coding assistants with documentation access, code generation tools, and workflow prompts.
+For editor configuration and runtime prerequisites, see
+[Set up Terreno MCP](../how-to/set-up-terreno-mcp.md). For the end-to-end diagnostic workflow, see
+[Debug a Terreno app with MCP](../how-to/debug-with-mcp.md).
 
 Both HTTP MCP surfaces (`@terreno/mcp` and the `modelRouter` endpoint in
 `@terreno/api`) use the MCP TypeScript SDK v2 and speak the stateless
@@ -107,7 +110,54 @@ Set `TERRENO_MCP_DOCS_DIR` environment variable to override default path.
 
 ## Tools
 
-Code generation tools that return TypeScript/JavaScript code as text. **Tools do not write files** — the AI assistant receives the code and writes it to appropriate locations.
+Code generation tools return TypeScript/JavaScript code as text. **Code generation tools do not
+write files** — the AI assistant receives the code and writes it to appropriate locations. Scaffold
+a new app with [`create-terreno-app`](create-terreno-app.md) (`bunx create-terreno-app`), not an MCP
+tool.
+
+The local `browser` tool is different: its `screenshot` action writes the requested image path so an
+agent can attach the rendered result as verification evidence. It keeps one headless session alive
+for the MCP connection. Call `open` first, perform interactions, call `snapshot` and `screenshot` to
+prove the final state, then call `close`.
+
+`open` accepts only `http:` and `https:` URLs. Snapshots redact password input values; use them for
+page structure and visible state, not credential inspection.
+
+``````json
+{"name":"browser","arguments":{"action":"open","url":"http://localhost:8082","width":1280,"height":720}}
+{"name":"browser","arguments":{"action":"wait","timeout":1000}}
+{"name":"browser","arguments":{"action":"click","selector":"button[type=submit]"}}
+{"name":"browser","arguments":{"action":"snapshot"}}
+{"name":"browser","arguments":{"action":"screenshot","output":"/opt/cursor/artifacts/app.png"}}
+{"name":"browser","arguments":{"action":"close"}}
+``````
+
+`browser` requires Bun 1.4 or newer. macOS uses system WebKit; Linux and Windows use an installed
+Chrome, Chromium, or Edge through the Chrome DevTools Protocol. Browser storage is ephemeral unless
+`open` receives `dataDir`. Set `TERRENO_MCP_EVAL=1` to enable its arbitrary-JavaScript `evaluate`
+action. Screenshot paths must stay under the project root or `/opt/cursor/artifacts`; persistent
+browser data must stay under the project root. Calls are serialized around the one session owned by
+the local MCP process.
+
+### SyncDB runtime tools
+
+Create the app client with `debug: true` so it registers by its configured
+`name`. The local MCP uses the in-process registry when available and Hermes CDP
+for a separately running app.
+
+| Tool | Purpose |
+| --- | --- |
+| `get_syncdb_state` | Read status, entities/tombstones, outbox, conflicts, cursors, streams, repair markers, values, and debugger events |
+| `syncdb_snapshot` | Capture, list, get, compare, or delete snapshots held by this MCP process |
+| `syncdb_action` | Mutate or directly edit local state, flush, reconcile/resync, resolve/retry, toggle offline, clear debug events, or merge a snapshot |
+
+State and snapshot responses redact fields containing `password`, `token`,
+`secret`, `authorization`, or `cookie`. Snapshot merge payloads are retained
+privately and are not returned. Start the local MCP with
+`TERRENO_MCP_EVAL=1` before calling `syncdb_action`.
+
+See [Debug a Terreno app with MCP](../how-to/debug-with-mcp.md) for examples and
+safety guidance.
 
 ### terreno_search_docs
 
@@ -341,47 +391,6 @@ Validate a Mongoose schema against Terreno conventions.
 - Recommendations for fixes
 - Severity levels (error, warning, info)
 
-### terreno_bootstrap_app
-
-Scaffold a new full-stack Terreno application (Expo frontend, Express/Mongoose backend, Cursor rules, MCP settings).
-
-**Parameters:**
-
-``````typescript
-{
-  appName: string;           // kebab-case (e.g., "my-app")
-  appDisplayName: string;    // Human-readable name
-  description?: string;
-  mcpServerUrl?: string;     // Default: https://mcp.terreno.app
-}
-``````
-
-**Returns:** File list, setup instructions, and full file contents for backend, frontend, CI workflows, and MCP configuration.
-
-The generated Profile tab (`frontend/app/(tabs)/profile.tsx`) uses `@terreno/ui` `TapToEdit` for name, email, and password. Each field saves independently with `PATCH /auth/me` (`usePatchMeMutation`). Name and email each have their own `useEffect`, so saving one field does not wipe an in-progress edit on the other.
-
-The generated app is expected to install and boot with no manual follow-up, so the
-scaffold deliberately ships no binary assets and no references to files it does not
-create:
-
-- **Fonts** come from `@terreno/ui`. `TerrenoProvider` wraps children in
-  `TerrenoFontProvider`, which loads Nunito and Titillium Web from
-  `@expo-google-fonts/*`. The generated `app/_layout.tsx` calls no `useFonts` of its own.
-- **Icon, splash, and favicon** are left unset in `app.json` so Expo uses its built-in
-  defaults. Point them at real files once the app has branding.
-- **`metro.config.js`** pins every `jspdf` request to `jspdf/dist/jspdf.es.min.js` on web
-  and drops it on native. `@terreno/admin-frontend` pulls jspdf in for consent-PDF export,
-  and jspdf's CommonJS and Node builds contain an AMD-style `require(["html2canvas"], cb)`
-  call that Metro's static transform cannot parse — without the override it fails the whole
-  bundle, including Expo Router's static web render.
-- **Auth-gated routes** use `<Stack.Protected guard={...}>`. Wrapping `Stack.Screen`
-  children in a conditional or fragment instead crashes the navigator.
-- **`tsconfig.json`** sets no `baseUrl`; it is deprecated in TypeScript 6 and makes `tsc`
-  abort with TS5101 before checking a single file. `paths` resolve relative to the tsconfig.
-- **Declared dependencies** include every package generated frontend source imports
-  (`react-native-reanimated`, `redux-persist`, `@reduxjs/toolkit`, `@expo/vector-icons`,
-  `lodash`, `luxon`, and the rest). Do not rely on transitive installs for those.
-
 ### terreno_bootstrap_ai_rules
 
 Scaffold AI coding assistant rules (AGENTS.md, Cursor/Windsurf rules, Copilot instructions, rulesync config).
@@ -416,7 +425,7 @@ Multi-step workflow prompts that guide AI assistants through complex tasks.
 
 ### terreno_bootstrap
 
-Workflow prompt for scaffolding a new Terreno app. Delegates to `terreno_bootstrap_app` and `terreno_bootstrap_ai_rules` tools.
+Workflow prompt for scaffolding a new Terreno app. Instructs the assistant to run `bunx create-terreno-app`, then `terreno_bootstrap_ai_rules`.
 
 **Arguments:**
 
@@ -556,6 +565,10 @@ Returns comprehensive code style guide from project documentation.
 | `PORT` | `8080` | HTTP server port |
 | `MCP_HOST` or `HOST` | `0.0.0.0` | Server host address |
 | `TERRENO_MCP_DOCS_DIR` | `../docs` | Path to documentation directory (relative to dist/) |
+| `TERRENO_PROJECT_ROOT` | nearest Terreno project root | Override local package, database, and log discovery |
+| `TERRENO_METRO_URL` | Frontend script port or `http://localhost:8082` | Metro origin used for `/events` and CDP discovery |
+| `TERRENO_MCP_EVAL` | Disabled | Set to `1` to enable local MCP `evaluate`, `navigate`, and SyncDB state-changing actions |
+| `TERRENO_BROWSER_LOGS` | Enabled only when `NODE_ENV=development` | Set to `true` to opt in in another non-production environment or `false` to disable; production rejects the route, and non-loopback clients must authenticate |
 
 **Example:**
 

package/dist/docs/versioned/next/reference/scan-plugin.md

@@ -0,0 +1,169 @@
+# Scan plugin reference
+
+Plugin: `terreno-scan` (`2.11.0`). Requires the lifecycle plugin
+([lifecycle plugin reference](lifecycle-plugin.md)).
+
+A scan turns a long-term outcome — "cold builds under 30s", "no unbounded reads", "WCAG
+AA on every screen" — into a measured campaign: charter the goal, map-reduce the
+repository into verified findings, slice those findings into IPs and tasks, run each
+slice through Grow/Pick/Roast/Brew/Taste, then re-measure and repeat.
+
+Scan stages never edit product code. The lifecycle does.
+
+| Skill | Preconditions | Primary output | PASS next |
+| --- | --- | --- | --- |
+| `terreno-scan-1-aim` | goal/outcome + repository | approved charter: metric, measured baseline, dry-run rules, exclusions, validity rule, severity rubric, slice policy, budget | Sweep |
+| `terreno-scan-2-sweep` | approved charter | per-rule hits, deterministic shard manifest, schema-valid candidate findings from parallel workers | Sift |
+| `terreno-scan-3-sift` | candidates for the round | deduped, adversarially verified, ranked findings report plus dropped-candidate summary | Plot, or Track when dry |
+| `terreno-scan-4-plot` | findings report + slice policy | ordered PR-sized slices, one standalone Grow brief each, findings marked `planned` | Track, with `handoff: grow` |
+| `terreno-scan-5-track` | landed slice or dry round | re-measured metric with command output, findings closed/reopened with evidence, round record, next move | Plot, Sweep, or `null` |
+
+Outer loops (not stages):
+
+| Skill | What it walks | Default |
+| --- | --- | --- |
+| `terreno-scan-campaign` | One goal, round after round | Aim once, then Sweep → Sift → Plot → lifecycle → Track until the metric hits target, the budget is spent, or a genuine human gate is reached. Stops at each gate. |
+| `terreno-scan-loop` | The same, but resident | Keeps the campaign moving **and** heartbeats over every open campaign PR — routing it to a reviewer, answering review comments through Taste, fixing red CI, tracking merges — refilling work as PRs land. Runs until the goal is met, a stop argument fires, or a human decision is required. |
+
+## Resident loop
+
+`terreno-scan-loop` is the "leave it running" entry point. One session holds the goal,
+the state, and the schedule; every unit of work happens in a fresh subagent.
+
+Arguments: `goal=<slug>`, `reviewer=<handle[,handle]>`, `assignee=<handle>`, `wip=<n>`,
+`rounds=<n>`, `until=<ISO timestamp>`, `tick=<seconds>`. Overrides apply to the run only
+and are recorded in state as overrides — they never rewrite the charter.
+
+Each tick snapshots the campaign's PRs and sorts each into one bucket, then acts in
+priority order:
+
+| Bucket | Action |
+| --- | --- |
+| `unrouted` | Apply the charter's routing, then count the slice in flight |
+| `answered` | A human commented or requested changes → one `terreno-5-taste` in a fresh subagent |
+| `broken` | CI failed or the PR conflicts → one `terreno-5-taste` |
+| `merged` | → `terreno-scan-5-track`: re-measure, close findings with evidence |
+| `closed` | Mark the slice abandoned, return its findings to `open`, free its slot |
+| `bot-pending`, `waiting` | Nothing — this is why the next tick exists |
+
+Then it refills capacity up to `wipLimit` and schedules the next tick: the provider's
+watch hook while CI runs, 2–5 minutes while review bots report, 15–30 minutes while a
+human holds the PR, and no wait at all while backlog work remains. Ticks that find
+nothing print nothing, and every comment is answered exactly once — answered ids live in
+state. See
+[`heartbeat.md`](https://github.com/TerrenoLabs/terreno/blob/master/plugins/terreno-scan/references/heartbeat.md).
+
+## PR routing
+
+Aim settles who reviews the campaign's PRs before any PR exists, and records a `review`
+block: `mode` (`fixed`, `codeowners`, `blame`, `round-robin`, `none`), reviewer and
+assignee handles, teams, draft policy, labels, `wipLimit`, `mergePolicy`, and how to
+notify. Handles are verified with `gh api repos/{owner}/{repo}/collaborators/<handle>`
+before use; an unverifiable handle is a human gate, never a silently unassigned PR.
+
+Routing is applied right after Brew reports the PR (`gh pr edit --add-reviewer
+--add-assignee --add-label`) and re-requested once when requested changes are addressed.
+The campaign never approves its own PRs, never dismisses a review, and never merges when
+`mergePolicy` is `human` — the default. See
+[`pr-routing.md`](https://github.com/TerrenoLabs/terreno/blob/master/plugins/terreno-scan/references/pr-routing.md).
+
+## Stage anatomy
+
+Every stage includes Preconditions, Inputs, Procedure, Supporting skills, Evidence
+produced, Success/Failure/Blocked conditions, and a recommended next stage — the same
+shape as the lifecycle stages.
+
+Results use `PASS`, `FAIL`, `BLOCKED`, or `PENDING` and the compact `v: 2`
+[`scan-result.schema.json`](https://github.com/TerrenoLabs/terreno/blob/master/plugins/terreno-scan/references/scan-result.schema.json)
+(`v`, `stage`, `status`, `next`, `action`; omit empty keys). Campaign state follows
+[`scan-state.schema.json`](https://github.com/TerrenoLabs/terreno/blob/master/plugins/terreno-scan/references/scan-state.schema.json)
+and findings follow
+[`finding.schema.json`](https://github.com/TerrenoLabs/terreno/blob/master/plugins/terreno-scan/references/finding.schema.json).
+Chat shows `status` / `next` / `action` plus the current metric; the YAML lives in a
+Details toggle.
+
+## Map-reduce
+
+Sweep shards rule hits into batches (default: at most 25 files or 80 hits per shard,
+never splitting a file) and maps one fresh worker per shard. Workers get a shard
+briefing — goal, rules, validity rule, severity rubric, file list, hit lines, allowed
+commands, and the return schema — and nothing else. They never search the repository at
+large, never spawn nested agents, and never edit files. Sift then dedupes by
+`rule + path + symbol`, re-runs evidence, refutes every high-severity candidate before
+keeping it, drops what does not reproduce, and ranks by impact × confidence ÷ effort.
+Dropped shards and capped coverage are always reported; silent truncation is a defect.
+See
+[`mapreduce.md`](https://github.com/TerrenoLabs/terreno/blob/master/plugins/terreno-scan/references/mapreduce.md).
+
+## Goal and metric
+
+Aim is not finished until the metric has a command that prints a number and the baseline
+came from running it. Track re-runs that command with the charter's protocol every round
+and records the value with its output. A finding that cannot be tied to the metric is
+dismissed in Sift, not deferred. Re-baselining without recording both values, the reason,
+and the round is untrustworthy and Track says so. See
+[`goal-tracking.md`](https://github.com/TerrenoLabs/terreno/blob/master/plugins/terreno-scan/references/goal-tracking.md).
+
+## Artifacts
+
+| Artifact | Default path | Committed |
+| --- | --- | --- |
+| Charter | `docs/scans/<goal-slug>/charter.md` | yes |
+| Findings report | `docs/scans/<goal-slug>/round-<n>-findings.md` | yes |
+| Shard manifest, candidates, slice briefs | round artifact directory | per repository policy |
+| Campaign state | `.terreno/scan/<goal-slug>.json` | no (git-ignored) |
+| Slice IP and tasks | the repository's existing IP/task convention, written by Grow | yes |
+
+An existing repository convention always wins over these defaults.
+
+## State machine
+
+```text
+Aim PASS → Sweep → Sift
+  Sift PASS (findings)    → Plot → handoff: grow
+  Sift PASS (dry round)   → Track
+  Plot PASS               → Grow → Pick/Roast inner loop → Brew → Taste → Track
+  Track PASS (backlog)    → Plot
+  Track PASS (empty)      → Sweep
+  Track PASS (target/budget/regression) → null, report and ask
+  Track PENDING (slice still in flight) → campaign waits → fresh Track
+  Any BLOCKED             → named human/external gate
+```
+
+The campaign loop owns persistence, retry, waiting, stop, and escalation. It never
+implements a finding itself, never commits, and never opens a PR — Plot hands each slice
+to Grow, and the lifecycle takes it from there.
+
+## Hosts
+
+| Host | Plugin | Invoke Aim | Invoke the campaign |
+| --- | --- | --- | --- |
+| Cursor | `terreno-scan` | `/terreno-scan-1-aim` | `/terreno-scan-campaign` |
+| Codex | `terreno-scan` | `$terreno-scan-1-aim` | `$terreno-scan-campaign` |
+| Claude Code | `terreno-scan` | `/terreno-scan:1-aim` | `/terreno-scan:campaign` |
+
+The resident loop is `/terreno-scan-loop` (Cursor), `$terreno-scan-loop` (Codex), and
+`/terreno-scan:loop` (Claude Code).
+
+`plugins/terreno-scan/` is canonical. `plugins/terreno-scan-claude/` is generated with
+shortened skill names; regenerate it with `bun run skills:sync` and never hand-edit it.
+
+## Example
+
+```text
+/terreno-scan:loop reduce cold compile time reviewer=octocat wip=2
+```
+
+Aim grills the target (30s), measures the baseline with `bun run compile` on a clean
+tree, approves four rules, and records `octocat` as reviewer with a two-PR limit. Sweep
+shards 180 hits into nine batches and maps nine workers. Sift keeps 12 of 31 candidates,
+refuting four high-severity claims that did not reproduce. Plot writes three slices; the
+loop runs the first through Grow, Pick/Roast, and Brew, then routes the PR to `octocat`.
+While that PR waits, the loop opens the second slice up to the limit and then goes quiet,
+ticking every 20 minutes. `octocat` requests a change at 14:05; the next tick hands that
+PR to Taste, which replies, fixes, runs the pre-push gate, pushes, and watches CI. When
+the PR merges, Track re-measures at 48.2s (from 58.6s), marks five findings fixed, and
+the loop refills capacity with the third slice.
+
+Stop it with a plain "stop" — it leaves every PR routed, state consistent, and reports
+what is in flight and who holds it.

package/dist/docs/versioned/next/reference/syncdb.md

@@ -23,7 +23,7 @@ Local-first data layer for Terreno frontends. A TinyBase `MergeableStore` on dev
 ## Key exports
 
 - `createSyncDb`, `SyncDb`, `SyncDbConfig`, `MutateArgs`
-- `betterAuthAdapter`, `AuthProvider`
+- `betterAuthAdapter`, `bridgeBetterAuthReactClient`, `AuthProvider`
 - `listConflicts`, `wipeLocalData`, `generateMutationId`
 - React (`@terreno/syncdb/react`): `SyncDbProvider`, `useEntity`, `useQuery`, `useEntityIds`, `useMutate`, `useSyncStatus`, `useConflicts`, `useSyncDebugLog`, `createCollectionHooks`
 - CLI: `terreno-syncdb-codegen` (generates `SYNC_COLLECTIONS` + friendly hooks from OpenAPI)
@@ -108,6 +108,7 @@ const todoRouter = modelRouter("/todos", Todo, {
   queryFilter: OwnerQueryFilter,
   sync: {
     scope: {type: "owner"}, // stream = todos|owner:{ownerId}
+    // adminBroadcast: true, // also emit sync:delta to todos|admin (default false)
   },
 });
 ```
@@ -126,7 +127,7 @@ new TerrenoApp({userModel: User})
 
 - **`SyncApp`** — HTTP sync routes (`/sync/snapshot`, `/sync/mutate`, `/sync/mutate/batch`, `/sync/key`, `/sync/streams`, `/sync/entities`).
 - **`RealtimeApp`** — Socket.io server with change-stream-driven `sync:delta` emission. Requires a **MongoDB replica set** (change streams). `modelRouter` `realtime` (RTK `sync` events) is deprecated and removed in Terreno 58; do not add it to new models.
-- **`ensureSyncIndexes`** — `TerrenoApp.start()` awaits index builds for snapshot queries and sync bookkeeping (`SyncMutation.mutationId` unique, `SyncCounter.stream` unique, etc.). Registration queues this work without contacting MongoDB, so models can load before the database connects. Hosts that build Express without `TerrenoApp.start()` should await `ensureSyncIndexes()` after connecting.
+- **`ensureSyncIndexes`** — `TerrenoApp.start()` binds the HTTP port first (or attaches to `httpServer` if the process already listened), then awaits index builds for snapshot queries and sync bookkeeping (`SyncMutation.mutationId` unique, `SyncCounter.stream` unique, etc.). Registration queues this work without contacting MongoDB, so models can load before the database connects. Hosts that build Express without `TerrenoApp.start()` should await `ensureSyncIndexes()` after connecting.
 
 Socket auth requires at least one configured authentication method. It enables legacy JWT
 validation when `tokenSecret` or `TOKEN_SECRET` is available. Better Auth can be used without
@@ -142,20 +143,29 @@ is the fallback.
 ## createSyncDb configuration
 
 ```typescript
-import {betterAuthAdapter, createSyncDb} from "@terreno/syncdb";
+import {betterAuthAdapter, bridgeBetterAuthReactClient, createSyncDb} from "@terreno/syncdb";
 
 export const syncDb = createSyncDb({
   name: "myapp",
   collections: ["todos"],
-  authProvider: betterAuthAdapter(authClient),
+  authProvider: betterAuthAdapter(bridgeBetterAuthReactClient(authClient)),
   baseUrl: "http://localhost:4000",
 });
 ```
 
+Wrap a Better Auth **react** client in `bridgeBetterAuthReactClient`. Its `useSession` is a React
+hook rather than the `.subscribe` surface the adapter watches, so without the bridge the adapter
+falls back to polling `getSession()` and produces constant `/api/auth/get-session` traffic. The
+bridge exposes the client's `$store.atoms.session` atom and degrades to the polling fallback when
+that atom is absent. Clients that already expose `getSession` plus a subscribable `useSession` can
+be passed to `betterAuthAdapter` directly.
+
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `name` | `string` | — (required) | Persisted database name |
 | `collections` | `string[]` | — (required) | Collection names to sync (local tables + subscriptions) |
+| `windowCollections` | `string[]` | `[]` | Collections that join `{collection}\|admin`, skip snapshots/reconcile, and hydrate only known REST membership ids |
+| `organizationIdProvider` | `() => string \| undefined` | — | Read at send time: sets `X-Organization-Id` on HTTP sync calls and `organizationId` on socket mutate payloads |
 | `authProvider` | `AuthProvider` | — (required) | `{getToken, getUserId, onAuthChange, refresh?}` |
 | `baseUrl` | `string` | — | Server origin; required unless both `transport` and `httpChannel` are injected |
 | `transport` | `SyncTransport` | socket transport from `baseUrl` | Override for tests or custom wiring |
@@ -189,7 +199,8 @@ export const syncDb = createSyncDb({
 | `goOnline()` | End simulated outage; reconnect triggers reconcile + outbox replay. |
 | `mutate({collection, operation, id?, data?})` | Optimistic local write + durable outbox enqueue + fire-and-forget replay. Returns `{mutationId, id}`. |
 | `reconcile()` | HTTP snapshot catch-up for every known stream; runs tombstone compaction on success. Also runs automatically on (re)connect, on a rate-limited seq-jump hint, and on the periodic timer; each `sync:subscribed` confirmation additionally pages just the streams it names. |
-| `forceResync()` | Purge every known stream locally and re-bootstrap from cursor 0 (outbox/conflicts untouched). Returns `{ok, reason?, streams, purged, repaired}`. |
+| `hydrateWindow({collection, ids, restRows?})` | Admin window upsert: REST rows (optional) land immediately; every requested id is also fetched from `GET /sync/entities` before this resolves so seq/deleted metadata is canonical for immediate update/delete. A `{collection}|admin` delta that lands while the fetch is in flight wins, so hydration never rewinds a row to an older seq. Unknown ids are ignored. |
+| `forceResync()` | Purge every known stream locally and re-bootstrap from cursor 0 (outbox/conflicts untouched). Returns `{ok, reason?, streams, purged, repaired}`. After discovery and each stream bootstrap it waits for in-flight `start`/`stop`/auth-change work, then abandons with `reason: "superseded"` when that work switched users or generations. |
 | `replayOutbox()` | Drain queued mutations for the current user now. |
 | `resolveConflict({mutationId, strategy})` | Apply `"useServer"` or `"keepMine"` to a recorded conflict. |
 | `retryFailed({entityId})` | Re-enable an entity's queued successors after a terminal validation failure. |
@@ -200,6 +211,27 @@ export const syncDb = createSyncDb({
 | `outbox` | Durable mutation outbox (`Outbox`). |
 | `debug` | `SyncDebugLog` when `debug` is enabled; otherwise `undefined`. |
 
+### Local MCP debugging
+
+When `debug` is enabled, `createSyncDb` registers the client by `name` on the
+development runtime bridge used by `terreno-mcp-local`. Production clients stay
+unregistered when debug logging is off.
+
+| Tool | Operations |
+| --- | --- |
+| `get_syncdb_state` | Read status, entities/tombstones, decoded outbox, conflicts, cursors, known streams, repair markers, values, and debug events |
+| `syncdb_snapshot` | `capture`, `list`, `get`, `compare`, `delete` |
+| `syncdb_action` | `mutate`, `setLocalEntity`, `deleteLocalEntity`, `flush`, `reconcile`, `forceResync`, `resolveConflict`, `retryFailed`, `goOffline`, `goOnline`, `clearDebug`, `mergeSnapshot` |
+
+Read and snapshot tools redact sensitive field names. `syncdb_action` requires
+the local MCP process to start with `TERRENO_MCP_EVAL=1`. `flush` means “drain
+the durable outbox now.” `mergeSnapshot` CRDT-merges TinyBase mergeable content
+from a snapshot retained in the same MCP process. Later HLCs win, including
+deletes; it does not replace the live store. To force specific rows from a
+capture, use `setLocalEntity` from `syncdb_snapshot` `get`.
+
+See [Debug a Terreno app with MCP](../how-to/debug-with-mcp.md).
+
 ## React hooks
 
 Import from `@terreno/syncdb/react`:
@@ -340,7 +372,7 @@ In React, prefer `useConflicts()`.
 | Strategy | Behavior |
 |----------|----------|
 | `"useServer"` | Overwrite local entity with canonical server data/seq; clear pending state; discard conflicted outbox row. Writes a **tombstone** when the server side is deleted. |
-| `"keepMine"` | Re-enqueue the mutation under a **fresh** `mutationId` with `baseVersion` set to the server's seq; local optimistic data is kept. |
+| `"keepMine"` | Re-enqueue the mutation under a **fresh** `mutationId` with `baseVersion` set to the server's seq; local optimistic data is kept. All durable mutation metadata, including `mutationMode: "adminWindow"`, is preserved so retried admin-window writes receive the same RBAC, protected-field, hook, and audit handling. |
 
 Resolve via `client.resolveConflict({mutationId, strategy})` or `useConflicts().resolve(...)`.
 
@@ -382,6 +414,7 @@ sync: {scope: {type: "owner"}}                        // todos|owner:{ownerId}
 sync: {scope: {type: "owner", field: "userId"}}       // todos|owner:{userId}
 sync: {scope: {type: "tenant", field: "organizationId"}} // todos|tenant:{orgId}
 sync: {scope: {type: "broadcast"}}                    // todos|all
+sync: {scope: {type: "owner"}, adminBroadcast: true}  // owner stream + todos|admin
 sync: {
   scope: (doc) => String(doc.workspaceId),
   snapshotFilter: (user) => ({workspaceId: {$in: [...]}}), // required for custom
@@ -390,6 +423,16 @@ sync: {
 
 - **Owner** streams use the authenticated socket's user id (client cannot pick another user's stream).
 - **Tenant/custom** scopes resolve memberships via `SyncApp` `getUserScopes`.
+- **`adminBroadcast`** (default `false`) is an additive fan-in flag on the existing collection `sync` config. When `true`, `sync:delta` emitters also publish to `{collection}|admin`. Do not change the app collection `scope` to broadcast for admin; app clients keep owner/tenant streams. Join `{collection}|admin` with `sync:subscribe {mode: "window"}`. The gate matches the admin UI shell: with `SyncApp({accessControl})`, the caller needs `admin:access`; without RBAC, `user.admin` / `Permissions.IsAdmin` is enough. When `AdminApp` is mounted it also registers that model's list/read permissions and `queryFilter`, so window subscribe, `GET /sync/entities`, and `|admin` live deltas cannot return rows `/admin` REST would hide (product `IsOwner` still treats `user.admin` as owner). Others get `sync:error`. The server confirms `sync:subscribed {mode: "window"}` and does not dump snapshot pages. Clients listed in `createSyncDb({windowCollections})` skip `GET /sync/snapshot` for those collections (startup, subscribe catch-up, and the reconcile timer). Hydrate known ids with `hydrateWindow` (REST rows + `GET /sync/entities`). For that HTTP lookup, an allowed admin-window caller on an `adminBroadcast` collection is not limited to owner/tenant stream membership. Deltas on `{collection}|admin` update or tombstone **ids already in the local window only**; unknown ids are ignored until Refresh or load-more hydrates them (Refresh = current REST query + `hydrateWindow`).
+- `AdminApp({organizations: true})` forces `adminBroadcast: false` for models
+  with `organizationId`. The current admin-window socket protocol has no
+  selected-organization field, so those models use REST with
+  `X-Organization-Id` instead of weakening `OrgQueryFilter` or streaming
+  cross-organization rows.
+- Use a dedicated `createSyncDb` client/store for an admin window when the same app
+  also subscribes to that collection through an owner or tenant stream. One socket
+  subscription has one mode per collection, and a separate store prevents
+  admin-hydrated rows from appearing in the product UI.
 - **`snapshotFilter`** restricts `GET /sync/snapshot` server-side. Auto-derived for owner/tenant; required for custom resolver scopes.
 
 ## Sync protocol
@@ -400,9 +443,9 @@ sync: {
 |----------|---------|
 | `GET /sync/snapshot?collection=&stream=&cursor=&limit=` | Bootstrap + catch-up per stream |
 | `GET /sync/streams` | Current stream membership for the user |
-| `GET /sync/entities` | Point lookup for entity repair |
-| `POST /sync/mutate` | Single mutation (HTTP fallback) |
-| `POST /sync/mutate/batch` | Batched mutations (max 100, strict order, stop at first non-ack) |
+| `GET /sync/entities` | Point lookup for entity repair and admin window hydrate. Admin-window callers (`admin:access` with RBAC, else `user.admin`) on `adminBroadcast` collections receive requested ids across product streams. When AdminApp registered a scope, list/read/`queryFilter` still apply; unknown or out-of-scope ids are omitted |
+| `POST /sync/mutate` | Single mutation (HTTP fallback). Optional `mutationMode: "adminWindow"` validates `adminBroadcast`, admin-window access, and a registered AdminApp write scope, then runs the shared sync executor with **AdminApp** pre/post hooks (not product `modelRouter` hooks), plus the same permission (including org membership), stripping, and audit semantics as `/admin` REST. HTTP mutate binds `X-Organization-Id` into org context |
+| `POST /sync/mutate/batch` | Batched mutations (max 100, strict order, stop at first non-ack). Each mutation may carry `mutationMode: "adminWindow"` under the same AdminApp executor hook path as single mutate |
 | `GET /sync/key` | Per-user encryption key material (web) |
 
 Conflict responses on mutate: **409** with `{nack}` body (`code: "conflict"`).
@@ -411,11 +454,11 @@ Conflict responses on mutate: **409** with `{nack}` body (`code: "conflict"`).
 
 | Event | Direction | Payload |
 |-------|-----------|---------|
-| `sync:subscribe` / `sync:unsubscribe` | client → server | `{collections: string[]}` |
-| `sync:subscribed` | server → client | `{collection, streams}` — sent after the stream rooms are joined; the client pages each confirmed stream from its cursor so a write landing between the startup snapshot and the join is not missed |
+| `sync:subscribe` / `sync:unsubscribe` | client → server | `{collections: string[], mode?: "window"}` |
+| `sync:subscribed` | server → client | `{collection, streams, mode?: "window"}` — sent after the stream rooms are joined; full-mode clients page each confirmed stream from its cursor. `mode: "window"` joins `{collection}\|admin` only and must not trigger snapshot paging |
 | `sync:error` | server → client | `{collection, message}` |
 | `sync:delta` | server → client | `{collection, id, method, data?, seq, stream, deleted?, frontierSeq?}` |
-| `sync:mutate` | client → server | `{mutationId, collection, operation, id?, data?, baseVersion?}` |
+| `sync:mutate` | client → server | `{mutationId, collection, operation, id?, data?, baseVersion?, mutationMode?}` — validated `mutationMode: "adminWindow"` uses AdminApp executor hooks server-side |
 | `sync:ack` | server → client | `{mutationId, id, seq}` |
 | `sync:nack` | server → client | `{mutationId, code, serverDoc?, serverSeq?, serverDeleted?, message?, retryAfterMs?}` |
 | `sync:mutateBatch` | client → server | `{mutations: SyncMutateRequest[], batchId?}` |
@@ -485,4 +528,8 @@ Backend sync requires a MongoDB replica set (`MONGO_URI` with `replicaSet=`) for
 - **No `bulkWrite` / `updateMany` / `deleteMany`** on synced models — use per-document loops.
 - **Do not write reserved tables** (`_outbox`, `_cursors`, `_conflicts`) directly — use `client.mutate`, hooks, and `resolveConflict`.
 - **User switch wipes local data** — confirmed different-user login clears the previous user's store; bare logout/401 does not (INV-2).
-- **Keep `@terreno/rtk` for non-synced routes** — generated OpenAPI hooks remain the right tool for custom REST endpoints, admin, and auth configuration. See [How to migrate from RTK to syncdb](../how-to/migrate-rtk-to-syncdb.md).
+- **Keep `@terreno/rtk` for non-synced routes** — generated OpenAPI hooks remain
+  the right tool for custom REST endpoints, auth, feature flags, and ObjectId
+  admin compatibility CRUD. Eligible admin String-`_id` collection CRUD uses
+  windowed syncdb; framework admin RPC uses its host-bound fetch client. See
+  [How to migrate from RTK to syncdb](../how-to/migrate-rtk-to-syncdb.md).

package/dist/docs/versioned/next/reference/test.md

@@ -109,8 +109,54 @@ Defaults: `TOKEN_SECRET`, `TOKEN_ISSUER`, `REFRESH_TOKEN_SECRET`, `SESSION_SECRE
 
 ## Coverage gates
 
-Package CI uses `scripts/check-coverage.ts` to enforce the package-wide thresholds
-declared in `bunfig.toml`.
+Package CI uses `scripts/check-coverage.ts` (`bun run test:coverage`, default 95%
+functions and lines) as the live gate. Bun 1.4.2+ may exit 1 on bunfig
+`coverageThreshold` before isolated LCOV merges; the script continues when tests
+reported `0 fail` and then enforces 95% on the merged report. Dedicated CircleCI
+jobs (`api-ci`, `ai-ci`,
+`rtk-ci`, `ui-ci`, `syncdb-ci`, `comms-ci`, `mcp-server-ci`, `admin-spa-ci`) run
+that script. Published packages without a dedicated workflow
+(`admin-backend`, `admin-frontend`, `api-health`, `feature-flags`, `@terreno/test`)
+run the same lint, compile, and coverage commands via the parameterized
+`packages-ci` job. Retained GitHub Actions twins stay in lockstep (`push.branches-ignore: ["**"]`),
+including `.github/workflows/packages-ci.yml`. Those twins run
+`scripts/ci/check-new-file-coverage-lcov.sh` with `working-directory: .` and
+pass `secrets.CODECOV_TOKEN` into `upload-codecov`.
+
+Each of those jobs then uploads `coverage/lcov.info` to Codecov with a distinct
+flag (`api`, `ui`, `rtk`, …) via `scripts/upload-codecov.sh`. The script
+downloads the linux uploader over HTTPS and refuses to run it unless the
+SHA-256 digest matches the pin in the script (`CODECOV_UPLOADER_SHA256`).
+`codecov.yml` sets per-package flags, `target: auto` with a 1% threshold so
+trivial deltas do not fail PRs, and PR comments for the coverage diff. Uploads
+skip when `CODECOV_TOKEN` is unset. Maintainers set that token in CircleCI
+project env and as a GitHub Actions secret. For a public repo, Codecov still
+requires a token unless the org disables token authentication for public
+repositories (see [Codecov tokens](https://docs.codecov.com/docs/codecov-tokens)).
+
+Demo CI uses `scripts/check-demo-coverage.ts` to fail when a PascalCase component
+exported from `ui/src/index.tsx` has neither a `demo/story-config` registration nor
+an allowlist reason in `DEMO_COVERAGE_ALLOWLIST`. Run it from the repo root:
+
+```bash
+bun run check:demo-coverage
+```
+
+The `demo_lint_and_typecheck` CircleCI command (and the retained
+`.github/workflows/ui-demo-ci.yml` job) runs the unit tests and this check after
+the demo compiles. Add a story plus `demoConfig.tsx` registration for new
+components, or an allowlist entry with a specific reason — not "hard to demo".
+The allowlist is limited to shell/providers, React context objects, thin RN
+list wrappers, subcomponents already exercised by a parent story
+(Filter, Table, DateTimeField, HeightField, ConsentFormScreen), and
+product surfaces that belong in `example-frontend` rather than the isolated
+UI demo (announcements and in-app notifications).
+Standalone picker sheets (`NumberPickerActionSheet`, `DecimalRangeActionSheet`)
+have their own demo stories.
+
+`demo/package.json` `test:ci` runs Bun tests, including a smoke suite that mounts every
+registered `DemoConfig` demo and story through `renderWithTheme` from
+`@terreno/ui`'s test utilities (`demo/storiesSmoke.test.tsx`).
 
 Pull requests also run the `New file coverage` workflow. Every newly added workspace
 `.ts` or `.tsx` implementation file must have at least 90% function coverage and 90%
@@ -118,10 +164,17 @@ line coverage. Test, spec, story, generated OpenAPI SDK, `dist`, isolated-test,
 `src/types` type modules, demo `story-config/*.config.tsx`, and Expo Router route
 files (`index`, `_layout`, `+not-found`, `[param]`, plus example recovery screens
 `forgotPassword` / `resetPassword` / `verifyEmail`) are excluded. A new implementation
-file that is absent from LCOV is treated as 0% covered. The gate runs each package's `bun test` file arguments (or `src` / `*.test.ts`
-globs) so Playwright `*.spec.ts` files are not collected. Globs are expanded in
-the coverage process before `bun test` is spawned, because spawn does not pass
-them through a shell. A glob that matches no files is omitted.
+file that is absent from LCOV is treated as 0% covered, except files listed in
+that package's `bunfig.toml` `coveragePathIgnorePatterns` (the same paths the
+95% package gate already omits). Package CI jobs that
+already produced `coverage/lcov.info` run the 90% check against that report
+(`--package` + `--lcov`) so the dedicated job does not rerun the suite.
+When the dedicated job does rerun a package, it prefers colocated
+`foo.test.ts` / `foo.test.tsx` next to each new `foo.ts` and falls back to
+the package `bun test` paths only when a new file has no sibling test.
+It compiles `@terreno/*` workspace dist deps only when the package imports
+them. The gate still expands globs before spawn so Playwright `*.spec.ts`
+files are not collected. A glob that matches no files is omitted.
 
 Run the same check locally against a base commit:
 

package/dist/docs/versioned/next/reference/ui-performance.md

@@ -137,8 +137,9 @@ time includes dependency evaluation in the Bun test harness. Lower is better.
 
 Changes in this slice:
 
-- Measured heavy optional widgets (`GPTChat`, `EmojiSelector`, `MarkdownEditor`, consent/admin tools, and related
+- Measured heavy optional widgets (`GPTChat`, `EmojiSelector`, `MarkdownEditor`, consent/admin tools, `LineChart`, `BarChart`, `AreaChart`, `DonutChart`, and related
   exports) now cross lazy root boundaries so their implementation files stay off the cold root import path.
+  `DashboardGrid` stays eager.
 - `MarkdownView`, `DataTable` header info, and `EmojiSelector` defer `react-native-markdown-display` and
   `emoji-datasource` until first use.
 - `RootImportRegression.test.tsx` and `bun run performance:imports` guard the public entrypoints.