@terreno/mcp 0.24.0 → 0.25.0

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

@@ -0,0 +1,591 @@
+# Implementation Plan: SyncDB Local-First Data Layer
+
+**Status:** Drafted from PRD
+**Priority:** High
+**Effort:** Large
+
+## Context
+
+`@terreno/rtk` currently provides RTK Query primitives (auth slice, base API, offline queue/middleware, realtime cache patching). The requested direction is to replace it with a local-first package where the browser-local database is the primary UI source of truth, mutations apply locally first, and server communication is asynchronous reconciliation via websocket deltas.
+
+The replacement must focus on:
+
+- local database-first reads,
+- local mutation durability and replay,
+- websocket-based delta sync,
+- encryption at rest for IndexedDB using Web Crypto,
+- no bundling/chunking optimization work in this phase.
+
+## Core Concept
+
+Build a new package, `@terreno/syncdb`, that supersedes `@terreno/rtk` for data synchronization concerns. The app reads from an encrypted local entity store (IndexedDB + in-memory cache), writes optimistically to local state and durable outbox first, and then syncs to the server over websocket/HTTP acknowledgement channels.
+
+Server remains source of truth for final validation and authorization, but **not** the source for immediate UI responsiveness.
+
+## Models
+
+No new backend Mongoose models are required in v1. Core state models are client-side storage schemas inside `@terreno/syncdb`.
+
+### Client local storage schema (IndexedDB)
+
+```typescript
+interface LocalEntityRecord {
+  key: string; // `${collection}:${id}`
+  collection: string;
+  id: string;
+  // encrypted payload envelope
+  payloadCiphertext: ArrayBuffer;
+  iv: Uint8Array;
+  keyId: string;
+  aadVersion: number;
+  updatedAt: string; // ISO from server/version metadata
+}
+
+interface LocalOutboxMutation {
+  mutationId: string;
+  collection: string;
+  operation: "create" | "update" | "delete" | "arrayPush" | "arrayUpdate" | "arrayRemove";
+  entityId?: string;
+  argsCiphertext: ArrayBuffer;
+  iv: Uint8Array;
+  keyId: string;
+  baseVersion?: string;
+  createdAt: string;
+  lastAttemptAt?: string;
+  attemptCount: number;
+  status: "queued" | "inFlight" | "acked" | "conflicted" | "failed";
+}
+
+interface SyncCursor {
+  stream: string; // e.g. collection or workspace stream
+  cursor: string; // monotonic sequence/offset from server
+  updatedAt: string;
+}
+
+interface SyncConflict {
+  conflictId: string;
+  mutationId: string;
+  collection: string;
+  entityId: string;
+  localCiphertext: ArrayBuffer;
+  serverCiphertext: ArrayBuffer;
+  iv: Uint8Array;
+  keyId: string;
+  createdAt: string;
+  dismissed: boolean;
+}
+
+interface KeyringEntry {
+  keyId: string;
+  wrappedDek: ArrayBuffer;
+  wrapAlg: "AES-KW";
+  createdAt: string;
+}
+```
+
+### In-memory runtime model
+
+- normalized entity map by `collection:id`
+- derived query subscriptions (similar to RTK query selectors, but local-first)
+- optimistic patch history for rollback/rebase on conflict
+
+## APIs
+
+### Package API surface (`@terreno/syncdb`)
+
+#### Bootstrap/configuration
+
+- `createSyncDbClient(config)` - initializes local stores, crypto, transport
+- `createSyncDbReduxBridge(client)` - optional bridge for Redux apps migrating from RTK
+- `withSyncDbProvider(...)` / hooks for React integration
+
+#### Read/query APIs
+
+- `useEntity({collection, id})`
+- `useQuery({collection, filter, sort, page})`
+- `selectEntity(state, key)` / `selectQuery(state, key)` for non-hook usage
+
+#### Mutation APIs
+
+- `useMutation({collection, operation})`
+- `client.mutate({...})` (local apply + durable outbox enqueue + async flush)
+- `resolveConflict({conflictId, strategy: "useServer" | "keepMine"})`
+
+#### Sync/transport APIs
+
+- `client.connectSync()` / `client.disconnectSync()`
+- `client.getSyncStatus()` returns online/syncing/authBlocked/conflicted/queue stats
+- `client.replayOutbox()` for manual replay triggers
+
+### Server contract requirements (existing/new endpoints/events)
+
+No new broad sync protocol backend is required to start, but these contracts must be supported:
+
+- Mutation ack/nack with stable `mutationId`
+- Delta events with monotonic cursor/sequence:
+  - `sync:delta`
+  - `sync:ack`
+  - `sync:nack`
+- Snapshot/bootstrap API for initial hydration (`since=cursor` or full snapshot)
+- Conflict responses include canonical server document/version metadata
+
+### OpenAPI/codegen direction
+
+- New generator package: `@terreno/syncdb-codegen`
+- Input remains backend OpenAPI
+- Output should generate typed syncdb query/mutation descriptors instead of RTK hooks
+
+## Notifications
+
+No push/email/SMS scope in this project.
+
+In-app sync state notifications required:
+
+- disconnected/offline state,
+- syncing queued changes,
+- auth-blocked replay,
+- unresolved conflict count.
+
+## UI
+
+`@terreno/syncdb` itself is data-layer first. Minimal reusable UI hooks/components are included:
+
+- `useSyncStatus`
+- `useConflicts`
+- optional small status helpers for banners
+
+Feature UI composition remains in consuming apps. For migration confidence, `example-frontend` should expose:
+
+- local-first todo list read from syncdb,
+- optimistic CRUD while offline,
+- conflict resolution controls.
+
+## Feature Flags & Migrations
+
+- Introduce feature flag in consumers: `USE_SYNCDB`.
+- Allow side-by-side mode:
+  - existing RTK path remains functional,
+  - syncdb path enabled per screen/domain.
+- Migration order:
+  1. todos/read-only,
+  2. todos with mutations,
+  3. additional resources.
+- No data migration on backend required for v1.
+- Client-side IndexedDB schema versioning and migration handlers required.
+
+## Activity Log & User Updates
+
+No new backend activity log behavior is required for this phase.
+
+Optional follow-up: include client-origin metadata headers (e.g., `X-Terreno-Syncdb`) on replayed mutations for observability.
+
+## Phases
+
+1. **Foundation and package scaffold**
+   - Create `@terreno/syncdb` package structure and public API skeleton.
+   - Add typed config and lifecycle primitives.
+
+2. **Local database + encryption**
+   - Implement IndexedDB adapter with encrypted entity/outbox storage.
+   - Add key management and login/logout key lifecycle.
+
+3. **Local mutation engine**
+   - Optimistic local writes, durable outbox enqueue, retry/replay orchestration.
+   - Conflict capture and resolution primitives.
+
+4. **Websocket delta sync**
+   - Handshake, cursor resume, delta apply pipeline, ack/nack integration.
+   - Reconnect handling and idempotent delta application.
+
+5. **React integration + migration bridge**
+   - Query/mutation hooks and optional Redux bridge for existing apps.
+   - Implement `example-frontend` todos flow using syncdb behind a flag.
+
+6. **Codegen replacement path**
+   - Create `@terreno/syncdb-codegen` prototype.
+   - Generate typed operation descriptors and migrate one domain.
+
+7. **Validation + docs**
+   - Unit/integration testing across crypto, storage, replay, sync ordering, and conflict scenarios.
+   - Consumer migration guide and operational playbook.
+
+## Not Included / Future Work
+
+- Bundling and chunking optimizations.
+- Service worker asset prefetch strategy.
+- Full cross-resource CRDT collaboration model.
+- Field-level/semantic conflict merge UI (beyond keep mine/use server).
+- Native mobile storage encryption strategy outside web IndexedDB.
+
+## Risks & Mitigations
+
+- **Delta ordering bugs can corrupt local state:** enforce cursor monotonicity + idempotent apply checks and reject out-of-order deltas until gap resolution.
+- **Crypto key lifecycle mistakes can cause data loss:** design explicit key versioning/rotation and recovery policy; test logout/login/rekey paths.
+- **Migration complexity across apps:** provide Redux bridge and feature-flagged incremental rollout rather than big-bang replacement.
+- **Conflict UX scope creep:** lock v1 to two conflict strategies and defer merge editor.
+- **Backend contract drift:** define strict event schemas and integration tests between client and server mock transport.
+
+## Acceptance Criteria
+
+### Feature: Local-First Todo Workflow
+
+#### AC-1: Offline create updates UI immediately and queues mutation
+**Priority:** P0
+**Screen:** Todos Screen
+**Preconditions:**
+- `USE_SYNCDB` is enabled.
+- User is authenticated.
+- Network is disabled (browser offline mode).
+
+**Steps:**
+1. Navigate to the todos tab and wait for `todos-screen-root`.
+2. Enter `Offline task` into `todos-input-title`.
+3. Tap `todos-button-save`.
+4. Observe `todos-item-offline-task` and `todos-sync-queue-count`.
+
+**Expected results:**
+- [ ] `todos-item-offline-task` is visible immediately after tapping save.
+- [ ] `todos-sync-status-offline` is visible.
+- [ ] `todos-sync-queue-count` increments by 1.
+
+**testIDs needed:** `todos-screen-root`, `todos-input-title`, `todos-button-save`, `todos-item-offline-task`, `todos-sync-status-offline`, `todos-sync-queue-count`
+
+---
+
+#### AC-2: Queued local mutations survive full page reload
+**Priority:** P0
+**Screen:** Todos Screen
+**Preconditions:**
+- AC-1 completed with at least one queued mutation.
+- Network remains disabled.
+
+**Steps:**
+1. Reload the app/browser tab.
+2. Return to todos and wait for `todos-screen-root`.
+3. Observe `todos-item-offline-task` and `todos-sync-queue-count`.
+
+**Expected results:**
+- [ ] `todos-item-offline-task` is still visible after reload.
+- [ ] `todos-sync-queue-count` remains greater than 0.
+- [ ] No login redirect occurs while session remains valid.
+
+**testIDs needed:** `todos-screen-root`, `todos-item-offline-task`, `todos-sync-queue-count`
+
+---
+
+#### AC-3: Reconnect replays outbox and clears queued state
+**Priority:** P0
+**Screen:** Todos Screen
+**Preconditions:**
+- At least one queued local mutation exists.
+- User remains authenticated.
+
+**Steps:**
+1. Re-enable network connectivity.
+2. Wait for `todos-sync-status-syncing`.
+3. Wait for `todos-sync-status-online`.
+4. Refresh the todos list using `todos-button-refresh`.
+
+**Expected results:**
+- [ ] Sync state transitions from offline/queued to syncing, then online.
+- [ ] `todos-sync-queue-count` reaches `0`.
+- [ ] `todos-item-offline-task` persists in the server-backed list after refresh.
+
+**testIDs needed:** `todos-sync-status-syncing`, `todos-sync-status-online`, `todos-sync-queue-count`, `todos-button-refresh`, `todos-item-offline-task`
+
+---
+
+### Feature: Delta Sync Integrity
+
+#### AC-4: Remote websocket delta applies once and does not duplicate rows
+**Priority:** P0
+**Screen:** Todos Screen
+**Preconditions:**
+- Two clients are logged in to the same workspace.
+- Both clients have `USE_SYNCDB` enabled and are online.
+
+**Steps:**
+1. In client A, create a todo titled `Delta task` with `todos-button-save`.
+2. In client B, wait for `todos-item-delta-task` to appear.
+3. Trigger a duplicate-delta test event (or reconnect client B to replay last cursor window).
+4. Count rows matching `todos-item-delta-task`.
+
+**Expected results:**
+- [ ] Client B shows `todos-item-delta-task` without manual refresh.
+- [ ] After duplicate/replay delta delivery, row count for `Delta task` remains exactly 1.
+- [ ] `todos-sync-cursor-state` reports no cursor gap error.
+
+**testIDs needed:** `todos-button-save`, `todos-item-delta-task`, `todos-sync-cursor-state`
+
+---
+
+### Feature: Conflict Resolution
+
+#### AC-5: Conflict creates resolvable record with keep-mine and use-server actions
+**Priority:** P1
+**Screen:** Todos Screen
+**Preconditions:**
+- Two clients edit the same todo record.
+- Server conflict contract (`409`) is enabled.
+
+**Steps:**
+1. Client A updates `todos-item-shared` title to `Mine`.
+2. Client B updates same item title to `Server`.
+3. Let client A reconnect/replay to receive conflict.
+4. In client A, open `todos-conflict-card-shared` and click `todos-conflict-action-use-server`.
+5. Repeat conflict and click `todos-conflict-action-keep-mine`.
+
+**Expected results:**
+- [ ] Conflict banner `todos-conflict-banner` appears when `409` is received.
+- [ ] Choosing `use-server` updates row text to `Server` and removes conflict card.
+- [ ] Choosing `keep-mine` retries mutation and final row text is `Mine` after replay.
+
+**testIDs needed:** `todos-item-shared`, `todos-conflict-banner`, `todos-conflict-card-shared`, `todos-conflict-action-use-server`, `todos-conflict-action-keep-mine`
+
+---
+
+### Feature: Validation and Error Handling
+
+#### AC-6: Invalid local mutation is rejected before queue insertion
+**Priority:** P1
+**Screen:** Todos Screen
+**Preconditions:**
+- User is authenticated.
+- `USE_SYNCDB` enabled.
+
+**Steps:**
+1. Clear `todos-input-title` to empty.
+2. Tap `todos-button-save`.
+3. Observe `todos-error-title-required` and `todos-sync-queue-count`.
+
+**Expected results:**
+- [ ] `todos-error-title-required` is visible.
+- [ ] No new todo row is inserted.
+- [ ] `todos-sync-queue-count` does not increment.
+
+**testIDs needed:** `todos-input-title`, `todos-button-save`, `todos-error-title-required`, `todos-sync-queue-count`
+
+---
+
+#### AC-7: Auth refresh failure pauses replay without clearing local state
+**Priority:** P1
+**Screen:** App Root / Todos Screen
+**Preconditions:**
+- Queue contains at least one pending mutation.
+- Access token is expired.
+- Refresh endpoint fails (network/server unavailable).
+
+**Steps:**
+1. Re-enable network partially so app can attempt replay while refresh endpoint fails.
+2. Wait for `app-sync-status-auth-blocked`.
+3. Inspect todos list and queued item.
+4. Restore refresh endpoint and re-authenticate if needed.
+
+**Expected results:**
+- [ ] `app-sync-status-auth-blocked` is shown.
+- [ ] Local queued items remain visible; queue is not cleared.
+- [ ] After refresh succeeds, replay resumes and queue drains.
+
+**testIDs needed:** `app-sync-status-auth-blocked`, `todos-item-offline-task`, `todos-sync-queue-count`
+
+---
+
+### Feature: Empty State and Navigation
+
+#### AC-8: Empty state renders correctly and transitions after first local create
+**Priority:** P1
+**Screen:** Todos Screen
+**Preconditions:**
+- User has zero todos.
+- `USE_SYNCDB` enabled.
+
+**Steps:**
+1. Open todos tab and wait for `todos-empty-state`.
+2. Enter `First local todo` in `todos-input-title`.
+3. Tap `todos-button-save`.
+
+**Expected results:**
+- [ ] `todos-empty-state` is visible before create.
+- [ ] `todos-empty-state` disappears after create.
+- [ ] `todos-item-first-local-todo` appears immediately.
+
+**testIDs needed:** `todos-empty-state`, `todos-input-title`, `todos-button-save`, `todos-item-first-local-todo`
+
+---
+
+#### AC-9: Sync status survives tab navigation and returns consistent state
+**Priority:** P2
+**Screen:** Tabs Navigation (Todos and Profile)
+**Preconditions:**
+- `USE_SYNCDB` enabled.
+- One queued item exists while offline.
+
+**Steps:**
+1. From todos, confirm `todos-sync-status-offline`.
+2. Navigate using `tabs-button-profile`.
+3. Navigate back using `tabs-button-todos`.
+4. Observe status and queue count again.
+
+**Expected results:**
+- [ ] Returning to todos still shows `todos-sync-status-offline`.
+- [ ] `todos-sync-queue-count` matches value before navigation.
+- [ ] No duplicate list rows appear after navigation.
+
+**testIDs needed:** `todos-sync-status-offline`, `tabs-button-profile`, `tabs-button-todos`, `todos-sync-queue-count`
+
+---
+
+### Feature: Access Isolation
+
+#### AC-10: Logout clears replay context to prevent cross-user mutation replay
+**Priority:** P1
+**Screen:** App Root / Login Screen
+**Preconditions:**
+- User A has queued offline mutations.
+- User A logs out; User B logs in on same device/browser profile.
+
+**Steps:**
+1. For User A, create queued mutation while offline.
+2. Tap `app-button-logout`.
+3. Log in as User B with `login-input-email`, `login-input-password`, `login-button-submit`.
+4. Re-enable network and open todos.
+
+**Expected results:**
+- [ ] User A queued mutations are not replayed under User B session.
+- [ ] User B sees only User B data.
+- [ ] `todos-sync-queue-count` is 0 after User B login unless User B creates new local mutations.
+
+**testIDs needed:** `app-button-logout`, `login-input-email`, `login-input-password`, `login-button-submit`, `todos-sync-queue-count`
+
+---
+
+### Coverage Notes
+
+- Happy path: AC-1, AC-2, AC-3, AC-4
+- Validation: AC-6
+- Error handling: AC-7
+- Empty states: AC-8
+- Permissions/access: AC-10
+- Navigation: AC-9
+- Data persistence: AC-2, AC-3
+- Out of scope confirmation: bundling/chunking optimization remains intentionally excluded from acceptance validation for this plan.
+
+---
+
+## Task List (Bot Consumption)
+
+*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 package entrypoints, config types, lifecycle interfaces, and baseline exports.
+  - 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 typed `createSyncDbClient` placeholder API.
+
+- [ ] **Task 1.2**: Define canonical storage and sync type contracts
+  - Description: Add interfaces for local entities, outbox mutations, sync cursor, conflicts, and keyring records.
+  - 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-only unit tests compile and enforce required fields for all persistence records.
+
+### Phase 2: Local DB + Crypto
+
+- [ ] **Task 2.1**: Implement IndexedDB adapter
+  - Description: Build object stores, schema versioning, migrations, and CRUD helpers for entities/outbox/cursors/conflicts.
+  - 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: tests verify create/read/update/delete and schema upgrade behavior.
+
+- [ ] **Task 2.2**: Implement Web Crypto key management
+  - Description: Add DEK generation, wrap/unwrap flow, and keyring persistence.
+  - Files: `syncdb/src/crypto/keyManager.ts` (new), `syncdb/src/crypto/keyManager.test.ts` (new)
+  - Depends on: Task 1.2
+  - Acceptance: tests verify deterministic decryptability with same key material and failure with wrong key.
+
+- [ ] **Task 2.3**: Encrypt/decrypt persistence envelope
+  - Description: Add AES-GCM envelope helpers and integrate with IndexedDB adapter reads/writes.
+  - Files: `syncdb/src/crypto/envelope.ts` (new), `syncdb/src/storage/secureStorage.ts` (new), tests in `syncdb/src/crypto/envelope.test.ts` (new)
+  - Depends on: Task 2.1, Task 2.2
+  - Acceptance: plaintext is never written to IndexedDB stores in tests; decrypt roundtrip passes.
+
+### Phase 3: Local Mutation Engine
+
+- [ ] **Task 3.1**: Build optimistic apply/revert pipeline
+  - Description: Add mutation planner that applies local patch and stores inverse patch for rollback.
+  - Files: `syncdb/src/mutations/optimistic.ts` (new), `syncdb/src/mutations/optimistic.test.ts` (new)
+  - Depends on: Task 2.3
+  - Acceptance: optimistic updates are immediate and reversable in unit tests.
+
+- [ ] **Task 3.2**: Durable outbox enqueue and replay state machine
+  - Description: Implement queue transitions (`queued` -> `inFlight` -> `acked/conflicted/failed`) and retry metadata.
+  - Files: `syncdb/src/mutations/outbox.ts` (new), `syncdb/src/mutations/outbox.test.ts` (new)
+  - Depends on: Task 3.1
+  - Acceptance: replay state transitions and retry counters are deterministic in tests.
+
+- [ ] **Task 3.3**: Conflict store and resolver actions
+  - Description: Persist conflict objects and implement `useServer`/`keepMine` resolution behavior.
+  - Files: `syncdb/src/mutations/conflicts.ts` (new), `syncdb/src/mutations/conflicts.test.ts` (new)
+  - Depends on: Task 3.2
+  - Acceptance: both resolution strategies update outbox/entity state as expected.
+
+### Phase 4: Websocket Delta Sync
+
+- [ ] **Task 4.1**: Implement sync transport client
+  - Description: Add websocket handshake, authentication payload, and reconnect strategy.
+  - Files: `syncdb/src/sync/transport.ts` (new), `syncdb/src/sync/transport.test.ts` (new)
+  - Depends on: Task 1.2
+  - Acceptance: transport emits lifecycle events and reconnect behavior in tests.
+
+- [ ] **Task 4.2**: Implement cursor-aware delta apply engine
+  - Description: Apply server deltas to local entities with idempotency and monotonic cursor checks.
+  - Files: `syncdb/src/sync/deltaApplier.ts` (new), `syncdb/src/sync/deltaApplier.test.ts` (new)
+  - Depends on: Task 2.3, Task 4.1
+  - Acceptance: duplicate/out-of-order deltas are safely handled; valid ordered deltas update local store.
+
+- [ ] **Task 4.3**: Wire ack/nack to outbox replay loop
+  - Description: Connect transport acknowledgements to outbox mutation completion/conflict paths.
+  - Files: `syncdb/src/sync/replayCoordinator.ts` (new), `syncdb/src/sync/replayCoordinator.test.ts` (new)
+  - Depends on: Task 3.3, Task 4.2
+  - Acceptance: ack removes queued mutation; nack creates conflict and preserves retry semantics.
+
+### Phase 5: React + Migration
+
+- [ ] **Task 5.1**: Implement React hooks API
+  - Description: Add `useEntity`, `useQuery`, `useMutation`, `useSyncStatus`, and conflict hooks.
+  - Files: `syncdb/src/react/hooks.ts` (new), `syncdb/src/react/provider.tsx` (new), `syncdb/src/react/hooks.test.tsx` (new)
+  - Depends on: Task 3.3, Task 4.3
+  - Acceptance: hooks re-render on local mutation and remote delta updates.
+
+- [ ] **Task 5.2**: Add Redux migration bridge
+  - Description: Provide optional bridge/adapters for existing Redux-based apps migrating from `@terreno/rtk`.
+  - Files: `syncdb/src/bridge/reduxBridge.ts` (new), `syncdb/src/bridge/reduxBridge.test.ts` (new)
+  - Depends on: Task 5.1
+  - Acceptance: bridge exposes selectors and dispatch-compatible mutation wrappers.
+
+- [ ] **Task 5.3**: Migrate example todos behind feature flag
+  - Description: Integrate syncdb into `example-frontend` for one domain (todos) with `USE_SYNCDB` toggle.
+  - 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: toggling flag changes data path to syncdb and preserves todo CRUD behavior.
+
+### Phase 6: Codegen + Documentation
+
+- [ ] **Task 6.1**: Prototype syncdb codegen package
+  - Description: Build `@terreno/syncdb-codegen` to emit typed operation descriptors from OpenAPI.
+  - Files: `syncdb-codegen/package.json` (new), `syncdb-codegen/src/index.ts` (new), tests under `syncdb-codegen/src/*.test.ts` (new)
+  - Depends on: Task 1.1
+  - Acceptance: generator emits descriptor file for at least one example endpoint group.
+
+- [ ] **Task 6.2**: Add consumer migration documentation
+  - Description: Document install/configuration/migration steps from `@terreno/rtk` to `@terreno/syncdb`.
+  - Files: `syncdb/README.md`, `docs/implementationPlans/syncdb-local-first.md`
+  - Depends on: Task 5.3
+  - Acceptance: docs include side-by-side migration example and rollout checklist.
+
+- [ ] **Task 6.3**: Validation suite run and stabilization
+  - Description: Run compile/lint/tests for new packages and touched example app flows, fixing regressions.
+  - Files: no dedicated source file; any fixes in touched files
+  - Depends on: Task 6.2
+  - Acceptance: relevant package compile/test/lint commands pass with documented outputs.

package/src/docs/versioned/0.24.0/reference/README.md

@@ -0,0 +1,22 @@
+# Reference
+
+Technical reference for Terreno packages and APIs. Information-oriented, precise descriptions.
+
+## Packages
+
+- [@terreno/api](api.md) — modelRouter, auth, permissions, setupServer
+- [@terreno/ui](ui.md) — Components, theming, layout
+- [@terreno/rtk](rtk.md) — Auth slice, SDK codegen, token handling
+- [@terreno/admin-backend](admin-backend.md) — Auto-generated admin CRUD endpoints
+- [@terreno/admin-frontend](admin-frontend.md) — Admin panel UI components
+- [@terreno/feature-flags](feature-flags.md) — Feature flags and A/B testing plugin
+- [@terreno/mcp](mcp-server.md) — AI coding assistant integration (MCP)
+
+## Configuration
+
+- [Environment Variables](environment-variables.md) — Complete environment variable reference for all packages
+
+## Other references
+
+- Root [package.json](https://github.com/flourishhealth/terreno/blob/master/package.json) — Workspace scripts and catalog
+- Per-package `package.json` in each package directory — Commands and dependencies