@terreno/mcp 57.3.0 → 57.4.0

package/src/docs/versioned/next/implementationPlans/examples-demo-coverage.md

@@ -86,15 +86,15 @@ The repo states that `example-frontend` and `example-backend` serve as documenta
 | Admin panel (embedded) | yes | yes | — |
 | Admin SPA | yes | n/a | — |
 | AI streaming chat | yes | yes | — |
-| AI structured output | ? | ? | verify |
+| AI structured output | no | no | **gap** — chat streaming only; see [example-coverage.md](../explanation/example-coverage.md) |
 | Feature flags + live updates | yes | yes | — |
 | Websockets / realtime | yes | yes | — |
 | Consent forms | yes | yes | — |
 | File upload / GCS | yes | yes | — |
-| Better Auth | ? | ? | verify |
-| syncdb local-first | (from #869) | (from #869) | verify after merge |
-| RBAC | no | no | not shipped |
-| Background jobs | no | no | not shipped |
+| Better Auth | yes | yes | — |
+| syncdb local-first | yes | yes | shipped in examples; #869 closed |
+| RBAC | yes | yes | shipped; see [rbac-permissions.md](rbac-permissions.md) |
+| Background jobs | no | no | **gap** — no generic queue example |
 
 Every `?` must be resolved by reading the example source, and every real gap either filled or recorded as a known gap.
 
@@ -149,15 +149,15 @@ See [`docs/tasks/examples-demo-coverage.md`](../tasks/examples-demo-coverage.md)
 
 ## Acceptance Criteria
 
-- [ ] Every component exported from `ui/src/index.tsx` has a demo story or an allowlist entry with a stated reason.
-- [ ] `bun run scripts/check-demo-coverage.ts` fails when a newly exported component has no story and no allowlist entry, and runs in `ui-demo-ci.yml`.
-- [ ] `demo/package.json`'s `test:ci` runs something real.
-- [ ] Stories exist for all P0 components, each showing multiple states (default, loading, error, disabled) where applicable.
-- [ ] Every published package's CI runs `scripts/check-coverage.ts` at the 95% threshold.
-- [ ] Packages currently below 95% have a tracked catch-up plan; no package is permanently exempt.
-- [ ] Every published package is covered by CI running its tests and coverage check, either through a dedicated workflow or the matrix job.
-- [ ] Codecov receives uploads from every package's CI and reports per-PR deltas.
-- [ ] `README.md` shows a coverage badge that reflects reality.
-- [ ] `docs/explanation/example-coverage.md` resolves every `?` in the capability matrix, and each real gap is either filled with an example or recorded as a known gap with an issue link.
-- [ ] `CONTRIBUTING.md` states the 95% coverage expectation and how to run coverage locally per package.
-- [ ] `bun run lint`, `bun run compile`, and the full test suite pass.
+- [x] Every component exported from `ui/src/index.tsx` has a demo story or an allowlist entry with a stated reason.
+- [x] `bun run scripts/check-demo-coverage.ts` fails when a newly exported component has no story and no allowlist entry, and runs in `ui-demo-ci.yml`.
+- [x] `demo/package.json`'s `test:ci` runs something real.
+- [x] Stories exist for all P0 components, each showing multiple states (default, loading, error, disabled) where applicable.
+- [x] Every published package's CI runs `scripts/check-coverage.ts` at the 95% threshold.
+- [x] Packages currently below 95% have a tracked catch-up plan; no package is permanently exempt.
+- [x] Every published package is covered by CI running its tests and coverage check, either through a dedicated workflow or the matrix job.
+- [x] Codecov receives uploads from every package's CI and reports per-PR deltas.
+- [x] `README.md` shows a coverage badge that reflects reality.
+- [x] `docs/explanation/example-coverage.md` resolves every `?` in the capability matrix, and each real gap is either filled with an example or recorded as a known gap with an issue link.
+- [x] `CONTRIBUTING.md` states the 95% coverage expectation and how to run coverage locally per package.
+- [x] `bun run lint`, `bun run compile`, and the full test suite pass.

package/src/docs/versioned/next/implementationPlans/framework-audit-log.md

@@ -0,0 +1,247 @@
+# Implementation Plan: Framework-level audit log
+
+**Status:** Approved  
+**Branch:** `cursor/framework-audit-log-grow-0d6c`  
+**Owner:** —  
+**Created:** 2026-09-10  
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1186 (implementation PRs use `Fixes #1186`)  
+**Task list:** [framework-audit-log.md](../tasks/framework-audit-log.md)  
+**Program:** [B2B platform](b2b-platform-program.md)  
+**Depends on:** — (soft: `organizationId` now; org-admin list filter waits on [org-management-ui](org-management-ui.md))  
+**RTK deprecation flag:** None — admin viewer uses generated OpenAPI / `useAdminApi`, not syncdb  
+
+## Goal
+
+Opt-in `AuditApp` in `@terreno/api` persists append-only `AuditEvent` rows for successful mutations: who changed which record, with changed-field before/after diffs. The existing admin Platform **Audit Log** lists them. Default retention is forever. This is the B2B compliance log; it generalizes example `AdminAuditLog` without replacing consent `ConsentResponse` rows.
+
+## Non-Goals
+
+- Waiting on `org-management-ui` to start (no `OrgsApp` in tree today).
+- Default-on `modelRouter` product CRUD.
+- Consent signing history (`ConsentResponse` + `GET /consents/audit/:userId` stay).
+- Login, failed auth, permission denials (except existing `RbacAudit` `denied: true` fanned through `auditSink`).
+- Sync mutate / outbox / socket writes (`@terreno/syncdb`). HTTP `modelRouter` only.
+- Admin hard-delete of events; SIEM export; legal hold.
+- Full-document snapshots.
+- Per-org-admin filtered lists (store `organizationId` now; filter when org context ships).
+
+## Decisions
+
+| ID | Question | Choice |
+| --- | --- | --- |
+| Q1 | Org dependency | Ship now. Optional `organizationId` from the mutated document or `req.organization` when present. |
+| Q2 | Default on | Off. `AuditApp` plugin + per-router `audit: true`. **AdminApp writes `AuditEvent` automatically when `AuditApp` is registered.** |
+| Q3 | Events | Successful create/update/delete and array mutations on audited routers; AdminApp → same collection; RBAC via existing `auditSink`; consent stays domain-specific. |
+| Q4 | Mutability / retention | HTTP list+read only. Create only via framework writers. No PATCH/DELETE. **Default retain forever.** Optional `retentionDays > 0` Mongo TTL. |
+| Q5 | Diffs | Changed fields only. Auto-redact `password`, `hash`, `salt`, `token`, `secret`, `refreshToken` (case-insensitive last path segment) plus per-router `redact`. Never log full request bodies. |
+
+**Recorded assumptions (not grilled):** No default-connection singleton (same as `RbacAudit`: `createAuditEventModel(connection)`). Example-backend **replaces** `AdminAuditLog` with `AuditEvent`. `onAdminAudit` remains an extra sink. Writes are best-effort (`logger.error`, mutation still succeeds). Persist is fire-and-forget on the request path. Optional Cloud Tasks enqueue (`GCP_TASKS_AUDIT_QUEUE` + `AUDIT_TASKS_URL`) writes Mongo on a worker via `POST /internal/audit-events`. `AuditEvent` is never audited. `audit: true` without `AuditApp` skips the write and logs an error once per process. Array mutations use `verb: "updated"` and `operation` `arrayPush` / `arrayUpdate` / `arrayRemove`. `organizationId` is stored as string. Admin list uses `Permissions.IsAdmin` until org RBAC lands.
+
+## Architecture
+
+```
+AuditApp({retentionDays?})
+  → createAuditEventModel(connection)
+  → set process recorder
+  → modelRouter("/audit-events", AuditEvent, {create/update/delete: [], list/read: IsAdmin})
+  → adminContribution() for Platform Audit Log
+
+modelRouter(..., {audit: true | {redact?: string[]}})
+  → after successful create/update/delete/array *
+  → recordAuditEvent({actorId, modelName, recordId, recordLabel?, organizationId?, verb, operation, before, after, source: "modelRouter"})
+
+AdminApp
+  → after successful admin CRUD, if recorder present
+  → recordAuditEvent({..., source: "admin"})
+  → then onAdminAudit? (unchanged extra sink)
+
+createAccess({auditSink: persistRbacAuditToAuditEvent})
+  → source: "rbac"; before/after from permissionDelta when present
+```
+
+`AuditApp` implements `TerrenoPlugin` (+ `adminContribution` like FeatureFlags). Importing `@terreno/api` does **not** register `AuditEvent` on `mongoose.connection`.
+
+### Config shape
+
+```typescript
+interface AuditAppOptions {
+  enqueue?: (write: AuditEventWrite) => Promise<void>;
+  processQueuePath?: string;
+  processQueueSecret?: string;
+  /** Mongo TTL in days. Omit or 0 = forever (no TTL index). */
+  retentionDays?: number;
+}
+
+interface ModelRouterAuditOptions {
+  redact?: string[]; // extra field names; merged with defaults
+}
+
+// modelRouter options:
+audit?: boolean | ModelRouterAuditOptions;
+```
+
+`audit: true` equals `{redact: []}`.
+
+### Writer contract
+
+```typescript
+interface AuditEventWrite {
+  actorId?: string;
+  after?: Record<string, unknown>;
+  before?: Record<string, unknown>;
+  modelName: string;
+  operation: "create" | "update" | "delete" | "arrayPush" | "arrayUpdate" | "arrayRemove";
+  organizationId?: string;
+  recordId?: string;
+  recordLabel?: string;
+  source: "admin" | "modelRouter" | "rbac";
+  verb: "created" | "deleted" | "updated";
+}
+```
+
+Diff helper: shallow (plus one-level nested objects) comparison of previous JSON vs next JSON after redaction. Unchanged keys omitted. Create: `before` omitted, `after` is redacted new fields. Delete: `after` omitted, `before` is redacted last state.
+
+`organizationId` resolution order: `req.organization?.id` / `_id`, else string of `doc.organizationId` when present.
+
+## Models
+
+`AuditEvent` (collection `auditevents`):
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `actorId` | ObjectId, ref User, indexed | Optional (system / missing user) |
+| `modelName` | string, required, indexed | |
+| `recordId` | string, indexed | |
+| `recordLabel` | string | Short label (admin list fields / `title` / `name` / `email`) |
+| `organizationId` | string, indexed | Optional |
+| `verb` | `created` \| `updated` \| `deleted`, indexed | Widget-compatible |
+| `operation` | string, required | Fine-grained verb |
+| `source` | `admin` \| `modelRouter` \| `rbac`, indexed | |
+| `before` / `after` | Mixed | Changed fields only, redacted |
+| `created` / `updated` | dates | `createdUpdatedPlugin`; no `isDeletedPlugin` (append-only) |
+
+Indexes: `{created: -1}`, `{modelName: 1, recordId: 1, created: -1}`. Optional TTL on `created` when `retentionDays > 0`. Every field has `description`. Five-type pattern co-located with the schema. `strict: "throw"`.
+
+HTTP: `create`/`update`/`delete` empty permission arrays. No public POST/PATCH/DELETE even for admins. Denied list/create (including non-admin GET list) returns **405**, matching `permissionMiddleware`; instance-level denials after a loaded document remain **403**.
+
+## APIs
+
+| Method | Path | Who | Behavior |
+| --- | --- | --- | --- |
+| GET | `/audit-events` | IsAdmin | Paginated list, default sort `-created`, `queryFields`: `modelName`, `recordId`, `actorId`, `verb`, `source`, `organizationId` |
+| GET | `/audit-events/:id` | IsAdmin | Read one |
+| POST/PATCH/DELETE | `/audit-events` | — | Disabled |
+
+Admin mounts the same model via `adminContribution` (or example registers it once — do **not** double-mount). Route path includes `audit-log` **or** model name `AuditEvent` so `AdminShell.isAuditLogModel` lifts it into Platform.
+
+RBAC helper `persistRbacAuditToAuditEvent(model)` returns an `RbacAuditSink`. Built-in `RbacAudit` collection unchanged.
+
+## Notifications
+
+None.
+
+## UI
+
+Reuse Platform Audit Log + `RecentActivityWidget`. Update `isAuditLogModel` to match `AuditEvent` (keep `AdminAuditLog` and `audit-log` path for leftover apps). List columns: `created`, `verb`, `modelName`, `recordLabel`, `actorId`. Detail form is read-only; show `before`/`after` as JSON (existing object field rendering is enough). No new custom screen.
+
+example-backend: register `AuditApp`, enable `audit: true` on `Todo`, drop `AdminAuditLog` model and `onAdminAudit` persistence (optional `onAdminAudit` may remain no-op or be removed). Point home `recentActivity` at `AuditEvent`. RBAC `auditSink` uses the helper. Scripts that count/wipe `AdminAuditLog` switch to `AuditEvent` (wipe only in test/dev scripts — production HTTP still cannot delete).
+
+## Docs in this slice
+
+| Page | Change |
+| --- | --- |
+| `docs/how-to/audit-log.md` | **New.** Enable `AuditApp`, per-router `audit`, AdminApp auto-write, redaction, TTL, append-only, org field. |
+| `docs/reference/api.md` | `AuditApp`, `audit` option, `persistRbacAuditToAuditEvent`, no default-connection model. |
+| `docs/explanation/admin-interface.md` | Platform Audit Log is `AuditEvent` when `AuditApp` is registered. |
+| `docs/reference/admin-backend.md` | `onAdminAudit` is extra; framework write when `AuditApp` present. |
+| `docs/explanation/roadmap-seed-issues.md` | IP + task URLs; soft org depend. |
+| `docs/implementationPlans/b2b-platform-program.md` | Row for this IP. |
+| `.rulesync/rules/api/00-api.mdc` | AuditApp + `audit` option. |
+| `CHANGELOG.md` | Added opt-in framework audit log. |
+
+## Testing
+
+Tracer: `TerrenoApp` + `AuditApp` + test model with `audit: true` → authenticated PATCH changes `title` → `GET /audit-events` as admin returns one row with `verb: "updated"`, `before.title` / `after.title`, no `password` if present.
+
+Cases:
+
+- Plugin omitted: `audit: true` does not throw on CRUD; no collection on default connection; error logged once.
+- Create/update/delete each write one event; actorId matches `req.user`.
+- Unchanged fields absent from `before`/`after`.
+- Default redact list strips secrets even if not in `redact`.
+- Per-router `redact: ["ssn"]` strips `ssn`.
+- Array push writes `operation: "arrayPush"`, `verb: "updated"`.
+- Admin POST writes `source: "admin"` without `onAdminAudit`.
+- `onAdminAudit` still fires when both configured; mutation 201 if either sink throws.
+- AuditEvent HTTP POST is 404/not registered; PATCH/DELETE disabled.
+- `organizationId` copied from document; from `req.organization` when set.
+- `retentionDays` omitted: no TTL index. `retentionDays: 1`: TTL index present (assert index spec; do not sleep a day).
+- Example RBAC role change fans into `AuditEvent` with `source: "rbac"`.
+- Existing `onAdminAudit` tests stay green (best-effort extra sink).
+- Admin frontend: `isAuditLogModel` true for `AuditEvent`; Recent Activity still skips when no audit model.
+
+Skills: `terreno-backend-api`, `mongoose-schema-safety`, `backend-test-env` (if tests touch env), `building-admin-interfaces`, `verify-ui-changes` (example `/admin` audit log after Todo/admin mutation), `update-docs`, `generate-sdk` if example OpenAPI admin SDK lists the new route.
+
+## Risks
+
+| Risk | Mitigation |
+| --- | --- |
+| Write volume / PII | Opt-in per router; redaction; append-only HTTP. |
+| Missing plugin | No-op + once-per-process error; docs. |
+| Example `AdminAuditLog` break | Replace in the same slice; shell still matches old name. |
+| TTL index change later | How-to: drop old TTL index when changing `retentionDays`. |
+| Sync bypass | Documented non-goal; follow-up IP. |
+| Org filter incomplete | Field stored; list filter is `org-management-ui`. |
+
+## Phases
+
+1. Tracer: model + `AuditApp` + `audit: true` create/update/delete + list/read API + redaction.
+2. Array mutations + `organizationId`.
+3. AdminApp auto-write + example migration + shell matcher + RBAC helper.
+4. Optional TTL.
+5. Docs, changelog, rulesync, seed, B2B table.
+
+## Feature Flags & Migrations
+
+No feature flag. New collection. example-backend drops `AdminAuditLog` (example-only; no published schema). Apps that copied `AdminAuditLog` keep it until they register `AuditApp`.
+
+## Activity Log & User Updates
+
+This IP **is** the activity log. No `UserUpdate` spam.
+
+## Not Included / Future Work
+
+- Org-admin scoped list (`org-management-ui`).
+- Sync-path audit.
+- Auth / login events.
+- SIEM export, legal hold, immutable object storage.
+- Custom diff UI beyond JSON fields.
+
+## Files to Create / Modify
+
+| File | Role |
+| --- | --- |
+| `api/src/audit/*` | Model, recorder, diff/redact, `AuditApp`, tests |
+| `api/src/api.ts` | `audit` option + post hooks |
+| `api/src/index.ts` | Exports |
+| `admin-backend/src/adminApp.ts` | Auto-write when recorder present |
+| `admin-frontend/src/AdminShell.tsx`, `AdminHome.tsx` | `isAuditLogModel` |
+| `example-backend/src/server.ts`, `access.ts`, models, scripts | `AuditApp`; drop `AdminAuditLog` |
+| Docs listed above | Same slice |
+
+## Task List
+
+[docs/tasks/framework-audit-log.md](../tasks/framework-audit-log.md)
+
+## Acceptance Criteria
+
+- [ ] `AuditApp` omitted: no `AuditEvent` on the default connection; product CRUD unchanged.
+- [ ] `audit: true` + `AuditApp`: create/update/delete persist one event with actor, model, record, changed-field diff, redacted secrets.
+- [ ] HTTP `/audit-events` is list+read for admin only; create/update/delete disabled.
+- [ ] Admin mutations write `AuditEvent` when the plugin is registered, without requiring `onAdminAudit`.
+- [ ] `onAdminAudit` still runs as an extra best-effort sink.
+- [ ] example-backend Platform Audit Log and Recent Activity read `AuditEvent`; `AdminAuditLog` removed.
+- [ ] RBAC `auditSink` helper writes `source: "rbac"` without dropping `RbacAudit`.
+- [ ] Default: no TTL. `retentionDays > 0` adds TTL on `created`.
+- [ ] How-to + api reference + admin explanation match the shipped design.
+- [ ] Merging the implementation PR closes https://github.com/FlourishHealth/terreno/issues/1186 (`Fixes #1186`).

package/src/docs/versioned/next/implementationPlans/gpt-chat-mascot.md

@@ -0,0 +1,40 @@
+# GPTChat optional mascot
+
+**Status:** Complete  
+**Branch:** `cursor/gpt-chat-mascot-d39f`  
+**Owner:** cloud agent  
+**Created:** 2026-09-15
+
+## Goal
+
+Let consuming apps brand the GPT screen with their own mascot. Terreno does not ship a default character.
+
+## Non-Goals
+
+- Bundling artwork, Lottie files, or a Terreno fox in `@terreno/ui`
+- Animating the mascot from `isStreaming` inside GPTChat (consumers wrap their own node)
+- Showing the mascot beside assistant bubbles
+
+## Decisions
+
+| Question | Decision |
+|----------|----------|
+| Who owns the asset? | Consumer. `mascot?: React.ReactNode` |
+| When is it visible? | Only while `currentMessages.length === 0` |
+| Default? | Omitted — existing empty chat unchanged |
+
+## UI
+
+`GPTChat` empty-state hero: optional mascot slot, then existing suggested prompts.
+
+## Task List
+
+[docs/tasks/gpt-chat-mascot.md](../tasks/gpt-chat-mascot.md)
+
+## Acceptance Criteria
+
+- [ ] Omitting `mascot` leaves the empty chat unchanged
+- [ ] Passing `mascot` shows it on an empty chat, including with suggested prompts
+- [ ] Messages hide the mascot
+- [ ] Demo story and example app show a consumer node
+- [ ] Docs describe the optional slot

package/src/docs/versioned/next/implementationPlans/job-queues.md

@@ -0,0 +1,330 @@
+# Implementation Plan: Durable background jobs (`@terreno/jobs`)
+
+**Status:** Complete — 2026-09-10  
+**Branch:** `cursor/durable-background-jobs-803d`  
+**Owner:** —  
+**Created:** 2026-09-10  
+**Approved:** 2026-09-10  
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1188 (this feature **closes** that issue; implementation PRs use `Fixes #1188`)  
+**Task list:** [job-queues.md](../tasks/job-queues.md)  
+**Depends on:** —  
+**RTK deprecation flag:** Partial — admin screens use generated SDK / `useAdminApi`  
+**Program:** [B2B platform](b2b-platform-program.md)  
+
+## Goal
+
+Terreno apps can enqueue named jobs that survive process restarts: retries with
+backoff, delayed and recurring schedules, dead-lettering, and an admin operations
+UI. Persistence and the default worker are **Mongo**. Execution is a pluggable
+`JobRunner` so the same job definitions run in-process, in a standalone worker,
+on **GCP Cloud Tasks**, on **Vercel Queues**, or on a custom runner. Comms,
+webhooks, and billing stay on their current paths; this IP ships the queue they
+will enqueue onto later.
+
+## Non-Goals
+
+- BullMQ, Redis, or any Redis-backed queue.
+- Vercel Workflows (`"use workflow"` / `"use step"`).
+- Migrating `@terreno/comms` sends, Expo receipt polling, `WebhooksApp`
+  200-then-queue dispatch, or `@terreno/billing` sync onto the queue.
+- Replacing or merging `BackgroundTask` / admin **scripts**.
+- Changing in-process `cronjob()` behavior (hard-coded `America/Chicago`).
+- Live GCP or Vercel integration tests in CI.
+- Generic `modelRouter` CRUD as the operator UI.
+
+## Decisions
+
+| Question | Decision |
+|----------|----------|
+| Package | New workspace package **`@terreno/jobs`**. `JobsApp` implements `TerrenoPlugin`. |
+| Persistence | Mongo collections owned by this package. Default runner claims work from Mongo. |
+| `BackgroundTask` | Unchanged. Scripts stay in-process bookkeeping. Jobs are a separate `Job` model. |
+| v1 consumers | Framework + example only. Public `enqueue` is the seam later IPs call. |
+| Workers | **Both:** `jobs.startWorker()` in the API process **or** a dedicated worker process. Explicit opt-in; registering `JobsApp` does not start a poll loop. |
+| Schedules | Delayed `runAt` and recurring cron. Timezone is an **IANA** string on each schedule (default **`UTC`**). |
+| Cloud dispatch | **GCP Cloud Tasks** and **Vercel Queues** adapters (mocked-SDK tests). Custom `JobRunner` is a first-class type. |
+| Vercel product | **Queues** only. Job catalog and admin stay in Terreno. |
+| Execute HTTP | `POST {basePath}/execute` for GCP/custom HTTP push (GCP: OIDC). Vercel uses private `handleCallback` consumers → `executeJobById`. Mongo runner does **not** mount execute unless a cloud/custom runner needs it. |
+| Admin UI | Custom screen `jobs` (comms pattern): list/filter, detail/attempts, retry, DLQ requeue, cancel. Home widget. example-frontend + admin-spa. |
+| Existing `cronjob()` | Leave it. Docs call it process-local. Durable work uses `JobsApp`. |
+| Delivery | At-least-once. Handlers must be idempotent. Optional `idempotencyKey` unique with `name`. |
+| Payload | JSON-serializable only. Admin redacts by default (`redactPayload`). |
+| Recurring overlap | One in-flight instance per schedule `name`; skip the tick if still running. |
+
+## Architecture
+
+```
+@terreno/jobs
+  JobsApp (TerrenoPlugin)
+    define(name, {handler, retry, schedule?})
+    enqueue({name, payload, runAt?, idempotencyKey?})
+    startWorker()                    // Mongo poll / runner.start
+    adminContribution() → screen "jobs"
+    optional POST /jobs/execute      // cloud/custom HTTP
+
+JobRunner
+  enqueue(job) → dispatch
+  start?(signal) → local poll (Mongo)
+  stop?()
+
+MongoJobRunner     — claim via findOneAndUpdate; lock TTL
+GcpCloudTasksRunner — create HTTP task → POST /jobs/execute (OIDC)
+VercelQueuesRunner  — send(topic,{jobId}) → private handleCallback consumer → executeJobById
+Custom              — app-supplied JobRunner
+```
+
+```typescript
+import {JobsApp, MongoJobRunner, getJobsService} from "@terreno/jobs";
+
+const jobs = new JobsApp({
+  runner: new MongoJobRunner(),
+  timezone: "UTC",
+});
+
+jobs.define("send-welcome-email", {
+  handler: async (payload, ctx) => {
+    ctx.log.info("sending");
+    // work
+  },
+  retry: {maxAttempts: 5, backoffMs: 1000},
+});
+
+new TerrenoApp({userModel: User}).register(jobs);
+
+// Explicit — API process or a worker entrypoint
+await jobs.startWorker();
+
+await getJobsService().enqueue({
+  name: "send-welcome-email",
+  payload: {userId: "..."},
+});
+```
+
+Standalone worker (example-backend): same `JobsApp` definitions, `build()` without
+`listen`, then `startWorker()`. Do not start two poll loops against the same
+queue unless lock TTL and claim are in place (they are).
+
+### Claim (Mongo)
+
+`findOneAndUpdate` where `status` is `pending` or `scheduled`, `runAt <= now`,
+and `lockedAt` is missing or older than `lockTtlMs` (default 15 minutes). Set
+`status: "running"`, `lockedAt`, `lockedBy` (hostname + pid). On success, wrap
+`runWithRequestContext({jobId})`. On handler success → `completed`. On throw →
+increment `attemptCount`, set `lastError`, either `pending` with `runAt` backoff
+or `dead` when `attemptCount >= maxAttempts`.
+
+### Retry
+
+Exponential backoff from `retry.backoffMs` (default 1000) with jitter, cap
+`retry.maxBackoffMs` (default 15 minutes). `maxAttempts` default 5. Dead-letter
+status is **`dead`**. Admin **Retry** enqueues a new `Job` (`retriedFromId`);
+**Requeue DLQ** resets the same row to `pending` with `runAt: now` and clears
+the lock.
+
+### Recurring
+
+`define(name, {schedule: {cron, timezone?}})` upserts a `JobSchedule` row.
+The worker ticks due schedules and `enqueue`s a child `Job` with
+`scheduleId`. Timezone defaults to `JobsApp` `timezone` then `UTC`. Invalid cron
+fails `define` / startup, not silently.
+
+### `JobRunner`
+
+```typescript
+interface JobRunner {
+  readonly id: string;
+  enqueue(job: JobDocument): Promise<void>;
+  start?(options: {jobs: JobsApp; signal: AbortSignal}): Promise<void>;
+  stop?(): Promise<void>;
+}
+```
+
+Mongo `enqueue` only persists (already saved) then no-ops dispatch — the poller
+picks it up. Cloud runners persist then create a platform task whose HTTP body
+is `{jobId}` (not the payload). Execute loads the Mongo row, claims if needed,
+runs the handler.
+
+GCP and Vercel SDKs are **optional peers** on subpath exports
+(`@terreno/jobs/runners/gcpCloudTasks`, `@terreno/jobs/runners/vercelQueues`).
+Core `@terreno/jobs` has zero cloud SDKs. Tests inject fakes.
+
+### Execute HTTP
+
+Mounted only when `JobsApp` `mountExecuteRoute: true` or the runner requests it
+(GCP default true; Vercel uses private `handleCallback` consumers; Mongo default false).
+
+| Status | When |
+|--------|------|
+| 200 | Handler finished (success or recorded failure/dead) |
+| 401 | Missing/invalid OIDC or platform signature |
+| 404 | Unknown `jobId` |
+| 409 | Job already `completed` / `cancelled` (idempotent no-op 200 preferred for provider retries — **200** if terminal success; **409** only if still `running` under a live lock) |
+
+Do not skip rate limiting on this path. Do not add it to generated SDK consumer
+hooks (admin uses dedicated jobs routes). OpenAPI: document execute as
+internal/operator; omit from public SDK codegen if tagged internal.
+
+### Logging
+
+`createScopedLogger({prefix: "[Job]", labels: {jobName, jobId}})`. Never log
+full payloads or secrets. Correlation: `runWithRequestContext({jobId})`.
+
+## Models
+
+Five-type pattern, field `description`s, `createdUpdatedPlugin`. **No**
+`isDeletedPlugin` on live queue rows (use `cancelled`). Not `modelRouter`
+models.
+
+**Job** — `name` (string, indexed), `payload` (Mixed), `status` (`pending` \|
+`scheduled` \| `running` \| `completed` \| `failed` \| `cancelled` \| `dead`),
+`runAt` (date, indexed), `attemptCount` (number), `maxAttempts` (number),
+`lockedAt` / `lockedBy`, `lastError`, `attempts[]` (`{at, error, errorClass}`),
+`scheduleId` (optional ref), `idempotencyKey` (optional), `retriedFromId` /
+`retriedById`, `payloadRedacted` (boolean). Unique sparse index
+`(name, idempotencyKey)`. Compound index `(status, runAt)`.
+
+**JobSchedule** — `name` (unique), `cron`, `timezone`, `nextRunAt`, `enabled`,
+`handlerName` (= `name`).
+
+## APIs
+
+Default `basePath` `/jobs`. Admin routes require `admin:access` plus
+`admin:jobs` when `accessControl` is configured; legacy `user.admin` when not.
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| GET | `/jobs` | Paginated list: `name`, `status`, `scheduleId`, date range, `q` |
+| GET | `/jobs/:id` | Detail: attempts, redacted payload, lock |
+| POST | `/jobs/:id/retry` | New job from payload; original `retriedById` |
+| POST | `/jobs/:id/requeue` | DLQ/`failed`/`cancelled` → `pending` now |
+| POST | `/jobs/:id/cancel` | `pending`/`scheduled`/`running` → `cancelled` (handler `ctx.signal`) |
+| GET | `/jobs/schedules` | Defined schedules + next run |
+| POST | `/jobs/schedules/:name/pause` | `enabled: false` |
+| POST | `/jobs/schedules/:name/resume` | `enabled: true` |
+| POST | `/jobs/execute` | Cloud/custom HTTP execute (not admin session) |
+
+Enqueue from app code only (`getJobsService().enqueue`). No public
+`POST /jobs` create for arbitrary names from the browser.
+
+## Notifications
+
+None. Failures are `Job` rows + `logger`. Downstream comms can `enqueue` later.
+
+## UI
+
+`JobsApp.adminContribution()`: custom screen `name: "jobs"`, display **Jobs**,
+icon `clock`. Built-in widget in `@terreno/admin-frontend` (`JOBS_ADMIN_WIDGETS`)
+so hosts do not re-map (comms pattern).
+
+| Piece | Role |
+|-------|------|
+| `JobsDashboardScreen` | Filters + table + pause/resume schedules |
+| `JobsJobDetail` | Attempts, error, retry / requeue / cancel |
+| Home widget `jobs` | Counts of `dead` + `running`; link to screen |
+
+example-frontend: `/admin/jobs`, `/admin/jobs/[id]`.  
+admin-spa: `/jobs`, `/jobs/[id]`.  
+`verify-ui-changes` on the example admin.
+
+RBAC: add `jobs` to `terrenoStatements.admin` (alongside `runScripts`).
+
+## Phases
+
+1. **Tracer:** package, `define`/`enqueue`, Mongo claim, `startWorker`, one example job.
+2. **Reliability:** retries, DLQ, lock TTL, cancel signal, delayed `runAt`, cron schedules.
+3. **Runners:** `JobRunner`, custom fake, GCP Cloud Tasks, Vercel Queues, execute HTTP.
+4. **Admin:** routes + UI + example + spa.
+5. **Docs + publish:** Diátaxis, changelog, CI, `publish-on-tag`, seed/positioning.
+
+## Feature Flags & Migrations
+
+New collections only. No user-data migration. Opt-in: apps that never register
+`JobsApp` are unchanged.
+
+## Activity Log & User Updates
+
+Each attempt is on `Job.attempts`. No end-user notifications.
+
+## Not Included / Future Work
+
+- Comms automatic scheduled retries (`comms-abstraction` / admin dashboard).
+- Webhook 200-then-queue (`inbound-webhooks`).
+- Billing Stripe handler offload (`billing-stripe`).
+- Vercel Workflows runner.
+- Redis/BullMQ runner.
+- Per-queue concurrency caps / rate limits beyond claim locks.
+- Streaming logs over sockets (poll admin GET).
+
+## Docs in this slice
+
+| Page | Change |
+|------|--------|
+| `docs/how-to/background-jobs.md` | **New.** Define, enqueue, worker vs API, Mongo vs GCP vs Vercel, execute auth, idempotency. |
+| `docs/reference/jobs.md` | **New.** Options, models, routes, runners, env. |
+| `docs/how-to/README.md` | Link the how-to. |
+| `docs/reference/api.md` | Contrast `cronjob()` / `wrapScript` as process-local. |
+| `docs/reference/environment-variables.md` | Jobs / Cloud Tasks / Vercel / execute audience. |
+| `docs/how-to/admin-import-prebuilt.md` | `JobsApp` screen `jobs`. |
+| `docs/explanation/roadmap-seed-issues.md` | IP + task URLs; `IP=job-queues`. |
+| `docs/explanation/positioning.md` | Celery/ActiveJob row → shipped via `@terreno/jobs` when Complete. |
+| `changelog/unreleased/job-queues.md` | Added. |
+| `.rulesync/rules/jobs/00-jobs.md` | Package rule; `bun run rules` / `skills:sync`. |
+| `.rulesync/skills/terreno-backend-api/SKILL.md` | Jobs vs scripts vs cron. |
+
+## Testing
+
+Bun + `@terreno/test` Mongo. Do not mock `@terreno/api` or models. Cloud adapters:
+inject fake Task/Queue clients. Execute route: signed vs unsigned. Claim: two
+workers cannot run the same job. Restart: `running` with expired lock is
+reclaimed. Recurring: timezone `America/New_York` vs `UTC` tick. Admin: 403
+without `admin:jobs`. UI: `verify-ui-changes`.
+
+## Files to Create / Modify
+
+- `jobs/` — new package (models, service, runners, routes, tests)
+- Root `package.json` workspace + `jobs:*` scripts
+- `api/src/rbac/statements.ts` — `admin: ["access", "runScripts", "viewBackgroundTasks", "jobs"]`
+- `admin-frontend` — jobs screens + widgets + tests
+- `admin-spa` — routes
+- `example-backend` — `JobsApp` + worker entry + demo job
+- `example-frontend` — admin routes + SDK regen if jobs admin paths are OpenAPI
+- `.github/workflows/jobs-ci.yml`, `publish-on-tag.yml`, `cd.yml` path filters
+- Docs/rules/changelog as in the table
+
+## Task List
+
+See [docs/tasks/job-queues.md](../tasks/job-queues.md).
+
+## Acceptance Criteria
+
+- [x] `enqueue` then kill the Node process; a new `startWorker()` runs the job.
+      Verified by bun test that simulates crash by leaving `pending` and starting
+      a second worker.
+- [x] Handler throw retries until `maxAttempts` then `status: "dead"`. Admin
+      requeue returns it to `pending` and the worker runs it. Verified by bun tests
+      + admin UI verification.
+- [x] Delayed `runAt` in the future is not claimed early; cron in a named IANA
+      timezone fires `nextRunAt` correctly. Verified by bun tests with frozen clocks
+      (Luxon).
+- [x] Two overlapping `startWorker()` loops claim a job once. Verified by bun test.
+- [x] Custom `JobRunner` receives `enqueue`; GCP and Vercel adapters create a
+      mocked platform task and `POST /jobs/execute` with valid auth runs the
+      handler, invalid auth 401. Verified by bun tests (no live cloud).
+- [x] Admin Jobs screen lists jobs, opens detail, retries, requeues DLQ, cancels.
+      Verified by `verify-ui-changes` artifacts.
+- [x] Apps without `JobsApp` behave as today (`cronjob`, scripts). Verified by
+      existing api/admin-backend tests remaining green.
+- [x] How-to + jobs reference match the shipped API. Verified in Roast;
+      `bun run website:build` on the docs task.
+
+## Named assumptions
+
+1. Handlers are registered in every process that executes jobs (API and worker).
+2. JSON payloads only; no Buffer/stream jobs in v1.
+3. Unique `(name, idempotencyKey)` makes duplicate enqueue a no-op returning the
+   existing row.
+4. `failed` is a transient row state between attempts if we surface it; terminal
+   exhaustion is `dead`. Pick may use `pending` between retries only — then omit
+   `failed` as terminal. Prefer **pending-with-future-`runAt`** between attempts
+   and **`dead`** at exhaustion so the admin filter is simple.
+5. Positioning Celery row updates when the IP is **Complete**, not while Draft.