zeno-mobile-runner 0.2.16 → 0.2.17

package/docs/production-readiness.md

@@ -1,13 +1,14 @@
 # Production Readiness
 
-ZMR is a public developer preview. The npm package is live, release artifacts
-are signed by GitHub release attestations, and local app teams can collect
-repeatable Android, iOS simulator, and physical iOS evidence. ZMR should not be
-called production-stable until the gates below are met and kept passing.
+ZMR is currently a public developer preview. The npm package is live, release
+artifacts are signed by GitHub release attestations, and app teams can collect
+repeatable Android, iPhone simulator, iPad simulator, and physical iOS/iPadOS
+evidence today. The product should not be described as production-stable until
+the gates below are passing and remain part of the release routine.
 
 ## Current Release Standard
 
-Every public release should satisfy:
+Every public release should satisfy these checks before publishing artifacts:
 
 - `bash tests/docs-readiness-test.sh`
 - `bash tests/public-safety-test.sh`
@@ -18,14 +19,20 @@ Every public release should satisfy:
 - `./scripts/verify-release-artifacts.sh --dist dist`
 - at least one trace or benchmark report rendered with `zmr report --junit`,
   or a pilot wrapper run that produced both `report.html` and `junit.xml`
-- a fresh npm install smoke:
+- a fresh curl installer smoke:
+
+  ```bash
+  ./install.sh --version 0.2.17 --dry-run
+  ```
+
+- a fresh npm convenience smoke:
 
   ```bash
   npm install --save-dev zeno-mobile-runner
   npx zmr version --json
   ```
 
-Tagged releases are expected to build release archives, generate
+Tagged releases should build release archives, generate
 `RELEASE_MANIFEST.json`, publish GitHub artifact attestations, upload release
 assets, and publish the npm tarball through trusted publishing after the npm
 package is configured with the `release.yml` trusted publisher.
@@ -36,12 +43,17 @@ workflow artifact for 30 days in addition to GitHub release assets.
 
 ## Product Gates Before 1.0
 
+These gates separate "usable preview" from "production-stable product claim."
+
 | Area | Required evidence | Current status |
 | --- | --- | --- |
 | Android emulator | 20-run pilot gate with zero failures and trace/report artifacts | Supported by `zmr-pilot-gate` and demo app |
 | Android physical device | 20-run pilot gate on a real connected device | Supported by ADB flow; app teams must collect evidence |
-| iOS simulator | 20-run pilot gate with XCTest shim selectors, screenshots, and reports | Supported by iOS demo and app-local shim |
-| iOS physical device | 20-run pilot gate on a real trusted device | Supported for lifecycle and shim screenshots; needs repeated public evidence |
+| iPhone simulator | 20-run pilot gate with XCTest shim selectors, screenshots, and reports | Supported by iOS demo and app-local shim |
+| iPad simulator | 20-run pilot gate on an iPad simulator with tablet layout coverage | Same iOS simulator path; needs repeated public evidence before production-stable claims |
+| iPhone physical device | 20-run pilot gate on a real trusted device | Supported for lifecycle and shim screenshots; needs repeated public evidence |
+| iPad physical device | 20-run pilot gate on a real trusted iPad | Same iOS/iPadOS physical path; app teams must collect separate tablet evidence |
+| tvOS / watchOS | Platform-specific lifecycle, shim, trace, and pilot evidence | Not supported in this preview |
 | React Native | Public setup guidance plus selector-grade app evidence using stable labels or ids | Guidance exists; repeated public demo evidence is still needed |
 | Expo | Public smoke, dev-client scaffold, and iOS/Android run evidence | Basic iOS smoke is documented; repeated matrix evidence is still needed |
 | Flutter | Platform-level Android/iOS smoke using semantics, deep links, and screenshots | Supported at platform level; widget-tree claims are intentionally out of scope |
@@ -52,7 +64,8 @@ workflow artifact for 30 days in addition to GitHub release assets.
 
 ## Reliability Evidence
 
-Use repeated app-local pilots before making app or device claims:
+Use repeated app-local pilots before making app or device claims. A single green
+demo proves wiring; a 20-run pilot proves reliability for a target class:
 
 ```bash
 zmr-pilot-gate \
@@ -81,13 +94,13 @@ zmr-release-readiness \
   --json
 ```
 
