@terreno/mcp 0.30.0 → 0.31.0

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

@@ -0,0 +1,240 @@
+# 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/dist/docs/versioned/next/implementationPlans/comms-adapter-expo-push.md

@@ -0,0 +1,107 @@
+# 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/dist/docs/versioned/next/implementationPlans/comms-adapter-sendgrid.md

@@ -0,0 +1,107 @@
+# 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/dist/docs/versioned/next/implementationPlans/comms-adapter-twilio-sms.md

@@ -0,0 +1,102 @@
+# 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/dist/docs/versioned/next/implementationPlans/comms-adapter-twilio-verify.md

@@ -0,0 +1,93 @@
+# 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.

package/dist/docs/versioned/next/implementationPlans/deploy-to-gcp.md

@@ -1,6 +1,7 @@
 # Implementation Plan: Deploy to GCP (Generalized) + `deploy-gcp` Skill
 
 **Status:** Approved — decisions recorded (2026-07-29)
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1005
 **Priority:** High
 **Effort:** Big batch
 **Owner:** unassigned

package/dist/docs/versioned/next/implementationPlans/deploy-to-vercel.md

@@ -1,6 +1,7 @@
 # Implementation Plan: Deploy to Vercel + `deploy-vercel` Skill
 
 **Status:** Draft — open Vercel spike TODOs; other decisions recorded (2026-07-29)
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1012
 **Priority:** High
 **Effort:** Big batch
 **Owner:** unassigned

package/dist/docs/versioned/next/implementationPlans/deployment-foundation.md

@@ -1,6 +1,7 @@
 # Implementation Plan: Deployment Foundation
 
 **Status:** Draft — blocking questions open
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1011
 **Priority:** High
 **Effort:** Big batch
 **Owner:** unassigned

package/dist/docs/versioned/next/implementationPlans/docs-reference-coverage.md

@@ -1,6 +1,7 @@
 # Implementation Plan: Reference Documentation Coverage
 
 **Status:** Draft — blocked on PR #869
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1009
 **Priority:** High
 **Effort:** Big batch
 **Owner:** unassigned