@terreno/mcp 57.3.0 → 57.6.0

package/dist/docs/versioned/next/reference/comms.md

@@ -70,6 +70,39 @@ A throwing `beforeSend` is logged and treated as no-op (send continues). Adapter
 call `recordDeliveryEvent()` / `recordOptOut()` to update the log and fire
 `onDeliveryEvent` / `onOptOut`.
 
+### Notification preferences hook
+
+When you register `NotificationsApp`, compose `notificationsBeforeSend` from `@terreno/api`
+into `CommsApp({beforeSend})` so outbound mail, SMS, and push respect per-user channel
+toggles. Missing `NotificationPreference` rows default to all channels on. The
+`verification` channel is never cancelled by this hook.
+
+```typescript
+import {notificationsBeforeSend} from "@terreno/api";
+
+new CommsApp({
+  beforeSend: async (context) => {
+    const pref = await notificationsBeforeSend({
+      channel: context.channel,
+      userId: context.userId,
+    });
+    if (pref?.cancel) {
+      return {cancel: true};
+    }
+    return existingBeforeSend?.(context);
+  },
+});
+```
+
+`getNotificationService().notify()` fans out to comms independently. Register this hook and
+pass `{userId}` as the second argument to direct `sendMail` / `sendSms` calls so they honor
+preferences; `sendPushToUser` already supplies its user id.
+
+```typescript
+await getCommsService().sendMail(message, {userId});
+await getCommsService().sendSms(message, {userId});
+```
+
 Each send stores one `CommsMessage` row with `attempts[]`. Rendered payloads are retained
 for `retainPayloadDays` (default 30, `0` disables) after `redactPayload`. Mail payloads
 keep `to`, `from`, `subject`, `text`, `html`, `replyTo`, `templateId`, and

package/dist/docs/versioned/next/reference/create-terreno-app.md

@@ -0,0 +1,44 @@
+# create-terreno-app
+
+Unscoped npm CLI that writes a deployable Terreno backend + Expo frontend to disk.
+
+Operator walkthrough (Mongo replica set, seed, SDK, web, deploy): [Create a Terreno app](../how-to/create-a-terreno-app.md). First-run tutorial: [Getting started](../tutorials/getting-started.md).
+
+## Install
+
+```bash
+bunx create-terreno-app my-app --display-name "My App"
+```
+
+npm (note the `--` before flags):
+
+```bash
+npm create terreno-app my-app -- --display-name "My App"
+```
+
+The published package name is `create-terreno-app`. Generated `@terreno/*`
+dependencies pin `^<create-terreno-app version>`.
+
+## CLI
+
+```bash
+bunx create-terreno-app <appName> --display-name <string> [--description <string>] [--mcp-server-url <url>] [--yes]
+```
+
+| Flag | Required | Default |
+| --- | --- | --- |
+| `appName` (positional) | yes | kebab-case (`^[a-z][a-z0-9-]*$`) |
+| `--display-name` | unless `--yes` | derived from `appName` when `--yes` |
+| `--description` | no | empty |
+| `--mcp-server-url` | no | hosted Terreno MCP URL |
+| `--yes` | no | off |
+
+Writes `<cwd>/<appName>/`. Refuses a non-empty target except `.git` / `.gitignore`. Does not run `bun install`, Mongo, or seed.
+
+Printed next steps install, seed, then start the backend. SDK and web run in a second terminal while the backend is up.
+
+The generated Profile tab uses `@terreno/ui` `TapToEdit` with `PATCH /auth/me`. Fonts come from `@terreno/ui`. `app.json` leaves icon/splash/favicon unset. `metro.config.js` pins `jspdf` so Metro can bundle admin PDF export. Generated tsconfigs use no TypeScript 6 deprecated options and no `ignoreDeprecations` (see [TypeScript configuration](../explanation/typescript-configuration.md)). Auth routes use `<Stack.Protected>`.
+
+## Library
+
+`generateAllFiles` returns the file list; `writeScaffold` writes it to disk. The CLI is the only supported way to scaffold an app. MCP `terreno_bootstrap_ai_rules` can add editor rules after the CLI runs.

package/dist/docs/versioned/next/reference/environment-variables.md

@@ -69,6 +69,9 @@ Comprehensive guide to environment variables used across Terreno packages and ex
 | `FRONTEND_URL` | example-backend CORS and `authOptions.publicAppUrl` | ❌ | `http://localhost:8082` | No | server |
 | `API_URL` | microservice split | ❌ | — | No | server |
 | `DISABLE_LOG_ALL_REQUESTS` | `@terreno/api` logging | ❌ | — | No | server |
