@terreno/agent-plugin 0.0.0-stage → 57.22.0

package/skills/terreno-data-fetching/references/auth-and-tokens.md

@@ -0,0 +1,93 @@
+# Auth and Tokens — Terreno
+
+## generateAuthSlice
+
+`generateAuthSlice(api)` from `@terreno/rtk` creates:
+
+- `authReducer` — tracks `userId`, `error`, `lastTokenRefreshTimestamp`
+- `logout` action — clears tokens from secure storage
+- `middleware` — stores tokens on login, removes on logout
+- Built-in endpoints: `emailLogin`, `emailSignUp`, `googleLogin`, `resetPassword`
+
+## Login
+
+```tsx
+import {useEmailLoginMutation} from "@/store/sdk";
+import {useSelectCurrentUserId} from "@terreno/rtk";
+
+const [login, {isLoading, error}] = useEmailLoginMutation();
+
+await login({email, password}).unwrap();
+// Tokens stored automatically; setUserId dispatched
+```
+
+## Logout
+
+```tsx
+import {useAppDispatch, logout} from "../store/index.ts";
+
+const dispatch = useAppDispatch();
+dispatch(logout());
+// Clears AUTH_TOKEN and REFRESH_TOKEN from storage
+```
+
+## Token storage
+
+- **Native:** `expo-secure-store` (encrypted)
+- **Web:** `@react-native-async-storage/async-storage` (SSR-safe wrapper)
+
+Never store tokens in plain AsyncStorage on native or in `EXPO_PUBLIC_*` env vars.
+
+## Token refresh
+
+`emptyApi` from `@terreno/rtk` automatically:
+
+- Refreshes access token when < 2 minutes from expiry
+- Retries failed requests after 401 with refreshed token
+- Uses a mutex to prevent concurrent refresh storms
+
+No manual refresh logic needed in app code.
+
+## Better Auth (optional)
+
+For apps using Better Auth instead of JWT/Passport:
+
+```tsx
+import {createBetterAuthClient, generateBetterAuthSlice, setTokenSource} from "@terreno/rtk";
+import {betterAuthAdapter, bridgeBetterAuthReactClient} from "@terreno/syncdb";
+
+const authClient = createBetterAuthClient({
+  baseURL: process.env.EXPO_PUBLIC_API_URL,
+  scheme: "myapp", // deep-link scheme, required
+});
+
+// {reducer, middleware, actions, slice, syncSession}; mount reducer at `betterAuth`
+const betterAuth = generateBetterAuthSlice({authClient});
+
+// One token source for syncdb and every rtk consumer, registered once at startup
+export const authProvider = betterAuthAdapter(bridgeBetterAuthReactClient(authClient));
+setTokenSource(authProvider);
+```
+
+With the source registered, `emptySplitApi` sends the Better Auth token, sends no
+`authorization` header when there is none, and logs out only after a 401 survives one
+`refresh()`. Do not fork the base query to read the session. Without `setTokenSource`, rtk
+uses the JWT tokens in storage (`jwtTokenSource`).
+
+Use `SocialLoginButton` from `@terreno/ui` for OAuth providers.
+
+## Current user
+
+```tsx
+import {useSelectCurrentUserId} from "@terreno/rtk";
+import {useReadProfile} from "@/hooks/useReadProfile"; // app-specific
+
+const userId = useSelectCurrentUserId();
+const {data: profile} = useReadProfile(); // GET /auth/me via sdk.ts
+```
+
+## Protected routes
+
+Gate navigation on `userId` in root `_layout.tsx`. Redirect unauthenticated users to `/login`.
+
+For admin routes, also check `user.admin === true` and redirect non-admins.

package/skills/terreno-data-fetching/references/realtime.md

