@terreno/mcp 57.0.0 → 57.2.0

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

@@ -1,13 +1,17 @@
 # Implementation Plan: @terreno/syncdb-codegen
 
-**Status:** Draft
-**Branch:** cursor/ip-syncdb-codegen-41d6
+**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`: a small CLI (runnable as an npm bin under bun and buildable as a standalone compiled bun binary) that reads a backend OpenAPI spec and generates a static, typed set of syncdb hooks — the local-first analogue of the existing `@rtk-query/codegen-openapi` flow (`bun run sdk` → `store/openApiSdk.ts`).
+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:
 
@@ -18,14 +22,14 @@ 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 the exact names RTK codegen would produce for the same routes — `useGetTodosQuery` (list query), `useGetTodosByIdQuery` (read), `usePostTodosMutation` (create), `usePatchTodosByIdMutation` (update/patch), `useDeleteTodosByIdMutation` (delete) — with payload types derived from the same OpenAPI schemas RTK codegen uses (`Todo`, `CreateTodoBody`, `UpdateTodoBody`), plus a `SYNC_COLLECTIONS` constant that feeds `createSyncDb`. Migrating a screen from RTK to syncdb becomes (mostly) an import-path change. 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 the same public factory the generated code uses.
+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 and call sites** match RTK; return shapes are syncdb-native where the semantics differ (no `isLoading`/`error` async state on mutations — writes are synchronous local applies plus a durable outbox; sync state lives in `useSyncStatus`). The mapping is documented in the generated file header and the migration guide.
+- 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 to npm or GitHub releases (the compiled binary is a local/CI build target for now; `@terreno/syncdb` itself is not in `publish-on-tag.yml` yet either).
+- 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.
 
@@ -40,9 +44,11 @@ Options were considered where the design was genuinely open; each row records th
 | **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`). | **(b) — per-operation, RTK names.** Generated per collection: `useGetTodosQuery`, `useGetTodosByIdQuery`, `usePostTodosMutation`, `usePatchTodosByIdMutation`, `useDeleteTodosByIdMutation`. Name derivation is the same deterministic pascal-case of the route path RTK uses (no singularization heuristics). This makes RTK→syncdb migration an import swap. Two consequences are accepted: (1) name **collisions with `openApiSdk.ts`** are intentional — during migration both files export e.g. `useGetTodosQuery`, and the import path picks the data source; imports must never be mixed via a barrel that re-exports both. (2) "update" and "patch" are the **same hook**: modelRouter only exposes PATCH (merge semantics) and syncdb's update is a merge, so `usePatchTodosByIdMutation` is the update hook — there is no separate PUT/replace hook to generate. |
+| **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.** 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` (the `example-backend/Dockerfile` pattern) for standalone use. Publishing platform binaries is future work. |
+| **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
 
@@ -59,9 +65,10 @@ example-backend                                example-frontend
                                               store/syncDbSdk.ts   (generated, never edited)
                                                 ├─ interface Todo / CreateTodoBody / UpdateTodoBody
                                                 ├─ export const SYNC_COLLECTIONS = ["todos"] as const
-                                                └─ export const {useGetTodosQuery, useGetTodosByIdQuery,
-                                                     usePostTodosMutation, usePatchTodosByIdMutation,
-                                                     useDeleteTodosByIdMutation} =
+                                                └─ export const {useListQuery: useTodos, useReadQuery: useTodo,
+                                                     useCreateMutation: useCreateTodo,
+                                                     useUpdateMutation: useUpdateTodo,
+                                                     useDeleteMutation: useDeleteTodo} =
                                                        createCollectionHooks<...>({collection: "todos"})
                                                              │ extended by (custom hooks)
                                                              ▼
@@ -69,11 +76,10 @@ example-backend                                example-frontend
                                                 └─ createCollectionHooks<LocalNote>({collection: "notes"})
 ```
 
-Three packages change:
+Two packages change:
 
-1. **`@terreno/syncdb`** (runtime): `createCollectionHooks` factory in `src/react/`, plus per-mutation `maxAttempts` plumbing through `client.mutate` → outbox → replay coordinator.
+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.
-3. **`@terreno/syncdb-codegen`** (new): CLI that parses the spec, discovers synced collections, and emits the SDK file.
 
 ### Runtime factory (`@terreno/syncdb/react`)
 
