@terreno/mcp 57.0.0-beta.1 → 57.1.0

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

@@ -58,12 +58,25 @@ await getCommsService().sendSms({
 });
 ```
 
-`sendPushToUser()` resolves active device tokens and deactivates tokens only when a provider marks
-a failure as permanent. `startVerification()` and `checkVerification()` delegate to the configured
-verification provider. `startVerification()` accepts `channel: "sms"` or `channel: "email"`;
-`checkVerification()` verifies the code against the same phone number or email destination and may
-return an `error` reason when `valid` is false. Start attempts store the verification channel in
-delivery-log metadata while recipient values remain redacted.
+`sendPushToUser()` resolves active device tokens and deactivates tokens when
+`errorClass` is `"permanent"` or `isPermanentFailure` is `true`. Provider throws become
+`errorClass: "transient"` with `errorCode: "provider-throw"` and never reject the
+`CommsService` promise. Transient failures retry once (`onRetry` with
+`context.attempt === 2`); push retries only the failed tokens. `checkVerification()` does
+not retry.
+
+`beforeSend` may mutate the message or cancel (`status: "cancelled"`, no provider call).
+A throwing `beforeSend` is logged and treated as no-op (send continues). Adapters later
+call `recordDeliveryEvent()` / `recordOptOut()` to update the log and fire
+`onDeliveryEvent` / `onOptOut`.
+
+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.
 
 ## Provider contracts
 
@@ -77,17 +90,67 @@ delivery-log metadata while recipient values remain redacted.
 Concrete SendGrid, Twilio, and Expo providers are separate adapter packages/subpath exports. Core
 `@terreno/comms` has no concrete provider SDK dependencies.
 
+### SendGrid mail adapter
+
+```bash
+bun add @sendgrid/mail
+```
+
+```typescript
+import {CommsApp} from "@terreno/comms";
+import {SendGridMailProvider} from "@terreno/comms/adapters/sendgrid";
+
+new TerrenoApp({userModel: User})
+  .register(
+    new CommsApp({
+      defaultFrom: "notifications@example.com",
+      mail: new SendGridMailProvider({
+        // apiKey defaults to process.env.SENDGRID_API_KEY (required)
+        fromEmail: "notifications@example.com",
+        fromName: "Terreno",
+        // sandboxMode defaults to true when NODE_ENV === "test"
+      }),
+      onError: async (_context, result) => {
+        console.error("mail failed", result.errorCode, result.errorClass);
+      },
+    })
+  )
+  .start();
+```
+
+`SendGridMailProvider` fails fast at construction when `SENDGRID_API_KEY` (or `apiKey`) is
+missing. Send-time failures never throw through `sendMail`; they return
+`accepted: false` with `errorCode` / `errorClass` (`permanent` | `transient` | `config`).
+Transient failures are retried once by `CommsService`. Accepted sends store the SendGrid
+`x-message-id` and a `metadata.consoleUrl` Email Activity deep link on the `CommsMessage`
+row.
+
+**Sender verification checklist (SendGrid):**
+
+1. Create an API key with Mail Send permission.
+2. Verify the from domain (or single sender) in SendGrid.
+3. Confirm the from address matches a verified identity.
+4. Use sandbox mode in CI/tests so no real mail is delivered.
+
 ## Configuration
 
 ```typescript
 interface CommsAppOptions {
   basePath?: string; // default: "/comms"
+  beforeSend?: (context: CommsHookContext) =>
+    Promise<{cancel?: boolean; message?: CommsHookMessage} | undefined>;
   defaultFrom?: string;
   logMessages?: boolean; // default: true
   mail?: MailProvider;
   onDeliveryEvent?: (event: DeliveryEvent) => Promise<void>;
+  onError?: (context: CommsHookContext, result: SendResult) => Promise<void>;
+  onOptOut?: (event: OptOutEvent) => Promise<void>;
+  onRetry?: (context: CommsHookContext, result: SendResult) => Promise<void>;
+  onSend?: (context: CommsHookContext, result: SendResult) => Promise<void>;
   push?: PushProvider;
+  redactPayload?: (context: CommsHookContext, payload: unknown) => unknown;
   redactRecipients?: boolean; // default: true
+  retainPayloadDays?: number; // default: 30; 0 stores no payload
   sms?: SmsProvider;
   verification?: VerificationProvider;
 }
@@ -99,7 +162,25 @@ When a channel is unconfigured:
 - production throws a `501` `APIError` titled `Comms channel not configured`.
 
 Delivery attempts are stored in `CommsMessage`. Recipient values are stored as `[redacted]` unless
