@terreno/mcp 57.2.0 → 57.4.0

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

@@ -70,13 +70,47 @@ 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
 `dynamicTemplateData`. SMS payloads keep `to` and `body`. Push payloads omit tokens.
 Verification start stores `{channel}` only; verification checks store no payload.
 `recordDeliveryEvent` writes `status`, `errorCode`, and `errorClass` onto the matching
-row (`opened` does not change status). Expired payloads are unset, not deleted.
+row (`opened` does not change status). Missing rows log a warning and still fire the hook.
+A failed row save logs a warning and **throws** so webhook claims can release and retry.
 
 ## Provider contracts
 
@@ -97,9 +131,12 @@ bun add @sendgrid/mail
 ```
 
 ```typescript
+import {TerrenoApp, WebhooksApp} from "@terreno/api";
 import {CommsApp} from "@terreno/comms";
 import {SendGridMailProvider} from "@terreno/comms/adapters/sendgrid";
 
+const webhooks = new WebhooksApp();
+
 new TerrenoApp({userModel: User})
   .register(
     new CommsApp({
@@ -109,12 +146,15 @@ new TerrenoApp({userModel: User})
         fromEmail: "notifications@example.com",
         fromName: "Terreno",
         // sandboxMode defaults to true when NODE_ENV === "test"
+        // webhookVerificationKey defaults to SENDGRID_WEBHOOK_VERIFICATION_KEY
       }),
+      webhooks,
       onError: async (_context, result) => {
         console.error("mail failed", result.errorCode, result.errorClass);
       },
     })
   )
