@terreno/mcp 57.3.0 → 57.4.0

package/dist/docs/versioned/next/implementationPlans/knip-cleanup.md

@@ -0,0 +1,136 @@
+# Implementation Plan: Remove the Knip baseline
+
+**Status:** Complete  
+**Created:** 2026-09-09  
+**Owner:** unassigned  
+**Primary packages:** repo-wide (`knip.jsonc`, `scripts/static-analysis/`, every workspace Knip currently fingerprints)  
+**RTK deprecation flag:** None
+
+## Goal
+
+`bun run analyze:full` stays green and Knip has no baseline file. Every finding that existed on 2026-09-08 (~1076 fingerprints: 529 default + 547 production) is either **gone from the live Knip report** (fixed) or **declared in `knip.jsonc` with a one-line reason** (disabled).
+
+Inventory snapshot (do not treat as the live list — Pick re-runs Knip):
+
+| Class | Default count (approx.) | Typical cause |
+| --- | --- | --- |
+| unused files | 123 | missing entries (`*.isolated.*`, `scripts/**/*.test.ts`, mcp tests, generated skill copies) |
+| unused exports / types | 212 / 81 | internals still `export`ed; scripts libs not in graph; public API unused in-monorepo |
+| unused dependencies | 62 | Expo autolink / Metro peers Knip cannot see; a few true leftovers |
+| unused devDependencies | 34 | `sinon`, codegen CLIs, types for removed libs |
+| unlisted | 13 | `expo-system-ui` in `app.json`, `jspdf` in metro stubs, optional `ioredis` |
+| binaries / catalog / optional peers | 5 | `eas`, `maestro`, catalog `@sentry/react-native` |
+
+## Non-Goals
+
+- Shrinking published `@terreno/*` public APIs (package `index` re-exports stay).
+- Deleting Expo native, autolink, or Metro packages because Knip cannot see them.
+- Running `knip --fix`.
+- Changing dependency-cruiser rules except regenerating its baseline if a deleted file is listed there.
+- Rewriting Biome or hook wiring.
+
+## Decisions
+
+| Question | Decision |
+|----------|----------|
+| Knip baseline when done? | None. Survivors live only in `knip.jsonc`. |
+| Unused published exports | Unexport or delete symbols **not** on the public package entry. Ignore leftover public API in `knip.jsonc`. |
+| Expo / native `dependencies` Knip cannot see | `ignoreDependencies` / ignore globs with a reason. Do not remove from `package.json`. |
+| Dead in-repo app/demo code | Delete or stop exporting when nothing in-repo uses it. Keep (then ignore as an entry) only what docs, E2E, or codegen still invoke. |
+| Shape | One IP. Tasks by finding class, not one IP per package. |
+
+## Architecture
+
+Knip has an incomplete **entry graph**. Most “unused files” are tests, isolated suites, Metro stubs, codegen configs, and generated skill copies that are never imported. Fix the graph first so later delete/unexport work is not guessing.
+
+```
+knip.jsonc
+  entries     → isolated tests, scripts tests, e2e, codegen, stubs
+  ignore*     → Expo autolink, binaries, public API leftovers
+code          → delete dead files; unexport internal unused symbols
+check:knip    → fail on any finding not handled above
+```
+
+### Disposition rules (Pick must apply in this order)
+
+1. **Entry** — file is executed by Bun/Playwright/Expo/codegen/CI but Knip does not see it. Add `entry` / plugin / workspace config. Do not delete.
+2. **Ignore** — tool-blind (autolink, `app.json` plugins, optional native peers) **or** published public API unused in this monorepo. Add `ignore` / `ignoreDependencies` / `ignoreBinaries` / `ignoreIssues` with a comment naming the reason. Do not delete Expo native deps.
+3. **Unexport** — symbol is `export`ed from an internal module and is not on the package public entry. Drop `export` or move to a non-exported binding.
+4. **Delete** — file or dependency unused after (1)–(3), including in-repo-dead example/demo hooks and leftover `devDependencies` such as `sinon` once the graph is honest.
+
+Never use `knip --fix`. Delete the old JSON baseline only after the live report is empty.
+
+### Public vs internal export
+
+A symbol is **public** if a published package `src/index.ts` / `src/index.tsx` (or documented extra export path in that package’s `package.json` `exports`) re-exports it. All other unused exports are **internal**.
+
+### Expo / Metro ignore set (starting list; Pick verifies)
+
+Apps (`demo`, `admin-spa`, `example-frontend`) and `ui` declare packages for autolinking, fonts, haptics, pickers, Skia, Metro polyfills (`crypto-browserify`, `stream-browserify`), and `jspdf` stubs. `app.json` / `app.config.ts` name `expo-system-ui` (and similar) without a JS import. Those stay in `package.json` and are ignored in Knip.
+
+## Models
+
+None.
+
+## APIs
+
+None. Operator surface is `knip.jsonc`, `bun run check:knip`, and `bun run analyze:full`.
+
+## Notifications
+
+None.
+
+## UI
+
+None. Example-frontend / demo file deletes must not remove screens still routed or documented. Frontend verification applies only to tasks that delete or unwire UI modules: launch the affected app, exercise the related screen, save artifacts.
+
+## Phases
+
+| Phase | Outcome |
+| --- | --- |
+| 1 Entry graph | Isolated tests, `scripts/**/*.test.ts`, mcp tests, e2e, codegen, Metro stubs, generated skill script copies are entries or ignored globs. Unused-file count drops sharply. |
+| 2 Documented ignores | Expo/autolink deps, binaries (`eas`, `maestro`), unlisted `app.json` plugins, catalog-only packages. |
+| 3 True unused packages | Remove `devDependencies` / dependencies that are unused after the graph is honest (`sinon`, stale `@types/*`, etc.). |
+| 4 Dead files | Delete in-repo-dead modules (example hooks, unused stories, unused scripts). |
+| 5 Internal exports | Unexport unused internals. Ignore remaining public unused exports/types. |
+| 6 Contract | Live Knip report empty. Delete the baseline. Rewrite the enforcement docs. |
+
+Keep the existing fat baseline until Phase 6, then delete it once the live report is empty.
+
+## Feature Flags & Migrations
+
+None.
+
+## Activity Log & User Updates
+
+None.
+
+## Not Included / Future Work
+
+- Teaching Knip Expo autolinking for real (upstream / custom compiler).
+- Publishing previously unused public exports with in-repo callers (out of scope; ignore is enough).
+
+## Files to Create / Modify
+
+| File | Role |
+| --- | --- |
+| `knip.jsonc` | Entries, ignores, workspace plugin fixes |
+| `scripts/static-analysis/knip-baseline.json` | Delete after reaching zero findings |
+| `scripts/static-analysis/full.ts` / `lib.test.ts` | Enforce zero findings directly |
+| `docs/explanation/static-analysis.md` | Policy: no Knip baseline; ignore vs delete |
+| Package `package.json` files | Remove true unused deps only |
+| Dead source files listed by live Knip after Phase 1 | Delete or unexport |
+
+## Task List
+
+[`docs/tasks/knip-cleanup.md`](../tasks/knip-cleanup.md)
+
+## Acceptance Criteria
+
+- [ ] `bun run analyze:full` exits 0.
+- [ ] `scripts/static-analysis/knip-baseline.json` does not exist.
+- [ ] Every `ignore` / `ignoreDependencies` / `ignoreBinaries` / `ignoreIssues` entry in `knip.jsonc` has a comment stating why it cannot be a code fix.
+- [ ] No published `@terreno/*` `index` export was removed.
+- [ ] No Expo autolink/native package was removed from an app or `ui` `package.json` solely because Knip flagged it.
+- [ ] `docs/explanation/static-analysis.md` describes the no-baseline policy and forbids `knip --fix`.
+- [ ] `bun test scripts/static-analysis/lib.test.ts` still passes.

