@terreno/mcp 57.2.0 → 57.3.0

package/dist/docs/versioned/next/implementationPlans/b2b-platform-program.md

@@ -1,6 +1,6 @@
 # Program: B2B platform
 
-**Status:** Draft — roadmap items drafted; decisions D1–D7 resolved 2026-08-09; first ten IPs open
+**Status:** Approved — decisions D1–D7 resolved 2026-08-09; first ten IPs open
 **Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1095
 **Owner:** unassigned
 **Created:** 2026-08-09
@@ -94,7 +94,7 @@ All decisions resolved by the maintainer on 2026-08-09:
 | IP | Status | Tasks |
 |---|---|---|
 | [comms-abstraction](comms-abstraction.md) | Approved — Phase 1 gap-fill implemented | [tasks](../tasks/comms-abstraction.md) |
-| [comms-adapter-expo-push](comms-adapter-expo-push.md) | Draft | [tasks](../tasks/comms-adapter-expo-push.md) |
+| [comms-adapter-expo-push](comms-adapter-expo-push.md) | In progress | [tasks](../tasks/comms-adapter-expo-push.md) |
 | [comms-adapter-twilio-sms](comms-adapter-twilio-sms.md) | Draft | [tasks](../tasks/comms-adapter-twilio-sms.md) |
 | [comms-adapter-twilio-verify](comms-adapter-twilio-verify.md) | Draft | [tasks](../tasks/comms-adapter-twilio-verify.md) |
 | [comms-adapter-sendgrid](comms-adapter-sendgrid.md) | In progress (Phase 1) | [tasks](../tasks/comms-adapter-sendgrid.md) |

package/dist/docs/versioned/next/implementationPlans/better-auth-strict-oauth-provider.md

@@ -0,0 +1,80 @@
+# Implementation plan: Better Auth sync omits unset `oauthProvider`
+
+**Status:** In progress  
+**Issue:** https://github.com/FlourishHealth/terreno/issues/1218  
+**Branch:** `cursor/better-auth-strict-oauth-provider-3b37`  
+**Created:** 2026-08-30  
+
+## Goal
+
+Email/password Better Auth users sync into a consumer `User` model that uses `strict: "throw"` and does **not** declare `oauthProvider`. The first authenticated `modelRouter` request after sign-up populates `req.user` (not 401).
+
+## Non-Goals
+
+- Adding `oauthProvider` to the `terreno bootstrap app` User schema
+- Inventing or shipping `betterAuthUserPlugin` (it is documented today but does not exist in `@terreno/api`)
+- Changing session-middleware behavior when sync still throws (debug log + `next()` without `req.user`)
+- JWT/Passport paths
+- Data migration or backfill of existing User documents
+
+## Decisions
+
+| Question | Decision |
+|----------|----------|
+| Q1 Which #1218 fix | Option 1: omit `oauthProvider` on create unless a non-empty provider string is passed |
+| Bootstrap User field | Out of scope |
+| OAuth without the field | Still fails `strict: "throw"`; apps that use OAuth must declare `oauthProvider` |
+
+## Architecture
+
+`syncBetterAuthUser` lazily creates the app `User` on the first authenticated request (`createBetterAuthSessionMiddleware`), not at Better Auth sign-up.
+
+**Create payload today** always includes `oauthProvider: oauthProvider || null`. Mongoose `strict: "throw"` rejects the undeclared key. Sync throws, middleware swallows the error, `req.user` is unset, permissions see an unauthenticated request → 401.
+
+**Create payload after:** spread `oauthProvider` only when `oauthProvider` is a non-empty string. Match the existing email-link branch (`if (oauthProvider) { userByEmail.oauthProvider = oauthProvider }`).
+
+Email/password and session middleware call `syncBetterAuthUser(userModel, betterAuthUser)` with no third argument.
+
+## Models
+
+No schema change in `@terreno/api` or bootstrap. Consumer OAuth apps keep declaring `oauthProvider` as they do in `example-backend`.
+
+## APIs
+
+Public function signature unchanged: `syncBetterAuthUser(userModel, betterAuthUser, oauthProvider?)`.
+
+## UI
+
+None.
+
+## Feature Flags & Migrations
+
+None. Existing documents that already stored `oauthProvider: null` are unchanged.
+
+## Not Included / Future Work
+
+- Optional bootstrap field or a real `betterAuthUserPlugin` for OAuth-ready templates
+- Louder logging when lazy sync fails inside session middleware
+
+## Files to Create / Modify
+
+| Path | Change |
+|------|--------|
+| `api/src/betterAuthSetup.ts` | Omit unset `oauthProvider` on create |
+| `api/src/betterAuthSetup.test.ts` | `strict: "throw"` schema **without** the field; OAuth still sets the field when declared |
+| `docs/how-to/configure-better-auth.md` | User model: `betterAuthId` required; `oauthProvider` only for OAuth; replace non-existent plugin example in that section |
+| `docs/explanation/authentication.md` | Lazy User sync; do not write `oauthProvider` for email/password |
+| `.rulesync/rules/api/00-api.md` | Same field rules; then `bun run rules` / `bun run skills:sync` |
+| `changelog/unreleased/better-auth-strict-oauth-provider.md` | `Fixed` |
+
+## Task List
+
+[docs/tasks/better-auth-strict-oauth-provider.md](../tasks/better-auth-strict-oauth-provider.md)
+
+## Acceptance Criteria
+
+- [x] `syncBetterAuthUser` without a provider creates a user on `strict: "throw"` with no `oauthProvider` path
+- [x] `syncBetterAuthUser(..., "google")` still sets `oauthProvider` when the schema declares the field
+- [x] Existing `syncBetterAuthUser` tests stay green
+- [x] How-to and explanation docs state when the field is required
+- [x] Agent rule copy matches after `bun run rules`