+  .register(webhooks)
   .start();
 ```
 
@@ -132,6 +172,157 @@ row.
 3. Confirm the from address matches a verified identity.
 4. Use sandbox mode in CI/tests so no real mail is delivered.
 
+Pass the same `WebhooksApp` into `CommsApp` **before** registering it. With
+`SendGridMailProvider` this mounts `POST {basePath}/webhooks/sendgrid` (default
+`/comms/webhooks/sendgrid`). The handler verifies ECDSA (`SENDGRID_WEBHOOK_VERIFICATION_KEY`
+or constructor `webhookVerificationKey`), claims each `sg_event_id`, correlates
+`sg_message_id` prefixes to stored `x-message-id`, and maps `delivered` / `bounce` /
+`dropped` / `open` plus opt-outs (`spamreport`, `unsubscribe`, `group_unsubscribe`).
+Missing verification key skips the route and logs an error. Full operator setup is in
+the inbound webhooks how-to.
+
+### Twilio SMS adapter
+
+```bash
+bun add twilio
+```
+
+```typescript
+import {TerrenoApp, WebhooksApp} from "@terreno/api";
+import {CommsApp} from "@terreno/comms";
+import {TwilioSmsProvider} from "@terreno/comms/adapters/twilioSms";
+
+const webhooks = new WebhooksApp();
+
+new TerrenoApp({userModel: User})
+  .register(
+    new CommsApp({
+      sms: new TwilioSmsProvider({
+        // accountSid / authToken default to TWILIO_ACCOUNT_SID / TWILIO_AUTH_TOKEN
+        // Prefer TWILIO_MESSAGING_SERVICE_SID; fall back to TWILIO_FROM_NUMBER
+      }),
+      webhookPublicUrl: process.env.PUBLIC_API_URL,
+      webhooks,
+      onError: async (_context, result) => {
+        console.error("sms failed", result.errorCode, result.errorClass);
+      },
+    })
+  )
+  .register(webhooks)
+  .start();
+```
+
+Pass the same `WebhooksApp` into `CommsApp` **before** `webhooks` is registered so the
+plugin can add routes, then mount it. With `TwilioSmsProvider` this registers
+`POST {basePath}/webhooks/twilio/status` and `POST {basePath}/webhooks/twilio/inbound`
+(default `basePath` `/comms`). Status callbacks map `delivered` / `undelivered` /
+`failed` (including `ErrorCode` `21610` → `permanent`) onto `CommsMessage`. Inbound
+`STOP` / `START` call `recordOptOut` with `reason: "sms-stop"` / `"sms-start"`.
+`statusCallbackUrl` defaults to the public status URL. Missing auth token or public URL
+(`webhookPublicUrl`, `PUBLIC_API_URL`, or `COMMS_WEBHOOK_PUBLIC_URL`) skips those routes
+and logs an error. Full operator setup is in the inbound webhooks how-to.
+
+`TwilioSmsProvider` fails fast at construction when account SID or auth token is missing.
+Destinations are normalized to E.164 with `libphonenumber-js`; invalid numbers return
+`accepted: false` with `errorClass: permanent` and `errorCode: twilio-invalid-destination`
+before any Twilio call, so the facade does not retry. Send failures never throw through
+`sendSms`; they return `accepted: false` with Twilio `errorCode` / `errorClass`
+(`permanent` | `transient` | `config`). Permanent codes (including 21610 STOP) are not
+retried. Accepted sends store `providerMessageId` and `metadata.consoleUrl` for the
+Twilio SMS log.
+
+The example backend registers this adapter when `TWILIO_ACCOUNT_SID`, `TWILIO_AUTH_TOKEN`,
+and a sender (`TWILIO_MESSAGING_SERVICE_SID` or `TWILIO_FROM_NUMBER`) are set. A sender
+without credentials throws at startup. Account credentials without a sender skip SMS so
+Verify-only configs can share `TWILIO_ACCOUNT_SID` / `TWILIO_AUTH_TOKEN`. Unconfigured
+environments keep the console SMS provider (or omit SMS in production). `twilio` is an
+optional peer — apps that do not send SMS do not install it. Apps that ship
+`bun build --compile` (the example Cloud Run image) must inject a Twilio client
+(static `import twilio from "twilio"`). The adapters' default
+`createRequire("twilio")` is not bundled into that binary.
+
+### Twilio Verify adapter
+
+```bash
+bun add twilio
+```
+
+```typescript
+import {CommsApp} from "@terreno/comms";
+import {TwilioVerifyProvider} from "@terreno/comms/adapters/twilioVerify";
+
+new TerrenoApp({userModel: User})
+  .register(
+    new CommsApp({
+      verification: new TwilioVerifyProvider({
+        // accountSid / authToken default to TWILIO_ACCOUNT_SID / TWILIO_AUTH_TOKEN
+        // verifyServiceSid defaults to TWILIO_VERIFY_SERVICE_SID
+      }),
+    })
+  )
+  .start();
+```
+
+`TwilioVerifyProvider` fails fast at construction when account SID, auth token, or
+`TWILIO_VERIFY_SERVICE_SID` is missing. `startVerification` supports `sms` and `email`.
+`checkVerification` returns `valid: true` only for Verify status `approved`; `pending`,
+`expired`, and max-attempt states return `valid: false` with those reasons. Start failures
+are classified (`config` / `transient` / `permanent`) and never throw through the facade.
+Verification `CommsMessage` rows redact the destination, never store the OTP, and are not
+retryable from admin. Accepted starts store `metadata.consoleUrl` for the Verify service.
+
+The example backend registers this adapter when `TWILIO_VERIFY_SERVICE_SID` is set together
+with `TWILIO_ACCOUNT_SID` and `TWILIO_AUTH_TOKEN`. A verify service SID without those
+credentials throws at startup. Unconfigured environments keep the console verification
+provider (or omit verification in production). Verify's email channel needs a Twilio Verify
+email integration; that setup is not automated.
+
+### Expo push adapter
+
+```bash
+bun add expo-server-sdk
+```
+
+```typescript
+import {CommsApp, getCommsService} from "@terreno/comms";
+import {ExpoPushProvider} from "@terreno/comms/adapters/expoPush";
+
+new TerrenoApp({userModel: User})
+  .register(
+    new CommsApp({
+      push: new ExpoPushProvider({
+        // accessToken defaults to process.env.EXPO_ACCESS_TOKEN (optional)
+        onDeadToken: async (token) => {
+          await getCommsService().deactivatePushToken(token);
+        },
+        onDeliveryEvent: async (event) => {
+          await getCommsService().recordDeliveryEvent(event);
+        },
+      }),
+    })
+  )
+  .start();
+```
+
+`ExpoPushProvider` validates tokens with `Expo.isExpoPushToken`, chunks with
+`chunkPushNotifications`, and returns one `SendResult` per input token. Invalid tokens
+never hit the Expo API (`errorCode: expo-invalid-token`, `errorClass: permanent`).
+Ticket `DeviceNotRegistered` is a permanent failure so `sendPushToUser` deactivates the
+`PushToken`. `MessageTooBig` is `errorClass: config`: the send fails and is not retried,
+but the token stays active. Successful tickets schedule one receipt poll (default 15
+minutes, `receiptPollDelayMs`) that emits `DeliveryEvent`s; a later `DeviceNotRegistered`
+receipt calls `onDeadToken`. `EXPO_ACCESS_TOKEN` is optional (higher Expo rate limits).
+
+Apps that ship `bun build --compile` (the example Cloud Run image) must inject
+an `Expo` client (static `import {Expo} from "expo-server-sdk"`). The adapter's
+default `createRequire("expo-server-sdk")` is not bundled into that binary.
+
+example-frontend requests notification permission, then `getExpoPushTokenAsync`, then
+`POST /comms/pushTokens` after login. Denied permission and web skip registration (empty
+token). Physical-device gating via `expo-device` is deferred until the native baseline
+lands. The profile **Send test push** card is `__DEV__` only, so production web exports
+(CircleCI Playwright) do not render it.
+
 ## Configuration
 
 ```typescript
