@terreno/agent-plugin 0.0.0-stage → 58.0.0-beta.2

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

@@ -0,0 +1,89 @@
+# Auth and Tokens — Terreno
+
+Session state lives in `@terreno/syncdb/auth`. There is no Redux store. Reference:
+`docs/reference/syncdb.md#auth`, `example-frontend/lib/betterAuth.ts`, `app/login.tsx`.
+
+## Better Auth client
+
+```tsx
+// lib/betterAuth.ts
+import {createBetterAuthClient} from "@terreno/syncdb/auth";
+import {baseUrl} from "@terreno/syncdb/config";
+
+export const betterAuthClient = createBetterAuthClient({
+  baseURL: baseUrl,
+  scheme: "myapp",
+  storagePrefix: "myapp",
+});
+```
+
+Storage is `expo-secure-store` on native and AsyncStorage on web. Never store tokens in
+plain AsyncStorage on native or in `EXPO_PUBLIC_*` env vars.
+
+## Session provider
+
+```tsx
+<SessionProvider authClient={betterAuthClient} syncDbs={[syncDb]} onLogout={() => apiClient.reset()}>
+  <App />
+</SessionProvider>
+```
+
+```tsx
+import {useSession} from "@terreno/syncdb/auth";
+
+const {userId, user, isAuthenticated, isLoading, error, logout, refresh} = useSession();
+```
+
+## Login
+
+```tsx
+const {refresh} = useSession();
+
+const result = await betterAuthClient.signIn.email({email, password});
+if (!result.error) {
+  await refresh(); // resolve userId now instead of waiting for the session atom
+}
+```
+
+Use `SocialLoginButton` from `@terreno/ui` with `betterAuthClient.signIn.social({provider})`
+for OAuth.
+
+## Logout
+
+```tsx
+const {logout} = useSession();
+await logout();
+```
+
+`logout()` signs out each `syncDbs` client first (wiping local rows when created with
+`wipeOnSignOut: true`), then the auth server, then runs `onLogout`.
+
+## Token refresh
+
+`betterAuthAdapter(bridgeBetterAuthReactClient(betterAuthClient))` is the shared
+`AuthProvider` for `createSyncDb` and `createApiClient`. The request client adds
+`Authorization: Bearer`, and on a 401 calls `authProvider.refresh()` once and retries.
+No manual refresh logic in app code. Code outside the client (SSE streams, `AdminProvider`
+`getAuthHeaders`) reads `authProvider.getToken()`.
+
+## JWT backends (legacy)
+
+Apps on `@terreno/api` JWT routes use `jwtAuthAdapter` as both the `authProvider` and the
+`SessionProvider` `source`, plus `useJwtAuth({adapter})` for `login`, `signup`,
+`googleLogin`, `resetPassword`. It refreshes when under 130 s remain and on a 401, with one
+shared refresh in flight. See `docs/reference/syncdb.md#jwt-auth-legacy`.
+
+## Current user
+
+```tsx
+import {useGetAuthMeQuery} from "@/store/apiSdk";
+
+const {userId} = useSession();
+const {data: me} = useGetAuthMeQuery(undefined, {skip: !userId});
+```
+
+## Protected routes
+
+Gate navigation on `useSession().userId` in root `_layout.tsx`. Redirect unauthenticated
+users to `/login`. For admin routes, check `canOpenAdminPage({admin: me?.admin, permissions:
+me?.permissions})` from `@terreno/syncdb/app`.

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