@@ -106,7 +112,7 @@ export const createCollectionHooks = <
 >(config: CollectionHooksConfig): CollectionHooks<TData, TCreate, TUpdate> => { ... };
 ```
 
-The factory returns **operation-named keys** (`useListQuery`, `useReadQuery`, `useCreateMutation`, `useUpdateMutation`, `useDeleteMutation`); the generated file renames them to the RTK-style collection-specific names via destructuring (`useListQuery: useGetTodosQuery`, ...). Custom hooks can keep the generic names or rename the same way. Each hook delegates to the existing `useQuery`/`useEntity`/`useMutate` internals (no listener logic duplicated) and threads `retries` into `client.mutate` as `maxAttempts`. This is the `emptySplitApi` of the syncdb world: generated code calls it, and custom hooks call it directly — that is the whole "custom hooks the same way RTK does" story.
+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
 
@@ -122,24 +128,24 @@ export type UpdateTodoBody = Partial<CreateTodoBody>;
 export const SYNC_COLLECTIONS = ["todos"] as const;
 
 export const {
-  useListQuery: useGetTodosQuery,
-  useReadQuery: useGetTodosByIdQuery,
-  useCreateMutation: usePostTodosMutation,
-  useUpdateMutation: usePatchTodosByIdMutation,
-  useDeleteMutation: useDeleteTodosByIdMutation,
+  useListQuery: useTodos,
+  useReadQuery: useTodo,
+  useCreateMutation: useCreateTodo,
+  useUpdateMutation: useUpdateTodo,
+  useDeleteMutation: useDeleteTodo,
 } = createCollectionHooks<Todo, CreateTodoBody, UpdateTodoBody>({collection: "todos"});
 ```
 
 Call-site comparison for migration:
 
 ```typescript
-// RTK                                              // syncdb (generated)
-const {data} = useGetTodosQuery({});                 const {data} = useGetTodosQuery();
-const {data} = useGetTodosByIdQuery({id});           const {data, isPending} = useGetTodosByIdQuery(id);
-const [createTodo] = usePostTodosMutation();         const [createTodo] = usePostTodosMutation();
-await createTodo({body}).unwrap();                   createTodo({data}); // sync, returns {mutationId, id}
-const [patchTodo] = usePatchTodosByIdMutation();     const [patchTodo] = usePatchTodosByIdMutation();
-const [deleteTodo] = useDeleteTodosByIdMutation();   const [deleteTodo] = useDeleteTodosByIdMutation();
+// 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.
@@ -176,22 +182,22 @@ None needed.
 
 ## UI
 
-No new screens. `example-frontend/components/SyncTodosScreen.tsx` swaps its hand-rolled `SyncTodo` interface and string-based hooks for the generated `useGetTodosQuery`/`usePostTodosMutation`/`usePatchTodosByIdMutation`/`useDeleteTodosByIdMutation`, and `store/syncdb.ts` imports `SYNC_COLLECTIONS` from the generated file. Behavior is unchanged; the existing syncdb Playwright e2e suite is the regression net.
+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 is plausible but the work splits cleanly into four phases if review prefers smaller units:
+**Single PR** (approved). Implementation order inside the PR:
 
-1. **syncdb runtime** — `createCollectionHooks` + `maxAttempts` plumbing (mutate → outbox → replay coordinator), with unit tests. No consumer-visible breaking changes.
-2. **api spec extension** — `x-terreno-sync` on list operations, with an OpenAPI generation test asserting the extension appears for `example-backend`-style sync configs and is absent otherwise.
-3. **codegen package** — new `syncdb-codegen/` workspace package: arg parsing, spec loading, collection discovery, type emitter, file emitter, snapshot tests against a fixture spec captured from `example-backend`, `build:binary` script.
-4. **integration + docs** — `example-frontend` `sync-sdk` script and screen migration; README updates (`syncdb/README.md`, new `syncdb-codegen/README.md`, `docs/how-to/migrate-rtk-to-syncdb.md` note); root `package.json` convenience scripts.
+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: not wired into `publish-on-tag.yml` in this IP (neither is `@terreno/syncdb` yet); tracked in Future Work so both are added together.
+- **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
 
@@ -199,41 +205,38 @@ None — developer tooling only.
 
 ## Not Included / Future Work
 
-- Publishing `@terreno/syncdb` and `@terreno/syncdb-codegen` to npm (add `publish-syncdb` + `publish-syncdb-codegen` jobs to `publish-on-tag.yml`).
 - 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.
-- Custom hook naming via config (`overrides.todos.hookPrefix`), for apps that need to avoid the intentional name overlap with RTK-generated hooks.
-- RTK-compatible async mutation state (`isLoading`, promise-returning triggers with `.unwrap()`), should a drop-in compatibility mode ever be wanted.
+- 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-codegen/package.json` — name `@terreno/syncdb-codegen`, `bin`, `build:binary`, catalog deps (dev-only: typescript, biome).
-- `syncdb-codegen/tsconfig.json`, `syncdb-codegen/biome.jsonc` — copied from `syncdb/` siblings.
-- `syncdb-codegen/src/cli.ts` — `#!/usr/bin/env bun` entry; arg parsing (`Bun.argv` + `util.parseArgs`), exit codes, error messages.
-- `syncdb-codegen/src/loadSpec.ts` — fetch/read + JSON parse of the OpenAPI document.
-- `syncdb-codegen/src/discoverCollections.ts` — walk `paths`, collect `x-terreno-sync` operations, resolve entity/create/update schema refs from the list/create/patch operations; apply `--collections` filter/fallback.
-- `syncdb-codegen/src/emitTypes.ts` — OpenAPI schema subset → TS interfaces.
-- `syncdb-codegen/src/emitSdk.ts` — assemble the output file (header, types, `SYNC_COLLECTIONS`, `createCollectionHooks` calls with overrides applied).
-- `syncdb-codegen/src/*.test.ts` — unit + snapshot tests against `syncdb-codegen/src/fixtures/openapi.example.json`.
-- `syncdb-codegen/README.md` — usage, args, config format, custom-hooks pattern.
+- `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/src/react/collectionHooks.ts` (new file in existing package) + `syncdb/src/react/index.ts` — `createCollectionHooks` export.
+- `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": "terreno-syncdb-codegen --schema ... --out ./store/syncDbSdk.ts --config ./syncdb-codegen.json"` script; add `@terreno/syncdb-codegen` as a workspace dev dependency.
+- `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; delete the local `SyncTodo` interface.
-- Root `package.json` — workspace entry + `syncdb-codegen:compile` / `syncdb-codegen:test` scripts.
-- `syncdb/README.md`, `docs/how-to/migrate-rtk-to-syncdb.md` — codegen sections.
+- `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
 
