@terreno/mcp 0.24.0 → 0.25.0

package/src/docs/versioned/0.24.0/tasks/admin-ui-v2-django-parity.md

@@ -0,0 +1,135 @@
+# Task List: Admin UI v2 — Django-Parity Admin (Config-Driven Shell)
+
+*Structured task breakdown for automated implementation. Each task should be independently implementable and testable.*
+
+**Status:** All phases below are complete. See `docs/implementationPlans/admin-ui-v2-django-parity.md` for acceptance criteria (also marked complete) and verification pointers.
+
+**Companion:** **Admin script runner** — `docs/implementationPlans/admin-script-runner.md` + `docs/tasks/admin-script-runner.md` (same delivery; documents `/admin/scripts/*`, `BackgroundTask`, and UI).
+
+See: `docs/implementationPlans/admin-ui-v2-django-parity.md` for full plan.
+
+## Phase 1: Admin config contract (backend)
+
+- [x] **Task 1.1**: Extend `AdminConfigResponse` / `GET /admin/config` for schema v2  
+  - Description: Add `schemaVersion`, per-model `group`, `listDisplay`, `listDisplayLinks`, `sortableFields`, `searchFields`, `filters` (typed: boolean, choice, text, dateRange, ref), `fieldsets`, `readonlyFields`, `hiddenFields`, declared `actions` (sync vs `background: true`), `permissions` (`create`/`update`/`delete` booleans), `pageSize`, `realtime`, `home` with **`title` + `slots`** (`navGlobal?`, `contentTop?`, `main?`, `sidebar?` — each an ordered `string[]` of widget ids; Django template-block analogue). Optionally accept legacy `home.widgets[]` for migration → normalize into `slots.main` + `recentActivity` forced last in `sidebar`. Include `customScreens`, existing `scripts`. Preserve v1 config fields for backward compatibility.  
+  - Files: `admin-backend/src/adminApp.ts`, `admin-backend/src/index.ts` (exports if needed), tests under `admin-backend/src/*.test.ts`  
+  - Depends on: none  
+  - Acceptance: Typed response; tests assert v1 fields still present; new fields optional-safe for old clients.
+
+- [x] **Task 1.2**: Document OpenAPI for extended config  
+  - Description: Ensure generated OpenAPI documents the new response shape (or manual `openApiBuilder` attachment on config route if required).  
+  - Files: `admin-backend/src/adminApp.ts`  
+  - Depends on: 1.1  
+  - Acceptance: `openapi.json` from a test server includes `/admin/config` response schema additions.
+
+## Phase 2: Bulk patch + background tasks (backend)
+
+- [x] **Task 2.1**: Implement `POST {basePath}{routePath}/bulk-patch`  
+  - Description: Body `{ ids: string[]; patch: Record<string, unknown> }`. Enforce **max 1000** ids. Allowlist patch keys per model from config (or from schema paths). Use `updateMany` / batched updates with per-id validation where needed. Return `{ updated: number; failures?: ... }`.  
+  - Files: `admin-backend/src/adminApp.ts`, new helper module if >300 LOC, tests  
+  - Depends on: 1.1  
+  - Acceptance: Tests for cap, unknown keys rejected, partial failure reporting; `IsAdmin` only.
+
+- [x] **Task 2.2**: Implement `POST /admin/background-tasks` (name finalized in code)  
+  - Description: Map prototype `background: true` actions to enqueue `BackgroundTask` (or existing script runner) with `kind`, target route, ids, metadata. Return `{ taskId }`. Reuse logging/error patterns from script routes.  
+  - Files: `admin-backend/src/adminApp.ts`, tests  
+  - Depends on: 1.1, 2.1 (shared validation helpers optional)  
+  - Acceptance: Test covers enqueue + 403 non-admin; OpenAPI entry exists.
+
+## Phase 3: modelRouter metadata parity (backend / examples)
+
+- [x] **Task 3.1**: Align `modelRouter` registration options with config lists  
+  - Description: For each model exposed in `example-backend` (or chosen demo), set `queryFields`, `sort`, `defaultLimit`/`maxLimit`, `responseHandler` for hidden fields, and `permissions.delete: []` for DotPhrase-style demo.  
+  - Files: `example-backend/src/**`, any consumer `AdminApp` registration  
+  - Depends on: 1.1  
+  - Acceptance: List queries accept filters used in UI; delete disabled where specified.
+
+## Phase 4: Admin frontend — shell + navigation
+
+- [x] **Task 4.1**: Admin shell (sidebar groups, screens, tools, user footer)  
+  - Description: New layout components using `@terreno/ui`; consume config for groups and `customScreens`; support `apiBase`/`routeBase` from prior admin-spa work.  
+  - Files: `admin-frontend/src/**` (new shell module + exports in `index.tsx`)  
+  - Depends on: 1.1  
+  - Acceptance: Lint/compile; story or test renders grouped nav from mock config.
+
+- [x] **Task 4.2**: Top bar breadcrumbs + contextual actions  
+  - Description: Match prototype routes (home, list, form, tool, screen); “Add {singular}” when `permissions.create !== false`.  
+  - Files: `admin-frontend/src/**`  
+  - Depends on: 4.1  
+  - Acceptance: Unit test for breadcrumb labels from route + model meta.
+
+## Phase 5: Admin frontend — list (changelist)
+
+- [x] **Task 5.1**: List view v2 — search, filters, sort, pagination  
+  - Description: Wire `DataTable` to server sort/page; debounced search; typed filters mapped to query params; `listDisplayLinks` drives link columns; inline boolean uses PATCH.  
+  - Files: `admin-frontend/src/AdminModelTable.tsx`, hooks, types  
+  - Depends on: 1.1, 3.1, 4.1  
+  - Acceptance: Tests with MSW or harness for query serialization; loading/error/empty states.
+
+- [x] **Task 5.2**: Bulk selection + action menu  
+  - Description: Sync actions call `bulk-patch`; confirm modals for `confirm` strings; background actions call enqueue endpoint; cap selection client-side at 1000 with user-visible message.  
+  - Files: `admin-frontend/src/AdminModelTable.tsx`, possibly `AdminScriptRunModal.tsx` reuse  
+  - Depends on: 2.1, 2.2, 5.1  
+  - Acceptance: Tests for confirm + request bodies.
+
+## Phase 6: Admin frontend — form (change view)
+
+- [x] **Task 6.1**: Fieldsets + readonly + exclude/hidden fields  
+  - Description: Render `fieldsets` with `Accordion`/`Card`; readonly fields not submitted; hidden fields omitted from form and detail panels as specified.  
+  - Files: `admin-frontend/src/AdminModelForm.tsx`, types  
+  - Depends on: 1.1, 4.1  
+  - Acceptance: Test that PATCH body excludes readonly keys.
+
+- [x] **Task 6.2**: Autocomplete ref picker  
+  - Description: Debounced fetch against referenced model list endpoint; keyboard/accessibility basics.  
+  - Files: `admin-frontend/src/AdminRefField.tsx` or new component, tests  
+  - Depends on: 5.1 (shared debounce util optional)  
+  - Acceptance: Unit test uses mock list API.
+
+## Phase 7: Home dashboard widgets
+
+- [x] **Task 7.1**: Widget registry + **`home.slots`** layout  
+  - Description: Implement built-ins: `modelStats`, `modelsGrid`, `feature-flags-overrides` (or generic “quick toggles” plugin slot), `versionConfig` summary, `scriptRunner`, `recentActivity`. Render regions in order: **`navGlobal`** (horizontal strip) → **`contentTop`** (full-width above grid) → **`main` | `sidebar`** (two-column). Enforce **`recentActivity` last within `sidebar`** when present. Validate unknown widget ids in dev.  
+  - Files: `admin-frontend/src/**` (new `AdminHome.tsx` or similar), exports  
+  - Depends on: 1.1, 4.1  
+  - Acceptance: Tests: (1) `scriptRunner` only in `navGlobal` does not mount inside `main` model grid; (2) `recentActivity` is last in `sidebar` when configured.
+
+## Phase 8: admin-spa + example integration
+
+- [x] **Task 8.1**: Wire new shell + routes in `admin-spa`  
+  - Description: Routes for home v2, list, form, tools, deep links to plugin URLs for screens; regenerate admin SDK if needed.  
+  - Files: `admin-spa/app/**`, `admin-spa/store/**`  
+  - Depends on: 4.x–7.x  
+  - Acceptance: `bun run admin-spa:compile` / smoke script; manual checklist in plan.
+
+- [x] **Task 8.2**: Example-backend registration + seed  
+  - Description: Register illustrative models + `AdminApp` config entries matching v2 demo shape (subset acceptable).  
+  - Files: `example-backend/**`  
+  - Depends on: 3.1  
+  - Acceptance: Running example + admin-spa exercises list/form/home.
+
+## Phase 9 (last): Audit log + recent actions
+
+- [x] **Task 9.1**: `AdminAuditLog` model + persistence (consumer or example-backend)  
+  - Description: Schema with descriptions, indexes on `created`, `modelName`, `actorId`. Optional TTL for retention.  
+  - Files: `example-backend/src/models/**` (or consumer app), types  
+  - Depends on: 8.2 (demo path)  
+  - Acceptance: Model compiles; `checkModelsStrict` happy in non-prod.
+
+- [x] **Task 9.2**: `modelRouter` or read-only list route for audit entries  
+  - Description: `GET` list with pagination, `IsAdmin`, sort `-created`. Consider create-only via internal hooks (no public POST from browser) — prefer server-side logging middleware writing entries.  
+  - Files: `example-backend/src/api/**`, tests  
+  - Depends on: 9.1  
+  - Acceptance: supertest list route returns inserted fixture rows.
+
+- [x] **Task 9.3**: Emit audit rows from admin mutations  
+  - Description: Hook `postUpdate`/`postCreate`/`postDelete` on registered admin models or central middleware in `AdminApp` to write `AdminAuditLog` with verb + label resolution.  
+  - Files: `admin-backend/src/adminApp.ts` and/or example-backend hooks  
+  - Depends on: 9.2  
+  - Acceptance: `onAdminAudit` fires after POST/PATCH/DELETE on admin model routes — **`admin-backend/src/adminApp.models.test.ts`** (`describe("AdminApp onAdminAudit")`). Consumer persistence: `example-backend/src/server.ts` (`AdminAuditLog.create` in `onAdminAudit`).
+
+- [x] **Task 9.4**: Home `recentActivity` widget backed by API  
+  - Description: Fetch latest N audit rows; render as the **final widget in `home.slots.sidebar`**; empty/error states.  
+  - Files: `admin-frontend/src/**` (home widget), `useAdminApi` or dedicated hook  
+  - Depends on: 7.1, 9.3  
+  - Acceptance: UI or integration test shows `recentActivity` below other **sidebar** widgets when multiple sidebar ids are configured.

