@terreno/mcp 57.20.0 → 58.0.0-beta.1

package/src/docs/versioned/next/explanation/planning-plugins.md

@@ -5,7 +5,7 @@ the lifecycle plugin knows *how to build one approved thing correctly*, and the
 plugin knows *what is worth building next and whether it worked*.
 
 ```text
-terreno-scan                            terreno (lifecycle)
+terreno-loop                            terreno (lifecycle)
 ------------                            -------------------
 Aim     charter a measurable goal
 Sweep   shard + map the repository
@@ -42,10 +42,26 @@ Five bounded transitions plus three outer loops. Canonical source:
 Full contract: [lifecycle plugin reference](../reference/lifecycle-plugin.md) and
 [loop engineering](loop-engineering.md).
 
-## terreno-scan (scan plugin)
-
-Five bounded transitions plus two outer loops. Canonical source: `plugins/terreno-scan/`;
-Claude Code consumes the generated `plugins/terreno-scan-claude/`. It depends on the
+Every IP also carries a testing plan: an `## E2E tests` table and a `## Regression
+cases` table, either of which may be `None — <reason>` but never missing. Grow plans the
+rows, Pick writes each spec in the task that delivers it, Roast runs them, Brew merges
+the manual cases into one living suite file per area under `docs/regression/`, and
+Taste keeps both current after review fixes. The point is that no bot decides alone
+whether a feature deserves an end-to-end test, and the checks a human repeats before a
+release live in a known file instead of in someone's head. See
+[Testing plan](../reference/lifecycle-plugin.md#testing-plan).
+
+Every IP also says which pages of the end-user guide it adds, updates, or retires. The
+guide is one plain-text page per feature, written in the words users see, so a chat agent
+can answer "how do I…" questions from it. Writing the page in the same task as the
+feature keeps it true; a guide written once at the end drifts from the app the first time
+a label changes. A repository with no end users opts out in its agent instructions. See
+[User guide](../reference/lifecycle-plugin.md#user-guide).
+
+## terreno-loop (scan plugin)
+
+Five bounded transitions plus two outer loops. Canonical source: `plugins/terreno-loop/`;
+Claude Code consumes the generated `plugins/terreno-loop-claude/`. It depends on the
 lifecycle plugin — Plot hands every slice to Grow.
 
 | Stage | Owns | PASS next |
@@ -78,6 +94,8 @@ Full contract: [scan plugin reference](../reference/scan-plugin.md).
 | Artifact | Owner | Committed |
 | --- | --- | --- |
 | IP and task list | Grow | yes |
+| Regression suites (`docs/regression/<area>.md`) | Brew, Taste | yes |
+| User guide (`docs/user-guide/<area>/<feature>.md`) | Pick, Taste | yes |
 | Execution state (`.terreno/pipeline/<slug>.json`) | Lifecycle outer loops | no |
 | Charter (`docs/scans/<goal>/charter.md`) | Aim | yes |
 | Findings report (`docs/scans/<goal>/round-<n>-findings.md`) | Sift | yes |
@@ -104,9 +122,9 @@ Three properties fall out of keeping discovery and delivery in separate plugins:
 
 | Host | Lifecycle | Scan |
 | --- | --- | --- |
-| Cursor | `terreno-planning`, `/terreno-1-grow` | `terreno-scan`, `/terreno-scan-1-aim` |
-| Codex | `terreno-planning`, `$terreno-1-grow` | `terreno-scan`, `$terreno-scan-1-aim` |
-| Claude Code | `terreno`, `/terreno:1-grow` | `terreno-scan`, `/terreno-scan:1-aim` |
+| Cursor | `terreno-planning`, `/terreno-1-grow` | `terreno-loop`, `/terreno-loop-1-aim` |
+| Codex | `terreno-planning`, `$terreno-1-grow` | `terreno-loop`, `$terreno-loop-1-aim` |
+| Claude Code | `terreno`, `/terreno:1-grow` | `terreno-loop`, `/terreno-loop:1-aim` |
 
 Install both from the marketplaces described in
 [install agent skills](../how-to/install-agent-skills.md). Claude Code resolves a plugin

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.
 
@@ -1342,6 +1343,42 @@ One easy-to-use harness inside `@terreno/ai` that runs long-lived agentic work d
 
 ---
 
+## e2e-and-regression-testing
+
+**Title:** `E2E tests and manual regression cases in every plan`
+
+**Labels:** `area:dx`, `type:feature`  
+**Project fields:** Area=`dx`, Target=`Next`, Impact=`Feature`, IP=`e2e-and-regression-testing`, Status=`In review`
+
+Today an implementation plan never says which end-to-end tests a feature needs, so bots decide alone whether a slice deserves a Playwright spec, and the manual checks a person should repeat before a release live in nobody's file. Most packages are tested only in-process.
+
+Every IP will carry `## E2E tests` and `## Regression cases` sections (either may be `None — <reason>`, neither may be missing). Grow plans the rows, Pick writes each spec with its feature, Roast runs them, Brew merges manual cases into one living suite per area under `docs/regression/`, and Taste keeps both current after fixes. Regression stays minimal: only what a developer or QA must check by hand, such as push notifications, real email delivery, or how the app feels. Terreno itself gains a real-process smoke test and an e2e guide page for every package, and brewery mirrors the contract.
+
+Out of scope: running manual cases automatically, and coverage targets.
+
+- **Implementation plan:** [e2e-and-regression-testing.md](https://github.com/TerrenoLabs/terreno/blob/master/docs/implementationPlans/e2e-and-regression-testing.md)
+- **Pull requests:** [#1628](https://github.com/TerrenoLabs/terreno/pull/1628), brewery [#15](https://github.com/joshgachnang/brewery/pull/15)
+
+---
+
+## lifecycle-user-guide
+
+**Title:** `An end-user guide that grows with every feature`
+
+**Labels:** `area:dx`, `type:feature`  
+**Project fields:** Area=`dx`, Target=`Next`, Impact=`Feature`, IP=`lifecycle-user-guide`, Status=`Shaping`
+
+Chat agents cannot answer "how do I…" questions about an app today, because no text describes its features in the words users see, and a guide written once drifts from the app the first time a label changes.
+
+Every IP will gain a `## User guide` section, and the task that ships a feature writes its page: one plain-text file per feature under `docs/user-guide/<area>/<feature>.md`, with `audience`, `platforms`, and the `questions` users would ask in its frontmatter, then what it does, how to use it, and what it is meant for. Roast checks the steps against the shipped screens, and Brew gates on the page. A repository with no end users opts out with `User guide: none`. A `backfill-user-guide` skill drafts pages for features that already shipped, for a human to approve.
+
+Open for discussion: how this relates to the support agent's `support/kb/` docs (one corpus or two), whether pages ship in the app or are served by the backend, and who reviews the wording.
+
+- **Implementation plan:** [lifecycle-user-guide.md](https://github.com/TerrenoLabs/terreno/blob/master/docs/implementationPlans/lifecycle-user-guide.md)
+- **Pull request:** [#1633](https://github.com/TerrenoLabs/terreno/pull/1633)
+
+---
+
 ## list-detail-layout
 
 **Title:** `ListDetailLayout: a route-driven list/detail layout for phone and tablet`
@@ -1353,6 +1390,17 @@ One easy-to-use harness inside `@terreno/ai` that runs long-lived agentic work d
 
 ---
 
+## e2e-and-regression-testing
+
+**Title:** `E2E tests and manual regression cases in every plan`
+
+**Labels:** `area:tooling`, `type:feature`  
+**Project fields:** Area=`tooling`, Target=`Next`, Impact=`Feature`, IP=`e2e-and-regression-testing`, Status=`Planned`
+
+- **Implementation plan:** [e2e-and-regression-testing.md](https://github.com/TerrenoLabs/terreno/blob/master/docs/implementationPlans/e2e-and-regression-testing.md)
+
+---
+
 # Shipped, umbrella, and declined IPs
 
 Tracking issues created for IPs that previously lacked a `**Roadmap issue:**` header.

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
@@ -41,6 +41,8 @@ Problem-oriented, practical steps. Use these when you know what you want to do.
 - [Debug with MCP](debug-with-mcp.md) — Follow a failure from symptom to verified fix with the local MCP tools
 - [Connect an MCP client with a service token](connect-mcp-service-token.md) — Mint a personal `mcp_` key for Perplexity and other remote clients
 - [Enable MCP OAuth for a JWT app](enable-mcp-oauth.md) — Let Claude.ai and ChatGPT connect to `/mcp` through OAuth 2.1 with your own consent screen
+- [Manage MCP from the admin panel](manage-mcp-in-admin.md) — Service tokens, OAuth clients and connections, request log, tool on/off switches, and sign-out-everywhere
+- [Expose an MCP server safely](expose-mcp-server-safely.md) — Put `/mcp` on the internet with OAuth, service tokens, a named Cloudflare Tunnel, and Access on the console
 - [Install agent skills](install-agent-skills.md) — `npx skills`, the Cursor plugin, the Codex plugin, or the Claude Code plugin
 - [Develop an AI feature](ai-feature-development.md) — Dataset → prompt → evaluators → experiment → production label → live traces (SOP)
 - [Observe LLM calls](observe-llm-calls.md) — Register ObservabilityApp, primaries, price map, sampleRate
@@ -57,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`

package/src/docs/versioned/next/how-to/add-feature-flags.md

@@ -54,49 +54,66 @@ After adding the backend routes, regenerate the SDK so the frontend can call the
 cd your-frontend && bun run sdk
 ```
 
-Regeneration may emit a hook for `/feature-flags/flagConfiguration`; prefer **`useTerrenoFeatureFlags`** / **`useFeatureFlags`** from `@terreno/rtk` so OpenFeature domain, cache keying, and optional socket refetch stay consistent.
+Regeneration may emit a hook for `/feature-flags/flagConfiguration`; prefer **`useTerrenoFeatureFlags`** / **`useFeatureFlags`** from `@terreno/syncdb/flags` so the OpenFeature domain, per-user refetch, and socket refresh stay consistent.
 
 ### 4. Use feature flags in the frontend
 
-**Recommended (OpenFeature):** add `@openfeature/react-sdk` to the app, wrap the tree (or the subtree that reads flags) in `<OpenFeatureProvider domain="feature-flags">`, and call `useTerrenoFeatureFlags(terrenoApi, {userId, socket})` once after auth so the OpenFeature client receives `GET /feature-flags/flagConfiguration`. Then use standard hooks such as `useBooleanFlagValue` / `useStringFlagValue` / `FeatureFlag`.
+Add `@openfeature/web-sdk` and `@openfeature/react-sdk` to the app (`catalog:` versions). Both
+hooks come from `@terreno/syncdb/flags`, fetch through the request client from
+`ApiClientProvider`, and refetch when the server pushes `featureFlagsChanged` on the syncdb
+socket.
 
-**Back-compat:** `useFeatureFlags(terrenoApi)` from `@terreno/rtk` still returns `{flags, getFlag, getVariant, isLoading, …}` with the same semantics as before; it uses `/flagConfiguration` under the hood. You do not need to call a generated RTK hook for `/flagConfiguration` directly.
+**Recommended (OpenFeature):** wrap the tree that reads flags in
+`<OpenFeatureProvider domain="feature-flags">` and call `useTerrenoFeatureFlags` once after
+auth. Pass your `syncDb` as `socket` when this component sits above `SyncDbProvider`. Then read
+values with `useBooleanFlagValue` / `useStringFlagValue` / `FeatureFlag`.
+
+```typescript
+import {OpenFeatureProvider} from "@openfeature/react-sdk";
+import {useTerrenoFeatureFlags} from "@terreno/syncdb/flags";
+import {syncDb} from "@/store/syncdb";
+
+const FlagsBridge: React.FC<{children: React.ReactNode; userId?: string}> = ({
+  children,
+  userId,
+}) => {
+  useTerrenoFeatureFlags({skip: !userId, socket: syncDb, userId});
+  return <OpenFeatureProvider domain="feature-flags">{children}</OpenFeatureProvider>;
+};
+```
 
 ```typescript
 import {useBooleanFlagValue} from "@openfeature/react-sdk";
-import {useTerrenoFeatureFlags, useSelectCurrentUserId} from "@terreno/rtk";
-import {terrenoApi} from "@/store/sdk";
 
 const GatedBanner: React.FC = () => {
-  const userId = useSelectCurrentUserId();
-  useTerrenoFeatureFlags(terrenoApi, {userId, skip: !userId});
   const showBanner = useBooleanFlagValue("new-ui", false);
   return showBanner ? <NewUI /> : null;
 };
 ```
 
+**Flat accessors:** `useFeatureFlags` returns `{flags, getFlag, getVariant, isLoading, error,
+refetch}`. Screens below the bridge can pass `socket: null` — they share the bridge's cached
+query, so its refetch updates them too.
+
 ```typescript
-import {useFeatureFlags} from "@terreno/rtk";
-import {terrenoApi} from "@/store/sdk";
+import {useFeatureFlags} from "@terreno/syncdb/flags";
 
-const LegacyStyle: React.FC = () => {
-  const {getFlag, isLoading} = useFeatureFlags(terrenoApi);
+const LegacyStyle: React.FC<{userId?: string}> = ({userId}) => {
+  const {getFlag, isLoading} = useFeatureFlags({skip: !userId, socket: null, userId});
 
   if (isLoading) {
     return <Spinner />;
   }
 
-  const showNewUI = getFlag("new-ui");
-
-  return showNewUI ? <NewUI /> : <OldUI />;
+  return getFlag("new-ui") ? <NewUI /> : <OldUI />;
 };
 ```
 
 ### 4b. Live updates (optional)
 
-To push flag changes to open clients without a refresh, pass **`liveUpdates`** when constructing `FeatureFlagsApp` (see `example-backend/src/server.ts`): Mongoose **`FeatureFlag.watch()`** drives a Socket.io broadcast. **MongoDB must run as a replica set** (a single-node replica set is enough); standalone instances cannot use change streams, and the plugin logs a warning if `watch()` fails.
+To push flag changes to open clients without a refresh, pass **`liveUpdates`** when constructing `FeatureFlagsApp` (see `example-backend/src/server.ts`): Mongoose **`FeatureFlag.watch()`** drives a Socket.io broadcast. Point `socketIoServer` at `() => realtimeApp.getIo()` so the push goes out on the socket the syncdb client already holds. **MongoDB must run as a replica set** (a single-node replica set is enough); standalone instances cannot use change streams, and the plugin logs a warning if `watch()` fails.
 
-On the client, pass the same Socket.io **client** into `useTerrenoFeatureFlags` / `useFeatureFlags` as `socket`; the hook listens for `featureFlagsChanged` (or `socketEventName`) and refetches `/flagConfiguration`. The event payload is only `{ key: string }` — the same flag keys are already returned to every authenticated user in `/flagConfiguration`, so this is not considered a new exposure.
+On the client there is nothing extra to wire: `useTerrenoFeatureFlags` listens for `featureFlagsChanged` (or `socketEventName`) through `syncDb.onSocketEvent` and refetches `/flagConfiguration`. The app opens no second socket. The event payload is only `{ key: string }` — the same flag keys are already returned to every authenticated user in `/flagConfiguration`, so this is not considered a new exposure.
 
 ### 5. Create flags via the admin panel
 
@@ -111,23 +128,31 @@ Navigate to the admin panel in your app. The "Feature Flags" card appears automa
 
 ## Migrating from `GET …/evaluate` (OpenFeature)
 
-Terreno's feature-flag stack uses **OpenFeature** (`@terreno/feature-flags` on the server, `@terreno/rtk` on the client). Use this checklist if you upgrade from a Terreno release that only documented `GET …/evaluate`.
+Terreno's feature-flag stack uses **OpenFeature** (`@terreno/feature-flags` on the server, `@terreno/syncdb/flags` on the client). Use this checklist if you upgrade from a Terreno release that only documented `GET …/evaluate`.
 
 ### Backend (`@terreno/feature-flags`)
 
 1. Keep **`FeatureFlagsApp`** registered as before; admin CRUD is unchanged.
 2. Prefer authenticated clients calling **`GET {basePath}/flagConfiguration`** — the JSON body matches OpenFeature's static configuration shape (for `TypedInMemoryProvider` on the client).
-3. **`GET {basePath}/evaluate`** still returns the legacy `Record<key, boolean | string | null>` map but is **deprecated** (`Deprecation: true`, `Sunset` header). Migrate direct HTTP or hand-written clients to `/flagConfiguration`, or rely on `@terreno/rtk` hooks below.
+3. **`GET {basePath}/evaluate`** still returns the legacy `Record<key, boolean | string | null>` map but is **deprecated** (`Deprecation: true`, `Sunset` header). Migrate direct HTTP or hand-written clients to `/flagConfiguration`, or rely on the `@terreno/syncdb/flags` hooks below.
 4. **`FeatureFlag`** documents gain optional **`defaultVariant`** (boolean: `"on"` / `"off"`; variant: a key from `variants`). Omitted values are filled on save. For existing databases, run a one-off backfill or reuse the pattern in `example-backend/src/scripts/seed-feature-flags.ts`.
 5. **Live updates (optional):** pass `liveUpdates: { socketIoServer: io | () => io }` to `FeatureFlagsApp`. MongoDB must run as a **replica set** (a single-node replica set is enough) so Mongoose change streams work.
 
-### Frontend (`@terreno/rtk` + OpenFeature)
-
-1. **`useFeatureFlags(terrenoApi, …)`** — no code changes required for the common case; it already uses `/flagConfiguration` and keeps `{ flags, getFlag, getVariant, isLoading, refetch }`.
-2. **OpenFeature React hooks** (`useBooleanFlagValue`, `useStringFlagValue`, `<FeatureFlag>`, …): add **`@openfeature/react-sdk`** and **`@openfeature/web-sdk`** to your app (align versions with `@terreno/rtk` **peerDependencies** and the root **`catalog`**).
-3. Wrap the UI that reads flags in **`<OpenFeatureProvider domain="feature-flags">`** (or the same `domain` you pass into the hook).
-4. After auth, call **`useTerrenoFeatureFlags(terrenoApi, { userId, skip, socket, … })`** once under your Redux `Provider` so OpenFeature is populated before hooks read flag values.
-5. **Regenerate the OpenAPI SDK** after the backend exposes the new route: `cd your-frontend && bun run sdk`. Prefer **`useTerrenoFeatureFlags` / `useFeatureFlags`** over calling a generated `flagConfiguration` hook directly, so domain, cache keys, and optional socket refetch stay consistent.
+### Frontend (`@terreno/syncdb/flags` + OpenFeature)
+
+1. Replace the Terreno 57 `useFeatureFlags(terrenoApi, options)` with
+   `useFeatureFlags(options)` from `@terreno/syncdb/flags`. The result shape is unchanged:
+   `{flags, getFlag, getVariant, isLoading, error, refetch}`. The legacy string `basePath`
+   argument is gone; pass `{basePath}`.
+2. Replace `useTerrenoFeatureFlags(terrenoApi, {socket, ...})` with
+   `useTerrenoFeatureFlags({socket: syncDb, ...})`. `socket` is now your `SyncDb` client, not a
+   Socket.io client, and defaults to the `SyncDbProvider` client.
+3. Drop `useSocketConnection` and `useRealtimeDebug`. Listen for other server events with
+   `useSocketEvent` from `@terreno/syncdb/react` (see
+   [WebSocket integration](./websocket-integration.md)).
+4. Keep `@openfeature/web-sdk` and `@openfeature/react-sdk` in the app (`catalog:` versions) and
+   wrap the UI that reads flags in `<OpenFeatureProvider domain="feature-flags">`.
+5. Mount the hooks under `ApiClientProvider`, or pass `client`.
 
 ### Further reading
 

package/src/docs/versioned/next/how-to/add-organizations.md

@@ -173,7 +173,8 @@ exactly one administered organization may omit it; Terreno infers that org.
 Operators and superadmins must select an org.
 
 Frontend admin hosts use `OrgContextProvider` + `OrgSwitcher`.
-`useAdminApi` adds the selected organization header automatically.
+`useAdminModelApi` and the built-in admin screens add the selected organization
+header automatically.
 
 Disabled organizations are excluded from `/orgs/mine` and cannot be selected as
 tenant context. Operators re-enable them from the organization directory UI or

package/src/docs/versioned/next/how-to/admin-custom-home.md

@@ -25,8 +25,14 @@ Built-in IDs include `modelStats`, `modelsGrid`, `scriptRunner`, `versionConfig`
 For an app-specific widget, implement `AdminHomeWidgetProps` and register it:
 
 ```tsx
-<AdminProvider widgets={{home: {operationsSummary: OperationsSummary}}} api={api}>
-  <AdminHome api={api} />
+<AdminProvider
+  apiBase="/admin"
+  apiOrigin={baseUrl}
+  getAuthHeaders={getAdminAuthHeaders}
+  routeBase="/admin"
+  widgets={{home: {operationsSummary: OperationsSummary}}}
+>
+  <AdminHome />
 </AdminProvider>
 ```
 

package/src/docs/versioned/next/how-to/admin-custom-widget.md

@@ -33,7 +33,6 @@ const RichTextWidget: React.FC<AdminFieldWidgetProps> = ({
 
 ```tsx
 <AdminProvider
-  api={api}
   apiBase="/admin"
   routeBase="/admin"
   widgets={{fields: {"rich-text": RichTextWidget}}}

package/src/docs/versioned/next/how-to/agent-ui-asks.md

@@ -248,9 +248,9 @@ use uploads, or lower the per-file cap with `asks: {maxFileSizeBytes: 5_000_000}
    <GPTChat resolveAskFiles={resolveAskFiles} {...chatProps} />;
    ```
 
-   `postFilesUpload` is an RTK Query mutation in `example-frontend/store/sdk.ts` whose body is a
-   `FormData` with a `file` part; the base query sends it with the session token. The generated
-   SDK has no file endpoints, because `/files/*` exists only on a server with a bucket.
+   `usePostFilesUploadMutation` is a generated hook in `example-frontend/store/apiSdk.ts` whose
+   body is a `FormData` with a `file` part; the request client sends it with the session token.
+   `/files/*` exists only on a server with a bucket.
    `createAskFileUploader` (in `gptAsks.ts`) returns `undefined` on 404, the upload's `id` and
    `size` on success, and throws with the server's detail otherwise (such as 401 when the session
    has ended), so the ask stays open. See `example-frontend/app/(tabs)/ai.tsx`.
@@ -297,9 +297,9 @@ answer as two rows, and ratings are sent by message index.
 
 A turn can stream only `{done}`, for example when the server cancels a second ask because one is
 already pending. Reload the conversation with `GET /gpt/histories/:id` when a turn streamed nothing
-visible, or when `done.pendingAsk` names an ask the stream did not send. The `@terreno/rtk` base
-query returns the `data` of single-document responses, so an RTK query for that route resolves to
-the history itself, not `{data}` (see [emptyApi](../reference/legacy/rtk.md#emptyapi--emptysplitapi)).
+visible, or when `done.pendingAsk` names an ask the stream did not send. The `@terreno/syncdb/api`
+request client unwraps the `data` of single-document responses, so `apiClient.request` for that
+route resolves to the history itself, not `{data}` (see [API client](../reference/syncdb.md#api-client)).
 
 Refetch the history list after a turn that streams ask events or reloads the conversation. The
 example app reopens a conversation from the list's cached rows, which still hold the pending ask.

package/src/docs/versioned/next/how-to/build-admin-screens.md

@@ -25,7 +25,6 @@ Embedded app (`example-frontend`):
 const syncConflicts = useConflicts();
 
 <AdminProvider
-  api={api}
   apiBase="/admin"
   apiOrigin={baseUrl}
   getAuthHeaders={getAdminAuthHeaders}
@@ -35,7 +34,6 @@ const syncConflicts = useConflicts();
   widgets={{screens: {"sync-lab": SyncLabScreen}}}
 >
   <AdminShellLayout
-    api={api}
     apiBase="/admin"
     configurationPath="/admin/configuration"
     rolesPath="/roles"
@@ -53,8 +51,8 @@ store name and `windowCollections` set; do not mix admin rows into the owner/ten
 product store. Start that client after `canOpenAdminPage` succeeds, block the admin
 shell until `start()` resolves, and call `stop()` when the admin layout unmounts.
 
-Gate entry with `canOpenAdminPage` from `@terreno/rtk` (`admin:access`). Do not
-rely on `user.admin` alone when RBAC is on. Import `baseUrl` from `@terreno/rtk`
+Gate entry with `canOpenAdminPage` from `@terreno/syncdb/app` (`admin:access`). Do not
+rely on `user.admin` alone when RBAC is on. Import `baseUrl` from `@terreno/syncdb/config`
 and pass it as `apiOrigin` so admin RPC (`GET /admin/config`, `/rbac/roles`, …)
 hits the API instead of the Expo web origin.
 
@@ -123,11 +121,15 @@ for those paths. Otherwise `[model]/[id]` treats the id as a generic document.
 
 ## 5. Fetch data the admin way
 
+- Every admin request goes through the `AdminProvider` fetch client. Admin
+  components take no `api` prop.
 - String-`_id` collections configured with `adminBroadcast` use windowed syncdb
-  when the host passes `syncDb` plus fetch auth.
-- ObjectId model CRUD and API-only hosts keep `useAdminApi`.
-- Bulk patch remains server-side: native admin fetch for windowed hosts, RTK fallback otherwise.
-- Admin RPC uses the host-bound native fetch client. Do not add axios.
+  when the host passes `syncDb`.
+- ObjectId and API-only models use fetch CRUD. Custom screens call
+  `useAdminModelApi(routePath, modelName)` for list/read/create/update/delete.
+- Bulk patch stays server-side at `{routePath}/bulk-patch` for every model.
+- Custom admin RPC uses `useAdminRpc` + `useAdminRpcQuery` / `useAdminRpcMutation`.
+  Do not add axios or a second request client.
 
 ## 6. Sidebar and grouping
 

package/src/docs/versioned/next/how-to/build-for-web.md

@@ -26,7 +26,7 @@ bun expo export --platform web
 
 ### Alternative: `app.json` `extra.BASE_URL`
 
-`@terreno/rtk` resolves the API base from `expo-constants` `extra.BASE_URL` and `EXPO_PUBLIC_API_URL` (see `rtk/src/constants.ts` `resolveBaseUrls`). Priority in **production** builds:
+`@terreno/syncdb/config` resolves the API base from `expo-constants` `extra.BASE_URL` and `EXPO_PUBLIC_API_URL` (see `syncdb/src/config/resolveBaseUrls.ts`). Priority in **production** builds:
 
 1. `EXPO_PUBLIC_API_URL` environment variable (set before export)
 2. `extra.BASE_URL` in app config (when env var is unset)

package/src/docs/versioned/next/how-to/call-external-apis.md

@@ -10,7 +10,7 @@ How to talk to third-party HTTP APIs (payment processors, health integrations, m
 | Calling an external service through its own SDK (Twilio, Google APIs, Stripe) | `withApiErrorHandling` around the SDK calls — the SDK owns transport, you standardize failures |
 | Logging or classifying a caught error from any external call | `normalizeApiError` |
 | Surfacing an external failure to your API's consumers from a route handler | `withApiErrorHandling` with `rethrowAs: "apiError"` |
-| Making internal requests to your own `@terreno/api` backend | None of these — use `@terreno/rtk` on the frontend or direct function calls on the backend |
+| Making internal requests to your own `@terreno/api` backend | None of these — use the generated `store/apiSdk.ts` hooks (`@terreno/syncdb/api` request client) or syncdb collection hooks on the frontend, or direct function calls on the backend |
 
 **Rule of thumb:** any file that would otherwise contain `axios.create(...)` plus a token variable plus a `try/catch → axios.isAxiosError → log → throw` block should use these utilities instead.
 
@@ -92,7 +92,7 @@ Note the hook's output classification also feeds the client's retry decision —
 
 ## When not to use this
 
-- **Your own backend's routes** — use the generated `@terreno/rtk` SDK (frontend) or call the function directly (backend).
+- **Your own backend's routes** — use syncdb collection hooks or the generated `store/apiSdk.ts` hooks (frontend) or call the function directly (backend).
 - **SDK-managed transport** (Twilio, googleapis) — don't fight the SDK's HTTP layer; adopt only `normalizeApiError`/`withApiErrorHandling` for consistent failure handling.
 - **Webhook notifiers** — `sendToSlack`/`sendToGoogleChat`/`sendToZoom` post to a fixed webhook. Slack channel creation, invites, and bot posts use `createSlackPrivateChannel`, `inviteSlackUsersToChannel`, and `postSlackMessage` with `SLACK_BOT_TOKEN`. See [Webhooks & Notifications](../reference/api.md#webhooks--notifications).
 

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

@@ -47,6 +47,13 @@ list pipelines on the slug above.
 | `.circleci/config.yml` | Setup workflow + `path-filtering` (this is the live config) |
 | `.circleci/continue-config.yml` | Real jobs/workflows gated by those params |
 
+## Bun version is pinned
+
+`install_bun_and_deps` pins Bun with `node/install-bun` `version`. Bun 1.4.4 reports
+lower line coverage than 1.4.2 for the same tests, which fails the 95% package
+coverage gates. Bump the pin together with the local toolchain and re-run
+`bun run test:coverage` in each package first.
+
 ## Bun install is uncached
 
 `install_bun_and_deps` runs `bun install --frozen-lockfile` with
@@ -87,8 +94,8 @@ The example-backend Docker job runs only when its image recipe changes
 (`Dockerfile`, `.dockerignore`, package manifests, or `bun.lock`). API/source
 changes are covered by preview CD builds and do not start a duplicate image job.
 
-UI, RTK, and admin-frontend changes do **not** start `example-backend-ci`.
-Those packages are covered by `ui-ci` / `rtk-ci` / `packages-ci` plus e2e and
+UI, syncdb, and admin-frontend changes do **not** start `example-backend-ci`.
+Those packages are covered by `ui-ci` / `syncdb-ci` / `packages-ci` plus e2e and
 admin-spa. `new-file-coverage` starts on package `src/` (and example app
 runtime paths including `example-frontend/components/`), not on every `*.ts`
 file in the repo (Playwright specs no longer compile the world). Package CI
@@ -112,7 +119,8 @@ which builds its own web bundle and backend (`playwright.config.ts` with
 policy checks share one `repo-policies` job so eight small checkouts do not
 sit in the concurrency queue. `repo-policies` uses Node 22.14 because Knip's
 oxc-parser throws `ERR_REQUIRE_ESM` on the shared 22.11 executor.
-Require `repo-policies` in branch protection. Require `e2e-auth` /
+The `typecheck` job runs in the same workflow: it compiles every package, then
+runs `bun run typecheck`. Require `repo-policies` and `typecheck` in branch protection. Require `e2e-auth` /
 `e2e-app` / … only as path-filtered checks; config-only PRs post `e2e-auth`
 as the smoke shard and do not run the other four. Do not require the old
 `no-barrel-imports` / `e2e-login` names.
@@ -168,13 +176,13 @@ non-PR branch builds.
 | Path (examples) | Parameter | PR job | `master` job |
 | --- | --- | --- | --- |
 | `demo/**`, `ui/**` | `run-deploy-demo` | `deploy-demo-preview` | `deploy-demo` |
-| `example-frontend/**`, `admin-frontend/**`, `rtk/**`, `ui/**`, `ai/**`, `blocks/**`, `syncdb/**`, `bun.lock` | `run-deploy-frontend` | `deploy-frontend-preview` | `deploy-frontend` |
+| `example-frontend/**`, `admin-frontend/**`, `ui/**`, `ai/**`, `blocks/**`, `syncdb/**`, `bun.lock` | `run-deploy-frontend` | `deploy-frontend-preview` | `deploy-frontend` |
 | `docs/**`, `website/**` | `run-deploy-docs` | `deploy-docs-preview` | `deploy-docs` |
 | `example-backend/**`, `api/**`, `comms/**`, `jobs/**`, `admin-spa/**`, `feature-flags/**`, `announcements/**`, plus every frontend path above | `run-cd-backend` | `gcp-cd-preview` | `gcp-cd-prod` |
 | `terraform/**`, `infra/**` | `run-cd-terraform` | `gcp-cd-preview` | `gcp-cd-prod` |
 | `mcp-server/**`, `ui/**` | `run-cd-mcp` | _(none)_ | `gcp-cd-prod` (runs `mcp-server` `test:ci` first) |
 
-The backend image bundles the admin SPA (ui, rtk, admin-frontend, syncdb), so
+The backend image bundles the admin SPA (ui, admin-frontend, syncdb), so
 those paths redeploy the backend too. Every frontend PR preview therefore gets
 an isolated `pr-N` backend: `deploy-frontend-preview` always points
 `EXPO_PUBLIC_API_URL` at it (the prod backend rejects preview CORS) and waits
@@ -282,7 +290,7 @@ ambient OIDC token for GCP impersonation.
 Branch protection must require the CircleCI job names below. Remove disabled
 GitHub check names or pull requests will wait for checks that can no longer run.
 
-Dedicated package jobs (`api-ci`, `ai-ci`, `blocks-ci`, `rtk-ci`, `ui-ci`, `syncdb-ci`,
+Dedicated package jobs (`api-ci`, `ai-ci`, `blocks-ci`, `ui-ci`, `syncdb-ci`,
 `comms-ci`, `mcp-server-ci`, `admin-spa-ci`) run `bun run test:coverage`
 (`scripts/check-coverage.ts`, 95% functions and lines). Isolated `syncdb` tests
 are included by that script. Published packages without a dedicated workflow
@@ -296,6 +304,7 @@ the same commands through the parameterized `packages-ci` job, gated by
 |----------------------------|--------------|
 | Repository policies (barrels, source rules, explicit any, licenses, changelog, parity, lifecycle, static analysis) | `repo-policies` |
 | Verify rules are in sync | `rulesync-check` |
+| (none) — every package's `typecheck` (src + tests) | `typecheck` (runs with `run-repo-policies`) |
 | `dco` | `dco` |
 | (none) | `approve` |
 | Run all tests (API CI) | `api-ci` |
@@ -303,7 +312,6 @@ the same commands through the parameterized `packages-ci` job, gated by
 | Admin frontend lint, compile, coverage | `packages-ci` (`admin-frontend`) |
 | Run all tests (AI CI) | `ai-ci` |
 | Lint, compile, and test blocks | `blocks-ci` |
-| RTK Lint and Build | `rtk-ci` |
 | Syncdb Lint, Build, and Tests | `syncdb-ci` |
 | UI Lint, Build, Types, and Tests + demo typecheck | `ui-ci` |
 | Demo Lint and TypeScript Check | `ui-demo-ci` (demo-only PRs) |
@@ -316,6 +324,7 @@ the same commands through the parameterized `packages-ci` job, gated by
 | Run admin script CLI (when backend CI did not already run) | `example-backend-script-runner` |
 | Build backend Docker image | `example-backend-docker` |
 | Admin SPA Build and E2E | `admin-spa-ci` |
+| (none) | `smoke` (every workspace `smoke` script; any package change) |
 | Lint, compile, and coverage (matrix package) | `packages-ci` (`admin-backend`, `admin-frontend`, `api-health`, `feature-flags`, `test`) |
 | E2E · `<shard>` | `e2e` (matrix `shard`: `auth`, `app`, `admin-core`, `admin-table`, `syncdb`) |
 | _(cross-site bearer specs, not required)_ | `e2e-cross-site` (after `e2e-prepare`; also the explicit-linking pass) |