@@ -0,0 +1,50 @@
+# Realtime — Terreno
+
+The syncdb client owns the app's only socket. Do not open a second one.
+
+## Server push events
+
+```tsx
+import {useSocketEvent} from "@terreno/syncdb/react";
+
+useSocketEvent("announcementPublished", (payload) => {
+  console.info("announcement", payload);
+});
+```
+
+Inside `SyncDbProvider` the hook uses that client; above it, pass `{client: syncDb}`, or
+`{client: null}` to listen to nothing. Outside React: `syncDb.onSocketEvent(event, handler)`
+returns an unsubscribe.
+
+## Feature flags
+
+```tsx
+import {OpenFeatureProvider} from "@openfeature/react-sdk";
+import {useTerrenoFeatureFlags} from "@terreno/syncdb/flags";
+
+const {userId} = useSession();
+useTerrenoFeatureFlags({client: apiClient, skip: !userId, socket: syncDb, userId});
+return <OpenFeatureProvider domain="feature-flags">{children}</OpenFeatureProvider>;
+```
+
+Flags load through the request client and refetch when the server pushes
+`featureFlagsChanged` on the sync socket. Screens can read flat accessors with
+`useFeatureFlags({skip, socket, userId})`. See `example-frontend/app/_layout.tsx` and
+`docs/reference/feature-flags.md`.
+
+## Sync status
+
+```tsx
+import {useSyncStatus} from "@terreno/syncdb/react";
+
+const {isOnline, queuedCount, conflictCount, failedCount, paused} = useSyncStatus();
+```
+
+Render `SyncStatusBanner` / `OfflineBanner` from `@terreno/ui` with these values.
+
+## Realtime model updates
+
+Live collection updates come from `sync` on the backend `modelRouter`; read them with
+`useQuery` / `useEntity`. `RealtimeApp` hosts the socket for `sync:delta` and app events.
+Terreno 58 removed `modelRouter` `realtime` and every `@terreno/rtk` socket helper
+(`useSocketConnection`, `realtimeList`, `realtimeDocument`, `useRealtimeDebug`).

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

@@ -0,0 +1,55 @@
+# SDK Customization — Terreno
+
+## Generated vs hand-maintained
+
+| File | Editable? | Purpose |
+|------|-----------|---------|
+| `store/apiSdk.ts` | **Never** | Typed hooks for every non-synced OpenAPI operation (`--api-out`) |
+| `store/syncDbSdk.ts` | **Never** | `SYNC_COLLECTIONS` + collection hooks (`--out`) |
+| `store/apiClient.ts` | **Yes** | `createApiClient` (auth, headers, `onError`) |
+| `syncdb-codegen.json` | **Yes** | Codegen config (`excludePaths`, per-collection `overrides`) |
+
+## Generated hooks
+
+Names follow the old RTK codegen rule: camelCased `operationId`, otherwise method + path with
+`{param}` as `By<Param>` (`PATCH /gpt/histories/{id}` → `usePatchGptHistoriesByIdMutation`).
+Each operation also gets `<Name>Args`, `<Name>Res`, and `<name>Request(arg)` for
+`apiClient.request(...)`. Tags come from the operation's OpenAPI tags.
+
+```tsx
+import {useGetAuthMeQuery, usePatchAuthMeMutation} from "@/store/apiSdk";
+```
+
+## Routes outside OpenAPI
+
+Prefer documenting the route in OpenAPI and regenerating. When that is not possible, call it
+directly through the request client:
+
+```tsx
+import {useApiMutation, useApiQuery, useLazyApiQuery} from "@terreno/syncdb/react";
+
+const {data, isLoading, refetch} = useApiQuery<Report>(
+  {url: "/reports/summary", params: {range}},
+  {providesTags: ["reports"], skip: !userId}
+);
+
+const [rebuild, {isLoading: isRebuilding}] = useApiMutation<RebuildBody, Report>(
+  (body) => ({body, method: "POST", url: "/reports/rebuild"}),
+  {invalidatesTags: ["reports"]}
+);
+await rebuild({range}).unwrap();
+```
+
+## Cache tags
+
+Queries register `providesTags`; mutations `invalidatesTags`. Imperatively:
+`apiClient.invalidateTags(["reports"])`. `apiClient.reset()` clears the cache (done on logout
+via `SessionProvider` `onLogout`). Synced collections have no request cache; their data is local.
+
+## Workflow after backend change
+
+1. Start backend (`bun run backend:dev`)
+2. Run `cd example-frontend && bun run sdk` (and `bun run sync-sdk` for synced schema changes)
+3. Import new hooks from `@/store/apiSdk` (or `@/store/syncDbSdk`)
+
+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`.