zeno-mobile-runner 0.1.3 → 0.2.0

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:
@@ -21,7 +37,11 @@ Then it sends JSON-RPC methods such as:
 - `wait.until`
 - `assert.visible`
 - `assert.healthy`
+- `scenario.validate`
 - `trace.events`
+- `trace.explain`
+- `trace.explore`
+- `trace.discover`
 - `trace.export`
 
 Use clients when an AI agent, service, or test harness wants to drive ZMR
@@ -37,12 +57,12 @@ even when normal page text is also present.
 
 | Language | Files | Why it looks this way |
 | --- | --- | --- |
-| TypeScript | `clients/typescript/index.mjs`, `index.d.ts` | ESM runtime plus type declarations, no build step required |
-| Python | `clients/python/zmr_client.py`, `pyproject.toml` | Standard-library importable module that can be vendored or pip-installed from source |
-| Go | `clients/go/zmr/client.go` | Normal Go package inside a module |
-| Rust | `clients/rust/src/lib.rs` | Cargo library crate convention |
-| Swift | `clients/swift/Sources/ZMRClient/ZMRClient.swift` | SwiftPM package for macOS host-side tools |
-| Kotlin | `clients/kotlin/src/main/kotlin/dev/zmr/ZmrClient.kt` | Gradle/Kotlin source package for JVM host-side tools |
+| TypeScript | `clients/typescript/index.mjs`, `index.d.ts` | ESM runtime plus type declarations, including `explainTrace`, `exploreTrace`, `discoverTrace`, and `validateScenario` helpers |
+| Python | `clients/python/zmr_client.py`, `pyproject.toml` | Standard-library importable module with `explain_trace`, `explore_trace`, `discover_trace`, and `validate_scenario` helpers |
+| Go | `clients/go/zmr/client.go` | Normal Go package inside a module, including `ExplainTrace`, `ExploreTrace`, `DiscoverTrace`, and `ValidateScenario` helpers |
+| Rust | `clients/rust/src/lib.rs` | Cargo library crate convention, including `explain_trace`, `explore_trace`, `discover_trace`, and `validate_scenario` helpers |
+| Swift | `clients/swift/Sources/ZMRClient/ZMRClient.swift` | SwiftPM package for macOS host-side tools, including `explainTrace`, `exploreTrace`, `discoverTrace`, and `validateScenario` helpers |
+| Kotlin | `clients/kotlin/src/main/kotlin/dev/zmr/ZmrClient.kt` | Gradle/Kotlin source package for JVM host-side tools, including `explainTrace`, `exploreTrace`, `discoverTrace`, and `validateScenario` helpers |
 
 Rust has `src/lib.rs` because Cargo expects a library crate there. The other
 clients do have equivalent entry points; they are just idiomatic for their

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
 
@@ -124,7 +133,9 @@ The script builds `zmr` when needed, validates both sample scenarios, installs t
 For each single run it writes:
 
 - `auth/report.html`
+- `auth/junit.xml`
 - `login-smoke/report.html`
+- `login-smoke/junit.xml`
 - `auth.zmrtrace`
 - `auth-redacted.zmrtrace`
 - `login-smoke.zmrtrace`
@@ -183,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:
@@ -233,9 +270,11 @@ Build the app for an iOS simulator, boot a simulator, then run:
 For each run it writes:
 
 - `ios-smoke/report.html`
+- `ios-smoke/junit.xml`
 - `ios-smoke.zmrtrace`
 - `ios-smoke-redacted.zmrtrace`
 - `ios-shim-smoke/report.html` when `--ios-shim` is set
+- `ios-shim-smoke/junit.xml` when `--ios-shim` is set
 - `ios-shim-smoke.zmrtrace` when `--ios-shim` is set
 - `ios-shim-smoke-redacted.zmrtrace` when `--ios-shim` is set
 

package/docs/expo-smoke.md

@@ -2,11 +2,11 @@
 
 This is the quickest public smoke path for an Expo app. It proves that the npm
 package installs, the wizard scaffolds a scenario, ZMR can launch an iOS app,
