@terreno/mcp 57.3.0 → 57.4.0

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

@@ -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/positioning-django-rails-universal.md

@@ -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/reference/README.md

@@ -12,9 +12,12 @@ Technical reference for Terreno packages and APIs. Information-oriented, precise
 - [@terreno/admin-frontend](admin-frontend.md) — Admin panel UI components
 - [@terreno/admin-spa](admin-spa.md) — Standalone admin SPA + Express serve plugin
 - [@terreno/api-health](api-health.md) — Health check TerrenoPlugin
+- [@terreno/announcements](announcements.md) — In-app product update announcements
 - [@terreno/comms](comms.md) — Pluggable mail, SMS, push, and verification providers
+- [@terreno/jobs](jobs.md) — Durable background jobs, schedules, and queue runners
 - [@terreno/feature-flags](feature-flags.md) — Feature flags and A/B testing plugin
 - [@terreno/mcp](mcp-server.md) — AI coding assistant integration (MCP)
+- [create-terreno-app](create-terreno-app.md) — Scaffold CLI (`bunx create-terreno-app`)
 - [@terreno/test](test.md) — Bun test helpers and in-memory MongoDB
 
 ## Legacy
@@ -30,6 +33,7 @@ Technical reference for Terreno packages and APIs. Information-oriented, precise
 
 - [UI performance](ui-performance.md) — Component render benchmarks
 - [Lifecycle plugin](lifecycle-plugin.md) — Grow/Pick/Roast/Brew/Taste contracts, results, and transitions