@@ -0,0 +1,45 @@
+# Realtime — Terreno
+
+## Realtime sockets
+
+```tsx
+import {useSocketConnection, getAuthToken} from "@terreno/rtk";
+
+const {socket, isSocketConnected} = useSocketConnection({
+  baseUrl: "ws://localhost:4000",
+  shouldConnect: !!userId,
+  getAuthToken: () => getAuthToken(),
+});
+```
+
+Sockets auto-reconnect and refresh auth on token rotation.
+
+## Feature flags
+
+```tsx
+import {useTerrenoFeatureFlags} from "@terreno/rtk";
+
+useTerrenoFeatureFlags(terrenoApi, {
+  skip: !userId,
+  socket,
+  userId,
+});
+```
+
+Wrap children in `OpenFeatureProvider` (see `example-frontend/app/_layout.tsx`).
+
+## Server status
+
+```tsx
+import {useServerStatus} from "@terreno/rtk";
+
+const {isServerReachable} = useServerStatus();
+```
+
+Use to show degraded UI when the backend is unreachable.
+
+## Realtime model updates
+
+`modelRouter` `realtime` (RTK cache-patching via `realtimeList` / `realtimeDocument`) is **deprecated** and **will be removed in Terreno 58**. Use `sync` on `modelRouter` with `@terreno/syncdb`. `RealtimeApp` stays as the socket host.
+
+Do not add new `realtimeList` / `realtimeDocument` wiring. After adding `sync` to a backend model, use syncdb hooks on the client.

package/skills/terreno-data-fetching/references/sdk-customization.md

@@ -0,0 +1,84 @@
+# SDK Customization — Terreno
+
+## Generated vs hand-maintained
+
+| File | Editable? | Purpose |
+|------|-----------|---------|
+| `store/openApiSdk.ts` | **Never** | Auto-generated hooks from OpenAPI |
+| `store/sdk.ts` | **Yes** | Extensions, cache tags, custom endpoints |
+| `openapi-config.ts` | **Yes** | Codegen configuration |
+
+## injectEndpoints
+
+Add app-specific endpoints that are not in the OpenAPI spec (rare — prefer backend routes):
+
+```tsx
+import {openapi} from "./openApiSdk";
+
+export const terrenoApi = openapi
+  .injectEndpoints({
+    endpoints: (build) => ({
+      getMe: build.query({
+        query: () => "/auth/me",
+        providesTags: ["profile"],
+      }),
+      patchMe: build.mutation({
+        query: (body) => ({
+          url: "/auth/me",
+          method: "PATCH",
+          body,
+        }),
+        invalidatesTags: ["profile"],
+      }),
+    }),
+  })
+  .enhanceEndpoints({
+    addTagTypes: ["todos", "users", "profile"],
+  });
+```
+
+Import hooks from `@/store/sdk`, not `@/store/openApiSdk` directly.
+
+## Cache tags
+
+Use `enhanceEndpoints` to add tag types, then `providesTags` / `invalidatesTags` in injected endpoints:
+
+```tsx
+import {invalidatesIdTags, providesIdTags} from "@terreno/rtk";
+
+// In injectEndpoints:
+listItems: build.query({
+  query: (params) => ({url: "/items", params}),
+  providesTags: providesIdTags("items"),
+}),
+createItem: build.mutation({
+  query: (body) => ({url: "/items", method: "POST", body}),
+  invalidatesTags: invalidatesIdTags("items"),
+}),
+```
+
+## Codegen config
+
+```typescript
+// openapi-config.ts
+const config: ConfigFile = {
+  apiFile: "@terreno/rtk",
+  apiImport: "emptySplitApi",
+  outputFile: "./store/openApiSdk.ts",
+  schemaFile: "http://localhost:4000/openapi.json",
+  hooks: true,
+  tag: true,
+  flattenArg: true,
+};
+```
+
+Override schema URL with `OPENAPI_URL` env var when needed.
+
+## Workflow after backend change
+
+1. Start backend (`bun run backend:dev`)
+2. Run `cd example-frontend && bun run sdk`
+3. Import new hooks from `@/store/sdk`
+4. If the endpoint needs custom cache behavior, update `sdk.ts`
+
+See the `generate-sdk` skill for the full procedure.

