@terreno/mcp 57.2.0 → 57.3.0

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

@@ -26,8 +26,10 @@ REST API framework built on Express and Mongoose. Provides modelRouter (CRUD end
 - Logging: `logger`, `createScopedLogger`, `createFeatureFlaggedLogger`, `setupLogging`, `formatLogContextSuffix`
 - Correlation: `runWithRequestContext`, `getCurrentLogContext`, `requestContextMiddleware`, `REQUEST_CONTEXT_ATTRIBUTE_NAMES`
 - `createOpenApiBuilder`
+- Seeds: `runSeeds`, `runSeedCli`, `seedBetterAuthUser`
 - `githubUserPlugin`, `setupGitHubAuth`, `addGitHubAuthRoutes`
-- Mongoose plugins: `findExactlyOne`, `findOneOrNone`, `upsertPlugin`, `DateOnly`
+- `AuthToken`, `AUTH_TOKEN_TTL` (hashed single-use password-reset / email-verification tokens)
+- Mongoose plugins: `findExactlyOne`, `findOneOrNone`, `upsertPlugin`, `DateOnly`, `emailVerificationPlugin`
 - Validation: `configureOpenApiValidator`, `validateRequestBody`, `validateQueryParams`, `createValidator`
 - Middleware: `openApiEtagMiddleware`, `sentryAppVersionMiddleware`
 - Extensibility: `TerrenoPlugin` interface
@@ -38,6 +40,14 @@ REST API framework built on Express and Mongoose. Provides modelRouter (CRUD end
 
 Two patterns for building Terreno APIs:
 
+### Deprecated: modelRouter `realtime`
+
+`modelRouter({ realtime })` (RTK cache-patching websocket events) is **deprecated** and **will be removed in Terreno 58**. Use `sync` with [`@terreno/syncdb`](syncdb.md). See [Migrate from RTK to syncdb](../how-to/migrate-rtk-to-syncdb.md).
+
+`RealtimeApp` is **not** deprecated. It still hosts Socket.io, change streams, and `sync:delta`.
+
+Keep `admin.realtime` when you want admin `admin:model.changed` events.
+
 ### TerrenoApp (Recommended)
 
 Fluent API with a register pattern:
@@ -69,6 +79,43 @@ const app = new TerrenoApp({userModel: User})
 - `build()` — Build Express app without listening
 - `start()` — Build and start server
 
+### HTTP rate limiting
+
+Opt-in. Pass `rateLimit: {}` on `TerrenoApp` to enable (omitted = off; Terreno 58 defaults on).
+
+```typescript
+new TerrenoApp({
+  userModel: User,
+  rateLimit: process.env.RATE_LIMIT_ENABLED === "true" ? {store: "memory"} : undefined,
+});
+```
+
+| Option | Default | Meaning |
+|--------|---------|---------|
+| `store` | `"memory"` | `"memory"` \| `"redis"` \| `"mongo"` |
+| `limits.authMax` | 20 / 15 min | login, signup, refresh, OTP, GitHub OAuth, Better Auth sign-in / sign-up / password reset / OAuth callback |
+| `betterAuthBasePath` | `BetterAuthApp` `config.basePath` or `/api/auth` | Prefix used to classify Better Auth credential routes |
+| `limits.apiMax` | 600 / 15 min | modelRouter and other HTTP |
+| `trustProxy` | `false` | Express `trust proxy`. Use `1` on Cloud Run. Unauthenticated key is `req.ip` |
+
+Skip: `GET /health`, `/healthz`, `/openapi.json`, `/swagger` (trailing slashes and letter case ignored). 429 is `APIError` `code: "rate-limit-exceeded"` with `Retry-After` and `RateLimit` / `RateLimit-Policy`. JWT login/signup/refresh ignore a stale access token. Operator guide: [Rate limiting](../how-to/rate-limiting.md).
+
+### MCP service tokens
+
+Opt-in. Omitted or `enabled: false` leaves `/mcp/service-tokens` unmounted and ignores `mcp_` Bearer credentials on `/mcp`.
+
+```typescript
+new TerrenoApp({
+  userModel: User,
+  mcpServiceTokens: {
+    enabled: true,
+    publicMcpUrl: process.env.PUBLIC_API_URL,
+  },
+});
+```
+
+`mcpServiceTokens: true` is `{enabled: true}`. When enabled, TerrenoApp mounts the self-serve routes (passing its OpenAPI bundle) and sets `mcpServiceTokens` on MCP auth. Operator steps: [Connect an MCP client with a service token](../how-to/connect-mcp-service-token.md).
+
 ### setupServer (Legacy)
 
 Callback-based pattern:
@@ -84,7 +131,11 @@ setupServer({
 });
 ``````
 
-Both patterns create the same middleware stack (CORS, auth, logging, OpenAPI).
+Both patterns create the same middleware stack (CORS, auth, logging, OpenAPI). HTTP rate limiting is a `TerrenoApp` option only — migrate from `setupServer` to `TerrenoApp` to enable it.
+
+## Collection catalog
+
+`modelRouter("/path", Model, options)` writes one catalog record per route path. MCP, realtime, and sync surfaces read that record; TerrenoApp calls `replaceCollectionOptions` once when access control is injected. Test helpers `clearMCPRegistry`, `clearRealtimeRegistry`, and `clearSyncRegistry` clear the entire catalog.
 
 ## MCP tools
 
@@ -102,6 +153,34 @@ const todoRouter = modelRouter("/todos", Todo, {
 
 Cross-model tools use `registerMCPTool` (see the example backend's `users_todo_statuses`). How-to: [Expose MCP tools](../how-to/expose-mcp-tools.md). In-process Vercel AI SDK wrappers: `getMCPTools` from `@terreno/ai`.
 
+Create, update, and delete tools share REST permission, hook, and persistence semantics: they call the same `executeCreate` / `executeUpdate` / `executeDelete` pipeline. MCP error results use `APIError.title` (for example `Create not allowed`, `preCreate hook error`). User-role stripping for RBAC User writes happens in the executor after hooks; MCP supplies the registry `modelName` for that check. List and read stay MCP handlers. `excludeFields` and `mcpResponseHandler` still apply after the executor returns. Invalid ids on instance writes 404 only when the document `_id` cannot be cast, not when a populate ref fails.
+
+### MCP service token model
+
+`McpServiceToken` stores the hashed credential records used by the optional MCP service-token feature. It is not a `modelRouter` model: consumer-facing create, list, and revoke routes are registered only when `mcpServiceTokens` is enabled on `TerrenoApp`.
+
+```typescript
+import {McpServiceToken} from "@terreno/api";
+
+const {mcpServiceToken, token} = await McpServiceToken.issueFor(
+  {_id: user._id},
+  {name: "Perplexity"}
+);
+// Store or show `token` once. Only its SHA-256 hash is persisted.
+```
+
+The token begins with `mcp_` followed by 32 random bytes encoded as hex. `verify(token)` returns `null` for unknown, expired, or revoked tokens. `revokeForUser(user, tokenId)` records `revokedAt`, and `countActiveForUser(userId)` excludes expired or revoked records. Document `deleteOne` (admin DELETE) also sets `revokedAt` and leaves the row for audit. Never return or log `tokenHash` or the plaintext token outside the initial issue result.
+
+Self-serve HTTP routes live at `/mcp/service-tokens`. `TerrenoApp` mounts them when `mcpServiceTokens` is enabled, passing its OpenAPI bundle. You can also call `addMcpServiceTokenRoutes(app, {publicMcpUrl, openApi})` yourself. They require session or JWT auth and **reject** `Authorization: Bearer mcp_…` so a service token cannot mint or list tokens.
+
+| Method | Path | Body / params | Response |
+| --- | --- | --- | --- |
+| POST | `/mcp/service-tokens` | `{name, expiresAt?}` | `{data: {id, name, token, tokenPrefix, mcpUrl, expiresAt, created}}` |
+| GET | `/mcp/service-tokens` | `?page&limit` | `{data, page, limit, total, more}` — no `token` or `tokenHash` |
+| DELETE | `/mcp/service-tokens/:id` | — | `{data: {id, revokedAt}}` — owner only |
+
+`expiresAt` is an optional ISO-8601 datetime (Luxon `DateTime.fromISO`). Omit it for a token that does not expire. Create returns `mcpUrl` from `publicMcpUrl`, else `BETTER_AUTH_URL`, else the request host, with `/mcp` appended when missing. An 11th **active** token for the same user is `400`. Revoke and cross-owner access are `404`. List includes revoked rows for the owner so the UI can show history. Default page size is 100 (maximum 100).
+
 ## Authentication
 
 @terreno/api includes built-in authentication with multiple strategies:
@@ -128,9 +207,46 @@ setupServer({
 - `POST /auth/signup` — Create user account
 - `POST /auth/login` — Authenticate with email/password
 - `POST /auth/refresh_token` — Refresh access token
+- `POST /auth/forgotPassword` — Always 202; mails a reset link only when the email exists
+- `POST /auth/resetPassword` — `{token, password}`; also aliased at `POST /resetPassword` for the RTK client
+- `POST /auth/sendVerification` — Authenticated; 202 only after delivery succeeds; mails a verification link when `emailVerified` is not true
+- `POST /auth/verifyEmail` — `{token}` sets `emailVerified` true
 - `GET /auth/me` — Get current user profile
 - `PATCH /auth/me` — Update current user profile
 
+Signup and `PATCH /auth/me` drop privileged fields: `admin`, `roles`, `organizationIds`,
+`emailVerified`, and `tokenEpoch`. Request logs redact `password`, `newPassword`,
+`oldPassword`, `token`, and `refreshToken` in request bodies and in URL query strings. Changing the mailbox through `PATCH /auth/me`
+invalidates unused `passwordReset` AuthTokens for that user even when the schema has no
+`emailVerified` field. When the schema uses `emailVerificationPlugin`, mailbox change also
+sets `emailVerified` to false and invalidates unused `emailVerification` tokens; changing letter
+casing alone does not.
+
+**AuthToken (password reset / email verification):** hashed single-use tokens live in a separate
+`AuthToken` collection, not on User. `AuthToken.issueFor(user, type)` invalidates other
+unused, unexpired tokens of that type for the same user, then returns a 32-byte hex
+plaintext once and stores only the SHA-256 hash. `AuthToken.consume(token, type)` atomically
+marks one unused, unexpired row. TTL is 1 hour for `passwordReset` and 24 hours for
+`emailVerification` (`AUTH_TOKEN_TTL`). Mongo also TTL-indexes `expiresAt`.
+
+Wire `authOptions.publicAppUrl` and `authOptions.sendMail` (typically
+`getCommsService().sendMail`) so forgot-password can deliver the link
+`${publicAppUrl}/resetPassword?token=...`. Forgot-password skips issuing a token when
+`publicAppUrl` is missing. Authenticated `POST /auth/sendVerification` returns 501 in that
+case instead of 202. Email lookup is case-insensitive. Successful reset calls `setPassword`, increments
+`tokenEpoch` so outstanding **refresh** tokens fail, and returns new JWT tokens. When
+`BetterAuthApp` is registered, JWT reset also updates that user's Better Auth password
+and deletes Better Auth sessions. Better Auth password reset updates the JWT password
+and `tokenEpoch` for the matching app User. Access
+tokens stay valid until expiry (default 15m). `POST /resetPassword`
+matches the `@terreno/rtk` `resetPassword` mutation path (`password` or `newPassword`).
+
+Add `tokenEpoch` (number, default 0) on the User schema so epoch bumps persist under
+`strict: "throw"`. See `example-backend` User. Opt in to `emailVerified` with
+`emailVerificationPlugin`. Set `authOptions.requireEmailVerification` to reject login
+with 403 `email-not-verified` until `POST /auth/verifyEmail`. Signup still returns JWTs
+and sends `${publicAppUrl}/verifyEmail?token=...` so the user can complete verification.
+
 **Environment variables:**
 - `TOKEN_SECRET` — JWT signing secret (required)
 - `TOKEN_ISSUER` — JWT issuer claim (required)
@@ -197,6 +313,15 @@ app.register(new BetterAuthApp({config: betterAuthConfig, userModel: User}));
 const server = app.start();
 ``````
 
+Set `publicAppUrl`, `sendMail`, and `renderAuthMail` (from `@terreno/comms`) so Better Auth
+`sendResetPassword` / `sendVerificationEmail` use the same templates as JWT recovery mail.
+Those hooks throw 501 and do not send when `publicAppUrl` is missing, so links are never
+relative. Password reset also sets `revokeSessionsOnPasswordReset`, so existing Better Auth sessions
+are deleted when that reset path succeeds. JWT `POST /auth/resetPassword` updates the
+Better Auth password and deletes those sessions when `BetterAuthApp` is registered.
+Optional `authMailTemplates` overrides
+subject/text/html per template id.
+
 **Endpoints (when enabled):**
 - `POST /api/auth/signup/email` — Email/password signup
 - `POST /api/auth/signin/email` — Email/password signin
@@ -403,6 +528,21 @@ userSchema.plugin(baseUserPlugin);
 // - admin: boolean (default: false)
 ``````
 
+### emailVerificationPlugin
+
+Opt-in `emailVerified` boolean for user schemas. Defaults to `false` so existing users stay
+unverified until they complete the verification flow. Apply this plugin; do not add the
+field by hand.
+
+``````typescript
+import {emailVerificationPlugin, type EmailVerified} from "@terreno/api";
+
+userSchema.plugin(emailVerificationPlugin);
+
+// Adds:
+// - emailVerified: boolean (default: false)
+``````
+
 ### firebaseJWTPlugin
 
 Firebase authentication integration.
@@ -491,6 +631,10 @@ router.use("/todos", modelRouter(Todo, {
 }));
 ``````
 
+### Builder validation
+
+Call `.withValidation()` before `.build()` so body and query checks run in the same handler that documents the route. `build()` still returns one Express `RequestHandler`, so callers can nest it in a middleware array. OpenAPI metadata stays on that handler, so the route remains in `/openapi.json`.
+
 ### Manual Validation
 
 For custom routes, use validation middleware directly:
@@ -608,6 +752,46 @@ router.post("/todos", [
 
 **Learn more:** See `api/src/openApiValidator.ts` for advanced usage and `api/src/api.ts` for modelRouter integration.
 
+## describeModel
+
+Walk a Mongoose model once and get a canonical field graph (`ModelDescription`). OpenAPI, admin config, and MCP Zod tools format that graph instead of re-walking `schema.paths`.
+
+``````typescript
+import {
+  describeModel,
+  describeModelForRouter,
+  modelDescriptionToOpenApiSpec,
+  modelDescriptionToAdminFields,
+  fieldDescriptionToZodType,
+} from "@terreno/api";
+
+const description = describeModel(Todo);
+const openApi = modelDescriptionToOpenApiSpec(description);
+const adminFields = modelDescriptionToAdminFields(description);
+``````
+
+### Field kinds
+
+| Kind | Description |
+|------|-------------|
+| `string` | String (optional `enum`) |
+| `number` | Number |
+| `boolean` | Boolean |
+| `date` | Date (OpenAPI `date-time`) |
+| `dateOnly` | Terreno DateOnly type |
+| `objectId` | ObjectId with optional `ref` |
+| `embedded` | Subdocument or array of subdocuments |
+| `mixed` | Schema.Types.Mixed |
+| `map` | Map type (`item` is the `of` kind; omitted `of` is `mixed`) |
+
+Each field includes `required`, optional `description`, `isArray`, nested `item` / `fields`, and `system` for `_id`, `__v`, `created`, `updated`, `deleted`.
+
+`describeModelForRouter(model, options)` adds `writableOnCreate` and `writableOnUpdate` using the same rules as MCP system-field exclusions and router validation / field views.
+
+`getOpenApiSpecForModel` builds HTTP body schemas from `ModelDescription`; populate merging for referenced models is unchanged.
+
+See [Schema metadata explanation](../explanation/schema-metadata.md).
+
 ## Middleware
 
 ### openApiEtagMiddleware
@@ -939,6 +1123,35 @@ setupServer({
 
 ## Webhooks & Notifications
 
+JSON and `application/x-www-form-urlencoded` parsers on `TerrenoApp` copy the original
+bytes onto `req.rawBody` (`Buffer`) so inbound webhook signatures can be verified
+without re-serializing `req.body`.
+
+Register inbound routes on `WebhooksApp`. Helpers: `hmacSignature`, `stripeSignature`,
+`twilioSignature`, `sendgridEventSignature`. Timestamped HMAC, Stripe, and SendGrid
+reject timestamps outside a 300s window by default. Idempotency is `memory` or `mongo`
+(`webhookReceipts`). Paths are not added to `/openapi.json` and do not use JWT.
+
+```typescript
+import {hmacSignature, TerrenoApp, WebhooksApp} from "@terreno/api";
+
+const webhooks = new WebhooksApp({idempotency: {store: "mongo"}});
+webhooks.route({
+  path: "/webhooks/example",
+  source: "example",
+  verify: hmacSignature({secret: process.env.WEBHOOK_SECRET!, header: "X-Webhook-Signature"}),
+  eventId: (req) => String((req.body as {id?: string})?.id ?? ""),
+  handler: async () => {
+    // process event
+  },
+});
+
+new TerrenoApp({userModel: User}).register(webhooks).start();
+```
+
+Call `webhooks.claim` / `webhooks.release` from a handler when one HTTP body contains
+nested ids (SendGrid `sg_event_id`). Operator guide: [Receive inbound webhooks](../how-to/inbound-webhooks.md).
+
 ### Slack Notifications
 
 ``````typescript
@@ -1123,6 +1336,25 @@ for (let i = 0; i < 3; i++) {
 
 ## Script Helpers
 
+### runSeeds and runSeedCli
+
+Define ordered `SeedStep` entries and run them in the default `sync` mode or in
+`reset` mode. The `SeedContext` provides:
+
+- `upsert(model, key, values)` — creates, updates, or reports unchanged data. Nested values ignore generated `_id`s. `Map` payloads compare as plain objects. Soft-deleted matches are restored instead of duplicated. Duplicate key matches keep the first document and remove the extras.
+- `deleteMany(model, filter?)` — reset helper with dry-run support
+- `mode`, `dryRun`, and structured `changes`
+
+`runSeedCli` adds `--dry-run`, `--reset`, repeatable `--only`, `--force`, and
+`--help`. It returns an exit code instead of terminating the process; seed CLIs
+should `process.exit` after `disconnect` so leftover Better Auth handles cannot
+keep the event loop open. Production resets require both `--force` and an
+approving `allowProductionReset` option.
+See [Seed a database](../how-to/seed-a-database.md).
+
+`seedBetterAuthUser` provisions a credential account and reconciles the
+application user model without requiring a running HTTP server.
+
 ### wrapScript
 
 Error handling wrapper for scripts and cron jobs.
@@ -1133,7 +1365,7 @@ import {wrapScript} from "@terreno/api";
 wrapScript(async () => {
   // Your script logic
   await processData();
-  console.log("Script completed successfully");
+  logger.info("Script completed successfully");
 });
 ``````
 
@@ -1290,5 +1522,4 @@ SENTRY_DSN=https://...@sentry.io/...
 - [How to create a model](../how-to/create-a-model.md)
 - [Add GitHub OAuth](../how-to/add-github-oauth.md)
 - [Authentication architecture](../explanation/authentication.md)
-- [API package source](../../api/src/)
-- [AI assistant rules](./.cursor/rules/api/)
+- [API package source](https://github.com/flourishhealth/terreno/tree/master/api/src)

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`.