@terreno/mcp 57.3.0 → 57.6.0

package/src/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
     }
   ]
 }
@@ -101,7 +150,14 @@ Field metadata includes:
 - `description` — From schema (ensure all fields have descriptions!)
 - `enum` — Enum values if applicable
 - `default` — Default value
-- `ref` — Referenced model name for ObjectId refs
+- `ref` / `itemRef` — Referenced admin config `name` for ObjectId refs. Framework
+  compiled names such as `TerrenoOrganization` are returned as their stable public
+  admin names (`Organization`) so frontend reference pickers resolve the matching model.
+- `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 +168,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 |
@@ -150,7 +224,10 @@ new AdminApp({
 });
 ```
 
-`adminAccess.resource` overrides the default `admin<ModelName>` name. Use
+`adminAccess.resource` overrides the default `admin<ModelName>` name. Framework
+models compiled as `Terreno*` still use the pre-namespace `admin<ModelName>`
+resource (`adminAuditEvent`, `adminAnnouncement`, `adminMcpServiceToken`) and
+the same `/admin/<PublicName>` UI key (`/admin/AuditEvent`). Use
 `adminAccess.authorize({action, instance, user})` when a model or screen needs a completely
 custom decision. The callback replaces the standard read/write/write-owned decision, while
 `admin:access` still protects the admin shell. Every action is authorized without an instance
@@ -165,6 +242,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 +252,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/src/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/src/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
 

package/src/docs/versioned/next/reference/admin-spa.md

