zig-mobile-runner 0.1.0

package/docs/benchmarking.md

@@ -0,0 +1,275 @@
+# Benchmarking
+
+ZMR benchmark output is intentionally simple: each run appends one JSON object to `results.jsonl`, and `zmr report` turns that directory into a local HTML report.
+
+## Single Tool Benchmark
+
+```bash
+scripts/benchmark.sh \
+  --zmr examples/android-app-login-smoke.json \
+  --device emulator-5554 \
+  --runs 10 \
+  --trace-root traces/zmr-login \
+  --results traces/bench-comparison/results.jsonl \
+  --replace \
+  --min-pass-rate 100 \
+  --max-failures 0 \
+  --max-p95-ms 30000
+```
+
+The command writes trace artifacts under `--trace-root` and appends normalized
+rows to `--results`. Omit `--results` to use `<trace-root>/results.jsonl`.
+Omitting `--trace-root` writes under `traces/` in the current app directory,
+not inside the installed ZMR package.
+Use `--replace` when starting a fresh shared comparison file.
+When any gate option is present, `scripts/benchmark_gate.py` reads
+`results.jsonl` and exits non-zero if pass rate, failure count, mean duration,
+or p95 duration misses the configured threshold.
+
+Generate a report:
+
+```bash
+zmr report traces/bench-<timestamp> --out traces/bench-<timestamp>/report.html
+```
+
+## Pilot Wrapper
+
+The configurable Android pilot script can run both sample scenarios repeatedly:
+
+```bash
+./scripts/run-android-pilot.sh \
+  --app-root /path/to/mobile-app \
+  --device emulator-5554 \
+  --runs 20 \
+  --min-pass-rate 100 \
+  --max-failures 0 \
+  --max-p95-ms 30000
+```
+
+For lower variance, restore a clean emulator snapshot at the start of the pilot.
+Use `--screen-record` when investigating visual flakes:
+
+```bash
+./scripts/run-android-pilot.sh \
+  --app-root /path/to/mobile-app \
+  --device emulator-5554 \
+  --avd Small_Phone \
+  --reset-emulator \
+  --restore-snapshot zmr-clean \
+  --screen-record \
+  --runs 20 \
+  --min-pass-rate 100 \
+  --max-failures 0
+```
+
+For `--runs 1`, the script exports normal and redacted `.zmrtrace` bundles. For `--runs > 1`, it writes benchmark directories and HTML reports.
+
+The iOS pilot wrapper supports the same repeated-run gates:
+
+```bash
+./scripts/run-ios-pilot.sh \
+  --app-root /path/to/mobile-app \
+  --app-path /path/to/mobile-app/build/Debug-iphonesimulator/Sample.app \
+  --device booted \
+  --ios-shim /path/to/mobile-app/.zmr/ios-shim \
+  --runs 20 \
+  --min-pass-rate 100 \
+  --max-failures 0 \
+  --max-p95-ms 45000
+```
+
+For a paired physical iOS device, pass the target type, a concrete device
+identifier from `zmr devices`, and a signed device artifact:
+
+```bash
+./scripts/run-ios-pilot.sh \
+  --app-root /path/to/mobile-app \
+  --app-path /path/to/mobile-app/build/Release-iphoneos/Sample.ipa \
+  --ios-device-type physical \
+  --device <physical-device-id> \
+  --ios-shim /path/to/mobile-app/.zmr/ios-shim \
+  --runs 20 \
+  --min-pass-rate 100 \
+  --max-failures 0 \
+  --max-p95-ms 45000
+```
+
+When `--ios-shim` is set, the iOS pilot prewarms the app-local XCTest shim with
+an `appState` command before timing scenarios. That moves cold
+`xcodebuild build-for-testing` work out of the measured run and fails early when
+the UI test target is miswired. Use `--skip-shim-prewarm` only when measuring
+first-command cold-start behavior.
+
+For release validation on a machine that has both platform builds and targets
+ready, `zmr-pilot-gate` runs the Android and iOS pilot wrappers with one
+external gate command:
+
+```bash
+zmr-pilot-gate \
+  --android --ios \
+  --android-app-root /path/to/mobile-app \
+  --ios-app-root /path/to/mobile-app --ios-app-path /path/to/mobile-app/build/Debug-iphonesimulator/Sample.app \
+  --ios-device-type simulator \
+  --ios-shim /path/to/mobile-app/.zmr/ios-shim \
+  --runs 20 \
+  --min-pass-rate 100 \
+  --max-failures 0
+```
+
+## Reading Results
+
+Benchmark reports include:
+
+- pass rate
+- failure count
+- mean duration
+- p95 duration
+- per-run status
+- terminal trace status
+- failed step index and error when available
+- links to each run's `events.jsonl`
+
+Before making public performance claims, run the same scenario repeatedly on a clean emulator image and include the raw `results.jsonl` plus the redacted trace bundle for any failure.
+
+## Compare Against A Baseline
+
+Use `zmr-compare-benchmarks` when a private app repo has benchmark rows from
+ZMR and another local runner. The public ZMR repo keeps this generic: rows are
+grouped by the `tool` field and no external runner is hardcoded.
+
+Collect ZMR rows into the shared comparison file first:
+
+```bash
+zmr-benchmark \
+  --zmr .zmr/android-smoke.json \
+  --platform android \
+  --device emulator-5554 \
+  --app-id com.example.mobiletest \
+  --app-build <build-id-or-artifact> \
+  --runs 20 \
+  --trace-root traces/zmr-login \
+  --results traces/bench-comparison/results.jsonl \
+  --replace \
+  --min-pass-rate 100 \
+  --max-failures 0
+```
+
+Then collect rows from an existing command-line runner by wrapping it with
+`zmr-benchmark-command`. This keeps benchmark collection tool-agnostic while
+still capturing per-run stdout/stderr logs and appending to the same results
+file:
+
+```bash
+zmr-benchmark-command \
+  --tool baseline \
+  --platform android \
+  --device emulator-5554 \
+  --app-id com.example.mobiletest \
+  --scenario .zmr/android-smoke.json \
+  --app-build <build-id-or-artifact> \
+  --runs 20 \
+  --trace-root traces/baseline-login \
+  --results traces/bench-comparison/results.jsonl \
+  -- baseline-runner test .baseline/login.yaml
+```
+
+For another runner or command, only change `--tool` and the command after
+`--`:
+
+```bash
+zmr-benchmark-command \
+  --tool runner-b \
+  --platform ios \
+  --device booted \
+  --app-id com.example.mobiletest \
+  --scenario .zmr/ios-smoke.json \
+  --app-build <build-id-or-artifact> \
+  --runs 20 \
+  --trace-root traces/runner-b-login \
+  --results traces/bench-comparison/results.jsonl \
+  -- npm run e2e:ios
+```
+
+```bash
+zmr-compare-benchmarks \
+  --results traces/bench-comparison/results.jsonl \
+  --candidate zmr \
+  --baseline baseline \
+  --min-candidate-pass-rate 100 \
+  --max-candidate-failures 0 \
+  --min-mean-speedup 1.25 \
+  --min-p95-speedup 1.25 \
+  --format markdown \
+  --out traces/bench-comparison/comparison.md \
+  --evidence-out traces/bench-comparison/evidence.jsonl
+```
+
+The report includes pass rate, failure count, mean duration, p95 duration, mean
+speedup, p95 speedup, candidate/baseline run counts, and whether the rows have
+the same benchmark context. The optional gates make CI fail when ZMR is not
+reliable enough or not faster than the baseline by the required margin. Only
+compare runs collected on the same host, device state, app build, and scenario.
+`--evidence-out` requires `--min-candidate-pass-rate`,
+`--max-candidate-failures`, `--min-mean-speedup`, and `--min-p95-speedup`, so
+market-claim evidence records explicit reliability and speedup thresholds. When
+`--evidence-out` is set, a successful comparison also requires at least 20 candidate rows,
+at least 20 baseline rows, and matching `platform`, `device`,
+`appId`, `scenario`, and `appBuild` metadata across candidate and baseline
+rows, then appends a `competitive benchmark comparison` row that
+`zmr-release-readiness --target market-claim` can consume directly.
+
+## Device Matrix
+
+Use `zmr-device-matrix` when CI needs to run one or more scenarios across
+multiple local emulators, simulators, or attached devices:
+
+```bash
+zmr-device-matrix \
+  --matrix .zmr/device-matrix.json \
+  --trace-root traces/zmr-matrix \
+  --min-pass-rate 100 \
+  --max-failures 0
+```
+
+Example matrix:
+
+```json
+{
+  "runs": 2,
+  "appId": "com.example.mobiletest",
+  "devices": [
+    {
+      "name": "android-api-35",
+      "platform": "android",
+      "serial": "emulator-5554",
+      "scenario": ".zmr/android-smoke.json",
+      "adb": "adb",
+      "androidShim": ".zmr/android-shim"
+    },
+    {
+      "name": "ios-18",
+      "platform": "ios",
+      "iosDeviceType": "simulator",
+      "serial": "booted",
+      "scenario": ".zmr/ios-smoke.json",
+      "xcrun": "xcrun",
+      "iosShim": ".zmr/ios-shim"
+    },
+    {
+      "name": "ios-physical",
+      "platform": "ios",
+      "iosDeviceType": "physical",
+      "serial": "<physical-device-id>",
+      "scenario": ".zmr/ios-smoke.json",
+      "xcrun": "xcrun",
+      "iosShim": ".zmr/ios-shim"
+    }
+  ]
+}
+```
+
+The command writes `matrix.jsonl` and `summary.json` under the trace root.
+Each device/run pair has a normal trace directory, so failures can be inspected
+with `zmr explain`, `zmr report`, or the trace viewer.
+For iOS rows, omit `iosDeviceType` for the default simulator path or set it to
+`physical` to pass `--ios-device-type physical` through to `zmr run`.

