zeno-mobile-runner 0.1.2 → 0.1.8

package/CHANGELOG.md

@@ -2,7 +2,166 @@
 
 All notable changes to Zeno Mobile Runner are tracked here.
 
-## Unreleased
+## 0.1.8 (2026-06-06)
+
+### Changed
+
+- `zmr-release-readiness --target production` now enforces an
+  `agent workflow smoke` gate, satisfied by the local release gate or
+  structured MCP/JSON-RPC, trace, discovery, validation, and redacted-export
+  evidence.
+
+## 0.1.7 (2026-06-06)
+
+### Added
+
+- Added MCP `assert_visible`, `assert_not_visible`, and `assert_healthy` tools
+  so MCP agents can use assertion-grade checks without dropping to JSON-RPC.
+- Added MCP `erase_text`, `hide_keyboard`, `wait_not_visible`, `wait_any`, and
+  `scroll_until_visible` tools so agents can cover common mobile flow control
+  without dropping to JSON-RPC.
+- Added MCP `install_app`, `launch_app`, `stop_app`, `clear_state`, and
+  `swipe` tools so MCP agents can run full app lifecycle and gesture flows.
+- Added MCP `open_link`, unscoped `type`, and `press_back` trace events so
+  trace-backed discovery sees full simple action sessions from MCP agents.
+- Added MCP `trace_events` cursor metadata so MCP agents get `afterSeq`,
+  `nextSeq`, and `latestSeq` parity with JSON-RPC trace polling.
+- Added JSON-RPC `trace.explain` and MCP `trace_explain` so live agents can
+  get the same failure summary, diagnostics, and next commands as
+  `zmr explain --json` without leaving the session.
+- Added TypeScript, Python, Go, Rust, Swift, and Kotlin trace explanation helpers
+  so reference clients can call JSON-RPC `trace.explain` directly.
+- Added `zmr explore --from-trace <trace-dir> --out <scenario.json> --goal
+  <goal> --include-actions --validate --json` as a review-first CLI
+  exploration handoff for agents. It reuses trace-backed discovery, carries the
+  goal in JSON, and returns explicit guardrails instead of claiming autonomous
+  crawling.
+- Added JSON-RPC `trace.explore` and MCP `trace_explore` so live agents can
+  generate the same goal-carrying, review-required scenario draft without
+  leaving the active traced session.
+- Added TypeScript `exploreTrace()`, Python `explore_trace()`, Go
+  `ExploreTrace()`, Rust `explore_trace()`, Swift `exploreTrace()`, and Kotlin
+  `exploreTrace()` helpers for the new JSON-RPC exploration method.
+- Added trace discovery auditing: `trace.discover` records a `trace.discover` event
+  for JSON-RPC and MCP agent sessions so generated scenario candidates are
+  visible in the trace.
+- Added `zmr draft --from-trace <trace-dir> --out <scenario.json> --json` for
+  trace-backed, review-first scenario drafting. The command reads the latest
+  semantic snapshot artifact and writes a conservative surface-smoke scenario
+  with `launch`, `snapshot`, and stable `assertVisible` checks only.
+- Added `zmr draft --include-actions` so agent sessions can turn supported
+  successful trace actions into reviewable replay drafts while unsupported
+  events are skipped with warnings instead of guessed.
+- Added `zmr discover --from-trace <trace-dir> --out <scenario.json>
+  --include-actions --validate --json` as the first-class trace-to-test handoff
+  for agents. It reuses the review-first draft engine, can validate the
+  generated scenario before returning, and reports `mode: "discover"` for
+  tooling.
+- Added JSON-RPC `trace.discover` and MCP `trace_discover` so live agents can
+  generate the same trace-backed scenario candidate without shelling out to the
+  CLI after a session.
+- Added JSON-RPC `scenario.validate` and MCP `scenario_validate` so agents can
+  validate generated or edited scenario files in-band before running them.
+- Added TypeScript `discoverTrace()` and Python `discover_trace()` helpers for
+  the new JSON-RPC discovery method.
+- Added TypeScript `validateScenario()` and Python `validate_scenario()`
+  helpers for in-band scenario validation.
+- Added Go `DiscoverTrace()` and `ValidateScenario()` helpers so Go agents can
+  use the same trace-to-test and validation loop without raw JSON-RPC calls.
+- Added Rust `discover_trace()` and `validate_scenario()` helpers so Rust
+  agents and host-side harnesses can use the same trace-to-test and validation
+  loop without raw JSON-RPC calls.
+- Added Swift `discoverTrace()` and `validateScenario()` helpers so macOS
+  host-side agents can use the same trace-to-test and validation loop without
+  raw JSON-RPC calls.
+- Added Kotlin `discoverTrace()` and `validateScenario()` helpers plus an
+  always-run source parity test so Kotlin host-side agents keep the same
+  trace-to-test and validation entry points even on machines without Gradle.
+- Added a trace-backed discovery handoff to traced `zmr run --json`
+  `nextCommands`, so agents can generate a reviewable replay scenario directly
+  from a run summary.
+- Added `zmr run --discover-out <scenario.json> --json` so traced runs can
+  write and validate the reviewable replay scenario before returning the run
+  summary.
+- Added replay coverage metadata to `zmr draft --json`, `zmr discover --json`,
+  and embedded run discovery output so agents can see how many trace actions
+  became replay steps and how many were skipped.
+- Added coordinate-complete `ui.swipe` trace replay so JSON-RPC sessions and
+  traced `zmr run` flows can carry swipes into generated replay scenarios
+  without guessing missing coordinates.
+- Added traced `pressBack` replay parity for `zmr run`, so generated replay
+  scenarios preserve back-navigation steps from ordinary scenario runs.
+- Added direction and timeout preserving `scrollUntilVisible` trace replay so
+  generated scenarios keep the original scroll intent from traced runs and
+  live agent sessions.
+- Added selector and timeout preserving wait replay so trace-backed discovery
+  keeps successful `waitVisible`, `waitNotVisible`, and matched `waitAny`
+  steps from ordinary scenario runs.
+- Added timeout context to native selector wait trace events and timeout
+  diagnostics, so real-device shim traces carry the same timing evidence as
+  snapshot-backed waits.
+- Added replay metadata for successful `assertNoneVisible` and timed
+  `assertHealthy` trace events, so generated replay scenarios preserve
+  assertion intent instead of dropping those checks.
+- Added selector and timeout preserving `assertVisible` and `assertNotVisible`
+  replay so trace-backed discovery keeps assertion intent distinct from waits.
+- Added `zmr report --junit <report.xml>` so trace directories and benchmark
+  result directories can produce CI-friendly JUnit XML alongside HTML reports.
+- Updated generated app report and reliability scripts to write `junit.xml`
+  beside `report.html` by default.
+- Updated Android and iOS pilot wrappers to emit `junit.xml` beside every
+  generated `report.html`.
+- Updated CI and tagged release workflows to retain generated run evidence as
+  GitHub Actions artifacts: CI keeps traces, coverage output, and the built
+  `zmr` binary for 14 days, while releases keep the generated `dist/` bundle
+  for 30 days.
+- Updated artifact upload workflow steps to a Node 24-compatible
+  `actions/upload-artifact` major so CI stays ahead of GitHub Actions runtime
+  deprecations.
+- Added `schemas/draft-output.schema.json` and included it in `zmr schemas
+  --json`.
+- Added `schemas/discover-output.schema.json` and included it in `zmr schemas
+  --json`.
+
+## 0.1.6 (2026-06-05)
+
+### Added
+
+- Added `zmr inspect --json` as a read-only app and agent handoff command. It
+  reports app-local config status, `.zmr/AGENTS.md` presence, configured
+  Android/iOS smoke scenarios, safe next commands, and explicit claim limits
+  without launching devices or writing tests.
+- Added `schemas/inspect-output.schema.json` and included it in `zmr schemas
+  --json` for generated clients and agent tooling.
+
+### Changed
+
+- Tagged release workflow now uses npm trusted publishing instead of a
+  long-lived `NPM_TOKEN` secret.
+- Fixed the tagged release publish step so npm receives the generated local
+  tarball instead of interpreting the path as a GitHub package spec.
+- Updated the tagged release workflow to Node 24 so npm trusted publishing can
+  use the GitHub Actions OIDC identity with a current npm CLI.
+- Added a public production-readiness checklist that ties release, framework,
+  reliability, trace privacy, and agent workflow claims to concrete evidence.
+
+## 0.1.3 (2026-06-03)
+
+### Fixed
+
+- Hardened the iOS XCTest shim for clean Expo/RN prebuilds by giving cold
+  `build-for-testing` runs a 90-minute default timeout with explicit progress
+  logging.
+- Made iOS simulator `app.stop` idempotent when `simctl terminate` reports the
+  app is already stopped.
+- Improved selector actions so native `selector.not_found` and
+  `selector.not_hittable` responses return a typed unavailable result instead
+  of failing the command parser.
+- Reused a resolved booted simulator UDID across `build-for-testing` and
+  `test-without-building`, and cleared stale shim PID/server/destination state
+  when reinstalling the app-local shim.
+- Avoided stale XCTest snapshot elements and replaced broad selector scans with
+  native predicate-based fallback queries.
 
 ## 0.1.2 (2026-05-28)
 