-and the runner can produce screenshots, traces, HTML reports, and redacted trace
-bundles.
+and the runner can produce screenshots, traces, HTML reports, JUnit XML, and
+redacted trace bundles.
 
-The flow below was verified locally with `zeno-mobile-runner@0.1.3` on an iOS
-simulator.
+Run the flow below on a local iOS simulator before treating a specific app build
+as validated.
 
 ```bash
 npx create-expo-app@latest /tmp/zmr-expo-smoke --template blank --yes
@@ -35,7 +35,7 @@ npx zmr run .zmr/ios-smoke.json \
   --trace-dir traces/zmr-ios \
   --json
 
-npx zmr report traces/zmr-ios --out traces/zmr-ios/report.html
+npx zmr report traces/zmr-ios --out traces/zmr-ios/report.html --junit traces/zmr-ios/junit.xml
 npx zmr export traces/zmr-ios --out traces/zmr-ios-redacted.zmrtrace --redact
 ```
 
@@ -55,9 +55,9 @@ Expected result shape:
 ```
 
 This smoke validates the platform-level loop: app launch, health check,
-screenshot capture, trace collection, report generation, and redacted export.
-For selector-grade React Native or Expo assertions on iOS, add the XCTest shim
-described in [app integration](app-integration.md).
+screenshot capture, trace collection, HTML/JUnit report generation, and
+redacted export. For selector-grade React Native or Expo assertions on iOS, add
+the XCTest shim described in [app integration](app-integration.md).
 
 Android follows the same pattern with a connected emulator or device:
 

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/install.md

@@ -54,8 +54,9 @@ zig build-exe src/main.zig -target aarch64-macos.15.0 -O ReleaseSafe -femit-bin=
 ./zig-out/bin/zmr version
 ```
 
-On macOS hosts where Zig can infer the target, `zig build test` and `zig build`
-are also valid.
+On hosts where Zig can infer the target and locate the system SDK, `zig build`
+can also build the binary. The explicit target form above is the supported
+verification path used by CI and release gates.
 
 ## First Run Without A Device
 

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
@@ -68,6 +71,8 @@ This creates:
 `.zmr/AGENTS.md` gives AI agents an app-local operating note with strict
 doctor/validate commands, schema discovery, direct `zmr run` smoke commands,
 JSON-RPC and MCP startup commands, selector guidance, the exact
+`zmr discover --from-trace traces/zmr-agent --out .zmr/discovered/replay-smoke.json --include-actions --validate --json`
+trace-to-test command,
 `zmr explain traces/zmr-agent --json` failure-triage command, the exact
 `zmr export traces/zmr-agent --out traces/zmr-agent-redacted.zmrtrace --redact`
 redacted trace export command.
@@ -91,12 +96,12 @@ Add app-local scripts:
     "zmr:schemas": "zmr schemas --json",
     "zmr:validate": "zmr validate --json .zmr/android-smoke.json && zmr validate --json .zmr/ios-smoke.json",
     "zmr:android": "zmr run .zmr/android-smoke.json --device emulator-5554 --trace-dir traces/zmr-android",
-    "zmr:android:report": "zmr report traces/zmr-android --out traces/zmr-android/report.html",
-    "zmr:android:reliability": "export ZMR_BIN=\"${ZMR_BIN:-zmr}\"; zmr-benchmark --zmr .zmr/android-smoke.json --device emulator-5554 --app-id com.example.mobiletest --runs 20 --trace-root traces/zmr-android-reliability --min-pass-rate 100 --max-failures 0 --max-p95-ms 30000 && \"$ZMR_BIN\" report traces/zmr-android-reliability --out traces/zmr-android-reliability/report.html",
+    "zmr:android:report": "zmr report traces/zmr-android --out traces/zmr-android/report.html --junit traces/zmr-android/junit.xml",
+    "zmr:android:reliability": "export ZMR_BIN=\"${ZMR_BIN:-zmr}\"; zmr-benchmark --zmr .zmr/android-smoke.json --device emulator-5554 --app-id com.example.mobiletest --runs 20 --trace-root traces/zmr-android-reliability --min-pass-rate 100 --max-failures 0 --max-p95-ms 30000 && \"$ZMR_BIN\" report traces/zmr-android-reliability --out traces/zmr-android-reliability/report.html --junit traces/zmr-android-reliability/junit.xml",
     "zmr:matrix": "ZMR_BIN=${ZMR_BIN:-zmr} zmr-device-matrix --matrix .zmr/device-matrix.json --trace-root traces/zmr-matrix --min-pass-rate 100 --max-failures 0",
     "zmr:ios": "zmr run .zmr/ios-smoke.json --platform ios --device booted --trace-dir traces/zmr-ios",
