@terreno/mcp 57.2.0 → 57.4.0

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

@@ -0,0 +1,209 @@
+# Tasks: Migrate built-in admin to syncdb
+
+IP: [migrate-admin-to-syncdb.md](../implementationPlans/migrate-admin-to-syncdb.md)
+
+**Status:** Approved. Pick–Roast execution is in progress.
+
+Skills for Pick: `terreno-data-fetching`, `terreno-backend-api`, `mongoose-schema-safety` (only if a later task touches schema — this IP must not), `generate-sdk` (only if OpenAPI for non-admin routes changes), `verify-ui-changes`, `update-docs`, `backend-test-env`, `terreno-ui`, `update-agent-docs`.
+
+---
+
+## Phase 1 — Characterization + CI (no product behavior)
+
+Phase 1 is a hard gate. Protocol and UI tasks stay blocked until every Phase 1 checkbox is done.
+
+- [x] **Task 1.1**: `admin-frontend` ≥95% line+function coverage + threshold
+  - Delivers: existing screens/hooks covered enough that `bun test` in `admin-frontend` meets 95% lines and functions; `bunfig.toml` `coverageThreshold` set so CI fails on drop
+  - Files: `admin-frontend/src/**/*.test.*`, `admin-frontend/bunfig.toml`
+  - Blocked by: none
+  - Acceptance: `cd admin-frontend && bun test --coverage` reports ≥95% lines and functions; threshold is committed
+
+- [x] **Task 1.2**: `admin-backend` coverage scope excludes `@terreno/test` dist
+  - Delivers: LCOV / bun coverage for the package measures `admin-backend/src` (and dist of this package only), not `../test/dist/**`; package still ≥95% on that scope
+  - Files: `admin-backend/bunfig.toml` (or coverage ignore), related test config
+  - Blocked by: none
+  - Acceptance: coverage report no longer attributes `@terreno/test` files; `adminApp.ts` and package source still ≥95%; `cd admin-backend && bun test --coverage` green
+
+- [x] **Task 1.3**: CircleCI jobs for admin packages
+  - Delivers: `admin-backend-ci` and `admin-frontend-ci` in continue-config; root script `admin-frontend:test`; both jobs in the required workflow
+  - Files: `.circleci/continue-config.yml`, `package.json`
+  - Blocked by: 1.1, 1.2
+  - Acceptance: config YAML lists both jobs; `bun run admin-frontend:test` and `bun run admin-backend:test` work from repo root
+
+- [x] **Task 1.4**: Shard existing admin Playwright specs into CI
+  - Delivers: `example-frontend/e2e/admin-home.spec.ts`, `admin-form.spec.ts`, `admin-table-search-filter.spec.ts`, `admin-table-bulk-actions.spec.ts`, `admin-custom-screens.spec.ts`, `admin-comms-back.spec.ts` (and siblings that exist) run in the CircleCI Playwright matrix, not only `admin.spec.ts`
+  - Files: `.circleci/continue-config.yml`, any e2e project config
+  - Blocked by: none
+  - Acceptance: continue-config matrix includes those spec files; a dry read of the YAML shows them next to `admin.spec.ts`
+
+- [x] **Task 1.5**: Golden HTTP tests for admin membership + config
+  - Delivers: pinned assertions for `GET /admin/config` shape and list/search/bulk-patch on a synced String `_id` model (example Todo) plus an ObjectId model (User) so later protocol work cannot silently change REST
+  - Files: `admin-backend/src/adminApp*.test.ts` (or new focused spec)
+  - Blocked by: none
+  - Acceptance: tests fail if list query params, pagination envelope, or bulk-patch URL/body change; `bun test` in admin-backend passes
+
+- [x] **Task 1.6**: Pin `useAdminApi` URL shapes
+  - Delivers: isolated tests that `list/read/create/update/delete/bulk-patch` hit `/admin/{routePath}` exactly as today
+  - Files: `admin-frontend/src/isolated/hooks.isolated.tsx`, `useAdminApi` tests
+  - Blocked by: none
+  - Acceptance: URL/method goldens for all six operations; isolated suite green
+
+- [x] **Task 1.7**: CRUD smoke E2E for embedded + SPA
+  - Delivers: Playwright covering Todos list → create → edit → delete on `example-frontend` `/admin` and `admin-spa` `/console` (extend existing specs; do not skip login/consent)
+  - Files: `example-frontend/e2e/admin.spec.ts` (or `admin-form.spec.ts`), `admin-spa/e2e/integration/adminSpa.integration.spec.ts` or new `admin-spa/e2e/crud.spec.ts`
+  - Blocked by: none
+  - Acceptance: specs assert visible row after create, field change after edit, row gone after delete; they pass locally against the documented full-stack commands
+  - Skills: `verify-ui-changes` (record how to run; Phase 1 may land specs that CI runs)
+
+---
+
+## Phase 2 — Fetch wrapper (RPC off RTK)
+
+- [x] **Task 2.1**: Tiny fetch client
+  - Delivers: `adminRequest({url, method, body, signal})` using native `fetch`, AbortController timeout, JSON + FormData, maps failures to `APIError`; unit tests with mocked `globalThis.fetch`
+  - Files: `admin-frontend/src/adminRequest.ts`, `admin-frontend/src/adminRequest.test.ts`
+  - Blocked by: 1.1
+  - Acceptance: tests for timeout abort, 4xx/5xx → APIError, JSON parse, FormData not JSON-stringified, credentials forwarded; no axios import
+  - Skills: `terreno-data-fetching`
+
+- [x] **Task 2.2**: Host-injected auth contract
+  - Delivers: admin context accepts `{baseUrl, getAuthHeaders, credentials}`; SPA fixture uses `credentials: "same-origin"` and empty/cookie headers; embedded fixture uses Bearer from `getAuthHeaders`
+  - Files: admin-frontend provider/context (existing Admin host types), tests
+  - Blocked by: 2.1
+  - Acceptance: unit tests prove Authorization header present/absent per fixture; cookie credential mode set
+  - Skills: `terreno-data-fetching`
+
+- [x] **Task 2.3**: Dual-run RPC hooks onto fetch
+  - Delivers: `useAdminConfig`, scripts, roles, configuration, documents, comms, AI explorer, consent, version-config, background-tasks, `AdminObjectPicker` list fetch use `adminRequest` when the client is provided; if only `api` is provided, existing `injectEndpoints` still works
+  - Files: `admin-frontend/src/useAdminConfig.ts`, `useAdminScripts.ts`, `useAdminRoles.ts`, `useConfigurationApi.ts`, `useDocumentStorageApi.ts`, `useAdminBackgroundTask.ts`, `useConsentHistory.ts`, `ConsentFormEditor.tsx`, `AdminVersionConfig.tsx`, `AdminObjectPicker.tsx`, `comms/useCommsDashboardApi.tsx`, `widgets/AIRequestsScreenWidget.tsx`, tests
+  - Blocked by: 2.2, 1.6
+  - Acceptance: each hook has tests for both backends; no behavior change when only `api` is passed
+  - Skills: `terreno-data-fetching`
+
+---
+
+## Phase 3 — Protocol (`adminBroadcast` + window subscribe)
+
+- [x] **Task 3.1**: `adminBroadcast` on `SyncConfig`
+  - Delivers: optional `adminBroadcast?: boolean` on existing collection `sync` config; default false; registration stores the flag; docs comment in types
+  - Files: `api/src/sync/types.ts`, `api/src/api.ts` (options plumbing), `api/src/sync/*.test.ts`
+  - Blocked by: 1.5
+  - Acceptance: registering with/without the flag; existing sync tests pass; no second `registerSync` for the same model
+  - Skills: `terreno-backend-api`
+
+- [x] **Task 3.2**: Emit deltas to `{collection}|admin`
+  - Delivers: when `adminBroadcast` is true, change-stream / mutate emit also targets `{collection}|admin` in addition to the owner/tenant/broadcast stream
+  - Files: emit path under `api/src/sync/` (change stream + mutate ack), tests
+  - Blocked by: 3.1
+  - Acceptance: unit/socket test: owner-scoped Todo create emits to `todos|owner:{id}` **and** `todos|admin`; flag false emits only the owner stream
+  - Skills: `terreno-backend-api`
+
+- [x] **Task 3.3**: Window subscribe — no snapshot, no full reconcile
+  - Delivers: admin clients subscribe to `{collection}|admin` (or `sync:subscribe` with window mode) and receive **cursor/ack only**, not a full snapshot; syncdb skips `reconcile()` for that collection while in window mode
+  - Files: `api/src/sync/socketHandlers.ts`, `syncdb/src/client.ts`, subscribe/bootstrap/reconcile modules, tests on both sides
+  - Blocked by: 3.2
+  - Acceptance: socket test: window subscribe does not emit snapshot pages; client test: reconcile interval does not GET `/sync/snapshot` for that collection
+  - Skills: `terreno-backend-api`
+
+- [x] **Task 3.4**: Hydrate known ids via REST + `GET /sync/entities`
+  - Delivers: helper used by admin UI (or syncdb window API) that given ids upserts entities; missing rows fetched from `/sync/entities`; RBAC: only admin-capable users may subscribe to `|admin`
+  - Files: `syncdb/src/sync/httpChannel.ts` (entities already), new window hydrate helper if needed, `api/src/sync/socketHandlers.ts` permission, tests
+  - Blocked by: 3.3, 1.5
+  - Acceptance: tests: hydrate 2 of 3 ids; unknown id ignored; non-admin subscribe to `|admin` nacks
+  - Skills: `terreno-backend-api`, `terreno-data-fetching`
+
+- [x] **Task 3.5**: Known-id-only deltas + Refresh contract
+  - Delivers: delta applier in window mode updates/deletes **existing local ids only**; new server rows do not appear until membership Refresh or load-more upserts them
+  - Files: `syncdb/src/sync/deltaApplier.ts`, tests
+  - Blocked by: 3.3
+  - Acceptance: tests: delta for unknown id is no-op; delta for known id updates store; delete delta removes known id; documented Refresh is a REST re-query + upsert (implemented in 4.x, contract tested here at applier)
+
+---
+
+## Phase 4 — Admin UI dual-run
+
+- [x] **Task 4.1**: `AdminModelTable` windowed path
+  - Delivers: when `syncDb` + fetch client present and model is String `_id` + synced + `adminBroadcast`, table membership from REST, rows from TinyBase, load more hydrates, Refresh control visible
+  - Files: `admin-frontend/src/AdminModelTable.tsx`, tests
+  - Blocked by: 3.4, 3.5, 2.2, 1.7
+  - Acceptance: unit tests with fake syncdb: page ids render; extra delta id does not render; Refresh adds it; RTK path still used when `api` only
+  - Skills: `terreno-ui`, `verify-ui-changes`
+
+- [x] **Task 4.2**: `AdminModelForm` syncdb writes
+  - Delivers: create/update/delete for String `_id` synced models go through `useMutate`; ObjectId models stay fetch/RTK dual-run
+  - Files: `admin-frontend/src/AdminModelForm.tsx`, tests
+  - Blocked by: 4.1
+  - Acceptance: form save tests for both model classes; ObjectId never calls `useMutate`
+  - Skills: `terreno-ui`
+
+- [x] **Task 4.3**: ConflictSheet in admin
+  - Delivers: `useConflicts` + `ConflictSheet` (`useServer` / `keepMine`) for admin-loaded ids, same as example app
+  - Files: admin-frontend conflict host (table or shell), tests
+  - Blocked by: 4.2
+  - Acceptance: test: conflict row shows sheet; keepMine / useServer callbacks invoked
+  - Skills: `terreno-ui`
+
+- [x] **Task 4.4**: Bulk-patch stays fetch
+  - Delivers: existing bulk-patch still uses fetch/RTK dual-run (not sync mutate) with goldens from 1.5/1.6 still passing
+  - Files: table bulk actions wiring
+  - Blocked by: 2.3, 4.1
+  - Acceptance: bulk-patch tests still pass on both backends
+
+---
+
+## Phase 5 — Hosts
+
+- [x] **Task 5.1**: example-frontend `/admin`
+  - Delivers: `AdminProvider` gets fetch client (Bearer) + existing `syncDb`; example `Todo` `sync` sets `adminBroadcast: true`; `/admin` Todos changelist uses windowed path
+  - Files: `example-frontend` admin layout/store, `example-backend/src/api/todos.ts` (`adminBroadcast: true`)
+  - Blocked by: 4.3, 4.4
+  - Acceptance: `bun run backend:dev` + `frontend:web`; Playwright from 1.7 still passes; new assertions for Refresh optional
+  - Skills: `verify-ui-changes`, `generate-sdk` only if OpenAPI changed (should not)
+
+- [x] **Task 5.2**: admin-spa `/console`
+  - Delivers: same windowed Todos path with `credentials: "same-origin"`; SyncDbProvider in SPA; cookie session still logs in
+  - Files: `admin-spa` app providers, e2e
+  - Blocked by: 5.1
+  - Acceptance: SPA CRUD E2E from 1.7 passes with the new path; no Bearer required for same-origin
+  - Skills: `verify-ui-changes`
+
+---
+
+## Phase 6 — Docs, skills, deprecation
+
+- [x] **Task 6.1**: Human + agent docs
+  - Delivers: admin collection CRUD documented as windowed syncdb; RPC as fetch wrapper; `adminBroadcast` + window subscribe in syncdb reference; migrate-rtk guide no longer says admin collection CRUD stays RTK; `api`/`injectEndpoints` deprecated; next-major removal named; changelog
+  - Files: `docs/reference/syncdb.md`, `docs/how-to/migrate-rtk-to-syncdb.md`, `docs/reference/admin.md` / `admin-frontend` pages if present, `.rulesync/skills/terreno-data-fetching`, `verify-ui-changes` if admin login steps change, changelog
+  - Blocked by: 5.2
+  - Acceptance: `update-docs` checklist; `bun run skills:sync` if skill text changed; no remaining “keep admin on RTK” for **model CRUD**
+  - Skills: `update-docs`, `update-agent-docs`
+
+---
+
+## Task graph (Pick frontier)
+
+```
+1.1 1.2 1.4 1.5 1.6 1.7
+  └─ 1.3 (needs 1.1+1.2)
+
+2.1 ← 1.1
+2.2 ← 2.1
+2.3 ← 2.2, 1.6
+
+3.1 ← 1.5
+3.2 ← 3.1
+3.3 ← 3.2
+3.4 ← 3.3, 1.5
+3.5 ← 3.3
+
+4.1 ← 3.4, 3.5, 2.2, 1.7
+4.2 ← 4.1
+4.3 ← 4.2
+4.4 ← 2.3, 4.1
+
+5.1 ← 4.3, 4.4
+5.2 ← 5.1
+6.1 ← 5.2
+```
+
+First Pick after Approved: **Task 1.1** (and any other Phase 1 tasks with `Blocked by: none` as the frontier).