+- [Scan plugin](scan-plugin.md) — Aim/Sweep/Sift/Plot/Track goal campaigns that feed the lifecycle
 - [Install agent skills](../how-to/install-agent-skills.md) — Published `skills/` tree for `npx skills`
 - [GitHub issue lifecycle](../how-to/github-issue-lifecycle.md) — Pick-ready issues and Pick plan comments
 - Root [package.json](https://github.com/flourishhealth/terreno/blob/master/package.json) — Workspace scripts and catalog

package/dist/docs/versioned/next/reference/admin-backend.md

@@ -34,7 +34,10 @@ admin.register(app);
 ``````
 
 This creates:
-- `GET /admin/config` — Model metadata endpoint
+- `GET /admin/config` — Model metadata endpoint (`migrations.enabled` when `AdminApp` is given `migrations.dir`)
+- `GET /admin/migrations/status` (`admin:access`) and `POST /admin/migrations/run?wetRun=` (`admin:runScripts`) as `modelRouter` collection actions when `migrations.dir` is set. CRUD on `/admin/migrations` is disabled (405), action permission denials are 405, and responses use `{data: ...}`. Both operations are documented under the `adminMigrations` OpenAPI tag.
+- Poll/cancel those tasks at `GET`/`DELETE /admin/scripts/tasks/:id`
+- Pass `migrations: {dir: "./migrations"}` on `AdminApp`
 - Standard CRUD routes for each model at `{basePath}{routePath}`
 - All routes protected with `Permissions.IsAdmin`, or fine-grained RBAC when `accessControl` is set
 
@@ -42,8 +45,9 @@ This creates:
 
 ``````typescript
 interface AdminOptions {
-  models: AdminModelConfig[];
+  models?: AdminModelConfig[];
   basePath?: string;  // Default: "/admin"
+  organizations?: boolean; // Default: false
 }
 
 interface AdminModelConfig {
@@ -55,16 +59,60 @@ interface AdminModelConfig {
 }
 ``````
 
+## Organization scoping
+
+Organization-aware admin CRUD is opt-in so existing single-tenant apps remain
+unchanged. Enable organizations in both access and admin wiring:
+
+``````typescript
+const access = createAccess({
+  connection: mongoose.connection,
+  organizations: true,
+  statements,
+  userModel: User,
+});
+
+new AdminApp({
+  accessControl: access,
+  organizations: true,
+});
+``````
+
+When enabled, models whose schema contains `organizationId`:
+
+- require organization context through `X-Organization-Id` (single-org
+  `org-admin` callers may use context inference);
+- AND `organizationId` into list and search queries;
+- deny read, update, delete, and bulk update for records outside the current org;
+- overwrite client-provided `organizationId` on create with the current org.
+
+Models without `organizationId` and every admin app that omits `organizations`
+keep their existing behavior. Organization directory, settings, and membership
+requests use the shared `OrgsApp` routes mounted by
+`TerrenoApp({organizations: true, accessControl: access})`.
+
 ## Generated Routes
 
-For each model, creates standard modelRouter CRUD endpoints:
+For each model, creates standard modelRouter CRUD endpoints plus admin membership helpers:
 
-- `GET {basePath}{routePath}` — List (paginated, sortable)
+- `GET {basePath}{routePath}` — List (paginated, sortable). Query params: `page`, `limit`, `sort`, `q` (partial search across string `searchFields`), plus `queryFields` from list/filter metadata. Envelope: `{data, limit, more, page, total}` (`page` is the raw query string when provided)
+- `GET {basePath}{routePath}/search?q=` — Typeahead search. Envelope: `{data}` (limit 20; empty `q` returns `{data: []}`)
+- `POST {basePath}{routePath}/bulk-patch` — Body `{ids: string[], patch: object}`. Success body `{updated}` plus `failures` when any id fails. Ids must pass `mongoose.isValidObjectId` (hex String `_id` values work; arbitrary UUID-like strings are rejected as `"Invalid id"`)
 - `POST {basePath}{routePath}` — Create
 - `GET {basePath}{routePath}/:id` — Read
 - `PATCH {basePath}{routePath}/:id` — Update
 - `DELETE {basePath}{routePath}/:id` — Delete
 
+## Scripts
+
+`POST {basePath}/scripts/:name/run` creates a `BackgroundTask` and returns `{taskId}`. Poll
+`GET {basePath}/scripts/tasks/:id`. Cancel `DELETE {basePath}/scripts/tasks/:id`.
+
+When `JobsApp` is already registered, the run is enqueued as job `admin/script` (see
+[Durable background jobs](../how-to/background-jobs.md#admin-scripts)). Call
+`defineAdminScriptJob` on the worker process with the same script list. The CLI
+(`runScriptCli`) does not enqueue.
+
 ## Config Endpoint
 
 `GET {basePath}/config` returns metadata for all registered models:
@@ -89,7 +137,8 @@ For each model, creates standard modelRouter CRUD endpoints:
           required: false,
           default: false
         }
-      }
+      },
+      adminBroadcast: false
     }
   ]
 }
@@ -102,6 +151,11 @@ Field metadata includes:
 - `enum` — Enum values if applicable
 - `default` — Default value
 - `ref` — Referenced model name for ObjectId refs
+- `adminBroadcast` — Always present. `true` when the app `modelRouter` `sync` config set
+  `adminBroadcast`, except organization-scoped models (forced to `false`)
+- `organizationScoped` — `true` when `AdminApp({organizations: true})` manages a model with
+  an `organizationId` path, except `AuditEvent` (platform log; rows may omit the field)
+- `syncCollection` — Sync collection tag (app `routePath` without a leading slash, e.g. `todos`) when `adminBroadcast` is true; omitted otherwise
 
 Field metadata is built from `describeModel()` via `modelDescriptionToAdminFields()` — not from a second OpenAPI property walk. Widget overrides (`fieldOverrides`) remain admin-backend configuration.
 
@@ -112,6 +166,24 @@ without it. Script, configuration, RBAC, and per-model permissions never grant e
 
 Without `accessControl`, that same page gate uses `Permissions.IsAdmin` (`user.admin`).
 
