@terreno/mcp 57.21.0 → 58.0.0-beta.2

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

@@ -282,6 +282,28 @@ per-file, per-rule counts so CI fails only on new violations. Suppress one line
 `test-hygiene-disable-next-line <rule>[, <rule>]` comment. Exit codes: 0 clean, 1 new
 violations, 2 usage error.
 
+### Documented-response checks (`@terreno/api/testing`)
+
+`expectDocumentedResponse({spec, path, method, response})` validates a real response body
+against the schema `/openapi.json` documents for that path, method, and status (AJV, with
+`#/components/...` refs and `nullable` resolved). It throws listing every violation, or when
+the route, status, or media type is not documented. `validateDocumentedResponse` returns
+`{valid, errors}` instead of throwing. `path` is the OpenAPI template
+(`/announcements/{id}/click`); pass the supertest response as `response`.
+
+`@terreno/api/testing` also registers api's own test models (including `User`). A package
+that defines its own `User` model imports the same two functions from the side-effect-free
+`@terreno/api/testing/openApi` entry instead, so one test process never compiles `User` twice.
+
+```typescript
+import {authAsUser, expectDocumentedResponse} from "@terreno/api/testing";
+
+const spec = (await supertest(app).get("/openapi.json")).body;
+const agent = await authAsUser(app, "notAdmin");
+const res = await agent.get("/auth/me").expect(200);
+expectDocumentedResponse({method: "get", path: "/auth/me", response: res, spec});
+```
+
 ## Smoke helpers
 
 A package smoke is a real-process check of the package's built output. It lives in
@@ -347,7 +369,7 @@ exits 0 on a 2-vCPU worker before it prints the `All files` row. When that
 row is still missing after one retry, the script uses `coverage/lcov.info`
 only if it lists every non-test source file under `src/`. Dedicated CircleCI
 jobs (`api-ci`, `ai-ci`, `blocks-ci`,
-`rtk-ci`, `ui-ci`, `syncdb-ci`, `comms-ci`, `mcp-server-ci`, `admin-spa-ci`) run
+`ui-ci`, `syncdb-ci`, `comms-ci`, `mcp-server-ci`, `admin-spa-ci`) run
 that script. Published packages without a dedicated workflow
 (`admin-backend`, `admin-frontend`, `api-health`, `feature-flags`, `@terreno/test`)
 run the same lint, compile, and coverage commands via the parameterized
@@ -357,7 +379,7 @@ including `.github/workflows/packages-ci.yml`. Those twins run
 pass `secrets.CODECOV_TOKEN` into `upload-codecov`.
 
 Each of those jobs then uploads `coverage/lcov.info` to Codecov with a distinct
-flag (`api`, `ui`, `rtk`, …) via `scripts/upload-codecov.sh`. The script
+flag (`api`, `ui`, `syncdb`, …) via `scripts/upload-codecov.sh`. The script
 downloads the linux uploader over HTTPS and refuses to run it unless the
 SHA-256 digest matches the pin in the script (`CODECOV_UPLOADER_SHA256`).
 `codecov.yml` sets per-package flags, `target: auto` with a 1% threshold so
@@ -394,7 +416,10 @@ registered `DemoConfig` demo and story through `renderWithTheme` from
 Pull requests also run the `New file coverage` workflow. Every newly added workspace
 `.ts` or `.tsx` implementation file must have at least 90% function coverage and 90%
 line coverage. Test, spec, story, generated OpenAPI SDK, `dist`, isolated-test,
-`src/types` type modules, demo `story-config/*.config.tsx`, and Expo Router route
+`src/types` type modules, modules whose only exports are `interface` and `type`
+aliases (comments and string literals do not count; TypeScript erases them, so
+Bun writes no LCOV record), demo
+`story-config/*.config.tsx`, and Expo Router route
 files (`index`, `_layout`, `+not-found`, `[param]`, plus example recovery screens
 `forgotPassword` / `resetPassword` / `verifyEmail`) are excluded. A new implementation
 file that is absent from LCOV is treated as 0% covered, except files listed in

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

@@ -597,9 +597,9 @@ pickers, sort menus).
 </DropdownPanel>
 ``````
 
-> `Filter` is the former name and stays exported as a deprecated alias (with `FilterProps`)
-> until Terreno 58. The `FilterSelectMenu` / `FilterBoolean` / `FilterAccordion` /
-> `FilterChangesBadge` controls keep their names.
+> `Filter` and `FilterProps`, the former names, were removed in Terreno 58. The
+> `FilterSelectMenu` / `FilterBoolean` / `FilterAccordion` / `FilterChangesBadge` controls
+> keep their names.
 
 #### Positioning
 