-    "zmr:ios:report": "zmr report traces/zmr-ios --out traces/zmr-ios/report.html",
-    "zmr:ios:reliability": "export ZMR_BIN=\"${ZMR_BIN:-zmr}\"; zmr-benchmark --zmr .zmr/ios-smoke.json --platform ios --device booted --app-id com.example.mobiletest --xcrun xcrun --runs 20 --trace-root traces/zmr-ios-reliability --min-pass-rate 100 --max-failures 0 --max-p95-ms 45000 && \"$ZMR_BIN\" report traces/zmr-ios-reliability --out traces/zmr-ios-reliability/report.html",
+    "zmr:ios:report": "zmr report traces/zmr-ios --out traces/zmr-ios/report.html --junit traces/zmr-ios/junit.xml",
+    "zmr:ios:reliability": "export ZMR_BIN=\"${ZMR_BIN:-zmr}\"; zmr-benchmark --zmr .zmr/ios-smoke.json --platform ios --device booted --app-id com.example.mobiletest --xcrun xcrun --runs 20 --trace-root traces/zmr-ios-reliability --min-pass-rate 100 --max-failures 0 --max-p95-ms 45000 && \"$ZMR_BIN\" report traces/zmr-ios-reliability --out traces/zmr-ios-reliability/report.html --junit traces/zmr-ios-reliability/junit.xml",
     "zmr:pilot": "zmr-pilot-gate --android --ios --android-app-root . --android-app-id com.example.mobiletest --android-device emulator-5554 --ios-app-root . --ios-app-path ./build/Debug-iphonesimulator/Sample.app --ios-app-id com.example.mobiletest --ios-device booted --runs 20 --min-pass-rate 100 --max-failures 0 --evidence-out traces/zmr-pilots/evidence.jsonl",
     "zmr:readiness": "zmr-release-readiness --evidence traces/zmr-pilots/evidence.jsonl --target production --json",
     "zmr:serve": "zmr serve --transport stdio --config .zmr/config.json --trace-dir traces/zmr-agent",
@@ -214,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:
@@ -341,6 +364,79 @@ npm run pack:npm
 
 That command builds release binaries, copies them into `prebuilds/`, and runs `npm pack`.
 
