@terreno/mcp 57.2.0 → 57.4.0

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

@@ -1,6 +1,6 @@
 # Implementation Plan: Migrate CI/CD to CircleCI
 
-**Status:** In progress — Phase 1–3 CI config landed (deploys deferred per request)  
+**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
 **Linear:** _(none)_  
@@ -164,11 +164,22 @@ Port and dual-run:
 - Recreate preview aliases + optional GitHub Deployments via API.
 - `preview-cleanup` equivalent for Netlify/GCP previews as applicable.
 
+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
+`preview-cleanup.yml` plus the manual CircleCI parameter.
+
 ### Phase 5 — EAS + fingerprint (v1)
 
 - Port `eas-pr`, `eas-dev-build`, `fingerprint-gate` scripts under `.circleci/` or keep scripts in `.github/workflows/scripts/` and invoke from CircleCI until relocated to `scripts/ci/`.
 - 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
+is implemented.
+
 ### Phase 6 — GCP CD + OIDC (v1)
 
 - Terraform: CircleCI OIDC provider + dual-trust.
@@ -176,18 +187,25 @@ Port and dual-run:
 - Port `preview-cleanup` onto OIDC (eliminate `GCP_SA_KEY`).
 - Dual-run CD carefully (concurrency: one deployer).
 
+Implemented as CircleCI jobs plus GHA dual-run until CircleCI OIDC/context
+values exist. Path filters start `gcp-cd-prod` / `gcp-cd-preview`. CircleCI
+skips apply when `terreno-gcp` is empty so terraform is not double-applied.
+
 ### Phase 7 — npm publish (v1)
 
 - Port `publish-on-tag` + `publish-feature-flags-manual`.
 - **Single-writer rule:** disable GHA tag trigger in the same change that enables CircleCI tag pipeline.
 - Keep Zoom notify + master version bump + docs cut + demo dispatch.
 
+Implemented as a semver-tag release job plus manual `syncdb`/`feature-flags`
+publishing. GHA publishing triggers are disabled. Docs version cutting remains
+a follow-up; package publish, stable master bumps, Zoom notify, and demo deploy
+are ported.
+
 ### Phase 8 — Mobile runners (post-v1 / still required for full cutover)
 
-- Maestro (`maestro-e2e`).
-- Appium Android on Linux VM.
-- Appium iOS on CircleCI macOS resource class (image pin parity with `macos-15` intent).
-- Then delete `demo-appium-ci.yml` / `maestro-e2e.yml`.
+- Maestro web/Chrome (`maestro-e2e`) is implemented on CircleCI Linux browsers + Mongo replica set. GHA `maestro-e2e.yml` is `on: []`.
+- Appium Android on Linux VM and Appium iOS on CircleCI macOS remain unported.
 
 ### Phase 9 — GitHub-native + agentic replacements (full cutover)
 
@@ -197,7 +215,8 @@ Port and dual-run:
 | `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` | CircleCI job + `CURSOR_API_KEY` (lose `pull_request_target` free fork safety — use least privilege + fork policy) |
+| `architectural-pr-review` | Implemented: CircleCI job + `CURSOR_API_KEY` / `GITHUB_TOKEN`. Checks out `origin/master`, skips forks. GHA workflow is `on: []`. |
+| 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/dist/docs/versioned/next/implementationPlans/model-router-mcp.md

@@ -1,5 +1,7 @@
 # Implementation Plan: modelRouter MCP Tools
 
+**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
 *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.*
 
@@ -177,7 +179,7 @@ No activity logging specific to this feature. MCP tool calls go through the same
 ## Not Included / Future Work
 
 - **Rate limiting** — structured for future hooks but not implemented
-- **MCP resources/prompts** — only tools generated from modelRouter plus `registerMCPTool`
+- **MCP resources/prompts** — only tools generated from modelRouter plus `registerMCPTool`. Follow-up: [`app-mcp-server.md`](app-mcp-server.md) (prompts, resources, named servers, Better Auth OAuth 2.1, Inspector/test DX, Streamable HTTP client, hosted generators).
 - **Array operation tools** — handled via update, no dedicated push/patch/delete array tools
 - **WebSocket transport** — HTTP/SSE only
 - **Admin dashboard** — use `getMCPTools()` programmatically or MCP client tool listing

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

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

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

@@ -0,0 +1,185 @@
+# Implementation Plan: In-app notification center
+
+**Status:** Approved  
+**Branch:** `cursor/notification-center-ip-b11f`  
+**Owner:** —  
+**Created:** 2026-09-10  
+**Approved:** 2026-09-10  
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1179 (this feature **closes** that issue; implementation PRs use `Fixes #1179`)  
+**Task list:** [notification-center.md](../tasks/notification-center.md)  
+**Depends on:** [comms-abstraction](comms-abstraction.md) (shipped)  
+**RTK deprecation flag:** Partial — inbox is a syncdb collection; no new RTK CRUD hooks  
+**Program:** [B2B platform](b2b-platform-program.md)  
+
+## Goal
+
+Apps can show an in-app inbox next to `@terreno/comms` mail/SMS/push. Registering
+`NotificationsApp` on `TerrenoApp` adds owner-scoped `Notification` and
+`NotificationPreference` models, a server `notify()` that writes the inbox and fans out
+to enabled comms channels, and `@terreno/ui` bell / inbox / preferences surfaces wired
+through syncdb in the example app.
+
+## Non-Goals
+
+- Preference **categories** (marketing vs system). v1 is four channel toggles only.
+- Client-authored inbox rows (`create: []` on the notification router).
+- Owner edits to `title` / `body` / `href` / `kind`.
+- Broadcast or fan-out to all users.
+- Email digests, admin notification templates, org-scoped inboxes.
+- Forced `Linking.openURL` for taps.
+- New Socket.io event types or `modelRouter.realtime` (removed in Terreno 58).
+- Making `@terreno/ui` depend on `@terreno/syncdb` or `@terreno/comms`.
+- `@terreno/api` depending on `@terreno/comms` (comms already depends on api).
+
+## Decisions
+
+| Question | Decision |
+|----------|----------|
+| Package | **`NotificationsApp` in `@terreno/api`** (ConsentApp pattern). UI in `@terreno/ui`. No new workspace package. Comms stays outbound adapters. |
+| Inbox transport | Synced collections, `sync: {scope: {type: "owner"}}`. Live updates via existing `RealtimeApp` `sync:delta`. Hooks: `useQuery` / `useMutate`. |
+| Create | Router `create: []`. Only `getNotificationService().notify(...)` (and tests) insert rows. Direct `Model.create` from app code is not the public seam. |
+| Owner patch | `preUpdate` keeps `readAt` and `archivedAt` (set or `null`). Dismiss archives via `archivedAt` so the row stays in syncdb. `deleted` is retention-only. |
+| Preferences | One `NotificationPreference` per user: `inapp`, `mail`, `push`, `sms`. Missing row = all **on**. |
+| `notify()` | Writes inbox if `inapp` is on; then `sendMail` / `sendSms` / `sendPushToUser` when that channel is on **and** a destination exists. Missing email/phone/tokens skip that channel; inbox write still succeeds. Direct `sendMail` still works; prefs apply only if the app registers `notificationsBeforeSend`. |
+| Comms hook | `@terreno/api` exports a duck-typed `notificationsBeforeSend({channel, userId})` (no import of comms types). Apps pass it as `CommsApp({beforeSend})`. Compose if the app already has a hook. |
+| Tap | Optional `href` on the row. UI calls `onOpen(notification)`. Example-frontend routes internal paths; does not call `Linking.openURL` by default. |
+| Retention | `NotificationsApp({retainDays?: number})` default **`0`** (keep). `retainDays > 0` tombstones (`deleted`) rows older than that; no Mongo TTL index (hard delete breaks syncdb). |
+| Mark all read | `POST /notifications/mark-all-read` (authenticated, owner filter) sets `readAt` on unread rows; change streams update clients. |
+| UI split | Presentational components receive data and callbacks. Example-frontend supplies them with syncdb hooks; the demo uses fixtures. |
+| Admin | No dedicated admin explorer in this IP. Consumer may add the models to `AdminApp` later. |
+| Kind | Optional `kind` string on `notify()` / the document for icons; **not** used for preferences. |
+
+## Architecture
+
+```
+notify({userId, title, body, href?, kind?})
+  → load NotificationPreference (defaults all on)
+  → if inapp: Notification.create({ownerId: userId, ...})  // syncPlugin stamps _syncSeq
+  → if mail  && email:  getCommsService().sendMail(...)     // optional; skip if no comms
+  → if sms   && phone:  getCommsService().sendSms(...)
+  → if push:            getCommsService().sendPushToUser(...)
+
+RealtimeApp change stream → sync:delta → useQuery("notifications")
+
+CommsApp({beforeSend: notificationsBeforeSend})
+  → cancel send when prefs.<channel> === false
+```
+
+`@terreno/api` must not import `@terreno/comms`. Fan-out uses an optional
+`getComms?: () => {sendMail; sendSms; sendPushToUser}` passed into `NotificationsApp`.
+example-backend passes `getCommsService`.
+
+### Models
+
+**Notification** (`ownerId`, `title`, `body`, `href?`, `kind?`, `readAt?`)
+
+- Plugins: `createdUpdatedPlugin`, `isDeletedPlugin`, `syncPlugin`, `findExactlyOne` / `findOneOrNone`.
+- Index: `{ownerId: 1, created: -1}`.
+- Every field has `description`.
+
+**NotificationPreference** (`ownerId` unique, `inapp`, `mail`, `push`, `sms` default true)
+
+- Same plugins. Synced owner scope so the preferences screen is local-first.
+- Client **may** create/update this collection (upsert defaults). Unique `ownerId`.
+
+### APIs
+
+| Method | Path | Permissions | Notes |
+|---|---|---|---|
+| — | `GET/PATCH/DELETE /notifications/:id` + list | list/read: authenticated + owner filter; update: owner; delete: owner; **create: []** | `modelRouter` + `sync: {scope: {type: "owner"}}` |
+| POST | `/notifications/mark-all-read` | IsAuthenticated | Sets `readAt` now on owner's unread, non-deleted rows |
+| — | preference CRUD | owner + sync owner | Create allowed (lazy defaults) |
+| service | `notify(input)` | server only | Public TypeScript seam |
+
+`preUpdate` on notifications: drop every key except `readAt`. Invalid `readAt` (non-date / non-null) → 400.
+
+### UI
+
+| Component | Role |
+|---|---|
+| `NotificationBell` | Icon button + unread badge; opens inbox sheet/dropdown |
+| `NotificationInbox` | List unread/read; mark read/unread; dismiss; tap → `onOpen` |
+| `NotificationPreferences` | Four `BooleanField` toggles |
+
+Props take data + callbacks (`items`, `unreadCount`, `onMarkRead`, `onDismiss`, `onOpen`, `preferences`, `onChangePreference`). No syncdb import in `@terreno/ui`.
+
+### Example app
+
+- Register `NotificationsApp` + pass `getCommsService`.
+- `CommsApp({beforeSend: notificationsBeforeSend})` composed with any existing hook.
+- Authenticated demo `POST` (pattern: `commsDev`) to call `notify()` for the current user.
+- `example-frontend`: add collections to syncdb; bell on the todos screen header; settings preferences route; `onOpen` uses Expo Router when `href` is an in-app path.
+
+## Notifications
+
+This IP **is** the notification system. No extra product pings required to ship it.
+
+## Phases
+
+1. **Backend tracer:** models, `notify()` inbox write, owner read/update/delete, sync, tests.
+2. **Prefs + comms:** preference document, `notificationsBeforeSend`, optional comms fan-out, mark-all-read, `retainDays`.
+3. **UI + demo:** presentational components, stories, tests.
+4. **Example + docs:** example-backend/frontend, Diátaxis pages, rules, changelog.
+
+## Feature Flags & Migrations
+
+None. New collections only. `retainDays` default 0 so existing (empty) data is never tombstoned.
+
+## Activity Log & User Updates
+
+Inbox rows are the user-visible audit. Comms sends still log `CommsMessage`. Do not duplicate comms explorer here.
+
+## Not Included / Future Work
+
+- Category matrix and marketing defaults.
+- Broadcast / topics / org inbox (`org-management-ui`).
+- Digest email job (`job-queues`).
+- Admin templates and a notification explorer (`comms-admin-dashboard` stays delivery logs).
+- Client create for “reminders I wrote myself”.
+
+## Files to Create / Modify
+
+**Create**
+
+- `api/src/notifications/notificationsApp.ts`
+- `api/src/notifications/notificationService.ts`
+- `api/src/models/notification.ts`, `notificationPreference.ts`
+- `api/src/types/notification.ts`, `notificationPreference.ts`
+- matching `*.test.ts`
+- `ui/src/NotificationBell.tsx`, `NotificationInbox.tsx`, `NotificationPreferences.tsx` + tests
+- `docs/how-to/in-app-notifications.md`
+- `demo/stories/NotificationCenter.stories.tsx` (or equivalent demoConfig entry)
+
+**Modify**
+
+- `api/src/index.ts` exports
+- `example-backend/src/server.ts` (register plugin + beforeSend)
+- `example-frontend` sync collections, todos header, settings
+- `docs/reference/api.md` (new **In-app notifications** section; do not overload Webhooks & Notifications)
+- `docs/reference/ui.md`, `docs/reference/comms.md` (beforeSend composition)
+- `docs/how-to/README.md`
+- `.rulesync/rules/api/00-api.md` (then `bun run rules`)
+- `changelog/unreleased/`
+
+## Task List
+
+See [docs/tasks/notification-center.md](../tasks/notification-center.md).
+
+## Acceptance Criteria
+
+- [ ] `notify()` inserts an owner-scoped row when `inapp` is on; no row when the user turned in-app off.
+- [ ] Sync create of `notifications` is rejected; mark read and dismiss work; `sync:delta` delivers new rows.
+- [ ] `notificationsBeforeSend` cancels mail/SMS/push when that toggle is off.
+- [ ] `notify()` still writes inbox if comms is unregistered or a channel destination is missing.
+- [ ] `retainDays: 0` keeps rows; `retainDays > 0` tombstones old rows without a Mongo TTL index.
+- [ ] Bell shows unread count; inbox mark/dismiss/open; preferences persist via syncdb in example-frontend.
+- [ ] Docs: how-to + api reference + ui props; comms beforeSend note; issue 1179 closable.
+
+## Risks
+
+| Risk | Mitigation |
+|---|---|
+| `create: []` blocks `notify()` if someone uses the HTTP/sync mutate path only | `notify()` uses the Mongoose model (syncPlugin still stamps `_syncSeq`) |
+| api ↔ comms cycle | Optional `getComms` callback; duck-typed beforeSend |
+| Hard-delete TTL breaks snapshot catch-up | Tombstone via `isDeletedPlugin` only |
+| PHI in `body` | Owner scope + optional `retainDays`; no admin list in v1 |

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

