@terreno/mcp 57.1.0 → 57.3.0

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

@@ -76,7 +76,8 @@ 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 +98,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 +113,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 +139,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 +325,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 +351,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 +385,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/environment-variables.md

@@ -66,7 +66,7 @@ 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 |
 
@@ -136,14 +136,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 +195,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 +210,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
 
@@ -203,7 +241,7 @@ Sender identity must be verified in SendGrid before real delivery works.
 
 | 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 |
 | `DEFAULT_PAGE_SIZE` | Configuration model | ❌ | `20` | No | server |
@@ -239,3 +277,4 @@ 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)

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

@@ -122,6 +122,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.0.0`)
+Plugin: `terreno-planning` (`2.8.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 | 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 |
+
+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:
 
@@ -23,13 +34,39 @@ Every stage includes:
 - Success, failure, and blocked conditions
 - Recommended next stage
 
-Results use `PASS`, `FAIL`, `BLOCKED`, or `PENDING` and follow
-[`stage-result.schema.json`](https://github.com/FlourishHealth/terreno/blob/master/plugins/terreno-planning/references/stage-result.schema.json).
-Loop state follows
+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)
+(`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.
+
+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`, 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.
+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 outer loop owns state persistence, waiting, stage invocation, retries, and escalation.
-Brew exits after PR setup. Taste observes/acts once and exits.
+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.
 
 GitHub communication follows a fixed attention budget: `Why`, `What changed`, and
 `Verification` are the only visible PR sections; optional detail is expandable; comments
@@ -38,17 +75,53 @@ 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.
 
@@ -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)
 }
 ``````
 
@@ -333,12 +352,36 @@ Scaffold a new full-stack Terreno application (Expo frontend, Express/Mongoose b
   appName: string;           // kebab-case (e.g., "my-app")
   appDisplayName: string;    // Human-readable name
   description?: string;
-  mcpServerUrl?: string;     // Default: https://mcp.terreno.flourish.health
+  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).
@@ -380,6 +423,12 @@ Workflow prompt for scaffolding a new Terreno app. Delegates to `terreno_bootstr
 - `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.

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

@@ -125,15 +125,20 @@ new TerrenoApp({userModel: User})
 ```
 
 - **`SyncApp`** — HTTP sync routes (`/sync/snapshot`, `/sync/mutate`, `/sync/mutate/batch`, `/sync/key`, `/sync/streams`, `/sync/entities`).
-- **`RealtimeApp`** — Socket.io server with change-stream-driven `sync:delta` emission. Requires a **MongoDB replica set** (change streams).
-- **`ensureSyncIndexes`** — `TerrenoApp.start()` awaits index builds for snapshot queries and sync bookkeeping (`SyncMutation.mutationId` unique, `SyncCounter.stream` unique, etc.). Hosts that build Express without `TerrenoApp.start()` should await `ensureSyncIndexes()` themselves.
+- **`RealtimeApp`** — Socket.io server with change-stream-driven `sync:delta` emission. Requires a **MongoDB replica set** (change streams). `modelRouter` `realtime` (RTK `sync` events) is deprecated and removed in Terreno 58; do not add it to new models.
+- **`ensureSyncIndexes`** — `TerrenoApp.start()` awaits index builds for snapshot queries and sync bookkeeping (`SyncMutation.mutationId` unique, `SyncCounter.stream` unique, etc.). Registration queues this work without contacting MongoDB, so models can load before the database connects. Hosts that build Express without `TerrenoApp.start()` should await `ensureSyncIndexes()` after connecting.
 
-Socket auth accepts legacy JWTs by default. For Better Auth sessions:
+Socket auth requires at least one configured authentication method. It enables legacy JWT
+validation when `tokenSecret` or `TOKEN_SECRET` is available. Better Auth can be used without
+a JWT secret:
 
 ```typescript
 new RealtimeApp({betterAuth: {auth, userModel: User}})
 ```
 
+When both methods are configured, JWT validation runs first and Better Auth session validation
+is the fallback.
+
 ## createSyncDb configuration
 
 ```typescript

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

@@ -106,3 +106,25 @@ Defaults: `TOKEN_SECRET`, `TOKEN_ISSUER`, `REFRESH_TOKEN_SECRET`, `SESSION_SECRE
 - Preload once per package via `bunfig.toml`; do not start Mongo in individual test files.
 - Prefer `registerSimpleMongoPreload` unless you need transactions or fixture caching (`registerBackendPreload`).
 - Never mock `@terreno/api` or Mongoose models in package tests — use the real stack against memory Mongo.
+
+## Coverage gates
+
+Package CI uses `scripts/check-coverage.ts` to enforce the package-wide thresholds
+declared in `bunfig.toml`.
+
+Pull requests also run the `New file coverage` workflow. Every newly added workspace
+`.ts` or `.tsx` implementation file must have at least 90% function coverage and 90%
+line coverage. Test, spec, story, generated OpenAPI SDK, `dist`, isolated-test,
+`src/types` type modules, demo `story-config/*.config.tsx`, and Expo Router route
+files (`index`, `_layout`, `+not-found`, `[param]`, plus example recovery screens
+`forgotPassword` / `resetPassword` / `verifyEmail`) are excluded. A new implementation
+file that is absent from LCOV is treated as 0% covered. The gate runs each package's `bun test` file arguments (or `src` / `*.test.ts`
+globs) so Playwright `*.spec.ts` files are not collected. Globs are expanded in
+the coverage process before `bun test` is spawned, because spawn does not pass
+them through a shell. A glob that matches no files is omitted.
+
+Run the same check locally against a base commit:
+
+```bash
+bun run check:new-file-coverage --base=origin/master --threshold=90
+```