+`AdminApp.register` also installs each model's list/read permissions and `queryFilter` on
+the sync admin window (`registerAdminBroadcastScope`). `GET /sync/entities` and
+`{collection}|admin` deltas then use that contract, not product `IsOwner`. Organization-scoped
+models are excluded because the current sync window protocol does not carry the selected
+organization context; they stay on REST so `X-Organization-Id` and `OrgQueryFilter` cannot be
+bypassed.
+
+For writes, AdminApp registers an admin-window mutation scope (`registerAdminWindowMutationScope`).
+Sync clients listed in `createSyncDb({windowCollections})` tag outbox rows with
+`mutationMode: "adminWindow"`. The server does not trust the marker alone: it also requires
+`adminBroadcast`, admin-window access (`admin:access` with RBAC, else `user.admin`), and the
+registered scope. Successful admin-window sync mutations enforce the same create/update/delete
+enabled flags, RBAC/`writeOwned` ownership, readonly/hidden stripping, User admin-flag/role gates,
+and `onAdminAudit` post hooks as REST — via AdminApp executor callbacks on the shared sync write
+pipeline (Mongoose validation, conflict/baseVersion checks, and ledger ordering unchanged).
+Organization-scoped models do not register this scope and use REST mutations. Product clients
+that omit the marker keep product sync permissions and hooks.
+
 With `accessControl`, each model can use a standard admin resource with three actions:
 
 | Action | Access |
@@ -165,6 +237,7 @@ writable controls are disabled, and `platformTools` reports visibility for Scrip
 and Configuration. Built-in tools use the existing editable permissions:
 
 - Scripts: `admin:runScripts` or `admin:viewBackgroundTasks`
+- Migrations apply/dry-run: `admin:runScripts` (status listing uses `admin:access`)
 - Roles: `rbac:read`
 - Version and Configuration: `configuration:read`
 - Audit Log and Feature Flags: their model's admin `read` permission
@@ -174,6 +247,11 @@ Read and list responses include `_adminCapabilities.update` and
 read-only for records the current user does not own. Script metadata separately exposes run and
 history permissions so a history-only role never receives an enabled Run control.
 
+When `AuditApp` is registered, successful admin POST/PATCH/DELETE persist append-only
+`AuditEvent` rows with `source: "admin"`. `onAdminAudit` is an extra best-effort sink; it is
+not required for the framework log. Failures in either sink do not change the mutation HTTP
+status. `AuditEvent` itself is never audited.
+
 **Important:** Only expose models that should be editable via admin panel. Avoid sensitive internal models.
 
 ## Best Practices

package/dist/docs/versioned/next/reference/admin-config.md