@@ -167,7 +358,8 @@ Delivery attempts are stored in `CommsMessage`. Recipient values are stored as `
 Mail payloads keep `to`, `from`, `subject`, `text`, `html`, `replyTo`, `templateId`, and
 `dynamicTemplateData`. SMS payloads keep `to` and `body`. Verification start keeps `{channel}`
 only; verification checks store no payload. `recordDeliveryEvent` writes `status`, `errorCode`,
-and `errorClass` onto the matching row (`opened` does not change status).
+and `errorClass` onto the matching row (`opened` does not change status). Missing rows warn;
+save failures throw after a warning so inbound webhook claims can retry.
 
 `beforeSend` may replace the message or cancel the send (`status: "cancelled"`). `onSend` and
 `onError` fire after every channel outcome. `onRetry` fires once before the inline retry when
@@ -192,11 +384,26 @@ The default `basePath` is `/comms`.
 | `GET` | `/comms/pushTokens` | Authenticated owner | List the current user's tokens |
 | `GET` | `/comms/pushTokens/:id` | Owner | Read one token |
 | `DELETE` | `/comms/pushTokens/:id` | Owner | Deactivate a token |
-| `GET` | `/comms/messages` | Admin | Filtered, paginated delivery log |
+| `GET` | `/comms/messages` | Admin | Filtered, paginated delivery log. Query: `channel`, `provider`, `status`, `errorClass`, `errorCode`, `userId`, `to`, `templateId`, `retriedFromId`, `startDate`, `endDate`, free-text `q`, `page`, `limit` |
+| `GET` | `/comms/messages/:id` | Admin | Full row: attempts, metadata, retained payload, retry links, `retryable` / `retryDisabledReason` |
+| `POST` | `/comms/messages/:id/retry` | Admin | Re-send through the facade. Creates a linked row. 400 codes: `comms-retry-not-retryable`, `comms-retry-payload-expired`, `comms-retry-channel-unconfigured` |
+| `POST` | `/comms/messages/retryMany` | Admin | Same filters as list plus `limit` (cap 100). Returns `{retried, skipped: [{id, reason}]}` |
+| `GET` | `/comms/stats` | Admin | Counts by channel × provider × status with day buckets. Default range 7d. Includes per-provider failure rate |
 
 An active token cannot be claimed by another user. After its owner deactivates it, another
 authenticated user on the same device may register it.
 
+## Admin dashboard
+
+`CommsApp.adminContribution()` registers a custom screen named `comms` with the sidebar label **Comms Dashboard**. `@terreno/admin-frontend` ships `COMMS_ADMIN_WIDGETS` (`CommsDashboardScreen`, `CommsMessageDetail`) and hosts wire:
+
+- example-frontend: `/admin/comms` and `/admin/comms/[id]`
+- admin-spa: `/comms` and `/comms/[id]`
+
+Filters persist in the URL. List, stats, and bulk retry use the same match: when no dates are set, both the table and the cards use the trailing 7 days (labeled **Last 7 days**). Editing any filter while those dates are still implicit writes both bounds into the URL so the other bound is not dropped. `beforeSend` cancel on push attaches `loggedMessageId` the same way mail and SMS do. Created and attempt times print in the operator's locale (`DateTime.DATETIME_MED`), not UTC ISO. Inline and detail Retry create a new `CommsMessage` and navigate to it. **Retry matching** confirms the filtered list count (capped at 100) then posts `retryMany`.
+
+Run `bun run backend:seed` from the repository root to populate the example dashboard with 10 current, idempotent delivery logs across mail, SMS, push, and verification. The sample includes delivered, sent, failed, bounced, and cancelled states so stats, provider breakdowns, filters, and retry controls are visible immediately.
+
 ## Templates
 
 `renderTemplate()` replaces top-level `{{variable}}` placeholders in `subject`, `text`, and `html`.
@@ -211,3 +418,9 @@ const message = renderTemplate({
   },
 });
 ```
