@terreno/mcp 57.0.0 → 57.2.0

package/dist/docs/versioned/next/tasks/model-router-mcp.md

@@ -6,78 +6,78 @@
 
 ### Phase 1: Core MCP Infrastructure
 
-- [ ] **Task 1.1**: Define MCP types and interfaces
+- [x] **Task 1.1**: Define MCP types and interfaces
   - Description: Create `MCPConfig` interface (with `methods` defaulting to `['list', 'read']`, `excludeFields` for hiding sensitive fields, `maxLimit` defaulting to 50), `MCPRegistryEntry`, and add `mcp?: MCPConfig` to `ModelRouterOptions`. Create the `api/src/mcp/` directory structure.
   - Files: `api/src/mcp/types.ts`, `api/src/mcp/index.ts`, `api/src/api.ts` (add mcp to ModelRouterOptions)
   - Depends on: none
   - Acceptance: Types compile, existing tests still pass, `mcp` is an optional field on `ModelRouterOptions`
 
-- [ ] **Task 1.2**: Build MCP tool registry
-  - Description: Create a global registry that collects MCP tool entries as `modelRouter()` is called. When a modelRouter has `mcp` config, it pushes an entry to the registry. Export `getMCPRegistry()` internally and `getMCPTools()` publicly (returns `Record<string, CoreTool>`).
+- [x] **Task 1.2**: Build MCP tool registry
+  - Description: Create a global registry that collects MCP tool entries as `modelRouter()` is called. When a modelRouter has `mcp` config, it pushes an entry to the registry. Export `getMCPRegistry()` from `@terreno/api`. Vercel AI SDK wrapping lives in `getMCPTools()` on `@terreno/ai`.
   - Files: `api/src/mcp/registry.ts`, `api/src/mcp/index.ts`, `api/src/api.ts` (register in modelRouter function)
   - Depends on: Task 1.1
-  - Acceptance: Calling `modelRouter(Todo, { ..., mcp: { methods: ['list', 'read'] } })` adds entries to the registry. `getMCPTools()` returns CoreTool objects.
+  - Acceptance: Calling `modelRouter(Todo, { ..., mcp: { methods: ['list', 'read'] } })` adds entries to the registry. `getMCPRegistry()` returns those entries.
 
-- [ ] **Task 1.3**: Generate Zod schemas from Mongoose models
+- [x] **Task 1.3**: Generate Zod schemas from Mongoose models
   - Description: Build a utility that converts a Mongoose model's schema into Zod schemas suitable for MCP tool `inputSchema`. Handle common field types (String, Number, Boolean, Date, ObjectId, Array, Mixed). Generate separate schemas for create (required fields), update (all optional + id required), read (id + optional populate), list (queryFields + pagination), and delete (id only). Respect `excludeFields` — omit listed fields from all generated schemas.
   - Files: `api/src/mcp/schemaGenerator.ts`, `api/src/mcp/schemaGenerator.test.ts`
   - Depends on: Task 1.1
   - Acceptance: Given a Mongoose model, produces valid Zod schemas for each CRUD method. Tests cover all common field types. `excludeFields` removes specified fields from schemas.
 
-- [ ] **Task 1.4**: Generate MCP tool definitions from registry entries
+- [x] **Task 1.4**: Generate MCP tool definitions from registry entries
   - Description: Build tool generator that takes an `MCPRegistryEntry` and produces both `@modelcontextprotocol/sdk` `Tool` objects (JSON Schema input) and Vercel `ai` SDK `CoreTool` objects. Auto-generate descriptions from model name, fields, and queryFields. Apply `toolPrefix` naming (`{prefix}_{method}`). Only generate tools for methods listed in `mcp.methods`.
   - Files: `api/src/mcp/toolGenerator.ts`, `api/src/mcp/toolGenerator.test.ts`
   - Depends on: Task 1.2, Task 1.3
   - Acceptance: Registry entry with `methods: ['list', 'read']` produces exactly `todos_list` and `todos_read` tools with correct schemas and descriptions.
 
-- [ ] **Task 1.5**: Implement MCP tool handlers (CRUD execution)
+- [x] **Task 1.5**: Implement MCP tool handlers (CRUD execution)
   - Description: Build the execute functions for each CRUD tool. Each handler: (1) extracts user from auth context, (2) checks permissions via `checkPermissions()`, (3) for read/update/delete: loads document and checks object-level permissions, (4) applies queryFilter and population for list, (5) enforces `maxLimit` cap on list results (default 50), (6) runs pre/post hooks, (7) strips `excludeFields` from response data, (8) serializes via `mcpResponseHandler` or default. Reuse internal logic from REST handlers but decoupled from Express req/res.
   - Files: `api/src/mcp/handlers.ts`, `api/src/mcp/handlers.test.ts`
   - Depends on: Task 1.4
   - Acceptance: Each CRUD handler works with correct permission checks, population, filtering. List enforces maxLimit. excludeFields are stripped from responses. Tests cover: successful CRUD, permission denied (403), not found (404), validation errors, owner filtering, population, maxLimit enforcement, excludeFields stripping.
 
-- [ ] **Task 1.6**: Auth-agnostic user extraction for MCP
+- [x] **Task 1.6**: Auth-agnostic user extraction for MCP
   - Description: Build middleware/utility that extracts user from MCP transport headers using whichever auth provider is configured (JWT via passport or Better Auth via `auth.api.getSession()`). Should mirror `authenticateMiddleware` behavior but work with raw headers instead of Express req.
   - Files: `api/src/mcp/auth.ts`, `api/src/mcp/auth.test.ts`
   - Depends on: Task 1.1
   - Acceptance: Given headers with a valid JWT, returns User. Given headers with a valid Better Auth session token, returns User. Given no/invalid headers with `allowAnonymous: false`, returns null. Works with both auth providers.
 
-- [ ] **Task 1.7**: Mount MCP server in TerrenoApp
+- [x] **Task 1.7**: Mount MCP server in TerrenoApp
   - Description: In `TerrenoApp`'s startup flow, check if the MCP registry has any entries. If so, create an `McpServer` instance from `@modelcontextprotocol/sdk`, register all tools from the registry, set up `StreamableHTTPServerTransport`, and mount on `/mcp`. Wire up `ListToolsRequestSchema` and `CallToolRequestSchema` handlers.
   - Files: `api/src/mcp/server.ts`, `api/src/expressServer.ts` (or TerrenoApp equivalent — integrate into startup)
   - Depends on: Task 1.4, Task 1.5, Task 1.6
   - Acceptance: Starting a TerrenoApp with MCP-configured models auto-mounts `/mcp`. MCP clients can list tools and call them. No MCP config = no `/mcp` endpoint.
 