-Keep the generated evidence in the app repository unless it is fully redacted
-and safe to publish.
+Keep generated evidence in the app repository unless it is fully redacted and
+safe to publish.
 
 ## Agentic Standard
 
-ZMR is agentic when an external agent can work from structured state instead of
-screenscraping or guessing:
+ZMR meets the agent-first bar when an external agent can work from structured
+state instead of screenshots, terminal prose, or guessed coordinates:
 
 - `zmr doctor --json` explains setup state and remediation.
 - `zmr schemas --json` exposes machine-readable contracts.
@@ -105,7 +118,7 @@ screenscraping or guessing:
   trace events, trace explanation, trace discovery/exploration, scenario
   validation, and redacted export.
 
-The safe discovery pattern is still external-agent-first: observe with
+The safe discovery pattern remains external-agent-first: observe with
 `semantic_snapshot`, choose one typed action, record successful steps into a
 candidate scenario, validate it, rerun it deterministically, and require human
 review before committing generated tests.
@@ -114,10 +127,12 @@ review before committing generated tests.
 
 - Claim Android and iOS app-level support only for flows that pass local pilot
   evidence on the target device class.
+- Claim iPad support separately from iPhone support. The runner path is shared,
+  but tablet layouts and size classes can change UI trees and selector outcomes.
 - Claim React Native and Expo support through app-level lifecycle, deep links,
   accessibility labels, selectors, screenshots, traces, and reports.
 - Claim Flutter support at the Android/iOS app level when the app exposes stable
   semantics, labels, ids, or deep links.
 - Do not claim Flutter widget-tree inspection, Dart state inspection, managed
-  device-farm coverage, or a built-in autonomous test writer until those
-  features exist and have public evidence.
+  device-farm coverage, tvOS, watchOS, or a built-in autonomous test writer until
+  those features exist and have public evidence.

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

