@terreno/mcp 57.2.0 → 57.4.0

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/FlourishHealth/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/FlourishHealth/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/FlourishHealth/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/FlourishHealth/terreno/blob/master/plugins/terreno-scan/references/scan-state.schema.json)
+and findings follow
+[`finding.schema.json`](https://github.com/FlourishHealth/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/FlourishHealth/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/FlourishHealth/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)
   },
 });
 ```
@@ -125,32 +126,46 @@ 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).
-- **`ensureSyncIndexes`** — `TerrenoApp.start()` awaits index builds for snapshot queries and sync bookkeeping (`SyncMutation.mutationId` unique, `SyncCounter.stream` unique, etc.). Hosts that build Express without `TerrenoApp.start()` should await `ensureSyncIndexes()` themselves.
+- **`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()` 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 accepts legacy JWTs by default. For Better Auth sessions:
+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
+a JWT secret:
 
 ```typescript
 new RealtimeApp({betterAuth: {auth, userModel: User}})
 ```
 
+When both methods are configured, JWT validation runs first and Better Auth session validation
+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 |
@@ -184,6 +199,7 @@ 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. |
+| `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}`. |
 | `replayOutbox()` | Drain queued mutations for the current user now. |
 | `resolveConflict({mutationId, strategy})` | Apply `"useServer"` or `"keepMine"` to a recorded conflict. |
@@ -335,7 +351,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(...)`.
 
@@ -377,6 +393,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
@@ -385,6 +402,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
@@ -395,9 +422,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"`).
@@ -406,11 +433,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?}` |
@@ -480,4 +507,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

@@ -106,3 +106,76 @@ Defaults: `TOKEN_SECRET`, `TOKEN_ISSUER`, `REFRESH_TOKEN_SECRET`, `SESSION_SECRE
 - Preload once per package via `bunfig.toml`; do not start Mongo in individual test files.
 - Prefer `registerSimpleMongoPreload` unless you need transactions or fixture caching (`registerBackendPreload`).
 - Never mock `@terreno/api` or Mongoose models in package tests — use the real stack against memory Mongo.
+
+## Coverage gates
+
+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 (`on: []`),
+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%
+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. 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:
+
+```bash
+bun run check:new-file-coverage --base=origin/master --threshold=90
+```

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