@@ -311,8 +470,8 @@ All notable changes to Zeno Mobile Runner are tracked here.
 - Tagged release workflow now publishes GitHub artifact attestation for release
   archives and metadata.
 - Tagged release workflow now builds the npm tarball, attests it, uploads it
-  with the release assets, and publishes with npm provenance when `NPM_TOKEN`
-  is configured.
+  with the release assets, and can publish with npm provenance from supported
+  CI.
 - Release manifests and checksum verification now include generated npm
   tarballs when present.
 - Native selector wait timeouts now capture one final snapshot when possible,

package/FEATURES.md

@@ -22,7 +22,8 @@ state, and writes deterministic traces. It does not embed an LLM.
 
 - npm-first installation with `zeno-mobile-runner` as a dev dependency.
 - `npx zmr-wizard` scaffolds `.zmr/config.json`, Android and iOS smoke
-  scenarios, optional app package scripts, and `traces/` gitignore rules.
+  scenarios, optional app package scripts, HTML/JUnit report scripts, and
+  `traces/` gitignore rules.
 - `zmr init --app` provides the same app-local bootstrap for source and archive
   installs.
 - `.zmr/config.json` is schema validated, auto-discovered from app checkouts,
@@ -34,14 +35,44 @@ state, and writes deterministic traces. It does not embed an LLM.
 
 - JSON-RPC v1 over newline-delimited stdio or localhost TCP.
 - MCP stdio server with mobile-native tools for AI agents, including semantic