package/docs/client-installation.md

@@ -0,0 +1,141 @@
+# Client Installation
+
+ZMR has two layers:
+
+1. The `zmr` binary controls devices, runs scenarios, serves JSON-RPC, and writes traces.
+2. Language clients are optional wrappers around `zmr serve --transport stdio`.
+
+For fastest adoption, install the binary once with npm, a release tarball, or
+Homebrew. Then use a language client only when you want tests or agents written
+in that language.
+
+## Binary First
+
+Today, install the GitHub release tarball:
+
+```bash
+npm install --save-dev https://github.com/johnmikel/zig-mobile-runner/releases/download/v0.1.0/zig-mobile-runner-0.1.0.tgz
+npx zmr version
+```
+
+After the npm registry package is published:
+
+```bash
+npm install --save-dev zig-mobile-runner
+npx zmr-wizard --app-id com.example.mobiletest --package-json
+```
+
+Homebrew is the best install path for non-JavaScript teams because it gives any
+language the same `zmr` executable:
+
+```bash
+# Today, after downloading or building a release archive:
+brew install --build-from-source ./dist/homebrew/zmr.rb
+
+# Intended tap install after the tap is published:
+brew tap johnmikel/zmr
+brew install zmr
+```
+
+## TypeScript
+
+```bash
+npm install --save-dev zig-mobile-runner
+```
+
+```js
+import { createZmrClient } from "zig-mobile-runner/clients/typescript/index.mjs";
+
+const zmr = createZmrClient({
+  command: "zmr",
+  args: ["serve", "--transport", "stdio", "--config", ".zmr/config.json"],
+});
+```
+
+## Python
+
+```bash
+python3 -m pip install "git+https://github.com/johnmikel/zig-mobile-runner.git#subdirectory=clients/python"
+```
+
+```python
+from zmr_client import ZmrClient
+
+with ZmrClient("zmr", ["serve", "--transport", "stdio", "--config", ".zmr/config.json"]) as zmr:
+    zmr.create_session()
+    snapshot = zmr.snapshot()
+```
+
+## Go
+
+```bash
+go get github.com/johnmikel/zig-mobile-runner/clients/go@main
+```
+
+```go
+client, err := zmr.Start(ctx, "zmr", "serve", "--transport", "stdio", "--config", ".zmr/config.json")
+```
+
+## Rust
+
+Until the Rust client is published as its own crate, add the repository as a
+vendor checkout or submodule and depend on the client package by path:
+
+```bash
+git submodule add https://github.com/johnmikel/zig-mobile-runner.git vendor/zig-mobile-runner
+```
+
+```toml
+[dependencies]
+zmr-client = { path = "vendor/zig-mobile-runner/clients/rust" }
+```
+
+```rust
+let mut client = zmr_client::Client::start("zmr", ["serve", "--transport", "stdio"])?;
+```
+
+## Swift
+
+Until the Swift client is split into a standalone SwiftPM repository or package
+registry entry, add the repository as a vendor checkout or submodule and use a
+local SwiftPM package path:
+
+```bash
+git submodule add https://github.com/johnmikel/zig-mobile-runner.git vendor/zig-mobile-runner
+```
+
+```swift
+.package(path: "vendor/zig-mobile-runner/clients/swift")
+```
+
+The Swift client is for macOS agent/test tools. It is not embedded in the iOS
+app under test.
+
+## Kotlin
+
+Use the Kotlin client as source or build a local jar:
+
+```bash
+git submodule add https://github.com/johnmikel/zig-mobile-runner.git vendor/zig-mobile-runner
+gradle -p vendor/zig-mobile-runner/clients/kotlin build
+```
+
+```kotlin
+val zmr = ZmrClient(listOf("zmr", "serve", "--transport", "stdio", "--config", ".zmr/config.json"))
+```
+
+The Kotlin client is useful for Android teams that prefer Kotlin for host-side
+test orchestration. It does not replace the Android app shim or run inside the
+app process.
+
+## Which Client Should You Use?
+
+- Use only the CLI for committed `.zmr/*.json` scenarios and CI.
+- Use TypeScript or Python for most AI agents because they are easy to generate
+  and inspect.
+- Use Go or Rust for long-running infrastructure services.
+- Use Swift or Kotlin when native mobile teams want host-side tooling in their
+  everyday language.
+
+All clients call the same public JSON-RPC protocol, so feature parity should
+come from the runner, not from language-specific behavior.