@@ -50,7 +50,24 @@ admin-spa/
   dist/                # Pre-built static export (produced by build:web)
 ```
 
-Boot flow in the SPA: `AppConfigGate` fetches `${basePath}/app-config.json` → `StoreProvider` builds Better Auth + Redux → `AdminGate` redirects anonymous users to `/login` and non-admins to `/forbidden`.
+Boot flow in the SPA: `AppConfigGate` fetches `${basePath}/app-config.json` →
+`StoreProvider` builds Better Auth + Redux → `AdminGate` redirects anonymous
+users to `/login` and non-admins to `/forbidden` → the authorized provider reads
+`/admin/config`. When config contains String-`_id` models with `adminBroadcast`
+and `syncCollection`, it starts a same-origin cookie-authenticated syncdb client
+with those collections in window mode and forwards `useConflicts()` to the admin.
+ObjectId and non-broadcast models remain on RTK.
+
+When the backend enables organizations, the bundled SPA exposes:
+
+- `/orgs` — operator-only organization directory;
+- `/orgs/:orgId` — organization settings;
+- `/orgs/:orgId/members` — organization memberships.
+
+`AdminSpaShell` renders `OrgSwitcher` on every admin route. The switcher and
+directory use `/orgs` API routes while generic model CRUD continues under the
+configured `adminApiBasePath`. Org-admins do not receive the directory link.
+The default `/console` mount therefore serves these as `/console/orgs/...`.
 
 ## AdminSpaServeApp
 

package/src/docs/versioned/next/reference/ai.md

@@ -367,6 +367,8 @@ new LangfuseApp({
 | `evaluation.enabled` | — | Register evaluation scoring routes |
 | `cache` | — | Prompt/trace TTL overrides |
 
+Client construction failures log a warning and skip the plugin so the API process still listens. Tracing init failures log and leave admin routes mounted. example-backend does not register `LangfuseApp` when `MONGO_DB_NAME` is a PR preview database (`terreno-example-pr-*`). GitHub Actions preview deploys omit Langfuse secrets and use `secrets_update_strategy: overwrite` so a previous revision cannot merge those keys into the preview.
+
 Calls `shutdownLangfuseClient()` and `shutdownTracing()` on `SIGTERM`.
 
 ## Langfuse integration

package/src/docs/versioned/next/reference/announcements.md

@@ -0,0 +1,179 @@
+# Announcements reference
+
+`@terreno/announcements` provides admin-managed in-app product update announcements.
+
+## Plugin
+
+```typescript
+import {AnnouncementsApp} from "@terreno/announcements";
+
+new TerrenoApp({ userModel: User })
+  .register(new AnnouncementsApp({
+    defaultAcknowledgementPolicy: "dismiss-only",
+    help: {enabled: true},
+    isStaff: (user) => user.admin === true,
+    matchAudience: (user, announcement) => true,
+  }))
+  .start();
+```
+
+### Plugin options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `adminOverviewPermissions` | `PermissionMethod[]` | `IsAdmin` | Access methods for `GET /announcements/overview`; pass the consumer RBAC `adminAnnouncement:read` permission when the admin shell uses RBAC-only users |
+| `basePath` | `string` | `"/announcements"` | Mount path for user and admin routes |
+| `defaultAcknowledgementPolicy` | `"required" \| "dismiss-only"` | `"dismiss-only"` | Fills omitted per-announcement `acknowledgementPolicy` at read time and pre-fills the admin editor |
+| `help.enabled` | `boolean` | `false` | Registers help search/detail routes for MCP and in-app help |
+| `matchAudience` | `(user, announcement) => boolean` | always `true` | Opaque audience JSON filter composed with `audienceType` via `matchAudienceByType` |
+| `isStaff` | `(user) => boolean` | `user.admin === true` | Staff check used by `matchAudienceByType` for `audienceType` |
+| `permissions` | partial CRUD overrides | admin-only | Overrides default `IsAdmin` permissions on announcement CRUD |
+
+## Acknowledgement policy
+
+Per-announcement `acknowledgementPolicy` controls whether users must acknowledge or may dismiss with an impression only.
+
+| Policy | Pending queue advancement | Public DTO `requiresAcknowledgement` |
+|--------|---------------------------|--------------------------------------|
+| `required` | User must POST `/acknowledge` for the current `version` | `true` |
+| `dismiss-only` | User may dismiss; POST `/impression` clears the item | `false` |
+
+**Resolution order** (pending, feed, help, public DTO):
+
+```
+policy = announcement.acknowledgementPolicy
+  ?? (legacy requiresAcknowledgement === true ? "required" : undefined)
+  ?? defaultAcknowledgementPolicy
+  ?? "dismiss-only"
+requiresAcknowledgement = policy === "required"
+```
+
+Legacy MongoDB documents that still store `requiresAcknowledgement: true` map to `"required"` on read. The boolean field is not part of the schema or admin create/update payloads.
+
+## Models
+
+- **Announcement** — `title`, `body` (markdown), `status` (`draft` | `published` | `archived`), `version`, `priority`, `displayMode` (`modal` | `banner` | `feed`, default `modal`), `audienceType` (`staff` | `patient` | `all`, default `all`), `acknowledgementPolicy`, optional `minBuildNumber`, `audience` (Mixed), `publishAt`, `expiresAt`, `platforms`, `primaryAction`
+- **AnnouncementAcknowledgement** — per-user acknowledgement at a specific `version`
+- **AnnouncementImpression** — per-view analytics row
+- **AnnouncementClickEvent** — per-click analytics row (`action: "primaryAction"`, `version` at click time, optional `platform`)
+
+Legacy MongoDB documents without `displayMode` or `audienceType` behave as `modal` and `all` at read time.
+
+### `matchAudienceByType`
+
+Exported helper composed with the plugin `matchAudience` callback (both must pass):
+
+```typescript
+import {matchAudienceByType} from "@terreno/announcements";
+
+matchAudienceByType({
+  user,
+  announcement,
+  isStaff: (candidate) => candidate.admin === true,
+});
+// all → true; staff → isStaff(user); patient → !isStaff(user)
+```
+
+The plugin applies `matchAudienceByType` before `matchAudience`. When `isStaff` is omitted on `AnnouncementsApp`, it defaults to `user.admin === true`.
+
+## User routes
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/announcements/pending` | Current interrupt (`modal` or `banner` only) + `remainingCount` (`platform` query: `ios` \| `android` \| `web`; optional `version` build number) |
+| GET | `/announcements/feed` | Paginated published changelog — all display modes (`platform` and optional `version` as above) |
+| POST | `/announcements/:id/acknowledge` | Record acknowledgement (idempotent per version). Same visibility as pending/feed; **404** when not visible. |
+| POST | `/announcements/:id/impression` | Record a view. Same visibility as pending/feed; **404** when not visible. |
+| POST | `/announcements/:id/click` | Record a primary-action click (`{ action: "primaryAction", platform? }`; optional `?version=` for min-build visibility). Returns **404** when not visible (checked before action/CTA validation). **400** when `action` is invalid, `primaryAction` is absent, or an explicit `platform` value is invalid. |
+
+`current` and feed items include resolved `requiresAcknowledgement` (boolean) and `displayMode` derived from policy resolution and stored fields above.
+
+### Query `version`
+
+Optional integer build number on `GET /pending`, `GET /feed`, and help routes. When an announcement has `minBuildNumber` set:
+
+- `?version=9` hides the item when `minBuildNumber` is `10`
+- `?version=10` (or higher) shows it
+- omitting `version` does **not** hide gated items
+
+`POST /announcements/:id/acknowledge`, `POST /announcements/:id/impression`, and `POST /announcements/:id/click` use the same visibility rules as pending/feed (schedule, expiry, platform, min build, `audienceType`, and `matchAudience`). All three return **404** when the announcement is not visible to the caller, so targeted IDs cannot be confirmed by writing event rows. Click checks visibility before action/CTA validation. Returns **400** when `action` is not `"primaryAction"`, the announcement has no `primaryAction`, or an explicit body `platform` is not `ios` / `android` / `web` (omit `platform` to use query/user-agent resolution). Each click inserts a new row (not idempotent). Acknowledge is idempotent per `(userId, announcementId, version)`.
+
+## Admin routes
+
+Admin CRUD is on `/announcements` via `modelRouter`. Custom actions:
+
+- `GET /announcements/config` — returns `{ data: { defaultAcknowledgementPolicy } }` from the plugin constructor (admin only; defaults to `"dismiss-only"` when omitted). Used to pre-fill the admin editor acknowledgement policy field.
+- `GET /announcements/overview` — paginated admin dashboard with per-announcement metrics and aggregate totals. Access uses `adminOverviewPermissions` (defaults to `IsAdmin`). Query: `page` (default `1`), `limit` (default `20`, max `100`).
+- `POST /announcements/:id/publish` — draft → published
+- `POST /announcements/:id/archive` — published → archived
+
+### `GET /announcements/overview`
+
+Admin-only list for launch dashboards. Includes **all** lifecycle statuses (`draft`, `published`, `archived`). Soft-deleted announcements and event rows are excluded.
+
+**Query**
+
+| Param | Default | Max | Description |
+|-------|---------|-----|-------------|
+| `page` | `1` | — | 1-based page index |
+| `limit` | `20` | `100` | Rows per page |
+
+**Response** `{ data, totals, page, limit, total, more }`
+
+- `data[]` — announcement rows sorted by `priority` desc, then `publishedAt` desc, then `_id` desc (deterministic pagination).
+- Each row: `_id`, `title`, `status`, resolved `displayMode`, resolved `audienceType`, resolved `acknowledgementPolicy`, `priority`, `version`, `publishedAt`, `expiresAt` (ISO strings when set), and `metrics: { impressions, acknowledgements, clicks }`.
+- Per-row metrics count **all event versions** for that announcement (aggregation grouped by `announcementId`, not N+1 queries).
+- `totals` — `announcements`, `published`, `draft`, `archived`, plus global `impressions`, `acknowledgements`, and `clicks` across non-deleted event rows.
+
+**Auth:** `401` unauthenticated; `403` when `adminOverviewPermissions` denies access.
+
+Read-only admin lists: `/announcement-acknowledgements`, `/announcement-impressions`, `/announcement-click-events`.
+
+Terreno RBAC includes `adminAnnouncementAcknowledgement`, `adminAnnouncementImpression`, and `adminAnnouncementClickEvent`. The built-in `admin` role receives read access to these audit models; `superadmin` receives all declared actions.
+
+## Help API (optional)
+
+When `help.enabled` is true, authenticated users can search product update notes for MCP and in-app help. Draft announcements are never exposed. Results respect `matchAudienceByType`, `matchAudience`, `publishAt` / `expiresAt`, optional `?version=` min-build gating, and the same visibility rules as `/pending`.
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/announcements/help/search` | Search published notes (`q`, `limit`, `includeArchived`) |
+| GET | `/announcements/help/:id` | Full update note by Mongo id (`includeArchived`) |
+
+`includeArchived=true` includes `archived` announcements alongside `published`. Omit it (default) to search only published notes.
+
+## MCP integration
+
+`@terreno/mcp` exposes three optional tools that search bundled `@terreno/*` upgrade markdown and, when configured, announcement help routes on your backend:
+
+- `terreno_search_update_notes` — keyword search; returns summaries with ids
+- `terreno_get_update_note` — full note by id (`upgrade:<semver>` or `announcement:<mongoId>`)
+- `terreno_ask_update_help` — natural-language question with ranked matches and full bodies
+
+Set these environment variables on the MCP server to include live announcements:
+
+| Variable | Description |
+|----------|-------------|
+| `TERRENO_HELP_API_URL` | Backend base URL (e.g. `http://localhost:4000`) |
+| `TERRENO_HELP_API_TOKEN` | Optional Bearer token for authenticated help routes |
+
+## Consumer UI
+
+`@terreno/ui` exports `AnnouncementNavigator`, `AnnouncementScreen`, `AnnouncementBanner`, `useAnnouncements`, and `useAcknowledgeAnnouncement`. These are app-level product surfaces — they are not registered in the isolated UI component demo. Wire them in a consumer app (`example-frontend`) with a real API.
+
+- Pending and feed requests send the current client platform (`ios`, `android`, or `web`) and, when available, the app build number from `Constants.expoConfig.extra.buildNumber` (same source as `useUpgradeCheck`).
+- `requiresAcknowledgement` on pending/feed items is resolved server-side from `acknowledgementPolicy` and `defaultAcknowledgementPolicy`; the navigator trusts that flag.
+- Feed failures do not block the modal queue — only pending errors surface in `AnnouncementNavigator`.
+- Markdown bodies support YouTube and Loom embeds via `MarkdownView`; ordinary links open with `Linking.openURL`.
+
+### `useAcknowledgeAnnouncement`
+
+Injects RTK Query mutations for acknowledgement, impression, and primary-action click tracking:
+
+| Method | Route | Notes |
+|--------|-------|-------|
+| `acknowledge(id)` | `POST /announcements/:id/acknowledge` | Invalidates pending queue. Query includes `platform` and, when available, `version` (same visibility gate as pending/feed). |
+| `recordImpression(id)` | `POST /announcements/:id/impression` | Sends current `platform` in body |
+| `recordClick(id)` | `POST /announcements/:id/click` | Body `{ action: "primaryAction", platform }`; query includes `platform` and, when available, `version` (same visibility gate as pending/feed) |
+
+`AnnouncementNavigator` wires `onPrimaryAction` for modal and banner surfaces: it calls `recordClick` once per primary CTA press (only when `primaryAction` is present), then opens the URL with `Linking`. Click POST failures log `console.warn` and do not block navigation. Standalone `AnnouncementScreen` / `AnnouncementBanner` usage without `onPrimaryAction` still opens the URL directly.