@terreno/mcp 57.3.0 → 57.4.0

package/src/docs/versioned/next/reference/jobs.md

@@ -0,0 +1,319 @@
+# @terreno/jobs
+
+Durable background jobs plugin for `@terreno/api`. Persists work in MongoDB, runs handlers
+with retries and schedules, and supports pluggable dispatch (`MongoJobRunner`, GCP Cloud
+Tasks, Vercel Queues, custom).
+
+Operator guide: [Durable background jobs](../how-to/background-jobs.md).
+
+## Install
+
+```bash
+bun add @terreno/jobs
+```
+
+Peers: `mongoose ^8.0.0 || ^9.0.0`; optional `@google-cloud/tasks`, `@vercel/queue`.
+
+## Package exports
+
+| Import | Contents |
+| --- | --- |
+| `@terreno/jobs` | `JobsApp`, `getJobsService`, `tryGetJobsService`, `unregisterJobsService`, `Job`, `JobSchedule`, types, `MongoJobRunner` |
+| `@terreno/jobs/runners/gcpCloudTasks` | `GcpCloudTasksRunner`, client seams |
+| `@terreno/jobs/runners/vercelQueues` | `VercelQueuesRunner`, `createVercelQueuesConsumer`, limits/helpers |
+
+## JobsApp
+
+`JobsApp` implements `TerrenoPlugin` and `JobsRunnerHost`.
+
+### Options (`JobsAppOptions`)
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `basePath` | `"/jobs"` | Admin routes and execute route prefix |
+| `runner` | `MongoJobRunner` | Dispatch + optional poll loop |
+| `timezone` | `"UTC"` | Default IANA zone for schedules without `schedule.timezone` |
+| `lockTtlMs` | `900_000` (15 min) | Stale `lockedAt` reclaim threshold |
+| `pollIntervalMs` | `1_000` | Mongo runner idle sleep between polls |
+| `accessControl` | — | Terreno RBAC; jobs admin needs `admin:access` **and** `admin:jobs` |
+| `redactPayload` | — | Admin payload projection hook (see below) |
+| `mountExecuteRoute` | `false` | Force `POST {basePath}/execute` |
+| `executeAuth` | — | Required when execute route is mounted |
+
+Execute route mounts when `mountExecuteRoute: true` **or** `runner.requiresExecuteRoute === true`.
+
+### Methods
+
+| Method | Description |
+| --- | --- |
+| `define(name, definition)` | Register handler, retry, and optional schedule |
+| `register(app, openApi?)` | Mount admin + execute routes; register `JobsService` |
+| `startWorker()` | Start runner `start()` (fire-and-forget); reconciles schedules first |
+| `stopWorker()` | Abort signal + `runner.stop()` |
+| `executeQueuedJob(jobId, signal?)` | Run by id (queue consumer / tests) |
+| `adminContribution()` | Admin screen + home widget metadata |
+
+## JobDefinition
+
+```typescript
+interface JobDefinition {
+  handler: (payload: unknown, ctx: JobHandlerContext) => Promise<void>;
+  retry?: {
+    backoffMs?: number;      // default 1_000
+    maxAttempts?: number;    // default 5
+    maxBackoffMs?: number;   // default 900_000
+  };
+  schedule?: {
+    cron: string;
+    timezone?: string;       // IANA; falls back to JobsApp timezone
+  };
+}
+```
+
+`JobHandlerContext`: `{jobId, log: ScopedLogger, signal: AbortSignal}`.
+
+## Enqueue (`EnqueueJobParams`)
+
+| Field | Required | Description |
+| --- | --- | --- |
+| `name` | yes | Registered handler name |
+| `payload` | yes | JSON-serializable mixed |
+| `runAt` | no | Earliest claim time (default now, UTC) |
+| `idempotencyKey` | no | Dedupes per `name` |
+| `scheduleId` | no | Set by scheduler for cron children |
+
+`getJobsService().enqueue(...)` after `JobsApp.register()`. `tryGetJobsService()` returns
+`undefined` when `JobsApp` is not mounted. `unregisterJobsService()` clears the process
+singleton (tests).
+
+### Admin scripts (`admin/script`)
+
+`@terreno/admin-backend` `defineAdminScriptJob` registers handler name `admin/script` with
+`retry.maxAttempts: 1`. Payload: `{scriptName, taskId, wetRun, args, createdByName?}`.
+The Scripts UI still polls `BackgroundTask` by `taskId`. Without `JobsApp`, script HTTP
+runs stay in-process.
+
+## JobRunner
+
+```typescript
+interface JobRunner {
+  readonly id: string;
+  readonly requiresExecuteRoute?: boolean;
+  enqueue(job: JobDocument): Promise<void>;
+  start?(options: JobRunnerStartOptions): Promise<void>;
+  stop?(): Promise<void>;
+}
+```
+
+Built-in ids: `mongo`, `gcp-cloud-tasks`, `vercel-queues`.
+
+## Job model (`Job`)
+
+| Field | Default | Description |
+| --- | --- | --- |
+| `name` | — | Handler name (indexed) |
+| `status` | — | See statuses below |
+| `payload` | — | Handler input |
+| `payloadRedacted` | `false` | Admin omission flag |
+| `runAt` | — | Earliest claim (indexed) |
+| `attemptCount` | `0` | Executions so far |
+| `attempts` | `[]` | `{at, error?, errorClass?}` |
+| `maxAttempts` | `5` | From definition at enqueue |
+| `backoffMs` | `1_000` | Retry base |
+| `maxBackoffMs` | `900_000` | Retry cap |
+| `lastError` | — | Latest failure message; `$unset` when the job completes |
+| `lockedAt` / `lockedBy` | — | Claim lease |
+| `idempotencyKey` | — | Partial unique with `name` |
+| `scheduleId` | — | Parent schedule ref |
+| `retriedFromId` / `retriedById` | — | Admin retry linkage |
+| `created` / `updated` | plugins | Timestamps |
+
+Indexes: `(name, idempotencyKey)` partial unique; `(status, runAt)`; `(scheduleId, status)`.
+
+### Statuses
+
+| Status | Meaning |
+| --- | --- |
+| `pending` | Waiting for `runAt`; claimable |
+| `running` | Claimed; handler executing |
+| `scheduled` | Reserved in schema / in-flight filter |
+| `completed` | Success |
+| `dead` | Exhausted `maxAttempts` |
+| `failed` | No handler registered at run time |
+| `cancelled` | Admin cancel |
+
+### Retry backoff
+
+`computeRetryDelayMs`: `backoffMs * 2^(attemptCount-1)`, capped at `maxBackoffMs`, × equal jitter in `[0.5, 1.0)`.
+
+### Claim / lock
+
+`createClaimLock` sets `lockedAt`, `lockedBy` (worker id). Claims match `status ∈ {pending,running,scheduled}`, `runAt <= now`, and expired or missing lock. `executeJobById` returns `noop` for terminal rows, `409` conflict for live lock or not-due.
+
+## JobSchedule model
+
+| Field | Default | Description |
+| --- | --- | --- |
+| `name` | — | Unique; matches `define` name |
+| `handlerName` | — | Same as `name` |
+| `cron` | — | Standard cron expression |
+| `timezone` | `UTC` | IANA zone |
+| `enabled` | `true` | Pause via admin API |
+| `nextRunAt` | — | Next tick (UTC instant) |
+
+## HTTP routes
+
+Base: `{basePath}` (default `/jobs`). All admin routes require auth + jobs admin permission.
+
+| Method | Path | Description |
+| --- | --- | --- |
+| GET | `/jobs` | Paginated list (`page`, `limit`, `name`, `status`, `scheduleId`, `start`, `end`, `q`) |
+| GET | `/jobs/stats` | Counts by status |
+| GET | `/jobs/:id` | Detail |
+| POST | `/jobs/:id/retry` | New linked row from `dead` / `failed` |
+| POST | `/jobs/:id/requeue` | Reset same row from `dead` / `failed` / `cancelled` |
+| POST | `/jobs/:id/cancel` | Cancel `pending` / `running` / `scheduled` |
+| GET | `/jobs/schedules` | All schedules |
+| POST | `/jobs/schedules/:name/pause` | `enabled: false` |
+| POST | `/jobs/schedules/:name/resume` | `enabled: true` |
+| POST | `/jobs/execute` | Internal dispatch (`{jobId}`); `executeAuth` required |
+
+List defaults: `limit` 50, max 200. Execute uses 30-minute handler timeout.
+
+### RBAC
+
+When `accessControl` is configured, every jobs admin route checks **both**
+`admin:access` and `admin:jobs` (`accessControl.can({permissions: {admin: ["access", "jobs"]}})`).
+Default `terrenoStatements.admin` includes both actions. When `accessControl` is omitted,
+routes fall back to legacy `user.admin === true`.
+
+### Admin payload redaction
+
+`JobsAdminRedactPayload`:
+
+```typescript
+type JobsAdminRedactPayload = (input: {
+  name: string;
+  payload: unknown;
+  payloadRedacted: boolean;
+}) => unknown | undefined;
+```
+
+**Default (omit hook):** `payload` is not included in admin list/detail JSON.
+
+**Opt-in projection** — return only fields operators need; raw identity passthrough is
+discouraged:
+
+```typescript
+new JobsApp({
+  redactPayload: ({name, payload}) => {
+    if (name === "billing/capture") {
+      return {invoiceId: (payload as {invoiceId?: string}).invoiceId};
+    }
+    return undefined; // hide unknown job types
+  },
+});
+```
+
+Return `undefined` to hide payload for a row. `payloadRedacted: true` on the document
+always hides payload regardless of the hook.
+
+## Admin frontend widgets
+
+`@terreno/admin-frontend` public exports for jobs:
+
+| Export | Role |
+| --- | --- |
+| `JOBS_ADMIN_WIDGETS`, `JobsDashboardScreenWidget` | Screen widget map (`jobs` → dashboard) |
+| `JOBS_HOME_WIDGETS`, `JobsHomeWidget` | Home widget (`dead` / `running` counts) |
+| `JobsDashboardScreen`, `JobsJobDetail` | Full screens (Expo admin routes) |
+| `JobsStatusBadge` | Status chip |
+| `canCancelJob`, `canRequeueJob`, `canRetryJob`, `formatJobTimestamp`, `jobRowId`, `unwrapJobRow` | Row helpers |
+| `JobRow`, `JobAttemptRow`, `JobScheduleRow`, `JobsStats` | Row/types for tables |
+| `JobsDashboardFilters`, `parseJobsDashboardSearchParams`, `serializeJobsDashboardSearchParams` | URL filter helpers |
+
+Widgets are registered in the built-in registry — enable via `JobsApp.adminContribution()` only.
+The admin shell lists Jobs under **Platform** (not Screens). Hosts still contribute
+`name: "jobs"`; do not add a second sidebar link.
+Custom screens should pass the app's generated RTK `api` into `AdminProvider`; jobs screens wire
+admin HTTP internally (not via a public `useJobsDashboardApi` export).
+
+## GCP Cloud Tasks (`@terreno/jobs/runners/gcpCloudTasks`)
+
+### `GcpCloudTasksRunnerConfig`
+
+| Field | Required | Description |
+| --- | --- | --- |
+| `project` | yes | GCP project id |
+| `location` | yes | Queue region |
+| `queue` | yes | Queue name |
+| `publicUrl` | yes | Absolute `http(s)` API origin (no trailing slash) |
+| `serviceAccountEmail` | yes | OIDC invoker SA |
+| `oidcAudience` | no | Defaults to execute URL |
+| `basePath` | no | Default `/jobs` |
+| `dispatchDeadlineSeconds` | no | Cloud Tasks HTTP wait before retry. Range 15–1800. Default **1800**. The runner sends protobuf `{seconds}` (what `@google-cloud/tasks` expects); REST encodes `"1800s"` so a 30-minute Cloud Run handler is not retried at the 10-minute HTTP default |
+| `client` | no | Injected Cloud Tasks client. Required in `bun build --compile` images (REST + `google-auth-library` in the example app). Optional peer `createRequire` fallback for Node. |
+
+Enqueue: `createTask` POST to `{publicUrl}{basePath}/execute`, body `{jobId}` base64,
+`dispatchDeadline` `{seconds: 1800}` by default (REST JSON `"1800s"`), `scheduleTime` when
+`runAt` is future.
+`requiresExecuteRoute: true`.
+`start()` ticks due Mongo schedules into `enqueue`; it does not claim job rows.
+
+**Operator responsibility:** implement `executeAuth` to verify the OIDC token (issuer,
+audience, SA email). `@terreno/jobs` does not ship a GCP verifier.
+
+## Vercel Queues (`@terreno/jobs/runners/vercelQueues`)
+
+### `VercelQueuesRunnerConfig`
+
+| Field | Default | Description |
+| --- | --- | --- |
+| `topic` | required | Queue topic name |
+| `region` | — | Optional send region |
+| `retentionSeconds` | `86400` | Min 60, max 604800 |
+| `send` | — | Test seam |
+
+Constants: `VERCEL_QUEUE_MAX_DELAY_SECONDS` = 604800 (7d); visibility retry clamp 30–3600s.
+
+Enqueue: `send(topic, {jobId}, {delaySeconds?, retentionSeconds?, idempotencyKey})`.
+`runAt` beyond 7 days throws `VercelQueueRunAtBeyondLimitError`.
+
+`createVercelQueuesConsumer({host, handleCallback?, signal?, visibilityTimeoutSeconds?})` wraps
+`@vercel/queue` `handleCallback` → `executeJobById`. `requiresExecuteRoute: false`.
+
+`vercel.json`: `"experimentalTriggers": [{"type": "queue/v2beta", "topic": "<topic>"}]`.
+
+## Environment variables
+
+`@terreno/jobs` uses **explicit constructor options**, not env readers.
+
+| Variable | Read by | Notes |
+| --- | --- | --- |
+| `JOBS_START_WORKER` | example-backend only | `true`/`false`; unset → `true`. Disable in API when running `jobs:worker`. |
+| `JOB_TRACE_LOGS` | app convention | Gates verbose worker logs via `createFeatureFlaggedLogger` (not read by jobs package) |
+
+Legacy `GCP_TASKS_NOTIFICATIONS_QUEUE` / `GCP_TASK_PROCESSOR_QUEUE` appear in example-backend **test** fixtures only — not used by `@terreno/jobs`. Configure Cloud Tasks via `GcpCloudTasksRunner` constructor args.
+
+## Process-local alternatives
+
+| API | Package | Durable | Use |
+| --- | --- | --- | --- |
+| `cronjob()` | `@terreno/api` | No | In-process recurring timer |
+| `wrapScript()` | `@terreno/api` | No | One-shot CLI / script wrapper |
+| `JobsApp` | `@terreno/jobs` | Yes | Retries, DLQ, schedules, admin, cloud dispatch |
+
+## Commands (monorepo)
+
+```bash
+bun run jobs:compile
+bun run jobs:lint
+bun run jobs:test
+bun run jobs:worker   # example-backend standalone worker
+```
+
+## Related
+
+- [Durable background jobs how-to](../how-to/background-jobs.md)
+- [API reference — wrapScript / cronjob](api.md#wrapscript)
+- [Environment variables](environment-variables.md#background-jobs)

package/src/docs/versioned/next/reference/legacy/rtk.md

@@ -2,7 +2,11 @@
 
 > **Deprecated for data synchronization.** `@terreno/rtk` remains published through the **56.x** line (and the stable **0.x** line) with a deprecation notice. It will **not** be published in the next major Terreno release. For collection reads/writes, offline sync, and realtime convergence, use [`@terreno/syncdb`](../syncdb.md) and the [migration guide](../../how-to/migrate-rtk-to-syncdb.md).
 >
-> RTK Query is still the correct tool for **non-synced** endpoints: generated OpenAPI hooks (`/auth/me`, admin RPC, AI routes), Better Auth session Redux wiring, feature flags, and sockets.
+> RTK Query remains the correct tool for **non-synced** generated OpenAPI routes
+> such as `/auth/me` and AI APIs, Better Auth session Redux wiring, feature
+> flags, and sockets. Built-in admin RPC uses host-bound fetch; ObjectId/API-only
+> admin CRUD keeps RTK compatibility in Terreno 57, then `useAdminApi` and the
+> required admin `api` prop are removed in Terreno 58.
 
 Redux Toolkit Query utilities for frontends using @terreno/api backends. JWT auth, token storage, SDK code generation from OpenAPI, and real-time WebSocket connections.
 

package/src/docs/versioned/next/reference/lifecycle-plugin.md

@@ -1,6 +1,6 @@
 # Lifecycle plugin reference
 
-Plugin: `terreno-planning` (`2.8.0`)
+Plugin: `terreno-planning` (`2.12.0`)
 
 Planning skills are model-invocable: agents may select them from descriptions, not only
 from slash commands. Grow, Brew, and Taste each implement one bounded transition. Pick continues an inner loop until the
@@ -10,11 +10,11 @@ loops that invoke those stages; they are not stages and must not appear as `stag
 
 | Skill | Preconditions | Primary output | PASS next |
 | --- | --- | --- | --- |
-| `terreno-1-grow` | request/spec + repository | approved IP/tasks + criterion/verification map | Pick (enters inner loop) |
+| `terreno-1-grow` | request/spec + repository | approved IP/tasks + criterion/verification map + standalone approval brief | Pick (enters inner loop) |
 | `terreno-2-pick` | approved task + branch/state | one implemented slice, then Roast, then the next task | Roast, or Brew when the list is done |
 | `terreno-3-roast` | Pick result + current diff | independent requirement/evidence verdict for the current task | emit Pick if tasks remain, else Brew; never invoke Pick; pass a task-scoped briefing; do not spawn two unconstrained reviewers |
 | `terreno-4-brew` | Roast PASS for every in-scope task + branch/evidence | pushed head + PR + product-CI trigger check + review-bot wait + attached evidence | Taste |
-| `terreno-5-taste` | PR + current state | one current-head reaction; before push: pull latest `master`, lint and typecheck in a no-context subagent, then watch CI | null or fresh Taste |
+| `terreno-5-taste` | PR + current state | one current-head reaction; before push: pull latest `master`, re-verify last-run failed tests locally, run root `prepush` when present (otherwise affected-package checks) in a no-context subagent, then watch CI | null or fresh Taste |
 
 Outer loops (not stages):
 
@@ -39,6 +39,8 @@ Results use `PASS`, `FAIL`, `BLOCKED`, or `PENDING` and the compact `v: 2` schem
 (`v`, `stage`, `status`, `next`, `action`; omit empty keys). Loop state follows
 [`execution-state.schema.json`](https://github.com/FlourishHealth/terreno/blob/master/plugins/terreno-planning/references/execution-state.schema.json).
 Chat and PRs show `status` / `next` / `action`; the YAML lives in a Details toggle.
+When the current PR has GitHub Deployments, those demo URLs are the last visible
+section of every wait-for-human or done chat.
 
 The outer loop owns state persistence, Taste `PENDING` reinvocation, Grow/Brew/Taste
 invocation, retries, and escalation. Pick owns the
@@ -49,9 +51,12 @@ until async review bots (Bugbot, CodeQL, and similar) on the current head have r
 preferring provider CLI watch hooks or harness event subscriptions over sleep polling.
 Taste then waits in a loop for product CI using GitHub CLI (`gh pr checks --watch`,
 `gh run watch`) or CircleCI CLI (`circleci run watch`) until jobs are terminal or the
-wait times out. Before any push, Taste always pulls latest `master`, then spawns a
-fresh subagent with no parent conversation to run lint, typecheck, and the locally
-affected tests in each affected package, then pushes and watches product CI.
+wait times out. Before any push, Taste always pulls latest `master`, records last-run
+failed tests and re-verifies them locally, then spawns a
+fresh subagent with no parent conversation. If the repository root defines a `prepush`
+package script, Taste runs it as the authoritative local gate; otherwise it falls back
+to lint, typecheck, and locally affected tests in each affected package. Taste then
+pushes and watches product CI.
 Taste observes product CI on every discovered host (GitHub Actions, CircleCI,
 Buildkite, and similar), not only GitHub checks. A documented not-applicable host
 counts as skipped; an unexplained untriggered host prevents Brew `PASS`. Brew still
@@ -66,11 +71,24 @@ docs, and risks, then presents that report once. It asks the human only
 for an actual product/architecture/security/data/destructive/policy decision or
 unreplaceable credential. Before asking, it gives the overall goal/state, completed
 work, decisive evidence, two to four options with impact, and a recommendation; the
-message ends with one exact question.
-
-GitHub communication follows a fixed attention budget: `Why`, `What changed`, and
-`Verification` are the only visible PR sections; optional detail is expandable; comments
-are reserved for blocked decisions or non-obvious review resolutions.
+message ends with one exact question, then PR deployment URLs when a PR has them.
+
+Grow's human-facing output is a standalone approval brief, not an index. It opens with a
+paragraph on where the repository is and where the change takes it, adds background on
+current state when a reviewer needs it, then the idea, then the plan (tasks, tracer,
+verification, out of scope, risks). A Decisions table follows the plan with no row cap,
+pairing every settled human decision with the question that prompted it; it is omitted
+when grilling settled none. Paths to the IP and task files come last.
+
+GitHub communication follows a fixed attention budget. The PR title is
+`[ticket] Short feature title` (Linear `TEAM-n` or GitHub `#n`; omit brackets when
+no ticket is attached) and names the feature only — never `feat:`, `IP Approved`,
+or `Task list`. `Why` preserves the IP's initial justification, `What changed`
+briefly describes the approved IP and intended outcomes, and `Verification` always
+contains reproducible testing instructions. Brew updates verification as testing
+changes but otherwise keeps the body stable instead of summarizing the latest turn.
+These are the only visible PR sections; optional detail is expandable; comments are
+reserved for blocked decisions or non-obvious review resolutions.
 
 Every stage follows the
 [documentation contract](https://github.com/FlourishHealth/terreno/blob/master/plugins/terreno-planning/references/documentation-contract.md):

package/src/docs/versioned/next/reference/mcp-server.md

@@ -107,7 +107,7 @@ Set `TERRENO_MCP_DOCS_DIR` environment variable to override default path.
 
 ## Tools
 
-Code generation tools that return TypeScript/JavaScript code as text. **Tools do not write files** — the AI assistant receives the code and writes it to appropriate locations.
+Code generation tools that return TypeScript/JavaScript code as text. They do not write files — the AI assistant receives the code and writes it to appropriate locations. Scaffold a new app with [`create-terreno-app`](create-terreno-app.md) (`bunx create-terreno-app`), not an MCP tool.
 
 ### terreno_search_docs
 
@@ -341,47 +341,6 @@ Validate a Mongoose schema against Terreno conventions.
 - Recommendations for fixes
 - Severity levels (error, warning, info)
 
-### terreno_bootstrap_app
-
-Scaffold a new full-stack Terreno application (Expo frontend, Express/Mongoose backend, Cursor rules, MCP settings).
-
-**Parameters:**
-
-``````typescript
-{
-  appName: string;           // kebab-case (e.g., "my-app")
-  appDisplayName: string;    // Human-readable name
-  description?: string;
-  mcpServerUrl?: string;     // Default: https://mcp.terreno.app
-}
-``````
-
-**Returns:** File list, setup instructions, and full file contents for backend, frontend, CI workflows, and MCP configuration.
-
-The generated Profile tab (`frontend/app/(tabs)/profile.tsx`) uses `@terreno/ui` `TapToEdit` for name, email, and password. Each field saves independently with `PATCH /auth/me` (`usePatchMeMutation`). Name and email each have their own `useEffect`, so saving one field does not wipe an in-progress edit on the other.
-
-The generated app is expected to install and boot with no manual follow-up, so the
-scaffold deliberately ships no binary assets and no references to files it does not
-create:
-
-- **Fonts** come from `@terreno/ui`. `TerrenoProvider` wraps children in
-  `TerrenoFontProvider`, which loads Nunito and Titillium Web from
-  `@expo-google-fonts/*`. The generated `app/_layout.tsx` calls no `useFonts` of its own.
-- **Icon, splash, and favicon** are left unset in `app.json` so Expo uses its built-in
-  defaults. Point them at real files once the app has branding.
-- **`metro.config.js`** pins every `jspdf` request to `jspdf/dist/jspdf.es.min.js` on web
-  and drops it on native. `@terreno/admin-frontend` pulls jspdf in for consent-PDF export,
-  and jspdf's CommonJS and Node builds contain an AMD-style `require(["html2canvas"], cb)`
-  call that Metro's static transform cannot parse — without the override it fails the whole
-  bundle, including Expo Router's static web render.
-- **Auth-gated routes** use `<Stack.Protected guard={...}>`. Wrapping `Stack.Screen`
-  children in a conditional or fragment instead crashes the navigator.
-- **`tsconfig.json`** sets no `baseUrl`; it is deprecated in TypeScript 6 and makes `tsc`
-  abort with TS5101 before checking a single file. `paths` resolve relative to the tsconfig.
-- **Declared dependencies** include every package generated frontend source imports
-  (`react-native-reanimated`, `redux-persist`, `@reduxjs/toolkit`, `@expo/vector-icons`,
-  `lodash`, `luxon`, and the rest). Do not rely on transitive installs for those.
-
 ### terreno_bootstrap_ai_rules
 
 Scaffold AI coding assistant rules (AGENTS.md, Cursor/Windsurf rules, Copilot instructions, rulesync config).
@@ -416,7 +375,7 @@ Multi-step workflow prompts that guide AI assistants through complex tasks.
 
 ### terreno_bootstrap
 
-Workflow prompt for scaffolding a new Terreno app. Delegates to `terreno_bootstrap_app` and `terreno_bootstrap_ai_rules` tools.
+Workflow prompt for scaffolding a new Terreno app. Instructs the assistant to run `bunx create-terreno-app`, then `terreno_bootstrap_ai_rules`.
 
 **Arguments:**
 

package/src/docs/versioned/next/reference/scan-plugin.md

@@ -0,0 +1,169 @@
+# Scan plugin reference
+
+Plugin: `terreno-scan` (`2.11.0`). Requires the lifecycle plugin
+([lifecycle plugin reference](lifecycle-plugin.md)).
+
+A scan turns a long-term outcome — "cold builds under 30s", "no unbounded reads", "WCAG
+AA on every screen" — into a measured campaign: charter the goal, map-reduce the
+repository into verified findings, slice those findings into IPs and tasks, run each
+slice through Grow/Pick/Roast/Brew/Taste, then re-measure and repeat.
+
+Scan stages never edit product code. The lifecycle does.
+
+| Skill | Preconditions | Primary output | PASS next |
+| --- | --- | --- | --- |
+| `terreno-scan-1-aim` | goal/outcome + repository | approved charter: metric, measured baseline, dry-run rules, exclusions, validity rule, severity rubric, slice policy, budget | Sweep |
+| `terreno-scan-2-sweep` | approved charter | per-rule hits, deterministic shard manifest, schema-valid candidate findings from parallel workers | Sift |
+| `terreno-scan-3-sift` | candidates for the round | deduped, adversarially verified, ranked findings report plus dropped-candidate summary | Plot, or Track when dry |
+| `terreno-scan-4-plot` | findings report + slice policy | ordered PR-sized slices, one standalone Grow brief each, findings marked `planned` | Track, with `handoff: grow` |
+| `terreno-scan-5-track` | landed slice or dry round | re-measured metric with command output, findings closed/reopened with evidence, round record, next move | Plot, Sweep, or `null` |
+
+Outer loops (not stages):
+
+| Skill | What it walks | Default |
+| --- | --- | --- |
+| `terreno-scan-campaign` | One goal, round after round | Aim once, then Sweep → Sift → Plot → lifecycle → Track until the metric hits target, the budget is spent, or a genuine human gate is reached. Stops at each gate. |
+| `terreno-scan-loop` | The same, but resident | Keeps the campaign moving **and** heartbeats over every open campaign PR — routing it to a reviewer, answering review comments through Taste, fixing red CI, tracking merges — refilling work as PRs land. Runs until the goal is met, a stop argument fires, or a human decision is required. |
+
+## Resident loop
+
+`terreno-scan-loop` is the "leave it running" entry point. One session holds the goal,
+the state, and the schedule; every unit of work happens in a fresh subagent.
+
+Arguments: `goal=<slug>`, `reviewer=<handle[,handle]>`, `assignee=<handle>`, `wip=<n>`,
+`rounds=<n>`, `until=<ISO timestamp>`, `tick=<seconds>`. Overrides apply to the run only
+and are recorded in state as overrides — they never rewrite the charter.
+
+Each tick snapshots the campaign's PRs and sorts each into one bucket, then acts in
+priority order:
+
+| Bucket | Action |
+| --- | --- |
+| `unrouted` | Apply the charter's routing, then count the slice in flight |
+| `answered` | A human commented or requested changes → one `terreno-5-taste` in a fresh subagent |
+| `broken` | CI failed or the PR conflicts → one `terreno-5-taste` |
+| `merged` | → `terreno-scan-5-track`: re-measure, close findings with evidence |
+| `closed` | Mark the slice abandoned, return its findings to `open`, free its slot |
+| `bot-pending`, `waiting` | Nothing — this is why the next tick exists |
+
+Then it refills capacity up to `wipLimit` and schedules the next tick: the provider's
+watch hook while CI runs, 2–5 minutes while review bots report, 15–30 minutes while a
+human holds the PR, and no wait at all while backlog work remains. Ticks that find
+nothing print nothing, and every comment is answered exactly once — answered ids live in
+state. See
+[`heartbeat.md`](https://github.com/FlourishHealth/terreno/blob/master/plugins/terreno-scan/references/heartbeat.md).
+
+## PR routing
+
+Aim settles who reviews the campaign's PRs before any PR exists, and records a `review`
+block: `mode` (`fixed`, `codeowners`, `blame`, `round-robin`, `none`), reviewer and
+assignee handles, teams, draft policy, labels, `wipLimit`, `mergePolicy`, and how to
+notify. Handles are verified with `gh api repos/{owner}/{repo}/collaborators/<handle>`
+before use; an unverifiable handle is a human gate, never a silently unassigned PR.
+
+Routing is applied right after Brew reports the PR (`gh pr edit --add-reviewer
+--add-assignee --add-label`) and re-requested once when requested changes are addressed.
+The campaign never approves its own PRs, never dismisses a review, and never merges when
+`mergePolicy` is `human` — the default. See
+[`pr-routing.md`](https://github.com/FlourishHealth/terreno/blob/master/plugins/terreno-scan/references/pr-routing.md).
+
+## Stage anatomy
+
+Every stage includes Preconditions, Inputs, Procedure, Supporting skills, Evidence
+produced, Success/Failure/Blocked conditions, and a recommended next stage — the same
+shape as the lifecycle stages.
+
+Results use `PASS`, `FAIL`, `BLOCKED`, or `PENDING` and the compact `v: 2`
+[`scan-result.schema.json`](https://github.com/FlourishHealth/terreno/blob/master/plugins/terreno-scan/references/scan-result.schema.json)
+(`v`, `stage`, `status`, `next`, `action`; omit empty keys). Campaign state follows
+[`scan-state.schema.json`](https://github.com/FlourishHealth/terreno/blob/master/plugins/terreno-scan/references/scan-state.schema.json)
+and findings follow
+[`finding.schema.json`](https://github.com/FlourishHealth/terreno/blob/master/plugins/terreno-scan/references/finding.schema.json).
+Chat shows `status` / `next` / `action` plus the current metric; the YAML lives in a
+Details toggle.
+
+## Map-reduce
+
+Sweep shards rule hits into batches (default: at most 25 files or 80 hits per shard,
+never splitting a file) and maps one fresh worker per shard. Workers get a shard
+briefing — goal, rules, validity rule, severity rubric, file list, hit lines, allowed
+commands, and the return schema — and nothing else. They never search the repository at
+large, never spawn nested agents, and never edit files. Sift then dedupes by
+`rule + path + symbol`, re-runs evidence, refutes every high-severity candidate before
+keeping it, drops what does not reproduce, and ranks by impact × confidence ÷ effort.
+Dropped shards and capped coverage are always reported; silent truncation is a defect.
+See
+[`mapreduce.md`](https://github.com/FlourishHealth/terreno/blob/master/plugins/terreno-scan/references/mapreduce.md).
+
+## Goal and metric
+
+Aim is not finished until the metric has a command that prints a number and the baseline
+came from running it. Track re-runs that command with the charter's protocol every round
+and records the value with its output. A finding that cannot be tied to the metric is
+dismissed in Sift, not deferred. Re-baselining without recording both values, the reason,
+and the round is untrustworthy and Track says so. See
+[`goal-tracking.md`](https://github.com/FlourishHealth/terreno/blob/master/plugins/terreno-scan/references/goal-tracking.md).
+
+## Artifacts
+
+| Artifact | Default path | Committed |
+| --- | --- | --- |
+| Charter | `docs/scans/<goal-slug>/charter.md` | yes |
+| Findings report | `docs/scans/<goal-slug>/round-<n>-findings.md` | yes |
+| Shard manifest, candidates, slice briefs | round artifact directory | per repository policy |
+| Campaign state | `.terreno/scan/<goal-slug>.json` | no (git-ignored) |
+| Slice IP and tasks | the repository's existing IP/task convention, written by Grow | yes |
+
+An existing repository convention always wins over these defaults.
+
+## State machine
+
+```text
+Aim PASS → Sweep → Sift
+  Sift PASS (findings)    → Plot → handoff: grow
+  Sift PASS (dry round)   → Track
+  Plot PASS               → Grow → Pick/Roast inner loop → Brew → Taste → Track
+  Track PASS (backlog)    → Plot
+  Track PASS (empty)      → Sweep
+  Track PASS (target/budget/regression) → null, report and ask
+  Track PENDING (slice still in flight) → campaign waits → fresh Track
+  Any BLOCKED             → named human/external gate
+```
+
+The campaign loop owns persistence, retry, waiting, stop, and escalation. It never
+implements a finding itself, never commits, and never opens a PR — Plot hands each slice
+to Grow, and the lifecycle takes it from there.
+
+## Hosts
+
+| Host | Plugin | Invoke Aim | Invoke the campaign |
+| --- | --- | --- | --- |
+| Cursor | `terreno-scan` | `/terreno-scan-1-aim` | `/terreno-scan-campaign` |
+| Codex | `terreno-scan` | `$terreno-scan-1-aim` | `$terreno-scan-campaign` |
+| Claude Code | `terreno-scan` | `/terreno-scan:1-aim` | `/terreno-scan:campaign` |
+
+The resident loop is `/terreno-scan-loop` (Cursor), `$terreno-scan-loop` (Codex), and
+`/terreno-scan:loop` (Claude Code).
+
+`plugins/terreno-scan/` is canonical. `plugins/terreno-scan-claude/` is generated with
+shortened skill names; regenerate it with `bun run skills:sync` and never hand-edit it.
+
+## Example
+
+```text
+/terreno-scan:loop reduce cold compile time reviewer=octocat wip=2
+```
+
+Aim grills the target (30s), measures the baseline with `bun run compile` on a clean
+tree, approves four rules, and records `octocat` as reviewer with a two-PR limit. Sweep
+shards 180 hits into nine batches and maps nine workers. Sift keeps 12 of 31 candidates,
+refuting four high-severity claims that did not reproduce. Plot writes three slices; the
+loop runs the first through Grow, Pick/Roast, and Brew, then routes the PR to `octocat`.
+While that PR waits, the loop opens the second slice up to the limit and then goes quiet,
+ticking every 20 minutes. `octocat` requests a change at 14:05; the next tick hands that
+PR to Taste, which replies, fixes, runs the pre-push gate, pushes, and watches CI. When
+the PR merges, Track re-measures at 48.2s (from 58.6s), marks five findings fixed, and
+the loop refills capacity with the third slice.
+
+Stop it with a plain "stop" — it leaves every PR routed, state consistent, and reports
+what is in flight and who holds it.