+| `TERRENO_BROWSER_LOGS` | `@terreno/api` dev log ingestion | ❌ | enabled only in development; loopback or authenticated requests only | No | server |
+| `ALLOW_MIGRATIONS` | `@terreno/api` `terreno-migrate` | ❌ | unset | No | server |
+| `MIGRATIONS_DIR` | example-backend Dockerfile / `resolveMigrationDir` | ❌ | `<cwd>/migrations` when `dir` is `$bunfs` | No | server |
 
 ## Client / build-time
 
@@ -97,6 +100,19 @@ Resolution order for API base URL (`rtk/src/constants.ts`):
 2. `extra.BASE_URL` (production only, when env unset)
 3. Dev fallbacks: `hostUri`, experience URL, `localhost`
 
+## Development tooling
+
+| Variable | Read by | Required | Default | Secret | Scope |
+|----------|---------|----------|---------|--------|-------|
+| `TERRENO_PROJECT_ROOT` | `terreno-mcp-local`, `terreno` CLI | ❌ | nearest Terreno project root | No | tooling |
+| `TERRENO_METRO_URL` | `terreno-mcp-local` | ❌ | frontend script port or `http://localhost:8082` | No | tooling |
+| `TERRENO_MCP_EVAL` | `terreno-mcp-local` | ❌ | disabled | No | tooling |
+| `TERRENO_WEB_URL` | `terreno` CLI | ❌ | `http://localhost:8082` | No | tooling |
+| `BUN_CHROME_PATH` | Bun WebView | ❌ | browser auto-discovery | No | tooling |
+| `TERRENO_OPENAPI` | `terreno` CLI | ❌ | — | No | tooling |
+| `TERRENO_API_URL` | `terreno` CLI | ❌ | OpenAPI `servers[0].url` | No | tooling |
+| `TERRENO_TOKEN` | `terreno` CLI | ❌ | — | Yes | tooling |
+
 ## AI
 
 | Variable | Read by | Required | Default | Secret | Scope |
@@ -206,6 +222,7 @@ There is **no** `RATE_LIMIT_ENABLED` (or similar) read by `@terreno/api`. Apps t
 |----------|---------|----------|---------|--------|-------|
 | `SLACK_WEBHOOKS` | `@terreno/api` | ❌ | — | Yes | server |
 | `SLACK_WEBHOOK_URL` | scripts | ❌ | — | Yes | server |
+| `SLACK_BOT_TOKEN` | `@terreno/api` `lookupSlackUserIdByEmail` | ❌ | — | Yes | server |
 | `GOOGLE_CHAT_WEBHOOKS` | `@terreno/api` | ❌ | — | Yes | server |
 | `GOOGLE_CHAT_WEBHOOK_URL` | scripts | ❌ | — | Yes | server |
 | `ZOOM_CHAT_WEBHOOKS` | `@terreno/api` | ❌ | — | Yes | server |
@@ -237,6 +254,24 @@ secrets and `PUBLIC_API_URL` / `COMMS_WEBHOOK_PUBLIC_URL` as above. See
 | `TERRENO_MCP_EVAL` | MCP eval | ❌ | — | No | tooling |
 | `TERRENO_PROJECT_ROOT` | MCP local | ❌ | — | No | tooling |
 