-- [ ] **Task 1.8**: Integration tests
+- [x] **Task 1.8**: Integration tests
   - Description: End-to-end tests that spin up a TerrenoApp with MCP-configured models and test the full flow: MCP client connects, lists tools, performs CRUD via tool calls, verifies permissions block unauthorized access, verifies population and query filtering work.
   - Files: `api/src/mcp/integration.test.ts`
   - Depends on: Task 1.7
   - Acceptance: Full CRUD lifecycle works over MCP. Permission denials return appropriate errors. Owner filtering restricts results. Population returns nested data.
 
-- [ ] **Task 1.9**: Export public API
-  - Description: Export `MCPConfig`, `getMCPTools()`, and any other public interfaces from `@terreno/api`'s main index. Update package exports.
-  - Files: `api/src/index.ts`, `api/src/mcp/index.ts`
+- [x] **Task 1.9**: Export public API
+  - Description: Export `MCPConfig` and MCP registry/server helpers from `@terreno/api`. Export `getMCPTools()` from `@terreno/ai` so the Vercel `ai` SDK stays out of `@terreno/api`.
+  - Files: `api/src/index.ts`, `ai/src/index.ts`, `ai/src/service/getMCPTools.ts`
   - Depends on: Task 1.7
-  - Acceptance: Consumers can `import { MCPConfig, getMCPTools } from "@terreno/api"`.
+  - Acceptance: Consumers can `import { MCPConfig } from "@terreno/api"` and `import { getMCPTools } from "@terreno/ai"`.
 
 ---
 
 ### Phase 2: Frontend Integration
 
-- [ ] **Task 2.1**: `useTerrenoChat` hook
+- [x] **Task 2.1**: `useTerrenoChat` hook
   - Description: Create a hook wrapping `@ai-sdk/react`'s `useChat()` pre-configured for a Terreno MCP backend. Handles Bearer token injection from auth state (reads from Redux store — JWT token or Better Auth session). Accepts `baseURL` and optional `tools` override.
-  - Files: `rtk/src/useTerrenoChat.ts`, `rtk/src/useTerrenoChat.test.ts`
+  - Files: `rtk/src/useTerrenoChat.ts`
   - Depends on: Task 1.7
   - Acceptance: Hook connects to MCP-enabled backend, streams responses with tool calls, injects auth token automatically.
 
-- [ ] **Task 2.2**: `useMCPTools` hook
-  - Description: Create a hook that discovers available MCP tools from the backend. Uses `@ai-sdk/mcp`'s `createMCPClient()` to connect and list tools. Caches result. Returns typed tool list.
-  - Files: `rtk/src/useMCPTools.ts`, `rtk/src/useMCPTools.test.ts`
+- [x] **Task 2.2**: `useMCPTools` hook
+  - Description: Create a hook that discovers available MCP tools from the backend via JSON-RPC call to /mcp endpoint. Caches result. Returns typed tool list.
+  - Files: `rtk/src/useMCPTools.ts`
   - Depends on: Task 1.7
   - Acceptance: Hook returns list of available tools with names, descriptions, and input schemas. Handles connection errors gracefully.
 
-- [ ] **Task 2.3**: Export frontend public API
-  - Description: Export `useTerrenoChat` and `useMCPTools` from `@terreno/rtk`. Add `@ai-sdk/react` and `@ai-sdk/mcp` as dependencies.
+- [x] **Task 2.3**: Export frontend public API
+  - Description: Export `useTerrenoChat` and `useMCPTools` from `@terreno/rtk`. Add `@ai-sdk/react` and `ai` as dependencies.
   - Files: `rtk/src/index.ts`, `rtk/package.json`
   - Depends on: Task 2.1, Task 2.2
   - Acceptance: Consumers can `import { useTerrenoChat, useMCPTools } from "@terreno/rtk"`.
@@ -86,19 +86,19 @@
 
 ### Phase 3: Examples & Polish
 
-- [ ] **Task 3.1**: Add MCP config to example backend models
-  - Description: Add `mcp` config to the existing Todo and Food models in `example-backend`. Todos: read-only (`list`, `read`). Food: full CRUD. Include `mcpResponseHandler` example on one model.
-  - Files: `example-backend/src/routes/todos.ts`, `example-backend/src/routes/food.ts`
+- [x] **Task 3.1**: Add MCP config to example backend models
+  - Description: Add `mcp` config to the existing Todo and User models in `example-backend`. Todos: read-only (`list`, `read`) with excludeFields. Users: read-only (`list`, `read`) with sensitive fields excluded.
+  - Files: `example-backend/src/api/todos.ts`, `example-backend/src/api/users.ts`
   - Depends on: Task 1.9
-  - Acceptance: Starting example-backend mounts `/mcp` with todo and food tools. MCP client can list and call them.
+  - Acceptance: Starting example-backend mounts `/mcp` with todo and user tools. MCP client can list and call them.
 
-- [ ] **Task 3.2**: Demo chat screen in example frontend
+- [x] **Task 3.2**: Demo chat screen in example frontend
   - Description: Add a simple chat screen to `example-frontend` that uses `useTerrenoChat()` to connect to the MCP-enabled backend. Show tool calls inline (e.g., "Searching todos..." with results). Navigation from home screen.
   - Files: `example-frontend/app/chat.tsx`, `example-frontend/app/_layout.tsx` (add nav)
   - Depends on: Task 2.3, Task 3.1
   - Acceptance: User can chat with the AI, which calls MCP tools to query/modify data. Tool calls and results visible in the UI.
 
-- [ ] **Task 3.3**: Refine auto-generated tool descriptions
+- [x] **Task 3.3**: Refine auto-generated tool descriptions
   - Description: Improve description generation quality. Include field types, required vs optional, enum values, ref model names. Test with multiple model shapes to ensure descriptions are helpful for LLMs.
   - Files: `api/src/mcp/toolGenerator.ts`, `api/src/mcp/toolGenerator.test.ts`
   - Depends on: Task 1.4

package/dist/docs/versioned/next/tasks/offline-mode.md

@@ -1,5 +1,7 @@
 # Task List: Offline Mode
 
+**Status:** Closed (2026-08-20) — IP deferred; superseded by `@terreno/syncdb`. Open tasks below will not be executed.
+
 *Structured task breakdown for automated implementation. Each task should be independently implementable and testable.*
 
 ## Phase 1: RTK Core Offline Framework

package/dist/docs/versioned/next/tasks/org-management-ui.md

