@terreno/mcp 57.20.0 → 58.0.0-beta.1

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

@@ -1,6 +1,6 @@
 # @terreno/test
 
-Shared Bun test helpers for Terreno backend packages: in-memory MongoDB lifecycle, auth env defaults, HTTP fixtures, and log silencing.
+Shared Bun test helpers for Terreno packages: in-memory MongoDB lifecycle, auth env defaults, HTTP fixtures, log silencing, and real-process smoke helpers.
 
 ## Install
 
@@ -79,7 +79,7 @@ Defaults: `TOKEN_SECRET`, `TOKEN_ISSUER`, `REFRESH_TOKEN_SECRET`, `SESSION_SECRE
 | Variable | Effect |
 |----------|--------|
 | `TERRENO_TEST_USE_MEMORY_MONGO` | When `"true"`, `registerSimpleMongoPreload` starts `mongodb-memory-server` if `TERRENO_TEST_MONGODB_URI` is unset. |
-| `TERRENO_TEST_MONGODB_URI` | External MongoDB URI. Takes priority over in-memory server in `startMongoServer` and `registerSimpleMongoPreload`. |
+| `TERRENO_TEST_MONGODB_URI` | External MongoDB URI. Takes priority over in-memory server in `startMongoServer`, `registerSimpleMongoPreload`, and `smokeMongoUri`. |
 | `TERRENO_TEST_MONGO_LAUNCH_TIMEOUT_MS` | Per-mongod start timeout for in-memory servers started by `startMongoServer`. Default `60000` (mongodb-memory-server's own default is 10s). Startup is tried twice. |
 | `BUN_TEST_DISABLE_DB` | When `"true"`, `registerBackendPreload` skips all Mongo `beforeAll`/`afterAll` hooks (no DB startup). |
 
@@ -282,6 +282,76 @@ 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
+`<package>/e2e/smoke.ts` (`e2e/smoke.spec.ts` for browser packages), runs with the package's
+`smoke` script after `bun run compile`, and takes 30 s or less. It starts a server on a real
+port, runs the compiled binary, or opens a page, then walks one happy path. It exits non-zero on
+the first failed check. These helpers do the process work:
+
+| Export | Description |
+|--------|-------------|
+| `freePort()` | An unused TCP port on `127.0.0.1`. |
+| `smokeMongoUri({databaseName?})` | MongoDB URI with the database name (default `terrenoSmoke`). Uses `TERRENO_TEST_MONGODB_URI` when set (the CI sidecar). Otherwise it starts one single-node in-memory replica set per process, so change streams work. `stopSmokeMongo()` stops it. |
+| `spawnUntilReady({cmd, url, timeoutMs?, cwd?, env?, stopGraceMs?})` | Starts a long-running child and resolves once `url` answers 2xx (default timeout 20 s). Returns `{pid, output, stop}`. It rejects with the child's output when the child exits first or is not ready in time. `stop()` sends SIGTERM, then SIGKILL after `stopGraceMs` (default 5 s). |
+| `spawnExampleBackend({mongoUri, port?, env?, timeoutMs?, backendDir?})` | Starts the monorepo's `example-backend` by path with dev auth secrets and the demo AI model, then waits for `/health` (default timeout 60 s). `env` overrides the defaults; `backendDir` points at another directory holding `src/index.ts`. Returns `{baseUrl, port, pid, output, stop}`. Client smokes (rtk, syncdb, admin-frontend, example-frontend) use it, so they never import `@terreno/api`. Its `stop()` waits only 0.5 s after SIGTERM: example-backend's SIGTERM hook stops the jobs worker but keeps serving, so a longer grace only adds time. |
+| `runBin({bin, args?, cwd?, env?, timeoutMs?})` | Runs a binary to completion and resolves `{exitCode, stdout, stderr}`. A `.js`, `.mjs`, `.cjs`, or `.ts` path runs with Bun. Running past `timeoutMs` (default 30 s) rejects. Background processes the binary leaves behind are killed when it exits. |
+
+Each child that `spawnUntilReady`, `spawnExampleBackend`, or `runBin` starts runs in its own
+process group. `stop()`, a timeout, and the smoke process exiting, crashing, or receiving
+`SIGINT` or `SIGTERM` kill the whole group, so a wrapper command (`sh -c`, `bun run`) and the
+server it started both die and no server is left on a port. A smoke killed with `SIGKILL`
+cannot clean up.
+
+A server smoke can host its own server by re-running its file with an argument, which keeps
+one file per package. `api/e2e/smoke.ts` is the reference:
+
+```typescript
+import {freePort, smokeMongoUri, spawnUntilReady, stopSmokeMongo} from "@terreno/test";
+
+const port = await freePort();
+const server = await spawnUntilReady({
+  cmd: [process.execPath, __filename, "serve"],
+  env: {MONGO_URI: await smokeMongoUri({databaseName: "apiSmoke"}), PORT: String(port)},
+  url: `http://127.0.0.1:${port}/health`,
+});
+try {
+  // fetch() the happy path and throw on the first unexpected response
+} finally {
+  await server.stop();
+  await stopSmokeMongo();
+}
+```
+
+Run one package's smoke with `bun run --cwd <package> smoke`. From the repo root,
+`bun run smoke` runs every workspace's `smoke` script one at a time and prints each package's
+time. It keeps going after a failure and exits 1 if any package failed. Pass workspace
+directory names to run a subset: `bun run smoke api rtk`. Naming a workspace that does not
+exist or has no `smoke` script is an error.
+
 ## Conventions
 
 - Preload once per package via `bunfig.toml`; do not start Mongo in individual test files.
@@ -299,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
@@ -309,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
@@ -346,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

@@ -112,6 +112,33 @@ Figma AI surface/border roles and the dark status ramps. Custom overrides set
 through `useTheme()` are layered over the active mode; `resetTheme()` removes
 those overrides without changing the provider's selected mode.
 
+### Field theme
+
+The `field` section colors the input box of `TextField` (and the fields built on it, such as
+`TextArea`, `EmailField`, `NumberField`, and `PasswordField`), `SelectField`, `DateTimeField`,
+`HeightField`, and `OtpField`. Each token maps to a primitive key:
+
+| Token | Used for | Light | Dark |
+|---|---|---|---|
+| `background` | Enabled input background | `neutral000` | `neutral800` |
+| `backgroundDisabled` | Disabled input background | `neutral300` | `neutral600` |
+| `border` | Border at rest | `neutral500` | `neutral300` |
+| `borderFocus` | Border while focused | `primary200` | `primary200` |
+| `borderError` | Border when the field has an error | `error100` | `error050` |
+| `borderDisabled` | Border when disabled | `neutral700` | `neutral100` |
+
+```tsx
+const {setTheme} = useTheme();
+setTheme({field: {background: "neutral050", border: "neutral300", borderFocus: "primary500"}});
+```
+
+The defaults equal the `surface` and `border` tokens fields used before, so fields look the
+same unless you set `field`. Fields no longer follow `surface.base`, `surface.neutralLight`,
+`border.dark`, `border.focus`, `border.error`, or `border.activeNeutral`; restyle them through
+`field` instead. `DateTimeField` keeps `surface.disabled` for its disabled time picker.
+`MarkdownEditorField` and the native address autocomplete keep their own `border.default`
+styling.
+
 ### DashboardGrid and DashboardGridItem
 
 Eager layout-only wrapping grid. Default columns `{sm: 1, md: 2, lg: 3}`. Children stay caller-supplied `Card`s. Cell width is `(rowWidth - gap × (columns - 1)) / columns` so flex `gap` does not wrap extra columns.
@@ -570,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
 
@@ -1224,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
+
+`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:
+
+```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
 
-Client side of `ConsentApp` ([API reference](api.md#consent-forms-consentapp),
-[concepts](../explanation/consent-forms.md)). Lazily exported from the package root.
+| 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
+
+The navigators are built on hooks you can call directly. Each takes `(client, baseUrl?)` and
+keeps loading, error, and data in React state.
 
-### ConsentNavigator and ConsentFormScreen
+| 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, ...}` |
 
