@terreno/mcp 57.3.0 → 57.6.0

package/src/docs/versioned/next/explanation/source-rules.md

@@ -49,7 +49,7 @@ bun test scripts/check-source-rules/
 | Layer | What it does |
 | --- | --- |
 | **`bun run check:source-rules`** | Scans scoped production sources and fails on any remaining hit |
-| **Repository policies CI** | GitHub Actions job `Production source rules` (CircleCI twin `source-rules`) |
+| **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.

package/src/docs/versioned/next/explanation/static-analysis.md

@@ -3,6 +3,18 @@
 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 and runs lint, TypeScript compilation, and full static
+analysis:
+
+```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.
 
@@ -12,7 +24,8 @@ repository-wide correctness checks with a partial changed-file scan.
 | --- | --- | --- | --- |
 | 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 analyze:full` | Both development and production module graphs | Agent stop hooks and CI |
+| 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,
@@ -26,28 +39,73 @@ development runs `bun run bootstrap`; without that exclusion, each package's com
 `dist/*.d.ts` entry point contributes unlisted-dependency findings that CI can never
 reproduce.
 
-## Ratchets
+## 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.
 
-The repository already contains findings that cannot be removed in one change. The
-checked-in baselines allow existing findings to remain while rejecting new ones:
+## Zero-finding policy
 
-- `scripts/static-analysis/knip-baseline.json`
-- `.dependency-cruiser-known-violations.json`
+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`.
 
-Knip fingerprints omit line and column positions, so moving an existing declaration does
-not create a false regression. A renamed symbol, moved file, or new finding must be fixed
-or deliberately reviewed into the baseline.
+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.
 
-After intentionally accepting repository-wide analysis changes, regenerate both
-baselines:
+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:baseline
+bun run analyze:dependency-baseline
 bun run analyze:full
 ```
 
-Review the baseline diff before committing it. Never run `knip --fix` unattended because
-an incomplete entry graph can remove runtime-loaded code.
+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
 
@@ -56,7 +114,9 @@ native configuration for Cursor, Claude Code, Codex CLI, GitHub Copilot, Copilot
 Google Antigravity CLI, and Devin.
 
 Post-edit events run the changed-file Biome command. Stop events run both repository-wide
-ratchets. Hook failure and retry behavior differs by host, so CircleCI remains the merge
+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
@@ -69,7 +129,7 @@ gate and the real Git pre-commit hook covers commits made outside an agent.
 | `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 hook commands, ratchet logic, and tests |
+| `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/src/docs/versioned/next/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`, `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/src/docs/versioned/next/how-to/README.md

@@ -12,19 +12,26 @@ Problem-oriented, practical steps. Use these when you know what you want to do.
 
 ## 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)