-  snapshots, selector actions, waits, trace polling, and trace export.
+  snapshots, selector actions, waits, assertions, trace polling, trace
+  exploration, trace discovery, and trace export.
 - `runner.capabilities`, `device.list`, `session.create`,
   `observe.snapshot`, `observe.semanticSnapshot`, UI actions, waits,
-  assertions, live trace events, and redacted trace export.
+  assertions, scenario validation, live trace events, trace-backed exploration,
+  trace-backed discovery, and redacted trace export.
 - TypeScript, Python, Go, Rust, Swift, and Kotlin reference clients.
 - Machine-readable CLI output for `zmr version --json`, `zmr schemas --json`,
-  `zmr doctor --json`, `zmr devices --json`, `zmr validate --json`,
+  `zmr inspect --json`, `zmr doctor --json`, `zmr devices --json`,
+  `zmr discover --json`, `zmr draft --json`, `zmr validate --json`,
   `zmr run --json`, and `zmr explain --json`.
+- Traced `zmr run --json` output includes executable follow-up commands for
+  reports, failure explanation, trace-backed scenario discovery, and redacted
+  export.
+- `zmr run --discover-out <scenario.json> --json` can generate and validate a
+  reviewable replay scenario from the trace immediately after the run.
+- `zmr explore --from-trace --goal ... --json` gives CLI agents a
+  goal-carrying, review-first exploration handoff with explicit guardrails,
+  replay coverage, validation, and deterministic next commands.
+- JSON-RPC `trace.explore` and MCP `trace_explore` expose the same
+  goal-carrying, review-required trace exploration from active traced sessions.
+- `zmr discover --from-trace` turns a traced agent session into a reviewable
+  scenario candidate and can validate the generated scenario before returning.
+- `zmr draft --from-trace` turns a traced semantic snapshot into a reviewable
+  surface-smoke scenario with conservative `assertVisible` checks.
+- `zmr draft --include-actions` can turn supported successful trace actions
+  into a replay draft while warning instead of guessing unsupported events.
+  Wait replay preserves selectors and timeouts when the trace records them.
+  Native selector wait traces include timeout context for successful waits and
+  timeout diagnostics.
+  Assertion replay preserves `assertVisible` and `assertNotVisible` selectors
+  and timeouts, `assertNoneVisible` selector arrays, and `assertHealthy`
+  timeouts when the trace records them.
+  Selector scroll replay preserves direction and timeout when the trace records
+  them.
+- Draft and discover JSON include `replay` coverage metadata so agents can
+  compare trace action events considered for replay, generated replay steps,
+  and skipped events.
 - Public JSON Schemas for scenarios, snapshots, semantic snapshots, action
   results, trace events, protocol messages, setup diagnostics, and release
   manifests.