+Tagged GitHub releases publish through npm trusted publishing, not a long-lived
+`NPM_TOKEN` secret. Configure the npm package trusted publisher before relying
+on the tag workflow:
+
+- Package: `zeno-mobile-runner`
+- Provider: GitHub Actions
+- 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
+release assets, verifies exactly one local npm tarball exists under `./dist/`,
+and then publishes that tarball with public access.
+
+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
+verified local tarball manually, authenticate first:
+
+```bash
+npm login --auth-type=web
+npm whoami
+```
+
+The browser/passkey step must finish before publishing. If `npm whoami` returns
+`E401 Unauthorized`, the local machine is not authenticated and `npm publish`
+will fail.
+
+Build and verify the package before publishing:
+
+```bash
+./scripts/ci-gate.sh
+npm pack --dry-run --json
+npm run pack:npm
+```
+
+Publish the generated tarball from `dist/`:
+
+```bash
+npm publish ./dist/zeno-mobile-runner-<version>.tgz --access public
+```
+
+If npm returns `E403` with a two-factor authentication message, the account or
+organization requires either a current interactive 2FA challenge or a granular
+automation token configured to bypass 2FA. For local passkey accounts, rerun
+`npm login --auth-type=web`, complete the passkey challenge in the browser, and
+confirm `npm whoami` before retrying the same `npm publish` command.
+
 ## Node API
 
 ```js

package/docs/production-readiness.md

@@ -0,0 +1,123 @@
+# 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.
+
+## Current Release Standard
+
+Every public release should satisfy:
+
+- `bash tests/docs-readiness-test.sh`
+- `bash tests/public-safety-test.sh`
+- `npm test`
+- `zig test src/test_harness.zig -target aarch64-macos.15.0`
+- `./scripts/release-gate.sh`
+- `npm run pack:npm`
+- `./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:
+
+  ```bash
+  npm install --save-dev zeno-mobile-runner
+  npx zmr version --json
+  ```
+
+Tagged releases are expected to 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.
+
+CI runs retain `traces/`, `zig-cache/coverage/`, and `zig-out/bin/zmr` for 14
+days when those files are produced. Tagged releases retain `dist/` as a
+workflow artifact for 30 days in addition to GitHub release assets.
+
+## Product Gates Before 1.0
+
+| 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 |
+| 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 |
+| Agent workflows | MCP and JSON-RPC loop with semantic snapshots, typed actions, traces, redacted export, guarded trace exploration, and scenario validation | Supported and enforced by the `agent workflow smoke` readiness gate; `zmr explore` is review-first and trace-backed, and an unbounded autonomous crawler is not shipped |
+| CI reporting | HTML reports plus JUnit XML artifacts from trace, benchmark, and pilot directories | Supported by `zmr report --junit` and pilot wrappers |
+| Trace privacy | Redacted export path, denylist/allowlist controls, and public-safety tests | Supported and gated |
+| Release supply chain | Trusted npm publish, GitHub artifact attestations, checksums, SBOM, and release manifest | Workflow is ready; npm trusted publisher must be configured in package settings |
+
+## Reliability Evidence
+
+Use repeated app-local pilots before making app or device claims:
+
+```bash
+zmr-pilot-gate \
+  --android \
+  --ios \
+  --android-app-root . \
+  --android-app-id com.example.mobiletest \
+  --android-device emulator-5554 \
+  --ios-app-root . \
+  --ios-app-path ./build/Debug-iphonesimulator/Sample.app \
+  --ios-app-id com.example.mobiletest \
+  --ios-device booted \
+  --ios-shim ./.zmr/ios-shim \
+  --runs 20 \
+  --min-pass-rate 100 \
+  --max-failures 0 \
+  --evidence-out traces/zmr-pilots/evidence.jsonl
+```
+
+Then summarize readiness:
+
+```bash
+zmr-release-readiness \
+  --evidence traces/zmr-pilots/evidence.jsonl \
+  --target production \
+  --json
+```
+
+Keep the 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 doctor --json` explains setup state and remediation.
+- `zmr schemas --json` exposes machine-readable contracts.
+- `zmr validate --json` catches scenario mistakes before device runs.
+- `zmr serve` exposes JSON-RPC for long-running sessions.
+- `zmr mcp` exposes MCP tools for semantic snapshots, typed actions, and
+  assertion-grade checks.
+- `zmr explain --json` summarizes failed traces.
+- `zmr report --junit` emits CI-compatible test results from trace and
+  benchmark evidence.
+- `zmr export --redact` produces shareable trace bundles.
+- `zmr-release-readiness --target production` requires the `agent workflow
+  smoke` gate, satisfied by a passed `./scripts/release-gate.sh` row or
+  structured evidence for MCP, JSON-RPC, semantic snapshots, typed actions,
+  trace events, trace explanation, trace discovery/exploration, scenario
+  validation, and redacted export.
+
+The safe discovery pattern is still 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.
+
+## Claims Policy
+
+- Claim Android and iOS app-level support only for flows that pass local pilot
+  evidence on the target device class.
+- 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.

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

@@ -1,4 +1,4 @@
-{"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"]}}
 {"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}