@terreno/mcp 0.31.0 → 56.0.0-beta.0

package/src/docs/versioned/next/implementationPlans/comms-abstraction.md

@@ -1,240 +0,0 @@
-# Implementation Plan: Pluggable communications layer (@terreno/comms)
-
-**Status:** Draft
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1018
-**Priority:** High
-**Effort:** Big batch
-**Owner:** unassigned
-**Created:** 2026-08-09
-**Program:** [B2B platform](b2b-platform-program.md)
-**Depends on:** none (inbound-webhooks is needed only by adapter delivery-callback phases)
-**RTK deprecation flag:** None — backend-only package
-
-## Goal
-
-Terreno backends cannot send email, SMS, or push notifications: there is no mail
-integration at all, `expo-server-sdk` sits unused in `@terreno/api`, and the RTK client's
-`resetPassword` call has no backend to talk to. This IP creates `@terreno/comms`, a new
-workspace package that defines **provider interfaces** for the four outbound channels
-(mail, SMS, push, OTP verification), a **`CommsApp`** TerrenoPlugin that registers
-configured providers and exposes send services to routes and other plugins, **push-token
-registration** routes and model, a **delivery log**, and **console adapters** so every
-channel works in development with zero external accounts.
-
-Concrete providers (Twilio, SendGrid, Expo push) are separate IPs — one per adapter — so
-consumer apps install only the SDKs they use.
-
-## Non-Goals
-
-- Any concrete provider SDK integration (see `comms-adapter-*` IPs).
-- In-app notification center, inbox UI, or user notification preferences
-  (`notification-center` item).
-- Password reset / email verification flows (`password-reset-and-email-verification` item
-  — a consumer of this layer).
-- Inbound webhook handling (`inbound-webhooks` item); this IP only defines the
-  `DeliveryEvent` type adapters will feed from callbacks.
-- Broadcast/bulk campaign tooling.
-
-## Decisions
-
-| Question | Decision |
-|----------|----------|
-| New package or `@terreno/api` module? | New package `@terreno/comms`, mirroring `@terreno/feature-flags` — keeps provider SDKs out of the core dependency tree |
-| How do provider SDKs stay optional? | Adapters live in subpath exports (`@terreno/comms/adapters/<name>`) with their SDKs as `peerDependencies` marked optional; core package has zero provider SDKs |
-| Precedent to follow | `secretProviders.ts` (env + GCP behind one interface) and the OpenFeature provider in `@terreno/feature-flags` |
-| Templates | Minimal: `{subject, text, html}` render helper with variable interpolation; no template builder |
-| Where do send calls log? | `CommsMessage` Mongoose model, mirroring the `AIRequest.logRequest` pattern — logging failures never break the send |
-| Dev experience | `ConsoleMailProvider` / `ConsoleSmsProvider` / `ConsolePushProvider` / `ConsoleVerificationProvider` print to logger and record to `CommsMessage`; default when no provider configured in non-production |
-
-## Architecture
-
-```
-@terreno/comms
-  src/
-    types.ts            # Provider interfaces + message/result types
-    commsApp.ts         # CommsApp TerrenoPlugin
-    commsService.ts     # sendMail/sendSms/sendPush/startVerification/checkVerification
-    models/
-      commsMessage.ts   # Delivery log
-      pushToken.ts      # Device push token registry
-    routes/
-      pushTokens.ts     # modelRouter for token registration
-      commsExplorer.ts  # Admin-only delivery log explorer
-    adapters/
-      console.ts        # Dev adapters for all four channels
-    templates.ts        # renderTemplate({subject, text, html}, data)
-```
-
-### Provider interfaces (types.ts)
-
-```typescript
-export interface SendResult {
-  providerMessageId?: string;
-  accepted: boolean;
-  error?: string;
-}
-
-export interface MailMessage {
-  to: string | string[];
-  from?: string;            // default from CommsApp options
-  subject: string;
-  text?: string;
-  html?: string;
-  replyTo?: string;
-  metadata?: Record<string, string>;
-}
-
-export interface MailProvider {
-  readonly id: string;      // "console" | "sendgrid" | ...
-  sendMail(message: MailMessage): Promise<SendResult>;
-}
-
-export interface SmsProvider {
-  readonly id: string;
-  sendSms(message: {to: string; body: string}): Promise<SendResult>;
-}
-
-export interface PushMessage {
-  tokens: string[];
-  title: string;
-  body: string;
-  data?: Record<string, unknown>;
-  badge?: number;
-  sound?: string | null;
-}
-
-export interface PushProvider {
-  readonly id: string;
-  sendPush(message: PushMessage): Promise<SendResult[]>; // one per token
-}
-
-export interface VerificationProvider {
-  readonly id: string;
-  startVerification(options: {to: string; channel: "sms" | "email"}): Promise<SendResult>;
-  checkVerification(options: {to: string; code: string}): Promise<{valid: boolean}>;
-}
-
-export interface DeliveryEvent {
-  channel: "mail" | "sms" | "push";
-  providerMessageId: string;
-  status: "delivered" | "bounced" | "failed" | "opened";
-  raw?: unknown;
-}
-```
-
-### CommsApp (TerrenoPlugin)
-
-```typescript
-export interface CommsOptions {
-  mail?: MailProvider;
-  sms?: SmsProvider;
-  push?: PushProvider;
-  verification?: VerificationProvider;
-  defaultFrom?: string;                       // mail from fallback
-  logMessages?: boolean;                      // default true → CommsMessage
-  onDeliveryEvent?: (event: DeliveryEvent) => Promise<void>;
-}
-
-new TerrenoApp({userModel: User})
-  .register(new CommsApp({mail: new ConsoleMailProvider(), push: new ExpoPushProvider()}))
-  .start();
-```
-
-`CommsApp.register()` mounts the push-token routes and admin explorer;
-`getCommsService()` (module-level accessor, mirroring how `FeatureFlagsApp` exposes
-evaluation) gives routes and other plugins `sendMail` / `sendSms` / `sendPushToUser` /
-`startVerification` / `checkVerification`. `sendPushToUser(userId, message)` resolves the
-user's active `PushToken`s and prunes tokens the provider reports dead.
-
-Unconfigured channel behavior: in production, throw `APIError({status: 501, title:
-"Comms channel not configured"})`; in development, fall back to the console adapter with a
-`logger.warn`.
-
-## Models
-
-All fields carry `description`; both models use `createdUpdatedPlugin` + `isDeletedPlugin`
-and live per the five-type pattern (`CommsMessageDocument`, etc.).
-
-**PushToken** — `userId` (ref User, required, indexed), `token` (string, required, unique),
-`platform` ("ios" | "android" | "web"), `deviceId` (string, optional), `active` (boolean,
-default true), `lastSeenAt` (date).
-
-**CommsMessage** — `channel` ("mail" | "sms" | "push" | "verification"), `provider`
-(string), `to` (string, redacted-at-rest for sms/mail per option), `subject` (string,
-optional), `userId` (ref User, optional), `status` ("sent" | "failed" | "delivered" |
-"bounced"), `providerMessageId` (string, indexed), `error` (string, optional), `metadata`
-(Mixed). Static `logSend()` mirrors `AIRequest.logRequest`.
-
-## APIs
-
-| Method | Path | Permissions | Notes |
-|---|---|---|---|
-| POST | `/comms/pushTokens` | IsAuthenticated | Upsert by `token`; sets `userId`, `platform`, `lastSeenAt` |
-| GET | `/comms/pushTokens` | IsOwner via queryFilter | List own device tokens |
-| DELETE | `/comms/pushTokens/:id` | IsOwner | Deactivate on logout/uninstall |
-| GET | `/comms/messages` | IsAdmin | Paginated delivery log explorer; filters: `channel`, `status`, `userId`, date range |
-
-Push token routes via `modelRouter` with `preCreate` owner injection and
-`OwnerQueryFilter`; explorer via `createOpenApiBuilder`, modeled on
-`addAiRequestsExplorerRoutes`.
-
-## Notifications
-
-None beyond the feature itself.
-
-## UI
-
-None in this IP. example-frontend gains a settings row that registers the Expo push token
-(client helper already exists in `store/utils.ts`) once the Expo adapter lands.
-
-## Phases
-
-1. **Package + contracts:** `@terreno/comms` package scaffold, `types.ts`, console
-   adapters, `CommsMessage` + logging, `commsService`, unit tests.
-2. **CommsApp + routes:** plugin registration, `PushToken` model + routes, admin explorer,
-   OpenAPI, supertest coverage.
-3. **Integration:** example-backend registers `CommsApp` (console adapters), seed docs,
-   `docs/reference/comms.md`, catalog entries, publish wiring in `publish-on-tag.yml`.
-
-## Feature Flags & Migrations
-
-None. New collections only; no existing data touched.
-
-## Activity Log & User Updates
-
-Every send attempt is a `CommsMessage` row (that is the audit surface). No user-facing
-updates.
-
-## Not Included / Future Work
-
-- Adapter IPs: `comms-adapter-expo-push`, `comms-adapter-twilio-sms`,
-  `comms-adapter-twilio-verify`, `comms-adapter-sendgrid`.
-- Notification center, user notification preferences.
-- Queue-backed sending with retries — arrives with `job-queues`; until then sends are
-  inline with one retry.
-
-## Files to Create / Modify
-
-- `comms/` (new workspace package: `package.json`, `tsconfig.json`, `biome.jsonc`, `src/*`
-  as in Architecture)
-- Root `package.json` — workspace entry + scripts (`comms:compile|lint|test`)
-- `example-backend/src/server.ts` — register `CommsApp`
-- `docs/reference/comms.md`, `.cursor/rules/comms/00-comms.mdc` (via rulesync)
-- `.github/workflows/publish-on-tag.yml`, new `comms-ci` workflow
-
-## Task List
-
-See [docs/tasks/comms-abstraction.md](../tasks/comms-abstraction.md).
-
-## Acceptance Criteria
-
-- [ ] A Terreno app with only console adapters can call `sendMail`, `sendSms`,
-      `sendPushToUser`, and `startVerification`/`checkVerification` in development, each
-      producing a logger line and a `CommsMessage` row.
-- [ ] `POST /comms/pushTokens` registers a device token for the authenticated user;
-      re-posting the same token updates rather than duplicates; other users cannot list or
-      delete it.
-- [ ] `GET /comms/messages` is admin-only, paginated, and filterable by channel and status.
-- [ ] Production apps with an unconfigured channel get a 501 `APIError`, not a silent no-op.
-- [ ] `@terreno/comms` core has zero provider SDKs in `dependencies`.
-- [ ] All routes appear in `/openapi.json` and the generated SDK compiles.

