zig-mobile-runner 0.1.0

package/docs/roadmap.md

@@ -0,0 +1,334 @@
+# ZMR Product Roadmap
+
+**Goal:** Make Zig Mobile Runner a shippable open-source mobile test runner for AI agents, with Android production support first and iOS production support next.
+
+**Product Thesis:** ZMR should feel like Playwright for mobile agents: fast typed control, rich observations, deterministic traces, and reliable isolation. It should beat shell-driven mobile automation by moving orchestration, waits, retries, traces, and protocol handling into a small Zig core while delegating platform-specific state and interaction to focused native adapters.
+
+**Current State:** `0.1.0` local dev preview. Android pilot flows exist. iOS simulator lifecycle, snapshot, and selector actions are supported through `simctl` plus the XCTest shim. Coverage gate is above 90%. Demo traces can be generated without an emulator.
+
+---
+
+## Definition Of Shippable
+
+ZMR is shippable when a new developer can install it, run the no-device demo, connect an Android emulator, run the Android pilot wrapper, connect a booted iOS simulator, run the iOS smoke wrapper, inspect actionable traces, and integrate an external AI agent through JSON-RPC without manual code changes or hidden setup.
+
+The first public product should be a **developer preview**, not a broad device-farm platform. It should be honest about limitations and strong on repeatability.
+
+## Product Principles
+
+- **Typed agent protocol first:** agents should consume structured snapshots and action results, not parse terminal output.
+- **Deterministic traces:** every run should leave enough evidence to debug failure without rerunning immediately.
+- **Fast local loop:** fake-device tests, fake demos, and simulator/emulator flows must run locally.
+- **Adapter boundaries:** Android, iOS, and future platforms should share runner semantics without sharing platform hacks.
+- **No embedded LLM:** ZMR is the control plane; external agents decide.
+- **Security by default:** persisted JSON traces redact common secrets; publishing real visual artifacts requires explicit sanitizer work.
+
+## Release Tracks
+
+### Track A: `0.1.x` Dev Preview Hardening
+
+Purpose: make the current repo credible for early users.
+
+Ship criteria:
+- `README.md` has install, demo, Android pilot, iOS smoke, app integration, and troubleshooting instructions.
+- `docs/protocol.md` documents every JSON-RPC method, params, response shape, and error shape.
+- `docs/shipping.md` has one copy-paste release gate.
+- `scripts/demo.sh` passes on a clean macOS machine with Zig and no emulator.
+- `scripts/coverage.sh` stays at or above 90%.
+- Release archives include binary, README, license, protocol docs, demo scenarios, checksum file, and verifier.
+
+Work:
+- [x] Add `zmr doctor` to detect Zig, ADB, `xcrun`, emulator/simulator state, Android SDK paths, and missing permissions.
+- [x] Add `zmr init` to scaffold a starter scenario.
+- [x] Add stable JSON schemas for scenario files, snapshots, action results, and JSON-RPC payloads.
+- [x] Add app-local `.zmr/config.json` schema and CLI default loading.
+- [x] Add public error code taxonomy instead of exposing raw Zig error names.
+- [x] Add install instructions for manual tarball/source install.
+- [x] Add release notes template and changelog.
+
+Verification:
+- `zig fmt --check build.zig src`
+- `bash -n scripts/*.sh tests/*.sh`
+- `zig test src/main.zig -target aarch64-macos.15.0`
+- `./scripts/demo.sh`
+- `./scripts/coverage.sh`
+- `./scripts/build-release.sh`
+
+### Track B: Android Production Adapter
+
+Purpose: move Android from useful pilot to product-grade reliability.
+
+Ship criteria:
+- Android sample app auth probe and login smoke flows pass repeatedly on a clean emulator.
+- Failure traces identify selector misses, active package/activity, visible text, screenshots, logs, and timing.
+- A native Android shim can provide hierarchy and interaction when ADB shell/UI Automator is too slow or flaky.
+- Runner can install, launch, stop, clear state, deep link, tap, type, swipe, press back, wait, assert, and snapshot reliably.
+
+Work:
+- [x] Add Android shim project under `shims/android/`.
+- [x] Implement faster hierarchy retrieval through Android accessibility/UI Automator APIs.
+- [x] Implement reliable tap/type/swipe through the shim with ADB shell fallback.
+- [x] Add app idle/settle detection instead of fixed sleeps where possible.
+- [x] Add local emulator helper script for boot, wait-ready, snapshot save/load, and kill.
+- [x] Add in-run emulator lifecycle orchestration: create, boot, wait-ready, reset, snapshot restore.
+  - [x] Pilot wrapper can reset the target emulator and boot an AVD from a named snapshot.
+  - [x] `zmr run` can boot an AVD, restore a snapshot, reset, and wait-ready before scenario execution.
+  - [x] `zmr run` can create a missing AVD from an installed Android system image.
+- [x] Add Android artifact capture: screenshot, hierarchy, logcat window, package/activity, display metrics, optional screen recording.
+  - [x] Pilot wrapper can capture an optional MP4 screen recording for visual flake triage.
+  - [x] Snapshots include Android display density when available.
+  - [x] Traced Android runs can capture opt-in MP4 screen recordings.
+- [x] Add Android flake harness that repeats pilot scenarios and emits pass rate/duration summaries.
+
+Acceptance:
+- `examples/android-app-auth-probe.json` passes 20/20 local runs.
+- `examples/android-app-login-smoke.json` passes 20/20 local runs.
+- Repeated-run reports show stable pass rate, useful failure diagnostics, and acceptable runtime on a clean emulator.
+- All Android adapter unit/fake tests pass without an emulator.
+
+### Track C: iOS Production Adapter
+
+Purpose: keep the iOS simulator adapter at agent-grade quality and expand the supported surface deliberately.
+
+Ship criteria:
+- iOS supports structured hierarchy, selector matching, tap, type, swipe, press home/back-equivalent navigation, launch, stop, clear state, deep link, screenshot, logs, and snapshots.
+- iOS implementation uses XCTest/XCUIAutomation boundaries instead of fragile coordinate-only shelling.
+- iOS simulator smoke flow runs with the same scenario semantics as Android where platform concepts overlap.
+
+Work:
+- [x] Create app-local XCTest shim source and installer under `shims/ios/`.
+- [x] Define a small local shim protocol for hierarchy, element query, tap, type, swipe, keyboard, and app state.
+- [x] Add Zig-side iOS shim command and snapshot mapping tests.
+- [x] Add Zig-side iOS shim process control for one-command local shim execution.
+- [x] Map XCUIElement snapshots into `UiNode` with stable ids, labels, identifiers, values, enabled/visible flags, and bounds.
+- [x] Add iOS selector tests using fake shim responses.
+- [x] Add real simulator E2E smoke scenario with install/launch/openLink/snapshot/tap/type using the generated XCTest shim.
+- [x] Add `examples/ios-dev-client-open-link.json` for Expo dev-client
+  simulator flows that need to open a local Metro bundle before selector waits.
+- [x] Decide and document iOS clear-state semantics: best-effort app uninstall by bundle id; a missing app is already clean.
+
+Acceptance:
+- `examples/ios-smoke.json` passes on a real booted simulator with a test app.
+- At least one selector-driven iOS flow passes repeatedly without manual interaction.
+- iOS unsupported-action errors disappear for normal UI actions.
+- iOS traces include screenshot, hierarchy, logs, active app id, timings, and assertions.
+
+### Track D: Protocol And SDKs
+
+Purpose: make ZMR easy for external AI agents and test harnesses to consume.
+
+Ship criteria:
+- JSON-RPC is stable and versioned.
+- Clients can generate valid scenarios and validate snapshots using schemas.
+- At least one reference client exists.
+
+Work:
+- [x] Add `schemas/` with JSON Schema files for scenario, snapshot, action result, trace event, and JSON-RPC messages.
+- [x] Add protocol compatibility tests that load fixtures and assert exact response shapes.
+- [x] Add a TypeScript reference client package in `clients/typescript/`.
+- [x] Add a Python reference client package in `clients/python/`.
+- [x] Add a Go reference client package in `clients/go/`.
+- [x] Add a Rust reference client package in `clients/rust/`.
+- [x] Add streaming observation/event mode for long-running agent sessions.
+- [x] Add `trace.export` support for live RPC sessions, not only scenario runs.
+- [x] Add semantic protocol version policy.
+
+Acceptance:
+- Reference clients can run demo scenarios through stdio.
+- Protocol fixtures are committed and checked in CI.
+- Breaking changes require protocol version changes and changelog entries.
+
+### Track E: Trace Viewer And Diagnostics
+
+Purpose: make failures easy to understand, not just logged.
+
+Ship criteria:
+- A failed run produces a portable trace bundle that a human can inspect quickly.
+- Trace viewer shows timeline, screenshots, hierarchy, selected nodes, action inputs, logs, and assertion failures.
+
+Work:
+- [x] Define `trace.json` manifest for each run.
+- [x] Add trace bundle export as `.zmrtrace` tar/zip.
+- [x] Build a local static trace viewer under `viewer/`.
+- [x] Add screenshot + UI tree side-by-side inspection.
+- [x] Add replay controls for snapshot-linked trace frames.
+- [x] Add selector miss diagnostics: nearest text matches, hidden/disabled candidates, offscreen hints.
+- [x] Add artifact redaction options for screenshots/XML before sharing.
+- [x] Add benchmark report viewer for duration and flake trends. V1: `zmr report`.
+- [x] Add local device-matrix runner for multi-device smoke gates before cloud
+  device farm certification.
+
+Acceptance:
+- `scripts/demo.sh` produces a trace that opens in the viewer.
+- Selector timeout traces show enough context to fix the selector without rerunning.
+- Public demo traces contain no real app secrets.
+
+### Track F: Scenario Authoring
+
+Purpose: make scenario files easy to create, review, and maintain inside `.zmr/`.
+
+Ship criteria:
+- Users can author scenarios by hand, generate them from examples, and keep app-local runner state under `.zmr/`.
+- Scenario errors are precise and actionable.
+
+Work:
+- [x] Add `zmr validate <scenario.json>` with semantic checks.
+- [x] Add line/field-aware parse errors.
+- [x] Add `zmr explain <trace-dir>` for a concise failure summary.
+- [x] Add examples for auth, onboarding, referral, deep link, and error-state flows.
+- [x] Add scenario style guide for resilient selectors and waits.
+- [x] Add `zmr import flow-yaml` as a one-time migration helper into native
+  `.zmr/*.json` scenarios.
+
+Acceptance:
+- [x] Invalid scenarios fail before touching a device.
+- Docs explain how to write robust agent-generated scenarios.
+
+### Track G: Packaging, CI, And Distribution
+
+Purpose: make releases boring and reproducible.
+
+Ship criteria:
+- CI builds, tests, packages, and publishes checksummed artifacts.
+- Users can install on macOS and Linux without building from source.
+
+Work:
+- [x] Add GitHub release workflow smoke test against packaged binary.
+- [x] Add Homebrew formula.
+- [x] Add macOS archive signing helper for credentialed release maintainers.
+- [x] Add macOS archive notarization helper for credentialed release maintainers.
+- [x] Add Linux x86_64/aarch64 archives with checksum verification docs.
+- [x] Add SBOM generation.
+- [x] Add dependency/license report.
+- [x] Add machine-readable release manifest with artifact digests and sizes.
+- [x] Add tagged-release npm tarball generation and provenance publish path.
+- [x] Add release checklist that includes demo, coverage, pilot E2E, benchmark, and docs review.
+  - [x] Add `scripts/release-gate.sh` so the local release gate is one command.
+
+Acceptance:
+- Fresh machine install path is documented and verified.
+- `zmr version`, `zmr devices`, and `scripts/demo.sh` work from release artifact.
+- Release notes explain platform support and known limitations.
+
+### Track H: Security, Privacy, And Governance
+
+Purpose: make the open-source product safe to use with real apps.
+
+Ship criteria:
+- Secret handling is explicit.
+- Trace sharing rules are documented.
+- Contribution rules are clear.
+
+Work:
+- [x] Add `SECURITY.md` with vulnerability reporting process.
+- [x] Add `CONTRIBUTING.md` with test, formatting, and coverage expectations.
+- [x] Add trace privacy guide.
+- [x] Add screenshot/XML redaction strategy.
+- [x] Add config controls for log capture and artifact capture.
+- [x] Add denylist/allowlist for sensitive node ids and text.
+- [x] Add governance note for protocol evolution.
+
+Acceptance:
+- No docs suggest sharing real traces without sanitization.
+- Security-sensitive defaults are conservative.
+- Contributors can run the full local gate.
+
+## Suggested Release Milestones
+
+### `v0.1.0`: Public Dev Preview
+
+Scope:
+- Current Android runner.
+- iOS lifecycle/snapshot/selector support with `scripts/run-ios-pilot.sh`,
+  simulator-first capture, and physical-device lifecycle through `devicectl`.
+- Fake demo.
+- Public Android and iOS pilot wrappers.
+- Release archives and docs.
+
+Exit gate:
+- Full acceptance gate passes.
+- README and shipping docs match reality.
+- Known limitations are explicit.
+
+### `v0.2.0-alpha`: Android Reliability Alpha
+
+Scope:
+- `zmr doctor`, `zmr validate`, public schemas.
+- Improved Android wait/diagnostics.
+- Repeated Android pilot benchmark report.
+- Public error taxonomy.
+
+Exit gate:
+- Android pilot flows pass repeated local runs.
+- Trace failures are actionable.
+- Coverage remains above 90%.
+
+### `v0.3.0-alpha`: Native Android Shim
+
+Scope:
+- Android shim for hierarchy and interaction.
+- ADB fallback retained.
+- Repeated benchmark reports with trace diagnostics.
+
+Exit gate:
+- Shim path is faster or materially more reliable than shell-only path.
+- Android shim has fake and emulator tests.
+- Failure modes are cleanly surfaced through JSON-RPC.
+
+### `v0.4.0-alpha`: iOS UI Alpha
+
+Scope:
+- XCTest/XCUIAutomation shim.
+- Selector-grade iOS tap/type/swipe.
+- Real iOS simulator smoke flow.
+
+Exit gate:
+- iOS selector flow passes repeated runs.
+- Shared scenario semantics work across Android/iOS where possible.
+- Unsupported platform differences are documented.
+
+### `v0.5.0-beta`: Agent Integration Beta
+
+Scope:
+- TypeScript and Python reference clients.
+- Live trace export.
+- Streaming observation mode.
+- Stable protocol fixtures.
+
+Exit gate:
+- External client can run a full scenario over stdio.
+- Protocol compatibility tests gate CI.
+- Trace bundles are inspectable without local code knowledge.
+
+### `v1.0.0`: Stable Local Runner
+
+Scope:
+- Android production support.
+- iOS simulator support with documented limitations.
+- Trace viewer.
+- Release packaging.
+- Security/contribution docs.
+
+Exit gate:
+- Clean install experience.
+- Stable protocol policy.
+- Full release checklist passes.
+- At least two real app pilot flows are documented with repeated-run results.
+
+## Immediate Next Sprint
+
+The next sprint should focus on making the current preview easier to trust and easier to install.
+
+1. [x] Add `zmr doctor`.
+2. [x] Add `zmr validate`.
+3. [x] Add JSON schemas for scenarios and snapshots.
+4. [x] Expand `docs/protocol.md` with exact request/response examples and error codes.
+5. [x] Add release notes/changelog.
+6. [x] Run the Android pilot flows repeatedly and record results in `docs/benchmarking.md`. Android V1 acceptance is 20/20 auth probe and 20/20 login smoke on 2026-04-29.
+
+## Open Decisions
+
+- Should the Android native shim be an APK, instrumentation test APK, or long-running local service?
+- Should the trace viewer be bundled as static files or shipped as a separate package?
+- Should public SDKs live in this repo or separate repos once protocol stabilizes?
+- What exact compatibility promise should `protocolVersion` make before `v1.0.0`?

