@terreno/mcp 57.3.0 → 57.6.0

package/src/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/src/docs/versioned/next/implementationPlans/migrate-cicd-to-circleci-research.md

@@ -1,9 +1,9 @@
 # Research: Migrate CI/CD to CircleCI
 
 **Status:** Research complete — decisions recorded in IP `migrate-cicd-to-circleci.md`  
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1088
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1088
 **Date:** 2026-08-17  
-**Repo:** FlourishHealth/terreno (`master` @ `1e3e79a6`)  
+**Repo:** TerrenoLabs/terreno (`master` @ `1e3e79a6`)  
 **Branch:** `cursor/migrate-cicd-circleci-2b6d`
 
 ## Scope statement

package/src/docs/versioned/next/implementationPlans/migrate-cicd-to-circleci.md

@@ -2,7 +2,7 @@
 
 **Status:** In progress — CI, release, Netlify/GCP production path deploys, and PR previews landed; EAS PR/fingerprint temporarily disabled; GitHub-native maintenance remains  
 **Discussion:** _(none)_  
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1088
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1088
 **Linear:** _(none)_  
 **Priority:** High  
 **Effort:** Large (cross-cutting infra; many workflows)  
@@ -112,7 +112,7 @@ Prefer extending the module (`circleci_oidc` or rename to `ci_oidc` with multipl
 
 ### GitHub ↔ CircleCI integration
 
-- CircleCI GitHub App (or OAuth) on `FlourishHealth/terreno`.
+- CircleCI GitHub App (or OAuth) on `TerrenoLabs/terreno`.
 - Status checks reported to GitHub for branch protection (job names documented in `docs/explanation/repository-settings.md`).
 - PR comments / labels / Deployments API: call GitHub REST via `gh` or `curl` with `terreno-github-api` context (replaces `GITHUB_TOKEN` action privileges).
 - Tag + schedule triggers: CircleCI pipeline triggers (or GitHub → CircleCI API webhook) for cron jobs currently on GHA.
@@ -168,7 +168,7 @@ Implemented: production and PR preview jobs exist on CircleCI. GitHub Actions
 is the live Netlify/GCP writer until `terreno-netlify` / `terreno-gcp` are
 populated; CircleCI deploy scripts skip (exit 0) when those variables are
 missing. After a successful CircleCI deploy, set GHA deploy workflows back to
-`on: []` in the same change. Preview cleanup on PR close is GHA
+`push.branches-ignore: ["**"]` in the same change. Preview cleanup on PR close is GHA
 `preview-cleanup.yml` plus the manual CircleCI parameter.
 
 ### Phase 5 — EAS + fingerprint (v1)
@@ -177,7 +177,7 @@ missing. After a successful CircleCI deploy, set GHA deploy workflows back to
 - PR comment + `fingerprint-acknowledged` label via GitHub API.
 
 Manual EAS dispatch is implemented. EAS PR updates and fingerprint
-acknowledgement are retained with `on: []` until CircleCI comment/label parity
+acknowledgement are retained with `push.branches-ignore: ["**"]` until CircleCI comment/label parity
 is implemented.
 
 ### Phase 6 — GCP CD + OIDC (v1)
@@ -204,7 +204,7 @@ are ported.
 
 ### Phase 8 — Mobile runners (post-v1 / still required for full cutover)
 
-- Maestro web/Chrome (`maestro-e2e`) is implemented on CircleCI Linux browsers + Mongo replica set. GHA `maestro-e2e.yml` is `on: []`.
+- Maestro web/Chrome (`maestro-e2e`) is implemented on CircleCI Linux browsers + Mongo replica set. GHA `maestro-e2e.yml` is `push.branches-ignore: ["**"]`.
 - Appium Android on Linux VM and Appium iOS on CircleCI macOS remain unported.
 
 ### Phase 9 — GitHub-native + agentic replacements (full cutover)
@@ -215,7 +215,7 @@ are ported.
 | `dependabot-auto-merge` | Keep Dependabot PRs on GitHub; auto-merge via CircleCI on Dependabot branches **or** Renovate on CircleCI |
 | `triage.yml` | CircleCI pipeline trigger on `issues` via GitHub Apps webhook → CircleCI API, or GitHub Action **stub** only if product accepts residual GHA (conflicts with CC1 — prefer webhook) |
 | `roadmap-generate` | Scheduled CircleCI job with `ROADMAP_PROJECT_TOKEN` |
-| `architectural-pr-review` | Implemented: CircleCI job + `CURSOR_API_KEY` / `GITHUB_TOKEN`. Checks out `origin/master`, skips forks. GHA workflow is `on: []`. |
+| `architectural-pr-review` | Implemented: CircleCI job + `CURSOR_API_KEY` / `GITHUB_TOKEN`. Checks out `origin/master`, skips forks. GHA workflow is `push.branches-ignore: ["**"]`. |
 | Cursor Approval / Security / Bugbot | **Cannot move.** Cursor GitHub App automations, not repo workflows. |
 | `agentics-maintenance` + `*.lock.yml` gh-aw | Re-home to CircleCI scheduled pipelines calling the same scripts **or** retire features; do not leave gh-aw as the only runner if CC1 holds |
 | `docs-audit` | Scheduled CircleCI job |

package/src/docs/versioned/next/implementationPlans/model-router-actions.md

@@ -2,7 +2,7 @@
 
 **Status:** Deferred
 **Closed:** 2026-08-20 — Not pursued; custom `endpoints` callbacks remain the supported pattern for non-CRUD routes.
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1097
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1097
 
 ## Goal
 

package/src/docs/versioned/next/implementationPlans/model-router-mcp.md

@@ -2,7 +2,7 @@
 
 **Status:** Complete (write path now uses unified mutation executors — see [unified-mutation-executors.md](unified-mutation-executors.md); list/read remain handlers)
 
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1092
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1092
 *When an engineer is assigned to a project but before you begin coding, you should fill in the implementation plan and get feedback from the engineering team. Once you have finished or you make any changes, tag Josh with the @ symbol so he can review. Also tag anyone else that needs to be notified, has conflicting work, etc.*
 
 ## Overview

package/src/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/TerrenoLabs/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.

package/src/docs/versioned/next/implementationPlans/native-module-baseline.md

@@ -1,7 +1,7 @@
 # Implementation Plan: Native module baseline for the next major release
 
 **Status:** Draft
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1026
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1026
 **Priority:** High
 **Effort:** Small batch (code) — coordination cost is the release itself
 **Owner:** unassigned