package/docs/clients.md

@@ -0,0 +1,98 @@
+# Client Guide
+
+ZMR clients are reference implementations for the JSON-RPC protocol used by
+`zmr serve`. They are intentionally small and dependency-light.
+
+## What Clients Mean
+
+The runner is still the Zig binary. A client starts or connects to:
+
+```bash
+zmr serve --transport stdio --config .zmr/config.json --trace-dir traces/zmr-agent
+```
+
+Then it sends JSON-RPC methods such as:
+
+- `runner.capabilities`
+- `session.create`
+- `observe.snapshot`
+- `observe.semanticSnapshot`
+- `ui.tap`
+- `wait.until`
+- `assert.visible`
+- `assert.healthy`
+- `trace.events`
+- `trace.export`
+
+Use clients when an AI agent, service, or test harness wants to drive ZMR
+programmatically instead of shelling out for each scenario. For package-manager
+install commands, see [client-installation.md](client-installation.md).
+Prefer the semantic snapshot helper for agent planning; it normalizes native
+Android/iOS classes into roles, selectors, bounds, and recommended actions.
+Use `assert.healthy` after launches, deep links, and high-risk transitions so
+agent-written tests fail on crash overlays and development-client load errors
+even when normal page text is also present.
+
+## Language Layouts
+
+| Language | Files | Why it looks this way |
+| --- | --- | --- |
+| TypeScript | `clients/typescript/index.mjs`, `index.d.ts` | ESM runtime plus type declarations, no build step required |
+| Python | `clients/python/zmr_client.py`, `pyproject.toml` | Standard-library importable module that can be vendored or pip-installed from source |
+| Go | `clients/go/zmr/client.go` | Normal Go package inside a module |
+| Rust | `clients/rust/src/lib.rs` | Cargo library crate convention |
+| Swift | `clients/swift/Sources/ZMRClient/ZMRClient.swift` | SwiftPM package for macOS host-side tools |
+| Kotlin | `clients/kotlin/src/main/kotlin/dev/zmr/ZmrClient.kt` | Gradle/Kotlin source package for JVM host-side tools |
+
+Rust has `src/lib.rs` because Cargo expects a library crate there. The other
+clients do have equivalent entry points; they are just idiomatic for their
+languages rather than named `lib.rs`. Swift and Kotlin are useful for native
+mobile teams, but they still run on the development machine and drive the
+external `zmr` binary. They are not app-runtime SDKs.
+
+## Quick Starts
+
+TypeScript:
+
+```bash
+node clients/typescript/examples/fake-session.mjs
+```
+
+Python:
+
+```bash
+python3 clients/python/examples/fake_session.py
+```
+
+Go:
+
+```bash
+go run ./clients/go/examples/fake-session \
+  --zmr ./zig-out/bin/zmr \
+  --adb ./tests/fake-adb.sh \
+  --trace-dir traces/demo-go-client
+```
+
+Rust:
+
+```bash
+cargo run --manifest-path clients/rust/Cargo.toml --example fake_session -- \
+  --zmr ./zig-out/bin/zmr \
+  --adb ./tests/fake-adb.sh \
+  --trace-dir traces/demo-rust-client
+```
+
+Swift:
+
+```bash
+swift build --package-path clients/swift
+```
+
+Kotlin:
+
+```bash
+gradle -p clients/kotlin build
+```
+
+For real app usage, replace the fake server with `zmr serve --transport stdio`
+and pass `.zmr/config.json`.