@@ -0,0 +1,107 @@
+# Tasks: Organizations as a first-class primitive (admin UI + RBAC)
+
+IP: [org-management-ui](../implementationPlans/org-management-ui.md)
+
+Supporting skills (all tasks): `update-docs`. Models: `mongoose-schema-safety`. API tests: `backend-test-env`. Admin UI: `terreno-ui`, `building-terreno-apps`, `verify-ui-changes`. SDK: `generate-sdk`. Data: `terreno-data-fetching`.
+
+## Phase 1 — Models + context
+
+- [ ] **Task 1.1**: Organization + Membership models
+  - Delivers: persist orgs and per-org `roleName` (`org-admin` \| `member`)
+  - Files: `api/src/orgs/organizationModel.ts`, types, `api/src/orgs/*.test.ts`
+  - Blocked by: none
+  - Docs: field `description`s (OpenAPI); note in `docs/reference/api.md` stub section if the page is updated later in 6.1
+  - Acceptance: unit tests for compound unique index and duplicate membership rejection
+- [ ] **Task 1.2**: `orgScopedPlugin`
+  - Delivers: required indexed `organizationId` on consumer schemas
+  - Files: `api/src/orgs/orgPlugin.ts` + tests
+  - Blocked by: 1.1
+  - Docs: none until 6.1
+  - Acceptance: save without org fails; index present
+- [ ] **Task 1.3**: Org context middleware + `OrgQueryFilter`
+  - Delivers: Q13 header matrix; lists never cross orgs
+  - Files: `api/src/orgs/orgContext.ts`, `orgPermissions.ts`, `api/src/permissions.ts` (stop using `User.organizationIds`)
+  - Blocked by: 1.1, 1.2
+  - Docs: none until 6.1
+  - Acceptance: supertest — operator missing header on scoped list → 400; org-admin of one org omits header → scoped; org A member never reads org B including `$or` / query-param attacks; non-member header → 403
+
+## Phase 2 — RBAC
+
+- [ ] **Task 2.1**: `organization` statements + `operator` role + membership-scoped `org-admin`
+  - Delivers: platform vs org grants as in the IP tables
+  - Files: `api/src/rbac/statements.ts`, `roleModel.ts`, resolve/can path for Membership `roleName`, tests
+  - Blocked by: 1.3
+  - Docs: `docs/reference/api.md` RBAC/org note (or 6.1)
+  - Acceptance: `org-admin` on org A cannot `organization:list` all orgs; `operator` can; `user.roles` containing `org-admin` is not how grants work (test that membership wins)
+
+## Phase 3 — OrgsApp routes
+
+- [ ] **Task 3.1**: Operator org CRUD + `/orgs/mine`
+  - Delivers: create/list-all/mine/read/patch/soft-delete + `onOrgAudit`
+  - Files: `api/src/orgs/orgsApp.ts`, exports, OpenAPI, supertest
+  - Blocked by: 2.1
+  - Docs: none until 6.1
+  - Acceptance: org-admin 403 on `GET /orgs`; operator 200; create does not require membership; disable/soft-delete suspends memberships
+- [ ] **Task 3.2**: Members attach / patch / delete + last-admin guards
+  - Delivers: existing-user attach; no email; last `org-admin` protected
+  - Files: `api/src/orgs/orgsApp.ts` + tests
+  - Blocked by: 3.1
+  - Docs: none until 6.1
+  - Acceptance: attach by email of existing user; unknown email 404; demote last org-admin 400; no comms/send invoked
+
+## Phase 4 — Admin backend
+
+- [ ] **Task 4.1**: Admin org routes + AdminApp tenant context
+  - Delivers: admin UI can call org APIs; generic admin model lists use context filter
+  - Files: `admin-backend/src/*` (org registration or aliases), AdminApp queryFilter/preCreate, tests
+  - Blocked by: 3.2
+  - Docs: `docs/reference/admin-backend.md` org section (may land with 6.1)
+  - Acceptance: operator `/admin` list of an org-scoped model without header → 400; with header → only that org; org-admin cannot hit all-orgs admin list
+
+## Phase 5 — Admin frontend
+
+- [ ] **Task 5.1**: `OrgDirectoryScreen` (operator)
+  - Delivers: all-orgs table, create, disable, enter org
+  - Files: `admin-frontend/src/orgs/OrgDirectoryScreen.tsx` + tests
+  - Blocked by: 4.1
+  - Docs: `docs/reference/admin-frontend.md` component section
+  - Acceptance: loading/error/empty; org-admin nav hidden in unit test via role prop/fixture
+- [ ] **Task 5.2**: `OrgSwitcher` + `useOrgContext` (header + URL)
+  - Delivers: Q10/Q13 client behavior for org-admins and operators-in-org
+  - Files: `admin-frontend/src/orgs/OrgSwitcher.tsx`, `useOrgContext.tsx`, `AdminShellLayout` slot
+  - Blocked by: 5.1
+  - Docs: admin-frontend reference
+  - Acceptance: switching sets `X-Organization-Id` on subsequent admin queries (test with mocked api); single-org org-admin still renders org name
+- [ ] **Task 5.3**: Org settings + members table
+  - Delivers: settings PATCH; members DataTable; add existing user; last-admin error; disabled Invite; billing placeholder
+  - Files: `admin-frontend/src/orgs/OrgSettingsScreen.tsx`, `OrgMembersScreen.tsx` + tests
+  - Blocked by: 5.2, 3.2
+  - Docs: admin-frontend reference
+  - Acceptance: Invite control disabled; billing placeholder visible; last-admin error shown
+- [ ] **Task 5.4**: Host wiring — admin-spa + example-frontend `/admin`
+  - Delivers: routes on both hosts; SDK regen
+  - Files: `admin-spa/app/orgs/*`, `example-frontend/app/admin/orgs/*`, `example-frontend/store/openApiSdk.ts` (generated)
+  - Blocked by: 5.3
+  - Docs: `docs/reference/admin-spa.md` nav entry
+  - Acceptance: `cd example-frontend && bun run sdk` compiles; both apps have `/admin/orgs` routes
+- [ ] **Task 5.5**: Frontend verification
+  - Delivers: evidence org-admin vs operator flows
+  - Files: `/opt/cursor/artifacts/` (not in repo)
+  - Blocked by: 5.4, 6.2
+  - Docs: none
+  - Acceptance: login operator → directory → create/open org → members; login org-admin → no directory → switcher → members only that org; screenshots/video on the PR (`verify-ui-changes`)
+
+## Phase 6 — Example + docs
+
+- [ ] **Task 6.1**: Docs (same slice as behavior; can land incrementally but must be complete before Brew)
+  - Delivers: stranger can operate orgs from docs
+  - Files: `docs/how-to/add-organizations.md`, `docs/explanation/organizations.md`, `docs/reference/api.md`, `docs/reference/admin-backend.md`, `docs/reference/admin-frontend.md`, `docs/reference/admin-spa.md`, `.rulesync/**` if agent rules need org context
+  - Blocked by: 4.1 (content must match shipped routes)
+  - Docs: (this task)
+  - Acceptance: `bun run website:build` (or package docs check used in CI); how-to has one minimal OrgsApp + AdminApp example
+- [ ] **Task 6.2**: example-backend migration + seeds
+  - Delivers: Membership instead of `User.organizationIds`; operator + two org-admins
+  - Files: `example-backend/src/models/user.ts`, `types/models/userTypes.ts`, `api/projects.ts`, `scripts/seed-*`, `access.ts`, `rbacRoles.ts`, tests
+  - Blocked by: 3.2, 2.1
+  - Docs: seed users named in `docs/how-to/add-organizations.md`
+  - Acceptance: grep finds no `organizationIds` on User; isolation tests pass; seed creates operator@example.com