@@ -58,6 +89,8 @@ state, and writes deterministic traces. It does not embed an LLM.
 - Wait and retry behavior around transient observation failures.
 - Import helper for a documented subset of common mobile-flow YAML commands
   into native `.zmr/*.json` scenarios.
+- Trace-backed draft helper for generating reviewable surface and replay
+  scenarios from observed UI state and successful supported trace actions.
 
 ## Traces And Diagnostics
 
@@ -68,6 +101,10 @@ state, and writes deterministic traces. It does not embed an LLM.
   selected node details, payloads, artifact links, and snapshot replay
   controls.
 - `zmr explain` summarizes failed traces for humans and agents.
+- `zmr report --junit <report.xml>` writes CI-friendly JUnit XML for trace
+  directories and benchmark result directories.
+- Android and iOS pilot wrappers emit `junit.xml` next to generated HTML
+  reports, so CI can collect the same artifacts used by app-local scripts.
 - Redacted `.zmrtrace` export can replace or omit screenshots, omit screen
   recordings, and redact common secrets plus app-configured denylist fields.
 
@@ -75,6 +112,8 @@ state, and writes deterministic traces. It does not embed an LLM.
 
 - `zmr-benchmark` repeats ZMR scenarios with pass-rate, failure-count, and p95
   duration gates.
+- Benchmark directories can be rendered as both HTML and JUnit XML artifacts
+  with `zmr report`.
 - `zmr-benchmark-command` records normalized rows for app-local baseline
   commands without hardcoding another tool.
 - `zmr-compare-benchmarks` compares candidate and baseline rows into generic
@@ -89,17 +128,21 @@ state, and writes deterministic traces. It does not embed an LLM.
 - Release archive builder with checksums, SPDX SBOM, third-party notices,
   generated Homebrew formula, and `RELEASE_MANIFEST.json`.
 - npm package tarball generation with bundled prebuilt binaries.
-- `zmr-release-readiness` checks repeated app/device evidence for teams that
-  want a machine-readable readiness summary.
+- `zmr-release-readiness` checks repeated app/device evidence and the
+  agent workflow smoke for teams that want a machine-readable readiness
+  summary.
 - Tagged release workflow with artifact attestation and optional npm
   provenance publishing.
+- CI workflow retains run traces, coverage output, and built runner artifacts
+  for 14 days; tagged release workflow retains the generated `dist/` bundle
+  for 30 days.
 - Security, contribution, trace privacy, troubleshooting, protocol versioning,
   app integration, benchmarking, and npm packaging docs.
 - Reusable agent skill under `skills/zmr-mobile-testing/`.
 
 ## Current Limitations
 
-- Current release status is `0.1.2`, a public developer preview rather than
+- Current release status is `0.1.8`, a public developer preview rather than
   a production-stable `1.0.0`.
 - Physical iOS log capture is still simulator-first. Physical iOS screenshots
   are available when the XCTest/XCUIAutomation shim is configured.

package/README.md

@@ -53,10 +53,10 @@ See [docs/frameworks.md](docs/frameworks.md) and
 ## Why ZMR
 
 - **Agent-native protocol:** structured snapshots, semantic mobile trees,