package/dist/docs/versioned/next/tasks/migrate-cicd-to-circleci.md

@@ -98,11 +98,12 @@ Research: [`docs/implementationPlans/migrate-cicd-to-circleci-research.md`](../i
 
 ## Phase 4: Netlify deploys
 
-- [ ] **Task 4.1**: Port demo / frontend-example / docs Netlify workflows
+- [x] **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.
+  - Note: Path filters and preview jobs exist. Live Netlify still runs on GHA until `terreno-netlify` is filled; CircleCI skips. Cleanup on PR close is GHA `preview-cleanup.yml`.
 
 - [ ] **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`.
@@ -144,11 +145,12 @@ Research: [`docs/implementationPlans/migrate-cicd-to-circleci-research.md`](../i
   - Depends on: Task 0.1
   - Acceptance: `gcloud` auth from a CircleCI job succeeds with WIF (no JSON key).
 
-- [ ] **Task 6.2**: Port `cd.yml`
+- [x] **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.
+  - Note: Path filters exist. Live GCP still runs on GHA until `terreno-gcp` is filled; CircleCI skips apply.
 
 - [ ] **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).
@@ -172,11 +174,11 @@ Research: [`docs/implementationPlans/migrate-cicd-to-circleci-research.md`](../i
 
 ## 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`
+- [x] **Task 8.1**: Port Maestro web E2E
+  - Description: Port `maestro-e2e` (Chrome + xvfb against example-frontend, optional demo smokes) to CircleCI `node22_browsers_mongo_rs`. Appium Android remains separate.
+  - Files: `.circleci/continue-config.yml`, `.circleci/config.yml`, `.github/workflows/maestro-e2e.yml`
   - Depends on: Task 5.2
-  - Acceptance: manual pipeline runs Android Appium and Maestro successfully.
+  - Acceptance: CircleCI `maestro-e2e` is the writer; GHA workflow is `on: []`.
 
 - [ ] **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`.
@@ -184,6 +186,12 @@ Research: [`docs/implementationPlans/migrate-cicd-to-circleci-research.md`](../i
   - Depends on: Task 8.1
   - Acceptance: iOS Appium green on a representative run; then delete GHA Appium workflow.
 
+- [ ] **Task 8.3**: Port Appium Android
+  - Description: Linux VM with emulator strategy documented.
+  - Files: `.circleci/continue-config.yml`
+  - Depends on: Task 8.1
+  - Acceptance: Android Appium green on a representative run.
+
 ## Phase 9: GitHub-native + agentic replacements
 
 - [ ] **Task 9.1**: Replace CodeQL workflow
@@ -198,11 +206,17 @@ Research: [`docs/implementationPlans/migrate-cicd-to-circleci-research.md`](../i
   - 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`
+- [x] **Task 9.3a**: Port architectural PR review
+  - Description: CircleCI `architectural-pr-review` runs `.github/scripts/architectural-pr-review.ts` after checking out `origin/master`. Skips forks and missing `CURSOR_API_KEY` / `GITHUB_TOKEN`. GHA workflow is `on: []`.
+  - Files: `.circleci/continue-config.yml`, `.github/workflows/architectural-pr-review.yml`, `.github/scripts/architectural-pr-review.ts`
+  - Depends on: Task 0.2
+  - Acceptance: CircleCI job is the writer; Cursor Approval Agent stays on GitHub.
+
+- [ ] **Task 9.3b**: Replace remaining gh-aw agentics
+  - Description: Per lockfile (`update-rules`, `update-docs`, daily improvers) and `agentics-maintenance`: either port to CircleCI scheduled pipelines or retire with maintainer sign-off.
+  - Files: `.github/workflows/*lock*`, `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.
+  - Acceptance: written retire-or-port decision for each remaining lock workflow.
 
 ## Phase 10: Cleanup
 

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

@@ -0,0 +1,107 @@
+# Tasks: MongoDB migrations tooling
+
+IP: [mongodb-migrations-tooling.md](../implementationPlans/mongodb-migrations-tooling.md)  
+**Closes:** https://github.com/FlourishHealth/terreno/issues/1189
+
+**Feature profile:** false (full IP)
+
+## Phase 1 — Runner, lock, history
+
+- [x] **Task 1.1**: Migration context + in-memory/programmatic runner
+  - Delivers: `runMigrations({migrations, dryRun})` runs pending `up` in order; dry-run calls `up({dryRun: true})` and does **not** record applied ids; wet records checksum + `appliedAt`; already-applied ids are skipped; checksum mismatch throws
+  - Files: `api/src/migrations/types.ts`, `api/src/migrations/runner.ts`, `api/src/migrations/runner.test.ts`
+  - Blocked by: none
+  - Skills: `terreno-backend-api`, `backend-test-env`, `mongoose-schema-safety`
+  - Docs: stub “Migrations” subsection in `docs/reference/api.md`
+  - Acceptance: bun tests — dry-run increments a counter inside `up` but history stays empty; wet applies once; second wet is a no-op; edited checksum fails
+
+- [x] **Task 1.2**: Lock collection (wait, heartbeat, 10-minute steal)
+  - Delivers: `withMigrationLock` uses `terreno_migrations` `_id: "_lock"`; concurrent second waiter proceeds after steal when `expiresAt` is past; holder heartbeats; `finally` releases
+  - Files: `api/src/migrations/lock.ts`, `api/src/migrations/lock.test.ts`; wire lock around wet `runMigrations`
+  - Blocked by: 1.1
+  - Skills: `backend-test-env`, `mongoose-schema-safety`
+  - Docs: lock TTL in the api.md stub
+  - Acceptance: two overlapping wet runs serialize; expired lock is stolen; crash-simulated missing release still steals after TTL (test injects past `expiresAt`)
+
+## Phase 2 — Files, CLI, production gate
+
+- [x] **Task 2.1**: File loader + `checkMigrationFiles`
+  - Delivers: load `migrations/<YYYYMMDDHHmmss>-<slug>.ts`; id must match filename; duplicate ids fail; optional `down`; `checkMigrationFiles` is the no-Mongo CI check
+  - Files: `api/src/migrations/load.ts`, `api/src/migrations/load.test.ts`, fixture files under `api/src/migrations/fixtures/`
+  - Blocked by: 1.1
+  - Skills: `terreno-backend-api`
+  - Docs: file naming in api.md
+  - Acceptance: tests for sort order, bad id, missing export, successful load of `up`/`down`
+
+- [x] **Task 2.2**: Production gate + CLI `status`/`up`/`down`/`check`
+  - Delivers: `terreno-migrate` bin; prod wet requires `ALLOW_MIGRATIONS=true` and `--force`; `down --steps` stops with a clear error when `down` is missing; `--dry` never writes history
+  - Files: `api/src/migrations/cli.ts`, `api/src/migrations/cli.test.ts`, `api/package.json` `bin`, `api/src/index.ts` exports
+  - Blocked by: 1.2, 2.1
+  - Skills: `terreno-backend-api`, `backend-test-env`
+  - Docs: command table in `docs/how-to/run-mongodb-migrations.md` (create page); `ALLOW_MIGRATIONS` row in `docs/reference/environment-variables.md`
+  - Acceptance: argv tests (help, check, dry up, prod deny); integration up/down against memory Mongo; `down` without function fails
+
+## Phase 3 — Generate from schema snapshot
+
+- [x] **Task 3.1**: Schema catalog + diff
+  - Delivers: `buildSchemaCatalog(models)` and `diffSchemaCatalog(before, after)` covering indexes, optional fields, required, unique, rename heuristic
+  - Files: `api/src/migrations/schemaCatalog.ts`, `api/src/migrations/schemaCatalog.test.ts`
+  - Blocked by: none (can parallel 1.x in theory; Pick runs after 2.2)
+  - Skills: `mongoose-schema-safety`
+  - Docs: what generate can/cannot emit (how-to)
+  - Acceptance: fixture schemas produce stable catalogs; required+unique+rename classified unsafe; optional field + index classified safe
+
+- [x] **Task 3.2**: `generate` CLI writes a timestamped file
+  - Delivers: `terreno-migrate generate --dir --models`; uses last `schemaAfter`; no-op diff exits 0; unsafe ops emit throwing stub; generated `up` honors `dryRun` for safe index ops
+  - Files: `api/src/migrations/generate.ts`, `api/src/migrations/generate.test.ts`, CLI subcommand
+  - Blocked by: 2.2, 3.1
+  - Skills: `mongoose-schema-safety`, `update-docs`
+  - Docs: generate workflow on the how-to
+  - Acceptance: temp dir tests — first generate from empty snapshot; second generate no-op; required-field stub throws in dry-run and wet
+
+## Phase 4 — Boot hook
+
+- [x] **Task 4.1**: `TerrenoApp` `migrations.runOnStart`
+  - Delivers: option default off; when true, wet `up` after DB connect before listen; prod still needs `ALLOW_MIGRATIONS`; failure prevents listen
+  - Files: `api/src/terrenoApp.ts`, `api/src/terrenoApp.migrations.test.ts` (or extend existing app tests)
+  - Blocked by: 2.2
+  - Skills: `terreno-backend-api`, `backend-test-env`
+  - Docs: option table in api.md
+  - Acceptance: tests — omitted option does not query `terreno_migrations`; `runOnStart: true` applies pending; prod without env throws before listen
+
+## Phase 5 — Admin HTTP
+
+- [x] **Task 5.1**: Admin migrations routes + config flag
+  - Delivers: `GET /admin/migrations/status` and `POST /admin/migrations/run?wetRun=` as `modelRouter` collection actions; creates BackgroundTask and runs batch pending; poll/cancel via existing script task routes; prod wet 403 without `ALLOW_MIGRATIONS`; `GET /admin/config` includes `migrations.enabled`
+  - Files: `admin-backend/src/adminApp.ts`, `admin-backend/src/adminApp.migrations.test.ts`, AdminApp options type
+  - Blocked by: 1.2, 2.1
+  - Skills: `terreno-backend-api`, `building-admin-interfaces`, `backend-test-env`
+  - Docs: `docs/reference/admin-config.md` + admin-backend reference
+  - Acceptance: 201 + taskId; dry-run does not persist applied ids; non-admin 403; unknown when migrations not configured 404
+
+## Phase 6 — Admin UI
+
+- [x] **Task 6.1**: Migrations page, nav, spa route
+  - Delivers: `__migrations` screen distinct from `__scripts`; status list; Dry run / Apply pending; reuse task polling (script-runner modal or equivalent); shell nav when `migrations.enabled`
+  - Files: `admin-frontend/src/AdminMigrations.tsx`, tests, `AdminShell.tsx`, `AdminScreenRouter.tsx`, types; `admin-spa` route
+  - Blocked by: 5.1
+  - Skills: `terreno-ui`, `building-admin-interfaces`, `verify-ui-changes`, `update-docs`
+  - Docs: `docs/how-to/build-admin-screens.md` nav note
+  - Acceptance: frontend tests for routing/nav; browser verification of dry-run vs apply on example admin (artifacts under `/opt/cursor/artifacts/`)
+
+## Phase 7 — Example, CI, agent docs
+
+- [x] **Task 7.1**: example-backend wiring + reversible fixture
+  - Delivers: `example-backend/migrations/` with a reversible index (or no-op) migration; package scripts `migrate:check` / `migrate:up` / `migrate:status`; test `exerciseReversibleMigrations`; do not wipe `terreno_migrations` in seed reset
+  - Files: `example-backend/package.json`, `example-backend/src/server.ts` (pass `migrations` into AdminApp + TerrenoApp), seed reset guard, tests
+  - Blocked by: 2.2, 5.1
+  - Skills: `update-docs`, `backend-test-env`
+  - Docs: example commands on the how-to
+  - Acceptance: `bun test` in example-backend covers migrate check + up/down; seed `--reset` leaves history collection
+
+- [x] **Task 7.2**: Diátaxis, changelog, mongoose-schema-safety
+  - Delivers: how-to complete; api/env/admin reference; skill tells authors to use versioned migrations for backfills; `CHANGELOG.md` Added; `bun run skills:sync` / `bun run rules` if the skill source changed
+  - Files: `docs/how-to/run-mongodb-migrations.md`, `docs/how-to/README.md`, `docs/reference/*`, `docs/how-to/seed-a-database.md`, `plugins/terreno-planning/skills/mongoose-schema-safety/SKILL.md` (canonical then sync), `CHANGELOG.md`
+  - Blocked by: 3.2, 4.1, 6.1, 7.1 (content must match shipped CLI/UI)
+  - Skills: `update-docs`
+  - Acceptance: stranger can generate → dry-run → up from the how-to; skill no longer points only at ad-hoc `ScriptRunner` backfills

package/dist/docs/versioned/next/tasks/notification-center.md

@@ -0,0 +1,102 @@
+# Tasks: In-app notification center
+
+IP: [notification-center.md](../implementationPlans/notification-center.md)  
+**Closes:** https://github.com/FlourishHealth/terreno/issues/1179
+
+**Feature profile:** false (full IP)
+
+## Phase 1 — Tracer (inbox write + sync)
+
+- [x] **Task 1.1**: Notification model + `NotificationsApp` + `notify()` inbox write
+  - Delivers: `new NotificationsApp()` registers owner-scoped `/notifications` with `create: []`, `sync: {scope: {type: "owner"}}`, `isDeletedPlugin` + `syncPlugin`; `getNotificationService().notify({userId, title, body, href?, kind?})` inserts a row and change-stream/sync can see it; HTTP/sync create is 403/nack
+  - Files: `api/src/models/notification.ts`, `api/src/types/notification.ts`, `api/src/notifications/notificationsApp.ts`, `api/src/notifications/notificationService.ts`, `api/src/notifications/notificationsApp.test.ts`, `api/src/index.ts`
+  - Blocked by: none
+  - Skills: `terreno-backend-api`, `mongoose-schema-safety`, `backend-test-env`, `update-docs`
+  - Docs: stub **In-app notifications** in `docs/reference/api.md` (do not mix with Slack/Zoom notifiers)
+  - Acceptance: bun + supertest — `notify` creates one owner row; unauthenticated list 401; other user cannot read; POST `/notifications` 403 or disabled; every schema field has `description`
+
+- [x] **Task 1.2**: Owner mark-read and dismiss
+  - Delivers: `preUpdate` allows only `readAt` (ISO/date or `null`); `delete` soft-deletes; other fields in PATCH are stripped/rejected; unread query is `readAt` unset/null
+  - Files: `api/src/notifications/notificationsApp.ts`, tests in `notificationsApp.test.ts`
+  - Blocked by: 1.1
+  - Skills: `terreno-backend-api`, `backend-test-env`
+  - Docs: one sentence on patch/delete in the api.md stub
+  - Acceptance: bun tests — PATCH `{readAt}` persists; PATCH `{title: "x"}` does not change title; DELETE hides from list; second user 403
+
+## Phase 2 — Preferences, comms fan-out, retention
+
+- [x] **Task 2.1**: Preference model + defaults + `notificationsBeforeSend`
+  - Delivers: `NotificationPreference` unique `ownerId`, four booleans default true; missing row treated as all on; export duck-typed `notificationsBeforeSend({channel, userId})` that cancels when that boolean is false (`verification` channel never cancelled by this hook)
+  - Files: `api/src/models/notificationPreference.ts`, `api/src/types/notificationPreference.ts`, preference router on `NotificationsApp`, tests
+  - Blocked by: 1.1
+  - Skills: `terreno-backend-api`, `mongoose-schema-safety`, `backend-test-env`
+  - Docs: prefs table in api.md stub
+  - Acceptance: bun tests — no row → beforeSend does not cancel; `mail: false` → `{cancel: true}` for `channel: "mail"`; inapp false → `notify` does **not** insert a Notification
+
+- [x] **Task 2.2**: Optional comms fan-out from `notify()`
+  - Delivers: `NotificationsApp({getComms})`; after inbox write, call `sendMail` / `sendSms` / `sendPushToUser` when that pref is on and destination exists (email from User, phone if present on user, push via comms); missing `getComms` or missing destination skips that channel without failing `notify`; do not import `@terreno/comms` from `@terreno/api`
+  - Files: `api/src/notifications/notificationService.ts`, tests with a fake `getComms`
+  - Blocked by: 2.1
+  - Skills: `terreno-backend-api`, `backend-test-env`
+  - Docs: fan-out order in api.md
+  - Acceptance: bun tests — fake mail called when pref on + email present; mail not called when pref off; `notify` resolves when `getComms` throws after inbox write (log `logger.error`, still return the notification id)
+
+- [x] **Task 2.3**: Mark-all-read + `retainDays`
+  - Delivers: `POST /notifications/mark-all-read` sets `readAt` on the caller's unread rows; `retainDays` default `0` (no sweep); `retainDays > 0` tombstones (`deleted`) rows with `created` older than N days (best-effort on `notify` and/or a small `sweepExpired()`); **no** Mongo TTL index
+  - Files: `notificationsApp.ts`, `notificationService.ts`, tests
+  - Blocked by: 1.2
+  - Skills: `terreno-backend-api`, `backend-test-env`
+  - Docs: `retainDays` default 0 in api.md
+  - Acceptance: bun tests — mark-all-read only affects caller; retainDays 0 leaves old rows; retainDays 1 tombstones a row dated 2 days ago via Luxon; collection indexes do not include a TTL expireAfterSeconds on Notification
+
+## Phase 3 — UI
+
+- [x] **Task 3.1**: `NotificationBell` + `NotificationInbox`
+  - Delivers: presentational components (no syncdb import); bell shows badge from `unreadCount`; inbox lists items, mark read/unread, dismiss, tap calls `onOpen`; empty and loading states; `testID`s
+  - Files: `ui/src/NotificationBell.tsx`, `ui/src/NotificationInbox.tsx`, tests, `ui/src/index.tsx` exports
+  - Blocked by: none
+  - Skills: `terreno-ui`, `update-docs`, `verify-ui-changes`
+  - Docs: stub props in `docs/reference/ui.md`
+  - Acceptance: bun `ui` tests with `renderWithTheme`; badge hidden at 0; `onOpen` fired with the item; dismiss/mark callbacks fired
+
+- [x] **Task 3.2**: `NotificationPreferences`
+  - Delivers: four `BooleanField`s bound to `{inapp, mail, push, sms}`; `onChange` per channel
+  - Files: `ui/src/NotificationPreferences.tsx`, test, export
+  - Blocked by: none
+  - Skills: `terreno-ui`
+  - Docs: prefs props in ui.md
+  - Acceptance: bun tests — toggling mail calls `onChange("mail", false)`
+
+- [x] **Task 3.3**: Demo stories
+  - Delivers: demoConfig entries with fixture unread/read items and prefs toggles
+  - Files: `demo/stories/` + `demo/demoConfig.tsx` (or current demo registration)
+  - Blocked by: 3.1, 3.2
+  - Skills: `terreno-ui`, `verify-ui-changes`
+  - Docs: none (4.1)
+  - Acceptance: demo route renders bell + inbox + prefs without a backend
+
+## Phase 4 — Example app + docs
+
+- [x] **Task 4.1**: example-backend register + demo notify
+  - Delivers: `NotificationsApp({getComms: getCommsService})`; compose `notificationsBeforeSend` into `CommsApp` `beforeSend`; authenticated demo route (follow `commsDev`) that `notify`s the current user
+  - Files: `example-backend/src/server.ts`, `example-backend/src/api/` demo route + test
+  - Blocked by: 2.2, 2.3
+  - Skills: `terreno-backend-api`, `backend-test-env`
+  - Docs: none (4.3)
+  - Acceptance: bun tests — registered routes exist; demo notify 401 without auth; 200 with auth creates a row
+
+- [x] **Task 4.2**: example-frontend syncdb + bell + prefs
+  - Delivers: collections `notifications` and `notification-preferences`; bell on todos header; settings preferences screen; `onOpen` uses Expo Router for in-app `href`; optional “send test” calling the demo route
+  - Files: `example-frontend/store/syncdb.ts` (codegen/list), todos screen, settings route, tests if present
+  - Blocked by: 3.1, 3.2, 4.1
+  - Skills: `terreno-data-fetching`, `terreno-ui`, `verify-ui-changes`, `generate-sdk` (only if a non-sync demo route needs SDK)
+  - Docs: none (4.3)
+  - Acceptance: `useQuery` lists notify rows after demo send; mark read persists; prefs toggle survives reload (syncdb); no new RTK CRUD hooks for the collection
+
+- [x] **Task 4.3**: Diátaxis docs + rules + changelog
+  - Delivers: `docs/how-to/in-app-notifications.md`; finish `docs/reference/api.md` and `docs/reference/ui.md`; `docs/reference/comms.md` beforeSend composition; `docs/how-to/README.md` link; `.rulesync/rules/api` mention + `bun run rules`; `changelog/unreleased/notification-center.md`
+  - Files: those docs + rules
+  - Blocked by: 4.2
+  - Skills: `update-docs`
+  - Docs: (this task)
+  - Acceptance: a stranger can register the plugin and wire the bell from the how-to without reading the IP; website/how-to index lists the page

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

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