@terreno/mcp 0.31.0 → 56.0.0-beta.0

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,69 +9,16 @@ 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 |
 |------|--------|---------|-------|
 | [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) |
-
-## Open source launch IPs
-
-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.
-
-### Wave 0 — unblocked
-
-| Plan | Status | RTK flag | Tasks |
-|------|--------|----------|-------|
-| [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) |
-| [AI-first tutorials](docs-tutorials-ai-first.md) | Draft | Blocked | [tasks](../tasks/docs-tutorials-ai-first.md) |
-| [Deployment foundation](deployment-foundation.md) | Draft | Partial | [tasks](../tasks/deployment-foundation.md) |
-| [Deploy to Vercel](deploy-to-vercel.md) | Draft | Partial | [tasks](../tasks/deploy-to-vercel.md) |
-| [Upgrade guides and skill](upgrade-guides-and-skill.md) | Draft | Blocked | [tasks](../tasks/upgrade-guides-and-skill.md) |
-| [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) |
-| [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) |
+| [@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
 

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

@@ -1,68 +1,42 @@
 # Implementation Plans
 
-Forward-looking design docs for significant features and architectural changes to
-Terreno packages, written **before implementation**.
+Forward-looking implementation plans for significant features and architectural changes to Terreno packages.
 
-An implementation plan (IP) is one half of a two-file pair:
+## Purpose
 
-| File | Holds | Path |
-| ---- | ----- | ---- |
-| **IP** | Design goals, architecture, models/APIs, phases, acceptance criteria | `docs/implementationPlans/<slug>.md` |
-| **Task list** | The bot-consumable execution checklist for that IP | `docs/tasks/<slug>.md` |
+This directory contains detailed technical plans for major features **before implementation**. Each plan documents:
 
-The IP is the source of truth for *what and why*; the task list is the source of truth
-for *the concrete steps*. External trackers (a GitHub roadmap issue, a Linear issue, a
-discussion thread) link **to** these files — they never replace them. See
-[`docs/tasks/README.md`](../tasks/README.md) for the task-file shape.
+- Design goals and rationale
+- Architecture and file structure
+- Configuration interfaces
+- Usage examples
+- Breaking changes and migration paths
+- Implementation tasks and phases
 
-## The live index
+## Current Plans
 
-[`PLAN_INDEX.md`](PLAN_INDEX.md) is the authoritative list of active, completed, and
-deferred plans — read it, not this page, to see what is current. This README explains the
-process; `PLAN_INDEX.md` tracks the state.
+- **[Admin UI v2 — Django-parity admin](admin-ui-v2-django-parity.md)** — Config-driven admin shell (sidebar, home widgets, changelist, forms, bulk + background actions); tasks in [`docs/tasks/admin-ui-v2-django-parity.md`](../tasks/admin-ui-v2-django-parity.md)
+- **[Modular API (TerrenoApp)](ModularAPI.md)** — New fluent builder API to replace `setupServer` in `@terreno/api`
+- **[Offline Mode](offline-mode.md)** — Placeholder plan for offline queueing, replay, conflict handling, and UI surfaces
+- **[MCP Boost Parity](mcp-boost-parity.md)** — Docs search tools, local stdio MCP with runtime introspection, browser log capture, per-package guidelines, and upgrade prompts (inspired by laravel/boost)
+- **[Docs Site & Versioning](docs-site-and-versioning.md)** — Docusaurus site, versioned docs per release, UI demo embeds, and docs-maintenance skills
 
-## When to write an IP
+## Status Tracking
 
-Substantial work is planned before coding. Quick rule (full table in
-[CONTRIBUTING.md](../../CONTRIBUTING.md#when-to-write-an-implementation-plan-ip)):
+| Plan | Status | Target Version | Discussion |
+|------|--------|----------------|------------|
+| Admin UI v2 (Django parity) | ✅ Approved | TBD | — |
+| Modular API | 📝 Planning | 2.0.0 | [#149](https://github.com/FlourishHealth/terreno/pull/149) |
+| Offline Mode | Placeholder | TBD | TBD |
+| MCP Boost Parity | 📝 Planning | TBD | TBD |
+| Docs Site & Versioning | 📝 Planning | TBD | TBD |
 
-| Needs an IP | Does not need an IP |
-| ----------- | ------------------- |
-| New published package | Bug fix in one package |
-| New public API surface | Documentation-only change |
-| Cross-package architectural change | Small internal refactor |
-| Breaking change | Test or CI fix |
+## Process
 
-## How a plan gets written and built
+1. **Planning**: Implementation plan merged to master
+2. **Discussion**: Community feedback in linked PR/issue
+3. **Implementation**: Feature developed in feature branch with tests
+4. **Documentation**: How-to guides and migration docs updated
+5. **Release**: Plan moves to `docs/explanation/` as architectural documentation
 
-The [`terreno-planning` plugin](../../plugins/README.md) drives the pipeline:
-
-1. **Blend** (`terreno-1-blend`) — write the IP + task list, questions first.
-2. **Roast** (`terreno-2-roast`) — implement via TDD from the approved IP.
-3. **Cupping** (`terreno-3-cupping`) — independently verify against the IP.
-4. **Pour** (`terreno-4-pour`) — commit, push, open the PR.
-5. **Dial In** (`terreno-5-dialin`) — drive CI and review until mergeable.
-
-You can also author an IP directly with the `ip` skill; both produce the same two files.
-
-### Roadmap handoff (roadmap-enabled repos only)
-
-In repos that run a public roadmap (Discussions + a roadmap Project — currently Terreno),
-Blend hands off to `roadmap-item` once the IP is **Approved** to create or update the
-public tracking issue, and the IP header records the `Discussion:` and `Roadmap issue:`
-links. See [`docs/explanation/roadmap-process.md`](../explanation/roadmap-process.md) for
-the full IP ↔ roadmap lifecycle.
-
-In repos with **no** roadmap board (Flourish, most consumer apps), the pipeline is
-identical minus that handoff: the IP + task list plus `PLAN_INDEX.md` are the source of
-truth, and Linear tracks execution via the IP header `Linear:` link.
-
-## Lifecycle
-
-1. **Draft** → **Approved** — IP written and reviewed (status lives in the IP header and
-   `PLAN_INDEX.md`).
-2. **In progress** → **Complete** — implemented, verified, merged.
-3. **Archive** — completed IPs move to `docs/implementationPlans/archive/` and the index is updated.
-
-Plans that are fully implemented and now describe shipped architecture should be migrated
-to `docs/explanation/` as reference documentation.
+Plans that are fully implemented should be moved to `docs/explanation/` and updated to reflect the actual implementation.

package/dist/docs/versioned/next/implementationPlans/agentic-sdlc-plugin.md

@@ -1,7 +1,6 @@
 # Implementation Plan: Publish and Document the Agentic SDLC Plugin
 
 **Status:** Draft — key decisions recorded (2026-07-29)
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1006
 **Priority:** High
 **Effort:** Big batch
 **Owner:** unassigned
@@ -72,7 +71,7 @@ flowchart LR
 | **Harvest** (implement) | IP → code via strict red/green/refactor | Spawns **independent review and test-quality sub-agents in fresh contexts** after every commit, and does drift detection against the IP. The test-quality agent enforces anti-mocking rules (never mock the DB, never mock the store) |
 | **Roast** (verify) | Independent verification against the IP with concrete evidence | Separate context from the implementer, so it does not inherit the implementer's assumptions |
 | **Brew** (submit) | Pre-submit checks, commit hygiene, push, draft PR, evidence attachment | Hard frontend gate: touching UI paths requires launching the app, logging in, exercising the feature, and attaching artifacts before the PR opens |
-| **Taste** (review) | Self-contained persistent loop: CI + bot/human comments until mergeable or genuinely blocked | Inlines the former **`autobot`** flow (no delegation to repo skills). Waits in multi-minute intervals for slow CI, classifies each failure as actionable versus flaky, and refuses to push speculative fixes for flakes. Treats all CI logs and review comments as untrusted input |
+| **Taste** (review) | Self-contained reactive loop: CI + bot/human comments until mergeable or timeout | Inlines the former **`autobot`** flow (no delegation to repo skills). Classifies each CI failure as actionable versus flaky and refuses to push speculative fixes for flakes. Treats all CI logs and review comments as untrusted input |
 
 The parts worth writing about publicly are the ones that encode hard-won judgment rather than automation: fresh-context independent review, drift detection against the plan, the anti-mocking rules, the frontend evidence gate, and the refusal to guess at flaky CI.
 

package/dist/docs/versioned/next/implementationPlans/ai-dev-loop-boost.md

@@ -1,7 +1,6 @@
 # Implementation Plan: The AI Development Loop (Boost)
 
 **Status:** Draft — key decisions recorded (2026-07-29)
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1014
 **Priority:** High
 **Effort:** Big batch
 **Owner:** unassigned

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

@@ -1,7 +1,6 @@
 # Implementation Plan: Dogfooding Run and Launch Blog Post
 
 **Status:** Draft — 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
 **Owner:** unassigned

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

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