@terreno/mcp 57.2.0 → 57.3.0

package/src/docs/versioned/57.2.0/tasks/infra-mcp.md

@@ -0,0 +1,43 @@
+# Tasks: Infrastructure MCP server (`@terreno/infra-mcp`)
+
+Plan: [docs/implementationPlans/infra-mcp.md](../implementationPlans/infra-mcp.md)
+Status: Blocked — Phase 1 RBAC wiring depends on the RBAC module PR ([rbac-permissions.md](../implementationPlans/rbac-permissions.md)). Scaffold/adapter tasks marked (unblocked) can start now.
+
+## Phase 1 — Read-only core
+
+- [ ] (unblocked) Scaffold `infra-mcp/` workspace package: package.json (catalog deps), tsconfig, biome, bun test setup, root workspace + catalog entries (zod 4, `@modelcontextprotocol/server`, `@better-auth/oauth-provider`, `@better-auth/mcp`)
+- [ ] (unblocked) `src/config.ts`: `defineInfraMcp` config schema (zod), secret resolution (env/Secret Manager), boot validation
+- [ ] (unblocked) `src/server.ts`: Express/TerrenoApp server with SDK v2 `/mcp` endpoint (`createMcpHandler`, `legacy: "stateless"`, `toNodeHandler`) + `/health`
+- [ ] (unblocked) `src/auth.ts`: Better Auth OAuth 2.1 setup — authorization server, RFC 9728 protected-resource metadata, bearer verification middleware; login page flow verified with Cursor and Claude Code
+- [ ] `src/access.ts`: `infraStatements`, default roles (`infra-readonly`, `infra-operator`), `createAccess` wiring, `Mcp-Name`-keyed authz middleware, per-user filtered `tools/list` (**blocked on RBAC PR**)
+- [ ] `src/models/infraAuditLog.ts` + audit middleware around `tools/call` (statuses: allowed/denied/confirmed/rejected/error; per-tool arg redaction)
+- [ ] (unblocked) Integration adapter types + registry (`src/integrations/types.ts`, `registry.ts`)
+- [ ] (unblocked) GCP native adapter (ADC): `gcp_query_logs`, `gcp_list_log_names`, `gcp_query_metrics`, `gcp_list_error_groups`, `gcp_list_cloud_run_services`, `gcp_get_cloud_run_service`
+- [ ] (unblocked) Sentry native adapter (REST + static token): `sentry_search_issues`, `sentry_get_issue`, `sentry_list_issue_events`, `sentry_get_event`
+- [ ] (unblocked) Mongo native adapter (read URI): `mongo_list_collections`, `mongo_collection_schema`, `mongo_find`, `mongo_aggregate` (reject `$out`/`$merge`). Extract the shared read-query/schema logic from `mcp-server/src/local/tools/databaseQuery.ts` + `databaseSchema.ts` into a reusable module both packages import — do not fork copies into infra-mcp (per architectural review)
+- [ ] Admin panel registration (`@terreno/admin-backend`): Users, InfraAuditLog (read-only)
+- [ ] Terraform: `infra_mcp_service` Cloud Run module instance, Artifact Registry, runtime SA with viewer/logging IAM only
+- [ ] Tests: authz matrix (role × tool × tools/list filtering), adapter handlers, audit records, legacy-client fallback
+- [ ] Deploy + end-to-end verification from a real MCP client; docs: `.cursor/rules/infra-mcp/00-infra-mcp.mdc`, AGENTS.md/CLAUDE.md package lists
+- [ ] Roadmap: open the tracking issue from [roadmap-seed-issues.md](../explanation/roadmap-seed-issues.md#infra-mcp) once the IP is Approved, add it to the Terreno Roadmap board, and register `@terreno/infra-mcp` → `area:mcp` in `scripts/issueAreaLabels.ts` + the bug-report package dropdown when the package lands
+
+## Phase 2 — Write tier + machine callers
+
+- [ ] `confirmWrite` elicitation wrapper; fail-closed behavior for clients without elicitation support
+- [ ] Config override (`confirmWrites: false`) gated by `infra:writeUnconfirmed`; tests for both paths
+- [ ] Write tools: `sentry_resolve_issue`, `sentry_assign_issue`, `gcp_rollback_cloud_run_revision`, `gcp_update_cloud_run_traffic`, `mongo_update_one`, `mongo_delete_one`; widen runtime SA IAM minimally
+- [ ] Service tokens: spike Better Auth `apiKey` plugin; fallback `ServiceToken` model; machine users (`isServiceAccount`) with role assignment; admin surface (token shown once)
+- [ ] Cloud agent migration: `INFRA_MCP_URL` + service token in agent environments; verify log-digging flows; remove `GCP_SA_*` injection; update AGENTS.md Cursor Cloud instructions
+
+## Phase 3 — Proxied adapters + remaining vendors
+
+- [ ] `ProxiedAdapter`: `@modelcontextprotocol/client` (stdio + HTTP), deny-by-default `allowedTools` with mandatory tier annotations, tool name prefixing, upstream lifecycle management
+- [ ] Reference proxied integration (`@sentry/mcp-server` stdio or `@google-cloud/observability-mcp`) with parity tests against native tools
+- [ ] Expo/EAS native adapter (`EXPO_TOKEN`): build status, update status, submission status (read); trigger tools deferred to write expansion
+- [ ] Vercel native adapter (API token): deployments, logs, project info (read)
+
+## Phase 4 — OSS packaging
+
+- [ ] `defineInfraMcp` config reference + quickstart docs (website); one-man-shop deploy path (container anywhere)
+- [ ] Publish `@terreno/infra-mcp`; changelog + upgrade notes
+- [ ] Dogfood writeup: our deployment as the reference architecture

package/src/docs/versioned/57.2.0/tasks/migrate-cicd-to-circleci.md

@@ -0,0 +1,219 @@
+# Task List: Migrate CI/CD to CircleCI
+
+See: [`docs/implementationPlans/migrate-cicd-to-circleci.md`](../implementationPlans/migrate-cicd-to-circleci.md)  
+Research: [`docs/implementationPlans/migrate-cicd-to-circleci-research.md`](../implementationPlans/migrate-cicd-to-circleci-research.md)
+
+## Instructions for the implementing agent
+
+- Dual-run every phase: CircleCI green → flip required checks → delete GHA twin. Never enable tag publish on both systems.
+- Do not store plaintext GCP JSON keys in CircleCI if OIDC is available; migrate `preview-cleanup` off `GCP_SA_KEY`.
+- Pin orb versions (including `circleci/node` with Bun support ≥7.2.0).
+- Prefer path parameters that mirror existing GHA path filters.
+- Update docs in the same PR that changes the source of truth for how CI runs.
+- After Phase 0, confirm CircleCI project follows the GitHub default branch `master`.
+
+## Phase 0: Prerequisites
+
+- [ ] **Task 0.1**: Confirm CircleCI org/plan and project link
+  - Description: Verify the requester-created CircleCI organization, plan, and that `FlourishHealth/terreno` is connected with permission to report GitHub checks. Enable **dynamic config** / setup workflows for the project. Record org slug + project slug in the IP header or how-to doc.
+  - Files: `docs/how-to/circleci.md` (stub OK)
+  - Depends on: none (human prerequisite)
+  - Acceptance: a manual “hello” pipeline can be triggered from the project; dynamic config is enabled.
+  - Note: hello scaffold merged (#1052). Dynamic config + org slug still need maintainer confirmation.
+
+- [ ] **Task 0.2**: Create CircleCI Contexts (empty shells)
+  - Description: Create contexts named in the IP (`terreno-npm`, `terreno-netlify`, `terreno-expo`, `terreno-gcp`, `terreno-e2e`, `terreno-release`, `terreno-agentic`, `terreno-github-api`). Document which GitHub secrets map into each. Do not paste secret values into the repo.
+  - Files: `docs/how-to/circleci.md`
+  - Depends on: Task 0.1
+  - Acceptance: contexts exist; mapping table is complete; access restrictions noted for `terreno-release`.
+  - Note: mapping table documented in how-to; contexts themselves are still a human step.
+
+- [x] **Task 0.3**: Inventory required GitHub checks
+  - Description: List current branch-protection required checks and map each to the GHA job `name:` and the future CircleCI job name. Start from `docs/explanation/repository-settings.md` and live settings.
+  - Files: `docs/how-to/circleci.md` or a short table in the IP
+  - Depends on: none
+  - Acceptance: table covers policies, rulesync, package CI, fingerprint, and CD-related checks.
+
+## Phase 1: Foundation
+
+- [x] **Task 1.1**: Add setup + continue config skeleton
+  - Description: Create `.circleci/config.yml` with `setup: true` using `circleci/path-filtering` (and `circleci/continuation`). Create `.circleci/continue-config.yml` with parameters for each package/area and a no-op `config-ok` job that always runs.
+  - Files: `.circleci/config.yml`, `.circleci/continue-config.yml`
+  - Depends on: Task 0.1
+  - Acceptance: push triggers setup → continuation; `config-ok` is green.
+
+- [x] **Task 1.2**: Shared Bun + cache commands
+  - Description: Add reusable commands (inline or orb) for installing Bun via `circleci/node`, `bun install --frozen-lockfile`, and cache keys equivalent to today’s GHA bun cache. Pin Bun policy (`latest` vs pin) consistently with EAS jobs that need a pin.
+  - Files: `.circleci/continue-config.yml`
+  - Depends on: Task 1.1
+  - Acceptance: a sample job restores cache on second run; install is frozen-lockfile.
+
+- [x] **Task 1.3**: Path-filter mapping
+  - Description: Encode path → parameter mapping for api, ai, ui, rtk, comms, mcp-server, admin-*, example-*, demo, docs/website, terraform, e2e-relevant sets, matching current workflow path filters.
+  - Files: `.circleci/config.yml`
+  - Depends on: Task 1.1
+  - Acceptance: a docs-only change sets docs/deploy params without setting `run-api`.
+  - Note: deploy path params omitted until Phase 4+.
+
+## Phase 2: Package CI + policy
+
+- [x] **Task 2.1**: Port package CI jobs
+  - Description: Port api/ai/rtk/ui/ui-demo/comms/mcp-server/example-frontend/example-backend(+script)/admin-spa CI to CircleCI jobs gated by path params. Include Mongo service where GHA used it. Fix mcp branch filter to `master`.
+  - Files: `.circleci/continue-config.yml`, possibly package scripts unchanged
+  - Depends on: Task 1.2, Task 1.3
+  - Acceptance: dual-run green for each package on a change that touches it; GHA still required.
+
+- [x] **Task 2.2**: Port Docker build-only job
+  - Description: Port `example-backend-docker.yml` to CircleCI remote Docker / machine with layer caching replacement for `type=gha`.
+  - Files: `.circleci/continue-config.yml`
+  - Depends on: Task 2.1
+  - Acceptance: PR touching `example-backend/**` builds the image without pushing.
+
+- [x] **Task 2.3**: Port repo-policies + rulesync + DCO
+  - Description: Port `repo-policies.yml`, `rulesync-check.yml`, and fork DCO checks. DCO must use GitHub API via `terreno-github-api` context.
+  - Files: `.circleci/continue-config.yml`
+  - Depends on: Task 0.2, Task 1.2
+  - Acceptance: intentional barrel-import / dirty rulesync / missing DCO on a fork PR fails the CircleCI job.
+  - Note: DCO skips cleanly if `GITHUB_TOKEN` unset until context is created.
+
+- [ ] **Task 2.4**: Dual-run cutover for Phase 2
+  - Description: Add CircleCI checks to branch protection; remove GHA package/policy workflows once trusted; delete corresponding `.github/workflows/*-ci.yml` and policy workflows.
+  - Files: `.github/workflows/*`, `docs/explanation/repository-settings.md`
+  - Depends on: Task 2.1, Task 2.2, Task 2.3
+  - Acceptance: required checks are CircleCI-only for these surfaces; GHA files gone.
+
+## Phase 3: Playwright E2E
+
+- [x] **Task 3.1**: Port `e2e-ci` and `admin-spa-integration`
+  - Description: Mongo replica set, E2E secrets context, Playwright browsers, artifact store for reports. Skip Dependabot-equivalent if applicable.
+  - Files: `.circleci/continue-config.yml`
+  - Depends on: Task 2.1, Task 0.2
+  - Acceptance: matrix (or equivalent) passes on master; artifacts downloadable.
+
+- [ ] **Task 3.2**: Dual-run cutover for E2E
+  - Description: Flip required checks if any; delete GHA e2e/admin-spa-integration workflows.
+  - Files: `.github/workflows/e2e-ci.yml`, `admin-spa-integration.yml`, `admin-spa-ci.yml` as applicable
+  - Depends on: Task 3.1
+  - Acceptance: GHA twins deleted; CircleCI owns e2e.
+
+## Phase 4: Netlify deploys
+
+- [ ] **Task 4.1**: Port demo / frontend-example / docs Netlify workflows
+  - Description: Build + `netlify-cli` deploy prod/preview; preserve alias naming (`pr-N`); recreate GitHub Deployment statuses via API if still desired.
+  - Files: `.circleci/continue-config.yml`
+  - Depends on: Task 0.2, Task 1.3
+  - Acceptance: preview deploy URL posted or visible; prod deploy on master path filter.
+
+- [ ] **Task 4.2**: Preview cleanup port
+  - Description: On PR close, clean Netlify/GCP preview resources from CircleCI (webhook or GitHub App → pipeline). Prefer OIDC over `GCP_SA_KEY`.
+  - Files: `.circleci/continue-config.yml`
+  - Depends on: Task 4.1
+  - Acceptance: closing a PR removes preview resources; no orphaned Cloud Run `pr-N` services in a test PR.
+
+- [ ] **Task 4.3**: Dual-run cutover for Netlify
+  - Description: Delete GHA deploy workflows after CircleCI trusted.
+  - Files: `.github/workflows/demo-deploy.yml`, `frontend-example-deploy.yml`, `docs-deploy.yml`, `preview-cleanup.yml`
+  - Depends on: Task 4.1, Task 4.2
+  - Acceptance: GHA deploy twins deleted.
+
+## Phase 5: EAS + fingerprint
+
+- [ ] **Task 5.1**: Relocate CI scripts
+  - Description: Move EAS/fingerprint shell scripts from `.github/workflows/scripts/` to `scripts/ci/` (or `.circleci/scripts/`) and update callers.
+  - Files: `scripts/ci/*`, old script paths
+  - Depends on: none
+  - Acceptance: scripts runnable locally with documented env; no broken references.
+
+- [ ] **Task 5.2**: Port eas-pr, eas-dev-build, fingerprint-gate
+  - Description: CircleCI jobs using `EXPO_TOKEN`; PR comments and label gate via GitHub API; manual pipeline for eas-dev-build.
+  - Files: `.circleci/continue-config.yml`
+  - Depends on: Task 5.1, Task 0.2
+  - Acceptance: fingerprint change fails until `fingerprint-acknowledged`; EAS update/build path works on a test PR.
+
+- [ ] **Task 5.3**: Dual-run cutover for EAS
+  - Description: Delete GHA eas/fingerprint workflows after trust.
+  - Files: `.github/workflows/eas-pr.yml`, `eas-dev-build.yml`, `fingerprint-gate.yml`
+  - Depends on: Task 5.2
+  - Acceptance: GHA twins deleted; CircleCI checks required where fingerprint was required.
+
+## Phase 6: GCP CD + OIDC
+
+- [ ] **Task 6.1**: Add CircleCI OIDC provider in terraform
+  - Description: Extend or add module so GCP trusts CircleCI OIDC alongside GitHub during dual-run. Wire terreno terraform root; document outputs for CircleCI project settings.
+  - Files: `terraform/modules/**`, terreno/Flourish terraform roots, `terraform/README.md`
+  - Depends on: Task 0.1
+  - Acceptance: `gcloud` auth from a CircleCI job succeeds with WIF (no JSON key).
+
+- [ ] **Task 6.2**: Port `cd.yml`
+  - Description: Path-filtered terraform fmt/preview/apply + Docker build/push + Cloud Run deploys + mcp-test/deploy. Preserve concurrency semantics (do not cancel in-flight prod applies).
+  - Files: `.circleci/continue-config.yml`
+  - Depends on: Task 6.1
+  - Acceptance: terraform preview on PR; apply+deploy on master for a safe test path; GitHub Deployment records optional but documented.
+
+- [ ] **Task 6.3**: Dual-run cutover for CD
+  - Description: Single deployer: disable GHA `cd.yml` when CircleCI CD is required; remove GitHub OIDC provider only after GHA CD is gone (or keep read-only if other repos need it — document).
+  - Files: `.github/workflows/cd.yml`, terraform OIDC
+  - Depends on: Task 6.2
+  - Acceptance: only CircleCI performs terreno CD; no double apply.
+
+## Phase 7: npm publish
+
+- [ ] **Task 7.1**: Port publish-on-tag + manual feature-flags publish
+  - Description: Reproduce package publish graph, upgrade-docs gate, version bump, Zoom notify, demo dispatch, docs version cut. Use `terreno-release` + `terreno-npm` contexts.
+  - Files: `.circleci/continue-config.yml`
+  - Depends on: Task 0.2, Task 2.1
+  - Acceptance: dry-run or package-by-package rehearsal documented; Zoom path tested against a sandbox webhook if available.
+
+- [ ] **Task 7.2**: Single-writer tag cutover
+  - Description: In one coordinated change: enable CircleCI tag pipeline; delete/disable `.github/workflows/publish-on-tag.yml` and manual GHA publish; verify no double publish.
+  - Files: `.github/workflows/publish-on-tag.yml`, `publish-feature-flags-manual.yml`
+  - Depends on: Task 7.1
+  - Acceptance: next tag publishes once from CircleCI only.
+
+## Phase 8: Mobile (post-v1, required for CC1)
+
+- [ ] **Task 8.1**: Port Maestro + Appium Android
+  - Description: Port `maestro-e2e` and Android half of `demo-appium-ci` to CircleCI Linux VM with emulator strategy documented.
+  - Files: `.circleci/continue-config.yml`
+  - Depends on: Task 5.2
+  - Acceptance: manual pipeline runs Android Appium and Maestro successfully.
+
+- [ ] **Task 8.2**: Port Appium iOS on CircleCI macOS
+  - Description: Select macOS resource class/image with Working WDA; port iOS job; compare flake rate to GHA `macos-15`.
+  - Files: `.circleci/continue-config.yml`
+  - Depends on: Task 8.1
+  - Acceptance: iOS Appium green on a representative run; then delete GHA Appium workflow.
+
+## Phase 9: GitHub-native + agentic replacements
+
+- [ ] **Task 9.1**: Replace CodeQL workflow
+  - Description: Implement SARIF upload to GitHub Code Scanning from CircleCI or an approved SAST substitute; delete `codeql-analysis.yml` only when coverage is accepted.
+  - Files: `.circleci/continue-config.yml`, `.github/workflows/codeql-analysis.yml`
+  - Depends on: Task 0.2
+  - Acceptance: Security tab still receives results **or** explicit maintainer sign-off on alternative.
+
+- [ ] **Task 9.2**: Replace Dependabot auto-merge + triage + roadmap-generate + docs-audit
+  - Description: Implement CircleCI (or Renovate) equivalents; wire issue/schedule triggers without leaving required logic on GHA.
+  - Files: `.circleci/continue-config.yml`, corresponding GHA deletions
+  - Depends on: Task 0.2
+  - Acceptance: each former workflow’s acceptance behavior has an owner on CircleCI; GHA files deleted.
+
+- [ ] **Task 9.3**: Replace architectural review + gh-aw agentics
+  - Description: Per lockfile (`update-rules`, `update-docs`, daily improvers) and `architectural-pr-review` / `agentics-maintenance`: either port to CircleCI scheduled/PR pipelines with the same scripts or **retire** with maintainer sign-off. CC1 forbids leaving them on GHA.
+  - Files: `.github/workflows/*lock*`, `architectural-pr-review.yml`, `agentics-maintenance.yml`, `.circleci/continue-config.yml`
+  - Depends on: Task 0.2
+  - Acceptance: written retire-or-port decision for each; no gh-aw workflows remain if ported/retired.
+
+## Phase 10: Cleanup
+
+- [ ] **Task 10.1**: Docs sweep
+  - Description: Update CONTRIBUTING, repository-settings, terraform README, deploy guides, AGENTS/Cursor Cloud CI notes to CircleCI-first. Remove stale GHA instructions.
+  - Files: `docs/**`, `CONTRIBUTING.md`, `AGENTS.md` / rules as needed
+  - Depends on: Phases 2–7 at minimum; 8–9 for full CC1
+  - Acceptance: `rg -n "GitHub Actions" docs/explanation/repository-settings.md` and deploy docs reflect CircleCI as source of truth.
+
+- [ ] **Task 10.2**: Final GHA workflow purge + IP close
+  - Description: Ensure `.github/workflows` has no CI/CD yml left (except intentionally empty dir or README). Set the IP `**Status:**` to Complete and archive the IP.
+  - Files: `.github/workflows/`, `docs/implementationPlans/migrate-cicd-to-circleci.md`
+  - Depends on: Task 9.3, Task 10.1, Task 8.2
+  - Acceptance: `ls .github/workflows/*.yml` is empty (or only an agreed stub); IP status Complete.

package/src/docs/versioned/57.2.0/tasks/model-router-actions.md

@@ -0,0 +1,48 @@
+# modelRouter Actions — Task List
+
+**Status:** Closed (2026-08-20) — IP deferred. Open tasks below will not be executed.
+
+## Phase 1: Foundation (types + runtime + per-route OpenAPI middleware)
+
+- [ ] **Task 1.1**: Add `zod ^4.3.6` as a **peerDependency** of `@terreno/api` (also pin `^4.3.6` in `devDependencies` so the package compiles/tests on its own) and `@asteasolutions/zod-to-openapi ^8.5.0` as a regular `dependency` (it bundles its own usage). Use Bun catalog for Zod if a catalog version exists.
+- [ ] **Task 1.2**: Create `api/src/docLoader.ts` exporting `loadDocOr404(model, id, populatePaths?)`. Behavior matches the existing permission middleware doc-load (`permissions.ts:148–200`): 404 on missing, soft-delete-aware metadata via `model.collection.findOne` fallback.
+- [ ] **Task 1.3**: Refactor `permissionMiddleware` in `api/src/permissions.ts` to call `loadDocOr404`. Add a regression test asserting soft-delete 404 metadata is intact. No public API change.
+- [ ] **Task 1.4**: Create `api/src/actions.ts` with public types: `ActionContext`, `BaseActionConfig`, `InstanceActionConfig`, `CollectionActionConfig`. Also export `defineInstanceAction()` and `defineCollectionAction()` identity helpers that preserve per-action generics across the `Record<string, ...>` boundary.
+- [ ] **Task 1.5**: Implement `runActionPermissions(action, scope, req, doc?)` in `api/src/actions.ts`. Maps HTTP method + scope → CRUD method. Pre-doc denial → **405** (matches `permissions.ts:136`). Post-doc denial → **403** (matches `permissions.ts:203`). Uses existing `checkPermissions` helper so `[]` arrays disable the action via 405.
+- [ ] **Task 1.6**: Implement `validateActionRequest(action, req)` in `api/src/actions.ts`. Runs Zod `safeParse` on body/query when schemas provided. On failure throws `APIError({status: 400, title: "Validation failed", fields})` — emitted as `meta.fields` on the wire by `errors.ts:117–121`. Parsed values returned through `ctx`, NOT by mutating `req.query` (Express 5 getter).
+- [ ] **Task 1.7**: Implement `wrapActionResponse(handlerResult, action, res)` — auto-wraps in `{data: ...}` with `status ?? 200`; skips wrap if `res.headersSent`. Default `null` for `undefined` return.
+- [ ] **Task 1.8**: Implement `assertNoActionCollisions(model, options)` — throws synchronously on:
+  - Action name doesn't match `/^[A-Za-z][A-Za-z0-9_-]+$/` (incl. empty names).
+  - Action name matches a Mongoose array-field path (would collide with `POST /:id/:field` at `api.ts:1159–1175`).
+- [ ] **Task 1.9**: Implement `createActionOpenApiMiddleware({action, scope, actionName, model})` in `api/src/actions.ts`. Per-request middleware that on first request through the route calls `options.openApi.path()` with an Operation Object built from inlined Zod-derived schemas (`OpenApiGeneratorV3.generateSchema()`). No-op when `options.openApi` is undefined. Sets `operationId: '${tag}_${actionName}'`. Tag defaults to `model.collection.collectionName`.
+- [ ] **Task 1.10**: Implement `registerActionRoutes(router, model, options)` — composes the middleware chain in order: `authenticateMiddleware(options.allowAnonymous)` → action OpenAPI middleware → pre-doc `runActionPermissions` → (instance only) `loadDocOr404` + post-doc `runActionPermissions` → `validateActionRequest` → wrapped `asyncHandler(action.handler)` → `wrapActionResponse`.
+- [ ] **Task 1.11**: Extend `ModelRouterOptions<T>` in `api/src/api.ts` with `instanceActions?` and `collectionActions?`. Inside `_buildModelRouter`, call `assertNoActionCollisions` and `registerActionRoutes` in the pre-CRUD `endpoints` slot (before the user's `options.endpoints` callback runs, so actions take precedence on path conflicts).
+- [ ] **Task 1.12**: Re-export `ActionContext`, `InstanceActionConfig`, `CollectionActionConfig`, `defineInstanceAction`, `defineCollectionAction` from `api/src/index.ts`.
+- [ ] **Task 1.13**: Write tests in `api/src/actions.test.ts` covering all Phase 1 acceptance criteria: registration validation (missing perms throws, empty perms registers but returns 405, action-name regex, array-field collision, empty name); routing (instance + collection happy path for GET + POST; `ctx.doc` set on instance; `req.obj` set on instance for parity with CRUD); permission flow (pre-doc → 405, post-doc → 403, 401 from passport, `IsAuthenticatedOrReadOnly` GET works with `allowAnonymous: true`, `IsOwner` doc-aware); validation (good body, bad body → 400 with `meta.fields`, query schema, Zod coercion through `ctx`, `req.query` not mutated, Zod `.strip` default observed); response shape (envelope, custom `status`, null/undefined return, `res.headersSent` escape hatch, custom list-style envelope via `res.json` + return); doc loading (404 missing, 404 metadata on soft-deleted); **type ergonomics**: a TS-level compile-only test that `defineInstanceAction<TDoc>({body: z.object({x: z.string()}), handler: async ({doc, body}) => {}})` infers `doc: TDoc` and `body: {x: string}` correctly.
+- [ ] **Task 1.14**: Add a regression test for **co-registration**: a modelRouter using BOTH `instanceActions: {foo: ...}` AND `endpoints: (router) => router.get('/:id/foo', ...)` — assert that the action wins (registered first in the pre-CRUD slot, before user `options.endpoints`). Same test for `collectionActions` colliding with a user `endpoints` route. Documents the precedence.
+
+## Phase 2: OpenAPI verification
+
+- [ ] **Task 2.1**: Tests against the generated `openapi.json` for actions registered via `TerrenoApp`: operation appears under `paths`; correct method + path; default tag = `model.collection.collectionName`; per-action `tag` override; inlined request body schema; inlined response schema under configured status; `id` path param present for instance actions; deterministic `operationId`.
+- [ ] **Task 2.2**: Same suite but for actions registered via the legacy `setupServer` path (`expressServer.ts:257`) — verifies the per-request OpenAPI emission fires on first hit and produces parity with the `TerrenoApp` path.
+
+## Phase 3: Migration + dogfooding
+
+- [ ] **Task 3.1**: Migrate `api/src/consentApp.ts` `/consent-forms` `endpoints` actions (scope: only those three actions; `/consents/*` routes at lines 195–457 are out of scope):
+  - `generate` → `collectionActions.generate`, conditional on `aiConfig` (built at runtime into the `collectionActions` map before passing to `modelRouter`).
+  - `translate` → `collectionActions.translate`, same conditional.
+  - `/:id/publish` → `instanceActions.publish`.
+- [ ] **Task 3.2**: Confirm all existing consent-form tests pass without modification.
+- [ ] **Task 3.3**: Add a `markComplete` instance action and a `bulkComplete` collection action to `example-backend/src/api/todos.ts` to demonstrate both scopes (and document the Zod `.strict()` recommendation in the example).
+- [ ] **Task 3.4**: Regenerate `example-frontend` SDK: `cd example-frontend && bun run sdk`.
+- [ ] **Task 3.5**: Smoke-test: run `bun run backend:dev` and `bun run frontend:web` together; exercise both new todo actions end-to-end (curl + the regenerated hooks).
+
+## Phase 4: Consumer compile-check + docs
+
+- [ ] **Task 4.1**: Run `bun run compile` (and `bun run test` where present) in each in-repo consumer of `@terreno/api`: `admin-backend`, `admin-frontend`, `ai`, `api-health`, `feature-flags`, `mcp-server`, `rtk`, `example-backend`, `example-frontend`. Fix any breakage from the new deps.
+- [ ] **Task 4.2**: Document in the explainer that `zod` is a `peerDependency` of `@terreno/api` — consumers must install Zod themselves (already true for `example-backend`). Note this in the changelog as a breaking install requirement.
+- [ ] **Task 4.3**: Write `docs/explanation/model-router-actions.md` covering: motivation; call-site example; semantics (permission method mapping, 405 vs 403 status codes, response envelope, validation error wire shape at `meta.fields`, collision detection, Zod `.strict()` recommendation, concurrency caveat for action handlers, `queryFilter` not applied to instance auto-load); migration notes from hand-rolled `endpoints` actions.
+- [ ] **Task 4.4**: Update `mcp-server/src/tools.ts` `generate_route` (and any related prompt in `prompts.ts`) to suggest `instanceActions`/`collectionActions`.
+- [ ] **Task 4.5**: Bump `@terreno/api` package version in `api/package.json`. Prepare a changelog entry mentioning: the new feature, the new deps (`zod`, `@asteasolutions/zod-to-openapi`), the behavior-preserving permission middleware refactor, and the new `operationId`-based hook names in regenerated SDKs.
+
+See `docs/implementationPlans/model-router-actions.md` for full details on each task.

package/src/docs/versioned/57.2.0/tasks/model-router-mcp.md

@@ -0,0 +1,105 @@
+# Tasks: modelRouter MCP Tools
+
+*Structured task breakdown for automated implementation. Each task should be independently implementable and testable.*
+
+---
+
+### Phase 1: Core MCP Infrastructure
+
+- [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`
+
+- [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. `getMCPRegistry()` returns those entries.
+
+- [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.
+
+- [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.
+
+- [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.
+
+- [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.
+
+- [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.
+
+- [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.
+
+- [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 } from "@terreno/api"` and `import { getMCPTools } from "@terreno/ai"`.
+
+---
+
+### Phase 2: Frontend Integration
+
+- [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`
+  - Depends on: Task 1.7
+  - Acceptance: Hook connects to MCP-enabled backend, streams responses with tool calls, injects auth token automatically.
+
+- [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.
+
+- [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"`.
+
+---
+
+### Phase 3: Examples & Polish
+
+- [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 user tools. MCP client can list and call them.
+
+- [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.
+
+- [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
+  - Acceptance: Descriptions include actionable detail. LLM can understand what each tool does and what inputs are expected without additional context.

package/src/docs/versioned/57.2.0/tasks/native-module-baseline.md

@@ -0,0 +1,42 @@
+# Tasks: Native module baseline for the next major release
+
+IP: [native-module-baseline](../implementationPlans/native-module-baseline.md)
+
+## Phase 1 — Dependencies + config
+
+- [ ] **Task 1.1**: Catalog + app package manifests
+  - Description: add the seven packages to root catalog (sorted) and to example-frontend + demo deps via `catalog:`
+  - Files: root `package.json`, `example-frontend/package.json`, `demo/package.json`
+  - Depends on: none
+  - Acceptance: `bun install` + full compile green
+- [ ] **Task 1.2**: Config plugins + build properties
+  - Description: stripe + purchases plugins; `expo-build-properties` Kotlin 2.x / compileSdk 36 pins
+  - Files: `example-frontend/app.json`, `demo/app.json`
+  - Depends on: 1.1
+  - Acceptance: `expo config` resolves without errors; web export unaffected
+
+## Phase 2 — Builds + verification
+
+- [ ] **Task 2.1**: EAS dev builds
+  - Description: iOS + Android dev-client builds via existing eas-dev-build workflow
+  - Files: `eas.json` profiles if needed
+  - Depends on: Phase 1
+  - Acceptance: both builds compile
+- [ ] **Task 2.2**: Diagnostics story
+  - Description: hidden demo story listing resolved native module versions
+  - Files: `demo/stories/NativeModules.stories.tsx`, `demo/demoConfig.tsx`
+  - Depends on: 2.1
+  - Acceptance: story shows all seven modules on a dev build; screenshot evidence
+- [ ] **Task 2.3**: Expo Go degradation doc
+  - Description: document which flows need a dev build (stripe, local-auth) vs preview modes (purchases)
+  - Files: `docs/` upgrade note draft
+  - Depends on: 2.1
+  - Acceptance: reviewed checklist in the note
+
+## Phase 3 — Release
+
+- [ ] **Task 3.1**: Upgrade note + major release coordination
+  - Description: consumer checklist (rebuild dev clients, add plugins, merchant id); breaking-release CI gate
+  - Files: upgrade notes location per release process
+  - Depends on: Phase 2
+  - Acceptance: breaking-release CI gate passes on the release PR

package/src/docs/versioned/57.2.0/tasks/offline-mode.md

@@ -0,0 +1,141 @@
+# 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
+
+- [ ] **Task 1.1**: Formalize offline state and queue record types
+  - Description: Extend the offline slice state to represent connection quality, auth-blocked replay, queue record statuses, base timestamps, optimistic/server IDs, and persisted queue versioning. Keep the slice default inert until offline mode is mounted by a consuming app.
+  - Files: `rtk/src/offlineSlice.ts`, `rtk/src/useOfflineStatus.ts`, `rtk/src/index.ts`, related `rtk/src/*.test.ts`
+  - Depends on: none
+  - Acceptance: Unit tests cover enqueue/dequeue/status transitions, conflict storage, auth-blocked state, queue version defaults, and selectors for `online`, `spotty`, `offline`, queued mutations, conflicts, and replay-paused state.
+
+- [ ] **Task 1.2**: Replace endpoint-name-only offline gating with modelRouter config
+  - Description: Introduce a typed `OfflineModelRouterConfig` that maps model names and modelRouter operations to generated RTK Query endpoint names. Preserve a migration path for existing endpoint-name configuration only if it is already shipped behavior; otherwise replace it with the modelRouter config.
+  - Files: `rtk/src/offlineGate.ts`, `rtk/src/offlineMiddleware.ts`, `rtk/src/index.ts`, `rtk/src/offlineGate.test.ts`
+  - Depends on: Task 1.1
+  - Acceptance: Tests prove disabled/default config never defers mutations, enabled modelRouter endpoints are deferred while offline, unconfigured custom routes are not deferred, and array operations can be configured separately from create/update/delete.
+
+- [ ] **Task 1.3**: Add optimistic create ID strategy
+  - Description: Add default ObjectId-compatible ID generation for optimistic modelRouter creates, inject the generated ID into the configured request field, and support per-model overrides for `generateId`, request field, and server ID reconciliation strategy.
+  - Files: `rtk/src/offlineMiddleware.ts`, `rtk/src/offlineGate.ts`, `rtk/src/offlineIds.ts` (new if useful), `rtk/src/index.ts`, related tests
+  - Depends on: Task 1.2
+  - Acceptance: Tests verify default IDs are stable and ObjectId-shaped, custom generators are used, optimistic create cache entries use the same local ID as the queued mutation, and a server-returned replacement ID can be mapped when explicitly configured.
+
+- [ ] **Task 1.4**: Harden optimistic cache update strategies
+  - Description: Make optimistic cache updates explicit per modelRouter operation while providing safe defaults for create, update, delete, array push, array update, and array remove. Expose an override hook so app teams can customize cache updates for complex list filters or response shapes.
+  - Files: `rtk/src/offlineMiddleware.ts`, `rtk/src/offlineOptimistic.ts` (new if useful), `rtk/src/useOfflineStatus.ts`, related tests
+  - Depends on: Task 1.3
+  - Acceptance: Tests cover optimistic insert, patch, remove, and array mutations against RTK Query cache entries, including rollback or conflict marking when replay fails with a non-network/non-auth error.
+
+- [ ] **Task 1.5**: Pause replay on auth refresh failure without clearing cache
+  - Description: Separate token-refresh failure from explicit logout. If refresh cannot complete because the server/network is unavailable or refresh returns a retryable failure, mark replay as auth-blocked and keep RTK Query cache, queue, conflicts, and optimistic records intact. Reserve destructive cleanup for the actual logout action.
+  - Files: `rtk/src/emptyApi.ts`, `rtk/src/authSlice.ts`, `rtk/src/offlineMiddleware.ts`, `rtk/src/offlineSlice.ts`, related tests
+  - Depends on: Task 1.1
+  - Acceptance: Tests simulate expired access tokens with unreachable refresh endpoint and verify queued mutations are held, cache data remains, and replay resumes after auth is refreshed; explicit logout still clears tokens and configured offline/cache state.
+
+- [ ] **Task 1.6**: Implement keep-mine and use-server conflict resolution
+  - Description: Add conflict resolution actions/helpers. `useServer` should discard the queued mutation and patch cache to the server value. `keepMine` should update the queued mutation with the latest server timestamp, reapply the local optimistic value, and retry replay with fresh precondition headers.
+  - Files: `rtk/src/offlineSlice.ts`, `rtk/src/offlineMiddleware.ts`, `rtk/src/useOfflineStatus.ts`, `rtk/src/index.ts`, related tests
+  - Depends on: Task 1.4
+  - Acceptance: Tests cover `409 Conflict` replay responses, stored local/server values, resolving with `useServer`, resolving with `keepMine`, and preventing duplicate conflict records for the same queued mutation.
+
+## Phase 2: Connection Quality and UI
+
+- [ ] **Task 2.1**: Upgrade server status monitoring to connection quality
+  - Description: Extend `useServerStatus` to compute `online`, `spotty`, and `offline` from browser/native reachability events, health-check failures, latency, and recent failure rate. Make health URL, interval, timeout, latency threshold, failure count, and failure-rate thresholds configurable.
+  - Files: `rtk/src/useServerStatus.ts`, `rtk/src/offlineSlice.ts`, `rtk/src/index.ts`, related tests
+  - Depends on: Task 1.1
+  - Acceptance: Tests cover all three connection states, threshold overrides, transition from spotty back to online, transition to offline after configured consecutive failures, and no polling when status monitoring is disabled.
+
+- [ ] **Task 2.2**: Expose richer offline status hooks
+  - Description: Expand `useOfflineStatus` to return connection quality, queue length, syncing state, auth-blocked state, conflicts, local-only helpers, and conflict resolution callbacks while preserving low-level selectors for custom UI.
+  - Files: `rtk/src/useOfflineStatus.ts`, `rtk/src/offlineSlice.ts`, `rtk/src/index.ts`, related tests
+  - Depends on: Task 1.6, Task 2.1
+  - Acceptance: Hook tests or focused unit tests verify returned state and callbacks for queued, syncing, auth-blocked, conflicted, local-only, and healthy states.
+
+- [ ] **Task 2.3**: Update offline banner for online, spotty, offline, syncing, and auth-blocked states
+  - Description: Evolve `OfflineBanner` so apps can show offline, spotty connection, syncing queued changes, pending changes, and auth-blocked sync messaging. Keep props simple enough for custom state sources.
+  - Files: `ui/src/OfflineBanner.tsx`, `ui/src/index.tsx`, `ui/src/OfflineBanner.test.tsx` (new if absent), `demo/stories/OfflineBanner.stories.tsx` (new or update)
+  - Depends on: Task 2.1
+  - Acceptance: UI tests or stories cover hidden/online, spotty, offline, syncing, pending queue, and auth-blocked variants with clear copy and accessible test IDs.
+
+- [ ] **Task 2.4**: Add conflict resolution UI components
+  - Description: Add reusable conflict UI that renders unresolved conflicts and lets users choose "Keep mine" or "Use server". Keep it generic by accepting display renderers for local and server values.
+  - Files: `ui/src/OfflineConflictList.tsx` (new), `ui/src/OfflineConflictCard.tsx` (new), `ui/src/index.tsx`, `ui/src/*.test.tsx`, `demo/stories/OfflineConflict*.stories.tsx`
+  - Depends on: Task 2.2
+  - Acceptance: Tests or stories cover no-conflict, single-conflict, multiple-conflict, keep-mine click, use-server click, dismissed/resolved conflict filtering, and custom value rendering.
+
+## Phase 3: modelRouter Backend Contract
+
+- [ ] **Task 3.1**: Verify client-provided modelRouter create IDs
+  - Description: Add backend tests that prove modelRouter create accepts a client-provided ObjectId-compatible `_id` when the schema allows it and rejects invalid IDs through existing validation/error handling.
+  - Files: `api/src/api.ts`, `api/src/tests/*.test.ts` or existing modelRouter test file, `api/src/tests.ts`
+  - Depends on: Task 1.3
+  - Acceptance: API tests pass for create with client `_id`, returned document keeps that `_id`, duplicate IDs fail safely, and invalid IDs return a clear validation/error response.
+
+- [ ] **Task 3.2**: Formalize conflict response tests for modelRouter updates
+  - Description: Add/extend modelRouter tests for `If-Unmodified-Since` and `X-Unmodified-Since-ISO` headers to guarantee stale updates return `409 Conflict` with the current server document and fresh updates succeed.
+  - Files: `api/src/api.ts`, `api/src/tests/*.test.ts` or existing modelRouter test file
+  - Depends on: none
+  - Acceptance: API tests cover conflict by HTTP-date header, conflict by ISO header, success with current timestamp, missing timestamp behavior, and response body shape consumed by `@terreno/rtk`.
+
+- [ ] **Task 3.3**: Document the modelRouter offline contract
+  - Description: Add docs for modelRouter offline compatibility: supported CRUD/array endpoints, client-provided IDs, conflict headers, expected `409` response shape, permissions behavior, and explicit non-support for custom sync endpoints in v1.
+  - Files: `api/README.md` or package docs, `rtk/README.md` or package docs, `docs/implementationPlans/offline-mode.md`
+  - Depends on: Task 3.1, Task 3.2
+  - Acceptance: Docs show a modelRouter route configuration and matching frontend offline config, and clearly state that custom route sync is future work.
+
+## Phase 4: Example App Integration
+
+- [ ] **Task 4.1**: Enable offline mode for example todos
+  - Description: Wire the example frontend store to mount the offline reducer, persist the offline slice, configure todos modelRouter endpoints for offline create/update/delete, and keep API cache persistence consistent with the offline plan.
+  - Files: `example-frontend/store/index.ts`, `example-frontend/store/sdk.ts`, `example-frontend/app/_layout.tsx`, `example-frontend/package.json` if scripts need updates
+  - Depends on: Task 1.6, Task 2.2
+  - Acceptance: Example app can create, update, and delete todos while offline; queued todos survive app reload when persistence is enabled; replay syncs after the backend is reachable again.
+
+- [ ] **Task 4.2**: Integrate connection banner and sync state in the example app
+  - Description: Add root-level status monitoring and display `OfflineBanner` for offline, spotty, syncing, pending queue, and auth-blocked states. Ensure copy is visible without disrupting auth navigation.
+  - Files: `example-frontend/app/_layout.tsx`, `example-frontend/app/(tabs)/_layout.tsx`, `example-frontend/app/(tabs)/index.tsx`
+  - Depends on: Task 2.3, Task 4.1
+  - Acceptance: Manual test can trigger offline/spotty/syncing/auth-blocked states and see the correct banner copy and pending queue count.
+
+- [ ] **Task 4.3**: Add example conflict resolution flow
+  - Description: Show unresolved todo conflicts in the example app and wire "Keep mine" / "Use server" actions to the RTK conflict resolution helpers.
+  - Files: `example-frontend/app/(tabs)/index.tsx`, `example-frontend/components/*` if a local wrapper is useful
+  - Depends on: Task 2.4, Task 4.1
+  - Acceptance: Manual test can create a stale update conflict, see local/server values, choose "Use server" to accept server state, and choose "Keep mine" to replay local state.
+
+- [ ] **Task 4.4**: Add example backend support tests or fixtures for offline scenarios
+  - Description: Ensure the example backend todo model and route can support client IDs and conflict timestamps. Add tests or fixtures that make the example integration verifiable without modifying generated SDK files manually.
+  - Files: `example-backend/src/models/todo.ts`, `example-backend/src/api/todos.ts`, `example-backend/src/**/*.test.ts`
+  - Depends on: Task 3.1, Task 3.2
+  - Acceptance: Example backend tests pass and confirm todos work with the modelRouter offline contract.
+
+## Phase 5: Verification, Documentation, and Release Readiness
+
+- [ ] **Task 5.1**: Add package-level offline mode docs
+  - Description: Write consumer documentation for enabling offline mode, configuring modelRouter endpoints, selecting ID strategy, configuring connection quality, handling auth-blocked replay, and rendering conflict UI.
+  - Files: `rtk/README.md`, `ui/README.md` if present, `docs/implementationPlans/offline-mode.md`
+  - Depends on: Task 1.6, Task 2.4, Task 3.3
+  - Acceptance: Docs include copy-pasteable store setup, model config, status hook usage, `OfflineBanner`, and conflict resolution examples.
+
+- [ ] **Task 5.2**: Add end-to-end manual verification guide
+  - Description: Document the exact local steps to verify offline create/update/delete, replay, auth-blocked behavior, spotty status, and conflict resolution using example backend and frontend.
+  - Files: `docs/offline-mode-verification.md` (new) or relevant docs directory, `docs/implementationPlans/offline-mode.md`
+  - Depends on: Task 4.3
+  - Acceptance: Guide lists setup commands, offline simulation steps, expected UI states, and cleanup steps; it does not require editing generated SDK files manually.
+
+- [ ] **Task 5.3**: Run focused validation suite
+  - Description: Run and fix failures for the focused packages touched by offline mode.
+  - Files: no source changes expected unless validation finds failures
+  - Depends on: Task 5.1, Task 5.2
+  - Acceptance: `bun run rtk:compile` or equivalent package compile passes, `bun run ui:test` passes for new UI tests, `bun run api:test` passes for modelRouter tests, and example package checks used by the repo pass or have documented blockers.
+
+- [ ] **Task 5.4**: Regenerate SDK only if backend API surface changes
+  - Description: If implementation changes OpenAPI output for modelRouter conflict responses or example backend route schemas, regenerate `example-frontend/store/openApiSdk.ts` using the SDK generation workflow. If no OpenAPI surface changed, explicitly skip this task in the implementation PR notes.
+  - Files: `example-frontend/store/openApiSdk.ts`, `example-frontend/openapi-config.ts`
+  - Depends on: Task 3.3, Task 4.4
+  - Acceptance: Generated SDK is updated only from the backend OpenAPI spec and never edited manually; PR notes state whether SDK regeneration was required.