package/src/docs/versioned/0.24.0/tasks/feature-flags-openfeature.md

@@ -0,0 +1,77 @@
+# Feature Flags → OpenFeature — Task List
+
+See `docs/implementationPlans/feature-flags-openfeature.md` for full details.
+
+## Phase 0: Catalog & deps
+
+- [x] **0.1** Add `@openfeature/server-sdk`, `@openfeature/web-sdk`, `@openfeature/react-sdk`, `@openfeature/core` to the root `package.json` `catalog` (pin minor; check latest at time of work). Verify with `bun install` from root.
+
+## Phase 1: Backend OpenFeature integration
+
+- [x] **1.1** Add `@openfeature/server-sdk` (catalog version) to `feature-flags/package.json` dependencies. Run `bun install`.
+- [x] **1.2** Add `defaultVariant` field to `FeatureFlag` schema (`feature-flags/src/featureFlagModel.ts`) with description and validation. **No getter** — use a `pre("save")` hook that populates `defaultVariant` when undefined (boolean → "off"; variant → first variant key). Validation: if set, boolean must be `"on"`/`"off"`; variant must be one of `variants[].key`. Add `defaultVariant` to `featureFlagAdminConfig.listFields`.
+- [x] **1.3** Update `FeatureFlagDocument` type in `feature-flags/src/types.ts` with optional `defaultVariant`. Add `FlagDefinition` and `FlagConfigurationResponse` interfaces.
+- [x] **1.4** Create `feature-flags/src/openFeatureProvider.ts` exporting `MongoFeatureFlagProvider` implementing OpenFeature's `Provider` interface. Use `findOneOrNone` (per repo rule — never `findOne`). Returns `FLAG_NOT_FOUND` / `TYPE_MISMATCH` `ResolutionDetails` shapes for missing or wrong-type flags. Delegates the targeting math to existing `evaluateFlag()`.
+- [x] **1.5** Update `FeatureFlagsApp.register()` (`feature-flags/src/featureFlagsApp.ts`): construct provider, call `OpenFeature.setProvider(domain, provider)` (default domain `"feature-flags"`), register new `/flagConfiguration` route, keep `/evaluate` with `Deprecation: true` + `Sunset: <90d>` headers + one-shot warn log.
+- [x] **1.6** Add `buildFlagDefinition(flag, targetingKey, user, segments)` helper. **Critical filter**: `/flagConfiguration` matches today's `evaluateAllFlags` filter (`archived: $ne true, enabled: true`) — disabled flags are omitted entirely. Every returned `FlagDefinition` has `disabled: false`.
+- [x] **1.7** Update `FeatureFlagsOptions` type (`feature-flags/src/types.ts`) to add `liveUpdates` and `openFeatureDomain` fields.
+- [x] **1.8** Update `feature-flags/src/index.ts` to export `MongoFeatureFlagProvider`, `FlagDefinition`, `FlagConfigurationResponse`.
+- [x] **1.9** Add `feature-flags/src/tests/openFeatureProvider.test.ts` covering: boolean and variant resolution; disabled flag returns default + reason "DISABLED"; `TYPE_MISMATCH` on wrong-type call; `FLAG_NOT_FOUND` on missing flag; rule-match path; segment-match path; deterministic-hash path; missing `targetingKey`; variant default fallback; `resolveNumberEvaluation` and `resolveObjectEvaluation` return `FLAG_NOT_FOUND`.
+- [x] **1.10** Extend `feature-flags/src/tests/featureFlagsApp.test.ts`: `/flagConfiguration` returns the right shape for both flag types; **explicitly verifies disabled flags are OMITTED**; verifies `defaultVariant` flows through; verifies `/evaluate` still works AND now includes `Deprecation` + `Sunset` headers. Add `featureFlagModel.test.ts` (or extend existing tests) with: legacy doc (no `defaultVariant`) can be saved and the hook populates a default; explicit `defaultVariant: "on"` on boolean passes; `defaultVariant: "bad"` on boolean is rejected.
+- [x] **1.11** Run `bun run --filter=@terreno/feature-flags compile test lint`. Fix issues.
+
+## Phase 2: Frontend OpenFeature integration
+
+- [x] **2.0 (blocking spike)** Verify `@openfeature/react-sdk` works under React Native. Write a tiny `bun test` using `@testing-library/react-native` that wraps a component in `<OpenFeatureProvider>` with a `TypedInMemoryProvider` and asserts `useBooleanFlagValue("k", false)` returns `true` after `PROVIDER_READY`. If it fails on RN, fall back to importing only from `@openfeature/web-sdk` and writing a thin React adapter inside `@terreno/rtk` that uses `useSyncExternalStore` against the OF client's event emitter. Do not proceed to 2.1 until this is green.
+- [x] **2.1** Add `@openfeature/web-sdk` + `@openfeature/react-sdk` as **peerDependencies** (NOT direct deps) in `rtk/package.json`. Add `@openfeature/core` as a direct dep for types. Run `bun install` from root.
+- [x] **2.2** Create `rtk/src/useTerrenoFeatureFlags.ts`. Critical behaviors:
+  - RTK Query endpoint cache key includes `userId` so user switching invalidates cache.
+  - On data success, `await OpenFeature.setProvider(domain, new TypedInMemoryProvider(data))`; subscribe to `PROVIDER_READY` via `client.addHandler`.
+  - `isLoading` stays `true` until BOTH RTK has data AND `PROVIDER_READY` has fired (gated by a ref-tracked boolean).
+  - On `userId` change: `OpenFeature.setContext(domain, {targetingKey: userId})` BEFORE the refetch resolves.
+  - Module-level ref counter for provider lifetime; do not clear provider on individual unmount; clear only when count returns to zero (last consumer leaves).
+  - StrictMode safety: ref tracks in-flight `setProvider` promise to dedupe double-effect.
+  - If `options.socket` is provided, subscribe to `socketEventName ?? "featureFlagsChanged"` → `refetch()`. Cleanup on unmount.
+  - Return `{flags, isLoading, error, refetch, client}`.
+- [x] **2.3** Rewrite `rtk/src/useFeatureFlags.ts` as a BC wrapper over `useTerrenoFeatureFlags`. Preserve overloaded signature (`string | UseFeatureFlagsOptions`). `getFlag` uses `client.getBooleanValue(key, false)`. `getVariant` returns `null` when `!flags[key]` (the flag is disabled/missing — disabled flags are filtered out of `/flagConfiguration`); otherwise returns `client.getStringValue(key, "") || null`. Build `flatFlags: Record<string, boolean | string | null>` from the raw `FlagConfiguration` map by projecting each `FlagDefinition`: boolean → `variants[defaultVariant]`, variant → `defaultVariant`. Add explicit type tests.
+- [x] **2.4** Update `rtk/src/index.ts` to export `useTerrenoFeatureFlags` and its types. Do **not** re-export OpenFeature hooks (consumers add `@openfeature/react-sdk` directly).
+- [x] **2.5** Update `rtk/src/useFeatureFlags.test.ts` to match the new wire shape. Cover: legacy options shape (string), modern options shape (object), `skip`, `getFlag`/`getVariant` for boolean and variant flags, `null` on disabled/missing, timing logs preserved, **snapshot test** locking the `flatFlags` projection so `profile.tsx`'s render output is byte-identical to before.
+- [x] **2.6** Add `rtk/src/useTerrenoFeatureFlags.test.ts` covering: provider is set on success; `isLoading` stays `true` until `PROVIDER_READY`; domain isolation (default provider not affected); refetch path; no-op when `skip: true`; `userId` change triggers context + refetch + provider replacement; StrictMode double-mount does not double-set provider; ref count prevents premature provider clearing; socket event triggers refetch.
+- [x] **2.7** Run `bun run --filter=@terreno/rtk compile test lint`. Fix issues.
+
+## Phase 3: Live updates (opt-in)
+
+- [x] **3.1** In `FeatureFlagsApp.register()`, when `options.liveUpdates?.socketIoServer` is provided (accept either a value or a `() => Server | null` getter — example-backend's `io` is lazily initialized), start `FeatureFlag.watch([], {fullDocument: "updateLookup"})`. On each change, emit `featureFlagsChanged` (configurable event name) plus call `provider.emitConfigurationChanged()`. Log on stream `error`; one auto-reconnect attempt, then disable + warn.
+- [x] **3.2** Add `feature-flags/src/tests/featureFlagsApp.liveUpdates.test.ts`. Test approach: **mock `FeatureFlag.watch`** to return a fake `EventEmitter` with the change-stream interface (`on`, `close`). The tests do NOT spin up a replica-set Mongo. Cover: emission on insert/update/delete (via emitting fake change events), custom event name, error handler logs a warn, double-error disables the stream.
+- [x] **3.3** In `useTerrenoFeatureFlags`, when `options.socket` is provided, subscribe to `options.socketEventName ?? "featureFlagsChanged"` and call `refetch()` on each event. Cleanup on unmount. Acknowledge that the emit is global broadcast (all connected clients) — no PII in the payload.
+- [x] **3.4** Add a test in `useTerrenoFeatureFlags.test.ts` proving: when a fake `EventEmitter` socket emits the event, the hook refetches and OF consumers re-render.
+- [x] **3.5** Document the Mongoose replica-set requirement (production must use a replica set, including single-node replica set) and Socket.io wiring in `docs/how-to/add-feature-flags.md` (new "Live updates" section). Also document the broadcast scope (flag-key payload visible to every authenticated socket) — acceptable since flag keys ship to every authed client via `/flagConfiguration` anyway.
+
+## Phase 4: Example apps + docs + SDK regen
+
+- [x] **4.1** Update `example-backend` `FeatureFlagsApp` construction to pass `liveUpdates: {socketIoServer: () => io}` — use a getter, since `example-backend/src/websockets.ts:24` initializes `io` lazily during `connectToWebsockets`.
+- [x] **4.2** Update `example-backend/src/scripts/seed-feature-flags.ts`: add `defaultVariant` to each `SEED_FLAGS` entry (`"off"` for boolean flags; for the `profile-layout` variant flag, `"compact"`). **Bump the seed**: either add a `seedVersion` field to FeatureFlag (skip if too invasive) OR add an idempotent "patch missing defaultVariant" upsert at the top of the script that updates existing docs in dev DBs to populate the new field. Document the dev-db backfill in the migration note.
+- [x] **4.3** Update `example-frontend/app/_layout.tsx` to wrap children in `<OpenFeatureProvider domain="feature-flags">` and call `useTerrenoFeatureFlags(terrenoApi, {socket, userId})` once user is authenticated.
+- [x] **4.4** Update `example-frontend/app/(tabs)/profile.tsx`: add a small section that uses `useBooleanFlagDetails("dark-mode-toggle", false)` and renders `reason` alongside value — verifies OF metadata is plumbed through and proves the `reason` field shape downstream.
+- [x] **4.5** Add `example-frontend/types/openfeature.d.ts` demonstrating the type-safe flag keys augmentation. Reference it from the docs.
+- [ ] **4.6** Regenerate frontend SDK: `cd example-frontend && bun run sdk`. Verify the new endpoint is in `openApiSdk.ts` and document that consumers should NOT call the generated hook directly; use `useTerrenoFeatureFlags`/`useFeatureFlags` instead.
+- [x] **4.7** Update `docs/reference/feature-flags.md`: new endpoint shape, `MongoFeatureFlagProvider` export, `defaultVariant` field semantics, recommended OF hooks for new code, BC notes, **number/object flag types not supported** (always returns default), **type-safe flag keys drift warning**, dev-db backfill note for existing seeded flags.
+- [x] **4.8** Update `docs/how-to/add-feature-flags.md`: recommend OF hooks for new code; show `useFeatureFlags` only in a "BC / migration" section.
+- [x] **4.9** Add a short note at the top of `docs/implementationPlans/feature-flags.md` linking to this new IP.
+- [x] **4.10** Add `example-frontend/e2e/feature-flags.spec.ts` Playwright test:
+  - Login as admin
+  - PATCH a flag via `/feature-flags/flags/:id` (e.g., toggle `enabled` on `todo-summary-card`)
+  - Within ~5s, assert the example-frontend's todos screen shows/hides the summary card accordingly **without** a page reload
+  - Verifies the full live-update loop (change stream → socket emit → hook refetch → OF re-render)
+  - Skip the test if the test environment does not have a Mongo replica set (use `test.skip` with a clear message) so CI doesn't fail when devs run without one.
+- [ ] **4.11** Run full workspace check: `bun run lint && bun run compile && bun run test`. Run example stack manually (`bun run backend:dev` + `bun run frontend:web`) and verify the profile screen shows flags identical to before.
+
+## Definition of Done
+
+- All workspace tests pass.
+- `example-frontend` runs end-to-end with seeded flags, showing identical values to before the migration.
+- Admin edits to a flag (via the admin panel) propagate to an open example-frontend session within ~1 second without a manual refresh.
+- A consumer using only `useFeatureFlags(api)` requires zero code changes.
+- A consumer can now also use `useBooleanFlagValue("key", false)` directly from `@openfeature/react-sdk`.
+- Type-safe flag keys augmentation is documented and demonstrated in `example-frontend`.
+- The legacy `/evaluate` endpoint still works, returns the old shape, and includes a `Deprecation` header.

package/src/docs/versioned/0.24.0/tasks/syncdb-local-first.md

@@ -0,0 +1,117 @@
+# Task List: SyncDB Local-First Data Layer
+
+*Structured task breakdown for automated implementation. Each task should be independently implementable and testable.*
+
+## Phase 1: Foundation
+
+- [ ] **Task 1.1**: Scaffold `@terreno/syncdb` package
+  - Description: Create the package with core entrypoints, lifecycle interfaces, and typed configuration.
+  - Files: `syncdb/package.json` (new), `syncdb/src/index.ts` (new), `syncdb/src/types.ts` (new), `syncdb/README.md` (new)
+  - Depends on: none
+  - Acceptance: package compiles and exports `createSyncDbClient` and configuration types.
+
+- [ ] **Task 1.2**: Define storage and sync contracts
+  - Description: Add canonical interfaces for entities, outbox records, sync cursors, conflicts, and keyring entries.
+  - Files: `syncdb/src/storage/types.ts` (new), `syncdb/src/sync/types.ts` (new), `syncdb/src/crypto/types.ts` (new)
+  - Depends on: Task 1.1
+  - Acceptance: type checks enforce required fields and operations.
+
+## Phase 2: Local DB and Encryption
+
+- [ ] **Task 2.1**: Implement IndexedDB adapter with migrations
+  - Description: Add object stores for entities/outbox/cursors/conflicts/keyring and schema version migration support.
+  - Files: `syncdb/src/storage/indexedDb.ts` (new), `syncdb/src/storage/migrations.ts` (new), `syncdb/src/storage/indexedDb.test.ts` (new)
+  - Depends on: Task 1.2
+  - Acceptance: storage CRUD + migration tests pass.
+
+- [ ] **Task 2.2**: Implement key manager (Web Crypto)
+  - Description: Add DEK generation + wrap/unwrap logic and persistence integration.
+  - Files: `syncdb/src/crypto/keyManager.ts` (new), `syncdb/src/crypto/keyManager.test.ts` (new)
+  - Depends on: Task 1.2
+  - Acceptance: key lifecycle tests pass for generate/wrap/unwrap/reload.
+
+- [ ] **Task 2.3**: Encrypt IndexedDB payloads at rest
+  - Description: Add AES-GCM envelope encryption/decryption and integrate in storage read/write paths.
+  - Files: `syncdb/src/crypto/envelope.ts` (new), `syncdb/src/storage/secureStorage.ts` (new), `syncdb/src/crypto/envelope.test.ts` (new)
+  - Depends on: Task 2.1, Task 2.2
+  - Acceptance: tests verify no plaintext persistence and successful decrypt roundtrip.
+
+## Phase 3: Local Mutation Engine
+
+- [ ] **Task 3.1**: Add optimistic local mutation application
+  - Description: Apply local patches immediately and retain inverse patches for rollback.
+  - Files: `syncdb/src/mutations/optimistic.ts` (new), `syncdb/src/mutations/optimistic.test.ts` (new)
+  - Depends on: Task 2.3
+  - Acceptance: immediate local apply and rollback tests pass.
+
+- [ ] **Task 3.2**: Implement durable outbox state machine
+  - Description: Persist queued mutations and manage transitions `queued -> inFlight -> acked/conflicted/failed`.
+  - Files: `syncdb/src/mutations/outbox.ts` (new), `syncdb/src/mutations/outbox.test.ts` (new)
+  - Depends on: Task 3.1
+  - Acceptance: replay transition and retry logic tests pass.
+
+- [ ] **Task 3.3**: Implement conflict capture and resolution
+  - Description: Persist conflict records and support `useServer` and `keepMine` resolution paths.
+  - Files: `syncdb/src/mutations/conflicts.ts` (new), `syncdb/src/mutations/conflicts.test.ts` (new)
+  - Depends on: Task 3.2
+  - Acceptance: both resolution strategies correctly update local state and queue state.
+
+## Phase 4: Websocket Delta Sync
+
+- [ ] **Task 4.1**: Build sync transport client
+  - Description: Add websocket connect/auth/reconnect lifecycle and sync event channel handling.
+  - Files: `syncdb/src/sync/transport.ts` (new), `syncdb/src/sync/transport.test.ts` (new)
+  - Depends on: Task 1.2
+  - Acceptance: transport lifecycle tests pass including reconnect behavior.
+
+- [ ] **Task 4.2**: Implement cursor-aware delta applier
+  - Description: Apply deltas idempotently with monotonic cursor checks and gap handling.
+  - Files: `syncdb/src/sync/deltaApplier.ts` (new), `syncdb/src/sync/deltaApplier.test.ts` (new)
+  - Depends on: Task 2.3, Task 4.1
+  - Acceptance: ordered delta tests pass; duplicate/out-of-order deltas are safely handled.
+
+- [ ] **Task 4.3**: Wire ack/nack replay coordinator
+  - Description: Connect outbox replay to server ack/nack responses and conflict creation.
+  - Files: `syncdb/src/sync/replayCoordinator.ts` (new), `syncdb/src/sync/replayCoordinator.test.ts` (new)
+  - Depends on: Task 3.3, Task 4.2
+  - Acceptance: ack finalizes queued mutations; nack creates conflict records.
+
+## Phase 5: App Integration and Migration Bridge
+
+- [ ] **Task 5.1**: Implement React hooks and provider
+  - Description: Add `useEntity`, `useQuery`, `useMutation`, `useSyncStatus`, and context provider wiring.
+  - Files: `syncdb/src/react/provider.tsx` (new), `syncdb/src/react/hooks.ts` (new), `syncdb/src/react/hooks.test.tsx` (new)
+  - Depends on: Task 3.3, Task 4.3
+  - Acceptance: hooks update on local mutations and remote deltas.
+
+- [ ] **Task 5.2**: Add Redux migration bridge
+  - Description: Provide optional adapter for Redux-based consumers transitioning from `@terreno/rtk`.
+  - Files: `syncdb/src/bridge/reduxBridge.ts` (new), `syncdb/src/bridge/reduxBridge.test.ts` (new)
+  - Depends on: Task 5.1
+  - Acceptance: bridge supports selector and dispatch-driven mutation usage.
+
+- [ ] **Task 5.3**: Integrate `example-frontend` todos behind `USE_SYNCDB`
+  - Description: Switch todos flow to syncdb under a feature flag while keeping legacy path available.
+  - Files: `example-frontend/store/index.ts`, `example-frontend/store/sdk.ts`, `example-frontend/app/(tabs)/index.tsx`, `example-frontend/app/_layout.tsx`
+  - Depends on: Task 5.1, Task 5.2
+  - Acceptance: flagged path supports offline local create/update/delete and sync reconciliation.
+
+## Phase 6: Codegen and Validation
+
+- [ ] **Task 6.1**: Prototype `@terreno/syncdb-codegen`
+  - Description: Create codegen package that emits typed syncdb operation descriptors from OpenAPI.
+  - Files: `syncdb-codegen/package.json` (new), `syncdb-codegen/src/index.ts` (new), `syncdb-codegen/src/*.test.ts` (new)
+  - Depends on: Task 1.1
+  - Acceptance: generator produces valid descriptors for one sample domain.
+
+- [ ] **Task 6.2**: Author migration docs
+  - Description: Document migration path from `@terreno/rtk` to `@terreno/syncdb` and rollout strategy.
+  - Files: `syncdb/README.md`, `docs/implementationPlans/syncdb-local-first.md`
+  - Depends on: Task 5.3
+  - Acceptance: docs include setup, API usage, and feature-flag rollout playbook.
+
+- [ ] **Task 6.3**: Run validation suite
+  - Description: Execute compile, lint, and tests for touched packages and resolve regressions.
+  - Files: as needed in touched packages
+  - Depends on: Task 6.2
+  - Acceptance: relevant compile/lint/test commands pass with no blockers.

package/src/docs/versioned/next/how-to/README.md

@@ -8,6 +8,7 @@ Problem-oriented, practical steps. Use these when you know what you want to do.
 - [Add GitHub OAuth authentication](add-github-oauth.md) — Enable GitHub login for your API
 - [Configure Better Auth](configure-better-auth.md) — Set up Better Auth with social OAuth (Google, GitHub, Apple)
 - [Add WebSocket integration](websocket-integration.md) — Set up real-time Socket.io connections
+- [Call external APIs](call-external-apis.md) — Authenticated HTTP client, retries, and error normalization for third-party integrations
 - [Deploy to Google Cloud Platform](deploy-to-gcp.md) — Deploy demo and example apps to GCS with CDN
 
 ## Coming Soon

package/src/docs/versioned/next/how-to/call-external-apis.md

@@ -0,0 +1,101 @@
+# Call external APIs
+
+How to talk to third-party HTTP APIs (payment processors, health integrations, meeting providers, etc.) from a `@terreno/api` backend using the shared HTTP client utilities, instead of hand-rolling axios setup, token caching, retry, and error handling per integration.
+
+## When to use each piece
+
+| You are... | Use |
+|---|---|
+| Calling a third-party REST API that needs a bearer token, OAuth2 client-credentials, or API-key auth | `createAuthenticatedClient` |
+| Calling an external service through its own SDK (Twilio, Google APIs, Stripe) | `withApiErrorHandling` around the SDK calls — the SDK owns transport, you standardize failures |
+| Logging or classifying a caught error from any external call | `normalizeApiError` |
+| Surfacing an external failure to your API's consumers from a route handler | `withApiErrorHandling` with `rethrowAs: "apiError"` |
+| Making internal requests to your own `@terreno/api` backend | None of these — use `@terreno/rtk` on the frontend or direct function calls on the backend |
+
+**Rule of thumb:** any file that would otherwise contain `axios.create(...)` plus a token variable plus a `try/catch → axios.isAxiosError → log → throw` block should use these utilities instead.
+
+## Create a client
+
+```typescript
+import {createAuthenticatedClient} from "@terreno/api";
+
+const widgetApi = createAuthenticatedClient({
+  apiName: "widgetService", // used in logs and normalized errors; defaults to baseURL
+  auth: {
+    credentials: {clientId: process.env.WIDGET_CLIENT_ID!, clientSecret: process.env.WIDGET_CLIENT_SECRET!},
+    refreshOn401: true,
+    tokenUrl: "https://api.widgets.example/oauth/token",
+    type: "oauth2",
+  },
+  baseURL: "https://api.widgets.example/v2",
+});
+
+const response = await widgetApi.axios.get("/widgets/123");
+```
+
+Auth strategies:
+
+- `{type: "bearer", getToken}` — you supply an async token fetcher; the client caches the result until `invalidateToken()` is called.
+- `{type: "oauth2", tokenUrl, credentials, refreshOn401}` — the client performs the client-credentials grant itself (HTTP Basic auth, form-encoded). With `refreshOn401: true`, a 401 response invalidates the cached token and retries the request exactly once with a fresh one.
+- `{type: "apiKey", header, getKey}` — the key is sent on the header you name.
+
+Tokens are fetched lazily and concurrent first requests share a single fetch. Create the client once per service at module scope — not per request — so the token cache is actually shared.
+
+## What you get for free
+
+- **Retry with backoff** for transient failures (429 rate limits, 5xx, network errors), honoring `Retry-After`, capped by `maxDelayMs`. Defaults: 3 total attempts, 250ms base delay, 30s delay ceiling — override via the `retry` option.
+- **Idempotency safety**: only GET/HEAD/OPTIONS are retried by default. Retrying a failed POST can duplicate side effects (a payment, a prescription, a meeting). If a specific POST/PUT/DELETE is genuinely safe to repeat, opt it in per request:
+
+  ```typescript
+  import {markRetryUnsafe} from "@terreno/api";
+
+  // Safe to repeat: the upstream endpoint is idempotent on externalId.
+  await widgetApi.axios.post("/widgets", {externalId, name}, markRetryUnsafe());
+  ```
+
+  The request body must be replayable — JSON is fine; streams/FormData are consumed on first send.
+- **Quiet transport logging**: the client logs retries and token refreshes at debug level only and always rejects with the original axios error. Error-level logging belongs to the call site (next section) so composed usage logs each failure exactly once.
+
+## Handle failures at the call site
+
+Wrap calls with `withApiErrorHandling` to normalize, log once, and rethrow:
+
+```typescript
+import {withApiErrorHandling} from "@terreno/api";
+
+export const getWidget = async (id: string): Promise<Widget> => {
+  const response = await withApiErrorHandling(() => widgetApi.axios.get(`/widgets/${id}`), {
+    apiName: "widgetService",
+    operation: "getWidget",
+  });
+  return response.data;
+};
+```
+
+- Default (`rethrowAs: "raw"`): logs the normalized shape (status code, classification, extracted messages) and rethrows the original error for callers that need it.
+- `rethrowAs: "apiError"`: throws a terreno `APIError` (stable title, per-occurrence `detail`) so route handlers surface a clean JSONAPI error instead of a raw axios failure. In this mode the `APIError` constructor does the logging.
+
+For SDK-based integrations where `createAuthenticatedClient` doesn't apply, `withApiErrorHandling` still works — `normalizeApiError` classifies non-axios errors as `"unknown"` while preserving the message.
+
+## Sensitive response data
+
+`normalizeApiError` never logs raw payload bodies: it extracts only recognized message fields (`{message}`, JSONAPI `{errors: [{title, detail}]}`, plain strings truncated to 500 chars). If the upstream service puts sensitive data *inside* those message fields, supply a `redactError` hook (available on both `createAuthenticatedClient` and `withApiErrorHandling`):
+
+```typescript
+redactError: (normalized) => ({
+  ...normalized,
+  messages: normalized.messages.map((message) => message.replace(PATIENT_ID_PATTERN, "[redacted]")),
+}),
+```
+
+Note the hook's output classification also feeds the client's retry decision — redact messages, don't rewrite classifications, unless changing retry behavior is intended.
+
+## When not to use this
+
+- **Your own backend's routes** — use the generated `@terreno/rtk` SDK (frontend) or call the function directly (backend).
+- **SDK-managed transport** (Twilio, googleapis) — don't fight the SDK's HTTP layer; adopt only `normalizeApiError`/`withApiErrorHandling` for consistent failure handling.
+- **Webhook notifiers** — `sendSlackMessage`/`sendGoogleChatMessage`/`sendZoomMessage` already exist; see [Webhooks & Notifications](../reference/api.md#webhooks--notifications).
+
+## Related
+
+- [@terreno/api reference — HTTP Client](../reference/api.md#http-client)

package/src/docs/versioned/next/reference/api.md

@@ -13,6 +13,7 @@ REST API framework built on Express and Mongoose. Provides modelRouter (CRUD end
 - [Logging & Tracing](#logging--tracing)
 - [Extensibility](#extensibility)
 - [Webhooks & Notifications](#webhooks--notifications)
+- [HTTP Client](#http-client)
 - [Utilities](#utilities)
 - [Script Helpers](#script-helpers)
 
@@ -29,6 +30,7 @@ REST API framework built on Express and Mongoose. Provides modelRouter (CRUD end
 - Middleware: `openApiEtagMiddleware`, `sentryAppVersionMiddleware`
 - Extensibility: `TerrenoPlugin` interface
 - Notifiers: `sendSlackMessage`, `sendGoogleChatMessage`, `sendZoomMessage`
+- HTTP client: `createAuthenticatedClient`, `withApiErrorHandling`, `normalizeApiError`, `markRetryUnsafe`
 
 ## Server Setup
 
@@ -970,6 +972,75 @@ await sendZoomMessage({
 - Deployment confirmations
 - Health check failures
 
+## HTTP Client
+
+Utilities for calling **external** third-party APIs with consistent auth, retry, and error handling. See the how-to guide: [Call external APIs](../how-to/call-external-apis.md).
+
+### createAuthenticatedClient
+
+Axios instance factory with a pluggable auth strategy, lazy token caching, and a retry policy for transient failures.
+
+``````typescript
+import {createAuthenticatedClient} from "@terreno/api";
+
+const client = createAuthenticatedClient({
+  apiName: "widgetService",
+  auth: {getToken: async () => fetchServiceToken(), type: "bearer"},
+  baseURL: "https://api.widgets.example/v2",
+  retry: {maxAttempts: 3}, // optional; shown with defaults below
+});
+
+const response = await client.axios.get("/widgets/123");
+client.invalidateToken(); // drop the cached token; next request re-authenticates
+``````
+
+**Auth strategies** (`auth` option):
+- `{type: "bearer", getToken}` — caller-supplied async token fetcher, cached until invalidated
+- `{type: "oauth2", tokenUrl, credentials, refreshOn401}` — client-credentials grant handled internally; `refreshOn401: true` refreshes and retries exactly once on a 401
+- `{type: "apiKey", header, getKey}` — key sent on the named header
+
+**Retry policy** (`retry` option, all fields optional):
+
+| Field | Default | Meaning |
+|---|---|---|
+| `maxAttempts` | `3` | Total attempts including the first request |
+| `retryOn` | `["rateLimited", "server", "network"]` | Failure classifications to retry |
+| `baseDelayMs` | `250` | Base for exponential backoff with jitter |
+| `maxDelayMs` | `30000` | Ceiling for any single delay, including `Retry-After` values |
+
+Only idempotent methods (GET/HEAD/OPTIONS) are retried by default. Opt a request in with `markRetryUnsafe(config?)` when the operation is safe to repeat and its body is replayable.
+
+**Why:** external integrations otherwise duplicate token plumbing and diverge on retry behavior; centralizing them makes rate-limit handling and credential rotation consistent, and makes non-idempotent retries an explicit, reviewable choice.
+
+### normalizeApiError
+
+Pure function converting any thrown value into a stable, log-safe shape.
+
+``````typescript
+import {normalizeApiError} from "@terreno/api";
+
+const normalized = normalizeApiError(error, {apiName: "widgetService", operation: "getWidget"});
+// {isAxios, statusCode, messages, classification, apiName, operation}
+``````
+
+`classification` is one of `"rateLimited" | "unauthorized" | "notFound" | "validation" | "server" | "network" | "unknown"`. Messages are extracted only from recognized body fields (`{message}`, JSONAPI `{errors: [{title, detail}]}`, plain strings truncated to 500 chars) — raw payload bodies never reach the normalized shape.
+
+### withApiErrorHandling
+
+Call-site wrapper: normalize → optional `redactError` hook → log exactly once → rethrow.
+
+``````typescript
+import {withApiErrorHandling} from "@terreno/api";
+
+const response = await withApiErrorHandling(() => client.axios.get(`/widgets/${id}`), {
+  apiName: "widgetService",
+  operation: "getWidget",
+  rethrowAs: "apiError", // optional; default "raw" rethrows the original error
+});
+``````
+
+With `rethrowAs: "apiError"` the failure is converted to a terreno `APIError` (stable title, per-occurrence `detail`, classification in `meta`) suitable for route handlers. Works with SDK-based integrations too — it does not require `createAuthenticatedClient`.
+
 ## Utilities
 
 ### checkModelsStrict

package/dist/docs/versioned/0.19.0/README.md

@@ -1,29 +0,0 @@
-# Terreno Documentation
-
-Documentation for the Terreno monorepo: shared packages for full-stack applications with React Native and Express/Mongoose.
-
-## Structure
-
-- **[Tutorials](tutorials/)** — Learning-oriented, hands-on lessons
-- **[How-to guides](how-to/)** — Problem-oriented, practical steps
-- **[Reference](reference/)** — Technical reference for APIs and packages
-- **[Explanation](explanation/)** — Concepts and context
-- **[Implementation Plans](implementationPlans/)** — Forward-looking plans for major features
-
-## Packages
-
-| Package | Description |
-|---------|-------------|
-| [@terreno/api](reference/api.md) | REST API framework (Express/Mongoose) |
-| [@terreno/ui](reference/ui.md) | React Native UI component library |
-| [@terreno/rtk](reference/rtk.md) | RTK Query utilities for API backends |
-| [@terreno/admin-backend](reference/admin-backend.md) | Admin panel backend plugin |
-| [@terreno/admin-frontend](reference/admin-frontend.md) | Admin panel frontend screens |
-| [@terreno/api-health](reference/api-health.md) | Health check endpoint plugin |
-| [@terreno/mcp-server](reference/mcp-server.md) | AI coding assistant integration (MCP) |
-
-## Quick links
-
-- [Getting started](tutorials/getting-started.md)
-- [AGENTS.md](../AGENTS.md) — Onboarding context for AI assistants
-- [.cursorrules](../.cursorrules) — Project and code style rules