@terreno/mcp 57.2.0 → 57.4.0

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

@@ -1,5 +1,8 @@
 # Add a model to the admin
 
+Generic table/form routes are already in the host app. Do not add an Expo file per
+model. For screens and nav, see [Build admin screens](build-admin-screens.md).
+
 Add `admin` directly to the model's existing `modelRouter` options:
 
 ```ts
@@ -35,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-custom-home.md

@@ -1,5 +1,8 @@
 # Customize the admin home
 
+Home widgets sit in the admin shell. Screen and sidebar rules:
+[Build admin screens](build-admin-screens.md).
+
 Configure home slots on `AdminApp`:
 
 ```ts

package/src/docs/versioned/next/how-to/admin-custom-widget.md

@@ -1,5 +1,8 @@
 # Add a custom admin field widget
 
+Field widgets are one of three admin widget buckets. Screen and nav rules:
+[Build admin screens](build-admin-screens.md).
+
 1. Name the widget in model admin metadata:
 
 ```ts

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.

package/src/docs/versioned/next/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/FlourishHealth/terreno/blob/master/docs/implementationPlans/job-queues.md)