@terreno/mcp 57.14.0 → 57.16.1

package/src/docs/versioned/57.15.0/how-to/background-jobs.md

@@ -0,0 +1,296 @@
+# Durable background jobs
+
+Use `@terreno/jobs` when work must survive process restarts, retry with backoff, run on a
+schedule, or dispatch through Cloud Tasks / Vercel Queues. Register `JobsApp`, define
+handlers, enqueue rows in MongoDB, then start a worker explicitly.
+
+For one-off **CLI** scripts or in-process timers, keep `@terreno/api` [`wrapScript` / `cronjob`](../reference/api.md#wrapscript) — they are process-local. Admin panel **HTTP** script runs go through `admin/script` when `JobsApp` is registered (see below). See [Jobs reference](../reference/jobs.md) for exports, routes, and defaults.
+
+## Install and register
+
+```bash
+bun add @terreno/jobs
+```
+
+Peer dependency: `mongoose ^8.0.0 || ^9.0.0`.
+
+```typescript
+import {TerrenoApp} from "@terreno/api";
+import {JobsApp, MongoJobRunner} from "@terreno/jobs";
+
+const jobsApp = new JobsApp({
+  accessControl, // optional — requires admin:access AND admin:jobs when set
+  runner: new MongoJobRunner(),
+  timezone: "UTC",
+});
+
+jobsApp.define("billing/capture", {
+  handler: async (payload, ctx) => {
+    ctx.log.info("capturing", {invoiceId: (payload as {invoiceId?: string}).invoiceId});
+    // business logic
+  },
+  retry: {maxAttempts: 5, backoffMs: 1_000, maxBackoffMs: 900_000},
+});
+
+new TerrenoApp({userModel: User})
+  .register(jobsApp)
+  .start();
+```
+
+`JobsApp.register()` wires admin routes and optional `POST /jobs/execute`. It does **not**
+start a worker. Call `jobsApp.startWorker()` from the API process or a dedicated worker
+entrypoint.
+
+## Admin scripts
+
+When `JobsApp` is registered **before** `AdminApp`, `POST {adminBase}/scripts/:name/run`
+enqueues job `admin/script` (`maxAttempts: 1`) and still returns `{taskId}` for the existing
+Scripts poll UI (`BackgroundTask`). Progress, logs, dry/wet, and cancel stay on that row.
+Cancel also cancels the job so `ctx.signal` aborts.
+
+Apps without `JobsApp` keep the previous in-process `void` runner. The CLI
+(`runScriptCli` / `bun run script`) stays process-local.
+
+Register the same script catalog on the worker:
+
+```typescript
+import {defineAdminScriptJob} from "@terreno/admin-backend";
+
+defineAdminScriptJob(jobsApp, (name) => adminScripts.find((script) => script.name === name));
+```
+
+`AdminApp` also binds `admin/script` from its `scripts` list at register time. Cloud Tasks
+uses this path automatically when `JobsApp` is constructed with `GcpCloudTasksRunner` — the
+worker/execute process must load the same script definitions. If runner `enqueue` throws,
+the HTTP handler marks the `BackgroundTask` failed and returns 500 instead of leaving it
+`pending`.
+
+## Enqueue
+
+```typescript
+import {getJobsService} from "@terreno/jobs";
+import {DateTime} from "luxon";
+
+await getJobsService().enqueue({
+  name: "billing/capture",
+  payload: {invoiceId: "inv_123"},
+});
+
+await getJobsService().enqueue({
+  name: "billing/capture",
+  payload: {invoiceId: "inv_123"},
+  idempotencyKey: "capture:inv_123",
+});
+
+await getJobsService().enqueue({
+  name: "billing/capture",
+  payload: {invoiceId: "inv_123"},
+  runAt: DateTime.utc().plus({hours: 1}).toJSDate(),
+});
+```
+
+- Unknown `name` → `APIError` 400.
+- Duplicate `(name, idempotencyKey)` returns the existing row and does **not** redispatch.
+- `enqueue` persists first; the injected `JobRunner.enqueue` runs only for **new** rows.
+
+## In-process worker vs standalone worker
+
+| Mode | When | Steps |
+| --- | --- | --- |
+| In-process | Local dev, single replica | After `TerrenoApp.start()`, call `jobsApp.startWorker()`. |
+| Standalone | Production API + worker split | API: `JOBS_START_WORKER=false`. Run `bun run jobs:worker` (example-backend) in a second process with the same job definitions and Mongo URI. |
+
+Example-backend gates the API-process worker with `JOBS_START_WORKER` (unset → `true`):
+
+```bash
+# API only — no poll loop in the web process
+JOBS_START_WORKER=false bun run backend:dev
+
+# Dedicated worker (same env + Mongo as API)
+bun run jobs:worker
+```
+
+On shutdown, call `jobsApp.stopWorker()` so in-flight handlers receive `ctx.signal` abort.
+
+## Mongo runner: restart, retry, idempotency, schedules
+
+**Restart:** Jobs are Mongo documents. A crashed worker leaves `running` rows; after
+`lockTtlMs` (default 15 minutes) another worker reclaims them via `lockedAt` expiry.
+
+**Retry:** Handler throws → `attemptCount++`, `attempts[]` entry, exponential backoff with
+equal jitter, `status: "pending"` and future `runAt`. At `maxAttempts` (default 5) →
+`status: "dead"`. Missing handler → `status: "failed"` (no automatic retry).
+
+**Idempotency:** Optional `idempotencyKey` per `name` with a partial unique index. Use for
+“enqueue once” semantics, not handler-side dedupe.
+
+**Schedules:** Pass `schedule: {cron, timezone?}` on `define`. Worker `startWorker()` calls
+`reconcileSchedules()`; the poll loop ticks due schedules, enqueues a child job, and skips a
+tick when a child for that schedule is still `pending` / `running` / `scheduled`.
+
+## At-least-once handlers
+
+Delivery is **at-least-once**: lock expiry, Cloud Task retries, or Vercel queue redelivery
+can run a handler more than once.
+
+- Make handlers idempotent (stable keys, upserts, “already processed” checks).
+- Use `idempotencyKey` on enqueue to prevent duplicate **rows**, not duplicate execution after admin retry/requeue.
+- Respect `ctx.signal` for cooperative cancellation.
+- Use `ctx.log` (scoped logger) — `jobId` is in request context for log correlation.
+
+## Admin
+
+`JobsApp.adminContribution()` registers:
+
+- Custom screen `jobs` (dashboard)
+- Home widget `jobs` (dead / running counts)
+
+When `accessControl` is configured, callers need **both** `admin:access` and `admin:jobs`
+(default `terrenoStatements.admin` includes both). When `accessControl` is omitted, routes
+use legacy `user.admin === true`.
+
+Frontend routes (example): `/admin/jobs`, `/admin/jobs/[id]`. Widgets ship in
+`@terreno/admin-frontend` (`JOBS_ADMIN_WIDGETS`, `JOBS_HOME_WIDGETS`) — no host remap.
+See [Import pre-built admins](admin-import-prebuilt.md).
+
+Admin payloads are **hidden by default** (omit `redactPayload`). Opt in with a projection —
+do not pass through the raw payload unless every field is safe for operators:
+
+```typescript
+// Default — no hook; payload omitted from admin API responses
+new JobsApp({accessControl});
+
+// Opt-in — expose only non-sensitive fields
+new JobsApp({
+  accessControl,
+  redactPayload: ({name, payload}) => {
+    if (name === "billing/capture") {
+      return {invoiceId: (payload as {invoiceId?: string}).invoiceId};
+    }
+    return undefined;
+  },
+});
+```
+
+## GCP Cloud Tasks runner
+
+Optional peer: `@google-cloud/tasks`.
+
+```typescript
+import {GcpCloudTasksRunner} from "@terreno/jobs/runners/gcpCloudTasks";
+
+const jobsApp = new JobsApp({
+  executeAuth: async (req) => {
+    // Verify OIDC token on POST /jobs/execute — your responsibility
+    return verifyGcpOidc(req);
+  },
+  runner: new GcpCloudTasksRunner({
+    project: "my-project",
+    location: "us-central1",
+    queue: "background-jobs",
+    publicUrl: "https://api.example.com",
+    serviceAccountEmail: "tasks-invoker@my-project.iam.gserviceaccount.com",
+    oidcAudience: "https://api.example.com/jobs/execute", // optional; defaults to execute URL
+  }),
+});
+```
+
+`GcpCloudTasksRunner` sets `requiresExecuteRoute: true`. Each enqueue creates an HTTP POST
+to `{publicUrl}/jobs/execute` with body `{jobId}` (base64) and an OIDC token. Delayed jobs
+use Cloud Tasks `scheduleTime`. HTTP tasks set `dispatchDeadline` to `{seconds: 1800}`
+(REST JSON `"1800s"`) by default so Cloud Tasks does not retry at 10 minutes while a
+30-minute Cloud Run handler is still running. Override with `dispatchDeadlineSeconds`
+(15–1800).
+`@terreno/jobs` does **not** read `GCP_TASK_*` env vars —
+pass explicit constructor config. Compiled `bun build --compile` binaries must pass a
+`client` that does not load `@google-cloud/tasks` (that package reads
+`cloud_tasks_client_config.json` from disk and is omitted from `$bunfs`). The example
+backend POSTs to the Cloud Tasks REST API with `google-auth-library`.
+
+The deployed example backend selects this runner with `JOBS_RUNNER=gcp-cloud-tasks`.
+Infra Manager creates one queue, the API Cloud Run identity
+`terreno-backend-runtime` (queue enqueuer + `actAs` on the callback SA), and a
+callback-only `terreno-jobs-invoker` service account. The CD script supplies
+the remaining `GCP_TASKS_*` values. Do not grant enqueue or `actAs` to the
+project default Compute Engine SA. Both GitHub Actions and CircleCI deploy the same
+runner configuration so either deploy path preserves Cloud Tasks execution. The API
+process starts the worker so cron schedules
+enqueue Cloud Tasks (`GcpCloudTasksRunner.start()` ticks Mongo schedules only). The tasks
+Cloud Run service is the execution pool: Cloud Tasks pushes authenticated callbacks to it,
+and queue rate limits bound concurrency. Keep `JOBS_START_WORKER=false` on the tasks
+service so it does not double-tick schedules. Do not run `jobs:worker` in this mode —
+that process would also tick schedules.
+
+PR previews use the same queue but different callback URLs and databases. GitHub Actions
+and CircleCI both deploy the `pr-<number>` tag on the tasks Cloud Run service before the
+API preview starts enqueueing. GitHub Actions uses `env_vars_update_strategy: overwrite`
+and `secrets_update_strategy: overwrite` (CircleCI `--set-env-vars`) so `MONGO_DB_NAME` /
+`PR_NUMBER` and leftover secrets on a tagged revision do not merge into the next production
+or preview deploy. The preview smoke container receives the same `JOBS_*` env as Cloud Run.
+A task created by PR 123 targets that tag and reads
+`terreno-example-pr-123`; it cannot execute against another PR or production.
+
+## Vercel Queues runner
+
+Optional peer: `@vercel/queue`.
+
+```typescript
+import {
+  createVercelQueuesConsumer,
+  VercelQueuesRunner,
+} from "@terreno/jobs/runners/vercelQueues";
+
+const jobsApp = new JobsApp({
+  runner: new VercelQueuesRunner({topic: "terreno-jobs"}),
+});
+
+// Private consumer route (platform auth via handleCallback — not Express execute route)
+export const POST = createVercelQueuesConsumer({host: jobsApp});
+```
+
+`vercel.json` must declare the queue trigger (private route):
+
+```json
+{
+  "experimentalTriggers": [
+    {"type": "queue/v2beta", "topic": "terreno-jobs"}
+  ]
+}
+```
+
+**7-day limit:** `delaySeconds` and retention are capped at 604_800 seconds (7 days). `runAt`
+beyond that window throws `VercelQueueRunAtBeyondLimitError` at enqueue — use a shorter delay
+or a different runner for longer deferrals. Retention is bumped to cover `delaySeconds` when
+needed.
+
+`VercelQueuesRunner` does **not** mount `POST /jobs/execute`; the consumer calls
+`executeJobById` through `createVercelQueuesConsumer`.
+
+## Custom runner
+
+Implement `JobRunner`:
+
+```typescript
+import type {JobRunner} from "@terreno/jobs";
+
+const runner: JobRunner = {
+  id: "my-bus",
+  requiresExecuteRoute: false, // set true if you use POST /jobs/execute
+  async enqueue(job) {
+    await myBus.publish({jobId: job._id.toString()});
+  },
+  async start({jobs, signal, pollIntervalMs}) {
+    // optional — MongoJobRunner implements start; dispatch-only runners omit it
+  },
+};
+```
+
+Inject with `new JobsApp({runner})`. Dispatch failures on untouched `pending` rows roll back
+the insert when possible (`JobDispatchError`).
+
+## Related
+
+- [Jobs reference](../reference/jobs.md)
+- [Environment variables — jobs](../reference/environment-variables.md#background-jobs)
+- [Import pre-built admins](admin-import-prebuilt.md)
+- Implementation plan: [job-queues.md](https://github.com/TerrenoLabs/terreno/blob/master/docs/implementationPlans/job-queues.md)

package/src/docs/versioned/57.15.0/how-to/build-a-durable-workflow.md

@@ -0,0 +1,232 @@
+# Build a durable workflow
+
+Build a multi-step task that survives restarts, asks a person to sign off, and performs its
+side effect exactly once. The one worked example is the example backend's clinical tracer,
+`clinic.intakeSummary`: fetch a chart, summarize it with an agent, wait for a clinician,
+file a note. API: [AI harness reference](../reference/ai-harness.md). Why it is shaped this
+way: [Durable agent harness](../explanation/durable-agent-harness.md).
+
+| File | What it holds |
+| --- | --- |
+| `example-backend/src/harness/clinicalIntake.ts` | The task, the summarizer agent, the approvers |
+| `example-backend/src/harness/fakeEhr.ts` | The EHR client (`getChart`, `writeNote`) over `FakePatientChart` / `FakeClinicalNote` |
+| `example-backend/src/harness/clinicModels.ts` | Model resolver: Gemini when configured, else the demo model |
+| `example-backend/src/harness/clinicDemoModel.ts` | Deterministic local `LanguageModel` for dev and e2e |
+| `example-backend/src/harness/exampleHarness.ts` | `Harness.open` + runner, started in the API process |
+| `example-backend/src/harness/startClinicalIntake.ts` | Admin script that starts a run |
+
+## Try it (5 minutes)
+
+1. Start a replica-set `mongod`, the backend (`bun run backend:dev`), and the frontend
+   (`bun run frontend:web`). Steps: [Run tests locally](run-tests-locally.md).
+2. Seed: `bun run backend:seed`. It creates charts `p-1001`, `p-1002`, `p-1003`, the admin
+   `admin@example.com`, and the clinician `clinician@example.com` (password
+   `testpassword123`).
+3. Start a run: `cd example-backend && bun run script startClinicalIntake --wet --patientId p-1001`,
+   or run `startClinicalIntake` from the admin **Scripts** screen.
+4. Sign in as the admin and open **AI Harness → Approvals**
+   (`http://localhost:8082/admin/harness-approvals`). Open the item and approve it.
+5. Open **AI Observability → Traces**: the newest `clinic.intakeSummary@1` trace shows every
+   phase, the summarizer with its model call, and the sign-off.
+
+## 1. Define the task
+
+Split the work at every point where a crash would need a different answer. Each phase is a
+checkpoint; `replay` says what to do when a phase is cut off.
+
+| Phase | `replay` | Work | Why that policy |
+| --- | --- | --- | --- |
+| `fetch` | `safe` | `ehr.getChart(patientId)`; no chart fails the task | A read; running it twice is harmless |
+| `summarize` | `safe` | `rt.runAgent(summarizer, {input: chart, output: IntakeSummarySchema})` | A replay finds the same subagent turn; finished model calls are not repeated |
+| `review` | `safe` | `rt.approval("clinician-signoff", {...})`; branch on the decision | A replay finds the same approval row |
+| `write` | default (`never`) | `ehr.writeNote(..., {idempotencyKey: \`note-${task.id}\`})` | A write cut off mid-call needs a person to check the EHR |
+
+```typescript
+const intakeSummary = defineTask<IntakeSummaryInput, IntakeSummaryState, IntakeSummaryResult>({
+  name: "clinic.intakeSummary",
+  version: 1,
+  approvals: {"clinician-signoff": {approvers: [isAdminOrClinician]}},
+  initial: () => ({phase: "fetch", state: {}}),
+  retry: {maxAttempts: 3},
+  phases: {
+    fetch: {
+      replay: "safe",
+      run: async (task, rt) => {
+        const chart = await ehr.getChart(task.input.patientId);
+        if (!chart) {
+          await rt.commit({terminal: {status: "failed", error: `No chart for patient ${task.input.patientId}`}});
+          return;
+        }
+        await rt.commit({phase: "summarize", state: {chart}});
+      },
+    },
+    // summarize, review, write: see the sections below
+  },
+});
+```
+
+Keep `state` plain JSON: it is stored on every checkpoint. Bump `version` when phases or
+state change: [Ship a new task version](ship-a-new-task-version.md).
+
+## 2. Add the agent
+
+```typescript
+const summarizer = defineAgent({
+  name: "clinic.summarizer",
+  model, // {provider: "google", modelId: "gemini-2.5-flash"} or the demo model
+  fallbackModels,
+  instructions: CLINIC_SUMMARIZER_INSTRUCTIONS, // a named constant, never inline
+  tools: [],
+});
+
+summarize: {
+  replay: "safe",
+  run: async (task, rt) => {
+    const summary = await rt.runAgent<NoteContent>(summarizer, {
+      input: task.state.chart,
+      output: IntakeSummarySchema, // {summary, risk, sources}
+    });
+    await rt.commit({phase: "review", state: {...task.state, summary}});
+  },
+},
+```
+
+`Harness.open({models})` turns the agent's `{provider, modelId}` into a model. The example
+resolver (`resolveExampleModel`) maps:
+
+| Ref | Model |
+| --- | --- |
+| `google/*` | The server's Gemini / Vertex model (`GEMINI_API_KEY` or `GOOGLE_VERTEX_PROJECT`) |
+| `demo/clinic-summarizer-demo` | The demo model: derives the summary from the chart by fixed rules, prefixes it `[Demo model: no LLM was called]`, calls no network |
+
+The summarizer uses the demo model when no provider is configured or `CLINIC_DEMO_MODEL=true`,
+so dev and e2e runs need no API key. Its `LLM` spans are named `demo/clinic-summarizer-demo`.
+
+## 3. Ask for approval
+
+Declare approvers on the definition, keyed by the approval key. Approvers in one list are
+ANDed, so "admin **or** clinician" is one approver:
+
+```typescript
+const isAdminOrClinician = anyApprover(
+  Permissions.IsAdmin,
+  access.permission({clinicalIntake: ["signoff"]}) // RBAC: the `clinician` role grants it
+);
+
+review: {
+  replay: "safe",
+  run: async (task, rt) => {
+    const decision = await rt.approval("clinician-signoff", {
+      title: `Sign off intake summary for ${chart.name}`,
+      summary: signoffSummary(chart, summary), // markdown shown in the inbox
+      payload: {patientId: chart.patientId, ...summary},
+      timeout: {hours: 24},
+    });
+    if (!decision.approved) {
+      const reason = decision.expired
+        ? "Sign-off expired before anyone decided"
+        : (decision.reason ?? "Rejected");
+      await rt.commit({terminal: {status: "completed", result: {status: "rejected", reason}}});
+      return;
+    }
+    await rt.commit({phase: "write", state: {...task.state, signedOffBy: decision.decidedBy}});
+  },
+},
+```
+
+The example adds the `clinicalIntake.signoff` statement and a `clinician` role
+(`example-backend/src/access.ts`, `rbacRoles.ts`). Admins decide in the admin inbox.
+Clinicians without admin access decide over HTTP (`GET /harness/approvals`,
+`POST /harness/approvals/:id/approve`) or in a `HarnessApprovalInbox` mounted outside the
+admin shell ([admin-frontend](../reference/admin-frontend.md#ai-harness-approvals-inbox)).
+
+## 4. Perform the side effect once
+
+Leave the side-effecting phase at the default `replay: "never"` and pass an idempotency key
+the EHR enforces:
+
+```typescript
+write: {
+  run: async (task, rt) => {
+    rt.signal.throwIfAborted();
+    const note = await ehr.writeNote(task.input.patientId, task.state.summary, {
+      idempotencyKey: `note-${task.id}`,
+      signedOffBy: task.state.signedOffBy,
+      taskId: task.id,
+    });
+    await rt.commit({terminal: {status: "completed", result: {status: "filed", noteId: String(note._id)}}});
+  },
+},
+```
+
+`FakeClinicalNote.idempotencyKey` is unique, so even a retried write returns the first note.
+
+## 5. Register and run
+
+```typescript
+const harness = await Harness.open({
+  models: resolveExampleModel,
+  registry: [intakeSummary, summarizer],
+  runner: new InProcessRunner(exampleRunnerOptions()),
+});
+terraApp.register(new HarnessApp({harness})); // before AdminApp: adds the approvals inbox
+await harness.start();                         // after listen: the runner claims work
+
+await harness.createTask(intakeSummary, {patientId}, {requestId: `intake-${patientId}`});
+```
+
+`requestId` makes starting idempotent: the script returns the first run for a repeated key
+(pass `--requestId` to start another). Every process that runs or decides tasks registers
+the same definitions.
+
+## 6. Observe
+
+| Where | What you see |
+| --- | --- |
+| **AI Harness → Approvals** | The pending sign-off: title, markdown summary, payload |
+| **AI Observability → Traces** (`/admin/ai-trace-detail?id=<traceId>`) | The span waterfall |
+| `GET /ai/observability/traces/:traceId` | The same tree as JSON (admin) |
+| `GET /harness/tasks/:id/events` | Live `task.status` and `approval.*` events (SSE) |
+
+`HarnessTask.traceId` links a run to its trace. A completed run's tree:
+
+```
+CHAIN clinic.intakeSummary@1
+├── CHAIN fetch
+├── CHAIN summarize                          (waiting on the summarizer)
+├── AGENT clinic.summarizer
+│   ├── CHAIN request
+│   └── LLM   demo/clinic-summarizer-demo
+├── CHAIN summarize                          (summary committed)
+├── CHAIN review                             (waiting on sign-off)
+├── CHAIN wait:terreno.approval:clinician-signoff:<step>:0
+├── CHAIN approval:clinician-signoff         (decision, decidedBy)
+├── CHAIN review
+└── CHAIN write
+```
+
+## 7. Recover an interrupted run
+
+| Cut off during | What happens | You do |
+| --- | --- | --- |
+| `fetch`, `summarize`, `review` | After the lease expires (`HARNESS_LEASE_SECONDS`, default 30), the next runner replays the phase. A cut-off model request is re-requested; an error `request` span records the interruption. | Nothing |
+| `write` | The task goes `interrupted`. | Check the EHR for `note-<taskId>`, then `POST /harness/tasks/:id/resolveInterrupted` with `{action: "retry" \| "complete" \| "abort", reason}` |
+
+The proof is `example-backend/src/harness/clinicalIntake.crash.test.ts`. It starts the real
+API process (`bun run src/index.ts`) against a replica set with
+`CLINIC_DEMO_MODEL_DELAY_MS=600000`, starts a run, waits until the summarizer's model
+request is in flight, sends `SIGKILL`, starts a fresh process, approves, and asserts:
+the run ends `filed`, exactly one `FakeClinicalNote` exists, and the trace has one `LLM`
+span plus an interruption span naming the dead process's lease. Run it with
+`cd example-backend && bun test src/harness/clinicalIntake.crash.test.ts` (about 50 s).
+The Playwright spec `example-frontend/e2e/harness-intake.spec.ts` covers approve-in-inbox →
+`filed` → span tree in the Traces screen.
+
+## Configuration
+
+| Variable | Default | Effect |
+| --- | --- | --- |
+| `GEMINI_API_KEY` / `GOOGLE_VERTEX_PROJECT` | unset | When set, the summarizer uses `google/gemini-2.5-flash` (fallback `gemini-2.5-flash-lite`) |
+| `CLINIC_DEMO_MODEL` | unset | `true` forces the demo model even with a provider |
+| `CLINIC_DEMO_MODEL_DELAY_MS` | `0` | Demo model waits this long per request (crash drills) |
+| `HARNESS_LEASE_SECONDS` | `30` | Owner and task lease; heartbeat is a third of it. Short values speed up crash recovery in tests |

package/src/docs/versioned/57.15.0/how-to/build-admin-screens.md

@@ -0,0 +1,152 @@
+# Build admin screens
+
+Use this when adding or changing admin UI. Read [How admin interfaces are
+shaped](../explanation/admin-interface.md) first.
+
+## 1. Choose the screen kind
+
+| Need | Do this |
+| --- | --- |
+| CRUD table + form for a Mongoose model | Add `admin` on `modelRouter`. Stop. No new Expo screen. |
+| Dashboard tile on Home | Add a home widget ID to `AdminApp.home.slots` and register `widgets.home`. |
+| Operator tool that is not a model | Register `customScreens` + `widgets.screens` with the same `name`. |
+| Workflow the generic form cannot do | Dedicated Expo route (see consent and comms). Keep the model table for search. |
+
+Adding a model: [Add a model to the admin](admin-add-model.md). Home tiles:
+[Customize the admin home](admin-custom-home.md). Field editors:
+[Add a custom admin field widget](admin-custom-widget.md).
+
+## 2. Wrap the admin tree once
+
+Embedded app (`example-frontend`):
+
+```tsx
+// app/admin/_layout.tsx
+const syncConflicts = useConflicts();
+
+<AdminProvider
+  api={api}
+  apiBase="/admin"
+  apiOrigin={baseUrl}
+  getAuthHeaders={getAdminAuthHeaders}
+  routeBase="/admin"
+  syncConflicts={syncConflicts}
+  syncDb={adminSyncDb}
+  widgets={{screens: {"sync-lab": SyncLabScreen}}}
+>
+  <AdminShellLayout
+    api={api}
+    apiBase="/admin"
+    configurationPath="/admin/configuration"
+    rolesPath="/roles"
+    routeBase="/admin"
+    versionConfigPath="/version-config"
+  >
+    <Stack screenOptions={{headerShown: false, contentStyle: {flex: 1}}} />
+  </AdminShellLayout>
+</AdminProvider>
+```
+
+Render this tree inside `SyncDbProvider client={adminSyncDb}`. If product screens
+also sync the same collection, make `adminSyncDb` a dedicated client with a unique
+store name and `windowCollections` set; do not mix admin rows into the owner/tenant
+product store. Start that client after `canOpenAdminPage` succeeds, block the admin
+shell until `start()` resolves, and call `stop()` when the admin layout unmounts.
+
+Gate entry with `canOpenAdminPage` from `@terreno/rtk` (`admin:access`). Do not
+rely on `user.admin` alone when RBAC is on. Import `baseUrl` from `@terreno/rtk`
+and pass it as `apiOrigin` so admin RPC (`GET /admin/config`, `/rbac/roles`, …)
+hits the API instead of the Expo web origin.
+
+Standalone SPA (`admin-spa`): `routeBase=""`, `apiBase="/admin"`, `credentials="same-origin"`,
+and `getAuthHeaders` that return `{}` so the cookie session is sent without a Bearer header.
+Omit `apiOrigin`. Each route wraps `AdminShellLayout` because the root layout is only
+providers. Model tables render **Create** once, in the table chrome
+(`testID="admin-create-button"`), because admin Expo stacks use `headerShown: false`.
+Model forms render **Save** / **Delete** in the form chrome
+(`testID="admin-save-button"` / `admin-delete-button`) for the same reason.
+The navigator header only receives the screen title.
+
+## 3. Keep generic model routes generic
+
+```
+app/admin/
+  _layout.tsx          # Provider + shell (embedded host)
+  index.tsx            # <AdminHome />
+  [model]/index.tsx    # <AdminScreenRouter name={model} />
+  [model]/create.tsx   # <AdminModelForm mode="create" />
+  [model]/[id].tsx     # <AdminModelForm />
+```
+
+`AdminScreenRouter` resolves the URL segment as: `__scripts` → script list,
+`__migrations` → migrations status (when `GET /admin/config` has
+`migrations.enabled`), matching model name → table, matching custom-screen
+name → `widgets.screens[name]`, else not-found. Do not copy `AdminModelTable`
+into a new file per model.
+
+Create paths are `[model]/create`, not `new`.
+
+## 4. Add a custom screen (both sides)
+
+Backend (`name` is the URL segment and the widget key):
+
+```ts
+new AdminApp({
+  customScreens: [{
+    displayName: "SyncDB Load Lab",
+    name: "sync-lab",
+    description: "Stress-test the local-first sync layer",
+  }],
+});
+```
+
+Frontend: register `widgets.screens["sync-lab"]` on `AdminProvider`. Built-in IDs
+(`comms`, `documents`, `ai-requests`, `version-config`) are already in the
+registry — do not re-map them.
+
+The screen component receives `AdminScreenWidgetProps`. Wrap UI in
+`AdminScreenPage` with `backHref={routeBase}`:
+
+```tsx
+import {AdminScreenPage} from "@terreno/admin-frontend";
+import type {AdminScreenWidgetProps} from "@terreno/admin-frontend";
+
+export const OperationsScreen: React.FC<AdminScreenWidgetProps> = ({routeBase}) => (
+  <AdminScreenPage backHref={routeBase} color="transparent" padding={0} title="Operations">
+    {/* @terreno/ui only */}
+  </AdminScreenPage>
+);
+```
+
+If the screen has extra URL segments (for example `/comms/:id`), add Expo files
+for those paths. Otherwise `[model]/[id]` treats the id as a generic document.
+
+## 5. Fetch data the admin way
+
+- String-`_id` collections configured with `adminBroadcast` use windowed syncdb
+  when the host passes `syncDb` plus fetch auth.
+- ObjectId model CRUD and API-only hosts keep `useAdminApi`.
+- Bulk patch remains server-side: native admin fetch for windowed hosts, RTK fallback otherwise.
+- Admin RPC uses the host-bound native fetch client. Do not add axios.
+
+## 6. Sidebar and grouping
+
+Set `admin.group` on the model so related collections share a Models heading.
+Do not add sidebar links in app code. The shell reads `/admin/config`.
+
+Platform links appear only when `platformTools` says they should. Pass
+`configurationPath`, `rolesPath`, and `versionConfigPath` into `AdminShellLayout`
+so those buttons have destinations. Jobs (`customScreens` name `jobs`) appears
+under Platform, not Screens.
+
+## 7. Verify
+
+Log in as an admin (`admin@example.com` / `testpassword123` in the example). Open
+`/admin` (or `/console` for the SPA). Confirm:
+
+1. Home loads with the expected widgets.
+2. The new model or screen is in the correct sidebar section.
+3. Table → create → edit round-trips, or the custom screen's primary action works.
+4. A user without `admin:access` cannot open the page.
+
+Follow `verify-ui-changes`. Save evidence under `/opt/cursor/artifacts/`.