zeno-mobile-runner 0.1.8 → 0.2.1

package/docs/benchmarks/benchmark-lab-v1.json

@@ -0,0 +1,155 @@
+{
+  "schemaVersion": 1,
+  "name": "Benchmark Lab v1",
+  "purpose": "Define reproducible mobile benchmark fixtures, modes, adapters, and claim boundaries for ZMR against framework-relevant local runners.",
+  "claimPolicy": {
+    "minimumRuns": 20,
+    "candidatePassRate": 100,
+    "candidateFailures": 0,
+    "requiresSameContext": true,
+    "requiresCommittedRows": true,
+    "requiresSanitizedCommands": true,
+    "forbiddenClaim": "Do not present fixture results as universal speed or reliability claims."
+  },
+  "modes": [
+    {
+      "id": "cold-command",
+      "label": "Cold command",
+      "description": "Each row measures the command surface a user would run from a shell, including runner startup."
+    },
+    {
+      "id": "warm-suite",
+      "label": "Warm suite",
+      "description": "The app, device, and runner bridge are prepared before timed rows so the benchmark isolates repeated scenario execution."
+    },
+    {
+      "id": "native-floor",
+      "label": "Native floor",
+      "description": "A lower-bound timing for the platform shim path. It is diagnostic evidence, not a product comparison."
+    }
+  ],
+  "fixtures": [
+    {
+      "id": "native-ios-workflow",
+      "label": "Generated native iOS workflow",
+      "framework": "native-ios",
+      "platforms": ["ios"],
+      "status": "evidence-committed",
+      "scenario": "examples/ios-shim-workflow.json",
+      "appGenerator": "scripts/create-ios-demo-app.sh",
+      "workflow": [
+        "launch",
+        "profile-entry",
+        "catalog-scroll",
+        "item-detail",
+        "save-item",
+        "review-assertion"
+      ],
+      "evidence": "docs/benchmarks/2026-06-09-ios-workflow-comparison.md"
+    },
+    {
+      "id": "native-android-workflow",
+      "label": "Generated native Android workflow",
+      "framework": "native-android",
+      "platforms": ["android"],
+      "status": "evidence-committed",
+      "scenario": "examples/android-workflow.json",
+      "appGenerator": "scripts/create-android-demo-app.sh",
+      "workflow": [
+        "launch",
+        "profile-entry",
+        "catalog-scroll",
+        "item-detail",
+        "save-item",
+        "review-assertion"
+      ],
+      "evidence": "docs/benchmarks/2026-06-09-android-workflow.md"
+    },
+    {
+      "id": "react-native-expo-workflow",
+      "label": "React Native and Expo workflow",
+      "framework": "react-native-expo",
+      "platforms": ["android", "ios"],
+      "status": "fixture-available",
+      "scenario": "examples/react-native-expo-workflow.json",
+      "appGenerator": "scripts/create-react-native-expo-demo-app.sh",
+      "workflow": [
+        "deep-link-open",
+        "profile-entry",
+        "list-scroll",
+        "stateful-save",
+        "review-assertion"
+      ],
+      "notes": "Generated fixture uses testID values, accessibility labels, and deep links. Public ZMR rows and baseline runner rows are not collected yet."
+    },
+    {
+      "id": "flutter-semantics-workflow",
+      "label": "Flutter semantics workflow",
+      "framework": "flutter",
+      "platforms": ["android", "ios"],
+      "status": "planned",
+      "workflow": [
+        "deep-link-open",
+        "semantics-label-selection",
+        "scroll",
+        "stateful-save",
+        "review-assertion"
+      ],
+      "notes": "Measure app-level Android/iOS automation through semantics labels and deep links. Do not claim widget-tree driver support."
+    }
+  ],
+  "runnerAdapters": [
+    {
+      "id": "zmr",
+      "label": "ZMR",
+      "status": "available",
+      "collector": "scripts/benchmark.sh",
+      "modes": ["cold-command", "warm-suite"]
+    },
+    {
+      "id": "maestro",
+      "label": "Maestro",
+      "status": "evidence-committed",
+      "collector": "scripts/benchmark-command.sh",
+      "modes": ["cold-command"]
+    },
+    {
+      "id": "appium",
+      "label": "Appium",
+      "status": "partial",
+      "collector": "scripts/benchmark-command.sh",
+      "modes": ["cold-command"],
+      "notes": "The current public iOS workflow attempt failed while starting WebDriverAgent, so fixture-specific setup hardening is required before timing rows."
+    },
+    {
+      "id": "detox",
+      "label": "Detox",
+      "status": "planned",
+      "collector": "scripts/benchmark-command.sh",
+      "modes": ["warm-suite"],
+      "notes": "Requires a React Native fixture with project-local native build targets and a test harness."
+    }
+  ],
+  "nextSlices": [
+    {
+      "id": "android-native-rows",
+      "status": "done",
+      "description": "Collect 20-run Android rows for the generated native workflow on a clean emulator."
+    },
+    {
+      "id": "react-native-expo-fixture",
+      "status": "done",
+      "description": "Add a generated React Native/Expo fixture with stable test IDs, deep links, and matching ZMR workflow files."
+    },
+    {
+      "id": "flutter-semantics-fixture",
+      "status": "next",
+      "description": "Add a Flutter fixture that proves app-level semantics support without widget-tree claims."
+    },
+    {
+      "id": "warm-suite-runner",
+      "status": "later",
+      "description": "Add suite-level benchmark collection so bridge prewarm and repeated scenario execution are measured separately from cold command startup."
+    }
+  ]
+}