@@ -241,12 +244,13 @@ See [docs/tasks/syncdb-codegen.md](../tasks/syncdb-codegen.md).
 
 ## Acceptance Criteria
 
-- [ ] `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/`).
-- [ ] `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).
-- [ ] `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).
-- [ ] `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 RTK-named hooks (`useGetTodosQuery`, `useGetTodosByIdQuery`, `usePostTodosMutation`, `usePatchTodosByIdMutation`, `useDeleteTodosByIdMutation`) — names byte-identical to what `@rtk-query/codegen-openapi` derives for the same routes (snapshot test).
-- [ ] `--collections todos` filters output to that collection; a spec without extensions and no `--collections` flag exits non-zero with an actionable message.
-- [ ] A config file with `{overrides: {todos: {retries: false}}}` produces `createCollectionHooks<...>({collection: "todos", retries: false})` in the output.
-- [ ] `bun run build:binary` in `syncdb-codegen/` produces a standalone executable that generates identical output to the bin entry.
+- [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).
-- [ ] `bun run lint`, `bun run syncdb:test`, `bun run api:test`, and the new `syncdb-codegen:test` pass.
+- [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`.

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

@@ -3,6 +3,7 @@
 *When an engineer is assigned to a project but before you begin coding, you should fill in the implementation plan and get feedback from the engineering team. Once you have finished or you make any changes, tag Josh with the @ symbol so he can review. Also tag anyone else that needs to be notified, has conflicting work, etc.*
 
 **Status:** Shaped, ready for review
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1081
 **Priority:** High
 **Effort:** Large
 **Supersedes:** the prior v1 plan (PR #739, previous content of this file) and the foundation implementation in PR #835 (to be closed with a comment linking here). Proven pieces of #835 — the outbox state machine, AES-GCM codec, delta applier, and type contracts — are harvested and adapted, not reused wholesale.

package/src/docs/versioned/next/implementationPlans/syncdb-phase-c-design.md

@@ -1,5 +1,6 @@
 # SyncDB Phase C Design (syncdb-2)
 
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1081
 Design authority doc for Phase C (server protocol correctness). Hand this verbatim to a
 Sonnet implementer. Read alongside `terreno-syncdb-2.md` (INV-1..4, C1-C8). C5 (mutation
 ledger lease) is owned/implemented elsewhere — this doc designs *around* it and never

package/src/docs/versioned/next/implementationPlans/terreno-langfuse-integration.md

@@ -1,5 +1,6 @@
 # @terreno/langfuse
 
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1093
 A TerrenoApp plugin that integrates [Langfuse](https://langfuse.com) into Terreno backends and frontends. Provides prompt management with MongoDB caching, OpenTelemetry tracing, Vercel AI SDK helpers, React hooks, and an admin UI — all wired up via `.install()`.
 
 > **Prerequisite:** This package relies on the new TerrenoApp plugin system (see [PR #149](https://github.com/FlourishHealth/terreno/pull/149)). TerrenoApp must support `.install()` before this package can be used.

package/src/docs/versioned/next/implementationPlans/terreno-syncdb-2.md

@@ -1,5 +1,6 @@
 # SyncDB Hardening Plan (terreno-syncdb-2)
 
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1081
 Implementation plan for hardening PR #869 (`@terreno/syncdb` local-first data layer,
 branch `worktree-ip-syncdb`). This plan is self-contained: it restates each defect,
 the exact fix, the files involved, and the tests that prove it. Work happens on a

package/src/docs/versioned/next/implementationPlans/upgrade-banner.md

@@ -1,5 +1,9 @@
 # Implementation Plan: Upgrade Banner
 
+**Status:** Complete
+**Closed:** 2026-08-20 — Shipped via `VersionConfig` model, `VersionCheckPlugin` (`GET /version-check`), `AdminVersionConfig`, `useUpgradeCheck` (`@terreno/rtk`), and `UpgradeRequiredScreen` (`@terreno/ui`).
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1079
+
 *When an engineer is assigned to a project but before you begin coding, you should fill in the implementation plan and get feedback from the engineering team. Once you have finished or you make any changes, tag Josh with the @ symbol so he can review. Also tag anyone else that needs to be notified, has conflicting work, etc.*
 
 ## Models

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

@@ -6,7 +6,6 @@ Technical reference for Terreno packages and APIs. Information-oriented, precise
 
 - [@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/syncdb](syncdb.md) — Local-first data layer (reads, writes, offline sync)
 - [@terreno/ai](ai.md) — AI service, GPT routes, Langfuse integration
 - [@terreno/admin-backend](admin-backend.md) — Auto-generated admin CRUD endpoints
@@ -18,11 +17,17 @@ Technical reference for Terreno packages and APIs. Information-oriented, precise
 - [@terreno/mcp](mcp-server.md) — AI coding assistant integration (MCP)
 - [@terreno/test](test.md) — Bun test helpers and in-memory MongoDB
 
+## Migrating from RTK
+
+`@terreno/rtk` is deprecated for **data synchronization**. New apps should use [`@terreno/syncdb`](syncdb.md). Existing RTK consumers: follow [Migrate from @terreno/rtk to @terreno/syncdb](../how-to/migrate-rtk-to-syncdb.md). Archived RTK reference: [legacy/rtk.md](legacy/rtk.md).
+
 ## Configuration
 
 - [Environment Variables](environment-variables.md) — Complete environment variable reference for all packages
 
 ## Other references
 
+- [Lifecycle plugin](lifecycle-plugin.md) — Grow/Pick/Roast/Brew/Taste contracts, results, and transitions
+- [Install agent skills](../how-to/install-agent-skills.md) — Published `skills/` tree for `npx skills`
 - 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

package/src/docs/versioned/next/reference/admin-backend.md

@@ -33,7 +33,7 @@ admin.register(app);
 This creates:
 - `GET /admin/config` — Model metadata endpoint
 - Standard CRUD routes for each model at `{basePath}{routePath}`
-- All routes protected with `Permissions.IsAdmin`
+- All routes protected with `Permissions.IsAdmin`, or fine-grained RBAC when `accessControl` is set
 
 ## AdminApp Options
 
@@ -102,7 +102,72 @@ Field metadata includes:
 
 ## Permissions
 
-All admin routes use `Permissions.IsAdmin`, which checks `user.admin === true`.
+`admin:access` is the only permission that opens the admin page. `GET /admin/config` returns 403
+without it. Script, configuration, RBAC, and per-model permissions never grant entry on their own.
+
+Without `accessControl`, that same page gate uses `Permissions.IsAdmin` (`user.admin`).
+
+With `accessControl`, each model can use a standard admin resource with three actions:
+
+| Action | Access |
+| --- | --- |
+| `read` | List, search, and read any record |
+| `write` | Create, update, bulk-update, and delete any record |
+| `writeOwned` | Create records and update/delete records accepted by the ownership helper |
+
+Declare an `admin<ModelName>` statement and optionally customize ownership:
+
+```typescript
+import {ADMIN_MODEL_ACCESS} from "@terreno/api";
+import {adminOwnedBy, AdminApp} from "@terreno/admin-backend";
+
+const statements = {
+  adminForm: ADMIN_MODEL_ACCESS,
+  adminScreen: ["formReports"],
+} as const;
+
+modelRouter("/forms", Form, {
+  admin: {
+    adminAccess: {isOwned: adminOwnedBy("staffId")},
+    displayName: "Forms",
+    listFields: ["title", "staffId"],
+  },
+  // ...
+});
+
+new AdminApp({
+  accessControl,
+  customScreens: [{
+    adminAccess: {resource: "adminScreen", action: "formReports"},
+    displayName: "Form reports",
+    name: "form-reports",
+  }],
+});
+```
+
+`adminAccess.resource` overrides the default `admin<ModelName>` name. Use
+`adminAccess.authorize({action, instance, user})` when a model or screen needs a completely
+custom decision. The callback replaces the standard read/write/write-owned decision, while
+`admin:access` still protects the admin shell. Every action is authorized without an instance
+first (router and `/admin/config` probes). Return `true` for `read` / `update` / `delete` when
+`instance` is missing if some records may be allowed; the loaded record is authorized next.
+`create` is also checked again with the request body.
+
+`writeOwned` can create any new record; `isOwned` is only applied to update and delete.
+
+The config endpoint is caller-specific: models and custom screens without read access are omitted,
+writable controls are disabled, and `platformTools` reports visibility for Scripts, Roles, Version,
+and Configuration. Built-in tools use the existing editable permissions:
+
+- Scripts: `admin:runScripts` or `admin:viewBackgroundTasks`
+- Roles: `rbac:read`
+- Version and Configuration: `configuration:read`
+- Audit Log and Feature Flags: their model's admin `read` permission
+
+Read and list responses include `_adminCapabilities.update` and
+`_adminCapabilities.delete` for each record. This keeps `writeOwned` forms and row controls
+read-only for records the current user does not own. Script metadata separately exposes run and
+history permissions so a history-only role never receives an enabled Run control.
 
 **Important:** Only expose models that should be editable via admin panel. Avoid sensitive internal models.
 

package/src/docs/versioned/next/reference/admin-config.md

@@ -0,0 +1,51 @@
+# Admin configuration reference
+
+`AdminConfig` is the `admin` object accepted by `modelRouter`.
+
+| Field | Django admin analogue | Description |
+| --- | --- | --- |
+| `displayName` | `verbose_name_plural` | Required navigation and page label. |
+| `listFields` | `list_display` | Required allowlist of list/form fields. |
+| `listDisplay` | `list_display` | Optional visible list columns. |
+| `listDisplayLinks` | `list_display_links` | Columns linking to the edit screen. |
+| `searchFields` | `search_fields` | String fields matched by the list search box as a case-insensitive partial query. |
+| `sortableFields` | `sortable_by` | Columns allowed to sort. |
+| `defaultSort` | `ordering` | Initial sort field(s), using `-field` for descending. |
+| `pageSize` | `list_per_page` | Rows per page. |
+| `filters` | `list_filter` | Filter drawer definitions. |
+| `fieldsets` | `fieldsets` | Ordered collapsible form groups. |
+| `fieldOrder` | `fields` | Flat form order when fieldsets are absent. |
+| `readonlyFields` | `readonly_fields` | Visible, non-editable fields. |
+| `hiddenFields` | `exclude` | Fields omitted from admin forms and responses. |
+| `excludeFields` | `exclude` | Additional response-scrubbing fields. |
+| `autocompleteFields` | `autocomplete_fields` | Reference fields using async search. |
+| `fieldOverrides` | `formfield_overrides` | Per-field label/help/widget metadata. |
+| `adminPermissions` | `has_*_permission` | Admin-route permission method overrides. |
+| `adminFilter` | `get_queryset` | Server-enforced query constraint. |
+| `actions` | `actions` | Declarative bulk-patch/background actions. |
+| `bulkPatchAllowlist` | — | Fields accepted by bulk patch. |
+| `recordTitleField` | `__str__` | Field used for edit-page titles. |
+| `group` | `app_label` | Navigation group. |
+| `icon` | — | Navigation icon name. |
+| `realtime` | — | Emit scrubbed admin change events. |
+| `includeDeleted` | — | Reserved compatibility option. |
+
+## Supporting types
+
+`AdminFilter` has `field`, `kind`, and optional `label`. Kinds are `boolean`, `text`, `ref`,
+`dateRange`, and `choice`; refs add `refModel`, choices add `{label,value}[]`.
+
+`AdminFieldset` has `title`, `fields`, optional `description`, and optional `collapsed`.
+
+`AdminAction` has `id`, `label`, optional `confirm`, `background`, and `patchKeys`.
+
+`AdminContribution` may provide `models`, `customScreens`, `homeWidgets`, and `scripts`.
+Model contributions contain `model`, `routePath`, and `admin`. Duplicate `routePath`s
+throw for registered routers; the same Mongoose model at two paths gets unique config
+`name`s so the admin UI can route to each.
+
+## Legacy migration
+
+Move each object from `AdminApp.models` to the model's `modelRouter({admin: ...})`; remove
+`model` and `routePath` from the nested config because those come from the router registration.
+Plugin-owned models should come from `plugin.adminContribution()` instead of host duplication.

package/src/docs/versioned/next/reference/admin-frontend.md

@@ -71,6 +71,22 @@ Auto-generates fields from model schema:
 
 System fields (`_id`, `__v`, `created`, `updated`, `deleted`) are automatically skipped.
 
+### AdminRolesList
+
+Role editing starts with a dedicated **Admin page** toggle for `admin:access`. That is the only
+permission that opens the admin panel. Grant it first; model and tool permissions do nothing until
+the role can enter.
+
+Standard admin model permissions then use one access-level selector:
+
+- No access
+- Read only
+- Read + write owned
+- Read + write all
+
+Other application and screen permissions remain individual toggles. Saving writes the same
+permission JSON used by `rbacRouter`, so no separate configuration format is required.
+
 ### AdminFieldRenderer
 
 Renders field values in table cells with formatting.
@@ -201,5 +217,9 @@ const CustomFieldRenderer = ({value, field, ...props}) => {
 Expects backend to provide:
 1. `GET {baseUrl}/config` — Model metadata
 2. CRUD routes at `{basePath}{routePath}` for each model
-3. Admin authentication (`IsAdmin` permission)
+3. `admin:access` (or `IsAdmin` when RBAC is off) to open the page; per-model RBAC after that
 4. Paginated responses: `{data, page, limit, total, more}`
+
+When RBAC is enabled, `/admin/config` is filtered for the current user. `AdminShell` uses its
+`platformTools` flags to hide denied Scripts, Roles, Version, and Configuration links, and only
+renders model or custom-screen links returned by the server.

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

@@ -72,6 +72,7 @@ src/
   service/
     aiService.ts           # Provider-agnostic AI service
     fileStorage.ts         # GCS upload helper
+    getMCPTools.ts         # modelRouter MCP tools as Vercel AI SDK tools
     mcpService.ts          # MCP client connections
     parseAiJson.ts         # LLM JSON normalization/parsing
     prompts.ts             # System prompt constants
@@ -84,7 +85,8 @@ src/
 ## Key exports
 
 - **Plugins:** `AiApp`, `LangfuseApp`
-- **Service:** `AIService`, `TemperaturePresets`, `FileStorageService`, `MCPService`
+- **Service:** `AIService`, `TemperaturePresets`, `FileStorageService`, `MCPService`,
+  `getMCPTools`
 - **Models:** `AIRequest`, `GptHistory`, `FileAttachment`, `Project`
 - **Routes:** `addGptRoutes`, `addGptHistoryRoutes`, `addAiRequestsExplorerRoutes`, `addFileRoutes`, `addProjectRoutes`, `addMcpRoutes`
 - **Structured output:** `parseAiJson`, `normalizeLlmJsonTextForStructuredOutput`, re-exported `Output`, `jsonSchema`, `JSONValue`, `FlexibleSchema` from `ai`
@@ -393,6 +395,18 @@ await storage.getSignedUrl(gcsKey);  // 1-hour v4 signed URL
 await storage.delete(gcsKey);        // GCS delete + soft-delete FileAttachment
 ```
 
+## getMCPTools
+
+Wraps registered `modelRouter` MCP tools as Vercel AI SDK `Tool` objects for
+in-process `streamText` / `generateText`. HTTP MCP clients still use `POST /mcp`
+from `@terreno/api`; this helper is the chat-route path.
+
+```typescript
+import {getMCPTools} from "@terreno/ai";
+
+const tools = getMCPTools(req.user);
+```
+
 ## MCPService
 
 Manages SSE MCP client connections for tool calling.

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

@@ -5,6 +5,7 @@ REST API framework built on Express and Mongoose. Provides modelRouter (CRUD end
 ## Table of Contents
 
 - [Server Setup](#server-setup)
+- [MCP tools](#mcp-tools)
 - [Authentication](#authentication)
 - [Model Schema Conventions](#model-schema-conventions)
 - [Mongoose Plugins](#mongoose-plugins)
@@ -20,6 +21,7 @@ REST API framework built on Express and Mongoose. Provides modelRouter (CRUD end
 ## Key exports
 
 - `TerrenoApp`, `setupServer`, `modelRouter`, `Permissions`, `OwnerQueryFilter`
+- `registerMCPTool`, `getMCPRegistry`
 - `APIError`, `logger`, `asyncHandler`, `authenticateMiddleware`
 - Logging: `logger`, `createScopedLogger`, `createFeatureFlaggedLogger`, `setupLogging`, `formatLogContextSuffix`
 - Correlation: `runWithRequestContext`, `getCurrentLogContext`, `requestContextMiddleware`, `REQUEST_CONTEXT_ATTRIBUTE_NAMES`
@@ -84,6 +86,22 @@ setupServer({
 
 Both patterns create the same middleware stack (CORS, auth, logging, OpenAPI).
 
+## MCP tools
+
+Opt a model into Model Context Protocol tools with `mcp` on `modelRouter`. `TerrenoApp` mounts `POST /mcp` when any model has `mcp` or a custom tool is registered.
+
+```typescript
+const todoRouter = modelRouter("/todos", Todo, {
+  mcp: {
+    excludeFields: ["ownerId"],
+    methods: ["list", "read", "create", "update", "delete"],
+  },
+  permissions: { /* same as REST */ },
+});
+```
+
+Cross-model tools use `registerMCPTool` (see the example backend's `users_todo_statuses`). How-to: [Expose MCP tools](../how-to/expose-mcp-tools.md). In-process Vercel AI SDK wrappers: `getMCPTools` from `@terreno/ai`.
+
 ## Authentication
 
 @terreno/api includes built-in authentication with multiple strategies: