@terreno/mcp 57.21.0 → 58.0.0-beta.1

package/src/docs/versioned/next/implementationPlans/remove-legacy-realtime.md

@@ -56,4 +56,4 @@ Today a model can enable both `realtime` (RTK `sync` events + cache patching) an
 - [x] Using `modelRouter` `realtime` logs a one-time warning that names Terreno 58 and syncdb.
 - [x] Using `realtimeList` / `realtimeDocument` / `setRealtimeSocket` logs a one-time warning that names Terreno 58 and syncdb.
 - [x] Task list describes 58 deletion without removing `RealtimeApp`.
-- [ ] Terreno 58 removes the deprecated APIs (later).
+- [x] Terreno 58 removes the deprecated APIs.

package/src/docs/versioned/next/implementationPlans/remove-rtk.md

@@ -0,0 +1,185 @@
+# Implementation Plan: Remove @terreno/rtk and Redux in Terreno 58
+
+**Status:** Approved  
+**Roadmap:** Area=`syncdb`, Target=`58`, Impact=`Breaking`  
+**Branch:** `remove-rtk-58` (one PR into `release-58.0.0`)  
+**Owner:** Josh Gachnang  
+**Created:** 2026-10-20  
+**Target:** Terreno **58.0.0** (breaking)
+
+## Goal
+
+Delete the `@terreno/rtk` package and every Redux dependency from the monorepo. After this
+change `@terreno/syncdb` is the only frontend data and session layer:
+
+- Synced collections use `useQuery` / `useMutate` (unchanged).
+- Every other HTTP call (`/auth/me`, modelRouter actions, AI, consents, announcements,
+  version check) goes through a new syncdb request client with generated, typed hooks.
+- Session state comes from `@terreno/syncdb/auth` (Better Auth, plus a ported JWT adapter).
+- Feature flags and server pushes ride syncdb's existing socket.
+- GptHistory and McpServiceToken become synced collections.
+- All unit and e2e tests exercise these syncdb paths. No test imports RTK or Redux.
+
+This fulfils the promise in `rtk/README.md`: rtk is not published in the next major.
+
+## Non-Goals
+
+- Backend JWT/Passport auth (`api/src/auth.ts`) stays. Only the frontend RTK slice is replaced.
+- Frozen `website/versioned_docs/**` snapshots are not edited.
+- Syncing any ObjectId model other than GptHistory and McpServiceToken (e.g. User, PushToken,
+  AIRequest, AIDataset).
+- Replacing SSE streaming for `/gpt/prompt` and `/gpt/histories/:id/stream`. They stay
+  `fetch`-based, authenticated through the new client's auth provider.
+- Converting `api/src/auth.ts` / `authRecovery.ts` `router.*` routes to modelRouter actions.
+  Codegen reads them from OpenAPI as-is.
+
+## Decisions
+
+| Question | Decision |
+|----------|----------|
+| How far does removal go? | Delete the whole `@terreno/rtk` package. |
+| Which release? | Terreno 58.0.0, on the `release-58.0.0` line. |
+| Does Redux go too? | Yes. Remove `@reduxjs/toolkit`, `react-redux`, `redux-persist`, `@rtk-query/codegen-openapi` from both apps, the generators, and the catalog. App state moves to React context / `useStoredState`. |
+| Where do non-collection calls go? | Inside `@terreno/syncdb`: a request client + `useApiQuery` / `useApiMutation`, generalized from admin-frontend's `adminRequest` / `useAdminRpc`. |
+| GptHistory / McpServiceToken (ObjectId)? | Make both synced collections. |
+| GptHistory data migration | Migration shipped in `@terreno/ai` re-inserts each history with `_id` = its ObjectId hex string, rewrites `AIDataset.historyId`, deletes originals. New rows get UUIDs. |
+| McpServiceToken shape | Synced read-only (sync `responseHandler` strips `tokenHash`; client create/update/delete disabled). Create and revoke stay modelRouter actions called through the request client. Same hex-string `_id` migration. |
+| Home for non-data leftovers | syncdb subpaths: `/auth`, `/config`, `/flags`, `/app`. |
+| Replacement for `useSocketConnection` | An event-subscription API on syncdb's existing socket. Flags refetch on push. One socket per app. |
+| Codegen scope | Typed hooks for **every** non-synced OpenAPI operation (anything without `x-terreno-sync`). Replaces `@rtk-query/codegen-openapi` and the RTK `bun run sdk`. |
+| `@terreno/ui` consent / announcement hooks | Take a structural `client` prop (minimal request-client interface declared in ui). ui gains no dependency on syncdb. |
+| rtk features with no consumers | Delete offline middleware, `sessionApi`, `useServerStatus`, `useCan`, `useTerrenoChat`, `generateTags`, `mongooseSlice`, dev store. **Port** legacy JWT frontend auth into `@terreno/syncdb/auth`. Replace MCP `get_rtk_state` and `terreno state --slice rtk` with the existing syncdb state tools. |
+| PR shape | One PR. Tasks still land expand → migrate → contract on the branch, each leaving the branch green. |
+| 13 frontend-called routes are missing from OpenAPI (`/auth/me` + auth recovery, flags, version check, consents, announcements, `/files/upload`) — how does codegen cover them? | Document them in OpenAPI in their owning packages (`api`, `feature-flags`, `announcements`, `ai`) so codegen covers every call and `/auth/me` gets the app's own User type. |
+
+## Architecture
+
+### Before
+
+```
+example-frontend / admin-spa
+  Redux store ── betterAuth slice (@terreno/rtk) ── appState slice ── redux-persist
+             └── RTK Query api (store/betterAuthApi.ts + generated openApiSdk.ts)
+  @terreno/rtk: useSocketConnection, useFeatureFlags, useUpgradeCheck, baseUrl, ...
+  @terreno/syncdb: synced collections only (baseUrl passed in from rtk)
+```
+
+### After
+
+```
+@terreno/syncdb
+  .              createSyncDb, collections, sync socket (+ new socket event API)
+  /react         useQuery, useMutate, ... + useApiQuery, useApiMutation, ApiClientProvider
+  /api           createApiClient (fetch; auth from AuthProvider; envelope unwrap; tags)
+  /auth          createBetterAuthClient, betterAuthAdapter, SessionProvider/useSession,
+                 jwtAuthAdapter + useJwtAuth (ported JWT login/refresh/logout)
+  /config        baseUrl, baseWebsocketsUrl, resolveBaseUrls, resolveDevApiPort
+  /flags         useFeatureFlags, useTerrenoFeatureFlags (client + socket push, OpenFeature)
+  /app           useUpgradeCheck, canOpenAdminPage/hasPermission, installDevConsoleLogger,
+                 useMCPTools
+  /buildNumber   coerceBuildNumber, resolveBuildNumber (node-only)
+  codegen        `terreno-syncdb generate` emits collection hooks (today) AND typed hooks
+                 for every non-synced operation (new)
+```
+
+The request client and syncdb share one `AuthProvider` (`getToken`, `refresh`, `onAuthChange`),
+so 401 → refresh → retry behaves the same for sync and RPC. The client keeps
+`useAdminRpc`'s call shape (`{data, error, isLoading, isFetching, refetch}`,
+`[trigger, {isLoading}]` with `.unwrap()`), plus what the app needs that admin did not: a
+shared per-client cache keyed by URL+args (dedupes identical queries), lazy queries,
+imperative `client.request`, tag invalidation, `App-Version` / `App-Platform` headers,
+and `credentials` for cookie SPAs.
+
+admin-frontend's `adminRequest` / `useAdminRpc` become thin wrappers over the syncdb client so
+there is one implementation.
+
+### Session without Redux
+
+`SessionProvider` subscribes to the Better Auth session atom (already bridged by
+`bridgeBetterAuthReactClient`) and exposes `useSession()` → `{userId, user, isLoading,
+isAuthenticated, error, logout}`. `logout` signs out, stops syncdb, and wipes local data.
+JWT apps use `jwtAuthAdapter` (SecureStore / AsyncStorage tokens, mutex refresh, refresh
+when < 2 min to expiry, 401 → refresh → retry) and `useJwtAuth()` (`login`, `signup`,
+`googleLogin`, `resetPassword`, `logout`), feeding the same `SessionProvider`.
+
+### Socket events
+
+syncdb's socket transport gains `client.onSocketEvent(name, handler) → unsubscribe` and
+`useSocketEvent(name, handler)`. The RealtimeApp server already hosts that socket; feature
+flags subscribe to their existing push event and refetch `/feature-flags/flagConfiguration`.
+
+## Models
+
+| Model | Change |
+|-------|--------|
+| `GptHistory` (`ai/src/models/gptHistory.ts`) | `_id: String` (UUID default), `isDeletedPlugin` + `syncPlugin`. |
+| `AIDataset.historyId` (`ai/src/models/aiDataset.ts`) | Ref type `String`. |
+| `McpServiceToken` (`api/src/models/mcpServiceToken.ts`) | `_id: String`, `isDeletedPlugin` + `syncPlugin`. |
+
+Migrations (`api/src/migrations` framework):
+
+- `@terreno/ai` migration `gpt-history-string-ids`: for each ObjectId `_id` row, insert a copy with
+  `_id = oid.toHexString()`, update `AIDataset.historyId` refs to the hex string, delete the
+  original. Idempotent (skips rows whose `_id` is already a string). Runs in batches.
+- `@terreno/api` migration `mcp-service-token-string-ids`: same approach for McpServiceToken.
+
+## APIs
+
+| Route | Change |
+|-------|--------|
+| `/gpt/histories` | `modelRouter` gains `sync: {scope: owner}`. Existing REST CRUD stays for headless clients. |
+| `/gpt/prompt`, `/gpt/histories/:id/stream`, `/gpt/histories/:id/turn`, `/gpt/actions` | Accept string history ids. |
+| `/mcp/service-tokens` | Becomes `modelRouter("/mcp/service-tokens", McpServiceToken, {sync, ...})` with client writes disabled; `collectionActions.create` returns the plaintext once; `instanceActions.revoke`. |
+| Feature-flags deprecation message (`feature-flags/src/featureFlagsApp.ts:150`) | Names `@terreno/syncdb/flags`. |
+
+## UI
+
+- `ConsentNavigator`, `AnnouncementNavigator` and their hooks take `client: TerrenoRequestClient`
+  (structural interface in `ui/src/requestClient.ts`) instead of `api`.
+- No visual change. example-frontend's AI screen, MCP settings, profile, admin layout, auth screens,
+  documents, and notifications must behave the same; verified with screenshots in the PR.
+
+## Phases
+
+1. **Expand (syncdb):** request client + hooks, codegen for non-synced ops, `/config`, `/auth`
+   (Better Auth + JWT), socket events + `/flags`, `/app`.
+2. **Backend sync:** GptHistory and McpServiceToken synced, with migrations.
+3. **Migrate consumers:** ui, example-frontend, admin-spa, admin-frontend, generators, MCP/cli tools,
+   tests.
+4. **Contract:** delete `rtk/`, CI, scripts, configs; docs and rules; full verification.
+
+## Feature Flags & Migrations
+
+- No runtime flag; this is a major-version break.
+- Two data migrations (above). Upgrade notes tell operators to run migrations before deploying
+  58 frontends.
+
+## Not Included / Future Work
+
+- Syncing User/profile (`/auth/me`) or other ObjectId models.
+- Moving SSE chat streaming onto sync deltas.
+
+## Files to Create / Modify
+
+See [`docs/tasks/remove-rtk.md`](../tasks/remove-rtk.md) for per-task files.
+
+## Task List
+
+[`docs/tasks/remove-rtk.md`](../tasks/remove-rtk.md)
+
+## Acceptance Criteria
+
+| # | Criterion | Verification |
+|---|-----------|--------------|
+| AC1 | `rtk/` does not exist and no workspace references it. | `test ! -d rtk`; `rg -l '@terreno/rtk' -g '!website/versioned_docs/**' -g '!CHANGELOG.md' -g '!changelog/**' -g '!docs/implementationPlans/**' -g '!docs/tasks/**' -g '!**/upgrades/**'` → no hits outside upgrade/migration prose. |
+| AC2 | No Redux in the repo's packages. | `rg -l '@reduxjs/toolkit\|react-redux\|redux-persist\|@rtk-query/codegen-openapi' -g 'package.json' -g '*.ts' -g '*.tsx' -g 'bun.lock'` → no hits. |
+| AC3 | Everything builds and every suite passes with no test importing or mocking RTK. | `bun install && bun run compile`; `bun run test:agent` green; `rg -l "store/sdk\|openApiSdk\|betterAuthApi\|injectEndpoints" -g '*.test.*' -g '*.isolated.*' -g '*.spec.ts'` → no hits. |
+| AC4 | E2E and Maestro pass; RTK console-allowlist entries are gone and no new allowlist entries were added. | `bun run frontend:e2e` (all shards), `bun run admin-spa:test` + its e2e, `bun run maestro:test`; `rg "rejected query\|rejected mutation\|terrenoFlagConfiguration\|SocketConnection" example-frontend/e2e` → no hits. |
+| AC5 | GptHistory and McpServiceToken migrations rewrite ids and refs and are idempotent. | Bun tests in `ai/` and `api/` against the in-memory replica set: seed ObjectId rows + AIDataset refs → run twice → string ids, refs match, counts equal. |
+| AC6 | Synced McpServiceToken payloads never contain `tokenHash`; plaintext is returned only by the create action. | `api` sync snapshot + delta tests assert absence; action test asserts plaintext once. |
+| AC7 | example-frontend opens exactly one socket.io connection when logged in, and a flag change pushed by the server updates the UI. | Playwright spec counting `socket.io` websocket connections; flags spec toggling a flag via API. |
+| AC8 | Generated SDK covers every non-synced operation and is typed. | syncdb codegen tests against fixture spec; `example-frontend` `bun run sdk` then `bun run compile`. |
+| AC9 | JWT frontend auth works without Better Auth. | Ported bun tests from `authSlice` / `emptyApi` (login, refresh before expiry, 401 refresh-retry, mutex, logout) pass against `jwtAuthAdapter`. |
+| AC10 | Scaffolded apps build without rtk/Redux. | `create-terreno-app` generate tests + compile of a generated app; `mcp-server` tests. |
+| AC11 | Changed screens verified in a running app. | Screenshots/videos under `/opt/cursor/artifacts/` attached to the PR: login, profile, AI chat (list/rename/delete history), MCP tokens, consents, announcements, admin layout, admin-spa login. |
+| AC12 | Docs and rules describe the new layout; nothing tells users to install `@terreno/rtk`. | `bun run skills:sync` and rulesync regenerate cleanly; `website` docs-audit passes; 58.0.0 upgrade notes cover every removed export with its replacement. |

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-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: