@terreno/mcp 57.19.2 → 57.21.0

package/dist/docs/versioned/57.20.0/explanation/schema-metadata.md

@@ -0,0 +1,65 @@
+# Schema metadata (`describeModel`)
+
+Terreno walks each Mongoose schema **once** and builds a `ModelDescription` field graph. OpenAPI, admin config, and MCP tools are **views** of that graph — they do not re-walk `schema.paths` independently.
+
+## Why one descriptor
+
+Before `describeModel`, three surfaces each interpreted Mongoose differently:
+
+- **OpenAPI** — `mongoose-to-swagger` in `getOpenApiSpecForModel`
+- **Admin** — OpenAPI property walk plus Mongoose ref patching in `extractFieldMeta`
+- **MCP** — `schema.paths` + `SchemaType.instance` switch in `schemaGenerator`
+
+That drifted on refs, enums, nested arrays, and system fields. A single descriptor keeps field facts in one place.
+
+## Core API
+
+```typescript
+import {describeModel, describeModelForRouter} from "@terreno/api";
+
+const description = describeModel(Todo);
+// description.fields[path].kind, .required, .description, .enum, .ref, .isArray, .item, .system
+
+const routerDescription = describeModelForRouter(Todo, {
+  validation: {excludeFromCreate: ["ownerId"]},
+  fieldView: {read: "*", write: ["title", "completed"]},
+});
+// adds writableOnCreate / writableOnUpdate per field
+```
+
+## Field kinds
+
+| Kind | Mongoose source | Notes |
+|------|-----------------|-------|
+| `string` | String | Includes enum strings |
+| `number` | Number | |
+| `boolean` | Boolean | |
+| `date` | Date | ISO date-time in OpenAPI |
+| `dateOnly` | DateOnly | Custom Terreno type |
+| `objectId` | ObjectId | Carries `ref` model name |
+| `embedded` | Subdocument / array of subdocuments | Nested `fields` |
+| `mixed` | Mixed | Accepts any value in OpenAPI |
+| `map` | Map | `item` follows Map `of` (omitted `of` is `mixed`); OpenAPI `additionalProperties` |
+
+System paths (`_id`, `__v`, `created`, `updated`, `deleted`) are marked with `system: true`.
+
+`required` is true only when the field is required on every document. A conditional
+`required` (a function, such as "required when `provisional` is true") leaves it false, so
+OpenAPI and generated SDKs type the field as optional; Mongoose still enforces the condition
+on save.
+
+## Views (not canonical)
+
+| Surface | Function | Notes |
+|---------|----------|-------|
+| OpenAPI | `modelDescriptionToOpenApiSpec` | Used by `getOpenApiSpecForModel`; populate still merges referenced models |
+| Admin `/admin/config` | `modelDescriptionToAdminFields` | Widget choice stays in admin-backend |
+| MCP Zod | `fieldDescriptionToZodType` | Create/update tools omit system fields |
+
+Populate paths remain a `getOpenApiSpecForModel` concern; the descriptor records `ref` on the local path only.
+
+## Related
+
+- [API reference — describeModel](../reference/api.md#describemodel)
+- [How to create a model](../how-to/create-a-model.md)
+- [Admin backend reference](../reference/admin-backend.md)

package/dist/docs/versioned/57.20.0/explanation/source-rules.md

@@ -0,0 +1,57 @@
+# Production source rules
+
+Terreno production TypeScript follows six mechanical conventions. This page is the
+policy those conventions implement. CI fails a PR that introduces a new production
+file (or a new hit in an existing file) that would trip them.
+
+## Scope
+
+`{api,ui,rtk,ai,admin-backend,admin-frontend,example-backend}/src/**/*.{ts,tsx}`
+
+`example-frontend` and `demo` are listed in the original align glob but have no `src/`
+tree (`app/`, `components/`, `stories/` instead), so this scanner does not cover them.
+
+Skipped: tests (`*.test.*`, `*.spec.*`, `*.isolated.*`, `__tests__`), generated SDKs
+(`openApiSdk.ts`, `*OpenApiSdk.ts`), declaration files (`*.d.ts`), `node_modules`, `dist`,
+and test harness files such as `bunSetup.ts`.
+
+## Rules
+
+| Rule | Ban | Use instead |
+| --- | --- | --- |
+| Arrow functions | `function` declarations | `const name = (…) => {…}` |
+| Luxon | `new Date(`, `Date.now()` | `DateTime` from `luxon` |
+| API errors (backend) | `throw new Error(` | `throw new APIError({…})` |
+| Logging | `console.log(` | Backend `logger.*`; frontend `console.info` / `warn` / `error` |
+| Mongoose reads (backend) | `Model.findOne(` | `findExactlyOne`, `findOneOrNone`, `findOneOrNoneFor` |
+| Explicit any | `as any` | Precise types, or `as unknown as T` |
+
+## Allowed leftovers
+
+These still match a naive grep and are **not** violations:
+
+- Mongoose hooks, statics, methods, and virtuals that need `this` (`schema.pre`, `.post`, `.method`, `.statics`, `.virtual`). A nearby hook does not whitelist a later `function` in the same file.
+- TypeScript overload signatures plus their implementation (`modelRouter`)
+- `React.forwardRef(function …)` and `*.prototype.* = function` patches that close over `this`
+- Raw Mongo `collection.findOne`
+- `as any` with a line-level `biome-ignore lint/suspicious/noExplicitAny`
+- Hits inside comments or string literals
+
+## Commands
+
+```bash
+bun run check:source-rules
+bun test scripts/check-source-rules/
+```
+
+## Enforcement
+
+| Layer | What it does |
+| --- | --- |
+| **`bun run check:source-rules`** | Scans scoped production sources and fails on any remaining hit |
+| **Repository policies CI** | CircleCI job `repo-policies` (includes `check:source-rules`) |
+| **`bun run check`** | Local aggregate that includes this scanner |
+
+A **new** production file that uses `export function`, `Date.now()`, `throw new Error`, `console.log`, `Model.findOne`, or unsuppressed `as any` fails CI.
+
+Do not add suppress comments for these rules. Fix the code, or use one of the allowed leftovers above.

package/dist/docs/versioned/57.20.0/explanation/static-analysis.md

@@ -0,0 +1,136 @@
+# Static analysis
+
+Run `bun run analyze:full` before pushing changes that alter imports, exports, package
+dependencies, or module boundaries.
+
+Taste does not need to infer that policy in this repository. The root `prepush` package
+script is the canonical local gate. It runs lint and TypeScript compilation, then the
+local mirror of every CI job the branch triggers, including full static analysis when
+repo policies apply (see [Run tests locally](../how-to/run-tests-locally.md#prepush-mirrors-ci)):
+
+```bash
+bun run prepush
+```
+
+The reusable Taste stage checks for a root `prepush` script before every push and runs it
+in a fresh, no-context subagent. Repositories without one retain Taste's fallback:
+package-level lint, typecheck, and locally affected tests.
+
+Terreno uses two analysis speeds so agents receive quick edit feedback without replacing
+repository-wide correctness checks with a partial changed-file scan.
+
+## Analysis layers
+
+| Layer | Command | Scope | Enforcement |
+| --- | --- | --- | --- |
+| Biome | `bun run analyze:fast` | Changed and untracked analyzable files | Agent post-edit hooks |
+| Biome | `bun run analyze:staged` | Staged analyzable files | Git pre-commit |
+| Knip | `bun run check:knip` | Both development and production module graphs | Dedicated GitHub workflow |
+| Knip | `bun run analyze:full` | Both development and production module graphs | Agent stop hooks and CircleCI |
+| dependency-cruiser | `bun run analyze:full` | Workspace source dependency graph | Agent stop hooks and CI |
+
+Biome runs from the nearest workspace configuration. Knip finds unused files, exports,
+types, dependencies, binaries, and duplicate exports. dependency-cruiser rejects new
+cycles and production imports from test or isolated modules while reporting orphan
+modules.
+
+Knip ignores `**/dist/**` so analysis reports the same findings whether or not the
+workspace has been compiled. CI analyzes a fresh checkout and never builds, while local
+development runs `bun run bootstrap`; without that exclusion, each package's compiled
+`dist/*.d.ts` entry point contributes unlisted-dependency findings that CI can never
+reproduce.
+
+## Entry graph
+
+Knip only follows files reachable from entries. Register executed-but-unimported files
+in `knip.jsonc` `workspaces.<name>.entry` instead of deleting them or stuffing them into
+the JSON baseline.
+
+Setting `entry` **replaces** Knip’s default `{index,cli,main}` / `src/{index,cli,main}`
+patterns for that workspace, so those defaults must be repeated next to extra globs.
+
+| Kind | Why Knip misses it | Entry |
+| --- | --- | --- |
+| `*.isolated.ts(x)` | Run as `bun test $file`, not `*.test.ts` | `src/isolated/**/*.isolated.{ts,tsx}` on the owning package |
+| `scripts/**/*.test.ts`, `.github/scripts/**/*.test.ts` | Root `test` is `bun run --filter '*' test:ci`, so the Bun plugin never loads them | Root workspace `"."` |
+| `example-frontend/e2e/**/*.ts` | Playwright helpers and setup files are executed through project configuration, not app imports | `example-frontend` entry glob |
+| Generated SDK contracts not yet imported by a screen | Codegen output is retained for compatibility verification | `ignoreFiles` for only the unused-file issue; exports and dependencies remain analyzed |
+| OpenAPI codegen configs, Metro `jspdf` stubs, Expo fingerprint configs, Playwright CI config, `ui/babel.config.js`, Docusaurus `src/theme/**` swizzles, `scripts/ci/prepare-package-publish.mjs` | Invoked by Expo/Metro/Docusaurus/CI, not imported from app `index` | Extra `entry` globs on the owning workspace |
+| Generated `expo-cicd-workflows/scripts/*.js` (including `.rulesync/`) | Skill copies; they import `ajv` / `js-yaml` outside this repo’s package graph | `ignore` globs |
+| `example-backend` production dependencies | Knip's package-script entry for `bun run src/index.ts` shadows the explicit `src/index.ts!` entry in production mode | Keep default-mode enforcement; use exact dependency names suffixed with `!` as production-only exceptions |
+| `mcp-server/src/__tests__/preload.ts` | `bunfig.toml` `test.preload`; Knip's Bun plugin is disabled for this workspace | `mcp-server` extra entry |
+
+## Runtime-only dependencies
+
+Do not remove an Expo, React Native, or Metro dependency solely because Knip cannot find
+a static import. Expo autolinking, `app.json` plugin strings, Metro aliases/polyfills,
+platform-specific modules, and published UI peer surfaces load dependencies outside
+Knip's source graph. Keep those dependencies in the owning `package.json` and list them
+under that workspace's `ignoreDependencies` in `knip.jsonc`, with a comment naming the
+runtime loader.
+
+The same rule covers externally installed CLIs (`maestro`, `eas`), catalog pins retained
+for native fingerprint compatibility, and optional peers consumed by published-package
+users. Declare those narrowly with `ignoreBinaries` or `ignoreDependencies`; do not add a
+fake local import.
+
+## Exports and test seams
+
+Remove `export` from unused module internals. Keep published package-entry exports for
+compatibility even when this monorepo has no consumer; suppress only their `exports` or
+`types` issue on the defining file, with a public-API comment in `knip.jsonc`.
+
+Some internal helpers are intentionally exported so tests can exercise deterministic
+logic without widening the npm entry point. Mark those declarations `@internal`: default
+Knip still proves that tests use them, while production mode excludes the test-only seam.
+Generated SDK files use a path-scoped `ignoreIssues` entry instead of hand edits.
+
+## Zero-finding policy
+
+Knip has no baseline. `bun run check:knip` runs the default and production graphs and
+fails on every finding. The dedicated `Knip / Zero findings` GitHub workflow runs this
+command for every pull request and every push to `master`.
+
+Fix every Knip finding or add the narrowest justified exception to `knip.jsonc` with a
+comment naming the runtime loader, public compatibility promise, generated source, or
+tool limitation. Do not create a Knip baseline or any other separate finding inventory.
+
+dependency-cruiser still uses `.dependency-cruiser-known-violations.json` to ratchet its
+remaining findings. After intentionally accepting repository-wide dependency-graph
+changes, regenerate only that baseline:
+
+```bash
+bun run analyze:dependency-baseline
+bun run analyze:full
+```
+
+Review the dependency-cruiser baseline diff before committing; findings may only stay
+level or decrease. Never run `knip --fix` unattended because an incomplete entry graph
+can remove runtime-loaded code.
+
+## Agent hooks
+
+`.rulesync/hooks.json` is the hook source of truth. `bun run rules` translates it into
+native configuration for Cursor, Claude Code, Codex CLI, GitHub Copilot, Copilot CLI,
+Google Antigravity CLI, and Devin.
+
+Post-edit events run the changed-file Biome command. Stop events run both repository-wide
+ratchets. `analyze:full` retries Knip without `--cache` when a concurrent stop-hook and
+prepush run corrupt or lock the cache, so the stop hook does not fail with empty JSON.
+Hook failure and retry behavior differs by host, so CircleCI remains the merge
+gate and the real Git pre-commit hook covers commits made outside an agent.
+
+`simple-git-hooks` installs the pre-commit hook during `bun install` through the root
+`prepare` script.
+
+## Configuration ownership
+
+| File | Purpose |
+| --- | --- |
+| `knip.jsonc` | Entry graph, plugins, generated-code exceptions |
+| `.dependency-cruiser.js` | Dependency rules and resolver conditions |
+| `.rulesync/hooks.json` | Canonical agent lifecycle hooks |
+| `scripts/static-analysis/` | Portable direct Knip checks, dependency ratchet logic, and tests |
+
+Generated agent hook files must not be edited directly. Change `.rulesync/hooks.json`,
+then run `bun run rules`.

package/dist/docs/versioned/57.20.0/explanation/test-isolation.md

@@ -0,0 +1,42 @@
+# Test isolation in Bun suites
+
+`bun test` runs every test file of a package in one process. `mock.module` replaces a
+module for that whole process, and `mock.restore()` does not undo it. A test that
+mocks a module can pass on its own, then break other files, or be broken by them,
+when the whole package runs. CI always runs the whole package, so this kind of
+failure shows up only after a push.
+
+## The rule
+
+A branch may not add a `mock.module` call to a shared suite, meaning any `*.test.*` or
+`*.spec.*` file outside an `isolated/` directory. Existing calls are grandfathered. The
+check only counts lines the branch adds.
+
+```bash
+bun run check:test-isolation            # vs merge-base with origin/master
+```
+
+`bun run prepush` and the CircleCI `repo-policies` job both run it.
+
+## Fixes, in order of preference
+
+1. **Inject the dependency.** Pass a fake through props, options, or a parameter
+   instead of replacing the module.
+2. **Isolate the file.** Move the test to `src/isolated/<name>.isolated.ts(x)`. Packages
+   whose `test:coverage` uses `scripts/check-coverage.ts` run each isolated file in its
+   own `bun test` process and merge the coverage.
+3. **Mock once in the preload.** Register the mock in the package's bun preload (for
+   example `src/tests/bunSetup.ts`) so every file sees the same module.
+4. **Mark an identical mock.** When the call matches the preload exactly, put
+   `// isolation-safe: <reason>` on the line above it.
+
+## Why a ratchet
+
+Terreno has about 80 existing shared-suite files that call `mock.module`. Most mock
+native modules the same way everywhere, which is harmless. Blocking new calls stops
+the problem from growing without forcing a migration of working tests. Both
+"passes alone, fails in the suite" fixes on the AI observability branch (#1196) came
+from new module mocks.
+
+Roast also runs the package's full CI test command, not only the changed test file,
+so any remaining order-dependent failure shows up before push.

package/dist/docs/versioned/57.20.0/explanation/typescript-configuration.md

@@ -0,0 +1,46 @@
+# TypeScript configuration
+
+Copy the `tsconfig.json` of the closest profile below when you add a package. Every config
+builds on TypeScript 6 with no `ignoreDeprecations`, so `tsc` fails fast on any option that
+TypeScript 7 removes.
+
+## Profiles
+
+| Profile | Packages | `module` | `target` | Emits |
+| --- | --- | --- | --- | --- |
+| Node library | `api`, `ai`, `admin-backend`, `announcements`, `api-health`, `blocks`, `comms`, `feature-flags`, `jobs`, `test`, `admin-spa` server (`tsconfig.server.json`) | `nodenext` | `es2023` | CommonJS `dist/` |
+| Node ESM tool | `mcp-server`, `create-terreno-app` | `nodenext` | `es2023` | ESM `dist/` (`"type": "module"`) |
+| Frontend library | `ui`, `admin-frontend`, `rtk`, `syncdb` | `esnext` + `moduleResolution: bundler` | `es2022` | ESM `dist/` for Metro |
+| Bun CLI | `cli` | `esnext` + `moduleResolution: bundler` + `customConditions: ["bun"]` | `es2022` | ESM `dist/` for Bun |
+| Expo app | `example-frontend`, `demo`, `admin-spa` | extends `expo/tsconfig.base` | from Expo | nothing (`noEmit`) |
+| Bun app | `example-backend` | `preserve` | `esnext` | nothing (`noEmit`) |
+| Docs site | `website` | extends `@docusaurus/tsconfig` | from Docusaurus | nothing (`noEmit`) |
+
+Each workspace keeps a self-contained config. Packages without a `files` allowlist publish
+their `tsconfig.json`, so an `extends` into a repo-root base would ship a broken path.
+
+## Why these settings
+
+| Setting | Reason |
+| --- | --- |
+| `module: nodenext` for Node packages | Models Node's real resolution, including `exports` conditions. CommonJS output keeps dynamic `import()` as a real ESM import. `module: commonjs` rewrote it to `require()`, which cannot load `file://` URLs or ESM-only code. |
+| `target: es2023` for Node packages | Node 20+ (the Mongoose 9 floor) runs ES2023 natively, so `tsc` emits readable code with no downleveling or helpers. |
+| `target: es2022` for frontend libraries | Metro and Babel transform consumer bundles, and ES2022 class-field semantics match what Babel and Hermes expect. |
+| `isolatedModules` | Bun, Metro, and Babel transpile one file at a time. `tsc` flags code that only works with whole-program compilation. `syncdb` leaves it off because TinyBase's `Persists` is an ambient `const enum` that `tsc` must inline. |
+| No `baseUrl` | Deprecated in TypeScript 6 and removed in 7. `paths` resolve from the tsconfig's own directory, as do Bun, Expo's Metro resolver, and `check:no-barrel-imports`. `website` sets `"baseUrl": null` to clear the value `@docusaurus/tsconfig` still sets. |
+| Explicit `types` | TypeScript 6 defaults `types` to `[]`. List ambient packages (`node`, `bun`) instead of loading every `@types/*` package. |
+| `strict: true` | Already the TypeScript 6 default. It stays explicit because it is the most important check. |
+
+## Do not add
+
+| Option | Why |
+| --- | --- |
+| `ignoreDeprecations` | Hides options that stop working in TypeScript 7. |
+| `baseUrl` | Deprecated. Write `paths` entries relative to the tsconfig (`"./src/*"`). |
+| `moduleResolution: node` / `node10` / `classic` | Deprecated. Use `nodenext` for Node or `bundler` for bundled code. |
+| `target: es5`, `downlevelIteration` | Deprecated. No supported runtime needs ES5 output. |
+| `esModuleInterop`, `allowSyntheticDefaultImports`, `forceConsistentCasingInFileNames` | Already `true` by default in TypeScript 6. Setting them to `false` is deprecated. |
+
+`create-terreno-app` scaffolds follow the Expo app and Bun app profiles. Its
+`tsconfig.codegen.json` pairs `module: commonjs` with `moduleResolution: bundler`, because
+the RTK codegen CLI forces CommonJS when it registers `ts-node`.

package/dist/docs/versioned/57.20.0/explanation/versioning-policy.md

@@ -0,0 +1,35 @@
+# Versioning policy
+
+All published `@terreno/*` packages share one version. Upgrade them together. Mixing versions is unsupported.
+
+## Lockstep
+
+A git tag `X.Y.Z` (no `v` prefix) is the version for every package that `.github/workflows/publish-on-tag.yml` publishes: `api`, `test`, `ui`, `rtk`, `admin-backend`, `admin-frontend`, `admin-spa`, `blocks`, `ai`, `api-health`, `comms`, `feature-flags`, `mcp`, `syncdb`. Publish jobs read that tag; they do not pick per-package versions.
+
+Inside the monorepo, packages depend on each other with `workspace:*` (for example `@terreno/rtk` → `@terreno/ui`). On npm they are released at the same number. `@terreno/ui` also pins Expo-line peers (`react-native` `~0.86.0` on the 57 line). Installing `@terreno/ui@57` next to Expo 54 is outside support, same as mixing `@terreno/api@57` with `@terreno/ui@0.31`.
+
+## Pre-1.0 (and Expo-aligned majors)
+
+While the public API is still moving, a **minor** may include breaking changes. Those land only with an upgrade note in `mcp-server/src/docs/upgrades/<version>.md`. The changelog `### Breaking` / `### Changed` / `### Deprecated` / `### Removed` headings require that file (`bun run check:upgrade-docs`).
+
+From 56 onward the **major** tracks the Expo SDK major (`56.x`, `57.x`). That is not a 1.0 stability promise. It is a peer-stack label.
+
+## Deprecation window
+
+A public API marked deprecated stays available for **at least three minor releases** on the current major (example: deprecated in `57.1.0` → still present in `57.2.0` and `57.3.0`). Removal happens in a later minor or the next major, always with an upgrade note.
+
+Worked example: `@terreno/rtk` collection CRUD was deprecated in `56.0.0` (restated in `57.1.0`). The package still publishes on 57.x for the OpenAPI SDK, Better Auth Redux, feature flags, and sockets. It will not ship in the **next major**. Migrate collection screens with [migrate-rtk-to-syncdb.md](../how-to/migrate-rtk-to-syncdb.md) as a separate operation from a routine version bump.
+
+## Where to read changes
+
+| Source | Use |
+| --- | --- |
+| [`CHANGELOG.md`](../../CHANGELOG.md) | What shipped |
+| [`mcp-server/src/docs/upgrades/`](../../mcp-server/src/docs/upgrades/) | What you must do |
+| MCP `terreno_get_upgrade_guide` | Concatenated notes for `fromVersion` → `toVersion` |
+
+Note format: [`mcp-server/src/docs/upgrades/README.md`](../../mcp-server/src/docs/upgrades/README.md).
+
+## What 1.0 will mean
+
+OSS launch question P9 ([oss-launch-program.md](../implementationPlans/oss-launch-program.md)): 1.0 is an API-stability audit after syncdb has settled — not the Expo-aligned 57 line. Until that audit, treat minors as able to break with a note.

package/dist/docs/versioned/57.20.0/how-to/README.md

@@ -0,0 +1,84 @@
+# How-to Guides
+
+Problem-oriented, practical steps. Use these when you know what you want to do.
+
+## Deployment
+
+- [Deployment baseline](../explanation/deployment-baseline.md) — seven requirements every host must satisfy
+- [Build for web](build-for-web.md) — export static web bundle with correct API URL
+- [Deploy to Google Cloud Platform](deploy-to-gcp.md) — index for GCP guides
+- [Deploy backend to Cloud Run](deploy-backend-to-cloud-run.md) — container + Secret Manager + Cloud Run
+- [Deploy web to GCS + CDN](deploy-web-to-gcs-cdn.md) — static hosting with SPA routing
+- [Deploy to Vercel](deploy-to-vercel.md) — web on Vercel, backend on Cloud Run or Vercel Functions; previews, CORS, CI
+- [Run WebSockets on Vercel Functions](vercel-function-websockets.md) — Socket.IO and syncdb on Vercel's WebSocket beta: transports, reconnects, state
+
+## Contents
+
+- [Create a Terreno app](create-a-terreno-app.md) — Scaffold a full-stack app with `create-terreno-app` (Bun or npm)
+- [Update dependencies](update-dependencies.md) — Daily rolling PR, exercise test, Expo fingerprint freeze
+- [CircleCI](circleci.md) — Dual-run CI on CircleCI (package CI / policy / e2e; deploys later)
+- [Release automation](release-automation.md) — Let agents merge release notes and roadmap updates; publish only merged notes
+- [Set up tests in a Terreno app](set-up-app-tests.md) — Bun backend and frontend tests, Playwright web E2E, Maestro on iOS/Android
+- [Run tests locally](run-tests-locally.md) — Map every CircleCI test job to a Cursor Cloud / laptop command
+- [GitHub Actions CI](github-actions-ci.md) — Cut PR runtime: docs previews, compile-once e2e, pinned Bun
+- [Add feature flags](add-feature-flags.md) — Add feature flags, A/B testing, and OpenFeature migration
+- [Rate limiting](rate-limiting.md) — Opt-in HTTP limiter on `TerrenoApp` (memory or Redis)
+- [Receive inbound webhooks](inbound-webhooks.md) — HMAC, Stripe, Twilio, and SendGrid signatures on `WebhooksApp`
+- [Durable background jobs](background-jobs.md) — `@terreno/jobs`: enqueue, workers, schedules, Cloud Tasks / Vercel Queues
+- [Create a Mongoose model](create-a-model.md) — Define models with proper conventions
+- [Enable the framework audit log](audit-log.md) — `AuditApp`, per-router `audit`, append-only events
+- [Sign consent on a user's behalf](sign-consent-on-behalf.md) — Provisional consent signatures: RBAC grant, signer screen, status checks, void, print
+- [Seed a database](seed-a-database.md) — Idempotent sync, dry runs, and guarded reset-and-reseed
+- [Run MongoDB migrations](run-mongodb-migrations.md) — Versioned `up`/`down` files, `terreno-migrate`, production gate
+- [Add GitHub OAuth authentication](add-github-oauth.md) — Enable GitHub login for your API
+- [Configure Better Auth](configure-better-auth.md) — Set up Better Auth with social OAuth (Google, GitHub, Apple)
+- [Set up social login](set-up-social-login.md) — Register Google, GitHub, and Apple once on the stable deploy, proxy previews through it, and move stable onto one domain
+- [Password reset and email verification](password-reset.md) — JWT routes, comms templates, Better Auth hooks
+- [Recover a locked-out user](recover-locked-out-user.md) — Platform and org-admin recovery: 2FA, passkeys, providers, sessions, suspend
+- [Add WebSocket integration](websocket-integration.md) — Set up real-time Socket.io connections
+- [Expose Model Context Protocol tools](expose-mcp-tools.md) — Turn `modelRouter` models into MCP tools an LLM can call
+- [Set up Terreno MCP](set-up-terreno-mcp.md) — Connect Cursor or Claude Code to the hosted docs/codegen server and the local runtime server
+- [Debug with MCP](debug-with-mcp.md) — Follow a failure from symptom to verified fix with the local MCP tools
+- [Connect an MCP client with a service token](connect-mcp-service-token.md) — Mint a personal `mcp_` key for Perplexity and other remote clients
+- [Enable MCP OAuth for a JWT app](enable-mcp-oauth.md) — Let Claude.ai and ChatGPT connect to `/mcp` through OAuth 2.1 with your own consent screen
+- [Install agent skills](install-agent-skills.md) — `npx skills`, the Cursor plugin, the Codex plugin, or the Claude Code plugin
+- [Develop an AI feature](ai-feature-development.md) — Dataset → prompt → evaluators → experiment → production label → live traces (SOP)
+- [Observe LLM calls](observe-llm-calls.md) — Register ObservabilityApp, primaries, price map, sampleRate
+- [Build a durable workflow](build-a-durable-workflow.md) — Phased harness task with an agent, a human sign-off, and a once-only side effect (`clinic.intakeSummary`)
+- [Run the harness on multiple instances](run-harness-on-multiple-instances.md) — `JobsRunner`: harness phases as `@terreno/jobs` jobs on every instance
+- [Ship a new task version](ship-a-new-task-version.md) — Change a durable harness task without stranding in-flight runs
+- [GitHub issue lifecycle](github-issue-lifecycle.md) — Create pick-ready issues, Pick ⇄ Roast, or unattended `status:ready-for-dev` pickup
+- [Call external APIs](call-external-apis.md) — Authenticated HTTP client, retries, and error normalization for third-party integrations
+- [Upgrade banner](upgrade-banner.md) — Soft warning and hard-block app update UX
+- [Upgrade Terreno](upgrade-terreno.md) — Lockstep `@terreno/*` bumps, note range, order, rollback
+- [Automate Terreno upgrades](automate-terreno-upgrades.md) — Hourly workflow that launches one upgrade agent when a week-old release is out and no upgrade is open
+- [Track upstream Expo](track-upstream-expo.md) — Morning probe for SDK betas; `release-X.Y.Z` loop log + native fingerprint deps
+- [Build a list/detail screen](build-list-detail-screens.md) — `ListDetailLayout` route group: list on a phone, list + detail panes on a tablet, selection in the URL
+- [Show loading skeletons](show-loading-skeletons.md) — `loading`, `loadingComponent`, and `loadingAnimation` on Box, Card, charts, and Page; `withLoading` for custom components
+- [Compose charts in a dashboard grid](charts-and-dashboards.md) — `LineChart` / `BarChart` / `AreaChart` / `DonutChart` inside `Card`s in `DashboardGrid` (ops-dashboard scorecards and spans: [dashboard-chart-parity](../implementationPlans/dashboard-chart-parity.md))
+- [Compare rendered chart snapshots](compare-chart-rendered-snapshots.md) — PNG goldens for the chart visual gallery, not JSON snapshots
+- [Migrate from @terreno/rtk to @terreno/syncdb](migrate-rtk-to-syncdb.md) — Move data sync to the local-first layer
+- [Use syncdb correctly](use-syncdb-correctly.md) — Serial snapshot startup, outbox-halting 403s, phantom creates, conflicts, and other library behavior apps must handle
+- [Generate a REST CLI from OpenAPI](generate-a-rest-cli.md) — Scaffold `terreno generate rest-cli` for an app API
+- [In-app notifications](in-app-notifications.md) — Register `NotificationsApp`, syncdb inbox, and UI bell
+- [Add organizations](add-organizations.md) — Opt into Membership-backed tenancy, RBAC, admin, and seeded examples
+- [Add a GPT chat mascot](add-gpt-chat-mascot.md) — Optional consumer-owned character on empty `GPTChat`
+- [Add agent asks to a chat](agent-ui-asks.md) — Turn on `asks`, show and answer them in `GPTChat`, try the keyless demo agent, and answer asks from an Apple Watch or another small client
+- [Validate a block document locally](agent-ui-blocks.md) — `terreno-blocks validate` for a whole-reply YAML document
+- [Add a stepper callback](agent-ui-blocks.md#add-a-stepper-callback) — `scaleStepperHostAction` or your own `handles: "stepper"` action; checklist ticks, copy buttons, the `richBlocks: false` opt-out, and the `blocks:smoke` model check are on the same page
+- [Give the agent photos](agent-ui-blocks.md#give-the-agent-photos) — Generate a stored photo library once and let the agent cite it with `findPhotos`
+
+## Admin
+
+- [Build admin screens](build-admin-screens.md) — Screens, sidebar nav, `routeBase`, custom screens
+- [Add a model to the admin](admin-add-model.md) — `modelRouter({admin: ...})` setup
+- [Import pre-built admins](admin-import-prebuilt.md) — Plugin `adminContribution()` wiring
+- [Add a custom admin field widget](admin-custom-widget.md) — Custom field widgets
+- [Customize the admin home](admin-custom-home.md) — Home slots and built-in widgets
+
+## Coming Soon
+
+- Add custom permissions
+- Implement file uploads
+- Configure email notifications
+- Customize AI workflows

package/dist/docs/versioned/57.20.0/how-to/add-feature-flags.md

@@ -0,0 +1,140 @@
+# Add Feature Flags
+
+Add feature flags and A/B testing to your Terreno app using `@terreno/feature-flags`.
+
+## Prerequisites
+
+- A working Terreno backend using `TerrenoApp`
+- `@terreno/admin-backend` registered for the admin panel (optional but recommended)
+
+## Steps
+
+### 1. Install the package
+
+```bash
+bun add @terreno/feature-flags
+```
+
+### 2. Register the backend plugin
+
+In your server file, register `FeatureFlagsApp` and add the admin config:
+
+```typescript
+import {TerrenoApp} from "@terreno/api";
+import {AdminApp} from "@terreno/admin-backend";
+import {FeatureFlagsApp, featureFlagAdminConfig} from "@terreno/feature-flags";
+
+// Define segment functions to classify users for targeting rules
+const segments = {
+  "pro-users": (user) => user.plan === "pro",
+  "beta-testers": (user) => user.betaTester === true,
+  "internal-team": (user) => user.email?.endsWith("@mycompany.com"),
+};
+
+new TerrenoApp({userModel: User})
+  .register(new FeatureFlagsApp({segments}))
+  .register(
+    new AdminApp({
+      models: [
+        featureFlagAdminConfig,  // adds Feature Flags to the admin panel
+        // ...your other models
+      ],
+    })
+  )
+  .start();
+```
+
+`featureFlagAdminConfig` is a pre-configured admin model config exported by the package. It sets up the display name, list fields, route path, and model reference so you don't need to configure them manually.
+
+### 3. Regenerate the frontend SDK
+
+After adding the backend routes, regenerate the SDK so the frontend can call the new endpoints (with the example backend running, or set `OPENAPI_URL` to your deployed `openapi.json`):
+
+```bash
+cd your-frontend && bun run sdk
+```
+
+Regeneration may emit a hook for `/feature-flags/flagConfiguration`; prefer **`useTerrenoFeatureFlags`** / **`useFeatureFlags`** from `@terreno/rtk` so OpenFeature domain, cache keying, and optional socket refetch stay consistent.
+
+### 4. Use feature flags in the frontend
+
+**Recommended (OpenFeature):** add `@openfeature/react-sdk` to the app, wrap the tree (or the subtree that reads flags) in `<OpenFeatureProvider domain="feature-flags">`, and call `useTerrenoFeatureFlags(terrenoApi, {userId, socket})` once after auth so the OpenFeature client receives `GET /feature-flags/flagConfiguration`. Then use standard hooks such as `useBooleanFlagValue` / `useStringFlagValue` / `FeatureFlag`.
+
+**Back-compat:** `useFeatureFlags(terrenoApi)` from `@terreno/rtk` still returns `{flags, getFlag, getVariant, isLoading, …}` with the same semantics as before; it uses `/flagConfiguration` under the hood. You do not need to call a generated RTK hook for `/flagConfiguration` directly.
+
+```typescript
+import {useBooleanFlagValue} from "@openfeature/react-sdk";
+import {useTerrenoFeatureFlags, useSelectCurrentUserId} from "@terreno/rtk";
+import {terrenoApi} from "@/store/sdk";
+
+const GatedBanner: React.FC = () => {
+  const userId = useSelectCurrentUserId();
+  useTerrenoFeatureFlags(terrenoApi, {userId, skip: !userId});
+  const showBanner = useBooleanFlagValue("new-ui", false);
+  return showBanner ? <NewUI /> : null;
+};
+```
+
+```typescript
+import {useFeatureFlags} from "@terreno/rtk";
+import {terrenoApi} from "@/store/sdk";
+
+const LegacyStyle: React.FC = () => {
+  const {getFlag, isLoading} = useFeatureFlags(terrenoApi);
+
+  if (isLoading) {
+    return <Spinner />;
+  }
+
+  const showNewUI = getFlag("new-ui");
+
+  return showNewUI ? <NewUI /> : <OldUI />;
+};
+```
+
+### 4b. Live updates (optional)
+
+To push flag changes to open clients without a refresh, pass **`liveUpdates`** when constructing `FeatureFlagsApp` (see `example-backend/src/server.ts`): Mongoose **`FeatureFlag.watch()`** drives a Socket.io broadcast. **MongoDB must run as a replica set** (a single-node replica set is enough); standalone instances cannot use change streams, and the plugin logs a warning if `watch()` fails.
+
+On the client, pass the same Socket.io **client** into `useTerrenoFeatureFlags` / `useFeatureFlags` as `socket`; the hook listens for `featureFlagsChanged` (or `socketEventName`) and refetches `/flagConfiguration`. The event payload is only `{ key: string }` — the same flag keys are already returned to every authenticated user in `/flagConfiguration`, so this is not considered a new exposure.
+
+### 5. Create flags via the admin panel
+
+Navigate to the admin panel in your app. The "Feature Flags" card appears automatically. Create a flag with:
+
+- **Key**: unique identifier, e.g. `new-ui`
+- **Name**: human-readable label
+- **Type**: `boolean` for on/off toggles, `variant` for A/B tests
+- **Enabled**: global kill switch
+- **Rules**: optional targeting (field-based or segment-based)
+- **Rollout Percentage**: gradual rollout for boolean flags (default 100%)
+
+## Migrating from `GET …/evaluate` (OpenFeature)
+
+Terreno's feature-flag stack uses **OpenFeature** (`@terreno/feature-flags` on the server, `@terreno/rtk` on the client). Use this checklist if you upgrade from a Terreno release that only documented `GET …/evaluate`.
+
+### Backend (`@terreno/feature-flags`)
+
+1. Keep **`FeatureFlagsApp`** registered as before; admin CRUD is unchanged.
+2. Prefer authenticated clients calling **`GET {basePath}/flagConfiguration`** — the JSON body matches OpenFeature's static configuration shape (for `TypedInMemoryProvider` on the client).
+3. **`GET {basePath}/evaluate`** still returns the legacy `Record<key, boolean | string | null>` map but is **deprecated** (`Deprecation: true`, `Sunset` header). Migrate direct HTTP or hand-written clients to `/flagConfiguration`, or rely on `@terreno/rtk` hooks below.
+4. **`FeatureFlag`** documents gain optional **`defaultVariant`** (boolean: `"on"` / `"off"`; variant: a key from `variants`). Omitted values are filled on save. For existing databases, run a one-off backfill or reuse the pattern in `example-backend/src/scripts/seed-feature-flags.ts`.
+5. **Live updates (optional):** pass `liveUpdates: { socketIoServer: io | () => io }` to `FeatureFlagsApp`. MongoDB must run as a **replica set** (a single-node replica set is enough) so Mongoose change streams work.
+
+### Frontend (`@terreno/rtk` + OpenFeature)
+
+1. **`useFeatureFlags(terrenoApi, …)`** — no code changes required for the common case; it already uses `/flagConfiguration` and keeps `{ flags, getFlag, getVariant, isLoading, refetch }`.
+2. **OpenFeature React hooks** (`useBooleanFlagValue`, `useStringFlagValue`, `<FeatureFlag>`, …): add **`@openfeature/react-sdk`** and **`@openfeature/web-sdk`** to your app (align versions with `@terreno/rtk` **peerDependencies** and the root **`catalog`**).
+3. Wrap the UI that reads flags in **`<OpenFeatureProvider domain="feature-flags">`** (or the same `domain` you pass into the hook).
+4. After auth, call **`useTerrenoFeatureFlags(terrenoApi, { userId, skip, socket, … })`** once under your Redux `Provider` so OpenFeature is populated before hooks read flag values.
+5. **Regenerate the OpenAPI SDK** after the backend exposes the new route: `cd your-frontend && bun run sdk`. Prefer **`useTerrenoFeatureFlags` / `useFeatureFlags`** over calling a generated `flagConfiguration` hook directly, so domain, cache keys, and optional socket refetch stay consistent.
+
+### Further reading
+
+- [Feature flags reference](../reference/feature-flags.md)
+- [OpenFeature implementation plan](../implementationPlans/feature-flags-openfeature.md)
+
+## Next steps
+
+- See the [reference docs](../reference/feature-flags.md) for the full API, targeting rules, and variant flags
+- See `example-backend/src/server.ts` for a complete working example