-  actions, waits, assertions, live trace events, and redacted trace export over
-  JSON-RPC or MCP.
+  actions, waits, assertions, live trace events, trace explanation, and
+  redacted trace export over JSON-RPC or MCP.
 - **Trace-first debugging:** every run can produce screenshots, UI trees, logs,
-  timings, action inputs, assertion results, and an HTML report.
+  timings, action inputs, assertion results, and HTML/JUnit reports.
 - **Fast local core:** Zig owns orchestration, subprocess control, selectors,
   waits, retries, scenario execution, and packaged binaries.
 - **App-local setup:** `.zmr/config.json`, smoke scenarios, shim commands, and
@@ -93,14 +93,35 @@ Useful commands:
 zmr version --json
 zmr schemas --json
 zmr devices --json
+zmr inspect --json
+zmr explore --from-trace traces/zmr-agent --out .zmr/discovered/login-smoke.json --goal "find a stable login smoke" --include-actions --validate --json
+zmr discover --from-trace traces/zmr-agent --out .zmr/discovered/replay-smoke.json --include-actions --validate --json
+zmr draft --from-trace traces/zmr-agent --out .zmr/discovered/surface-smoke.json --json
+zmr draft --from-trace traces/zmr-agent --out .zmr/discovered/replay-smoke.json --include-actions --json
 zmr init --app --json --dir . --app-id com.example.mobiletest
 zmr validate --json .zmr/login-smoke.json
 zmr run .zmr/login-smoke.json --json --trace-dir traces/login-smoke
+zmr run .zmr/login-smoke.json --json --trace-dir traces/login-smoke --discover-out .zmr/discovered/login-smoke.json
 zmr explain --json traces/login-smoke
