@terreno/mcp 57.20.0 → 58.0.0-beta.1

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

@@ -27,7 +27,7 @@ Technical reference for Terreno packages and APIs. Information-oriented, precise
 
 ## Legacy
 
-`@terreno/rtk` is deprecated for **data synchronization**. New apps should use [`@terreno/syncdb`](syncdb.md). Existing RTK consumers: follow [Migrate from @terreno/rtk to @terreno/syncdb](../how-to/migrate-rtk-to-syncdb.md). Archived RTK reference: [legacy/rtk.md](legacy/rtk.md). `modelRouter` `realtime` and the RTK cache-patching helpers are removed in Terreno 58.
+`@terreno/rtk` and Redux were removed in Terreno 58; [`@terreno/syncdb`](syncdb.md) replaces them. Upgrading: [How to upgrade from @terreno/rtk to @terreno/syncdb (Terreno 58)](../how-to/migrate-rtk-to-syncdb.md) maps every removed export. Stub: [legacy/rtk.md](legacy/rtk.md).
 
 ## Configuration
 

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

@@ -113,6 +113,29 @@ When `JobsApp` is already registered, the run is enqueued as job `admin/script`
 `defineAdminScriptJob` on the worker process with the same script list. The CLI
 (`runScriptCli`) does not enqueue.
 
+## MCP screens
+
+`mcpAdminModels(options?)` returns model configs for an MCP server's admin screens, in the `MCP` sidebar group:
+
+| Route | Model | Allowed | Notes |
+| --- | --- | --- | --- |
+| `/mcp-service-tokens` | `McpServiceToken` | list, read, delete | Delete sets `revokedAt` |
+| `/mcp-oauth-clients` | `McpOAuthClient` | list, read, delete | Delete removes the registration and revokes every token issued to it |
+| `/mcp-oauth-connections` | `McpOAuthToken` | list, read, delete | One row per token pair; delete revokes the whole family (connection) and keeps the rows |
+| `/mcp-request-log` | `McpRequestLog` | list, read | Needs `mcpRequestLog` on `TerrenoApp` |
+| `/mcp-tools` | `McpToolSetting` | list, read, update | Only `enabled` is writable. Needs `mcpToolSettings` on `TerrenoApp` |
+
+Options: `group` (default `"MCP"`); `requestLog: true` and `toolSettings: true` add those screens. Both default to `false`; set them to match `TerrenoApp`'s `mcpRequestLog` and `mcpToolSettings`. Hash fields are hidden. Each config sets `adminAccess.resource`; with `accessControl`, spread `mcpAdminStatements` into your `createAccess({statements})`.
+
+`mcpAdminScripts()` adds `mcp-sign-out-everywhere` (`--user <id or email>`), which revokes every OAuth connection and service token the user holds. A dry run reports the counts. Email lookup uses the model registered as `User`.
+
+```typescript
+new AdminApp({
+  models: [...appModels, ...mcpAdminModels({requestLog: true, toolSettings: true})],
+  scripts: [...appScripts, ...mcpAdminScripts()],
+});
+```
+
 ## Config Endpoint
 
 `GET {basePath}/config` returns metadata for all registered models:

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

