@unotest/mobile 0.1.1 → 0.8.0

package/.claude/skills/write-e2e-test.md

@@ -1,294 +1,406 @@
 ---
 name: write-e2e-test
-description: Write a new E2E test for the project under test using @unotest/mobile. Use when the user asks to write/cover/add a test for a feature, flow, or screen.
+description: Write a new E2E test for the project under test using @unotest/mobile. Records actions through explore_step (execute + record in one call), then generates a DSL test and verifies it via run_test. Use when the user asks to write/cover/add a test for a feature, flow, or screen.
 ---
 
 # Skill: write-e2e-test
 
-You are writing an end-to-end test using `@unotest/mobile` against an iOS
-React Native app. Tests live in `unotest/e2e/` inside the **project under
-test** (not in the `@unotest/mobile` package itself).
+You are writing an end-to-end test using `@unotest/mobile` against an
+iOS React Native app. The test lives in `unotest/e2e/<name>.js` in the
+project under test.
 
-This skill is the single source of truth — everything you need to write a
-correct test is below. Do not hunt for separate docs.
+**Default mode is verify-against-live-app.** A test that hasn't been
+run is unverified — selectors may be invented, transitions may race,
+the scenario may not actually pass. Producing a test you can't show
+green is the failure case.
 
-## Before you write
+Two modes, picked at phase 1 based on environment:
 
-1. **Survey existing helpers** in `unotest/e2e/_helpers/`. Don't reinvent
-   `signin`, `seed_user_*`, `wipe_*` — reuse what's there. If a helper
-   you need doesn't exist, add it to `_helpers/<topic>.js` (not inline).
+- **Interactive (preferred)** — phases 1-5 below. The app is launchable
+  on a configured simulator, MCP tools (`explore_start`, `explore_step`,
+  `a11y_tree`, `resolve_selector`, `run_test`, …) are available. You
+  record the flow live, generate the DSL, save it, run it, iterate
+  until green.
 
-2. **Survey existing scenarios** in `unotest/e2e/`. Match the style and
-   reuse the same setup/seed patterns.
+- **Draft-only (fallback)** — if the first `explore_step { action:
+  "app_launch" }` fails or no sim is configured, you cannot verify.
+  Write the file from the description the user gave you, mark it as
+  unverified in your final reply ("⚠ unverified — no live app —
+  run `npx unotest-mobile e2e <name>` after fixing the env"), and STOP.
+  Don't pretend a draft is a working test.
 
-3. **Read the env file** `unotest/.env`. It tells you the app's bundle id,
-   simulator slot names, database URL, project CLI paths.
+## Workflow — record then generate then verify
 
-4. **Ask the user only what you can't infer:** which feature/flow to test,
-   which user role if the app has roles, happy path, negative cases. Do
-   not ask about conventions — they are below.
+Five phases, in this order. Don't skip phases.
 
-## Scenario shape
+### Phase 0 — read context
 
-Four phases per scenario — Setup, Enter, Act, Assert.
+`unotest/e2e/_template/example.js` shows the exact DSL syntax (bare
+top-level functions, no `import`/`export`/`async`/`await`/`const`/`let`/
+`var`/arrow-functions). Read it first. The DSL looks like JavaScript
+but is a frozen subset — when your default JS instincts disagree with
+the template, the template wins.
 
-```js
-// id-<scenario-id>
-// <one-line human description>
-// #<6-digit hex color>
-function test_<entry_name>() {
-  // 1. SETUP — DB / API / CLI fixtures
-  wipe_e2e_users();
-  user_id = seed_user("e2e-user@example.com", "e2e-pass-1234");
+`unotest/.env` has `APP_BUNDLE_ID` and `APP_PATH` — you'll need both.
+Read it.
 
-  // 2. ENTER — bring the app to a known initial UI state
-  setDevice("A");
-  appLaunch(true);
-  waitFor(getByTestId("screen-welcome"), 15000);
+### Phase 1 — start the exploration
 
-  // 3. ACT — the actions you're testing
-  signin("e2e-user@example.com", "e2e-pass-1234");
-  waitFor(getByTestId("screen-home"), 15000);
-  tap(getByTestId("btn-create-item"));
-  type(getByTestId("input-title"), "Hello");
-  tap(getByTestId("btn-save"));
+```
+explore_start { scenario_name: "<flow>", device: "A" }
+```
+
+Returns `{ explorationId }`. Keep this id — every recorded step needs
+it. Device slot ("A"/"B") is fixed for the session.
 
-  // 4. ASSERT — UI + data checks
-  assertVisible(getByTestId("item-row-Hello"));
-  count = dbQuery("SELECT count(*)::text FROM items WHERE user_id = $1", user_id);
-  assertEqual(count, "1");
+### Phase 2 — first recorded step: launch the app
+
+```
+explore_step {
+  explorationId,
+  action: "app_launch",
+  clean: true,
+  description: "Cold start",
+  section: "Setup"
 }
 ```
 
-The **3-line comment header** above `function` is mandatory for `test_*`
-and `flow_*` (linter rule E7). The order is fixed: id, description, hex
-color. The header is metadata used by the future Blockly visual editor;
-keep it stable.
-
-## DSL — strict JS subset
-
-The DSL is **not** full JavaScript. The parser rejects what the
-visual-editor target (Blockly) can't render.
-
-**Allowed:**
-- Top-level `function name(args) { ... }` definitions
-- Bare-name assignment: `x = expr;` (no `var`/`let`/`const`)
-- `if`/`else`, blocks `{ ... }`
-- Function calls (statement or expression position)
-- Literals: number, string, `true` / `false` / `null`
-- Array literals `[a, b, c]` (used for variadic args)
-- Arithmetic: `+ - * /`
-- Comparisons: `== != < <= > >=`
-- Logical: `&& ||`
-- String concatenation: `"a" + "b"`
-
-**Forbidden** (linter will reject):
-- `var` / `let` / `const`
-- `for` / `while` (`maxSteps` budget protects from infinite loops)
-- Object literals `{a: 1}` — pass payloads as JSON-as-string instead
-- Member access `obj.field` — primitives only
-- Index access `arr[i]`
-- Unary `!` / `-` (use `0 - n` for negative numbers)
-- `===` / `!==` (use `==` / `!=`)
-- `+=` / `-=` / `++` / `--`
-- Arrow functions, classes, destructuring
-- Nested function definitions
-
-For structured payloads, pass JSON as a string:
-```js
-apiCall("POST", "/api/users", '{"email":"x@y.z","name":"X"}');
+`clean: true` does terminate + launch (NOT a full wipe — login state
+may persist; phase 4 handles that). The first step **must** be the
+bootstrap — without `app_launch` (or `open_deeplink`) the generated
+test has no entry point. Wait for the launch to settle before
+discovering.
+
+### Phase 3 — discover, then act (loop)
+
+For each screen you traverse:
+
+1. **Discover** — `a11y_tree { device: "A" }`. Default `mode: "outline"`
+   returns a compact text format partitioned into `on_screen` /
+   `off_screen`. Reading it:
+
+   ```
+   on_screen:
+     - screen #screen-welcome
+       - button "Sign In" #btn-signin
+       - "Welcome back!" {clipped: top}
+   off_screen:
+     bottom:
+       - "Settings"
+       - button "Sign Out"
+   _meta:
+     totalNodes: 142  onScreen: 18  offScreen: 23
+     viewport: 393x852
+     mode: outline
+   ```
+
+   Line grammar: `- [role] ["name"] [#testId] [{clipped: side}]`.
+   `#testId` is the stable selector — prefer it over text matching.
+   `{clipped: top}` means the node straddles the top viewport edge.
+
+   **`off_screen` is a HINT, not a selector source.** Items there
+   exist in the tree but are past the viewport — `explore_step
+   { action: "swipe", direction: "up", ... }` (ad-hoc — omit
+   `explorationId` if you're just exploring) then re-call `a11y_tree`.
+
+   Use `mode: "full"` only when you need raw bounds for debugging.
+
+2. **Verify** the selector before using it:
+   ```
+   resolve_selector { device: "A", selector: { testId: "btn-signin" } }
+   ```
+   `{ status: "found" }` → use it. `{ status: "miss", candidates: [...] }`
+   → read the top-3 candidates, pick the closest, retry. Don't guess.
+
+3. **Act + record** — every UI action goes through `explore_step`.
+   Passing `explorationId` records the step into the session log.
+   `section` and `description` are required when recording (they
+   shape the generated DSL into readable `//@collapse` blocks):
+
+   ```
+   explore_step {
+     explorationId,
+     action: "tap",
+     selector: { testId: "btn-signin" },
+     description: "Open signin",
+     section: "Sign in flow"
+   }
+   explore_step {
+     explorationId,
+     action: "type",
+     selector: { testId: "input-email" },
+     value: "petr@volkov.io",
+     description: "Email",
+     section: "Sign in flow"
+   }
+   ```
+
+   Group related steps under one `section`. Adjacent same-section
+   entries collapse into one block. Sections like `"Setup"`,
+   `"Sign in flow"`, `"Verify dashboard"` work well.
+
+   **Ad-hoc probes** — to try a tap or swipe without polluting the
+   recording, **omit `explorationId`** (you must then pass `device`
+   explicitly). Discovery tools (`a11y_tree`, `resolve_selector`,
+   `screenshot`) never record either way.
+
+   **Recording-time reject:** `explore_step { action: "wait_for",
+   optional: true, explorationId, ... }` is refused — DSL `waitFor`
+   has no optional semantics; the generated test would diverge.
+   Run it ad-hoc instead.
+
+4. **Re-discover** after every action that changes the screen.
+
+5. If you record a wrong step, **remove it** before continuing:
+   ```
+   explore_remove_step { explorationId, entryId: "<from explore_step result>" }
+   ```
+   To add an action you forgot (or an assertion), use
+   `explore_record { explorationId, action, ..., description, section }` —
+   same shape as `explore_step` but without executing.
+
+Anti-pattern: building selectors by analogy from web testing instead
+of from `a11y_tree`. Selectors invented this way are the #1 source of
+`run_test` failures.
+
+### Phase 4 — stop, generate, save
+
+```
+explore_stop { explorationId }            → { stepCount, readyForConversion: true }
+generate_dsl_from_exploration { explorationId }  → { draftDsl, warnings }
 ```
 
-## DSL functions
-
-### Device
-
-| Function | Effect |
-|---|---|
-| `setDevice(slot)` | Switch the "current device" for subsequent UI calls. `slot` must be in `EnvConfig.simBySlot` (defined in `unotest/.env`, e.g. `"A"` or `"B"`). |
-| `appLaunch(clean?)` | Launch the app under test. `clean=true` → terminate + relaunch from clean state. |
-| `openDeeplink(url)` | Open a URL on the current device. |
-
-### Selectors (pure — return Selector objects, no driver call)
-
-| Function | Returns |
-|---|---|
-| `getByTestId(s)` | `{ testId: s }` |
-| `getByText(s)` | `{ text: s }` |
-| `getByLabel(s)` | `{ label: s }` |
-| `ordinal(target, n)` | wraps a Selector with `ordinal: n` (0-indexed) |
-| `near(target, anchor, maxPx?)` | wraps a Selector with `near: { anchor, maxDistancePx? }` |
-
-`testId`, `text`, `label` are **equal-priority citizens** — there is no
-implicit fallback chain. Use `getByText` on custom buttons that lack a
-`testID`. iOS surfaces a React Native `testID` as the WDA `name` attribute.
-
-### UI actions
-
-| Function | Behavior |
-|---|---|
-| `tap(selector)` | Auto-wait up to `defaultActionWaitMs`, then tap the element's center. |
-| `type(selector, text)` | Auto-wait, tap to focus, send keys. |
-| `swipe(direction, fromSel?)` | Direction is `"up"` / `"down"` / `"left"` / `"right"`. If `fromSel` is given, auto-wait + swipe from its center; else from screen center. |
-| `pressKey(key)` | `"home"` / `"enter"` / `"escape"`. iOS has no `back`. No selector → no auto-wait. |
-| `waitFor(selector, timeoutMs?)` | Explicit poll up to `defaultWaitForTimeoutMs`. |
-| `pause(ms)` | Sleep. Use sparingly; prefer `waitFor`. |
-
-### Data
-
-| Function | Description |
-|---|---|
-| `dbQuery(sql, ...args)` | Parameterized SELECT through `DbClient` (pg / mysql / sqlite, picked by `DATABASE_URL`). Returns the **first cell of the first row** as a string. For multi-row results use multiple `dbQuery` calls. |
-| `dbExec(sql, ...args)` | Parameterized INSERT/UPDATE/DELETE. If the driver returned rows (e.g. `INSERT ... RETURNING` on pg or sqlite 3.35+), returns the first cell of the first row; otherwise `""`. Does not parse the SQL. |
-| `apiCall(method, path, body?, headers?)` | HTTP request via `ApiClient.call`. `body` is JSON-as-string. Returns raw response body. |
-| `shell(cmd, ...args)` | `execFile`-style spawn — args go straight to `child_process` argv with **no shell interpretation**. Throws on non-zero exit. Returns stdout. |
-
-Project-specific seeding (creating users, fixtures, etc.) lives in
-`unotest/e2e/_helpers/`. The core `@unotest/mobile` package does not know
-about your backend stack — you wire it via `shell` / `dbExec` / `apiCall`.
-
-### Time
-
-| Function | Description |
-|---|---|
-| `today()` | ISO date `YYYY-MM-DD` (UTC) for the runtime. |
-| `daysFromNow(n)` | ISO date `n` days from today. For negative n use `daysFromNow(0 - n)` — the DSL has no unary minus. |
-| `nowMs()` | Unix timestamp in milliseconds (useful for unique suffixes). |
-
-### Assertions
-
-| Function | Effect |
-|---|---|
-| `assertEqual(a, b)` | Throws if `a !== b`. |
-| `assertVisible(selector)` | Resolves the selector against the current screen; throws if no match. |
-| `assertCount(selector, n)` | Probes `ordinal: 0..N-1`; throws if the total count is not `n`. |
-| `assertEnabled(selector)` | Resolves against the **raw** a11y tree (not compact). Throws if `enabled !== true` or the field is missing. |
-| `assertDisabled(selector)` | Same, expects `enabled === false`. |
-
-## Helpers
-
-- Live in `unotest/e2e/_helpers/*.js`. Globally visible to all scenarios.
-- `snake_case` function names (`seed_user`, `signin`, `wipe_e2e_users`).
-- `return` is **allowed** in helpers (forbidden in `test_*` / `flow_*`).
-- **Snapshot scoping**: helper mutations don't leak to caller variables.
-  Pass information back via return values.
-- Recursion depth capped at `maxCallDepth` (default 32).
-- Cross-file: every file under `_helpers/` is auto-loaded for every
-  scenario — convention, not magic.
-
-Extract to a helper when:
-- 5+ lines repeat across 2+ scenarios.
-- A piece of setup needs to be available to many tests.
-
-Don't extract prematurely — one-off code stays inline.
-
-Example:
-
-```js
-// unotest/e2e/_helpers/seed.js
-function seed_user(email, password) {
-  shell("npm", "--prefix", "./apps/api", "run", "cli", "--",
-        "create-user", "--email", email, "--password", password);
-  return dbQuery("SELECT id FROM users WHERE email = $1", email);
-}
+Read the warnings before saving:
+
+- **`FRAGILE_LOCATOR`** — selector lacks a stable identifier (only
+  `pointPercent`, or `ordinal` without a pinned `testId`/`text`/`label`).
+  Ideally add a `testId` in the app and re-record. If not possible,
+  accept and document.
+- **`NO_DSL_PRIMITIVE`** — selector shape has no DSL function (e.g.
+  `near`). The line is rendered as `// SKIPPED …`. Fix the entry:
+  `explore_remove_step` + `explore_record` with a stable selector.
+  (Or `save_exploration_as_test { force: true }` to keep the comment
+  inline — only if a partial test is genuinely better than none.)
+- **`BUNDLE_ID_IGNORED`** — `app_launch` had an explicit `bundleId`,
+  but DSL `appLaunch()` reads bundle from `APP_BUNDLE_ID` env.
+  Harmless; the generated `appLaunch(clean)` works the same.
+
+Then persist:
+
+```
+save_exploration_as_test { explorationId, scenarioName: "<name>" }
 ```
 
-## Setup strategy
+- Default behavior: any `NO_DSL_PRIMITIVE` blocks the save with an
+  actionable error. Fix the entries, or pass `force: true` to write
+  with `// SKIPPED` comments.
+- File exists? Pass `overwrite: true`.
 
-Pick the highest viable option:
+The 3-line scenario header (`// id-...`, `// <title>`, `// #<color>`)
+is emitted automatically by the generator above the
+`function test_<name>()` line.
 
-1. **`shell()` to a project CLI** — goes through real business logic
-   (password hashing, hooks, side effects). Best fidelity.
-   ```js
-   shell("npm", "run", "cli", "--", "create-user", "--email", email);
-   ```
-2. **`apiCall()`** — when the CLI doesn't exist but the endpoint does.
-3. **Direct `dbExec("INSERT INTO ...")`** — only when intentionally
-   bypassing business logic. Rare; document why.
+### Phase 5 — reset state, then run_test
 
-For dates, use `today()` / `daysFromNow(n)`. **Never** hardcode a date
-like `"2026-05-12"` — tests would silently rot.
+You probably logged in / created data interactively. The test must
+start from the same clean state your scenario assumes.
+`appLaunch(clean: true)` alone is NOT enough — it terminates and
+launches the app, but if you also need a fresh sandbox + uninstall,
+use `app_install { clean: true }` (it wipes the keychain too — B5).
 
-## Cleanup
+Via MCP — reinstall the app to wipe its sandbox AND auth tokens:
+```
+app_install { path: "<APP_PATH from unotest/.env>", clean: true }
+```
 
-Wipe **at the start of the scenario**, not at the end. Failed runs skip
-end-of-test cleanup; start-of-test cleanup always runs.
+**Do NOT pass `erase: true`.** `erase: true` runs `simctl erase` which
+wipes the entire simulator including WebDriverAgent. `clean: true`
+alone is the right soft-reset — it now resets the keychain too, so
+the legacy `xcrun simctl keychain booted reset` workaround is no
+longer needed.
 
-```js
-function test_X() {
-  wipe_e2e_users();   // beginning — always runs
-  // ...
-}
+Then verify:
+```
+run_test { name: "<scenario-name>", pauseOnFailure: true }
+```
+
+The response is JSON wrapped in `{ content: [{ type: "text", text: "<json>" }] }`:
+```
+JSON.parse(response.content[0].text).next.outcome
+```
+
+- `"completed"` → green, you're done.
+- `"paused-failure"` → fix and `resume { runtimeId }` (or
+  `abort_runtime` + `run_test` again).
+- Common causes: wrong initial state (re-run `app_install { clean: true }`),
+  wrong testId (re-discover, fix the .js file), timing
+  (add `waitFor(getByTestId(...), 15000)`).
+
+Iterate until `outcome === "completed"`.
+
+## `explore_step` cheat-sheet
+
+| `action`        | required                  | optional                    |
+|-----------------|---------------------------|------------------------------|
+| `tap`           | `selector`                |                              |
+| `type`          | `selector`, `value`       |                              |
+| `press_key`     | `key`                     |                              |
+| `swipe`         | `direction`               | `from` (anchor selector)     |
+| `wait_for`      | `selector`                | `timeoutMs`, `optional`*     |
+| `app_launch`    |                           | `bundleId`, `clean`          |
+| `open_deeplink` | `url`                     |                              |
+| `accept_alert`  |                           | `button` (label)             |
+| `dismiss_alert` |                           |                              |
+
+\* When recording: `optional: true` is rejected — run ad-hoc instead.
+
+When recording, also required: `description`, `section`. Ad-hoc
+(no `explorationId`) requires `device` instead.
+
+## When a11y_tree shows an `alert:` section (P2a)
+
+Outline starts with `alert:` → a native iOS alert is active
+(UIAlertController, system permission prompt, ATT, Sign Out confirm, etc.).
+**Do not tap by coordinates — native alerts live in SpringBoard, not in
+the app a11y tree. A coord-tap goes through to the underlying app view
+behind the alert and either does nothing or re-triggers the alert.**
+
+Route through the explore_step alert actions:
+
+```
+explore_step { explorationId, action: "accept_alert", button: "<label>", ... }
+explore_step { explorationId, action: "dismiss_alert", ... }
+```
+
+(Or DSL `acceptAlert("<label>")` / `dismissAlert()` when running the
+generated test.)
+
+Example outline:
+```
+alert:
+  text: "Are you sure you want to sign out?"
+  buttons: [Sign Out, Cancel]
+  hint: use acceptAlert("<label>") or dismissAlert — direct tap won't reach SpringBoard
+```
+
+Action by intent:
+- sign-out confirm → `accept_alert { button: "Sign Out" }`
+- location permission → `accept_alert { button: "Allow Once" }` or `"Don't Allow"`
+- ATT prompt → `accept_alert { button: "Allow" }` or `"Ask App Not to Track"`
+- cancel → `dismiss_alert` (or `accept_alert { button: "Cancel" }`)
+
+The `buttons:` array is the authoritative source of labels. If `buttons:`
+is missing (WDA endpoint failed) — infer from `text:` or fall back to
+`dismiss_alert` (WDA finds Cancel/Dismiss on its own).
+
+After accept/dismiss — always re-call `a11y_tree`. If the `alert:`
+section is still present, handle the next one (permission prompts can
+chain: TCC → confirm).
+
+## DSL cheat-sheet (in saved scenarios)
+
+The generated test file uses these DSL functions — they have not
+changed from the previous surface.
+
+Device & lifecycle:
+- `setDevice("A")` — required before any UI call; "A"/"B" slots.
+- `appLaunch(clean?)` — boot the app. `clean=true` is terminate+launch.
+- `openDeeplink(url)` — open `myapp://...`.
+
+UI actions (selector arg always first):
+- `tap(selector)`, `type(selector, "text")`
+- `swipe("up"|"down"|"left"|"right", selector?)` — direction first; selector optional (defaults to whole screen).
+- `pressKey("enter"|"back"|"space")`
+- `waitFor(selector, timeoutMs)` — waits until present.
+- `pause(ms)` — last resort; prefer `waitFor`.
+
+Native iOS alerts (UIAlertController — permission prompts, ATT,
+Sign Out confirmation, iOS update banners):
+- `acceptAlert("Allow Once")` — tap a specific button by label.
+  **Always prefer this form** — the no-arg fallback is position-based
+  and kind-dependent.
+- `dismissAlert()` — tap the cancel button (first button on a standard
+  modal alert, last button on an action sheet).
+- `acceptAlert()` — no label. Position-based fallback: for a standard
+  UIAlertController modal it taps the LAST button (the affirmative one
+  like `OK` / `Allow` / `Sign Out`); for an action sheet it taps FIRST.
+- `readAlert()` → string (title + body, newline-separated). Throws if
+  no alert is on screen.
+
+**Use the alert API for any `UIAlertController`** — that includes
+system SpringBoard prompts AND React Native `Alert.alert(...)` (the
+iOS 26 redesigned alerts in particular break naive selector taps).
+App-level `<Modal>` / BottomSheet / custom overlays with arbitrary
+children are regular `tap()` territory.
+
+Selectors:
+- `getByTestId("id")`, `getByText("text")`, `getByLabel("a11y label")`
+- `ordinal(selector, n)` — nth match (0-indexed). Don't rely on
+  `ordinal` for native alert buttons.
+- `near(a, b)` — A closest to B.
+
+Assertions:
+- `assertVisible(selector)`, `assertCount(selector, n)`,
+  `assertEnabled(selector)`, `assertDisabled(selector)`,
+  `assertEqual(a, b)`.
+
+Data primitives (when scenario needs them):
+- `dbQuery("SELECT ... WHERE x = ?", arg)` → rows.
+- `dbExec("INSERT INTO t ... VALUES (?, ?)", a, b)` → affected count.
+- `apiCall("POST", "/path", "<json-string>")` → response.
+- `shell("git", "status")` → `{stdout, stderr, exitCode}`.
+
+Time: `today()`, `daysFromNow(n)`, `nowMs()`.
+
+## Helpers convention
+
+Reusable steps go in `unotest/e2e/_helpers/<group>.js`. Helper naming
+is **snake_case** (`signin_as`, `seed_workout`). **Before recording an
+inline flow, check `_helpers/` for an existing helper** — `Glob` or
+`Read`. If `signin_as(email, password)` exists, the generated test
+should call it instead of re-recording four steps. (After
+`generate_dsl_from_exploration`, edit the file to swap inline steps
+for the helper call.)
+
+```
+unotest/e2e/_helpers/auth.js:
+function signin_as(email, password) { ... }
+```
+
+Call without import — helpers are auto-discovered.
+
+## Anti-patterns
+
+- **Don't record selectors you haven't verified via `resolve_selector`.**
+  `miss` → fix before recording the step.
+- **Don't tap UIAlertController buttons with
+  `explore_step { action: "tap", selector: { text: "..." } }`.** Use
+  `explore_step { action: "accept_alert" | "dismiss_alert", button? }`.
+- **Don't `app_install { erase: true }` mid-session.** Kills WDA.
+- **Don't consider the task done without a green `run_test`.** "I
+  recorded the flow, generated the file, looks right" is not done.
+  `outcome === "completed"` is done.
+- **Don't `await` anything in the saved scenario. No `import`/`export`/
+  `async`/arrow-functions/`const`/`let`/`var`/object-literals.** DSL,
+  not Node.
+- **Don't omit `section` / `description` when recording.** They're how
+  the agent (and humans) will read the generated test later.
+
+## Fast feedback
+
+After editing any scenario:
+```
+npx unotest-mobile lint
 ```
 
-## Authoring workflow
-
-1. **Plan the test.** One-line description. Decide setup, actor, assertion.
-2. **Pick a path:**
-   - Single feature → `unotest/e2e/<feature>/<actor>-<verb>-<context>.js`
-   - Cross-feature smoke / integration → `unotest/e2e/<actor>-<verb>-<context>.js`
-3. **Copy `unotest/e2e/_template.js`**, rename, adjust the 3-line header
-   (id / description / color).
-4. **Write setup** using existing helpers. If you need a new one, add to
-   `_helpers/<topic>.js` first, then use it.
-5. **Run via MCP `run_test` with `pauseOnFailure: true`:**
-   - On pause: `inspect_runtime <id>` → see vars, last error.
-   - Use `screenshot` + `a11y_tree` to understand UI state.
-   - Use `resolve_selector` to find correct testIDs (returns the top-3
-     near-misses with reasons when no exact match).
-   - Fix the scenario, then `resume <id>` to retry the failed step.
-   - Once green: `abort_runtime <id>` to teardown.
-6. **Lint:** `npx @unotest/mobile lint` (also runs automatically on every
-   `e2e <name>`).
-
-## Linter codes
-
-| Code | Severity | Meaning |
-|---|---|---|
-| E1 | error | Function name not in `FunctionRegistry` and not declared as a user helper. |
-| E2 | error | AST node outside the MVP subset, or `return` in a `test_*` / `flow_*` body. |
-| E3 | error | `setDevice("X")` slot not in `EnvConfig.simBySlot`. |
-| E4 | error | JSON-string arg in `apiCall` doesn't parse. |
-| W5 | warn  | An `assert*` call before any UI action — likely a typo. |
-| E7 | error | `test_*` / `flow_*` function missing the 3-line header (`// id-...`, `// description`, `// #color`) immediately above `function`. |
-| E8 | error | Duplicate user-function name, or a user function shadows a built-in. |
-
-## Common antipatterns
-
-- **Hardcoding testIDs without verifying** them in the app. Use
-  `resolve_selector` first to confirm the ID exists.
-- **Inlining 30 lines of signin** in every scenario — extract a `signin` helper.
-- **One mega-test** covering everything — split by actor / action so
-  failures point at one thing.
-- **Tests depending on each other's state** — every scenario must be
-  self-contained.
-- **Using `getByText("...")` when a `testID` exists** — `testID` is stable
-  across locale changes; visible text is not.
-- **Hardcoding dates** — use `today()` / `daysFromNow(n)`.
-- **Object literals or member access** — DSL forbids them; use JSON
-  strings and primitive returns.
-
-## When the test fails to run
-
-| Symptom | Likely cause |
-|---|---|
-| `Invalid environment` | `unotest/.env` missing keys. Compare to `.env.example`. |
-| `ECONNREFUSED` from `dbQuery` | `DATABASE_URL` not reachable. For docker Postgres, ensure the host port is exposed (`ports: ["5432:5432"]`). |
-| `relation "..." does not exist` | DB migrations not run, or a helper references a table that doesn't exist in this project. |
-| `Sim "X" not found` | `SIM_A_NAME` / `SIM_B_NAME` in `.env` don't match `xcrun simctl list devices`. |
-| `Entry function "test_X" not found` | File basename doesn't match the function name. Convention: `unotest/e2e/<path>/foo-bar.js` → `function test_foo_bar()`. |
-
-If a selector resolves to the wrong element or times out: use
-`resolve_selector` (MCP) to see the top-3 near-misses with reasons.
-
-## Output to user
-
-After writing tests:
-
-1. **Summarize the scenarios you added** — file paths, one line each.
-2. **List any new helpers added** to `_helpers/`.
-3. **Call out app-side TODOs** — missing `testID`s, missing CLI
-   subcommands, missing DB schema. Don't silently assume; surface them
-   so the user can decide.
-4. **Confirm `npx @unotest/mobile lint` passes.** If you ran `run_test`,
-   report pass/fail per scenario.
+Lint codes to recognize:
+- E1/E2 — unknown function or unsupported statement (drift to plain JS).
+- E5 — wrong arg count for a built-in.
+- E6 — wrong arg TYPE / order, e.g. `swipe(getByTestId("x"), "up")` —
+  argTypes are `("up"|..., selector)`.
+- E7 — missing 3-line header above `test_*`/`flow_*` (generator emits
+  it; only fires if you hand-edited).
+- E8 — helper used but not defined in `_helpers/`.
+
+If lint flags `import`/`export`/`await`/`const` — re-read the DSL
+section above and rewrite.