@terreno/mcp 57.3.0 → 57.4.0

package/src/docs/versioned/next/tasks/knip-cleanup.md

@@ -0,0 +1,146 @@
+# Task List: Remove the Knip baseline
+
+See: [`docs/implementationPlans/knip-cleanup.md`](../implementationPlans/knip-cleanup.md)
+
+**Status:** Complete  
+**RTK deprecation flag:** None
+
+## Instructions for the implementing agent
+
+- Re-run Knip (JSON reporter, default + production, same as `scripts/static-analysis/full.ts`) at the start of every task. The IP inventory is a snapshot, not the live list.
+- Disposition order: **entry → ignore (with comment) → unexport → delete**. Never `knip --fix`.
+- Do not delete the old Knip baseline until Task 6.1. Earlier tasks must keep `bun run analyze:full` green while the live finding count falls.
+- Do not remove symbols from published package public entries (`src/index.ts` / `src/index.tsx` / `package.json` `exports`).
+- Do not remove Expo autolink, native, or Metro packages from `demo`, `admin-spa`, `example-frontend`, or `ui` `package.json` because Knip cannot see them.
+- Tests: `bun test --only-failures` on the closest package; after config edits, `bun test scripts/static-analysis/lib.test.ts`.
+- Supporting skills: `update-docs`. UI deletes also use `verify-ui-changes`.
+
+### Phase 1: Entry graph
+
+- [x] **Task 1.1**: Register isolated suites and repo script tests as Knip entries
+  - Delivers: `*.isolated.ts(x)` and `scripts/**/*.test.ts` (plus `scripts/static-analysis/lib.test.ts`, `.github/scripts/*.test.ts`) stop reporting as unused files
+  - Files: `knip.jsonc`, `docs/explanation/static-analysis.md` (entry-graph section: isolated files and `scripts/` tests are first-class entries)
+  - Blocked by: none
+  - Docs: `docs/explanation/static-analysis.md`
+  - Skills: `update-docs`
+  - Acceptance: live default Knip report has no `files` finding whose path contains `.isolated.` or `scripts/` + `.test.`; `bun run analyze:full` exits 0; docs name this entry rule
+
+- [x] **Task 1.2**: Put mcp-server tests back on the Bun plugin
+  - Delivers: `mcp-server/src/__tests__/**` are in the graph (today `workspaces.mcp-server.bun: false` because Knip 6.34 wants `test.preload` as an array)
+  - Files: `knip.jsonc` and/or `mcp-server/package.json` (`test.preload` array form if required)
+  - Blocked by: none
+  - Docs: none beyond a comment in `knip.jsonc`
+  - Acceptance: no default `files` findings under `mcp-server/src/__tests__/`; mcp `bun test` still runs; `analyze:full` exits 0
+
+- [x] **Task 1.3**: Register codegen, Metro stubs, Playwright, fingerprint, and Docusaurus theme entries
+  - Delivers: tool-owned files are entries instead of “unused files”: `openapi-config.ts`, `comms-openapi-config.ts`, `jspdf-native-stub.js`, `fingerprint.config.js`, `playwright.circleci.config.ts`, `ui/babel.config.js`, `website/src/theme/**`, `scripts/ci/prepare-package-publish.mjs`, `scripts/planning/fingerprintRisk.ts`, `scripts/planning/updateDependenciesPr.ts` if they are invoked from `package.json` / CI
+  - Files: `knip.jsonc`; `package.json` scripts only if an entry name is wrong
+  - Blocked by: none
+  - Docs: `docs/explanation/static-analysis.md` — table row for Metro stubs / codegen configs
+  - Skills: `update-docs`
+  - Acceptance: those paths are absent from live `files` findings or listed as `entry`; comments explain each ignore glob if an ignore is used instead; `analyze:full` exits 0
+
+- [x] **Task 1.4**: Ignore generated Expo skill script copies; keep the canonical copy in graph if it is real
+  - Delivers: duplicate `expo-cicd-workflows/scripts/{fetch,validate}.js` under `.agents/`, `.claude/`, `.cursor/`, `.devin/`, `.github/`, `.rulesync/`, `skills/` do not appear as unused files
+  - Files: `knip.jsonc` ignore globs; confirm canonical path (`.rulesync/skills/...` or `skills/...`)
+  - Blocked by: none
+  - Docs: one sentence in `docs/explanation/static-analysis.md` that generated skill copies are ignored
+  - Skills: `update-docs`
+  - Acceptance: no `files` findings whose path contains `expo-cicd-workflows/scripts/`; `analyze:full` exits 0
+
+### Phase 2: Documented ignores (cannot fix)
+
+- [x] **Task 2.1**: Ignore Expo autolink / Metro / font / native `dependencies` Knip cannot see
+  - Delivers: `ignoreDependencies` (or workspace-scoped equivalent) for the live unused-deps list on `demo`, `admin-spa`, `example-frontend`, `ui` that exist for autolinking or Metro, including `jspdf` unlisted from metro stubs and `expo-system-ui` / `expo-updates` unlisted from `app.json`
+  - Files: `knip.jsonc`, `docs/explanation/static-analysis.md` (why these stay in `package.json`)
+  - Blocked by: Task 1.3
+  - Docs: `docs/explanation/static-analysis.md`
+  - Skills: `update-docs`
+  - Acceptance: those packages are gone from live `dependencies` / `unlisted` findings; each ignore has a comment; no app/`ui` `package.json` lost an Expo native dep; `analyze:full` exits 0
+
+- [x] **Task 2.2**: Ignore binaries, catalog-only, and optional peers that are real
+  - Delivers: `eas`, `maestro`, catalog `@sentry/react-native` if unused in this repo but required by the catalog contract, `admin-frontend` optional `react-native-webview`
+  - Files: `knip.jsonc`
+  - Blocked by: none
+  - Docs: comment in `knip.jsonc`; mention binaries in `docs/explanation/static-analysis.md` if not already there
+  - Skills: `update-docs`
+  - Acceptance: live report has no `binaries` / `catalog` / `optionalPeerDependencies` findings except any still destined for Task 3.1 deletion; `analyze:full` exits 0
+
+- [x] **Task 2.3**: Ignore remaining unlisted modules that are optional or type-only
+  - Delivers: honest ignores or `optionalDependencies` for `ioredis` (rate-limit redis store), `@ai-sdk/google-vertex`, `@docusaurus/plugin-content-docs`, `express` in ai tests, `@terreno/api` from `@terreno/test` if the graph cannot see the workspace package
+  - Files: `knip.jsonc` and/or the declaring `package.json` if the package should be listed instead of ignored
+  - Blocked by: Task 1.2
+  - Acceptance: Pick records in the task log each remaining unlisted name as either added to `package.json` or ignored with reason; live `unlisted` count is 0 or only items Task 3 will delete; `analyze:full` exits 0
+
+### Phase 3: Remove true unused packages
+
+- [x] **Task 3.1**: Delete unused `devDependencies` after the graph is honest
+  - Delivers: remove packages that still appear as unused `devDependencies` and are not CLIs invoked from scripts (`sinon`, `@types/sinon`, `@types/bcrypt`, `@types/cron`, leftover `typedoc`/`prettier`/`ts-node`/`tsx` only if no script references them). Keep `@rtk-query/codegen-openapi`, `@biomejs/biome`, `mongodb` as a driver for example-backend tests, etc., when a script or plugin uses them — those become entries or ignores in Phase 1–2, not deletions
+  - Files: affected `package.json` files, lockfile via `bun install`
+  - Blocked by: Task 1.1, Task 1.2, Task 1.3, Task 2.2
+  - Docs: none unless a documented install step named a removed tool
+  - Acceptance: `rg` of the repo and `package.json` scripts show no remaining reference; `bun run compile` (or package `compile`) and the package test script still pass for each touched package; live unused-devDep list for those names is empty; `analyze:full` exits 0
+
+- [x] **Task 3.2**: Remove unused runtime deps that are not Expo/autolink
+  - Delivers: example-backend / website / test / api leftovers (`clsx`, unused `lodash` in `@terreno/test`, `generaterr` / `scmp` / `@sentry/profiling-node` **only if** nothing loads them including Sentry init). If a dep is loaded via string/dynamic import, ignore it instead
+  - Files: affected `package.json`, source if an import must move
+  - Blocked by: Task 2.1, Task 3.1
+  - Acceptance: each removed name has no remaining import; package tests pass; `analyze:full` exits 0
+
+### Phase 4: Dead files
+
+- [x] **Task 4.1**: Delete in-repo-dead example-frontend modules
+  - Delivers: remove unused files Knip still reports after Phase 1 (candidates from snapshot: `hooks/useLogoutUser.ts`, `useSentryUserSetup.ts`, `useUpdateProfile.ts`, `constants/Colors.ts`, and any unused store helpers). Keep files that routes, tests, or docs still import — those need an entry or a real import
+  - Files: `example-frontend/**` listed by live Knip `files`
+  - Blocked by: Task 1.3
+  - Docs: update example-frontend docs/README only if a named file was documented
+  - Skills: `update-docs`, `verify-ui-changes` if a routed screen changes
+  - Acceptance: those paths absent from live `files` findings; `cd example-frontend && bun test` passes; if UI was unwired, login + related screen still work with artifacts under `/opt/cursor/artifacts/`
+
+- [x] **Task 4.2**: Delete or wire dead demo / example-backend / api example files
+  - Delivers: `demo/stories/PasswordField.stories.tsx` if unregistered; `demo/.eslintrc.js` if unused; `example-backend` unused scripts (`configuration-example.ts`, `seed-admin-spa-admin.ts`, `seedConsents.ts`) unless `package.json` / AdminApp should call them — then add entries; `example-backend/src/constants/index.ts` if a banned barrel leftover; `api/src/example.ts`; unused vendor `convert-yaml.js` only if nothing requires it
+  - Files: paths from live Knip `files` in those packages
+  - Blocked by: Task 1.3
+  - Docs: example-backend README / how-to if a seed script is removed or registered
+  - Skills: `update-docs`
+  - Acceptance: live `files` findings for those packages are 0 or only ignored globs; relevant `bun test` passes; `analyze:full` exits 0
+
+- [x] **Task 4.3**: Delete or keep-with-entry remaining unused files (`ui/checkDeps.js`, `processCounties.js`, `compileAuthEntry.ts`, leftover demo tests already covered)
+  - Delivers: every remaining default `files` finding is either an entry, an ignore glob with comment, or deleted
+  - Files: leftover paths from live Knip
+  - Blocked by: Task 1.1, Task 1.4, Task 4.1, Task 4.2
+  - Acceptance: live default+production `files` count is 0; `analyze:full` exits 0
+
+### Phase 5: Exports and types
+
+- [x] **Task 5.1**: Unexport unused **internal** symbols in `scripts/` and examples
+  - Delivers: after tests are in the graph, remaining unused exports/types in `scripts/`, `example-frontend/`, `example-backend/`, `demo/` that are not a public package entry become non-exported (or deleted if the whole helper is dead)
+  - Files: modules named by live `exports` / `types` findings in those trees
+  - Blocked by: Task 1.1, Task 4.1, Task 4.2
+  - Acceptance: those packages have no unused **internal** export/type findings; tests that imported the symbol still compile (they use the same module, not the export); `analyze:full` exits 0
+
+- [x] **Task 5.2**: Unexport unused **internal** symbols in published packages
+  - Delivers: same as 5.1 for `api`, `admin-frontend`, `comms`, `syncdb`, `mcp-server`, `ai`. Do **not** remove re-exports from `src/index.ts(x)`
+  - Files: internal modules named by live findings
+  - Blocked by: Task 1.2
+  - Docs: none unless a documented “internal helper” was publicized in explanation/reference — then update that page
+  - Skills: `update-docs`
+  - Acceptance: each remaining unused export/type is classified public (re-exported from the package entry) or is gone; package `bun test` / `compile` passes; `analyze:full` exits 0
+
+- [x] **Task 5.3**: Ignore leftover **public** unused exports and types
+  - Delivers: `ignoreIssues` (path-scoped `exports`/`types`) for public API unused inside this monorepo, with comments
+  - Files: `knip.jsonc`, `docs/explanation/static-analysis.md` (public API ignore rule)
+  - Blocked by: Task 5.1, Task 5.2
+  - Docs: `docs/explanation/static-analysis.md`
+  - Skills: `update-docs`
+  - Acceptance: live `exports` and `types` counts are 0; no public `index` export removed; `analyze:full` exits 0
+
+### Phase 6: Remove baseline
+
+- [x] **Task 6.1**: Delete the Knip baseline and enforce zero findings directly
+  - Delivers: live default+production fingerprint set is `[]`; no Knip baseline exists; docs state that new findings are fixed or added to `knip.jsonc` with a reason
+  - Files: delete `scripts/static-analysis/knip-baseline.json`; update `docs/explanation/static-analysis.md`, `scripts/static-analysis/full.ts`, and tests
+  - Blocked by: Task 2.1, Task 2.2, Task 2.3, Task 3.2, Task 4.3, Task 5.3
+  - Docs: `docs/explanation/static-analysis.md`
+  - Skills: `update-docs`
+  - Acceptance: `test ! -e scripts/static-analysis/knip-baseline.json`; `bun run check:knip` prints no findings and exits 0; `bun run analyze:full` exits 0; static-analysis tests pass

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