@@ -10,14 +10,25 @@ 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`:
+`AdminProvider` is required. It binds host auth onto one fetch client, and every
+admin request goes through it: model CRUD, `/admin/config`, scripts, roles,
+configuration, documents, comms, jobs, organizations, consent, announcements,
+version-config, background-tasks, migrations, AI observability, and the object
+picker. Admin components take no `api` prop (the RTK `api` prop was removed in Terreno 58).
 
 | 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.
+| Standalone SPA | `credentials="same-origin"` (cookie session). Omit `apiOrigin` and `getAuthHeaders`. |
+| Embedded app | `getAuthHeaders` that return `Authorization: Bearer …`, plus `apiOrigin` set to the API origin (`baseUrl` from `@terreno/syncdb/config`) |
+
+`AdminProvider` calls `bindAdminRequest({credentials, getAuthHeaders, origin: apiOrigin})`
+and exposes the result through `useAdminRpc()`. Relative URLs such as `/admin/config` are
+prefixed with `origin` when it is set. Successful mutations invalidate mounted queries
+through tags; those background refetches keep cached data with `isLoading: false` and
+report `isFetching: true`. An admin screen rendered outside `AdminProvider` falls back to
+an unauthenticated same-origin `fetch` and warns once in development. Product screens that
+reuse admin components (for example `DocumentStorageBrowser` or `ConsentHistory`) wrap
+them in `AdminProvider` with the same auth binding. Do not add axios.
 
 Optional `syncDb` on `AdminProvider` enables windowed changelists for models whose
 config includes `adminBroadcast: true` and `syncCollection`. When product screens
@@ -29,11 +40,10 @@ admin-frontend.
 ``````typescript
 // app/admin/index.tsx
 import {AdminHome} from "@terreno/admin-frontend";
-import {api} from "@/store/openApiSdk";
 
-export default function AdminScreen() {
-  return <AdminHome api={api} apiBase="/admin" routeBase="/admin" />;
-}
+// Rendered inside the AdminProvider in app/admin/_layout.tsx.
+const AdminScreen: React.FC = () => <AdminHome apiBase="/admin" routeBase="/admin" />;
+export default AdminScreen;
 ``````
 
 ## Components
@@ -50,7 +60,6 @@ callback only navigates.
 const {selectOrganization} = useOrgContext();
 
 <OrgDirectoryScreen
-  api={api}
   isOperator={currentUser.roles?.includes("operator") ?? false}
   onEnterOrganization={(organization) => {
     selectOrganization(organization);
@@ -65,7 +74,6 @@ navigation. Org-admins do not receive this link:
 
 ``````typescript
 <AdminShellLayout
-  api={api}
   apiBase="/admin"
   isOrganizationOperator={isOperator}
   organizationDirectoryPath="/orgs"
@@ -80,12 +88,8 @@ navigation. Org-admins do not receive this link:
 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. `useAdminApi`'s `useListQuery` and `useReadQuery` carry the organization
-in the query argument, so a switch after a request started (such as the switcher
-settling on a default organization) fetches the new organization's rows instead of
-leaving the screen loading. Derive `initialOrganization` from the current pathname so context
+`X-Organization-Id` to subsequent `useAdminModelApi` requests. Queries re-run when
+the organization changes, so rows loaded for one org do not appear 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.
 
@@ -98,9 +102,8 @@ const routeOrganization = useMemo(
 
 <OrgContextProvider initialOrganization={routeOrganization}>
   <AdminShellLayout
-    api={api}
     apiBase="/admin"
-    organizationSwitcher={<OrgSwitcher api={api} routeBase="/admin" />}
+    organizationSwitcher={<OrgSwitcher routeBase="/admin" />}
     routeBase="/admin"
   >
     {children}
@@ -320,10 +323,7 @@ to `[model]`.
 Entry screen showing all available models as cards.
 
 ``````typescript
-<AdminModelList
-  baseUrl="/admin"
-  api={api}
-/>
+<AdminModelList baseUrl="/admin" />
 ``````
 
 Fetches config from `{baseUrl}/config` and displays clickable model cards.
@@ -333,11 +333,7 @@ Fetches config from `{baseUrl}/config` and displays clickable model cards.
 Table view for a specific model with pagination, sorting, and actions.
 
 ``````typescript
-<AdminModelTable
-  baseUrl="/admin"
-  api={api}
-  modelName="User"
-/>
+<AdminModelTable baseUrl="/admin" modelName="User" />
 ``````
 
 Features:
@@ -346,13 +342,12 @@ Features:
 - 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.
+  Admin list requests serialize nested operators with bracket notation (`qs`).
 - 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.
+- Windowed TinyBase path when `AdminProvider` has `syncDb` 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. Membership `refetch` errors (`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. Other models use the REST list from `useAdminModelApi`.
 - 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
@@ -369,7 +364,6 @@ Create or edit form for a model instance.
 ``````typescript
 <AdminModelForm
   baseUrl="/admin"
-  api={api}
   modelName="User"
   id="507f1f77bcf86cd799439011"  // Optional for edit mode
 />
@@ -398,12 +392,12 @@ items follow the same default rules.
 
 System fields (`_id`, `__v`, `created`, `updated`, `deleted`) are automatically skipped.
 
-When `AdminProvider` has `syncDb` plus a fetch client and the model config reports
+When `AdminProvider` has `syncDb` 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`.
+windowed configuration use REST fetch CRUD (`useAdminModelApi`). Organization-scoped
+models always use REST 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
@@ -415,14 +409,15 @@ 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.
+client at `{routePath}/bulk-patch` for every model.
 
 ```tsx
 const syncConflicts = useConflicts();
 
 <AdminProvider