@@ -1,4 +1,4 @@
-{"jsonrpc":"2.0","id":1,"result":{"name":"zmr","version":"0.2.16","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.17","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-versioning.md

@@ -1,12 +1,14 @@
 # Protocol Versioning
 
-ZMR exposes two public automation surfaces:
+Use this page when changing scenario JSON, JSON-RPC, MCP-visible schemas, trace
+schemas, or stable error codes. ZMR exposes two public automation surfaces:
 
 - scenario JSON files consumed by `zmr run`
 - JSON-RPC methods exposed by `zmr serve`
 
-The current protocol version is a date string. Before `v1.0.0`, breaking changes
-are allowed only when the protocol version and changelog are updated together.
+The current protocol version is a date string. Before `v1.0.0`, breaking
+changes are allowed only when the protocol version and changelog are updated
+together.
 `runner.capabilities` exposes this policy in machine-readable form:
 
 ```json

package/docs/protocol.md

@@ -1,8 +1,11 @@
 # ZMR JSON-RPC Protocol
 
-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`.
+ZMR exposes newline-delimited JSON-RPC 2.0 over stdio or localhost TCP. This is
+the contract used by reference clients, agent harnesses, and the MCP server
+internals. Each request is one JSON object followed by `\n`; each response is
+one JSON object followed by `\n`.
 
-Current runner version: `0.2.16`.
+Current runner version: `0.2.17`.
 
 Current protocol version: `2026-04-28`.
 
@@ -47,7 +50,7 @@ and protocol versions. The response is covered by
 `schemas/inspect-output.schema.json`:
 
 ```json
-{"ok":true,"status":"ready","schemaVersion":1,"runnerVersion":"0.2.16","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.17","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 +63,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.2.16","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.17","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 +74,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.2.16","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.17","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 +87,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.2.16","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.17","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 +217,7 @@ installers, setup scripts, and generated clients. The response is covered by
 `schemas/version-output.schema.json`:
 
 ```json
-{"name":"zmr","version":"0.2.16","protocolVersion":"2026-04-28","minimumCompatibleProtocolVersion":"2026-04-28","stability":"dev-preview","breakingChangePolicy":"version-and-changelog"}
+{"name":"zmr","version":"0.2.17","protocolVersion":"2026-04-28","minimumCompatibleProtocolVersion":"2026-04-28","stability":"dev-preview","breakingChangePolicy":"version-and-changelog"}
 ```
 
 ## Capabilities Output Contract
@@ -226,7 +229,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.2.16","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.17","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
@@ -278,7 +281,7 @@ generated app-local file, direct paths for the config/scenario/matrix/agent
 files, first-run commands, and the generated script names:
 
 ```json
-{"ok":true,"mode":"app","dir":".","appId":"com.example.mobiletest","created":["./.zmr/config.json","./.zmr/android-smoke.json","./.zmr/ios-smoke.json","./.zmr/device-matrix.json","./.zmr/AGENTS.md"],"configPath":"./.zmr/config.json","androidScenarioPath":"./.zmr/android-smoke.json","iosScenarioPath":"./.zmr/ios-smoke.json","deviceMatrixPath":"./.zmr/device-matrix.json","agentInstructionsPath":"./.zmr/AGENTS.md","next":"zmr doctor --strict --json --config ./.zmr/config.json","nextCommands":["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"],"smokeCommands":["zmr run ./.zmr/android-smoke.json --device emulator-5554 --trace-dir ./traces/zmr-android","zmr run ./.zmr/ios-smoke.json --platform ios --device booted --trace-dir ./traces/zmr-ios"],"scriptCount":16,"scriptNames":["doctor","schemas","validate","android","androidReport","androidReliability","ios","iosReport","iosReliability","matrix","pilotGate","readiness","serve","mcp","explain","exportTrace"]}
+{"ok":true,"mode":"app","dir":".","appId":"com.example.mobiletest","created":["./.zmr/config.json","./.zmr/android-smoke.json","./.zmr/ios-smoke.json","./.zmr/device-matrix.json","./.zmr/AGENTS.md"],"configPath":"./.zmr/config.json","androidScenarioPath":"./.zmr/android-smoke.json","iosScenarioPath":"./.zmr/ios-smoke.json","deviceMatrixPath":"./.zmr/device-matrix.json","agentInstructionsPath":"./.zmr/AGENTS.md","next":"zmr doctor --strict --json --config ./.zmr/config.json","nextCommands":["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"],"smokeCommands":["zmr run ./.zmr/android-smoke.json --device emulator-5554 --trace-dir ./traces/zmr-android --ensure-device","zmr run ./.zmr/ios-smoke.json --platform ios --device booted --trace-dir ./traces/zmr-ios --ensure-device"],"scriptCount":16,"scriptNames":["doctor","schemas","validate","android","androidReport","androidReliability","ios","iosReport","iosReliability","matrix","pilotGate","readiness","serve","mcp","explain","exportTrace"]}
 ```
 
 Agents should read `agentInstructionsPath` for the app-local operating note and
@@ -299,8 +302,9 @@ Single-scenario mode reports the created scenario and next validation command:
 ## Import Output Contract
 
 `zmr import flow-yaml <flow.yaml> --out .zmr/imported.json --json` converts a
-supported subset of mobile-flow YAML into native ZMR scenario JSON. The
-response is covered by `schemas/import-output.schema.json`:
+supported subset of mobile-flow YAML into native ZMR scenario JSON. Keep the
+generated JSON as the reviewed, deterministic scenario that agents and CI run.
+The response is covered by `schemas/import-output.schema.json`:
 
 ```json
 {"ok":true,"format":"flow-yaml","source":"flows/login.yaml","out":".zmr/login-smoke.json","name":"Imported login smoke","appId":"com.example.mobiletest","stepCount":10,"next":"zmr validate .zmr/login-smoke.json","nextCommands":["zmr validate --json .zmr/login-smoke.json","zmr run .zmr/login-smoke.json --json --trace-dir traces/zmr-run"]}
@@ -360,7 +364,7 @@ zmr serve --transport stdio --platform ios --ios-device-type physical --device <
 zmr mcp --config .zmr/config.json --trace-dir traces/mcp-agent-session
 ```
 
-`runner.capabilities` reports `platforms: ["android","ios"]`, `platformSupport.ios.status: "supported"`, and legacy `iosPreview: false`. Android supports emulators and connected devices. iOS simulators use `simctl` for discovery, install, launch, stop, clear-state-by-uninstall, deep links, screenshots, logs, and snapshots. Physical iOS devices use `devicectl` for discovery, install, launch, deep-link launch, clear-state-by-uninstall, and best-effort stop. Selector-grade `ui.*` methods on iOS require a configured XCTest/XCUIAutomation shim command; without one they return `IosXCTestShimRequired`. With the shim configured, single-field `ui.tap`, selector-scoped `ui.type`, selector-scoped `ui.eraseText`, `wait.*`, and `assert.*` can execute directly through XCTest. Compound selectors continue to use the portable snapshot-matching fallback. iOS snapshot responses are bounded to common XCTest element families so traces stay usable on large apps. Physical iOS screenshot artifacts use the XCTest shim; physical-device log capture is intentionally limited in this release.
+`runner.capabilities` reports `platforms: ["android","ios"]`, `platformSupport.ios.status: "supported"`, and legacy `iosPreview: false`. Android supports emulators and connected devices. iOS and iPadOS simulators use `simctl` for discovery, install, launch, stop, clear-state-by-uninstall, deep links, screenshots, logs, and snapshots. Physical iPhone and iPad devices use `devicectl` for discovery, install, launch, deep-link launch, clear-state-by-uninstall, and best-effort stop. Selector-grade `ui.*` methods on iOS require a configured XCTest/XCUIAutomation shim command; without one they return `IosXCTestShimRequired`. With the shim configured, single-field `ui.tap`, selector-scoped `ui.type`, selector-scoped `ui.eraseText`, `wait.*`, and `assert.*` can execute directly through XCTest. Compound selectors continue to use the portable snapshot-matching fallback. iOS snapshot responses are bounded to common XCTest element families so traces stay usable on large apps. Physical iOS screenshot artifacts use the XCTest shim; physical-device log capture is intentionally limited in this release.
 
 ## Core Methods
 
@@ -433,7 +437,7 @@ Request:
 Response:
 
 ```json
-{"jsonrpc":"2.0","id":1,"result":{"name":"zmr","version":"0.2.16","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.17","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`
@@ -515,7 +519,7 @@ Request:
 Response:
 
 ```json
-{"jsonrpc":"2.0","id":25,"result":{"ok":true,"mode":"discover","schemaVersion":1,"runnerVersion":"0.2.16","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.17","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
@@ -538,7 +542,7 @@ Request:
 Response:
 
 ```json
-{"jsonrpc":"2.0","id":27,"result":{"ok":true,"mode":"explore","schemaVersion":1,"runnerVersion":"0.2.16","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.17","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`.
@@ -719,12 +723,15 @@ Current stable public codes:
 
 ## Selectors
 
-Selectors can combine fields. All provided fields must match the same visible node.
+Selectors must be non-empty and can combine fields. Unknown selector keys are
+rejected by `zmr validate`, JSON-RPC, and MCP tool handling. All provided fields
+must match the same visible node.
 
 ```json
 {
   "id": "email-login-submit-button",
   "resourceId": "email-login-submit-button",
+  "stableId": "rid:email-login-submit-button:4",
   "text": "Sign in",
   "textContains": "Sign",
   "contentDesc": "Account",
@@ -733,6 +740,11 @@ Selectors can combine fields. All provided fields must match the same visible no
 }
 ```
 
+Prefer app-owned `id`/`resourceId` values, accessibility identifiers, content
+descriptions, labels, and stable text for committed scenarios. Use `stableId`
+only as a fallback copied from the current `semantic_snapshot` when an agent
+needs to act immediately and no stronger selector exists.
+
 ## Example
 
 ```json
@@ -744,7 +756,8 @@ Selectors can combine fields. All provided fields must match the same visible no
 
 ## Scenario-Only Flow Primitives
 
-Scenario JSON supports additional orchestration primitives for agent-grade mobile flows:
+Scenario JSON supports additional orchestration primitives for agent-grade
+mobile flows:
 
 - `waitAny`
 - `waitNotVisible`
@@ -757,4 +770,6 @@ Scenario JSON supports additional orchestration primitives for agent-grade mobil
 - `hideKeyboard`
 - `"optional": true` on any step
 
-These are intentionally explicit JSON structures instead of YAML conditionals, so agents can generate, validate, and mutate flows without parsing a second language.
+These are intentionally explicit JSON structures instead of YAML conditionals,
+so agents can generate, validate, and mutate flows without parsing a second
+language.

package/docs/scenario-authoring.md

@@ -1,11 +1,12 @@
 # Scenario Authoring
 
-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.
+ZMR scenarios are JSON so agents, code generators, and CI scripts can create
+and mutate them without learning another DSL. The parser is strict: validate
+before a device run, keep flows explicit, and bias selectors toward app-owned
+identifiers.
 
-Scenarios can be written by hand, or generated review-first from the trace of
-a live session:
+Scenarios can be written by hand or generated review-first from the trace of a
+live session:
 
 ```mermaid
 flowchart LR
@@ -19,17 +20,22 @@ flowchart LR
 
 ## Selector Strategy
 
-Prefer selectors in this order:
+Prefer selectors in this order for committed scenarios:
 
 1. `id` or `resourceId` for app-owned controls.
 2. `contentDesc` for intentional accessibility labels.
 3. Exact `text` for stable product copy.
 4. `textContains` only for headings, errors, or partial copy that is expected to
    vary.
+5. `stableId` only as a fallback copied from the current `semantic_snapshot`
+   when no app-owned selector exists.
 
 Avoid selecting by text that includes user data, timestamps, counts, prices, or
 network-provided content. Prefer app-owned resource ids or accessibility identifiers
 over widening a selector until it matches unrelated nodes.
+Treat `stableId` as a live-session fallback: it can unblock immediate agent
+actions, but committed CI scenarios should prefer app-owned selectors because UI
+tree shape and fallback IDs can change as layouts evolve.
 
 ## Waits And Assertions
 
@@ -81,7 +87,7 @@ The importer supports the common subset needed for smoke scenarios:
 `hideKeyboard`, `assertVisible`, `assertNotVisible`, `assertHealthy`,
 `openLink`, `back`,
 `scrollUntilVisible`, `takeScreenshot`, and simple wait commands. Review the
-generated JSON before committing it; native `.zmr/*.json` scenarios remain the
+generated JSON before committing it. Native `.zmr/*.json` scenarios remain the
 runtime contract for agents and CI.
 
 Use `setLocation` before location-dependent assertions to set simulator or
@@ -115,4 +121,5 @@ The example directory includes templates for common app flows:
 
 Run `zmr validate --json <scenario.json>` before touching a device. Invalid
 scenarios report `fieldPath`, `line`, and `column` when ZMR can identify the
-source location.
+source location. Unknown root, step, and selector fields are rejected so typos do
+not silently change test intent.

package/docs/support-matrix.md

@@ -0,0 +1,38 @@
+# Support Matrix
+
+Use this page to decide what ZMR can claim today, what needs app-local proof,
+and what is still outside the preview. ZMR is intended as an AI-agent-first
+replacement path for mobile automation: agents observe UI state, choose typed
+actions, validate generated scenarios, and export trace evidence that can replay
+in CI without an LLM.
+
+Support is claimed only when ZMR has lifecycle, observation, selector/action,
+trace, and repeat-run evidence for the target class.
+
+| Target | Status | Evidence standard | Notes |
+| --- | --- | --- | --- |
+| Android emulator | Supported | Public demo smoke plus 20-run pilot gate | ADB/UI Automator, optional Android shim, emulator lifecycle helpers |
+| Android physical device | Supported, app-team evidence required | 20-run pilot gate on a connected device | Same ADB path; publish only redacted app-safe evidence |
+| iPhone simulator | Supported | Public iOS simulator demo smoke plus shim traces | `simctl` lifecycle with app-local XCTest/XCUIAutomation shim for selector-grade actions |
+| iPad simulator | Supported, evidence-needed | iPad simulator smoke plus 20-run pilot gate before production claims | Uses the same iOS simulator path; teams should verify tablet layouts and size-class branches |
+| iPhone physical device | Supported, validate locally | 20-run pilot gate on a trusted device | `devicectl` lifecycle plus XCTest shim, subject to signing, Developer Mode, and Xcode availability |
+| iPad physical device | Supported, evidence-needed | 20-run pilot gate on a trusted iPad before production claims | Uses the same physical iOS/iPadOS path; keep it a separate row because tablet UI can diverge |
+| tvOS simulator/device | Not supported in this preview | Separate proof of concept, shim, destination, and trace evidence required | Reasonable Apple-platform research after iPad evidence, but not a 1.0 dependency |
+| watchOS simulator/device | Not supported in this preview | Separate companion/pairing/lifecycle design and evidence required | Treat as customer-driven roadmap work, not a 1.0 dependency |
+| Cloud device farms | Not included | Adapter and provider-specific evidence required | Current focus is local and self-managed devices |
+
+## Evidence Policy
+
+- Production-stable support requires a 20-run pilot gate with zero failures and
+  redacted trace/report artifacts.
+- iPad evidence must stay separate from iPhone evidence. The runner path is
+  shared, but layouts, split views, and size-class behavior can produce
+  different UI trees and selector outcomes.
+- App-owned selectors should come first: `resourceId`/`id`, accessibility
+  identifiers, content descriptions, accessibility labels, then stable visible
+  text.
+- Use `stableId` only as a fallback copied from a current semantic snapshot. It
+  is useful for immediate agent actions; committed CI scenarios should prefer
+  app-owned identifiers.
+- tvOS and watchOS should stay out of public support claims until their platform
+  lifecycles, shim protocols, and trace evidence exist.

package/docs/trace-privacy.md

@@ -1,7 +1,8 @@
 # Trace Privacy
 
-ZMR traces are debugging artifacts. They can contain sensitive app state even
-when scenario files are generic.
+ZMR traces are product-debugging artifacts. Treat them as sensitive by default:
+even a generic scenario can capture private UI state, logs, identifiers, or
+typed inputs from the app under test.
 
 ```mermaid
 flowchart LR
@@ -24,7 +25,8 @@ Raw trace directories may include:
 
 ## Sharing Rules
 
-- Disable unnecessary raw artifacts in `.zmr/config.json`:
+- Disable unnecessary raw artifacts in `.zmr/config.json` before collecting
+  traces that may leave a trusted machine:
 
   ```json
   {

package/docs/troubleshooting.md

@@ -1,6 +1,7 @@
 # Troubleshooting
 
-Start with structured diagnostics instead of reading terminal output by hand:
+Start with structured diagnostics. They give humans, agents, and CI scripts the
+same setup state, error codes, field paths, and remediation hints:
 
 ```bash
 zmr doctor --json
@@ -13,25 +14,25 @@ zmr explain traces/zmr-android
 `zmr doctor --json` is the first command to run when setup is unclear. It
 reports Zig, ADB, Android device count, `xcrun`, iOS simulator state, physical
 iOS device state, and configured Android/iOS shim command paths in a
-machine-readable shape that scripts and agents can inspect. Device readiness
-checks report `warning` when ADB sees zero devices, `xcrun` sees zero booted
-iOS simulators, `devicectl` sees zero paired physical iOS devices, or all
-listed physical devices are disconnected/unavailable, with stable
+machine-readable shape. Device readiness checks report `warning` when ADB sees
+zero devices, `xcrun` sees zero booted iOS simulators, `devicectl` sees zero
+paired physical iOS devices, or all listed physical devices are
+disconnected/unavailable, with stable
 `setup.android.no_devices`, `setup.ios.no_booted_simulators`,
 `setup.ios.no_physical_devices`, and
 `setup.ios.no_ready_physical_devices` error codes.
 Missing tool and shim checks also include stable setup codes such as
 `setup.adb.not_found` and `setup.android_shim.not_found`.
 By default `doctor` exits zero after printing diagnostics so interactive setup
-can keep going; add `--strict` when CI or install scripts should exit non-zero
+can keep going. Add `--strict` when CI or install scripts should exit non-zero
 for any warning or missing check.
-When run with `--config .zmr/config.json`, it
-first reports whether the config file itself loaded, then validates configured
-smoke scenario files from `android.smokeScenario` and
-`ios.smokeScenario` so app-local setup mistakes fail before device orchestration
-starts. Config files with wrong types, such as string values for boolean
-artifact controls, unknown fields, such as misspelled `smokeScenario`, or empty strings
-where paths/app ids/script commands are required are reported as `config` warnings.
+
+When run with `--config .zmr/config.json`, `doctor` first reports whether the
+config file loaded, then validates configured smoke scenario files from
+`android.smokeScenario` and `ios.smokeScenario` so app-local setup mistakes fail
+before device orchestration starts. Config files with wrong types, unknown
+fields such as misspelled `smokeScenario`, or empty strings where paths, app
+ids, or script commands are required are reported as `config` warnings.
 Those warnings include `fieldPath` in JSON mode when ZMR can identify the
 invalid `.zmr/config.json` key, plus stable `errorCode` values for setup
 automation.
@@ -109,6 +110,7 @@ zmr validate --json .zmr/android-smoke.json
 The JSON output includes `errorCode`, `fieldPath`, `line`, and `column` when ZMR
 can locate the source. Fix schema and selector mistakes there first; device
 state debugging is slower and less reliable when the scenario itself is invalid.
+Unknown root, step, and selector fields are rejected to catch typos early.
 
 ## Android Device Issues
 
@@ -234,7 +236,8 @@ with the `appState` command above.
 
 ## Trace And Failure Issues
 
-When a run fails, do not rerun blindly. Inspect the recorded failure:
+When a run fails, inspect the recorded failure before changing selectors or
+rerunning:
 
 ```bash
 zmr explain traces/zmr-android

package/npm/app-config.mjs

@@ -71,12 +71,14 @@ export function appConfig(appId, { android = true, ios = true, androidShim = "",
       defaultDevice: "emulator-5554",
       smokeScenario: ".zmr/android-smoke.json",
       traceDir: "traces/zmr-android",
+      ensureDevice: true,
     },
     ios: {
       enabled: ios,
       defaultDevice: "booted",
       smokeScenario: ".zmr/ios-smoke.json",
       traceDir: "traces/zmr-ios",
+      ensureDevice: true,
     },
     artifacts: {
       screenshots: true,

package/npm/commands.mjs

@@ -1,11 +1,11 @@
 export function smokeRunCommand({ platform, androidShim = "", iosShim = "" }) {
   if (platform === "android") {
-    const args = ["zmr", "run", ".zmr/android-smoke.json", "--device", "emulator-5554", "--trace-dir", "traces/zmr-android"];
+    const args = ["zmr", "run", ".zmr/android-smoke.json", "--device", "emulator-5554", "--trace-dir", "traces/zmr-android", "--ensure-device"];
     if (androidShim) args.push("--android-shim", androidShim);
     return shellJoin(args);
   }
   if (platform === "ios") {
-    const args = ["zmr", "run", ".zmr/ios-smoke.json", "--platform", "ios", "--device", "booted", "--trace-dir", "traces/zmr-ios"];
+    const args = ["zmr", "run", ".zmr/ios-smoke.json", "--platform", "ios", "--device", "booted", "--trace-dir", "traces/zmr-ios", "--ensure-device"];
     if (iosShim) args.push("--ios-shim", iosShim);
     return shellJoin(args);
   }
@@ -76,10 +76,10 @@ export function reliabilityCommand({ scenario, platform = "", device, appId, xcr
 
 export function devClientRunCommand({ platform }) {
   if (platform === "android") {
-    return "zmr run .zmr/android-dev-client-smoke.json --device emulator-5554 --trace-dir traces/zmr-android-dev-client";
+    return "zmr run .zmr/android-dev-client-smoke.json --device emulator-5554 --trace-dir traces/zmr-android-dev-client --ensure-device";
   }
   if (platform === "ios") {
-    return "zmr run .zmr/ios-dev-client-open-link.json --platform ios --device booted --trace-dir traces/zmr-ios-dev-client";
+    return "zmr run .zmr/ios-dev-client-open-link.json --platform ios --device booted --trace-dir traces/zmr-ios-dev-client --ensure-device";
   }
   throw new Error(`unsupported dev-client platform: ${platform}`);
 }

package/npm/scaffold.mjs

@@ -139,12 +139,12 @@ export function appInitOutput(appRoot, appId, plan, { packageScripts = false } =
   } else {
     if (androidScenarioPath) {
       smokeCommands.push(
-        `zmr run ${shellQuote(androidScenarioPath)} --device emulator-5554 --trace-dir ${shellQuote(pathJoin(appRoot, "traces", "zmr-android"))}`,
+        `zmr run ${shellQuote(androidScenarioPath)} --device emulator-5554 --trace-dir ${shellQuote(pathJoin(appRoot, "traces", "zmr-android"))} --ensure-device`,
       );
     }
     if (iosScenarioPath) {
       smokeCommands.push(
-        `zmr run ${shellQuote(iosScenarioPath)} --platform ios --device booted --trace-dir ${shellQuote(pathJoin(appRoot, "traces", "zmr-ios"))}`,
+        `zmr run ${shellQuote(iosScenarioPath)} --platform ios --device booted --trace-dir ${shellQuote(pathJoin(appRoot, "traces", "zmr-ios"))} --ensure-device`,
       );
     }
   }