zeno-mobile-runner 0.2.16 → 0.2.17

package/docs/config.md

@@ -1,16 +1,18 @@
 # App-Local Config
 
-ZMR uses `.zmr/config.json` as the app-local source of truth for default app ids,
-devices, scenario paths, and trace directories.
+Use `.zmr/config.json` to keep app-specific defaults in the app repository:
+app ids, device targets, scenario paths, trace directories, artifact settings,
+redaction rules, and shim command paths.
 
-The schema is published at `schemas/zmr-config.schema.json`.
-Runtime parsing follows the schema for primitive field types. For example,
+The schema is published at `schemas/zmr-config.schema.json`. Runtime parsing
+follows the schema for primitive field types. For example,
 boolean fields such as `artifacts.screenRecording`, `artifacts.screenshots`,
-`android.resetBeforeRun`, and `android.waitReady` must be JSON booleans, not
-strings. Path, id, redaction-list, and script command string fields must be
-non-empty. `zmr doctor --json --config .zmr/config.json` reports those type/value mistakes as
-structured `config` warnings. Unknown fields are rejected too, so typos in
-app-local config do not silently fall back to defaults.
+`android.resetBeforeRun`, `android.waitReady`, and `ios.ensureDevice` must be
+JSON booleans, not strings. Path, id, redaction-list, and script command string
+fields must be non-empty. `zmr doctor --json --config .zmr/config.json`
+reports those type/value mistakes as structured `config` warnings. Unknown
+fields are rejected too, so typos in app-local config do not silently fall back
+to defaults.
 
 Example:
 
@@ -29,13 +31,15 @@ Example:
     "avdSystemImage": "system-images;android-35;google_apis;arm64-v8a",
     "avdDeviceProfile": "pixel_6",
     "resetBeforeRun": false,
-    "waitReady": true
+    "waitReady": true,
+    "ensureDevice": true
   },
   "ios": {
     "enabled": true,
     "defaultDevice": "booted",
     "smokeScenario": ".zmr/ios-smoke.json",
-    "traceDir": "traces/zmr-ios"
+    "traceDir": "traces/zmr-ios",
+    "ensureDevice": true
   },
   "artifacts": {
     "screenshots": true,
@@ -68,12 +72,13 @@ invoked from another checkout. Relative optional tool commands such as
 `tools.adbPath` are resolved the same way when they look like paths; bare
 commands such as `adb`, `xcrun`, or `zig` stay as PATH lookups.
 
-Explicit CLI flags always win:
+Explicit CLI flags always win. Use config for stable app defaults and CLI flags
+for one-off local or CI overrides:
 
 - `--app-id` overrides `appId`
 - `--device` overrides platform `defaultDevice`
 - `--trace-dir` overrides platform `traceDir`
-- `--android-avd`, `--create-avd-if-missing`, `--avd-system-image`, `--avd-device`, `--restore-snapshot`, `--reset-emulator`, and `--wait-emulator` override Android emulator lifecycle defaults
+- `--android-avd`, `--create-avd-if-missing`, `--avd-system-image`, `--avd-device`, `--restore-snapshot`, `--reset-emulator`, `--wait-emulator`, `--ensure-device`, and `--no-ensure-device` override device lifecycle defaults
 - `--screen-record` and `--no-screen-record` override `artifacts.screenRecording`
 - a positional scenario path overrides platform `smokeScenario`
 - `--adb`, `--emulator`, `--avdmanager`, `--android-shim`, `--xcrun`, `--ios-shim`, and `--zig` override optional tool paths
@@ -83,6 +88,9 @@ Explicit CLI flags always win:
 The Android platform config can boot and wait for an emulator before a traced
 `zmr run` starts:
 
+- `ensureDevice`: when the requested Android device is not ready, boot the
+  configured `avdName`; if no `avdName` is configured, boot the first local AVD
+  from `emulator -list-avds`, then wait for `sys.boot_completed=1`.
 - `avdName`: AVD name passed to the Android emulator.
 - `createAvdIfMissing`: check `emulator -list-avds` and create the AVD when absent.
 - `avdSystemImage`: installed Android system image package for `avdmanager create avd`.
@@ -91,12 +99,18 @@ The Android platform config can boot and wait for an emulator before a traced
 - `resetBeforeRun`: best-effort `adb emu kill` before booting the configured AVD.
 - `waitReady`: wait for `adb wait-for-device` and `sys.boot_completed=1`.
 
-The equivalent CLI flags are `--android-avd <name>`,
+The equivalent CLI flags are `--ensure-device`, `--no-ensure-device`,
+`--android-avd <name>`,
 `--create-avd-if-missing`, `--avd-system-image <package>`,
 `--avd-device <profile>`, `--restore-snapshot <name>`, `--reset-emulator`,
 and `--wait-emulator`. AVD creation, snapshot restore, and reset require an AVD
 name. AVD creation also requires an installed system image package.
 
+For iOS simulator runs, `ensureDevice` or `--ensure-device` reuses an already
+booted simulator when one exists. If the target is `booted` and none are
+running, ZMR boots the first available shutdown simulator and waits for
+`simctl bootstatus -b`. Physical iOS devices are never auto-booted.
+
 ## Android Shim
 
 Set `tools.androidShimPath` when an app repo has built or installed an Android
@@ -127,7 +141,7 @@ CLI `--ios-shim <path>` takes precedence over the config value for `zmr run`,
 ## Artifact Capture
 
 The `artifacts` object controls what raw trace artifacts are persisted during
-`zmr run`.
+`zmr run`. Turn off raw artifacts when traces might leave a trusted machine.
 
 - `screenshots`: write PNG screenshot artifacts.
 - `hierarchy`: write raw Android UI hierarchy XML artifacts.

package/docs/demo.md

@@ -1,6 +1,8 @@
 # Demo
 
-Run the local demo with no emulator, simulator, app, or credentials:
+Run the local demo when you want a fast proof of the CLI, schemas, fake-device
+flows, reference clients, trace output, and diagnostics without an emulator,
+simulator, app build, or credentials:
 
 ```bash
 ./scripts/demo.sh
@@ -94,14 +96,15 @@ snapshot handling.
 Load any generated `.zmrtrace` in `viewer/index.html` to inspect the replay
 timeline, payloads, screenshot, UI tree, selected node details, and raw
 artifacts side-by-side. When the viewer and the bundle are served over HTTP,
-link straight to a loaded trace with `viewer/index.html?bundle=<url>` — useful
-for CI artifact links and shared triage.
+link straight to a loaded trace with `viewer/index.html?bundle=<url>`, which is
+useful for CI artifact links and shared triage.
 
 ![ZMR trace viewer with a loaded Android demo trace showing the timeline, device screenshot, and UI tree](assets/viewer-android.png)
 
 ## Real Android Pilot Demo
 
-Run the Android pilot against a sample app test build:
+Run the Android pilot against a sample app test build when you want real
+emulator/device evidence:
 
 ```bash
 ./scripts/run-android-pilot.sh \
@@ -109,11 +112,13 @@ Run the Android pilot against a sample app test build:
   --device emulator-5554
 ```
 
-To force a known emulator state, direct `zmr run` supports `--android-avd`,
-`--create-avd-if-missing`, `--avd-system-image`, `--avd-device`,
-`--restore-snapshot`, `--reset-emulator`, and `--wait-emulator`. The pilot
-wrapper accepts the same state controls while also building/installing the app.
-Add `--screen-record` to keep a pilot-level MP4 under the trace root:
+Direct `zmr run --ensure-device` can boot an Android emulator or iOS simulator
+before the scenario starts. To force a known Android emulator state, direct
+`zmr run` also supports `--android-avd`, `--create-avd-if-missing`,
+`--avd-system-image`, `--avd-device`, `--restore-snapshot`,
+`--reset-emulator`, and `--wait-emulator`. The pilot wrapper accepts the same
+state controls while also building/installing the app. Add `--screen-record` to
+keep a pilot-level MP4 under the trace root:
 
 ```bash
 ./scripts/run-android-pilot.sh \

package/docs/expo-smoke.md

@@ -1,9 +1,9 @@
 # Expo Smoke Test
 
-This is the quickest public smoke path for an Expo app. It proves that the npm
-package installs, the wizard scaffolds a scenario, ZMR can launch an iOS app,
-and the runner can produce screenshots, traces, HTML reports, JUnit XML, and
-redacted trace bundles.
+This is the quickest public smoke path for an Expo app. It proves the
+framework-neutral ZMR binary install, app-local scaffold, iOS app launch,
+screenshot capture, trace collection, HTML reporting, JUnit XML, and redacted
+export.
 
 Run the flow below on a local iOS simulator before treating a specific app build
 as validated.
@@ -11,12 +11,11 @@ as validated.
 ```bash
 npx create-expo-app@latest /tmp/zmr-expo-smoke --template blank --yes
 cd /tmp/zmr-expo-smoke
-npm install --save-dev zeno-mobile-runner
+curl -fsSL https://raw.githubusercontent.com/johnmikel/zeno-mobile-runner/main/install.sh | sh
+export PATH="$HOME/.local/bin:$PATH"
 
-npx zmr-wizard --yes --dir . \
-  --app-id com.example.zenoexposmoke \
-  --ios \
-  --package-json
+zmr init --app --dir . \
+  --app-id com.example.zenoexposmoke
 ```
 
 Boot a simulator, then build and launch the app:
@@ -29,14 +28,14 @@ npx expo run:ios --device <simulator-name>
 Run the generated ZMR scenario:
 
 ```bash
-npx zmr run .zmr/ios-smoke.json \
+zmr run .zmr/ios-smoke.json \
   --platform ios \
   --device booted \
   --trace-dir traces/zmr-ios \
   --json
 
-npx zmr report traces/zmr-ios --out traces/zmr-ios/report.html --junit traces/zmr-ios/junit.xml
-npx zmr export traces/zmr-ios --out traces/zmr-ios-redacted.zmrtrace --redact
+zmr report traces/zmr-ios --out traces/zmr-ios/report.html --junit traces/zmr-ios/junit.xml
+zmr export traces/zmr-ios --out traces/zmr-ios-redacted.zmrtrace --redact
 ```
 
 Expected result shape:
@@ -62,12 +61,7 @@ the XCTest shim described in [app integration](app-integration.md).
 Android follows the same pattern with a connected emulator or device:
 
 ```bash
-npx zmr-wizard --yes --dir . \
-  --app-id com.example.zenoexposmoke \
-  --android \
-  --package-json
-
-npx zmr run .zmr/android-smoke.json \
+zmr run .zmr/android-smoke.json \
   --platform android \
   --device emulator-5554 \
   --trace-dir traces/zmr-android \

package/docs/frameworks.md

@@ -2,25 +2,31 @@
 
 ZMR drives the installed mobile app through Android and iOS automation surfaces.
 It does not require a React Native, Expo, Flutter, Swift, Kotlin, or Java test
-SDK inside the app. The app only needs stable selectors and a predictable way to
-reach the screens you want to test.
+SDK inside the app. The app only needs stable selectors, predictable navigation,
+and build artifacts that ZMR can install or launch.
 
 ## React Native
 
-Use app-owned selectors for controls that agents need to find:
+Use app-owned selectors for controls that agents need to find repeatedly:
 
 - `testID` for Android resource ids and iOS accessibility identifiers.
-- `accessibilityLabel` for user-facing controls that should be visible to assistive technology.
-- Stable visible text for headings, tabs, and actions that are not localized or data-driven.
+- `accessibilityLabel` for user-facing controls that should be visible to
+  assistive technology.
+- Stable visible text for headings, tabs, and actions that are not localized or
+  data-driven.
 - Deep links for jumping directly to logged-in, onboarding, or error states.
 
-Keep generated ZMR files under `.zmr/` and run the wizard from the app repo:
+Keep generated ZMR files under `.zmr/` and initialize ZMR from the app repo:
 
 ```bash
-npx zmr-wizard --app-id com.example.mobiletest --package-json
+zmr init --app --app-id com.example.mobiletest
 ```
 
-To inspect a generated public fixture with a longer workflow:
+JavaScript teams that want generated package scripts can use
+`npx zmr-wizard --app-id com.example.mobiletest --package-json` instead.
+
+To inspect a generated public fixture with a longer workflow, use the npm
+helper from a JavaScript toolchain:
 
 ```bash
 npx zmr-create-react-native-expo-demo-app --out /tmp/zmr-rn-expo-demo
@@ -32,9 +38,11 @@ values, accessibility labels, and Android/iOS ZMR workflow scenarios under
 
 ## Expo
 
-Expo development builds work like React Native apps once they are installed on a
-simulator, emulator, or device. For dev-client flows, give ZMR the scheme that
-opens your development build:
+Expo development builds work like React Native apps once they are installed on
+an emulator, simulator, or device. `zmr init --app` creates baseline Android
+and iOS smoke scenarios. For dev-client flows that need generated open-link
+scenarios, use the JavaScript wizard and give ZMR the scheme that opens the
+development build:
 
 ```bash
 npx zmr-wizard \
@@ -43,15 +51,15 @@ npx zmr-wizard \
   --package-json
 ```
 
-The wizard adds Android and iOS dev-client scenarios that open Metro before
-selector assertions run.
+The wizard adds Android and iOS dev-client scenarios that open Metro
+before selector assertions run. For CI, prefer a known Metro command, stable
+deep link, and a prebuilt development client.
 
 ## Flutter
 
-ZMR supports Flutter apps at the platform level. It can launch the Android or
-iOS app, open deep links, wait for accessibility semantics, tap visible
-controls, type text, take screenshots, collect traces, and export redacted
-artifacts.
+ZMR supports Flutter apps at the Android/iOS app level. It can launch the app,
+open deep links, wait for accessibility semantics, tap visible controls, type
+text, take screenshots, collect traces, and export redacted artifacts.
 
 ZMR does not inspect Flutter widget trees, read Dart state, or replace Flutter's
 own widget/integration test APIs. For reliable ZMR scenarios, expose stable
@@ -66,8 +74,9 @@ Semantics(
 ```
 
 Prefer app-owned semantics labels for form fields, primary buttons, tabs, and
-important states. Deep links are the cleanest way to skip setup screens and reach
-the state an agent needs to inspect.
+important states. Deep links are the cleanest way to skip setup screens and
+reach the state an agent needs to inspect. Do not describe ZMR as a Flutter
+widget-tree driver.
 
 ## Native Android And iOS
 
@@ -76,7 +85,7 @@ Native apps should expose:
 - Android `resourceId` values or content descriptions for important controls.
 - iOS accessibility identifiers or labels for important controls.
 - Deep links for direct navigation into test states.
-- Optional Android and iOS shims when native selector actions and bounded
-  hierarchy snapshots are needed.
+- Optional Android and iOS/iPadOS shims when native selector actions and
+  bounded hierarchy snapshots are needed.
 
 See [app-integration.md](app-integration.md) for the shim setup commands.

package/docs/install.md

@@ -1,10 +1,52 @@
 # Install
 
-Most mobile app teams should install ZMR from npm inside the app repository.
-That keeps `.zmr/` config, scenarios, generated package scripts, and traces with
-the app they belong to.
+Install ZMR where the mobile app lives. That keeps `.zmr/` config, scenarios,
+generated package scripts, and trace output next to the app they verify.
 
-## npm Install
+Use the curl installer for the framework-neutral path. It installs the native
+`zmr` binary from the GitHub release archive for your OS and CPU, verifies the
+archive against `SHA256SUMS`, and leaves app setup to `zmr init --app`. npm
+remains the convenience path for JavaScript teams that want package scripts and
+helper bins in `node_modules/.bin`.
+
+## Curl Install
+
+Recommended path for native Android, native iOS, Flutter, React Native, Expo,
+and mixed mobile repositories:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/johnmikel/zeno-mobile-runner/main/install.sh | sh
+export PATH="$HOME/.local/bin:$PATH"
+zmr init --app --app-id com.example.mobiletest
+zmr doctor --strict --json --config .zmr/config.json
+```
+
+The installer defaults to the latest GitHub release. It downloads
+`zmr-<version>-<target>.tar.gz` plus `SHA256SUMS` from the release, and refuses
+to install when the archive checksum entry is missing or mismatched:
+
+```bash
+./install.sh --version 0.2.17 --dry-run
+```
+
+Dry-run output includes `checksum-verification: required`, the selected
+platform target, the archive URL, and the checksum URL. Use
+`--install-dir <dir>` to install somewhere other than `~/.local/bin`, or
+`--base-url <url>` when testing release candidates from a staging bucket.
+
+The native binary works the same way regardless of app framework:
+
+```bash
+zmr validate .zmr/android-smoke.json
+zmr run .zmr/android-smoke.json --device emulator-5554 --trace-dir traces/zmr-android --ensure-device
+zmr mcp --config .zmr/config.json --trace-dir traces/zmr-agent
+```
+
+## JavaScript Teams
+
+Use npm when the app repo wants ZMR pinned as a dev dependency, generated npm
+scripts, and the helper commands such as `zmr-wizard`,
+`zmr-install-android-shim`, `zmr-install-ios-shim`, and `zmr-device-matrix`:
 
 ```bash
 npm install --save-dev zeno-mobile-runner
@@ -13,8 +55,8 @@ npx zmr doctor --strict --json --config .zmr/config.json
 ```
 
 The wizard creates `.zmr/config.json`, Android and iOS smoke scenarios,
-`.zmr/device-matrix.json`, and `.zmr/AGENTS.md`. Run the generated validation
-before touching a device:
+`.zmr/device-matrix.json`, `.zmr/AGENTS.md`, and optional package scripts. Run
+the generated validation before touching a device:
 
 ```bash
 npm run zmr:validate
@@ -36,14 +78,17 @@ app-local `.zmr/` setup.
 
 ## Homebrew Or Existing Binary
 
-Teams that do not use JavaScript can install or build the `zmr` executable once
-and point any language client or script at it:
+Homebrew remains a native install option once you have a generated formula from
+the release artifacts:
 
 ```bash
 brew install --build-from-source ./dist/homebrew/zmr.rb
 zmr version
 ```
 
+Any existing `zmr` binary can also be used by language clients, MCP configs, or
+scripts as long as it matches the protocol version expected by the app repo.
+
 ## Build From Source
 
 ```bash
@@ -60,6 +105,9 @@ verification path used by CI and release gates.
 
 ## First Run Without A Device
 
+These commands prove the binary, schemas, and fake-device demo before device
+or simulator setup enters the loop:
+
 ```bash
 zmr version --json
 zmr schemas --json
@@ -71,8 +119,8 @@ zmr validate examples/demo-fake.json
 
 ## App Codebase Integration
 
-ZMR runs outside the app process and points at app build artifacts. For real app
-pilots, pass the app root, app id, target device, and optional shim paths:
+ZMR runs outside the app process and points at app build artifacts. For a real
+app pilot, pass the app root, app id, target device, and optional shim paths:
 
 ```bash
 npx zmr-pilot-gate \
@@ -91,6 +139,8 @@ npx zmr-pilot-gate \
   --evidence-out traces/zmr-pilots/evidence.jsonl
 ```
 
-See [app-integration.md](app-integration.md), [frameworks.md](frameworks.md),
-and [config.md](config.md) for framework guidance, shim setup, `.zmr/config.json`
-defaults, and CLI override precedence.
+Next:
+
+- [app-integration.md](app-integration.md): app-side test surface and shims
+- [frameworks.md](frameworks.md): React Native, Expo, Flutter, and native apps
+- [config.md](config.md): `.zmr/config.json` defaults and CLI precedence

package/docs/npm.md

@@ -1,12 +1,14 @@
 # npm Package
 
-ZMR can be installed in a mobile app codebase as a dev dependency:
+Install the npm package inside a mobile app repo when you want the `zmr` binary,
+setup wizard, app-local scripts, schemas, examples, clients, and agent skill to
+version with the app:
 
 ```bash
 npm install --save-dev zeno-mobile-runner
 ```
 
-The package exposes:
+The package exposes these command surfaces:
 
 - `zmr`: CLI binary wrapper.
 - `zmr-init`: app-local scenario scaffolder.
@@ -44,8 +46,8 @@ The package exposes:
 - packaged docs, schemas, examples, reference clients, and the reusable
   `skills/zmr-mobile-testing` agent skill.
 
-Most app teams can start with `zmr-wizard`, generated smoke scenarios, and
-redacted traces. Use the pilot and readiness helpers when you want repeated
+JavaScript app teams should start with `zmr-wizard`, generated smoke scenarios,
+and redacted traces. Use pilot and readiness helpers when you need repeated
 local evidence for your own app and devices.
 
 ## App Setup
@@ -67,25 +69,39 @@ This creates:
   AGENTS.md
 ```
 
-`.zmr/config.json` is the app-local source of truth for default devices, trace directories, smoke scenario paths, and suggested script commands. `.zmr/device-matrix.json` gives CI a ready Android/iOS matrix starting point. ZMR auto-discovers config from the app repo, and explicit CLI flags override it. The wizard does not inspect or depend on any other mobile test runner configuration.
-`.zmr/AGENTS.md` gives AI agents an app-local operating note with strict
-doctor/validate commands, schema discovery, direct `zmr run` smoke commands,
-JSON-RPC and MCP startup commands, selector guidance, the exact
-`zmr discover --from-trace traces/zmr-agent --out .zmr/discovered/replay-smoke.json --include-actions --validate --json`
-trace-to-test command,
-`zmr explain traces/zmr-agent --json` failure-triage command, the exact
-`zmr export traces/zmr-agent --out traces/zmr-agent-redacted.zmrtrace --redact`
-redacted trace export command.
-`zmr-init` and wizard runs without `--package-json` write direct commands in `.zmr/AGENTS.md` so agents can execute the generated guidance immediately.
-`zmr-init` accepts the same platform, shim, and Expo dev-client scaffold flags as the wizard, plus `--package-json` for non-interactive app templates that do not need dependency checks.
-`zmr-init` prints direct `Next steps` commands before the package-script snippet so humans and agents can run the generated smoke, reliability, matrix, pilot, JSON-RPC, MCP, failure-triage, and redacted-export commands without editing `package.json`.
+`.zmr/config.json` is the app-local source of truth for default devices, trace
+directories, smoke scenario paths, and suggested script commands.
+`.zmr/device-matrix.json` gives CI a ready Android/iOS matrix starting point.
+ZMR auto-discovers config from the app repo, and explicit CLI flags override it.
+The wizard does not inspect or depend on any other mobile test runner
+configuration.
+
+`.zmr/AGENTS.md` gives AI agents an app-local operating note with:
+
+- strict doctor and validation commands
+- schema discovery
+- direct `zmr run` smoke commands
+- JSON-RPC and MCP startup commands
+- selector guidance
+- trace-to-test discovery commands
+- failure-triage commands
+- redacted trace export commands
+
+`zmr-init` and wizard runs without `--package-json` write direct commands in
+`.zmr/AGENTS.md` so agents can execute the generated guidance immediately.
+`zmr-init` accepts the same platform, shim, and Expo dev-client scaffold flags
+as the wizard, plus `--package-json` for non-interactive app templates that do
+not need dependency checks.
 For setup scripts and AI agents that need a machine-readable handoff, use
 `npx zmr-init --json --dir . --app-id com.example.mobiletest` or
 `npx zmr-wizard --json --dir . --app-id com.example.mobiletest --android --ios`.
-The JSON form is covered by `schemas/init-output.schema.json` and includes
-the generated config, scenario, Expo dev-client scenario, device matrix, and
+The JSON form is covered by `schemas/init-output.schema.json` and includes the
+generated config, scenario, Expo dev-client scenario, device matrix, and
 `AGENTS.md` paths plus `nextCommands`, `scriptCount`, and `scriptNames`.
-Wizard runs with `--package-json` write npm script commands in `.zmr/AGENTS.md` because the wizard installs those scripts into `package.json`. Run `npm run zmr:validate` after editing generated scenarios and before starting longer smoke, matrix, or pilot runs.
+Wizard runs with `--package-json` write npm script commands in `.zmr/AGENTS.md`
+because the wizard installs those scripts into `package.json`. Run
+`npm run zmr:validate` after editing generated scenarios and before starting
+longer smoke, matrix, or pilot runs.
 
 Add app-local scripts:
 
@@ -95,11 +111,11 @@ Add app-local scripts:
     "zmr:doctor": "zmr doctor --strict --json --config .zmr/config.json",
     "zmr:schemas": "zmr schemas --json",
     "zmr:validate": "zmr validate --json .zmr/android-smoke.json && zmr validate --json .zmr/ios-smoke.json",
-    "zmr:android": "zmr run .zmr/android-smoke.json --device emulator-5554 --trace-dir traces/zmr-android",
+    "zmr:android": "zmr run .zmr/android-smoke.json --device emulator-5554 --trace-dir traces/zmr-android --ensure-device",
     "zmr:android:report": "zmr report traces/zmr-android --out traces/zmr-android/report.html --junit traces/zmr-android/junit.xml",
     "zmr:android:reliability": "export ZMR_BIN=\"${ZMR_BIN:-zmr}\"; zmr-benchmark --zmr .zmr/android-smoke.json --device emulator-5554 --app-id com.example.mobiletest --runs 20 --trace-root traces/zmr-android-reliability --min-pass-rate 100 --max-failures 0 --max-p95-ms 30000 && \"$ZMR_BIN\" report traces/zmr-android-reliability --out traces/zmr-android-reliability/report.html --junit traces/zmr-android-reliability/junit.xml",
     "zmr:matrix": "ZMR_BIN=${ZMR_BIN:-zmr} zmr-device-matrix --matrix .zmr/device-matrix.json --trace-root traces/zmr-matrix --min-pass-rate 100 --max-failures 0",
-    "zmr:ios": "zmr run .zmr/ios-smoke.json --platform ios --device booted --trace-dir traces/zmr-ios",
+    "zmr:ios": "zmr run .zmr/ios-smoke.json --platform ios --device booted --trace-dir traces/zmr-ios --ensure-device",
     "zmr:ios:report": "zmr report traces/zmr-ios --out traces/zmr-ios/report.html --junit traces/zmr-ios/junit.xml",
     "zmr:ios:reliability": "export ZMR_BIN=\"${ZMR_BIN:-zmr}\"; zmr-benchmark --zmr .zmr/ios-smoke.json --platform ios --device booted --app-id com.example.mobiletest --xcrun xcrun --runs 20 --trace-root traces/zmr-ios-reliability --min-pass-rate 100 --max-failures 0 --max-p95-ms 45000 && \"$ZMR_BIN\" report traces/zmr-ios-reliability --out traces/zmr-ios-reliability/report.html --junit traces/zmr-ios-reliability/junit.xml",
     "zmr:pilot": "zmr-pilot-gate --android --ios --android-app-root . --android-app-id com.example.mobiletest --android-device emulator-5554 --ios-app-root . --ios-app-path ./build/Debug-iphonesimulator/Sample.app --ios-app-id com.example.mobiletest --ios-device booted --runs 20 --min-pass-rate 100 --max-failures 0 --evidence-out traces/zmr-pilots/evidence.jsonl",
@@ -130,8 +146,9 @@ npx zmr-wizard \
   --package-json
 ```
 
-The wizard checks Node, ZMR, ADB, `xcrun`, and Zig when applicable. It scaffolds `.zmr` scenarios and can patch `package.json` scripts.
-It also ensures `traces/` is ignored in the app repo.
+The wizard checks Node, ZMR, ADB, `xcrun`, and Zig when applicable. It
+scaffolds `.zmr` scenarios, can patch `package.json` scripts, and ensures
+`traces/` is ignored in the app repo.
 When `--expo-dev-client-scheme` is set, it also writes
 `.zmr/android-dev-client-smoke.json` and `.zmr/ios-dev-client-open-link.json`.
 Package-script setup also adds `zmr:android:dev-client`,
@@ -165,8 +182,9 @@ Rerunning `zmr init --app` refreshes generated `.zmr/config.json`,
 `.zmr/device-matrix.json`, and `.zmr/AGENTS.md` the same way, while preserving
 existing scenario files. Pass `--force` only when you intentionally want to
 replace the generated smoke scenarios too.
-The reliability scripts use `zmr-benchmark` with `100%` pass-rate and zero-failure
-defaults; tune p95 thresholds only after capturing stable local baseline runs.
+The reliability scripts use `zmr-benchmark` with `100%` pass-rate and
+zero-failure defaults. Tune p95 thresholds only after capturing stable local
+baseline runs.
 The wizard only adds `zmr:readiness` for Android+iOS setups because the
 production readiness target requires Android, iOS simulator, and physical iOS
 evidence; single-platform setups should use `zmr:pilot` and the platform
@@ -179,8 +197,8 @@ explicit runner binary instead of relying on `PATH` or `ZMR_BIN`. Add
 `--evidence-out traces/zmr-pilots/evidence.jsonl` so production-readiness rows
 can be evaluated with `zmr-release-readiness`.
 
-The standalone CLI has the same non-interactive app-local bootstrap for
-source or release-archive installs:
+The standalone CLI has the same non-interactive app-local bootstrap for source
+or native-binary installs:
 
 ```bash
 zmr init --app --json --dir . --app-id com.example.mobiletest