@@ -1251,18 +1251,87 @@ On web, that container is portaled to `document.body` (`position: fixed`, `z-ind
 
 Only the visible toast takes clicks. Every full-width layer around it (the container, its safe area, and the `Toast` layout wrapper) uses `pointerEvents: "box-none"`, so a button at the same height as an open toast stays clickable. Declare that style through `StyleSheet.create`; react-native-web drops `pointerEvents` from inline styles.
 
-## Consent components
+## Consent and announcement navigators
 
-Client side of `ConsentApp` ([API reference](api.md#consent-forms-consentapp),
-[concepts](../explanation/consent-forms.md)). Lazily exported from the package root.
+`ConsentNavigator` and `AnnouncementNavigator` gate authenticated app content on the
+consent (`@terreno/api` consents) and announcement (`@terreno/announcements`) routes.
+Both take a request `client` instead of an RTK Query api (the `api` prop was removed in
+Terreno 58). Pass the app's `@terreno/syncdb/api` client:
 
-### ConsentNavigator and ConsentFormScreen
+```tsx
+import {AnnouncementNavigator, ConsentNavigator} from "@terreno/ui";
+import {apiClient} from "@/store/apiClient"; // createApiClient({authProvider, baseUrl, ...})
+
+<ConsentNavigator client={apiClient}>
+  <AnnouncementNavigator client={apiClient} frequency={{userId}}>
+    <AppTabs />
+  </AnnouncementNavigator>
+</ConsentNavigator>
+```
+
+### `TerrenoRequestClient`
+
+`client` is any object with a `request` method of this shape. A syncdb `ApiClient` satisfies
+it structurally; `@terreno/ui` does not depend on `@terreno/syncdb`.
+
+```typescript
+interface TerrenoRequestArgs {
+  url: string;                       // relative paths resolve against the client's base URL
+  method?: string;                   // default "GET"
+  params?: Record<string, unknown>;  // query string; undefined values are omitted
+  body?: Record<string, unknown> | null;
+  headers?: Record<string, string>;
+  unwrap?: boolean;                  // unwrap {data} envelopes (default true)
+}
+
+interface TerrenoRequestClient {
+  request: <T = unknown>(args: TerrenoRequestArgs) => Promise<T>;
+}
+```
+
+A failed request must reject with an error carrying the HTTP `status` (syncdb's `ApiError`
+does). On `401` / `403` both navigators render `children` so the app's auth handling runs;
+any other error shows a **Retry** screen and calls `onError`.
+
+### `ConsentNavigator` props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `client` | `TerrenoRequestClient` | Required. Sends `GET /consents/pending` and `POST /consents/respond`. |
+| `baseUrl` | `string` | Optional path prefix for the consent routes. |
+| `children` | `ReactNode` | Rendered once no consent forms are pending. |
+| `extraScreens` | `ReactNode[]` | Shown in order after the forms; each element receives an `onNext` prop. |
+| `onError` | `(error: unknown) => void` | Called for non-auth load errors and failed submissions. |
+| `variables` | `Record<string, string>` | Substituted into consent form markdown. |
+
+### `AnnouncementNavigator` props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `client` | `TerrenoRequestClient` | Required. Sends `GET /announcements/pending`, `GET /announcements/feed`, and the acknowledge / impression / click events. |
+| `baseUrl` | `string` | Optional path prefix for the announcement routes. |
+| `children` | `ReactNode` | App content; hidden behind a modal announcement, kept mounted under a banner. |
+| `frequency` | `AnnouncementFrequencyConfig` | Client-side interrupt caps (`maxInterruptionsPerSession`, `cooldownHours`, `skipFirstLaunch`, `userId`). |
+| `onError` | `(error: unknown) => void` | Called for non-auth load errors and failed acknowledgements. |
+
+### Hooks
 
-`ConsentNavigator` wraps app content, fetches `GET /consents/pending` through
-`useConsentForms(api, baseUrl)`, and renders `ConsentFormScreen` for each pending form until
-the list is empty. `ConsentFormScreen` shows the form's markdown (with `{{variable}}`
-substitution), required checkboxes, an optional signature, the scroll-to-bottom gate, and the
-agree and decline buttons.
+The navigators are built on hooks you can call directly. Each takes `(client, baseUrl?)` and
+keeps loading, error, and data in React state.
+
+| Hook | Returns |
+|------|---------|
+| `useConsentForms(client, baseUrl?)` | `{forms, isLoading, error, refetch}` |
+| `useSubmitConsent(client, baseUrl?)` | `{submit, isSubmitting, error}` |
+| `useAnnouncements(client, baseUrl?, {page, limit}?)` | `{pending, feed, isLoading, error, refetch, isFeedLoading, feedError, refetchFeed}` |
+| `useAcknowledgeAnnouncement(client, baseUrl?)` | `{acknowledge, recordImpression, recordClick, isSubmitting, error, ...}` |
+
+Queries fetch on mount and when `client`, `baseUrl`, or feed paging change. `refetch()` joins
+a request already in flight. A successful `submit` refetches every mounted `useConsentForms`
+on the same client, and a successful `acknowledge` refetches every mounted pending
+announcement on the same client.
+
+### Provisional signatures on consent forms
 
 When staff signed the form provisionally, the pending form carries
 `provisionalSignature: {signedAt, signedByName}` (`ConsentFormPublic`), and the screen shows
@@ -1284,12 +1353,12 @@ For staff who record consent on a user's behalf. The server must grant the viewe
 ```tsx
 import {ProvisionalConsentSigner} from "@terreno/ui";
 
-<ProvisionalConsentSigner api={terrenoApi} userId={memberId} />
+<ProvisionalConsentSigner client={apiClient} userId={memberId} />
 ```
 
 | Prop | Type | Description |
 | --- | --- | --- |
-| `api` | RTK Query api | The consumer api, as passed to `ConsentNavigator` |
+| `client` | `TerrenoRequestClient` | The app's request client, as passed to `ConsentNavigator` |
 | `baseUrl` | `string` | Optional prefix for consent routes |
 | `userId` | `string` | The user being signed for |
 | `onSigned` | `(response) => void` | Called with the stored `ConsentResponse` after a provisional signature |
@@ -1318,14 +1387,14 @@ the signer, date, and note. Provisional rows also have "Void". It opens a dialog
 a required reason, sends it to `POST /consent-responses/:id/void`, and refetches, so the row
 returns to "Pending". A void error shows in the dialog and calls `onError`.
 
-`useProvisionalConsent({api, baseUrl?, userId})` returns `{statuses, isLoading, error,
+`useProvisionalConsent({client, baseUrl?, userId})` returns `{statuses, isLoading, error,
 refetch, sign, isSigning, voidSignature, isVoiding}`. `statuses` are `ProvisionalConsentStatusRow`s
 (`{form, status, isConsented, respondedAt?, provisional?}`). `sign({consentFormId, note,
 locale?})` signs for the hook's `userId` and resolves to the `ConsentResponse`, or rejects
-with the RTK error. `voidSignature({responseId, reason})` voids a provisional signature the
-same way. The hook injects `getConsentStatus`, `signConsentProvisionally`, and
-`voidProvisionalConsent` once per `(api, baseUrl)`. Signing and voiding invalidate the
-`ConsentStatus` and `PendingConsents` tags.
+with the request error. `voidSignature({responseId, reason})` voids a provisional signature the
+same way. The hook requests `GET /consent-responses/status`, `POST /consent-responses/provisional`,
+and `POST /consent-responses/:id/void` on the client. Signing and voiding refetch every mounted
+`useProvisionalConsent` and `useConsentForms` on the same client.
 
 testIDs: `provisional-consent-signer`, `provisional-consent-loading`,
 `provisional-consent-error`, `provisional-consent-retry-button`, `provisional-consent-empty`,
@@ -2391,6 +2460,21 @@ describe("MyComponent", () => {
 
 **Why:** Most @terreno/ui components require ThemeProvider context to access theme values.
 
+### createFakeRequestClient
+
+In-repo test helper (`ui/src/test-utils.tsx`) for components that take a
+`TerrenoRequestClient`. Routes are `"METHOD /path/:param"` keys; unmatched requests reject
+with a 404-shaped error. `fakeHttpError(status)` builds an error carrying `status`.
+
+``````typescript
+const {client, callsTo} = createFakeRequestClient({
+  "GET /consents/pending": () => ({data: [form]}),
+  "POST /consents/respond": () => ({agreed: true}),
+});
+renderWithTheme(<ConsentNavigator client={client}>{children}</ConsentNavigator>);
+expect(callsTo("POST /consents/respond")).toHaveLength(1);
+``````
+
 ### TapToEdit testIDs
 
 Pass `testID` on `TapToEdit`. The Field input uses that id. Action controls suffix it:
@@ -2823,6 +2907,35 @@ for that type:
 A value that is already formatted, such as "Oct 8, 2026, 3:00 PM", is not ISO, so a `date`
 column shows it unchanged.
 
+## DataTable column widths
+
+`width` on a `DataTableColumn` is optional. A column with a `width` is always that many
+pixels. A column without one is sized automatically:
+
+1. Its natural width is the wider of its header (title plus the sort, info, and filter icons)
+   and its content, plus cell padding, clamped to 80–360px. Content is read from at most 50
+   rows, spread evenly across `data`. Dates are measured as formatted; boolean cells are a
+   fixed icon width; custom cells whose value is not a string or number count as 120px.
+2. When the table body is wider than the sum of all columns, auto-sized columns grow to fill
+   it, in proportion to their natural widths. When the columns are wider than the body, they
+   keep their natural widths and the table scrolls horizontally.
+
+Text is measured with one shared canvas on web and estimated from font size on native, so
+sizing never renders or lays out extra cells. Measurement reruns only when `columns`, `data`,
+`defaultTextSize`, or `customColumnComponentMap` change; a container resize only reruns the
+fill step. Keep `columns` and `data` referentially stable between renders.
+
+```typescript
+const columns: DataTableColumn[] = [
+  {columnType: "text", title: "Name"},            // auto
+  {columnType: "text", title: "Email"},           // auto
+  {columnType: "number", title: "Visits"},        // auto
+  {columnType: "custom", title: "", width: 60},   // fixed
+];
+```
+
+Custom cell components receive the column with its resolved `width`.
+
 ## DataTable server-side filtering
 
 `DataTable` is data-layer agnostic. Optional filter and search props emit a

package/src/docs/versioned/next/tasks/native-module-baseline.md

@@ -4,16 +4,18 @@ IP: [native-module-baseline](../implementationPlans/native-module-baseline.md)
 
 ## Phase 1 — Dependencies + config
 
-- [ ] **Task 1.1**: Catalog + app package manifests
+- [x] **Task 1.1**: Catalog + app package manifests
   - Description: add the seven packages to root catalog (sorted) and to example-frontend + demo deps via `catalog:`
   - Files: root `package.json`, `example-frontend/package.json`, `demo/package.json`
   - Depends on: none
   - Acceptance: `bun install` + full compile green
-- [ ] **Task 1.2**: Config plugins + build properties
+  - Done: six of seven manifest entries landed; `react-native-otp-verify` dropped (no New Architecture support). See IP Implementation notes.
+- [x] **Task 1.2**: Config plugins + build properties
   - Description: stripe + purchases plugins; `expo-build-properties` Kotlin 2.x / compileSdk 36 pins
   - Files: `example-frontend/app.json`, `demo/app.json`
   - Depends on: 1.1
   - Acceptance: `expo config` resolves without errors; web export unaffected
+  - Done: stripe + local-authentication + build-properties plugins. `react-native-purchases` ships no config plugin. compileSdk pinned to 37 (RN 0.88 default), not 36.
 
 ## Phase 2 — Builds + verification
 
@@ -22,16 +24,18 @@ IP: [native-module-baseline](../implementationPlans/native-module-baseline.md)
   - Files: `eas.json` profiles if needed
   - Depends on: Phase 1
   - Acceptance: both builds compile
-- [ ] **Task 2.2**: Diagnostics story
+- [x] **Task 2.2**: Diagnostics story
   - Description: hidden demo story listing resolved native module versions
   - Files: `demo/stories/NativeModules.stories.tsx`, `demo/demoConfig.tsx`
   - Depends on: 2.1
   - Acceptance: story shows all seven modules on a dev build; screenshot evidence
-- [ ] **Task 2.3**: Expo Go degradation doc
+  - Done: hidden `Native Modules` page (`hidden: true` config, routable at `/demo/Native%20Modules`). Web screenshot only; on-device check waits on Task 2.1.
+- [x] **Task 2.3**: Expo Go degradation doc
   - Description: document which flows need a dev build (stripe, local-auth) vs preview modes (purchases)
   - Files: `docs/` upgrade note draft
   - Depends on: 2.1
   - Acceptance: reviewed checklist in the note
+  - Done: Expo Go table in `mcp-server/src/docs/upgrades/58.0.0.md`.
 
 ## Phase 3 — Release
 

package/src/docs/versioned/next/tasks/rate-limiting.md

@@ -8,12 +8,12 @@ IP: [rate-limiting.md](../implementationPlans/rate-limiting.md)
 ## Phase 1 — Tracer (memory, TerrenoApp)
 
 - [x] **Task 1.1**: Rate-limit module + TerrenoApp mount
-  - Delivers: `rateLimit: {}` on `TerrenoApp` limits HTTP; omitted option is a no-op; `POST /auth/login` uses the auth bucket (20 / 15 min); modelRouter list uses `api` (600 / 15 min); skip `/health` and `/openapi.json`; 429 `APIError` `code: "rate-limit-exceeded"` with `Retry-After` and IETF `RateLimit` / `RateLimit-Policy`; memory store; `trust proxy` default `1` when enabled
+  - Delivers: `rateLimit: {}` on `TerrenoApp` limits HTTP; omitted option used to be a no-op (Terreno 58 default-on — see Task 5.1); `POST /auth/login` uses the auth bucket (20 / 15 min); modelRouter list uses `api` (600 / 15 min); skip `/health` and `/openapi.json`; 429 `APIError` `code: "rate-limit-exceeded"` with `Retry-After` and IETF `RateLimit` / `RateLimit-Policy`; memory store; `trust proxy` default `1` when enabled
   - Files: `api/src/rateLimit/types.ts`, `api/src/rateLimit/store.ts`, `api/src/rateLimit/memoryStore.ts`, `api/src/rateLimit/policies.ts`, `api/src/rateLimit/middleware.ts`, `api/src/rateLimit/rateLimit.test.ts`, `api/src/terrenoApp.ts`, `api/src/index.ts`, `api/src/api.ts` (remove `TODO add rate limit`)
   - Blocked by: none
   - Skills: `terreno-backend-api`, `backend-test-env`, `update-docs`
   - Docs: stub section in `docs/reference/api.md` (`rateLimit` option) so the tracer is documented when it lands
-  - Acceptance: bun tests — default off (burst login no 429); auth 20 then 429; 21st list GET still 200; 601st list 429; `/health` never 429; 429 body/headers; login classified auth
+  - Acceptance: bun tests — with limiter off (`rateLimit: false`), burst login no 429; auth 20 then 429; 21st list GET still 200; 601st list 429; `/health` never 429; 429 body/headers; login classified auth
 
 ## Phase 2 — Shared stores
 
@@ -68,3 +68,10 @@ IP: [rate-limiting.md](../implementationPlans/rate-limiting.md)
   - Blocked by: 4.1
   - Skills: `update-docs`
   - Acceptance: seed `Implementation plan` / `Tasks` links are not `*(not yet written)*`
+
+## Phase 5 — Terreno 58
+
+- [x] **Task 5.1**: Default the limiter on
+  - Delivers: omitted `rateLimit` mounts the memory limiter with default limits; `rateLimit: false` turns it off; `{}` / options unchanged; example-backend passes `{trustProxy: 1}` when deployed and `false` locally; 58 upgrade note
+  - Files: `api/src/terrenoApp.ts`, `api/src/rateLimit/rateLimit.test.ts`, `example-backend/src/server.ts`, `docs/how-to/rate-limiting.md`, `docs/reference/api.md`, `mcp-server/src/docs/upgrades/58.0.0.md`, `.rulesync/rules/api/00-api.md`
+  - Acceptance: omitted → 429 on the 21st login; `false` → 25 logins succeed; `{}` → 429 on the 21st login; backend suites stay green

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

@@ -28,31 +28,31 @@ See: [`docs/implementationPlans/remove-legacy-realtime.md`](../implementationPla
 
 ## Phase 2: Delete in Terreno 58
 
-- [ ] **Task 2.1**: Remove `modelRouter` `realtime` registration
+- [x] **Task 2.1**: Remove `modelRouter` `realtime` registration
   - Delivers: passing `realtime` is a type error; no `registerRealtime` from `modelRouter`
   - Files: `api/src/api.ts`, `api/src/realtime/types.ts`, `api/src/realtime/deprecation.ts`, `api/src/index.ts`, `api/src/api.test.ts`
   - Blocked by: Terreno 58 major
   - Acceptance: TypeScript and tests fail if a router still passes `realtime`; `sync` registration is unchanged
 
-- [ ] **Task 2.2**: Stop emitting legacy `sync` (RTK) websocket events
+- [x] **Task 2.2**: Stop emitting legacy `sync` (RTK) websocket events
   - Delivers: change streams emit `sync:delta` only for synced models; no RTK `sync` payload
   - Files: `api/src/realtime/changeStreamWatcher.ts`, `api/src/realtime/realtimeApp.ts`, `api/src/realtime/registry.ts`, related tests
   - Blocked by: Task 2.1
   - Acceptance: a model with only `sync` still emits `sync:delta`; no `sync` events for collection CRUD; `admin:model.changed` still works when `admin.realtime` is true
 
-- [ ] **Task 2.3**: Remove `@terreno/rtk` cache-patching helpers
+- [x] **Task 2.3**: Remove `@terreno/rtk` cache-patching helpers
   - Delivers: `realtimeList`, `realtimeDocument`, `setRealtimeSocket`, `getRealtimeSocket` are gone from the package
   - Files: `rtk/src/realtime.ts`, `rtk/src/realtime.test.ts`, `rtk/src/index.ts`, `rtk/README.md`
   - Blocked by: Task 2.1
   - Acceptance: package compile fails if those symbols are imported; `useSocketConnection` still exists
 
-- [ ] **Task 2.4**: Remove example and bootstrap usage
+- [x] **Task 2.4**: Remove example and bootstrap usage
   - Delivers: example-backend/example-frontend/MCP bootstrap do not configure RTK realtime
   - Files: `example-backend/src/api/todos.ts`, `example-frontend/store/sdk.ts`, `example-frontend/app/_layout.tsx`, MCP bootstrap templates
   - Blocked by: Task 2.3
   - Acceptance: todos stay on `sync` + syncdb; `setRealtimeSocket` / `realtimeList` / `realtimeDocument` are gone; `RealtimeApp` remains registered
 
-- [ ] **Task 2.5**: Docs, skills, changelog, 58.0.0 upgrade note
+- [x] **Task 2.5**: Docs, skills, changelog, 58.0.0 upgrade note
   - Delivers: upgrade note lists every removed symbol and the syncdb replacement
   - Files: `docs/how-to/migrate-rtk-to-syncdb.md`, `docs/reference/api.md`, `.rulesync/skills/terreno-data-fetching/references/realtime.md`, `.rulesync/skills/terreno-backend-api/references/model-router.md`, `mcp-server/src/docs/upgrades/58.0.0.md`, changelog
   - Blocked by: Task 2.4

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

@@ -0,0 +1,155 @@
+# Task List: Remove @terreno/rtk and Redux in Terreno 58
+
+See: [`docs/implementationPlans/remove-rtk.md`](../implementationPlans/remove-rtk.md)
+
+**Target:** Terreno **58.0.0**, branch `remove-rtk-58`, one PR into `release-58.0.0`.
+
+Wide refactor: **expand → migrate → contract**. Every task leaves the branch compiling and
+green. Phase 4.1 (delete `rtk/`) is blocked by every migration task.
+
+**Supporting skills:** `terreno-data-fetching`, `terreno-backend-api`,
+`mongoose-schema-safety`, `building-terreno-apps`, `building-admin-interfaces`, `terreno-ui`,
+`backend-test-env`, `verify-ui-changes`, `update-docs`, `generate-sdk` (rewrite in 4.2).
+
+## Phase 1: Expand syncdb
+
+- [x] **Task 1.1** (tracer): Request client + query/mutation hooks + `/config`
+  - Delivers: `createApiClient({baseUrl, authProvider, credentials?, headers?})` and `useApiQuery` / `useLazyApiQuery` / `useApiMutation` / `ApiClientProvider`, with a shared per-client cache keyed by URL+args, tag invalidation, `{data}` / list-envelope unwrap matching RTK, 401 → `authProvider.refresh` → retry, `App-Version` / `App-Platform` headers. `@terreno/syncdb/config` exports `baseUrl`, `baseWebsocketsUrl`, `resolveBaseUrls`, `resolveDevApiPort` (moved from `rtk/src/constants.ts` with their tests). example-frontend profile screen reads `GET /auth/me` through `useApiQuery`; `store/syncdb.ts` imports `baseUrl` from `@terreno/syncdb/config`.
+  - Files: `syncdb/src/api/{client,cache,hooks}.ts` + tests, `syncdb/src/config/baseUrl.ts` + tests, `syncdb/package.json` exports, `admin-frontend/src/{adminRequest,useAdminRpc}.ts` (wrap the syncdb client), `example-frontend/app/(tabs)/profile.tsx`, `example-frontend/store/syncdb.ts`
+  - Blocked by: none
+  - Acceptance: bun tests for dedupe, tag invalidation, envelope unwrap, refresh-retry, abort/timeout; admin-frontend tests still pass unchanged; profile e2e passes
+  - Docs: `docs/reference/syncdb.md` (API client, config sections)
+
+- [x] **Task 1.2**: Codegen for every non-synced OpenAPI operation
+  - Delivers: `terreno-syncdb generate` also emits typed request/response types and `useXQuery` / `useXMutation` hooks for every operation without `x-terreno-sync`, including plain routes (`/auth/me`, `/consents/pending`, `/files/upload` multipart, `/version-check`). Tags inferred per path. example-frontend `bun run sdk` runs it and writes `store/apiSdk.ts`; profile screen switches to the generated `useGetAuthMeQuery`.
+  - Also: add OpenAPI docs for the 13 frontend-called routes the spec omits — `GET/PATCH /auth/me`, `POST /auth/{sendVerification,forgotPassword,verifyEmail}`, `POST /resetPassword` (`api`); `GET /feature-flags/flagConfiguration` (`feature-flags`); `GET /version-check` (`api`); `GET /consents/pending`, `POST /consents/respond` (`api`); `GET /announcements/{pending,feed}`, `POST /announcements/{id}/{acknowledge,click,impression}` (`announcements`); `POST /files/upload` multipart (`ai`).
+  - Files: `syncdb/src/codegen/{emitApi,discoverOperations}.ts` + fixtures/tests, `syncdb/src/codegen/{cli,generate}.ts`, `example-frontend/scripts/generate-sdk.ts`, `example-frontend/store/apiSdk.ts` (generated), OpenAPI registrations in the owning packages + their route tests
+  - Blocked by: 1.1
+  - Acceptance: codegen tests against fixture spec cover query, mutation, path params, multipart, synced ops excluded; generated file compiles in example-frontend; live `/openapi.json` lists all 13 previously missing routes
+  - Docs: `docs/reference/syncdb.md` (codegen), `docs/how-to/` page for regenerating the SDK
+
+- [x] **Task 1.3**: `@terreno/syncdb/auth` — Better Auth client + session without Redux
+  - Delivers: `createBetterAuthClient`, `createStorageAdapter`, cookie-jar repair (moved with tests), `SessionProvider` + `useSession()` → `{userId, user, isLoading, isAuthenticated, error, logout}`; `logout` signs out, stops syncdb, wipes local data. example-frontend `lib/betterAuth.ts` imports from syncdb.
+  - Files: `syncdb/src/auth/{betterAuthClient,session,SessionProvider}.ts(x)` + tests, `syncdb/package.json` (move `better-auth`, `@better-auth/expo`, `expo-secure-store`, async-storage deps/peers), `example-frontend/lib/betterAuth.ts`
+  - Blocked by: 1.1
+  - Acceptance: ported `betterAuthClient` / `betterAuthSlice` behaviours as hook tests (session sync on start, after login, logout side effects)
+  - Docs: `docs/reference/syncdb.md` (auth), `docs/explanation/authentication.md`, `docs/how-to/configure-better-auth.md`
+
+- [x] **Task 1.4**: Port legacy JWT frontend auth
+  - Delivers: `jwtAuthAdapter` (token storage on SecureStore/AsyncStorage, refresh when < 2 min to expiry, mutex, 401 → refresh → retry, logout on refresh failure) and `useJwtAuth()` (`login`, `signup`, `googleLogin`, `resetPassword`, `logout`) feeding `SessionProvider`; token-expiry helpers (`getTokenExpirationTimes`, `shouldShowStillThereModal`).
+  - Files: `syncdb/src/auth/{jwtAuthAdapter,useJwtAuth,tokenExpiry}.ts` + tests (ported from `rtk/src/authSlice*.test.ts`, `rtk/src/isolated/emptyApi*.isolated.ts`)
+  - Blocked by: 1.3
+  - Acceptance: AC9 — ported tests pass against an `api` test server using JWT auth
+  - Docs: `docs/explanation/authentication.md`, `docs/reference/syncdb.md`
+
+- [x] **Task 1.5**: Socket event API + `@terreno/syncdb/flags`
+  - Delivers: `client.onSocketEvent` / `useSocketEvent`; `useFeatureFlags(client)` / `useTerrenoFeatureFlags` (OpenFeature provider) fetching via the request client and refetching on the flags push event. example-frontend `_layout.tsx` drops `useSocketConnection` / `useRealtimeDebug`. Server deprecation message updated.
+  - Files: `syncdb/src/sync/socketTransport.ts`, `syncdb/src/react/useSocketEvent.ts`, `syncdb/src/flags/*` + tests (ported from `rtk/src/useFeatureFlags.test.ts`, `useTerrenoFeatureFlags.test.ts`), `feature-flags/src/featureFlagsApp.ts`, `example-frontend/app/_layout.tsx`, `(tabs)/{ai,documents,profile}.tsx`
+  - Blocked by: 1.1
+  - Acceptance: AC7 — Playwright spec asserts one socket.io connection and a pushed flag change updates the UI
+  - Docs: `docs/reference/feature-flags.md`, `docs/how-to/add-feature-flags.md`, `docs/how-to/websocket-integration.md`
+
+- [x] **Task 1.6**: `@terreno/syncdb/app` and `/buildNumber`
+  - Delivers: `useUpgradeCheck` (on the request client), `hasPermission` / `canOpenAdminPage`, `installDevConsoleLogger`, `useMCPTools` (token from the shared AuthProvider, fixing the Better Auth gap), `buildNumber` node subpath — all moved with tests. example-frontend uses them.
+  - Files: `syncdb/src/app/*`, `syncdb/src/buildNumber.ts` + tests, `example-frontend/app/_layout.tsx`, `app/admin/_layout.tsx`, `(tabs)/{ai,profile}.tsx`
+  - Blocked by: 1.1
+  - Acceptance: ported `useUpgradeCheck*`, `usePermissions`, `devConsoleLogger`, `useMCPTools`, `buildNumber` tests pass
+  - Docs: `docs/how-to/upgrade-banner.md`, `docs/how-to/expose-mcp-tools.md`, `docs/reference/syncdb.md`
+
+## Phase 2: Backend sync for GptHistory and McpServiceToken
+
+- [x] **Task 2.1**: GptHistory synced with string ids + migration
+  - Delivers: String `_id` (UUID default), `syncPlugin` + `isDeletedPlugin`, `sync: {scope: owner}` on `/gpt/histories`; `AIDataset.historyId` String; `gpt-history-string-ids` migration; SSE / turn / actions routes accept string ids. Backend example registers the stream.
+  - Files: `ai/src/models/{gptHistory,aiDataset}.ts`, `ai/src/routes/{gptHistories,gpt,gptActions}.ts`, `ai/src/migrations/gptHistoryStringIds.ts` + tests, `example-backend/src/server.ts`
+  - Blocked by: none
+  - Acceptance: AC5; existing `ai` route tests pass with string ids; sync snapshot test returns only the owner's histories
+  - Docs: `docs/reference/ai.md`, `.rulesync/rules/ai/00-ai.md`, 58.0.0 upgrade notes (run migration first)
+  - Skills: `mongoose-schema-safety`
+
+- [x] **Task 2.2**: McpServiceToken synced read-only + actions + migration
+  - Delivers: `modelRouter("/mcp/service-tokens", McpServiceToken, {sync})` with client writes disabled, sync `responseHandler` stripping `tokenHash`; `collectionActions.create` (plaintext once), `instanceActions.revoke`; `mcp-service-token-string-ids` migration; `verify` unchanged.
+  - Files: `api/src/models/mcpServiceToken.ts`, `api/src/mcp/serviceTokens.ts`, `api/src/migrations/` (built-in migration), tests
+  - Blocked by: none
+  - Acceptance: AC6; migration idempotence test; existing MCP auth tests pass
+  - Docs: `docs/reference/mcp-server.md` / service-token how-to, upgrade notes
+
+## Phase 3: Migrate consumers
+
+- [x] **Task 3.1**: `@terreno/ui` consents and announcements take `client`
+  - Delivers: `TerrenoRequestClient` structural interface; `ConsentNavigator`, `AnnouncementNavigator`, `useConsentForms`, `useSubmitConsent`, `useAnnouncements`, `useAcknowledgeAnnouncement` take `client`; no `injectEndpoints`. Tests use a fake client.
+  - Files: `ui/src/requestClient.ts`, the six source files above and their tests, `ui/src/OfflineBanner.tsx` (JSDoc)
+  - Blocked by: 1.1
+  - Acceptance: ui suite green; `rg injectEndpoints ui/src` → none
+  - Docs: `docs/reference/ui.md` (consent / announcement props)
+
+- [x] **Task 3.2**: example-frontend — remove Redux store, session, auth screens
+  - Delivers: delete `store/index.ts`, `store/appState.ts` Redux slice (→ context + `useStoredState`), `store/errors.ts` middleware (→ client `onError` reporting to Sentry), `store/betterAuthApi.ts`; root layout uses `SessionProvider` + `ApiClientProvider`; login, signup, forgot / reset password, verify email use generated hooks / `useSession`.
+  - Files: `example-frontend/store/*`, `app/_layout.tsx`, `app/{login,signup,forgotPassword,resetPassword,verifyEmail}.tsx`, `lib/authRecoveryActions.ts`, related tests
+  - Blocked by: 1.2, 1.3, 1.5, 1.6, 3.1
+  - Acceptance: auth e2e shard green; unit suite green
+  - Docs: `example-frontend/README.md`, `.rulesync/rules/example-frontend/00-example-frontend.md`
+
+- [x] **Task 3.3**: example-frontend — profile, admin layout, notifications, documents, push tokens
+  - Delivers: all remaining non-AI screens on generated hooks; `store/sdk.ts`, `store/openApiSdk.ts`, `store/commsOpenApiSdk.ts`, `openapi-config.ts`, `comms-openapi-config.ts` deleted.
+  - Files: `app/(tabs)/{profile,documents}.tsx`, `app/admin/**`, `components/NotificationCenter.tsx`, `components/TodoSummaryCard.tsx`, `app/gcs-settings.tsx`, `hooks/useSyncLabEngines.ts`, `app/admin/SyncLabScreen.tsx`
+  - Blocked by: 3.2
+  - Acceptance: app + admin-core + admin-table e2e shards green
+  - Docs: none beyond 3.2 (record skip)
+
+- [x] **Task 3.4**: example-frontend — AI screen and MCP settings on syncdb
+  - Delivers: `ai.tsx` histories via `useQuery("gptHistories")` / `useMutate` (rename, delete), no `updateQueryData` / `invalidateTags`; SSE uses the shared auth provider; MCP settings list via `useQuery("mcpServiceTokens")`, create/revoke via generated action hooks; `useMCPTools` from `/app`.
+  - Files: `app/(tabs)/ai.tsx`, `app/settings/mcp/index.tsx`, `store/syncdb.ts` (collections), `lib/gptAsks.ts`
+  - Blocked by: 2.1, 2.2, 3.2
+  - Acceptance: `ai-chat` e2e green incl. list / rename / delete across reload; new MCP tokens spec green
+  - Docs: `docs/how-to/` AI chat page if it names RTK hooks
+
+- [x] **Task 3.5**: example-frontend tests off RTK
+  - Delivers: `tests/bunSetup.ts` / `testPreload.ts` no longer import or mock `@/store/sdk`; `documents.test.tsx`, `NotificationCenter.test.tsx`, `orgMembersRoute.test.tsx`, `errors.test.ts`, `gptAsks.test.ts`, `TodoSummaryCard.test.tsx` use the syncdb client / fake transport; e2e allowlists and comments drop RTK entries (`consoleAllowlist.ts`, `syncdbSuite.ts`, `offlineHelpers.ts`, `adminAuth.ts`, `login` / `signup` / `admin-todo-crud` specs).
+  - Files: listed above
+  - Blocked by: 3.3, 3.4
+  - Acceptance: AC3 and AC4 for example-frontend
+  - Docs: none (record skip)
+
+- [x] **Task 3.6**: admin-spa off Redux
+  - Delivers: `StoreProvider` / `AdminGate` use `SessionProvider` (cookie mode); profile via the request client with `credentials: "same-origin"`; `store/sdk.ts` deleted; Redux deps removed.
+  - Files: `admin-spa/components/{StoreProvider,AdminGate,AdminSpaShell}.tsx`, `admin-spa/app/orgs/index.tsx`, `admin-spa/store/*`, `admin-spa/src/adminSpaUiCoverage.test.tsx`, `admin-spa/package.json`, `admin-spa/metro.config.js`
+  - Blocked by: 1.1, 1.3
+  - Acceptance: `bun run admin-spa:test` + admin-spa e2e and integration specs green
+  - Docs: `docs/reference/admin-spa*` / `docs/reference/admin-frontend.md` references
+
+- [x] **Task 3.7**: admin-frontend RTK-shaped test doubles
+  - Delivers: observability / prompts isolated tests use fake request clients instead of `injectEndpoints` APIs; RTK wording in assertions removed.
+  - Files: `admin-frontend/src/isolated/{observabilityFakeApi,aiObservabilityScreens,AiPromptsListScreen,AiPromptEditorScreen,adminRpcHooks}.isolated.tsx`, the other test files named in the IP research
+  - Blocked by: 1.1
+  - Acceptance: admin-frontend suite green; `rg -i "rtk|injectEndpoints" admin-frontend/src` → none
+  - Docs: `.rulesync/rules/admin-frontend/00-admin-frontend.md` (layout example imports `baseUrl` from `/config`)
+
+- [x] **Task 3.8**: Generators, MCP tools, cli
+  - Delivers: `create-terreno-app` scaffolds syncdb client, `SessionProvider`, generated `apiSdk.ts`, no Redux / rtk; `mcp-server` bootstrap templates, prompts, `tools.ts` (`generateInstallAdmin`), `resources.ts` (drop `terreno://docs/rtk`) updated; `get_rtk_state` and `terreno state --slice rtk` removed in favour of syncdb state tools.
+  - Files: `create-terreno-app/src/generate.ts` + tests, `mcp-server/src/{tools,prompts,bootstrap,resources}.ts`, `mcp-server/src/docs/templates/**`, `mcp-server/src/local/**`, `cli/src/commands/project.ts`, `cli/src/help.ts` + tests
+  - Blocked by: 1.2, 1.3, 1.5, 1.6
+  - Acceptance: AC10; generated app compiles in a temp dir
+  - Docs: `docs/how-to/create-a-terreno-app.md`, `docs/reference/mcp-server.md`, `docs/reference/cli.md`
+
+## Phase 4: Contract
+
+- [x] **Task 4.1**: Delete `rtk/` and its wiring
+  - Delivers: `rtk/` removed; root workspaces, `rtk:*` scripts, catalog entries (`@reduxjs/toolkit`, `@rtk-query/codegen-openapi`, `redux-persist`, `react-redux`, `axios-retry`, `async-mutex`, `jwt-decode` if unused); metro aliases; `example-backend/Dockerfile`; `knip.jsonc`; `biome.jsonc`; `codecov.yml`; CircleCI (`config.yml`, `continue-config.yml`); GitHub workflows (`rtk-ci.yml` deleted; `publish-on-tag`, `cd`, `docs-deploy`, `eas-pr`, `frontend-example-deploy`, `admin-spa-ci`, `dependabot`, issue templates, `architectural-pr-review.ts`); `scripts/**` maps and their tests; `website/scripts` + docusaurus redirect; `mcp-server/scripts/sync-package-guidelines.ts`. Apps declare native deps rtk used to pull in (`expo-secure-store`, `@better-auth/expo`, `better-auth`, `socket.io-client`, `expo-network` if still used); Expo fingerprint change recorded.
+  - Files: listed above, `bun.lock`
+  - Blocked by: 3.1–3.8
+  - Acceptance: AC1, AC2; `bun install && bun run compile`; `bun run check:knip`; `bun run analyze:full`
+  - Docs: none beyond 4.2
+
+- [x] **Task 4.2**: Docs, rules, skills, upgrade notes
+  - Delivers: `docs/how-to/migrate-rtk-to-syncdb.md` rewritten as the 58 upgrade path (every removed export → replacement table); `docs/reference/legacy/rtk.md` and `docs/explanation/announcements/rtk-deprecation.md` updated to "removed in 58"; `docs/explanation/local-first-data.md`, `docs/reference/environment-variables.md`, remaining single mentions; `mcp-server/src/docs/upgrades/58.0.0.md`; `changelog/unreleased/remove-rtk.md`; `.rulesync/rules/rtk/00-rtk.md` deleted, root / syncdb / example-frontend / mcp-server rules updated; plugin skills (`terreno-data-fetching`, `building-terreno-apps`, `generate-sdk`, `upgrading-terreno`, `building-admin-interfaces`); `README.md`, `AGENTS.md`, `CLAUDE.md`, `CLAUDE-consumer.md`, `CONTRIBUTING.md`; regenerate rulesync outputs and `bun run skills:sync`.
+  - Files: listed above
+  - Blocked by: 4.1
+  - Acceptance: AC12
+  - Skills: `update-docs`, `update-agent-docs`
+
+- [x] **Task 4.3**: Full verification and UI evidence
+  - Delivers: `bun run prepush`; full `frontend:e2e`; admin-spa e2e; `maestro:test`; screenshots / videos for AC11 under `/opt/cursor/artifacts/`.
+  - Files: none (evidence only)
+  - Blocked by: 4.2
+  - Acceptance: AC3, AC4, AC11 with commands and artifact paths recorded in the PR Verification table
+  - Skills: `verify-ui-changes`

package/dist/docs/guidelines/rtk/guidelines/core.md

@@ -1,26 +0,0 @@
-### @terreno/rtk
-
-Redux Toolkit Query integration:
-
-- **generateAuthSlice**: Creates auth reducer and middleware with JWT handling
-- **emptyApi**: Base RTK Query API for code generation
-- **Platform utilities**: Secure token storage (expo-secure-store for native, AsyncStorage for web)
-
-Key imports:
-
-```typescript
-import {generateAuthSlice} from "@terreno/rtk";
-```
-
-Always use generated SDK hooks — never use `axios` or `request` directly:
-
-```typescript
-// Correct
-import {useGetYourRouteQuery} from "@/store/openApiSdk";
-const {data, isLoading, error} = useGetYourRouteQuery({id: "value"});
-
-// Wrong - don't use axios directly
-// const result = await axios.get("/api/yourRoute/value");
-```
-
-**No barrel imports** in app store code — import hooks from `@/store/sdk` or `@/store/openApiSdk`, not `@/store`. See `docs/explanation/no-barrel-imports.md`.