zeno-mobile-runner 0.2.16 → 0.2.17

package/CHANGELOG.md

@@ -4,6 +4,39 @@ All notable changes to Zeno Mobile Runner are tracked here.
 
 ## Unreleased
 
+## 0.2.17 (2026-06-29)
+
+### Added
+
+- Added a curl-first `install.sh` for framework-neutral native binary installs,
+  including OS/arch release archive selection, mandatory `SHA256SUMS`
+  verification, dry-run output, and installer coverage in CI/release gates.
+- Added a public metadata guard that fails CI/release gates when public docs,
+  current branch metadata, remote branch metadata, or tag metadata reintroduce
+  unwanted contributor identity strings.
+- Added a support matrix covering Android, iPhone, iPad, tvOS, watchOS, cloud
+  device farms, and the evidence required before making stronger product
+  claims.
+
+### Changed
+
+- Reworked onboarding, agent workflow, app integration, support, readiness,
+  troubleshooting, benchmarking, client, shim, schema, and contribution docs
+  around DX-friendly setup paths, evidence-first product claims, and
+  agent-first mobile verification.
+- Repositioned public onboarding around `curl | sh` plus `zmr init --app`,
+  with npm documented as the JavaScript-team convenience path instead of the
+  default install story.
+- MCP tool schemas now expose strict selector shapes, including `stableId`, so
+  agents can discover supported selector fields directly from tool metadata.
+
+### Fixed
+
+- Scenario parsing and validation now reject unknown root, step, and selector
+  fields instead of silently accepting typos.
+- Selectors now reject empty selector objects and support `stableId` matching as
+  a live-session fallback from semantic snapshots.
+
 ## 0.2.16 (2026-06-25)
 
 ### Fixed

package/CONTRIBUTING.md

@@ -1,12 +1,13 @@
 # Contributing
 
-ZMR is a Zig-based mobile test runner for external agents and local test files.
-Keep changes small, typed, traceable, and covered by tests.
+ZMR is a Zig-based mobile runner for AI agents, app teams, and deterministic
+CI scenarios. Contributions should keep the public surface small, typed,
+traceable, and backed by tests or evidence.
 
 ## Local Checks
 
-Run the focused checks for your change first, then run the release gate before a
-PR:
+Run focused checks for the files you touched first. Before a PR or release
+candidate, run the broader gate:
 
 ```bash
 zig fmt --check build.zig src
@@ -35,8 +36,20 @@ npm pack --dry-run
 
 ## Design Expectations
 
-- Keep the public interface in scenario files, JSON-RPC, and documented CLI
-  flags.
+- Keep public behavior in scenario JSON, JSON-RPC, MCP schemas, and documented
+  CLI flags.
 - Keep platform shims behind adapter boundaries.
-- Preserve ADB/simctl fallback behavior until native shims are proven stable.
+- Preserve ADB, UI Automator, `simctl`, and `devicectl` fallback behavior until
+  native shims have evidence on the target class.
 - Prefer deterministic trace evidence over terminal-only diagnostics.
+- Keep product claims tied to [docs/support-matrix.md](docs/support-matrix.md)
+  and [docs/production-readiness.md](docs/production-readiness.md).
+
+## Documentation Expectations
+
+- Lead onboarding docs with the user outcome, then give copy-paste commands.
+- Keep protocol, schema, ADR, and benchmark docs precise rather than promotional.
+- Use app-owned selectors in examples before `stableId` or coordinate fallback.
+- Mark unsupported or evidence-needed platforms explicitly.
+- Run `bash tests/docs-readiness-test.sh` and
+  `bash tests/public-safety-test.sh` before publishing docs.

package/FEATURES.md

@@ -1,9 +1,10 @@
-# Features
+# Feature Overview
 
-Zeno Mobile Runner is a local, agent-native mobile test runner for Android,
-iOS simulators, and physical iOS devices. It is designed for external agents and normal test files: ZMR
-controls devices, exposes typed observations, executes actions, waits for UI
-state, and writes deterministic traces. It does not embed an LLM.
+Zeno Mobile Runner is a local mobile automation runner for AI agents, app
+teams, and CI systems. It controls Android and iOS/iPadOS targets, exposes typed
+observations and actions, validates JSON scenarios, and writes deterministic
+trace evidence. It does not embed an LLM; external agents stay in charge of
+planning.
 
 ## Platform Support
 
@@ -11,21 +12,26 @@ state, and writes deterministic traces. It does not embed an LLM.
   optional app-local instrumentation shim.
 - Android emulator lifecycle helpers for boot, wait-ready, reset, snapshot
   restore, optional AVD creation, and optional screen recording.
-- iOS simulators through `xcrun simctl` for lifecycle, install, launch, deep
-  links, screenshots, logs, clear-state-by-uninstall, and device discovery.
-- Physical iOS devices through `xcrun devicectl` for discovery, install,
-  launch, deep-link launch, clear-state-by-uninstall, and best-effort stop.
-- iOS selector actions through an app-local XCTest/XCUIAutomation shim on
-  simulators and physical devices.
+- iOS and iPadOS simulators through `xcrun simctl` for lifecycle, install,
+  launch, deep links, screenshots, logs, clear-state-by-uninstall, and device
+  discovery.
+- Physical iPhone and iPad devices through `xcrun devicectl` for discovery,
+  install, launch, deep-link launch, clear-state-by-uninstall, and best-effort
+  stop.
+- iOS/iPadOS selector actions through an app-local XCTest/XCUIAutomation shim
+  on simulators and physical devices.
+- Explicit claim boundaries for iPad, tvOS, watchOS, physical devices, and
+  cloud device farms in [docs/support-matrix.md](docs/support-matrix.md).
 
 ## App Integration
 
-- 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, HTML/JUnit report scripts, and
-  `traces/` gitignore rules.
-- `zmr init --app` provides the same app-local bootstrap for source and archive
-  installs.
+- Curl-first installation of the native `zmr` binary for React Native, Expo,
+  Flutter, native Android, native iOS, and mixed mobile repositories.
+- `zmr init --app` scaffolds `.zmr/config.json`, Android and iOS smoke
+  scenarios, HTML/JUnit report scripts, and `traces/` gitignore rules without
+  requiring Node in the app repo.
+- npm remains a JavaScript-team convenience: `npx zmr-wizard` scaffolds the
+  same app-local state plus optional package scripts and helper bins.
 - `.zmr/config.json` is schema validated, auto-discovered from app checkouts,
   and overridden by explicit CLI flags.
 - Android and iOS shim installers generate app-local commands and source files
@@ -79,8 +85,8 @@ state, and writes deterministic traces. It does not embed an LLM.
 
 ## Scenario Execution
 
-- JSON scenarios with launch, stop, clear state, open link, tap, type, erase
-  text, hide keyboard, swipe, back/home-equivalent navigation, waits,
+- Strict JSON scenarios with launch, stop, clear state, open link, tap, type,
+  erase text, hide keyboard, swipe, back/home-equivalent navigation, waits,
   assertions, snapshots, optional steps, conditionals, repeats, sleeps, and
   scroll-until-visible.
 - Selector matching for text, text contains, content description, resource id,
@@ -142,10 +148,13 @@ state, and writes deterministic traces. It does not embed an LLM.
 
 ## Current Limitations
 
-- Current release status is `0.2.16`, a public developer preview rather than
+- Current release status is `0.2.17`, 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.
+- iPad uses the same iOS/iPadOS automation path, but tablet production claims
+  require separate evidence because layout and size-class behavior can diverge.
+- tvOS and watchOS are not supported in this preview.
 - Broad cloud device farm certification is out of scope for this preview.
 - Public benchmark fixtures are generic. Performance claims for a real app
   should come from equivalent app-local candidate and baseline runs.

package/README.md

@@ -1,19 +1,19 @@
 # Zeno Mobile Runner
 
-> The verification loop for AI coding agents building Expo, React Native,
-> Flutter, and native Android/iOS apps.
+> Mobile UI automation built for AI coding agents, deterministic CI scenarios,
+> and traceable product evidence.
 
 [![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)
 
-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.
+AI agents can edit mobile apps quickly, but they need a reliable way to see the
+screen, act on native UI, and prove the result. Zeno Mobile Runner (ZMR) is that
+control plane: one local binary that installs and launches apps, captures
+semantic UI state, performs typed actions, waits and asserts, and exports a
+replayable trace. ZMR does not embed an LLM. Agents, scripts, and CI systems
+drive it through MCP, JSON-RPC, CLI JSON, or committed JSON scenarios.
 
 ![ZMR trace viewer showing a passed iOS run with timeline, device screenshot, UI tree, and selector payload](docs/assets/viewer-hero.png)
 
@@ -26,24 +26,24 @@ JSON scenarios.
 <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
+## Why This Exists
 
-- **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.
+- **Agents need structured mobile state.** ZMR returns semantic UI trees,
+  stable selectors, screenshots, and typed action results, so an agent can
+  reason from product state instead of guessing from terminal output.
+- **Product claims need evidence.** Every traced session can include events,
+  screenshots, UI hierarchies, timings, assertion results, HTML and JUnit
+  reports, and a redacted bundle for review.
+- **Exploration should become tests.** After a live agent session,
+  `zmr discover` converts trace evidence into reviewable JSON scenarios that
+  replay in CI without an LLM in the loop.
 
-## How it works
+## How It Works
 
 ```mermaid
 flowchart LR
-    A["AI coding agent<br/>Claude Code · Cursor · custom harness"]
-    subgraph zmr["ZMR — one small Zig binary"]
+    A["AI coding agent<br/>AI IDE · Cursor · custom MCP 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>"]
@@ -65,33 +65,37 @@ flowchart LR
     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).
+Android can run with no app instrumentation, with an optional app-local shim for
+faster native actions. iOS and iPadOS selector actions use an app-local
+XCTest/XCUIAutomation shim scaffolded by the wizard. ZMR works below the
+JavaScript and Dart layer, so React Native, Expo, Flutter, and native apps share
+the same runner model. See [docs/frameworks.md](docs/frameworks.md).
 
-## Five-minute start
+## Five-Minute Start
 
-Inside a mobile app repo:
+Run this from the mobile app repository. It installs the native `zmr` binary,
+creates app-local configuration, and verifies the setup before a device run:
 
 ```bash
-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
+curl -fsSL https://raw.githubusercontent.com/johnmikel/zeno-mobile-runner/main/install.sh | sh
+export PATH="$HOME/.local/bin:$PATH"
+zmr init --app --app-id com.example.mobiletest
+zmr doctor --strict --json --config .zmr/config.json
 ```
 
-Hook it up to your coding agent (Claude Code shown; any MCP client works):
+JavaScript teams can keep ZMR versioned inside the app repo and generate npm
+scripts instead:
 
 ```bash
-claude mcp add zmr -- npx zmr mcp --config .zmr/config.json --trace-dir traces/zmr-agent
+npm install --save-dev zeno-mobile-runner
+npx zmr-wizard --app-id com.example.mobiletest --package-json
 ```
 
-Claude Code users can instead install the plugin, which bundles the MCP server
-and a mobile-testing skill:
+Hook it up to any MCP-capable coding agent by pointing the client at the local
+binary:
 
-```text
-/plugin marketplace add johnmikel/zeno-mobile-runner
-/plugin install zmr@zmr-marketplace
+```bash
+zmr mcp --config .zmr/config.json --trace-dir traces/zmr-agent
 ```
 
 Or in an `.mcp.json` / MCP client config:
@@ -100,17 +104,17 @@ Or in an `.mcp.json` / MCP client config:
 {
   "mcpServers": {
     "zmr": {
-      "command": "npx",
-      "args": ["zmr", "mcp", "--config", ".zmr/config.json", "--trace-dir", "traces/zmr-agent"]
+      "command": "zmr",
+      "args": ["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."*
+Then ask the agent to verify its own work: "launch the app, walk through
+onboarding, and show me the trace."
 
-## The agent verification loop
+## Agent Verification Loop
 
 ```mermaid
 sequenceDiagram
