@terreno/mcp 57.1.0 → 57.2.0

package/src/docs/versioned/57.1.0/implementationPlans/rtk-to-syncdb-migration-docs.md

@@ -0,0 +1,220 @@
+# Implementation Plan: RTK Deprecation and SyncDB Migration Docs
+
+**Status:** Complete — syncdb reference, migration guide, agent surfaces, and deprecation signalling shipped on `master`
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1007
+**Priority:** Critical (gates most of Wave 1)
+**Effort:** Big batch
+**Owner:** unassigned
+**Created:** 2026-07-27
+**Program:** [OSS launch](oss-launch-program.md)
+**Depends on:** a merged `@terreno/syncdb` package. It was **not** delivered by PR #869 (closed); it lives on the **`release-56.0.0`** launch branch (`syncdb/`), so this IP is authored on and targets `release-56.0.0`, not `master`.
+**RTK deprecation flag:** **Unblocked on `release-56.0.0`** — this IP *is* the RTK deprecation. The `@terreno/syncdb` public surface is now final on `release-56.0.0` (`syncdb/src/index.ts`, `syncdb/src/react/index.ts`, `syncdb/src/testing/index.ts`); docs are written against that source.
+
+## Goal
+
+Make **Better Auth + `@terreno/syncdb`** the documented, blessed frontend platform, and give every existing `@terreno/rtk` consumer a correct, tested migration path. This is the gating IP for the launch documentation: publishing tutorials, reference docs, or a positioning rewrite against RTK Query would guarantee an immediate rewrite.
+
+Scope is documentation, deprecation signalling, and migration tooling — not syncdb feature work (that is PR #869's own scope).
+
+## Non-Goals
+
+- Implementing or changing `@terreno/syncdb` behavior.
+- Migrating internal Flourish applications (tracked separately).
+- Removing `@terreno/rtk` from the repo or unpublishing it.
+- Rewriting the tutorials themselves — that is [`docs-tutorials-ai-first`](docs-tutorials-ai-first.md), which depends on this IP.
+
+## Blocking questions
+
+**Recorded 2026-07-29** (see program [P6–P7](oss-launch-program.md#blocking-questions-program-level)).
+
+| # | Question | Decision |
+|---|----------|----------|
+| M1 | RTK support window (→ P6) | **Keep publishing with deprecation notice through the current major line; stop publishing `@terreno/rtk` in the next major** |
+| M2 | `npm deprecate` marker | **B** — mark at end of support window |
+| M3 | Auth vs data migration | **C** — Better Auth first, then syncdb |
+| M4 | `docs/reference/rtk.md` (→ P7 **A**) | **Remove from the public reference index** — no legacy reference page. Existing RTK consumers use **`docs/how-to/migrate-rtk-to-syncdb.md`** only; do not maintain a parallel RTK reference path in launch docs |
+| M5 | SDK codegen command | **A** — `bun run sdk` keeps working |
+| M6 | Codemod | **B (reaffirmed 2026-08-09)** — no migration script/codemod. Ship the *context* an AI agent needs (the syncdb reference, verified before/after pairs, and the `upgrading-terreno` skill), not a mechanical transform. See "Migration strategy" below |
+| M7 | Local-first default | **A — confirmed local-first only.** `@terreno/syncdb` has no server-first mode and no opt-in flag: the local store is the UI source of truth (`syncdb/src/index.ts:4-7`, `syncdb/README.md:3`) and `SyncDbConfig` (`syncdb/src/client.ts`) exposes no server-first option |
+
+## Architecture
+
+### Documentation surface map
+
+Every document below currently describes an RTK-shaped world and must be reconciled.
+
+| Document | Current state | Target state |
+|----------|---------------|--------------|
+| `docs/reference/rtk.md` | Primary frontend reference | **Removed from launch reference** (P7 A). Redirect to migration guide; archive pre-launch content if needed for inbound links |
+| `docs/reference/syncdb.md` | does not exist | New primary frontend data reference |
+| `docs/how-to/migrate-rtk-to-syncdb.md` | does not exist | New step-by-step migration guide |
+| `docs/explanation/local-first-data.md` | does not exist | New conceptual explainer: why local-first, what changes for the developer |
+| `docs/explanation/authentication.md` | JWT-primary | Better Auth primary, JWT documented as legacy |
+| `docs/how-to/configure-better-auth.md` | Exists, positioned as optional | Repositioned as the default auth path |
+| `docs/README.md` | Package table omits `ai`, `syncdb` | Complete package table with syncdb as the frontend data package |
+| `.rulesync/skills/generate-sdk/SKILL.md` | RTK Query codegen | syncdb descriptor codegen; RTK path kept as a legacy branch during the support window |
+| `.rulesync/rules/rtk/*` | RTK conventions for agents | New `syncdb` rules; RTK rules marked legacy |
+| `AGENTS.md`, `CLAUDE.md`, `CLAUDE-consumer.md` | "Always use generated SDK hooks" (RTK) | syncdb hooks; RTK guidance moved to a legacy note |
+| `README.md` architecture diagram | `@terreno/rtk` box | `@terreno/syncdb` box |
+| `mcp-server` resources + bootstrap templates | RTK store wiring | syncdb client wiring |
+
+### Surface map reconciliation (Task 1.2, checked against `release-56.0.0`)
+
+The pre-merge surface map above was a hypothesis. Reconciled against the merged
+`syncdb/` on `release-56.0.0`:
+
+- **Three entry points, not one:** `@terreno/syncdb` (client, protocol/status/conflict
+  types, `betterAuthAdapter`, key providers/codecs, persister factories, transports,
+  `wipeLocalData`, `generateMutationId`, `listConflicts`, `OUTBOX_TABLE`),
+  `@terreno/syncdb/react` (`SyncDbProvider`, `useSyncDbClient`, `useEntity`, `useQuery`,
+  `useEntityIds`, `useMutate`, `useSyncStatus`, `useConflicts`, `useSyncDebugLog`), and
+  `@terreno/syncdb/testing` (`createFakeTransport`).
+- **Backend surface #869's hypothesis under-specified:** `SyncApp` (`GET /sync/snapshot`,
+  `POST /sync/mutate`, `POST /sync/mutate/batch`, `GET /sync/key`, `POST /sync/entities`),
+  `RealtimeApp` (Socket.io `sync:subscribe`/`sync:mutate`/`sync:delta`/`sync:ack`/`sync:nack`/
+  `sync:mutateBatch`), the required `syncPlugin` + `isDeletedPlugin`, the `sync` modelRouter
+  config (owner/tenant/broadcast/custom scoping + `getUserScopes`/`snapshotFilter`), and
+  `ensureSyncIndexes()` plus the `SyncCounter`/`SyncMutation`/`SyncScopeMove`/`SyncKey`
+  bookkeeping models. All are documented in `docs/reference/syncdb.md`.
+- **Encryption at rest (web) is a real public surface:** AES-GCM codec, `createServerKeyProvider`
+  (default) / `createLocalKeyProvider`, `onDecryptFailure`. Documented.
+- **M5 confirmed:** `bun run sdk` still generates `store/openApiSdk.ts` for non-synced routes
+  (auth, profile, admin, AI, feature flags); synced collections use syncdb hooks instead.
+- **M7 confirmed:** local-first only (see the blocking-questions table).
+
+### Migration strategy: AI-context-first (not codemods)
+
+The migration is delivered as **context for an AI coding agent (and humans) to perform
+the migration in a specific app**, not as a script that mechanically transforms code.
+The RTK → syncdb move is not find-and-replace: writes change semantics (local-first;
+optimistic code gets *deleted*), conflicts and sync status are net-new concepts with
+app-specific UI, and auth migrates on its own schedule. Those are per-screen judgment
+calls, not blind transforms.
+
+This IP therefore ships three context artifacts and no migration script:
+
+1. **The syncdb reference** (`docs/reference/syncdb.md`) — the ground-truth API the agent
+   maps RTK calls onto.
+2. **The migration guide** (`docs/how-to/migrate-rtk-to-syncdb.md`) — organized by *what the
+   developer changes*, with **verified before/after pairs** from the real `example-frontend`
+   migration (RTK todos on `master` → `SyncTodosScreen` on `release-56.0.0`). An agent
+   generalizes far better from a correct concrete example than from prose.
+3. **The `upgrading-terreno` skill** (owned by [`upgrade-guides-and-skill`](upgrade-guides-and-skill.md))
+   — drives an agent to migrate one screen at a time behind a flag, verify, and repeat.
+
+Design rules that follow: every code sample is real and compiles against the merged
+syncdb; the guide names what to **delete** (manual optimistic updates, write spinners,
+refetch-after-mutate), not just what to add; prefer decision tables and per-step
+checklists over narrative; keep the rollout unit small (per screen). A mechanical helper
+may be added later for a narrow safe sub-step, but it is never the primary path.
+
+### The migration guide's shape
+
+The migration guide is the highest-value artifact. It must be organized by *what the developer has to change*, not by package internals:
+
+1. **Before you start** — decision table: adopt Better Auth first (M3), confirm backend version, confirm Mongo is a replica set.
+2. **Install and configure** — add `@terreno/syncdb`, create the client, wrap the app, remove the Redux store or keep it side-by-side.
+3. **Reads** — `useGetTodosQuery` → syncdb query hook. Show the same screen before and after, side by side.
+4. **Writes** — `usePostTodosMutation` → syncdb mutation. This is where behavior genuinely changes: writes land locally first, so loading states, error handling, and optimistic-update code all get simpler or get deleted. Show what to delete.
+5. **Conflicts** — new concept with no RTK equivalent. What a conflict is, when it happens, the two v1 strategies, and the minimum UI a consumer must add.
+6. **Sync status** — replacing spinner-driven UX with sync-state UX.
+7. **Auth** — JWT auth slice → Better Auth session, including token storage differences and the socket auth handshake.
+8. **Codegen** — regenerating typed operations, and what changes in the generated file.
+9. **Feature flags** — the OpenFeature provider's new data source.
+10. **Rollback** — how to go back if it goes wrong, per-screen via the `USE_SYNCDB` flag.
+11. **Checklist** — a copy-pasteable checklist for a real migration.
+
+Each step needs a working before/after code pair taken from the actual `example-frontend` migration in #869, not invented.
+
+### Deprecation signalling
+
+| Channel | Action |
+|---------|--------|
+| `docs/reference/legacy/rtk.md` | Legacy banner with the support window and end date/version |
+| `rtk/README.md` | Deprecation notice at the top linking the migration guide |
+| Root `CHANGELOG.md` | `Deprecated` entry in the release that lands #869 |
+| GitHub Discussions | Announcement post (see [`public-roadmap-github`](public-roadmap-github.md)) |
+| `mcp-server/src/docs/upgrades/<version>.md` | Upgrade note so `terreno_get_upgrade_guide` returns it |
+| `ROADMAP.md` | An item with `Impact = Breaking` and the removal target |
+| Agent rules | `.rulesync/rules/rtk/` marked legacy so agents stop generating RTK code |
+
+Agent rules matter most in practice: if the MCP server and bootstrap templates keep emitting RTK code, every AI-generated Terreno app starts on the deprecated path.
+
+## Models
+
+None.
+
+## APIs
+
+None new. This IP documents the surface #869 introduces; it must not add to it.
+
+## Notifications
+
+One Announcements discussion post at the start of the deprecation window. No in-app notifications.
+
+## UI
+
+None directly. The migration guide specifies the minimum conflict-resolution and sync-status UI a consumer must build; if `example-frontend` lacks a good reference implementation after #869, file a follow-up rather than inventing one here.
+
+## Phases
+
+1. **Reconcile with merged #869** — read the merged code, produce a verified inventory of the actual public API, and correct the surface map above. Nothing else starts until this is done.
+2. **Reference docs** — `docs/reference/syncdb.md`, move and banner `rtk.md`, update `docs/README.md`.
+3. **Migration guide** — the eleven-step guide with verified before/after pairs.
+4. **Explainers and auth repositioning** — `local-first-data.md`, rewrite `authentication.md`, reposition Better Auth.
+5. **Agent surfaces** — rules, skills, `AGENTS.md`/`CLAUDE*.md`, MCP resources and bootstrap templates.
+6. **Deprecation signalling** — READMEs, changelog, upgrade note, announcement draft, roadmap item.
+
+## Feature Flags & Migrations
+
+- `USE_SYNCDB` (introduced by #869) is the consumer-side rollout flag; the migration guide is organized around enabling it per screen.
+- No repo-side flag needed for documentation.
+- Docusaurus redirects required for every moved page (`docs/reference/rtk.md` → `docs/reference/legacy/rtk.md`).
+
+## Not Included / Future Work
+
+- Removing `@terreno/rtk` from the monorepo (end of support window, separate IP).
+- Native (iOS/Android) local storage encryption, which #869 explicitly defers.
+- Migrating Flourish's internal apps.
+- A `syncdb` performance/tuning guide.
+
+## Files to Create / Modify
+
+**Create**
+
+- `docs/reference/syncdb.md`
+- `docs/reference/legacy/rtk.md` (moved)
+- `docs/how-to/migrate-rtk-to-syncdb.md`
+- `docs/explanation/local-first-data.md`
+- `mcp-server/src/docs/upgrades/<syncdb-release-version>.md`
+- `.rulesync/rules/syncdb/00-syncdb.md`
+
+**Modify**
+
+- `docs/reference/README.md`, `docs/README.md`, `docs/how-to/README.md`
+- `docs/explanation/authentication.md`, `docs/how-to/configure-better-auth.md`
+- `README.md` (architecture diagram and package list)
+- `rtk/README.md`, `syncdb/README.md`
+- `.rulesync/rules/rtk/00-rtk.md` (legacy banner), `.rulesync/skills/generate-sdk/SKILL.md`
+- `AGENTS.md`, `CLAUDE.md`, `CLAUDE-consumer.md`
+- `mcp-server/src/docs/resources/*.md`, `mcp-server/src/docs/templates/bootstrap/**`
+- `CHANGELOG.md`
+- `website/docusaurus.config.ts` (redirects)
+
+## Task List
+
+See [`docs/tasks/rtk-to-syncdb-migration-docs.md`](../tasks/rtk-to-syncdb-migration-docs.md).
+
+## Acceptance Criteria
+
+- [x] A verified inventory of `@terreno/syncdb`'s public exports exists and every documented API appears in the merged package's `src/index.ts`.
+- [x] `docs/reference/syncdb.md` documents every exported hook, client method, and config option, with a runnable example for each.
+- [x] `docs/how-to/migrate-rtk-to-syncdb.md` covers all eleven steps, and every before/after pair compiles against the merged code.
+- [x] Following the guide, a fresh clone of `example-frontend` can be moved from the RTK path to the syncdb path with no undocumented steps.
+- [x] `docs/reference/rtk.md` no longer exists at its old path; the Legacy page states the support window; a Docusaurus redirect resolves the old URL.
+- [x] `docs/explanation/authentication.md` presents Better Auth first and JWT as legacy.
+- [x] No agent-facing surface (`AGENTS.md`, `CLAUDE*.md`, `.rulesync/rules/`, MCP resources, bootstrap templates) instructs an agent to write RTK Query code for a new app.
+- [x] `terreno_bootstrap_app` output uses syncdb, and a bootstrapped app runs.
+- [x] `terreno_get_upgrade_guide` returns the syncdb upgrade note for the release range that includes #869.
+- [x] `CHANGELOG.md` has a `Deprecated` entry naming `@terreno/rtk`, the support window, and the migration guide link.
+- [x] `bun run lint`, `bun run compile`, `bun run rules:check`, and `bun run website:build` all pass.

package/src/docs/versioned/57.1.0/implementationPlans/syncdb-codegen-research.md

@@ -0,0 +1,137 @@
+# Research: @terreno/syncdb-codegen
+
+**Date:** 2026-08-20  
+**Scope:** Validate the draft IP (`docs/implementationPlans/syncdb-codegen.md`) against the current `master` codebase and parent syncdb work.  
+**Status:** Complete — clarification pass answered 2026-08-20. IP **Approved**.
+
+## Clarification outcomes (2026-08-20)
+
+| # | Topic | Choice |
+|---|-------|--------|
+| 1 | Collection discovery | A — `x-terreno-sync` + `--collections` fallback |
+| 2 | Per-mutation retries | A — `maxAttempts` plumbing |
+| 3 | Type emission | A — hand-rolled emitter |
+| 4 | Hook factory | A — `createCollectionHooks` in `@terreno/syncdb/react` |
+| 5 | Hook naming | **C — friendly names** (`useTodos`, `useTodo`, `useCreateTodo`, …) |
+| 6 | Mutation return | A — `[trigger]` one-tuple |
+| 7 | example-frontend scope | A — todos only |
+| 8 | Delivery | **B — single PR** |
+| 9 | npm publish | **Include `@terreno/syncdb-codegen` in `publish-on-tag.yml`** |
+
+## Open questions (blocking — see blend Step 3)
+
+Resolved — see table above.
+
+## Problem summary
+
+`@terreno/syncdb` is implemented (Phases 1–8 of `syncdb-local-first.md` landed). Consumers still hand-write collection strings, entity interfaces, and hook wiring — see `example-frontend/components/SyncTodosScreen.tsx`. RTK consumers get typed hooks from `bun run sdk` → `openApiSdk.ts`. The gap is a **codegen CLI** that reads the same OpenAPI spec and emits typed syncdb hooks (friendly names per approved IP).
+
+## What was investigated
+
+| Area | Locations | Finding |
+|------|-----------|---------|
+| React hooks | `syncdb/src/react/hooks.ts`, `index.ts` | `useQuery`, `useEntity`, `useMutate` exist; no per-operation hooks, no `createCollectionHooks` |
+| Mutate / outbox | `syncdb/src/client.ts`, `mutations/outbox.ts`, `storage/schema.ts` | `MutateArgs` has no `maxAttempts`; outbox rows have `errorNackCount` only; replay uses global `MAX_ERROR_NACK_ATTEMPTS = 5` |
+| OpenAPI list | `api/src/openApi.ts` `listOpenApiMiddleware` | No vendor extensions; no `operationId`; tags = model collection name |
+| Sync registry | `api/src/sync/registry.ts`, `api/src/api.ts` | In-memory only; `collectionTag = routePath.replace(/^\//, "")`; not reflected in OpenAPI |
+| Example backend | `example-backend/src/api/todos.ts`, `projects.ts` | `sync: {scope: {type: "owner"}}` on todos; tenant scope on projects |
+| RTK hook names | `example-frontend/store/openApiSdk.ts` | `useGetTodosQuery`, `useGetTodosByIdQuery`, `usePostTodosMutation`, `usePatchTodosByIdMutation`, `useDeleteTodosByIdMutation` |
+| Codegen package | `syncdb-codegen/` | **Does not exist** — tasks/IP only |
+| Parent IP | `docs/implementationPlans/syncdb-local-first.md` | Shaped; codegen listed as Phase 6 / future work |
+| Roadmap | `.github/roadmap-fields.yml` present | Roadmap-enabled repo; no GitHub issue found for syncdb-codegen |
+
+## Current consumer pattern (manual)
+
+```typescript
+// example-frontend/components/SyncTodosScreen.tsx
+interface SyncTodo { _id: string; title?: string; completed?: boolean; created?: string; }
+const todos = useQuery<SyncTodo>("todos", {sort: sortByCreatedDesc});
+const {update, remove} = useMutate("todos");
+```
+
+`example-frontend/store/syncdb.ts` maintains `SYNC_COLLECTIONS` by hand — can drift from backend `sync` registration.
+
+## Candidate options (not chosen here — see blocking questions)
+
+### How codegen discovers synced collections
+
+| Option | Pros | Cons |
+|--------|------|------|
+| **A. `x-terreno-sync` on list OpenAPI ops** | Single input (same as RTK); spec is versioned with backend; ~10-line api change | Must thread `routePath` into `listOpenApiMiddleware` (not available today) |
+| **B. `--collections` CLI flag only** | No api change | Drifts from backend; duplicates config |
+| **C. `GET /sync/config` manifest** | Runtime truth | Extra endpoint; second source of truth vs OpenAPI |
+
+Draft IP recommends **A + B fallback**.
+
+### Per-mutation retry budget (`retries` / `maxAttempts`)
+
+| Option | Pros | Cons |
+|--------|------|------|
+| **A. Plumb `maxAttempts` through mutate → outbox → replay** | Config is honest; matches RTK `maxRetries: 0` intent | Touches syncdb storage + replay coordinator |
+| **B. Codegen emits `retries` but engine ignores** | Smaller diff | Lying generated config |
+
+Draft IP recommends **A**.
+
+### Type emission from OpenAPI schemas
+
+| Option | Pros | Cons |
+|--------|------|------|
+| **A. Hand-rolled emitter for mongoose-to-swagger dialect** | Zero runtime deps; small compiled binary | Must grow if spec dialect widens |
+| **B. `openapi-typescript` or oazapfts** | Battle-tested | Heavier dep; may emit more than needed |
+
+Draft IP recommends **A** (~150 lines + snapshot tests).
+
+### Hook factory location
+
+| Option | Pros | Cons |
+|--------|------|------|
+| **A. `createCollectionHooks` in `@terreno/syncdb/react`** | Versioned with hooks; custom hooks use same factory | Expands syncdb public API |
+| **B. Inline factory in every generated file** | No syncdb API change | Duplicated generated code |
+| **C. Runtime export from `@terreno/syncdb-codegen`** | — | Codegen becomes app dependency (rejected) |
+
+Draft IP recommends **A**.
+
+### Hook naming and RTK collision
+
+| Option | Pros | Cons |
+|--------|------|------|
+| **A. Grouped `useTodosMutate()`** | No name collision with RTK | Different call sites; harder migration |
+| **B. RTK-exact per-op names (`useGetTodosQuery`, …)** | Import-path migration | Intentional name collision — must not barrel-export both SDKs |
+| **C. Friendly names (`useCreateTodo`)** | Readable | Diverges from RTK; migration friction |
+
+Draft IP recommends **B**.
+
+### Mutation hook return shape
+
+| Option | Pros | Cons |
+|--------|------|------|
+| **A. `[trigger]` one-tuple** | RTK destructuring compiles; syncdb writes are sync | `.unwrap()` / `isLoading` must be deleted at migration |
+| **B. Full RTK async tuple** | Drop-in compat | Fakes async state syncdb does not have |
+
+Draft IP recommends **A**.
+
+## Technical notes for implementation
+
+1. **`listOpenApiMiddleware` needs `routePath`**: Today signature is `(model, options)` only. `collection` for `x-terreno-sync` must match `sync/registry.ts` `collectionTag` (path without leading `/`). Pass path from `_buildModelRouter` or read from options if added there.
+
+2. **`scope` in extension**: Emit scope **type** string (`owner` | `tenant` | `broadcast` | `custom`). Function resolvers → `"custom"`.
+
+3. **Name derivation**: Match `@rtk-query/codegen-openapi` — pascal-case from HTTP method + path segments (verified against `openApiSdk.ts` for `/todos`).
+
+4. **example-backend has two synced models** (todos owner, projects tenant). Draft IP example-frontend integration only wires todos — confirm whether projects should appear in generated SDK for the example app.
+
+5. **No data migration** for optional `_outbox.maxAttempts` cell — missing cell keeps engine default (5).
+
+6. **Roadmap handoff**: When IP status → Approved, run `roadmap-item` to create/update tracking issue (no existing issue found).
+
+## Open questions (blocking — see blend Step 3)
+
+Transferred to the clarification pass in the blend thread; do not treat draft IP decisions as approved until answered.
+
+## References
+
+- `docs/implementationPlans/syncdb-codegen.md` (draft IP)
+- `docs/tasks/syncdb-codegen.md` (task breakdown)
+- `docs/implementationPlans/syncdb-local-first.md` (parent — Phase 6 codegen)
+- `docs/how-to/migrate-rtk-to-syncdb.md` (migration guide — codegen section TBD)
+- `.rulesync/skills/generate-sdk/SKILL.md` (RTK codegen parallel)

package/src/docs/versioned/57.1.0/implementationPlans/syncdb-codegen.md

@@ -0,0 +1,256 @@
+# Implementation Plan: @terreno/syncdb-codegen
+
+**Status:** In progress
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1087
+**Branch:** cursor/syncdb-codegen-in-package-746d
+**Owner:**
+**Created:** 2026-07-08
+**Approved:** 2026-08-20
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1110
+**Research:** [syncdb-codegen-research.md](./syncdb-codegen-research.md)
+
+## Goal
+
+Ship **`terreno-syncdb-codegen` as a bin of `@terreno/syncdb`** (not a separate workspace package): a CLI that reads a backend OpenAPI spec and generates a static, typed set of syncdb hooks — the local-first analogue of `@rtk-query/codegen-openapi` (`bun run sync-sdk` → `store/syncDbSdk.ts`).
+
+Today syncdb consumers hand-write both the entity types and the collection strings:
+
+```typescript
+// example-frontend/components/SyncTodosScreen.tsx — all manual today
+interface SyncTodo { _id: string; title?: string; completed?: boolean; created?: string; }
+const todos = useQuery<SyncTodo>("todos", {sort: sortByCreatedDesc});
+const {update, remove} = useMutate("todos"); // update/remove payloads are Record<string, unknown>
+```
+
+After this IP, a generated `store/syncDbSdk.ts` provides one hook per operation with **friendly, entity-centric names** — `useTodos` (list), `useTodo` (read by id), `useCreateTodo`, `useUpdateTodo`, `useDeleteTodo` — with payload types derived from the same OpenAPI schemas RTK codegen uses (`Todo`, `CreateTodoBody`, `UpdateTodoBody`), plus a `SYNC_COLLECTIONS` constant that feeds `createSyncDb`. Names deliberately differ from RTK codegen so `openApiSdk.ts` and `syncDbSdk.ts` can coexist without collision during migration. Mutation hooks still use one-element `[trigger]` tuples for familiar destructuring; triggers are syncdb-native (no `.unwrap()`). Custom hooks are supported the same way RTK supports custom endpoints: the generated file is never edited, and consumers extend it in a sibling file using `createCollectionHooks`.
+
+## Non-Goals
+
+- Covering the whole syncdb surface. Only the five CRUD operations (list query, read, create, update/patch, delete) get generated per-collection hooks. `useSyncStatus`, `useConflicts`, `useSyncDbClient`, and `SyncDbProvider` are global (not per-collection) and stay as direct imports from `@terreno/syncdb/react`.
+- Full RTK return-shape emulation. Hook **names** are syncdb-friendly (not RTK-derived); mutation hooks use `[trigger]` tuples only. Return shapes are syncdb-native (no `isLoading`/`error` async state on mutations — writes are synchronous local applies plus a durable outbox; sync state lives in `useSyncStatus`). The RTK ↔ syncdb mapping is documented in the generated file header and the migration guide.
+- Runtime schema validation of mutation payloads (types are compile-time only, matching RTK codegen).
+- Publishing per-platform compiled binaries as GitHub release artifacts (the compiled binary remains a local/CI `build:binary` target).
+- Watch mode, incremental generation, or multi-output-file support.
+- Generating Redux integration or migrating non-synced endpoints — per `docs/how-to/migrate-rtk-to-syncdb.md`, custom routes stay on RTK.
+
+## Decisions
+
+Options were considered where the design was genuinely open; each row records the recommendation this plan is built on. Rejected alternatives are listed so review can overrule them cheaply.
+
+| Question | Decision |
+|----------|----------|
+| **How does codegen know which collections are synced?** OpenAPI does not mark sync today; the server-side `syncRegistry` (`api/src/sync/registry.ts`) is in-memory only. Options: (a) emit an `x-terreno-sync` vendor extension on the list path from `modelRouter` when `options.sync` is set; (b) require an explicit `--collections` CLI arg; (c) add a `GET /sync/config` manifest endpoint. | **(a) with (b) as override.** The extension is a ~10-line change in `@terreno/api`'s list OpenAPI middleware, keeps the spec the single input (same as RTK codegen), and can't drift from the backend. `--collections` remains as an explicit filter/override for apps that sync a subset. (c) adds server surface for no extra information and is rejected. |
+| **How is "retries vs not" expressed?** RTK disables retries per-endpoint via `extraOptions: {maxRetries: 0}` (see `rtk/src/authSlice.ts`). syncdb retries live in the replay engine: `MAX_ERROR_NACK_ATTEMPTS = 5` with exponential backoff in `syncdb/src/sync/replayCoordinator.ts`, not configurable per mutation. Options: (a) plumb an optional per-mutation `maxAttempts` through `client.mutate` → outbox row → replay coordinator, and expose `retries` in the codegen config; (b) codegen-only option that is silently ignored until the engine supports it. | **(a).** Small, contained change: `MutateArgs.maxAttempts?`, one optional outbox cell, one `??` in the replay coordinator's error-nack branch. `retries: false` maps to `maxAttempts: 1` (fail fast, like RTK's `maxRetries: 0`), a number maps directly, and omitted keeps the engine default of 5. (b) would generate config that lies. Note syncdb mutations are idempotent via `mutationId`, so unlike RTK the motivation is fail-fast UX (surface a terminal failure immediately), not duplicate-write safety. |
+| **Config surface: flags only, or a config file?** The binary should "take a few args", but per-collection overrides (retries, exclusions) don't map well to flags. | **Flags for the common path, optional JSON config for overrides.** `--schema`, `--out`, `--collections` cover the RTK-equivalent happy path. `--config ./syncdb-codegen.json` adds `{overrides: {<collection>: {retries?: boolean \| number}}, exportName?, sdkImportPath?}`. JSON (not TS) because a compiled bun binary cannot reliably import arbitrary consumer TypeScript at runtime; RTK's TS `ConfigFile` needs the `tsx`/`TS_NODE_PROJECT` dance we currently work around in `example-frontend/scripts/generate-sdk.ts`. |
+| **How are TS types emitted from OpenAPI schemas?** Options: (a) a small hand-rolled emitter for the subset `mongoose-to-swagger` actually produces (objects, primitives, enums as string unions, arrays, `$ref`); (b) depend on `openapi-typescript` or oazapfts. | **(a).** The @terreno/api spec is a narrow, known dialect; a ~150-line emitter with snapshot tests keeps the binary dependency-free and small. If the emitter grows past that dialect, revisit (b). |
+| **Where does the shared hook factory live?** Generated code and custom hooks must be built the same way (the RTK parallel: generated `injectEndpoints` and app `sdk.ts` both build on `emptySplitApi`). Options: (a) new `createCollectionHooks` export in `@terreno/syncdb/react`; (b) inline the factory into every generated file; (c) a runtime export of `@terreno/syncdb-codegen`. | **(a).** One implementation, versioned with the hooks it wraps, and consumers already depend on `@terreno/syncdb`. (b) duplicates logic into generated output; (c) would make the codegen package a runtime dependency of apps, which it should never be. |
+| **Hook granularity and naming.** Options: (a) one grouped `useTodosMutate()` returning `{create, update, remove}`; (b) one hook per operation with RTK codegen's exact naming scheme (`use{Method}{Path}Query/Mutation`); (c) per-operation hooks with friendlier names (`useCreateTodo`). | **(c) — per-operation, friendly names.** Generated per collection (entity `Todo`, collection `todos`): `useTodos`, `useTodo`, `useCreateTodo`, `useUpdateTodo`, `useDeleteTodo`. Derivation: `entityName` from the list-item schema `$ref` basename (`Todo`); `pluralName` = PascalCase of the collection path segment (`todos` → `Todos`). List hook `use{Plural}`; read hook `use{Entity}`; mutations `useCreate{Entity}`, `useUpdate{Entity}`, `useDelete{Entity}`. No collision with RTK hooks during dual-stack migration. "Update" and "patch" are the same hook — modelRouter only exposes PATCH (merge semantics). |
+| **Mutation hook return shape.** RTK mutation hooks return `[trigger, {isLoading, error, ...}]` and triggers return promises with `.unwrap()`. syncdb writes are synchronous local applies; there is no per-call async state. | **One-element tuple `[trigger]`.** Keeps the RTK call site (`const [createTodo] = usePostTodosMutation()`) working unchanged; the trigger returns `{mutationId, id}` synchronously instead of a promise, so `.unwrap()`/`isLoading` usages are deleted during migration (the compiler flags them). Pending/conflict state is per-entity (`isPending` on reads) and global (`useSyncStatus`), not per-call. |
+| **Distribution.** "Compiled bun binary" vs npm reality. | **Both, npm-bin first, published on tag.** The package ships `"bin": {"terreno-syncdb-codegen": "./dist/cli.js"}` with a `#!/usr/bin/env bun` shebang (the `@terreno/mcp` pattern), plus a `build:binary` script running `bun build --compile src/cli.ts --outfile dist/terreno-syncdb-codegen` for standalone use. Add `publish-syncdb-codegen` to `publish-on-tag.yml` (modeled on `publish-syncdb` / `publish-mcp`). |
+| **Delivery shape.** Four phased PRs vs one. | **Single PR** — all runtime, api, codegen, integration, docs, and publish wiring land together. Task phases remain for implementation order inside the PR. |
+| **example-frontend generated collections.** Backend syncs todos and projects; example app scope. | **todos only** in the checked-in `syncDbSdk.ts`; projects stay manual or a follow-up when a syncdb screen ships for them. |
+
+## Architecture
+
+```
+example-backend                                example-frontend
+  modelRouter("/todos", Todo, {sync: {...}})     bun run sync-sdk
+    └─ list OpenAPI middleware emits               └─ terreno-syncdb-codegen
+       x-terreno-sync on GET /todos                     --schema http://localhost:4000/openapi.json
+            │                                           --out ./store/syncDbSdk.ts
+            ▼                                                │
+      /openapi.json  ──── fetch/read ────────────────────────┘
+                                                             │ emits
+                                                             ▼
+                                              store/syncDbSdk.ts   (generated, never edited)
+                                                ├─ interface Todo / CreateTodoBody / UpdateTodoBody
+                                                ├─ export const SYNC_COLLECTIONS = ["todos"] as const
+                                                └─ export const {useListQuery: useTodos, useReadQuery: useTodo,
+                                                     useCreateMutation: useCreateTodo,
+                                                     useUpdateMutation: useUpdateTodo,
+                                                     useDeleteMutation: useDeleteTodo} =
+                                                       createCollectionHooks<...>({collection: "todos"})
+                                                             │ extended by (custom hooks)
+                                                             ▼
+                                              store/syncSdk.ts    (hand-written, optional)
+                                                └─ createCollectionHooks<LocalNote>({collection: "notes"})
+```
+
+Two packages change:
+
+1. **`@terreno/syncdb`** (runtime + CLI): `createCollectionHooks` factory in `src/react/`, per-mutation `maxAttempts` plumbing through `client.mutate` → outbox → replay coordinator, and `src/codegen/` (`terreno-syncdb-codegen` bin).
+2. **`@terreno/api`**: `listOpenApiMiddleware` (or the shared path-building step in `api/src/openApi.ts`) adds `"x-terreno-sync": {collection, scope}` to the list operation when `options.sync` is present.
+
+### Runtime factory (`@terreno/syncdb/react`)
+
+```typescript
+export interface CollectionHooksConfig {
+  collection: string;
+  /** false → 1 attempt (fail fast); number → max replay attempts; omitted → engine default (5). */
+  retries?: boolean | number;
+}
+
+export type MutationTrigger<TArgs> = (args: TArgs) => {mutationId: string; id: string};
+
+export interface CollectionHooks<TData, TCreate, TUpdate> {
+  /** List query (RTK: useGet{Path}Query). */
+  useListQuery: (options?: UseQueryOptions<TData>) => {data: TData[]};
+  /** Single-entity read (RTK: useGet{Path}ByIdQuery). */
+  useReadQuery: (id: string) => UseEntityResult<TData>;
+  /** Create (RTK: usePost{Path}Mutation). */
+  useCreateMutation: () => [MutationTrigger<{data: TCreate}>];
+  /** Update via merge — patch semantics (RTK: usePatch{Path}ByIdMutation). */
+  useUpdateMutation: () => [MutationTrigger<{id: string; data: TUpdate}>];
+  /** Soft delete (RTK: useDelete{Path}ByIdMutation). */
+  useDeleteMutation: () => [MutationTrigger<{id: string}>];
+}
+
+export const createCollectionHooks = <
+  TData = Record<string, unknown>,
+  TCreate = Record<string, unknown>,
+  TUpdate = Partial<TCreate>,
+>(config: CollectionHooksConfig): CollectionHooks<TData, TCreate, TUpdate> => { ... };
+```
+
+The factory returns **operation-named keys** (`useListQuery`, `useReadQuery`, `useCreateMutation`, `useUpdateMutation`, `useDeleteMutation`); the generated file renames them to friendly collection-specific names via destructuring (`useListQuery: useTodos`, `useReadQuery: useTodo`, …). Custom hooks can keep the generic factory keys or apply the same rename pattern. Each hook delegates to the existing `useQuery`/`useEntity`/`useMutate` internals (no listener logic duplicated) and threads `retries` into `client.mutate` as `maxAttempts`.
+
+### Generated file shape
+
+```typescript
+// store/syncDbSdk.ts — GENERATED by @terreno/syncdb-codegen. Do not edit.
+import {createCollectionHooks} from "@terreno/syncdb/react";
+
+export interface Todo { _id: string; title: string; completed: boolean; ownerId: string; created: string; updated: string; }
+export interface CreateTodoBody { title: string; completed?: boolean; }
+export type UpdateTodoBody = Partial<CreateTodoBody>;
+
+/** Collections with sync enabled on the backend; pass to createSyncDb. */
+export const SYNC_COLLECTIONS = ["todos"] as const;
+
+export const {
+  useListQuery: useTodos,
+  useReadQuery: useTodo,
+  useCreateMutation: useCreateTodo,
+  useUpdateMutation: useUpdateTodo,
+  useDeleteMutation: useDeleteTodo,
+} = createCollectionHooks<Todo, CreateTodoBody, UpdateTodoBody>({collection: "todos"});
+```
+
+Call-site comparison for migration:
+
+```typescript
+// RTK (openApiSdk)                         // syncdb (syncDbSdk — generated)
+const {data} = useGetTodosQuery({});        const {data} = useTodos();
+const {data} = useGetTodosByIdQuery({id});  const {data, isPending} = useTodo(id);
+const [createTodo] = usePostTodosMutation(); const [createTodo] = useCreateTodo();
+await createTodo({body}).unwrap();          createTodo({data}); // sync, returns {mutationId, id}
+const [patchTodo] = usePatchTodosByIdMutation(); const [patchTodo] = useUpdateTodo();
+const [deleteTodo] = useDeleteTodosByIdMutation(); const [deleteTodo] = useDeleteTodo();
+```
+
+`SYNC_COLLECTIONS` replaces the hand-maintained list in `example-frontend/store/syncdb.ts`, closing the "client string must match backend route" gap.
+
+### CLI
+
+```
+terreno-syncdb-codegen --schema <url|path> --out <file> [--collections a,b] [--config <json>] [--no-format]
+```
+
+- `--schema` (required): OpenAPI URL or local JSON file (same source as `openapi-config.ts`'s `schemaFile`).
+- `--out` (required): output `.ts` path.
+- `--collections` (optional): comma-separated allowlist; also the fallback when the spec has no `x-terreno-sync` extensions (older backends). Errors clearly if neither extensions nor the flag identify any collection.
+- `--config` (optional): JSON file with `{overrides: {todos: {retries: false}}}` per-collection settings.
+- `--no-format` (optional): skip the biome/prettier formatting pass (codegen formats output via `Bun.spawn`-ed `bunx biome check --write` when available, mirroring `generate-sdk.ts`; falls back to raw emit).
+
+## Models
+
+No Mongoose model changes. One local-storage schema change in syncdb: the `_outbox` reserved table gains an optional `maxAttempts` numeric cell (`syncdb/src/storage/schema.ts`, `syncdb/src/mutations/outbox.ts`). Missing cell means engine default, so existing persisted stores need no migration.
+
+## APIs
+
+No new HTTP endpoints. One OpenAPI spec addition in `@terreno/api`: list operations of sync-enabled model routers gain
+
+```json
+"x-terreno-sync": {"collection": "todos", "scope": "owner"}
+```
+
+Vendor extensions are legal OpenAPI and ignored by the RTK codegen, Swagger UI, and the AJV validator, so this is backward-compatible.
+
+## Notifications
+
+None needed.
+
+## UI
+
+No new screens. `example-frontend/components/SyncTodosScreen.tsx` swaps its hand-rolled `SyncTodo` interface and string-based hooks for the generated `useTodos`/`useCreateTodo`/`useUpdateTodo`/`useDeleteTodo`/`useTodo`, and `store/syncdb.ts` imports `SYNC_COLLECTIONS` from the generated file. Behavior is unchanged; the existing syncdb Playwright e2e suite is the regression net.
+
+## Phases
+
+**Single PR** (approved). Implementation order inside the PR:
+
+1. **syncdb runtime** — `createCollectionHooks` + `maxAttempts` plumbing (mutate → outbox → replay coordinator), with unit tests.
+2. **api spec extension** — `x-terreno-sync` on list operations (+ pass `routePath` into `listOpenApiMiddleware`), with an OpenAPI generation test.
+3. **codegen CLI** — `syncdb/src/codegen/`: arg parsing, spec loading, collection discovery, type emitter, file emitter, snapshot tests, `build:binary` on `@terreno/syncdb`.
+4. **integration + docs** — `example-frontend` `sync-sdk` script and screen migration; README / reference / migration-guide updates. Codegen ships with existing `publish-syncdb` (no extra npm package).
+
+## Feature Flags & Migrations
+
+- No new feature flags. The existing `use-syncdb` flag continues to gate the syncdb path in `example-frontend`.
+- No data migrations. The new `_outbox.maxAttempts` cell is optional and defaulted.
+- **Publishing:** codegen is a bin of `@terreno/syncdb`; the existing `publish-syncdb` job is sufficient. Do not add a separate `@terreno/syncdb-codegen` package or publish job.
+
+## Activity Log & User Updates
+
+None — developer tooling only.
+
+## Not Included / Future Work
+
+- Per-platform prebuilt binaries as release artifacts.
+- Generated wrappers for `useSyncStatus`/`useConflicts` (no per-collection typing to add).
+- Server-driven filters/sorts in `useQuery` options (syncdb filters run client-side in JS; nothing for codegen to type beyond `TData`).
+- Zod/AJV runtime validation of mutation payloads against the OpenAPI schema.
+- Optional RTK-compatible hook naming mode (`overrides.todos.naming: "rtk"`) for teams that want import-swap migration without renames.
+- RTK-compatible async mutation state (`isLoading`, promise-returning triggers with `.unwrap()`).
+- A `--watch` mode.
+- Generating `projects` hooks in example-frontend until a syncdb screen exists for that collection.
+
+## Files to Create / Modify
+
+**Create**
+- `syncdb/src/codegen/cli.ts` — `#!/usr/bin/env bun` entry; arg parsing (`Bun.argv` + `util.parseArgs`), exit codes, error messages.
+- `syncdb/src/codegen/loadSpec.ts` — fetch/read + JSON parse of the OpenAPI document.
+- `syncdb/src/codegen/discoverCollections.ts` — walk `paths`, collect `x-terreno-sync` operations, resolve entity/create/update schema refs; apply `--collections` filter/fallback.
+- `syncdb/src/codegen/emitTypes.ts` — OpenAPI schema subset → TS interfaces.
+- `syncdb/src/codegen/emitSdk.ts` — assemble the output file (header, types, `SYNC_COLLECTIONS`, `createCollectionHooks` calls with overrides applied).
+- `syncdb/src/codegen/*.test.ts` — unit + snapshot tests against `syncdb/src/codegen/fixtures/openapi.example.json`.
+- `example-frontend/syncdb-codegen.json` — per-collection overrides example (todos with default retries).
+
+**Modify**
+- `syncdb/package.json` — `"bin": {"terreno-syncdb-codegen": "./src/codegen/cli.ts"}`, `build:binary`.
+- `syncdb/src/react/collectionHooks.ts` + `syncdb/src/react/index.ts` — `createCollectionHooks` export.
+- `syncdb/src/client.ts` — `MutateArgs.maxAttempts?`, pass-through to outbox.
+- `syncdb/src/mutations/outbox.ts`, `syncdb/src/storage/schema.ts` — optional `maxAttempts` cell.
+- `syncdb/src/sync/replayCoordinator.ts` — `row.maxAttempts ?? MAX_ERROR_NACK_ATTEMPTS` in the error-nack branch.
+- `api/src/openApi.ts` (`listOpenApiMiddleware`) — emit `x-terreno-sync` when `options.sync` is set.
+- `example-frontend/package.json` — `"sync-sdk"` script.
+- `example-frontend/store/syncDbSdk.ts` — generated output (checked in, like `openApiSdk.ts`).
+- `example-frontend/store/syncdb.ts` — import `SYNC_COLLECTIONS` from the generated file.
+- `example-frontend/components/SyncTodosScreen.tsx` — use generated hooks (`useTodo`, `useCreateTodo`, `useUpdateTodo`, `useDeleteTodo`); keep `useEntityIds` for list virtualization.
+- `syncdb/README.md`, `docs/how-to/migrate-rtk-to-syncdb.md`, `docs/reference/syncdb.md` — codegen sections.
+
+## Task List
+
+See [docs/tasks/syncdb-codegen.md](../tasks/syncdb-codegen.md).
+
+## Acceptance Criteria
+
+- [x] `createCollectionHooks<Todo>({collection: "todos"})` returns the five per-operation hooks (`useListQuery`, `useReadQuery`, `useCreateMutation`, `useUpdateMutation`, `useDeleteMutation`) whose behavior matches direct `useQuery`/`useEntity`/`useMutate` calls; mutation hooks return `[trigger]` tuples so RTK-style destructuring compiles (unit tests in `syncdb/src/react/`).
+- [x] `createCollectionHooks({collection: "todos", retries: false})` produces mutations whose outbox rows fail terminally after a single `error` nack; `retries: 3` fails after three attempts; omitted keeps the current 5-attempt backoff (replay coordinator tests).
+- [x] `GET /openapi.json` from a backend with `sync: {scope: {type: "owner"}}` on `/todos` includes `x-terreno-sync: {collection: "todos", scope: "owner"}` on the list operation; non-synced routes have no extension (api test).
+- [x] `terreno-syncdb-codegen --schema <fixture> --out out.ts` emits a file that type-checks under the example-frontend tsconfig and contains `SYNC_COLLECTIONS`, typed interfaces, and per synced collection the five friendly hooks (`useTodos`, `useTodo`, `useCreateTodo`, `useUpdateTodo`, `useDeleteTodo` for the todos fixture — snapshot test).
+- [x] `--collections todos` filters output to that collection; a spec without extensions and no `--collections` flag exits non-zero with an actionable message.
+- [x] A config file with `{overrides: {todos: {retries: false}}}` produces `createCollectionHooks<...>({collection: "todos", retries: false})` in the output.
+- [x] `bun run build:binary` in `syncdb/` produces a standalone executable that generates identical output to the bin entry.
+- [ ] `bun run sync-sdk` in `example-frontend` (backend running) regenerates `store/syncDbSdk.ts` with no diff when the backend is unchanged; SyncTodosScreen works against the generated hooks (existing syncdb e2e suite passes).
+- [x] `bun run lint` (syncdb, example-frontend), `bun test` in `syncdb/` (500 pass), and `api/src/openApi.test.ts` (26 pass).
+- [x] No separate `@terreno/syncdb-codegen` package or `publish-syncdb-codegen` job; the CLI ships with `@terreno/syncdb`.