+zmr report traces/login-smoke --out traces/login-smoke/report.html --junit traces/login-smoke/junit.xml
 zmr import flow-yaml .zmr/legacy-flow.yaml --out .zmr/legacy-flow.json
 zmr export traces/login-smoke --out traces/login-smoke-redacted.zmrtrace --redact
 ```
 
+For traced runs, `zmr run --json` returns executable `nextCommands` for
+HTML and JUnit reporting, failure explanation, `zmr discover --from-trace`,
+and redacted export so agents can continue from a run summary without guessing
+the next handoff. The generated report handoff writes `report.html` and
+`junit.xml` beside the trace for CI artifact collection.
+
+When an agent should produce the reviewable scenario in the same command, add
+`--discover-out .zmr/discovered/<name>.json`. ZMR still treats the generated
+file as review-first: it writes from trace evidence, validates the file, and
+returns the embedded `discovery` result without crawling or committing tests.
+The `discovery.replay` object shows how many trace action events were
+considered for replay, how many became scenario steps, and how many were
+skipped.
+
 See [docs/scenario-authoring.md](docs/scenario-authoring.md) for selector and
 wait guidance.
 
@@ -108,6 +129,93 @@ wait guidance.
 
 Agents can use the CLI, JSON-RPC, or MCP surface. Start JSON-RPC over stdio:
 
+```bash
+zmr inspect --json --dir .
+```
+
+`zmr inspect --json` gives agents a read-only handoff for the app checkout:
+config status, generated agent instructions, configured platform scenarios, and
+recommended next commands. It does not launch devices or write tests.
+
+After a live session has produced trace artifacts, agents can ask ZMR to turn
+the trace into a validated, reviewable scenario candidate. `zmr explore` is
+the agent-facing handoff: it records the goal, writes from existing trace
+evidence, validates the candidate, and returns guardrails that make the limits
+machine-readable:
+
+```bash
+zmr explore --from-trace traces/zmr-agent \
+  --out .zmr/discovered/login-smoke.json \
+  --goal "find a stable login smoke" \
+  --include-actions \
+  --validate \
+  --json
+```
+
+`zmr explore` is not an autonomous crawler. It does not launch devices, invent
+missing actions, discover credentials, or commit tests. Its JSON includes
+`autonomous:false`, `reviewRequired:true`, `guardrails`, and the same replay
+coverage and validation fields as `zmr discover`.
+
+When an agent wants the lower-level trace-to-test primitive directly, use
+`zmr discover`:
+
+```bash
+zmr discover --from-trace traces/zmr-agent \
+  --out .zmr/discovered/replay-smoke.json \
+  --include-actions \
+  --validate \
+  --json
+```
+
+`zmr discover` is offline and review-first. It writes a scenario from stable
+trace evidence, optionally validates it immediately, and returns next commands
+for deterministic reruns. It does not crawl the app, discover credentials, or
+commit tests. Its JSON includes `replay` coverage metadata so agents can report
+which trace action events became replay steps and which were skipped.
+
+For CLI-driven agent loops, `zmr run --json --trace-dir traces/zmr-agent
+--discover-out .zmr/discovered/replay-smoke.json` performs the same
+trace-backed discovery after the run and embeds the discover result in the run
+JSON response.
+
+For the lower-level draft primitive, agents can still ask ZMR to write a
+conservative surface-smoke scenario from the latest snapshot:
+
+```bash
+zmr draft --from-trace traces/zmr-agent \
+  --out .zmr/discovered/surface-smoke.json \
+  --json
+zmr validate --json .zmr/discovered/surface-smoke.json
+```
+
+`zmr draft` writes `launch`, `snapshot`, and `assertVisible` steps from stable
+visible selectors. It does not tap controls or type into fields unless
+`--include-actions` is explicitly requested.
+
+When the trace was produced by an agent or JSON-RPC/MCP session that took typed
+actions, add `--include-actions` to replay successful supported actions before
+the final snapshot assertions:
+
+```bash
+zmr draft --from-trace traces/zmr-agent \
+  --out .zmr/discovered/replay-smoke.json \
+  --include-actions \
+  --json
+zmr validate --json .zmr/discovered/replay-smoke.json
+```
+
+Replay drafts only use trace events with enough stable data to reproduce them,
+such as launch, deep links, selector taps, selector text entry,
+selector/timeout-preserving waits, back, keyboard hiding, coordinate-complete
+swipes, direction/timeout-preserving selector scrolls, `assertNoneVisible`
+selector arrays, selector/timeout-preserving `assertVisible` and
+`assertNotVisible`, and timed `assertHealthy` checks.
+Native selector wait traces include timeout context for successful waits and
+timeout diagnostics.
+Unsupported or underspecified events are skipped with warnings instead of guessed.
+Text entry events whose text was redacted from the trace are also skipped.
+
 ```bash
 zmr serve --transport stdio --config .zmr/config.json --trace-dir traces/zmr-agent
 ```
@@ -118,8 +226,20 @@ Agents that support the Model Context Protocol can use the native MCP surface:
 zmr mcp --config .zmr/config.json --trace-dir traces/zmr-agent
 ```
 
-The MCP server exposes mobile-specific tools such as `semantic_snapshot`, `tap`,
-`type`, `wait_visible`, `trace_events`, and `trace_export`.
+The MCP server exposes mobile-specific tools such as `semantic_snapshot`,
+`install_app`, `launch_app`, `stop_app`, `clear_state`, `tap`, `type`,
+`erase_text`, `hide_keyboard`, `swipe`, `press_back`, `open_link`,
+`wait_visible`, `wait_not_visible`, `wait_any`, `scroll_until_visible`,
+`assert_visible`, `assert_not_visible`, `assert_healthy`, `scenario_validate`,
+`trace_events`, `trace_explain`, `trace_explore`, `trace_discover`, and
+`trace_export`.
+
+For agent-led discovery and test authoring, see
+[docs/agent-discovery.md](docs/agent-discovery.md). ZMR supports that loop
+through MCP, JSON-RPC, trace events, in-band trace discovery, offline surface
+drafts, replay drafts, live and offline guarded trace exploration, and traced
+run `nextCommands` today. Built-in exploration is review-first and
+trace-backed, not an unbounded autonomous crawler.
 
 ## Optional Protocol Clients
 
@@ -129,7 +249,10 @@ same JSON-RPC protocol.
 
 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.
+for teams that want to embed the protocol from those ecosystems. Go and Rust
+also 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 |
 | --- | --- | --- |