@@ -1,6 +1,6 @@
 # Implementation Plan: Organizations as a first-class primitive (admin UI + RBAC)
 
-**Status:** Draft — awaiting approval
+**Status:** Approved
 **Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1024 (absorbs `orgs-and-teams`; retitle on approve)
 **Priority:** High
 **Effort:** Big batch
@@ -51,7 +51,10 @@ frames are **not** acceptance criteria for this IP (see [Claude Design brief](#c
 | Q12 | Who creates orgs | `operator` and `superadmin` only (API + `/admin/orgs`) |
 
 **Recorded assumptions (not grilled):** `org-admin` / `member` live on Membership (per org).
-`operator` / `superadmin` live on `user.roles`. Inherit native models, slugs, soft-delete,
+`operator` / `superadmin` live on `user.roles`. Organizations are **opt-in**
+(`createAccess({ organizations: true })` + `TerrenoApp({ organizations: true })` or `OrgsApp`);
+existing single-tenant apps omit that flag. New apps from bootstrap enable organizations by
+default. Inherit native models, slugs, soft-delete,
 last-admin guards, and `X-Organization-Id` from the superseded IP. Admin data layer stays
 RTK/OpenAPI.
 
@@ -300,8 +303,10 @@ logs in, sees switcher, members table for that org only.
 
 ## Feature Flags & Migrations
 
-New collections; `OrgsApp` opt-in. Adopting apps backfill `organizationId` with a documented
-recipe (formal migrator is `mongo-migrations`).
+New collections; organizations are opt-in (`createAccess({ organizations: true })` plus
+`OrgsApp` / `TerrenoApp({ organizations: true })`). Existing single-tenant apps are unchanged.
+New apps from `terreno_bootstrap_app` enable organizations by default. Adopting apps backfill
+`organizationId` with a documented recipe (formal migrator is `mongo-migrations`).
 
 Example-backend **breaking for the example app only:** remove `User.organizationIds`;
 resolve tenants via Membership. Seed users: `operator@example.com` (`operator`), two

package/dist/docs/versioned/next/implementationPlans/oss-governance-baseline.md

@@ -1,6 +1,6 @@
 # Implementation Plan: OSS Governance Baseline
 
-**Status:** Approved — decisions recorded (2026-07-29)
+**Status:** Complete
 **Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1003
 **Priority:** High
 **Effort:** Small batch

package/dist/docs/versioned/next/implementationPlans/oss-launch-program.md

@@ -1,6 +1,6 @@
 # Program: Open Source Launch
 
-**Status:** Draft — decisions recorded (defaults accepted 2026-07-29)
+**Status:** In progress — decisions recorded (defaults accepted 2026-07-29)
 **Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1094
 **Priority:** High
 **Effort:** Epic (multiple IPs)

package/dist/docs/versioned/next/implementationPlans/password-reset-and-email-verification.md

@@ -1,6 +1,6 @@
 # Implementation Plan: Password reset and email verification
 
-**Status:** Draft
+**Status:** Approved
 **Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1023
 **Priority:** High
 **Effort:** Big batch
@@ -86,10 +86,10 @@ with app-override hooks.
 
 ## UI
 
-example-frontend: `/resetPassword` (token from URL, new-password form using the existing
-RTK `resetPassword` mutation) and a "verify your email" banner + re-send button on the
-profile screen. `LoginScreen` gains an optional `onForgotPassword` link prop in
-`@terreno/ui`.
+example-frontend: `/forgotPassword`, `/resetPassword`, and `/verifyEmail` routes plus a
+"verify your email" banner + re-send button on the profile screen. Recovery screens try
+Better Auth first and fall back to JWT routes. `LoginScreen` gains an optional
+`onForgotPassword` link prop in `@terreno/ui`.
 
 ## Phases
 
@@ -135,13 +135,13 @@ See [docs/tasks/password-reset-and-email-verification.md](../tasks/password-rese
 
 ## Acceptance Criteria
 
-- [ ] `POST /auth/forgotPassword` returns 202 for existing and non-existing emails alike,
+- [x] `POST /auth/forgotPassword` returns 202 for existing and non-existing emails alike,
       sending mail only for existing ones.
-- [ ] A reset token works exactly once, fails after expiry, and a successful reset
+- [x] A reset token works exactly once, fails after expiry, and a successful reset
       invalidates outstanding refresh tokens.
-- [ ] The unmodified RTK client `resetPassword` mutation completes the flow end to end.
-- [ ] With `requireEmailVerification` on, an unverified user gets 403 code
+- [x] The unmodified RTK client `resetPassword` mutation completes the flow end to end.
+- [x] With `requireEmailVerification` on, an unverified user gets 403 code
       `email-not-verified` on login and can complete verification to proceed.
-- [ ] Better Auth mode sends the same two templates through comms.
-- [ ] example-frontend can complete forgot → email link (console adapter output in dev) →
+- [x] Better Auth mode sends the same two templates through comms.
+- [x] example-frontend can complete forgot → email link (console adapter output in dev) →
       reset → login with the new password; UI verification evidence attached to the PR.

package/dist/docs/versioned/next/implementationPlans/positioning-django-rails-universal.md

@@ -1,6 +1,6 @@
 # Implementation Plan: Positioning — "Django/Rails for TypeScript, with Universal Apps"
 
-**Status:** Draft — blocking questions open
+**Status:** Implemented
 **Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1008
 **Priority:** High
 **Effort:** Small batch
@@ -81,7 +81,7 @@ The Django/Rails claim invites the obvious question. `docs/explanation/positioni
 | Auth + permissions | Better Auth + `Permissions` / RBAC | RBAC shipped (`rbac-permissions.md`, Complete) |
 | Templates / views | `@terreno/ui` components, one codebase for iOS/Android/web | SSR is not shipped yet — see [`web-ssr-and-admin-spa`](web-ssr-and-admin-spa.md) |
 | `manage.py` / generators | MCP server tools (the *tool* layer) + the `/terreno-*` SDLC pipeline (the *process* layer) | Agent-driven rather than CLI-driven. Django gives you `manage.py startapp`; Terreno gives you a reviewed path from a request to a mergeable PR |
-| Celery / ActiveJob | Not shipped | On the roadmap |
+| Celery / ActiveJob | `@terreno/jobs` `JobsApp` (`jobs/`) — shipped [`job-queues`](job-queues.md) | [How-to](../how-to/background-jobs.md), [reference](../reference/jobs.md); optional GCP Cloud Tasks and Vercel Queues runners (was Not shipped when this IP was written) |
 | Migrations | No migrations framework | Schema evolution is convention + the `mongoose-schema-safety` skill |
 
 Being straight about the gaps is what makes the analogy credible rather than marketing.

package/dist/docs/versioned/next/implementationPlans/public-roadmap-github.md

@@ -1,6 +1,6 @@
 # Implementation Plan: Public Roadmap on GitHub
 
-**Status:** Approved — decisions recorded (2026-07-29)
+**Status:** Complete
 **Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1004
 **Priority:** High
 **Effort:** Small batch