+
+Auth mail helpers `renderAuthMail()` and `DEFAULT_AUTH_MAIL_TEMPLATES` render reset and
+verify links as `${publicAppUrl}/resetPassword?token=...` and
+`${publicAppUrl}/verifyEmail?token=...`. Pass `templates` to override subject/text/html
+per template id (`resetPassword` | `verifyEmail`). Variables: `resetUrl`, `verifyUrl`,
+`publicAppUrl`, `token`.

package/src/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. `tsconfig.json` has no `baseUrl` (TypeScript 6). 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/src/docs/versioned/next/reference/environment-variables.md

@@ -66,9 +66,11 @@ Comprehensive guide to environment variables used across Terreno packages and ex
 | `ENABLE_SWAGGER` | `@terreno/api` | ❌ | `false` | No | server |
 | `APP_ENV` | example-backend | ❌ | `development` | No | server |
 | `BACKEND_URL` | scripts, deploy | ❌ | — | No | server |
-| `FRONTEND_URL` | example-backend CORS | ❌ | auto | No | server |
+| `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 |
+| `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
 
@@ -136,14 +138,45 @@ Resolution order for API base URL (`rtk/src/constants.ts`):
 | `COMMS_DEFAULT_FROM` | example-backend / `@terreno/comms` | ❌ | — | No | server |
 | `COMMS_DEFAULT_FROM_NAME` | example-backend | ❌ | — | No | server |
 | `SENDGRID_API_KEY` | `@terreno/comms/adapters/sendgrid` | ❌ | — | Yes | server |
+| `SENDGRID_WEBHOOK_VERIFICATION_KEY` | `@terreno/comms/adapters/sendgrid` | ❌ | — | Yes | server |
 | `SENDGRID_SANDBOX_MODE` | example-backend | ❌ | — | No | server |
+| `TWILIO_ACCOUNT_SID` | `@terreno/comms/adapters/twilioSms`, `@terreno/comms/adapters/twilioVerify` | ❌ | — | Yes | server |
+| `TWILIO_AUTH_TOKEN` | `@terreno/comms/adapters/twilioSms`, `@terreno/comms/adapters/twilioVerify` | ❌ | — | Yes | server |
+| `TWILIO_MESSAGING_SERVICE_SID` | `@terreno/comms/adapters/twilioSms` | ❌ | — | No | server |
+| `TWILIO_FROM_NUMBER` | `@terreno/comms/adapters/twilioSms` | ❌ | — | No | server |
+| `TWILIO_VERIFY_SERVICE_SID` | `@terreno/comms/adapters/twilioVerify` | ❌ | — | No | server |
+| `EXPO_ACCESS_TOKEN` | `@terreno/comms/adapters/expoPush` | ❌ | — | Yes | server |
+| `PUBLIC_API_URL` | `@terreno/comms` Twilio webhooks | ❌ | — | No | server |
+| `COMMS_WEBHOOK_PUBLIC_URL` | `@terreno/comms` Twilio webhooks | ❌ | — | No | server |
 
 Set `COMMS_ENABLED=false` to omit the example backend's communications plugin and routes.
 When `SENDGRID_API_KEY` is set, the example backend registers `SendGridMailProvider`
 (optional peer `@sendgrid/mail`). Without a key, non-production environments keep the
 console mail provider; production leaves mail unconfigured until a provider is wired.
 `SENDGRID_SANDBOX_MODE=true` forces SendGrid sandbox mode for non-test runtimes.
+`SENDGRID_WEBHOOK_VERIFICATION_KEY` (or constructor `webhookVerificationKey`) is the
+SendGrid Event Webhook ECDSA public key. Missing it skips `POST /comms/webhooks/sendgrid`.
+`PUBLIC_API_URL` or `COMMS_WEBHOOK_PUBLIC_URL` is the public HTTPS origin used to sign
+Twilio callbacks (no trailing slash). Missing it skips Twilio webhook routes.
 Sender identity must be verified in SendGrid before real delivery works.
