@terreno/mcp 57.3.0 → 57.6.0

package/src/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/TerrenoLabs/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/src/docs/versioned/next/implementationPlans/offline-mode.md

@@ -2,7 +2,7 @@
 
 **Status:** Deferred
 **Closed:** 2026-08-20 — Superseded by [@terreno/syncdb](syncdb-local-first.md) local-first outbox and offline-capable sync.
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1096
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1096
 **Priority:** High
 **Effort:** Medium
 

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

@@ -1,7 +1,7 @@
 # Implementation Plan: Organizations as a first-class primitive (admin UI + RBAC)
 
 **Status:** Approved
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1024 (absorbs `orgs-and-teams`; retitle on approve)
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1024 (absorbs `orgs-and-teams`; retitle on approve)
 **Priority:** High
 **Effort:** Big batch
 **Owner:** unassigned
@@ -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/src/docs/versioned/next/implementationPlans/orgs-and-teams.md

@@ -2,7 +2,7 @@
 
 **Status:** Superseded — 2026-08-24
 **Superseded by:** [org-management-ui](org-management-ui.md) (backend primitive + RBAC + admin UI)
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1024
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1024
 **Priority:** High
 **Effort:** Big batch
 **Owner:** unassigned

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

@@ -1,7 +1,7 @@
 # Implementation Plan: OSS Governance Baseline
 
 **Status:** Complete
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1003
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1003
 **Priority:** High
 **Effort:** Small batch
 **Owner:** unassigned

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

@@ -1,7 +1,7 @@
 # Program: Open Source Launch
 
 **Status:** In progress — decisions recorded (defaults accepted 2026-07-29)
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1094
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1094
 **Priority:** High
 **Effort:** Epic (multiple IPs)
 **Owner:** unassigned
@@ -40,7 +40,7 @@ Language rules for all docs:
 
 ## RTK deprecation gate
 
-**`@terreno/rtk` is being replaced.** PR [#869](https://github.com/flourishhealth/terreno/pull/869) (`@terreno/syncdb` local-first data layer) makes **Better Auth + `@terreno/syncdb`** the supported frontend platform. RTK Query becomes legacy.
+**`@terreno/rtk` is being replaced.** PR [#869](https://github.com/TerrenoLabs/terreno/pull/869) (`@terreno/syncdb` local-first data layer) makes **Better Auth + `@terreno/syncdb`** the supported frontend platform. RTK Query becomes legacy.
 
 **Program-wide rule: IPs flagged `Blocked` may not be implemented until #869 merges.** Writing docs against RTK now guarantees a rewrite. Planning (this program) proceeds; implementation of `None`-flagged IPs may start before #869; `Partial` IPs proceed except for `[RTK]`-marked tasks.
 
@@ -69,7 +69,7 @@ Every `[RTK]`-marked task in every task file must be reviewed against the merged
 
 ## Boost dependency (AI story)
 
-PR [#802](https://github.com/flourishhealth/terreno/pull/802) (MCP Boost parity, Phases 4–6) is **assumed merged** by the AI-facing IPs. It delivers the runtime half of the AI story:
+PR [#802](https://github.com/TerrenoLabs/terreno/pull/802) (MCP Boost parity, Phases 4–6) is **assumed merged** by the AI-facing IPs. It delivers the runtime half of the AI story:
 
 - `read_logs` merging backend / app (CDP) / Metro / browser sources
 - `last_error` across sources

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

@@ -1,7 +1,7 @@
 # Implementation Plan: Password reset and email verification
 
 **Status:** Approved
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1023
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1023
 **Priority:** High
 **Effort:** Big batch
 **Owner:** unassigned

package/src/docs/versioned/next/implementationPlans/pluggable-database-sqlite-research.md

@@ -147,4 +147,4 @@ Recorded in the planning thread; the IP will not be written until these are answ
 - `admin-backend/src/adminApp.ts`, `mcp-server/src/tools.ts`, `test/src/mongo/mongoServer.ts`
 - [syncdb-codegen.md](syncdb-codegen.md), [comms-abstraction.md](comms-abstraction.md), [positioning-django-rails-universal.md](positioning-django-rails-universal.md), [deploy-to-gcp.md](deploy-to-gcp.md) (GC2 future-Postgres note)
 - Better Auth SQLite adapters: https://better-auth.com/docs/adapters/sqlite ; Drizzle adapter: https://better-auth.com/docs/adapters/drizzle
-- Prior art: [PR #145](https://github.com/FlourishHealth/terreno/pull/145) (closed) — an earlier SQL-adapter plan proposing Bun.SQL multi-dialect support and JOIN-based population; superseded by this IP's adapter seam + batched population design
+- Prior art: [PR #145](https://github.com/TerrenoLabs/terreno/pull/145) (closed) — an earlier SQL-adapter plan proposing Bun.SQL multi-dialect support and JOIN-based population; superseded by this IP's adapter seam + batched population design

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

@@ -1,7 +1,7 @@
 # Implementation Plan: Positioning — "Django/Rails for TypeScript, with Universal Apps"
 
 **Status:** Implemented
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1008
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1008
 **Priority:** High
 **Effort:** Small batch
 **Owner:** unassigned
@@ -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/src/docs/versioned/next/implementationPlans/public-roadmap-github.md

@@ -1,7 +1,7 @@
 # Implementation Plan: Public Roadmap on GitHub
 
 **Status:** Complete
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1004
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1004
 **Priority:** High
 **Effort:** Small batch
 **Owner:** unassigned

package/src/docs/versioned/next/implementationPlans/rate-limiting.md

@@ -4,7 +4,7 @@
 **Branch:** `cursor/api-rate-limiting-d03a`  
 **Owner:** —  
 **Created:** 2026-08-30  
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1187 (this feature **closes** that issue; implementation PRs use `Fixes #1187`)  
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1187 (this feature **closes** that issue; implementation PRs use `Fixes #1187`)  
 **Task list:** [rate-limiting.md](../tasks/rate-limiting.md)  
 **Depends on:** —  
 **RTK deprecation flag:** None  
@@ -209,4 +209,4 @@ Skills: `backend-test-env` if any test mutates env (Redis URL). `mongoose-schema
 - [ ] 429 is `APIError` with `Retry-After` and `RateLimit` headers.
 - [ ] Docs how-to + reference + auth explanation + Terreno 58 default-on note exist.
 - [ ] Sync mutation limiter behavior unchanged (existing sync tests still pass).
-- [ ] Merging the implementation PR closes https://github.com/FlourishHealth/terreno/issues/1187 (`Fixes #1187`).
+- [ ] Merging the implementation PR closes https://github.com/TerrenoLabs/terreno/issues/1187 (`Fixes #1187`).

package/src/docs/versioned/next/implementationPlans/rbac-permissions.md

@@ -1,7 +1,7 @@
 # RBAC Permissions for Terreno — API Design
 
 **Status:** Complete — phases 1–6 shipped in PR #932 (2026-08-22)
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1089
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1089
 **Target package:** `@terreno/api` (new `src/rbac/` module), with surfaces in `admin-backend`, `admin-frontend`, `admin-spa`, `rtk`, and the modelRouter MCP work
 **Depends on:** `better-auth/plugins/access` (already a dependency via the Better Auth provider)
 

package/src/docs/versioned/next/implementationPlans/rtk-to-syncdb-migration-docs.md

@@ -1,7 +1,7 @@
 # Implementation Plan: RTK Deprecation and SyncDB Migration Docs
 
 **Status:** Complete — syncdb reference, migration guide, agent surfaces, and deprecation signalling shipped on `master`
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1007
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1007
 **Priority:** Critical (gates most of Wave 1)
 **Effort:** Big batch
 **Owner:** unassigned