-  api={api}
   apiBase="/admin"
+  apiOrigin={baseUrl}
+  getAuthHeaders={getAdminAuthHeaders}
   syncConflicts={syncConflicts}
   syncDb={syncDb}
 >
@@ -523,22 +518,20 @@ Provisional display:
 Fetches admin configuration from backend.
 
 ``````typescript
-const {config, isLoading, error} = useAdminConfig(api, baseUrl);
+const {config, isLoading, error} = useAdminConfig("/admin");
 ``````
 
 Returns model metadata from `{baseUrl}/config`.
 
-### useAdminApi
-
-> 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.
+### useAdminModelApi
 
-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.
+Fetch CRUD hooks for one admin model over the `AdminProvider` client: 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`. List resolves to the `{data, more, page, limit, total}` envelope; read,
+create, and update resolve to the document. Writes refetch mounted list and read
+queries for the same model, and organization-scoped admin sends `X-Organization-Id`.
+Replaces the Terreno 57 `useAdminApi(api, routePath, modelName)` RTK hook.
 
 ``````typescript
 const {
@@ -548,68 +541,90 @@ const {
   useUpdateMutation,
   useDeleteMutation,
   useBulkPatchMutation,
-} = useAdminApi(api, "/admin/users", "User");
+} = useAdminModelApi("/admin/users", "User");
 
-const {data, isLoading} = useListQuery({limit: 20, page: 1, q: "Ada", sort: "-created"});
+const {data, isLoading, refetch} = 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();
 ``````
 
+### useAdminRpc, useAdminRpcQuery, useAdminRpcMutation
+
+`useAdminRpc()` returns the `AdminProvider` fetch client. `useAdminRpcQuery({rpc, url,
+providesTags, headers, skip, pollingInterval, transformResponse})` runs a GET and
+returns `{data, error, isError, isLoading, isFetching, refetch}`;
+`useAdminRpcMutation(rpc, {invalidatesTags})` returns `[trigger, {isLoading}]` where
+`trigger(args).unwrap()` sends the request. Use these for custom admin RPC. The
+client is `adminRequest`, built on `apiFetch` from `@terreno/syncdb/api` (timeout, JSON or
+`FormData`, `credentials` forwarded); `unwrapAdminEnvelope` unwraps `{data}` responses the
+same way the syncdb request client does.
+
 ## Expo Router Setup
 
 ``````typescript
 // app/admin/_layout.tsx
+import {AdminProvider} from "@terreno/admin-frontend";
+import {baseUrl} from "@terreno/syncdb/config";
 import {Stack} from "expo-router";
+import {getAdminAuthHeaders} from "@/store/syncdb"; // () => ({Authorization: "Bearer …"})
 
 export default function AdminLayout() {
-  return <Stack screenOptions={{headerShown: false}} />;
+  return (
+    <AdminProvider apiBase="/admin" apiOrigin={baseUrl} getAuthHeaders={getAdminAuthHeaders} routeBase="/admin">
+      <Stack screenOptions={{headerShown: false}} />
+    </AdminProvider>
+  );
 }
 
 // app/admin/index.tsx - Model list
 import {AdminModelList} from "@terreno/admin-frontend";
-export default () => <AdminModelList baseUrl="/admin" api={api} />;
+export default () => <AdminModelList baseUrl="/admin" />;
 
 // app/admin/[modelName]/index.tsx - Model table
 import {AdminModelTable} from "@terreno/admin-frontend";
 export default () => {
   const {modelName} = useLocalSearchParams();
-  return <AdminModelTable baseUrl="/admin" api={api} modelName={modelName} />;
+  return <AdminModelTable baseUrl="/admin" modelName={modelName} />;
 };
 
 // app/admin/[modelName]/new.tsx - Create form
 import {AdminModelForm} from "@terreno/admin-frontend";
 export default () => {
   const {modelName} = useLocalSearchParams();
-  return <AdminModelForm baseUrl="/admin" api={api} modelName={modelName} />;
+  return <AdminModelForm baseUrl="/admin" modelName={modelName} />;
 };
 
 // app/admin/[modelName]/[id].tsx - Edit form
 import {AdminModelForm} from "@terreno/admin-frontend";
 export default () => {
   const {modelName, id} = useLocalSearchParams();
-  return <AdminModelForm baseUrl="/admin" api={api} modelName={modelName} id={id} />;
+  return <AdminModelForm baseUrl="/admin" modelName={modelName} id={id} />;
 };
 ``````
 
 ## Protecting Admin Routes
 
 ``````typescript
-// app/_layout.tsx
-import {useSelectCurrentUser} from "@/store/openApiSdk";
+// app/admin/_layout.tsx
+import {canOpenAdminPage} from "@terreno/syncdb/app";
+import {useSession} from "@terreno/syncdb/auth";
 import {Redirect} from "expo-router";
+import {useGetAuthMeQuery} from "@/store/apiSdk";
 
-function RootLayout() {
-  const user = useSelectCurrentUser();
-  const pathname = usePathname();
-  
-  if (!user?.admin && pathname.startsWith("/admin")) {
+const AdminGate: React.FC<{children: React.ReactNode}> = ({children}) => {
+  const {userId} = useSession();
+  const {data: me, isLoading} = useGetAuthMeQuery(undefined, {skip: !userId});
+
+  if (isLoading) {
+    return null;
+  }
+  if (!canOpenAdminPage({admin: me?.admin, permissions: me?.permissions})) {
     return <Redirect href="/" />;
   }
-  
-  return <Stack />;
-}
+  return <>{children}</>;
+};
 ``````
 
 ## Custom Field Renderers
@@ -664,10 +679,10 @@ handled as a generic model form:
 import {CommsDashboardScreenWidget, CommsMessageDetail} from "@terreno/admin-frontend";
 
 // list: /admin/comms
-<CommsDashboardScreenWidget api={api} config={config} routeBase="/admin" screenName="comms" />
+<CommsDashboardScreenWidget config={config} routeBase="/admin" screenName="comms" />
 
 // detail: /admin/comms/[id]
-<CommsMessageDetail api={api} messageId={id} routeBase="/admin" />
+<CommsMessageDetail messageId={id} routeBase="/admin" />
 ```
 
 The list screen persists filters in the URL (`channel`, `provider`, `status`, `errorClass`, `q`,
@@ -703,7 +718,7 @@ prompt** on `aiPrompt:create`, **Create evaluator** on `aiEvaluator:create`, and
 Dataset detail hides **Add item** without `aiDataset:update` and **Run experiment** without
 `aiExperiment:create`; dataset lists hide **Import** without
 `aiDataset:update`. Judge schema checks use the production prompt version, or the latest version
-when production is unset. Widgets do not couple to host Redux.
+when production is unset. Widgets do not couple to host app state.
 
 `ai-prompts` lists prompts with a folder rail, search, type badge, latest vs production columns
 (tooltips), 7-day usage, and **Create prompt** when `aiPrompt:create` is allowed. The create modal
@@ -844,7 +859,7 @@ markdown renders as markdown), plus a **Reason** field and
 | In flight | Both buttons and the reason field are disabled until the decision returns, so it is sent once. |
 
 Requests use the host-bound admin request client (`AdminProvider` `getAuthHeaders` / `apiOrigin`),
