@terreno/mcp 57.2.0 → 57.4.0

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

@@ -2,6 +2,9 @@
 
 Backend plugin that auto-generates admin CRUD endpoints for Mongoose models. Works with `@terreno/admin-frontend` to provide a complete admin panel solution.
 
+Screens, sidebar, and host wiring: [How admin interfaces are shaped](../explanation/admin-interface.md)
+and [Build admin screens](../how-to/build-admin-screens.md).
+
 ## Quick Start
 
 ``````typescript
@@ -31,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
 
@@ -39,8 +45,9 @@ This creates:
 
 ``````typescript
 interface AdminOptions {
-  models: AdminModelConfig[];
+  models?: AdminModelConfig[];
   basePath?: string;  // Default: "/admin"
+  organizations?: boolean; // Default: false
 }
 
 interface AdminModelConfig {
@@ -52,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:
@@ -86,19 +137,27 @@ For each model, creates standard modelRouter CRUD endpoints:
           required: false,
           default: false
         }
-      }
+      },
+      adminBroadcast: false
     }
   ]
 }
 ``````
 
 Field metadata includes:
-- `type` — Field type (string, number, boolean, date, objectid, etc.)
+- `type` — Field type (string, number, boolean, date, objectid, array, etc.)
 - `required` — Whether field is required
 - `description` — From schema (ensure all fields have descriptions!)
 - `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.
 
 ## Permissions
 
@@ -107,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 |
@@ -160,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
@@ -169,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

@@ -2,20 +2,140 @@
 
 React Native components for building admin panels that connect to `@terreno/admin-backend`.
 
+**Build a screen or change nav:** [How admin interfaces are shaped](../explanation/admin-interface.md)
+and [Build admin screens](../how-to/build-admin-screens.md).
+
 ## Quick Start
 
+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 {AdminModelList} from "@terreno/admin-frontend";
+import {AdminHome} from "@terreno/admin-frontend";
 import {api} from "@/store/openApiSdk";
 
 export default function AdminScreen() {
-  return <AdminModelList baseUrl="/admin" api={api} />;
+  return <AdminHome api={api} apiBase="/admin" routeBase="/admin" />;
 }
 ``````
 
 ## 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.
@@ -43,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
 
@@ -71,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
@@ -128,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
@@ -222,4 +400,37 @@ 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
+
+Wrap custom admin screen content in `AdminScreenPage`. It renders the standard `Page` header with a back arrow by default; the arrow navigates to `/admin` via `router.push`, not `router.back()`, because sidebar navigation does not always leave a reliable history entry on web. Pass the host's `routeBase` as `backHref` when admin uses a different prefix; an empty standalone-admin base resolves to `/`. Detail screens can target their parent route (for example `/admin/comms`). Pass `backButton={false}` only when the host supplies equivalent navigation.
+
+```typescript
+import {AdminScreenPage} from "@terreno/admin-frontend";
+
+<AdminScreenPage title="Operations" scroll>
+  <OperationsDashboard />
+</AdminScreenPage>
+```
+
+### Comms dashboard
+
+`COMMS_ADMIN_WIDGETS.comms` is registered in the built-in screen registry. `CommsApp` contributes
+custom screen `name: "comms"`. Hosts should also add message detail routes so `/comms/:id` is not
+handled as a generic model form:
+
+```typescript
+import {CommsDashboardScreenWidget, CommsMessageDetail} from "@terreno/admin-frontend";
+
+// list: /admin/comms
+<CommsDashboardScreenWidget api={api} config={config} routeBase="/admin" screenName="comms" />
+
+// detail: /admin/comms/[id]
+<CommsMessageDetail api={api} messageId={id} routeBase="/admin" />
+```
+
+The list screen persists filters in the URL (`channel`, `provider`, `status`, `errorClass`, `q`,
+`startDate`, `endDate`, `page`) and calls `/comms/messages`, `/comms/stats`, and
+`/comms/messages/retryMany`.

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

@@ -2,6 +2,9 @@
 
 Standalone Expo Router admin web SPA plus an Express plugin (`AdminSpaServeApp`) that serves the pre-built static export from a Terreno backend on the same origin.
 
+How screens and nav work (including `routeBase=""`): [How admin interfaces are shaped](../explanation/admin-interface.md).
+How to add a screen: [Build admin screens](../how-to/build-admin-screens.md).
+
 ## Table of Contents
 
 - [Install](#install)
@@ -47,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/dist/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