@terreno/mcp 57.20.0 → 58.0.0-beta.1

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

@@ -49,11 +49,16 @@ REST API framework built on Express and Mongoose. Provides modelRouter (CRUD end
 
 Two patterns for building Terreno APIs:
 
-### Deprecated: modelRouter `realtime`
+### Removed: modelRouter `realtime`
 
-`modelRouter({ realtime })` (RTK cache-patching websocket events) is **deprecated** and **will be removed in Terreno 58**. Use `sync` with [`@terreno/syncdb`](syncdb.md). See [Migrate from RTK to syncdb](../how-to/migrate-rtk-to-syncdb.md).
+Terreno 58 removed `modelRouter({ realtime })` and the legacy RTK `sync` websocket event. Passing `realtime` is now a TypeScript error. Use `sync` with [`@terreno/syncdb`](syncdb.md). See [Upgrade from @terreno/rtk to @terreno/syncdb](../how-to/migrate-rtk-to-syncdb.md).
 
-`RealtimeApp` is **not** deprecated. It still hosts Socket.io, change streams, and `sync:delta`.
+Also removed: `RealtimeConfig`, `RealtimeEvent`, `DocumentSubscription`, `QuerySubscription`, the realtime registry (`registerRealtime`, `getRealtimeRegistry`, `findRegistryEntryByCollection`, `findRegistryEntryByRoutePath`, `updateRealtimeRegistryOptions`, `clearRealtimeRegistry`, `RealtimeRegistryEntry`), the query-subscription store (`addQuerySubscription`, `removeQuerySubscription`, `removeAllSocketQueries`, `getQuerySubscriptionsForCollection`, `computeQueryId`, `clearQueryStore`), and `MAX_MODEL_SUBSCRIPTIONS` / `MAX_DOCUMENT_SUBSCRIPTIONS` / `MAX_QUERY_SUBSCRIPTIONS`. The server no longer handles `subscribe:model`, `subscribe:document`, or `subscribe:query`.
+
+`RealtimeApp` stays. It hosts Socket.io, socket auth, change streams, and `sync:delta`.
+Before it sends a `sync:delta` to a socket, it runs the router's `read` permissions (or RBAC
+read access) against the change's post-image hydrated as a model document, as REST does. So a
+virtual owner field works: `GptHistory`'s `ownerId` alias of `userId` passes `Permissions.IsOwner`.
 
 Keep `admin.realtime` when you want admin `admin:model.changed` events.
 