@@ -130,7 +134,7 @@ sequenceDiagram
     ZMR-->>Agent: .zmrtrace evidence bundle
 ```
 
-The MCP server exposes the full loop as mobile-native tools:
+The MCP server exposes the loop as mobile-native tools:
 
 | Group | Tools |
 | --- | --- |
@@ -142,16 +146,16 @@ The MCP server exposes the full loop as mobile-native tools:
 | 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
+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
+## 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:
+Scenarios are plain JSON. Agents and build scripts can generate, validate, and
+mutate them without a second DSL, then replay them in CI with no LLM cost:
 
 ```json
 {
@@ -176,8 +180,9 @@ zmr report traces/login-smoke --out traces/login-smoke/report.html --junit trace
 zmr export traces/login-smoke --out login-smoke-redacted.zmrtrace --redact
 ```
 
-Traced `zmr run --json` responses include executable `nextCommands` so agents
-can continue to reporting, explanation, discovery, or export without guessing.
+Traced `zmr run --json` responses include executable `nextCommands`, so agents
+can continue to reporting, explanation, discovery, or export without rebuilding
+paths from text.
 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>`.
 
@@ -186,23 +191,26 @@ 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.
 
-## 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 |
-| iOS physical device | Supported, validate locally | `devicectl` lifecycle plus XCTest shim; pilot on your own app/device before relying on it in CI |
+| iPhone simulator | Supported | `simctl` plus app-local XCTest/XCUIAutomation shim for native selector actions |
+| iPad simulator | Supported, evidence-needed | Same iOS simulator path; validate tablet layouts and size-class branches before production claims |
+| iPhone physical device | Supported, validate locally | `devicectl` lifecycle plus XCTest shim; pilot on your app/device before relying on it in CI |
+| iPad physical device | Supported, evidence-needed | Same iOS/iPadOS physical path; collect separate iPad pilot evidence before claiming production readiness |
+| Apple TV / Apple Watch | Not supported in this preview | Requires separate platform lifecycle, shim, destination, and trace evidence |
 | Cloud device farms | Not included | ZMR focuses on local and self-managed device targets in this preview |
 
 Slow CI hardware can extend the generated iOS shim build timeout with
 `ZMR_IOS_SHIM_BUILD_TIMEOUT_SECONDS`; `ZMR_IOS_SHIM_RESPONSE_TIMEOUT_SECONDS`
 bounds each in-flight request, and `ZMR_IOS_SHIM_TIMEOUT_MS` remains the outer
-process ceiling. Current release: `0.2.16` developer preview.
+process ceiling. Current release: `0.2.17` developer preview.
 Protocol version: `2026-04-28`.
 
-## Optional protocol clients
+## Optional Protocol Clients
 
 TypeScript and Python clients are the common starting points; Go, Rust, Swift,
 and Kotlin reference clients embed the same JSON-RPC protocol from those
@@ -212,15 +220,24 @@ ecosystems. All are thin wrappers around `zmr serve --transport stdio`. See
 
 ## Documentation
 
+**Start here**
+
+- [docs/install.md](docs/install.md): install paths and first setup checks
+- [docs/support-matrix.md](docs/support-matrix.md): platform support, evidence
+  levels, and Apple-platform scope
+- [docs/production-readiness.md](docs/production-readiness.md): release,
+  reliability, privacy, and claim gates
+
 **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
+- [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/install.md](docs/install.md): curl, npm, Homebrew, and app setup
 - [docs/frameworks.md](docs/frameworks.md): React Native, Expo, Flutter, and native app guidance
 - [docs/scenario-authoring.md](docs/scenario-authoring.md): selectors, waits, and scenario design
 - [docs/app-integration.md](docs/app-integration.md): app-side Android/iOS shims
@@ -232,7 +249,6 @@ ecosystems. All are thin wrappers around `zmr serve --transport stdio`. See
 - [FEATURES.md](FEATURES.md): complete feature list and limitations
 - [docs/protocol.md](docs/protocol.md): JSON-RPC methods and schemas
 - [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
 - [docs/benchmarks](docs/benchmarks/README.md): public-safe benchmark evidence
 

package/SECURITY.md

@@ -1,13 +1,15 @@
 # Security Policy
 
 ZMR is a local mobile automation runner. It can collect screenshots, UI trees,
-logs, app ids, device metadata, and scenario inputs. Treat raw traces as
-sensitive.
+logs, app identifiers, device metadata, scenario inputs, and trace events.
+Treat raw traces as sensitive by default, especially when they come from a
+private app or a signed device build.
 
 ## Supported Versions
 
-The current supported line is `0.1.x` dev preview. Security fixes should target
-the latest dev-preview branch until a stable release exists.
+The current supported line is the latest `0.2.x` developer preview. Security
+fixes should target `main` and the latest published preview release until a
+stable release exists.
 
 ## Reporting A Vulnerability
 
@@ -21,14 +23,17 @@ Include:
 - Reproduction steps.
 - Whether the issue exposes screenshots, logs, trace data, credentials, or
   device access.
-- A minimal scenario or redacted trace bundle when possible.
+- A minimal scenario or redacted `.zmrtrace` bundle when possible.
 
 Do not publish raw traces from private apps in public issues.
 
 ## Trace Handling
 
 - Use `zmr export --redact` before sharing trace bundles.
+- Add `--omit-screenshots` when visual artifacts may include personal,
+  customer, or proprietary data.
 - Do not share raw screenshot artifacts from private apps.
 - Do not paste logs that include tokens, emails, API keys, or device identifiers.
+- Keep `.zmr/` app configuration free of secrets; use the app's normal secure
+  configuration path for credentials.
 - Prefer fake-device reproductions for public bug reports.
-

package/clients/README.md

@@ -1,17 +1,18 @@
 # ZMR Language Clients
 
-ZMR clients are small wrappers around the same newline-delimited JSON-RPC
-protocol exposed by:
+ZMR language clients are small host-side wrappers around the same
+newline-delimited JSON-RPC protocol exposed by:
 
 ```bash
 zmr serve --transport stdio --config .zmr/config.json --trace-dir traces/zmr-agent
 ```
 
-They are intended for AI agents, CI harnesses, and app teams that want typed
-or idiomatic calls without reimplementing JSON-RPC framing. TypeScript and
-Python are the most direct starting points for app and agent automation. Go,
-Rust, Swift, and Kotlin stay available as reference integrations for teams that
-want to embed host-side orchestration in those ecosystems.
+They are intended for AI agents, CI harnesses, and app teams that want typed or
+idiomatic calls without reimplementing JSON-RPC framing. The `zmr` binary still
+does the device work. TypeScript and Python are the most direct starting points
+for app and agent automation. Go, Rust, Swift, and Kotlin stay available as
+reference integrations for teams that want host-side orchestration in those
+ecosystems.
 Each client includes `devices()` for `device.list`, including the portable
 `ready` boolean, and a semantic snapshot helper for `observe.semanticSnapshot`
 so agents can work from normalized roles, selectors, bounds, and recommended

package/clients/go/README.md

@@ -1,7 +1,7 @@
 # ZMR Go Client
 
-Small standard-library JSON-RPC client for driving `zmr serve --transport stdio`
-from Go agents and test harnesses.
+Small standard-library JSON-RPC client for Go agents and host-side test
+harnesses that drive `zmr serve --transport stdio`.
 
 ```go
 client, err := zmr.Start(ctx, "zmr", "serve", "--transport", "stdio")

package/clients/kotlin/README.md

@@ -1,6 +1,6 @@
 # ZMR Kotlin Client
 
-Small JVM client for Kotlin agents and test harnesses that drive
+Small JVM client for Kotlin agents and host-side test harnesses that drive
 `zmr serve --transport stdio`.
 
 For now, build it from a local checkout and consume the generated jar:
@@ -27,7 +27,7 @@ gradle -p clients/kotlin runFakeSession \
 ```
 
 ```kotlin
-implementation(files("path/to/zeno-mobile-runner/clients/kotlin/build/libs/zmr-client-0.2.16.jar"))
+implementation(files("path/to/zeno-mobile-runner/clients/kotlin/build/libs/zmr-client-0.2.17.jar"))
 ```
 
 ```kotlin

package/clients/kotlin/build.gradle.kts

@@ -4,7 +4,7 @@ plugins {
 }
 
 group = "dev.zmr"
-version = "0.2.16"
+version = "0.2.17"
 
 kotlin {
     jvmToolchain(17)

package/clients/python/README.md

@@ -1,6 +1,7 @@
 # ZMR Python Reference Client
 
-Standard-library Python client for ZMR's newline-delimited JSON-RPC protocol.
+Standard-library Python client for host-side agents and harnesses using ZMR's
+newline-delimited JSON-RPC protocol.
 
 ```python
 from zmr_client import ZmrClient

package/clients/python/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "zmr-client"
-version = "0.2.16.dev1"
+version = "0.2.17.dev1"
 description = "Python JSON-RPC client for Zeno Mobile Runner."
 requires-python = ">=3.9"
 license = { text = "MIT" }

package/clients/rust/Cargo.lock

@@ -100,7 +100,7 @@ checksum = "b8848ee67ecc8aedbaf3e4122217aff892639231befc6a1b58d29fff4c2cabaa"
 
 [[package]]
 name = "zmr-client"
-version = "0.2.16"
+version = "0.2.17"
 dependencies = [
  "serde",
  "serde_json",

package/clients/rust/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "zmr-client"
-version = "0.2.16"
+version = "0.2.17"
 edition = "2021"
 license = "MIT"
 description = "Rust JSON-RPC client for Zeno Mobile Runner."

package/clients/rust/README.md

@@ -1,7 +1,7 @@
 # ZMR Rust Client
 
-Small synchronous JSON-RPC client for driving `zmr serve --transport stdio`
-from Rust agents and test harnesses.
+Small synchronous JSON-RPC client for Rust agents and host-side test harnesses
+that drive `zmr serve --transport stdio`.
 
 ```rust
 let mut client = zmr_client::Client::start(

package/clients/swift/README.md

@@ -1,7 +1,7 @@
 # ZMR Swift Client
 
-Small Foundation-based client for macOS test harnesses and agents that drive
-`zmr serve --transport stdio`.
+Small Foundation-based client for macOS agents and host-side test harnesses that
+drive `zmr serve --transport stdio`.
 
 Add it to a Swift package. Until this client is published as a standalone Swift
 package, consume it from a local checkout:

package/clients/typescript/README.md

@@ -1,6 +1,7 @@
 # ZMR TypeScript Reference Client
 
-Zero-dependency ESM client for ZMR's newline-delimited JSON-RPC protocol.
+Zero-dependency ESM client for host-side agents and harnesses using ZMR's
+newline-delimited JSON-RPC protocol.
 
 ```js
 import { createZmrClient } from "./index.mjs";

package/clients/typescript/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zmr/client",
-  "version": "0.2.16",
+  "version": "0.2.17",
   "type": "module",
   "main": "index.mjs",
   "types": "index.d.ts",

package/docs/adr/0001-agent-native-runner-boundary.md

@@ -1,4 +1,4 @@
-# 0001: Agent-Native Runner Boundary
+# 0001: Agent-First Runner Boundary
 
 ## Status
 

package/docs/adr/README.md

@@ -1,12 +1,14 @@
 # Architecture Decisions
 
-Accepted architecture decisions for ZMR are recorded here so product docs,
-protocol docs, and implementation choices stay aligned.
+Accepted architecture decisions for ZMR are recorded here so product claims,
+protocol docs, implementation boundaries, and support-matrix wording stay
+aligned.
 
-- [0001: Agent-Native Runner Boundary](0001-agent-native-runner-boundary.md)
+- [0001: Agent-First Runner Boundary](0001-agent-native-runner-boundary.md)
 - [0002: App-Local `.zmr/` Contract](0002-app-local-zmr-contract.md)
 - [0003: iOS XCTest Shim](0003-ios-simulator-xctest-shim.md)
 - [0004: Benchmark Claims And Baseline Collection](0004-benchmark-claims-and-baseline-collection.md)
 
-ADRs describe current decisions, not permanent constraints. A later ADR can
-supersede an earlier decision when the product or support matrix changes.
+ADRs describe current decisions, not permanent constraints. Add a new ADR when
+the product direction, public protocol, or support matrix changes enough to
+supersede an earlier decision.