package/dist/docs/versioned/next/tasks/orgs-and-teams.md

@@ -1,6 +1,8 @@
 # Tasks: Organizations, teams, and multi-tenant scoping
 
-IP: [orgs-and-teams](../implementationPlans/orgs-and-teams.md)
+**Superseded.** Do not execute. Canonical tasks: [org-management-ui](org-management-ui.md).
+
+IP: [orgs-and-teams](../implementationPlans/orgs-and-teams.md) (superseded by [org-management-ui](../implementationPlans/org-management-ui.md))
 
 ## Phase 1 — Models + plugin
 

package/dist/docs/versioned/next/tasks/pluggable-database-sqlite.md

@@ -0,0 +1,44 @@
+# Tasks: Pluggable database layer and SQLite adapter
+
+IP: [pluggable-database-sqlite.md](../implementationPlans/pluggable-database-sqlite.md)
+
+## Phase 1 — Adapter seam + Mongoose adapter (no behavior change)
+
+- [ ] Define `DatabaseAdapter`, `AdapterCollection`, `AdapterCapabilities`, `PopulatePath`, and `MongoFilter` types in `api/src/db/adapter.ts`
+- [ ] Implement `MongooseAdapter` in `api/src/db/mongooseAdapter.ts` delegating to today's exact Mongoose calls (including the `docLoader.ts` native soft-delete probe)
+- [ ] Refactor `api/src/api.ts` list/read/create/update/delete/array handlers to use the adapter
+- [ ] Refactor `api/src/sync/executors.ts` and `api/src/docLoader.ts` to use the adapter
+- [ ] Refactor permissions doc loading (`permissionMiddleware`) to use the adapter
+- [ ] Add `TerrenoAppOptions.database` with Mongoose adapter default; export adapter types + `mongooseAdapter()` from `api/src/index.ts`
+- [ ] Add capability checks (`changeStreams`, `transactions`, `textSearch`) to realtime, syncdb, feature-flag, and search registration paths (all pass on Mongo)
+- [ ] Gate: full existing api test suite green with zero test edits
+
+## Phase 2 — @terreno/db-sqlite core
+
+- [ ] Scaffold `db-sqlite/` workspace package (catalog deps, tsconfig, biome, CI wiring)
+- [ ] Driver injection layer (`bun:sqlite` default; accept `better-sqlite3` / `node:sqlite` / `libsql` handles); connection defaults (WAL, busy_timeout, foreign_keys off)
+- [ ] Schema → DDL mapping per the IP table (String/Number/Boolean/Date/ObjectId/enum/JSON/`DateOnly`/`_id`/`__v`; NOT NULL; JS-layer defaults; indexes incl. unique + sparse-as-partial)
+- [ ] `ensureSchema` additive migration with `_terreno_schema` metadata table; destructive changes → startup error + generated SQL file
+- [ ] CRUD: create / findById / save (validate + changed-path persist) / delete (soft + hard) with `model.hydrate()` documents
+- [ ] Plugin semantics: created/updated timestamps, soft-delete read filter, `__v` optimistic-concurrency conflict path, document save middleware via the hook registry
+- [ ] Query compiler for the modelRouter filter subset (equality, `$in/$nin/$ne/$exists/$gt/$gte/$lt/$lte`, `$and`/`$or`, date ranges) incl. `json_extract` and `json_each` paths; unknown operators → 400
+- [ ] Sort / skip / limit / count
+- [ ] Population: batched two-phase loads per path, field selection in SQL, single + array refs, dangling ref → null, soft-delete filter on referenced models, populate on findById/list and post-create/update re-reads
+- [ ] Adapter conformance suite in `api/src/db/conformance/` (CRUD, query operators, pagination, plugins, population) run against both adapters
+
+## Phase 3 — Auth + capability hardening
+
+- [ ] `adapter.getBetterAuthDatabase()` seam in `betterAuthSetup.ts` (Mongo adapter returns today's `mongodbAdapter` client)
+- [ ] Better Auth on SQLite: driver handle → Kysely adapter; schema tables created from `ensureSchema` via Better Auth migration tooling; signup/login/session → `req.user` end-to-end test
+- [ ] Gate `setupAuth`/passport path to the Mongo adapter with an actionable startup error
+- [ ] Startup errors for missing capabilities name the capability and the feature that needs it (tested)
+- [ ] `@terreno/test`: `TERRENO_TEST_DB=sqlite` mode (temp-file DB per suite, no mongod)
+
+## Phase 4 — Example, docs, and integration
+
+- [ ] `example-backend` `DB_ADAPTER=sqlite` mode: adapter wiring, skip change-stream features via capability flags, seed script works, boot + CRUD smoke test with no mongod
+- [ ] Parity checks: `/openapi.json` and admin `/admin/config` identical across adapters for example models
+- [ ] Docs: `docs/how-to/run-on-sqlite.md`, `docs/explanation/database-adapters.md`; update positioning docs' MongoDB-only claims
+- [ ] MCP: `terreno_generate_model` / bootstrap templates mention adapter choice
+- [ ] Changelog + upgrade note (no action needed for existing apps)
+- [ ] `bun run lint`, `bun run compile`, api + db-sqlite tests green in CI

package/dist/docs/versioned/next/tasks/public-roadmap-github.md

@@ -80,7 +80,7 @@ See: [`docs/implementationPlans/public-roadmap-github.md`](../implementationPlan
   - Acceptance: workflow parses as valid YAML; the secret-validation step lists every required variable; the commit step is conditional on a real diff.
 
 - [x] **Task 4.3**: Seed `ROADMAP.md` and link it
-  - Description: Commit an initial hand-written `ROADMAP.md` (the generator will overwrite it later) built from the IPs in `docs/implementationPlans/oss-launch-program.md` plus the active plans in `PLAN_INDEX.md`. Add a note at the top that it is generated from the Project board. Link it from `README.md` and add it to the docs site sidebar in `website/docusaurus.config.ts` (or the sidebars file if navigation is defined there — check both).
+  - Description: Commit an initial hand-written `ROADMAP.md` (the generator will overwrite it later) built from the IPs in `docs/implementationPlans/oss-launch-program.md` plus active IPs (those whose `**Status:**` header is not Complete/Deferred/Closed). Add a note at the top that it is generated from the Project board. Link it from `README.md` and add it to the docs site sidebar in `website/docusaurus.config.ts` (or the sidebars file if navigation is defined there — check both).
   - Files: `ROADMAP.md` (new), `README.md`, `website/docusaurus.config.ts` or `website/sidebars.ts`
   - Depends on: Task 4.1
   - Acceptance: `ROADMAP.md` lists every IP in the program with a `Target`; the docs site builds (`bun run website:build`) with the new nav entry; the README links it.

package/dist/docs/versioned/next/tasks/rtk-to-syncdb-migration-docs.md

@@ -42,13 +42,13 @@ See: [`docs/implementationPlans/rtk-to-syncdb-migration-docs.md`](../implementat
   - Depends on: Task 1.1
   - Acceptance: every documented symbol exists in the inventory; every config option lists a type and default; no `TODO` or placeholder text remains.
 
-- [ ] **Task 2.2**: Remove `rtk.md` from the public reference index
+- [x] **Task 2.2**: Remove `rtk.md` from the public reference index
   - Description: Per IP decision M4 (P7 A), remove `docs/reference/rtk.md` from the public reference tree — do **not** maintain a parallel RTK reference page at launch. Add a Docusaurus redirect from the old URL to `docs/how-to/migrate-rtk-to-syncdb.md`. Archive the pre-launch `rtk.md` content only if inbound links require it (e.g. under `docs/reference/legacy/` with a deprecation banner), but do not list it in `docs/reference/README.md`.
   - Files: `docs/reference/rtk.md` (removed or archived), `website/docusaurus.config.ts`, `docs/reference/README.md`
   - Depends on: Task 2.1
   - Acceptance: `docs/reference/README.md` has no RTK entry; the old URL redirects to the migration guide; no launch doc presents RTK as a supported reference path.
 
-- [ ] **Task 2.3**: Update the reference and docs indexes
+- [x] **Task 2.3**: Update the reference and docs indexes
   - Description: Update `docs/reference/README.md` and `docs/README.md`: add `@terreno/syncdb` and `@terreno/ai` to the package table (`ai` is currently missing entirely), add `@terreno/admin-spa` and `@terreno/feature-flags` if absent. Do **not** list `rtk` in the public reference index per M4 — link the migration guide from a "Migrating from RTK" note instead. Confirm every shipped package in `publish-on-tag.yml` appears exactly once in the appropriate section.
   - Files: `docs/reference/README.md`, `docs/README.md`
   - Depends on: Task 2.2
@@ -80,7 +80,7 @@ See: [`docs/implementationPlans/rtk-to-syncdb-migration-docs.md`](../implementat
   - Depends on: Task 3.3
   - Acceptance: all eleven sections complete; the rollback section states what local data survives; the checklist has no step absent from the body; the guide is listed in `docs/how-to/README.md`.
 
-- [ ] **Task 3.5**: Validate the guide by performing the migration
+- [x] **Task 3.5**: Validate the guide by performing the migration
   - Description: On a scratch branch, take a screen in `example-frontend` that #869 did **not** migrate and migrate it following only the guide. Record every point where the guide was insufficient. Fix the guide. Then revert the scratch branch — the migration itself is not part of this IP's deliverable, only the guide corrections are.
   - Files: `docs/how-to/migrate-rtk-to-syncdb.md`
   - Depends on: Task 3.4
@@ -88,13 +88,13 @@ See: [`docs/implementationPlans/rtk-to-syncdb-migration-docs.md`](../implementat
 
 ## Phase 4: Explainers and auth repositioning
 
-- [ ] **Task 4.1**: Write `docs/explanation/local-first-data.md`
+- [x] **Task 4.1**: Write `docs/explanation/local-first-data.md`
   - Description: Conceptual explainer, no step-by-step. Cover: what local-first means here (local DB is the UI source of truth, server is the authority), the mental-model shift from request/response to apply-locally-then-reconcile, what the developer stops having to think about (loading states on writes, manual optimistic updates, refetch orchestration), what they must newly think about (conflicts, sync status, encryption at rest, key lifecycle on logout), and the tradeoffs versus server-first fetching. Link the migration guide and the syncdb reference.
   - Files: `docs/explanation/local-first-data.md` (new)
   - Depends on: Task 2.1
   - Acceptance: no shell commands or step lists; names at least three things developers stop doing and three they start doing; linked from `docs/explanation/README.md` if one exists.
 
-- [ ] **Task 4.2**: Reposition authentication documentation
+- [x] **Task 4.2**: Reposition authentication documentation
   - Description: Rewrite `docs/explanation/authentication.md` so Better Auth is the primary path and JWT/Passport is described as legacy with its support status. Update `docs/how-to/configure-better-auth.md` to drop "optional"/"alternative" framing and present it as the default setup. Add a short decision section: when a consumer would still choose JWT (existing deployment, custom token requirements). Verify every claim against `api/src/betterAuth*.ts` and the #869 socket auth changes.
   - Files: `docs/explanation/authentication.md`, `docs/how-to/configure-better-auth.md`
   - Depends on: Task 3.3
@@ -102,25 +102,25 @@ See: [`docs/implementationPlans/rtk-to-syncdb-migration-docs.md`](../implementat
 
 ## Phase 5: Agent surfaces
 
-- [ ] **Task 5.1**: Add syncdb agent rules and mark RTK rules legacy
+- [x] **Task 5.1**: Add syncdb agent rules and mark RTK rules legacy
   - Description: Create `.rulesync/rules/syncdb/00-syncdb.md` following the structure of `.rulesync/rules/rtk/00-rtk.md` (commands, architecture, key exports, usage patterns, conventions, testing). Add a legacy banner to the top of the RTK rule file stating that new code must use syncdb and that the RTK rules exist only for maintaining existing consumers. Run `bun run rules` and commit all mirrors.
   - Files: `.rulesync/rules/syncdb/00-syncdb.md` (new), `.rulesync/rules/rtk/00-rtk.md`, generated mirrors
   - Depends on: Task 2.1
   - Acceptance: `bun run rules:check` exits 0; the syncdb rule documents only APIs from the inventory; the RTK rule's first line marks it legacy.
 
-- [ ] **Task 5.2**: Update the SDK codegen skill
+- [x] **Task 5.2**: Update the SDK codegen skill
   - Description: Rewrite `.rulesync/skills/generate-sdk/SKILL.md` for the syncdb codegen path. Keep an explicitly-labeled legacy branch for consumers still on RTK during the support window. Update the trigger description, the prerequisite list, the command, the output file path, and the "never edit the generated file" warning to name the correct file. Regenerate mirrors.
   - Files: `.rulesync/skills/generate-sdk/SKILL.md`, generated mirrors
   - Depends on: Task 3.4
   - Acceptance: the skill's primary path produces a working generated file when run against `example-backend`; the legacy branch is clearly labeled; `bun run rules:check` exits 0.
 
-- [ ] **Task 5.3**: Update root agent context files
+- [x] **Task 5.3**: Update root agent context files
   - Description: Update `AGENTS.md`, `CLAUDE.md`, and `CLAUDE-consumer.md`: replace the `@terreno/rtk` package description and the "always use generated SDK hooks" guidance with the syncdb equivalent, update the architecture diagram, and add a short legacy note pointing at the migration guide. Do not change unrelated sections. Note that `CLAUDE.local.md` also contains a stale copy — either update or delete it (it appears to be an outdated duplicate; confirm before deleting).
   - Files: `AGENTS.md`, `CLAUDE.md`, `CLAUDE-consumer.md`, possibly `CLAUDE.local.md`
   - Depends on: Task 5.1
   - Acceptance: no root agent file instructs writing RTK Query code for new work; the architecture diagram names syncdb; `bun run rules:check` exits 0.
 
-- [ ] **Task 5.4**: Update MCP resources and bootstrap templates
+- [x] **Task 5.4**: Update MCP resources and bootstrap templates
   - Description: Update `mcp-server/src/docs/resources/*.md` (the `terreno://docs/rtk` resource and the patterns/overview bundles) and every file under `mcp-server/src/docs/templates/bootstrap/` that wires the Redux store, auth slice, or RTK hooks. A bootstrapped app must run on syncdb + Better Auth. Also check `mcp-server/src/prompts.ts` for RTK-specific prompt text.
   - Files: `mcp-server/src/docs/resources/*.md`, `mcp-server/src/docs/templates/bootstrap/**`, `mcp-server/src/prompts.ts`
   - Depends on: Task 5.1
@@ -128,37 +128,37 @@ See: [`docs/implementationPlans/rtk-to-syncdb-migration-docs.md`](../implementat
 
 ## Phase 6: Deprecation signalling
 
-- [ ] **Task 6.1**: Add the deprecation notice to `rtk/README.md`
+- [x] **Task 6.1**: Add the deprecation notice to `rtk/README.md`
   - Description: Add a notice block at the very top of `rtk/README.md`: deprecated as of version X, supported through version Y, superseded by `@terreno/syncdb`, link the migration guide. Do not remove existing content.
   - Files: `rtk/README.md`
   - Depends on: Task 2.2
   - Acceptance: the notice is the first content after the title; versions are concrete, not placeholders.
 
-- [ ] **Task 6.2**: Add the changelog entry
+- [x] **Task 6.2**: Add the changelog entry
   - Description: Add a `Deprecated` entry to the root `CHANGELOG.md` under the release that includes #869, naming `@terreno/rtk`, the support window, and the migration guide link. Add the corresponding `Added` entry for `@terreno/syncdb`.
   - Files: `CHANGELOG.md`
   - Depends on: Task 6.1
   - Acceptance: both entries exist under the correct version heading; the migration guide link resolves.
 
-- [ ] **Task 6.3**: Write the upgrade note
+- [x] **Task 6.3**: Write the upgrade note
   - Description: Create `mcp-server/src/docs/upgrades/<version>.md` for the release containing #869, following the format of the existing `0.20.0.md` and `0.21.0.md` notes. Include: what changed, whether action is required, the auth-then-data migration order, links to the migration guide, and before/after snippets for the two most common changes (a read hook and a write hook).
   - Files: `mcp-server/src/docs/upgrades/<version>.md` (new)
   - Depends on: Task 3.4
   - Acceptance: `terreno_get_upgrade_guide` with a range spanning this version returns the note; the format matches the existing notes.
 
-- [ ] **Task 6.4**: Draft the announcement post
+- [x] **Task 6.4**: Draft the announcement post
   - Description: Add the announcement body to `docs/explanation/roadmap-process.md` under a "Drafted announcements" heading (or to a new `docs/explanation/announcements/rtk-deprecation.md` if that file does not exist yet). It should explain to outside users what changed, why local-first, what they must do and by when, and where to ask questions. Under 400 words. Do not post it — posting is a maintainer action.
   - Files: `docs/explanation/roadmap-process.md` or `docs/explanation/announcements/rtk-deprecation.md`
   - Depends on: Task 6.2
   - Acceptance: under 400 words; names the support window; links the migration guide and the Q&A discussion category.
 
-- [ ] **Task 6.5**: Update the README architecture and package list
+- [x] **Task 6.5**: Update the README architecture and package list
   - Description: Update `README.md`: replace `@terreno/rtk` with `@terreno/syncdb` in the architecture diagram and the published-packages list, keeping `rtk` listed with a `(deprecated)` marker. Update the "Integration Flow" numbered list to describe the syncdb loop. Do not make positioning changes here — those belong to [`positioning-django-rails-universal`](../implementationPlans/positioning-django-rails-universal.md).
   - Files: `README.md`
   - Depends on: Task 6.1
   - Acceptance: the diagram names syncdb; `rtk` is marked deprecated; the integration flow describes local-first reads and writes; no positioning prose changed.
 
-- [ ] **Task 6.6**: Delete the working inventory document
+- [x] **Task 6.6**: Delete the working inventory document
   - Description: Confirm every fact from `docs/implementationPlans/syncdb-api-inventory.md` has landed in `docs/reference/syncdb.md` or the migration guide, then delete the working file. It is scaffolding, not a deliverable.
   - Files: `docs/implementationPlans/syncdb-api-inventory.md` (deleted)
   - Depends on: all Phase 2–5 tasks

package/dist/docs/versioned/next/tasks/syncdb-codegen.md

@@ -1,65 +1,71 @@
 # Task List: @terreno/syncdb-codegen
 
-Paired with [docs/implementationPlans/syncdb-codegen.md](../implementationPlans/syncdb-codegen.md). Each task is independently implementable and testable.
+Paired with [docs/implementationPlans/syncdb-codegen.md](../implementationPlans/syncdb-codegen.md). **Delivery: single PR** — phases define implementation order only.
 
 ## Phase 1: syncdb runtime
 
-- [ ] **Task 1.1**: Per-mutation `maxAttempts` plumbing
+- [x] **Task 1.1**: Per-mutation `maxAttempts` plumbing
   - Description: Add optional `maxAttempts` to `MutateArgs`, store it as an optional cell on the outbox row, and have the replay coordinator's `error`-nack branch use `row.maxAttempts ?? MAX_ERROR_NACK_ATTEMPTS` when deciding terminal failure. Missing cell keeps current behavior.
   - Files: `syncdb/src/client.ts`, `syncdb/src/mutations/outbox.ts`, `syncdb/src/storage/schema.ts`, `syncdb/src/sync/replayCoordinator.ts`, `syncdb/src/sync/replayCoordinator.test.ts`, `syncdb/src/mutations/outbox.test.ts`
   - Depends on: none
   - Acceptance: `maxAttempts: 1` fails terminally after one error nack; omitted preserves 5-attempt exponential backoff; existing tests unchanged.
 
-- [ ] **Task 1.2**: `createCollectionHooks` factory
-  - Description: New `createCollectionHooks<TData, TCreate, TUpdate>({collection, retries})` in `@terreno/syncdb/react` returning the five per-operation hooks `{useListQuery, useReadQuery, useCreateMutation, useUpdateMutation, useDeleteMutation}`. Read hooks delegate to the existing `useQuery`/`useEntity`; mutation hooks return one-element `[trigger]` tuples (RTK call-site parity) whose triggers wrap `client.mutate`, mapping `retries` (false → 1, number → n, omitted → undefined) to `maxAttempts`.
+- [x] **Task 1.2**: `createCollectionHooks` factory
+  - Description: New `createCollectionHooks<TData, TCreate, TUpdate>({collection, retries})` in `@terreno/syncdb/react` returning the five per-operation hooks `{useListQuery, useReadQuery, useCreateMutation, useUpdateMutation, useDeleteMutation}`. Read hooks delegate to the existing `useQuery`/`useEntity`; mutation hooks return one-element `[trigger]` tuples whose triggers wrap `client.mutate`, mapping `retries` (false → 1, number → n, omitted → undefined) to `maxAttempts`.
   - Files: `syncdb/src/react/collectionHooks.ts` (new), `syncdb/src/react/collectionHooks.test.tsx` (new), `syncdb/src/react/index.ts`
   - Depends on: Task 1.1
   - Acceptance: factory hooks behave identically to direct hook calls; `const [create] = useCreateMutation()` destructuring compiles and works; typed create/update payloads compile; `retries` reaches the outbox row.
 
 ## Phase 2: OpenAPI extension in @terreno/api
 
-- [ ] **Task 2.1**: Emit `x-terreno-sync` on list operations
-  - Description: When `modelRouter` options include `sync`, the list operation's OpenAPI object gains `"x-terreno-sync": {collection, scope}` where `collection` is the route path without the leading slash and `scope` is the scope type ("owner" | "tenant" | "broadcast" | "custom").
-  - Files: `api/src/openApi.ts`, `api/src/openApi.test.ts` (or the existing spec-generation test file)
+- [x] **Task 2.1**: Emit `x-terreno-sync` on list operations
+  - Description: When `modelRouter` options include `sync`, the list operation's OpenAPI object gains `"x-terreno-sync": {collection, scope}` where `collection` is the route path without the leading slash and `scope` is the scope type ("owner" | "tenant" | "broadcast" | "custom"). Thread `routePath` into `listOpenApiMiddleware` so `collection` matches `syncRegistry` `collectionTag`.
+  - Files: `api/src/openApi.ts`, `api/src/api.ts` (call site), `api/src/openApi.test.ts` (or existing spec-generation test file)
   - Depends on: none
   - Acceptance: spec for a synced model contains the extension with correct collection tag and scope; non-synced routes contain no extension; RTK codegen output for example-frontend is unchanged.
 
-## Phase 3: codegen package
+## Phase 3: codegen CLI (`@terreno/syncdb`)
 
-- [ ] **Task 3.1**: Package scaffold
-  - Description: New `syncdb-codegen/` workspace package (`@terreno/syncdb-codegen`) with bin `terreno-syncdb-codegen` (`#!/usr/bin/env bun`), `compile`, `test`, `lint`, and `build:binary` (`bun build --compile src/cli.ts --outfile dist/terreno-syncdb-codegen`) scripts, modeled on `syncdb/` + the `mcp-server` bin pattern.
-  - Files: `syncdb-codegen/package.json` (new), `syncdb-codegen/tsconfig.json` (new), `syncdb-codegen/biome.jsonc` (new), root `package.json` (workspaces + `syncdb-codegen:compile`/`syncdb-codegen:test` scripts)
+- [x] **Task 3.1**: Bin scaffold
+  - Description: Add `terreno-syncdb-codegen` bin and `build:binary` to `@terreno/syncdb` (`src/codegen/cli.ts` with `#!/usr/bin/env bun`), modeled on the `mcp-server` bin pattern. No new workspace package.
+  - Files: `syncdb/package.json`, `syncdb/src/codegen/cli.ts`
   - Depends on: none
-  - Acceptance: `bun run syncdb-codegen:compile` and `bun run lint` pass from the repo root.
+  - Acceptance: `bun syncdb/src/codegen/cli.ts --help`-equivalent missing-args usage exits 1; `bun run lint` in syncdb passes.
 
-- [ ] **Task 3.2**: Spec loading and collection discovery
+- [x] **Task 3.2**: Spec loading and collection discovery
   - Description: Load the OpenAPI document from a URL or file path; walk `paths` for `x-terreno-sync` extensions; resolve each collection's entity schema (list response `data` items ref), create body, and update body schema refs; apply `--collections` as filter or fallback; fail with an actionable error when no collections resolve.
-  - Files: `syncdb-codegen/src/loadSpec.ts` (new), `syncdb-codegen/src/discoverCollections.ts` (new), tests, `syncdb-codegen/src/fixtures/openapi.example.json` (new, captured from example-backend)
+  - Files: `syncdb/src/codegen/loadSpec.ts`, `syncdb/src/codegen/discoverCollections.ts`, tests, `syncdb/src/codegen/fixtures/openapi.example.json`
   - Depends on: Task 2.1, Task 3.1
-  - Acceptance: fixture spec yields `[{collection: "todos", entityRef, createRef, updateRef}]`; missing extensions + no flag exits non-zero.
+  - Acceptance: fixture spec yields todos; missing extensions + no flag exits non-zero.
 
-- [ ] **Task 3.3**: Type and SDK emitters
-  - Description: Emit TS interfaces from the OpenAPI schema subset produced by `mongoose-to-swagger` (objects, primitives, string-union enums, arrays, `$ref`, required lists), then assemble the output file: generated header, interfaces, `SYNC_COLLECTIONS as const`, and one destructured `createCollectionHooks` block per collection renaming the factory keys to RTK-style hook names (`useListQuery: useGetTodosQuery`, `useReadQuery: useGetTodosByIdQuery`, `useCreateMutation: usePostTodosMutation`, `useUpdateMutation: usePatchTodosByIdMutation`, `useDeleteMutation: useDeleteTodosByIdMutation`), with per-collection `retries` overrides from `--config` JSON applied. Name derivation must match `@rtk-query/codegen-openapi`'s pascal-case of the route path. Format via `bunx biome check --write` when available; `--no-format` skips.
-  - Files: `syncdb-codegen/src/emitTypes.ts` (new), `syncdb-codegen/src/emitSdk.ts` (new), snapshot tests
+- [x] **Task 3.3**: Type and SDK emitters
+  - Description: Emit TS interfaces from the OpenAPI schema subset, then assemble the output file with friendly hook names (`useTodos`, `useTodo`, `useCreateTodo`, `useUpdateTodo`, `useDeleteTodo`).
+  - Files: `syncdb/src/codegen/emitTypes.ts`, `syncdb/src/codegen/emitSdk.ts`, `syncdb/src/codegen/hookNames.ts`, tests
   - Depends on: Task 3.2
-  - Acceptance: snapshot output type-checks; emitted hook names for the todos fixture are byte-identical to the RTK-generated names in `example-frontend/store/openApiSdk.ts`; `{overrides: {todos: {retries: false}}}` appears as `retries: false` in the emitted factory call.
+  - Acceptance: todos fixture emits friendly hooks; retries override appears in the factory call.
 
-- [ ] **Task 3.4**: CLI entry and binary build
-  - Description: `cli.ts` wires arg parsing (`util.parseArgs`) → load → discover → emit → write, with clear usage/error output and non-zero exit codes. Verify `build:binary` produces a standalone executable with identical output.
-  - Files: `syncdb-codegen/src/cli.ts` (new), `syncdb-codegen/src/cli.test.ts` (new)
+- [x] **Task 3.4**: CLI entry and binary build
+  - Description: `cli.ts` wires arg parsing → load → discover → emit → write. Verify `build:binary` produces a standalone executable.
+  - Files: `syncdb/src/codegen/cli.ts`, `syncdb/src/codegen/cli.test.ts`
   - Depends on: Task 3.3
-  - Acceptance: `terreno-syncdb-codegen --schema fixtures/openapi.example.json --out /tmp/out.ts` succeeds; missing required args print usage and exit 1; compiled binary output matches bin output byte-for-byte.
+  - Acceptance: missing required args print usage and exit 1; `--schema` fixture write succeeds.
 
 ## Phase 4: Integration and docs
 
-- [ ] **Task 4.1**: example-frontend integration
-  - Description: Add `sync-sdk` script and `syncdb-codegen.json`, check in generated `store/syncDbSdk.ts`, source `SYNC_COLLECTIONS` from it in `store/syncdb.ts`, and migrate `SyncTodosScreen` to the generated hooks (`useGetTodosQuery`, `usePostTodosMutation`, `usePatchTodosByIdMutation`, `useDeleteTodosByIdMutation`; delete the local `SyncTodo` interface). Imports come from `@/store/syncDbSdk` — never re-export these alongside `openApiSdk.ts` from a shared barrel, since the names intentionally collide.
-  - Files: `example-frontend/package.json`, `example-frontend/syncdb-codegen.json` (new), `example-frontend/store/syncDbSdk.ts` (generated), `example-frontend/store/syncdb.ts`, `example-frontend/components/SyncTodosScreen.tsx`
+- [x] **Task 4.1**: example-frontend integration
+  - Description: Add `sync-sdk` script and `syncdb-codegen.json`, check in generated `store/syncDbSdk.ts` (todos collection only), source `SYNC_COLLECTIONS` from it in `store/syncdb.ts`, and migrate `SyncTodosScreen` to generated `useTodo` / `useCreateTodo` / `useUpdateTodo` / `useDeleteTodo` (keep `useEntityIds` for list virtualization).
+  - Files: `example-frontend/package.json`, `example-frontend/syncdb-codegen.json`, `example-frontend/store/syncDbSdk.ts`, `example-frontend/store/syncdb.ts`, `example-frontend/components/SyncTodosScreen.tsx`
   - Depends on: Task 1.2, Task 3.4
-  - Acceptance: `bun run sync-sdk` regenerates with no diff against an unchanged backend; syncdb Playwright e2e suite passes; `compile` passes.
+  - Acceptance: generated hooks are the screen's mutate/read path; `SYNC_COLLECTIONS` feeds `createSyncDb`.
 
-- [ ] **Task 4.2**: Documentation
-  - Description: Codegen section in `syncdb/README.md`, new `syncdb-codegen/README.md` (args, config format, custom-hooks pattern via `createCollectionHooks`), and a note in the RTK migration guide pointing at generated hooks.
-  - Files: `syncdb/README.md`, `syncdb-codegen/README.md` (new), `docs/how-to/migrate-rtk-to-syncdb.md`
+- [x] **Task 4.2**: Documentation
+  - Description: Codegen section in `syncdb/README.md` and `docs/reference/syncdb.md`, plus the RTK migration guide mapping.
+  - Files: `syncdb/README.md`, `docs/how-to/migrate-rtk-to-syncdb.md`, `docs/reference/syncdb.md`
   - Depends on: Task 4.1
-  - Acceptance: docs cover install, generation, custom hooks, and retries overrides; examples compile as written.
+  - Acceptance: docs cover generation, custom hooks, retries overrides, and friendly names.
+
+- [x] **Task 4.3**: npm publish
+  - Description: Codegen ships inside `@terreno/syncdb`. Do not add `publish-syncdb-codegen` or a second package.
+  - Files: none
+  - Depends on: Task 3.1
+  - Acceptance: no new workspace package; existing `publish-syncdb` covers the bin.

package/dist/docs/versioned/next/tasks/upgrade-banner.md

@@ -1,5 +1,7 @@
 # Task List: Upgrade Banner
 
+**Status:** Closed (2026-08-20) — IP complete. Shipped via `VersionCheckPlugin`, `AdminVersionConfig`, `useUpgradeCheck`, and `UpgradeRequiredScreen`. Open tasks below were not executed.
+
 *Structured task breakdown for automated implementation. Each task should be independently implementable and testable.*
 
 ## Phase 1: Backend + Admin