@terreno/mcp 57.2.0 → 57.3.0

package/dist/docs/versioned/next/reference/environment-variables.md

@@ -66,7 +66,7 @@ Comprehensive guide to environment variables used across Terreno packages and ex
 | `ENABLE_SWAGGER` | `@terreno/api` | ❌ | `false` | No | server |
 | `APP_ENV` | example-backend | ❌ | `development` | No | server |
 | `BACKEND_URL` | scripts, deploy | ❌ | — | No | server |
-| `FRONTEND_URL` | example-backend CORS | ❌ | auto | No | server |
+| `FRONTEND_URL` | example-backend CORS and `authOptions.publicAppUrl` | ❌ | `http://localhost:8082` | No | server |
 | `API_URL` | microservice split | ❌ | — | No | server |
 | `DISABLE_LOG_ALL_REQUESTS` | `@terreno/api` logging | ❌ | — | No | server |
 
@@ -136,14 +136,45 @@ Resolution order for API base URL (`rtk/src/constants.ts`):
 | `COMMS_DEFAULT_FROM` | example-backend / `@terreno/comms` | ❌ | — | No | server |
 | `COMMS_DEFAULT_FROM_NAME` | example-backend | ❌ | — | No | server |
 | `SENDGRID_API_KEY` | `@terreno/comms/adapters/sendgrid` | ❌ | — | Yes | server |
+| `SENDGRID_WEBHOOK_VERIFICATION_KEY` | `@terreno/comms/adapters/sendgrid` | ❌ | — | Yes | server |
 | `SENDGRID_SANDBOX_MODE` | example-backend | ❌ | — | No | server |
+| `TWILIO_ACCOUNT_SID` | `@terreno/comms/adapters/twilioSms`, `@terreno/comms/adapters/twilioVerify` | ❌ | — | Yes | server |
+| `TWILIO_AUTH_TOKEN` | `@terreno/comms/adapters/twilioSms`, `@terreno/comms/adapters/twilioVerify` | ❌ | — | Yes | server |
+| `TWILIO_MESSAGING_SERVICE_SID` | `@terreno/comms/adapters/twilioSms` | ❌ | — | No | server |
+| `TWILIO_FROM_NUMBER` | `@terreno/comms/adapters/twilioSms` | ❌ | — | No | server |
+| `TWILIO_VERIFY_SERVICE_SID` | `@terreno/comms/adapters/twilioVerify` | ❌ | — | No | server |
+| `EXPO_ACCESS_TOKEN` | `@terreno/comms/adapters/expoPush` | ❌ | — | Yes | server |
+| `PUBLIC_API_URL` | `@terreno/comms` Twilio webhooks | ❌ | — | No | server |
+| `COMMS_WEBHOOK_PUBLIC_URL` | `@terreno/comms` Twilio webhooks | ❌ | — | No | server |
 
 Set `COMMS_ENABLED=false` to omit the example backend's communications plugin and routes.
 When `SENDGRID_API_KEY` is set, the example backend registers `SendGridMailProvider`
 (optional peer `@sendgrid/mail`). Without a key, non-production environments keep the
 console mail provider; production leaves mail unconfigured until a provider is wired.
 `SENDGRID_SANDBOX_MODE=true` forces SendGrid sandbox mode for non-test runtimes.
+`SENDGRID_WEBHOOK_VERIFICATION_KEY` (or constructor `webhookVerificationKey`) is the
+SendGrid Event Webhook ECDSA public key. Missing it skips `POST /comms/webhooks/sendgrid`.
+`PUBLIC_API_URL` or `COMMS_WEBHOOK_PUBLIC_URL` is the public HTTPS origin used to sign
+Twilio callbacks (no trailing slash). Missing it skips Twilio webhook routes.
 Sender identity must be verified in SendGrid before real delivery works.