package/dist/docs/versioned/next/implementationPlans/billing-stripe.md

@@ -1,13 +1,13 @@
 # Implementation Plan: Stripe billing and subscriptions
 
-**Status:** Draft
+**Status:** Approved
 **Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1025
 **Priority:** High
 **Effort:** Epic
 **Owner:** unassigned
 **Created:** 2026-08-09
 **Program:** [B2B platform](b2b-platform-program.md)
-**Depends on:** [org-management-ui](org-management-ui.md), inbound-webhooks (IP pending — hard dependency for Phase 3)
+**Depends on:** [org-management-ui](org-management-ui.md), [inbound-webhooks](inbound-webhooks.md) (hard dependency for Phase 3)
 **RTK deprecation flag:** None for the backend; the two screens in Phase 4 follow whatever
 data layer example-frontend uses at that time
 
@@ -110,8 +110,9 @@ settings show a billing placeholder until this IP ships (see `org-management-ui`
    validation, unit tests.
 2. **Checkout + portal:** customer creation, session routes, `getEntitlements`,
    `planSegment`, `RequiresPlan`, tests with mocked Stripe SDK.
-3. **Webhook sync** *(gated on inbound-webhooks)*: signature-verified event routes,
-   idempotent handlers, dunning email, `stripe-mock`/fixture tests.
+3. **Webhook sync** *(gated on inbound-webhooks)*: register `POST /billing/webhooks/stripe`
+   on the shared `WebhooksApp` with `stripeSignature`. Do not fork parsers. Idempotent
+   handlers, dunning email, `stripe-mock`/fixture tests.
 4. **UI + example + docs:** plan picker + billing settings in example-frontend, seeds
    with Stripe test-mode instructions, `docs/how-to/add-billing.md`, SDK regen.
 

package/dist/docs/versioned/next/implementationPlans/build-terreno-app-validation.md

@@ -1,6 +1,6 @@
 # Implementation Plan: Dogfooding Run and Launch Blog Post
 
-**Status:** Draft — key decisions recorded (2026-07-29)
+**Status:** Approved — key decisions recorded (2026-07-29)
 **Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1015
 **Priority:** High (this is the program's acceptance test)
 **Effort:** Big batch

package/dist/docs/versioned/next/implementationPlans/can-as-permission-seam.md

@@ -0,0 +1,134 @@
+# `can()` as the permission seam
+
+**Status:** Approved — 2026-08-24  
+**Branch:** `cursor/architecture-ips-a7ec`  
+**Owner:** —  
+**Created:** 2026-08-24  
+**Architecture source:** [rbac-permissions.md](rbac-permissions.md) (Complete — this IP **finishes** `can()` as enforcement, it does not redesign roles/statements)  
+**Task list:** [can-as-permission-seam.md](../tasks/can-as-permission-seam.md)  
+**Depends on:** [unified-mutation-executors.md](unified-mutation-executors.md) so MCP and REST do not keep two permission forks  
+**Related:** shipped `createAccess().can()` and `buildAccessPermissions` / `resolveModelRouterAccess` compiling into `RESTPermissions`
+
+## Goal
+
+When a router has `access` + `accessControl`, transports call `accessControl.can({user, resource, action, doc})` (plus existing scopes/field masks). Stop compiling RBAC into `PermissionMethod[]` and then running `checkPermissions` as the real engine.
+
+Today `resolveModelRouterAccess` in `api/src/rbac/modelRouterAccess.ts` builds legacy `permissions.create/list/...` arrays. `permissionMiddleware` and executors still AND those functions. Apps still pass both `access` and `permissions` (example-backend). The RBAC IP already defined `can()` + `IsPermitted` as the target.
+
+## Non-Goals
+
+- New role/statement/scope/field-view model (already shipped).
+- Deleting `Permissions.IsAuthenticated` / `IsOwner` / `RESTPermissions` for routers that have **no** `access` block.
+- Redis/cross-process RBAC cache (explicitly out of the completed RBAC IP).
+- Admin UI for roles (shipped).
+- Collapsing `api/src/rbac/*` files into one file (fails the deletion test).
+
+## Decisions
+
+| Question | Decision |
+|----------|----------|
+| Interface shape | **A — `can()` is the engine when `access` is set.** `permissionMiddleware` and executors branch: RBAC path calls `can()`; legacy path calls `checkPermissions`. Not B (delete `PermissionMethod` in one cut). |
+| `permissions` field | Remains **required on the type** for routers without `access`. When `access` is set, `permissions` may still be present but **must not** be AND-composed with `can()` (that double-gate is the bug). `resolveModelRouterAccess` stops replacing `permissions` with compiled methods for the request path. |
+| Empty array = 405 | Preserve: empty `permissions.create` disables create. For `access`, missing action / deny from `can()` is 403 unless the method is not in the access map — map CRUD methods to resource actions as today’s `buildAccessPermissions` does. Disabled method stays 405 when the access config omits that action the same way empty arrays work; document the mapping table in reference docs. |
+| Executors | After unified-mutation-executors, one `assertCanWrite(method, …)` used by executors (and thus MCP). Middleware uses the same helper for HTTP load-object-and-check. |
+| `IsPermitted` | Keep as the adapter for **custom** routes that are not modelRouter CRUD. |
+| Compatibility | Routers with only `permissions:` unchanged. Routers with `access:` may drop redundant `permissions` arrays in example-backend in a follow-up task in this IP. |
+
+## Interface shapes considered
+
+**A (chosen).**
+
+```typescript
+assertAllowed({
+  method: RESTMethod,
+  options: Pick<ModelRouterOptions<T>, "access" | "accessControl" | "permissions">,
+  user?: User,
+  doc?: T,
+}): Promise<void> // throws APIError 403/405
+```
+
+Inside: if `options.access && options.accessControl` → `can()`; else `checkPermissions`.
+
+**B (rejected for this slice).** Remove `RESTPermissions` from `ModelRouterOptions`. Forces every consumer to adopt RBAC in one release.
+
+## Architecture
+
+```
+Before:
+  access → buildAccessPermissions → PermissionMethod[] → checkPermissions
+                                                      ↗ executors
+                                                      ↗ permissionMiddleware
+                                                      ↗ MCP handlers (until unified writes)
+
+After:
+  access.can(...)  ← assertAllowed ← HTTP / executors / MCP
+  permissions[]    ← assertAllowed   (legacy routers only)
+```
+
+Do not call `buildAccessPermissions` on the hot path. It may remain as a deprecated helper for one minor if tests rely on it; contract phase deletes hot-path use.
+
+## Docs in this slice
+
+| Page | Change |
+|------|--------|
+| `docs/reference/api.md` | Permission evaluation order: `access`+`accessControl` → `can()`; else `permissions` arrays. Dual AND is gone. |
+| `docs/how-to/create-a-model.md` | Example with `access` only (plus TerrenoApp-injected `accessControl`). |
+| `docs/implementationPlans/rbac-permissions.md` | Pointer: enforcement inversion completed here. |
+
+## Testing
+
+Seam: `assertAllowed` + one modelRouter integration test with `access` that **fails** if compiled `permissions` still AND with a denying extra `Permissions.IsAdmin`.
+
+Cases:
+
+- Legacy router: empty delete array → 405.
+- RBAC deny role → 403 with existing reason shape.
+- RBAC allow + leftover `permissions: {create: [Permissions.IsAdmin]}` on a non-admin who `can()` create → **allow** (proves no double gate).
+- Scope deny still deny.
+- MCP write deny uses the same helper (after unified executors).
+
+## Risks
+
+| Risk | Mitigation |
+|------|------------|
+| 403 vs 405 drift | Table in reference docs; tests per method omitted vs denied. |
+| Query filter / field views currently bundled in `resolveModelRouterAccess` | Keep queryFilter and responseHandler injection; only stop compiling permission **methods**. |
+| Custom routes using `permissionMiddleware` | Same `assertAllowed` inside middleware so custom CRUD-shaped routes benefit. |
+
+## Phases
+
+1. Add `assertAllowed`; unit tests for legacy vs `can()` vs double-gate.
+2. Wire `permissionMiddleware` + executors; delete hot-path `buildAccessPermissions`.
+3. example-backend: `access` without redundant AND-permissions where safe. Docs + changelog.
+
+## Feature Flags & Migrations
+
+No flag. Behavior change for apps that set **both** `access` and denying `permissions` expecting AND: they become `can()`-only. Changelog **Breaking** note: `access` wins; remove duplicate `permissions` if you relied on AND.
+
+## Not Included / Future Work
+
+- Making `permissions` optional in the TypeScript type (major).
+- External permission sources (already in RBAC module).
+
+## Files to Create / Modify
+
+- `api/src/permissions.ts` or `api/src/rbac/assertAllowed.ts` (prefer small new module next to rbac)
+- `api/src/rbac/modelRouterAccess.ts` — stop hot-path compile
+- `api/src/api.ts` — `_buildModelRouter` must not require compiled arrays when `access` is set
+- `api/src/sync/executors.ts`
+- `api/src/rbac/modelRouterAccess.test.ts`, executor and api permission tests
+- `example-backend` modelRouters if they dual-specify
+- Docs listed above
+
+## Acceptance Criteria
+
+- [ ] With `access`+`accessControl`, `can()` is the only allow/deny engine for CRUD (HTTP + executors).
+- [ ] Dual `access` + denying `permissions` does not AND.
+- [ ] Legacy `permissions`-only routers unchanged (405 empty array, AND semantics).
+- [ ] Query filters and field views from `resolveModelRouterAccess` still apply.
+- [ ] Breaking note published for the AND change.
+- [ ] Docs match; api tests pass.
+
+## Task List
+
+[docs/tasks/can-as-permission-seam.md](../tasks/can-as-permission-seam.md)

package/dist/docs/versioned/next/implementationPlans/collection-registry.md

@@ -0,0 +1,133 @@
+# One collection registry
+
+**Status:** Approved — 2026-08-24  
+**Branch:** `cursor/architecture-ips-a7ec`  
+**Owner:** —  
+**Created:** 2026-08-24  
+**Architecture source:** [modular-api-design.md](../explanation/modular-api-design.md), [model-router-mcp.md](model-router-mcp.md), [admin-improvements.md](admin-improvements.md)  
+**Task list:** [collection-registry.md](../tasks/collection-registry.md)  
+**Depends on:** [unified-mutation-executors.md](unified-mutation-executors.md) (soft — writes already one pipeline; registry does not need to wait on MCP adapters, but avoid teaching two write paths)  
+**Unlocks:** simpler RBAC option injection; [describe-model-schema.md](describe-model-schema.md) can hang metadata on the descriptor
+
+## Goal
+
+Register a modelRouter collection once. MCP, realtime, and Sync stop each owning a process-global array plus `update*RegistryOptions` after TerrenoApp injects `accessControl`.
+
+`modelRouter` today (`api/src/api.ts`): `registerMCPModel` / `registerRealtime` / `registerSync` at call time, then `updateMCPRegistryOptions` / `updateRealtimeRegistryOptions` / `updateSyncRegistryOptions` in `_buildModelRouter` when options are enriched. RBAC and MCP work keep touching all three.
+
+## Non-Goals
+
+- A fourth parallel registry.
+- Redesigning MCP tool JSON, Socket.IO payloads, or the Sync protocol.
+- Merging admin’s `AdminApp` model list into this registry in v1 (admin still has its own config; a later task may read the descriptor).
+- Replacing `ModelRouterOptions` with a new public options type in one PR (options bag can stay; the **runtime catalog** is what unifies).
+- Splitting TerrenoApp into Options/Middleware/Hooks files ([ModularAPI.md](ModularAPI.md) file-split is explicitly not this IP).
+
+## Decisions
+
+| Question | Decision |
+|----------|----------|
+| Interface shape | **A — `CollectionRegistry` keyed by route path**, holding `{path, model, options, surfaces}`. Surfaces keep **read helpers** (`getMCPRegistry()`, `findRealtimeByCollectionName()`, …) as views. Not B (event bus / subscribe API) — one extra indirection, same data. |
+| Identity | Primary key: `routePath` (e.g. `/todos`). MCP’s `modelName` index is a secondary lookup that must not diverge. |
+| Option patch | `replaceCollectionOptions(routePath, options)` updates the single record. Surface `update*RegistryOptions` become one-line wrappers or are deleted in the contract phase. |
+| Custom MCP tools | Stay on a **separate** `mcpCustomTools` list. They are not collections. |
+| Sync-only validation | `registerSync` schema checks (`deleted`, `_syncSeq`, scope fields) and index tracking stay in `api/src/sync/registry.ts` **functions** called from `CollectionRegistry.register` when `options.sync` is set. Do not lose those guards. |
+| Compatibility | Public exports `registerMCPModel`, `registerRealtime`, `registerSync`, `clear*Registry` remain until the contract phase, implemented as wrappers. Tests migrate to `clearCollectionRegistry()`; wrappers keep calling it. |
+| Tests | One registry clear in test setup; existing MCP/realtime/sync tests keep working through wrappers in Phase 1. |
+
+## Interface shapes considered
+
+**A (chosen).**
+
+```typescript
+interface CollectionRecord<T = unknown> {
+  routePath: string;
+  model: Model<T>;
+  options: ModelRouterOptions<T>;
+  surfaces: {mcp: boolean; realtime: boolean; sync: boolean};
+}
+
+registerCollection({routePath, model, options}): void
+replaceCollectionOptions(routePath, options): void
+getCollection(routePath): CollectionRecord | undefined
+listCollections(): CollectionRecord[]
+```
+
+**B (rejected).** Surfaces subscribe `onCollection(record)`. Requires teardown, ordering, and still stores the same records.
+
+## Architecture
+
+```
+Before:
+  modelRouter → registerMCP + registerRealtime + registerSync
+             → later updateMCP* + updateRealtime* + updateSync*
+
+After:
+  modelRouter → CollectionRegistry.register(descriptor)
+  TerrenoApp.build → CollectionRegistry.replaceOptions(path, enriched)
+  MCP / realtime / sync read views of the same records
+```
+
+`api/src/mcp/registry.ts` (~70 lines) and `api/src/realtime/registry.ts` (~78 lines) are nearly the same array + update-by-key. `api/src/sync/registry.ts` adds contract validation and index promises — keep that logic, not the duplicated options pointer.
+
+## Docs in this slice
+
+| Page | Change |
+|------|--------|
+| `docs/explanation/modular-api-design.md` | Collection catalog is the runtime seam for surfaces. |
+| `docs/reference/api.md` | `modelRouter` registers one collection; MCP/realtime/sync flags attach surfaces. |
+| MCP / realtime / sync reference sections | Registration is not a separate app-facing API. |
+
+## Testing
+
+Seam: `registerCollection` + `replaceCollectionOptions`. Tests:
+
+- Register with `mcp` + `sync`; `getMCPRegistry()` and sync lookup see the same `options` object identity after replace.
+- `replaceCollectionOptions` on unknown path is a no-op (current update* behavior).
+- Sync still throws on missing `deleted` / `_syncSeq` at register time.
+- Existing realtime/MCP/sync integration tests pass without behavior change.
+
+## Risks
+
+| Risk | Mitigation |
+|------|------------|
+| Startup order / TerrenoApp.build | Keep register-then-replace; do not require all modelRouters to be three-arg form beyond today’s warnings. |
+| Test isolation | `clearCollectionRegistry()` clears all surfaces; wrappers’ `clearMCPRegistry` etc. call it **or** clear only that view — **Decision: clear all** so tests cannot leave a stale MCP entry after a sync-only clear. Update tests that assumed independent clears. |
+| Export churn | Wrappers stay through one minor release; changelog lists wrappers as deprecated internals if they were public. |
+
+## Phases
+
+1. Add `CollectionRegistry`; `modelRouter` writes it **and** still calls existing register functions (dual-write). Tests prove options identity after replace on the new registry.
+2. Point MCP/realtime/sync lookups at the registry; delete duplicate arrays. Keep wrapper function names.
+3. Delete dual-write; `update*RegistryOptions` become wrappers. Docs + changelog.
+
+## Feature Flags & Migrations
+
+No runtime flag. Dual-write in Phase 1 is the migration.
+
+## Not Included / Future Work
+
+- Admin `models[]` reading `CollectionRegistry`.
+- Per-app registry instance (today is process-global, matching current registries). A TerrenoApp-scoped map is a later seam if two apps share a process.
+
+## Files to Create / Modify
+
+- `api/src/collectionRegistry.ts` (new)
+- `api/src/api.ts` — register/replace
+- `api/src/mcp/registry.ts`, `api/src/realtime/registry.ts`, `api/src/sync/registry.ts` — views + sync validation
+- Tests that `clearMCPRegistry` / `clearRealtimeRegistry` / `clearSyncRegistry`
+- `api/src/index.ts` exports if any new public names
+- Docs listed above
+
+## Acceptance Criteria
+
+- [ ] One in-memory catalog holds collection options for MCP, realtime, and sync.
+- [ ] TerrenoApp option enrichment updates that catalog once per path.
+- [ ] Sync schema/index guards still fail fast at startup.
+- [ ] Independent `clearMCPRegistry()` in a test cannot leave realtime entries pointing at old options (documented clear-all behavior, tests updated).
+- [ ] No behavior change to MCP tools, socket events, or sync protocol.
+- [ ] Docs describe the catalog; `bun test` for api mcp/realtime/sync registries passes.
+
+## Task List
+
+[docs/tasks/collection-registry.md](../tasks/collection-registry.md)

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

@@ -1,6 +1,6 @@
 # Implementation Plan: Pluggable communications layer (@terreno/comms)
 
-**Status:** Approved — Phase 1 gap-fill implemented
+**Status:** Complete — `@terreno/comms` shipped; adapters track as their own IPs
 **Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1018
 **Priority:** High
 **Effort:** Big batch
@@ -58,7 +58,7 @@ consumer apps install only the SDKs they use.
 | Provider throws | Facade never rethrows from `sendMail` / `sendSms` / `sendPushToUser` / `startVerification` / `checkVerification`. A throwing provider becomes `errorClass: "transient"`, `errorCode: "provider-throw"`, then follows the same retry rules |
 | Push retry | Retry **only tokens** whose first `SendResult` is `errorClass: "transient"` via a second `sendPush`; merge. Do not re-send accepted tokens |
 | Push prune | Deactivate when `errorClass === "permanent"` **or** `isPermanentFailure === true` (shipped alias; adapters may set both) |
-| Delivery / opt-out intake | `CommsService.recordDeliveryEvent` / `recordOptOut` update the matching log row (by `providerMessageId`) and invoke hooks. Missing rows: `logger.warn`, still fire the hook |
+| Delivery / opt-out intake | `CommsService.recordDeliveryEvent` / `recordOptOut` update the matching log row (by `providerMessageId`) and invoke hooks. Missing rows: `logger.warn`, still fire the hook. Save failures: `logger.warn` then rethrow |
 | Payload expiry | `payloadExpiresAt` on the row. Mongo TTL indexes must **not** be used (they would delete the log). `CommsMessage.clearExpiredPayloads()` unsets `payload` only; `logSend` / `appendAttempt` call it best-effort (limit 50) |
 | `checkVerification` | Log a verification row; no inline retry; never persist the code |
 

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

@@ -1,6 +1,6 @@
 # Implementation Plan: Comms adapter — Expo push notifications
 
-**Status:** Draft
+**Status:** In progress
 **Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1019
 **Priority:** High
 **Effort:** Small batch
@@ -96,12 +96,12 @@ 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
+- [x] With a mocked Expo client, `sendPush` returns one `SendResult` per token across chunk
       boundaries.
-- [ ] A `DeviceNotRegistered` receipt deactivates the corresponding `PushToken` via core
+- [x] A `DeviceNotRegistered` receipt deactivates the corresponding `PushToken` via core
       pruning.
-- [ ] Invalid tokens are rejected before hitting the SDK and logged as failed
+- [x] 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
+- [x] `@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.
+- [x] example-frontend registers its token after login on a physical device build.

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

@@ -102,9 +102,10 @@ None new. Phase 2 adds one webhook route via the inbound-webhooks framework.
    `x-message-id` capture + Email Activity deep link, mocked-client tests;
    example-backend env-gated registration; docs (including the sender-verification
    prerequisite checklist).
-2. **Delivery events + opt-outs** *(gated on inbound-webhooks IP)*: Event Webhook route
-   with ECDSA signature verification; event mapping per the table →
-   `DeliveryEvent`/`OptOutEvent` → `CommsMessage.status` + consumer hooks.
+2. **Delivery events + opt-outs** *(owned and shipped by
+   [inbound-webhooks](inbound-webhooks.md) Task 3.3)*: Event Webhook route with ECDSA
+   signature verification; event mapping per the table → `DeliveryEvent`/`OptOutEvent` →
+   `CommsMessage.status` + consumer hooks. Do not Pick those tasks on this adapter IP.
 
 ## Feature Flags & Migrations
 

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

@@ -1,6 +1,6 @@
 # Implementation Plan: Comms adapter — Twilio SMS
 
-**Status:** Draft
+**Status:** Approved
 **Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1020
 **Priority:** Medium
 **Effort:** Small batch
@@ -56,7 +56,8 @@ export class TwilioSmsProvider implements SmsProvider {
 
 Errors map Twilio exception codes to `SendResult.error`/`errorCode`/`errorClass`, with
 the full Twilio error payload kept in `CommsMessage.metadata` for triage. Invalid
-destination numbers fail fast with a `BadRequestError` before any API call.
+destination numbers return a permanent `SendResult` (`errorCode: twilio-invalid-destination`)
+before any API call so the facade does not retry.
 
 ### Error classification
 
@@ -102,10 +103,11 @@ None new — Phase 2 adds one webhook route via the inbound-webhooks framework.
 1. **Send path:** provider, config resolution, E.164 validation, error-code
    classification map, `withApiErrorHandling` wrapping, console deep-link metadata, tests
    with mocked Twilio client; example-backend env-gated registration; docs.
-2. **Delivery callbacks + opt-outs** *(gated on inbound-webhooks IP)*: status callback
-   route with Twilio signature verification, statuses → `DeliveryEvent` →
-   `CommsMessage.status` updates (with `errorCode`), STOP/START keyword handling →
-   `OptOutEvent` → `onOptOut`.
+2. **Delivery callbacks + opt-outs** *(owned and shipped by
+   [inbound-webhooks](inbound-webhooks.md) Task 3.2)*: status callback route with Twilio
+   signature verification, statuses → `DeliveryEvent` → `CommsMessage.status` updates
+   (with `errorCode`), STOP/START keyword handling → `OptOutEvent` → `onOptOut`. Do not
+   Pick those tasks on this adapter IP.
 
 ## Feature Flags & Migrations
 

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

@@ -1,6 +1,6 @@
 # Implementation Plan: Comms adapter — Twilio Verify (OTP)
 
-**Status:** Draft
+**Status:** Complete
 **Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1021
 **Priority:** Medium
 **Effort:** Small batch
@@ -88,12 +88,12 @@ See [docs/tasks/comms-adapter-twilio-verify.md](../tasks/comms-adapter-twilio-ve
 
 ## Acceptance Criteria
 
-- [ ] `startVerification` creates a Verify verification on the configured service for sms
+- [x] `startVerification` creates a Verify verification on the configured service for sms
       and email channels.
-- [ ] `checkVerification` returns `valid: true` only for `approved`; expired and
+- [x] `checkVerification` returns `valid: true` only for `approved`; expired and
       max-attempt states return `valid: false` with a reason.
-- [ ] Failed starts/checks record `errorCode`/`errorClass` per the classification row and
+- [x] Failed starts/checks record `errorCode`/`errorClass` per the classification row and
       fire the consumer `onError` hook; verification rows are marked non-retryable for
       the admin dashboard.
-- [ ] 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.
+- [x] No OTP code ever appears in logs or `CommsMessage` rows; destinations are redacted.
+- [x] Missing `TWILIO_VERIFY_SERVICE_SID` fails fast at registration with a clear error.

package/dist/docs/versioned/next/implementationPlans/comms-admin-dashboard.md

@@ -1,6 +1,6 @@
 # Implementation Plan: Comms admin dashboard (errors, retries, log digging)
 
-**Status:** Draft
+**Status:** Approved
 **Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1091
 **Priority:** High
 **Effort:** Medium batch

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

@@ -1,6 +1,6 @@
 # Implementation Plan: Deploy to Vercel + `deploy-vercel` Skill
 
-**Status:** Draft — open Vercel spike TODOs; other decisions recorded (2026-07-29)
+**Status:** Approved — open Vercel spike TODOs; other decisions recorded (2026-07-29)
 **Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1012
 **Priority:** High
 **Effort:** Big batch
@@ -38,7 +38,8 @@ Give Terreno the fastest possible "my app is on the internet" path, and a skill
 
 Complete these before Phase 1 of the how-to guide ships:
 
-- [ ] **V1-todo:** Can `@terreno/api` run on Vercel with Socket.io sessions and MongoDB change streams? Document runtime limits, cold starts, and whether session affinity is available.
+- [ ] **V1-todo:** Can `@terreno/api` run on Vercel with Socket.io sessions and MongoDB change streams? Use [Vercel Functions WebSockets (Public Beta)](https://vercel.com/docs/functions/websockets) as the source of truth. Document runtime limits, Fluid compute, cold starts, max-duration disconnects, and that a connection is pinned to one function instance (not session affinity across reconnects).
+- [ ] **V1-todo:** Write operator docs for websocket usage on Vercel Functions (see **Vercel Functions WebSockets** below). Link the beta page; do not copy it. Re-verify every config key and limitation against that page before the how-to ships.
 - [ ] **V1-todo:** Can `@terreno/ai` SSE streaming work through `expo-server/adapter/vercel` without unacceptable buffering?
 - [ ] **V1-todo:** Where do user file uploads land on an all-in-one Vercel deploy (Blob, external GCS, or other)?
 - [ ] **V1-todo:** Compare all-in-one Vercel vs split (Vercel web + long-running backend) on cost, ops complexity, and preview-deployment ergonomics.
@@ -121,14 +122,51 @@ New skill at `.rulesync/skills/deploy-vercel/SKILL.md`:
 
 The verification step must include the websocket check. A Terreno web app can look completely fine while realtime and live feature flags are silently broken.
 
+### Vercel Functions WebSockets (Public Beta) — required how-to
+
+Vercel now documents WebSockets on Vercel Functions as **Public Beta**: [WebSockets](https://vercel.com/docs/functions/websockets). Phase 0 and the how-to must treat that page as the vendor contract. The Terreno page is operator docs for `@terreno/api` (`RealtimeApp` / Socket.io) and `@terreno/syncdb` on that runtime — not a reprint of Vercel’s examples.
+
+**Ship** `docs/how-to/vercel-function-websockets.md`. Link it from `docs/how-to/deploy-web-to-vercel.md` and from `docs/how-to/websocket-integration.md`. Mark the feature **beta**; tell operators to re-read the Vercel page before production. Do **not** present all-in-one Vercel hosting as the recommended Terreno topology until the V1 TODOs close.
+
+The published page must cover the following (cite the Vercel URL; keep examples Terreno-shaped).
+
+#### What Vercel guarantees (as of the beta page)
+
+| Fact | Terreno implication |
+|------|---------------------|
+| A WebSocket starts as HTTP `GET` with `Upgrade`. Routing Middleware, rewrites, Firewall, and rate limits apply **before** the upgrade. | Document Firewall rules and rate limits on the Socket.io path. Better Auth / JWT handshake auth still runs on the upgrade, same as today. |
+| After upgrade, messages stay on the **same function instance** for the life of that connection. Fluid compute can multiplex many connections on one instance. | In-memory `socket.join` rooms work for one connection’s instance only. Cross-instance fan-out still needs the Redis adapter (`RealtimeApp` `adapter: "redis"` + `VALKEY_URL` / `REDIS_URL`). |
+| New connections are **not** guaranteed to hit the same instance. After a deploy, **new** connections may land on the new deployment while **existing** connections stay on the old one until they close. | Presence, rooms, counters, and pub/sub must live in Redis (or equivalent), not process memory. Change-stream watchers are per instance — spike must record cost and fan-out via Redis. |
+| The connection closes when the function hits **max duration**. Clients must reconnect, resubscribe, and reload state. | Document exponential backoff. `@terreno/rtk` `useSocketConnection` already reconnects; `@terreno/syncdb` must resubscribe after reconnect. Name the debug flag (`WEBSOCKETS_DEBUG` at time of writing). |
+| Socket.IO is supported if the **client uses the WebSocket transport only** (`transports: ['websocket']`). Long-polling is not the Vercel path. | Terreno already documents `transports: ["websocket"]` in `docs/how-to/websocket-integration.md`. The Vercel page must restate that long-polling is forbidden on Functions. |
+| Express (and Hono, etc.) can serve sockets by attaching `ws` / Socket.IO to a Node HTTP server and **`export default server`**. | Spike must map this to `TerrenoApp.build()` (or equivalent) vs `start()`. Today the process listens; a Function entry exports the HTTP server. Record the exact adapter file (`api/server.ts` or Expo `expo-server/adapter/vercel` is a **different** path — do not conflate web SSR with the API process). |
+| Fluid compute is required. It is the default for new Vercel projects created on or after 2025-04-23. | Document how to confirm Fluid is on. Without it, do not host Terreno sockets on Functions. |
+| Usage is billed as Function time while the socket is open, plus Fast Data Transfer / Fast Origin Transfer. | Include a cost warning in the all-in-one vs split comparison (V1 cost TODO). Long-lived sync sockets are not “free HTTP”. |
+
+#### Required operator sections
+
+1. **When to use this** — hosting `@terreno/api` (or a dedicated socket process) on Vercel Functions. When **not** to: static Expo `single` output on Vercel talking to a long-running backend (interim topology); native EAS; treating the Vercel **AI SDK** as this feature.
+2. **Prerequisites** — Fluid compute; Function max duration set high enough for the product; Redis if more than one instance or rolling deploys; MongoDB Atlas replica set still required for change streams (unchanged).
+3. **Socket.IO on a Function** — export an HTTP server with Socket.IO attached; client `path` and `transports: ['websocket']`; Terreno `RealtimeApp` + `SyncApp` still registered. Link Vercel’s Socket.IO snippet as the vendor shape, then show the Terreno registration, not a second copy of `ws` echo servers.
+4. **Reconnects** — max-duration close; backoff; resubscribe; “looks fine while sync/flags are dead”.
+5. **State** — no in-memory rooms across instances; Redis; deploy split-brain (old + new deployments both alive).
+6. **Limits and pricing** — pointer to Vercel’s limits/pricing on that page; Function duration while connected.
+7. **Verify** — DevTools Network → WS; `WEBSOCKETS_DEBUG`; confirm the client did **not** fall back to polling.
+
+#### Explicitly out of scope for this page
+
+- Next.js `experimental_upgradeWebSocket` from `@vercel/functions` (not Terreno’s server).
+- Bun `Bun.serve()` / Python FastAPI examples (link the Vercel page; do not re-home them).
+- Replacing MongoDB change streams with Vercel Queues or Vercel KV pub/sub as the Terreno protocol.
+
 ## Models / APIs / Notifications / UI
 
 None.
 
 ## Phases
 
-0. **Spike** — close all **Open TODOs** above; record decision on V1/V2/V3 in this file.
-1. **How-to guide** — `single` output, clone → public URL (topology per V1 outcome).
+0. **Spike** — close all **Open TODOs** above; record decision on V1/V2/V3 in this file; write `docs/how-to/vercel-function-websockets.md` from the beta contract (may ship before V1 is decided, as constraints — not as a topology recommendation).
+1. **How-to guide** — `single` output, clone → public URL (topology per V1 outcome); link the websocket Functions page.
 2. **Preview deployments and origins** — CORS, `trustedOrigins`, OAuth redirects.
 3. **Advanced: server output** — only if V2 is approved.
 4. **Skill** — author and generate mirrors.
@@ -148,6 +186,7 @@ None.
 **Create**
 
 - `docs/how-to/deploy-to-vercel.md` (blocked on Phase 0 spike)
+- `docs/how-to/vercel-function-websockets.md` (Vercel Functions WebSockets beta; may ship during Phase 0)
 - `.rulesync/skills/deploy-vercel/SKILL.md`
 
 **Modify (after V3 decision)**
@@ -155,6 +194,11 @@ None.
 - `example-frontend/vercel.json` (candidate)
 - `example-backend/vercel.json` (candidate — only if all-in-one path wins)
 
+**Modify (with Task 0.2)**
+
+- `docs/how-to/README.md`
+- `docs/how-to/websocket-integration.md`
+
 ## Task List
 
 See [`docs/tasks/deploy-to-vercel.md`](../tasks/deploy-to-vercel.md).
@@ -163,6 +207,7 @@ See [`docs/tasks/deploy-to-vercel.md`](../tasks/deploy-to-vercel.md).
 
 - [ ] All **Open TODOs** are closed with a written decision on V1, V2, and V3.
 - [ ] `docs/how-to/deploy-to-vercel.md` matches the decided topology (not the interim split doc if all-in-one wins, and vice versa).
+- [ ] `docs/how-to/vercel-function-websockets.md` exists, cites [Vercel Functions WebSockets](https://vercel.com/docs/functions/websockets), covers Fluid compute, websocket-only Socket.IO, instance pinning, max-duration reconnects, Redis for cross-instance state, Function billing while connected, and Terreno `RealtimeApp` / syncdb — without recommending all-in-one until V1 is decided.
 - [ ] Preview-deployment CORS and `trustedOrigins` guidance is present.
 - [ ] `deploy-vercel` skill includes websocket verification in its checklist.
 - [ ] Vercel AI SDK vs Vercel hosting disambiguation appears in both `@terreno/ai` and deployment docs.