-never RTK `injectEndpoints`. Test ids: `harness-approvals` (root), `harness-approvals-list`,
+never a second request client. Test ids: `harness-approvals` (root), `harness-approvals-list`,
 `harness-approvals-empty`, `harness-approvals-error`, `harness-approvals-loading`,
 `harness-approvals-refresh`, `harness-approvals-notice`, `harness-approval-row-<id>-clickable`,
 `harness-approval-detail`, `harness-approval-payload`, `harness-approval-reason`,
@@ -858,7 +873,7 @@ never RTK `injectEndpoints`. Test ids: `harness-approvals` (root), `harness-appr
 
 ```typescript
 import {bindAdminRequest, HarnessApprovalInbox} from "@terreno/admin-frontend";
-import {baseUrl} from "@terreno/rtk";
+import {baseUrl} from "@terreno/syncdb/config";
 import {Page} from "@terreno/ui";
 
 // getAuthHeaders: the host's `() => ({Authorization: "Bearer …"})`, as passed to AdminProvider.

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

@@ -46,17 +46,23 @@ admin-spa/
     appConfig.ts       # AdminSpaAppConfig defaults + merge helper
     index.ts           # Public exports
   app/                 # Expo Router SPA (Better Auth + admin screens)
-  store/               # Redux + Better Auth client
+  components/          # AppConfigGate, StoreProvider (session + request client), AdminGate
+  store/               # Admin window syncdb config
   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
