zig-mobile-runner 0.1.0

package/docs/demo.md

@@ -0,0 +1,259 @@
+# Demo
+
+Run the local demo with no emulator, simulator, app, or credentials:
+
+```bash
+./scripts/demo.sh
+```
+
+The script builds `zig-out/bin/zmr`, then runs:
+
+- `zmr version`
+- `zmr version --json`
+- `zmr schemas --json`
+- `zmr validate examples/demo-fake.json`
+- `zmr validate examples/demo-failure.json`
+- `zmr validate examples/android-app-onboarding.json`
+- `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/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`
+- 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`
+- `zmr doctor --json` output for a missing Android shim that includes a
+  remediation `hint`
+- `zmr doctor --json` output that warns with stable setup `errorCode` values
+  when no Android devices, booted iOS simulators, or paired physical iOS
+  devices are ready
+- expected-failing `zmr doctor --strict --json` output for the same no-device
+  setup, showing how CI can fail without parsing the diagnostics itself
+- `zmr doctor --json --config traces/demo-doctor-config.json` output that
+  validates configured smoke scenario files, including an `ios-smoke-scenario` remediation
+  for a bad `ios.smokeScenario` and a `zmr validate on the configured Android
+  smoke scenario` hint for malformed scenario JSON
+- `zmr doctor --json --config traces/demo-bad-config.json` output that reports
+  stable `errorCode` plus `fieldPath` for an invalid app-local config value
+  before device setup starts
+- `zmr devices --adb ./tests/fake-adb.sh`
+- `zmr devices --json --adb ./tests/fake-adb.sh`
+- `zmr devices --platform ios --xcrun ./tests/fake-xcrun.sh`
+- `zmr devices --json --platform ios --xcrun ./tests/fake-xcrun.sh`
+- `zmr init --app --json --dir traces/demo-init-app --app-id com.example.demoapp`
+  followed by validation and strict config-driven doctor checks from that
+  generated app-local workspace
+- `zmr import flow-yaml traces/demo-flow-yaml-flow.yaml --out traces/demo-imported-flow.json --json`
+  followed by validation of the generated native ZMR scenario
+- `zmr run examples/demo-fake.json --trace-dir traces/demo-fake-android --json`
+- `scripts/device-matrix.sh --matrix traces/demo-device-matrix.json --trace-root traces/demo-device-matrix`
+- `zmr run examples/demo-failure.json --trace-dir traces/demo-failure --json`
+- `zmr explain traces/demo-failure`
+- `zmr explain traces/demo-failure --json`
+- `zmr serve --transport stdio --trace-dir traces/demo-rpc-session`
+- `node clients/typescript/examples/fake-session.mjs`
+- `python3 clients/python/examples/fake_session.py`
+- `swift run ZMRFakeSession` from `clients/swift`
+- `gradle -p clients/kotlin runFakeSession`
+- `go run ./clients/go/examples/fake-session --zmr ./zig-out/bin/zmr --adb ./tests/fake-adb.sh --trace-dir traces/demo-go-client`
+- `cargo run --manifest-path clients/rust/Cargo.toml --example fake_session -- --zmr ./zig-out/bin/zmr --adb ./tests/fake-adb.sh --trace-dir traces/demo-rust-client`
+- `zmr run examples/ios-smoke.json --platform ios --trace-dir traces/demo-fake-ios`
+
+The fake Android flow exercises selector matching and wait/assert trace output.
+The fake device-matrix flow exercises Android, iOS simulator, and physical iOS
+matrix rows without requiring local hardware, producing `matrix.jsonl` and
+`summary.json`.
+The fake failure flow exercises failed trace diagnostics and the terminal
+`zmr explain` summary.
+The fake JSON-RPC flow exercises the agent protocol over stdio, live RPC trace
+recording, `observe.snapshot`, and redacted `trace.export`.
+Doctor output is intentionally structured for setup automation; `--json`
+includes remediation `hint` values for missing or warning checks, and
+`--config` validates app-local smoke scenario files. Add `--strict` when a
+non-`ok` diagnostic should also make the command fail.
+The TypeScript reference client flow exercises the same protocol through the
+client API external agents would use.
+The Python reference client flow verifies the same agent integration path with
+only the Python standard library.
+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 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
+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.
+
+## Real Android Pilot Demo
+
+Run the Android pilot against a sample app test build:
+
+```bash
+./scripts/run-android-pilot.sh \
+  --app-root /path/to/mobile-app \
+  --device emulator-5554
+```
+
+To force a known emulator state, direct `zmr run` supports `--android-avd`,
+`--create-avd-if-missing`, `--avd-system-image`, `--avd-device`,
+`--restore-snapshot`, `--reset-emulator`, and `--wait-emulator`. The pilot
+wrapper accepts the same state controls while also building/installing the app.
+Add `--screen-record` to keep a pilot-level MP4 under the trace root:
+
+```bash
+./scripts/run-android-pilot.sh \
+  --app-root /path/to/mobile-app \
+  --device emulator-5554 \
+  --avd Small_Phone \
+  --reset-emulator \
+  --restore-snapshot zmr-clean \
+  --screen-record
+```
+
+The script builds `zmr` when needed, validates both sample scenarios, installs the debug test APK, starts the app's test Metro server, and runs:
+
+- `examples/android-app-auth-probe.json`
+- `examples/android-app-login-smoke.json`
+
+For each single run it writes:
+
+- `auth/report.html`
+- `login-smoke/report.html`
+- `auth.zmrtrace`
+- `auth-redacted.zmrtrace`
+- `login-smoke.zmrtrace`
+- `login-smoke-redacted.zmrtrace`
+- `screenrecord.mp4` when pilot `--screen-record`, `zmr run --screen-record`, or `.zmr/config.json` `artifacts.screenRecording` is enabled
+
+Use the redacted bundles for demos outside a trusted local machine:
+
+```bash
+open viewer/index.html
+```
+
+Then load `auth-redacted.zmrtrace` or `login-smoke-redacted.zmrtrace`.
+
+Inspect the command plan without touching the emulator:
+
+```bash
+./scripts/run-android-pilot.sh --dry-run --skip-emulator --skip-metro --app-root <android-app-root>
+```
+
+Run repeated benchmark passes:
+
+```bash
+./scripts/run-android-pilot.sh \
+  --app-root <android-app-root> \
+  --device emulator-5554 \
+  --runs 20 \
+  --min-pass-rate 100 \
+  --max-failures 0
+```
+
+`<trace-root>/metro.log` may contain sensitive app output from the sample app test environment. Do not publish raw Metro logs.
+
+## Real Android Demo APK
+
+To generate a small public native Android app and matching smoke scenario:
+
+```bash
+npx zmr-demo-android --out /tmp/zmr-android-demo --device emulator-5554 --avd <avd-name>
+```
+
+The wrapper builds a signed debug APK with Android SDK command-line tools
+only, boots the named AVD when the requested device is not ready, installs the
+app, and runs the generated smoke scenario. To inspect or customize the
+generated app before running manually:
+
+```bash
+npx zmr-create-android-demo-app --out /tmp/zmr-android-demo
+adb install -r /tmp/zmr-android-demo/build/app-debug.apk
+zmr run /tmp/zmr-android-demo/.zmr/android-smoke.json \
+  --device emulator-5554 \
+  --app-id com.example.mobiletest \
+  --trace-dir /tmp/zmr-android-demo/traces/android-demo
+```
+
+The scenario launches the app, waits for visible text, taps a button, types
+text into a field, and captures a trace-backed snapshot.
+
+## Real iOS Simulator Demo
+
+To generate a small public demo app with the ZMR XCTest shim already installed:
+
+```bash
+npx zmr-demo-ios --out /tmp/zmr-ios-demo --device booted --cleanup-build-products
+```
+
+That command creates the demo app, builds it, installs it on the requested
+simulator, runs the plain iOS smoke and selector-grade shim smoke, then writes
+reports and redacted `.zmrtrace` bundles. `--cleanup-build-products` removes
+generated Xcode `DerivedData` after the pilot so repeated demo runs keep their
+footprint small. When `--device booted` is used and no
+simulator is running, the command boots an available iOS simulator first. If
+the first available simulator fails to boot because CoreSimulator cannot start
+`launchd_sim`, the script tries the next available iOS simulator before failing.
+
+To inspect or customize the generated app before running the pilot manually:
+
+```bash
+npx zmr-create-ios-demo-app --out /tmp/zmr-ios-demo
+cd /tmp/zmr-ios-demo
+xcodebuild -project ios/ZMRDemo.xcodeproj -scheme ZMRDemo -destination 'generic/platform=iOS Simulator' -derivedDataPath DerivedData build
+```
+
+Then boot a simulator and run from the ZMR repo:
+
+```bash
+scripts/run-ios-pilot.sh \
+  --app-root /tmp/zmr-ios-demo \
+  --app-path /tmp/zmr-ios-demo/DerivedData/Build/Products/Debug-iphonesimulator/ZMRDemo.app \
+  --app-id com.example.mobiletest \
+  --device booted \
+  --ios-shim /tmp/zmr-ios-demo/.zmr/ios-shim
+```
+
+Build the app for an iOS simulator, boot a simulator, then run:
+
+```bash
+./scripts/run-ios-pilot.sh \
+  --app-root /path/to/mobile-app \
+  --app-path /path/to/mobile-app/build/Debug-iphonesimulator/Sample.app \
+  --app-id com.example.mobiletest \
+  --device booted \
+  --ios-shim /path/to/mobile-app/.zmr/ios-shim
+```
+
+For each run it writes:
+
+- `ios-smoke/report.html`
+- `ios-smoke.zmrtrace`
+- `ios-smoke-redacted.zmrtrace`
+- `ios-shim-smoke/report.html` when `--ios-shim` is set
+- `ios-shim-smoke.zmrtrace` when `--ios-shim` is set
+- `ios-shim-smoke-redacted.zmrtrace` when `--ios-shim` is set
+
+The iOS demo covers simulator install, launch/open-link, screenshot capture,
+log capture, trace export, and viewer inspection. With `--ios-shim`, it also
+runs `examples/ios-shim-smoke.json`, which exercises launch, waitVisible, tap,
+selector-scoped typeText, hideKeyboard, and snapshot through the generated
+XCTest/XCUIAutomation shim command.
+
+When an iOS shim is configured, the pilot wrapper prewarms it before scenario
+timing by sending `{"cmd":"appState"}`. That catches Xcode target wiring issues
+early and keeps cold `build-for-testing` cost out of benchmark durations.
+The same app-state check is used as an idempotent launch confirmation when the
+app is already running but `simctl launch` reports a non-zero exit.
+
+Simulator demos require a simulator-built `iphonesimulator` `.app`. A signed
+device `.ipa` is for `--ios-device-type physical` only and is rejected early for
+simulator pilots.
+
+`clearState` on iOS is best-effort app uninstall by bundle id. Repeating it is
+safe: a simulator where the app is already absent is treated as clean.

package/docs/dsl.md

@@ -0,0 +1,57 @@
+# Scenario DSL
+
+ZMR uses JSON as the V1 scenario DSL:
+
+```json
+{
+  "name": "Login smoke",
+  "appId": "com.example.mobiletest",
+  "steps": [
+    { "action": "launch" },
+    { "action": "tap", "selector": { "resourceId": "email" } },
+    { "action": "typeText", "text": "user@example.com" },
+    { "action": "assertVisible", "selector": { "text": "Welcome" } }
+  ]
+}
+```
+
+## Why JSON For V1
+
+JSON is strict, deterministic, schema-validatable, and easy for agents to emit.
+
+- It is strict and deterministic.
+- It has mature schema validation.
+- It is easy for AI agents and code generators to emit.
+- It works cleanly across TypeScript, Python, Go, Rust, Zig, and CI tooling.
+- It avoids hidden parser behavior while the protocol is still a developer
+  preview.
+
+JSON is not the most pleasant hand-authored format for every team. That is why
+ZMR keeps scenario files small, supports generated scenarios, and includes an
+import path for a documented subset of mobile-flow YAML.
+
+## Authoring Recommendation
+
+- Use JSON for committed `.zmr/*.json` scenarios.
+- Use `zmr validate --json` before device runs.
+- Generate JSON from higher-level tools when humans want a friendlier surface.
+- Keep selectors stable and explicit: resource ids or accessibility identifiers
+  first, labels/content descriptions second, text third.
+
+## Human-Friendly Layer
+
+JSON should stay the canonical machine contract. A friendlier authoring layer
+can come later as a compiler to JSON, not as a second runtime format.
+
+## Roadmap
+
+The likely production shape is:
+
+1. JSON remains the canonical machine contract.
+2. A friendlier authoring layer can compile to JSON.
+3. The compiler must preserve source locations so validation errors still point
+   to the human-authored file.
+4. The JSON Schema and protocol fixtures remain the compatibility boundary.
+
+This keeps agents accurate while leaving room for nicer hand-authored test
+files later.

package/docs/install.md

@@ -0,0 +1,233 @@
+# Install
+
+ZMR is at present distributed as local release archives built by `scripts/build-release.sh`.
+
+## Build From Source
+
+```bash
+git clone <repo-url> zig-mobile-runner
+cd zig-mobile-runner
+zig test src/main.zig -target aarch64-macos.15.0
+zig build-exe src/main.zig -target aarch64-macos.15.0 -O ReleaseSafe -femit-bin=zig-out/bin/zmr
+./zig-out/bin/zmr version
+```
+
+On this macOS 26 host, Zig `0.15.2` at present needs the explicit `aarch64-macos.15.0` target. Normal Zig environments can also use:
+
+```bash
+zig build test
+zig build
+```
+
+## Local Release Archive
+
+```bash
+./scripts/build-release.sh
+tar -xzf dist/zmr-0.1.0-aarch64-macos.15.0.tar.gz -C /tmp
+/tmp/zmr-0.1.0-aarch64-macos.15.0/zmr version
+```
+
+Verify checksums:
+
+```bash
+cd dist
+shasum -a 256 -c SHA256SUMS
+```
+
+Maintainers can run the stricter release verifier after building:
+
+```bash
+./scripts/verify-release-artifacts.sh
+```
+
+It verifies each checksum entry and requires the archives, SBOM, notices,
+Homebrew formula, and `RELEASE_MANIFEST.json` to be present in `SHA256SUMS`.
+It also checks that manifest artifact sizes and SHA-256 digests match the files
+in `dist/`.
+
+Maintainers publishing macOS archives can sign and notarize them after building
+and before uploading release assets:
+
+```bash
+./scripts/sign-macos-release.sh --identity "Developer ID Application: Example"
+./scripts/notarize-macos-release.sh --keychain-profile "zmr-notary"
+./scripts/verify-release-artifacts.sh
+```
+
+The signing helper extracts each macOS tarball, signs the `zmr` binary with
+hardened runtime, verifies the signature, rebuilds the tarball, refreshes the
+Homebrew formula checksums, and regenerates `SHA256SUMS`. Use `--dry-run` to
+inspect which archives would be signed.
+
+The notarization helper packages each signed macOS archive for `xcrun
+notarytool submit --wait`, writes JSON receipts under `dist/notarization/`,
+refreshes `RELEASE_MANIFEST.json`, and regenerates `SHA256SUMS`. It accepts
+either `--keychain-profile <profile>` or explicit `--apple-id`, `--team-id`,
+and `--password` credentials.
+
+Release metadata is written alongside the archives:
+
+- `SBOM.spdx.json`: SPDX 2.3 software bill of materials for the release.
+- `THIRD_PARTY_NOTICES.md`: dependency and license report.
+- `homebrew/zmr.rb`: generated Homebrew formula with per-platform archive
+  URLs and SHA-256 checksums.
+- `RELEASE_MANIFEST.json`: machine-readable release artifact inventory with
+  paths, types, sizes, and SHA-256 digests.
+- `zig-mobile-runner-*.tgz`: npm package tarball when `npm run pack:npm` has
+  been run.
+- `notarization/*.notary.json`: optional Apple notarization receipts when
+  `scripts/notarize-macos-release.sh` has been run.
+
+All release metadata files and generated package tarballs are included in
+`SHA256SUMS`.
+
+## npm Package
+
+`npm run pack:npm` builds release archives, copies the platform binaries into
+`prebuilds/`, writes `dist/zig-mobile-runner-*.tgz`, and refreshes
+`RELEASE_MANIFEST.json` plus `SHA256SUMS` so the tarball is covered by the same
+integrity checks as native archives. The tagged release workflow uploads that
+tarball with the GitHub release assets, includes it in artifact attestation, and
+runs:
+
+```bash
+npm publish dist/zig-mobile-runner-*.tgz --provenance --access public
+```
+
+The publish step is skipped unless `NPM_TOKEN` is configured for the repository.
+
+## Homebrew Formula
+
+`scripts/build-release.sh` generates a formula under `dist/homebrew/zmr.rb`.
+Tagged releases upload that file with the release assets. For a local release
+build:
+
+```bash
+brew install --build-from-source ./dist/homebrew/zmr.rb
+zmr version
+```
+
+For an external tap, copy the generated formula into the tap after confirming
+the `url` values point at the final GitHub release asset location.
+
+## First Run
+
+```bash
+zmr doctor
+zmr init zmr-scenario.json --app-id com.example.mobiletest
+zmr init --app --json --dir . --app-id com.example.mobiletest
+zmr doctor --strict --json --config .zmr/config.json
+zmr validate examples/demo-fake.json
+./scripts/demo.sh
+```
+
+## npm Install
+
+Inside a mobile app repo:
+
+```bash
+npm install --save-dev zig-mobile-runner
+npx zmr-wizard --app-id com.example.mobiletest --package-json
+npx zmr doctor --strict --json --config .zmr/config.json
+npx zmr-device-matrix --matrix .zmr/device-matrix.json --trace-root traces/zmr-matrix
+```
+
+The npm package exposes the app-facing CLI wrapper, setup wizard, benchmark
+helpers, matrix runner, pilot gate, shim installers, public demo generators,
+release-readiness checker, schemas, examples, reference clients, and the
+packaged agent skill. Common app-local commands are:
+
+```bash
+npx zmr-wizard --app-id com.example.mobiletest --android --ios --package-json
+npx zmr-install-android-shim --app-root . --test-package com.example.mobiletest.test
+npx zmr-install-ios-shim --app-root . --scheme SampleUITests --bundle-id com.example.mobiletest
+npm run zmr:serve
+npm run zmr:mcp
+npx 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
+```
+
+See [docs/npm.md](npm.md) for the full npm binary list, binary resolution,
+app-local `.zmr/` setup, and package publishing details.
+See [config.md](config.md) for `.zmr/config.json` defaults and CLI override precedence.
+
+## App Codebase Integration
+
+Use the runner from a separate checkout and point it at app build artifacts:
+
+```bash
+/path/to/zig-mobile-runner/scripts/run-android-pilot.sh \
+  --app-root /path/to/mobile-app \
+  --app-id com.example.mobiletest \
+  --device emulator-5554
+
+/path/to/zig-mobile-runner/scripts/run-ios-pilot.sh \
+  --app-root /path/to/mobile-app \
+  --app-path /path/to/mobile-app/build/Debug-iphonesimulator/Sample.app \
+  --app-id com.example.mobiletest \
+  --device booted
+```
+
+See [app-integration.md](app-integration.md) for the expected app-side test surface.
+
+## Android Requirements
+
+- Android SDK platform tools with `adb` on `PATH`.
+- A booted emulator or connected device for real Android runs.
+- Test app installed with the expected app id, for example `com.example.mobiletest`.
+
+## iOS Requirements
+
+- Xcode command line tools with `xcrun` on `PATH`.
+- A booted simulator for real simulator runs, or a paired physical device
+  identifier from `zmr devices --json --platform ios --ios-device-type physical`
+  for physical-device lifecycle and selector runs.
+- `zmr doctor --json` reports simulator readiness as `ios-simulators` and
+  paired-device readiness as `ios-physical-devices`, so setup scripts can fail
+  fast before install or XCTest work starts.
+- A simulator-built `iphonesimulator` `.app` for simulator launch/open-link
+  smoke scenarios. A signed device `.ipa` is not simulator-compatible; run it
+  with `--ios-device-type physical` and a real physical device identifier.
+- Physical-device installs require a signed `.app` or `.ipa` accepted by
+  `xcrun devicectl`.
+- Optional app-provided XCTest/XCUIAutomation shim command for hierarchy,
+  selector actions, and native selector waits. Pass it with `--ios-shim <path>`
+  or set `tools.iosShimPath` in `.zmr/config.json`.
+
+To scaffold the shim command and XCTest source into an app repo:
+
+```bash
+npx zmr-install-ios-shim \
+  --app-root . \
+  --scheme SampleUITests \
+  --test-target SampleUITests \
+  --workspace ios/Sample.xcworkspace \
+  --app-target SampleApp \
+  --derived-data-path ios/build/ZMRDerivedData \
+  --bundle-id com.example.mobiletest \
+  --patch-xcodeproj
+```
+
+Run `.zmr/ensure-ios-shim-target.sh` to create/update the UI test target, add
+the generated Swift files, configure `.zmr/ZMRShimUITests-Info.plist`, and write
+a shared scheme. The helper uses the Ruby `xcodeproj` gem. For workspace input,
+it resolves the referenced `.xcodeproj` automatically when there is one project,
+or when exactly one project contains `--app-target`, or when `--bundle-id` disambiguates
+matching app targets. Use `--project ios/Sample.xcodeproj`
+instead of `--workspace` for still-ambiguous multi-project workspaces or
+project-only apps.
+
+The installer also patches or creates `.zmr/config.json` with
+`tools.iosShimPath: "./.zmr/ios-shim"`, so `zmr run`, `zmr serve`, and
+`zmr doctor` can discover the shim from app-local config without repeating the
+flag on every command.
+
+The generated `.zmr/ios-shim` caches `build-for-testing` output under
+`.zmr/ios-shim-state/` and uses `test-without-building` for selector commands.
+Set `ZMR_IOS_SHIM_FORCE_REBUILD=1` after app-side target changes, or
+`ZMR_IOS_SHIM_ONESHOT=1` for the slower one-command-per-XCTest fallback when
+debugging Xcode wiring.
+
+For reliable real simulator and physical-device runs, execute ZMR from a normal
+terminal or CI worker with access to Xcode, CoreSimulator, and device caches.
+Restricted sandboxes can block Xcode log/cache access and make `xcodebuild` or
+`simctl` report misleading setup errors.

package/docs/market-positioning.md

@@ -0,0 +1,70 @@
+# Market Positioning
+
+ZMR is a developer-preview runner. It should compete by being the best local
+mobile automation control plane for AI agents, not by pretending to be a mature
+drop-in replacement for every existing runner on day one.
+
+## What The Market Rewards
+
+The existing market rewards frameworks that feel easy to start, expose stable
+selectors and waits, produce useful reports, and run well in CI. Some tools lean
+on app internals, some use simple flow files, and some emphasize hosted device
+coverage. ZMR should avoid copying those surfaces directly. Its opportunity is a
+mobile-native control plane: device lifecycle, app install/launch/clear state,
+accessibility trees, selector actions, logs, screenshots, trace bundles, and
+physical-device workflows.
+
+## ZMR Position
+
+ZMR should lead with:
+
+- **Agent-native protocol:** structured snapshots and actions over JSON-RPC,
+  plus an MCP stdio server for agent runtimes.
+- **Semantic mobile tree:** normalized roles, names, selectors, bounds, and
+  recommended actions so agents do not parse platform-specific hierarchy dumps.
+- **Trace-first reliability:** every action produces evidence agents and humans
+  can inspect.
+- **Small deterministic core:** Zig runner, explicit adapters, schema-validated
+  inputs, stable CLI JSON.
+- **App-local setup:** `.zmr/` owns config, scenarios, shims, and private traces.
+- **Language-neutral clients:** TypeScript, Python, Go, and Rust can all drive
+  the same protocol.
+
+## Where ZMR Is Already Strong
+
+| Area | ZMR advantage |
+| --- | --- |
+| AI agent integration | First-class JSON-RPC, MCP tools, semantic snapshots, live trace events, schemas, agent guide, packaged skill |
+| Failure diagnostics | Trace bundles, snapshot replay, UI tree, screenshots, logs, `zmr explain` |
+| Language neutrality | Protocol clients across multiple languages |
+| Local release discipline | Release gate, coverage gate, artifacts, SBOM, checksums, attestation |
+| App-local privacy | `.zmr/` config and redacted trace export |
+| Mobile focus versus browser engines | Native Android/iOS device lifecycle and accessibility semantics instead of CDP-only web primitives |
+
+## Where ZMR Must Catch Up
+
+| Area | Gap |
+| --- | --- |
+| npm distribution | Tarball exists in GitHub release, registry publish still pending |
+| Android proof | Public generic Android demo wrapper exists; repeated emulator proof and app-local pilots still need published release evidence |
+| iOS scale | Simulator demo passes, but repeated-run evidence should be published |
+| Physical iOS | Local lifecycle and selector support exist through `devicectl` plus the XCTest shim; screenshots use the shim, physical log capture still needs hardening |
+| Cloud | Not supported yet |
+| Human DSL | JSON is reliable for agents; a friendlier authoring layer should compile to JSON |
+| Brand surface | README is now concise; a docs/landing site should follow after npm publish |
+
+## Website Recommendation
+
+For `0.1.x`, GitHub README plus release assets are enough. After npm publish,
+create a docs site with:
+
+- homepage: value proposition, install, demo GIF/video, trace viewer screenshot
+- docs: install, `.zmr/`, scenarios, JSON-RPC, clients, shims, privacy
+- compare: honest capability matrix
+- examples: Android app, iOS app, agent session
+- releases: checksums, SBOM, artifact verification
+
+Do not create a marketing-only site before the npm package and repeated device
+evidence are in place. The strongest market fit is a clean first-run path that
+actually works.
+