@@ -0,0 +1,256 @@
+# UI performance benchmarks
+
+Run the benchmark that covers the component being changed:
+
+```bash
+cd ui
+bun run performance:p0
+bun run performance:p0:openapi
+bun run performance:p1
+bun run performance:p2:button
+bun run performance:p2:responsive-box
+bun run performance:datatable-virtual
+bun run performance:imports
+```
+
+The benchmarks render large trees through the same React Native test environment as the UI
+component suite. They report median wall-clock times after two warmups and seven measured samples:
+
+- 500 `Box`, `Text`, and `Heading` instances
+- 100 `MarkdownView` instances
+- 500 theme consumers
+- 500 `useOpenAPISpec` consumers
+- a 100-row, eight-column `DataTable` with two pinned columns
+- 500 `Icon` instances
+- 500 plain `Button` instances and 100 confirmation `Button` instances
+- 500 responsive `Box` instances with `sm`, `md`, and `lg` direction props
+- 1,000-row `DataTable` workloads with pinned and unpinned virtualization
+- initial mount, same-prop update, and changed-prop/theme update timings
+
+Use it for before/after comparisons on the same machine. It is not a device frame-rate benchmark;
+native and browser profiling remain necessary for user-visible regressions.
+
+## August 2026 P0 optimization results
+
+All measurements below came from the same Cursor Cloud VM using Bun 1.3.11 and the default benchmark
+settings. Times are milliseconds; lower is better.
+
+| Step | Box same | Text same | Heading same | Markdown same | Theme same |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| Baseline | 6.86 | 4.70 | 4.69 | 37.87 | 1.29 |
+| Memoize `Box` and reuse its style/ref | 5.78 | 4.84 | 4.69 | 30.58 | 1.63 |
+| Centralize fonts; memoize typography and markdown styles | 5.71 | 4.03 | 3.94 | 0.63 | 1.20 |
+| Stabilize theme actions and context value | 1.07 | 0.96 | 0.86 | 0.33 | 1.22 |
+| Share `Box` style mappers per computed theme | 1.01 | 0.90 | 0.79 | 0.31 | 1.21 |
+
+Final same-prop improvements versus baseline:
+
+| Workload | Improvement |
+| --- | ---: |
+| `Box` | 85.2% |
+| `Text` | 80.9% |
+| `Heading` | 83.2% |
+| `MarkdownView` | 99.2% |
+| Theme consumers | 6.4% |
+
+Changed-prop work remains intact: the final medians were 9.02ms for `Box`, 6.89ms for `Text`,
+6.52ms for `Heading`, and 28.08ms for `MarkdownView`. This is intentional: memoization skips only
+equivalent props, while changed props and theme values still render and are covered by
+`P0RenderRegression.test.tsx`.
+
+## August 2026 P1 optimization results
+
+These measurements used the same Cursor Cloud VM and Bun 1.3.11, with 21 measured samples to reduce
+variance. The changed `DataTable` workload replaces one cell while preserving the other row
+references. Times are milliseconds; lower is better.
+
+| Workload | Phase | Baseline | Optimized | Change |
+| --- | --- | ---: | ---: | ---: |
+| `DataTable` | Initial render | 23.20 | 24.08 | Within benchmark variance |
+| `DataTable` | Same-prop update | 32.49 | 0.18 | 99.4% faster |
+| `DataTable` | One-cell update | 31.74 | 1.57 | 95.1% faster |
+| `Icon` | Initial render | 1.47 | 1.50 | Within benchmark variance |
+| `Icon` | Same-prop update | 1.81 | 0.93 | 48.6% faster |
+| `Icon` | Changed-prop update | 3.07 | 3.61 | Full redraw retained |
+
+`DataTable` now reuses equivalent table, content, row, and cell work; computes pinned offsets once;
+and applies the default text size without cloning the full grid. `Icon` skips equivalent parent
+updates while still redrawing for icon prop and theme changes. `P1RenderRegression.test.tsx` covers
+both guarantees.
+
+The P1 example renderers import public component subpaths such as `@terreno/ui/DataTable` and
+`@terreno/ui/Icon`. These subpaths avoid evaluating the complete root export graph. The root
+`@terreno/ui` import and existing direct `src`/`dist` paths remain supported.
+
+## August 2026 OpenAPI context optimization results (Task 1.1)
+
+These measurements used the same Cursor Cloud VM and Bun 1.3.11, with 21 measured samples and 3
+warmups. The workload renders 500 `useOpenAPISpec` consumers under a parent rerender with an
+unchanged spec, then replaces the spec URL so field lookups must refresh. Times are milliseconds;
+lower is better.
+
+| Phase | Baseline | Optimized | Change |
+| --- | ---: | ---: | ---: |
+| Initial render | 1.65 | 1.64 | Within benchmark variance |
+| Same-prop update | 1.91 | 1.70 | 11.0% faster |
+| Spec replacement update | 1.76 | 1.79 | Within benchmark variance |
+
+`OpenAPIProvider` now memoizes `getModelField`, `getModelFields`, and the context value with complete
+`spec` dependencies. Unchanged metadata skips memoized consumers; replacing the spec updates field
+lookups immediately. `OpenAPIRenderRegression.test.tsx` covers both guarantees.
+
+## August 2026 DataTable virtualization results
+
+These measurements used the same Cursor Cloud VM and Bun 1.3.11, with 21 measured samples and 1,000-row
+pinned and unpinned workloads (`bun run performance:datatable-virtual`). Mounted row counts count unique
+`bench-table.row-*` test ids present after the initial render. Times are milliseconds; lower is better.
+
+| Workload | Phase | Baseline | Virtualized | Change |
+| --- | --- | ---: | ---: | ---: |
+| `DataTable` unpinned | Initial render | 224.59 | 3.45 | 98.5% faster |
+| `DataTable` unpinned | Same-prop update | 4.38 | 0.72 | 83.6% faster |
+| `DataTable` unpinned | One-cell update | 4.19 | 1.25 | 70.2% faster |
+| `DataTable` unpinned | Mounted rows | 1,000 | 15 | 98.5% fewer |
+| `DataTable` pinned (2 cols) | Initial render | 232.72 | 3.09 | 98.7% faster |
+| `DataTable` pinned (2 cols) | Same-prop update | 7.17 | 0.69 | 90.4% faster |
+| `DataTable` pinned (2 cols) | One-cell update | 6.86 | 1.31 | 80.9% faster |
+| `DataTable` pinned (2 cols) | Mounted rows | 1,000 | 15 | 98.5% fewer |
+
+Large `DataTable` bodies now virtualize with React Native `FlatList`, syncing pinned, more-column, and
+scrollable row lists while preserving horizontal header/body scroll sync, sorting, pagination, pinned
+columns, row-detail modals, custom cells, highlights, and row test ids. `DataTableVirtualizationRegression.test.tsx`
+covers viewport-bounded mounts, queued vertical-scroll flush after the sync lock, and changed rows after scrolling.
+
+## August 2026 root import optimization results
+
+These measurements used the same Cursor Cloud VM and Bun 1.3.11. Each workload uses a fresh Bun test process
+(seven measured samples, two warmups). The graph columns count evaluated `@terreno/ui` source modules reached through
+static `import`/`export` edges (type-only re-exports are excluded). Output bytes sum those module file sizes. Elapsed
+time includes dependency evaluation in the Bun test harness. Lower is better.
+
+| Workload | Modules | Output bytes | Elapsed (ms) | Baseline modules | Baseline bytes | Baseline elapsed (ms) |
+| --- | ---: | ---: | ---: | ---: | ---: | ---: |
+| `@terreno/ui/Button` subpath | 17 | 345,992 | 22.8 | 19 | 383,185 | 22.3 |
+| `@terreno/ui` root | 138 | 889,124 | 189.3 | 151 | 1,031,537 | 207.9 |
+| `@terreno/ui/DataTable` subpath | 25 | 387,392 | 24.9 | 26 | 424,006 | 44.6 |
+| `@terreno/ui/MarkdownView` subpath | 5 | 19,036 | 3.5 | 7 | 148,456 | 27.0 |
+
+Changes in this slice:
+
+- 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.
+
+Run the import benchmark locally:
+
+```bash
+cd ui
+bun run performance:imports
+```
+
+Override sample counts when comparing smaller deltas:
+
+```bash
+UI_IMPORT_BENCHMARK_SAMPLES=21 \
+UI_IMPORT_BENCHMARK_WARMUPS=3 \
+bun run performance:imports
+```
+
+The benchmark prints a machine-readable `UI_IMPORT_BENCHMARK_RESULTS` JSON line for CI or local reporting.
+
+## August 2026 P2 Button optimization results
+
+These measurements used the same Cursor Cloud VM and Bun 1.3.11, with 21 measured samples. The
+changed workload replaces one button label or confirmation message while preserving every other
+prop. Times are milliseconds; lower is better.
+
+| Workload | Phase | Baseline | Optimized | Change |
+| --- | --- | ---: | ---: | ---: |
+| Plain `Button` | Initial render | 7.85 | 8.66 | Within benchmark variance |
+| Plain `Button` | Same-prop update | 13.73 | 0.94 | 93.1% faster |
+| Plain `Button` | One-label update | 11.99 | 0.98 | 91.8% faster |
+| Confirmation `Button` | Initial render | 1.71 | 1.93 | Within benchmark variance |
+| Confirmation `Button` | Same-prop update | 2.79 | 0.30 | 89.2% faster |
+| Confirmation `Button` | One-message update | 2.71 | 0.32 | 88.3% faster |
+
+`Button` now skips equivalent parent updates, keeps debounce identity stable, and cancels retained
+debounce timers on replacement or unmount. Plain buttons use a separate path that does not allocate
+confirmation state or request the lazy modal. Delayed handlers remain disabled until completion.
+Confirmation buttons clear the press cooldown when the modal closes, so Cancel, dismiss, or Confirm
+still allows an immediate reopen while repeated presses that do not close the modal stay debounced.
+`P2ButtonRenderRegression.test.tsx` covers equivalent props plus changed labels, confirmation
+content, and theme values.
+
+## August 2026 P2 responsive Box optimization results
+
+These measurements used the same Cursor Cloud VM and Bun 1.3.11, with 21 measured samples. Times
+are milliseconds; lower is better.
+
+| Phase | Baseline | Optimized | Change |
+| --- | ---: | ---: | ---: |
+| Initial render | 3.01 | 3.12 | Within benchmark variance |
+| Same-prop update | 0.89 | 0.88 | Within benchmark variance |
+| One-direction update | 0.92 | 0.90 | Within benchmark variance |
+| Initial `Dimensions.get` calls | 1,500 | 1 | 99.9% fewer |
+
+Responsive Boxes now subscribe to one shared window-dimension source. A resize or rotation updates
+the cached breakpoint and every subscribed Box without a synchronous dimension read per responsive
+prop. Non-responsive Boxes do not subscribe. Focused regressions cover the native 320pt / 375pt / 600pt /
+1024pt boundaries, the web 1024pt / 1280pt desktop boundaries, listener sharing, cleanup, and
+changed responsive styles.
+
+## Environment overrides
+
+Increase samples or workload size when comparing smaller changes:
+
+```bash
+UI_P0_BENCHMARK_SAMPLES=21 \
+UI_P0_BENCHMARK_WARMUPS=3 \
+UI_P0_BENCHMARK_SIZE=1000 \
+bun run performance:p0
+```
+
+```bash
+UI_P1_BENCHMARK_SAMPLES=21 \
+UI_P1_BENCHMARK_WARMUPS=3 \
+UI_P1_BENCHMARK_TABLE_ROWS=200 \
+UI_P1_BENCHMARK_ICONS=1000 \
+bun run performance:p1
+```
+
+```bash
+UI_P0_OPENAPI_BENCHMARK_SAMPLES=21 \
+UI_P0_OPENAPI_BENCHMARK_WARMUPS=3 \
+UI_P0_OPENAPI_BENCHMARK_SIZE=500 \
+bun run performance:p0:openapi
+```
+
+```bash
+UI_P2_BUTTON_BENCHMARK_SAMPLES=21 \
+UI_P2_BUTTON_BENCHMARK_WARMUPS=3 \
+UI_P2_BUTTON_BENCHMARK_SIZE=1000 \
+UI_P2_CONFIRMATION_BUTTON_BENCHMARK_SIZE=200 \
+bun run performance:p2:button
+```
+
+```bash
+UI_P2_RESPONSIVE_BOX_BENCHMARK_SAMPLES=21 \
+UI_P2_RESPONSIVE_BOX_BENCHMARK_WARMUPS=3 \
+UI_P2_RESPONSIVE_BOX_BENCHMARK_SIZE=1000 \
+bun run performance:p2:responsive-box
+```
+
+```bash
+UI_DATATABLE_VIRTUAL_BENCHMARK_SAMPLES=21 \
+UI_DATATABLE_VIRTUAL_BENCHMARK_WARMUPS=3 \
+UI_DATATABLE_VIRTUAL_BENCHMARK_ROWS=1500 \
+bun run performance:datatable-virtual
+```
+
+The benchmarks print machine-readable `UI_P0_BENCHMARK_RESULTS`, `UI_P1_BENCHMARK_RESULTS`,
+`UI_P2_BUTTON_BENCHMARK_RESULTS`, `UI_P2_RESPONSIVE_BOX_BENCHMARK_RESULTS`,
+`UI_DATATABLE_VIRTUAL_BENCHMARK_RESULTS`, or `UI_IMPORT_BENCHMARK_RESULTS` JSON lines for CI or
+local reporting.