zeno-mobile-runner 0.1.3 → 0.2.0

package/README.md

@@ -1,182 +1,230 @@
 # Zeno Mobile Runner
 
-> Agent-native mobile UI automation for React Native, Expo, Flutter, and native Android/iOS apps.
+> The verification loop for AI coding agents building Expo, React Native,
+> Flutter, and native Android/iOS apps.
 
 [![CI](https://github.com/johnmikel/zeno-mobile-runner/actions/workflows/ci.yml/badge.svg)](https://github.com/johnmikel/zeno-mobile-runner/actions/workflows/ci.yml)
 [![Release](https://img.shields.io/github/v/release/johnmikel/zeno-mobile-runner?include_prereleases)](https://github.com/johnmikel/zeno-mobile-runner/releases)
 [![npm](https://img.shields.io/npm/v/zeno-mobile-runner)](https://www.npmjs.com/package/zeno-mobile-runner)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-ZMR gives AI agents and test harnesses a typed mobile control plane. It can
-install and launch apps, observe the UI, choose an action, wait for the screen to
-settle, assert state, and export a replayable trace. The runner does not embed an
-LLM. Agents stay outside and use ZMR through CLI JSON, scenarios, JSON-RPC, MCP,
-or optional protocol clients.
+Your coding agent can write mobile code, but it cannot see the phone. ZMR is
+its eyes and hands: a typed mobile control plane that installs and launches
+apps, observes the UI, taps and types, waits for the screen to settle, asserts
+state, and exports a replayable trace as proof. The runner does not embed an
+LLM. Agents stay outside and drive ZMR through MCP, JSON-RPC, CLI JSON, or
+JSON scenarios.
+
+![ZMR trace viewer showing a passed iOS run with timeline, device screenshot, UI tree, and selector payload](docs/assets/viewer-hero.png)
+
+<p align="center">
+  <img src="docs/assets/device-ios-demo.png" width="260" alt="iOS simulator screenshot captured by ZMR during a scenario run" />
+  &nbsp;&nbsp;
+  <img src="docs/assets/device-android-demo.png" width="260" alt="Android emulator screenshot captured by ZMR during a scenario run" />
+</p>
+
+<p align="center"><em>Real on-device screenshots from ZMR traces: the same demo flow
+driven on an iOS simulator and an Android emulator.</em></p>
+
+## Why agents need this
+
+- **Agents can't verify what they can't observe.** ZMR returns semantic UI
+  trees with stable selectors, screenshots, and typed action results an agent
+  can reason about — not raw pixels it has to guess at.
+- **Evidence, not vibes.** Every session can write a deterministic trace:
+  events, screenshots, UI hierarchies, timings, assertion results, HTML and
+  JUnit reports, and a redacted shareable bundle.
+- **Tests fall out for free.** After a live agent session, `zmr discover`
+  turns the trace into a reviewable JSON scenario that replays in CI without
+  an LLM in the loop.
+
+## How it works
+
+```mermaid
+flowchart LR
+    A["AI coding agent<br/>Claude Code · Cursor · custom harness"]
+    subgraph zmr["ZMR — one small Zig binary"]
+        MCP["MCP server<br/><code>zmr mcp</code>"]
+        RPC["JSON-RPC stdio/TCP<br/><code>zmr serve</code>"]
+        CLI["CLI + JSON scenarios<br/><code>zmr run</code>"]
+        CORE["Core engine<br/>selectors · waits · assertions<br/>scenario runner · trace writer"]
+        MCP --> CORE
+        RPC --> CORE
+        CLI --> CORE
+    end
+    subgraph devices["Devices"]
+        AND["Android emulator/device<br/>ADB · UI Automator · optional shim"]
+        IOS["iOS simulator/device<br/>simctl · devicectl · XCTest shim"]
+    end
+    TRACE["Trace<br/>events.jsonl · screenshots · UI trees<br/>report.html · junit.xml · .zmrtrace"]
+    A -- "MCP tools" --> MCP
+    A -- "JSON-RPC" --> RPC
+    A -- "CLI JSON" --> CLI
+    CORE --> AND
+    CORE --> IOS
+    CORE --> TRACE
+```
+
+No app instrumentation is required on Android. iOS selector actions use an
+app-local XCTest shim that the wizard scaffolds. ZMR works below the
+JavaScript/Dart layer, so React Native, Expo, Flutter, and fully native apps
+are all driven the same way. See [docs/frameworks.md](docs/frameworks.md).
 
-## Install
+## Five-minute start
 
 Inside a mobile app repo:
 
 ```bash
-npm install --save-dev zeno-mobile-runner
+npm install --save-dev zeno-mobile-runner   # bun add --dev zeno-mobile-runner
 npx zmr-wizard --app-id com.example.mobiletest --package-json
 npx zmr doctor --strict --json --config .zmr/config.json
 ```
 
-Run a generated smoke scenario:
+Hook it up to your coding agent (Claude Code shown; any MCP client works):
 
 ```bash
-npm run zmr:validate
-npm run zmr:android
-npm run zmr:ios
+claude mcp add zmr -- npx zmr mcp --config .zmr/config.json --trace-dir traces/zmr-agent
 ```
 
-## React Native, Expo, and Flutter
-
-ZMR works below the JavaScript or Dart framework layer. It drives the installed
-Android or iOS app through platform lifecycle commands, deep links, accessibility
-semantics, screenshots, logs, selector actions, waits, assertions, and traces.
-
-- **React Native:** prefer `testID`, `accessibilityLabel`, stable text, and deep
-  links for direct navigation into important states.
-- **Expo development builds:** pass `--expo-dev-client-scheme <scheme>` to the
-  wizard so ZMR scaffolds dev-client open-link scenarios.
-- **Flutter:** ZMR supports Flutter apps at the Android and iOS app level when
-  the app exposes stable semantics labels, text, deep links, or native ids. It is
-  not a Flutter widget-tree driver and does not inspect Flutter internals.
-- **Native Android/iOS:** use resource ids, content descriptions, accessibility
-  identifiers, XCTest labels, and app-owned deep links.
-
-See [docs/frameworks.md](docs/frameworks.md) and
-[docs/app-integration.md](docs/app-integration.md) for app-side setup guidance.
-
-## 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.
-- **Trace-first debugging:** every run can produce screenshots, UI trees, logs,
-  timings, action inputs, assertion results, and an HTML report.
-- **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
-  traces live in the app repo.
-- **Android and iOS:** Android uses ADB/UI Automator plus an optional native
-  shim. iOS simulators use `simctl`; physical iOS devices use `devicectl`;
-  selector-grade iOS automation uses the XCTest/XCUIAutomation shim.
-
-## Scenario Example
-
-ZMR scenarios are JSON so agents and build scripts can generate, validate, and
-mutate them without a second DSL.
+Or in an `.mcp.json` / MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "zmr": {
+      "command": "npx",
+      "args": ["zmr", "mcp", "--config", ".zmr/config.json", "--trace-dir", "traces/zmr-agent"]
+    }
+  }
+}
+```
+
+Then ask the agent to verify its own work: *"launch the app, walk through
+onboarding, and show me the trace."*
+
+## The agent verification loop
+
+```mermaid
+sequenceDiagram
+    participant Agent as AI agent
+    participant ZMR
+    participant Device as Emulator / simulator
+    Agent->>ZMR: semantic_snapshot
+    ZMR->>Device: capture UI + screenshot
+    ZMR-->>Agent: roles, stable selectors, bounds
+    Agent->>ZMR: tap / type / swipe / open_link
+    ZMR->>Device: execute + settle
+    Agent->>ZMR: wait_visible / assert_visible
+    ZMR-->>Agent: typed result + trace events
+    Agent->>ZMR: trace_discover
+    ZMR-->>Agent: reviewable replay scenario
+    Agent->>ZMR: trace_export --redact
+    ZMR-->>Agent: .zmrtrace evidence bundle
+```
+
+The MCP server exposes the full loop as mobile-native tools:
+
+| Group | Tools |
+| --- | --- |
+| Observe | `snapshot`, `semantic_snapshot` |
+| App lifecycle | `install_app`, `launch_app`, `stop_app`, `clear_state`, `open_link` |
+| Act | `tap`, `type`, `erase_text`, `hide_keyboard`, `swipe`, `press_back` |
+| Wait | `wait_visible`, `wait_not_visible`, `wait_any`, `scroll_until_visible` |
+| Assert | `assert_visible`, `assert_not_visible`, `assert_healthy` |
+| Evidence | `trace_events`, `trace_explain`, `trace_discover`, `trace_explore`, `trace_export`, `scenario_validate` |
+
+The same surface is available over JSON-RPC for harnesses that embed ZMR
+directly — see [docs/protocol.md](docs/protocol.md) and
+[docs/ai-agents.md](docs/ai-agents.md). When a run fails, `zmr explain`
+diagnoses the trace for humans and agents alike:
+
+![Terminal session showing a failed run, zmr explain diagnosing the failure with visible texts, and the fixed run passing](docs/assets/cli-run-explain.png)
+
+## Deterministic scenarios for CI
+
+Scenarios are plain JSON — agents and build scripts generate, validate, and
+mutate them without a second DSL, and they replay in CI with no LLM cost:
 
 ```json
 {
   "name": "Login smoke",
   "appId": "com.example.mobiletest",
   "steps": [
+    { "action": "clearState" },
     { "action": "launch" },
     { "action": "assertHealthy", "timeoutMs": 5000 },
     { "action": "tap", "selector": { "resourceId": "email" } },
     { "action": "typeText", "text": "user@example.com" },
-    { "action": "tap", "selector": { "resourceId": "password" } },
-    { "action": "typeText", "text": "password" },
     { "action": "tap", "selector": { "text": "Login" } },
     { "action": "waitVisible", "selector": { "text": "Welcome" }, "timeoutMs": 30000 }
   ]
 }
 ```
 
-Useful commands:
-
 ```bash
-zmr version --json
-zmr schemas --json
-zmr devices --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 explain --json traces/login-smoke
-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
-```
-
-See [docs/scenario-authoring.md](docs/scenario-authoring.md) for selector and
-wait guidance.
-
-## Agent Workflow
-
-Agents can use the CLI, JSON-RPC, or MCP surface. Start JSON-RPC over stdio:
-
-```bash
-zmr serve --transport stdio --config .zmr/config.json --trace-dir traces/zmr-agent
+zmr report traces/login-smoke --out traces/login-smoke/report.html --junit traces/login-smoke/junit.xml
+zmr export traces/login-smoke --out login-smoke-redacted.zmrtrace --redact
 ```
 
-Agents that support the Model Context Protocol can use the native MCP surface:
-
-```bash
-zmr mcp --config .zmr/config.json --trace-dir traces/zmr-agent
-```
+Traced `zmr run --json` responses include executable `nextCommands` so agents
+can continue to reporting, explanation, discovery, or export without guessing.
+Open any exported bundle in the static [trace viewer](viewer/index.html) — or
+serve it and link straight to it with `viewer/index.html?bundle=<url>`.
 
-The MCP server exposes mobile-specific tools such as `semantic_snapshot`, `tap`,
-`type`, `wait_visible`, `trace_events`, and `trace_export`.
+For repeat-run reliability gates, p95 duration thresholds, baseline
+comparisons against your current E2E tool, and multi-device matrices, see
+[docs/benchmarking.md](docs/benchmarking.md) and the public
+[Benchmark Lab](docs/benchmarks/README.md) evidence.
 
-For agent-led discovery and test authoring, see
-[docs/agent-discovery.md](docs/agent-discovery.md). ZMR supports that loop
-through MCP and JSON-RPC today; a built-in autonomous crawler is not shipped in
-this preview.
-
-## Optional Protocol Clients
-
-Clients are thin wrappers around `zmr serve --transport stdio`. They do not
-replace the runner; they make it easier for agents and test code to call the
-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.
-
-| Language | Entry point | Example |
-| --- | --- | --- |
-| TypeScript | `clients/typescript/index.mjs` + `index.d.ts` | `node clients/typescript/examples/fake-session.mjs` |
-| Python | `clients/python/zmr_client.py` + `pyproject.toml` | `python3 clients/python/examples/fake_session.py` |
-| Go | `clients/go/zmr/client.go` | `go run ./clients/go/examples/fake-session` |
-| Rust | `clients/rust/src/lib.rs` | `cargo run --manifest-path clients/rust/Cargo.toml --example fake_session` |
-| Swift | `clients/swift/Sources/ZMRClient` | `swift build --package-path clients/swift` |
-| Kotlin | `clients/kotlin/src/main/kotlin/dev/zmr` | `gradle -p clients/kotlin build` |
-
-See [clients/README.md](clients/README.md), [docs/clients.md](docs/clients.md),
-and [docs/client-installation.md](docs/client-installation.md).
-
-## Platform Support
+## Platform support
 
 | Target | Status | Notes |
 | --- | --- | --- |
 | Android emulator | Supported | ADB/UI Automator, optional Android shim, emulator lifecycle helpers |
 | Android physical device | Supported | Requires ADB connection and app build/install surface |
-| iOS simulator | Supported | `simctl` plus app-local XCTest/XCUIAutomation shim for native selector actions, native waits, and bounded snapshots |
-| 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 |
+| iOS simulator | Supported | `simctl` plus app-local XCTest/XCUIAutomation shim for native selector actions |
+| iOS physical device | Supported, validate locally | `devicectl` lifecycle plus XCTest shim; pilot on your own app/device before relying on it in CI |
+| Cloud device farms | Not included | ZMR focuses on local and self-managed device targets in this preview |
+
+Slow CI hardware can extend the iOS shim cold-build timeout with
+`ZMR_IOS_SHIM_TIMEOUT_MS`. Current release: `0.2.0` developer preview.
+Protocol version: `2026-04-28`.
+
+## Optional protocol clients
 
-Current release: `0.1.3` developer preview. Protocol version:
-`2026-04-28`.
+TypeScript and Python clients are the common starting points; Go, Rust, Swift,
+and Kotlin reference clients embed the same JSON-RPC protocol from those
+ecosystems. All are thin wrappers around `zmr serve --transport stdio`. See
+[docs/clients.md](docs/clients.md) and
+[docs/client-installation.md](docs/client-installation.md).
 
 ## Documentation
 
-- [FEATURES.md](FEATURES.md): complete feature list and limitations
+**For agents**
+
+- [docs/ai-agents.md](docs/ai-agents.md): JSON-RPC and MCP agent workflows
+- [docs/agent-discovery.md](docs/agent-discovery.md): agent-led discovery, `zmr explore`/`discover`/`draft`, and the trace-to-test loop
+- [skills/zmr-mobile-testing/SKILL.md](skills/zmr-mobile-testing/SKILL.md): reusable agent skill
+
+**For test authors**
+
 - [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/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/app-integration.md](docs/app-integration.md): app-side Android/iOS shims
+- [docs/expo-smoke.md](docs/expo-smoke.md): reproducible Expo and iOS smoke test
+- [docs/benchmarking.md](docs/benchmarking.md): repeat-run gates, reports, device matrix, baselines
+
+**Reference**
+
+- [FEATURES.md](FEATURES.md): complete feature list and limitations
 - [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
-- [docs/client-installation.md](docs/client-installation.md): npm, Homebrew, TS, Python, Go, Rust, Swift, and Kotlin setup
 - [docs/trace-privacy.md](docs/trace-privacy.md): safe trace export
+- [docs/production-readiness.md](docs/production-readiness.md): release, reliability, and agent-readiness gates
 - [docs/troubleshooting.md](docs/troubleshooting.md): common setup and runtime issues
-- [skills/zmr-mobile-testing/SKILL.md](skills/zmr-mobile-testing/SKILL.md): reusable agent skill
+- [docs/benchmarks](docs/benchmarks/README.md): public-safe benchmark evidence
 
 ## License
 

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:

package/clients/go/zmr/client.go

@@ -134,6 +134,39 @@ type TraceEvents struct {
 	Events    []map[string]interface{} `json:"events"`
 }
 
+type TraceDiagnostic struct {
+	Kind               string   `json:"kind"`
+	Status             string   `json:"status,omitempty"`
+	SnapshotID         string   `json:"snapshotId,omitempty"`
+	ArtifactStatus     string   `json:"artifactStatus,omitempty"`
+	SemanticStatus     string   `json:"semanticStatus,omitempty"`
+	Error              string   `json:"error,omitempty"`
+	ScreenshotArtifact string   `json:"screenshotArtifact,omitempty"`
+	Source             string   `json:"source,omitempty"`
+	ActivePackage      string   `json:"activePackage,omitempty"`
+	ActiveActivity     string   `json:"activeActivity,omitempty"`
+	VisibleTexts       []string `json:"visibleTexts,omitempty"`
+	NearestTextMatches []string `json:"nearestTextMatches,omitempty"`
+}
+
+type TraceExplain struct {
+	OK                  bool             `json:"ok"`
+	TraceDir            string           `json:"traceDir"`
+	Scenario            string           `json:"scenario"`
+	Status              string           `json:"status"`
+	AppID               string           `json:"appId,omitempty"`
+	DurationMS          int64            `json:"durationMs,omitempty"`
+	EventCount          int64            `json:"eventCount,omitempty"`
+	SnapshotCount       int64            `json:"snapshotCount,omitempty"`
+	PartialFailureCount int64            `json:"partialFailureCount,omitempty"`
+	FailedStepIndex     int64            `json:"failedStepIndex,omitempty"`
+	Error               string           `json:"error,omitempty"`
+	Diagnostic          *TraceDiagnostic `json:"diagnostic,omitempty"`
+	PartialFailure      *TraceDiagnostic `json:"partialFailure,omitempty"`
+	LastEvent           string           `json:"lastEvent,omitempty"`
+	NextCommands        []string         `json:"nextCommands"`
+}
+
 type TraceExport struct {
 	TraceDir        string `json:"traceDir"`
 	Out             string `json:"out"`
@@ -141,6 +174,59 @@ type TraceExport struct {
 	OmitScreenshots bool   `json:"omitScreenshots"`
 }
 
+type ValidationResult struct {
+	OK           bool     `json:"ok"`
+	Path         string   `json:"path"`
+	Name         string   `json:"name,omitempty"`
+	AppID        string   `json:"appId,omitempty"`
+	StepCount    int      `json:"stepCount,omitempty"`
+	ErrorCode    string   `json:"errorCode,omitempty"`
+	Message      string   `json:"message,omitempty"`
+	FieldPath    string   `json:"fieldPath,omitempty"`
+	Line         int      `json:"line,omitempty"`
+	Column       int      `json:"column,omitempty"`
+	NextCommands []string `json:"nextCommands,omitempty"`
+}
+
+type ReplaySummary struct {
+	Enabled           bool `json:"enabled"`
+	EventCount        int  `json:"eventCount"`
+	StepCount         int  `json:"stepCount"`
+	SkippedEventCount int  `json:"skippedEventCount"`
+}
+
+type TraceDiscoverOptions struct {
+	IncludeActions bool
+	Validate       bool
+	Force          bool
+	Name           string
+	AppID          string
+}
+
+type TraceDiscover struct {
+	OK              bool              `json:"ok"`
+	Mode            string            `json:"mode"`
+	SchemaVersion   int               `json:"schemaVersion"`
+	RunnerVersion   string            `json:"runnerVersion"`
+	ProtocolVersion string            `json:"protocolVersion"`
+	Out             string            `json:"out"`
+	TraceDir        string            `json:"traceDir"`
+	SourceSnapshot  string            `json:"sourceSnapshot"`
+	Name            string            `json:"name"`
+	AppID           string            `json:"appId,omitempty"`
+	SelectorCount   int               `json:"selectorCount"`
+	StepCount       int               `json:"stepCount"`
+	Replay          ReplaySummary     `json:"replay"`
+	Warnings        []string          `json:"warnings"`
+	Validated       bool              `json:"validated"`
+	Validation      *ValidationResult `json:"validation"`
+	NextCommands    []string          `json:"nextCommands"`
+	Goal            string            `json:"goal,omitempty"`
+	Autonomous      bool              `json:"autonomous,omitempty"`
+	ReviewRequired  bool              `json:"reviewRequired,omitempty"`
+	Guardrails      []string          `json:"guardrails,omitempty"`
+}
+
 func Start(ctx context.Context, command string, args ...string) (*Client, error) {
 	cmd := exec.CommandContext(ctx, command, args...)
 	stdin, err := cmd.StdinPipe()
@@ -415,6 +501,12 @@ func (c *Client) AssertHealthy(ctx context.Context, timeoutMS int64) (bool, erro
 	return out, err
 }
 
+func (c *Client) ValidateScenario(ctx context.Context, path string) (ValidationResult, error) {
+	var out ValidationResult
+	err := c.Request(ctx, "scenario.validate", map[string]interface{}{"path": path}, &out)
+	return out, err
+}
+
 func (c *Client) ExportTrace(ctx context.Context, outPath string, redact bool, omitScreenshots bool) (TraceExport, error) {
 	var out TraceExport
 	err := c.Request(ctx, "trace.export", map[string]interface{}{"out": outPath, "redact": redact, "omitScreenshots": omitScreenshots}, &out)
@@ -430,3 +522,53 @@ func (c *Client) TraceEvents(ctx context.Context, afterSeq int64, limit int64) (
 	err := c.Request(ctx, "trace.events", params, &out)
 	return out, err
 }
+
+func (c *Client) ExplainTrace(ctx context.Context) (TraceExplain, error) {
+	var out TraceExplain
+	err := c.Request(ctx, "trace.explain", map[string]interface{}{}, &out)
+	return out, err
+}
+
+func (c *Client) DiscoverTrace(ctx context.Context, outPath string, options TraceDiscoverOptions) (TraceDiscover, error) {
+	var out TraceDiscover
+	params := map[string]interface{}{"out": outPath}
+	if options.IncludeActions {
+		params["includeActions"] = true
+	}
+	if options.Validate {
+		params["validate"] = true
+	}
+	if options.Force {
+		params["force"] = true
+	}
+	if options.Name != "" {
+		params["name"] = options.Name
+	}
+	if options.AppID != "" {
+		params["appId"] = options.AppID
+	}
+	err := c.Request(ctx, "trace.discover", params, &out)
+	return out, err
+}
+
+func (c *Client) ExploreTrace(ctx context.Context, outPath string, goal string, options TraceDiscoverOptions) (TraceDiscover, error) {
+	var out TraceDiscover
+	params := map[string]interface{}{"out": outPath, "goal": goal}
+	if options.IncludeActions {
+		params["includeActions"] = true
+	}
+	if options.Validate {
+		params["validate"] = true
+	}
+	if options.Force {
+		params["force"] = true
+	}
+	if options.Name != "" {
+		params["name"] = options.Name
+	}
+	if options.AppID != "" {
+		params["appId"] = options.AppID
+	}
+	err := c.Request(ctx, "trace.explore", params, &out)
+	return out, err
+}