+## Background jobs
+
+| Variable | Read by | Required | Default | Secret | Scope |
+|----------|---------|----------|---------|--------|-------|
+| `JOBS_START_WORKER` | example-backend (`jobsStartWorker.ts`) | ❌ | `true` (unset) | No | server |
+
+`@terreno/jobs` itself does **not** read environment variables — pass `JobsApp` and runner
+options explicitly. `JOBS_START_WORKER` only gates whether the example API process calls
+`jobsApp.startWorker()` after listen. Set `false` when running the standalone
+`bun run jobs:worker` process against the same MongoDB.
+
+`JOB_TRACE_LOGS` is an optional app convention for verbose worker logging (see
+[API logging & tracing](api.md#logging--tracing)); not read by the jobs package.
+
+Legacy names `GCP_TASKS_NOTIFICATIONS_QUEUE` and `GCP_TASK_PROCESSOR_QUEUE` appear in
+example-backend **test** setup only. They are not read by `@terreno/jobs`. Use
+`GcpCloudTasksRunner` constructor config instead. See [Jobs reference](jobs.md).
+
 ## Example backend (app-specific)
 
 | Variable | Read by | Required | Default | Secret | Scope |
@@ -244,6 +279,14 @@ secrets and `PUBLIC_API_URL` / `COMMS_WEBHOOK_PUBLIC_URL` as above. See
 | `OTEL_SERVICE_NAME` | OpenTelemetry (example-backend) | ❌ | `example-backend` | No | server |
 | `PR_NUMBER` | PR preview deploy | ❌ | — | No | server |
 | `PR_SERVICE_URL` | PR preview deploy | ❌ | — | No | server |
+| `JOBS_RUNNER` | example-backend | ❌ | `mongo` | No | server |
+| `JOBS_START_WORKER` | example-backend | ❌ | `true` with Mongo | No | server |
+| `GCP_TASKS_PROJECT` | example-backend Cloud Tasks runner | ✅ when `JOBS_RUNNER=gcp-cloud-tasks` | — | No | server |
+| `GCP_TASKS_LOCATION` | example-backend Cloud Tasks runner | ✅ when `JOBS_RUNNER=gcp-cloud-tasks` | — | No | server |
+| `GCP_TASKS_QUEUE` | example-backend Cloud Tasks runner | ✅ when `JOBS_RUNNER=gcp-cloud-tasks` | — | No | server |
+| `GCP_TASKS_PUBLIC_URL` | example-backend Cloud Tasks runner | ✅ when `JOBS_RUNNER=gcp-cloud-tasks` | — | No | server |
+| `GCP_TASKS_OIDC_AUDIENCE` | example-backend Cloud Tasks runner | ❌ | `{publicUrl}/jobs/execute`; deployed Cloud Run uses the canonical tasks-service root URL so tagged PR callbacks pass platform IAM | No | server |
+| `GCP_TASKS_SERVICE_ACCOUNT_EMAIL` | example-backend Cloud Tasks runner | ✅ when `JOBS_RUNNER=gcp-cloud-tasks` | — | No | server |
 | `DEFAULT_PAGE_SIZE` | Configuration model | ❌ | `20` | No | server |
 | `CRON_SECRET_KEY` | tests | ❌ | — | Yes | tooling |
 | `WIDGET_CLIENT_SECRET` | widgets | ❌ | — | Yes | server |
@@ -269,8 +312,8 @@ secrets and `PUBLIC_API_URL` / `COMMS_WEBHOOK_PUBLIC_URL` as above. See
 
 ## Example `.env` files
 
-- [`example-backend/.env.example`](https://github.com/FlourishHealth/terreno/blob/master/example-backend/.env.example)
-- [`example-frontend/.env.example`](https://github.com/FlourishHealth/terreno/blob/master/example-frontend/.env.example)
+- [`example-backend/.env.example`](https://github.com/TerrenoLabs/terreno/blob/master/example-backend/.env.example)
+- [`example-frontend/.env.example`](https://github.com/TerrenoLabs/terreno/blob/master/example-frontend/.env.example)
 
 ## Related documentation
 
@@ -278,3 +321,4 @@ secrets and `PUBLIC_API_URL` / `COMMS_WEBHOOK_PUBLIC_URL` as above. See
 - [Build for web](../how-to/build-for-web.md)
 - [Configure Better Auth](../how-to/configure-better-auth.md)
 - [Rate limiting](../how-to/rate-limiting.md)
+- [Durable background jobs](../how-to/background-jobs.md)

package/dist/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/dist/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/dist/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):
 
@@ -35,23 +35,28 @@ Every stage includes:
 - Recommended next stage
 
 Results use `PASS`, `FAIL`, `BLOCKED`, or `PENDING` and the compact `v: 2` schema
-[`stage-result.schema.json`](https://github.com/FlourishHealth/terreno/blob/master/plugins/terreno-planning/references/stage-result.schema.json)
+[`stage-result.schema.json`](https://github.com/TerrenoLabs/terreno/blob/master/plugins/terreno-planning/references/stage-result.schema.json)
 (`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).
+[`execution-state.schema.json`](https://github.com/TerrenoLabs/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):
+[pick-roast inner loop](https://github.com/TerrenoLabs/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`, 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,23 +71,36 @@ 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):
+[documentation contract](https://github.com/TerrenoLabs/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. Brew and Taste
 observe product CI per
-[product-ci.md](https://github.com/FlourishHealth/terreno/blob/master/plugins/terreno-planning/references/product-ci.md).
+[product-ci.md](https://github.com/TerrenoLabs/terreno/blob/master/plugins/terreno-planning/references/product-ci.md).
 
 Install the published skill set directly:
 
 ```bash
-npx skills add FlourishHealth/terreno
+npx skills add TerrenoLabs/terreno
 ```
 
 Or install the combined lifecycle and Terreno app plugin:
@@ -94,24 +112,24 @@ Or install the combined lifecycle and Terreno app plugin:
 | 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:
+Cursor installs `terreno-planning` from [`.cursor-plugin/marketplace.json`](https://github.com/TerrenoLabs/terreno/blob/master/.cursor-plugin/marketplace.json). Codex:
 
 ```text
-codex plugin marketplace add FlourishHealth/terreno
+codex plugin marketplace add TerrenoLabs/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)
+Codex reads [`.agents/plugins/marketplace.json`](https://github.com/TerrenoLabs/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 marketplace add TerrenoLabs/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).
+[`plugins/terreno-claude/`](https://github.com/TerrenoLabs/terreno/tree/master/plugins/terreno-claude).
 Stage procedure, Terreno app skills, contracts, agents, and references are generated
 from the canonical `plugins/terreno-planning/` tree.