-`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.
+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
@@ -1257,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 |
@@ -1291,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`,
@@ -2364,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:
@@ -2796,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/regression/README.md

@@ -0,0 +1,87 @@
+# Regression suites
+
+Run `bun run check:regression-suites` after you edit any file here. CI runs the same check in
+the `repo-policies` job.
+
+These files hold a minimal manual pass a developer or QA walks before a release: a short check
+that the app works as intended, plus the behavior no unit test, smoke, or e2e spec can reach,
+such as push notifications, real email delivery, other hardware or operating-system behavior,
+full flows across devices, and how the app feels. Keep them small. Most features add no case
+here, and anything an e2e spec can drive and assert belongs in an e2e spec instead. Each area
+has one living file. Implementation plans
+propose cases under `## Regression cases`, and Brew writes them here with real IDs before it
+opens the pull request. See [Where regression suites live](../testing/e2e.md#where-regression-suites-live)
+for how this tier fits with the automated ones.
+
+## Areas
+
+| File | Area | Covers |
+| --- | --- | --- |
+| [planning.md](planning.md) | `PLAN` | Retired: planning-stage checks, kept so their IDs are never reused |
+| [auth.md](auth.md) | `AUTH` | Email delivery for password reset and verification, and native session storage |
+| [admin.md](admin.md) | `ADMIN` | Admin edits and announcements seen live on a phone |
+| [syncdb.md](syncdb.md) | `SYNC` | Offline writes, persistence across an app kill, and account switches on a device |
+| [ui-native.md](ui-native.md) | `NATIVE` | Notification permission prompts, finger-drawn signatures, and keyboard behavior on iOS and Android |
+
+## Suite format
+
+Every file follows the same shape:
+
+```markdown
+# Auth regression suite
+
+Area: AUTH
+Owner: <team or person>
+Last full run: 2026-01-15 (<who>, <short sha>)
+
+| ID | Case | Steps | Expected | Platforms | Automated by | Added |
+| --- | --- | --- | --- | --- | --- | --- |
+| AUTH-001 | ... | ... | ... | ... | manual | <IP slug> |
+```
+
+- **Title** is the first line, a `#` heading.
+- **`Area:`** declares the ID prefix: uppercase letters and digits. Find a suite by this line,
+  not by its file name. No two files declare the same area.
+- **`Owner:`** names the team or person who keeps the file current.
+- **`Last full run:`** is `never`, or the date, who walked it, and the short commit SHA. Change
+  it only after a person walks every case in the file.
+- **IDs** are `<AREA>-NNN`, zero-padded to three digits, and never reused. The next free ID is
+  one past the highest the file has ever held. A retired case keeps its row with `Retired` in
+  `Expected`. Provisional IP IDs such as `AUTH-new-1` never appear here.
+- **Steps** name a concrete starting state (who is signed in, what data exists, which build or
+  device), then an action a person can follow without guessing.
+- **Expected** is observable: what is on screen, in the inbox, or in the response. "It works"
+  or a restatement of the action does not count.
+- **Automated by** is `manual` or the path of the spec that covers the case. It never names an
+  IP-local `E<n>` row.
+- **Added** is the slug of the implementation plan that added the case.
+
+Escape a literal pipe inside a cell as `\|`.
+
+## What the check enforces
+
+`scripts/regression/checkSuites.ts` reads every `.md` file here except this README and fails
+when a file:
+
+- lacks the title, `Area:`, `Owner:`, or `Last full run:` line, or one of them is malformed
+- has a table whose columns differ from the seven above, or more than one table
+- has a row with the wrong number of cells, an ID that is not `<AREA>-NNN`, a `-new-` ID, or a
+  duplicate ID
+- has an empty cell, including Steps and Expected
+- names an `E<n>` row in Automated by
+
+It also fails when two files declare the same area. It does not judge whether a step meets the
+bar above; reviewers do.
+
+## Add a case
+
+1. Open the area's file, or create `<area>.md` with `Last full run: never` and an `Owner:`.
+2. Add a row with the next free ID.
+3. Run `bun run check:regression-suites`.
+
+## Backfill the suites
+
+To find cases an older feature should have had, run the `backfill-regression` skill. It
+surveys the app for behavior automation cannot reach, proposes cases one area at a time, and
+writes only the sets you approve. It records denied cases in
+`.terreno/regression-backfill.json` (not committed) so it never proposes them again.

package/src/docs/versioned/next/regression/admin.md

@@ -0,0 +1,13 @@
+# Admin regression suite
+
+Area: ADMIN
+Owner: Josh Gachnang
+Last full run: never
+
+Walk these cases with an admin account on web and a second, non-admin account signed in on a
+phone. Both run against the same deployed example-backend.
+
+| ID | Case | Steps | Expected | Platforms | Automated by | Added |
+| --- | --- | --- | --- | --- | --- | --- |
+| ADMIN-001 | An admin edit reaches the owner's phone live | A non-admin user is signed in on a phone with the Todos tab open and one todo titled "Buy milk". On web, an admin opens the Admin Panel, opens that todo, changes its title to "Buy oat milk", and saves | Within 10 seconds, without pulling to refresh or reopening the app, the phone's Todos list shows "Buy oat milk" | iOS, Android | manual | e2e-and-regression-testing |
+| ADMIN-002 | A published announcement shows on a phone | A non-admin user is signed in on a phone. On web, an admin creates and publishes an announcement from the Admin Panel, then the user force quits and reopens the app | The announcement shows once on the phone with the admin's title and body, and does not show again after it is dismissed and the app is reopened | iOS, Android | manual | e2e-and-regression-testing |

package/src/docs/versioned/next/regression/auth.md

@@ -0,0 +1,15 @@
+# Auth regression suite
+
+Area: AUTH
+Owner: Josh Gachnang
+Last full run: never
+
+Walk these cases against example-frontend and example-backend on a deployed environment whose
+backend sends real email. Use an inbox you can open, not a seeded `@example.com` address.
+
+| ID | Case | Steps | Expected | Platforms | Automated by | Added |
+| --- | --- | --- | --- | --- | --- | --- |
+| AUTH-001 | Password reset email reaches a real inbox | Signed out, with an account whose email is a real inbox you can open: on the login screen tap the forgot-password link, enter that email, tap "Send reset link", open the email, follow its link, enter a new password, tap "Save new password", then sign in with the new password | One reset email arrives within 2 minutes from the configured sender. Its link opens the "Reset password" screen in the app. Sign-in with the new password lands on Todos, and sign-in with the old password shows an error | Web, iOS, Android | manual | e2e-and-regression-testing |
+| AUTH-002 | Verification email confirms the account | Signed in as a new account with a real inbox that has not verified its email: open Profile, tap "Resend" on the verify-email banner, open the email, follow its link, tap "Confirm email", then reopen Profile | One verification email arrives within 2 minutes. After confirming, Profile no longer shows the "Verify your email" banner | Web, iOS, Android | manual | e2e-and-regression-testing |
+| AUTH-003 | Session survives a force quit on a device | Signed in on a release build on a phone, with at least one todo: force quit the app from the app switcher, wait 10 seconds, then open it again | The app opens on Todos with the same todos and no login screen, because the session is read back from the device's secure storage | iOS, Android | manual | e2e-and-regression-testing |
+| AUTH-004 | Logout clears the stored session on a device | Signed in on a release build on a phone: open Profile, tap "Logout", force quit the app, then open it again | The app opens on the login screen, and no data from the previous account shows before sign-in | iOS, Android | manual | e2e-and-regression-testing |

package/src/docs/versioned/next/regression/planning.md

@@ -0,0 +1,16 @@
+# Planning regression suite
+
+Area: PLAN
+Owner: Josh Gachnang
+Last full run: never
+
+Every case here is retired: they checked agent behavior, not the app, which the minimal
+regression rule leaves out. The rows stay so their IDs are never reused.
+
+| ID | Case | Steps | Expected | Platforms | Automated by | Added |
+| --- | --- | --- | --- | --- | --- | --- |
+| PLAN-001 | Grow plans e2e and regression | In a fresh session in a repo that has `docs/testing/e2e.md`, run Grow on "add a due date to todos" and approve it | Retired: an agent-behavior check, not an app check | Claude Code, Cursor, Codex | manual | e2e-and-regression-testing |
+| PLAN-002 | Grow without a guide | Repeat PLAN-001 in a repo with no `docs/testing/e2e.md` and no Testing conventions table | Retired: an agent-behavior check, not an app check | Claude Code | manual | e2e-and-regression-testing |
+| PLAN-003 | Brew writes the suite | Take an approved IP with one regression case through Brew | Retired: an agent-behavior check, not an app check | Claude Code | manual | e2e-and-regression-testing |
+| PLAN-004 | Pick writes, Roast enforces a planned spec | Run Pick on a PLAN-001 task that owns an `## E2E tests` row. Then delete the spec file and run Roast | Retired: an agent-behavior check, not an app check | Claude Code | manual | e2e-and-regression-testing |
+| PLAN-005 | Taste renumbers a collision | On a branch that added `AUTH-00N`, merge a master commit that also added `AUTH-00N`, then run Taste | Retired: an agent-behavior check, not an app check | Claude Code | manual | e2e-and-regression-testing |

package/src/docs/versioned/next/regression/syncdb.md

@@ -0,0 +1,15 @@
+# SyncDB regression suite
+
+Area: SYNC
+Owner: Josh Gachnang
+Last full run: never
+
+Walk these cases on a release build on a physical phone, against a deployed example-backend.
+Turn the network off with airplane mode, not by stopping the backend, so the operating system
+reports the device as offline.
+
+| ID | Case | Steps | Expected | Platforms | Automated by | Added |
+| --- | --- | --- | --- | --- | --- | --- |
+| SYNC-001 | An offline edit replays after airplane mode | Signed in on a phone with the Todos tab open and one todo, and the same account open on web: turn on airplane mode, mark the todo complete, wait 30 seconds, then turn airplane mode off | The phone shows the todo complete at once while offline. Within 10 seconds of reconnecting, web shows it complete without a reload, and the phone shows no conflict | iOS, Android | manual | e2e-and-regression-testing |
+| SYNC-002 | An offline create survives a force quit | Signed in on a phone in airplane mode: create a todo titled "Offline note", force quit the app, reopen it still in airplane mode, then turn airplane mode off | After reopening offline the list still shows "Offline note". After reconnecting it appears on web for the same account within 10 seconds, exactly once | iOS, Android | manual | e2e-and-regression-testing |
+| SYNC-003 | Switching accounts on one phone leaks no rows | Signed in on a phone as user A with at least two todos: open Profile, tap "Logout", then sign in as user B, who has no todos | User B's Todos tab is empty, both before and after the first sync completes. None of user A's todos appear at any point | iOS, Android | manual | e2e-and-regression-testing |

package/src/docs/versioned/next/regression/ui-native.md

@@ -0,0 +1,16 @@
+# Native UI regression suite
+
+Area: NATIVE
+Owner: Josh Gachnang
+Last full run: never
+
+Walk these cases on a fresh install on a physical phone. Delete the app first so the operating
+system asks for each permission again. NATIVE-001 and NATIVE-002 need a development build,
+because Profile shows "Send test push" only in development builds; the others run on either.
+
+| ID | Case | Steps | Expected | Platforms | Automated by | Added |
+| --- | --- | --- | --- | --- | --- | --- |
+| NATIVE-001 | Allowing notifications enables push | On a fresh install of a development build, sign in, tap Allow on the system notification prompt, open Profile, tap "Send test push", then lock the phone | The system prompt appears once, right after sign-in. A test notification shows on the lock screen within 1 minute | iOS, Android | manual | e2e-and-regression-testing |
+| NATIVE-002 | Denying notifications registers no device | On a fresh install of a development build, sign in as an account with no other signed-in devices, tap Don't Allow on the system notification prompt, then open Profile and tap "Send test push" | The app keeps working on Todos. Profile shows "No registered push tokens for this account." under the push button, and the prompt does not reappear on the next launch | iOS, Android | manual | e2e-and-regression-testing |
+| NATIVE-003 | A consent signature can be drawn with a finger | On a fresh install, sign in as an account that has never accepted the consent forms. On each consent screen that asks for a signature, draw a signature with one finger, then accept every form | The stroke follows the finger and the screen does not scroll while drawing. After the last form the app opens on Todos, and after a force quit and reopen no consent screen shows again | iOS, Android | manual | e2e-and-regression-testing |
+| NATIVE-004 | The keyboard does not cover a focused field | Signed in on a phone in portrait: open Profile, scroll to the "API Key" field in the Gemini API Key card, and tap it | The keyboard opens and the focused field stays visible above it, with its "API Key" label on screen | iOS, Android | manual | e2e-and-regression-testing |

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