@@ -99,15 +104,21 @@ new TerrenoApp({
 
 ### HTTP rate limiting
 
-Opt-in. Pass `rateLimit: {}` on `TerrenoApp` to enable (omitted = off; Terreno 58 defaults on).
+On by default. Omitted, `undefined`, or `{}` mounts the limiter with the memory store and the defaults below. `rateLimit: false` turns it off. On Cloud Run pass `trustProxy: 1`.
 
 ```typescript
 new TerrenoApp({
   userModel: User,
-  rateLimit: process.env.RATE_LIMIT_ENABLED === "true" ? {store: "memory"} : undefined,
+  rateLimit: {trustProxy: 1}, // or `false` to turn the limiter off
 });
 ```
 
+| `rateLimit` | Result |
+|-------------|--------|
+| omitted / `undefined` | On: memory store, default limits |
+| `{}` / `{store, limits, trustProxy, skip, betterAuthBasePath}` | On with those options |
+| `false` | Off |
+
 | Option | Default | Meaning |
 |--------|---------|---------|
 | `store` | `"memory"` | `"memory"` \| `"redis"` \| `"mongo"` |
@@ -138,6 +149,24 @@ new TerrenoApp({
 
 `mcpServiceTokens: true` is `{enabled: true}`. When enabled, TerrenoApp mounts the self-serve routes (passing its OpenAPI bundle) and sets `mcpServiceTokens` on MCP auth. Operator steps: [Connect an MCP client with a service token](../how-to/connect-mcp-service-token.md).
 
+### MCP request log and tool settings
+
+Both are opt-in and off by default.
+
+```typescript
+new TerrenoApp({
+  userModel: User,
+  mcpRequestLog: {enabled: true, retentionDays: 30}, // `true` is {enabled: true, retentionDays: 30}
+  mcpToolSettings: true,
+});
+```
+
+- `mcpRequestLog` writes one `McpRequestLog` row per `tools/call`: `toolName`, `userId`, `credential`, `serviceTokenId` or `oauthClientId` + `oauthFamilyId`, `durationMs`, `outcome` (`ok`, `tool_error`, `exception`), `errorName` (the error class only), and `expiresAt` (TTL index). Tool arguments, results, and error messages are never stored. Writes are fire-and-forget: a failed write is logged at debug level and never fails or delays the tool call. `retentionDays` must be positive; it applies to rows written after a change.
+- `mcpToolSettings` upserts one `McpToolSetting` row per tool when `/mcp` mounts (`name`, `description`, `source`: `model` or `custom`, `registered`, `lastRegisteredAt`). `enabled` is set to `true` only on insert, so a restart never undoes an admin's switch. Tools no longer registered get `registered: false`; rows are never deleted. Each `/mcp` request leaves out tools with `enabled: false`, so they are missing from `tools/list` and `tools/call` answers with an unknown-tool error. A tool without a row is served. `McpToolSetting.disabledNames()` caches the disabled set per process for 5 seconds; any write through the model clears it, so other instances see a switch within 5 seconds. A failed read reuses the last known set, or fails the request when there is none.
+- `MCPAuthResult` carries `serviceTokenId`, `oauthClientId`, and `oauthFamilyId` (identifiers, never secrets) for these rows.
+
+Admin screens for both, plus service tokens and OAuth clients and connections: [Manage MCP from the admin panel](../how-to/manage-mcp-in-admin.md).
+
 ### Audit log (`AuditApp`)
 
 Opt-in append-only log. Register the plugin; importing `@terreno/api` does **not** compile `AuditEvent` onto the default mongoose connection. The compiled Mongoose name is `TerrenoAuditEvent` on collection `auditevents`. Admin UI and RBAC keep `AuditEvent` / `adminAuditEvent`.
@@ -193,7 +222,7 @@ Both patterns create the same middleware stack (CORS, auth, logging, OpenAPI). H
 
 ## Collection catalog
 
-`modelRouter("/path", Model, options)` writes one catalog record per route path. MCP, realtime, and sync surfaces read that record; TerrenoApp calls `replaceCollectionOptions` once when access control is injected. Test helpers `clearMCPRegistry`, `clearRealtimeRegistry`, and `clearSyncRegistry` clear the entire catalog.
+`modelRouter("/path", Model, options)` writes one catalog record per route path. MCP and sync surfaces read that record; TerrenoApp calls `replaceCollectionOptions` once when access control is injected. Test helpers `clearMCPRegistry` and `clearSyncRegistry` clear the entire catalog.
 
 ## modelRouter actions
 
@@ -364,7 +393,7 @@ Create, update, and delete tools share REST permission, hook, and persistence se
 
 ### MCP service token model
 
-`McpServiceToken` stores the hashed credential records used by the optional MCP service-token feature. It is not a `modelRouter` model: consumer-facing create, list, and revoke routes are registered only when `mcpServiceTokens` is enabled on `TerrenoApp`.
+`McpServiceToken` stores the hashed credential records used by the optional MCP service-token feature. `_id` is a String (UUID for new rows; ObjectId hex for rows migrated from 57.x). The schema uses `isDeletedPlugin` and `syncPlugin`, so with `mcpServiceTokens` enabled the collection is synced read-only to its owner.
 
 ```typescript
 import {McpServiceToken} from "@terreno/api";
@@ -376,17 +405,23 @@ const {mcpServiceToken, token} = await McpServiceToken.issueFor(
 // Store or show `token` once. Only its SHA-256 hash is persisted.
 ```
 
-The token begins with `mcp_` followed by 32 random bytes encoded as hex. `issueFor` records the user's `tokenEpoch` (pass it on the user argument; default 0). `/mcp` refuses a token whose recorded epoch differs from the user's current `tokenEpoch` and sets its `revokedAt`, so a password reset, Better Auth password change, or session revocation ends every key minted before it. A row stored without `tokenEpoch` counts as epoch 0. `revokeOutdatedForUser(user)` revokes the user's keys from earlier epochs; the list and create routes call it so the list shows them as revoked. `verify(token)` returns `null` for unknown, expired, or revoked tokens. `revokeForUser(user, tokenId)` records `revokedAt`, and `countActiveForUser(userId)` excludes expired or revoked records. Document `deleteOne` (admin DELETE) also sets `revokedAt` and leaves the row for audit. Never return or log `tokenHash` or the plaintext token outside the initial issue result.
+The token begins with `mcp_` followed by 32 random bytes encoded as hex. `issueFor` records the user's `tokenEpoch` (pass it on the user argument; default 0). `/mcp` refuses a token whose recorded epoch differs from the user's current `tokenEpoch` and sets its `revokedAt`, so a password reset, Better Auth password change, or session revocation ends every key minted before it. A row stored without `tokenEpoch` counts as epoch 0. `revokeOutdatedForUser(user)` revokes the user's keys from earlier epochs; the list and create routes call it so the list shows them as revoked. `verify(token)` returns `null` for unknown, expired, or revoked tokens. `revokeForUser(user, tokenId)` records `revokedAt`, and `countActiveForUser(userId)` excludes expired or revoked records. A delete never removes or tombstones the row: document `deleteOne` and a soft delete (admin DELETE sets `deleted: true`) both set `revokedAt` and keep `deleted: false`, so the owner's synced row shows the revoke. `revokeAllForUser(userId)` revokes every active token the user holds and returns the count. Never return or log `tokenHash` or the plaintext token outside the initial issue result.
 
-Self-serve HTTP routes live at `/mcp/service-tokens`. `TerrenoApp` mounts them when `mcpServiceTokens` is enabled, passing its OpenAPI bundle. You can also call `addMcpServiceTokenRoutes(app, {publicMcpUrl, openApi})` yourself. They require session or JWT auth and **reject** `Authorization: Bearer mcp_…` so a service token cannot mint or list tokens.
+Self-serve routes are `modelRouter("/mcp/service-tokens", McpServiceToken, {sync: {scope: {type: "owner", field: "userId"}}})`. `TerrenoApp` mounts them when `mcpServiceTokens` is enabled, passing its OpenAPI bundle. You can also call `addMcpServiceTokenRoutes(app, {publicMcpUrl, openApi})` yourself, or build the registration with `createMcpServiceTokenRouter(options)`. They require session or JWT auth and **reject** `Authorization: Bearer mcp_…` so a service token cannot mint, list, or revoke tokens.
 
 | Method | Path | Body / params | Response |
 | --- | --- | --- | --- |
-| POST | `/mcp/service-tokens` | `{name, expiresAt?}` | `{data: {id, name, token, tokenPrefix, mcpUrl, expiresAt, created}}` |
-| GET | `/mcp/service-tokens` | `?page&limit` | `{data, page, limit, total, more}` — no `token` or `tokenHash` |
-| DELETE | `/mcp/service-tokens/:id` | — | `{data: {id, revokedAt}}` — owner only |
+| POST | `/mcp/service-tokens/create` | `{name, expiresAt?}` | `{data: {id, name, token, tokenPrefix, mcpUrl, expiresAt, created}}` (operation `mcpServiceTokens_create`) |
+| GET | `/mcp/service-tokens` | `?page&limit` | `{data, page, limit, more, total}` — the caller's rows, no `token` or `tokenHash` |
+| GET | `/mcp/service-tokens/:id` | — | `{data}` — owner only (`403` otherwise) |
+| POST | `/mcp/service-tokens/:id/revoke` | — | `{data}` — the revoked row without `tokenHash` (operation `mcpServiceTokens_revoke`) |
+| POST / PATCH / DELETE | `/mcp/service-tokens[/:id]` | — | `405`: client writes are disabled |
+
+`expiresAt` is an optional ISO-8601 datetime (Luxon `DateTime.fromISO`). Omit it for a token that does not expire. Create returns `mcpUrl` from `publicMcpUrl`, else `BETTER_AUTH_URL`, else the request host, with `/mcp` appended when missing. An 11th **active** token for the same user is `400`. Revoking an unknown, foreign, or already revoked token is `404`. List includes revoked rows for the owner so the UI can show history. Default and maximum page size is 100.
+
+Sync: collection `mcp/service-tokens`, stream `mcp/service-tokens|owner:{userId}`. Snapshot entities, `/sync/entities` rows, and `sync:delta` payloads go through `toPublicMcpServiceToken`, which drops `tokenHash`. Sync `create`, `update`, and `delete` mutations are nacked `unauthorized`; mint and revoke through the actions above.
 
-`expiresAt` is an optional ISO-8601 datetime (Luxon `DateTime.fromISO`). Omit it for a token that does not expire. Create returns `mcpUrl` from `publicMcpUrl`, else `BETTER_AUTH_URL`, else the request host, with `/mcp` appended when missing. An 11th **active** token for the same user is `400`. Revoke and cross-owner access are `404`. List includes revoked rows for the owner so the UI can show history. Default page size is 100 (maximum 100).
+Migration: `mcpServiceTokenStringIdsMigration.up` (slug `mcp-service-token-string-ids`) re-inserts each ObjectId row with `_id = oldId.toHexString()` and deletes the original. It is idempotent, resumes an interrupted run, and works without transactions. `migrateMcpServiceTokenStringIds(ctx)` returns `{converted, pending}`. Wire it into an app `migrations/` file as shown in [Run MongoDB migrations](../how-to/run-mongodb-migrations.md#framework-migrations).
 
 ### MCP OAuth
 
@@ -437,7 +472,7 @@ The consent endpoints are in OpenAPI (`getMcpOAuthRequest`, `approveMcpOAuthRequ
 
 Tokens are opaque (`mcpat_` access, `mcprt_` refresh) and stored only as SHA-256 hashes in `McpOAuthToken`. Each refresh rotates the pair; reusing a rotated refresh token revokes every pair issued from that authorization (its family). Codes are single-use: a failed exchange burns the code, and replaying a used code revokes the tokens it issued. The code exchange fixes the family id when it consumes the code, so a replay can revoke the family before its tokens exist. A `client_credentials` token has no refresh token. Its document still stores a unique hash of a discarded secret so the `refreshTokenHash` unique index is unchanged, and `hasRefreshToken: false` rejects that hash if it is ever presented. `McpOAuthClient.revoke(clientId)` revokes every family issued to that client. An authorization-code exchange, a refresh, or a client_credentials grant that loses a race with that revoke is discarded instead of returned. `deleteOne`, `findOneAndDelete`, and `deleteMany` revoke those families too. A query `deleteOne` or `findOneAndDelete` whose filter matches several clients deletes one of them and revokes that client's tokens. `bulkWrite` bypasses the hooks.
 
-`McpOAuthToken.revokeFamily(familyId)` first writes an `McpOAuthRevokedFamily` tombstone, then revokes every pair in the family. `McpOAuthToken.issue` refuses a tombstoned family with `McpOAuthFamilyRevokedError` (the token endpoint answers `invalid_grant`), and checks again after creating the pair, revoking it if a revoke landed meanwhile. A request that won a rotation or code exchange before a concurrent revoke therefore cannot leave a live pair behind. Tombstones expire after the family's last refresh expiry, and at least one hour after the revoke.
+`McpOAuthToken.revokeFamily(familyId)` first writes an `McpOAuthRevokedFamily` tombstone, then revokes every pair in the family. `McpOAuthToken.issue` refuses a tombstoned family with `McpOAuthFamilyRevokedError` (the token endpoint answers `invalid_grant`), and checks again after creating the pair, revoking it if a revoke landed meanwhile. A request that won a rotation or code exchange before a concurrent revoke therefore cannot leave a live pair behind. Tombstones expire after the family's last refresh expiry, and at least one hour after the revoke. Deleting an `McpOAuthToken` row (document `deleteOne` or query `deleteOne`, as the admin panel does) calls `revokeFamily` for that row's family and keeps every row, so the connection ends and its history stays. `deleteMany` and `bulkWrite` still remove rows without revoking. `McpOAuthToken.revokeAllForUser(userId)` revokes every active family the user holds and returns how many.
 
 Models: `McpOAuthClient` (`mcpoauthclients`), `McpOAuthAuthorization` (`mcpoauthauthorizations`, TTL on `expiresAt`), `McpOAuthToken` (`mcpoauthtokens`, TTL on `refreshExpiresAt`), `McpOAuthRevokedFamily` (`mcpoauthrevokedfamilies`, unique `familyId`, TTL on `expiresAt`).
 
@@ -471,8 +506,7 @@ setupServer({
 - `POST /auth/refresh_token` — Refresh access token
 - `POST /auth/forgotPassword` — Always 202; mails a reset link only when the email exists (with
   `BetterAuthApp` registered, only when that user already has a JWT password)
-- `POST /auth/resetPassword` — `{token, password}`; also aliased at `POST /resetPassword` for the
-  RTK client. With `BetterAuthApp` registered, a token for a user without a JWT password gets 400
+- `POST /auth/resetPassword` — `{token, password}`; also aliased at `POST /resetPassword` (the `jwtAuthAdapter` `resetPassword` path in `@terreno/syncdb/auth`). With `BetterAuthApp` registered, a token for a user without a JWT password gets 400
   `legacy-password-reset-unavailable` and sets no password (`POST /auth/login` has no second
   factor); that user resets through Better Auth
 - `POST /auth/sendVerification` — Authenticated; 202 only after delivery succeeds; mails a verification link when `emailVerified` is not true
@@ -497,8 +531,8 @@ letter case, needs no password. `currentPassword` is never saved.
 | User has no password (for example GitHub-only or social-only) | 400 `Set a password on your account before changing your email. …` | Nothing |
 | Right `currentPassword` | 200 with the updated user | The whole body |
 
-The status is 403, not 401, so `@terreno/rtk` does not treat a wrong password as an expired
-session and log the user out.
+The status is 403, not 401, so the syncdb request client does not treat a wrong password as an
+expired session and log the user out.
 
 The password is checked against the passport-local-mongoose hash first. A wrong password
 counts toward the model's passport lockout when `limitAttempts` is on, the same counter
@@ -575,7 +609,7 @@ case instead of 202. Email lookup is case-insensitive. Successful reset calls `s
 and deletes Better Auth sessions. Better Auth password reset updates the JWT password of the
 matching app User when it already has one, and bumps its `tokenEpoch`. Access
 tokens stay valid until expiry (default 15m). `POST /resetPassword`
-matches the `@terreno/rtk` `resetPassword` mutation path (`password` or `newPassword`).
+matches the `@terreno/syncdb/auth` `jwtAuthAdapter` `resetPassword` path (`password` or `newPassword`).
 
 For any other server-side password change, such as an admin "set password" action, call
 `changeUserPassword(user, password, {adminId, app: req.app})`. It does what reset does: sets the
@@ -803,7 +837,7 @@ Endpoints it adds, under `basePath` (default `/api/auth`):
   cookie, and redirects to the provider. A link that cannot start redirects to
   `errorCallbackURL` (or `callbackURL`) with `error=session_expired`, `error=provider_not_found`,
   or `error=link_failed`. The provider callback links the account and redirects to `callbackURL`
-  with no `#ott`, since no session is created. rtk's `linkSocialWithHandoff` drives both steps;
+  with no `#ott`, since no session is created. `linkSocialWithHandoff` from `@terreno/syncdb/auth` drives both steps;
   see [Linking a provider in bearer mode](../how-to/configure-better-auth.md#linking-a-provider-in-bearer-mode).
 
 With the opt-in `rateLimit`, every path above is in the auth bucket. Better Auth's own limiter
@@ -814,7 +848,7 @@ allows three starts, three link intents, and three link starts per ten seconds p
 Every Better Auth server answers `GET {basePath}/terreno/methods` (default
 `/api/auth/terreno/methods`) with the sign-in methods it has enabled, so a login screen renders
 only those. It needs no session. Read it from a frontend with `useAuthMethods(authClient)` from
-`@terreno/rtk`.
+`@terreno/syncdb/auth`.
 
 ``````json
 {
@@ -852,8 +886,7 @@ plugin-registered providers are reflected.
 
 Every Better Auth server serves `POST {basePath}/terreno/set-password` (default
 `/api/auth/terreno/set-password`) so a signed-in user who has no password, such as one who signed
-up with a provider, can add one. Better Auth's own `setPassword` is server-only. rtk's
-`useAccountSecurity` calls it from the password card's "Set a password" form.
+up with a provider, can add one. Better Auth's own `setPassword` is server-only. `useAccountSecurity` from `@terreno/syncdb/auth` calls it from the password card's "Set a password" form.
 
 | Request | Response |
 | --- | --- |
@@ -885,8 +918,8 @@ means the cookie expired. Only values the response sets are carried. Such a sign
 answers with a two-factor challenge has no `set-auth-token`. The header is listed in
 `Access-Control-Expose-Headers`. On `{basePath}/two-factor/*`, `/passkey/*`, and `/sign-in/*`,
 the header's challenge cookies are merged into the request's cookies unless a real cookie of
-the same name is present; other names, including session cookies, are ignored. rtk's bearer mode
-uses it; see
+the same name is present; other names, including session cookies, are ignored. The
+`@terreno/syncdb/auth` bearer mode uses it; see
 [Challenges without cookies](../explanation/authentication.md#challenges-without-cookies).
 
 **Endpoints (when enabled):**

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

@@ -2,7 +2,7 @@
 
 Install: `bun add -g @terreno/cli` then run `terreno --help`.
 
-The `terreno` binary is the operator CLI for Terreno apps. It wraps documentation search, codegen (syncdb SDK, RTK OpenAPI SDK, Mongoose models, routes, screens, forms, admin install notes), app bootstrap, local project tools from `@terreno/mcp`, and **OpenAPI-driven REST calls**.
+The `terreno` binary is the operator CLI for Terreno apps. It wraps documentation search, codegen (syncdb collection SDK, typed API request SDK, Mongoose models, routes, screens, forms, admin install notes), app bootstrap, local project tools from `@terreno/mcp`, and **OpenAPI-driven REST calls**.
 
 Generate an app-specific CLI from your backend spec:
 
@@ -18,7 +18,7 @@ terreno generate rest-cli --schema http://localhost:4000/openapi.json --out ./to
 | `docs component <Name>` | Print `@terreno/ui` component props |
 | `docs upgrade --from --to` | Lockstep upgrade notes |
 | `generate syncdb` | Typed syncdb hooks from OpenAPI (`--schema`, `--out`, `--collections`, `--config`, `--no-format`) |
-| `generate sdk` | Run `@rtk-query/codegen-openapi` with `--config` |
+| `generate sdk` | Typed request hooks (`apiSdk.ts`) for every non-synced route via the syncdb codegen (`--schema`, `--out`, `--config`, `--no-format`); same output as `terreno-syncdb-codegen --api-out`. A legacy RTK `--config openapi-config.ts` alone is rejected |
 | `generate rest-cli` | Scaffold a bun CLI from OpenAPI (`--schema`, `--out`, `--name`, `--base-url`) |
 | `generate model` | Mongoose model (`--name`, `--field name:Type:required`, `--owner`, `--soft-delete`) |
 | `generate route` | `modelRouter` module (`--model-name`, `--route-path`, `--owner-filtered`, `--query-fields`, `--sort`) |
@@ -33,8 +33,7 @@ terreno generate rest-cli --schema http://localhost:4000/openapi.json --out ./to
 | `api request <METHOD> <path>` | Invoke by method + path template |
 | `info` | Local `@terreno/*` versions (via MCP local tools) |
 | `logs` | Merge backend/browser JSONL, Metro events, and app CDP console (`--entries`, `--level`, `--since`, `--sources`; `last-error`) |
-| `state` | Inspect client state with `get_client_state`: RTK Query (Better Auth via the `auth` alias or `betterAuth`; `--slice`, `--query`) and SyncDB, through the dev stores or Metro CDP. The result names the detected `layer` |
-| `eval` | Evaluate JavaScript in the app runtime through Metro CDP (`--code`; requires `TERRENO_MCP_EVAL=1`) |
+| `state` | Inspect the live SyncDB client (`get_syncdb_state`): status, entities, outbox, conflicts, cursors, streams, debug events (`--collection`, `--entity-id`, `--limit`, `--name`, `--no-events`). Needs `createSyncDb({debug: true})`. The Terreno 57 `--slice` / `--query` Redux flags were removed in 58 and now exit 1 || `eval` | Evaluate JavaScript in the app runtime through Metro CDP (`--code`; requires `TERRENO_MCP_EVAL=1`) |
 | `navigate` | Navigate Expo Router through Metro CDP (requires `TERRENO_MCP_EVAL=1`) |
 | `web [url]` | Automate the web app with Bun 1.4 `Bun.WebView`; ordered `--action` JSON, `--snapshot`, and `--screenshot` |
 | `db schema` | Mongo collections (`--collection-filter`, `--summary`) |

package/src/docs/versioned/next/reference/environment-variables.md

@@ -85,10 +85,10 @@ Comprehensive guide to environment variables used across Terreno packages and ex
 
 | Variable | Read by | Required | Default | Secret | Scope |
 |----------|---------|----------|---------|--------|-------|
-| `EXPO_PUBLIC_API_URL` | `@terreno/rtk` | ✅ prod web | dev auto-detect | No | **client** |
-| `EXPO_PUBLIC_DEV_API_PORT` | `@terreno/rtk` | ❌ | `4000` | No | **client** |
-| `EXPO_PUBLIC_BUILD_NUMBER` | example-frontend | ❌ | — | No | **client** |
-| `OPENAPI_URL` | example-frontend `sdk` script | ❌ | `http://localhost:4000/openapi.json` | No | tooling |
+| `EXPO_PUBLIC_API_URL` | `@terreno/syncdb/config` | ✅ prod web | dev auto-detect | No | **client** |
+| `EXPO_PUBLIC_DEV_API_PORT` | `@terreno/syncdb/config` | ❌ | `4000` | No | **client** |
+| `EXPO_PUBLIC_BUILD_NUMBER` | `@terreno/syncdb/buildNumber` (`app.config.ts`) | ❌ | git commit count | No | **client** |
+| `OPENAPI_URL` | example-frontend `sdk` / `sync-sdk` scripts | ❌ | `http://localhost:4000/openapi.json` | No | tooling |
 
 ### `app.json` `extra` (not `process.env`)
 
@@ -96,18 +96,17 @@ Configured in `expo.extra` and read via `expo-constants`:
 
 | Key | Read by | Notes |
 |-----|---------|-------|
-| `BASE_URL` | `@terreno/rtk` | Production fallback when `EXPO_PUBLIC_API_URL` unset; use `__SAME_ORIGIN__` for same-origin admin SPA |
-| `DEV_API_PORT` | `@terreno/rtk` | Override dev API port (mirrors `EXPO_PUBLIC_DEV_API_PORT`) |
-| `AUTH_DEBUG` | `@terreno/rtk` | `"true"` enables auth debug logs |
-| `WEBSOCKETS_DEBUG` | `@terreno/rtk` | `"true"` enables socket debug logs |
-| `SOCKET_TRANSPORTS` | example-frontend (`store/socketTransports.ts`) | Comma-separated Socket.IO transports passed to `useSocketConnection({transports})` and `createSyncDb({socketTransports})`. Unset keeps `polling,websocket`; the Vercel build sets `websocket` |
-| `APP_ENV` | `@terreno/rtk` | Logged at startup |
+| `BASE_URL` | `@terreno/syncdb/config` | Production fallback when `EXPO_PUBLIC_API_URL` unset; use `__SAME_ORIGIN__` for same-origin admin SPA |
+| `DEV_API_PORT` | `@terreno/syncdb/config` | Override dev API port (mirrors `EXPO_PUBLIC_DEV_API_PORT`) |
+| `buildNumber` | `@terreno/syncdb/app` `useUpgradeCheck` | Sent to `GET /version-check`; set it with `resolveBuildNumber` |
+| `SOCKET_TRANSPORTS` | example-frontend (`store/socketTransports.ts`) | Comma-separated Socket.IO transports passed to `createSyncDb({socketTransports})`. Unset keeps `polling,websocket`; the Vercel build sets `websocket` |
 
-Resolution order for API base URL (`rtk/src/constants.ts`):
+Resolution order for API base URL (`syncdb/src/config/resolveBaseUrls.ts`):
 
-1. `EXPO_PUBLIC_API_URL` (production and dev)
-2. `extra.BASE_URL` (production only, when env unset)
-3. Dev fallbacks: `hostUri`, experience URL, `localhost`
+1. `extra.BASE_URL` = `__SAME_ORIGIN__` → the page origin (web)
+2. `EXPO_PUBLIC_API_URL` (production and dev)
+3. `extra.BASE_URL` (production only, when env unset)
+4. Dev fallbacks: `hostUri`, experience URL, `localhost` on the dev API port
 
 `EXPO_PUBLIC_API_URL` is inlined only into app source. Code under `node_modules`, including `@terreno/rtk`, does not see the inlined value in a production export and falls back to `extra.BASE_URL`, so set both for production web builds. `example-frontend/scripts/vercelBuild.ts` writes `extra.BASE_URL` from `EXPO_PUBLIC_API_URL` before `expo export`.
 
@@ -232,7 +231,7 @@ for authenticated test sends.
 | `VALKEY_URL` | `@terreno/api` realtime adapter **and** `rateLimit.store: "redis"` | ❌ | — | Yes | server |
 | `REDIS_URL` | `@terreno/api` fallback after `VALKEY_URL` (realtime + Redis rate-limit store) | ❌ | — | Yes | server |
 
-There is **no** `RATE_LIMIT_ENABLED` (or similar) read by `@terreno/api`. Apps that want an env toggle pass `rateLimit: process.env.RATE_LIMIT_ENABLED === "true" ? {store: "memory"} : undefined` themselves. See [Rate limiting](../how-to/rate-limiting.md).
+There is **no** `RATE_LIMIT_ENABLED` (or similar) read by `@terreno/api`. The limiter is on by default. Apps that want an env toggle pass `rateLimit: process.env.RATE_LIMIT_DISABLED === "true" ? false : {trustProxy: 1}` themselves. See [Rate limiting](../how-to/rate-limiting.md).
 
 ## Webhooks & notifications
 
@@ -317,7 +316,8 @@ example-backend **test** setup only. They are not read by `@terreno/jobs`. Use
 
 `SEED_DEFAULTS=true` runs the example seed (default users, all with the published password
 `testpassword123`) when the server starts. A process with `NODE_ENV=production` logs a warning and
-skips it, so no deployed revision, PR previews included, holds those accounts.
+skips it, so no deployed revision holds those accounts. The exception is a PR preview, whose
+`MONGO_DB_NAME` starts with `terreno-example-pr-`: it seeds its own throwaway database.
 
 ## Testing & CI (tooling only)
 

package/src/docs/versioned/next/reference/feature-flags.md

@@ -41,14 +41,16 @@ new TerrenoApp({userModel: User})
 
 ### Frontend
 
-Use the `useFeatureFlags` hook from `@terreno/rtk` to evaluate flags for the current user:
+Use `useFeatureFlags` from `@terreno/syncdb/flags` to read flags for the current user. It
+loads `GET {basePath}/flagConfiguration` with the syncdb request client (the one from
+`ApiClientProvider`) and refetches when the server pushes `featureFlagsChanged` on the
+syncdb socket:
 
 ```typescript
-import {useFeatureFlags} from "@terreno/rtk";
-import {terrenoApi} from "@/store/sdk";
+import {useFeatureFlags} from "@terreno/syncdb/flags";
 
-const MyComponent = () => {
-  const {getFlag, getVariant, isLoading} = useFeatureFlags(terrenoApi);
+const MyComponent: React.FC<{userId?: string}> = ({userId}) => {
+  const {getFlag, getVariant, isLoading} = useFeatureFlags({skip: !userId, userId});
 
   if (isLoading) return <Spinner />;
 
@@ -59,11 +61,41 @@ const MyComponent = () => {
 };
 ```
 
-New code can also use OpenFeature React hooks (`useBooleanFlagValue`, `useStringFlagValue`, `FeatureFlag`, …) after wiring `useTerrenoFeatureFlags` and `<OpenFeatureProvider domain="feature-flags">` — see `@terreno/rtk` and [how-to: add feature flags](../how-to/add-feature-flags.md).
+New code can also use OpenFeature React hooks (`useBooleanFlagValue`, `useStringFlagValue`, `FeatureFlag`, …) after wiring `useTerrenoFeatureFlags` and `<OpenFeatureProvider domain="feature-flags">` — see [how-to: add feature flags](../how-to/add-feature-flags.md).
+
+#### `@terreno/syncdb/flags`
+
+| Export | Description |
+|--------|-------------|
+| `useTerrenoFeatureFlags(options?)` | Loads `/flagConfiguration` into OpenFeature's `TypedInMemoryProvider` for `domain`; returns `{client, flags, isLoading, error, refetch}` |
+| `useFeatureFlags(options?)` | Flat accessors over `useTerrenoFeatureFlags`: `{flags, getFlag, getVariant, isLoading, error, refetch}` |
+| `TerrenoFlagConfiguration`, `TerrenoFlagDefinition` | Wire shape of `/flagConfiguration` |
+| `DEFAULT_FEATURE_FLAGS_BASE_PATH`, `DEFAULT_FEATURE_FLAGS_DOMAIN`, `DEFAULT_FEATURE_FLAGS_EVENT` | `"/feature-flags"`, `"feature-flags"`, `"featureFlagsChanged"` |
+
+Options (both hooks):
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `userId` | `null` | Current user. A change refetches and sets the OpenFeature `targetingKey` |
+| `skip` | `false` | Do not fetch or listen (for example while signed out) |
+| `client` | `ApiClientProvider` client | Request client from `@terreno/syncdb/api` |
+| `socket` | `SyncDbProvider` client | Anything with `onSocketEvent` (a `SyncDb`). Pass your `syncDb` when the hook sits above `SyncDbProvider`; `null` turns live refresh off |
+| `socketEventName` | `"featureFlagsChanged"` | Push event that triggers a refetch |
+| `basePath` | `"/feature-flags"` | `FeatureFlagsApp` `basePath` |
+| `domain` | `"feature-flags"` | OpenFeature domain; must match `<OpenFeatureProvider domain>` |
+
+`isLoading` is `true` until the first response is installed in OpenFeature and again while a
+refetch is in flight; it is `false` when skipped or after an error. Every hook reading the same
+`basePath` shares one cache entry, so a single instance that listens to the socket (usually the
+root `OpenFeatureProvider` bridge) is enough; other screens can pass `socket: null`. The last
+unmounted `useTerrenoFeatureFlags` for a domain restores OpenFeature's NOOP provider.
+
+`@openfeature/web-sdk` (and `@openfeature/react-sdk` for the React hooks) are optional peer
+dependencies of `@terreno/syncdb`; add them to apps that import `@terreno/syncdb/flags`.
 
 ## OpenFeature integration
 
-`FeatureFlagsApp` registers an OpenFeature **server** provider (`MongoFeatureFlagProvider`) on a dedicated domain (default `"feature-flags"`) so the global default provider is unchanged. The authenticated bulk endpoint **`GET {basePath}/flagConfiguration`** returns a `FlagConfiguration`-compatible map (suitable for `TypedInMemoryProvider` on the client). Disabled **boolean** flags are included and resolve to `off`, so a client can tell a turned-off flag from one that was never created. Disabled variant flags and archived flags are omitted. The legacy **`GET {basePath}/evaluate`** response shape is unchanged but is **deprecated**: responses include `Deprecation: true` and a `Sunset` HTTP-date header (~90 days). Prefer `useTerrenoFeatureFlags` / `useFeatureFlags` from `@terreno/rtk`, or migrate direct HTTP callers to `/flagConfiguration`.
+`FeatureFlagsApp` registers an OpenFeature **server** provider (`MongoFeatureFlagProvider`) on a dedicated domain (default `"feature-flags"`) so the global default provider is unchanged. The authenticated bulk endpoint **`GET {basePath}/flagConfiguration`** returns a `FlagConfiguration`-compatible map (suitable for `TypedInMemoryProvider` on the client). Disabled **boolean** flags are included and resolve to `off`, so a client can tell a turned-off flag from one that was never created. Disabled variant flags and archived flags are omitted. The legacy **`GET {basePath}/evaluate`** response shape is unchanged but is **deprecated**: responses include `Deprecation: true` and a `Sunset` HTTP-date header (~90 days). Prefer `useTerrenoFeatureFlags` / `useFeatureFlags` from `@terreno/syncdb/flags`, or migrate direct HTTP callers to `/flagConfiguration`. The server logs this advice once per process on the first `/evaluate` call.
 
 ### `defaultVariant` on `FeatureFlag`
 
@@ -81,6 +113,15 @@ Consumers may augment `@openfeature/core` with `BooleanFlagKey` / `StringFlagKey
 
 Pass `liveUpdates: { socketIoServer: io | () => io }` to broadcast on Mongoose change streams. **Requires MongoDB as a replica set** (single-node replset is fine). Emits a socket event (default `featureFlagsChanged`, payload `{ key }`) and `PROVIDER_CONFIGURATION_CHANGED` on the server provider. All authenticated subscribers receive the same event name; payload is only the flag key (same keys are already exposed per user via `/flagConfiguration`).
 
+Emit on the Socket.io server that hosts the syncdb socket — `RealtimeApp.getIo()` — so clients
+receive the push on the one socket they already hold:
+
+```typescript
+const realtimeApp = new RealtimeApp({/* ... */});
+app.register(realtimeApp);
+app.register(new FeatureFlagsApp({liveUpdates: {socketIoServer: () => realtimeApp.getIo()}}));
+```
+
 ## Exports
 
 ### Classes

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

@@ -237,8 +237,8 @@ always hides payload regardless of the hook.
 Widgets are registered in the built-in registry — enable via `JobsApp.adminContribution()` only.
 The admin shell lists Jobs under **Platform** (not Screens). Hosts still contribute
 `name: "jobs"`; do not add a second sidebar link.
-Custom screens should pass the app's generated RTK `api` into `AdminProvider`; jobs screens wire
-admin HTTP internally (not via a public `useJobsDashboardApi` export).
+Custom screens render inside the app's `AdminProvider` (auth binding); jobs screens wire
+admin HTTP through its fetch client internally (not via a public `useJobsDashboardApi` export).
 
 ## GCP Cloud Tasks (`@terreno/jobs/runners/gcpCloudTasks`)