package/docs/config.md

@@ -0,0 +1,175 @@
+# App-Local Config
+
+ZMR uses `.zmr/config.json` as the app-local source of truth for default app ids,
+devices, scenario paths, and trace directories.
+
+The schema is published at `schemas/zmr-config.schema.json`.
+Runtime parsing follows the schema for primitive field types. For example,
+boolean fields such as `artifacts.screenRecording`, `artifacts.screenshots`,
+`android.resetBeforeRun`, and `android.waitReady` must be JSON booleans, not
+strings. Path, id, redaction-list, and script command string fields must be
+non-empty. `zmr doctor --json --config .zmr/config.json` reports those type/value mistakes as
+structured `config` warnings. Unknown fields are rejected too, so typos in
+app-local config do not silently fall back to defaults.
+
+Example:
+
+```json
+{
+  "schemaVersion": 1,
+  "appId": "com.example.mobiletest",
+  "android": {
+    "enabled": true,
+    "defaultDevice": "emulator-5554",
+    "smokeScenario": ".zmr/android-smoke.json",
+    "traceDir": "traces/zmr-android",
+    "avdName": "Small_Phone",
+    "restoreSnapshot": "zmr-clean",
+    "createAvdIfMissing": false,
+    "avdSystemImage": "system-images;android-35;google_apis;arm64-v8a",
+    "avdDeviceProfile": "pixel_6",
+    "resetBeforeRun": false,
+    "waitReady": true
+  },
+  "ios": {
+    "enabled": true,
+    "defaultDevice": "booted",
+    "smokeScenario": ".zmr/ios-smoke.json",
+    "traceDir": "traces/zmr-ios"
+  },
+  "artifacts": {
+    "screenshots": true,
+    "hierarchy": true,
+    "logs": true,
+    "screenRecording": false
+  },
+  "redaction": {
+    "denylistText": ["customer dob", "internal token"],
+    "allowlistText": ["public token label"],
+    "denylistResourceIds": ["password-field", "ssn"],
+    "allowlistResourceIds": ["public-token-label"]
+  },
+  "tools": {
+    "androidShimPath": "./.zmr/android-shim",
+    "iosShimPath": "./.zmr/ios-shim"
+  }
+}
+```
+
+## Precedence
+
+ZMR auto-discovers `.zmr/config.json` from the current working directory.
+Pass `--config <path>` to load a different file.
+
+Relative scenario, trace, and shim paths from config resolve against the app
+root. For the standard `.zmr/config.json` location, the app root is the parent
+directory of `.zmr/`, even when `--config` is an absolute path and ZMR is
+invoked from another checkout. Relative optional tool commands such as
+`tools.adbPath` are resolved the same way when they look like paths; bare
+commands such as `adb`, `xcrun`, or `zig` stay as PATH lookups.
+
+Explicit CLI flags always win:
+
+- `--app-id` overrides `appId`
+- `--device` overrides platform `defaultDevice`
+- `--trace-dir` overrides platform `traceDir`
+- `--android-avd`, `--create-avd-if-missing`, `--avd-system-image`, `--avd-device`, `--restore-snapshot`, `--reset-emulator`, and `--wait-emulator` override Android emulator lifecycle defaults
+- `--screen-record` and `--no-screen-record` override `artifacts.screenRecording`
+- a positional scenario path overrides platform `smokeScenario`
+- `--adb`, `--emulator`, `--avdmanager`, `--android-shim`, `--xcrun`, `--ios-shim`, and `--zig` override optional tool paths
+
+## Android Emulator Lifecycle
+
+The Android platform config can boot and wait for an emulator before a traced
+`zmr run` starts:
+
+- `avdName`: AVD name passed to the Android emulator.
+- `createAvdIfMissing`: check `emulator -list-avds` and create the AVD when absent.
+- `avdSystemImage`: installed Android system image package for `avdmanager create avd`.
+- `avdDeviceProfile`: optional device profile for the created AVD.
+- `restoreSnapshot`: optional emulator snapshot name to load at boot.
+- `resetBeforeRun`: best-effort `adb emu kill` before booting the configured AVD.
+- `waitReady`: wait for `adb wait-for-device` and `sys.boot_completed=1`.
+
+The equivalent CLI flags are `--android-avd <name>`,
+`--create-avd-if-missing`, `--avd-system-image <package>`,
+`--avd-device <profile>`, `--restore-snapshot <name>`, `--reset-emulator`,
+and `--wait-emulator`. AVD creation, snapshot restore, and reset require an AVD
+name. AVD creation also requires an installed system image package.
+
+## Android Shim
+
+Set `tools.androidShimPath` when an app repo has built or installed an Android
+instrumentation shim command. ZMR sends one JSON command to the shim over stdin
+and reads one JSON response from stdout. Existing ADB/UI Automator behavior
+remains the fallback when no shim is configured.
+
+CLI `--android-shim <path>` takes precedence over the config value for
+`zmr run`, `zmr serve`, and `zmr doctor`.
+
+## iOS Shim
+
+Set `tools.iosShimPath` when an app repo has built or installed an
+XCTest/XCUIAutomation shim command. ZMR sends one JSON command to the shim over
+stdin and reads one JSON response from stdout. The public scenario and JSON-RPC
+interfaces stay unchanged. The generated shim command may cache the XCTest
+`build-for-testing` output and use `test-without-building` internally; ZMR still
+treats it as a simple command transport.
+
+With the shim configured, iOS waits and assertions use native XCTest selector
+queries for single-field selectors before falling back to portable snapshot
+matching. `observe.snapshot` uses a bounded XCTest snapshot so large native or
+React Native trees remain fast enough for interactive agent loops.
+
+CLI `--ios-shim <path>` takes precedence over the config value for `zmr run`,
+`zmr serve`, and `zmr doctor`.
+
+## Artifact Capture
+
+The `artifacts` object controls what raw trace artifacts are persisted during
+`zmr run`.
+
+- `screenshots`: write PNG screenshot artifacts.
+- `hierarchy`: write raw Android UI hierarchy XML artifacts.
+- `logs`: include recent device log windows in snapshots.
+- `screenRecording`: capture an Android MP4 for the whole traced `zmr run`.
+
+Screenshots, hierarchy, and logs default to `true`; screen recording defaults to
+`false` because it can be large and privacy-sensitive. Set raw artifacts to
+`false` in app repos when traces may contain private visual state,
+accessibility text, or log output. Selector matching can still use the live
+hierarchy even when raw hierarchy persistence is disabled.
+
+## Trace Redaction
+
+The `redaction` object adds app-specific rules on top of ZMR's built-in email,
+token, and sensitive-key scrubbing for persisted trace JSON.
+
+- `denylistText`: redact trace strings containing any listed text.
+- `allowlistText`: skip app-specific text denylist matches for strings
+  containing any listed text. Built-in email/token scrubbing still applies.
+- `denylistResourceIds`: redact matching node `resourceId` values and force the
+  node's `text` and `contentDesc` fields to secret placeholders.
+- `allowlistResourceIds`: skip resource-id based redaction for matching nodes.
+  Built-in value-level email/token scrubbing still applies.
+
+All matches are case-insensitive substrings. These rules apply to local
+persisted snapshot JSON and trace events for both `zmr run` and
+`zmr serve --trace-dir`. They do not edit raw screenshot pixels or raw hierarchy
+XML; disable those artifacts or share `zmr export --redact` bundles when traces
+leave a trusted machine.
+
+## Commands
+
+```bash
+zmr init --app --json --dir . --app-id com.example.mobiletest
+zmr run --config .zmr/config.json
+zmr run .zmr/android-smoke.json --device emulator-5554
+zmr serve --transport stdio --config .zmr/config.json
+zmr mcp --config .zmr/config.json --trace-dir traces/zmr-agent
+zmr doctor --strict --json --config .zmr/config.json
+```
+
+For `zmr serve`, the platform `traceDir` from `.zmr/config.json` is used as the
+live JSON-RPC trace directory unless `--trace-dir` overrides it. Keep generated
+trace output under `traces/` and ignore that directory in app repositories.