package/skills/terreno-frontend-tests/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: terreno-frontend-tests
+description: >-
+  Write and fix frontend tests for a Terreno Expo app: Bun + React Native Testing Library unit
+  tests for components, screens, hooks, Redux/RTK and syncdb data, and Playwright web E2E for
+  flows across screens and the backend. Covers renderWithTerreno, testID selectors, mocking
+  data hooks without leaking module mocks, async waiting, and Playwright login/fixtures. Use
+  when adding or changing frontend behavior or when a frontend test fails. If the app has no
+  test preload or Playwright config, run terreno-test-setup first.
+---
+
+# Writing Terreno frontend tests
+
+## 1. Pick the layer
+
+| Behavior | Layer |
+|----------|-------|
+| Pure function, reducer, selector, formatter | Bun unit test, no rendering |
+| Component or screen renders states and reacts to input | Bun + React Native Testing Library |
+| Custom hook | `renderHook` with `createTerrenoWrapper` |
+| Flow across screens, real backend, auth, navigation, persistence | Playwright web E2E |
+| Native-only behavior (gestures, push, camera, deep links on device) | `terreno-mobile-tests` |
+
+Prefer the lowest layer that proves the behavior; add one E2E per user-visible flow, not per
+edge case.
+
+Done when: the test sits next to the code (`TodoList.tsx` → `TodoList.test.tsx`; E2E in
+`e2e/<feature>.spec.ts`).
+
+## 2. testIDs first
+
+Every element a test touches gets a `testID` in the component, named
+`{screen}-{element}-{qualifier}`: `todos-screen`, `todos-create-button`,
+`todo-item-${id}`, `login-screen-email-input`. Add missing IDs to the component before writing
+the test. Select by `testID` in both layers; fall back to role, then text.
+
+Always give testIDs to: each screen's root `Box`/`Page`, buttons and pressables, inputs, error
+and validation text, loading indicators, list containers, and list items (dynamic IDs).
+
+## 3. Component tests (Bun + RNTL)
+
+```tsx
+import {describe, expect, it, mock} from "bun:test";
+import {renderWithTerreno} from "@terreno/test/expo/renderWithTerreno";
+import {fireEvent} from "@testing-library/react-native";
+import {TodoForm} from "./TodoForm";
+
+describe("TodoForm", () => {
+  it("submits the trimmed title", async () => {
+    const onSubmit = mock((_title: string) => undefined);
+    const {findByTestId, getByTestId} = renderWithTerreno(<TodoForm onSubmit={onSubmit} />);
+    await findByTestId("todo-form");
+
+    fireEvent.changeText(getByTestId("todo-form-title-input"), "  Buy milk ");
+    fireEvent.press(getByTestId("todo-form-submit-button"));
+
+    expect(onSubmit).toHaveBeenCalledWith("Buy milk");
+  });
+
+  it("shows a validation error for an empty title", async () => {
+    const {findByTestId, getByTestId} = renderWithTerreno(<TodoForm onSubmit={mock()} />);
+    await findByTestId("todo-form");
+    fireEvent.press(getByTestId("todo-form-submit-button"));
+    expect(await findByTestId("todo-form-title-error")).toBeTruthy();
+  });
+});
+```
+
+- `renderWithTerreno(ui, {store?, theme?})` wraps in `TerrenoProvider` (and Redux `Provider`
+  with `store`). Use it instead of hand-wrapping.
+- Start every test with `await findByTestId("<root testID>")`: `TerrenoProvider` loads fonts
+  asynchronously, and querying synchronously before that settles logs
+  `not wrapped in act(...)` warnings.
+- Then `getBy*` for what is rendered, `findBy*` for what appears after an effect or promise,
+  `queryBy*` to assert absence.
+- Assert with `bun:test`'s `expect`: `expect(getByText("Buy milk")).toBeTruthy()`,
+  `within(getByTestId("todos-list")).getByText(...)`, `expect(queryByTestId(...)).toBeNull()`.
+  RNTL's extra matchers (`toHaveTextContent`, `toBeVisible`) run but do not type-check
+  against `bun:test`, so `tsc` fails on them.
+- Import order: `bun:test`, then `@terreno/*`, then `@testing-library/*`, then local files
+  (what Biome's `organizeImports` expects).
+- Interact with `fireEvent.press` / `fireEvent.changeText`; Terreno `Button` calls `onClick`
+  through `onPress`.
+- Cover each state the component has: loading, empty, error, populated, disabled.
+- Hooks: `renderHook(() => useThing(), {wrapper: createTerrenoWrapper({store})})` from
+  `@testing-library/react-native` and `@terreno/test/expo/renderWithTerreno`.
+
+## 4. Data in component tests
+
+Choose in this order:
+
+1. **Props.** Split data loading (container) from rendering (presentational) and test the
+   presentational component with literal props. Most screens need nothing else.
+2. **syncdb collections in screens.** Wrap the app's collection hooks in one module
+   (`store/syncDbSdk.ts` exporting `useTodos()` etc.) and mock that module in a preload with
+   controllable rows, the same way as RTK hooks below. Test syncing behavior itself (outbox,
+   conflicts, deltas) against a real client built with `createFakeTransport` from
+   `@terreno/syncdb/testing`; it also needs a fake `httpChannel`, a memory
+   `persisterFactory`, and an `authProvider` — copy the `makeHarness` pattern from
+   `node_modules/@terreno/syncdb/src/client.test.ts`.
+3. **Generated RTK hooks (`useGetXQuery`) and app modules.** Mock them **once in a preload**
+   (a second preload file after `testPreload.ts`) with controllable state, never with
+   `mock.module` inside a test file — module mocks last for the whole process and leak into
+   every later file:
+   ```typescript
+   // tests/sdkMocks.ts (preloaded)
+   import {mock} from "bun:test";
+   export const sdkState = {todos: [] as unknown[], isLoading: false};
+   const actualSdk = await import("@/store/sdk");
+   mock.module("@/store/sdk", () => ({
+     ...actualSdk,
+     useGetTodosQuery: () => ({data: {data: sdkState.todos}, isLoading: sdkState.isLoading}),
+   }));
+   ```
+   Tests set `sdkState` in `beforeEach`; reset it in the preload's `afterEach`.
+
+Auth tokens: `setAuthTokens({authToken: "token"})` / `clearAuthTokenStorage()` from
+`@terreno/test/expo/authTokenStorage` seed the in-memory SecureStore/AsyncStorage the preload
+installs (cleared after every test).
+
+## 5. Async, time, and isolation
+
+- Wait for UI with `findBy*` or RNTL's `waitFor`. For non-render conditions (mock calls,
+  store state, socket events) use `waitUntil` / `waitForCalls` from `@terreno/test`. Never
+  sleep with `setTimeout`.
+- Freeze the clock with `freezeTime("2024-06-01T10:30:00Z")` from `@terreno/test` (Date.now,
+  new Date, and Luxon together).
+- `spyOn` is restored after every test by the preload. `mock.module` is not — keep it in
+  preload files.
+- `terreno-test-hygiene` (from `@terreno/test`) flags module-scope `mock.module`, sleeps,
+  barrel mocks, and component snapshots; run it before pushing if the repo uses it.
+- Do not snapshot components (`toMatchSnapshot`): assert the text, testIDs, and props that
+  matter.
+
+## 6. Playwright web E2E
+
+```typescript
+import {expect, test} from "@playwright/test";
+import {loginAs} from "./helpers/login";
+
+test.describe("Todos", () => {
+  test.beforeEach(async ({page}) => {
+    await loginAs(page);
+    await page.getByTestId("todos-screen").waitFor({state: "visible"});
+  });
+
+  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(page.getByTestId("todos-list")).toContainText("Buy milk");
+  });
+});
+```
+
+Rules:
+
+- Select with `getByTestId()`; fall back to `getByRole()`; use `getByText()` sparingly (React
+  Native Web wraps text in extra elements). Never select by class name (`.css-abc123` changes
+  every build) or deep structure (`div > div > div`).
+- React Native Web renders `View` as `div`, `Text` as `div`/`span`, `Pressable` as
+  `div[role="button"]`, `TextInput` as `input`/`textarea`, `Switch` as `div[role="switch"]`
+  with `aria-checked`.
+- Never `page.waitForTimeout()`. After navigation, wait for the target screen's root testID to
+  be visible; after a fetch, wait for the content or for the spinner to be hidden; use
+  web-first assertions (`await expect(locator).toHaveText(...)`), which retry.
+- Log in through `loginAs(page)` in `test.beforeEach`, never inside a test body.
+- Group with `test.describe()`, navigate in `test.beforeEach()`, name tests as user behavior
+  (`"user can submit a valid form"`), and keep tests independent: each creates its own data
+  or uses its own fixture user from `e2e/fixtures/testUsers.ts`.
+- Seed through the API (`request.post`) in `beforeEach`/`auth.setup.ts`, not through the UI,
+  unless the UI path is what is under test.
+
+Run:
+
+```bash
+bunx playwright test e2e/todos.spec.ts --reporter=list
+bunx playwright test --ui                 # debug interactively
+bunx playwright show-trace test-results/<test>/trace.zip
+```
+
+## Checklist
+
+- [ ] Every touched element has a `{screen}-{element}-{qualifier}` testID
+- [ ] Each component state (loading, empty, error, populated) has a test
+- [ ] Data comes from props or a preload SDK/syncdb-hook mock — no `mock.module` in test
+      files
+- [ ] No sleeps, `waitForTimeout`, class selectors, or component snapshots
+- [ ] E2E logs in with `loginAs` in `beforeEach` and waits on screen root testIDs
+- [ ] `bun test` (and `bunx playwright test` for E2E changes) passes for the whole app
+- [ ] UI changes also get runtime evidence via `verify-ui-changes`