-`redactRecipients` is explicitly `false`.
+`redactRecipients` is explicitly `false`. Rendered payloads are retained for `retainPayloadDays`
+(default 30) after `redactPayload`; expired payloads are unset without deleting the log row.
+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).
+
+`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
+`errorClass` is `"transient"` (`context.attempt === 2`; shipped signature is `(context, result)`).
+Throwing hooks are logged and never change the send outcome. Exception text stays in logs;
+`metadata.hookErrors` records only `hook-threw` per hook name. Adapters should call
+`recordDeliveryEvent()` and `recordOptOut()` rather than invoking those hooks directly.
+
+Provider throws become `{accepted: false, errorClass: "transient", errorCode: "provider-throw"}`.
+Permanent and config failures are not retried. Push retries re-send only the tokens whose first
+result was transient; tokens are deactivated when `errorClass` is `"permanent"` or
+`isPermanentFailure` is true. Each push token gets its own hook context (`attempt`, `isRetry`,
+`messageId`).
 
 ## Routes
 

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

@@ -133,9 +133,17 @@ Resolution order for API base URL (`rtk/src/constants.ts`):
 | Variable | Read by | Required | Default | Secret | Scope |
 |----------|---------|----------|---------|--------|-------|
 | `COMMS_ENABLED` | example-backend | ❌ | `true` | No | server |
+| `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_SANDBOX_MODE` | example-backend | ❌ | — | No | server |
 
 Set `COMMS_ENABLED=false` to omit the example backend's communications plugin and routes.
-Provider credentials are documented by their separate adapter packages.
+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.
+Sender identity must be verified in SendGrid before real delivery works.
 
 ## Observability
 

package/dist/docs/versioned/next/reference/{rtk.md → legacy/rtk.md}

@@ -1,4 +1,8 @@
-# @terreno/rtk
+# @terreno/rtk (legacy)
+
+> **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.
 
 Redux Toolkit Query utilities for frontends using @terreno/api backends. JWT auth, token storage, SDK code generation from OpenAPI, and real-time WebSocket connections.
 
@@ -114,7 +118,7 @@ export const store = configureStore({
 }
 ``````
 
-**Learn more:** [Configure Better Auth](../how-to/configure-better-auth.md)
+**Learn more:** [Configure Better Auth](../../how-to/configure-better-auth.md)
 
 ## WebSocket Integration
 
@@ -439,8 +443,8 @@ EXPO_PUBLIC_API_URL=http://localhost:4000
 
 ## Related Documentation
 
-- [Authentication Architecture](../explanation/authentication.md) — Deep-dive into JWT + Passport system
-- [WebSocket Integration How-To](../how-to/websocket-integration.md) — Real-time connection setup
-- [Add GitHub OAuth](../how-to/add-github-oauth.md) — Step-by-step OAuth setup guide
-- [@terreno/api Reference](./api.md) — Backend API framework
-- [@terreno/ui Reference](./ui.md) — React Native components
+- [Authentication Architecture](../../explanation/authentication.md) — Deep-dive into JWT + Passport system
+- [WebSocket Integration How-To](../../how-to/websocket-integration.md) — Real-time connection setup
+- [Add GitHub OAuth](../../how-to/add-github-oauth.md) — Step-by-step OAuth setup guide
+- [@terreno/api Reference](../api.md) — Backend API framework
+- [@terreno/ui Reference](../ui.md) — React Native components

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

@@ -0,0 +1,54 @@
+# Lifecycle plugin reference
+
+Plugin: `terreno-planning` (`2.0.0`)
+
+All five skills are explicitly invoked (`disable-model-invocation: true`) and implement
+one bounded transition.
+
+| 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 |
+
+Every stage includes:
+
+- Preconditions
+- Inputs
+- Procedure
+- Supporting skills
+- Evidence produced
+- 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
+[`execution-state.schema.json`](https://github.com/FlourishHealth/terreno/blob/master/plugins/terreno-planning/references/execution-state.schema.json).
+
+The outer loop owns state persistence, waiting, stage invocation, retries, and escalation.
+Brew exits after PR setup. Taste observes/acts once and exits.
+
+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.
+
+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.
+
+Install the published skill set (lifecycle stages plus repo and package skills):
+
+```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.
+
+Exact commands and domain conventions are supplied by repository-local skills discovered
+at stage start; they are not bundled into the lifecycle plugin.
+

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

@@ -7,6 +7,13 @@ Published npm package for the Terreno Model Context Protocol (MCP) server. The m
 
 It provides AI coding assistants with documentation access, code generation tools, and workflow prompts.
 