@@ -153,7 +276,7 @@ and [docs/client-installation.md](docs/client-installation.md).
 | iOS physical device | Supported, validate locally | `devicectl` lifecycle plus app-local XCTest/XCUIAutomation shim; run pilots on your own app/device before relying on it in CI |
 | Cloud device farms | Not included | ZMR is focused on local and self-managed device targets in this preview |
 
-Current release: `0.1.2` developer preview. Protocol version:
+Current release: `0.1.8` developer preview. Protocol version:
 `2026-04-28`.
 
 ## Documentation
@@ -161,8 +284,11 @@ Current release: `0.1.2` developer preview. Protocol version:
 - [FEATURES.md](FEATURES.md): complete feature list and limitations
 - [docs/install.md](docs/install.md): source, npm, Homebrew, and app setup
 - [docs/frameworks.md](docs/frameworks.md): React Native, Expo, Flutter, and native app guidance
+- [docs/expo-smoke.md](docs/expo-smoke.md): reproducible Expo and iOS smoke test
+- [docs/production-readiness.md](docs/production-readiness.md): release, reliability, framework, and agent-readiness gates
 - [docs/app-integration.md](docs/app-integration.md): app-side Android/iOS shims
 - [docs/scenario-authoring.md](docs/scenario-authoring.md): selectors, waits, and scenario design
+- [docs/agent-discovery.md](docs/agent-discovery.md): agent-led discovery and scenario authoring loop
 - [docs/protocol.md](docs/protocol.md): JSON-RPC methods and schemas
 - [docs/ai-agents.md](docs/ai-agents.md): JSON-RPC and MCP agent workflows
 - [docs/clients.md](docs/clients.md): language client guide

package/build.zig.zon

@@ -1,7 +1,7 @@
 .{
-    .name = .zig_mobile_runner,
-    .version = "0.0.1",
+    .name = .zeno_mobile_runner,
+    .version = "0.1.7",
     .minimum_zig_version = "0.15.2",
     .paths = .{""},
-    .fingerprint = 0x5a9670ea13a33fab,
+    .fingerprint = 0xcc2c8187874868fc,
 }

package/clients/README.md

@@ -19,9 +19,12 @@ actions instead of raw platform hierarchy classes.
 The TypeScript and Python clients expose the broadest app-facing control
 surface: session lifecycle, app launch/stop/link/state, snapshot and semantic
 snapshot, tap/type/erase/hide-keyboard/swipe/back/scroll, waits, assertions,
-trace event polling, and trace export. The Go, Rust, Swift, and Kotlin clients
-show the same protocol shape in other host languages and are useful starting
-points for custom integration work.
+scenario validation, trace event polling, trace explanation, trace discovery,
+trace exploration, and trace export.
+The Go and Rust clients also include typed scenario validation and trace
+explanation/exploration/discovery helpers. Swift and Kotlin include lightweight
+trace explanation, validation, exploration, and discovery helpers for
+host-side agents in those ecosystems.
 Use the `assertHealthy`/`assert_healthy` helper after launches, links, and major
 navigation steps to catch native crash overlays and development-client failures
 without hand-maintaining negative selectors in every client.
@@ -45,6 +48,7 @@ const zmr = createZmrClient({
   command: "zmr",
   args: ["serve", "--transport", "stdio", "--config", ".zmr/config.json"],
 });
+const explored = await zmr.exploreTrace(".zmr/discovered/agent-goal.json", "find a stable login smoke", { includeActions: true, validate: true, force: true });
 ```
 
 ## Python
@@ -64,6 +68,8 @@ from zmr_client import ZmrClient
 
 with ZmrClient("zmr", ["serve", "--transport", "stdio", "--config", ".zmr/config.json"]) as zmr:
     snapshot = zmr.snapshot()
+    explanation = zmr.explain_trace()
+    explored = zmr.explore_trace(".zmr/discovered/agent-goal.json", "find a stable login smoke", include_actions=True, validate=True, force=True)
 ```
 
 ## Go
