zeno-mobile-runner 0.1.3 → 0.2.0

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.3`.
+Current runner version: `0.2.0`.
 
 Current protocol version: `2026-04-28`.
 
@@ -24,6 +24,10 @@ Public schemas:
 - `schemas/capabilities-output.schema.json`
 - `schemas/explain-output.schema.json`
 - `schemas/run-output.schema.json`
+- `schemas/inspect-output.schema.json`
+- `schemas/discover-output.schema.json`
+- `schemas/explore-output.schema.json`
+- `schemas/draft-output.schema.json`
 - `schemas/release-manifest.schema.json`
 - `schemas/release-readiness-output.schema.json`
 - `schemas/schemas-output.schema.json`
@@ -36,12 +40,74 @@ methods.
 form for setup scripts, generated clients, and editor integrations. The
 response is covered by `schemas/schemas-output.schema.json`.
 
+`zmr inspect --json` returns a read-only app handoff for humans and agents. It
+reports the app root, config and `.zmr/AGENTS.md` presence, configured Android
+and iOS smoke scenarios, safe next commands, claim limits, and current runner
+and protocol versions. The response is covered by
+`schemas/inspect-output.schema.json`:
+
+```json
+{"ok":true,"status":"ready","schemaVersion":1,"runnerVersion":"0.2.0","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`
+is the public trace-to-test handoff for agents. It reads the trace manifest and
+latest snapshot artifact, writes a reviewable scenario, and optionally validates
+that generated scenario before returning. With `--include-actions`, it replays
+only successful supported trace actions that contain stable replay data. It is
+offline and review-first: it does not start a device session, crawl the app,
+invent credentials, or commit files. The response is covered by
+`schemas/discover-output.schema.json`:
+
+```json
+{"ok":true,"mode":"discover","schemaVersion":1,"runnerVersion":"0.2.0","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>
+--include-actions --validate --json` is the review-first exploration handoff
+for CLI agents. It uses the same trace-backed scenario writer as `discover`,
+but carries the agent goal and explicit guardrails in the response. It does not
+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.2.0","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
+level scenario-writing primitive used by `discover`. It reads the
+trace manifest and latest semantic snapshot artifact, then writes a reviewable
+surface-smoke scenario. The generated scenario starts with `launch` and
+`snapshot`, then adds `assertVisible` steps for a small set of visible stable
+selectors. It does not start a device session, crawl the app, tap controls, type
+into fields, or commit files. The response is covered by
+`schemas/draft-output.schema.json`:
+
+```json
+{"ok":true,"mode":"draft","schemaVersion":1,"runnerVersion":"0.2.0","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
+successful supported replay steps before the final snapshot assertions. Replay
+drafts currently include app launch, deep links, selector taps, selector text
+entry, selector erase, selector/timeout-preserving visible/not-visible waits,
+matched wait-any events as `waitVisible`, back, keyboard hiding,
+coordinate-complete swipes, direction/timeout-preserving selector scrolls, and
+selector/timeout-preserving `assertVisible` and `assertNotVisible`,
+`assertNoneVisible` selector arrays plus timed `assertHealthy` checks. Events
+without enough replay data, failed events, diagnostics, underspecified swipes,
+and control events are skipped with warnings rather than guessed. Text entry
+events redacted from the trace are skipped.
+The `replay` object in draft and discover JSON reports whether action replay
+was enabled, how many trace action events were considered, how many replay
+steps were generated, and how many events were skipped.
+
 `zmr-release-readiness --json` checks one or more repeated app/device evidence
 files and emits a machine-readable readiness summary. The output is covered by
 `schemas/release-readiness-output.schema.json`:
 
 ```json
-{"ok":false,"target":"production","status":"blocked","evidence":"traces/zmr-pilots/evidence.jsonl","evidenceFiles":["traces/zmr-pilots/evidence.jsonl"],"passed":["Android emulator pilot"],"satisfied":["Android hardware pilot"],"failed":[],"planned":[],"missing":["iOS simulator hardware pilot","iOS physical hardware pilot"],"insufficient":[],"blocked":["iOS simulator hardware pilot","iOS physical hardware pilot"],"requirements":[{"name":"Android hardware pilot","status":"satisfied","evidenceName":"Android emulator pilot"},{"name":"iOS simulator hardware pilot","status":"missing","reason":"no matching passed evidence row"},{"name":"iOS physical hardware pilot","status":"missing","reason":"no matching passed evidence row"}],"nextSteps":[],"recommendedWording":"Do not call this app/device matrix ready yet. Missing evidence: iOS simulator hardware pilot, iOS physical hardware pilot.","claimLimitations":["missing evidence"]}
+{"ok":false,"target":"production","status":"blocked","evidence":"traces/zmr-pilots/evidence.jsonl","evidenceFiles":["traces/zmr-pilots/evidence.jsonl"],"passed":["local release gate","public Android emulator demo","public iOS simulator demo"],"satisfied":["local release gate","public Android demo","public iOS simulator demo","agent workflow smoke"],"failed":[],"planned":[],"missing":["physical iOS readiness","Android hardware pilot","iOS simulator hardware pilot","iOS physical hardware pilot"],"insufficient":[],"blocked":["physical iOS readiness","Android hardware pilot","iOS simulator hardware pilot","iOS physical hardware pilot"],"requirements":[{"name":"local release gate","status":"satisfied","evidenceName":"local release gate"},{"name":"public Android demo","status":"satisfied","evidenceName":"public Android emulator demo"},{"name":"public iOS simulator demo","status":"satisfied","evidenceName":"public iOS simulator demo"},{"name":"agent workflow smoke","status":"satisfied","evidenceName":"local release gate"},{"name":"physical iOS readiness","status":"missing","reason":"no matching passed evidence row"},{"name":"Android hardware pilot","status":"missing","reason":"no matching passed evidence row"},{"name":"iOS simulator hardware pilot","status":"missing","reason":"no matching passed evidence row"},{"name":"iOS physical hardware pilot","status":"missing","reason":"no matching passed evidence row"}],"nextSteps":[{"requirement":"Android hardware pilot + iOS simulator hardware pilot","command":"zmr-pilot-gate --android --ios --android-app-root /path/to/mobile-app --android-app-id <android-app-id> --android-device <android-serial> --ios-app-root /path/to/mobile-app --ios-app-path /path/to/mobile-app/build/Debug-iphonesimulator/Sample.app --ios-app-id <ios-app-id> --ios-device booted --ios-shim /path/to/mobile-app/.zmr/ios-shim --runs 20 --min-pass-rate 100 --max-failures 0 --evidence-out /path/to/mobile-app/traces/zmr-pilots/evidence.jsonl","commands":["zmr-pilot-gate --android --ios --android-app-root /path/to/mobile-app --android-app-id <android-app-id> --android-device <android-serial> --ios-app-root /path/to/mobile-app --ios-app-path /path/to/mobile-app/build/Debug-iphonesimulator/Sample.app --ios-app-id <ios-app-id> --ios-device booted --ios-shim /path/to/mobile-app/.zmr/ios-shim --runs 20 --min-pass-rate 100 --max-failures 0 --evidence-out /path/to/mobile-app/traces/zmr-pilots/evidence.jsonl"],"covers":["Android hardware pilot","iOS simulator hardware pilot"]},{"requirement":"physical iOS readiness + iOS physical hardware pilot","command":"zmr-pilot-gate --ios --ios-device-type physical --ios-device <physical-device-id> --ios-app-root /path/to/mobile-app --ios-app-path /path/to/mobile-app/build/Release-iphoneos/Sample.ipa --ios-app-id <ios-app-id> --ios-shim /path/to/mobile-app/.zmr/ios-shim --runs 20 --min-pass-rate 100 --max-failures 0 --evidence-out /path/to/mobile-app/traces/zmr-pilots/evidence.jsonl","commands":["zmr-pilot-gate --ios --ios-device-type physical --ios-device <physical-device-id> --ios-app-root /path/to/mobile-app --ios-app-path /path/to/mobile-app/build/Release-iphoneos/Sample.ipa --ios-app-id <ios-app-id> --ios-shim /path/to/mobile-app/.zmr/ios-shim --runs 20 --min-pass-rate 100 --max-failures 0 --evidence-out /path/to/mobile-app/traces/zmr-pilots/evidence.jsonl"],"covers":["physical iOS readiness","iOS physical hardware pilot"]}],"recommendedWording":"Do not publish the production claim yet. Missing evidence: physical iOS readiness, Android hardware pilot, iOS simulator hardware pilot, iOS physical hardware pilot.","claimLimitations":["missing evidence"]}
 ```
 
 Zero-dependency TypeScript, standard-library Python, standard-library Go, and
@@ -54,6 +120,12 @@ Rust reference clients live under `clients/typescript/`, `clients/python/`,
 
 `trace.json` is the stable bundle entrypoint for agents and viewers. It includes `schemaVersion`, `runnerVersion`, `protocolVersion`, `scenarioName`, `appId`, `status`, start/end/duration timestamps, failure metadata, `eventsPath`, `artifactsDir`, event/snapshot counts, partial failure count, and `reportPath` when `zmr report` has generated a single-trace HTML report.
 
+`zmr report <trace-or-benchmark-dir> --out <report.html> --junit <report.xml>`
+writes the local HTML report and a CI-friendly JUnit XML file. For trace
+directories, the XML contains one testcase for the scenario. For benchmark
+directories with `results.jsonl`, the XML contains one testcase per benchmark
+row.
+
 `zmr export <trace-dir> --out <bundle.zmrtrace>` writes a deterministic tar archive with relative paths only. V1 bundles include `trace.json`, `events.jsonl`, optional `report.html`, and every regular file under `artifacts/`.
 
 `zmr export <trace-dir> --out <bundle.zmrtrace> --redact` writes a shareable bundle without mutating the local trace directory. Redacted bundles replace PNG screenshots with placeholder frames, omit screen recording artifacts, scrub text artifacts for emails/tokens/sensitive JSON values, and add `redaction` metadata to the bundled `trace.json`. Add `--omit-screenshots` when the bundle should contain no screenshot artifacts at all.
@@ -81,14 +153,23 @@ Clients should read the last `scenario.end` event as the authoritative trace out
 scenario completes. For traced runs it mirrors the authoritative `trace.json`
 terminal fields, including trace paths, event/snapshot counts, failed step, and
 stable error name. Traced summaries also include `nextCommands` so agents can
-immediately render an HTML report, explain the failure, or export a redacted
-trace bundle. Failed scenarios still exit non-zero after writing the JSON
-summary. The response is covered by `schemas/run-output.schema.json`:
+immediately render HTML and JUnit reports, explain the failure, generate a
+reviewable scenario from the trace, or export a redacted trace bundle. Failed
+scenarios still exit non-zero after writing the JSON summary. The response is
+covered by `schemas/run-output.schema.json`:
 
 ```json
-{"ok":false,"status":"failed","scenario":"login smoke","appId":"com.example.mobiletest","traceDir":"traces/login-smoke","eventsPath":"events.jsonl","artifactsDir":"artifacts","durationMs":100,"eventCount":4,"snapshotCount":1,"failedStepIndex":2,"error":"WaitTimeout","nextCommands":["zmr report traces/login-smoke --out traces/login-smoke/report.html","zmr explain traces/login-smoke --json","zmr export traces/login-smoke --out traces/login-smoke.zmrtrace --redact"]}
+{"ok":false,"status":"failed","scenario":"login smoke","appId":"com.example.mobiletest","traceDir":"traces/login-smoke","eventsPath":"events.jsonl","artifactsDir":"artifacts","durationMs":100,"eventCount":4,"snapshotCount":1,"failedStepIndex":2,"error":"WaitTimeout","nextCommands":["zmr report traces/login-smoke --out traces/login-smoke/report.html --junit traces/login-smoke/junit.xml","zmr explain traces/login-smoke --json","zmr discover --from-trace traces/login-smoke --out .zmr/discovered/replay-smoke.json --include-actions --validate --force --json","zmr export traces/login-smoke --out traces/login-smoke.zmrtrace --redact"]}
 ```
 
+`zmr run <scenario.json> --trace-dir <trace-dir> --discover-out
+<scenario.json> --json` runs the same trace-backed discover engine before
+printing the run summary. The response includes `discovery` with the
+`zmr discover --json` payload, including validation results and next commands.
+If discovery cannot run, the run summary remains authoritative and includes
+`discoveryError` with the stable error name. `--discover-out` requires an
+effective `--trace-dir`, either passed directly or resolved from `.zmr/config.json`.
+
 When a run captures useful artifacts but a non-terminal enrichment fails, such
 as an iOS screenshot succeeding while XCTest hierarchy extraction fails, the
 terminal status is `partial` and `partialFailureCount` is greater than zero.
@@ -114,12 +195,12 @@ The text summary includes the terminal status, failed step, stable error, last d
 
 `zmr explain <trace-dir> --json` or `zmr explain --json <trace-dir>` returns
 the same failure triage fields in a stable machine-readable shape for agents
-and CI. It also includes `traceDir` and `nextCommands` for rendering an HTML
-report or exporting a redacted bundle. The response is covered by
+and CI. It also includes `traceDir` and `nextCommands` for rendering HTML and
+JUnit reports or exporting a redacted bundle. The response is covered by
 `schemas/explain-output.schema.json`:
 
 ```json
-{"ok":true,"traceDir":"traces/login-smoke","scenario":"login smoke","status":"failed","appId":"com.example.mobiletest","durationMs":100,"eventCount":4,"snapshotCount":1,"failedStepIndex":2,"error":"WaitTimeout","diagnostic":{"kind":"wait.visible","status":"timeout","snapshotId":"snapshot-7","activePackage":"com.example.mobiletest","activeActivity":".MainActivity","visibleTexts":["Sign in","Try again"],"nearestTextMatches":["Dashboards (score 1)"]},"lastEvent":"scenario.end","nextCommands":["zmr report traces/login-smoke --out traces/login-smoke/report.html","zmr export traces/login-smoke --out traces/login-smoke.zmrtrace --redact"]}
+{"ok":true,"traceDir":"traces/login-smoke","scenario":"login smoke","status":"failed","appId":"com.example.mobiletest","durationMs":100,"eventCount":4,"snapshotCount":1,"failedStepIndex":2,"error":"WaitTimeout","diagnostic":{"kind":"wait.visible","status":"timeout","snapshotId":"snapshot-7","activePackage":"com.example.mobiletest","activeActivity":".MainActivity","visibleTexts":["Sign in","Try again"],"nearestTextMatches":["Dashboards (score 1)"]},"lastEvent":"scenario.end","nextCommands":["zmr report traces/login-smoke --out traces/login-smoke/report.html --junit traces/login-smoke/junit.xml","zmr export traces/login-smoke --out traces/login-smoke.zmrtrace --redact"]}
 ```
 
 For partial visual captures, `diagnostic.kind` is
@@ -133,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.3","protocolVersion":"2026-04-28","minimumCompatibleProtocolVersion":"2026-04-28","stability":"dev-preview","breakingChangePolicy":"version-and-changelog"}
+{"name":"zmr","version":"0.2.0","protocolVersion":"2026-04-28","minimumCompatibleProtocolVersion":"2026-04-28","stability":"dev-preview","breakingChangePolicy":"version-and-changelog"}
 ```
 
 ## Capabilities Output Contract
@@ -145,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.3","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","observe.snapshot","observe.semanticSnapshot"]}
+{"name":"zmr","version":"0.2.0","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
@@ -307,7 +388,11 @@ zmr mcp --config .zmr/config.json --trace-dir traces/mcp-agent-session
 - `assert.visible`
 - `assert.notVisible`
 - `assert.healthy`
+- `scenario.validate`
 - `trace.events`
+- `trace.explore`
+- `trace.discover`
+- `trace.explain`
 - `trace.export`
 
 `runner.capabilities` returns both legacy `protocolVersion` and a structured `protocol` object. Clients should treat `protocol.version` as the compatibility key for method and payload shape, and should reject servers older than `protocol.minimumCompatibleVersion` unless they intentionally support that older shape. Before `v1.0.0`, `protocol.stability` is `dev-preview` and breaking changes require both a protocol version bump and changelog entry.
@@ -347,7 +432,7 @@ Request:
 Response:
 
 ```json
-{"jsonrpc":"2.0","id":1,"result":{"name":"zmr","version":"0.1.3","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","trace.events","trace.export"]}}
+{"jsonrpc":"2.0","id":1,"result":{"name":"zmr","version":"0.2.0","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`
@@ -373,6 +458,90 @@ Response:
 server-side event counter; `nextSeq` is the last returned event and can be
 passed back as `afterSeq`.
 
+### `trace.explain`
+
+Summarizes the active live trace with the same JSON shape as
+`zmr explain <trace-dir> --json`. Use it when an agent needs the current trace
+status, failure diagnostic, last event, and next commands without leaving the
+JSON-RPC session.
+
+Request:
+
+```json
+{"jsonrpc":"2.0","id":26,"method":"trace.explain","params":{}}
+```
+
+Response:
+
+```json
+{"jsonrpc":"2.0","id":26,"result":{"ok":true,"traceDir":"traces/agent-session","scenario":"json-rpc session","status":"failed","appId":"com.example.mobiletest","durationMs":100,"eventCount":4,"snapshotCount":1,"failedStepIndex":2,"error":"WaitTimeout","diagnostic":{"kind":"wait.visible","status":"timeout","snapshotId":"snapshot-7","visibleTexts":["Sign in","Try again"]},"lastEvent":"scenario.end","nextCommands":["zmr report traces/agent-session --out traces/agent-session/report.html --junit traces/agent-session/junit.xml","zmr export traces/agent-session --out traces/agent-session.zmrtrace --redact"]}}
+```
+
+Without `--trace-dir`, it returns a result with `traceDir: null` and a message
+explaining how to enable live trace explanation.
+
+### `scenario.validate`
+
+Validates a ZMR scenario file and returns the same structured payload as
+`zmr validate --json`, including field paths and source locations for invalid
+files.
+
+Request:
+
+```json
+{"jsonrpc":"2.0","id":23,"method":"scenario.validate","params":{"path":".zmr/discovered/agent-smoke.json"}}
+```
+
+Response:
+
+```json
+{"jsonrpc":"2.0","id":23,"result":{"ok":true,"path":".zmr/discovered/agent-smoke.json","name":"agent smoke","appId":"com.example.mobiletest","stepCount":4,"nextCommands":["zmr run .zmr/discovered/agent-smoke.json --json --trace-dir traces/zmr-run"]}}
+```
+
+### `trace.discover`
+
+Generates a reviewable scenario candidate from the active live trace. It uses
+the same engine as `zmr discover --from-trace`, so it can include supported
+successful replay actions, add final snapshot assertions, and optionally
+validate the generated scenario before returning.
+
+Request:
+
+```json
+{"jsonrpc":"2.0","id":25,"method":"trace.discover","params":{"out":".zmr/discovered/agent-smoke.json","includeActions":true,"validate":true,"force":true,"name":"agent smoke"}}
+```
+
+Response:
+
+```json
+{"jsonrpc":"2.0","id":25,"result":{"ok":true,"mode":"discover","schemaVersion":1,"runnerVersion":"0.2.0","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
+scenarios remain review-first: ZMR does not crawl, invent credentials, or
+commit tests.
+
+### `trace.explore`
+
+Generates a review-required scenario candidate from the active live trace for a
+stated goal. It uses the same trace-backed engine as `zmr explore --from-trace`:
+the runner writes from existing trace evidence only, does not crawl the app,
+does not discover credentials or secrets, and returns `reviewRequired: true`.
+
+Request:
+
+```json
+{"jsonrpc":"2.0","id":27,"method":"trace.explore","params":{"out":".zmr/discovered/agent-goal.json","goal":"find a stable login smoke","includeActions":true,"validate":true,"force":true,"name":"agent goal smoke"}}
+```
+
+Response:
+
+```json
+{"jsonrpc":"2.0","id":27,"result":{"ok":true,"mode":"explore","schemaVersion":1,"runnerVersion":"0.2.0","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`.
+
 ### `device.list`
 
 Response:
@@ -432,10 +601,14 @@ exposes tool calls for agent runtimes that prefer MCP over raw JSON-RPC.
 zmr mcp --config .zmr/config.json --trace-dir traces/mcp-agent
 ```
 
-Core tools are `snapshot`, `semantic_snapshot`, `tap`, `type`, `press_back`,
-`open_link`, `wait_visible`, `trace_events`, and `trace_export`. The MCP
-protocol handshake is intentionally standard, while the tool names and payloads
-are versioned with the ZMR runner and public schemas.
+Core tools are `snapshot`, `semantic_snapshot`, `install_app`, `launch_app`,
+`stop_app`, `clear_state`, `tap`, `type`, `erase_text`, `hide_keyboard`,
+`swipe`, `press_back`, `open_link`, `wait_visible`, `wait_not_visible`,
+`wait_any`, `scroll_until_visible`, `assert_visible`, `assert_not_visible`,
+`assert_healthy`, `scenario_validate`, `trace_events`, `trace_explain`,
+`trace_explore`, `trace_discover`, and `trace_export`. The MCP protocol handshake is
+intentionally standard, while the tool names and payloads are versioned with
+the ZMR runner and public schemas.
 
 ### `ui.tap`
 
@@ -466,6 +639,32 @@ Request:
 {"jsonrpc":"2.0","id":7,"method":"assert.notVisible","params":{"selector":{"textContains":"Loading"},"timeoutMs":5000}}
 ```
 
+### MCP `trace_discover`
+
+`trace_discover` mirrors JSON-RPC `trace.discover` for MCP agents. Required
+argument: `out`. Optional arguments: `includeActions`, `validate`, `force`,
+`name`, and `appId`. The tool response text is the same discover JSON payload.
+
+### MCP `trace_explore`
+
+`trace_explore` mirrors JSON-RPC `trace.explore` for MCP agents. Required
+arguments: `out` and `goal`. Optional arguments: `includeActions`, `validate`,
+`force`, `name`, and `appId`. The tool response text is the same guarded
+explore JSON payload, including `autonomous:false`, `reviewRequired:true`, and
+`guardrails`.
+
+### MCP `trace_explain`
+
+`trace_explain` mirrors JSON-RPC `trace.explain` for MCP agents. It takes no
+arguments. The tool response text is the same explanation JSON payload returned
+by `zmr explain --json`.
+
+### MCP `scenario_validate`
+
+`scenario_validate` mirrors JSON-RPC `scenario.validate` for MCP agents.
+Required argument: `path`. The tool response text is the same validation JSON
+payload returned by `zmr validate --json`.
+
 ### `trace.export`
 
 When `zmr serve` is started with `--trace-dir`, live JSON-RPC sessions use the

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:
@@ -71,6 +84,9 @@ The importer supports the common subset needed for smoke scenarios:
 generated JSON before committing it; native `.zmr/*.json` scenarios remain the
 runtime contract for agents and CI.
 
+`assertVisible` and `assertNotVisible` accept the same `timeoutMs` field as
+waits when a scenario needs assertion-specific timing.
+
 ## Example Templates
 
 The example directory includes templates for common app flows:
@@ -80,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
@@ -228,7 +234,7 @@ When a run fails, do not rerun blindly. Inspect the recorded failure:
 
 ```bash
 zmr explain traces/zmr-android
-zmr report traces/zmr-android --out traces/zmr-android/report.html
+zmr report traces/zmr-android --out traces/zmr-android/report.html --junit traces/zmr-android/junit.xml
 ```
 
 Timeout diagnostics include the active package/activity, visible text, hidden or

package/examples/android-workflow.json

@@ -0,0 +1,79 @@
+{
+  "name": "ZMR Android workflow demo",
+  "appId": "com.example.mobiletest",
+  "steps": [
+    { "action": "stop" },
+    { "action": "launch" },
+    {
+      "action": "waitVisible",
+      "selector": { "text": "ZMR Android Demo" },
+      "timeoutMs": 30000
+    },
+    {
+      "action": "tap",
+      "selector": { "resourceId": "com.example.mobiletest:id/continue_button" }
+    },
+    {
+      "action": "waitVisible",
+      "selector": { "text": "Profile" },
+      "timeoutMs": 10000
+    },
+    {
+      "action": "typeText",
+      "selector": { "resourceId": "com.example.mobiletest:id/profile_name_input" },
+      "text": "Riley"
+    },
+    {
+      "action": "typeText",
+      "selector": { "resourceId": "com.example.mobiletest:id/profile_email_input" },
+      "text": "riley@example.test"
+    },
+    { "action": "hideKeyboard" },
+    {
+      "action": "tap",
+      "selector": { "resourceId": "com.example.mobiletest:id/save_profile_button" }
+    },
+    {
+      "action": "waitVisible",
+      "selector": { "text": "Catalog" },
+      "timeoutMs": 10000
+    },
+    {
+      "action": "scrollUntilVisible",
+      "selector": { "resourceId": "com.example.mobiletest:id/catalog_item_north_ridge_pack" },
+      "direction": "down",
+      "timeoutMs": 10000
+    },
+    {
+      "action": "tap",
+      "selector": { "resourceId": "com.example.mobiletest:id/catalog_item_north_ridge_pack" }
+    },
+    {
+      "action": "waitVisible",
+      "selector": { "text": "North Ridge Pack" },
+      "timeoutMs": 10000
+    },
+    {
+      "action": "tap",
+      "selector": { "resourceId": "com.example.mobiletest:id/detail_save_button" }
+    },
+    {
+      "action": "waitVisible",
+      "selector": { "text": "Saved North Ridge Pack" },
+      "timeoutMs": 10000
+    },
+    {
+      "action": "tap",
+      "selector": { "resourceId": "com.example.mobiletest:id/review_button" }
+    },
+    {
+      "action": "assertVisible",
+      "selector": {
+        "resourceId": "com.example.mobiletest:id/workflow_status",
+        "text": "Workflow complete"
+      },
+      "timeoutMs": 10000
+    },
+    { "action": "snapshot" }
+  ]
+}

package/examples/ios-shim-workflow.json

@@ -0,0 +1,79 @@
+{
+  "name": "ZMR iOS shim workflow demo",
+  "appId": "com.example.mobiletest",
+  "steps": [
+    { "action": "stop" },
+    { "action": "launch" },
+    {
+      "action": "waitVisible",
+      "selector": { "text": "ZMR iOS Demo" },
+      "timeoutMs": 30000
+    },
+    {
+      "action": "tap",
+      "selector": { "resourceId": "continue_button" }
+    },
+    {
+      "action": "waitVisible",
+      "selector": { "text": "Profile" },
+      "timeoutMs": 10000
+    },
+    {
+      "action": "typeText",
+      "selector": { "resourceId": "profile_name_input" },
+      "text": "Riley"
+    },
+    {
+      "action": "typeText",
+      "selector": { "resourceId": "profile_email_input" },
+      "text": "riley@example.test"
+    },
+    { "action": "hideKeyboard" },
+    {
+      "action": "tap",
+      "selector": { "resourceId": "save_profile_button" }
+    },
+    {
+      "action": "waitVisible",
+      "selector": { "text": "Catalog" },
+      "timeoutMs": 10000
+    },
+    {
+      "action": "scrollUntilVisible",
+      "selector": { "resourceId": "catalog_item_north_ridge_pack" },
+      "direction": "down",
+      "timeoutMs": 10000
+    },
+    {
+      "action": "tap",
+      "selector": { "resourceId": "catalog_item_north_ridge_pack" }
+    },
+    {
+      "action": "waitVisible",
+      "selector": { "text": "North Ridge Pack" },
+      "timeoutMs": 10000
+    },
+    {
+      "action": "tap",
+      "selector": { "resourceId": "detail_save_button" }
+    },
+    {
+      "action": "waitVisible",
+      "selector": { "text": "Saved North Ridge Pack" },
+      "timeoutMs": 10000
+    },
+    {
+      "action": "tap",
+      "selector": { "resourceId": "review_button" }
+    },
+    {
+      "action": "assertVisible",
+      "selector": {
+        "resourceId": "workflow_status",
+        "text": "Workflow complete"
+      },
+      "timeoutMs": 10000
+    },
+    { "action": "snapshot" }
+  ]
+}