package/dist/docs/versioned/next/implementationPlans/migrate-admin-to-syncdb.md

@@ -0,0 +1,210 @@
+# Implementation Plan: Migrate built-in admin to syncdb
+
+**Status:** Approved
+**Branch:** `cursor/migrate-admin-to-syncdb-de61`
+**Owner:** Josh Gachnang
+**Created:** 2026-09-01
+**Grow run:** https://cursor.com/agents/bc-47350376-6566-4c5a-aee2-e6a28698de61
+
+## Goal
+
+Move **built-in admin model list/read/create/update/delete** for collections that already use **String `_id`** onto **windowed local-first syncdb**, with **REST remaining the membership source** (search, sort, pagination, RBAC). Remaining admin RPC (config, scripts, roles, comms, AI, consent, documents, version-config, background-tasks) leaves RTK `injectEndpoints` for a **tiny native `fetch` wrapper** with **host-injected auth**.
+
+Ship **great characterization coverage and CI first**, then protocol, then UI, then hosts. Dual-run RTK `api` for one release so existing hosts keep working; **deprecate `api` / `injectEndpoints` in docs in this IP**; **delete the inject path in the next Terreno major**.
+
+## Non-Goals
+
+- Migrating ObjectId `_id` models (`User`, `AdminAuditLog`, and any other ObjectId collection) onto syncdb. Those stay **fetch CRUD**. No schema migration in this IP.
+- Axios. Admin HTTP uses native `fetch` plus a small wrapper.
+- Full-stream `reconcile()` for admin collections. Admin subscribe is **window mode**: no snapshot of the entire owner/tenant/broadcast stream.
+- A second `sync:` registration on the admin `modelRouter`. One sync registration per model stays on the **app** router (`/todos`, not `/admin/todos`).
+- Changing app-user collections to broadcast. Users keep owner/tenant streams; admin is an extra fan-in (`adminBroadcast`).
+- Removing `injectEndpoints` in this release (next major).
+- Replacing generated OpenAPI SDK, Better Auth Redux, or feature-flag RTK with syncdb.
+
+## Decisions
+
+| # | Question | Decision |
+| --- | --- | --- |
+| Q1 | What data plane does admin use? | String-`_id` **model CRUD** → **syncdb** (windowed). Remaining admin **RPC is not RTK**; dedicated **fetch** hooks. |
+| Q2 | Coverage-first? | **A:** ≥95% line+function on admin packages; **fix CI coverage scope**; add embedded + SPA CRUD E2E **before** behavior migration. |
+| Q3 | HTTP client | Native **`fetch` + tiny wrapper** (AbortController timeout, credentials, JSON/FormData, `APIError`). **No axios**. |
+| Q4 | Auth injection | Host injects `{baseUrl, getAuthHeaders, credentials}`. SPA: `credentials: "same-origin"`. Embedded: Bearer. |
+| Q5 | Local-first shape | **Windowed local-first:** load more hydrates more; keep loaded rows synced. |
+| Q6 | Which models? | **B:** Sync only models that already have **String `_id`**. ObjectId models stay fetch CRUD. |
+| Q7 | RTK dual-run | **B:** Dual-run **this release** (`api` still works). Delete RTK inject path **next major**. |
+| Q8 | List membership vs store | **A:** REST list/search/sort/RBAC stays **membership**. Pages **upsert** into TinyBase. Writes + per-id via syncdb. **Full-stream reconcile OFF** for admin collections. |
+| Q9 | Deltas vs new matches | **A + Refresh:** deltas **update/delete known ids only**. New matches via load-more or **visible Refresh**. No surprise inserts. |
+| Q10 | Owner streams? | Admin needs a **cross-owner** view. Not the signed-in admin's owner stream. |
+| Q11 | Dual-run vs cutover | Land **both** in this IP. **Deprecate `api` in docs now**. Remove `injectEndpoints` **next Terreno major**. |
+| Q12 | Conflicts | **`ConflictSheet`** (`useServer` / `keepMine`) like the example app. |
+| Q13 | Fan-in | **`adminBroadcast: true`** on the **existing** collection `SyncConfig`. Deltas also to `{collection}\|admin`. Admin clients join in **window** mode: no full snapshot/reconcile; hydrate via REST ids + `GET /sync/entities`. |
+
+## Architecture
+
+### Today
+
+Admin CRUD is **RTK `injectEndpoints`** in `@terreno/admin-frontend` (`useAdminApi.ts` → `GET/POST/PATCH/DELETE /admin/{routePath}` plus bulk-patch). Config and other RPC are more inject hooks (`useAdminConfig`, scripts, roles, configuration, documents, comms, AI explorer, consent, version-config, background-tasks).
+
+The backend mounts a **separate** `modelRouter` under `/admin/...` **without** `sync:`. Example `Todo` is already synced on the **app** router (`example-backend/src/api/todos.ts`) with String `_id` + `syncPlugin`. Same Mongo model, different mount. Registry allows **one sync registration per model**; a second `sync` on the admin router is forbidden (`api/src/sync/registrationSideEffects.ts`).
+
+Canonical docs still say profile/admin stay on RTK (`docs/how-to/migrate-rtk-to-syncdb.md`).
+
+### Target data planes
+
+| Surface | After this IP | Auth |
+| --- | --- | --- |
+| String-`_id` model changelist + form | REST membership + TinyBase rows + `{collection}\|admin` window subscribe | Host-injected (cookie or Bearer) via fetch for REST; existing sync socket auth for deltas/mutate |
+| ObjectId model changelist + form | Fetch CRUD only (same `/admin/{routePath}` URLs) | Same fetch wrapper |
+| Admin RPC (config, scripts, roles, comms, …) | Fetch hooks; **not** RTK | Same fetch wrapper |
+| Host RTK `api` | Still accepted; dual-run. Deprecated in docs | Unchanged |
+
+### Windowed local-first (String `_id`)
+
+1. **Membership:** `GET /admin/{routePath}` (existing list/search/sort/RBAC) returns the **page of ids** (and enough fields to render immediately).
+2. **Hydrate:** those ids **upsert** into TinyBase. Missing entities come from `GET /sync/entities` (already exists) when the list payload is incomplete for sync seq / tombstones.
+3. **Subscribe:** admin client joins collection stream `{collection}|admin` in **window** mode. Socket handlers must **not** send a full snapshot or trigger client `reconcile()` of the whole user stream.
+4. **Deltas:** apply **update/delete only if the id is already in the local window**. Unknown ids are ignored (no surprise inserts).
+5. **Load more / Refresh:** load more requests the next REST page and hydrates those ids. **Refresh** re-runs the current REST query and upserts/removes to match membership (visible control).
+6. **Writes:** `useMutate` / `POST /sync/mutate` (same write path as the app) plus admin REST bulk-patch remaining on fetch until a later IP if bulk is not a sync mutation.
+
+Do **not** set collection `scope` to broadcast for the app. App clients keep owner/tenant streams. `adminBroadcast: true` is an **additive fan-in**: change-stream emit also publishes to `{collection}|admin`. Only clients that subscribe in admin window mode join that stream.
+
+### Why not a second sync registration
+
+`registerSync` throws if the model is already registered. Admin REST stays the **admin RBAC/list** surface. Sync stays on the **app** collection registration. Admin UI does not invent a second TinyBase table name; it uses the same collection tag as the app (`todos`), with an admin stream suffix.
+
+### Fetch wrapper
+
+New module in `@terreno/admin-frontend` (not axios, not `emptyApi` JWT refresh). Responsibilities:
+
+- `AbortController` timeout
+- `credentials` (`same-origin` for SPA cookies; `omit`/`include` as injected)
+- `getAuthHeaders()` for Bearer (embedded)
+- JSON body by default; `FormData` passthrough
+- Map non-2xx to `APIError` shape admin already understands
+
+Hosts pass `{baseUrl, getAuthHeaders, credentials}` into `AdminProvider` / existing admin context. SPA must keep cookie session working; embedded example-frontend must keep Bearer.
+
+### Dual-run
+
+`AdminModelTable` / `AdminModelForm` / related hooks:
+
+- If `syncDb` + `adminRequest` (fetch client) are present **and** the model is String `_id` + registered for sync with `adminBroadcast`, use the new path.
+- Else existing `useAdminApi(api, …)` RTK path.
+
+No host is forced to pass `syncDb` this release. Docs tell new/updated hosts to inject both.
+
+### Conflicts
+
+Same `ConflictSheet` as the example app: `useServer` / `keepMine`. Admin window does not invent a second conflict UX.
+
+## Models
+
+No new Mongo models. No `_id` type changes.
+
+| Model (example) | `_id` | This IP |
+| --- | --- | --- |
+| `Todo` | String | Tracer: windowed syncdb + adminBroadcast |
+| Other app models already String `_id` + `sync` | String | Same pattern once `adminBroadcast: true` |
+| `User`, `AdminAuditLog`, other ObjectId | ObjectId | Fetch CRUD only |
+
+`SyncConfig` gains:
+
+```ts
+adminBroadcast?: boolean;
+```
+
+Default `false`. When `true`, emitters also send deltas to `{collection}|admin`. Permission to join that stream is **admin-only** (reuse existing admin permission checks used by `/admin/*`, not owner-stream membership).
+
+## APIs
+
+### Additive protocol
+
+| Piece | Change |
+| --- | --- |
+| `SyncConfig.adminBroadcast` | Opt-in fan-in to `{collection}\|admin` |
+| `sync:subscribe` | Accept window/admin mode (exact payload field named in Pick; suggested `{mode: "window"}` or subscribe to `{tag}\|admin` without snapshot) |
+| `sync:subscribed` | Must not dump full stream snapshot for window subscribers |
+| `GET /sync/entities` | Hydrate known ids (already exists; pin tests) |
+| `GET /admin/{routePath}` | Unchanged membership/search/RBAC |
+| `POST /sync/mutate` | Writes for String `_id` synced models (already exists) |
+
+### Unchanged REST (still used)
+
+- `GET /admin/config`
+- `/admin/{routePath}` list/read/create/update/delete/bulk-patch (membership + ObjectId CRUD + bulk)
+- `/rbac/*`, scripts, configuration, documents, comms, AI, consent, version-config, background-tasks
+
+## Notifications
+
+None. No user-facing comms templates.
+
+## UI
+
+- **Changelist (`AdminModelTable`):** windowed rows from TinyBase for String `_id` synced models; REST pagination/search/sort unchanged; **Refresh** control; load more hydrates more ids; no rows appearing that were not in the last membership set.
+- **Form (`AdminModelForm`):** read/write via syncdb for those models; ObjectId stays fetch.
+- **Conflicts:** `ConflictSheet` when `useConflicts` reports for admin-loaded ids.
+- **Hosts:** `example-frontend` `/admin` and `admin-spa` `/console` both wired for the tracer.
+- Admin v2 `home.slots` unchanged.
+
+## Phases
+
+1. **Characterization + CI** — raise coverage, fix LCOV scope, add package CI jobs, pin URL goldens, add CRUD E2E. **No product behavior change.**
+2. **Fetch wrapper** — client + host injection; migrate RPC inject hooks onto fetch (dual-run until hosts pass the wrapper).
+3. **Protocol** — `adminBroadcast`, `{collection}|admin` emit, window subscribe, skip reconcile, known-id delta apply, entity hydrate tests.
+4. **Admin UI dual-run** — table/form/ConflictSheet/Refresh; ObjectId stays fetch.
+5. **Hosts** — example-frontend + admin-spa; cookie vs Bearer must both work.
+6. **Docs/skills** — stop saying admin collection CRUD stays RTK; deprecate `api` inject; changelog.
+
+Phase 1 is a **hard gate**. Protocol/UI tasks are blocked until Phase 1 acceptance is green.
+
+## Feature Flags & Migrations
+
+No feature flag. `adminBroadcast` is explicit per collection. Hosts opt into the new UI path by passing `syncDb` + fetch client.
+
+**Deprecation:** this release documents “do not add new `injectEndpoints` in admin-frontend.” Next major deletes `useAdminApi` RTK inject and the `api` prop requirement.
+
+## Activity Log & User Updates
+
+No end-user product changelog beyond admin operators. Framework changelog records protocol + deprecation.
+
+## Not Included / Future Work
+
+- ObjectId → String `_id` + `syncPlugin` for User / audit log (own IP; mongoose-schema-safety).
+- Delete RTK inject (next major).
+- Bulk-patch as sync mutations.
+- Admin-only collections with no app router (would still need one `sync:` registration, not a duplicate).
+
+## Files to Create / Modify
+
+**Phase 1:** `admin-frontend/**/*.test.*`, `admin-frontend/bunfig.toml`, `admin-backend` coverage config, `.circleci/continue-config.yml`, root `package.json` (`admin-frontend:test`), `example-frontend/e2e/admin*.spec.ts`, `admin-spa/e2e/**`.
+
+**Phase 2:** `admin-frontend/src/adminRequest.ts` (name at Pick), host context types, RPC hooks listed under Architecture.
+
+**Phase 3:** `api/src/sync/types.ts`, `streams.ts`, change-stream emit, `socketHandlers.ts`, `syncdb/src/client.ts` + subscribe/reconcile/delta applier, tests in `api/src/sync/*.test.ts` and `syncdb/src/sync/*.test.ts`.
+
+**Phase 4:** `AdminModelTable`, `AdminModelForm`, conflict wiring, `useAdminApi` dual-run.
+
+**Phase 5:** `example-frontend` store/syncdb + admin layout; `admin-spa` session fetch + SyncDbProvider.
+
+**Phase 6:** `docs/reference/admin-*.md`, `docs/reference/syncdb.md`, `docs/how-to/migrate-rtk-to-syncdb.md`, `docs/reference/admin-frontend.md` (if present), `terreno-data-fetching` skill (admin fetch exception), `verify-ui-changes`, changelog.
+
+## Task List
+
+[docs/tasks/migrate-admin-to-syncdb.md](../tasks/migrate-admin-to-syncdb.md)
+
+## Acceptance Criteria
+
+- [ ] `admin-frontend` and `admin-backend` report ≥95% line and function coverage on **package source** (not `@terreno/test/dist`). CircleCI runs both package jobs.
+- [ ] Embedded `/admin` and SPA `/console` have CRUD E2E for Todos (list, create, edit, delete, search/filter, bulk where already specified) **before** protocol/UI cutover, and they still pass after cutover.
+- [ ] Example **Todos** admin changelist is windowed local-first: REST membership, TinyBase rows, `{todos}|admin` deltas update known ids only, Refresh/load-more add membership, ConflictSheet works.
+- [ ] ObjectId models still CRUD via fetch; no `_id` migration.
+- [ ] SPA cookie auth and embedded Bearer auth both work; no axios in the new client.
+- [ ] Hosts that still pass only `api` keep working (dual-run).
+- [ ] Docs and skills no longer tell agents to keep admin **collection CRUD** on RTK; `api`/`injectEndpoints` marked deprecated; next-major removal called out.
+- [ ] `bun run lint` and focused package tests pass; `verify-ui-changes` for `/admin` and `/console` tracer.
+
+## Tracer
+
+Example **Todos** admin changelist: `example-frontend` `/admin` and `admin-spa` `/console`.

