@terreno/mcp 0.31.0 → 56.0.0-beta.2

package/dist/docs/versioned/next/how-to/migrate-rtk-to-syncdb.md

@@ -0,0 +1,445 @@
+# How to Migrate from @terreno/rtk to @terreno/syncdb
+
+This guide is **AI-context-first**: it is written for an agent (or human) performing a screen-by-screen migration, not as a codemod. Work through one concern at a time — reads, then writes, then conflicts, then sync-status UX — and delete RTK-era code as you go.
+
+`@terreno/syncdb` supersedes `@terreno/rtk` for **data synchronization** (CRUD reads/writes, offline queue, realtime convergence). It does not replace the generated OpenAPI SDK, Better Auth Redux wiring, or feature-flag infrastructure.
+
+## 1. Before you start
+
+| Decision | Requirement | Why |
+|----------|-------------|-----|
+| **Better Auth first?** | Recommended before or in parallel with data migration | `betterAuthAdapter` is the shipped `AuthProvider`; socket sessions work cleanly with `RealtimeApp({betterAuth})`. Legacy JWT sockets still work during transition. |
+| **Backend version** | `@terreno/api` with `SyncApp`, `RealtimeApp`, `syncPlugin`, `isDeletedPlugin` | Without backend sync registration, the client has nothing to talk to. |
+| **MongoDB replica set** | Required for `RealtimeApp` change streams | Single-node replset is fine for dev. |
+| **Per-collection rollout** | One synced collection at a time | REST and sync share the same write path; migrate screen-by-screen. |
+| **Redux** | Keep Redux for auth, feature flags, app state; drop RTK Query for migrated collections | See §2. |
+
+**Auth can migrate before data (M3).** A typical two-step order:
+
+1. **Step A — Auth:** Move login/session to Better Auth (`generateBetterAuthSlice`, `betterAuthAdapter`, `syncDb.start()` on login). Screens can still read/write via RTK Query during this step.
+2. **Step B — Data:** For each collection, replace RTK Query hooks with syncdb hooks and delete the RTK path for that screen.
+
+The example app completed both steps; todos are syncdb-only while profile/admin still use generated RTK hooks.
+
+Reference: [`docs/reference/syncdb.md`](../reference/syncdb.md), and the package [`syncdb/README.md`](https://github.com/flourishhealth/terreno/blob/release-56.0.0/syncdb/README.md).
+
+## 2. Install and configure
+
+### Install packages
+
+```bash
+bun install @terreno/syncdb
+bunx expo install expo-sqlite   # native persistence — install in the app, rebuild native
+```
+
+### Create the sync client
+
+**After** (`example-frontend/store/syncdb.ts`):
+
+```typescript
+import {baseUrl} from "@terreno/rtk";
+import {betterAuthAdapter, createSyncDb} from "@terreno/syncdb";
+import {betterAuthClient} from "@/lib/betterAuth";
+
+const authProvider = betterAuthAdapter(betterAuthClient, {pollIntervalMs: 60_000});
+
+export const syncDb = createSyncDb({
+  authProvider,
+  baseUrl,
+  collections: ["todos"],
+  name: "terreno-example",
+  debug: __DEV__ ? {capacity: 1000} : false,
+});
+```
+
+### Start/stop on auth
+
+**After** (`example-frontend/app/_layout.tsx`):
+
+```typescript
+useEffect(() => {
+  if (!userId) {
+    return;
+  }
+  let stopped = false;
+  syncDb
+    .start()
+    .then(() => {
+      if (!stopped) {
+        setSyncDbReady(true);
+      }
+    })
+    .catch((error) => {
+      console.error("[syncdb] Failed to start client", error);
+    });
+  return () => {
+    stopped = true;
+    setSyncDbReady(false);
+    void syncDb.stop();
+  };
+}, [userId, syncDbStartAttempt]);
+```
+
+Gate writes with a ready flag (`useSyncDbReady`) so `mutate()` is not called before `start()` resolves a user.
+
+### Wrap screens with `SyncDbProvider`
+
+**After** (`example-frontend/app/(tabs)/index.tsx`):
+
+```tsx
+import {SyncDbProvider} from "@terreno/syncdb/react";
+import {syncDb} from "@/store/syncdb";
+
+const TodosScreen = () => (
+  <SyncDbProvider client={syncDb}>
+    <SyncTodosScreen />
+  </SyncDbProvider>
+);
+```
+
+The example also mounts `SyncDbProvider` at the root (`_layout.tsx`) for `SyncHealthToast`.
+
+### Redux store: keep vs remove
+
+| Keep on Redux | Remove for migrated collections |
+|---------------|--------------------------------|
+| `generateBetterAuthSlice` / session | `generateAuthSlice` (JWT) once Better Auth ships |
+| `terrenoApi` reducer for **non-synced** routes | `useGetTodosQuery` / todo mutations |
+| `createOfflineMiddleware` + offline slice | `realtimeList` / `realtimeDocument` for that collection |
+| Feature-flag / app-state slices | Per-screen `isLoading` spinners tied to RTK mutations |
+
+**Before** (`origin/master:example-frontend/store/index.ts`): `generateAuthSlice`, `createOfflineMiddleware`, offline payload sessionStorage.
+
+**After** (`example-frontend/store/index.ts`): `generateBetterAuthSlice`, `terrenoApi` only — no offline middleware.
+
+## 3. Reads
+
+There is no `isLoading` for reads after bootstrap — data is already in the local store.
+
+### List reads
+
+**Before** (`origin/master:example-frontend/app/(tabs)/index.tsx`):
+
+```typescript
+const {data: todosData, isLoading, refetch, isFetching} = useGetTodosQuery({}, {skip: !userId});
+const todos = todosData?.data ?? [];
+```
+
+**After** (`example-frontend/components/SyncTodosScreen.tsx`):
+
+```typescript
+import {useEntity, useEntityIds} from "@terreno/syncdb/react";
+
+const incompleteIds = useEntityIds<SyncTodo>("todos", {
+  filter: (t) => !t.completed,
+  sort: sortByCreatedDesc,
+});
+
+// Per row:
+const {data} = useEntity<SyncTodo>("todos", id);
+```
+
+For small lists, `useQuery` is fine:
+
+```typescript
+import {useQuery} from "@terreno/syncdb/react";
+const todos = useQuery<Todo>("todos", {filter: (t) => !t.completed});
+```
+
+`filter` / `sort` run in JS — there are no server query params. Tombstones are excluded unless `{includeDeleted: true}`.
+
+### Delete this RTK read code
+
+- `useGetTodosQuery` / `useGet*Query` for the migrated collection
+- `isLoading`, `isFetching`, `refetch`, `RefreshControl` wired to list fetch
+- `skip: !userId` guards on list queries (replace with `useSyncDbReady` on writes; reads are safe once bootstrapped)
+- `realtimeList("todos")` / `realtimeDocument("todos")` in `store/sdk.ts` for that collection
+
+## 4. Writes
+
+Writes are synchronous from the UI's perspective: local apply + outbox enqueue + background replay.
+
+### Create / update / delete
+
+**Before** (`origin/master:example-frontend/app/(tabs)/index.tsx`):
+
+```typescript
+const [createTodo, {isLoading: isCreating}] = usePostTodosMutation();
+const [updateTodo] = usePatchTodosByIdMutation();
+const [deleteTodo] = useDeleteTodosByIdMutation();
+
+await createTodo({title, completed: false}).unwrap();
+await updateTodo({id, completed: true}).unwrap();
+await deleteTodo(id).unwrap();
+```
+
+**After** (`example-frontend/components/SyncTodosScreen.tsx`):
+
+```typescript
+import {generateMutationId} from "@terreno/syncdb";
+import {useMutate} from "@terreno/syncdb/react";
+
+const {create, update, remove} = useMutate("todos");
+
+const id = generateMutationId();
+create({data: {_id: id, title, completed: false, created: DateTime.now().toISO()}});
+update({id, data: {completed: true}});
+remove({id});
+```
+
+Client-minted `_id` on creates lets the optimistic row render before the server acks.
+
+### Delete this RTK write code
+
+- `usePost*Mutation`, `usePatch*Mutation`, `useDelete*Mutation` for the migrated collection
+- `.unwrap()` / try-catch around mutation promises for happy-path UX
+- **`isLoading` / `isCreating` / `isUpdating` spinners on write buttons** — syncdb writes do not await the server
+- Manual optimistic cache updates (`updateQueryData`, `upsertQueryData`, temporary local rows in component state)
+- `refetch()` or tag invalidation after mutate (`invalidatesTags` for that collection)
+- `createOfflineMiddleware` endpoint list entries for that collection (`configureOfflineMutationEndpoints`)
+- `If-Unmodified-Since` / 409 handling in custom mutation code (conflicts move to `useConflicts()`)
+
+Server rejection surfaces later as outbox nacks — conflicts in `useConflicts()`, terminal failures in `getSyncStatus().failedCount`.
+
+## 5. Conflicts
+
+A **conflict** means the client's `baseVersion` (last seen `_syncSeq`) disagrees with the server. The server returns a `conflict` nack:
+
+- HTTP: `POST /sync/mutate` → **409** with `{nack: {code: "conflict", serverDoc, serverSeq, ...}}`
+- Socket: `sync:nack` with `code: "conflict"`
+
+The client records the conflict locally; the UI must let the user pick a side.
+
+### Strategies
+
+| Strategy | When to use |
+|----------|-------------|
+| `useServer` | Accept canonical server data (or tombstone if server deleted the doc) |
+| `keepMine` | Re-enqueue local changes with a fresh `baseVersion` |
+
+```typescript
+import {useConflicts} from "@terreno/syncdb/react";
+
+const {conflicts, resolve} = useConflicts();
+resolve({mutationId, strategy: "useServer"});
+resolve({mutationId, strategy: "keepMine"});
+```
+
+### Minimum UI
+
+The example app uses:
+
+- `SyncConflictsController` — single app-wide sheet state (`example-frontend/components/SyncConflictsController.tsx`)
+- `ConflictSheet` rendered from `SyncHealthToast` (`example-frontend/app/_layout.tsx`)
+- `SyncStatusBanner` conflict badge → `openConflicts("todos")` (`example-frontend/components/SyncTodosScreen.tsx`)
+
+Copy that pattern or build equivalent: show local vs server fields, two resolution actions, block further edits on conflicted entities until resolved.
+
+## 6. Sync status
+
+Replace **request-loading UX** with **sync-state UX**.
+
+| RTK era | Syncdb era |
+|---------|------------|
+| `isLoading` on queries | No list loading spinner (data is local) |
+| `useOfflineStatus` / `useServerStatus` | `useSyncStatus()` |
+| `OfflineBanner` on fetch failure | `SyncStatusBanner` + `SyncHealthToast` |
+| Pull-to-refresh `refetch()` | Optional `client.forceResync()` for support tooling |
+
+**After** (`example-frontend/components/SyncTodosScreen.tsx`):
+
+```typescript
+import {useSyncStatus} from "@terreno/syncdb/react";
+import {SyncStatusBanner} from "@terreno/ui";
+
+const syncStatus = useSyncStatus();
+
+<SyncStatusBanner
+  isOnline={syncStatus.isOnline}
+  queuedCount={syncStatus.queuedCount}
+  conflictCount={syncStatus.conflictCount}
+  failedCount={syncStatus.failedCount}
+  paused={syncStatus.paused}
+  draining={syncStatus.draining}
+  sentThisDrain={syncStatus.sentThisDrain}
+  totalThisDrain={syncStatus.totalThisDrain}
+  onOpenConflicts={openConflictSheet}
+  onAuthRequired={handleAuthRequired}
+/>
+```
+
+`SyncHealthToast` (`example-frontend/components/SyncHealthToast.tsx`) adds persistent toasts for per-collection conflicts/failures and an initial "Syncing…" toast with optional force reload.
+
+`paused: "auth"` means replay is halted until the same user re-authenticates — wire `onAuthRequired` to your login flow.
+
+## 7. Auth
+
+**Auth can ship before data migration.** Complete Better Auth + `betterAuthAdapter` first; keep RTK Query for reads/writes until each screen migrates.
+
+### Better Auth adapter
+
+**After** (`example-frontend/store/syncdb.ts`):
+
+```typescript
+import {betterAuthAdapter, createSyncDb} from "@terreno/syncdb";
+import {betterAuthClient} from "@/lib/betterAuth";
+
+const authProvider = betterAuthAdapter(syncAuthClient, {pollIntervalMs: 60_000});
+
+export const syncDb = createSyncDb({authProvider, baseUrl, collections: ["todos"], name: "terreno-example"});
+```
+
+`betterAuthAdapter` implements `AuthProvider`:
+
+- `getToken()` / `getUserId()` — read session per request (not cached)
+- `onAuthChange` — session atom subscription (example bridges `$store.atoms.session`)
+- `refresh()` — one silent refresh per auth-pause episode
+
+### Token storage
+
+Better Auth session tokens live in the Better Auth client (`@terreno/rtk` `createBetterAuthClient`):
+
+- **Native:** `expo-secure-store`
+- **Web:** `@react-native-async-storage/async-storage`
+
+Syncdb does not store tokens itself — it calls `authProvider` on every transport/HTTP request.
+
+### Socket auth and `sync:auth-expired`
+
+On connect, the socket transport sends the bearer token from `getToken()`. When the server's session re-validation sweep finds an expired/disabled session, it emits `sync:auth-expired` then disconnects (`api/src/realtime/sessionRevalidation.ts`). The client maps this to `paused: "auth"` — **no local wipe**, outbox preserved (INV-2).
+
+### Backend
+
+```typescript
+new RealtimeApp({betterAuth: {auth, userModel: User}})
+```
+
+Required for Better Auth socket sessions. Legacy JWT sockets continue to work without it.
+
+## 8. Codegen
+
+### Does `bun run sdk` still work?
+
+**Yes.** `example-frontend/package.json` still defines:
+
+```json
+"sdk": "bun scripts/generate-sdk.ts && bun biome check --write scripts/generate-sdk.ts"
+```
+
+It runs `@rtk-query/codegen-openapi` against `openapi-config.ts` and writes `store/openApiSdk.ts`.
+
+### What changes post-migration
+
+| Still generated | Stop using for migrated collections |
+|-----------------|-------------------------------------|
+| Auth routes, `GET /auth/me`, admin, AI explorer, version config, feature flags | `useGetTodosQuery`, `usePostTodosMutation`, etc. |
+| Custom REST / RPC endpoints | Todo `realtimeList` / `realtimeDocument` wiring in `store/sdk.ts` |
+
+Keep running `bun run sdk` after backend route changes — non-synced screens still import from `store/sdk.ts`.
+
+Workflow:
+
+```bash
+# Backend running on port 4000
+cd example-frontend && bun run sdk
+```
+
+## 9. Feature flags
+
+Post-migration, feature flags stay on `@terreno/rtk` + OpenFeature — **not** on syncdb.
+
+**After** (`example-frontend/app/_layout.tsx`):
+
+```typescript
+import {OpenFeatureProvider} from "@openfeature/react-sdk";
+import {useTerrenoFeatureFlags} from "@terreno/rtk";
+
+const OpenFeatureBridge = ({children, socket}) => {
+  const bridgeUserId = useSelector(selectBetterAuthUserId) ?? undefined;
+  useTerrenoFeatureFlags(terrenoApi, {skip: !bridgeUserId, socket, userId: bridgeUserId});
+  return <OpenFeatureProvider domain="feature-flags">{children}</OpenFeatureProvider>;
+};
+```
+
+See [`docs/reference/feature-flags.md`](../reference/feature-flags.md) and [`docs/how-to/add-feature-flags.md`](add-feature-flags.md).
+
+**Example app gap:** todos do **not** gate on a feature flag — `SyncTodosScreen` is syncdb-only. For a gradual rollout, add a boolean flag and render the RTK screen when off, syncdb screen when on (see §10). The reference migration intentionally skipped flag wiring to keep one data path for e2e tests.
+
+## 10. Rollback
+
+### Per-screen feature flag
+
+Ship both implementations behind a flag:
+
+- Flag **off** → legacy RTK Query screen
+- Flag **on** → syncdb screen
+
+Both bundles ship until you flip the default and delete the RTK path.
+
+The example app does **not** use this pattern for todos.
+
+### What local data survives
+
+| Event | Local IndexedDB / SQLite | Outbox |
+|-------|------------------------|--------|
+| Logout / 401 | **Kept** (INV-2) | **Kept** — same user can sign back in and replay |
+| Different-user login | **Wiped** | **Wiped** |
+| `signOut()` default | **Kept** | **Kept** |
+| `signOut()` with `wipeOnSignOut: true` | **Wiped** | **Wiped** |
+| Schema version mismatch | **Wiped** + re-bootstrap | Re-built |
+| Decrypt failure (web, default) | **Wiped** + re-bootstrap | Re-built |
+
+`wipeLocalData` clears store tables, persisted databases, and cached encryption keys (`syncdb/src/storage/wipe.ts`).
+
+Rolling back a **screen** to RTK does not automatically clear syncdb data — stale local todos may still exist until user switch or explicit wipe. Plan for that if you flip the flag off in production.
+
+## 11. Checklist
+
+Copy and track per collection:
+
+```
+[ ] 1. Backend: isDeletedPlugin + syncPlugin on schema
+[ ] 2. Backend: modelRouter sync scope configured
+[ ] 3. Backend: SyncApp + RealtimeApp registered; Mongo replica set running
+[ ] 4. Backend: ensureSyncIndexes succeeds at startup
+[ ] 5. Frontend: @terreno/syncdb installed; expo-sqlite in app (native)
+[ ] 6. Frontend: createSyncDb client + betterAuthAdapter
+[ ] 7. Frontend: syncDb.start()/stop() wired to auth in root layout
+[ ] 8. Frontend: SyncDbProvider wraps migrated screens
+[ ] 9. Reads: useGet*Query → useQuery / useEntityIds + useEntity
+[ ] 10. Writes: usePost/Patch/Delete*Mutation → useMutate().create/update/remove
+[ ] 11. Deleted RTK: mutation isLoading spinners, refetch-after-mutate, offline middleware entries, realtime cache patches
+[ ] 12. Conflicts: useConflicts + resolution UI (ConflictSheet or equivalent)
+[ ] 13. Sync status: useSyncStatus + SyncStatusBanner / health toasts (not query isLoading)
+[ ] 14. Auth: Better Auth session + onAuthRequired → re-login when paused
+[ ] 15. Codegen: bun run sdk still run for non-synced routes; remove todo hooks from screens
+[ ] 16. Feature flags: OpenFeature bridge still fed via useTerrenoFeatureFlags (if used)
+[ ] 17. Rollback plan: feature flag or accept stale local data on revert
+[ ] 18. Verify: CRUD, offline create/edit/delete, reconnect, conflict both strategies, user switch
+```
+
+## Backend prerequisites (detail)
+
+Before a collection can sync:
+
+- [ ] `isDeletedPlugin` on schema (soft delete required)
+- [ ] `syncPlugin` on schema (`_syncSeq` stamping)
+- [ ] `modelRouter("/path", Model, {sync: {scope: ...}})` three-argument form
+- [ ] Custom scopes include `snapshotFilter`
+- [ ] `new SyncApp({getUserScopes?})` for tenant/custom scopes
+- [ ] `new RealtimeApp({betterAuth?})` + MongoDB replica set
+- [ ] No `updateMany`, `deleteMany`, `deleteOne`, `findOneAndDelete`, or `bulkWrite` on synced models
+
+## What stays on @terreno/rtk
+
+- Generated OpenAPI SDK for non-synced routes
+- Better Auth Redux slice (`generateBetterAuthSlice`)
+- Feature flags (`useTerrenoFeatureFlags` / `useFeatureFlags`)
+- Socket connection for flags and legacy realtime (until removed)
+- `@terreno/rtk` is not being removed
+
+## Further reading
+
+- [`docs/reference/syncdb.md`](../reference/syncdb.md) — full API reference
+- [`syncdb/README.md`](https://github.com/flourishhealth/terreno/blob/release-56.0.0/syncdb/README.md) — architecture and protocol detail
+- [`docs/how-to/configure-better-auth.md`](configure-better-auth.md) — Better Auth setup

package/dist/docs/versioned/next/implementationPlans/PLAN_INDEX.md

@@ -9,35 +9,47 @@ Umbrella plans that coordinate several IPs.
 | Program | Status | Created | IPs |
 |---------|--------|---------|-----|
 | [Open source launch](oss-launch-program.md) | Draft — decisions recorded; Vercel spike open | 2026-07-27 | 15 |
-| [B2B platform](b2b-platform-program.md) | Draft — decisions D1–D7 resolved | 2026-08-09 | 9 written (+ [rbac-permissions](rbac-permissions.md)); 29 roadmap items seeded |
 
 ## Active
 
 | Plan | Status | Created | Tasks |
 |------|--------|---------|-------|
+| [Migrate CI/CD to CircleCI](migrate-cicd-to-circleci.md) | Draft — decisions recorded | 2026-08-17 | [tasks](../tasks/migrate-cicd-to-circleci.md) |
 | [Admin UI v2 — Django-parity admin](admin-ui-v2-django-parity.md) | Approved | 2026-06-15 | [tasks](../tasks/admin-ui-v2-django-parity.md) |
-| [RBAC Permissions](rbac-permissions.md) | Draft (API design) | 2026-07-08 | TBD |
-| [SyncDB Local-First Data Layer](syncdb-local-first.md) | In progress ([PR #869](https://github.com/flourishhealth/terreno/pull/869)) | 2026-07-13 | [tasks](../tasks/syncdb-local-first.md) |
-| [MCP Boost parity](mcp-boost-parity.md) | In progress ([PR #802](https://github.com/flourishhealth/terreno/pull/802)) | 2026-06-21 | TBD |
-| [Infrastructure MCP server](infra-mcp.md) | Draft — blocked on [RBAC](rbac-permissions.md) | 2026-08-09 | [tasks](../tasks/infra-mcp.md) |
+| [@terreno/syncdb-codegen](syncdb-codegen.md) | Draft | 2026-07-08 | [tasks](../tasks/syncdb-codegen.md) |
+| [SyncDB local-first data layer (v2)](syncdb-local-first.md) | In progress — Phases 1–8 landed, Phase 9 follow-ups open | 2026-06-23 | [tasks](../tasks/syncdb-local-first.md) |
+| [SyncDB hardening (syncdb-2)](terreno-syncdb-2.md) | Implemented — Phases A–F landed; deviations carried into Phase 9 | 2026-07-11 | [tasks](../tasks/syncdb-local-first.md) (Phase 8/9) |
+| [SyncDB Phase C design](syncdb-phase-c-design.md) | Implemented — design authority for C1–C8 | 2026-07-11 | [tasks](../tasks/syncdb-local-first.md) (Phase 8) |
+
+## Completed
+
+| Plan | Status | Created | Tasks |
+|------|--------|---------|-------|
+| [APIError redesign — standards-first extension of Error](apierror-standard-error-redesign.md) | Complete | 2026-07-28 | n/a |
 
-## Open source launch IPs
+## Deferred / Closed
 
-All part of the [launch program](oss-launch-program.md). The **RTK flag** column marks dependence on the `@terreno/rtk` → `@terreno/syncdb` migration in PR #869: `None` is safe to implement now, `Partial` has some blocked tasks, `Blocked` cannot start until #869 merges.
+*(Plans parked or superseded.)*
 
-### Wave 0 — unblocked
+## Backlog
 
-| Plan | Status | RTK flag | Tasks |
-|------|--------|----------|-------|
+*(Links to ideas not yet promoted to a full IP.)*
+
+| Idea | Notes |
+|------|-------|
+| [Langfuse integration](terreno-langfuse-integration.md) | AI observability plugin |
+| [modelRouter MCP tools](model-router-mcp.md) | MCP surface for consumer app APIs |
+| [Offline mode](offline-mode.md) | Superseded in large part by [syncdb](syncdb-local-first.md) — confirm and close |
+| [modelRouter actions](model-router-actions.md) | — |
+| [B2B platform](b2b-platform-program.md) | Draft — decisions D1–D7 resolved | 2026-08-09 | 10 written (+ [rbac-permissions](rbac-permissions.md)); 30 roadmap items seeded |
+| [RBAC Permissions](rbac-permissions.md) | Draft (API design) | 2026-07-08 | TBD |
+| [SyncDB Local-First Data Layer](syncdb-local-first.md) | In progress ([PR #869](https://github.com/flourishhealth/terreno/pull/869)) | 2026-07-13 | [tasks](../tasks/syncdb-local-first.md) |
+| [MCP Boost parity](mcp-boost-parity.md) | In progress ([PR #802](https://github.com/flourishhealth/terreno/pull/802)) | 2026-06-21 | TBD |
+| [Infrastructure MCP server](infra-mcp.md) | Draft — blocked on [RBAC](rbac-permissions.md) | 2026-08-09 | [tasks](../tasks/infra-mcp.md) |
 | [OSS governance baseline](oss-governance-baseline.md) | Draft | None | [tasks](../tasks/oss-governance-baseline.md) |
 | [Public roadmap on GitHub](public-roadmap-github.md) | Draft | None | [tasks](../tasks/public-roadmap-github.md) |
 | [Deploy to GCP (generalized)](deploy-to-gcp.md) | Draft | None | [tasks](../tasks/deploy-to-gcp.md) |
 | [Agentic SDLC plugin (`/terreno-*`)](agentic-sdlc-plugin.md) | Draft | Partial | [tasks](../tasks/agentic-sdlc-plugin.md) |
-
-### Wave 1 — gated on PR #869
-
-| Plan | Status | RTK flag | Tasks |
-|------|--------|----------|-------|
 | [RTK deprecation and syncdb migration docs](rtk-to-syncdb-migration-docs.md) | Draft | **Blocked** (gating IP) | [tasks](../tasks/rtk-to-syncdb-migration-docs.md) |
 | [Positioning — Django/Rails for TypeScript](positioning-django-rails-universal.md) | Draft | Partial | [tasks](../tasks/positioning-django-rails-universal.md) |
 | [Reference documentation coverage](docs-reference-coverage.md) | Draft | Blocked | [tasks](../tasks/docs-reference-coverage.md) |
@@ -48,48 +60,14 @@ All part of the [launch program](oss-launch-program.md). The **RTK flag** column
 | [The AI development loop (Boost)](ai-dev-loop-boost.md) | Draft | Partial | [tasks](../tasks/ai-dev-loop-boost.md) |
 | [Dogfooding run and launch blog post](build-terreno-app-validation.md) | Draft | Blocked | [tasks](../tasks/build-terreno-app-validation.md) |
 | [Examples, demo, and test coverage](examples-demo-coverage.md) | Draft | Partial | [tasks](../tasks/examples-demo-coverage.md) |
-
-### Wave 2 — independent
-
-| Plan | Status | RTK flag | Tasks |
-|------|--------|----------|-------|
 | [Web SSR and admin SPA](web-ssr-and-admin-spa.md) | Draft | Partial | [tasks](../tasks/web-ssr-and-admin-spa.md) |
-
-## B2B platform IPs
-
-All part of the [B2B platform program](b2b-platform-program.md). Roadmap items for the
-full program (including items whose IPs are pending decisions D1–D4) are seeded in
-[roadmap-seed-issues.md](../explanation/roadmap-seed-issues.md).
-
-| Plan | Status | RTK flag | Tasks |
-|------|--------|----------|-------|
 | [Pluggable communications layer (@terreno/comms)](comms-abstraction.md) | Draft | None | [tasks](../tasks/comms-abstraction.md) |
 | [Comms adapter — Expo push](comms-adapter-expo-push.md) | Draft | None | [tasks](../tasks/comms-adapter-expo-push.md) |
 | [Comms adapter — Twilio SMS](comms-adapter-twilio-sms.md) | Draft | None | [tasks](../tasks/comms-adapter-twilio-sms.md) |
 | [Comms adapter — Twilio Verify (OTP)](comms-adapter-twilio-verify.md) | Draft | None | [tasks](../tasks/comms-adapter-twilio-verify.md) |
 | [Comms adapter — SendGrid email](comms-adapter-sendgrid.md) | Draft | None | [tasks](../tasks/comms-adapter-sendgrid.md) |
+| [Comms admin dashboard (errors, retries, log digging)](comms-admin-dashboard.md) | Draft | Partial | [tasks](../tasks/comms-admin-dashboard.md) |
 | [Password reset and email verification](password-reset-and-email-verification.md) | Draft | None | [tasks](../tasks/password-reset-and-email-verification.md) |
 | [Organizations, teams, and multi-tenant scoping](orgs-and-teams.md) | Draft | None | [tasks](../tasks/orgs-and-teams.md) |
 | [Stripe billing and subscriptions](billing-stripe.md) | Draft | None | [tasks](../tasks/billing-stripe.md) |
 | [Native module baseline (next major)](native-module-baseline.md) | Draft | None | [tasks](../tasks/native-module-baseline.md) |
-
-## Completed
-
-| Plan | Status | Created | Tasks |
-|------|--------|---------|-------|
-| [APIError redesign — standards-first extension of Error](apierror-standard-error-redesign.md) | Complete | 2026-07-28 | n/a |
-
-## Deferred / Closed
-
-*(Plans parked or superseded.)*
-
-## Backlog
-
-*(Links to ideas not yet promoted to a full IP.)*
-
-| Idea | Notes |
-|------|-------|
-| [Langfuse integration](terreno-langfuse-integration.md) | AI observability plugin |
-| [modelRouter MCP tools](model-router-mcp.md) | MCP surface for consumer app APIs |
-| [Offline mode](offline-mode.md) | Superseded in large part by [syncdb](syncdb-local-first.md) — confirm and close |
-| [modelRouter actions](model-router-actions.md) | — |

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 nine IPs open
+**Status:** Draft — roadmap items drafted; decisions D1–D7 resolved 2026-08-09; first ten IPs open
 **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` (existing draft), `invitations-and-seats`, `org-management-ui` |
-| 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); consumers: `password-reset-and-email-verification`, `notification-center` |
+| 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) |
 | E | B2B UI surfaces | `data-grid-server-filters`, `charts-and-dashboards`, `dark-mode-theme`, `command-palette`, `wizard-stepper`, `wysiwyg-editor` (markdown stays for now, per D3), `global-search` |
@@ -97,6 +97,7 @@ All decisions resolved by the maintainer on 2026-08-09:
 | [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) | Draft | [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) |
 | [billing-stripe](billing-stripe.md) | Draft | [tasks](../tasks/billing-stripe.md) |