package/skills/terreno-mobile-tests/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: terreno-mobile-tests
+description: >-
+  Write and fix mobile tests for a Terreno Expo app on iOS and Android: Maestro flows that
+  drive the native app on a simulator or emulator, and Bun unit tests for Platform.OS-specific
+  code. Covers testID selectors on native, login subflows, waiting, platform branches,
+  keyboards and system dialogs, reaching the local backend from a device, and debugging flaky
+  flows. Use when a change affects native-only behavior (navigation gestures, push, deep
+  links, permissions, keyboard, platform branches) or a Maestro flow fails. If the app has no
+  Maestro setup, run terreno-test-setup first.
+---
+
+# Writing Terreno mobile tests
+
+## 1. Pick the layer
+
+| Behavior | Layer |
+|----------|-------|
+| Logic that branches on `Platform.OS` / `Platform.select` | Bun unit test run per platform (`TEST_PLATFORM=android bun test`) |
+| Component behavior identical on every platform | `terreno-frontend-tests` (Bun + RNTL), once |
+| Flow on a real device: navigation, keyboard, deep link, permission prompt, push tap, app restart | Maestro flow |
+| Same flow in a browser | Playwright (`terreno-frontend-tests`) |
+
+Done when: you named the layer and, for Maestro, which platforms (iOS, Android, or both) the
+flow must pass on.
+
+## 2. Platform unit tests
+
+The preload fixes `Platform.OS` per run (see `terreno-test-setup`). Write the test once and
+assert the branch for the current platform:
+
+```typescript
+import {describe, expect, it} from "bun:test";
+import {Platform} from "react-native";
+import {keyboardOffset} from "./layout";
+
+describe("keyboardOffset", () => {
+  it("uses the platform's offset", () => {
+    expect(keyboardOffset()).toBe(Platform.OS === "ios" ? 64 : 0);
+  });
+});
+```
+
+Run `bun test` and `bun run test:android` (and `test:web` if the code has a web branch).
+
+## 3. Maestro flows
+
+Write a flow per user goal, under `maestro/`, reusing subflows for login and navigation:
+
+```yaml
+appId: ${APP_ID}
+---
+# Creates a todo and sees it in the list after an app restart.
+- launchApp:
+    clearState: true
+- runFlow: subflows/login.yaml
+- extendedWaitUntil:
+    visible:
+      id: "todos-screen"
+    timeout: 30000
+- tapOn:
+    id: "todos-title-input"
+- inputText: "Buy milk"
+- hideKeyboard
+- tapOn:
+    id: "todos-create-button"
+- assertVisible: "Buy milk"
+- stopApp
+- launchApp
+- extendedWaitUntil:
+    visible: "Buy milk"
+    timeout: 30000
+```
+
+Rules:
+
+- **Select by `id:`** (the React Native `testID`). Fall back to visible text only for system
+  UI and text you are asserting. Never select by coordinates or index.
+- **Wait for screens** with `extendedWaitUntil: {visible: {id: "<screen>-screen"}, timeout}`
+  after launch and every navigation. Never use fixed `waitForAnimationToEnd` chains or sleeps
+  as the main wait.
+- **Keyboards**: `hideKeyboard` after `inputText` before tapping something the keyboard may
+  cover.
+- **Fresh state**: `launchApp: {clearState: true}` at the start of a flow that must not depend
+  on a previous run; seed data through the backend (seed script or API) rather than the UI.
+- **Per-platform steps** with `runFlow: {when: {platform: Android}, commands: [...]}`: Android
+  has a system `back`; iOS does not (navigate with the app's back button testID instead).
+- **System dialogs** (permissions, iOS "Save Password?") are optional and platform-specific:
+  ```yaml
+  - runFlow:
+      when:
+        visible: "Not Now"
+      commands:
+        - tapOn: "Not Now"
+  ```
+- **Secrets and IDs** come from `-e` env vars (`${APP_ID}`, `${EMAIL}`, `${PASSWORD}`), never
+  hard-coded.
+- One goal per flow; `maestro/config.yaml` lists them in order for CI.
+
+## 4. Run and debug
+
+```bash
+maestro test -e APP_ID=com.<org>.<app> -e EMAIL=... -e PASSWORD=... maestro/todos.yaml
+maestro --device <udid|emulator-serial> test ...   # pick a device when several are booted
+maestro hierarchy                                  # dump the screen: confirm a testID exists
+maestro studio                                     # build steps interactively
+```
+
+| Symptom | Cause and fix |
+|---------|---------------|
+| `Element not found` for an `id:` | The component does not forward `testID`, or the element is off-screen: check `maestro hierarchy`, add `testID`, or `scrollUntilVisible` |
+| App shows a network error | Backend unreachable: Android needs `adb reverse tcp:4000 tcp:4000` (and `tcp:8081` for Metro) after every emulator start |
+| Passes on iOS, fails on Android | Keyboard covering the target (`hideKeyboard`), or a step that relies on iOS-only UI |
+| First run on a fresh emulator times out | Maestro's driver install is slow the first time; rerun once |
+| Red screen / stale bundle | Metro not running or serving another app: restart `expo start` for this app |
+
+Save a screenshot on failure for the PR with `takeScreenshot: <name>` before the failing step,
+or capture with `xcrun simctl io booted screenshot` / `adb exec-out screencap -p > shot.png`.
+
+## Checklist
+
+- [ ] Platform branches have unit tests that run under each platform they branch on
+- [ ] Each Maestro flow targets one user goal, starts from `clearState`, and seeds data via the
+      backend
+- [ ] Every step selects by `id:` (testID) except system dialogs and asserted text
+- [ ] Screens are awaited with `extendedWaitUntil`; no sleeps
+- [ ] The flow passed on each platform the change affects, and you reported which devices ran

package/skills/terreno-test-setup/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: terreno-test-setup
+description: >-
+  Bootstrap or repair the test setup of a Terreno app: backend Bun tests with in-memory
+  Mongo, frontend Bun + React Native Testing Library unit tests and Playwright web E2E, and
+  mobile Maestro flows on iOS/Android. Use when an app has no tests yet, `bun test` finds
+  nothing or crashes on import, a new backend/frontend/mobile package needs tests, or CI needs
+  a test job or sharding. Not for writing individual tests — use terreno-backend-tests,
+  terreno-frontend-tests, or terreno-mobile-tests.
+---
+
+# Terreno test setup
+
+Bootstrap one layer at a time. Each layer is done only when its completion check passes.
+Apps from `create-terreno-app` have `"test": "bun test"` scripts but no preload, helpers, or
+example test, so start with the backend.
+
+## 0. Inventory
+
+1. Read `backend/package.json`, `frontend/package.json`, every `bunfig.toml`, and any
+   existing `*.test.ts(x)`, `e2e/`, or `.maestro/` / `maestro/` directory.
+2. Note the installed `@terreno/*` version. All `@terreno/*` packages share one version, so
+   `@terreno/test` must match it.
+3. Pick the layers the user asked for. "Set up tests" with no qualifier means backend +
+   frontend unit; add Playwright and Maestro only when asked or when CI already expects them.
+
+Done when: you can name, per layer, what exists and what is missing.
+
+## 1. Backend (Bun + in-memory Mongo)
+
+Follow [references/backend.md](references/backend.md): add `@terreno/test`, a `bunfig.toml`
+preload that calls `registerBackendPreload`, service mocks registered once in that preload,
+and one route test.
+
+Done when: `cd backend && bun test` passes with the example route test while the dev
+`mongod` is stopped (proves the suite uses the in-memory server, not the dev database).
+
+## 2. Frontend unit tests (Bun + React Native Testing Library)
+
+Follow [references/frontend.md](references/frontend.md): add `@terreno/test`,
+`@testing-library/react-native@^13`, and `react-test-renderer`, a preload that calls
+`registerExpoTestEnvironment`, and one component test using `renderWithTerreno`.
+
+Done when: `cd frontend && bun test` passes with the example component test.
+
+## 3. Frontend web E2E (Playwright)
+
+Follow [references/frontend.md#playwright-web-e2e](references/frontend.md#playwright-web-e2e):
+`playwright.config.ts` with `webServer` entries for backend + web, `e2e/auth.setup.ts`,
+`e2e/helpers/login.ts` (`loginAs`), and one spec selecting by `testID`.
+
+Done when: `bunx playwright test` passes locally against a replica-set Mongo.
+
+## 4. Mobile (Maestro on iOS / Android)
+
+Follow [references/mobile.md](references/mobile.md): a dev-client build on a simulator or
+emulator, `maestro/config.yaml` plus one login flow keyed by `testID`, and optional
+per-platform unit runs.
+
+Done when: `maestro test maestro/` passes on at least one platform the user targets, and you
+recorded which platforms and devices were exercised.
+
+## 5. Scripts and CI
+
+1. Package scripts: `test` (local), `test:ci` (same suite, no watch), plus `test:e2e` and
+   `test:maestro` when those layers exist.
+2. Large suites: shard with `terreno-test-shard --shard <i>/<n>` (ships with
+   `@terreno/test`); add `terreno-test-hygiene --update-baseline` once, then run
+   `terreno-test-hygiene` in CI so new flaky patterns fail. See
+   [references/backend.md#ci](references/backend.md#ci).
+3. E2E and Maestro jobs need a replica-set `mongod`, the backend, and the web or native app
+   running; unit jobs need nothing but `bun install`.
+
+Done when: every layer you set up has a script, and the CI config (if the repo has one)
+runs each script.
+
+## Finish
+
+Report each layer as set up / skipped / blocked with the exact command that proves it, then
+point the user at the matching writing skill: `terreno-backend-tests`,
+`terreno-frontend-tests`, `terreno-mobile-tests`.