package/docs/benchmarks/benchmark-lab-v1.md

@@ -0,0 +1,95 @@
+# Benchmark Lab v1
+
+Benchmark Lab v1 is the public evidence plan for ZMR. It keeps framework
+fixtures, runner adapters, timing modes, and claim boundaries explicit so speed
+or reliability statements are reproducible instead of anecdotal.
+It is the framework-level evidence map for React Native, Expo, Flutter, native
+Android, and native iOS fixtures.
+
+The machine-readable source is
+[benchmark-lab-v1.json](benchmark-lab-v1.json). Render or validate it with:
+
+```bash
+zmr-benchmark-lab --manifest docs/benchmarks/benchmark-lab-v1.json --format markdown
+zmr-benchmark-lab --manifest docs/benchmarks/benchmark-lab-v1.json --format json
+```
+
+## Direction
+
+ZMR should compete first where mobile teams already make framework choices:
+React Native, Expo, Flutter, native Android, and native iOS. The lab is not a
+generic benchmark scoreboard. Each fixture must represent an app workflow a
+developer can inspect, build, run, and adapt.
+
+The near-term wedge is agent-native mobile testing: structured observation,
+selector-grade actions, trace-first debugging, and reviewable scenario
+generation. Benchmarks should prove the local runner path is fast and reliable
+without overstating what one fixture demonstrates.
+
+## Fixtures
+
+| Fixture | Framework | Platforms | Status | Scenario |
+| --- | --- | --- | --- | --- |
+| Generated native iOS workflow | native-ios | iOS | evidence committed | `examples/ios-shim-workflow.json` |
+| Generated native Android workflow | native-android | Android | evidence committed | `examples/android-workflow.json` |
+| React Native and Expo workflow | react-native-expo | Android, iOS | fixture available | `examples/react-native-expo-workflow.json` |
+| Flutter semantics workflow | flutter | Android, iOS | planned | pending |
+
+The first richer iOS evidence pack is
+[2026-06-09 iOS simulator workflow comparison](2026-06-09-ios-workflow-comparison.md).
+It covers launch, profile entry, catalog scroll, item detail, save, review, and
+final-state assertion on the generated native iOS demo app.
+
+The first Android workflow evidence pack is
+[2026-06-09 Android emulator workflow](2026-06-09-android-workflow.md). It
+records 20 repeated ZMR runs through the platform UIAutomator path.
+
+The React Native/Expo fixture is available through
+`scripts/create-react-native-expo-demo-app.sh`. It generates an Expo app with
+stable `testID` values, accessibility labels, a deep-link scheme, and matching
+Android/iOS ZMR workflow scenarios. Public timing rows are still pending.
+
+## Runner Adapters
+
+| Adapter | Status | Collector | Notes |
+| --- | --- | --- | --- |
+| ZMR | available | `scripts/benchmark.sh` | Candidate runner for all fixtures. |
+| Maestro | evidence committed | `scripts/benchmark-command.sh` | Use YAML flows that match the same visible app state. |
+| Appium | partial | `scripts/benchmark-command.sh` | The current public iOS workflow attempt failed while starting WebDriverAgent, so setup needs hardening before timing rows. |
+| Detox | planned | `scripts/benchmark-command.sh` | Requires a React Native fixture with native build targets and a project-local test harness. |
+
+Other local runner rows can be collected with the same generic command wrapper,
+but public docs should only name tools when a fixture-specific evidence pack is
+available or when a status row explains why evidence is missing.
+
+## Modes
+
+| Mode | Meaning |
+| --- | --- |
+| Cold command | Measures the shell command a user runs, including runner startup. |
+| Warm suite | Prepares the app, device, and runner bridge before timed rows, isolating repeated scenario execution. |
+| Native floor | Measures a direct platform shim path as diagnostic lower-bound evidence, not a product comparison. |
+
+Cold-command rows are the best default for user-facing claims. Warm-suite rows
+are the best way to prove the core execution path can become faster without
+hiding setup work. Native-floor rows show where remaining overhead lives.
+
+## Claim Rules
+
+- Use at least 20 candidate rows and 20 baseline rows for public comparison
+  evidence.
+- Require 100% candidate pass rate and zero candidate failures for any public
+  speed claim.
+- Compare only rows with the same host class, OS/toolchain, device state, app
+  id, app build, scenario, and timing mode.
+- Commit sanitized result rows and commands. Do not commit raw trace logs when
+  they contain local absolute paths or app data.
+- Phrase every result as fixture-specific evidence. Do not describe one lab run
+  as a universal product claim.
+
+## Next Slices
+
+1. Add a Flutter semantics fixture that proves app-level Android/iOS support
+   without claiming widget-tree automation.
+2. Add warm-suite collection so bridge prewarm and repeated execution can be
+   measured separately from command startup.

package/docs/clients.md

@@ -3,6 +3,22 @@
 ZMR clients are reference implementations for the JSON-RPC protocol used by
 `zmr serve`. They are intentionally small and dependency-light.
 