+When `TWILIO_ACCOUNT_SID` and `TWILIO_AUTH_TOKEN` are set with
+`TWILIO_MESSAGING_SERVICE_SID` or `TWILIO_FROM_NUMBER`, the example backend registers
+`TwilioSmsProvider` (optional peer `twilio`). A sender var without those credentials
+throws at startup. Shared account credentials without a sender do not enable SMS — they
+can still enable Verify when `TWILIO_VERIFY_SERVICE_SID` is set. Without an SMS sender,
+non-production keeps the console SMS provider; production omits SMS until a sender is wired.
+When `TWILIO_VERIFY_SERVICE_SID` is set with `TWILIO_ACCOUNT_SID` and `TWILIO_AUTH_TOKEN`,
+the example backend registers `TwilioVerifyProvider`. A verify service SID without those
+credentials throws at startup. Without `TWILIO_VERIFY_SERVICE_SID`, non-production keeps
+the console verification provider; production omits verification until a provider is wired.
+`EXPO_ACCESS_TOKEN` is optional; the example backend always registers
+`ExpoPushProvider` when comms is enabled, with a statically imported `Expo`
+client so the compiled Cloud Run binary includes `expo-server-sdk`. Without a
+token, Expo still accepts sends at a lower rate limit. The example backend also
+depends on `twilio` and injects a statically imported client into
+`TwilioSmsProvider` / `TwilioVerifyProvider` when those env vars are complete,
+so the compiled binary includes the SDK. Non-production also mounts `POST /comms/dev/testPush`
+for authenticated test sends.
 
 ## Observability
 
@@ -164,8 +197,10 @@ Sender identity must be verified in SendGrid before real delivery works.
 
 | Variable | Read by | Required | Default | Secret | Scope |
 |----------|---------|----------|---------|--------|-------|
-| `VALKEY_URL` | `@terreno/api` | ❌ | — | Yes | server |
-| `REDIS_URL` | various | ❌ | — | Yes | server |
+| `VALKEY_URL` | `@terreno/api` realtime adapter **and** `rateLimit.store: "redis"` | ❌ | — | Yes | server |
+| `REDIS_URL` | `@terreno/api` fallback after `VALKEY_URL` (realtime + Redis rate-limit store) | ❌ | — | Yes | server |
+
+There is **no** `RATE_LIMIT_ENABLED` (or similar) read by `@terreno/api`. Apps that want an env toggle pass `rateLimit: process.env.RATE_LIMIT_ENABLED === "true" ? {store: "memory"} : undefined` themselves. See [Rate limiting](../how-to/rate-limiting.md).
 
 ## Webhooks & notifications
 
@@ -177,7 +212,12 @@ Sender identity must be verified in SendGrid before real delivery works.
 | `GOOGLE_CHAT_WEBHOOK_URL` | scripts | ❌ | — | Yes | server |
 | `ZOOM_CHAT_WEBHOOKS` | `@terreno/api` | ❌ | — | Yes | server |
 | `ZOOM_WEBHOOK_URL` | scripts | ❌ | — | Yes | server |
-| `WEBHOOK_SECRET` | webhooks | ❌ | — | Yes | server |
+| `WEBHOOK_SECRET` | example-backend HMAC demo | ❌ | — | Yes | server |
+
+`WEBHOOK_SECRET` is read only by the example HMAC route (`POST /webhooks/example`).
+`@terreno/api` `WebhooksApp` does not read it. Twilio/SendGrid inbound paths use adapter
+secrets and `PUBLIC_API_URL` / `COMMS_WEBHOOK_PUBLIC_URL` as above. See
+[Receive inbound webhooks](../how-to/inbound-webhooks.md).
 
 ## Admin SPA
 
@@ -199,13 +239,39 @@ Sender identity must be verified in SendGrid before real delivery works.
 | `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 |
 |----------|---------|----------|---------|--------|-------|
-| `FLOURISH_SERVICE` | OpenTelemetry | ❌ | `flourish-backend` | No | server |
+| `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 |
@@ -239,3 +305,5 @@ Sender identity must be verified in SendGrid before real delivery works.
 - [Deployment baseline](../explanation/deployment-baseline.md)
 - [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)