@terreno/mcp 57.21.0 → 58.0.0-beta.1

package/src/docs/versioned/next/explanation/announcements/rtk-deprecation.md

@@ -1,28 +1,33 @@
-# RTK deprecation announcement (draft)
+# RTK removal announcement (draft)
 
 **Do not post until maintainers review.** Target: GitHub Discussions → Announcements.
 
 ---
 
-## `@terreno/rtk` data sync is deprecated — migrate to `@terreno/syncdb`
+## `@terreno/rtk` and Redux are removed in Terreno 58
 
-Starting with **56.0.0**, Terreno's default frontend data path is **local-first** via [`@terreno/syncdb`](https://github.com/TerrenoLabs/terreno/blob/master/docs/reference/syncdb.md). Collection reads and writes apply to an on-device store first; the server reconciles over the sync protocol. This replaces RTK Query hooks for CRUD lists and mutations.
+Terreno **58.0.0** deletes `@terreno/rtk` and every Redux dependency. [`@terreno/syncdb`](https://github.com/TerrenoLabs/terreno/blob/master/docs/reference/syncdb.md) is now the only frontend data and session layer. `@terreno/rtk` is not published for 58.
 
 ### What changed
 
-- **New:** `@terreno/syncdb` — `useQuery`, `useMutate`, offline outbox, conflict resolution, sync status UX
-- **Deprecated:** RTK Query hooks for synced collections (`useGetTodosQuery`, `usePostTodosMutation`, manual optimistic updates)
-- **Unchanged:** `bun run sdk` still generates the OpenAPI SDK for auth, profile, admin, AI, and other non-synced routes
+- **Collections:** `useQuery` / `useMutate` read and write a local-first store (unchanged since 56).
+- **Every other route** (`/auth/me`, modelRouter actions, AI, consents, announcements): a request client in `@terreno/syncdb/api` with typed hooks generated by `terreno-syncdb-codegen --api-out`. Hook names match the old RTK codegen.
+- **Session:** `SessionProvider` + `useSession()` from `@terreno/syncdb/auth` (Better Auth, or `jwtAuthAdapter` for JWT backends).
+- **Flags and pushes:** ride the syncdb socket (`@terreno/syncdb/flags`, `useSocketEvent`). One socket per app.
+- **App utilities:** base URLs in `@terreno/syncdb/config`; upgrade check, permissions, dev logger, and MCP tools in `@terreno/syncdb/app`.
+- **Backend:** `GptHistory` and `McpServiceToken` are synced collections with String ids. Two data migrations ship with 58.
 
 ### What you need to do
 
-1. **By next major:** move collection screens from RTK Query to syncdb. `@terreno/rtk` will not publish in the next major line.
-2. **Support window:** `@terreno/rtk` continues to publish with a deprecation notice through the **current major** (56.x beta and stable 0.x).
-3. **Recommended order:** migrate to **Better Auth** first, then syncdb per screen ([migration guide](https://github.com/TerrenoLabs/terreno/blob/master/docs/how-to/migrate-rtk-to-syncdb.md)).
+1. Run the `GptHistory` and `McpServiceToken` migrations before deploying 58 frontends.
+2. Follow the [upgrade guide](https://github.com/TerrenoLabs/terreno/blob/master/docs/how-to/migrate-rtk-to-syncdb.md). It maps every removed export to its replacement.
+3. Remove `@terreno/rtk`, `@reduxjs/toolkit`, `react-redux`, `redux-persist`, and `@rtk-query/codegen-openapi` from the app.
 
-### Why local-first
+Apps that stay on 57.x keep `@terreno/rtk` 57.x.
 
-Instant UI, durable offline writes, and simpler screen code — at the cost of explicit conflict and sync-status handling. See [local-first data](https://github.com/TerrenoLabs/terreno/blob/master/docs/explanation/local-first-data.md).
+### Why
+
+One data layer means one socket, one auth provider, and one cache for every request. See [local-first data](https://github.com/TerrenoLabs/terreno/blob/master/docs/explanation/local-first-data.md).
 
 ### Questions
 

package/src/docs/versioned/next/explanation/authentication.md

@@ -6,9 +6,9 @@ Understanding how authentication works in @terreno/api — Better Auth sessions
 
 **Better Auth is the default path** for new Terreno apps. It provides session-based authentication with MongoDB storage, built-in social OAuth (Google, GitHub, Apple), and clean integration with `@terreno/syncdb` (`betterAuthAdapter`, `RealtimeApp` socket sessions).
 
-Set `AUTH_PROVIDER=better-auth` and register `BetterAuthApp` on the server. On the client, use `createBetterAuthClient` + `generateBetterAuthSlice` from `@terreno/rtk` for session Redux state, then wire `betterAuthAdapter` into `createSyncDb`.
+Set `AUTH_PROVIDER=better-auth` and register `BetterAuthApp` on the server. On the client, use `createBetterAuthClient` and `SessionProvider` / `useSession()` from `@terreno/syncdb/auth` for session state (React context, no Redux), then wire `betterAuthAdapter` into `createSyncDb` and the API client.
 
-**JWT/Passport (legacy)** remains supported through the current major release line for existing deployments. It uses stateless tokens, Passport strategies (email/password, GitHub OAuth, anonymous), and manual token refresh via `@terreno/rtk`. New projects should not start on JWT unless they have a specific requirement (custom token contracts, non-cookie clients, or a phased migration).
+**JWT/Passport (legacy)** remains supported through the current major release line for existing deployments. It uses stateless tokens, Passport strategies (email/password, GitHub OAuth, anonymous), and client-side token refresh via `jwtAuthAdapter` from `@terreno/syncdb/auth`. New projects should not start on JWT unless they have a specific requirement (custom token contracts, non-cookie clients, or a phased migration).
 
 Both systems can run in parallel during migration (`AUTH_PROVIDER` selects the primary path; legacy JWT routes stay available).
 
@@ -23,7 +23,7 @@ Both systems can run in parallel during migration (`AUTH_PROVIDER` selects the p
 | `@terreno/syncdb` local-first data | Non-cookie API clients only |
 | Socket sessions via `RealtimeApp` | Gradual migration in progress |
 
-**Setup:** [Configure Better Auth](../how-to/configure-better-auth.md). **Data layer:** migrate auth before or with syncdb — see [Migrate from RTK to syncdb](../how-to/migrate-rtk-to-syncdb.md) §7.
+**Setup:** [Configure Better Auth](../how-to/configure-better-auth.md). **Data layer:** migrate auth before or with syncdb — see [Upgrade from @terreno/rtk to @terreno/syncdb](../how-to/migrate-rtk-to-syncdb.md) §3–4.
 
 ## Authentication Strategies
 
@@ -68,7 +68,7 @@ the `X-Terreno-Auth-Challenge` header instead:
    never set a session cookie, and a tampered value fails Better Auth's signature check (the 2FA
    verify answers 401, a passkey verify 400 `CHALLENGE_NOT_FOUND`, and a tampered trust value
    just asks for the second factor).
-4. rtk's bearer mode stores the header under `${storagePrefix}_auth_challenge` in the same
+4. `@terreno/syncdb/auth`'s bearer mode stores the header under `${storagePrefix}_auth_challenge` in the same
    `bearerStorage` as the bearer token. It never stores a token from a response that asks for a
    second factor. It drops the 2FA challenge and `dont_remember` after a successful verify, and
    everything but the trust-device value on sign-out. The trust-device value stays until the server
@@ -147,7 +147,7 @@ short-lived cookie. The callback rejects a response without matching state.
 
 ### MCP service tokens (opt-in, `/mcp` only)
 
-Personal `mcp_` keys for remote MCP clients (Perplexity, Cursor JSON config) that cannot hold a session cookie. `TerrenoApp` must set `mcpServiceTokens`. Users mint keys from `POST /mcp/service-tokens` or **Profile → MCP connections**. The plaintext secret is returned **once**; the database stores SHA-256 `tokenHash`.
+Personal `mcp_` keys for remote MCP clients (Perplexity, Cursor JSON config) that cannot hold a session cookie. `TerrenoApp` must set `mcpServiceTokens`. Users mint keys from `POST /mcp/service-tokens/create` or **Profile → MCP connections**. The plaintext secret is returned **once**; the database stores SHA-256 `tokenHash`.
 
 `extractUserFromHeaders` on `/mcp` tries a `mcp_` Bearer first, then Better Auth, then JWT. A match loads the owning `User` and updates `lastUsedAt`. Revoked, expired, or disabled-user keys resolve to no user, and so does a key minted before the user's last password reset or session revocation (`tokenEpoch` changed since it was issued). MCP OAuth grants end the same way. The same Bearer is ignored on REST, sync, admin, and on the mint/list/revoke routes (a key cannot mint another key).
 
@@ -210,19 +210,21 @@ modelRouter(Model, {
 
 ### Token Payload
 
-Access tokens contain:
+Access and refresh tokens contain:
 
 ``````json
 {
-  "sub": "507f1f77bcf86cd799439011",  // User ID
-  "admin": false,                      // Admin status
-  "iat": 1709000000,                   // Issued at (timestamp)
-  "exp": 1709000900,                   // Expires at (timestamp)
-  "iss": "your-app-name"               // Issuer (from TOKEN_ISSUER env var)
+  "id": "507f1f77bcf86cd799439011",  // User ID (the frontend reads the signed-in user from it)
+  "sid": "4f9c…",                     // Session ID, kept across refreshes
+  "te": 0,                            // User token epoch; bumping it revokes refresh tokens
+  "iat": 1709000000,                  // Issued at (timestamp)
+  "exp": 1709000900,                  // Expires at (timestamp)
+  "iss": "your-app-name"              // Issuer (from TOKEN_ISSUER env var)
 }
 ``````
 
-Customize the payload with `authOptions.generateJWTPayload`:
+Add claims with `authOptions.generateJWTPayload`. `id`, `sid`, and `te` always win over
+custom claims:
 
 ``````typescript
 setupServer({
@@ -238,42 +240,58 @@ setupServer({
 
 ### Token Refresh Flow
 
-1. Access token expires (after 15 minutes)
-2. API request returns `401 Unauthorized`
-3. Frontend middleware detects 401
-4. Frontend calls `POST /auth/refresh_token` with refresh token
-5. Backend validates refresh token
-6. Backend issues new access token and refresh token
-7. Frontend retries original request with new token
+1. Before each request, the frontend checks the stored access token. With under two minutes
+   left (or already expired), it calls `POST /auth/refresh_token` with the refresh token first.
+2. If a request still returns `401 Unauthorized`, the frontend refreshes and retries the
+   request once.
+3. The backend verifies the refresh token and the user's token epoch, then returns a new
+   access and refresh token pair (`{data: {token, refreshToken}}`).
+4. Concurrent requests share one refresh call.
+5. If the backend rejects the refresh, the frontend clears both tokens and signs out. A
+   network failure or timeout keeps the session and the current token.
 
-This is handled automatically by @terreno/rtk's `emptyApi` configuration.
+`jwtAuthAdapter` from `@terreno/syncdb/auth` does this for the syncdb request client and
+`createSyncDb` (it replaces `@terreno/rtk`'s `emptyApi` base query).
 
 ## Frontend Integration
 
-### Redux Store Setup (with @terreno/rtk)
+### Session State (Better Auth)
 
-``````typescript
-import {generateAuthSlice} from "@terreno/rtk";
-import {configureStore} from "@reduxjs/toolkit";
-import {openapi} from "./openApiSdk";
+`@terreno/syncdb/auth` owns the frontend session. One Better Auth client feeds three
+consumers:
 
-const {authReducer, middleware, logout} = generateAuthSlice(openapi);
+- `SessionProvider` / `useSession()` — `{userId, user, isLoading, isAuthenticated, error,
+  logout, refresh}` for screens and routing.
+- `betterAuthAdapter(bridgeBetterAuthReactClient(client))` — the `AuthProvider` that
+  `createSyncDb` and the API client use for bearer tokens and 401 refresh.
+- The Better Auth client itself — `signIn.email`, `signIn.social`, password reset.
 
-export const store = configureStore({
-  reducer: {
-    auth: authReducer,
-    [openapi.reducerPath]: openapi.reducer,
-  },
-  middleware: (getDefault) =>
-    getDefault().concat(openapi.middleware, ...middleware),
-});
-``````
+The session store reads `getSession()` on start and then follows Better Auth's session atom,
+which fires after sign-in, sign-out, and user switches. A failed background read keeps the
+current session: a network blip is not a logout. `logout()` signs out of Better Auth, signs
+out syncdb clients (which wipe local data when created with `wipeOnSignOut`), runs the app's
+`onLogout`, and clears the session. This replaces the `@terreno/rtk` Better Auth Redux slice.
+See [syncdb reference: Auth](../reference/syncdb.md#auth).
+
+### Session State (JWT, legacy)
+
+JWT apps use the same `SessionProvider` / `useSession()` with a different session source.
+`jwtAuthAdapter({baseUrl})` returns one object that is both:
+
+- the `AuthProvider` for `createSyncDb` and `createApiClient` (bearer token, refresh before
+  expiry, refresh on 401), and
+- the `source` for `SessionProvider` (it pushes every sign-in and sign-out to the session).
+
+`useJwtAuth({adapter})` gives screens `login`, `signup`, `googleLogin`, `resetPassword`, and
+`logout`, plus `isAuthenticating` and `error`. `logout` goes through the `SessionProvider`, so
+syncdb clients sign out and `onLogout` runs. The signed-in user is the `id` claim of the stored
+token (`user` is `{id}`); load the profile from `/auth/me`. A refresh the server rejects signs
+the session out on its own. This replaces `@terreno/rtk`'s `generateAuthSlice` and Redux store.
+See [syncdb reference: JWT auth](../reference/syncdb.md#jwt-auth-legacy).
 
-**What this provides:**
-- Automatic token storage (SecureStore on mobile, AsyncStorage on web)
-- Token refresh middleware
-- Login/logout state management
-- Auth header injection for all API requests
+`getTokenExpirationTimes()` and `shouldShowStillThereModal()` read the stored tokens for
+"are you still there?" prompts (the modal shows with 65 seconds or less left on the refresh
+token).
 
 ### Token Storage
 
@@ -286,7 +304,8 @@ export const store = configureStore({
 - Falls back to localStorage
 - SSR-safe (checks `typeof window`)
 
-**Storage keys:**
+**Storage keys** (the same keys `@terreno/rtk` used, so signed-in users stay signed in after
+the move):
 - `AUTH_TOKEN` — Access token
 - `REFRESH_TOKEN` — Refresh token
 
@@ -368,7 +387,7 @@ address is the signal that lets the owner react. Status codes and messages are i
 - Use HTTPS in production
 - Validate token issuer (`TOKEN_ISSUER`)
 - Set appropriate token expiration times
-- Enable `TerrenoApp` `rateLimit` so login/signup/refresh use the stricter `auth` bucket (20 / 15 min). See [Rate limiting](../how-to/rate-limiting.md).
+- `TerrenoApp` rate limiting (on by default) puts login/signup/refresh in the stricter `auth` bucket (20 / 15 min). Keep it on and pass `trustProxy: 1` on Cloud Run. See [Rate limiting](../how-to/rate-limiting.md).
 - Keep login/signup/refresh reachable when the client still sends an expired access JWT. Those three routes skip JWT verification; `/auth/me` and other APIs still 401.
 - Log authentication failures
 
@@ -538,4 +557,4 @@ See [Receive inbound webhooks](../how-to/inbound-webhooks.md).
 - [Add GitHub OAuth](../how-to/add-github-oauth.md)
 - [Create a model](../how-to/create-a-model.md)
 - [API reference](../reference/api.md)
-- [@terreno/rtk reference (legacy)](../reference/legacy/rtk.md)
+- [Upgrade from @terreno/rtk to @terreno/syncdb](../how-to/migrate-rtk-to-syncdb.md)

package/src/docs/versioned/next/explanation/dependency-management.md

@@ -76,7 +76,7 @@ JavaScript packages, GitHub Actions, and a few Expo JS-only names may update. Me
 | `github-actions` | `github-actions` at `/` |
 | `root` | `bun` at `/` (root catalog and root tools) |
 | `backend` | `bun` under api, ai, backends, … |
-| `frontend` | `bun` under ui, rtk, demo, apps, … |
+| `frontend` | `bun` under ui, syncdb, admin-frontend, demo, apps, … |
 
 Frontend ignores catalog-managed names so those fixes land once, in the root catalog. Root ignores fingerprint-skip names, so a security fix for a native/Expo package never opens a PR; handle it by hand in a release. `dependabot-auto-merge.yml` approves patch and minor Dependabot PRs and enables squash auto-merge, so those security PRs merge when required checks pass. A semver-major security PR (or a group containing one) gets no approval or auto-merge and waits for a human. When one fails because the fix needs code changes, fold the bump into the rolling PR ([Update dependencies](../how-to/update-dependencies.md)); never push to the `dependabot/*` branch.
 

package/src/docs/versioned/next/explanation/deployment-baseline.md

@@ -32,7 +32,7 @@ Use [MongoDB Atlas](https://www.mongodb.com/atlas) or a single-node replica set
 
 **3 — Short-lived serverless timeouts**
 
-The RTK/socket client enables reconnection (`reconnection: true`, `reconnectionAttempts: 5` in `rtk/src/socket.ts`). When the backend drops idle connections (for example Cloud Run's default 300s request timeout), clients reconnect but realtime state may lag until the new socket attaches.
+The syncdb socket client enables reconnection (`reconnection: true` in `syncdb/src/sync/socketTransport.ts`). When the backend drops idle connections (for example Cloud Run's default 300s request timeout), clients reconnect and catch up from their sync cursors, but deltas may lag until the new socket attaches.
 
 **5 — Build-time API URL**
 

package/src/docs/versioned/next/explanation/example-coverage.md

@@ -19,8 +19,8 @@ that file (and its imports) to a working example. Gaps stay explicit.
 | UI blocks | yes — `uiBlocks` with `repair: true`, `exportDataset`, and the opt-in `scaleStepper` and `toggleChecklist` callbacks in `example-backend/src/ai/hostActions.ts`, wired from `example-backend/src/api/ai.ts`; `todoStats` in `example-backend/src/ai/tools.ts` stores a `ref` dataset; `findPhotos` in the same file cites the generated photo library, and `example-backend/src/api/photoLibrary.ts` signs its URLs | yes — `example-frontend/app/(tabs)/ai.tsx` (`uiBlocks`, dataset and action hooks, `hostActions` includes `exportDataset`, `scaleStepper`, and `toggleChecklist`, `resolveImage` resolves `file:` photo ids through `useLazyPhotoLibraryUrlQuery`) | e2e mocks a document with one inline and one `ref` chart. A second e2e test stores the Sunday roast reply (`blocks/src/fixtures/golden/sunday-roast.yaml` with `file:` photo ids) in a real `GptHistory`, streams it from the mocked model, and runs the stepper and checklist through the real `POST /gpt/actions`; photo URLs come from the real `GET /photoLibrary/:id/url`, and only the image download is stubbed (`example-frontend/e2e/helpers/seedGptHistory.ts`). Steps: [agent-ui-blocks.md](../how-to/agent-ui-blocks.md). |
 | Agent asks | yes — `asks: {approvals}` in `example-backend/src/api/ai.ts`, with the per-request `deleteCompletedTodos` approval tool from `example-backend/src/api/todoTools.ts`; it also passes `chat` to `addGptHistoryRoutes` for the headless `pendingAsks` and `turn` endpoints; keyless scripted agent with short compact-surface replies in `example-backend/src/api/demoAgent.ts` | yes — `example-frontend/app/(tabs)/ai.tsx` (`onAskSubmit`, `askErrors`), helpers in `example-frontend/lib/gptAsks.ts` | Without `GEMINI_API_KEY`, "Help me pick a plan" asks a `choice` in chat, "Pick toppings" asks a `select: "many"` `choice` with an Other field, "Send the weekly report" and "Archive old chats" ask a `confirm` (the second `destructive`), "Draft an announcement" asks a `markdown` edit of a draft, "Fill in the invoice details" asks a `form` with eight typed fields, "Upload a receipt" asks for `files`, sent as uploads when `GCS_BUCKET` is set and as data URLs otherwise, and "Delete my completed todos" calls `deleteCompletedTodos`, which runs only after the user approves the server's destructive approval card. e2e: `example-frontend/e2e/ai-chat.spec.ts`. Small clients: the curl walkthrough in the how-to and the demo's watch-sized `SimpleAskCard` story. Steps: [agent-ui-asks.md](../how-to/agent-ui-asks.md). |
 | AI structured output | no | no | `@terreno/ai` supports structured generation; the example only streams chat. Recorded gap — not claimed by a current tutorial. |
-| Feature flags + live updates | yes — `FeatureFlagsApp` in `example-backend/src/server.ts`, seed `example-backend/src/scripts/seed-feature-flags.ts` | yes — `useTerrenoFeatureFlags` in `example-frontend/app/_layout.tsx` | Socket-backed live updates share the realtime connection. |
-| Websockets / realtime | yes — `RealtimeApp` in `example-backend/src/server.ts`, `example-backend/src/websockets.ts` | yes — `useSocketConnection` in `example-frontend/app/_layout.tsx` | Sync deltas also use the socket (`SyncApp` + `@terreno/syncdb`). |
+| Feature flags + live updates | yes — `FeatureFlagsApp` in `example-backend/src/server.ts`, seed `example-backend/src/scripts/seed-feature-flags.ts` | yes — `useTerrenoFeatureFlags` (`@terreno/syncdb/flags`) in `example-frontend/app/_layout.tsx` | `featureFlagsChanged` pushes ride the syncdb socket; the app opens one socket. |
+| Websockets / realtime | yes — `RealtimeApp` in `example-backend/src/server.ts`, `example-backend/src/websockets.ts` | yes — the `syncDb` client socket (`example-frontend/store/syncdb.ts`) | Sync deltas and app events (`useSocketEvent`) share the one syncdb socket (`SyncApp` + `@terreno/syncdb`). |
 | Consent forms | yes — `example-backend/src/consentDefinitions.ts`, seed scripts | yes — `example-frontend/app/(tabs)/documents.tsx` (Consents section), admin `example-frontend/app/admin/consent-forms/` | First-login flow is covered by e2e (`example-frontend/e2e/consents.spec.ts`). |
 | Product announcements | yes — `AnnouncementsApp` in `example-backend/src/server.ts`, release upload token via `ANNOUNCEMENTS_UPLOAD_TOKEN`, seed `example-backend/src/scripts/seed-announcements.ts`, sample release pack `example-backend/announcements/releases/1.14.0/` with `bun run announcements:pack` | yes — `AnnouncementNavigator` in `example-frontend/app/_layout.tsx` and admin announcement routes | Seeded examples are drafts, so fresh databases do not interrupt sign-in. Release packs support multiple Markdown surfaces and idempotent draft or explicit live API import. |
 | What's new banner | n/a — generated from `CHANGELOG.md` by `bun run whats-new:generate` | yes — `WhatsNewBanner` in `example-frontend/components/SyncTodosScreen.tsx`, data in `example-frontend/constants/whatsNew.generated.json` | `bun run check:whats-new` keeps the data in sync with each release. |

package/src/docs/versioned/next/explanation/explicit-any-policy.md

@@ -15,8 +15,7 @@ Prefer `unknown` (and narrow) or a precise type. Use `as unknown as T` over `as
 Explicit `any` is acceptable only at **framework or library boundaries** where types are not expressible in TypeScript today, for example:
 
 - Mongoose model boundaries that inspect consumer-defined schemas (`api/src/populate.ts`)
-- RTK Query `Api<any, any, any, any>` in generic middleware (`rtk/src/offlineMiddleware.ts`)
-- Dynamic RTK hook lookup where endpoint names are not statically known (`admin-frontend`)
+- Dynamic lookups where member names are not statically known
 - Test mocks with type-erased doubles (`*.test.ts`, `*.isolated.tsx`)
 
 Every allowed use must be **lint-clean** and **documented** (see below).
@@ -38,15 +37,15 @@ The audit script (`bun run check:explicit-any`) classifies each explicit `any`:
 When `any` cannot be removed, add **both** comments on the line above (or a file header for tests):
 
 ```typescript
-// noExplicitAny: RTK Query generates hook names dynamically; not statically expressible
-// biome-ignore lint/suspicious/noExplicitAny: dynamic hook lookup on RTK Query enhanced API
-const hook = (api as any)[`useGet${name}Query`];
+// noExplicitAny: plugin methods are registered at runtime; names are not statically known
+// biome-ignore lint/suspicious/noExplicitAny: dynamic method lookup on a runtime-registered plugin
+const handler = (plugin as any)[`handle${name}`];
 ```
 
 For test files with many mocks, a file-level header is fine:
 
 ```typescript
-// noExplicitAny: test mocks use type-erased RTK Query API doubles
+// noExplicitAny: test mocks use type-erased request client doubles
 // biome-ignore-all lint/suspicious/noExplicitAny: test mock typing
 ```
 

package/src/docs/versioned/next/explanation/gcp-hosting-architecture.md

@@ -191,7 +191,7 @@ gs://bucket/
 
 ### Production Deploy
 
-1. **Trigger**: Push to `master` branch with changes to `demo/**`, `ui/**`, `example-frontend/**`, `rtk/**`
+1. **Trigger**: Push to `master` branch with changes to `demo/**`, `ui/**`, `example-frontend/**`, `syncdb/**`
 2. **Build**: GitHub Actions runs `bun run export` to generate static files
 3. **Ensure negative caching disabled**: Update backend bucket to prevent cached 404s
 4. **Upload**:

package/src/docs/versioned/next/explanation/local-first-data.md

@@ -1,6 +1,6 @@
 # Local-first data in Terreno
 
-Terreno's default frontend data path is **local-first**: the on-device store is what your UI reads and writes, and the server reconciles changes asynchronously. This is a different mental model from request/response fetching with RTK Query.
+Terreno's default frontend data path is **local-first**: the on-device store is what your UI reads and writes, and the server reconciles changes asynchronously. This is a different mental model from request/response fetching.
 
 ## What local-first means here
 
@@ -10,8 +10,8 @@ There is no server-first mode and no opt-in flag: if you use syncdb, you adopt t
 
 ## Mental model shift
 
-| Server-first (RTK Query) | Local-first (syncdb) |
-|--------------------------|----------------------|
+| Server-first (request/response) | Local-first (syncdb) |
+|---------------------------------|----------------------|
 | UI reads from cache filled by HTTP | UI reads from the local store |
 | Writes call the API, then invalidate/refetch | Writes apply locally, then reconcile |
 | Loading spinners track request lifecycle | Sync status tracks outbox + connectivity |
@@ -27,10 +27,12 @@ Think **apply locally, then reconcile** instead of **request, wait, update cache
 3. **Refetch orchestration** — `invalidatesTags`, `refetch()`, and list/detail cache coordination after mutations.
 4. **Treating the network as the read path** — list screens blocked on `isLoading` for every navigation.
 
-RTK Query remains appropriate for **non-synced generated** endpoints such as
-`/auth/me` and AI routes. Built-in admin RPC stays request/response through its
-host-bound fetch client; ObjectId/API-only admin CRUD keeps RTK compatibility in
-Terreno 57.
+Routes that are not collections — `/auth/me`, modelRouter actions, AI, consents —
+stay request/response. They go through the syncdb request client
+(`@terreno/syncdb/api`) and its generated hooks in `store/apiSdk.ts`, which share the
+sync client's `AuthProvider`. Built-in admin RPC and ObjectId/API-only admin CRUD use
+admin-frontend's host-bound fetch client. Terreno 58 removed `@terreno/rtk` and Redux;
+syncdb is the only frontend data layer.
 
 ## What you start doing
 
@@ -54,12 +56,12 @@ belong in `queryCollections` instead.
 
 **Gains:** instant UI, offline writes with a durable outbox, simpler screen code, and one write path on the server (sync and REST share `modelRouter`).
 
-**Costs:** larger conceptual surface (conflicts, sync status, local storage), mandatory replica-set MongoDB for realtime, and migration work for existing RTK Query screens.
+**Costs:** larger conceptual surface (conflicts, sync status, local storage), mandatory replica-set MongoDB for realtime, and migration work for screens that fetched collections over request/response.
 
 Server-first fetching is simpler when you only need online CRUD with no offline requirement — but Terreno's blessed path for collection data is local-first.
 
 ## Related docs
 
 - [syncdb reference](../reference/syncdb.md) — API ground truth
-- [Migrate from RTK to syncdb](../how-to/migrate-rtk-to-syncdb.md) — step-by-step migration
+- [Upgrade from @terreno/rtk to @terreno/syncdb](../how-to/migrate-rtk-to-syncdb.md) — the Terreno 58 upgrade path
 - [Authentication architecture](authentication.md) — Better Auth + socket sessions

package/src/docs/versioned/next/explanation/model-router-actions.md

@@ -128,7 +128,7 @@ Instance actions load the document by `id` before the handler runs. Missing docu
 When `openApi` is configured on the router (automatic with `TerrenoApp` and `setupServer`), each action is documented on first route registration. Operations use:
 
 - **Tag** — model collection name by default; override with `action.tag`.
-- **operationId** — `{tag}_{actionName}` (e.g. `todos_markComplete`) for stable RTK Query hook names after SDK regeneration.
+- **operationId** — `{tag}_{actionName}` (e.g. `todos_markComplete`) for stable generated hook names (`store/apiSdk.ts`) after SDK regeneration.
 
 Request/response schemas are derived from Zod when `body`, `query`, or `response` are set. Successful responses are documented as `{data: ...}` to match the wire format.
 

package/src/docs/versioned/next/explanation/modular-api-design.md

@@ -160,9 +160,9 @@ With TerrenoApp, an "app" is just a function that receives the `TerrenoApp` inst
 
 #### 6. One collection catalog for surfaces
 
-`modelRouter` registers each collection once in an in-memory **collection catalog** keyed by route path (for example `/todos`). The record holds the Mongoose model, `ModelRouterOptions`, and which surfaces are active (`mcp`, `realtime`, `sync`). TerrenoApp option enrichment calls `replaceCollectionOptions` once per path after RBAC injects `accessControl`.
+`modelRouter` registers each collection once in an in-memory **collection catalog** keyed by route path (for example `/todos`). The record holds the Mongoose model, `ModelRouterOptions`, and which surfaces are active (`mcp`, `sync`). TerrenoApp option enrichment calls `replaceCollectionOptions` once per path after RBAC injects `accessControl`.
 
-MCP, realtime, and sync read **views** of that catalog — they do not keep separate option arrays. `registerMCPModel`, `registerRealtime`, `registerSync`, and the `update*RegistryOptions` helpers remain as wrappers for tests and legacy callers. `clearMCPRegistry`, `clearRealtimeRegistry`, and `clearSyncRegistry` clear the **whole** catalog so tests cannot leave a stale MCP entry after a sync-only clear.
+MCP and sync read **views** of that catalog — they do not keep separate option arrays. `registerMCPModel`, `registerSync`, and the `update*RegistryOptions` helpers remain as wrappers for tests and legacy callers. `clearMCPRegistry` and `clearSyncRegistry` clear the **whole** catalog so tests cannot leave a stale MCP entry after a sync-only clear. The legacy realtime surface (`modelRouter` `realtime`, `registerRealtime`, `clearRealtimeRegistry`) was removed in Terreno 58.
 
 Custom MCP tools stay on a separate list; they are not collections. Sync schema validation and index enqueue still run when a collection first opts into `sync`.
 

package/src/docs/versioned/next/explanation/no-barrel-imports.md

@@ -10,7 +10,7 @@ Terreno avoids **barrel imports** — imports that resolve through an `index.ts`
 
 ## Allowed
 
-- **Published package APIs** — cross-package imports like `@terreno/api`, `@terreno/ui`, and `@terreno/rtk` use each package's public `src/index` entry. That is intentional.
+- **Published package APIs** — cross-package imports like `@terreno/api`, `@terreno/ui`, and `@terreno/syncdb/react` use each package's public entry (`src/index` or a declared subpath export). That is intentional.
 - **Package public entry files** — `api/src/index.ts`, `ui/src/index.tsx`, etc. may re-export for npm consumers. Do not import those barrels from *inside* the same package.
 - **Expo Router routes** — `app/**/index.tsx` files are route entries, not barrels.
 
@@ -29,12 +29,12 @@ import {User} from "../models/user";
 ```
 
 ```typescript
-// Bad — store/index.ts was a barrel of sdk/appState/utils
-import {useGetMeQuery} from "@/store";
+// Bad — a directory barrel
+import {useGetAuthMeQuery} from "@/store";
 
 // Good
-import {useGetMeQuery} from "@/store/sdk";
-import store, {useAppDispatch} from "@/store/index";
+import {useGetAuthMeQuery} from "@/store/apiSdk";
+import {syncDb} from "@/store/syncdb";
 ```
 
 ## Enforcement

package/src/docs/versioned/next/explanation/roadmap-seed-issues.md

@@ -554,7 +554,7 @@ org-admins manage only the current org. Invites and billing are design-only plac
 - **Implementation plan:** [org-management-ui.md](https://github.com/TerrenoLabs/terreno/blob/master/docs/implementationPlans/org-management-ui.md)
 - **Tasks:** [org-management-ui.md](https://github.com/TerrenoLabs/terreno/blob/master/docs/tasks/org-management-ui.md)
 - **RTK flag:** Partial — custom non-synced routes use the generated SDK;
-  ObjectId admin compatibility may use `useAdminApi` in Terreno 57, while
+  ObjectId admin CRUD uses the admin fetch client (`useAdminModelApi`), while
   eligible String-`_id` CRUD uses windowed syncdb
 - **Depends on:** rbac-permissions
 
@@ -871,9 +871,10 @@ Shipping this work **closes** https://github.com/TerrenoLabs/terreno/issues/1186
 **Labels:** `area:api`, `type:feature`
 **Project fields:** Area=`api`, Target=`Released`, Impact=`Feature`, IP=`rate-limiting`, Status=`Shipped`
 
-Adds opt-in HTTP rate limiting to `@terreno/api`: per-user or per-IP keys, stricter
+Adds HTTP rate limiting to `@terreno/api`: per-user or per-IP keys, stricter
 auth/OTP buckets (including login), memory Redis or Mongo stores, and 429 rate-limit
-headers. Default is off until Terreno 58. Sync mutation nacks stay a separate limiter.
+headers. Opt-in in 57.x; on by default from Terreno 58 (`rateLimit: false` turns it off).
+Sync mutation nacks stay a separate limiter.
 
 Shipping this work **closes** https://github.com/TerrenoLabs/terreno/issues/1187.
 

package/src/docs/versioned/next/explanation/source-rules.md

@@ -6,13 +6,13 @@ file (or a new hit in an existing file) that would trip them.
 
 ## Scope
 
-`{api,ui,rtk,ai,admin-backend,admin-frontend,example-backend}/src/**/*.{ts,tsx}`
+`{api,ui,ai,admin-backend,admin-frontend,example-backend}/src/**/*.{ts,tsx}`
 
 `example-frontend` and `demo` are listed in the original align glob but have no `src/`
 tree (`app/`, `components/`, `stories/` instead), so this scanner does not cover them.
 
 Skipped: tests (`*.test.*`, `*.spec.*`, `*.isolated.*`, `__tests__`), generated SDKs
-(`openApiSdk.ts`, `*OpenApiSdk.ts`), declaration files (`*.d.ts`), `node_modules`, `dist`,
+(`openApiSdk.ts`, `*OpenApiSdk.ts`, `*.gen.ts`), declaration files (`*.d.ts`), `node_modules`, `dist`,
 and test harness files such as `bunSetup.ts`.
 
 ## Rules

package/src/docs/versioned/next/explanation/typescript-configuration.md

@@ -10,7 +10,7 @@ TypeScript 7 removes.
 | --- | --- | --- | --- | --- |
 | Node library | `api`, `ai`, `admin-backend`, `announcements`, `api-health`, `blocks`, `comms`, `feature-flags`, `jobs`, `test`, `admin-spa` server (`tsconfig.server.json`) | `nodenext` | `es2023` | CommonJS `dist/` |
 | Node ESM tool | `mcp-server`, `create-terreno-app` | `nodenext` | `es2023` | ESM `dist/` (`"type": "module"`) |
-| Frontend library | `ui`, `admin-frontend`, `rtk`, `syncdb` | `esnext` + `moduleResolution: bundler` | `es2022` | ESM `dist/` for Metro |
+| Frontend library | `ui`, `admin-frontend`, `syncdb` | `esnext` + `moduleResolution: bundler` | `es2022` | ESM `dist/` for Metro |
 | Bun CLI | `cli` | `esnext` + `moduleResolution: bundler` + `customConditions: ["bun"]` | `es2022` | ESM `dist/` for Bun |
 | Expo app | `example-frontend`, `demo`, `admin-spa` | extends `expo/tsconfig.base` | from Expo | nothing (`noEmit`) |
 | Bun app | `example-backend` | `preserve` | `esnext` | nothing (`noEmit`) |
@@ -41,6 +41,4 @@ their `tsconfig.json`, so an `extends` into a repo-root base would ship a broken
 | `target: es5`, `downlevelIteration` | Deprecated. No supported runtime needs ES5 output. |
 | `esModuleInterop`, `allowSyntheticDefaultImports`, `forceConsistentCasingInFileNames` | Already `true` by default in TypeScript 6. Setting them to `false` is deprecated. |
 
-`create-terreno-app` scaffolds follow the Expo app and Bun app profiles. Its
-`tsconfig.codegen.json` pairs `module: commonjs` with `moduleResolution: bundler`, because
-the RTK codegen CLI forces CommonJS when it registers `ts-node`.
+`create-terreno-app` scaffolds follow the Expo app and Bun app profiles.

package/src/docs/versioned/next/explanation/versioning-policy.md

@@ -4,9 +4,9 @@ All published `@terreno/*` packages share one version. Upgrade them together. Mi
 
 ## Lockstep
 
-A git tag `X.Y.Z` (no `v` prefix) is the version for every package that `.github/workflows/publish-on-tag.yml` publishes: `api`, `test`, `ui`, `rtk`, `admin-backend`, `admin-frontend`, `admin-spa`, `blocks`, `ai`, `api-health`, `comms`, `feature-flags`, `mcp`, `syncdb`. Publish jobs read that tag; they do not pick per-package versions.
+A git tag `X.Y.Z` (no `v` prefix) is the version for every package that `.github/workflows/publish-on-tag.yml` publishes: `api`, `test`, `ui`, `admin-backend`, `admin-frontend`, `admin-spa`, `blocks`, `ai`, `api-health`, `comms`, `feature-flags`, `mcp`, `syncdb`. Publish jobs read that tag; they do not pick per-package versions.
 
-Inside the monorepo, packages depend on each other with `workspace:*` (for example `@terreno/rtk` → `@terreno/ui`). On npm they are released at the same number. `@terreno/ui` also pins Expo-line peers (`react-native` `~0.86.0` on the 57 line). Installing `@terreno/ui@57` next to Expo 54 is outside support, same as mixing `@terreno/api@57` with `@terreno/ui@0.31`.
+Inside the monorepo, packages depend on each other with `workspace:*` (for example `@terreno/admin-frontend` → `@terreno/ui`). On npm they are released at the same number. `@terreno/ui` also pins Expo-line peers (`react-native` `0.88.0` on the 58 line). Installing `@terreno/ui@58` next to Expo 57 is outside support, same as mixing `@terreno/api@58` with `@terreno/ui@57`.
 
 ## Pre-1.0 (and Expo-aligned majors)
 
@@ -18,7 +18,7 @@ From 56 onward the **major** tracks the Expo SDK major (`56.x`, `57.x`). That is
 
 A public API marked deprecated stays available for **at least three minor releases** on the current major (example: deprecated in `57.1.0` → still present in `57.2.0` and `57.3.0`). Removal happens in a later minor or the next major, always with an upgrade note.
 
-Worked example: `@terreno/rtk` collection CRUD was deprecated in `56.0.0` (restated in `57.1.0`). The package still publishes on 57.x for the OpenAPI SDK, Better Auth Redux, feature flags, and sockets. It will not ship in the **next major**. Migrate collection screens with [migrate-rtk-to-syncdb.md](../how-to/migrate-rtk-to-syncdb.md) as a separate operation from a routine version bump.
+Worked example: `@terreno/rtk` collection CRUD was deprecated in `56.0.0` (restated in `57.1.0`). The package published through 57.x and was removed in `58.0.0`, with `@terreno/syncdb` taking over its request client, session, flags, and app utilities. Upgrading across 58 follows [migrate-rtk-to-syncdb.md](../how-to/migrate-rtk-to-syncdb.md).
 
 ## Where to read changes
 

package/src/docs/versioned/next/how-to/README.md

@@ -22,7 +22,7 @@ Problem-oriented, practical steps. Use these when you know what you want to do.
 - [Run tests locally](run-tests-locally.md) — Map every CircleCI test job to a Cursor Cloud / laptop command
 - [GitHub Actions CI](github-actions-ci.md) — Cut PR runtime: docs previews, compile-once e2e, pinned Bun
 - [Add feature flags](add-feature-flags.md) — Add feature flags, A/B testing, and OpenFeature migration
-- [Rate limiting](rate-limiting.md) — Opt-in HTTP limiter on `TerrenoApp` (memory or Redis)
+- [Rate limiting](rate-limiting.md) — Default-on HTTP limiter on `TerrenoApp` (memory, Redis, or Mongo; `rateLimit: false` turns it off)
 - [Receive inbound webhooks](inbound-webhooks.md) — HMAC, Stripe, Twilio, and SendGrid signatures on `WebhooksApp`
 - [Durable background jobs](background-jobs.md) — `@terreno/jobs`: enqueue, workers, schedules, Cloud Tasks / Vercel Queues
 - [Create a Mongoose model](create-a-model.md) — Define models with proper conventions
@@ -59,9 +59,10 @@ Problem-oriented, practical steps. Use these when you know what you want to do.
 - [Show loading skeletons](show-loading-skeletons.md) — `loading`, `loadingComponent`, and `loadingAnimation` on Box, Card, charts, and Page; `withLoading` for custom components
 - [Compose charts in a dashboard grid](charts-and-dashboards.md) — `LineChart` / `BarChart` / `AreaChart` / `DonutChart` inside `Card`s in `DashboardGrid` (ops-dashboard scorecards and spans: [dashboard-chart-parity](../implementationPlans/dashboard-chart-parity.md))
 - [Compare rendered chart snapshots](compare-chart-rendered-snapshots.md) — PNG goldens for the chart visual gallery, not JSON snapshots
-- [Migrate from @terreno/rtk to @terreno/syncdb](migrate-rtk-to-syncdb.md) — Move data sync to the local-first layer
+- [Upgrade from @terreno/rtk to @terreno/syncdb (Terreno 58)](migrate-rtk-to-syncdb.md) — Remove `@terreno/rtk` and Redux; every removed export mapped to its replacement
 - [Use syncdb correctly](use-syncdb-correctly.md) — Serial snapshot startup, outbox-halting 403s, phantom creates, conflicts, and other library behavior apps must handle
 - [Generate a REST CLI from OpenAPI](generate-a-rest-cli.md) — Scaffold `terreno generate rest-cli` for an app API
+- [Generate the client SDK](generate-the-client-sdk.md) — `terreno-syncdb-codegen` writes collection hooks and typed request hooks from OpenAPI
 - [In-app notifications](in-app-notifications.md) — Register `NotificationsApp`, syncdb inbox, and UI bell
 - [Add organizations](add-organizations.md) — Opt into Membership-backed tenancy, RBAC, admin, and seeded examples
 - [Add a GPT chat mascot](add-gpt-chat-mascot.md) — Optional consumer-owned character on empty `GPTChat`