@@ -44,6 +44,13 @@ Model contributions contain `model`, `routePath`, and `admin`. Duplicate `routeP
 throw for registered routers; the same Mongoose model at two paths gets unique config
 `name`s so the admin UI can route to each.
 
+`AdminApp({migrations: {dir}})` enables `GET /admin/migrations/status` (`admin:access`)
+and `POST /admin/migrations/run?wetRun=` (`admin:runScripts`, same as Scripts) as
+`modelRouter` collection actions, plus `migrations.enabled` on `GET /admin/config`.
+Poll/cancel uses existing `/admin/scripts/tasks/:id`. Production wet apply requires
+`ALLOW_MIGRATIONS=true`. Unconfigured apps return 404 for those action routes.
+
+
 ## Legacy migration
 
 Move each object from `AdminApp.models` to the model's `modelRouter({admin: ...})`; remove

package/dist/docs/versioned/next/reference/admin-frontend.md

@@ -10,6 +10,22 @@ and [Build admin screens](../how-to/build-admin-screens.md).
 Home is `AdminHome` inside `AdminProvider` + `AdminShellLayout`. Generic models use
 `AdminScreenRouter` on `[model]/index`. See the how-to for `apiBase` vs `routeBase`.
 
+Pass fetch auth on `AdminProvider`:
+
+| Host | Props |
+| --- | --- |
+| Standalone SPA | `credentials="same-origin"` and `getAuthHeaders` that return `{}` (cookie session). Omit `apiOrigin`. |
+| Embedded app | `getAuthHeaders` that return `Authorization: Bearer …`, plus `apiOrigin` set to the API origin (`@terreno/rtk` `baseUrl`) |
+
+RPC that has left RTK uses `bindAdminRequest({credentials, getAuthHeaders, origin})` then `adminRequest`. Relative URLs such as `/admin/config` are prefixed with `origin` when it is set. When `AdminProvider` has `credentials` or `getAuthHeaders`, RPC hooks (`useAdminConfig`, scripts, roles, configuration, documents, comms, consent, version-config, background-tasks, AI explorer, object picker) use that client. Successful comms, scripts, and configuration mutations invalidate mounted fetch queries through the same tag contracts as RTK; those background refetches keep cached data with `isLoading: false` and report `isFetching: true`. Passing only `api` keeps `injectEndpoints`. Do not add axios.
+
+Optional `syncDb` on `AdminProvider` enables windowed changelists for models whose
+config includes `adminBroadcast: true` and `syncCollection`. When product screens
+also sync the same collection, inject a dedicated admin client/store configured
+with `windowCollections`; one client cannot join owner/tenant and admin modes for
+the same collection. Do not add `@terreno/syncdb` as a hard dependency of
+admin-frontend.
+
 ``````typescript
 // app/admin/index.tsx
 import {AdminHome} from "@terreno/admin-frontend";
@@ -22,6 +38,104 @@ export default function AdminScreen() {
 
 ## Components
 
+### OrgDirectoryScreen
+
+`OrgDirectoryScreen` is the operator-only organization directory. It renders
+loading, error, and empty states plus actions to create, disable, and open an
+organization. **Open** also calls `selectOrganization` when the directory is
+inside `OrgContextProvider`, so `X-Organization-Id` is set even if the host
+callback only navigates.
+
+``````typescript
+const {selectOrganization} = useOrgContext();
+
+<OrgDirectoryScreen
+  api={api}
+  isOperator={currentUser.roles?.includes("operator") ?? false}
+  onEnterOrganization={(organization) => {
+    selectOrganization(organization);
+    router.push(`/admin/orgs/${organization._id}`);
+  }}
+  routeBase="/admin"
+/>
+``````
+
+Pass the same operator check to `AdminShellLayout` to expose the directory in
+navigation. Org-admins do not receive this link:
+
+``````typescript
+<AdminShellLayout
+  api={api}
+  apiBase="/admin"
+  isOrganizationOperator={isOperator}
+  organizationDirectoryPath="/orgs"
+  routeBase="/admin"
+>
+  {children}
+</AdminShellLayout>
+``````
+
+### OrgContextProvider and OrgSwitcher
+
+Wrap organization-aware admin routes with `OrgContextProvider` and render
+`OrgSwitcher` through the shell's `organizationSwitcher` slot. Selecting an
+organization navigates to `{routeBase}/orgs/:orgId` and adds
+`X-Organization-Id` to subsequent `useAdminApi` requests. Query cache keys also
+include the organization id, preventing rows cached for one org from appearing
+in another. Derive `initialOrganization` from the current pathname so context
+follows URL changes after mount without overriding a switcher selection while
+navigation is in progress.
+
+``````typescript
+const pathname = usePathname();
+const routeOrganization = useMemo(
+  () => organizationFromPath(pathname),
+  [pathname]
+);
+
+<OrgContextProvider initialOrganization={routeOrganization}>
+  <AdminShellLayout
+    api={api}
+    apiBase="/admin"
+    organizationSwitcher={<OrgSwitcher api={api} routeBase="/admin" />}
+    routeBase="/admin"
+  >
+    {children}
+  </AdminShellLayout>
+</OrgContextProvider>
+``````
+
+When `/orgs/mine` returns one organization, `OrgSwitcher` shows its name and
+selects it automatically. With multiple organizations it selects the first by
+name (then id) as a deterministic default and renders a selector.
+Its **Organization** label uses the shell's inverted text color.
+When `/orgs/mine` returns **403** (callers without org-admin memberships, per API
+docs), the switcher renders nothing instead of an error banner. Other failures
+still show "Organizations unavailable".
+
+`OrgDirectoryScreen` (operators only) lists every organization, including
+disabled ones. Each row offers **Disable** or **Re-enable**; re-enabling sends
+`PATCH /orgs/:id` with `{disabled: false}`.
+
+### OrgSettingsScreen and OrgMembersScreen
+
+Use `OrgSettingsScreen` at `/admin/orgs/:orgId` and `OrgMembersScreen` at
+`/admin/orgs/:orgId/members`. Both send the selected organization header.
+
+`OrgSettingsScreen` edits the organization name and app-defined settings JSON.
+Type settings in the host app by augmenting `OrganizationSettings` (exported from
+this package and from `@terreno/api`) and reading them with
+`organizationSettingsOf(organization)`. The JSON editor still sends a full
+settings object on save; the backend schema rejects unknown keys.
+It includes a Billing card marked unavailable; billing is outside the
+organization-management feature.
+
+`OrgMembersScreen` lists current memberships, attaches an existing user by
+email, changes member roles, and removes members. Backend errors such as
+`Cannot remove the last org-admin` are shown inline. Invite is intentionally
+disabled because invitation tokens and email belong to the later invitations
+feature. The members page uses the full available admin content width.
+
 ### AdminModelList
 
 Entry screen showing all available models as cards.
@@ -49,10 +163,25 @@ Table view for a specific model with pagination, sorting, and actions.
 
 Features:
 - DataTable with columns from backend `listFields`
+- Toolbar search maps to list `q` (backend partial match + ObjectId lookup)
+- Declared `filters` map to DataTable column filters (`text` contains, `choice`
+  multi `$in`, `boolean`, `dateRange`, `ref` via `AdminRefField` in `renderFilter`)
+- Optional choice fields include **Empty**, which matches missing and null values.
+  Admin list requests serialize nested operators with bracket notation independently
+  of the host application's RTK base-query configuration.
 - Click row to edit
 - "Create New" button
 - Pagination controls
 - Reference fields render as clickable links
+- Windowed TinyBase path when `AdminProvider` has `syncDb` plus a fetch client (`credentials` or `getAuthHeaders`) and `GET /admin/config` reports `adminBroadcast` + `syncCollection` on a String `_id` model: REST list is membership only, rows overlay TinyBase, and a TinyBase table listener rerenders known rows as `{collection}|admin` deltas arrive. **Refresh** (`testID="admin-table-refresh"`) re-queries REST and calls `hydrateWindow`. **Create** (`testID="admin-create-button"`) is in the table chrome, not the navigator header, because admin stacks use `headerShown: false`. **Save** / **Delete** (`testID="admin-save-button"` / `admin-delete-button`) are in the form chrome for the same reason. Page select-all and bulk actions use the rendered rows, so a row a live tombstone removed leaves the selection. RTK `refetch` error envelopes (`error` / `isError`) toast and skip hydrate; an in-flight Refresh is discarded when page, search, or sort changes. A windowed create or delete never touches the cached REST list, so the form flags the collection through `markAdminWindowMembershipStale` and the changelist refetches membership automatically — whether it stayed mounted behind the form or remounts when the form pops. A create also passes the new id as `awaitId`, because `mutate` only enqueues on the outbox and the first refetch can beat the server; the changelist retries up to three times, 700 ms apart — including after transient list failures — then leaves **Refresh** as the fallback. Passing only `api` keeps the RTK list.
+- Organization-scoped models report `organizationScoped: true` and
+  `adminBroadcast: false`. They use REST list and mutation paths until the sync
+  window protocol carries selected-organization context. Home widgets delay
+  those list queries until `OrgContextProvider` has selected an organization.
+  `AdminModelForm` uses the same skip for org-scoped edit reads so create/edit
+  does not hit the API with a missing `X-Organization-Id`.
+  `AuditEvent` stays `organizationScoped: false` so Recent Activity and the
+  audit changelist still load unscoped rows when no organization is selected.
 
 ### AdminModelForm
 
@@ -77,6 +206,38 @@ Auto-generates fields from model schema:
 
 System fields (`_id`, `__v`, `created`, `updated`, `deleted`) are automatically skipped.
 
+When `AdminProvider` has `syncDb` plus a fetch client and the model config reports
+`adminBroadcast`, `syncCollection`, and a String `_id`, create/update/delete use the
+syncdb mutation outbox. Edit update/delete first hydrate the REST-loaded record so a
+deep-linked form can mutate locally. ObjectId models and hosts without the full
+windowed configuration keep the REST/RTK mutation path. Organization-scoped
+models always use REST/RTK regardless of String `_id`.
+
+Pass the host's `useConflicts()` result as `syncConflicts` on `AdminProvider`.
+Windowed form mutations set their own pending state before any asynchronous work, so
+Save/Delete show loading and duplicate presses cannot enqueue a second mutation.
+
+Windowed tables and forms render `AdminConflictSheet`, filtered to the ids loaded
+on that page or form, and forward **Use server** / **Keep mine** to syncdb's
+resolver. Only the most recently mounted sheet per collection renders, so a form
+stacked over its changelist shows one sheet instead of two.
+This adapter keeps `@terreno/syncdb` optional for admin-frontend.
+Bulk actions remain server operations: windowed models call the host fetch
+client at `{routePath}/bulk-patch`, while API-only/ObjectId hosts retain RTK.
+
+```tsx
+const syncConflicts = useConflicts();
+
+<AdminProvider
+  api={api}
+  apiBase="/admin"
+  syncConflicts={syncConflicts}
+  syncDb={syncDb}
+>
+  {children}
+</AdminProvider>;
+```
+
 ### AdminRolesList
 
 Role editing starts with a dedicated **Admin page** toggle for `admin:access`. That is the only
@@ -134,20 +295,31 @@ Returns model metadata from `{baseUrl}/config`.
 
 ### useAdminApi
 
-Generates RTK Query hooks for CRUD operations.
+> Deprecated in Terreno 57: do not add new admin `injectEndpoints`. Terreno 58
+> removes `useAdminApi` and the required `api` prop. During the compatibility
+> window, continue passing `api` for ObjectId model CRUD and API-only hosts.
+
+Generates compatibility RTK Query hooks for list/read/create/update/delete plus
+`POST {routePath}/bulk-patch`.
+Pass the model's `routePath` from config (for example `/admin/users` or `/admin/todos`), not the admin `baseUrl`.
+
+Admin RPC that is leaving RTK uses native `adminRequest` (`AbortController` timeout, JSON or `FormData`, `credentials` forwarded). Bind host auth with `bindAdminRequest`. Do not add axios.
 
 ``````typescript
 const {
   useListQuery,
-  useGetQuery,
+  useReadQuery,
   useCreateMutation,
   useUpdateMutation,
   useDeleteMutation,
-} = useAdminApi(api, baseUrl, modelName);
+  useBulkPatchMutation,
+} = useAdminApi(api, "/admin/users", "User");
 
-const {data, isLoading} = useListQuery({limit: 20, page: 1});
+const {data, isLoading} = useListQuery({limit: 20, page: 1, q: "Ada", sort: "-created"});
 const [create] = useCreateMutation();
 await create({email: "user@example.com"}).unwrap();
+const [bulkPatch] = useBulkPatchMutation();
+await bulkPatch({ids: ["abc"], patch: {name: "Ada"}}).unwrap();
 ``````
 
 ## Expo Router Setup
@@ -228,7 +400,8 @@ Expects backend to provide:
 
 When RBAC is enabled, `/admin/config` is filtered for the current user. `AdminShell` uses its
 `platformTools` flags to hide denied Scripts, Roles, Version, and Configuration links, and only
-renders model or custom-screen links returned by the server.
+renders model or custom-screen links returned by the server. The shell lifts Audit Log, Feature
+Flags, and Jobs into the Platform section (Jobs still comes from `customScreens`).
 
 ### Custom screen page chrome