package/dist/docs/versioned/next/implementationPlans/mongodb-migrations-tooling.md

@@ -0,0 +1,254 @@
+# MongoDB migrations tooling
+
+**Status:** Approved — decisions 2026-09-10  
+**Branch:** `cursor/mongodb-migrations-tooling-04f9`  
+**Owner:** —  
+**Created:** 2026-09-10  
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1189  
+**Primary packages:** `@terreno/api`, `@terreno/admin-backend`, `@terreno/admin-frontend`, `admin-spa`, `example-backend`
+
+## Goal
+
+Give Terreno apps a **versioned MongoDB migration runner** in `@terreno/api`: timestamped `up` / optional `down` files, a **lock** so concurrent deploys cannot double-apply, a **`terreno-migrate` CLI** that **generates files from Mongoose schema diffs** and applies them, an **optional boot hook**, **CI checks**, and an **admin Migrations page** that reuses BackgroundTask / script-runner dry/wet — not the Scripts screen. Ad-hoc backfill scripts remain for one-off maintenance; versioned migrate is the path for schema/index/data changes that must run once per environment.
+
+## Non-Goals
+
+- A separate `@terreno/migrations` package.
+- Framework-shipped migration packs (legacy SyncApp index drops stay in framework startup code).
+- Per-file apply/rollback in the admin UI (v1 is batch pending, like `migrate up`).
+- SQLite / cross-adapter data migration (see [`pluggable-database-sqlite.md`](pluggable-database-sqlite.md)).
+- Fully automatic data backfills for required fields, unique indexes, or renames.
+- Replacing `AdminApp` scripts or `runSeedCli`.
+- Auto `runOnStart` (the hook exists, default off).
+
+## Decisions
+
+| ID | Question | Choice |
+|----|----------|--------|
+| Q1 | Delivery surface | `@terreno/api` exports + `terreno-migrate` CLI (generate from diffs) |
+| Q2 | File layout | `migrations/<timestamp>-<name>.ts` with `up` and optional `down` |
+| Q3 | Production wet apply | `NODE_ENV=production` requires `ALLOW_MIGRATIONS=true`. CLI also needs `--force`. Boot `runOnStart: true` and admin Apply are the force equivalent. |
+| Q4 | Rollback | `down` optional; `migrate down` errors clearly when the target file has no `down` |
+| Q5 | CI | Validate module load + filename order; on a fresh DB run `up` then `down` for files that export `down` |
+| Q6 | Generate source | Current Mongoose models vs last committed `schemaAfter` snapshot in prior generated files (Django `makemigrations`) |
+| Q7 | When `up` runs | CLI always; optional `TerrenoApp` `migrations.runOnStart` (default false) |
+| Q8 | Lock | Wait, heartbeat, steal after **10 minutes** stale TTL |
+| Q9 | Admin | Separate Migrations page; reuse script-runner / `BackgroundTask`; dry + wet |
+| Q10 | Framework packs | App `migrations/` only in v1 |
+| Q11 | Boot gate | `runOnStart: true` plus `ALLOW_MIGRATIONS=true` in production |
+| Q12 | Admin wet in prod | Same `ALLOW_MIGRATIONS` gate as CLI |
+| Q13 | Dry-run | Call pending `up({dryRun: true})`; authors must no-op writes |
+| Q14 | Admin actions | Status + dry-run pending + apply pending as **one** BackgroundTask |
+| Q15 | Generator output | Indexes and safe additive ops generated; required / unique / rename emit a **fail-closed stub** until the author fills the backfill |
+
+**Assumptions (not grilled):** production means `NODE_ENV === "production"`; bin name `terreno-migrate` (same pattern as `terreno-syncdb-codegen`); history+lock live in Mongo collection `terreno_migrations`; seeds must not wipe that collection (already called out in [`seed-a-database.md`](../how-to/seed-a-database.md)).
+
+## Architecture
+
+```
+models (Mongoose)
+    │
+    ├─ terreno-migrate generate
+    │     vs last schemaAfter snapshot
+    │     → migrations/<ts>-<name>.ts  (+ schemaAfter)
+    │
+    ├─ terreno-migrate up|down|status [--dry]
+    │     lock → apply → record
+    │
+    ├─ TerrenoApp({migrations: {dir, models, runOnStart}})
+    │     optional up on listen (same runner)
+    │
+    └─ Admin
+          GET  {base}/migrations/status   collection action (applied / pending)
+          POST {base}/migrations/run?wetRun=
+                collection action → BackgroundTask (batch pending up)
+          GET/DELETE …/scripts/tasks/:id  reuse existing poll/cancel
+```
+
+### Migration module contract
+
+```typescript
+export interface MigrationContext {
+  dryRun: boolean;
+  mongoose: typeof import("mongoose");
+  logger: {info: ...; warn: ...; error: ...; debug: ...};
+  addLog?: (level, message) => Promise<void>;
+  checkCancellation?: () => Promise<void>;
+}
+
+export interface MigrationModule {
+  id: string; // must match filename without .ts
+  up: (ctx: MigrationContext) => Promise<void>;
+  down?: (ctx: MigrationContext) => Promise<void>;
+  /** Present on generated files; omitted on hand-written data migrations. */
+  schemaAfter?: SchemaCatalog;
+}
+```
+
+`loadMigrations({dir})` sorts by filename (`YYYYMMDDHHmmss-slug.ts`). Duplicate ids or a filename/id mismatch fail validation.
+
+### History and lock
+
+Collection `terreno_migrations` (not exposed on `modelRouter`):
+
+| `_id` | Role |
+|-------|------|
+| `"_lock"` | `{holder, heartbeatAt, expiresAt}` |
+| `<migration id>` | `{id, checksum, appliedAt, appliedBy}` |
+
+Lock acquire: if missing or `expiresAt` in the past, take it; else wait (poll ~1s) until expiry, then steal. Holder heartbeats while `up`/`down` runs. Always release in `finally`.
+
+Checksum is a stable hash of the file source. `up` of an already-applied id with a **different** checksum is a hard error (edited after apply).
+
+### Production gate
+
+`assertMigrationsAllowed({isProduction, allowEnv, force})`:
+
+| Environment | Dry-run | Wet |
+|-------------|---------|-----|
+| non-prod | allowed | allowed |
+| prod, `ALLOW_MIGRATIONS` unset | allowed | deny |
+| prod, env set, no force | allowed | deny (CLI) |
+| prod, env set, force (`--force` / `runOnStart` / admin Apply) | allowed | allowed |
+
+Admin status and dry-run never require the env gate. Admin wet in prod requires the env (Apply is force).
+
+### Generator (Q6 + Q15)
+
+`generate({models, dir})`:
+
+1. Build `SchemaCatalog` from registered Mongoose models (paths, types, required, unique, indexes — not methods/virtuals).
+2. Load last `schemaAfter` among sorted files (hand-written files without snapshot are skipped for the baseline).
+3. Diff: add/remove/change index; add optional field; add required field; unique index; rename heuristic (remove+add same type).
+4. Emit one new file:
+   - **Safe:** `createIndex` / `dropIndex` / no-op field comments for optional adds (Mongo is schemaless; optional add is snapshot-only unless an index is involved).
+   - **Unsafe:** required without default, unique, rename → `up` throws unless the author replaces the stub (and `dryRun` still throws so CI fails closed).
+5. Write `schemaAfter` of the **current** catalog so the next generate is incremental.
+6. No-op diff → exit 0, no file.
+
+Do **not** inspect the live database during generate.
+
+### CLI
+
+`@terreno/api` `"bin": {"terreno-migrate": "./src/migrations/cli.ts"}` (`#!/usr/bin/env bun`).
+
+```text
+terreno-migrate generate --dir ./migrations --models ./src/models.ts
+terreno-migrate status   --dir ./migrations
+terreno-migrate up       --dir ./migrations [--dry] [--force]
+terreno-migrate down     --dir ./migrations [--dry] [--force] [--steps N]
+terreno-migrate check    --dir ./migrations   # CI: validate files (no Mongo)
+```
+
+`--models` is a module that exports models (side-effect register) or `{models: Model[]}`. `up`/`down`/`status` need `MONGO_URI` (or `MONGODB_URI`).
+
+### Boot hook
+
+```typescript
+new TerrenoApp({
+  userModel: User,
+  migrations: {
+    dir: "./migrations",
+    models,              // for generate-at-runtime not required; used if runOnStart
+    runOnStart: false,   // default
+  },
+});
+```
+
+When `runOnStart: true`, `start()`/`build()` runs wet `up` after Mongo is connected and **before** listen. Production still requires `ALLOW_MIGRATIONS=true`. Failure aborts boot.
+
+### Admin (reuse script runner, not Scripts)
+
+- Config: `GET /admin/config` includes `migrations?: {enabled: boolean}` when `AdminApp` is given a migration loader (same `dir` as the app).
+- Routes (IsAdmin, authenticate):
+  - `GET {base}/migrations` → `{applied, pending, lock}`
+  - `POST {base}/migrations/run?wetRun=true|false` → `{taskId}` ; runner calls batch `up` with `dryRun: !wetRun`. Prod wet requires `ALLOW_MIGRATIONS`.
+  - Task poll/cancel: **existing** `/scripts/tasks/:id` (same `BackgroundTask`).
+- UI: nav item **Migrations** (`__migrations`), not `__scripts`. List applied/pending; Dry run / Apply pending; poll logs via `useAdminScripts` task endpoints or a thin `useAdminMigrations` wrapper. No per-file buttons.
+
+### CI (Q5)
+
+Export `checkMigrationFiles({dir})` (order, ids, load) and `exerciseReversibleMigrations({dir, connect})` (fresh DB, `up` all, `down` only files with `down`, in reverse, until an irreversible file stops the chain with a recorded skip).
+
+`example-backend` test uses the in-memory Mongo harness. Optional `bun run migrate:check` script.
+
+## Models
+
+No public CRUD model. Internal `terreno_migrations` documents only. Follow mongoose-schema-safety for any schema we do persist (descriptions, plugins only if we use a Mongoose model; a native collection is acceptable to keep this off `checkModelsStrict` consumer lists).
+
+## APIs
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| GET | `{adminBase}/migrations` | Status |
+| POST | `{adminBase}/migrations/run` | Batch pending; `wetRun` query |
+
+Programmatic: `runMigrations`, `loadMigrations`, `generateMigration`, `checkMigrationFiles`, `assertMigrationsAllowed`.
+
+## Notifications
+
+None.
+
+## UI
+
+Admin-spa + admin-frontend: Migrations screen and shell nav. `verify-ui-changes` is mandatory for that task.
+
+## Phases
+
+1. Runner + lock + history + dryRun (programmatic, no CLI).
+2. File loader + CLI `status`/`up`/`down`/`check` + production gate.
+3. `generate` + schema catalog + fail-closed stubs.
+4. `TerrenoApp` `runOnStart`.
+5. Admin HTTP.
+6. Admin UI + spa route.
+7. example-backend files, CI helper usage, docs, mongoose-schema-safety, changelog.
+
+## Feature Flags & Migrations
+
+No feature flag. Opt-in via `migrations` option / CLI. Existing apps unchanged until they add a `migrations/` directory.
+
+## Activity Log & User Updates
+
+Admin Apply creates a `BackgroundTask` (`taskType: "migrations:up"`) with logs; no end-user notifications.
+
+## Not Included / Future Work
+
+- Framework migration pack for SyncApp legacy indexes.
+- Per-migration admin rollback.
+- Live-DB drift command (`schema` vs Mongo indexes).
+- SQLite DDL migrations (owned by the SQLite adapter IP).
+
+## Files to Create / Modify
+
+**Create**
+
+- `api/src/migrations/` — types, lock, runner, loader, generate, cli, tests
+- `docs/how-to/run-mongodb-migrations.md`
+- `example-backend/migrations/` — at least one reversible example + one generated snapshot baseline
+- `admin-frontend/src/AdminMigrations.tsx` (+ tests)
+- `admin-spa/app/migrations.tsx` (or `__migrations` segment)
+
+**Modify**
+
+- `api/package.json` `bin`, `api/src/index.ts`, `api/src/terrenoApp.ts`
+- `admin-backend/src/adminApp.ts` + tests
+- `admin-frontend` shell, router, config types
+- `docs/reference/api.md`, `docs/reference/environment-variables.md`, `docs/reference/admin-config.md`, `docs/how-to/create-a-model.md` or mongoose-schema-safety skill, `docs/how-to/seed-a-database.md` (do not reset `terreno_migrations`)
+- `plugins/terreno-planning/skills/mongoose-schema-safety/SKILL.md` (and `bun run skills:sync`)
+- `CHANGELOG.md`
+
+## Task List
+
+[docs/tasks/mongodb-migrations-tooling.md](../tasks/mongodb-migrations-tooling.md)
+
+## Acceptance Criteria
+
+- [ ] `loadMigrations` + `runMigrations({dryRun})` apply pending ids once, persist history, honor `dryRun` (no history write on dry-run).
+- [ ] Concurrent `up` uses the lock; a stale lock older than 10 minutes is stolen.
+- [ ] Production wet CLI without `ALLOW_MIGRATIONS` or `--force` exits non-zero; dry-run still works.
+- [ ] `down` of a module without `down` fails with an actionable error; modules with `down` reverse on a fresh DB in CI.
+- [ ] `generate` writes a timestamped file from model-vs-snapshot diff; required/unique/rename stubs throw until edited.
+- [ ] `runOnStart: true` applies pending before listen; default omit does not.
+- [ ] Admin Migrations page is not Scripts; dry-run and Apply pending use BackgroundTask; prod Apply without env is 403.
+- [ ] example-backend can `bun run migrate:up` against the test DB; docs describe generate → dry-run → up.
+- [ ] mongoose-schema-safety tells authors to add a versioned migration instead of a one-off script for schema backfills.