package/docs/scenario-authoring.md

@@ -0,0 +1,88 @@
+# Scenario Authoring
+
+ZMR scenarios are plain JSON so agents can generate and mutate them without a
+second DSL. Keep scenarios explicit, short, and biased toward stable selectors.
+
+## Selector Strategy
+
+Prefer selectors in this order:
+
+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.
+
+Avoid selecting by text that includes user data, timestamps, counts, prices, or
+network-provided content. If a selector is hard to make stable, add an app-owned
+test id or accessibility identifier instead of widening the selector until it
+matches unrelated nodes.
+
+## Waits And Assertions
+
+Use a wait before actions that depend on navigation, network, or app state:
+
+```json
+{ "action": "waitVisible", "selector": { "id": "email-login-submit-button" }, "timeoutMs": 15000 }
+```
+
+Use assertions for product expectations, not for synchronization that is already
+covered by a wait. Prefer `waitAny` when either of two legitimate states can
+appear, such as an already-authenticated dashboard or a sign-in prompt.
+
+Add `assertHealthy` after launch, deep links, and major navigation steps to
+fail on common mobile crash overlays and development-server error screens that
+can coexist with otherwise valid UI:
+
+```json
+{ "action": "assertHealthy" }
+```
+
+Use `assertNoneVisible` when a flow needs app-specific negative assertions that
+are not part of ZMR's built-in health guard.
+
+## Optional And Recovery Steps
+
+Use `"optional": true` only for dismissals or recovery actions that are not part
+of the required product behavior:
+
+```json
+{ "action": "tap", "selector": { "textContains": "Not now" }, "optional": true }
+```
+
+Optional steps still emit trace events, so failures remain inspectable without
+making the whole flow flaky.
+
+## Importing Existing Flows
+
+Use the importer as a one-time migration helper when evaluating ZMR against an
+existing mobile-flow YAML suite:
+
+```bash
+zmr import flow-yaml flows/login.yaml --out .zmr/login-smoke.json --json
+zmr validate .zmr/login-smoke.json
+```
+
+The importer supports the common subset needed for smoke scenarios:
+`launchApp`, `stopApp`, `clearState`, `tapOn`, `inputText`, `eraseText`,
+`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
+runtime contract for agents and CI.
+
+## Example Templates
+
+The example directory includes templates for common app flows:
+
+- `examples/android-app-auth-probe.json`
+- `examples/android-app-login-smoke.json`
+- `examples/android-app-onboarding.json`
+- `examples/android-app-referral-deep-link.json`
+- `examples/android-app-error-state.json`
+- `examples/ios-dev-client-open-link.json`
+- `examples/ios-dev-client-route-snapshot.json`
+
+Run `zmr validate --json <scenario.json>` before touching a device. Invalid
+scenarios report `fieldPath`, `line`, and `column` when ZMR can identify the
+source location.

package/docs/shipping.md

@@ -0,0 +1,170 @@
+# V1 Dev Preview Shipping Checklist
+
+This checklist defines the current shippable unit. It is intentionally narrower than a general mobile automation product.
+
+For the maintainer-facing GitHub upload and npm publication sequence, see
+[docs/publication.md](publication.md).
+For the artifact-by-artifact proof checklist behind release and benchmark
+claims, see [docs/release-evidence.md](release-evidence.md).
+For the release-candidate command that writes `evidence.jsonl` and
+`summary.md`, see [docs/release-candidate.md](release-candidate.md).
+Use `zmr-release-readiness --evidence <evidence.jsonl> --target dev-preview`
+to verify the generated evidence supports a dev-preview release. Use
+`--target production` or `--target market-claim` only when the corresponding
+real-device pilot and benchmark evidence exists. Pass `--evidence` more than
+once when production evidence lives in a private app repository.
+
+## Included
+
+- Local CLI: `zmr devices`, `zmr run`, `zmr serve`.
+- Local hardening CLI: `zmr doctor`, `zmr init`, `zmr validate`.
+- Local migration CLI: `zmr import flow-yaml <flow.yaml> --out .zmr/<name>.json`.
+- Local failure summary CLI: `zmr explain <trace-dir>`.
+- JSON-RPC over stdio and localhost TCP.
+- Live JSON-RPC trace capture with `zmr serve --trace-dir` and redacted
+  `trace.export` bundles.
+- Live `trace.events` cursor polling for long-running agent sessions.
+- Android ADB/UI Automator adapter.
+- iOS simulator adapter through `xcrun simctl` for lifecycle, deep links,
+  screenshots, logs, and snapshots, with XCTest shim support for hierarchy and
+  selector-grade actions.
+- Fake-device test harness for emulator-free protocol and runner tests.
+- Fake Android/iOS demo shims and `scripts/demo.sh`.
+- Real Android pilot wrapper with redacted trace export: `scripts/run-android-pilot.sh`.
+- Real iOS simulator smoke wrapper with redacted trace export: `scripts/run-ios-pilot.sh`.
+- Generic baseline command benchmark collection:
+  `scripts/benchmark-command.sh` / `zmr-benchmark-command`.
+- Generic candidate-vs-baseline benchmark comparison:
+  `scripts/compare-benchmarks.py` / `zmr-compare-benchmarks`.
+- Local device-matrix runner with `matrix.jsonl` and `summary.json` outputs:
+  `scripts/device-matrix.sh` / `zmr-device-matrix`.
+- Deterministic trace event stream and snapshot artifacts.
+- Static trace viewer with snapshot replay controls, timeline, screenshots,
+  UI tree inspection, selected node details, payloads, and artifact links.
+- Redacted persisted JSON events/snapshots for common text secrets.
+- Release archive script with checksums, SPDX SBOM, third-party notices,
+  generated Homebrew formula, and `RELEASE_MANIFEST.json`.
+- npm package tarball generation with bundled prebuilt binaries.
+- Maintainer macOS signing helper: `scripts/sign-macos-release.sh`.
+- Maintainer macOS notarization helper: `scripts/notarize-macos-release.sh`.
+- npm package wrapper, app initializer, setup wizard, and npm tarball builder.
+- Standalone `zmr init --app` bootstrap for source or release-archive users who
+  need app-local `.zmr/config.json` plus Android/iOS smoke scenarios without npm.
+- TypeScript reference client under `clients/typescript/`.
+- Python reference client under `clients/python/`.
+- Go reference client under `clients/go/`.
+- Rust reference client under `clients/rust/`.
+- npm-exposed Android shim installer for app-local instrumentation source,
+  optional module source copy, optional Gradle `testInstrumentationRunner` and
+  dependency patching, and command setup.
+- npm-exposed iOS shim installer for app-local XCTest source, command setup,
+  and optional Xcode project/workspace UI test target and scheme wiring through
+  `xcodeproj`.
+- iOS workspace project resolution when exactly one workspace project contains
+  the configured `--app-target`, or when `--bundle-id` disambiguates matching
+  app targets.
+- CI workflows for tests, coverage, formatting, script syntax, and release artifacts.
+- Tagged release workflow publishes GitHub artifact attestation for release
+  archives, npm tarballs, and metadata.
+- Public JSON Schemas under `schemas/`.
+- Machine-readable import output contract under `schemas/import-output.schema.json`.
+- Protocol compatibility fixtures under `docs/protocol-fixtures/`.
+- Machine-readable protocol compatibility policy in `runner.capabilities`.
+- App-local `.zmr/config.json` schema and CLI default loading.
+- Internal iOS/Android shim protocol scaffolds under `shims/`.
+- Security, contribution, trace privacy, and protocol versioning docs.
+- Release evidence checklist in `docs/release-evidence.md`.
+- Release candidate evidence gate in `docs/release-candidate.md` and
+  `scripts/release-candidate.sh`.
+- Feature catalog in `FEATURES.md`.
+- Architecture decision records under `docs/adr/`.
+- AI agent integration guide in `docs/ai-agents.md`.
+- Reusable agent skill under `skills/zmr-mobile-testing/`.
+- Changelog and release notes template.
+- Android pilot scenarios:
+  - `examples/android-app-auth-probe.json`
+  - `examples/android-app-login-smoke.json`
+- Scenario authoring templates:
+  - `examples/android-app-onboarding.json`
+  - `examples/android-app-referral-deep-link.json`
+  - `examples/android-app-error-state.json`
+
+## Acceptance Gate
+
+Before tagging a dev-preview release:
+
+```bash
+./scripts/release-gate.sh
+```
+
+Use `./scripts/release-gate.sh --dry-run` to inspect the exact local commands.
+The script includes formatting, script syntax checks, focused shell tests, npm
+package tests, viewer tests, Zig unit tests, fake-tool validation, the
+no-emulator demo, coverage, release archive generation, checksum verification,
+packaged binary smoke, and `npm pack --dry-run`.
+The fake-tool validation uses `zmr doctor --strict` so warning or missing setup
+checks fail the local release gate instead of requiring callers to parse JSON.
+
+For Android and iOS simulator pilot validation, run the app-facing pilot gate
+against a booted Android emulator, a booted iOS simulator, and the built
+simulator `.app`:
+
+```bash
+zmr-pilot-gate --android --ios --android-app-root /path/to/mobile-app --android-app-id com.example.mobiletest --android-device emulator-5554 --ios-app-root /path/to/mobile-app --ios-app-path /path/to/mobile-app/build/Debug-iphonesimulator/Sample.app --ios-app-id com.example.mobiletest --ios-device booted --ios-shim /path/to/mobile-app/.zmr/ios-shim --runs 20 --min-pass-rate 100 --max-failures 0 --evidence-out /path/to/mobile-app/traces/zmr-pilots/evidence.jsonl
+```
+
+For physical iOS pilot validation, use a physical device identifier from
+`zmr devices --json --platform ios --ios-device-type physical` and a signed
+device artifact:
+
+```bash
+zmr-pilot-gate --ios --ios-device-type physical --ios-device <physical-device-id> --ios-app-root /path/to/mobile-app --ios-app-path /path/to/mobile-app/build/Release-iphoneos/Sample.ipa --ios-app-id com.example.mobiletest --ios-shim /path/to/mobile-app/.zmr/ios-shim --runs 20 --min-pass-rate 100 --max-failures 0 --evidence-out /path/to/mobile-app/traces/zmr-pilots/evidence.jsonl
+```
+
+Pass `--zmr-bin /path/to/zmr` when the pilot should use an explicit runner
+binary; the wrapper forwards it to Android, iOS, and physical iOS readiness
+checks.
+
+Add `--evidence-out /path/to/mobile-app/traces/zmr-pilots/evidence.jsonl` to
+write production-readiness rows that can be passed to
+`zmr-release-readiness` alongside the public release-candidate evidence.
+
+Run the pilot gates before publishing reliability or performance claims.
+
+## Not Yet Included
+
+- Automatic iOS workspace resolution when multiple workspace projects contain
+  the same requested app target and bundle id. In that case, callers must pass
+  `--project`.
+- Full physical iOS artifact parity. Physical iOS lifecycle, screenshots, and
+  XCTest shim interaction are supported locally, but physical-device log capture
+  still needs a supported capture channel.
+- Pixel-level screenshot or video masking. Redacted bundles at present replace
+  PNG screenshots with placeholder frames or omit screenshots entirely, and
+  omit screen recordings instead of attempting visual masking.
+- Broad cloud device farm certification. Local matrix validation is included;
+  hosted farm adapters and OS/device matrix certification are not.
+
+## Release Process
+
+1. Run `./scripts/release-gate.sh`.
+2. Run the Android and iOS pilot scenarios if emulator/simulator app builds are available.
+3. If publishing signed macOS archives, run `./scripts/sign-macos-release.sh --identity "<Developer ID Application identity>"` after `./scripts/build-release.sh`.
+4. If publishing notarized macOS archives, run `./scripts/notarize-macos-release.sh --keychain-profile "<notarytool profile>"`, then rerun `./scripts/verify-release-artifacts.sh`.
+5. Create the tag `v0.1.0` for the current package version. Bump
+   `src/version.zig` and `package.json` before using a different tag.
+6. Push the tag; `.github/workflows/release.yml` builds archives, smokes the host-compatible packaged binary, builds `dist/zig-mobile-runner-*.tgz`, publishes GitHub artifact attestation, and uploads checksums, SBOM, third-party notices, `RELEASE_MANIFEST.json`, the npm tarball, and the generated Homebrew formula.
+7. If `NPM_TOKEN` is configured, the release workflow publishes the npm tarball with `npm publish dist/zig-mobile-runner-*.tgz --provenance --access public`. Without that secret, the workflow skips npm publish but still uploads the tarball for manual inspection.
+
+`./scripts/verify-release-artifacts.sh` can also be run directly after
+`./scripts/build-release.sh`. It verifies every `SHA256SUMS` entry, requires the
+release archives plus SBOM/notices/Homebrew formula/manifest to be covered,
+also requires any generated npm tarball to be covered, cross-checks manifest
+sizes and digests, and fails on tampered or missing files before upload.
+
+`./scripts/sign-macos-release.sh --dry-run --identity "<identity>"` lists the
+macOS archives that would be signed without invoking `codesign`.
+
+`./scripts/notarize-macos-release.sh --dry-run --keychain-profile "<profile>"`
+lists the macOS archives that would be packaged and submitted to notarytool
+without invoking `ditto` or `xcrun`.

package/docs/trace-privacy.md

@@ -0,0 +1,88 @@
+# Trace Privacy
+
+ZMR traces are debugging artifacts. They can contain sensitive app state even
+when scenario files are generic.
+
+Raw trace directories may include:
+
+- screenshots
+- screen recordings
+- UI hierarchy XML or JSON
+- visible text and accessibility labels
+- log windows
+- app ids, package/activity names, and timing data
+- action inputs
+
+## Sharing Rules
+
+- Disable unnecessary raw artifacts in `.zmr/config.json`:
+
+  ```json
+  {
+    "schemaVersion": 1,
+    "artifacts": {
+      "screenshots": false,
+      "hierarchy": false,
+      "logs": false
+    },
+    "redaction": {
+      "denylistText": ["customer dob", "internal token"],
+      "denylistResourceIds": ["password-field", "ssn"],
+      "allowlistResourceIds": ["public-token-label"]
+    }
+  }
+  ```
+
+- Add app-specific text and resource-id denylist rules for customer data,
+  regulated identifiers, and internal identifiers that ZMR cannot infer.
+- Share redacted `.zmrtrace` bundles, not raw trace directories.
+- Use `zmr export <trace-dir> --out <bundle.zmrtrace> --redact`.
+- Review redacted bundles before attaching them to public issues.
+- Do not publish raw private app screenshots.
+- Do not publish private app screen recordings.
+- Do not publish logs containing credentials, tokens, emails, or customer data.
+
+## Current Redaction Behavior
+
+Persisted trace JSON scrubs obvious emails, bearer/JWT-like tokens, sensitive
+JSON keys, app-configured denylisted text, and app-configured sensitive
+resource ids. Resource-id denylist matches redact the id and force that node's
+`text` and `contentDesc` to secret placeholders. App-specific allowlists only
+skip app-specific denylist matches; built-in email/token scrubbing still
+applies.
+
+Redacted exports scrub common text secrets, replace PNG screenshots with safe
+placeholder frames, and omit screen recordings. Add `--omit-screenshots` to
+remove screenshot artifacts from the exported bundle entirely. Local trace
+directories are not mutated by export.
+
+Pixel-level screenshot masking is not implemented. Raw hierarchy XML can still
+contain app text; disable hierarchy capture or review redacted bundles before
+sharing them outside a trusted machine.
+
+## Screenshot And XML Strategy
+
+ZMR uses conservative artifact handling instead of partial visual masking:
+
+- Redacted `.zmrtrace` exports replace PNG screenshot files with generated
+  placeholder PNGs at the same artifact paths. This keeps trace replay frames
+  stable without shipping rendered app pixels.
+- `zmr export --redact --omit-screenshots` omits screenshot files entirely for
+  teams that cannot share visual artifacts outside trusted machines.
+- Redacted `.zmrtrace` exports omit screen recording files entirely. This avoids
+  shipping unreliable video masking that could miss rendered secrets.
+- Redacted exports scrub text-based artifacts, including JSON events, snapshot
+  JSON, logs, reports, and XML-like hierarchy files, for common emails, bearer
+  tokens, sensitive key names, and sensitive node attributes.
+- App-specific `.zmr/config.json` redaction rules apply before trace files are
+  written. Use them for private resource ids and business-specific text that
+  generic scrubbing cannot identify.
+- Set `artifacts.hierarchy: false` for apps whose raw accessibility trees are
+  sensitive by default. Selector matching still uses the live tree; this only
+  disables raw hierarchy persistence.
+- Keep unredacted local trace directories on trusted developer machines only.
+
+This strategy favors predictable placeholders, explicit visual omission, and
+app-owned denylist rules over a best-effort screenshot masker. Pixel-level
+masking can be added later as an opt-in exporter mode once it has visual
+verification tests.