+When `TWILIO_ACCOUNT_SID` and `TWILIO_AUTH_TOKEN` are set with
+`TWILIO_MESSAGING_SERVICE_SID` or `TWILIO_FROM_NUMBER`, the example backend registers
+`TwilioSmsProvider` (optional peer `twilio`). A sender var without those credentials
+throws at startup. Shared account credentials without a sender do not enable SMS — they
+can still enable Verify when `TWILIO_VERIFY_SERVICE_SID` is set. Without an SMS sender,
+non-production keeps the console SMS provider; production omits SMS until a sender is wired.
+When `TWILIO_VERIFY_SERVICE_SID` is set with `TWILIO_ACCOUNT_SID` and `TWILIO_AUTH_TOKEN`,
+the example backend registers `TwilioVerifyProvider`. A verify service SID without those
+credentials throws at startup. Without `TWILIO_VERIFY_SERVICE_SID`, non-production keeps
+the console verification provider; production omits verification until a provider is wired.
+`EXPO_ACCESS_TOKEN` is optional; the example backend always registers
+`ExpoPushProvider` when comms is enabled, with a statically imported `Expo`
+client so the compiled Cloud Run binary includes `expo-server-sdk`. Without a
+token, Expo still accepts sends at a lower rate limit. The example backend also
+depends on `twilio` and injects a statically imported client into
+`TwilioSmsProvider` / `TwilioVerifyProvider` when those env vars are complete,
+so the compiled binary includes the SDK. Non-production also mounts `POST /comms/dev/testPush`
+for authenticated test sends.
 
 ## Observability
 
@@ -164,8 +195,10 @@ Sender identity must be verified in SendGrid before real delivery works.
 
 | Variable | Read by | Required | Default | Secret | Scope |
 |----------|---------|----------|---------|--------|-------|
-| `VALKEY_URL` | `@terreno/api` | ❌ | — | Yes | server |
-| `REDIS_URL` | various | ❌ | — | Yes | server |
+| `VALKEY_URL` | `@terreno/api` realtime adapter **and** `rateLimit.store: "redis"` | ❌ | — | Yes | server |
+| `REDIS_URL` | `@terreno/api` fallback after `VALKEY_URL` (realtime + Redis rate-limit store) | ❌ | — | Yes | server |
+
+There is **no** `RATE_LIMIT_ENABLED` (or similar) read by `@terreno/api`. Apps that want an env toggle pass `rateLimit: process.env.RATE_LIMIT_ENABLED === "true" ? {store: "memory"} : undefined` themselves. See [Rate limiting](../how-to/rate-limiting.md).
 
 ## Webhooks & notifications
 
@@ -177,7 +210,12 @@ Sender identity must be verified in SendGrid before real delivery works.
 | `GOOGLE_CHAT_WEBHOOK_URL` | scripts | ❌ | — | Yes | server |
 | `ZOOM_CHAT_WEBHOOKS` | `@terreno/api` | ❌ | — | Yes | server |
 | `ZOOM_WEBHOOK_URL` | scripts | ❌ | — | Yes | server |
-| `WEBHOOK_SECRET` | webhooks | ❌ | — | Yes | server |
+| `WEBHOOK_SECRET` | example-backend HMAC demo | ❌ | — | Yes | server |
+
+`WEBHOOK_SECRET` is read only by the example HMAC route (`POST /webhooks/example`).
+`@terreno/api` `WebhooksApp` does not read it. Twilio/SendGrid inbound paths use adapter
+secrets and `PUBLIC_API_URL` / `COMMS_WEBHOOK_PUBLIC_URL` as above. See
+[Receive inbound webhooks](../how-to/inbound-webhooks.md).
 
 ## Admin SPA
 
@@ -203,7 +241,7 @@ Sender identity must be verified in SendGrid before real delivery works.
 
 | Variable | Read by | Required | Default | Secret | Scope |
 |----------|---------|----------|---------|--------|-------|
-| `FLOURISH_SERVICE` | OpenTelemetry | ❌ | `flourish-backend` | No | server |
+| `OTEL_SERVICE_NAME` | OpenTelemetry (example-backend) | ❌ | `example-backend` | No | server |
 | `PR_NUMBER` | PR preview deploy | ❌ | — | No | server |
 | `PR_SERVICE_URL` | PR preview deploy | ❌ | — | No | server |
 | `DEFAULT_PAGE_SIZE` | Configuration model | ❌ | `20` | No | server |
@@ -239,3 +277,4 @@ Sender identity must be verified in SendGrid before real delivery works.
 - [Deployment baseline](../explanation/deployment-baseline.md)
 - [Build for web](../how-to/build-for-web.md)
 - [Configure Better Auth](../how-to/configure-better-auth.md)
+- [Rate limiting](../how-to/rate-limiting.md)

package/dist/docs/versioned/next/reference/legacy/rtk.md

