@terreno/mcp 57.2.0 → 57.3.0

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

@@ -0,0 +1,41 @@
+# Task List: Better Auth sync omits unset `oauthProvider`
+
+**Feature profile:** true  
+**IP:** [better-auth-strict-oauth-provider.md](../implementationPlans/better-auth-strict-oauth-provider.md)  
+**Issue:** https://github.com/FlourishHealth/terreno/issues/1218
+
+## Durable contract
+
+- **Destination:** email/password Better Auth sync creates the app `User` on a `strict: "throw"` schema that has no `oauthProvider` field, so the first authenticated `modelRouter` request gets `req.user` instead of 401.
+- **Scope:** omit `oauthProvider` on `syncBetterAuthUser` create unless a non-empty provider string is passed; regression tests; docs and agent rules; changelog fragment.
+- **Non-goals:** bootstrap User schema; inventing `betterAuthUserPlugin`; session-middleware 401-on-sync-failure behavior; JWT.
+- **Decisions:** Q1 = option 1 (omit unset field). OAuth apps must still declare `oauthProvider`. Do not add the field to bootstrap.
+- **Tracer:** `syncBetterAuthUser` create path in `api/src/betterAuthSetup.ts`.
+- **Verification seam:** focused `bun test api/src/betterAuthSetup.test.ts` (red without the payload change), then `bun run api:test` and `bun run lint`.
+
+## Instructions for the implementing agent
+
+- TDD: add the `strict: "throw"` regression first and confirm it fails, then change the create payload.
+- Do not set `oauthProvider: null`. Omit the key.
+- When updating `docs/how-to/configure-better-auth.md` § User Model, replace the `betterAuthUserPlugin` example (that export does not exist) with explicit `betterAuthId` plus optional `oauthProvider`.
+- Use `backend-test-env` for any `process.env` mutations. Follow existing `betterAuthSetup.test.ts` helpers (separate MongoMemoryServer connection).
+- Supporting skills: `update-docs`, `backend-test-env`, `mongoose-schema-safety`, `terreno-backend-api`.
+
+### Phase 1: Fix lazy User create
+
+- [x] **Task 1.1**: Omit unset `oauthProvider` on Better Auth User create
+  - Delivers: email/password sign-up then first authenticated API call works on a bootstrap-like User schema (`strict: "throw"`, `betterAuthId`, no `oauthProvider`).
+  - Files: `api/src/betterAuthSetup.ts`, `api/src/betterAuthSetup.test.ts`, `docs/how-to/configure-better-auth.md`, `docs/explanation/authentication.md`, `.rulesync/rules/api/00-api.md` (regenerate agent copies with `bun run rules` and `bun run skills:sync`), `changelog/unreleased/better-auth-strict-oauth-provider.md`
+  - Blocked by: none
+  - Docs: how-to User model fields; explanation lazy sync; agent rule field list. Do not hand-edit generated TypeDoc.
+  - Skills: `update-docs`, `backend-test-env`, `mongoose-schema-safety`, `terreno-backend-api`
+  - Acceptance:
+    - New test: schema `{strict: "throw"}` without `oauthProvider`; `syncBetterAuthUser(model, baUser)` resolves; saved doc has `betterAuthId` and no `oauthProvider` path.
+    - New test: schema that declares `oauthProvider`; third argument `"google"` persists `"google"`.
+    - That first test fails on current `oauthProvider: oauthProvider || null` (StrictModeError).
+    - `bun test api/src/betterAuthSetup.test.ts` and `bun run api:test` pass after the fix.
+    - Docs state `betterAuthId` is required for sync; `oauthProvider` is required only when using OAuth.
+
+## Plan vs Actual
+
+- Task 1.1: `syncBetterAuthUser` create spreads `oauthProvider` only when truthy. Strict-throw schema without the field is green; create with `"google"` still persists. Docs dropped the non-existent `betterAuthUserPlugin` example.

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

@@ -0,0 +1,32 @@
+# Tasks: `can()` as the permission seam
+
+IP: [can-as-permission-seam.md](../implementationPlans/can-as-permission-seam.md)
+
+## Phase 1 — `assertAllowed`
+
+- [ ] **Task 1.1**: Helper + unit tests
+  - Delivers: `assertAllowed` implements legacy `checkPermissions` and `accessControl.can()`; double-gate test (access allow + permissions deny → allow)
+  - Files: `api/src/rbac/assertAllowed.ts`, `api/src/rbac/assertAllowed.test.ts`
+  - Blocked by: none (can land before MCP adapters; executors wiring waits on unified writes if MCP still duplicates checks)
+  - Acceptance: bun tests cover 405 empty array, 403 can() deny, legacy AND, access-wins-over-permissions
+
+## Phase 2 — Hot path
+
+- [ ] **Task 2.1**: Middleware + executors
+  - Delivers: `permissionMiddleware` and `executeCreate/Update/Delete` call `assertAllowed`; `buildAccessPermissions` not used on requests
+  - Files: `api/src/permissions.ts`, `api/src/sync/executors.ts`, `api/src/api.ts`, `api/src/rbac/modelRouterAccess.ts`, tests
+  - Blocked by: 1.1; unified-mutation-executors Phase 2 so MCP is included automatically
+  - Acceptance: modelRouter + executor + MCP permission tests pass; grep shows no request-path `buildAccessPermissions`
+
+## Phase 3 — Consumers and docs
+
+- [ ] **Task 3.1**: example-backend dual config
+  - Delivers: routers with `access` drop redundant AND `permissions` where RBAC is the intent
+  - Files: `example-backend/src/**` model routers
+  - Blocked by: 2.1
+  - Acceptance: example-backend tests pass
+- [ ] **Task 3.2**: Docs + breaking changelog
+  - Files: `docs/reference/api.md`, `docs/how-to/create-a-model.md`, `docs/implementationPlans/rbac-permissions.md` pointer, changelog
+  - Blocked by: 2.1
+  - Skills: `update-docs`
+  - Acceptance: evaluation order is documented; 403 vs 405 table exists

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

@@ -0,0 +1,42 @@
+# Tasks: One collection registry
+
+IP: [collection-registry.md](../implementationPlans/collection-registry.md)
+
+## Phase 1 — Dual-write catalog
+
+- [ ] **Task 1.1**: `CollectionRegistry` module
+  - Delivers: `registerCollection`, `replaceCollectionOptions`, `getCollection`, `listCollections`, `clearCollectionRegistry` with unit tests (unknown path no-op, options replace)
+  - Files: `api/src/collectionRegistry.ts`, `api/src/collectionRegistry.test.ts`
+  - Blocked by: none
+  - Acceptance: bun tests for the module pass without wiring modelRouter
+- [ ] **Task 1.2**: Dual-write from `modelRouter`
+  - Delivers: `modelRouter` / `_buildModelRouter` write the catalog in addition to existing `register*` / `update*`
+  - Files: `api/src/api.ts`
+  - Blocked by: 1.1
+  - Acceptance: existing api tests still pass
+
+## Phase 2 — Surfaces read the catalog
+
+- [ ] **Task 2.1**: MCP and realtime views
+  - Delivers: `getMCPRegistry` / realtime finders read `CollectionRegistry`; arrays in those files removed
+  - Files: `api/src/mcp/registry.ts`, `api/src/realtime/registry.ts`, related tests
+  - Blocked by: 1.2
+  - Acceptance: MCP and realtime tests pass; `updateMCPRegistryOptions` updates the shared record
+- [ ] **Task 2.2**: Sync view + keep validation
+  - Delivers: sync lookup uses catalog; `registerSync` validation + index promises still run
+  - Files: `api/src/sync/registry.ts`, `api/src/sync/*.test.ts`
+  - Blocked by: 1.2
+  - Acceptance: missing `deleted` / `_syncSeq` still throws; sync tests pass
+
+## Phase 3 — Contract
+
+- [ ] **Task 3.1**: Single writer + clear-all
+  - Delivers: `modelRouter` only writes `CollectionRegistry`; wrapper register/update/clear functions; tests that used independent clears updated
+  - Files: `api/src/api.ts`, registry wrappers, tests
+  - Blocked by: 2.1, 2.2
+  - Acceptance: one `replaceCollectionOptions` is enough for MCP+sync options identity
+- [ ] **Task 3.2**: Docs + changelog
+  - Files: `docs/explanation/modular-api-design.md`, `docs/reference/api.md`, changelog
+  - Blocked by: 3.1
+  - Skills: `update-docs`
+  - Acceptance: docs name the catalog as the runtime seam

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

@@ -2,27 +2,27 @@
 
 IP: [comms-adapter-expo-push](../implementationPlans/comms-adapter-expo-push.md)
 
-- [ ] **Task 1**: `ExpoPushProvider` implementation
+- [x] **Task 1**: `ExpoPushProvider` implementation
   - Description: token validation, chunked send, ticket collection per IP
   - Files: `comms/src/adapters/expoPush.ts`
   - Depends on: comms-abstraction Phase 1
   - Acceptance: mocked-client tests pass, one `SendResult` per token
-- [ ] **Task 2**: Receipt polling → `DeliveryEvent` + dead-token marking
+- [x] **Task 2**: Receipt polling → `DeliveryEvent` + dead-token marking
   - Description: poll receipts after configurable delay; map `DeviceNotRegistered` to permanent failure
   - Files: `comms/src/adapters/expoPush.ts`
   - Depends on: Task 1
   - Acceptance: dead token deactivated in test
-- [ ] **Task 3**: Dependency moves
+- [x] **Task 3**: Dependency moves
   - Description: optional peer `expo-server-sdk` on comms; remove from `@terreno/api`
   - Files: `comms/package.json`, `api/package.json`, root catalog if needed
   - Depends on: Task 1
   - Acceptance: `bun install` + full compile pass; api tests unaffected
-- [ ] **Task 4**: example-frontend token registration + dev test-send
+- [x] **Task 4**: example-frontend token registration + dev test-send
   - Description: register token on login via `POST /comms/pushTokens`; profile dev row triggers `sendPushToUser`
   - Files: `example-frontend/app/_layout.tsx` or profile screen, `example-backend` dev route
   - Depends on: Task 1, comms-abstraction Phase 2
   - Acceptance: UI verification per verify-ui-changes with screenshots
-- [ ] **Task 5**: Docs
+- [x] **Task 5**: Docs
   - Description: adapter section in `docs/reference/comms.md` with env/config table
   - Files: `docs/reference/comms.md`
   - Depends on: Task 1

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

@@ -25,15 +25,19 @@ IP: [comms-adapter-sendgrid](../implementationPlans/comms-adapter-sendgrid.md)
   - Depends on: 1.1
   - Acceptance: boot without key skips registration; compile passes without the SDK installed
 
-## Phase 2 — Delivery events + opt-outs (gated on inbound-webhooks)
+## Phase 2 — Delivery events + opt-outs (owned by inbound-webhooks)
+
+HTTP routes and mapping land in [inbound-webhooks](../implementationPlans/inbound-webhooks.md)
+Task 3.3. The tables in the SendGrid IP remain the contract. Do not Pick these on this
+adapter branch.
 
 - [ ] **Task 2.1**: Event Webhook route
   - Description: ECDSA signature verification via inbound-webhooks; event mapping per the IP table → `DeliveryEvent`; `x-message-id` prefix correlation
   - Files: `comms/src/adapters/sendgrid.ts`, webhook registration
-  - Depends on: inbound-webhooks IP
+  - Depends on: inbound-webhooks Task 3.3
   - Acceptance: signed fixtures per event type update `CommsMessage.status` (+ `errorCode` for bounce/dropped); unsigned rejected 401
 - [ ] **Task 2.2**: Opt-out events
   - Description: `spamreport`/`unsubscribe`/`group_unsubscribe` → `OptOutEvent` → consumer `onOptOut`
   - Files: `comms/src/adapters/sendgrid.ts` + tests
-  - Depends on: 2.1
+  - Depends on: inbound-webhooks Task 3.3
   - Acceptance: spamreport fixture fires `onOptOut`; subsequent `dropped` classified `permanent`

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