@@ -83,6 +89,10 @@ go run ./clients/go/examples/fake-session \
 
 ```go
 client, err := zmr.Start(ctx, "zmr", "serve", "--transport", "stdio", "--config", ".zmr/config.json")
+discovered, err := client.DiscoverTrace(ctx, ".zmr/discovered/go-agent.json", zmr.TraceDiscoverOptions{IncludeActions: true, Validate: true, Force: true})
+explored, err := client.ExploreTrace(ctx, ".zmr/discovered/go-goal.json", "find a stable login smoke", zmr.TraceDiscoverOptions{IncludeActions: true, Validate: true, Force: true})
+validation, err := client.ValidateScenario(ctx, discovered.Out)
+explanation, err := client.ExplainTrace(ctx)
 ```
 
 ## Rust
@@ -111,6 +121,20 @@ cargo run --manifest-path clients/rust/Cargo.toml --example fake_session -- \
 ```rust
 let mut client = zmr_client::Client::start("zmr", ["serve", "--transport", "stdio", "--config", ".zmr/config.json"])?;
 let snapshot = client.snapshot()?;
+let discovered = client.discover_trace(".zmr/discovered/rust-agent.json", zmr_client::TraceDiscoverOptions {
+    include_actions: true,
+    validate: true,
+    force: true,
+    ..Default::default()
+})?;
+let explored = client.explore_trace(".zmr/discovered/rust-goal.json", "find a stable login smoke", zmr_client::TraceDiscoverOptions {
+    include_actions: true,
+    validate: true,
+    force: true,
+    ..Default::default()
+})?;
+let validation = client.validate_scenario(&discovered.out)?;
+let explanation = client.explain_trace()?;
 ```
 
 ## Swift
@@ -128,6 +152,24 @@ git submodule add https://github.com/johnmikel/zeno-mobile-runner.git vendor/zen
 .package(path: "vendor/zeno-mobile-runner/clients/swift")
 ```
 
+```swift
+let client = ZMRClient(arguments: ["serve", "--transport", "stdio", "--config", ".zmr/config.json"])
+try client.start()
+let out = ".zmr/discovered/swift-agent.json"
+let discovered = try client.discoverTrace(
+    out: out,
+    options: TraceDiscoverOptions(includeActions: true, validate: true, force: true)
+)
+let explored = try client.exploreTrace(
+    out: ".zmr/discovered/swift-goal.json",
+    goal: "find a stable login smoke",
+    options: TraceDiscoverOptions(includeActions: true, validate: true, force: true)
+)
+let validation = try client.validateScenario(path: out)
+let explanation = try client.explainTrace()
+client.close()
+```
+
 Swift is useful for macOS host-side automation next to iOS app code. It is not
 an SDK embedded in the app under test.
 
@@ -140,6 +182,21 @@ git submodule add https://github.com/johnmikel/zeno-mobile-runner.git vendor/zen
 gradle -p vendor/zeno-mobile-runner/clients/kotlin build
 ```
 
+```kotlin
+val out = ".zmr/discovered/kotlin-agent.json"
+val discovered = client.discoverTrace(
+    out,
+    TraceDiscoverOptions(includeActions = true, validate = true, force = true)
+)
+val explored = client.exploreTrace(
+    ".zmr/discovered/kotlin-goal.json",
+    "find a stable login smoke",
+    TraceDiscoverOptions(includeActions = true, validate = true, force = true)
+)
+val validation = client.validateScenario(out)
+val explanation = client.explainTrace()
+```
+
 Kotlin is useful for Android teams that want host-side orchestration in Kotlin.
 It still drives the external `zmr` binary.
 

package/clients/go/README.md

@@ -12,6 +12,18 @@ defer client.Close()
 
 snapshot, err := client.Snapshot(ctx)
 healthy, err := client.AssertHealthy(ctx, 1000)
+explanation, err := client.ExplainTrace(ctx)
+discovered, err := client.DiscoverTrace(ctx, ".zmr/discovered/go-agent.json", zmr.TraceDiscoverOptions{
+    IncludeActions: true,
+    Validate: true,
+    Force: true,
+})
+explored, err := client.ExploreTrace(ctx, ".zmr/discovered/go-goal.json", "find a stable login smoke", zmr.TraceDiscoverOptions{
+    IncludeActions: true,
+    Validate: true,
+    Force: true,
+})
+validation, err := client.ValidateScenario(ctx, discovered.Out)
 ```
 
 Run the fake-session example from the repository root: