@unotest/mobile 0.1.0 → 0.8.0

package/CHANGELOG.md

@@ -4,6 +4,474 @@ All notable changes to `@unotest/mobile` will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.8.0] — 2026-05-18
+
+### Fixed — WdaDriver auto-recovers from stale WDA sessions (B6)
+
+- **What broke.** The MCP server cached a `sessionId` per slot. Anything
+  killing the underlying XCTest runner — `simctl erase`, app crash,
+  WDA process killed — invalidated that id, but the server kept using
+  it. Result: every WDA call returned `HTTP 404 "no such session"` and
+  the agent had no recovery path; the only fix was a manual MCP
+  reconnect. Observed live during a `signout-with-alert` eval re-run
+  immediately after a full suite (10-min timeout, ~$1 burned).
+- **Fix.** `WdaHttpClient.request()` now detects the three flavours of
+  WDA's session-gone signal (`no such session`, `Could not find session`,
+  `invalid session id`) and throws a typed `WdaSessionGoneError`.
+  `WdaDriver` wraps every session-using public method in a
+  `withFreshSession(slot, fn)` helper that catches the typed error,
+  drops the cached session, recreates it via the normal factory, and
+  retries the call **once**. Persistent failures bubble up unchanged
+  (no infinite loop). Invisible to user code — only a `wda:<slot>` log
+  warning marks the recovery.
+- Methods wrapped: `tap`, `type`, `swipe`, `pressKey`, `screenshot`,
+  `a11yTree`, `windowSize`, `acceptAlert`, `dismissAlert`, `readAlert`,
+  `readAlertButtons`. Inner helpers (`resolveBounds`,
+  `resolveElementId`) ride their outer caller's retry — no nested
+  wrapping needed.
+- Tests: +6 (4× HTTP layer session-gone classification covering all
+  three message flavours plus a negative case proving alert-404 isn't
+  mis-classified as session-gone; 2× driver-level retry path covering
+  the recover-and-succeed case and the persistent-failure-bounded-retry
+  case — the second guards against the obvious "what if retry also
+  fails" infinite-loop regression). 561 → 567 total.
+
+### Added — `install` auto-detects + pre-grants iOS permissions, pins keyboard (P4 / S4 + S8)
+
+- **Permission detection from Info.plist.** `unotest-mobile install`
+  (CLI + MCP `app_install`) parses the .app's `NS*UsageDescription`
+  keys via `plutil -convert json`, maps them to
+  `simctl privacy <service>` names, and surfaces the list as
+  `result.detectedPermissions`.
+- **Pre-grant on install.** When the resolved permissions list is
+  non-empty, every service is granted with `simctl privacy <udid> grant
+  <service> <bundleId>` immediately after install. Pre-empts SpringBoard
+  permission dialogs (location, motion, photos, …) that would otherwise
+  block scenarios on first launch — those dialogs live in SpringBoard,
+  not in the app's a11y tree.
+- **Keyboard pin.** `install` always pins the sim's software keyboard
+  to `en_US@QWERTY` via three `defaults write -g` calls. WDA's
+  `typeText` routes through whatever layout the sim was last using;
+  a leftover Cyrillic layout silently drops Latin characters
+  (`Qwerty34##` → `34`). Pin makes typing deterministic.
+- **Single grant owner.** `installApp(opts.permissions, opts.pinKeyboard)`
+  is the only call site for both `simctl.privacyGrant` and
+  `simctl.pinEnglishKeyboard`. CLI and MCP layers just compute the
+  permissions list (CLI flag / `APP_PERMISSIONS` env / interactive
+  prompt / MCP `updateEnv` auto-confirm) and pass it through. No more
+  double-grants from CLI + MCP racing each other on `app_install`.
+- **New CLI flags.**
+  - `--permissions=<list>` — explicit comma-separated services for this
+    run (e.g. `--permissions=location,motion`). Empty value
+    (`--permissions=`) = grant nothing. Wins over `APP_PERMISSIONS`.
+  - `--no-permissions` — explicit opt-out even when `APP_PERMISSIONS`
+    is set. Conflicts with `--permissions=<list>` (parser throws).
+- **`--update-env` extended.** Now persists `APP_PERMISSIONS` (when
+  newly resolved) alongside `APP_PATH`, `APP_BUNDLE_ID`,
+  `APP_URL_SCHEME`. Pre-passes the plist before install so detected
+  permissions land in **this** install (not just the next one) — the
+  prior gap where `install --update-env` only wrote `.env` but didn't
+  grant is closed.
+- **New env var:** `APP_PERMISSIONS` (comma-separated list, optional).
+  Default empty. Set automatically by `install --update-env`.
+- **Internal eval-harness cleanup.** The internal sim-setup helper
+  drops its standalone `grantPermissions` + `forceEnglishKeyboard`
+  routines (~70 lines) — both are now done by
+  `install --permissions=<kitchen-sink>`. Pregrant remains opt-in via
+  the existing `pregrantPermissions` option (default `true`).
+
+### Added — `a11y_tree` outline surfaces active iOS alerts (P2a)
+
+- **New `alert:` section in `mode: "outline"`.** When a native
+  `UIAlertController` is on screen its title, body, and button labels
+  appear as the first section of the outline, plus a `_meta.alert_active:
+  true` flag. Previously the alert lived in SpringBoard (outside the
+  app's a11y tree) and the agent kept tapping the underlying button
+  through the modal — usually the wrong one, sometimes destructive.
+- **Grammar contract.** The `alert:` section and `_meta.alert_active`
+  flag are cross-checked on parse: presence of one without the other is
+  a hard error, not a warning. Drift between them would silently put the
+  agent back in the "tap under the modal" failure mode.
+- **Wiring.** New `WdaHttpClient.alertButtons()` wraps
+  `GET /wda/alert/buttons`; `AlertController.readAlertButtons(slot)`
+  returns `string[] | null` (null when no alert is present). The
+  `a11y_tree` tool probes `readAlert` + `readAlertButtons` before
+  rendering — when both come back empty it skips the section entirely,
+  so the outline stays unchanged for non-alert screens.
+- Live-verified end-to-end: tap Sign Out → outline shows the
+  `Sign Out / Are you sure? / Cancel / Sign Out` alert → `dismiss_alert`
+  closes it, `accept_alert { button: "Sign Out" }` performs the real
+  logout. S13 (modal z-order) in the agent-blockers catalog is now
+  marked **partially fixed** — the native `UIAlertController` case is
+  closed; RN `<Modal>` remains open.
+
+### Fixed — three exploration → DSL bugs found in live acceptance (P2 follow-up)
+
+Live acceptance on a real app exposed three bugs the unit tests didn't
+cover. Each had its own root cause and its own fix:
+
+- **`//@collapse "Setup"` broke the vendor parser.** The generator
+  emitted bare-string-arg form, but vendor's `metaBlock()` expects
+  `//@collapse("Setup")` (paren'd call form). DSL view now emits the
+  paren'd form so the generated test parses.
+- **Generated tests didn't emit `setDevice("<slot>")`.** Without it the
+  runtime had no device selected and the first action threw "No device
+  selected". `DslViewService` now emits `setDevice(...)` as the first
+  line of the test body, derived from the exploration's slot.
+- **`AstExecutor` threw `UnsupportedAstNodeError "MetaBlockStatement"`.**
+  Meta blocks are a vendor AST node we need to round-trip transparently
+  (for future Blockly export). Added an `instanceof MetaBlockStatement`
+  branch that passes the body through without altering execution
+  semantics.
+
+After the fixes, `run_test` on a freshly-generated exploration returned
+`outcome: "completed"` for the first time end-to-end.
+
+### Fixed — `clean` now wipes the simulator keychain (B5)
+
+- **`appLaunch(clean: true)` and `app_install { clean: true }` now run
+  `simctl keychain <udid> reset`** between terminate/uninstall and the
+  next launch. Without this, auth tokens stored in the iOS Keychain
+  survived `simctl uninstall` (kSecAttrAccessibleWhenUnlocked without
+  bundle scoping), so the next launch silently landed on a logged-in
+  screen — defeating the "fresh state" intent of `clean: true`.
+- Behavior of the **default** `appLaunch()` / `app_install` (no `clean`)
+  is unchanged — keychain reset only fires when the caller explicitly
+  opts into a fresh state.
+- Keychain reset is invoked **unconditionally** in the `app_install
+  { clean: true }` flow even when `simctl uninstall` reports "app not
+  installed" — prior-run tokens may still linger, that's the whole
+  reason for B5.
+- MCP descriptions for `app_install`'s `clean` parameter and
+  `explore_step { action: "app_launch", clean: true }` updated.
+- The previously-required `xcrun simctl keychain booted reset` bash
+  workaround in `.claude/skills/write-e2e-test.md` (phase 5) is
+  removed; `app_install { clean: true }` now suffices.
+
+### Changed — MCP action surface unified into `explore_step` (BREAKING)
+
+- **`tap`, `type`, `swipe`, `press_key`, `wait_for`, `app_launch`,
+  `open_deeplink` MCP tools are removed.** Every UI action goes through
+  one tool — `explore_step { action: "tap" | "type" | … }`. The single
+  rule: passing `explorationId` records the call into an exploration
+  session; omitting it runs the action ad-hoc. There is no `record:
+  false` override.
+- **Alerts (`accept_alert`, `dismiss_alert`) appear here for the first
+  time as `explore_step` actions** — not as separate tools. The
+  Driver+DSL alert layer landed in P0; this release wires the MCP
+  entry point.
+- **New tools** — `explore_start`, `explore_stop`, `explore_state`,
+  `explore_step`, `explore_record`, `explore_remove_step`,
+  `generate_dsl_from_exploration`, `save_exploration_as_test`. The
+  `write-e2e-test` Claude Code skill covers the full surface.
+- **Recording-time reject:** `wait_for { optional: true }` cannot be
+  recorded — DSL `waitFor` has no optional semantics, so the
+  generated test would diverge. Use it ad-hoc.
+- **Recording-time warning:** `app_launch { bundleId }` is accepted
+  but `generate_dsl_from_exploration` emits `BUNDLE_ID_IGNORED` —
+  DSL `appLaunch()` reads the bundle from `APP_BUNDLE_ID` env.
+- **New env var:** `EXPLORATIONS_DIR` (default
+  `${ARTIFACTS_DIR}/explorations`). Append-only JSONL per session,
+  rescanned on MCP server restart to recover from crashes. Default
+  path is covered by the init template's `unotest/.gitignore`.
+
+Migration: any consumer that previously called `tap` / `type` / `swipe`
+/ `press_key` / `wait_for` / `app_launch` / `open_deeplink` directly
+through MCP must switch to `explore_step { action: <verb>, … }`. The
+JS-DSL functions of the same names (`tap()`, `type()`, …) are
+unchanged.
+
+### Changed — `a11y_tree` MCP tool returns a compact outline by default (BREAKING)
+
+- **New default `mode: "outline"`** — line-per-node text format with
+  hierarchy via indent + `on_screen` / `off_screen` partition against
+  the viewport. ~90% token reduction on typical mobile screens vs the
+  old compact JSON (measured on two captured UnoPeak screens: 4467 →
+  393 tokens, 4421 → 428 tokens; plan target was 60-75%, actual ~90%).
+  Grammar reference and full examples live in the
+  `write-e2e-test` Claude Code skill (phase 2).
+- **`mode: "compact"` REMOVED.** The pre-P1 compacted-JSON shape no
+  longer ships through MCP. Callers must use `mode: "outline"` (default)
+  or `mode: "full"` (raw JSON tree with bounds — escape hatch for
+  debugging / programmatic consumption).
+- **Off-screen partition** — nodes beyond viewport land in
+  `off_screen.{top,bottom,left,right}` as flat lists with stripped
+  identifiers; they're a HINT for the agent (which direction to scroll),
+  NOT a selector source. Duplicate-testId `@N` indexing is applied to
+  `on_screen` only (it'd be unstable across scrolls in `off_screen`).
+- **`clipped: side` flag** on `on_screen` entries that straddle the
+  viewport edge (e.g. a header sliding under the status bar).
+
+### Changed — `A11yNode.role` is normalized to short lowercase form (BREAKING, internal)
+
+- The WDA tree parser now strips the `XCUIElementType` prefix and
+  lowercases — `"XCUIElementTypeButton"` becomes `"button"`. Affects
+  any code that reads `A11yNode.role`:
+  selectors that matched on the full XCUI type string would silently
+  miss after this change. Internal-only — DSL surface unchanged.
+  Inspection layer (`isInteractiveRole`, `dedupeFields`, outline
+  renderer) consumes the normalized form via an exact-match Set.
+
+### Added — `InspectionDriver.windowSize(slot)`
+
+- Required by the new `treeInspector.semanticTree(raw, viewport)` flow
+  to partition nodes against viewport bounds. `WdaDriver` exposes it
+  via `/session/{id}/window/size` (same endpoint `swipe()` already used
+  internally; promoted to a public method).
+
+### Added — DSL linter: E5 (arity) + E6 (arg-type mismatch)
+
+- Linter now reads `argTypes` from FunctionRegistry and validates call
+  sites statically. E5 catches `tap()` (missing required arg) and
+  `tap(a, b)` (too many). E6 catches `swipe(getByTestId(...), "up")`
+  (selector where string expected) and similar reversed-args / wrong-
+  shape bugs before runtime. E6 only flags UNAMBIGUOUS shapes (literals,
+  built-in calls with known returnType) — variables, user-helper calls,
+  BinaryExpression are skipped to avoid false positives.
+- `DslFunction.variadic?: boolean` added; `dbQuery`/`dbExec`/`shell`
+  marked variadic so trailing SQL params / shell argv don't trigger E5.
+
+### Fixed — `bin/mcp.js` MCP-server entry hardcoded to `dist/`
+
+- Default-case (no subcommand) routed to `dist/mcp/server.js` unconditionally,
+  ignoring `UNOTEST_DEV`. Devs running with `UNOTEST_DEV=1` were silently
+  served the stale dist build, breaking iterative development. Now uses
+  the same `${baseDir}/mcp/server${ext}` pattern as other subcommands.
+
+### Added — native iOS alert handling
+
+- **Driver + DSL surface for native `UIAlertController` dialogs** —
+  permission prompts, ATT, Sign Out confirmations, iOS update banners.
+  Wraps WDA `/session/{id}/alert/{accept,dismiss,text}` endpoints, which
+  talk to SpringBoard's alert hierarchy instead of the app's a11y tree.
+  New DSL functions usable inside scenarios:
+  - `acceptAlert("label")` — tap a button by label (`"Allow Once"`,
+    `"Sign Out"`). **Recommended form** — label is the only path stable
+    across alert kinds and locales.
+  - `acceptAlert()` — no label. Falls back to WDA's position-based rule,
+    which is kind-dependent (UIAlertController: last button; action
+    sheet: first button — see FBAlert.m). Use only for single-button
+    modals or where the affirmative button has no stable label.
+  - `dismissAlert()` — position-based fallback for cancel (first button
+    on UIAlertController, last on action sheet).
+  - `readAlert()` — return title + body of the active alert as a string,
+    or throw `NoAlertPresentError` if none is on screen.
+  Before this, scenarios had no way to dismiss SpringBoard alerts: the
+  resolver-driven `tap(getByTestId(...))` couldn't reach buttons that
+  live outside the app process — `ordinal` selectors appeared to match
+  but the tap landed on the wrong element. Pre-granting permissions via
+  `xcrun simctl privacy` was the only workaround. MCP exposure (as
+  `explore_step` actions) lands in a follow-up.
+
+## [0.3.0] — 2026-05-15
+
+### Fixed
+
+- **MCP server no longer exits ~200ms after handshake.** `startMcpServer`
+  used to resolve once `server.connect(transport)` returned, which made
+  the outer wrapper call `process.exit(0)` and the client saw
+  `MCP error -32000: Connection closed`. The server now blocks on a
+  never-resolving promise; the only exits are via `transport.onclose`
+  or signal handlers, as intended. Affected anyone launching the server
+  via the no-arg `unotest-mobile` entry (`claude mcp add` flow).
+- **`BaseTool.tracked()` classifies structured failures as errors.**
+  Tools that return `this.fail(...)` / `this.failJson(...)` without
+  throwing (e.g. `app_install` on missing path) used to be recorded as
+  `result: "ok"` in the session log. They are now recorded as
+  `result: "error"` with `error_class: "ReturnedError"`. Thrown
+  exceptions get `error_class` set to the exception class name.
+
+### Added — skill
+
+- **`write-e2e-test` skill rewritten to discover-first / verify-by-running.**
+  Default mode walks the agent through interactive exploration
+  (`app_launch` → `a11y_tree` → `resolve_selector` → `tap`/`type`
+  per screen), then file write, then `run_test pauseOnFailure: true`,
+  then iterate until `next.outcome === "completed"`. A draft-only
+  fallback path triggers if MCP cannot reach a live app — the skill
+  marks the output as unverified and instructs the user to run
+  `npx unotest-mobile e2e <name>` later. Compared to the prior
+  write-only version: agent verifies the test against the live app
+  by default, no more "looks right, may not run" outputs.
+
+### Added — init / template
+
+- **`init` seeds `unotest/e2e/_template/example.js`** — canonical
+  syntax reference for AI agents and humans. First line is a sentinel
+  banner ("unotest-mobile JS-DSL — NOT Node.js. No import/export/
+  async/await…") so an agent reading the file picks up the DSL
+  constraints immediately, without having to consult the skill for
+  every quirk. The previous `_template.js` (TODO-scaffolding) stays
+  for human "copy to start" usage.
+
+### Added — session log
+
+- `SessionRecorder` now records `duration_ms`, `result_preview`
+  (truncated to 4 KB), `error_class`, and (under `SESSION_LOG_FULL=1`)
+  the full tool result. Schema additions are backward-compatible —
+  old entries still parse.
+- New env switches:
+  - `SESSION_LOG_DISABLE=1` (or empty `SESSION_LOG_PATH`) wires a
+    `NoopSessionRecorder` — no on-disk log, useful for CI / evals.
+  - `SESSION_LOG_FULL=1` — keep the full tool result alongside the
+    truncated preview.
+
+### Changed — docs
+
+- The consumer-facing manuals (quickstart, database-setup) no longer
+  hard-code `pnpm` in their examples. All consumer-side commands are
+  `npx unotest-mobile <cmd>` (works with npm / yarn / pnpm / bun
+  installs). The dev-only local-development manual keeps `pnpm` because
+  that's what contributors of this package use.
+- CLAUDE.md gains a "package-manager-agnostic commands in public
+  artifacts" section codifying the above rule.
+
+## [0.2.1] — 2026-05-14
+
+### Added
+
+- **Simulator runtime disambiguation.** When multiple simulators share
+  a name across iOS versions, pin to one via `SIM_A_NAME=<name> @
+  <runtime>` (e.g. `SIM_A_NAME=iPhone 16 @ iOS 17.5`). The runtime
+  part is matched as a substring of the friendly runtime name, so
+  partial values like `iOS 17` work too. The `Sim "X" not found` error
+  now lists all available sims with their runtime.
+
+### Fixed
+
+- CLI fatal-error output is now a clean one-liner (`✗ <message>`) instead
+  of a Node stack trace. Applies to `unotest-mobile install`, `e2e`,
+  `lint`, and the MCP server entry. Set `UNOTEST_DEBUG=1` to opt back
+  into stack traces when diagnosing harness-internal bugs.
+
+## [0.2.0] — 2026-05-14
+
+### Added
+
+- **`unotest-mobile install <path-to-.app>`** — new CLI subcommand to
+  install an iOS Simulator `.app` bundle on the configured slot(s). Reads
+  CFBundleIdentifier from Info.plist, warns on mismatch with
+  `APP_BUNDLE_ID` in `.env`, supports `--slot A|B|all` (default `A`),
+  `--clean` (uninstall existing), `--erase` (wipe sim — destructive),
+  `--launch` (sanity-check launch), `--update-env` (persist `APP_PATH`
+  and sync `APP_BUNDLE_ID`).
+- **`APP_PATH`** env var. When set in `unotest/.env`, `install` (CLI and
+  MCP) can be invoked without an explicit path. Useful for repeated
+  installs after each rebuild.
+- **`app_install` MCP tool** — same install logic as the CLI, exposed to
+  Claude Code / Desktop. With no args reads `APP_PATH`; otherwise returns
+  a structured `missing-app-path` error instructing the agent to ask the
+  user for the path, then call again with `path` + `updateEnv: true` to
+  persist.
+- **Pre-launch precondition check.** `WdaDriver.getSession()` now
+  verifies `APP_BUNDLE_ID` is installed on the target sim via `simctl
+  get_app_container` before starting the WDA session. If missing, throws
+  a clear actionable error pointing at `unotest-mobile install`.
+- `SimctlAdapter.isInstalled(udid, bundleId)` and
+  `SimctlAdapter.erase(udid)` — exposed on the adapter; ios-utils gains
+  matching `isAppInstalled` and `eraseSim`.
+
+### Changed
+
+- The `write-e2e-test` Claude Code skill gained a `Setup` section
+  covering install workflow, `--erase` / `--launch` / `--update-env`
+  flags, and the `app_install` MCP tool. The `When tests fail` table
+  also covers the new error modes (`App ... is not installed`,
+  `appLaunch needs a bundle id`, missing `DATABASE_URL` / `API_BASE_URL`,
+  driver-not-installed peer-dep error).
+- `unotest/.env.example` template adds a commented `APP_PATH=...` hint
+  next to `APP_BUNDLE_ID`.
+- `CLAUDE.md` adds a "Skill discipline" rule: any change to public
+  surface (CLI subcommands, MCP tools, DSL functions, linter codes, env
+  vars) must update the skill in the same commit.
+- The README inside the friend-test zip generated by
+  `unopeak/scripts/build-for-simulator.sh` now recommends
+  `npx @unotest/mobile install ./unopeak.app --launch --update-env` over
+  raw `simctl` commands.
+
+## [0.1.4] — 2026-05-14
+
+### Changed
+
+- **Most env vars are now optional.** Previously every variable in
+  `unotest/.env` was required at startup, even for scenarios that never
+  used the corresponding feature. Now the schema requires nothing
+  upfront — each var is validated at its actual use site:
+  - `APP_BUNDLE_ID` → required when a scenario calls `appLaunch()` or
+    starts a WDA session. Clear error if missing.
+  - `API_BASE_URL` → required when a scenario calls `apiCall(...)`.
+    The ApiClient is constructed lazily; missing-env stub throws a clear
+    error on first use.
+  - `DATABASE_URL` → required when a scenario calls `dbQuery(...)` /
+    `dbExec(...)`. The DbClient is constructed lazily; missing-env stub
+    throws a clear error on first use.
+  - `SIM_A_NAME` / `SIM_B_NAME` → schema-optional. Pool-aware validation
+    in `loadEnv()` requires the names only for slots actually present in
+    `SIM_POOL`. Improved error message points at the fix.
+  - `APP_URL_SCHEME`, `METRO_URL` → optional, reserved for future Expo
+    dev-client recovery flow (not yet wired).
+- The generated `unotest/.env.example` template reflects the new
+  optionality — only `SIM_A_NAME` / `SIM_POOL` and `WDA_PORTS` are
+  uncommented; everything else is shown as commented hints.
+
+### Removed
+
+- `INVITE_DEEPLINK_PREFIX` env var. It was required by the schema but
+  consumed nowhere in production code — a UnoPeak-specific leftover from
+  early MVP. Setting it now is a no-op (extra env vars are ignored).
+
+## [0.1.3] — 2026-05-14
+
+### Added
+
+- `unotest-mobile --version` / `-v` prints the package version.
+- `unotest-mobile --help` / `-h` prints a brief command summary.
+
+### Fixed
+
+- Meta flags (`--version`, `--help`) and unknown subcommands no longer
+  silently start the MCP server (which then crashed on missing
+  `unotest/.env`). Meta flags handled in the CLI dispatcher before any
+  environment load; unknown subcommands print a hint to stderr.
+
+## [0.1.2] — 2026-05-14
+
+### Fixed
+
+- Default `SESSION_LOG_PATH` and `ARTIFACTS_DIR` are now under `unotest/`
+  (`unotest/sessions/current.jsonl`, `unotest/artifacts`). Previously they
+  defaulted to bare `sessions/` and `artifacts/` at the consumer's project
+  root, which contradicted the `.gitignore` rules `init` writes
+  (`unotest/sessions/`, `unotest/artifacts/`) and polluted the project root.
+- DB driver "package not installed" error messages no longer hardcode
+  `pnpm add -D ...` — they now say `npm i -D ...` (with a note about your
+  package manager's equivalent).
+
+### Migration
+
+If you have an existing `unotest/.env` from `0.1.0` / `0.1.1` and want to
+adopt the new defaults, either delete the lines for `SESSION_LOG_PATH` and
+`ARTIFACTS_DIR` (defaults will kick in) or update them explicitly:
+
+```
+SESSION_LOG_PATH=unotest/sessions/current.jsonl
+ARTIFACTS_DIR=unotest/artifacts
+```
+
+Existing `sessions/` and `artifacts/` folders at the project root can be
+moved into `unotest/` or deleted.
+
+## [0.1.1] — 2026-05-14
+
+### Changed
+
+- `doctor` no longer warns when `package.json` lacks `react-native` / `expo`.
+  The harness drives iOS via WebDriverAgent, which works against any iOS app
+  (RN/Expo, native Swift/SwiftUI/Obj-C, Flutter exposing accessibility
+  semantics). The check is now an informational hint about the kind of
+  project detected, with guidance on `accessibilityIdentifier` for native
+  apps.
+
 ## [0.1.0] — 2026-05-14
 
 Initial public release.

package/README.md

@@ -77,10 +77,17 @@ function test_smoke_welcome() {
 
 After `init`, Claude Code (or any MCP-aware client) gets:
 
-**Low-level UI:**
-`devices_list`, `screenshot`, `a11y_tree`, `resolve_selector`, `tap`,
-`type`, `press_key`, `swipe`, `open_deeplink`, `app_launch`, `wait_for`,
-`session_reset`.
+**Discovery + lifecycle:**
+`devices_list`, `screenshot`, `a11y_tree`, `resolve_selector`,
+`app_install`, `session_reset`.
+
+**Exploration recording (P2):**
+`explore_start`, `explore_step`, `explore_record`, `explore_remove_step`,
+`explore_state`, `explore_stop`, `generate_dsl_from_exploration`,
+`save_exploration_as_test`. `explore_step` is the single execute-and-
+optionally-record entry point for all UI actions (tap, type, press_key,
+swipe, wait_for, app_launch, open_deeplink, accept_alert, dismiss_alert).
+Pass `explorationId` to record into a session, omit it for ad-hoc.
 
 **Pause-on-failure debugger:**
 `run_test` (with `pauseOnFailure: true`), `step`, `resume`,

package/bin/mcp.js

@@ -12,9 +12,10 @@
 // runtime — consumers don't install dev deps.
 
 import { spawn } from "node:child_process";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { dirname, resolve } from "node:path";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
 
 const here = dirname(fileURLToPath(import.meta.url));
 const root = resolve(here, "..");
@@ -22,19 +23,65 @@ const root = resolve(here, "..");
 const args = process.argv.slice(2);
 const sub = args[0];
 
+// Meta flags must work without environment setup — before unotest/.env
+// exists, before any subcommand context. Handle them in the dispatcher
+// before routing.
+if (sub === "--version" || sub === "-v") {
+  const pkg = JSON.parse(readFileSync(resolve(root, "package.json"), "utf8"));
+  process.stdout.write(`${pkg.version}\n`);
+  process.exit(0);
+}
+if (sub === "--help" || sub === "-h") {
+  process.stdout.write(
+    `unotest-mobile — AI-native E2E testing for iOS apps\n\n` +
+      `Usage: unotest-mobile [command] [...args]\n\n` +
+      `Commands:\n` +
+      `  init             Bootstrap a consumer project (env check + scaffold).\n` +
+      `  doctor           Re-run environment checks.\n` +
+      `  install <path>   Install a .app bundle on the configured simulator slot(s).\n` +
+      `  e2e <name>       Run scenario unotest/e2e/<name>.js.\n` +
+      `  lint             Static check of all scenarios + helpers.\n` +
+      `  (no command)     Run as MCP stdio server.\n\n` +
+      `Flags:\n` +
+      `  --version, -v    Print package version.\n` +
+      `  --help, -h       Show this help.\n\n` +
+      `Docs: https://www.npmjs.com/package/@unotest/mobile\n`,
+  );
+  process.exit(0);
+}
+
+// UNOTEST_DEV=1 — used by the evals harness (and useful for local dev)
+// to route subcommands through src/ via tsx instead of the prebuilt dist/.
+// Ensures `npx unotest-mobile lint` in a workdir runs against the CURRENT
+// source, not whatever happens to be in dist/ (or a published npm version).
+const dev = process.env.UNOTEST_DEV === "1";
+const ext = dev ? ".ts" : ".js";
+const baseDir = dev ? "src" : "dist";
+
 function dispatch(sub) {
   switch (sub) {
     case "init":
-      return { entry: "dist/runner/init.js", forwardArgs: args.slice(1) };
+      return { entry: `${baseDir}/runner/init${ext}`, forwardArgs: args.slice(1) };
     case "doctor":
-      return { entry: "dist/runner/doctor.js", forwardArgs: args.slice(1) };
+      return { entry: `${baseDir}/runner/doctor${ext}`, forwardArgs: args.slice(1) };
+    case "install":
+      return { entry: `${baseDir}/runner/install${ext}`, forwardArgs: args.slice(1) };
     case "lint":
-      return { entry: "dist/runner/cli.js", forwardArgs: ["lint"] };
+      return { entry: `${baseDir}/runner/cli${ext}`, forwardArgs: ["lint"] };
     case "e2e":
-      return { entry: "dist/runner/cli.js", forwardArgs: args.slice(1) };
+      return { entry: `${baseDir}/runner/cli${ext}`, forwardArgs: args.slice(1) };
     default:
       // No-arg invocation → MCP server (current claude mcp add behavior).
-      return { entry: "dist/mcp/server.js", forwardArgs: [] };
+      // Unknown subcommands also land here — print a hint to stderr so
+      // typos like `e2e init` (meant `init`) don't silently route into the
+      // MCP server with a confusing env error.
+      if (sub !== undefined) {
+        process.stderr.write(
+          `[unotest-mobile] unknown command "${sub}" — running MCP server. ` +
+            `See \`unotest-mobile --help\` for available commands.\n`,
+        );
+      }
+      return { entry: `${baseDir}/mcp/server${ext}`, forwardArgs: [] };
   }
 }
 
@@ -57,7 +104,18 @@ if (!paths.includes("/usr/bin") && existsSync("/usr/bin")) {
   env.PATH = `/usr/bin:${env.PATH ?? ""}`;
 }
 
-const child = spawn(process.execPath, [entryPath, ...forwardArgs], {
+// In dev mode, resolve tsx as a loader by absolute path (cwd-independent).
+// tsx walks up node_modules from this dispatcher's location, so it's
+// reliably found even when invoked from a workdir with no node_modules.
+const nodeArgs = [];
+if (dev) {
+  const req = createRequire(import.meta.url);
+  const tsxLoaderPath = req.resolve("tsx", { paths: [root] });
+  nodeArgs.push("--import", pathToFileURL(tsxLoaderPath).href);
+}
+nodeArgs.push(entryPath, ...forwardArgs);
+
+const child = spawn(process.execPath, nodeArgs, {
   stdio: "inherit",
   env,
   // No cwd override — inherit caller's cwd (consumer project root, where