@@ -4,36 +4,40 @@ IP: [comms-adapter-twilio-sms](../implementationPlans/comms-adapter-twilio-sms.m
 
 ## Phase 1 — Send path
 
-- [ ] **Task 1.1**: `TwilioSmsProvider` with config resolution
+- [x] **Task 1.1**: `TwilioSmsProvider` with config resolution
   - Description: constructor/env config, messaging-service-first sender selection
   - Files: `comms/src/adapters/twilioSms.ts`
   - Depends on: comms-abstraction Phase 1
   - Acceptance: mocked-client tests cover both sender configs
-- [ ] **Task 1.2**: E.164 validation + error classification
+- [x] **Task 1.2**: E.164 validation + error classification
   - Description: `libphonenumber-js` normalization; Twilio error-code → `errorCode`/`errorClass` map per the IP table (unknown codes → `transient`); full error payload into `CommsMessage.metadata`; Twilio SDK calls wrapped with `withApiErrorHandling`
   - Files: `comms/src/adapters/twilioSms.ts`
   - Depends on: 1.1
-  - Acceptance: invalid number → 400 before API call; fixtures for at least one code per class (e.g. 21610 permanent, 20429 transient, 20003 config) assert `errorClass`; permanent failures skip the inline retry
-- [ ] **Task 1.3**: Dashboard metadata + hooks coverage
+  - Acceptance: invalid number → permanent `SendResult` before API call; fixtures for at least one code per class (e.g. 21610 permanent, 20429 transient, 20003 config) assert `errorClass`; permanent failures skip the inline retry
+- [x] **Task 1.3**: Dashboard metadata + hooks coverage
   - Description: `metadata.consoleUrl` deep link per message SID; `onError` fires with the classified `SendResult`
   - Files: `comms/src/adapters/twilioSms.ts` + tests
   - Depends on: 1.2
   - Acceptance: failed-send test asserts consoleUrl and onError invocation
-- [ ] **Task 1.4**: Peer dep + example-backend registration + docs
+- [x] **Task 1.4**: Peer dep + example-backend registration + docs
   - Description: optional peer `twilio`; env-gated registration; reference + env-var docs
   - Files: `comms/package.json`, `example-backend/src/server.ts`, `docs/reference/comms.md`, `docs/reference/environment-variables.md`
   - Depends on: 1.1
   - Acceptance: compile + boot without twilio installed when unconfigured
 
-## Phase 2 — Delivery callbacks + opt-outs (gated on inbound-webhooks)
+## Phase 2 — Delivery callbacks + opt-outs (owned by inbound-webhooks)
+
+HTTP routes and mapping land in [inbound-webhooks](../implementationPlans/inbound-webhooks.md)
+Tasks 3.2–3.3. The tables in the Twilio SMS IP remain the contract. Do not Pick these on
+this adapter branch.
 
 - [ ] **Task 2.1**: Status callback route
   - Description: webhook endpoint with Twilio signature verification via inbound-webhooks framework; status mapping per IP table incl. `ErrorCode` propagation
   - Files: `comms/src/adapters/twilioSms.ts`, webhook registration
-  - Depends on: inbound-webhooks IP
+  - Depends on: inbound-webhooks Task 3.2
   - Acceptance: signed payload updates `CommsMessage.status` (+ `errorCode` on failure); unsigned rejected 401
 - [ ] **Task 2.2**: STOP/START opt-out handling
   - Description: inbound keyword webhook → `OptOutEvent` → consumer `onOptOut`; opt-in (START) emitted symmetrically
   - Files: `comms/src/adapters/twilioSms.ts`, webhook registration + tests
-  - Depends on: 2.1
+  - Depends on: inbound-webhooks Task 3.2
   - Acceptance: STOP fixture fires `onOptOut` with `reason: "sms-stop"`; 21610 on later sends classified `permanent`

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

@@ -2,17 +2,17 @@
 
 IP: [comms-adapter-twilio-verify](../implementationPlans/comms-adapter-twilio-verify.md)
 
-- [ ] **Task 1**: `TwilioVerifyProvider` start/check
+- [x] **Task 1**: `TwilioVerifyProvider` start/check
   - Description: provider per IP with config resolution and status mapping
   - Files: `comms/src/adapters/twilioVerify.ts`
   - Depends on: comms-abstraction Phase 1
   - Acceptance: mocked-client tests for approved/pending/expired/max-attempts
-- [ ] **Task 2**: Redacted logging + error classification
+- [x] **Task 2**: Redacted logging + error classification
   - Description: `CommsMessage` rows with channel `verification`, fully redacted destination, no codes, and verification channel metadata on start; `errorCode`/`errorClass` mapping (rate-limit transient, expired/max-attempts permanent, bad SID config); rows flagged non-retryable; `onError` fires on failures
   - Files: `comms/src/adapters/twilioVerify.ts`
   - Depends on: Task 1
   - Acceptance: log assertion tests prove no code/full destination in any row; failure fixtures assert class + onError
-- [ ] **Task 3**: Registration + docs
+- [x] **Task 3**: Registration + docs
   - Description: env-gated example-backend registration; fail-fast on missing service SID; reference + env docs
   - Files: `example-backend/src/server.ts`, `docs/reference/comms.md`, `docs/reference/environment-variables.md`
   - Depends on: Task 1

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

@@ -4,17 +4,17 @@ IP: [comms-admin-dashboard](../implementationPlans/comms-admin-dashboard.md)
 
 ## Phase 1 — Backend routes
 
-- [ ] **Task 1.1**: Upgrade explorer to `commsDashboard.ts` list + detail
+- [x] **Task 1.1**: Upgrade explorer to `commsDashboard.ts` list + detail
   - Description: rich filters (channel/provider/status/errorClass/errorCode/userId/to/templateId/dates/`q`), pagination, `GET /comms/messages/:id` with attempts + metadata + retained payload
   - Files: `comms/src/routes/commsDashboard.ts` + supertest
   - Depends on: comms-abstraction Phase 2 (incl. hooks/error-taxonomy additions)
   - Acceptance: every filter covered by a supertest case; non-admin 403
-- [ ] **Task 1.2**: `retryMessage` facade + retry route
+- [x] **Task 1.2**: `retryMessage` facade + retry route
   - Description: retryability validation (status, errorClass, payload retention, channel configured, not verification), linked rows via `retriedFromId`/`retriedById`, hooks fire with `isRetry: true`, acting admin recorded
   - Files: `comms/src/commsService.ts`, `comms/src/routes/commsDashboard.ts` + tests
   - Depends on: 1.1
   - Acceptance: each non-retryable reason returns 400 with its stable `code`; successful retry creates a linked row
-- [ ] **Task 1.3**: `retryMany` + `/comms/stats`
+- [x] **Task 1.3**: `retryMany` + `/comms/stats`
   - Description: bulk retry with cap + skipped reasons; aggregation by channel × provider × status with day buckets and failure rate
   - Files: `comms/src/routes/commsDashboard.ts` + tests
   - Depends on: 1.2
@@ -22,17 +22,17 @@ IP: [comms-admin-dashboard](../implementationPlans/comms-admin-dashboard.md)
 
 ## Phase 2 — Admin screens
 
-- [ ] **Task 2.1**: `CommsDashboardScreen`
+- [x] **Task 2.1**: `CommsDashboardScreen`
   - Description: stats cards, filter bar (URL-persisted), DataTable with status badges + inline retry
   - Files: `admin-frontend/src/comms/CommsDashboardScreen.tsx`, `CommsStatusBadge.tsx`, `useCommsDashboardApi.tsx` + tests
   - Depends on: 1.1, 1.3
   - Acceptance: loading/error/empty states; filters round-trip through the URL
-- [ ] **Task 2.2**: `CommsMessageDetail`
+- [x] **Task 2.2**: `CommsMessageDetail`
   - Description: attempt timeline, provider console links, JSON viewer for payload/metadata, confirmed retry button with disabled-reason tooltips
   - Files: `admin-frontend/src/comms/CommsMessageDetail.tsx` + tests
   - Depends on: 1.2, 2.1
   - Acceptance: non-retryable rows show the specific reason; retry navigates to the new row
-- [ ] **Task 2.3**: Example app + admin-spa wiring
+- [x] **Task 2.3**: Example app + admin-spa wiring
   - Description: expo-router screens under `app/admin/comms/`, admin-spa nav entry, `bun run sdk`
   - Files: `example-frontend/app/admin/comms/*`, `example-frontend/store/openApiSdk.ts`, admin-spa nav
   - Depends on: 2.1, 2.2
@@ -40,12 +40,12 @@ IP: [comms-admin-dashboard](../implementationPlans/comms-admin-dashboard.md)
 
 ## Phase 3 — Bulk retry UI + docs
 
-- [ ] **Task 3.1**: "Retry all failed" flow
+- [x] **Task 3.1**: "Retry all failed" flow
   - Description: filtered bulk retry with count confirmation modal; skipped-reason summary toast
   - Files: `admin-frontend/src/comms/CommsDashboardScreen.tsx` + tests
   - Depends on: 1.3, 2.1
   - Acceptance: confirmation shows the exact count; result summarizes retried/skipped
-- [ ] **Task 3.2**: Docs + rules
+- [x] **Task 3.2**: Docs + rules
   - Description: dashboard section in comms reference, admin reference update, rulesync
   - Files: `docs/reference/comms.md`, `docs/reference/admin.md`, `.rulesync/**`
   - Depends on: 2.x

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

@@ -16,18 +16,24 @@ See: [`docs/implementationPlans/deploy-to-vercel.md`](../implementationPlans/dep
 Close every **Open TODO** in the IP before writing the how-to guide.
 
 - [ ] **Task 0.1**: Spike `@terreno/api` on Vercel
-  - Description: Prototype whether Socket.io, MongoDB change streams, and `@terreno/ai` SSE can run on Vercel (all-in-one candidate). Record runtime limits, cold starts, session affinity, and SSE buffering. Compare against split topology (Vercel web + long-running backend).
+  - Description: Prototype whether Socket.io, MongoDB change streams, and `@terreno/ai` SSE can run on Vercel (all-in-one candidate). Treat [Vercel Functions WebSockets (Public Beta)](https://vercel.com/docs/functions/websockets) as the vendor contract. Record Fluid compute, max-duration disconnects, instance pinning (not affinity across reconnects), Redis for cross-instance fan-out, Function billing while sockets are open, cold starts, and SSE buffering. Compare against split topology (Vercel web + long-running backend).
   - Files: spike notes in PR / IP update; optional scratch `example-backend/vercel.json`
   - Depends on: none
   - Acceptance: IP questions **V1**, **V2**, and **V3** updated with a recorded decision; all IP Open TODO checkboxes checked or explicitly deferred with owner.
 
+- [ ] **Task 0.2**: Write Vercel Functions WebSocket operator docs
+  - Description: Create `docs/how-to/vercel-function-websockets.md` from the IP section **Vercel Functions WebSockets (Public Beta)**. Cite `https://vercel.com/docs/functions/websockets`; do not copy Vercel examples. Cover Fluid compute, HTTP Upgrade + Firewall/rate limits, websocket-only Socket.IO, `export default` HTTP server vs `TerrenoApp.start()`, instance pinning, max-duration reconnects, Redis (`RealtimeApp` adapter), Function billing while connected, and verification (`WEBSOCKETS_DEBUG`, DevTools WS, no polling fallback). Mark **beta**. Do not recommend all-in-one topology until V1 is decided. Link from `docs/how-to/README.md` and later from `docs/how-to/deploy-web-to-vercel.md` and `docs/how-to/websocket-integration.md`.
+  - Files: `docs/how-to/vercel-function-websockets.md` (new), `docs/how-to/README.md`, `docs/how-to/websocket-integration.md`
+  - Depends on: none (may ship before Task 0.1 closes; must re-verify against the Vercel page at ship time)
+  - Acceptance: every required operator section from the IP is present; the Vercel URL is cited; Next.js `experimental_upgradeWebSocket`, Bun, and Python examples are out of scope; `corsOrigin: true` is not recommended; listed in the how-to index.
+
 ## Phase 1: Core how-to guide
 
 - [ ] **Task 1.1**: Write the Vercel deployment guide for `single` output
-  - Description: Create `docs/how-to/deploy-web-to-vercel.md`. Open with a "What goes where" section using the **topology decided in Phase 0** (interim split layout until spike closes; do not document all-in-one until V1 is decided). Then: prerequisites; backend host setup per V1 outcome; `vercel.json` for `single` output; `EXPO_PUBLIC_API_URL`; deploy + verify. Link `docs/explanation/deployment-baseline.md` instead of restating baseline requirements.
+  - Description: Create `docs/how-to/deploy-web-to-vercel.md`. Open with a "What goes where" section using the **topology decided in Phase 0** (interim split layout until spike closes; do not document all-in-one until V1 is decided). Then: prerequisites; backend host setup per V1 outcome; `vercel.json` for `single` output; `EXPO_PUBLIC_API_URL`; deploy + verify. Link `docs/explanation/deployment-baseline.md` instead of restating baseline requirements. Link `docs/how-to/vercel-function-websockets.md` wherever sockets on Functions are mentioned.
   - Files: `docs/how-to/deploy-web-to-vercel.md` (new), `docs/how-to/README.md`
-  - Depends on: `deployment-foundation` Phase 4
-  - Acceptance: every config key verified against current Expo docs; the "what goes where" reasoning is present in the first section; the guide links rather than duplicates the baseline explainer; listed in the how-to index.
+  - Depends on: `deployment-foundation` Phase 4, Task 0.2
+  - Acceptance: every config key verified against current Expo docs; the "what goes where" reasoning is present in the first section; the guide links rather than duplicates the baseline explainer; listed in the how-to index; websocket Functions page is linked, not duplicated.
 
 - [ ] **Task 1.2**: `[RTK]` Add the verification section
   - Description: Add a "Verify the deployment" section with four checks, each with the expected result and what failure means: (1) the root URL loads the app; (2) a deep link loads directly on refresh (proves the SPA rewrite works); (3) login succeeds, proving the API call reaches the backend and CORS is configured; (4) the websocket connects, proving realtime and live feature flags work. For check 4, give a concrete way to verify — browser devtools Network tab filtered to WS, or the client's debug logging flag (find the actual flag name in the client package, `WEBSOCKETS_DEBUG` at time of writing) — and explain that the app looks fine when this is broken, which is why it must be checked explicitly.
@@ -84,7 +90,7 @@ Close every **Open TODO** in the IP before writing the how-to guide.
   - Acceptance: frontmatter complete; the production-deploy confirmation gate is present; the verification step includes the websocket check; no command appears in the skill that is absent from the how-to guide.
 
 - [ ] **Task 4.2**: Add the troubleshooting reference
-  - Description: Create `.rulesync/skills/deploy-vercel/references/troubleshooting.md` covering at least these six, each with the literal symptom the user sees: blank white page after deploy (missing rewrites); 404 on refreshing a deep link (same root cause, different symptom); network requests going to `localhost:4000` in production (`EXPO_PUBLIC_API_URL` absent at build time); CORS error text quoted verbatim from a browser console; websocket connection failing while the rest of the app works; and SSE responses arriving all at once on server output (the buffering caveat). For each, give the fix and the file or setting to change.
+  - Description: Create `.rulesync/skills/deploy-vercel/references/troubleshooting.md` covering at least these six, each with the literal symptom the user sees: blank white page after deploy (missing rewrites); 404 on refreshing a deep link (same root cause, different symptom); network requests going to `localhost:4000` in production (`EXPO_PUBLIC_API_URL` absent at build time); CORS error text quoted verbatim from a browser console; websocket connection failing while the rest of the app works (Fluid off, long-polling fallback, or max-duration close — link `docs/how-to/vercel-function-websockets.md`); and SSE responses arriving all at once on server output (the buffering caveat). For each, give the fix and the file or setting to change.
   - Files: `.rulesync/skills/deploy-vercel/references/troubleshooting.md` (new)
   - Depends on: Task 4.1
   - Acceptance: at least six entries; each quotes a real error string or describes a precisely observable symptom; each names the file or setting to change.

package/dist/docs/versioned/next/tasks/describe-model-schema.md

@@ -0,0 +1,37 @@
+# Tasks: `describeModel()` schema metadata
+
+IP: [describe-model-schema.md](../implementationPlans/describe-model-schema.md)
+
+## Phase 1 — Descriptor + MCP
+
+- [ ] **Task 1.1**: `describeModel` / `describeModelForRouter`
+  - Delivers: field graph + snapshot tests on a fixture schema
+  - Files: `api/src/schemaMetadata.ts`, `api/src/schemaMetadata.test.ts`
+  - Blocked by: none
+  - Acceptance: snapshots for enum, ref, array, subdocument, system fields
+- [ ] **Task 1.2**: MCP Zod from descriptor
+  - Delivers: `schemaGenerator.ts` maps `FieldDescription`; no SchemaType switch for kinds already in the descriptor
+  - Files: `api/src/mcp/schemaGenerator.ts`, `api/src/mcp/schemaGenerator.test.ts`
+  - Blocked by: 1.1
+  - Acceptance: MCP schema tests pass; create tools still omit system fields
+
+## Phase 2 — Admin
+
+- [ ] **Task 2.1**: `extractFieldMeta` from descriptor
+  - Delivers: admin config fields built from `describeModel`, not OpenAPI property walk
+  - Files: `admin-backend/src/adminApp.ts`, admin-backend tests
+  - Blocked by: 1.1
+  - Acceptance: ref, enum, required, nested array items still appear on `/admin/config`
+
+## Phase 3 — OpenAPI + docs
+
+- [ ] **Task 3.1**: `getOpenApiSpecForModel` from descriptor
+  - Delivers: OpenAPI properties derived from `ModelDescription`; populate still applied
+  - Files: `api/src/populate.ts`, `api/src/openApi.test.ts` / example-backend openapi snapshot if required
+  - Blocked by: 1.1
+  - Acceptance: OpenAPI tests pass; any snapshot diff is reviewed in the PR
+- [ ] **Task 3.2**: Docs + export
+  - Files: `docs/explanation/schema-metadata.md`, `docs/reference/api.md`, `docs/how-to/create-a-model.md`, admin reference, `api/src/index.ts`, changelog
+  - Blocked by: 1.2, 2.1, 3.1
+  - Skills: `update-docs`
+  - Acceptance: stranger finds “one descriptor, three views” without reading code

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

@@ -32,7 +32,7 @@ See: [`docs/implementationPlans/docs-reference-coverage.md`](../implementationPl
   - Depends on: none
   - Acceptance: all three environment variables documented with their effects; the preload example matches an actual `bunfig.toml` in the repo; under 150 lines.
 
-- [ ] **Task 1.4**: `[RTK]` Fix the reference index
+- [x] **Task 1.4**: `[RTK]` Fix the reference index
   - Description: Update `docs/reference/README.md` to list every reference page that exists, including `ai.md`, `admin-spa.md`, `test.md`, `api-health.md`, `feature-flags.md`, `environment-variables.md`, and `syncdb.md`, with `rtk.md` under a Legacy heading. Cross-check against `ls docs/reference/` so nothing is orphaned and nothing listed is missing.
   - Files: `docs/reference/README.md`
   - Depends on: Task 1.1, Task 1.2, Task 1.3
@@ -46,19 +46,19 @@ See: [`docs/implementationPlans/docs-reference-coverage.md`](../implementationPl
   - Depends on: Task 1.1
   - Acceptance: all four follow the six sections in order; `rg -n "\.claude/|\.cursor/" ai/README.md admin-backend/README.md admin-frontend/README.md api-health/README.md` returns nothing; every relative link replaced with an absolute URL; each Quick start compiles if pasted into a matching file.
 
-- [ ] **Task 2.2**: Add the missing READMEs
+- [x] **Task 2.2**: Add the missing READMEs
   - Description: Create `feature-flags/README.md` (source: `docs/reference/feature-flags.md`; cover `FeatureFlagsApp` registration, the `/flagConfiguration` endpoint, `liveUpdates` and its replica-set requirement, and the deprecated `/evaluate` endpoint), `test/README.md` (source: the new `docs/reference/test.md`), `demo/README.md` (how to run the component demo on port 8085, how stories are organized under `stories/`, how to add a story and register it in `demoConfig.tsx`, and the demo-vs-dev mode split), and `website/README.md` (how to run the docs site locally, where content comes from — `../docs` — how versioning works, and how deploys happen via Netlify).
   - Files: `feature-flags/README.md`, `test/README.md`, `demo/README.md`, `website/README.md` (all new)
   - Depends on: Task 1.3
   - Acceptance: every command shown exists in the corresponding `package.json` scripts or the root `package.json`; `demo/README.md` correctly names port 8085; `website/README.md` correctly states that docs content lives in `../docs`.
 
-- [ ] **Task 2.3**: Normalize the four good READMEs
+- [x] **Task 2.3**: Normalize the four good READMEs
   - Description: Apply the template's link discipline (not a rewrite) to `api/README.md`, `ui/README.md`, `mcp-server/README.md`, and `admin-spa/README.md`: convert relative repo links to absolute URLs, add the Documentation / License / Contributing sections if missing, and ensure the description line matches the standardized `package.json` description. Additionally, reconcile `mcp-server/README.md`'s tool list with `docs/reference/mcp-server.md` and the live hosted server — the README is known to omit `terreno_search_docs`, `terreno_get_component_docs`, and `terreno_get_upgrade_guide`.
   - Files: `api/README.md`, `ui/README.md`, `mcp-server/README.md`, `admin-spa/README.md`
   - Depends on: Task 2.1
   - Acceptance: no relative link escapes the package directory in any of the four; `mcp-server/README.md` and `docs/reference/mcp-server.md` list identical tool sets; each README's opening line matches its `package.json` description.
 
-- [ ] **Task 2.4**: Add `docs/tasks/README.md`
+- [x] **Task 2.4**: Add `docs/tasks/README.md`
   - Description: Create a short README in `docs/tasks/` explaining that files there are structured task breakdowns for automated implementation of the IPs in `docs/implementationPlans/`, that they are internal planning artifacts rather than user documentation, and that they are excluded from the docs site. Do the same check for `docs/implementationPlans/README.md` — it exists; verify it says something similar and update if not.
   - Files: `docs/tasks/README.md` (new), `docs/implementationPlans/README.md`
   - Depends on: none
@@ -66,13 +66,13 @@ See: [`docs/implementationPlans/docs-reference-coverage.md`](../implementationPl
 
 ## Phase 3: Sanitization
 
-- [ ] **Task 3.1**: Sweep public docs for internal leakage
+- [x] **Task 3.1**: Sweep public docs for internal leakage
   - Description: Run `rg -ni "flourish|a\.run\.app|netlify\.app|PRO-[0-9]|FH-[0-9]|slack|\.claude/|\.cursor/" docs/ */README.md README.md` excluding `infra/flourish/` and `docs/implementationPlans/`. For each hit decide: remove, replace with a placeholder, or relocate to `infra/flourish/`. Live example URLs (the Netlify frontend, the Cloud Run backend) may stay in a clearly-labeled "Live examples" list but must not appear in instructional steps as if the reader owns them. Record the total number of fixes in the PR body.
   - Files: various under `docs/` and package READMEs
   - Depends on: Task 2.3
   - Acceptance: the grep returns only permitted hits (live-example URLs in labeled lists, and `docs/implementationPlans/` planning content); the PR body reports the count and lists each judgment call.
 
-- [ ] **Task 3.2**: Fix the how-to index and stale "Coming Soon" entries
+- [x] **Task 3.2**: Fix the how-to index and stale "Coming Soon" entries
   - Description: `docs/how-to/README.md` lists feature flags under "Coming Soon" even though `docs/how-to/add-feature-flags.md` exists. Audit the whole index against `ls docs/how-to/*.md`, remove stale "Coming Soon" markers for anything that shipped, and add entries for guides that exist but are unlisted. Do the same audit for `docs/explanation/` and `docs/tutorials/` indexes if they exist.
   - Files: `docs/how-to/README.md`, `docs/explanation/README.md` and `docs/tutorials/README.md` if present
   - Depends on: none
@@ -80,13 +80,13 @@ See: [`docs/implementationPlans/docs-reference-coverage.md`](../implementationPl
 
 ## Phase 4: Drift protection
 
-- [ ] **Task 4.1**: Extend the docs-audit check
+- [x] **Task 4.1**: Extend the docs-audit check
   - Description: Update `.rulesync/skills/docs-audit/SKILL.md` and the script it drives (find it via `.github/workflows/docs-audit.yml`) to add two checks: (1) every package published by `publish-on-tag.yml` has a non-stub `README.md` (heuristic: at least 30 lines and containing an `## Install` heading) and a `docs/reference/<pkg>.md` page; (2) no file under `docs/` or any published package README matches the internal-leakage pattern from Task 3.1. Make both failures fatal in CI. Regenerate skill mirrors with `bun run rules`.
   - Files: `.rulesync/skills/docs-audit/SKILL.md`, the docs-audit script, `.github/workflows/docs-audit.yml`, generated mirrors
   - Depends on: Task 3.1
   - Acceptance: deleting `feature-flags/README.md` makes the audit fail with a message naming the package; adding the string `flourish-terreno` to a docs page makes it fail; `bun run rules:check` exits 0.
 
-- [ ] **Task 4.2**: Document the reference/rule duplication policy
+- [x] **Task 4.2**: Document the reference/rule duplication policy
   - Description: Add a short section to `docs/explanation/ai-workflows.md` (or `CONTRIBUTING.md` if that reads better) explaining the deliberate split from IP question RF2: `docs/reference/` is descriptive documentation for humans, `.rulesync/rules/` is prescriptive guidance for agents, both are maintained, and a change to a package's public API requires updating both. Note that the docs-audit workflow flags drift but cannot fully verify it.
   - Files: `docs/explanation/ai-workflows.md` or `CONTRIBUTING.md`
   - Depends on: Task 4.1

package/dist/docs/versioned/next/tasks/docs-site-and-versioning.md

@@ -0,0 +1,42 @@
+# Task List: Documentation Site, Versioned Docs, and Docs-Maintenance Skills
+
+See: [`docs/implementationPlans/docs-site-and-versioning.md`](../implementationPlans/docs-site-and-versioning.md)
+
+Phases 1–2 and most of 3–4 already shipped on `master` (`website/`, generated
+reference, `docs:version` job, `update-docs` / `docs-audit`, weekly audit CI).
+This file tracks the remaining frontier.
+
+## Instructions for the implementing agent
+
+- Public MCP tool schemas live in `mcp-server/src/tools.ts`. Search behavior
+  lives in `mcp-server/src/search/docIndex.ts`.
+- Run `cd mcp-server && bun test src/__tests__/search.test.ts src/search/docVersion.test.ts`.
+- Update `docs/reference/mcp-server.md` in the same slice as the tool schema.
+
+## Phase 3: Versioning (remaining)
+
+- [x] **Task 3.1**: MCP `version` parameter on doc search tools
+  - Delivers: `terreno_search_docs` and `terreno_get_component_docs` accept
+    optional `version`. Unmatched versions fall back to the nearest retained
+    snapshot with a note. Omitted `version` searches `next` (current `docs/`).
+    Historical searches do not mix other versions. Versioned `.mdx` files are
+    indexed.
+  - Files: `mcp-server/src/search/docIndex.ts`, `mcp-server/src/search/docVersion.ts`,
+    `mcp-server/src/tools.ts`, `docs/reference/mcp-server.md`
+  - Blocked by: none
+  - Acceptance: `searchDocs({queries: ["token"], version: "0.19.0"})` returns
+    only that snapshot; a patch like `0.19.1` falls back to `0.19.0` with a
+    note; omitted version does not return `versioned/0.19.0` chunks;
+    `getComponentDocsMarkdown` accepts the same `version` and reads the
+    snapshot MDX when present.
+
+## Phase 4: Skills (remaining)
+
+- [x] **Task 4.1**: `improve-rulesync` docs-vs-agent split
+  - Delivers: `improve-rulesync` states that user-facing guidance belongs in
+    `docs/` (the site) and agent-facing guidance belongs in `.ai/` / rules,
+    with cross-links rather than duplication.
+  - Files: `.rulesync/skills/improve-rulesync/SKILL.md` (then `bun run skills:sync`)
+  - Blocked by: Task 3.1
+  - Acceptance: the skill names both homes and forbids copying the same
+    architecture into both without a cross-link.

package/dist/docs/versioned/next/tasks/feature-flags-openfeature.md

@@ -1,5 +1,7 @@
 # Feature Flags → OpenFeature — Task List
 
+**Status:** Closed (2026-08-25) — IP complete; `@terreno/feature-flags` and `@terreno/rtk` ship on OpenFeature. The two open boxes are verification steps (SDK regen, full workspace run) that landed with the merge.
+
 See `docs/implementationPlans/feature-flags-openfeature.md` for full details.
 
 ## Phase 0: Catalog & deps

package/dist/docs/versioned/next/tasks/inbound-webhooks.md

@@ -0,0 +1,77 @@
+# Tasks: Inbound webhook framework
+
+IP: [inbound-webhooks.md](../implementationPlans/inbound-webhooks.md)  
+**Closes:** https://github.com/FlourishHealth/terreno/issues/1172
+
+**Feature profile:** false (full IP)
+
+## Phase 1 — Tracer (raw body, HMAC, memory claim)
+
+- [x] **Task 1.1**: Raw-body capture on TerrenoApp parsers
+  - Delivers: JSON (and urlencoded) parse stores `req.rawBody` as a `Buffer`; existing JSON routes still work
+  - Files: `api/src/webhooks/rawBody.ts`, `api/src/terrenoApp.ts`, `api/src/webhooks/rawBody.test.ts`
+  - Blocked by: none
+  - Skills: `terreno-backend-api`, `backend-test-env`
+  - Docs: stub one sentence in `docs/reference/api.md` that inbound routes will use `rawBody`
+  - Acceptance: bun test — parsed `req.body` matches today; `rawBody` equals the sent bytes; mutating parsed JSON does not change `rawBody`
+
+- [x] **Task 1.2**: `WebhooksApp` + HMAC verifier + memory idempotency
+  - Delivers: `new WebhooksApp().route({path, source, verify, eventId, handler})`; `app.register(webhooks)` mounts anonymous POST; valid HMAC 200 once; bad/missing signature 401 `webhook-signature-invalid`; duplicate `eventId` 200 `duplicate: true` without second handler; handler throw 500 then retry succeeds; path not in `/openapi.json`
+  - Files: `api/src/webhooks/webhooksApp.ts`, `api/src/webhooks/verifiers/hmac.ts`, `api/src/webhooks/idempotency/memoryStore.ts`, `api/src/webhooks/webhooksApp.test.ts`, `api/src/index.ts`, `api/src/terrenoPlugin.ts` (early capture hook if needed)
+  - Blocked by: 1.1
+  - Skills: `terreno-backend-api`
+  - Docs: stub `WebhooksApp` example in `docs/reference/api.md`
+  - Acceptance: bun + supertest cover the Goal tracer in the IP; timing-safe compare; empty `eventId` skips claim and warns; `webhooks.claim` is callable from a handler for nested ids
+
+## Phase 2 — Provider verifiers + Mongo receipts
+
+- [x] **Task 2.1**: Stripe + Twilio + SendGrid verifiers
+  - Delivers: `stripeSignature`, `twilioSignature`, `sendgridEventSignature` helpers; Stripe and SendGrid timestamps outside tolerance fail; Twilio form-urlencoded verifies; SendGrid ECDSA with a test keypair
+  - Files: `api/src/webhooks/verifiers/stripe.ts`, `twilio.ts`, `sendgrid.ts`, `verifiers/*.test.ts`
+  - Blocked by: 1.2
+  - Skills: `terreno-backend-api`
+  - Docs: verifier table in `docs/how-to/inbound-webhooks.md` (create page if 3.1 not started)
+  - Acceptance: fixture tests only (no network); mutated payload 401
+
+- [x] **Task 2.2**: Mongo idempotency store
+  - Delivers: `idempotency: {store: "mongo", ttlDays?}` uses mongoose connection and `webhookReceipts` unique `(source, eventId)` + TTL; claim-before-handler; release on throw
+  - Files: `api/src/webhooks/idempotency/mongoStore.ts`, schema/types if a model is used, tests via `@terreno/test`
+  - Blocked by: 1.2
+  - Skills: `mongoose-schema-safety`, `backend-test-env`
+  - Docs: collection / TTL note on the how-to
+  - Acceptance: two sources can share an event id string; TTL index present; no public modelRouter
+
+## Phase 3 — Example HMAC + comms routes
+
+- [x] **Task 3.1**: example-backend HMAC demo
+  - Delivers: `POST /webhooks/example` registered only when `WEBHOOK_SECRET` is set; handler logs `[Webhook]` and returns `{received: true}`
+  - Files: `example-backend/src/server.ts` (or small `webhooksExample.ts` + test)
+  - Blocked by: 1.2
+  - Skills: `terreno-backend-api`, `backend-test-env`
+  - Docs: none (4.1)
+  - Acceptance: bun test — unset secret → no route (404); set secret → signed POST 200
+
+- [x] **Task 3.2**: Twilio status + inbound routes on CommsApp
+  - Delivers: `CommsApp({webhooks, webhookPublicUrl, sms: TwilioSmsProvider})` mounts `POST {basePath}/webhooks/twilio/status` and `.../inbound`; Twilio verifier; status mapping per comms-adapter-twilio-sms table including `ErrorCode`; STOP/START → `recordOptOut`; `statusCallbackUrl` defaults to the public status URL; skip routes and `logger.error` if auth token missing
+  - Files: `comms/src/commsApp.ts`, `comms/src/adapters/twilioSms.ts` (or `comms/src/webhooks/twilio.ts`), tests, `example-backend/src/server.ts` (pass `webhooks` when SMS adapter is on)
+  - Blocked by: 2.1
+  - Skills: `terreno-backend-api`, `backend-test-env`
+  - Docs: paths in `docs/reference/comms.md` (full page in 4.1)
+  - Acceptance: bun tests — signed delivered/failed fixtures update `CommsMessage`; unsigned 401; STOP fires `onOptOut` `reason: "sms-stop"`; no `webhooks` option → those paths 404
+
+- [x] **Task 3.3**: SendGrid Event Webhook on CommsApp
+  - Delivers: `CommsApp({webhooks, mail: SendGridMailProvider})` mounts `POST {basePath}/webhooks/sendgrid`; ECDSA verifier; per-`sg_event_id` `webhooks.claim`; mapping per comms-adapter-sendgrid table; correlate `sg_message_id` prefix to stored `x-message-id`; `SENDGRID_WEBHOOK_VERIFICATION_KEY` (or constructor `webhookVerificationKey`); skip + `logger.error` if key missing
+  - Files: `comms/src/commsApp.ts`, `comms/src/adapters/sendgrid.ts` (or `comms/src/webhooks/sendgrid.ts`), tests, `example-backend/src/server.ts`
+  - Blocked by: 2.1
+  - Skills: `terreno-backend-api`, `backend-test-env`
+  - Docs: path + key in `docs/reference/comms.md` / env table (4.1)
+  - Acceptance: bun tests — signed delivered/bounce/spamreport fixtures; unsigned 401; duplicate `sg_event_id` no second `recordDeliveryEvent`; batch of two events both applied
+
+## Phase 4 — Docs and seed
+
+- [x] **Task 4.1**: Diátaxis + changelog + agent docs
+  - Delivers: how-to, reference, replace auth HMAC snippet, env table (`SENDGRID_WEBHOOK_VERIFICATION_KEY`, `PUBLIC_API_URL` / `COMMS_WEBHOOK_PUBLIC_URL`), comms webhook section, custom-routes skill, api rule, unreleased changelog, seed IP/task URLs, adapter Phase 2 ownership note, `bun run rules` / `skills:sync` if rulesync changed
+  - Files: `docs/how-to/inbound-webhooks.md`, `docs/how-to/README.md`, `docs/reference/api.md`, `docs/reference/comms.md`, `docs/explanation/authentication.md`, `docs/reference/environment-variables.md`, `docs/explanation/roadmap-seed-issues.md`, `docs/implementationPlans/billing-stripe.md`, `docs/implementationPlans/comms-adapter-twilio-sms.md`, `docs/implementationPlans/comms-adapter-sendgrid.md`, `.rulesync/skills/terreno-backend-api/references/custom-routes.md`, `.rulesync/rules/api/00-api.mdc`, `.rulesync/rules/comms/00-comms.md`, `changelog/unreleased/inbound-webhooks.md`
+  - Blocked by: 1.2 (content must match 2.x and 3.x)
+  - Skills: `update-docs`, `update-agent-docs`
+  - Acceptance: a stranger can register HMAC, Twilio, and SendGrid routes from the how-to/comms reference without reading this IP; `bun run website:build`; old `JSON.stringify(req.body)` snippet gone