+TypeScript and Python are the most common starting points for app teams and
+agent harnesses. Go, Rust, Swift, and Kotlin clients are reference integrations
+for teams that want to embed the protocol from those ecosystems. Go and Rust
+include typed trace discovery and scenario validation helpers for host-side
+agent loops; Swift and Kotlin include lightweight discovery and validation
+helpers for host-side automation.
+
+| Language | Entry point | Example |
+| --- | --- | --- |
+| TypeScript | `clients/typescript/index.mjs` + `index.d.ts` | `node clients/typescript/examples/fake-session.mjs` |
+| Python | `clients/python/zmr_client.py` + `pyproject.toml` | `python3 clients/python/examples/fake_session.py` |
+| Go | `clients/go/zmr/client.go` | `go run ./clients/go/examples/fake-session` |
+| Rust | `clients/rust/src/lib.rs` | `cargo run --manifest-path clients/rust/Cargo.toml --example fake_session` |
+| Swift | `clients/swift/Sources/ZMRClient` | `swift build --package-path clients/swift` |
+| Kotlin | `clients/kotlin/src/main/kotlin/dev/zmr` | `gradle -p clients/kotlin build` |
+
 ## What Clients Mean
 
 The runner is still the Zig binary. A client starts or connects to:

package/docs/demo.md

@@ -17,10 +17,13 @@ The script builds `zig-out/bin/zmr`, then runs:
 - `zmr validate examples/android-app-referral-deep-link.json`
 - `zmr validate examples/android-app-error-state.json`
 - `zmr validate examples/android-shim-smoke.json`
+- `zmr validate examples/android-workflow.json`
+- `zmr validate examples/react-native-expo-workflow.json`
 - `zmr validate examples/ios-smoke.json`
 - `zmr validate examples/ios-dev-client-open-link.json`
 - `zmr validate examples/ios-dev-client-route-snapshot.json`
 - `zmr validate examples/ios-shim-smoke.json`
+- `zmr validate examples/ios-shim-workflow.json`
 - expected-failing `zmr validate --json` output that shows `fieldPath`, `line`,
   and `column` for invalid scenarios covered by `schemas/validate-output.schema.json`
 - `zmr doctor --adb ./tests/fake-adb.sh --xcrun ./tests/fake-xcrun.sh --ios-shim ./tests/fake-ios-shim.sh`
@@ -81,6 +84,8 @@ The Swift and Kotlin reference client flows verify host-side native-language
 agent/test-harness integration for iOS and Android teams.
 The fake Android shim flow exercises shim-backed hierarchy, wait, tap, type,
 hide-keyboard, and snapshot handling.
+The React Native/Expo workflow example validates the framework fixture scenario
+that uses deep links, accessibility labels, and stable `testID` values.
 The fake iOS flow exercises simulator lifecycle, deep-link opening, screenshot
 artifact capture, log capture, and snapshot trace writing. The fake iOS shim
 flow exercises shim-backed hierarchy, wait, tap, type, hide-keyboard, and
@@ -88,7 +93,11 @@ 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.
+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.
+
+![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
 
@@ -185,6 +194,32 @@ zmr run /tmp/zmr-android-demo/.zmr/android-smoke.json \
 The scenario launches the app, waits for visible text, taps a button, types
 text into a field, and captures a trace-backed snapshot.
 
+## React Native And Expo Fixture
+
+To generate a public React Native and Expo app with stable test IDs,
+accessibility labels, deep-link routing, and matching Android/iOS ZMR workflow
+scenarios:
+
+```bash
+npx zmr-create-react-native-expo-demo-app --out /tmp/zmr-rn-expo-demo
+cd /tmp/zmr-rn-expo-demo
+bun install
+bunx expo start
+```
+
+After installing a development build on the target device, run the generated
+scenario for the platform you are measuring:
+
+```bash
+zmr run .zmr/react-native-expo-android-workflow.json \
+  --device emulator-5554 \
+  --app-id com.example.mobiletest \
+  --trace-dir traces/zmr-rn-expo-android
+```
+
+The fixture includes `expo-dev-client` and is available for benchmark
+collection, but it does not have public timing rows yet.
+
 ## Real iOS Simulator Demo
 
 To generate a small public demo app with the ZMR XCTest shim already installed:

package/docs/frameworks.md

@@ -20,6 +20,16 @@ Keep generated ZMR files under `.zmr/` and run the wizard from the app repo:
 npx zmr-wizard --app-id com.example.mobiletest --package-json
 ```
 
+To inspect a generated public fixture with a longer workflow:
+
+```bash
+npx zmr-create-react-native-expo-demo-app --out /tmp/zmr-rn-expo-demo
+```
+
+That fixture includes `expo-dev-client`, deep-link setup, stable `testID`
+values, accessibility labels, and Android/iOS ZMR workflow scenarios under
+`.zmr/`.
+
 ## Expo
 
 Expo development builds work like React Native apps once they are installed on a

package/docs/npm.md

@@ -33,6 +33,9 @@ The package exposes:
   matching `.zmr/` smoke scenario for public demos and emulator pilots.
 - `zmr-create-ios-demo-app`: creates a generic SwiftUI simulator app with
   `.zmr/` scenarios and the iOS shim already installed for public demos.
+- `zmr-create-react-native-expo-demo-app`: creates a generic React Native and
+  Expo app with stable `testID` values, accessibility labels, deep-link config,
+  and Android/iOS `.zmr/` workflow scenarios.
 - `zmr-demo-android`: creates, installs, and runs the generated Android demo
   through a real emulator/device.
 - `zmr-demo-ios`: creates, builds, and runs the generated iOS simulator demo
@@ -216,6 +219,24 @@ zmr run /tmp/zmr-android-demo/.zmr/android-smoke.json \
   --trace-dir /tmp/zmr-android-demo/traces/android-demo
 ```
 
+## React Native And Expo Demo Fixture
+
+Generate a public React Native and Expo app when you need a framework-level
+benchmark fixture before collecting timing rows:
+
+```bash
+npx zmr-create-react-native-expo-demo-app --out /tmp/zmr-rn-expo-demo
+cd /tmp/zmr-rn-expo-demo
+bun install
+bunx expo start
+```
+
+The generated app includes `expo-dev-client`, stable `testID` values,
+accessibility labels, an Expo deep-link scheme, and platform-specific ZMR
+workflow scenarios under `.zmr/`. After installing a development build on the
+target device, run the generated Android or iOS workflow scenario from the app
+directory.
+
 ## iOS Demo App
 
 For a clean public iOS demo that does not depend on a private app:
@@ -349,8 +370,12 @@ on the tag workflow:
 
 - Package: `zeno-mobile-runner`
 - Provider: GitHub Actions
-- Repository: `johnmikel/zeno-mobile-runner`
-- Workflow file: `release.yml`
+- Organization or user: `johnmikel`
+- Repository: `zeno-mobile-runner`
+- Workflow filename: `release.yml`
+- Environment name: leave blank unless the release job also declares a GitHub
+  deployment environment.
+- Allowed actions: `npm publish`
 
 The release workflow already requests `id-token: write`, builds the npm tarball
 from the tag, attests the generated release artifacts, uploads the GitHub
@@ -361,6 +386,23 @@ Trusted publishing requires a current npm runtime. The tag workflow uses Node
 24 so the npm CLI can exchange the GitHub Actions OIDC identity for publish
 authorization.
 
+With `npm@11.10.0` or newer, maintainers can also configure the same trust
+relationship from an authenticated local shell:
+
+```bash
+npm trust list zeno-mobile-runner
+npm trust github zeno-mobile-runner \
+  --repo johnmikel/zeno-mobile-runner \
+  --file release.yml \
+  --allow-publish
+```
+
+If `npm trust` is not available, update npm or use the package settings page on
+npmjs.com. A failed publish with `E404` for an existing package usually means
+the trusted-publisher configuration is missing, points at a different GitHub
+owner/repository/workflow filename, names an environment that the workflow does
+not use, or does not allow `npm publish`.
+
 ### Manual publish with passkey or 2FA
 
 Use trusted publishing for normal tagged releases. If you need to publish a

package/docs/protocol-fixtures/core-session.responses.jsonl

@@ -1,4 +1,4 @@
-{"jsonrpc":"2.0","id":1,"result":{"name":"zmr","version":"0.1.8","protocolVersion":"2026-04-28","protocol":{"version":"2026-04-28","minimumCompatibleVersion":"2026-04-28","stability":"dev-preview","breakingChangePolicy":"version-and-changelog"},"platforms":["android","ios"],"platformSupport":{"android":{"status":"supported","deviceTypes":["emulator","physical"],"automation":["adb","uiautomator","android-shim"]},"ios":{"status":"supported","deviceTypes":["simulator","physical"],"automation":["simctl","devicectl","xctest-shim"],"physicalDevices":true}},"iosPreview":false,"transports":["stdio","tcp"],"methods":["runner.capabilities","device.list","session.create","session.close","app.install","app.launch","app.stop","app.openLink","app.clearState","observe.snapshot","observe.semanticSnapshot","ui.tap","ui.type","ui.eraseText","ui.hideKeyboard","ui.swipe","ui.pressBack","ui.scrollUntilVisible","wait.until","wait.any","wait.gone","assert.visible","assert.notVisible","assert.healthy","scenario.validate","trace.events","trace.explore","trace.discover","trace.explain","trace.export"]}}
+{"jsonrpc":"2.0","id":1,"result":{"name":"zmr","version":"0.2.1","protocolVersion":"2026-04-28","protocol":{"version":"2026-04-28","minimumCompatibleVersion":"2026-04-28","stability":"dev-preview","breakingChangePolicy":"version-and-changelog"},"platforms":["android","ios"],"platformSupport":{"android":{"status":"supported","deviceTypes":["emulator","physical"],"automation":["adb","uiautomator","android-shim"]},"ios":{"status":"supported","deviceTypes":["simulator","physical"],"automation":["simctl","devicectl","xctest-shim"],"physicalDevices":true}},"iosPreview":false,"transports":["stdio","tcp"],"methods":["runner.capabilities","device.list","session.create","session.close","app.install","app.launch","app.stop","app.openLink","app.clearState","observe.snapshot","observe.semanticSnapshot","ui.tap","ui.type","ui.eraseText","ui.hideKeyboard","ui.swipe","ui.pressBack","ui.scrollUntilVisible","wait.until","wait.any","wait.gone","assert.visible","assert.notVisible","assert.healthy","scenario.validate","trace.events","trace.explore","trace.discover","trace.explain","trace.export"]}}
 {"jsonrpc":"2.0","id":2,"result":[{"serial":"fake-device-1","state":"device","ready":true}]}
 {"jsonrpc":"2.0","id":3,"result":{"sessionId":"default"}}
 {"jsonrpc":"2.0","id":4,"result":true}

package/docs/protocol.md

@@ -2,7 +2,7 @@
 
 ZMR exposes newline-delimited JSON-RPC 2.0 over stdio or localhost TCP in v1. Each request is one JSON object followed by `\n`. Each response is one JSON object followed by `\n`.
 
-Current runner version: `0.1.8`.
+Current runner version: `0.2.1`.
 
 Current protocol version: `2026-04-28`.
 
@@ -47,7 +47,7 @@ and protocol versions. The response is covered by
 `schemas/inspect-output.schema.json`:
 
 ```json
-{"ok":true,"status":"ready","schemaVersion":1,"runnerVersion":"0.1.8","protocolVersion":"2026-04-28","dir":".","configPath":".zmr/config.json","configExists":true,"agentInstructionsPath":".zmr/AGENTS.md","agentInstructionsExists":true,"platforms":[{"name":"android","enabled":true,"defaultDevice":"emulator-5554","smokeScenario":".zmr/android-smoke.json","smokeScenarioExists":true,"traceDir":"traces/zmr-android"},{"name":"ios","enabled":true,"defaultDevice":"booted","smokeScenario":".zmr/ios-smoke.json","smokeScenarioExists":true,"traceDir":"traces/zmr-ios"}],"recommendedCommands":["zmr doctor --strict --json --config .zmr/config.json","zmr schemas --json","zmr validate --json .zmr/android-smoke.json","zmr validate --json .zmr/ios-smoke.json","zmr serve --transport stdio --config .zmr/config.json --trace-dir traces/zmr-agent","zmr mcp --config .zmr/config.json --trace-dir traces/zmr-agent"],"claimsPolicy":["verify runs with trace evidence before making readiness claims","do not claim Flutter widget-tree inspection"],"limitations":["inspect is read-only and does not launch devices","autonomous crawling is not shipped; generate or edit scenarios for human review"]}
+{"ok":true,"status":"ready","schemaVersion":1,"runnerVersion":"0.2.1","protocolVersion":"2026-04-28","dir":".","configPath":".zmr/config.json","configExists":true,"agentInstructionsPath":".zmr/AGENTS.md","agentInstructionsExists":true,"platforms":[{"name":"android","enabled":true,"defaultDevice":"emulator-5554","smokeScenario":".zmr/android-smoke.json","smokeScenarioExists":true,"traceDir":"traces/zmr-android"},{"name":"ios","enabled":true,"defaultDevice":"booted","smokeScenario":".zmr/ios-smoke.json","smokeScenarioExists":true,"traceDir":"traces/zmr-ios"}],"recommendedCommands":["zmr doctor --strict --json --config .zmr/config.json","zmr schemas --json","zmr validate --json .zmr/android-smoke.json","zmr validate --json .zmr/ios-smoke.json","zmr serve --transport stdio --config .zmr/config.json --trace-dir traces/zmr-agent","zmr mcp --config .zmr/config.json --trace-dir traces/zmr-agent"],"claimsPolicy":["verify runs with trace evidence before making readiness claims","do not claim Flutter widget-tree inspection"],"limitations":["inspect is read-only and does not launch devices","autonomous crawling is not shipped; generate or edit scenarios for human review"]}
 ```
 
 `zmr discover --from-trace <trace-dir> --out <scenario.json> --validate --json`
@@ -60,7 +60,7 @@ invent credentials, or commit files. The response is covered by
 `schemas/discover-output.schema.json`:
 
 ```json
-{"ok":true,"mode":"discover","schemaVersion":1,"runnerVersion":"0.1.8","protocolVersion":"2026-04-28","out":".zmr/discovered/replay-smoke.json","traceDir":"traces/zmr-agent","sourceSnapshot":"traces/zmr-agent/artifacts/snapshot-2.json","name":"draft from login smoke","appId":"com.example.mobiletest","selectorCount":2,"stepCount":6,"replay":{"enabled":true,"eventCount":4,"stepCount":3,"skippedEventCount":1},"warnings":["draft requires human review before commit"],"validated":true,"validation":{"ok":true,"path":".zmr/discovered/replay-smoke.json","name":"draft from login smoke","appId":"com.example.mobiletest","stepCount":6},"nextCommands":["zmr validate --json .zmr/discovered/replay-smoke.json","zmr run .zmr/discovered/replay-smoke.json --json --trace-dir traces/zmr-agent"]}
+{"ok":true,"mode":"discover","schemaVersion":1,"runnerVersion":"0.2.1","protocolVersion":"2026-04-28","out":".zmr/discovered/replay-smoke.json","traceDir":"traces/zmr-agent","sourceSnapshot":"traces/zmr-agent/artifacts/snapshot-2.json","name":"draft from login smoke","appId":"com.example.mobiletest","selectorCount":2,"stepCount":6,"replay":{"enabled":true,"eventCount":4,"stepCount":3,"skippedEventCount":1},"warnings":["draft requires human review before commit"],"validated":true,"validation":{"ok":true,"path":".zmr/discovered/replay-smoke.json","name":"draft from login smoke","appId":"com.example.mobiletest","stepCount":6},"nextCommands":["zmr validate --json .zmr/discovered/replay-smoke.json","zmr run .zmr/discovered/replay-smoke.json --json --trace-dir traces/zmr-agent"]}
 ```
 
 `zmr explore --from-trace <trace-dir> --out <scenario.json> --goal <goal>
@@ -71,7 +71,7 @@ launch devices, crawl the app, invent missing actions, discover credentials, or
 commit files. The response is covered by `schemas/explore-output.schema.json`:
 
 ```json
-{"ok":true,"mode":"explore","schemaVersion":1,"runnerVersion":"0.1.8","protocolVersion":"2026-04-28","goal":"find a stable login smoke","autonomous":false,"reviewRequired":true,"guardrails":["writes from existing trace evidence only","does not crawl the app","does not discover credentials or secrets","requires human review before commit"],"out":".zmr/discovered/login-smoke.json","traceDir":"traces/zmr-agent","sourceSnapshot":"traces/zmr-agent/artifacts/snapshot-2.json","name":"draft from login smoke","appId":"com.example.mobiletest","selectorCount":2,"stepCount":6,"replay":{"enabled":true,"eventCount":4,"stepCount":3,"skippedEventCount":1},"warnings":["draft requires human review before commit"],"validated":true,"validation":{"ok":true,"path":".zmr/discovered/login-smoke.json","name":"draft from login smoke","appId":"com.example.mobiletest","stepCount":6},"nextCommands":["zmr validate --json .zmr/discovered/login-smoke.json","zmr run .zmr/discovered/login-smoke.json --json --trace-dir traces/zmr-agent"]}
+{"ok":true,"mode":"explore","schemaVersion":1,"runnerVersion":"0.2.1","protocolVersion":"2026-04-28","goal":"find a stable login smoke","autonomous":false,"reviewRequired":true,"guardrails":["writes from existing trace evidence only","does not crawl the app","does not discover credentials or secrets","requires human review before commit"],"out":".zmr/discovered/login-smoke.json","traceDir":"traces/zmr-agent","sourceSnapshot":"traces/zmr-agent/artifacts/snapshot-2.json","name":"draft from login smoke","appId":"com.example.mobiletest","selectorCount":2,"stepCount":6,"replay":{"enabled":true,"eventCount":4,"stepCount":3,"skippedEventCount":1},"warnings":["draft requires human review before commit"],"validated":true,"validation":{"ok":true,"path":".zmr/discovered/login-smoke.json","name":"draft from login smoke","appId":"com.example.mobiletest","stepCount":6},"nextCommands":["zmr validate --json .zmr/discovered/login-smoke.json","zmr run .zmr/discovered/login-smoke.json --json --trace-dir traces/zmr-agent"]}
 ```
 
 `zmr draft --from-trace <trace-dir> --out <scenario.json> --json` is the lower
@@ -84,7 +84,7 @@ into fields, or commit files. The response is covered by
 `schemas/draft-output.schema.json`:
 
 ```json
-{"ok":true,"mode":"draft","schemaVersion":1,"runnerVersion":"0.1.8","protocolVersion":"2026-04-28","out":".zmr/discovered/surface-smoke.json","traceDir":"traces/zmr-agent","sourceSnapshot":"traces/zmr-agent/artifacts/snapshot-2.json","name":"draft from login smoke","appId":"com.example.mobiletest","selectorCount":2,"stepCount":4,"replay":{"enabled":false,"eventCount":0,"stepCount":0,"skippedEventCount":0},"warnings":["draft requires human review before commit"],"nextCommands":["zmr validate --json .zmr/discovered/surface-smoke.json","zmr run .zmr/discovered/surface-smoke.json --json --trace-dir traces/zmr-agent"]}
+{"ok":true,"mode":"draft","schemaVersion":1,"runnerVersion":"0.2.1","protocolVersion":"2026-04-28","out":".zmr/discovered/surface-smoke.json","traceDir":"traces/zmr-agent","sourceSnapshot":"traces/zmr-agent/artifacts/snapshot-2.json","name":"draft from login smoke","appId":"com.example.mobiletest","selectorCount":2,"stepCount":4,"replay":{"enabled":false,"eventCount":0,"stepCount":0,"skippedEventCount":0},"warnings":["draft requires human review before commit"],"nextCommands":["zmr validate --json .zmr/discovered/surface-smoke.json","zmr run .zmr/discovered/surface-smoke.json --json --trace-dir traces/zmr-agent"]}
 ```
 
 `zmr draft --include-actions` additionally parses `events.jsonl` and prepends
@@ -214,7 +214,7 @@ installers, setup scripts, and generated clients. The response is covered by
 `schemas/version-output.schema.json`:
 
 ```json
-{"name":"zmr","version":"0.1.8","protocolVersion":"2026-04-28","minimumCompatibleProtocolVersion":"2026-04-28","stability":"dev-preview","breakingChangePolicy":"version-and-changelog"}
+{"name":"zmr","version":"0.2.1","protocolVersion":"2026-04-28","minimumCompatibleProtocolVersion":"2026-04-28","stability":"dev-preview","breakingChangePolicy":"version-and-changelog"}
 ```
 
 ## Capabilities Output Contract
@@ -226,7 +226,7 @@ and method inventory for JSON-RPC clients. The result object is covered by
 iOS simulator, or physical iOS workflows are available.
 
 ```json
-{"name":"zmr","version":"0.1.8","protocolVersion":"2026-04-28","protocol":{"version":"2026-04-28","minimumCompatibleVersion":"2026-04-28","stability":"dev-preview","breakingChangePolicy":"version-and-changelog"},"platforms":["android","ios"],"platformSupport":{"android":{"status":"supported","deviceTypes":["emulator","physical"],"automation":["adb","uiautomator","android-shim"]},"ios":{"status":"supported","deviceTypes":["simulator","physical"],"automation":["simctl","devicectl","xctest-shim"],"physicalDevices":true}},"iosPreview":false,"transports":["stdio","tcp"],"methods":["runner.capabilities","device.list","session.create","session.close","app.install","app.launch","app.stop","app.openLink","app.clearState","observe.snapshot","observe.semanticSnapshot","ui.tap","ui.type","ui.eraseText","ui.hideKeyboard","ui.swipe","ui.pressBack","ui.scrollUntilVisible","wait.until","wait.any","wait.gone","assert.visible","assert.notVisible","assert.healthy","scenario.validate","trace.events","trace.explore","trace.discover","trace.explain","trace.export"]}
+{"name":"zmr","version":"0.2.1","protocolVersion":"2026-04-28","protocol":{"version":"2026-04-28","minimumCompatibleVersion":"2026-04-28","stability":"dev-preview","breakingChangePolicy":"version-and-changelog"},"platforms":["android","ios"],"platformSupport":{"android":{"status":"supported","deviceTypes":["emulator","physical"],"automation":["adb","uiautomator","android-shim"]},"ios":{"status":"supported","deviceTypes":["simulator","physical"],"automation":["simctl","devicectl","xctest-shim"],"physicalDevices":true}},"iosPreview":false,"transports":["stdio","tcp"],"methods":["runner.capabilities","device.list","session.create","session.close","app.install","app.launch","app.stop","app.openLink","app.clearState","observe.snapshot","observe.semanticSnapshot","ui.tap","ui.type","ui.eraseText","ui.hideKeyboard","ui.swipe","ui.pressBack","ui.scrollUntilVisible","wait.until","wait.any","wait.gone","assert.visible","assert.notVisible","assert.healthy","scenario.validate","trace.events","trace.explore","trace.discover","trace.explain","trace.export"]}
 ```
 
 ## Doctor Output Contract
@@ -432,7 +432,7 @@ Request:
 Response:
 
 ```json
-{"jsonrpc":"2.0","id":1,"result":{"name":"zmr","version":"0.1.8","protocolVersion":"2026-04-28","protocol":{"version":"2026-04-28","minimumCompatibleVersion":"2026-04-28","stability":"dev-preview","breakingChangePolicy":"version-and-changelog"},"platforms":["android","ios"],"platformSupport":{"android":{"status":"supported","deviceTypes":["emulator","physical"],"automation":["adb","uiautomator","android-shim"]},"ios":{"status":"supported","deviceTypes":["simulator","physical"],"automation":["simctl","devicectl","xctest-shim"],"physicalDevices":true}},"iosPreview":false,"transports":["stdio","tcp"],"methods":["runner.capabilities","device.list","session.create","session.close","app.install","app.launch","app.stop","app.openLink","app.clearState","observe.snapshot","observe.semanticSnapshot","ui.tap","ui.type","ui.eraseText","ui.hideKeyboard","ui.swipe","ui.pressBack","ui.scrollUntilVisible","wait.until","wait.any","wait.gone","assert.visible","assert.notVisible","assert.healthy","scenario.validate","trace.events","trace.explore","trace.discover","trace.explain","trace.export"]}}
+{"jsonrpc":"2.0","id":1,"result":{"name":"zmr","version":"0.2.1","protocolVersion":"2026-04-28","protocol":{"version":"2026-04-28","minimumCompatibleVersion":"2026-04-28","stability":"dev-preview","breakingChangePolicy":"version-and-changelog"},"platforms":["android","ios"],"platformSupport":{"android":{"status":"supported","deviceTypes":["emulator","physical"],"automation":["adb","uiautomator","android-shim"]},"ios":{"status":"supported","deviceTypes":["simulator","physical"],"automation":["simctl","devicectl","xctest-shim"],"physicalDevices":true}},"iosPreview":false,"transports":["stdio","tcp"],"methods":["runner.capabilities","device.list","session.create","session.close","app.install","app.launch","app.stop","app.openLink","app.clearState","observe.snapshot","observe.semanticSnapshot","ui.tap","ui.type","ui.eraseText","ui.hideKeyboard","ui.swipe","ui.pressBack","ui.scrollUntilVisible","wait.until","wait.any","wait.gone","assert.visible","assert.notVisible","assert.healthy","scenario.validate","trace.events","trace.explore","trace.discover","trace.explain","trace.export"]}}
 ```
 
 ### `trace.events`
@@ -514,7 +514,7 @@ Request:
 Response:
 
 ```json
-{"jsonrpc":"2.0","id":25,"result":{"ok":true,"mode":"discover","schemaVersion":1,"runnerVersion":"0.1.8","protocolVersion":"2026-04-28","out":".zmr/discovered/agent-smoke.json","traceDir":"traces/agent-session","sourceSnapshot":"traces/agent-session/artifacts/snapshot-1.json","name":"agent smoke","appId":"com.example.mobiletest","selectorCount":1,"stepCount":4,"replay":{"enabled":true,"eventCount":2,"stepCount":1,"skippedEventCount":1},"warnings":["draft requires human review before commit"],"validated":true,"validation":{"ok":true,"path":".zmr/discovered/agent-smoke.json","name":"agent smoke","appId":"com.example.mobiletest","stepCount":4},"nextCommands":["zmr validate --json .zmr/discovered/agent-smoke.json","zmr run .zmr/discovered/agent-smoke.json --json --trace-dir traces/agent-session"]}}
+{"jsonrpc":"2.0","id":25,"result":{"ok":true,"mode":"discover","schemaVersion":1,"runnerVersion":"0.2.1","protocolVersion":"2026-04-28","out":".zmr/discovered/agent-smoke.json","traceDir":"traces/agent-session","sourceSnapshot":"traces/agent-session/artifacts/snapshot-1.json","name":"agent smoke","appId":"com.example.mobiletest","selectorCount":1,"stepCount":4,"replay":{"enabled":true,"eventCount":2,"stepCount":1,"skippedEventCount":1},"warnings":["draft requires human review before commit"],"validated":true,"validation":{"ok":true,"path":".zmr/discovered/agent-smoke.json","name":"agent smoke","appId":"com.example.mobiletest","stepCount":4},"nextCommands":["zmr validate --json .zmr/discovered/agent-smoke.json","zmr run .zmr/discovered/agent-smoke.json --json --trace-dir traces/agent-session"]}}
 ```
 
 Without `--trace-dir`, it returns `ok: false` with `traceDir: null`. Generated
@@ -537,7 +537,7 @@ Request:
 Response:
 
 ```json
-{"jsonrpc":"2.0","id":27,"result":{"ok":true,"mode":"explore","schemaVersion":1,"runnerVersion":"0.1.8","protocolVersion":"2026-04-28","out":".zmr/discovered/agent-goal.json","traceDir":"traces/agent-session","sourceSnapshot":"traces/agent-session/artifacts/snapshot-1.json","name":"agent goal smoke","appId":"com.example.mobiletest","selectorCount":1,"stepCount":4,"replay":{"enabled":true,"eventCount":2,"stepCount":1,"skippedEventCount":1},"warnings":["draft requires human review before commit"],"validated":true,"validation":{"ok":true,"path":".zmr/discovered/agent-goal.json","name":"agent goal smoke","appId":"com.example.mobiletest","stepCount":4},"nextCommands":["zmr validate --json .zmr/discovered/agent-goal.json","zmr run .zmr/discovered/agent-goal.json --json --trace-dir traces/agent-session"],"goal":"find a stable login smoke","autonomous":false,"reviewRequired":true,"guardrails":["writes from existing trace evidence only","does not crawl the app","does not discover credentials or secrets","requires human review before commit"]}}
+{"jsonrpc":"2.0","id":27,"result":{"ok":true,"mode":"explore","schemaVersion":1,"runnerVersion":"0.2.1","protocolVersion":"2026-04-28","out":".zmr/discovered/agent-goal.json","traceDir":"traces/agent-session","sourceSnapshot":"traces/agent-session/artifacts/snapshot-1.json","name":"agent goal smoke","appId":"com.example.mobiletest","selectorCount":1,"stepCount":4,"replay":{"enabled":true,"eventCount":2,"stepCount":1,"skippedEventCount":1},"warnings":["draft requires human review before commit"],"validated":true,"validation":{"ok":true,"path":".zmr/discovered/agent-goal.json","name":"agent goal smoke","appId":"com.example.mobiletest","stepCount":4},"nextCommands":["zmr validate --json .zmr/discovered/agent-goal.json","zmr run .zmr/discovered/agent-goal.json --json --trace-dir traces/agent-session"],"goal":"find a stable login smoke","autonomous":false,"reviewRequired":true,"guardrails":["writes from existing trace evidence only","does not crawl the app","does not discover credentials or secrets","requires human review before commit"]}}
 ```
 
 Without `--trace-dir`, it returns `ok: false` with `traceDir: null`.

package/docs/scenario-authoring.md

@@ -4,6 +4,19 @@ ZMR scenarios are JSON so agents can generate and mutate them without a second
 DSL. JSON is strict, schema-validatable, and easy for agents and code generators
 to emit. Keep scenarios explicit, short, and biased toward stable selectors.
 
+Scenarios can be written by hand, or generated review-first from the trace of
+a live session:
+
+```mermaid
+flowchart LR
+    SESSION["Live agent session<br/>or zmr run"] --> TRACE["Trace directory"]
+    TRACE --> DISCOVER["zmr discover / draft / explore<br/>--from-trace"]
+    DISCOVER --> CANDIDATE["Scenario candidate<br/>.zmr/discovered/*.json"]
+    CANDIDATE --> REVIEW["Human / agent review"]
+    REVIEW --> VALIDATE["zmr validate --json"]
+    VALIDATE --> CI["zmr run in CI<br/>report.html · junit.xml"]
+```
+
 ## Selector Strategy
 
 Prefer selectors in this order:
@@ -83,8 +96,10 @@ The example directory includes templates for common app flows:
 - `examples/android-app-onboarding.json`
 - `examples/android-app-referral-deep-link.json`
 - `examples/android-app-error-state.json`
+- `examples/android-workflow.json`
 - `examples/ios-dev-client-open-link.json`
 - `examples/ios-dev-client-route-snapshot.json`
+- `examples/ios-shim-workflow.json`
 
 Run `zmr validate --json <scenario.json>` before touching a device. Invalid
 scenarios report `fieldPath`, `line`, and `column` when ZMR can identify the

package/docs/trace-privacy.md

@@ -3,6 +3,15 @@
 ZMR traces are debugging artifacts. They can contain sensitive app state even
 when scenario files are generic.
 
+```mermaid
+flowchart LR
+    RUN["zmr run / live session"] --> DIR["Trace directory<br/>events.jsonl · screenshots ·<br/>UI trees · logs · timings"]
+    DIR --> REPORT["zmr report<br/>report.html · junit.xml"]
+    DIR --> EXPLAIN["zmr explain<br/>failure diagnosis"]
+    DIR --> EXPORT["zmr export --redact<br/>.zmrtrace bundle"]
+    EXPORT --> VIEWER["Static trace viewer<br/>or shared evidence"]
+```
+
 Raw trace directories may include:
 
 - screenshots

package/docs/troubleshooting.md

@@ -188,6 +188,12 @@ app targets. Pass `--project` explicitly for still-ambiguous multi-project
 workspaces. Run with `--ios-shim ./.zmr/ios-shim` or set
 `tools.iosShimPath` in `.zmr/config.json`.
 
+A clean prebuild can push the shim's first `build-for-testing` through a full
+native dependency compile. ZMR waits up to 90 minutes by default; on slower CI
+hardware, raise the ceiling with the `ZMR_IOS_SHIM_TIMEOUT_MS` environment
+variable (milliseconds), for example `ZMR_IOS_SHIM_TIMEOUT_MS=10800000` for
+three hours.
+
 If a real iOS run fails with CoreSimulator or Xcode cache errors such as
 `Operation not permitted`, `CoreSimulatorService connection became invalid`, or
 an unexpected workspace/build database error, rerun from a normal terminal or CI