+`StoreProvider` builds a cookie-session Better Auth client and a same-origin
+request client (`createApiClient({credentials: "same-origin"})` from
+`@terreno/syncdb/api`), then mounts `SessionProvider` (`@terreno/syncdb/auth`) and
+`ApiClientProvider` → `AdminGate` reads `useSession()` and redirects anonymous
 users to `/login` and non-admins to `/forbidden` → the authorized provider reads
-`/admin/config`. When config contains String-`_id` models with `adminBroadcast`
+`/admin/config`. The SPA loads the signed-in profile (`/auth/me`, for operator
+roles) with `useApiQuery` over that request client. It has no Redux store and no
+`@terreno/rtk` dependency. 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.
+ObjectId and non-broadcast models use the cookie-bound `AdminProvider` fetch client.
 
 When the backend enables organizations, the bundled SPA exposes:
 
@@ -139,6 +145,15 @@ new TerrenoApp({userModel: User})
 
 If no bundle exists at `distDir/index.html`, the plugin logs a warning suggesting `bun run --filter '@terreno/admin-spa' build:web` or `devProxyTarget`.
 
+## MCP OAuth consent route
+
+`${basePath}/oauth/consent?request=<id>` is the consent screen for `@terreno/api` MCP OAuth. Set `mcpOAuth.consentUrl` to `${issuer}${basePath}/oauth/consent` on a backend that serves the SPA from the same origin.
+
+- Any signed-in user can open it, not only admins. Admin providers (sync client, org context) do not start on this route.
+- A signed-out user is sent to `${basePath}/login?returnTo=<path>` and returned after sign-in. `returnTo` must start with a single `/` and contain no `\`, scheme, whitespace, or control characters; anything else is ignored.
+- The screen calls `GET /oauth/authorize/:request` and `POST /oauth/authorize/:request/approve` or `/deny` with the Better Auth session cookie, then follows `data.redirectUrl`.
+- States: loading, missing `request`, expired (400), already decided (409), not found, signed out, and error. Test ids start with `admin-spa-oauth-consent-`.
+
 ## Mount path constraint
 
 The default web export is built with `experiments.baseUrl: "/console"`, so `basePath` must match. To mount elsewhere, rebuild with a matching base (e.g. `EXPO_BASE_URL=/admin-ui bun run build:web`) and set `basePath` accordingly. Mounting at `/` requires a root-base build and `basePath: "/"`.

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

@@ -96,7 +96,8 @@ src/
   `getMCPTools`, `runBufferedChatTurn` (one chat turn to completion without HTTP: the same system
   prompt, tools, and block checks as `/gpt/histories/:id/turn`; takes `{body: {historyId, prompt},
   options, req}` where `req` carries `user` and `headers`)
-- **Models:** `AIRequest`, `GptHistory`, `FileAttachment`, `Project` (lazy; prefer `getProjectModel()`)
+- **Models:** `AIRequest`, `AIDataset`, `GptHistory`, `FileAttachment`, `Project` (lazy; prefer `getProjectModel()`)
+- **Migrations:** `gptHistoryStringIdsMigration` (`{slug, up}` for an app migration file), `migrateGptHistoryStringIds`, `GPT_HISTORY_STRING_IDS_MIGRATION`, type `GptHistoryStringIdsResult` ([GptHistory String ids](#gpthistory-string-ids))
 - **Routes:** `addGptRoutes`, `addGptHistoryRoutes`, `addAiRequestsExplorerRoutes`, `addFileRoutes`, `addProjectRoutes`, `addMcpRoutes`
 - **Structured output:** `parseAiJson`, `normalizeLlmJsonTextForStructuredOutput`, re-exported `Output`, `jsonSchema`, `JSONValue`, `FlexibleSchema` from `ai`
 - **Langfuse:** `initLangfuseClient`, `getLangfuseClient`, `shutdownLangfuseClient`, `compilePrompt`, `createPrompt`, `getPrompt`, `createTelemetryConfig`, `preparePromptForAI`, `initTracing`, `shutdownTracing`, `LangfuseCache`, cache helpers
@@ -224,10 +225,12 @@ Logs all AI calls for monitoring and admin explorer.
 
 ### GptHistory
 
-Conversation history with multi-modal prompts.
+Conversation history with multi-modal prompts. A synced collection: `/gpt/histories` streams each
+user's histories to `@terreno/syncdb` clients (see [addGptHistoryRoutes](#addgpthistoryroutesrouter-options)).
 
 | Field | Type | Description |
 |-------|------|-------------|
+| `_id` | string | A UUID for new histories, so offline sync clients can mint ids. Histories saved before 58 keep their old ObjectId as a hex string after the [migration](#gpthistory-string-ids) |
 | `userId` | ObjectId | Owner (required) |
 | `title` | string? | Auto-generated on the first chat turn's reply (`/gpt/prompt` or `turn`) when empty |
 | `projectId` | ObjectId? | Optional project association |
@@ -238,6 +241,30 @@ Assistant replies from `/gpt/prompt` carry `streamId` and `status`: `streaming`
 
 **Virtual:** `ownerId` aliases `userId` for `Permissions.IsOwner`.
 
+**Plugins:** `createdUpdatedPlugin`, `isDeletedPlugin`, `findOneOrNone`, `findExactlyOne`, `syncPlugin`. `syncPlugin` refuses `GptHistory.deleteMany`, `updateMany`, hard deletes, upserts, and query writes whose filter has no `_id`. Write one history at a time by `_id`; in tests, clear the collection with `GptHistory.collection.deleteMany({})`.
+
+`AIDataset.historyId` is the history's String `_id`. `registerAiDataset` still accepts an ObjectId and stores its hex string.
+
+#### GptHistory String ids
+
+Terreno 58 changed `GptHistory._id` from ObjectId to String. Histories saved before the upgrade still have ObjectId `_id`s, which the String schema cannot find. The `gpt-history-string-ids` migration moves them. Add it to the app's `migrations/` directory and apply it with `terreno-migrate` before deploying 58 frontends:
+
+```typescript
+// migrations/20261022130000-gpt-history-string-ids.ts
+import {gptHistoryStringIdsMigration} from "@terreno/ai";
+
+export const id = "20261022130000-gpt-history-string-ids";
+export const up = gptHistoryStringIdsMigration.up;
+```
+
+| Step | Effect |
+|------|--------|
+| 1 | Copy each ObjectId history (500 per batch) to `_id: oldId.toHexString()`, keeping every stored field. URLs and clients that hold the hex id keep working |
+| 2 | Rewrite `AIDataset.historyId` refs from the ObjectId to the hex string, including refs to histories that no longer exist |
+| 3 | Delete the ObjectId originals |
+
+A dry run (`terreno-migrate up --dry`) only counts the histories and refs it would change. The migration writes through the MongoDB driver, so it does not stamp sync seqs; moved histories reach sync clients as unstamped legacy rows on the next snapshot. Running it again changes nothing, and a run stopped partway finishes on the next run. It has no `down`: new histories get UUIDs, which have no ObjectId to go back to. `migrateGptHistoryStringIds({connection, dryRun, batchSize?, logger?, checkCancellation?})` runs the same steps without a migration file and returns `{historiesMigrated, datasetsUpdated}`.
+
 ### FileAttachment
 
 Metadata for files stored in GCS.
@@ -412,6 +439,8 @@ CRUD at `/gpt/histories` via `modelRouter`:
 | Create, List | `IsAuthenticated` |
 | Read, Update, Delete | `IsOwner` |
 
+Registered with the three-argument `modelRouter("/gpt/histories", GptHistory, {sync: {scope: {type: "owner", field: "userId"}}})`, so `SyncApp` serves the histories as the sync collection `gpt/histories` on each user's stream `gpt/histories|owner:{userId}`. A client reads them with `useQuery("gpt/histories")` and renames or deletes them with `useMutate("gpt/histories")`; sync payloads go through the same response handler as REST, so they also leave out `pendingAsk.promptIndex` and `pendingAsk.responseMessages`. Register `SyncApp` (and `RealtimeApp` for live deltas) in the app. REST CRUD stays for clients that do not sync. Every history route takes the String `_id`.
+
 Query filtered by `userId`; sort `-updated`; query fields `userId`, `projectId`. Create sets `userId` to the caller, so `{}` is a valid create body even when the app validates request bodies. Create and update bodies drop `pendingAsk` (including dotted `pendingAsk.*` paths), so only a chat turn writes it; the OpenAPI spec marks it `readOnly` on create and update. Create and update bodies also drop any `gcsKey` on `prompts[].content[]` parts (including dotted `prompts.N.content.M.gcsKey` paths) that the history does not already store, so a client can send stored prompts back but cannot add an attachment key.
 
 Pass `chat`, the options given to `addGptRoutes`, to add two headless actions for clients that do not read server-sent events, such as a watch app. Both exist only when `chat` turns `asks` on: without `chat`, or with `asks` off, neither action exists, so a host that never turned asks on gets no new endpoints. `AiApp` adds them when its `asks` option is set.
@@ -434,6 +463,9 @@ Bodies, results, and errors: [Headless endpoints](agent-ui-asks.md#headless-endp
 ### addFileRoutes(router, options)
 
 Requires `fileStorageService` and `gcsBucket` (registered by `AiApp` when both are set).
+`fileStorageService` may also be a function that returns the current service or `undefined`.
+Use it when storage is configured at runtime: the routes stay mounted and documented in
+`/openapi.json`, and answer `503 File storage is not configured` while it returns `undefined`.
 
 | Endpoint | Method | Auth | Description |
 |----------|--------|------|-------------|
@@ -495,7 +527,7 @@ new AiApp({
 | `toolChoice` | `"auto"` \| `"none"` \| `"required"` (default `"auto"` when tools present) |
 | `maxSteps` | Max tool-calling steps (default 5) |
 | `titleModelId` | Cheaper model for conversation title generation |
-| `openApiOptions` | Passed to route OpenAPI builders |
+| `openApiOptions` | Passed to route OpenAPI builders. Defaults to the OpenAPI instance `TerrenoApp` passes to `register` |
 | `projects` | Default `true`. `false` skips the `/gpt/projects` routes, so `AiApp` never registers the `Project` model |
 
 ## Cost and abuse limits
@@ -670,7 +702,7 @@ When `prompts.primary` is `local`, `ObservabilityApp.register` mounts admin-only
 | GET/POST | `/ai/observability/evaluators` | List / create. Create accepts `target: "full trace"` only (`generation span` and `dataset item` → 400). Seeded template install can still store other targets. `llm-judge` requires `judgePromptName`; create rejects when the judge prompt `outputSchema` omits a required dimension (400 names the key). `json-assert` supports `assertion` (`path` + `constraint`) or built-in output-schema mode. Human + `liveSampleRate > 0` → 400. Numeric dimension `range` is `min-max` (for example `0-1`); categorical `range` is `label|label` |
 | GET/PATCH/DELETE | `/ai/observability/evaluators/:id` | Read / update / soft-delete |
 | POST | `/ai/observability/traces/review` | Enqueue one or many traces against a human evaluator (`reason: "manual"`) |
-| GET | `/ai/observability/review` | Queue by `status` with counts; oldest-first. Response includes `more: false` so RTK preserves the count envelope. Rows include `traceName`, `promptName`, assignee, reason, and enqueue time |
+| GET | `/ai/observability/review` | Queue by `status` with counts; oldest-first. Response includes `more: false` so request clients keep the count envelope instead of unwrapping `data`. Rows include `traceName`, `promptName`, assignee, reason, and enqueue time |
 | GET | `/ai/observability/review/:id` | Item + evaluator dimensions + `given` / `wrote` panels and `rawInput` / `rawOutput` for the Raw JSON disclosure |
 | POST | `/ai/observability/review/:id` | `submit` (scores via ScoreSinks, status `done`), `skip`, or `assign` |
 

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

@@ -82,7 +82,7 @@ The plugin applies `matchAudienceByType` before `matchAudience`. When `isStaff`
 | 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) |
+| GET | `/announcements/feed` | Paginated published changelog — all display modes (`platform` and optional `version` as above; `limit` 1–100, default 20; `page` from 1). Returns `{data, more, page, total}`; `more` is true when a later page has items. |
 | 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 (`{ platform? }`). Same visibility as pending/feed; **404** when not visible. **400** for unknown keys or an invalid `platform`. |
 | 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. |
@@ -172,11 +172,11 @@ Set these environment variables on the MCP server to include live announcements:
 
 ### `useAcknowledgeAnnouncement`
 
-Injects RTK Query mutations for acknowledgement, impression, and primary-action click tracking:
+Sends acknowledgement, impression, and primary-action click events through the `client` passed to `useAcknowledgeAnnouncement(client, baseUrl?)` (see [`TerrenoRequestClient`](ui.md#terrenorequestclient)):
 
 | 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). |
+| `acknowledge(id)` | `POST /announcements/:id/acknowledge` | Refetches the pending announcement in every mounted `useAnnouncements` on the same client. 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) |