@terreno/mcp 57.21.0 → 58.0.0-beta.2

package/dist/docs/versioned/57.21.0/testing/e2e/rtk.md

@@ -0,0 +1,80 @@
+# @terreno/rtk e2e tests
+
+Run the rtk smoke after a compile:
+
+```bash
+bun run compile && bun run --cwd rtk smoke   # or, from the root: bun run smoke rtk
+```
+
+## Test tiers
+
+| Tier | What it covers | Command |
+| --- | --- | --- |
+| Unit and integration | The JWT and Better Auth slices, the Better Auth client factory (cookie and web bearer modes, cookie-jar repair, OAuth handoff), the base query's token-source and refresh paths, sockets, offline middleware, feature-flag and upgrade hooks, with `@better-auth/expo/client` and other modules mocked per file (`src/**/*.test.ts`) | `bun run --cwd rtk test` |
+| Smoke | The compiled package's Better Auth client, slice, and base query against a real example-backend | `bun run --cwd rtk smoke` |
+| E2E | Sign-in, session, and SDK queries seen by a user, through example-frontend's Playwright suite against example-backend | `bun run frontend:e2e` |
+| Manual regression | Cases in `docs/regression/` | none |
+
+## The smoke
+
+[`rtk/e2e/smoke.ts`](https://github.com/TerrenoLabs/terreno/blob/master/rtk/e2e/smoke.ts)
+runs at the `http` layer. It starts example-backend with `spawnExampleBackend()` against
+`smokeMongoUri()` (Better Auth is the backend's default provider), sets `EXPO_PUBLIC_API_URL` to
+the backend's URL, and then imports the compiled `@terreno/rtk` in the smoke's own Bun process.
+It builds a store the way a web app in bearer mode does:
+
+- `createBetterAuthClient({webAuth: "bearer"})` with an in-memory `bearerStorage`, because Bun
+  has no `window.localStorage`.
+- `setTokenSource(betterAuthAdapter(bridgeBetterAuthReactClient(client), {getBearerToken}))`,
+  the adapter from example-frontend's `store/syncdb.ts`, registered as in its `store/index.ts`.
+- `generateBetterAuthSlice` and `emptySplitApi` with one injected `getMe` query on `/auth/me`.
+
+Then it checks:
+
+1. A new user signs up and signs in through the Better Auth client, and the client stores the
+   bearer token from the sign-in response.
+2. `syncSession` puts that user in the `betterAuth` slice (`isAuthenticated`, matching email).
+3. The `getMe` query, sent by rtk's base query with the registered token source, returns the
+   signed-in user's email from `/auth/me`. Without `setTokenSource` this check fails.
+
+Each check prints one `✅` line. The smoke exits 1 on the first failure, after printing the
+backend's output. The email carries the run's timestamp, so runs against the shared CI Mongo do
+not collide.
+
+### Native-module shims
+
+rtk targets React Native, and its package root loads modules that cannot run in Bun. The smoke
+runs in Bun anyway, with `mock.module` shims installed before it imports the package:
+
+- [`rtk/test-preload.ts`](https://github.com/TerrenoLabs/terreno/blob/master/rtk/test-preload.ts),
+  the shims rtk's unit tests already use: `react-native` (`Platform.OS` is `"web"`, plus
+  `AppState`, `Linking`, `StyleSheet`), `expo-secure-store`,
+  `@react-native-async-storage/async-storage`, `expo-constants`, and `expo-network`.
+- `@terreno/ui`, a `useToast` stub: `socket.ts` imports it, and the smoke never calls it.
+- `expo-linking`, a `createURL` stub: the real `@better-auth/expo/client` plugin imports it for
+  social sign-in deep links. The unit tests mock that plugin whole; the smoke runs it.
+
+Because `Platform.OS` is `"web"`, the smoke proves the web bearer path, not the native
+SecureStore cookie-jar path. Native sign-in stays covered by the unit tests and example-frontend
+on a device.
+
+**Measured time:** 15–18 s in three root `bun run smoke` runs (the [guide's](../e2e.md#package-pages) figure), against a running replica-set Mongo
+(`TERRENO_TEST_MONGODB_URI`), excluding the compile. Single runs on a loaded container took up
+to 50 s. Almost all of it is example-backend booting until `/health` answers 200;
+the rtk checks take under a second. The first boot against a fresh database also runs
+example-backend's startup work and took about 70 s in a slow-I/O sandbox, so the smoke allows
+120 s for readiness. Budget: 30 s. A warm boot fits it; a slow or cold boot goes over, and the
+overage is `spawnExampleBackend()` readiness, which the other client smokes (syncdb,
+admin-frontend) share. The rtk checks themselves are not the cost.
+
+## Add an e2e test
+
+- **New rtk behavior** (a slice action, a base-query rule, a client option): add a unit test in
+  `rtk/src/`. The smoke stays one happy path; do not add edge cases to it.
+- **The smoke's happy path changed** (for example, `createBetterAuthClient`, `setTokenSource`, or
+  the base query's token-source path): update the checks in `rtk/e2e/smoke.ts` and keep it
+  within 30 s.
+- **The package root loads a new native module:** add its shim to the smoke's `loadRtk`, or to
+  `test-preload.ts` when the unit tests need it too, and list it above.
+- **A user-visible auth or SDK flow:** add a Playwright spec in `example-frontend/e2e/`, following
+  [Write a Playwright spec](../e2e.md#write-a-playwright-spec).

package/dist/docs/versioned/57.21.0/testing/e2e/syncdb.md

@@ -0,0 +1,79 @@
+# @terreno/syncdb e2e tests
+
+Run the syncdb smoke after a compile:
+
+```bash
+bun run compile && bun run --cwd syncdb smoke   # or, from the root: bun run smoke syncdb
+```
+
+## Test tiers
+
+| Tier | What it covers | Command |
+| --- | --- | --- |
+| Unit and integration | The TinyBase store, outbox, replay, conflicts, delta applier, snapshot bootstrap, query windows, persisters, encryption codecs, the Better Auth adapter, and the React hooks, against `createFakeTransport` and fake IndexedDB (`src/**/*.test.ts`). The real socket and HTTP protocol against an in-process server is covered by `api/src/sync/integration.test.ts` | `bun run --cwd syncdb test` |
+| Smoke | Two clients built from the compiled package sync one todo through a real example-backend child process | `bun run --cwd syncdb smoke` |
+| E2E | The synced todos screens in Chromium (offline outbox, conflicts, storage, chaos, load) through example-frontend's `syncdb-*.spec.ts` Playwright suite against example-backend | `bun run frontend:e2e` |
+| Manual regression | Cases in `docs/regression/` | none |
+
+## The smoke
+
+[`syncdb/e2e/smoke.ts`](https://github.com/TerrenoLabs/terreno/blob/master/syncdb/e2e/smoke.ts)
+runs at the `http` and websocket layer. It starts example-backend with `spawnExampleBackend()`
+against `smokeMongoUri()`, so it never imports `@terreno/api`. It imports `@terreno/syncdb` by
+package name, which resolves to `dist/`. Then it:
+
+1. Signs a new user up through `POST /api/auth/sign-up/email`, then signs the same user in
+   again through `POST /api/auth/sign-in/email`, giving two Better Auth sessions, as two devices
+   would have.
+2. Builds client A and client B with `createSyncDb` for the `todos` collection. Each uses the
+   default socket transport and HTTP channel, the memory persister, `debug: true`, and
+   `betterAuthAdapter` over a small client that reads `GET /api/auth/get-session` with its own
+   bearer token.
+3. Starts both clients and waits until each one settles: its debug log has a
+   `subscribe catch-up` pass for its `todos|owner:{userId}` stream, and `isSyncing` is false.
+4. Client A calls `mutate()` to create a todo, and the smoke waits until the server acks it: the
+   local row has a server `seq` and no pending mutation.
+5. Within 5 s of client A's write, client B's debug log has a `delta` event for that todo, and
+   B's local store holds it with its title and a server `seq`.
+
+It prints one `✅` line per check and exits 1 on the first failure, after printing the backend's
+output. Settling first means B's startup reconcile and subscribe catch-up are done before the
+write, and the periodic reconcile is off (`reconcileIntervalMs: 0`). The `delta` event is
+recorded only when a socket delta is applied, so step 5 fails if B gets the todo from an HTTP
+snapshot page instead. A client B signed in as a different user never receives the todo and
+also fails at step 5; that case proves owner scoping, not the socket path. Each run uses a new
+email and todo title, so reruns against a shared `TERRENO_TEST_MONGODB_URI` never collide.
+
+**Measured time:** 14–16 s against an external replica set on an idle container (passing runs
+took 13.8, 14.5 and 15.9 s), excluding the compile. Booting example-backend takes most of it.
+Settling takes about 0.5 s, and delivery from A to B took 110–720 ms. On a 4-core container
+shared with other builds and type checks, passing runs took 38–60 s, and two runs missed
+`spawnExampleBackend()`'s 60 s readiness timeout before the backend answered `/health`. The
+in-memory replica set did not start within 60 s on that container. Budget: 30 s.
+
+If the in-memory replica set times out waiting for a primary, point the smoke at a running
+replica set the way CI does:
+
+```bash
+TERRENO_TEST_MONGODB_URI="mongodb://127.0.0.1:27017/?replicaSet=rs0" bun run --cwd syncdb smoke
+```
+
+A mongod with less than 500 MB of free disk refuses example-backend's index builds
+(`available disk space ... is less than required minimum`). Free disk space, or lower
+`indexBuildMinAvailableDiskSpaceMB` on a scratch mongod.
+
+## Add an e2e test
+
+- **New store, outbox, conflict, or query behavior:** add a test in `syncdb/src/` against
+  `createFakeTransport`. The smoke stays one happy path; do not add edge cases to it.
+- **The sync protocol changed** (socket events, `/sync/snapshot`, ack shape, or stream keys):
+  add a case to `api/src/sync/integration.test.ts`, and update the checks in
+  `syncdb/e2e/smoke.ts` if the two-client path changed. Keep it within 30 s.
+- **A user-visible sync flow:** add a Playwright spec next to the `syncdb-*.spec.ts` files in
+  `example-frontend/e2e/`, following [Write a Playwright spec](../e2e.md#write-a-playwright-spec).
+  Open the screen with `openSyncTodos(page)` and call `allowSyncDbNoise(consoleGuard)` from
+  `e2e/helpers/syncdbSuite.ts`.
+
+See [the syncdb reference](../../reference/syncdb.md) for the client API,
+[Local-first data](../../explanation/local-first-data.md) for the design, and
+[the `@terreno/test` reference](../../reference/test.md#smoke-helpers) for the smoke helpers.

package/dist/docs/versioned/57.21.0/testing/e2e/test.md

@@ -0,0 +1,51 @@
+# E2E testing `@terreno/test`
+
+`@terreno/test` is the helper package every other package's smoke imports, so its own e2e test
+is one real-process smoke that proves those helpers work outside `bun test`.
+
+## Run it
+
+```bash
+bun run compile                # builds test/dist, which the smoke imports
+bun run --cwd test smoke       # or, from the root: bun run smoke test
+```
+
+It takes 2.5–3 s in three root `bun run smoke` runs (the [guide's](../e2e.md#package-pages) figure), and about 12 s as a single warm run that loads the package
+cold. The first run on a machine also downloads or unpacks the
+`mongod` binary for the in-memory replica set, which can add 20 s or more.
+
+## What it proves
+
+`test/e2e/smoke.ts` imports `@terreno/test` by package name, so it runs against the built
+`dist/` output, not the sources. It checks, in order:
+
+1. **Replica set.** `smokeMongoUri({databaseName: "testSmoke"})` returns a URI for that
+   database. A Mongoose connection to it opens a change stream filtered to one marker value,
+   inserts a document with that marker, and receives the insert as a change event within 10 s. Change streams need a
+   replica set, so a standalone `mongod` fails here.
+2. **Readiness.** `spawnUntilReady` starts a child process (the same file re-run with
+   `serve`) that runs a plain `Bun.serve` HTTP server. The child answers its first three
+   `/ready` requests with 503, then answers 200 with its pid and how many 503s it served. The
+   smoke checks that the child served all three 503s (so `spawnUntilReady` kept polling past
+   them), that a follow-up `GET /ready` answers 200, and that the answering pid is the
+   `pid` that `spawnUntilReady` returned.
+3. **Teardown.** After `stop()`, the child no longer answers on its port.
+
+The smoke exits 0 when every check passes. It exits 1 on the first failure and prints the
+child's output when the child was involved.
+
+## In CI
+
+Set `TERRENO_TEST_MONGODB_URI` to a replica-set URI (the CI Mongo sidecar) and the smoke uses
+it instead of starting an in-memory replica set. With a standalone (non-replica-set) Mongo
+there, check 1 fails, which is the intended signal.
+
+## Changing it
+
+- Keep the smoke on the package's public exports from `@terreno/test`. Testing an internal
+  module belongs in `test/src/smoke/smoke.test.ts`.
+- When a new smoke helper is added to `@terreno/test`, add a check for it here only if other
+  packages' smokes depend on it outside a server (for example a new process or database
+  helper).
+
+See [the `@terreno/test` reference](../../reference/test.md#smoke-helpers) for the helper APIs.

package/dist/docs/versioned/57.21.0/testing/e2e/ui.md

@@ -0,0 +1,68 @@
+# @terreno/ui e2e tests
+
+Run the ui smoke after a compile and the demo web export, with Playwright's Chromium installed:
+
+```bash
+bun run compile && bun run --cwd demo export && bun run --cwd ui smoke
+```
+
+## Test tiers
+
+| Tier | What it covers | Command |
+| --- | --- | --- |
+| Unit and integration | Components, hooks, and theming with `@testing-library/react-native` (`src/**/*.test.tsx`) | `bun run --cwd ui test:ci` |
+| Chart snapshots | Rendered chart PNGs compared with the committed snapshots in `demo/rendered-snapshots/` | `bun run ui:charts:compare` |
+| Smoke | The compiled components, bundled into the demo web export, responding to input in Chromium | `bun run --cwd ui smoke` |
+| E2E (web flows) | Maestro web flows against the served demo export (`.maestro/flows/demo/`) | `bun run maestro:demo` |
+| Manual regression | Cases in `docs/regression/` | none |
+
+## The smoke
+
+[`ui/e2e/smoke.spec.ts`](https://github.com/TerrenoLabs/terreno/blob/master/ui/e2e/smoke.spec.ts)
+runs at the `browser` layer. @terreno/ui ships components, not a server or a binary, so the
+smoke drives them where they render on the web: the demo's static export (`demo/dist/`), which
+bundles the compiled package. The one file has two roles.
+
+Run with Bun (`bun e2e/smoke.spec.ts`), it is the driver:
+
+1. It exits 1 at once when `demo/dist/index.html` is missing and asks for `bun run --cwd demo
+   export`. It does not check that the export is newer than `ui/dist`, so re-export after each
+   compile, as the command above does.
+2. It re-runs itself with a `serve` argument through `spawnUntilReady()`. That child is a static
+   file server for `demo/dist/` on a `freePort()`, with clean URLs (`/dev/Button` serves
+   `dev/Button.html`) and no SPA rewrite, as the deployed demo is served.
+3. It runs the root-locked Playwright CLI on Node against this same file, passing the server URL
+   in `UI_SMOKE_BASE_URL`. There is no Playwright config, so the default Chromium project runs
+   only this spec. Traces and screenshots go to a temp dir that the driver deletes.
+
+Loaded by Playwright, the file defines one test. It opens three single-story routes
+(`/dev/<component>?story=<story>`) and waits for each one's `demo-preview-root`:
+
+| Component | Story | What the test does |
+| --- | --- | --- |
+| Button | `Button` → `Loading` | Presses `button-loading-async`, whose `onClick` returns a 2 s promise. The button's spinner (`progressbar`) appears, then goes once the promise settles. |
+| TextField | `Text field` → `Text Field with Helper Text` | Types into `demo-text-field` key by key and checks that the controlled input holds the text. |
+| Modal | `Modal` → `Modals` | Presses `modal-demo-open-default`. `modal-demo.title` appears; pressing `modal-demo.primary` dismisses the modal. |
+
+The driver prints one `✅` line per step and exits 1 on the first failure, after printing the
+static server's output and Playwright's report.
+
+The smoke needs Chromium (`bunx playwright install chromium`) but no backend, database, or
+secrets.
+
+**Measured time:** 8.5–9 s across three runs on a 4-CPU container, excluding the compile and
+the demo export. The CircleCI `smoke` job prints each package's time on every run. Budget: 30 s.
+
+## Add an e2e test
+
+- **A component's behavior changed:** add a unit test next to it in `ui/src/`. The smoke stays
+  one happy path; do not add edge cases to it.
+- **Button, TextField, or Modal changed what a press, a keystroke, or a dismiss shows:** update
+  the assertions in `ui/e2e/smoke.spec.ts` and keep it within 30 s.
+- **A story the smoke uses changed:** keep the testIDs above on the story in `demo/stories/`
+  (`Button.stories.tsx`, `TextField.stories.tsx`, `Modal.stories.tsx`), or move the smoke to a
+  story that has them.
+- **A web flow across several components:** add a Maestro flow to `.maestro/flows/demo/`. Follow
+  [Write a Maestro flow](../e2e.md#write-a-maestro-flow).
+
+See [the `@terreno/test` reference](../../reference/test.md#smoke-helpers) for the smoke helpers.

package/dist/docs/versioned/57.21.0/testing/e2e.md

@@ -0,0 +1,282 @@
+# E2E testing guide
+
+Run every package smoke from the repo root, with the builds they test and Playwright Chromium:
+
+```bash
+bun run smoke:local
+```
+
+It runs `bun run compile`, `admin-spa build:web`, `demo export`, `example-frontend
+export:smoke`, and `bunx playwright install chromium`, then `bun run smoke`. Once those builds
+exist, `bun run smoke` alone reruns the smokes.
+
+This guide covers how Terreno builds and writes end-to-end tests: the test tiers, where each
+kind of spec lives, how specs find elements and wait, and the command that runs them. Each
+package has its own page under [Package pages](#package-pages). Implementation plans cite this
+guide in their `## E2E tests` section, and Pick writes each planned spec the way this page
+describes.
+
+## Test tiers
+
+Each tier answers a question the tier below it cannot. Add a test to the lowest tier that can
+prove the behavior.
+
+| Tier | Proves | Runs in | Lives in | Command |
+| --- | --- | --- | --- | --- |
+| Unit and integration | Functions, routes, and components behave, in-process | `bun test`, in-memory Mongo | `<package>/src/**/*.test.ts(x)` | `bun run --cwd <package> test:ci` |
+| Smoke | The package's built output works through its public entry in a real process | A child process, a real port, the compiled binary, or Chromium | `<package>/e2e/smoke.ts` or `smoke.spec.ts` | `bun run --cwd <package> smoke` |
+| E2E | A user flow works across the running frontend and backend | Playwright (browser) or Maestro (flow) | `<package>/e2e/*.spec.ts`, `.maestro/flows/` | `bun run frontend:e2e`, `bun run maestro:test` |
+| Manual regression | A short check that the app works as intended, plus what automation cannot reach: push notifications and other hardware or OS behavior, full flows across devices, how the app feels | A developer or QA, before a release | `docs/regression/<area>.md` | none |
+
+Unit tests are the default. A smoke exists once per package, not once per feature. A new e2e
+spec is for a user-visible flow that crosses the frontend and backend. Automate first. Most
+features add no manual case: add one only for a check no automated tier can make and no
+existing case covers. A developer or QA walks them.
+
+## Layers
+
+An IP's `## E2E tests` rows name one of these layers.
+
+| Layer | Spec location | Finds elements by | Waits for | Runs with |
+| --- | --- | --- | --- | --- |
+| `http` | `<package>/e2e/smoke.ts` | Response status and body | `spawnUntilReady` on a health URL | `bun run --cwd <package> smoke` |
+| `process` | `<package>/e2e/smoke.ts` | Exit code, stdout, stderr | The process to exit (`runBin`) | `bun run --cwd <package> smoke` |
+| `browser` | `<package>/e2e/*.spec.ts` | `getByTestId()` | A visible `testID` | `bun run --cwd <package> test:e2e`, or `smoke` for `smoke.spec.ts` |
+| `native flow` | `.maestro/flows/*.yaml` | `id:` (the `testID`) | `extendedWaitUntil` on a visible `id` | `bun run maestro:test` |
+
+Terreno's Maestro flows run against the web build today: each starts with a `url:` header. A
+flow on a simulator, emulator, or device starts with an `appId:` header instead and runs with
+`maestro --device <serial> test <flow.yaml>`. The repo has no device flows yet.
+
+## Smoke conventions
+
+A smoke follows one rule: **real process, built output, one happy path, about 30 s excluding
+the build.**
+
+- **Real process.** Start a server on a real port, run the compiled binary, or drive a page in
+  Chromium. Do not import the package into the test process and call it. That duplicates the
+  unit suite.
+- **Built output.** Run against the result of `bun run compile` (or the web export for browser
+  packages) through the package's public entry, the way a consumer gets it. Import the package
+  by name (`@terreno/<package>`), never from `../src`.
+- **One happy path.** Walk the package's main use once and throw on the first wrong response.
+  Edge cases belong in unit tests.
+- **About 30 s.** Each smoke finishes in 30 s or less, not counting the build. The CircleCI
+  `smoke` job's results table judges the budget. `bun run smoke` marks a package over 30 s with
+  `⏱ over 30 s budget` but does not fail it, because local times swing with machine load (see
+  [Package pages](#package-pages)). A package over budget on CI gets fixed.
+
+| Item | Convention |
+| --- | --- |
+| File | `<package>/e2e/smoke.ts`; browser packages use `<package>/e2e/smoke.spec.ts` |
+| Script | `"smoke"` in `<package>/package.json` (for example `"smoke": "bun e2e/smoke.ts"`) |
+| Lint | Add `./e2e` to the package's `lint` and `lint:fix` scripts and `e2e/**/*.ts` to its `biome.jsonc` `files.includes`, as api does |
+| Browser smoke | Serves the static web export (`dist/`), not Metro, and runs under its own Playwright config so the package's main e2e suite and its CI shards never pick it up |
+| Helpers | `freePort`, `smokeMongoUri`, `spawnUntilReady`, `spawnExampleBackend`, `runBin` from `@terreno/test` ([reference](../reference/test.md#smoke-helpers)) |
+| Mongo | `smokeMongoUri()`: the CI sidecar when `TERRENO_TEST_MONGODB_URI` is set, otherwise an in-memory replica set |
+| Client packages | rtk, syncdb, and admin-frontend use `spawnExampleBackend()` and never import `@terreno/api` |
+| Output | One `✅` line per check, then `<package> smoke passed in <ms> ms`; exit 1 on the first failure |
+| Root runner | `bun run smoke` runs every workspace's `smoke` one at a time and prints each time; `bun run smoke api rtk` runs a subset |
+| Package page | `docs/testing/e2e/<package>.md`, linked from [Package pages](#package-pages) |
+
+A server smoke hosts its own server by re-running its file with a `serve` argument, so each
+package keeps one smoke file. [`api/e2e/smoke.ts`](https://github.com/TerrenoLabs/terreno/blob/master/api/e2e/smoke.ts)
+is the reference. A browser smoke that needs a backend works the same way: Bun runs
+`smoke.spec.ts` as the driver, starts the server, then runs Playwright on Node against the same
+file, which defines the browser test. [`admin-frontend/e2e/smoke.spec.ts`](https://github.com/TerrenoLabs/terreno/blob/master/admin-frontend/e2e/smoke.spec.ts)
+is the reference.
+
+## Write a Playwright spec
+
+Playwright specs drive the web build in Chromium. example-frontend holds the main suite;
+admin-spa has its own.
+
+1. Give the screen's root `View` a `testID`, and give every element the spec touches or asserts
+   on a `testID`: buttons, inputs, error text, loading indicators, and list items (with
+   dynamic IDs such as `todo-item-{id}`). Name them `{screen}-{element}-{qualifier}`, for
+   example `login-screen-email-input`.
+2. Create `e2e/<feature>.spec.ts`. Import `test` and `expect` from `./fixtures/test`, not
+   `@playwright/test`: its `consoleGuard` fails a test that logs an unexpected `console.warn`,
+   `console.error`, or page error. Group tests with `test.describe()` and name each test as a
+   user behavior.
+3. Pick the user. A spec that creates or clears data owns a per-suite user: add one with
+   `suiteUser(...)` in `e2e/fixtures/testUsers.ts` and list it in `ALL_E2E_USERS` so
+   `auth.setup.ts` creates it. `TEST_USER` is reserved for `todos.spec.ts` and the suites that
+   change no todos.
+4. In `test.beforeEach()`, reset that user's data (`clearTodosAs(user)` from
+   `e2e/helpers/todosApi.ts`), then sign in with `loginAs(page, user)` from
+   `e2e/helpers/login.ts`. On a syncdb screen, call `allowSyncDbNoise(consoleGuard)` and open the
+   screen with `openSyncTodos(page)` from `e2e/helpers/syncdbSuite.ts`.
+5. After each navigation or action, wait for the element that proves the new state.
+6. Add the spec's base name to a shard's `specs` in `scripts/ci/e2eAffected/shards.ts`, plus any
+   new screen it drives to that shard's `routes`, and to the same group in
+   `.circleci/continue-config.yml` (`run_example_frontend_e2e`). Otherwise CI never runs it.
+   `bun test scripts/ci/e2eAffected/` checks the shard lists.
+
+```typescript
+import {expect, test} from "./fixtures/test";
+import {DUE_DATE_USER} from "./fixtures/testUsers"; // this spec's suiteUser() from step 3
+import {loginAs} from "./helpers/login";
+import {allowSyncDbNoise, openSyncTodos, todoItemByTitle} from "./helpers/syncdbSuite";
+import {clearTodosAs} from "./helpers/todosApi";
+
+test.describe("Todos", () => {
+  test.beforeEach(async ({page, consoleGuard}) => {
+    allowSyncDbNoise(consoleGuard);
+    await clearTodosAs(DUE_DATE_USER);
+    await loginAs(page, DUE_DATE_USER);
+    await openSyncTodos(page);
+  });
+
+  test("user can create a todo", async ({page}) => {
+    await page.getByTestId("todos-title-input").fill("Buy milk");
+    await page.getByTestId("todos-create-button").click();
+    await expect(todoItemByTitle(page, "Buy milk")).toBeVisible();
+    await expect(page.getByTestId("todos-title-input")).toHaveValue("");
+  });
+});
+```
+
+| Do | Don't |
+| --- | --- |
+| `getByTestId()` first, `getByRole()` for third-party components | Select by class name; React Native Web's `.css-*` classes change every build |
+| `waitFor({state: "visible"})` on the target, or wait for a spinner to hide | `waitForTimeout()` |
+| Keep each test independent, with its own data | Depend on another test's state |
+| `getByText()` only for text you assert on | Deep structural selectors such as `div > div > div` |
+
+React Native Web renders `View` as `div`, `Pressable` as `div role="button"`, `TextInput` as
+`input` or `textarea`, and `Switch` as `div role="switch"` with `aria-checked`.
+
+Run the suite with `bun run frontend:e2e` (it starts the backend and the web app and needs a
+replica-set `mongod`). Run one file with `cd example-frontend && bunx playwright test
+e2e/todos.spec.ts`. CircleCI runs the specs in named shards (`auth`, `app`, `admin-core`, …),
+each a group of spec files, and skips a shard no changed file can reach. Check that verdict
+with `bun run check:e2e-affected`.
+
+## Write a Maestro flow
+
+Maestro flows walk the same `testID`s a user would. Terreno's flows run against the web build,
+locally and in CI.
+
+1. Add `.maestro/flows/<feature>.yaml` with a `url:` header. A standalone flow then starts with
+   `launchApp`. A flow that runs after `login` starts with no `launchApp`, because that resets
+   the session, and first waits for the screen `login` ends on (`todos-screen`).
+2. Find elements with `id:`, which matches the `testID`.
+3. Wait with `extendedWaitUntil` on a visible `id` and an explicit `timeout`, never a fixed
+   sleep.
+4. Add the file to `flows:` in `.maestro/flows/config.yaml`, or `bun run maestro:test` skips it.
+   When it runs after `login`, also add its name (without `.yaml`) to
+   `executionOrder.flowsOrder`.
+
+```yaml
+url: http://localhost:8082/login
+---
+- launchApp
+- extendedWaitUntil:
+    visible:
+      id: "login-screen-email-input"
+    timeout: 60000
+- tapOn:
+    id: "login-screen-email-input"
+- inputText: "admin@example.com"
+```
+
+Run every flow with `bun run maestro:test`, or the demo flows with `bun run demo:maestro:test`.
+Local runs need the running example-frontend on port 8082 (`bun run frontend:web`), and the demo
+flows need the demo's static export served on port 8085 (`bun run --cwd demo export`, then
+`bunx serve demo/dist -l 8085`, as CI does).
+
+## Where regression suites live
+
+Manual regression cases live in `docs/regression/<area>.md`, one living file per area with
+stable case IDs such as `AUTH-004`. An IP lists the cases it adds under `## Regression cases`,
+and Brew writes them into the suite with real IDs before it opens the PR. A case belongs there
+only when no unit test, smoke, or e2e spec can check it, and most features add none. To fill
+gaps from older features, run the `backfill-regression` skill: it proposes cases one area at
+a time and writes only the sets you approve.
+
+The [regression suites index](../regression/README.md) lists the areas, restates the suite
+format, and describes `bun run check:regression-suites`, which CI runs on every change to a
+suite.
+
+## Package pages
+
+Each package page covers the package's test tiers, its smoke, how to add an e2e spec to it,
+and the smoke's measured time. Every smoke's budget is 30 s, excluding the build.
+
+| Package | Smoke | Layer | Measured time |
+| --- | --- | --- | --- |
+| [`@terreno/admin-backend`](e2e/admin-backend.md) | `admin-backend/e2e/smoke.ts` | http | 5.5–12.5 s |
+| [`@terreno/admin-frontend`](e2e/admin-frontend.md) | `admin-frontend/e2e/smoke.spec.ts` | browser | 23–24.5 s (in-memory Mongo) |
+| [`@terreno/admin-spa`](e2e/admin-spa.md) | `admin-spa/e2e/smoke.ts` | http | 4–4.5 s |
+| [`@terreno/ai`](e2e/ai.md) | `ai/e2e/smoke.ts` | http | 7–7.5 s |
+| [`@terreno/announcements`](e2e/announcements.md) | `announcements/e2e/smoke.ts` | http | 4.5–8 s |
+| [`@terreno/api`](e2e/api.md) | `api/e2e/smoke.ts` | http | 5–10 s |
+| [`@terreno/api-health`](e2e/api-health.md) | `api-health/e2e/smoke.ts` | http | 2 s |
+| [`@terreno/blocks`](e2e/blocks.md) | `blocks/e2e/smoke.ts` | process | 1–1.5 s |
+| [`@terreno/cli`](e2e/cli.md) | `cli/e2e/smoke.ts` | process | 2 s |
+| [`@terreno/comms`](e2e/comms.md) | `comms/e2e/smoke.ts` | http | 5–6.5 s |
+| [`create-terreno-app`](e2e/create-terreno-app.md) | `create-terreno-app/e2e/smoke.ts` | process | 2.5 s |
+| [demo](e2e/demo.md) | `demo/e2e/smoke.spec.ts` | browser | 7.5–8 s |
+| [example-backend](e2e/example-backend.md) | `example-backend/e2e/smoke.ts` | http | 16–20 s |
+| [example-frontend](e2e/example-frontend.md) | `example-frontend/e2e/smoke.spec.ts` | browser | 22–26 s (in-memory Mongo) |
+| [`@terreno/feature-flags`](e2e/feature-flags.md) | `feature-flags/e2e/smoke.ts` | http | 5–5.5 s |
+| [`@terreno/jobs`](e2e/jobs.md) | `jobs/e2e/smoke.ts` | http | 7.5–8.5 s |
+| [`@terreno/mcp`](e2e/mcp-server.md) | `mcp-server/e2e/smoke.ts` | process, http | 5.5–6 s |
+| [`@terreno/rtk`](e2e/rtk.md) | `rtk/e2e/smoke.ts` | http | 15–18 s |
+| [`@terreno/syncdb`](e2e/syncdb.md) | `syncdb/e2e/smoke.ts` | http, websocket | 15–19 s |
+| [`@terreno/test`](e2e/test.md) | `test/e2e/smoke.ts` | http | 2.5–3 s |
+| [`@terreno/ui`](e2e/ui.md) | `ui/e2e/smoke.spec.ts` | browser | 8.5–9 s |
+
+The times are what `bun run smoke` printed for each package across three root runs (the runs
+after the first one after a compile, described below) on a 4-CPU container, against a
+single-node replica set (`TERRENO_TEST_MONGODB_URI`), after `bun run compile` and
+`bun run --cwd admin-spa build:web` (admin-spa's time is from the two runs after its build). Each package page
+records how its own time splits. The admin-frontend and example-frontend times come from
+separate runs of each smoke on an idle container, with the in-memory replica set. The demo and
+ui times come from three separate runs of each smoke on the same container, against an existing
+demo export.
+
+The first root run after a compile was slower for four packages: example-backend took 48 s,
+syncdb 33 s, and create-terreno-app 21 s, and comms failed because its server did not answer
+within its 20 s readiness timeout. All four were back within their usual times on the next run.
+Run on its own right after the same compile, example-backend took 27 s on an empty database, and
+ai and admin-backend took 5.5–7 s, though an earlier run after a compile had measured 41 s and
+31.5 s for them.
+
+Two causes outside the smokes were later measured on the same container, and either one stretches
+a smoke well past its budget:
+
+- **A compile running at the same time.** The agent `Stop` hook
+  (`.rulesync/hooks/quality-check.sh`) runs `bun run compile` at the end of each agent turn. That
+  keeps all four CPUs busy for about 4 minutes and rewrites `dist/` while smokes load it. In one
+  root run that overlapped it, api took 75 s and jobs 93 s; alone, they take 5.5–9 s and 8.5–12 s.
+  admin-spa's server also missed its 20 s readiness timeout once while the compile ran.
+- **Slow disk.** The in-memory replica set keeps its data under `TMPDIR`. When that disk slowed
+  to 20 MB fsyncs taking 2–122 s, mongod missed its 60 s start timeout in every later smoke.
+  `dd if=/dev/zero of=$TMPDIR/ddtest bs=1M count=20 conv=fsync` shows whether this is the cause.
+
+Time smokes on an otherwise idle machine. A smoke that is over budget only under one of these
+conditions is not a regression. Full local runs on that container still put a different package
+over 30 s each time (admin-frontend 44.7 s in one run; example-frontend 89.8 s and feature-flags
+30.3 s in the next), while admin-frontend alone took 22.4–25.2 s. That noise is why the CI table,
+not a local run, decides the budget.
+
+A browser smoke that fails with `Executable doesn't exist` before it loads a page means the
+machine's preinstalled Playwright browsers are a different build from the Playwright version
+the repo locks. Install the matching Chromium under your home directory and run the smokes with
+the same variable:
+
+```bash
+PLAYWRIGHT_BROWSERS_PATH=$HOME/.cache/ms-playwright bunx playwright install chromium
+PLAYWRIGHT_BROWSERS_PATH=$HOME/.cache/ms-playwright bun run smoke
+```
+
+Manual cases that no smoke or e2e spec can check live in the
+[regression suites](../regression/README.md).
+
+## Related
+
+- [Run tests locally](../how-to/run-tests-locally.md): the local command for every CI job
+- [`@terreno/test` smoke helpers](../reference/test.md#smoke-helpers)
+- [Test isolation in Bun suites](../explanation/test-isolation.md)

package/dist/docs/versioned/57.21.0/tutorials/README.md

@@ -0,0 +1,11 @@
+# Tutorials
+
+Learning-oriented, hands-on lessons. Start here if you are new to Terreno.
+
+## Contents
+
+- [Getting started](getting-started.md) — Scaffold a new app with `create-terreno-app`, run it locally, or explore monorepo examples
+
+## Next steps
+
+- [Set up Terreno MCP](../how-to/set-up-terreno-mcp.md) — Connect your editor to the hosted `terreno` server and the local `terreno-mcp-local` server (logs, last error, client state, database)

package/dist/docs/versioned/57.21.0/user-guide/README.md

@@ -0,0 +1,25 @@
+# User guide
+
+The end-user guide for the example app: one page per feature, in the words users see on
+screen, which chat agents read to answer "how do I…" questions.
+
+Run `bun run check:user-guide` after you edit a page. The page format, frontmatter, and
+writing bar are in the planning plugin's
+[user-guide contract](../../plugins/terreno-planning/references/user-guide.md). To draft
+pages for features that shipped without one, run the `backfill-user-guide` skill.
+
+## Pages
+
+| Area | Page | Audience | Title |
+| --- | --- | --- | --- |
+| account | [sign-up.md](account/sign-up.md) | user | Create an account |
+| account | [sign-in.md](account/sign-in.md) | user | Sign in |
+| account | [reset-password.md](account/reset-password.md) | user | Reset your password |
+| account | [verify-email.md](account/verify-email.md) | user | Confirm your email address |
+| account | [profile.md](account/profile.md) | user | Update your profile |
+| account | [notification-preferences.md](account/notification-preferences.md) | user | Choose how you get notifications |
+| admin | [manage-records.md](admin/manage-records.md) | admin | Browse and edit records in the admin panel |
+| admin | [set-user-password.md](admin/set-user-password.md) | admin | Set a user's password |
+| ai | [chat.md](ai/chat.md) | user | Chat with the AI assistant |
+| documents | [files.md](documents/files.md) | user | Store and organize files |
+| todos | [manage-todos.md](todos/manage-todos.md) | user | Add, complete, rename, and delete todos |

package/dist/docs/versioned/57.21.0/user-guide/account/notification-preferences.md

@@ -0,0 +1,37 @@
+---
+title: Choose how you get notifications
+area: account
+audience: user
+platforms: [web, ios, android]
+questions:
+  - How do I turn off email notifications?
+  - How do I stop push notifications?
+  - Where are my notification settings?
+screens: [example-frontend/app/(tabs)/profile.tsx, example-frontend/app/settings/notifications.tsx]
+added: user-guide-backfill
+---
+
+# Choose how you get notifications
+
+## What it does
+
+Notification preferences decide which channels the app uses to reach you: the in-app
+inbox, email, push notifications, and text messages.
+
+## How to use it
+
+1. Open the **Profile** tab.
+2. Under **Session**, tap **Notification preferences**.
+3. Under **Notification preferences**, turn each channel on or off: **In-app inbox**,
+   **Email**, **Push**, and **SMS**.
+4. Tap **Back** when you are done. Changes save as you make them.
+
+## Intended use
+
+Turn off a channel you do not want to hear from. Every channel starts on. **Email** and
+**SMS** only send when your account has an address or phone number for them, and **Push**
+only reaches devices where you are signed in to the mobile app.
+
+## Related
+
+- [Update your profile](profile.md)