@@ -122,6 +122,8 @@ export const store = configureStore({
 
 ## WebSocket Integration
 
+> **Deprecated (removed in Terreno 58):** `realtimeList`, `realtimeDocument`, `setRealtimeSocket`, and `getRealtimeSocket` patch RTK Query caches from `sync` events. Use [`@terreno/syncdb`](../syncdb.md). `useSocketConnection` remains for feature flags and other sockets.
+
 ### useSocketConnection
 
 React hook for managing Socket.io connections with automatic reconnection, token refresh, and user feedback.

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

@@ -1,17 +1,28 @@
 # Lifecycle plugin reference
 
-Plugin: `terreno-planning` (`2.1.0`)
+Plugin: `terreno-planning` (`2.8.0`)
 
-All five skills are explicitly invoked (`disable-model-invocation: true`) and implement
-one bounded transition.
+Planning skills are model-invocable: agents may select them from descriptions, not only
+from slash commands. Grow, Brew, and Taste each implement one bounded transition. Pick continues an inner loop until the
+approved task list is done. Roast proves the current task and returns.
+`terreno-pick-roast-loop`, `terreno-planning-loop`, and `terreno-taste-sweep` are outer
+loops that invoke those stages; they are not stages and must not appear as `stage` values.
 
 | Skill | Preconditions | Primary output | PASS next |
 | --- | --- | --- | --- |
-| `terreno-1-grow` | request/spec + repository | approved IP/tasks + criterion/verification map | Pick |
-| `terreno-2-pick` | approved task + branch/state | implemented slice + tests/internal reviews | Roast |
-| `terreno-3-roast` | Pick result + current diff | independent requirement/evidence verdict | Brew |
-| `terreno-4-brew` | Roast PASS + branch/evidence | pushed head + PR + attached evidence | Taste |
-| `terreno-5-taste` | PR + current state | one current-head reaction result | null or fresh Taste |
+| `terreno-1-grow` | request/spec + repository | approved IP/tasks + criterion/verification map | Pick (enters inner loop) |
+| `terreno-2-pick` | approved task + branch/state | one implemented slice, then Roast, then the next task | Roast, or Brew when the list is done |
+| `terreno-3-roast` | Pick result + current diff | independent requirement/evidence verdict for the current task | emit Pick if tasks remain, else Brew; never invoke Pick; pass a task-scoped briefing; do not spawn two unconstrained reviewers |
+| `terreno-4-brew` | Roast PASS for every in-scope task + branch/evidence | pushed head + PR + product-CI trigger check + review-bot wait + attached evidence | Taste |
+| `terreno-5-taste` | PR + current state | one current-head reaction; before push: pull latest `master`, lint and typecheck in a no-context subagent, then watch CI | null or fresh Taste |
+
+Outer loops (not stages):
+
+| Skill | What it walks | Default |
+| --- | --- | --- |
+| `terreno-pick-roast-loop` | Approved task list through Pick/Roast recovery | Continue every actionable engineering retry; report once when all tasks pass or a genuine human gate is reached. |
+| `terreno-planning-loop` | Approved task list | Grow once, then Pick once (inner pick-roast loop). Pass `phases=` to restrict (`grow`, `pick`, `roast`, `brew`, `taste`). |
+| `terreno-taste-sweep` | Author's open broken PRs | Isolate each conflicting or failing (any discovered CI host) non-draft PR and reinvoke Taste until mergeable or blocked. |
 
 Every stage includes:
 
@@ -29,8 +40,33 @@ Results use `PASS`, `FAIL`, `BLOCKED`, or `PENDING` and the compact `v: 2` schem
 [`execution-state.schema.json`](https://github.com/FlourishHealth/terreno/blob/master/plugins/terreno-planning/references/execution-state.schema.json).
 Chat and PRs show `status` / `next` / `action`; the YAML lives in a Details toggle.
 
-The outer loop owns state persistence, waiting, stage invocation, retries, and escalation.
-Brew exits after PR setup. Taste observes/acts once and exits.
+The outer loop owns state persistence, Taste `PENDING` reinvocation, Grow/Brew/Taste
+invocation, retries, and escalation. Pick owns the
+[pick-roast inner loop](https://github.com/FlourishHealth/terreno/blob/master/plugins/terreno-planning/references/pick-roast-loop.md):
+one task, roast it, next task. Roast never invokes Pick. Do not start the next task
+until Roast PASS. Exactly one driver continues after each Roast. Brew and Taste wait
+until async review bots (Bugbot, CodeQL, and similar) on the current head have reported,
+preferring provider CLI watch hooks or harness event subscriptions over sleep polling.
+Taste then waits in a loop for product CI using GitHub CLI (`gh pr checks --watch`,
+`gh run watch`) or CircleCI CLI (`circleci run watch`) until jobs are terminal or the
+wait times out. Before any push, Taste always pulls latest `master`, then spawns a
+fresh subagent with no parent conversation to run lint, typecheck, and the locally
+affected tests in each affected package, then pushes and watches product CI.
+Taste observes product CI on every discovered host (GitHub Actions, CircleCI,
+Buildkite, and similar), not only GitHub checks. A documented not-applicable host
+counts as skipped; an unexplained untriggered host prevents Brew `PASS`. Brew still
+does not execute Taste.
+
+The focused Pick–Roast outer loop does not run Grow, Brew, Taste, or product CI. It
+resumes only `pick` or `roast` from durable `next.stage`; a stored `brew` finishes the
+loop without launching Brew, and `taste` or `grow` is `FAIL`. It keeps a
+schema-defined execution-state `ledger` entry for every Pick/Roast task attempt,
+including head/status/evidence and optional retry hypothesis, files, checks, artifacts,
+docs, and risks, then presents that report once. It asks the human only
+for an actual product/architecture/security/data/destructive/policy decision or
+unreplaceable credential. Before asking, it gives the overall goal/state, completed
+work, decisive evidence, two to four options with impact, and a recommendation; the
+message ends with one exact question.
 
 GitHub communication follows a fixed attention budget: `Why`, `What changed`, and
 `Verification` are the only visible PR sections; optional detail is expandable; comments
@@ -39,17 +75,53 @@ are reserved for blocked decisions or non-obvious review resolutions.
 Every stage follows the
 [documentation contract](https://github.com/FlourishHealth/terreno/blob/master/plugins/terreno-planning/references/documentation-contract.md):
 read architecture docs before acting, update them in the same slice, and fail the slice
-when user-visible or architectural behavior ships without matching docs.
+when user-visible or architectural behavior ships without matching docs. Brew and Taste
+observe product CI per
+[product-ci.md](https://github.com/FlourishHealth/terreno/blob/master/plugins/terreno-planning/references/product-ci.md).
 
-Install the published skill set (lifecycle stages plus repo and package skills):
+Install the published skill set directly:
 
 ```bash
 npx skills add FlourishHealth/terreno
 ```
 
-Regenerate the committed `skills/` tree with `bun run skills:sync`. Package skills under
-`<package>/.ai/skills/` overlay the repo copies.
+Or install the combined lifecycle and Terreno app plugin:
+
+| Host | Plugin | Stage names | Invoke Pick–Roast loop |
+| --- | --- | --- | --- |
+| Cursor | `terreno-planning` | `terreno-1-grow` … `terreno-5-taste`, outer loops | `/terreno-pick-roast-loop` |
+| Codex | `terreno-planning` | `terreno-1-grow` … `terreno-5-taste`, outer loops | `$terreno-pick-roast-loop` |
+| Claude Code | `terreno` | `1-grow` … `5-taste`, outer loops | `/terreno:pick-roast-loop` |
+| `npx skills` | — | Canonical stage and outer-loop names | `/terreno-pick-roast-loop` |
+
+Cursor installs `terreno-planning` from [`.cursor-plugin/marketplace.json`](https://github.com/FlourishHealth/terreno/blob/master/.cursor-plugin/marketplace.json). Codex:
+
+```text
+codex plugin marketplace add FlourishHealth/terreno
+codex plugin install terreno-planning --source terreno-plugins
+```
+
+Codex reads [`.agents/plugins/marketplace.json`](https://github.com/FlourishHealth/terreno/blob/master/.agents/plugins/marketplace.json)
+and `.codex-plugin/plugin.json` on the canonical plugin. Claude Code:
+
+```text
+/plugin marketplace add FlourishHealth/terreno
+/plugin install terreno@terreno-plugins
+```
+
+Claude Code resolves a plugin skill's command from the frontmatter `name`, so the short
+names ship as a generated Claude-only copy at
+[`plugins/terreno-claude/`](https://github.com/FlourishHealth/terreno/tree/master/plugins/terreno-claude).
+Stage procedure, Terreno app skills, contracts, agents, and references are generated
+from the canonical `plugins/terreno-planning/` tree.
 
-Exact commands and domain conventions are supplied by repository-local skills discovered
-at stage start; they are not bundled into the lifecycle plugin.
+Regenerate the committed `skills/` tree and the Claude plugin with `bun run skills:sync`.
+Plugin skills are authoritative when names overlap. Package skills under
+`<package>/.ai/skills/` remain package/MCP inputs and do not overlay the installable
+tree.
 
+The plugin bundles reusable backend/API, UI, data-fetching, schema, SDK, admin, prompt,
+docs, upgrade, deployment, and UI-verification workflows, plus `pre-commit` and
+`ui-verifier` agents on Cursor and Claude Code. Codex consumes the combined skills
+without plugin-defined agents. Repository-local skills supply only project-specific
+roadmap, release, and maintenance conventions discovered at stage start.

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

@@ -3,7 +3,7 @@
 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)
+- **`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).
 
 It provides AI coding assistants with documentation access, code generation tools, and workflow prompts.
 
@@ -120,9 +120,12 @@ BM25-style keyword search over markdown bundled with the MCP server: `docs/resou
   queries: string[];       // Required — one or more search phrases
   packages?: string[];     // Optional — filter by package id or scope, e.g. ["api", "@terreno/ui"]
   tokenLimit?: number;      // Approximate max tokens of markdown (default 3000)
+  version?: string;         // Optional @terreno/* lockstep version (e.g. 57.2.0). Omit for current `next` docs.
 }
 ``````
 
+Unmatched versions fall back to the nearest retained snapshot (`website/versioned_docs/`, copied into `docs/versioned/` at MCP build). The response names the resolved version and includes a note when a fallback happened. Pass the consumer app's `@terreno/*` version from `application_info` or `package.json`. Range prefixes such as `^57.2.0` are stripped before matching.
+
 ### terreno_get_component_docs
 
 Returns the full props table for a single `@terreno/ui` component from `ui-types-documentation.json`, plus short related markdown excerpts when the search index finds matches.
@@ -132,6 +135,22 @@ Returns the full props table for a single `@terreno/ui` component from `ui-types
 ``````typescript
 {
   component: string;        // e.g. "Button", "TextField"
+  version?: string;         // Optional @terreno/* lockstep version. Omit for current TypeDoc props.
+}
+``````
+
+When `version` matches a retained docs snapshot, the tool returns that version's generated component page (MDX chrome stripped). Snapshot filenames may be hyphenated (`text-field.mdx`) or concatenated (`userinactivity.mdx`); lookup tries both. Otherwise it uses current `ui-types-documentation.json` and notes the fallback.
+
+### terreno_get_upgrade_guide
+
+Return bundled Terreno lockstep upgrade notes between two semver versions (markdown). Use before major bumps to `@terreno/*` packages. The response always lists which versions in the range **have** notes. If some or all versions have none, it names those gaps — an empty concatenation would look like “nothing changed,” which is usually false. `fromVersion` must be less than or equal to `toVersion`. Note format: `mcp-server/src/docs/upgrades/README.md`.
+
+**Parameters:**
+
+``````typescript
+{
+  fromVersion: string;      // Installed @terreno/* semver (e.g. 0.19.0)
+  toVersion: string;        // Target semver to upgrade to (e.g. 0.20.0)
 }
 ``````
 
@@ -333,12 +352,36 @@ Scaffold a new full-stack Terreno application (Expo frontend, Express/Mongoose b
   appName: string;           // kebab-case (e.g., "my-app")
   appDisplayName: string;    // Human-readable name
   description?: string;
-  mcpServerUrl?: string;     // Default: https://mcp.terreno.flourish.health
+  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).
@@ -380,6 +423,12 @@ Workflow prompt for scaffolding a new Terreno app. Delegates to `terreno_bootstr
 - `appName` (string) — Application name in kebab-case
 - `appDisplayName` (string) — Human-readable display name
 
+### terreno_upgrade
+
+Lockstep Terreno upgrade workflow: read bundled upgrade notes, bump `@terreno/*` packages, run tests, and delegate Expo SDK steps to the official upgrading-expo skill.
+
+**Arguments:** `targetVersion` (optional) — target `@terreno/*` semver; omit to mean latest stable.
+
 ### terreno_create_crud_feature
 
 Generate complete CRUD feature: backend model + routes + frontend screens.

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

@@ -125,15 +125,20 @@ 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()` 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

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

@@ -106,3 +106,25 @@ 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` to enforce the package-wide thresholds
+declared in `bunfig.toml`.
+
+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. 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.
+
+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,255 @@
+# 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, and related
+  exports) now cross lazy root boundaries so their implementation files stay off the cold root import path.
+- `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.