@terreno/mcp 57.1.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
@@ -32,7 +32,7 @@ org switcher, dark mode).
 
 | Track | Theme | IPs / roadmap items |
 |---|---|---|
-| A | Tenancy & access | `orgs-and-teams`, `rbac-permissions` (Complete), `invitations-and-seats`, `org-management-ui` |
+| A | Tenancy & access | `org-management-ui` (supersedes `orgs-and-teams`), `rbac-permissions` (Complete), `invitations-and-seats` |
 | C | Communications (pluggable) | `comms-abstraction`, one item **per adapter**: `comms-adapter-expo-push` (first push adapter, per D4), `comms-adapter-twilio-sms`, `comms-adapter-twilio-verify`, `comms-adapter-sendgrid` (first mail adapter, per D2); operations: `comms-admin-dashboard`; consumers: `password-reset-and-email-verification`, `notification-center` |
 | B | Billing | `inbound-webhooks`, `billing-stripe` (web-first, per D1), `mobile-iap-revenuecat` (Future) |
 | D | Zero-to-deployed DX | `create-terreno-app`, `mongo-migrations` (deploy items already exist in the OSS launch program) |
@@ -42,7 +42,7 @@ org switcher, dark mode).
 
 ## Sequencing
 
-1. **Foundations first:** `comms-abstraction` and `orgs-and-teams` are independent and both
+1. **Foundations first:** `comms-abstraction` and `org-management-ui` are independent and both
    unblock most of the program. `inbound-webhooks` lands before billing and before comms
    delivery callbacks.
 2. **Close the auth hole early:** `password-reset-and-email-verification` ships as soon as
@@ -94,18 +94,19 @@ 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) |
 | [comms-admin-dashboard](comms-admin-dashboard.md) | Draft | [tasks](../tasks/comms-admin-dashboard.md) |
 | [password-reset-and-email-verification](password-reset-and-email-verification.md) | Draft | [tasks](../tasks/password-reset-and-email-verification.md) |
-| [orgs-and-teams](orgs-and-teams.md) | Draft | [tasks](../tasks/orgs-and-teams.md) |
+| [orgs-and-teams](orgs-and-teams.md) | Superseded by [org-management-ui](org-management-ui.md) | — |
+| [org-management-ui](org-management-ui.md) | Draft — awaiting approval | [tasks](../tasks/org-management-ui.md) |
 | [billing-stripe](billing-stripe.md) | Draft | [tasks](../tasks/billing-stripe.md) |
 | [native-module-baseline](native-module-baseline.md) | Draft | [tasks](../tasks/native-module-baseline.md) |
 | [rbac-permissions](rbac-permissions.md) | Complete (PR #932) | — |
 
-Remaining items (`inbound-webhooks`, `invitations-and-seats`, `org-management-ui`,
+Remaining items (`inbound-webhooks`, `invitations-and-seats`,
 `notification-center`, `framework-audit-log`, `rate-limiting`, `job-queues`, …) get IPs as
 they approach the top of the queue.
 

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:** [orgs-and-teams](orgs-and-teams.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
 
@@ -101,8 +101,8 @@ active/trialing/past_due/canceled/…), `currentPeriodEnd` (date), `cancelAtPeri
 ## UI
 
 Phase 4, kept deliberately thin: a plan-picker screen (`GET /billing/plans` + checkout
-redirect) and a billing settings card (current plan, status, portal link) in
-example-frontend; org-management surfaces integrate later via `org-management-ui`.
+redirect) and a billing settings card (current plan, status, portal link). Admin org
+settings show a billing placeholder until this IP ships (see `org-management-ui`).
 
 ## Phases
 
@@ -110,8 +110,9 @@ example-frontend; org-management surfaces integrate later via `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