package/src/docs/versioned/next/implementationPlans/comms-adapter-expo-push.md

@@ -1,107 +0,0 @@
-# Implementation Plan: Comms adapter — Expo push notifications
-
-**Status:** Draft
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1019
-**Priority:** High
-**Effort:** Small batch
-**Owner:** unassigned
-**Created:** 2026-08-09
-**Program:** [B2B platform](b2b-platform-program.md)
-**Depends on:** [comms-abstraction](comms-abstraction.md)
-**RTK deprecation flag:** None — backend adapter; client token registration already exists
-
-## Goal
-
-Implement `PushProvider` on Expo's push service so `sendPushToUser` delivers real
-notifications to iOS/Android devices. `expo-server-sdk` is already a dependency of
-`@terreno/api` (currently unused — it moves to this adapter's peer deps); the client-side
-token fetch (`getExpoPushTokenAsync`) already exists in `example-frontend/store/utils.ts`.
-
-## Non-Goals
-
-- Direct FCM/APNs integration (future adapter if demand appears).
-- Notification center / inbox UI.
-- Rich notification content (images, actions) beyond title/body/data/badge/sound.
-
-## Decisions
-
-| Question | Decision |
-|----------|----------|
-| SDK | `expo-server-sdk` as optional peer of `@terreno/comms` (subpath `adapters/expoPush`); removed from `@terreno/api` deps |
-| Receipts | Poll receipts after send (Expo's required pattern); surface as `DeliveryEvent`s to `onDeliveryEvent` |
-| Dead tokens | `DeviceNotRegistered` receipt → `SendResult.accepted: false` with permanent-failure marker so core pruning deactivates the `PushToken` |
-| Chunking | Use the SDK's `chunkPushNotifications`; one `SendResult` per token preserved through chunks |
-
-## Architecture
-
-```typescript
-// @terreno/comms/adapters/expoPush
-export class ExpoPushProvider implements PushProvider {
-  readonly id = "expo";
-  constructor(options?: {accessToken?: string; receiptPollDelayMs?: number});
-  sendPush(message: PushMessage): Promise<SendResult[]>;
-}
-```
-
-Send flow: validate tokens with `Expo.isExpoPushToken` → chunk → send → collect tickets →
-schedule one receipt poll (default 15 min, configurable; inline timer until `job-queues`
-lands) → map receipt errors to `DeliveryEvent`s and permanent-failure results.
-
-## Models
-
-None new — uses `PushToken` and `CommsMessage` from the abstraction.
-
-## APIs
-
-None new.
-
-## Notifications
-
-This is the notification plumbing itself.
-
-## UI
-
-example-frontend: register the push token on login via `POST /comms/pushTokens` (guarded by
-`expo-device` physical-device check once the native baseline lands) and a profile-screen
-test-send row in dev builds.
-
-## Phases
-
-Single phase.
-
-## Feature Flags & Migrations
-
-None.
-
-## Activity Log & User Updates
-
-Sends and receipt failures logged to `CommsMessage`.
-
-## Not Included / Future Work
-
-- Queue-backed receipt polling (moves to `job-queues` when available).
-- Web push (Expo tokens cover native only; web is a future adapter).
-
-## Files to Create / Modify
-
-- `comms/src/adapters/expoPush.ts` + tests (mock `Expo` client)
-- `comms/package.json` — optional peer `expo-server-sdk`
-- `api/package.json` — remove unused `expo-server-sdk`
-- `example-frontend/app/(tabs)/profile.tsx`, `store/utils.ts` — token registration wiring
-- `docs/reference/comms.md` — adapter section
-
-## Task List
-
-See [docs/tasks/comms-adapter-expo-push.md](../tasks/comms-adapter-expo-push.md).
-
-## Acceptance Criteria
-
-- [ ] With a mocked Expo client, `sendPush` returns one `SendResult` per token across chunk
-      boundaries.
-- [ ] A `DeviceNotRegistered` receipt deactivates the corresponding `PushToken` via core
-      pruning.
-- [ ] Invalid tokens are rejected before hitting the SDK and logged as failed
-      `CommsMessage` rows.
-- [ ] `@terreno/api` no longer lists `expo-server-sdk`; apps not using the adapter install
-      nothing new.
-- [ ] example-frontend registers its token after login on a physical device build.

package/src/docs/versioned/next/implementationPlans/comms-adapter-sendgrid.md

@@ -1,107 +0,0 @@
-# Implementation Plan: Comms adapter — transactional email (SendGrid)
-
-**Status:** Draft
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1022
-**Priority:** High
-**Effort:** Small batch
-**Owner:** unassigned
-**Created:** 2026-08-09
-**Program:** [B2B platform](b2b-platform-program.md)
-**Depends on:** [comms-abstraction](comms-abstraction.md); inbound-webhooks (Phase 2 only)
-**RTK deprecation flag:** None — backend only
-
-## Goal
-
-Implement `MailProvider` on Twilio SendGrid (decision D2 — first mail adapter, sharing the
-Twilio account story with the SMS and Verify adapters) so `sendMail` delivers real
-transactional email. This unblocks `password-reset-and-email-verification` and
-`invitations-and-seats`.
-
-## Non-Goals
-
-- Other mail providers (Resend/SES/SMTP — items when demand appears).
-- Marketing campaigns, contact lists, SendGrid dynamic template management.
-- Inbound email parsing.
-
-## Decisions
-
-| Question | Decision |
-|----------|----------|
-| SDK | `@sendgrid/mail` as optional peer, subpath `@terreno/comms/adapters/sendgrid` |
-| Auth | `SENDGRID_API_KEY` env or constructor option; fail fast at registration when missing |
-| From address | Constructor `fromEmail`/`fromName` falling back to `CommsApp.defaultFrom`; sender verification is a documented SendGrid prerequisite, not automated |
-| Templates | Terreno-side rendering (`templates.ts` from the abstraction) sent as `text`/`html`; SendGrid dynamic templates supported pass-through via `templateId` + `dynamicTemplateData` but not required |
-| Sandbox | SendGrid `mail_settings.sandbox_mode` toggle for CI/e2e so tests never send |
-| Delivery events | Phase 2: SendGrid Event Webhook (delivered/bounce/dropped/open) with ECDSA signature verification via the inbound-webhooks framework, mapped to `DeliveryEvent`s |
-
-## Architecture
-
-```typescript
-// @terreno/comms/adapters/sendgrid
-export class SendGridMailProvider implements MailProvider {
-  readonly id = "sendgrid";
-  constructor(options?: {
-    apiKey?: string;          // default env SENDGRID_API_KEY
-    fromEmail?: string;
-    fromName?: string;
-    sandboxMode?: boolean;    // default true when NODE_ENV === "test"
-  });
-  sendMail(message: MailMessage): Promise<SendResult>;
-}
-```
-
-Error mapping: SendGrid 4xx (bad address, unverified sender) → `accepted: false` with the
-response body's first error message in `SendResult.error` and full body in
-`CommsMessage.metadata`; 429/5xx retried once by the core facade. The provider never
-throws through `sendMail`.
-
-## Models / APIs / Notifications / UI
-
-None new. Phase 2 adds one webhook route via the inbound-webhooks framework.
-
-## Phases
-
-1. **Send path:** provider, config resolution, sandbox mode, error mapping, mocked-client
-   tests; example-backend env-gated registration; docs (including the sender-verification
-   prerequisite checklist).
-2. **Delivery events** *(gated on inbound-webhooks IP)*: Event Webhook route with ECDSA
-   signature verification; delivered/bounce/dropped/open → `DeliveryEvent` →
-   `CommsMessage.status`.
-
-## Feature Flags & Migrations
-
-None.
-
-## Activity Log & User Updates
-
-All sends logged to `CommsMessage` with provider `sendgrid`.
-
-## Not Included / Future Work
-
-- Suppression-list management, unsubscribe groups.
-- Batch sending beyond the multiple-recipient `to` array.
-
-## Files to Create / Modify
-
-- `comms/src/adapters/sendgrid.ts` + tests
-- `comms/package.json` — optional peer `@sendgrid/mail`
-- `example-backend/src/server.ts` — env-gated registration
-- `docs/reference/comms.md`, `docs/reference/environment-variables.md`
-
-## Task List
-
-See [docs/tasks/comms-adapter-sendgrid.md](../tasks/comms-adapter-sendgrid.md).
-
-## Acceptance Criteria
-
-- [ ] `sendMail` delivers text/html mail with from-address fallback chain (provider option
-      → `CommsApp.defaultFrom`), and passes `templateId`/`dynamicTemplateData` through when
-      given.
-- [ ] Sandbox mode is on by default under test and produces accepted results without real
-      sends.
-- [ ] SendGrid 4xx errors surface as `accepted: false` with the SendGrid error message;
-      nothing throws through the facade.
-- [ ] Missing API key fails fast at `CommsApp` registration with a clear error.
-- [ ] Apps not using the adapter do not install `@sendgrid/mail`.
-- [ ] (Phase 2) Event webhook updates `CommsMessage.status` only for
-      signature-verified payloads.

package/src/docs/versioned/next/implementationPlans/comms-adapter-twilio-sms.md

@@ -1,102 +0,0 @@
-# Implementation Plan: Comms adapter — Twilio SMS
-
-**Status:** Draft
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1020
-**Priority:** Medium
-**Effort:** Small batch
-**Owner:** unassigned
-**Created:** 2026-08-09
-**Program:** [B2B platform](b2b-platform-program.md)
-**Depends on:** [comms-abstraction](comms-abstraction.md); inbound-webhooks (Phase 2 only)
-**RTK deprecation flag:** None — backend only
-
-## Goal
-
-Implement `SmsProvider` on Twilio Programmable Messaging so Terreno apps can send
-transactional SMS (OTP fallback, alerts, invitation nudges) through the `@terreno/comms`
-facade with delivery logging.
-
-## Non-Goals
-
-- OTP verification (that is `comms-adapter-twilio-verify`, on Twilio Verify).
-- Push via Twilio (dropped by decision D5 — Expo push is the push adapter).
-- Bulk/campaign messaging, MMS/RCS.
-- Phone-number provisioning automation.
-
-## Decisions
-
-| Question | Decision |
-|----------|----------|
-| SDK | `twilio` as optional peer, subpath `@terreno/comms/adapters/twilioSms` |
-| Sender config | Prefer `TWILIO_MESSAGING_SERVICE_SID`; fall back to `TWILIO_FROM_NUMBER`; constructor options override env |
-| Number validation | Validate/normalize to E.164 with `libphonenumber-js` (already in catalog) before hitting the API |
-| Delivery status | Phase 2: status callback endpoint via the inbound-webhooks framework mapping Twilio statuses to `DeliveryEvent`s |
-| Secrets | `TWILIO_ACCOUNT_SID` + `TWILIO_AUTH_TOKEN` via env or the existing secret-provider layer |
-
-## Architecture
-
-```typescript
-// @terreno/comms/adapters/twilioSms
-export class TwilioSmsProvider implements SmsProvider {
-  readonly id = "twilio";
-  constructor(options?: {
-    accountSid?: string;      // default env TWILIO_ACCOUNT_SID
-    authToken?: string;       // default env TWILIO_AUTH_TOKEN
-    messagingServiceSid?: string;
-    fromNumber?: string;
-    statusCallbackUrl?: string; // Phase 2
-  });
-  sendSms(message: {to: string; body: string}): Promise<SendResult>;
-}
-```
-
-Errors map Twilio exception codes to `SendResult.error` with the Twilio error code kept in
-`CommsMessage.metadata` for triage. Invalid destination numbers fail fast with a
-`BadRequestError` before any API call.
-
-## Models / APIs / Notifications / UI
-
-None new — Phase 2 adds one webhook route via the inbound-webhooks framework.
-
-## Phases
-
-1. **Send path:** provider, config resolution, E.164 validation, error mapping, tests with
-   mocked Twilio client; example-backend env-gated registration; docs.
-2. **Delivery callbacks** *(gated on inbound-webhooks IP)*: status callback route with
-   Twilio signature verification, statuses → `DeliveryEvent` → `CommsMessage.status`
-   updates.
-
-## Feature Flags & Migrations
-
-None.
-
-## Activity Log & User Updates
-
-All sends logged to `CommsMessage` with provider `twilio`.
-
-## Not Included / Future Work
-
-- Inbound SMS (replies) handling.
-- Alphanumeric sender IDs, international compliance tooling.
-
-## Files to Create / Modify
-
-- `comms/src/adapters/twilioSms.ts` + tests
-- `comms/package.json` — optional peer `twilio`
-- `example-backend/src/server.ts` — env-gated registration
-- `docs/reference/comms.md`, `docs/reference/environment-variables.md`
-
-## Task List
-
-See [docs/tasks/comms-adapter-twilio-sms.md](../tasks/comms-adapter-twilio-sms.md).
-
-## Acceptance Criteria
-
-- [ ] `sendSms` delivers via messaging service or from-number config, preferring the
-      messaging service when both are present.
-- [ ] A non-E.164 destination fails with a 400 `APIError` before any Twilio call.
-- [ ] Twilio API errors produce `accepted: false` results with the Twilio error code in
-      `CommsMessage.metadata`; nothing throws through the facade.
-- [ ] Apps not using the adapter do not install the `twilio` SDK.
-- [ ] (Phase 2) Status callbacks flip `CommsMessage.status` to `delivered`/`failed` with
-      verified Twilio signatures.

package/src/docs/versioned/next/implementationPlans/comms-adapter-twilio-verify.md

@@ -1,93 +0,0 @@
-# Implementation Plan: Comms adapter — Twilio Verify (OTP)
-
-**Status:** Draft
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1021
-**Priority:** Medium
-**Effort:** Small batch
-**Owner:** unassigned
-**Created:** 2026-08-09
-**Program:** [B2B platform](b2b-platform-program.md)
-**Depends on:** [comms-abstraction](comms-abstraction.md)
-**RTK deprecation flag:** None — backend only
-
-## Goal
-
-Implement `VerificationProvider` on Twilio Verify so Terreno apps get managed one-time-code
-flows (SMS and email channels) without storing, expiring, or rate-limiting codes
-themselves. This is the delivery channel the future `mfa-step-up-auth` work builds on, and
-it is immediately usable for phone-number verification.
-
-## Non-Goals
-
-- The MFA enrollment/step-up product itself (`mfa-step-up-auth` item).
-- TOTP (app-authenticator) support — that is code-local (`otpauth`), not a Verify concern.
-- Custom code storage or self-managed rate limiting (Verify owns both).
-
-## Decisions
-
-| Question | Decision |
-|----------|----------|
-| SDK | `twilio` optional peer (shared with the SMS adapter), subpath `@terreno/comms/adapters/twilioVerify` |
-| Service config | `TWILIO_VERIFY_SERVICE_SID` env or constructor option |
-| Channels | `sms` and `email` (Verify's email channel requires a configured Verify email integration; documented, not automated) |
-| Abuse control | Rely on Verify's built-in rate limits; add Terreno-side per-user attempt caps only when `rate-limiting` IP lands |
-| Logging | Start/check attempts logged to `CommsMessage` with channel `verification`, never logging the code |
-
-## Architecture
-
-```typescript
-// @terreno/comms/adapters/twilioVerify
-export class TwilioVerifyProvider implements VerificationProvider {
-  readonly id = "twilio-verify";
-  constructor(options?: {accountSid?: string; authToken?: string; verifyServiceSid?: string});
-  startVerification(options: {to: string; channel: "sms" | "email"}): Promise<SendResult>;
-  checkVerification(options: {to: string; code: string}): Promise<{valid: boolean}>;
-}
-```
-
-`checkVerification` maps Verify's `approved` status to `valid: true`; `pending`, `expired`,
-and max-attempt states return `valid: false` with reason in the result error, letting
-callers throw the appropriate `APIError`.
-
-## Models / APIs / Notifications / UI
-
-None new. Consumer routes (e.g. `POST /auth/verifyPhone`) arrive with the features that
-need them; this IP ships the provider plus example-backend registration only.
-
-## Phases
-
-Single phase.
-
-## Feature Flags & Migrations
-
-None.
-
-## Activity Log & User Updates
-
-Verification attempts logged to `CommsMessage` (no codes, destination redacted to
-last-4).
-
-## Not Included / Future Work
-
-- MFA enrollment, recovery codes, biometric step-up (`mfa-step-up-auth`).
-- WhatsApp/voice channels.
-- Android SMS autofill hash configuration (`react-native-otp-verify`, decision D7).
-
-## Files to Create / Modify
-
-- `comms/src/adapters/twilioVerify.ts` + tests (mocked Twilio client)
-- `example-backend/src/server.ts` — env-gated registration
-- `docs/reference/comms.md`, `docs/reference/environment-variables.md`
-
-## Task List
-
-See [docs/tasks/comms-adapter-twilio-verify.md](../tasks/comms-adapter-twilio-verify.md).
-
-## Acceptance Criteria
-
-- [ ] `startVerification` creates a Verify verification on the configured service for sms
-      and email channels.
-- [ ] `checkVerification` returns `valid: true` only for `approved`; expired and
-      max-attempt states return `valid: false` with a reason.
-- [ ] No OTP code ever appears in logs or `CommsMessage` rows; destinations are redacted.
-- [ ] Missing `TWILIO_VERIFY_SERVICE_SID` fails fast at registration with a clear error.