+- [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
 - [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)
 - [Password reset and email verification](password-reset.md) — JWT routes, comms templates, Better Auth hooks
 - [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) — Configure hosted docs/codegen and local runtime tools
+- [Debug with MCP](debug-with-mcp.md) — Diagnose backend, browser, Metro, app, and client-state failures
 - [Connect an MCP client with a service token](connect-mcp-service-token.md) — Mint a personal `mcp_` key for Perplexity and other remote clients
 - [Install agent skills](install-agent-skills.md) — `npx skills`, the Cursor plugin, the Codex plugin, or the Claude Code plugin
 - [GitHub issue lifecycle](github-issue-lifecycle.md) — Create pick-ready issues, Pick ⇄ Roast, or unattended `status:ready-for-dev` pickup
@@ -32,7 +39,13 @@ Problem-oriented, practical steps. Use these when you know what you want to do.
 - [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
 - [Track upstream Expo](track-upstream-expo.md) — Morning probe for SDK betas; `release-X.Y.Z` loop log + native fingerprint deps
+- [Compose charts in a dashboard grid](charts-and-dashboards.md) — `LineChart` / `BarChart` / `AreaChart` / `DonutChart` inside `Card`s in `DashboardGrid`
+- [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
+- [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`
 
 ## Admin
 

package/src/docs/versioned/next/how-to/add-gpt-chat-mascot.md

@@ -0,0 +1,92 @@
+# Add a GPT chat mascot
+
+Pass a `mascot` node into `GPTChat`. Terreno does not ship a character — the consumer owns the image, Lottie, icon, or copy.
+
+## When it shows
+
+| Chat state | Mascot |
+| --- | --- |
+| `currentMessages` is empty | Rendered, centered in the chat panel above suggested prompts |
+| One or more messages | Hidden |
+
+The empty state fills the message area and centers both axes. GPTChat sizes that hero to the message viewport so a short mascot stays centered, and the same scroller still reaches a large mascot, suggested prompts, or an open keyboard. Streaming feedback stays with the centered hero until the first message arrives. Size the mascot for a hero slot (`Heading size="2xl"`, a large `Image`, or a Lottie view).
+
+Omit `mascot` to keep the default empty chat (prompts only, or a blank panel).
+
+## Steps
+
+### 1. Build the node in your app
+
+Keep the asset in the consumer package. `GPTChat` only mounts whatever you pass.
+
+```tsx
+import {Box, Heading} from "@terreno/ui";
+import {Image} from "react-native";
+import {useState} from "react";
+
+const MASCOTS = [
+  require("../assets/mascot-1.png"),
+  require("../assets/mascot-2.png"),
+  require("../assets/mascot-3.png"),
+  require("../assets/mascot-4.png"),
+];
+
+const ChatScreen: React.FC = (): React.ReactElement => {
+  // Select once per screen mount; ordinary re-renders keep the same character.
+  const [mascot] = useState(() => MASCOTS[Math.floor(Math.random() * MASCOTS.length)]);
+
+  return (
+    <GPTChat
+      currentMessages={currentMessages}
+      histories={histories}
+      mascot={
+        <Box alignItems="center" gap={3}>
+          <Image
+            accessibilityLabel="App mascot"
+            resizeMode="cover"
+            source={mascot}
+            style={{borderRadius: 112, height: 224, width: 224}}
+          />
+          <Heading align="center" size="md">Ask anything.</Heading>
+        </Box>
+      }
+      onCreateHistory={handleCreateHistory}
+      onDeleteHistory={handleDeleteHistory}
+      onSelectHistory={handleSelectHistory}
+      onSubmit={handleSubmit}
+    />
+  );
+};
+```
+
+For a single fixed mascot, pass one asset directly instead of selecting from an array.
+
+### 2. Pass it to `GPTChat`
+
+```tsx
+<GPTChat
+  currentMessages={currentMessages}
+  histories={histories}
+  mascot={ChatMascot}
+  onCreateHistory={handleCreateHistory}
+  onDeleteHistory={handleDeleteHistory}
+  onSelectHistory={handleSelectHistory}
+  onSubmit={handleSubmit}
+  suggestedPrompts={["What can you help with?"]}
+/>
+```
+
+### 3. Confirm empty vs thread
+
+Open a new chat: the mascot is visible. After the first user or assistant message, it is gone.
+
+## Example
+
+The example app bundles four consumer-owned plant robots in
+`example-frontend/assets/gptMascots/` and selects one on each AI screen mount. The
+demo story `GPTChat` → `Mascot` shows the slot without a backend.
+
+## Related
+
+- [`GPTChat` props](../reference/ui.md#gptchat)
+- Demo: `http://localhost:8085/dev/GPTChat?story=Mascot`

package/src/docs/versioned/next/how-to/add-organizations.md

@@ -0,0 +1,204 @@
+# Add organizations to a Terreno app
+
+Enable organizations only when the app is multi-tenant. Existing single-tenant
+apps can omit every option in this guide.
+
+## 1. Enable organization RBAC
+
+``````typescript
+import {createAccess, terrenoStatements} from "@terreno/api";
+
+export const access = createAccess({
+  connection: mongoose.connection,
+  organizations: true,
+  statements: terrenoStatements,
+  userModel: User,
+});
+
+await access.roles.seedDefaults();
+``````
+
+This adds Membership-based `org-admin` grants and seeds the locked `operator`
+role. It does not change apps that omit `organizations`.
+
+## 2. Mount organization routes
+
+``````typescript
+const app = new TerrenoApp({
+  accessControl: access,
+  organizations: true,
+  userModel: User,
+});
+``````
+
+This mounts `OrgsApp` at `/orgs`. To configure audit handling or a different
+path, pass an options object:
+
+``````typescript
+organizations: {
+  basePath: "/organizations",
+  onOrgAudit: recordOrganizationAudit,
+  settingsSchema: organizationSettingsSchema,
+}
+``````
+
+## 3. Type organization settings
+
+Keep native `Organization` fields unchanged. Put app fields on
+`Organization.settings` with a nested Mongoose schema and a TypeScript
+interface.
+
+1. Declare the settings shape (optional module augmentation):
+
+``````typescript
+// src/types/models/organizationSettingsTypes.ts
+export interface ExampleOrganizationSettings {
+  timezone?: string;
+}
+
+declare module "@terreno/api" {
+  interface OrganizationSettings extends ExampleOrganizationSettings {}
+}
+``````
+
+2. Build the nested schema. Use optional fields or defaults so existing
+organizations still validate:
+
+``````typescript
+// src/models/organizationSettings.ts
+import {createOrganizationSettingsSchema} from "@terreno/api";
+import type {ExampleOrganizationSettings} from "../types/models/organizationSettingsTypes";
+
+export const organizationSettingsSchema = createOrganizationSettingsSchema<ExampleOrganizationSettings>({
+  timezone: {
+    description: "IANA timezone used for organization-local dates",
+    type: String,
+  },
+});
+``````
+
+3. Register before you create or patch organizations (startup and seeds):
+
+``````typescript
+import {registerOrganizationSettings} from "@terreno/api";
+import {organizationSettingsSchema} from "./models/organizationSettings";
+
+registerOrganizationSettings(organizationSettingsSchema);
+``````
+
+Or pass the same schema on `TerrenoApp` / `OrgsApp`:
+
+``````typescript
+new TerrenoApp({
+  accessControl: access,
+  organizations: {settingsSchema: organizationSettingsSchema},
+  userModel: User,
+});
+``````
+
+Read typed settings with `organizationSettingsOf(organization)` or
+`organizationSettingsOf<ExampleOrganizationSettings>(organization)`.
+
+Without a registered schema, `settings` stays Mixed and accepts any object.
+Unknown keys and wrong types fail with **400** `Organization settings are invalid`
+once a schema is registered.
+
+## 4. Scope tenant models
+
+Add `orgScopedPlugin` to models that use ObjectId organization keys. Put
+`orgContextMiddleware({required: true})` before their routes, use
+`OrgQueryFilter` for lists, and overwrite client organization ids during
+create:
+
+``````typescript
+import {
+  authenticateMiddleware,
+  getOrgContext,
+  modelRouter,
+  OrgQueryFilter,
+  orgContextMiddleware,
+  orgScopedPlugin,
+  Permissions,
+  type TerrenoPlugin,
+} from "@terreno/api";
+import type express from "express";
+
+schema.plugin(orgScopedPlugin);
+
+const projectOrgContextPlugin: TerrenoPlugin = {
+  register(expressApp: express.Application): void {
+    expressApp.use(
+      "/projects",
+      authenticateMiddleware(),
+      orgContextMiddleware({required: true})
+    );
+  },
+};
+
+const projectRouter = modelRouter("/projects", Project, {
+  permissions: {
+    create: [Permissions.IsAuthenticated, Permissions.IsOrganizationMember],
+    delete: [Permissions.IsAuthenticated, Permissions.IsOrganizationMember],
+    list: [Permissions.IsAuthenticated],
+    read: [Permissions.IsAuthenticated, Permissions.IsOrganizationMember],
+    update: [Permissions.IsAuthenticated, Permissions.IsOrganizationMember],
+  },
+  preCreate: (body, _req) => ({
+    ...body,
+    organizationId: getOrgContext()?.organization?._id,
+  }),
+  queryFilter: OrgQueryFilter,
+});
+
+app.register(projectOrgContextPlugin).register(projectRouter);
+``````
+
+For admin CRUD, use `new AdminApp({accessControl: access, organizations:
+true})`. Models with an `organizationId` schema path are scoped automatically,
+except `AuditEvent` (the platform audit log lists without a selected org).
+Admin-window `POST /sync/mutate` and socket `sync:mutate` use the same membership
+check as REST for update and delete when `X-Organization-Id` (HTTP) or
+`organizationId` (socket payload) is set. Admin `createSyncDb({organizationIdProvider})`
+sends that id on every mutate.
+
+`orgScopedPlugin` also makes `organizationId` immutable after the document is
+created. Client PATCH bodies, admin writes, sync updates, and direct Mongoose
+saves that change `organizationId` return HTTP 400 with
+`organizationId cannot be changed`.
+
+## 5. Send organization context
+
+Send `X-Organization-Id` on tenant-scoped requests. `org-admin` callers with
+exactly one administered organization may omit it; Terreno infers that org.
+Operators and superadmins must select an org.
+
+Frontend admin hosts use `OrgContextProvider` + `OrgSwitcher`.
+`useAdminApi` adds the selected organization header automatically.
+
+Disabled organizations are excluded from `/orgs/mine` and cannot be selected as
+tenant context. Operators re-enable them from the organization directory UI or
+with `PATCH /orgs/:id` and `disabled: false` (see
+[How organization tenancy works](../explanation/organizations.md#disabled-organizations)).
+
+Creating or renaming an organization to a name that generates an existing slug,
+including a slug still held by a **soft-deleted** organization, returns **409**
+`Organization name already in use`. `OrgSwitcher` hides itself
+when `/orgs/mine` returns **403** for callers without org-admin memberships.
+
+## Example app accounts
+
+After `bun run backend:seed`, all accounts use password `testpassword123`:
+
+| Account | Access |
+| --- | --- |
+| `operator@example.com` | Platform organization directory; may enter either org |
+| `orgadmin-alpha@example.com` | Org admin for Alpha Workspace |
+| `orgadmin-beta@example.com` | Org admin for Beta Workspace |
+| `test@example.com` | Member of Alpha Workspace |
+| `admin@example.com` / `superadmin@example.com` | Existing example superadmin accounts |
+
+The seed creates Alpha Workspace and Beta Workspace plus two projects in Alpha
+Workspace. Membership rows, not fields on User, are the source of tenant access.
+In-process Better Auth seeding sets `disableRateLimit: true` so production
+preview smoke tests can create all six accounts without hitting Better Auth's
+sign-up limiter.

package/src/docs/versioned/next/how-to/admin-add-model.md

@@ -38,7 +38,15 @@ Common fields:
 - `searchFields`: string fields matched by the list search box (`q`) as a
   case-insensitive partial (`$regex`) query.
 - `sortableFields`: the only columns with sorting enabled.
-- `filters`: typed filter drawer controls.
+- `filters`: typed list filters rendered on `DataTable` column headers (web) or the
+  mobile **Filters** sheet. `text` filters are case-insensitive contains (`$regex`);
+  `choice` filters support multi-select (`$in`); `ref` stays a single ObjectId. The
+  backend accepts only escaped literal regex patterns and rejects extra nested operators.
+  Optional choice fields (Mongoose path not `required`) automatically expose an **Empty**
+  filter option; set `allowEmpty: false` on the filter config to hide it, or
+  `allowEmpty: true` on required fields when you intentionally want unset matching.
+  Empty filters can be combined with toolbar search or concrete choices. The wire
+  sentinel is consumed before Mongo receives the query.
 - `fieldsets`: grouped form sections.
 - `readonlyFields` / `hiddenFields`: display-only or omitted form fields.
 - `adminPermissions`: optional admin-specific permission methods.

package/src/docs/versioned/next/how-to/admin-import-prebuilt.md

@@ -3,12 +3,15 @@
 Register first-party plugins on the same `TerrenoApp` as `AdminApp`:
 
 ```ts
+import {JobsApp} from "@terreno/jobs";
+
 const app = new TerrenoApp({userModel: User})
   .register(new FeatureFlagsApp())
   .register(new ConsentApp({auditTrail: true}))
   .register(new DocumentStorageApp({bucketName: process.env.GCS_BUCKET ?? ""}))
   .register(new AIAdminApp())
-  .register(new AdminApp({home: {slots: {main: ["modelStats"]}}}));
+  .register(new JobsApp({accessControl})) // optional — needs admin:access + admin:jobs
+  .register(new AdminApp({home: {slots: {main: ["modelStats", "jobs"]}}}));
 ```
 
 `AdminApp` aggregates each plugin's `adminContribution()`:
@@ -17,6 +20,9 @@ const app = new TerrenoApp({userModel: User})
 - `ConsentApp`: ConsentForm and ConsentResponse models plus consent field-widget IDs.
 - `DocumentStorageApp`: `documents` custom screen.
 - `AIAdminApp`: `ai-requests` custom screen and explorer API.
+- `JobsApp`: `jobs` custom screen and home widget (`dead` / `running` counts). With
+  `accessControl`, requires **both** `admin:access` and `admin:jobs`; without it, legacy
+  `user.admin`. See [Durable background jobs](background-jobs.md).
 
 Wrap frontend admin routes in `AdminProvider`. First-party widgets are already in the built-in
 registry, so no consumer-side switch statement or custom-screen map is required.

package/src/docs/versioned/next/how-to/audit-log.md

@@ -0,0 +1,85 @@
+# Enable the framework audit log
+
+Register `AuditApp` and set `audit: true` on routers you want logged. Successful HTTP mutations write append-only `AuditEvent` rows. Default retention is forever.
+
+## Steps
+
+### 1. Register the plugin
+
+```typescript
+import {AuditApp, TerrenoApp} from "@terreno/api";
+
+new TerrenoApp({userModel: User}).register(new AuditApp()).start();
+```
+
+Importing `@terreno/api` does not register `AuditEvent`. HTTP list/read is admin-only at `GET /audit-events` and `GET /admin/audit-events`. Create/update/delete over HTTP are disabled (405), including the admin remount.
+
+### 2. Opt in per router
+
+```typescript
+modelRouter("/todos", Todo, {
+  audit: true, // or {redact: ["ssn"]}
+  permissions: {
+    /* ... */
+  },
+});
+```
+
+`audit: true` without `AuditApp` still returns 2xx and logs an error once per process.
+
+## Operations
+
+| HTTP | `verb` | `operation` | Diff |
+| --- | --- | --- | --- |
+| POST `/` | `created` | `create` | `after` only |
+| PATCH `/:id` | `updated` | `update` | Changed fields in `before` / `after` |
+| DELETE `/:id` | `deleted` | `delete` | `before` only |
+| POST `/:id/:field` | `updated` | `arrayPush` | Changed fields; `recordId` set |
+| PATCH `/:id/:field/:itemId` | `updated` | `arrayUpdate` | Changed fields; `recordId` set |
+| DELETE `/:id/:field/:itemId` | `updated` | `arrayRemove` | Changed fields; `recordId` set |
+
+`source` is `modelRouter` for these writes. Secrets (`password`, `hash`, `salt`, `token`,
+`secret`, `refreshToken`) are omitted at every object and array depth, including compound
+keys such as `tokenHash`. Extra `redact` names merge with that list as exact field names.
+
+### 3. Admin mutations
+
+When `AuditApp` is registered, AdminApp writes the same `AuditEvent` collection with
+`source: "admin"` after successful admin POST/PATCH/DELETE. You do not need `onAdminAudit` for
+that. `onAdminAudit` remains an extra sink if the app still wants a second destination.
+Admin diffs also omit each model's `hiddenFields` and `excludeFields`.
+
+RBAC mutations fan into the same collection when `createAccess({auditSink: persistRbacAuditToAuditEvent})` is set. `source` is `rbac`.
+
+`organizationId` is copied onto the event when `req.organization` is set (`id` or `_id`), otherwise from the request org AsyncLocalStorage, then `X-Organization-Id`, then the mutated document's `organizationId` string. Socket admin-window mutates attach `organizationId` on the payload so non-tenant models still land in the selected organization's audit log. The field is omitted when none of those exist. Admin list/read for `AuditEvent` is not organization-scoped, so unscoped rows stay visible when no organization is selected.
+
+`actorId` comes from `req.user.id` (or `_id`). Only a 24-hex Mongo ObjectId is stored;
+mongoose's looser `isValidObjectId` (12-character strings) is not used. Any other id
+shape still writes the event with `actorId` omitted and a warning logged.
+
+Update and delete snapshot `before` only when `audit` is on. If that `toJSON` throws, the
+mutation still completes and the event is recorded without a `before` snapshot.
+
+### 4. Fire-and-forget persist
+
+HTTP handlers do not await Mongo. Diffs still run before the response so `before` / `after` are captured. Failures log; the mutation stays 2xx.
+
+To persist completely off the API process, set Cloud Tasks env (`GCP_PROJECT`, `GCP_LOCATION`, `GCP_TASKS_AUDIT_QUEUE`, `AUDIT_TASKS_URL`, `AUDIT_TASKS_SECRET`) and `bun add @google-cloud/tasks`. `AuditApp` then enqueues the write and handles `POST /internal/audit-events` with header `X-Terreno-Audit-Secret`. Or pass `enqueue` yourself:
+
+```typescript
+new AuditApp({
+  enqueue: async (write) => {
+    await myQueue.push(write);
+  },
+  processQueuePath: "/internal/audit-events",
+  processQueueSecret: process.env.AUDIT_TASKS_SECRET,
+});
+```
+
+Authenticated malformed queue payloads are acknowledged without persistence. They cannot
+become valid on retry, and returning a non-2xx response would make Cloud Tasks retry the
+same poison task indefinitely.
+
+### 5. Retention
+
+Omit `retentionDays` or set `0` to keep events forever (no TTL index). `new AuditApp({retentionDays: 90})` creates a Mongo TTL index on `created` with `expireAfterSeconds = 90 * 86400`, replacing the default `{created: 1}` field index so Mongo does not reject a duplicate key pattern. Mongo expires documents in the background; lowering or removing TTL later requires dropping that index yourself (`db.auditevents.dropIndex(...)`) — Mongoose will not remove it.