+Both HTTP MCP surfaces (`@terreno/mcp` and the `modelRouter` endpoint in
+`@terreno/api`) use the MCP TypeScript SDK v2 and speak the stateless
+`2026-07-28` protocol revision. The HTTP handlers retain the SDK's stateless
+legacy fallback for 2025-era clients. `terreno-mcp-local` uses v2 `serveStdio`,
+which negotiates the connection era and pins one server instance for that
+connection.
+
 ## Table of Contents
 
 - [Overview](#overview)

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

@@ -10,6 +10,7 @@ Local-first data layer for Terreno frontends. A TinyBase `MergeableStore` on dev
 - [createSyncDb configuration](#createsyncdb-configuration)
 - [SyncDb client methods](#syncdb-client-methods)
 - [React hooks](#react-hooks)
+- [Codegen](#codegen)
 - [Conflict API](#conflict-api)
 - [Sync status API](#sync-status-api)
 - [Stream scoping](#stream-scoping)
@@ -24,7 +25,8 @@ Local-first data layer for Terreno frontends. A TinyBase `MergeableStore` on dev
 - `createSyncDb`, `SyncDb`, `SyncDbConfig`, `MutateArgs`
 - `betterAuthAdapter`, `AuthProvider`
 - `listConflicts`, `wipeLocalData`, `generateMutationId`
-- React (`@terreno/syncdb/react`): `SyncDbProvider`, `useEntity`, `useQuery`, `useEntityIds`, `useMutate`, `useSyncStatus`, `useConflicts`, `useSyncDebugLog`
+- React (`@terreno/syncdb/react`): `SyncDbProvider`, `useEntity`, `useQuery`, `useEntityIds`, `useMutate`, `useSyncStatus`, `useConflicts`, `useSyncDebugLog`, `createCollectionHooks`
+- CLI: `terreno-syncdb-codegen` (generates `SYNC_COLLECTIONS` + friendly hooks from OpenAPI)
 - Testing (`@terreno/syncdb/testing`): `createFakeTransport`
 
 ## Installation
@@ -181,7 +183,7 @@ export const syncDb = createSyncDb({
 | `goOffline()` | Simulated outage: disconnect transport, pause replay/reconcile/timer; local mutations keep queueing. |
 | `goOnline()` | End simulated outage; reconnect triggers reconcile + outbox replay. |
 | `mutate({collection, operation, id?, data?})` | Optimistic local write + durable outbox enqueue + fire-and-forget replay. Returns `{mutationId, id}`. |
-| `reconcile()` | HTTP snapshot catch-up for every known stream; runs tombstone compaction on success. |
+| `reconcile()` | HTTP snapshot catch-up for every known stream; runs tombstone compaction on success. Also runs automatically on (re)connect, on a rate-limited seq-jump hint, and on the periodic timer; each `sync:subscribed` confirmation additionally pages just the streams it names. |
 | `forceResync()` | Purge every known stream locally and re-bootstrap from cursor 0 (outbox/conflicts untouched). Returns `{ok, reason?, streams, purged, repaired}`. |
 | `replayOutbox()` | Drain queued mutations for the current user now. |
 | `resolveConflict({mutationId, strategy})` | Apply `"useServer"` or `"keepMine"` to a recorded conflict. |
@@ -199,6 +201,7 @@ Import from `@terreno/syncdb/react`:
 
 ```typescript
 import {
+  createCollectionHooks,
   SyncDbProvider,
   useConflicts,
   useEntity,
@@ -289,6 +292,30 @@ Available when the client was created with `debug: true`. `log?.snapshot()` retu
 
 Returns the `SyncDb` instance from context (escape hatch for imperative calls like `forceResync()`).
 
+### `createCollectionHooks`
+
+Factory used by `terreno-syncdb-codegen` and by hand-written custom collections. Returns five operation hooks (`useListQuery`, `useReadQuery`, `useCreateMutation`, `useUpdateMutation`, `useDeleteMutation`). Generated SDKs rename them to friendly names (`useTodos`, `useTodo`, `useCreateTodo`, …). Mutation hooks return `[trigger]`; triggers apply locally and return `{mutationId, id}` synchronously. Optional `retries` maps to `maxAttempts` (`false` → 1, a number → that many, omitted → engine default).
+
+```typescript
+export const {useListQuery: useNotes, useCreateMutation: useCreateNote} =
+  createCollectionHooks<Note, CreateNoteBody, UpdateNoteBody>({
+    collection: "notes",
+  });
+```
+
+## Codegen
+
+`terreno-syncdb-codegen` is a bin of `@terreno/syncdb`. It reads OpenAPI, discovers list operations with `x-terreno-sync`, and writes typed hooks plus `SYNC_COLLECTIONS`.
+
+```bash
+terreno-syncdb-codegen \
+  --schema http://localhost:4000/openapi.json \
+  --out ./store/syncDbSdk.ts \
+  --config ./syncdb-codegen.json
+```
+
+Do not edit the generated file. `--collections` filters when extensions exist. When they do not, it reads list/create/patch schemas from `GET /{name}` (or `/{name}/`). A missing path, a list response without `data.items`, a spec with no extensions and no `--collections` all exit non-zero.
+
 ## Conflict API
 
 A **conflict** occurs when the client's `baseVersion` (last seen `_syncSeq`) does not match the server's current seq. The server responds with a `conflict` nack (HTTP **409** on `POST /sync/mutate`, or `sync:nack` with `code: "conflict"` on the socket) carrying the canonical server document.
@@ -380,7 +407,7 @@ Conflict responses on mutate: **409** with `{nack}` body (`code: "conflict"`).
 | Event | Direction | Payload |
 |-------|-----------|---------|
 | `sync:subscribe` / `sync:unsubscribe` | client → server | `{collections: string[]}` |
-| `sync:subscribed` | server → client | `{collection, streams}` |
+| `sync:subscribed` | server → client | `{collection, streams}` — sent after the stream rooms are joined; the client pages each confirmed stream from its cursor so a write landing between the startup snapshot and the join is not missed |
 | `sync:error` | server → client | `{collection, message}` |
 | `sync:delta` | server → client | `{collection, id, method, data?, seq, stream, deleted?, frontierSeq?}` |
 | `sync:mutate` | client → server | `{mutationId, collection, operation, id?, data?, baseVersion?}` |

package/dist/docs/versioned/next/tasks/README.md

@@ -1,29 +1,39 @@
 # Task lists
 
-Bot-consumable execution checklists, one per implementation plan (IP). A task file is
-the second half of the pair described in
-[`docs/implementationPlans/README.md`](../implementationPlans/README.md):
+Bot-consumable execution checklists. Most files pair with an implementation plan (IP)
+as described in [`docs/implementationPlans/README.md`](../implementationPlans/README.md):
 
 - **IP** (`docs/implementationPlans/<slug>.md`) — the design: what and why.
 - **Task list** (`docs/tasks/<slug>.md`) — the steps: the concrete, ordered work.
 
 The filename slug matches the IP it belongs to.
 
+The loop's small-feature profile may use a task file with `**Feature profile:** true` and
+no full IP when repository policy permits. The destination, scope, decisions, acceptance
+criteria, tracer, and verification seam live in that durable contract so a fresh Pick
+agent can implement one task without conversation history.
+
 ## Task shape
 
-Each task is a checkbox with four fields so it can be picked up and verified independently:
+Each task is a tracer-bullet vertical slice with explicit blocking edges:
 
 ```markdown
 - [ ] **Task 1.1**: Short title
-  - Description: what to implement
+  - Delivers: the narrow end-to-end behavior this makes usable
   - Files: expected files to create or modify
-  - Depends on: none | other task IDs
-  - Acceptance: how to verify it is done
+  - Blocked by: none | other task IDs
+  - Acceptance: observable proof, including focused Bun tests
 ```
 
-Group tasks by phase (`### Phase 1: …`). Order them by dependency — models first, then
-APIs, then UI. Blend-style runs may append a **Plan vs Actual** log to the same file after
-each task.
+Group tasks by phase (`### Phase 1: …`) and order them by dependency. Every normal task
+cuts through the required data, API, UI, documentation, and test layers rather than
+batching one layer across the whole feature. A completed task is demoable or independently
+verifiable and small enough for one fresh agent context. Work the **frontier**: any task
+whose blockers are complete.
+
+Wide mechanical refactors that cannot land green as vertical slices use
+**expand → migrate batches → contract**. The contract task is blocked by every migration
+batch. Grow-style runs may append a **Plan vs Actual** log after each task.
 
 ## What lives here vs elsewhere
 
@@ -33,6 +43,7 @@ each task.
 | Concrete task steps and their status | this directory |
 | Public status and target | GitHub roadmap issue / Project (roadmap-enabled repos) |
 | Sprint estimates and assignees | Linear |
+| Current stage/attempt/head/result | loop-owned execution state (default `.terreno/pipeline/<slug>.json`) |
 
 Do not copy the full checklist into a GitHub issue or Linear. Create linked GitHub child
 issues only for tasks that outside contributors should be able to claim independently; the