@terreno/mcp 57.2.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.
 
@@ -122,6 +126,8 @@ export const store = configureStore({
 
 ## WebSocket Integration
 
+> **Deprecated (removed in Terreno 58):** `realtimeList`, `realtimeDocument`, `setRealtimeSocket`, and `getRealtimeSocket` patch RTK Query caches from `sync` events. Use [`@terreno/syncdb`](../syncdb.md). `useSocketConnection` remains for feature flags and other sockets.
+
 ### useSocketConnection
 
 React hook for managing Socket.io connections with automatic reconnection, token refresh, and user feedback.

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

@@ -1,17 +1,28 @@
 # Lifecycle plugin reference
 
-Plugin: `terreno-planning` (`2.1.0`)
+Plugin: `terreno-planning` (`2.12.0`)
 
-All five skills are explicitly invoked (`disable-model-invocation: true`) and implement
-one bounded transition.
+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
+approved task list is done. Roast proves the current task and returns.
+`terreno-pick-roast-loop`, `terreno-planning-loop`, and `terreno-taste-sweep` are outer
+loops that invoke those stages; they are not stages and must not appear as `stage` values.
 
 | Skill | Preconditions | Primary output | PASS next |
 | --- | --- | --- | --- |
-| `terreno-1-grow` | request/spec + repository | approved IP/tasks + criterion/verification map | Pick |
-| `terreno-2-pick` | approved task + branch/state | implemented slice + tests/internal reviews | Roast |
-| `terreno-3-roast` | Pick result + current diff | independent requirement/evidence verdict | Brew |
-| `terreno-4-brew` | Roast PASS + branch/evidence | pushed head + PR + attached evidence | Taste |
-| `terreno-5-taste` | PR + current state | one current-head reaction result | null or fresh Taste |
+| `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`, 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):
+
+| Skill | What it walks | Default |
+| --- | --- | --- |
+| `terreno-pick-roast-loop` | Approved task list through Pick/Roast recovery | Continue every actionable engineering retry; report once when all tasks pass or a genuine human gate is reached. |
+| `terreno-planning-loop` | Approved task list | Grow once, then Pick once (inner pick-roast loop). Pass `phases=` to restrict (`grow`, `pick`, `roast`, `brew`, `taste`). |
+| `terreno-taste-sweep` | Author's open broken PRs | Isolate each conflicting or failing (any discovered CI host) non-draft PR and reinvoke Taste until mergeable or blocked. |
 
 Every stage includes:
 
@@ -28,28 +39,107 @@ 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
+[pick-roast inner loop](https://github.com/FlourishHealth/terreno/blob/master/plugins/terreno-planning/references/pick-roast-loop.md):
+one task, roast it, next task. Roast never invokes Pick. Do not start the next task
+until Roast PASS. Exactly one driver continues after each Roast. Brew and Taste wait
+until async review bots (Bugbot, CodeQL, and similar) on the current head have reported,
+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`, 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
+does not execute Taste.
+
+The focused Pick–Roast outer loop does not run Grow, Brew, Taste, or product CI. It
+resumes only `pick` or `roast` from durable `next.stage`; a stored `brew` finishes the
+loop without launching Brew, and `taste` or `grow` is `FAIL`. It keeps a
+schema-defined execution-state `ledger` entry for every Pick/Roast task attempt,
+including head/status/evidence and optional retry hypothesis, files, checks, artifacts,
+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, then PR deployment URLs when a PR has them.
 
-The outer loop owns state persistence, waiting, stage invocation, retries, and escalation.
-Brew exits after PR setup. Taste observes/acts once and exits.
+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: `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.
+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):
 read architecture docs before acting, update them in the same slice, and fail the slice
-when user-visible or architectural behavior ships without matching docs.
+when user-visible or architectural behavior ships without matching docs. Brew and Taste
+observe product CI per
+[product-ci.md](https://github.com/FlourishHealth/terreno/blob/master/plugins/terreno-planning/references/product-ci.md).
 
-Install the published skill set (lifecycle stages plus repo and package skills):
+Install the published skill set directly:
 
 ```bash
 npx skills add FlourishHealth/terreno
 ```
 
-Regenerate the committed `skills/` tree with `bun run skills:sync`. Package skills under
-`<package>/.ai/skills/` overlay the repo copies.
+Or install the combined lifecycle and Terreno app plugin:
+
+| Host | Plugin | Stage names | Invoke Pick–Roast loop |
+| --- | --- | --- | --- |
+| Cursor | `terreno-planning` | `terreno-1-grow` … `terreno-5-taste`, outer loops | `/terreno-pick-roast-loop` |
+| Codex | `terreno-planning` | `terreno-1-grow` … `terreno-5-taste`, outer loops | `$terreno-pick-roast-loop` |
+| Claude Code | `terreno` | `1-grow` … `5-taste`, outer loops | `/terreno:pick-roast-loop` |
+| `npx skills` | — | Canonical stage and outer-loop names | `/terreno-pick-roast-loop` |
+
+Cursor installs `terreno-planning` from [`.cursor-plugin/marketplace.json`](https://github.com/FlourishHealth/terreno/blob/master/.cursor-plugin/marketplace.json). Codex:
+
+```text
+codex plugin marketplace add FlourishHealth/terreno
+codex plugin install terreno-planning --source terreno-plugins
+```
+
+Codex reads [`.agents/plugins/marketplace.json`](https://github.com/FlourishHealth/terreno/blob/master/.agents/plugins/marketplace.json)
+and `.codex-plugin/plugin.json` on the canonical plugin. Claude Code:
+
+```text
+/plugin marketplace add FlourishHealth/terreno
+/plugin install terreno@terreno-plugins
+```
+
+Claude Code resolves a plugin skill's command from the frontmatter `name`, so the short
+names ship as a generated Claude-only copy at
+[`plugins/terreno-claude/`](https://github.com/FlourishHealth/terreno/tree/master/plugins/terreno-claude).
+Stage procedure, Terreno app skills, contracts, agents, and references are generated
+from the canonical `plugins/terreno-planning/` tree.
 
-Exact commands and domain conventions are supplied by repository-local skills discovered
-at stage start; they are not bundled into the lifecycle plugin.
+Regenerate the committed `skills/` tree and the Claude plugin with `bun run skills:sync`.
+Plugin skills are authoritative when names overlap. Package skills under
+`<package>/.ai/skills/` remain package/MCP inputs and do not overlay the installable
+tree.
 
+The plugin bundles reusable backend/API, UI, data-fetching, schema, SDK, admin, prompt,
+docs, upgrade, deployment, and UI-verification workflows, plus `pre-commit` and
+`ui-verifier` agents on Cursor and Claude Code. Codex consumes the combined skills
+without plugin-defined agents. Repository-local skills supply only project-specific
+roadmap, release, and maintenance conventions discovered at stage start.

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

@@ -3,7 +3,7 @@
 Published npm package for the Terreno Model Context Protocol (MCP) server. The monorepo directory is still `mcp-server/`. The package exposes:
 
 - **`terreno-mcp`** — HTTP server used in Cloud Run and local debugging (`src/index.ts`)
-- **`terreno-mcp-local`** — stdio server for project runtime tools (`src/local/index.ts`): `application_info`, `database_schema`, `database_query`, `read_logs`, `last_error`, `get_rtk_state`, `evaluate` (gated by `TERRENO_MCP_EVAL`), `navigate` (CDP wiring planned)
+- **`terreno-mcp-local`** — stdio server for project runtime tools (`src/local/index.ts`): `application_info`, `database_schema`, `database_query`, `read_logs`, `last_error`, `get_rtk_state`, `evaluate` (gated by `TERRENO_MCP_EVAL`), `navigate` (CDP wiring planned). `application_info` reads bootstrap `backend/` + `frontend/`, or this monorepo's `example-backend/` + `example-frontend/` (bootstrap names win when both exist).
 
 It provides AI coding assistants with documentation access, code generation tools, and workflow prompts.
 
@@ -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
 
@@ -120,9 +120,12 @@ BM25-style keyword search over markdown bundled with the MCP server: `docs/resou
   queries: string[];       // Required — one or more search phrases
   packages?: string[];     // Optional — filter by package id or scope, e.g. ["api", "@terreno/ui"]
   tokenLimit?: number;      // Approximate max tokens of markdown (default 3000)
+  version?: string;         // Optional @terreno/* lockstep version (e.g. 57.2.0). Omit for current `next` docs.
 }
 ``````
 
+Unmatched versions fall back to the nearest retained snapshot (`website/versioned_docs/`, copied into `docs/versioned/` at MCP build). The response names the resolved version and includes a note when a fallback happened. Pass the consumer app's `@terreno/*` version from `application_info` or `package.json`. Range prefixes such as `^57.2.0` are stripped before matching.
+
 ### terreno_get_component_docs
 
 Returns the full props table for a single `@terreno/ui` component from `ui-types-documentation.json`, plus short related markdown excerpts when the search index finds matches.
@@ -132,6 +135,22 @@ Returns the full props table for a single `@terreno/ui` component from `ui-types
 ``````typescript
 {
   component: string;        // e.g. "Button", "TextField"
+  version?: string;         // Optional @terreno/* lockstep version. Omit for current TypeDoc props.
+}
+``````
+
+When `version` matches a retained docs snapshot, the tool returns that version's generated component page (MDX chrome stripped). Snapshot filenames may be hyphenated (`text-field.mdx`) or concatenated (`userinactivity.mdx`); lookup tries both. Otherwise it uses current `ui-types-documentation.json` and notes the fallback.
+
+### terreno_get_upgrade_guide
+
+Return bundled Terreno lockstep upgrade notes between two semver versions (markdown). Use before major bumps to `@terreno/*` packages. The response always lists which versions in the range **have** notes. If some or all versions have none, it names those gaps — an empty concatenation would look like “nothing changed,” which is usually false. `fromVersion` must be less than or equal to `toVersion`. Note format: `mcp-server/src/docs/upgrades/README.md`.
+
+**Parameters:**
+
+``````typescript
+{
+  fromVersion: string;      // Installed @terreno/* semver (e.g. 0.19.0)
+  toVersion: string;        // Target semver to upgrade to (e.g. 0.20.0)
 }
 ``````
 
@@ -322,23 +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.flourish.health
-}
-``````
-
-**Returns:** File list, setup instructions, and full file contents for backend, frontend, CI workflows, and MCP configuration.
-
 ### terreno_bootstrap_ai_rules
 
 Scaffold AI coding assistant rules (AGENTS.md, Cursor/Windsurf rules, Copilot instructions, rulesync config).
@@ -373,13 +375,19 @@ 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:**
 
 - `appName` (string) — Application name in kebab-case
 - `appDisplayName` (string) — Human-readable display name
 
+### terreno_upgrade
+
+Lockstep Terreno upgrade workflow: read bundled upgrade notes, bump `@terreno/*` packages, run tests, and delegate Expo SDK steps to the official upgrading-expo skill.
+
+**Arguments:** `targetVersion` (optional) — target `@terreno/*` semver; omit to mean latest stable.
+
 ### terreno_create_crud_feature
 
 Generate complete CRUD feature: backend model + routes + frontend screens.