agent-device 0.21.18 → 0.21.20

package/dist/src/cli-help.js

@@ -1,5 +1,273 @@
-import{r as e}from"./rolldown-runtime.js";import{_r as t}from"./sdk-batch.js";import{i as n}from"./catalog.js";import{r}from"./back-mode.js";import{C as i,N as a,S as o}from"./registry.js";import{a as s}from"./version.js";import{n as c,r as l}from"./command-schema.js";import{n as u}from"./cli-command-aliases.js";const d=[`Flows: launchApp (with clearState, permissions, and Apple-only launch arguments; permissions apply after state clearing but before launch, and a launchApp without permissions touches nothing — there is no silent all: allow default); setPermissions (mid-flow permission grants, denials, and resets; all resolves in the backend — one simctl call on iOS, the declared permissions on Android — with specific entries overriding after it); runFlow file/inline with platform, visibility, and limited boolean conditions; onFlowStart/onFlowComplete; repeat.times and retry.`,`Interactions: tapOn, doubleTapOn, longPressOn, inputText on the focused element, eraseText, openLink, hideKeyboard, basic pressKey, and back; selector targets poll until available and support recursive index, childOf, above, below, leftOf, rightOf, containsChild, containsDescendants, points, and optional; outer command labels are metadata, not target selectors.`,'Assertions and navigation: assertVisible, assertNotVisible, assertTrue (literal values and ${VAR} lookups only; "", "false", "0", "null", and "undefined" are falsy, everything else is truthy), extendedWaitUntil, scroll, scrollUntilVisible, absolute/percentage/target swipe, takeScreenshot, waitForAnimationToEnd, clearState, and stopApp.',`Scripts: ordered runScript file/env scripts with http.post, json, and output variables; evalScript inline expressions run flow-scoped JavaScript and write output.* leaves for later steps.`],f=[`Permissions: every entry is one settings permission call, applied in order with all first; the step stops at the first entry the selected platform refuses, earlier entries stay applied, and the error names what landed. Android’s only allow level is while-in-use, so location: inuse and location: never mean allow and deny there, while location: always and photos: limited are Apple-only and fail. On iOS, which service a runtime changes is simctl privacy’s own verdict: current runtimes refuse a targeted notifications change and leave notifications untouched under all.`,`Runtime: iOS and Android only; launchApp.clearState and standalone clearState support Android and iOS simulators, launch arguments are Apple-only, and other standalone device utility/state commands are unsupported.`,"Expressions: evalScript is the only command whose payload is evaluated as JavaScript (flow env and prior output leaves are string-typed); with that exception, fields stay literal or ${VAR} lookup-only — assertTrue supports literals and bare lookups, repeat.while is unsupported, and other expression-shaped payloads fail loud.",`Environment: flow env is the default, AD_VAR_* overrides it, and CLI -e KEY=VALUE wins over both.`,`Failure diagnostics: resolved targets and runFlow paths are rendered, while inputText payloads remain hidden; do not place secrets in diagnostic identifiers.`,`Trust: runScript and evalScript execute flow scripts in-process via node:vm, which is not a security sandbox; runScript may make http.post network requests and its output keys cannot contain a dot. evalScript is refused outright for a flow accepted over the daemon’s remote HTTP surface, since that context can escape to the host.`,`Errors and tracking: unsupported commands and fields fail with source context when available; open a focused issue only when implementation work is planned.`];function p(){return[`Supported subset:`,...d.map(e=>`  - ${e}`),``,`Boundaries:`,...f.map(e=>`  - ${e}`)].join(`
-`)}function m(e){let t=e.endsWith(`?`),n=t?e.slice(0,-1):e;return t?`[${n}]`:`<${n}>`}function h(e){return r().filter(t=>t.key===e)}function g(e){if(!e.usageHidden)return e.usageLabel??e.names[0]}function _(e){return(e??[]).flatMap(e=>h(e).map(g).filter(e=>e!==void 0).map(e=>`[${e}]`))}function v(e,t){return[t.usageOverride??[e,...(t.positionalArgs??[]).map(m)].join(` `),..._(t.usageFlags??t.allowedFlags)].join(` `)}function y(){return`agent-device <command> [args] [--json]
+import{r as e}from"./rolldown-runtime.js";import{vr as t}from"./sdk-batch.js";import{i as n}from"./catalog.js";import{r}from"./back-mode.js";import{C as i,P as a,c as o,w as s}from"./registry.js";import{a as c}from"./version.js";import{n as l,r as u}from"./command-schema.js";import{n as d}from"./cli-command-aliases.js";const f=[`Flows: launchApp (with clearState, permissions, and Apple-only launch arguments; permissions apply after state clearing but before launch, and a launchApp without permissions touches nothing — there is no silent all: allow default); setPermissions (mid-flow permission grants, denials, and resets; all resolves in the backend — one simctl call on iOS, the declared permissions on Android — with specific entries overriding after it); runFlow file/inline with platform, visibility, and limited boolean conditions; onFlowStart/onFlowComplete; repeat.times and retry.`,`Interactions: tapOn, doubleTapOn, longPressOn, inputText on the focused element, eraseText, openLink, hideKeyboard, basic pressKey, and back; selector targets poll until available and support recursive index, childOf, above, below, leftOf, rightOf, containsChild, containsDescendants, points, and optional; outer command labels are metadata, not target selectors.`,'Assertions and navigation: assertVisible, assertNotVisible, assertTrue (literal values and ${VAR} lookups only; "", "false", "0", "null", and "undefined" are falsy, everything else is truthy), extendedWaitUntil, scroll, scrollUntilVisible, absolute/percentage/target swipe, takeScreenshot, waitForAnimationToEnd, clearState, and stopApp.',`Scripts: ordered runScript file/env scripts with http.post, json, and output variables; evalScript inline expressions run flow-scoped JavaScript and write output.* leaves for later steps.`],p=[`Permissions: every entry is one settings permission call, applied in order with all first; the step stops at the first entry the selected platform refuses, earlier entries stay applied, and the error names what landed. Android’s only allow level is while-in-use, so location: inuse and location: never mean allow and deny there, while location: always and photos: limited are Apple-only and fail. On iOS, which service a runtime changes is simctl privacy’s own verdict: current runtimes refuse a targeted notifications change and leave notifications untouched under all.`,`Runtime: iOS and Android only; launchApp.clearState and standalone clearState support Android and iOS simulators, launch arguments are Apple-only, and other standalone device utility/state commands are unsupported.`,"Expressions: evalScript is the only command whose payload is evaluated as JavaScript (flow env and prior output leaves are string-typed); with that exception, fields stay literal or ${VAR} lookup-only — assertTrue supports literals and bare lookups, repeat.while is unsupported, and other expression-shaped payloads fail loud.",`Environment: flow env is the default, AD_VAR_* overrides it, and CLI -e KEY=VALUE wins over both.`,`Failure diagnostics: resolved targets and runFlow paths are rendered, while inputText payloads remain hidden; do not place secrets in diagnostic identifiers.`,`Trust: runScript and evalScript execute flow scripts in-process via node:vm, which is not a security sandbox; runScript may make http.post network requests and its output keys cannot contain a dot. evalScript is refused outright for a flow accepted over the daemon’s remote HTTP surface, since that context can escape to the host.`,`Errors and tracking: unsupported commands and fields fail with source context when available; open a focused issue only when implementation work is planned.`];function m(){return[`Supported subset:`,...f.map(e=>`  - ${e}`),``,`Boundaries:`,...p.map(e=>`  - ${e}`)].join(`
+`)}function h(e){let t=e.endsWith(`?`),n=t?e.slice(0,-1):e;return t?`[${n}]`:`<${n}>`}function g(e){return r().filter(t=>t.key===e)}function _(e){if(!e.usageHidden)return e.usageLabel??e.names[0]}function v(e){return(e??[]).flatMap(e=>g(e).map(_).filter(e=>e!==void 0).map(e=>`[${e}]`))}function y(e,t){return[t.usageOverride??[e,...(t.positionalArgs??[]).map(h)].join(` `),...v(t.usageFlags??t.allowedFlags)].join(` `)}const b=`Wait failure contract:
+  Read --json error.details.reason.
+  wait_target_absent: readable capture, no match.
+  wait_target_present: absence timeout; details.matches/firstMatch.
+  predicate_failed: no valid absence capture; observation/diagnostic kept.
+  wait_capture_stalled: no readable capture by deadline -- retriable.
+  wait_deadline_exceeded: later capture exhausted budget after a readable one.
+  wait_readiness_exhausted: readiness deadline; details.readinessPhase -- retriable.
+  wait_runner_restart_exhausted: restart deadline -- retriable.
+  wait_landmark_identity_mismatch: replay guard: selector matched, recorded identity differed.
+  wait_stable_timeout: no stable UI -- not absence.
+`,x={"manual-qa":{summary:`Follow manual test scripts with exact interactions and verification`,body:`agent-device help manual-qa
+
+Use this when asked to follow a manual QA script, test case, checklist, acceptance flow, or user-provided instructions.
+
+Contract:
+  Execute the script. Do not explore unrelated screens, read app source, invent missing requirements, or broaden scope.
+  Stop and report ambiguity when a required target or expected result is not visible after the documented recovery steps.
+
+Loop:
+  1. Open the requested app; use --relaunch only when the script needs fresh state.
+  2. Run snapshot -i to get current refs for the next step.
+  3. Run press/fill/click/longpress <ref-or-selector> --settle for each mutating step.
+  4. Treat a settled:true diff as the next observation. Do not add wait stable or another snapshot when the diff already shows the next target or expected result.
+  5. If --settle prints not settled, follow its hint before the next ref-based action.
+  6. Verify named expectations with wait text/selector/absent, get, is, find, or the settled diff. A bare screenshot/snapshot is not verification for a named expectation.
+  7. Close the session when the script ends.
+
+Command shapes:
+  agent-device open com.example.app --relaunch
+  agent-device open https://example.com/deep-link
+  agent-device snapshot -i
+  agent-device press @e12 --settle
+  agent-device press 'label="Follow"' --settle
+  agent-device fill @e13 "qa@example.com" --settle
+  agent-device wait text "Order placed" 3000
+  agent-device wait absent 'label="Loading..."' 3000
+  agent-device close
+  --relaunch forces fresh app state; a deep link/URL open does not need it. Labels with an apostrophe or quote (label="Don't leave") are shell-quoting hazards: prefer the @ref from the latest snapshot/settle output over quoting the literal label.
+
+Targets:
+  Prefer refs from the latest snapshot -i or settled diff. Use durable selectors when the label/id is known: label="Search", id="submit", role=button label="Follow". If label text matches both a field and its caption, target the field with label="Email" editable=true.
+  For text fields, use fill <target> <text> --settle to replace the field value; use type only to append to an already-focused field.
+  Do not use placeholders such as @ref, @eN, <button>, or <selector> in a final command plan. If the ref is unknown, first run snapshot -i.
+  Coordinates are fallback-only after refs/selectors fail or accessibility omits the target; use screenshot or snapshot -i --json to choose a visible center point.
+
+Recovery:
+  Network/typeahead result missing: wait text "Expected result" or wait <selector>.
+  A target that should be gone/disappear: use wait absent <selector>; wait exists ... is rejected in favor of the plain selector wait.
+  Keyboard visible over the next target: an element whose center sits behind the keyboard is refused with tap_keyboard_occludes_target, because the touch would activate a key instead of the target. End editing first -- the app's own Done/Cancel control, or keyboard enter when submission is wanted -- then retry. A target whose center stays above the keys still presses; a raw coordinate behind the keyboard taps anyway and reports the reason in warning.
+  Sparse or recovered accessibility snapshot: use screenshot as visual truth, leave the bad screen if needed, then retry snapshot -i.
+  Non-hittable success hint: verify with the settled diff or snapshot; retarget by a better ref/selector if the UI did not change.
+
+${b}`}},S={debugging:{summary:`Targeted failure evidence without dumping stale context`,body:`agent-device help debugging
+
+Use this when behavior fails, hangs, times out, throws alerts, or needs runtime evidence.
+
+Logs:
+  Keep log windows small. Prefer clear, mark, reproduce, then path.
+    agent-device logs clear --restart
+    agent-device logs mark "before diagnostics retry"
+    agent-device press 'id="load-diagnostics"'
+    agent-device logs path
+  Do not cat a full stale log into agent context. Open or grep only the relevant window when needed.
+  logs clear --restart is the compact command to clear old logs and start a fresh capture; do not split it into logs stop, logs clear, logs start.
+  On iOS simulators, logs scope by bundle id and resolved app executable, so use this instead of raw simctl log stream predicates.
+  On iOS physical devices, logs clear --restart relaunches the session app through devicectl process launch --console so stdout/stderr can be captured.
+  For iOS simulator launch-time stdout/stderr, use --launch-console on the direct app launch:
+    agent-device open MyApp --platform ios --relaunch --launch-console ./artifacts/app.console.log
+  --launch-console is only for direct iOS simulator app launches, not URL opens.
+
+Events:
+  Use events for a compact session timeline without dumping full app logs.
+    agent-device events
+    agent-device events 50 100
+  Events preserve command names, status, durations, bounded device/app inventory previews, lifecycle outcomes, artifact basenames, and structural action details such as scroll distance/direction, safe refs, and coordinates. User-entered text, clipboard contents, push/event payloads, selector values, free-form flags/messages/paths, and raw unknown command arguments are omitted or replaced with content-free placeholders. --no-record suppresses action.recorded entries, but request start/finish entries still record command, status, and timing.
+
+Network:
+  Use network dump for recent session HTTP traffic parsed from app logs.
+    agent-device network dump --include headers
+    agent-device network dump 20 --include all
+  Use this instead of logs path when the question is request/response metadata.
+  network log is a supported alias, but network dump --include headers is the clearest plan form. Do not write network log headers.
+
+Audio:
+  Use audio probe when the question is whether a browser page, macOS session, iOS simulator, or Android emulator produced audible output during a short observation window.
+    agent-device audio probe start 10 1000 --platform web
+    agent-device audio probe status --platform web
+    agent-device audio probe stop --platform web
+    agent-device audio probe start 10 1000 --platform macos
+    agent-device audio probe start 10 1000 --platform ios
+    agent-device audio probe start 10 1000 --platform android
+  audio probe start uses duration seconds first, then bucket milliseconds. Results are compact rmsDbfs and peakDbfs arrays so agents can correlate audible moments with screenshots, actions, network entries, or frame samples.
+  On web, audio probe samples HTML media elements and URL-backed media may be routed through the probe AudioContext while observed.
+  On macOS hosts, audio probe samples host system audio through ScreenCaptureKit for macOS sessions, iOS simulators, and Android emulators. It requires Screen Recording permission and is system-audio evidence, not app-instrumented audio. Physical iOS and Android devices are not supported.
+
+Crash symbolication:
+  Crash routing:
+    Use logs when you need the lead-up timeline before a failure.
+    Use debug symbols when you have crash.ips/crash.log plus a matching dSYM/build directory and need the failing frame.
+    Use Xcode/LLDB when you need live state, breakpoints, variables, memory, or stepping.
+  Use debug symbols when you already have an Apple crash artifact and local dSYMs and need the failing code path, not a full log dump:
+    agent-device debug symbols --artifact crash.log --dsym MyApp.dSYM --out crash-symbolicated.log
+    agent-device debug symbols --artifact crash.ips --search-path ./build --out crash-symbolicated.ips
+  debug is intentionally narrow. Do not use it for logs, network/audio evidence, performance samples, recordings, traces, or React Native internals.
+  Apple support matches crash Binary Images / IPS usedImages UUIDs against dwarfdump --uuid output from .dSYM bundles, then writes a symbolicated artifact path and compact crash report: app/thread, exception or termination, top symbolicated frames, and first-frame finding. This is better than pasting crash logs because it keeps agent context small while preserving the artifact on disk for inspection.
+  Android Java/R8 mapping.txt and native ndk-stack/addr2line symbolication are not in this first debug symbols workflow; capture crash evidence with logs and use the Android toolchain externally for now.
+
+Alerts:
+  Native and platform dialogs:
+    agent-device alert wait 3000
+    agent-device alert accept
+    agent-device alert dismiss
+  Android support is snapshot-derived for runtime permission prompts and native app dialogs. iOS support is runner-derived for XCTest alerts, app-owned modal popups with native blocking markers, and blocking system dialogs. Use cheap alert get for an immediate check; use alert wait <short-ms> only when a prompt may appear after async work.
+  If alert says no alert but a sheet is visibly on screen, treat it as app-owned UI:
+    agent-device snapshot -i
+    agent-device press 'label="Allow"'
+  Do not use settings permission to answer a dialog already on screen. Reserve settings permission for setup/resetting permission state before a flow.
+
+Diagnostics and traces:
+  Use --debug for CLI/daemon diagnostic ids and log paths.
+  Use AGENT_DEVICE_EXEC_TRACE=1 when you need host-tool spawn timing without full debug streaming; it flushes the full request diagnostics file on successful requests that spawn host tools.
+  Open output includes Session state; JSON also includes runnerLogPath and requestLogPath.
+  For open timing under --debug, run open --debug --json and inspect requestLogPath for the open_timing event.
+  Session requests/<request-id>.ndjson holds daemon request diagnostics; session runner.log holds Apple runner/xcodebuild output.
+  Against a remote daemon the Diagnostics Log path is always local: the failing request's record is fetched to <state-dir>/remote-diagnostics/, and if it cannot be fetched the line reads "unavailable" with the reason instead of a daemon-host path.
+  daemon.log is global daemon lifecycle evidence, not the primary per-run log.
+  Use trace for low-level session diagnostics around one repro:
+    agent-device trace start ./traces/diagnostics.trace
+    agent-device press 'id="load-diagnostics"'
+    agent-device trace stop ./traces/diagnostics.trace
+  The trace path is positional. Do not use --path for trace start or trace stop.
+  Use perf xctrace only for Apple native CPU/profile or Animation Hitches artifacts:
+    agent-device perf cpu profile start --kind xctrace --template "Time Profiler" --out ./artifacts/app.trace
+    agent-device perf cpu profile stop --kind xctrace --out ./artifacts/app.trace
+    agent-device perf cpu profile report --kind xctrace --out ./artifacts/app-profile.json
+    agent-device perf trace start --kind xctrace --template "Animation Hitches" --out ./artifacts/hitches.trace
+    agent-device perf trace stop --kind xctrace --out ./artifacts/hitches.trace
+  perf xctrace keeps the .trace artifact on disk; CPU report returns a bounded weighted top-function summary. Do not dump .trace contents into context.
+  For Android native CPU/trace evidence, use perf artifacts instead of raw adb/simpleperf/perfetto output:
+    agent-device perf cpu profile start --kind simpleperf --out /tmp/cpu.perf.data
+    agent-device perf cpu profile stop --kind simpleperf
+    agent-device perf cpu profile report --kind simpleperf --out /tmp/cpu-report.json
+    agent-device perf trace start --kind perfetto --out /tmp/app.perfetto-trace
+    agent-device perf trace stop --kind perfetto
+  Treat native perf output as the agent evidence: for example, state=stopped, outPath=/tmp/app.perfetto-trace, sizeBytes=5392410, method=adb-shell-perfetto. The 5.3 MB raw trace stays in the artifact.
+  CPU reports return at most ten top functions in structured data and print five in default CLI output.
+  Use explicit perf frames, perf memory, perf cpu, or perf trace forms. Aggregate perf was removed in 0.21: bare perf, perf sample, perf metrics, and metrics fail with exact replacements.
+  Startup duration belongs to the open command's startup result; read it there.
+
+Memory diagnostics:
+  Use perf memory when the symptom is leak/growth/OOM suspicion and you need agent-readable evidence.
+    agent-device perf memory sample --json
+    agent-device perf memory snapshot --kind android-hprof --out ./artifacts/app.hprof
+    agent-device perf memory snapshot --kind memgraph --out ./artifacts/app.memgraph
+  Example sample shape:
+    {"metrics":{"memory":{"available":true,"totalPssKb":562958,"totalRssKb":570304,"topConsumers":[{"name":"Dalvik Heap","pssKb":213456}]}}}
+  Example default snapshot output:
+    Memory artifact (android-hprof): /tmp/app.hprof (42MB)
+  Prefer perf memory sample over raw dumpsys/leaks output for first-pass agent diagnosis: it keeps arrays bounded and returns only relevant memory evidence.
+  Prefer perf memory snapshot over printing heap/memgraph data: snapshots return path, size, kind, method, and support metadata while the large artifact stays on disk for external inspection.
+  Unsupported platforms return artifact.available=false with reason/hint; do not pretend a heap or memgraph was captured.
+
+Stabilizers:
+  Android animation-sensitive flows:
+    agent-device settings animations off
+    agent-device snapshot
+    agent-device settings animations on
+  Re-enable settings you changed before finishing.
+
+Text-entry quirks:
+  iOS Allow Paste cannot be exercised under XCUITest; prefill with clipboard write "some text" instead and test the system prompt manually.
+  Android Gboard handwriting/stylus UI can capture text in an IME-owned input instead of the app field. If fill reports that input was captured by the keyboard/IME, use the diagnostic targetInput/actualInput details, inspect keyboard status/get if needed, and switch or disable handwriting outside the command plan before retrying. Do not keep retrying fill/type against the same field while the IME owns focus. If the exact target changes but app-owned formatting prevents raw equality, fill succeeds with verification: "unconfirmed" plus target-bound requested/before/after evidence; inspect that evidence instead of retrying the same mutation.
+
+React Native internals:
+  If the question is about React Native performance, profiling, props, state, hooks, render causes, slow components, or rerenders, use help react-devtools instead of inferring from screenshots or logs.`}},C={dogfood:{summary:`Exploratory QA workflow with reproducible evidence`,body:`agent-device help dogfood
+
+Use this when asked to dogfood, exploratory test, bug hunt, QA, or find issues in an app.
+
+Goal:
+  Find user-visible issues from runtime behavior. Do not read app source or invent findings from code.
+  Produce a concise report with severity, repro commands, expected/actual behavior, and evidence paths.
+
+Loop:
+  1. Identify target app/platform; ask only if missing.
+  2. Create output dirs and open the app. If auth or OTP is required, sign in or ask the user for the code.
+  3. Capture baseline snapshot -i and screenshot.
+  4. Map top-level navigation, then exercise primary flows and edge states.
+  5. For each issue, capture evidence and write the finding immediately, then continue.
+  6. Close the session and reconcile the report summary.
+  Keep stateful commands serial within the same session. Parallel runs can pollute text fields, focus, alerts, and navigation state.
+
+Coverage:
+  Navigation, forms, empty/error/loading states, offline or retry behavior, permissions, settings, accessibility labels, orientation/keyboard, and obvious performance stalls.
+  React Native warning/error overlays can be real findings or test blockers. Capture them, use react-native dismiss-overlay if unrelated, re-snapshot, and report them.
+  Expo Go/dev-client shells: use the provided exp:// or dev-client URL and record whether the shell, project load, or app UI is being tested. On iOS dogfood, prefer agent-device open "Expo Go" <url> when Expo Go is the known shell, then snapshot -i to confirm the project UI rather than the runner splash.
+  Android RN/Expo/Re.Pack dev server: direct Android localhost URL opens with a port auto-configure host reachability.
+  Categories: visual, functional, UX, content, performance, diagnostics, permissions, accessibility.
+  Severity: critical blocks a core flow/data/crashes; high breaks a major feature; medium has friction or workaround; low is polish.
+
+Evidence commands:
+  mkdir -p ./dogfood-output/screenshots ./dogfood-output/videos ./dogfood-output/traces
+  agent-device open <app> --platform ios
+  agent-device snapshot -i
+  agent-device screenshot ./dogfood-output/screenshots/initial.png
+  agent-device screenshot ./dogfood-output/screenshots/issue-001.png --overlay-refs
+  agent-device logs clear --restart
+  agent-device logs mark "issue-001 repro"
+  agent-device logs path
+  agent-device record start ./dogfood-output/videos/issue-001.mp4
+  agent-device record start ./dogfood-output/videos/benchmark.mp4 --hide-touches
+  agent-device record stop
+  agent-device close
+
+Evidence rules:
+  Interactive/behavioral issues need step screenshots and usually a repro video.
+  Static/on-load issues can use one screenshot; set repro video to N/A.
+  Use screenshot --overlay-refs when showing the tappable target or broken state helps repro.
+
+Report shape:
+  ./dogfood-output/report.md
+  Include date, platform, target app, session, scope, severity counts, and issues.
+  For each finding: ID, severity, category, title, affected flow/screen, repro commands, expected, actual, evidence files, notes.
+  Target 5-10 well-evidenced issues when available. If no issues are found, report coverage completed and residual risk instead of claiming the app is bug-free.
+
+Rules:
+  Findings must come from observed runtime behavior, not source reads.
+  After each mutation, use the --settle diff as evidence when available; otherwise re-snapshot.
+  Wait timeouts are integer milliseconds in the trailing positional: agent-device wait 'role=tab' 10000. Do not write duration suffixes such as 10s.
+  scroll takes a selector-less direction+amount form: agent-device scroll down 0.8. One gesture cannot travel further than 0.8 of the viewport axis, so a larger amount saturates rather than covering more ground; to cross several screens use agent-device scroll down --until <selector> or scroll bottom. Use --settle to wait for the UI to go quiet and get the settled diff.
+  Keep commands in the report reproducible; use selectors or refs from fresh snapshots, not guessed coordinates.
+  Prefer refs for exploration and selectors for deterministic replay.
+  Use logs, network, screenshot --overlay-refs, trace, perf frames, perf memory, native profiles, or react-devtools only when they add evidence to a specific issue.
+  Never delete screenshots, videos, traces, or report artifacts during a session.
+  Escalate to help debugging or help react-devtools when runtime symptoms require those tools.`},validate:{summary:`Engineering self-validation with device evidence and cleanup`,body:`agent-device help validate
+
+Use this when validating a code change, release candidate, performance fix, visual behavior, logging path, replay, or device-facing regression.
+
+Contract:
+  Prove the changed behavior through public agent-device surfaces. Do not validate against stale dist output, a retained stale daemon, or a runner built before the change.
+  Keep evidence reproducible: exact commands, target device/app, observed output, artifact paths, and cleanup status.
+
+Required freshness gate before device verification:
+  For a TypeScript runtime or CLI output change, start with pnpm build. For non-Android device verification, run pnpm clean:daemon next.
+  Before local Android verification, run pnpm build:android before pnpm clean:daemon so the bundled helpers match current source.
+  For an Apple runner change, run pnpm build:xcuitest and avoid inherited retained runners from older source. Do not build the Apple runner for TypeScript-only changes.
+  Use open --relaunch when startup state matters. Use a purpose-specific --session for multi-step validation.
+  CI may cache ~/.agent-device/apple-runner/derived with an exact key that includes the agent-device package and Xcode version. Runner reuse is authorized only by the cache metadata's content manifest, so a restore that fails validation rebuilds; prepare ios-runner already recovers one retryable non-connecting runner launch.
+
+Loop:
+  1. Build or prepare the changed surface with the repo command that owns it.
+  2. Open the target app/device state explicitly.
+  3. Use snapshot -i and press/fill/click/longpress --settle for UI-driving steps.
+  4. Use the settled diff as evidence when it shows the changed behavior; otherwise verify with wait/get/is/find, screenshot, logs, network, perf, or trace based on the claim.
+  5. Record timings, token/output size, screenshots/videos, logs, or perf artifacts only when they answer the validation question.
+  6. Close sessions and release leases before finishing.
+
+Evidence:
+  CLI/runtime freshness: pnpm build, pnpm clean:daemon, then agent-device --version or the command under test.
+  Apple runner freshness: pnpm build:xcuitest, then a live agent-device command on the target simulator/device.
+  Visual claim: screenshot, optionally screenshot --overlay-refs when target mapping matters.
+  Runtime/logging claim: logs clear --restart, logs mark, reproduce, logs path.
+  Network claim: network dump --include headers when headers are relevant.
+  Performance claim: perf frames, perf memory sample, native profile reports, or trace artifacts with bounded output.
+  Replay/regression claim: replay or test through the public command path.
+
+Report:
+  Summarize what changed, exact validation commands, pass/fail observations, artifact paths, and residual risk.
+  If live validation is blocked, state the blocker, device/session, and exact next command needed.`}};function w(){return`agent-device <command> [args] [--json]
 
 Automates iOS, Android, macOS, TV, and web apps for AI agents.
 All ${n().length} commands: agent-device help commands
@@ -50,62 +318,11 @@ Guides (agent-device help <topic>):
   react-native / react-devtools / cdp / tv / web / macos / remote
   physical-device / ios-system-ui / maestro
   foldable    iPhone Duo panels, the fold command, and why refs die on a pose change
-`}var b=e({buildCommandUsageText:()=>L,buildUsageText:()=>A,helpTopicIds:()=>z,resolveHelpTargetUsageText:()=>R});const x=[`Default config files: ~/.agent-device/config.json, ./agent-device.json (project-safe defaults only).`,`Use --config <path> or AGENT_DEVICE_CONFIG for explicit connection/provider defaults; project config cannot select endpoints or credentials.`],S=[{label:`AGENT_DEVICE_SESSION`,description:`Explicit session name`},{label:`AGENT_DEVICE_PLATFORM`,description:`Default platform binding`},{label:`AGENT_DEVICE_SCREENSHOT_SCALE`,description:`Default screenshot scale factor`},{label:`AGENT_DEVICE_SESSION_LOCK`,description:`Bound-session conflict mode`},{label:`AGENT_DEVICE_DAEMON_BASE_URL`,description:`Connect to remote daemon`},{label:`AGENT_DEVICE_DAEMON_AUTH_TOKEN`,description:`Remote daemon service/API token`},{label:`AGENT_DEVICE_CLOUD_BASE_URL`,description:`Bridge/control-plane API origin for cloud auth and /api-keys`}],C=[`agent-device open Settings --platform ios`,`agent-device open https://example.com --platform web`,`agent-device snapshot -i`,`agent-device fill @e3 "test@example.com"`,`agent-device replay ./session.ad`,`agent-device wait absent 'label="Loading..."' 3000`,`agent-device test ./suite --platform android`],w=`Wait failure contract:
-  Read error.details.reason in --json, not the message text.
-  wait_target_absent: a readable capture ran and found no match.
-  wait_target_present: wait absent timed out with matches; details include matches and firstMatch.
-  predicate_failed: wait absent had no valid capture; final observation/diagnostic is preserved.
-  wait_capture_stalled: no readable capture finished before the deadline -- retriable.
-  wait_deadline_exceeded: a later capture used the remaining budget after an earlier readable one.
-  wait_landmark_identity_mismatch: a replay destination guard found the selector but not the recorded identity.
-  wait_stable_timeout: wait stable never saw a stable UI -- not an absence verdict.
-`,T={commands:{summary:`Full command catalog, global flags, configuration, and environment`,body:`agent-device help commands`},"manual-qa":{summary:`Follow manual test scripts with exact interactions and verification`,body:`agent-device help manual-qa
-
-Use this when asked to follow a manual QA script, test case, checklist, acceptance flow, or user-provided instructions.
-
-Contract:
-  Execute the script. Do not explore unrelated screens, read app source, invent missing requirements, or broaden scope.
-  Stop and report ambiguity when a required target or expected result is not visible after the documented recovery steps.
-
-Loop:
-  1. Open the requested app; use --relaunch only when the script needs fresh state.
-  2. Run snapshot -i to get current refs for the next step.
-  3. Run press/fill/click/longpress <ref-or-selector> --settle for each mutating step.
-  4. Treat a settled:true diff as the next observation. Do not add wait stable or another snapshot when the diff already shows the next target or expected result.
-  5. If --settle prints not settled, follow its hint before the next ref-based action.
-  6. Verify named expectations with wait text/selector/absent, get, is, find, or the settled diff. A bare screenshot/snapshot is not verification for a named expectation.
-  7. Close the session when the script ends.
-
-Command shapes:
-  agent-device open com.example.app --relaunch
-  agent-device open https://example.com/deep-link
-  agent-device snapshot -i
-  agent-device press @e12 --settle
-  agent-device press 'label="Follow"' --settle
-  agent-device fill @e13 "qa@example.com" --settle
-  agent-device wait text "Order placed" 3000
-  agent-device wait absent 'label="Loading..."' 3000
-  agent-device close
-  --relaunch forces fresh app state; a deep link/URL open does not need it. Labels with an apostrophe or quote (label="Don't leave") are shell-quoting hazards: prefer the @ref from the latest snapshot/settle output over quoting the literal label.
-
-Targets:
-  Prefer refs from the latest snapshot -i or settled diff. Use durable selectors when the label/id is known: label="Search", id="submit", role=button label="Follow". If label text matches both a field and its caption, target the field with label="Email" editable=true.
-  For text fields, use fill <target> <text> --settle to replace the field value; use type only to append to an already-focused field.
-  Do not use placeholders such as @ref, @eN, <button>, or <selector> in a final command plan. If the ref is unknown, first run snapshot -i.
-  Coordinates are fallback-only after refs/selectors fail or accessibility omits the target; use screenshot or snapshot -i --json to choose a visible center point.
-
-Recovery:
-  Network/typeahead result missing: wait text "Expected result" or wait <selector>.
-  A target that should be gone/disappear: use wait absent <selector>; wait exists ... is rejected in favor of the plain selector wait.
-  Keyboard visible over the next target: an element whose center sits behind the keyboard is refused with tap_keyboard_occludes_target, because the touch would activate a key instead of the target. End editing first -- the app's own Done/Cancel control, or keyboard enter when submission is wanted -- then retry. A target whose center stays above the keys still presses; a raw coordinate behind the keyboard taps anyway and reports the reason in warning.
-  Sparse or recovered accessibility snapshot: use screenshot as visual truth, leave the bad screen if needed, then retry snapshot -i.
-  Non-hittable success hint: verify with the settled diff or snapshot; retarget by a better ref/selector if the UI did not change.
-
-${w}`},maestro:{summary:`Supported Maestro YAML commands, grammar, and runtime boundaries`,body:`agent-device help maestro
+`}var T=e({buildCommandUsageText:()=>V,buildUsageText:()=>P,helpTopicIds:()=>U,resolveHelpTargetUsageText:()=>H});const E=[`Default config files: ~/.agent-device/config.json, ./agent-device.json (project-safe defaults only).`,`Use --config <path> or AGENT_DEVICE_CONFIG for explicit connection/provider defaults; project config cannot select endpoints or credentials.`],D=[{label:`AGENT_DEVICE_SESSION`,description:`Explicit session name`},{label:`AGENT_DEVICE_PLATFORM`,description:`Default platform binding`},{label:`AGENT_DEVICE_SCREENSHOT_SCALE`,description:`Default screenshot scale factor`},{label:`AGENT_DEVICE_SESSION_LOCK`,description:`Bound-session conflict mode`},{label:`AGENT_DEVICE_DAEMON_BASE_URL`,description:`Connect to remote daemon`},{label:`AGENT_DEVICE_DAEMON_AUTH_TOKEN`,description:`Remote daemon service/API token`},{label:`AGENT_DEVICE_CLOUD_BASE_URL`,description:`Bridge/control-plane API origin for cloud auth and /api-keys`}],O=[`agent-device open Settings --platform ios`,`agent-device open https://example.com --platform web`,`agent-device snapshot -i`,`agent-device fill @e3 "test@example.com"`,`agent-device replay ./session.ad`,`agent-device wait absent 'label="Loading..."' 3000`,`agent-device test ./suite --platform android`],k={commands:{summary:`Full command catalog, global flags, configuration, and environment`,body:`agent-device help commands`},...x,maestro:{summary:`Supported Maestro YAML commands, grammar, and runtime boundaries`,body:`agent-device help maestro
 
 Run Maestro compatibility flows with replay <flow.yaml> --maestro or test <path> --maestro. Bind an iOS or Android target with --platform or an existing session.
 
-${p()}
+${m()}
 
 Unsupported syntax fails loudly rather than being skipped. Architecture, performance tradeoffs, and declared conformance divergences: https://github.com/callstack/agent-device/blob/main/docs/adr/0015-direct-maestro-engine.md
 Focused compatibility request: https://github.com/callstack/agent-device/issues/new`},workflow:{summary:`Normal agent-device bootstrap, exploration, and validation loop`,body:`agent-device help workflow
@@ -148,7 +365,7 @@ Session ordering:
   Stateful commands (open/press/fill/type/scroll/back/alert/replay/batch/close) run serially within one session. Parallelize only read-only commands, or separate sessions/devices.
 
 Read-only and waits:
-${w}
+${b}
   snapshot/get/is/find answer read-only questions; snapshot -i is for refs. --settle confirms local UI quieted; delayed results use wait text "Expected result" or wait <selector> instead of polling; strict disappearance uses wait absent <selector>.
   wait stable [quietMs] [timeoutMs] (defaults 500/10000) is the fallback for open/relaunch/navigation, or an intentionally-unsettled mutation -- not after a --settle whose diff already shows the change. Ambiguous find: add --first or --last.
 
@@ -296,129 +513,7 @@ Focus and visual truth:
   On Android TV and tvOS, if snapshot -i exposes a focused node, verify it with is focused <selector>.
   Use wait focused=true only when repeated snapshots preserve focus metadata for the app.
   If the app exposes only a surface view, or focus metadata is transient, use screenshot --overlay-refs, screenshot, or diff snapshot as visual truth and keep moving focus with tv-remote. On Vega OS, use the VVD display as visual truth until capture support lands.
-  Do not assume press/click @ref works on Android TV, tvOS, or Vega OS until the desired element is focused.`},debugging:{summary:`Targeted failure evidence without dumping stale context`,body:`agent-device help debugging
-
-Use this when behavior fails, hangs, times out, throws alerts, or needs runtime evidence.
-
-Logs:
-  Keep log windows small. Prefer clear, mark, reproduce, then path.
-    agent-device logs clear --restart
-    agent-device logs mark "before diagnostics retry"
-    agent-device press 'id="load-diagnostics"'
-    agent-device logs path
-  Do not cat a full stale log into agent context. Open or grep only the relevant window when needed.
-  logs clear --restart is the compact command to clear old logs and start a fresh capture; do not split it into logs stop, logs clear, logs start.
-  On iOS simulators, logs scope by bundle id and resolved app executable, so use this instead of raw simctl log stream predicates.
-  On iOS physical devices, logs clear --restart relaunches the session app through devicectl process launch --console so stdout/stderr can be captured.
-  For iOS simulator launch-time stdout/stderr, use --launch-console on the direct app launch:
-    agent-device open MyApp --platform ios --relaunch --launch-console ./artifacts/app.console.log
-  --launch-console is only for direct iOS simulator app launches, not URL opens.
-
-Events:
-  Use events for a compact session timeline without dumping full app logs.
-    agent-device events
-    agent-device events 50 100
-  Events preserve command names, status, durations, bounded device/app inventory previews, lifecycle outcomes, artifact basenames, and structural action details such as scroll distance/direction, safe refs, and coordinates. User-entered text, clipboard contents, push/event payloads, selector values, free-form flags/messages/paths, and raw unknown command arguments are omitted or replaced with content-free placeholders. --no-record suppresses action.recorded entries, but request start/finish entries still record command, status, and timing.
-
-Network:
-  Use network dump for recent session HTTP traffic parsed from app logs.
-    agent-device network dump --include headers
-    agent-device network dump 20 --include all
-  Use this instead of logs path when the question is request/response metadata.
-  network log is a supported alias, but network dump --include headers is the clearest plan form. Do not write network log headers.
-
-Audio:
-  Use audio probe when the question is whether a browser page, macOS session, iOS simulator, or Android emulator produced audible output during a short observation window.
-    agent-device audio probe start 10 1000 --platform web
-    agent-device audio probe status --platform web
-    agent-device audio probe stop --platform web
-    agent-device audio probe start 10 1000 --platform macos
-    agent-device audio probe start 10 1000 --platform ios
-    agent-device audio probe start 10 1000 --platform android
-  audio probe start uses duration seconds first, then bucket milliseconds. Results are compact rmsDbfs and peakDbfs arrays so agents can correlate audible moments with screenshots, actions, network entries, or frame samples.
-  On web, audio probe samples HTML media elements and URL-backed media may be routed through the probe AudioContext while observed.
-  On macOS hosts, audio probe samples host system audio through ScreenCaptureKit for macOS sessions, iOS simulators, and Android emulators. It requires Screen Recording permission and is system-audio evidence, not app-instrumented audio. Physical iOS and Android devices are not supported.
-
-Crash symbolication:
-  Crash routing:
-    Use logs when you need the lead-up timeline before a failure.
-    Use debug symbols when you have crash.ips/crash.log plus a matching dSYM/build directory and need the failing frame.
-    Use Xcode/LLDB when you need live state, breakpoints, variables, memory, or stepping.
-  Use debug symbols when you already have an Apple crash artifact and local dSYMs and need the failing code path, not a full log dump:
-    agent-device debug symbols --artifact crash.log --dsym MyApp.dSYM --out crash-symbolicated.log
-    agent-device debug symbols --artifact crash.ips --search-path ./build --out crash-symbolicated.ips
-  debug is intentionally narrow. Do not use it for logs, network/audio evidence, performance samples, recordings, traces, or React Native internals.
-  Apple support matches crash Binary Images / IPS usedImages UUIDs against dwarfdump --uuid output from .dSYM bundles, then writes a symbolicated artifact path and compact crash report: app/thread, exception or termination, top symbolicated frames, and first-frame finding. This is better than pasting crash logs because it keeps agent context small while preserving the artifact on disk for inspection.
-  Android Java/R8 mapping.txt and native ndk-stack/addr2line symbolication are not in this first debug symbols workflow; capture crash evidence with logs and use the Android toolchain externally for now.
-
-Alerts:
-  Native and platform dialogs:
-    agent-device alert wait 3000
-    agent-device alert accept
-    agent-device alert dismiss
-  Android support is snapshot-derived for runtime permission prompts and native app dialogs. iOS support is runner-derived for XCTest alerts, app-owned modal popups with native blocking markers, and blocking system dialogs. Use cheap alert get for an immediate check; use alert wait <short-ms> only when a prompt may appear after async work.
-  If alert says no alert but a sheet is visibly on screen, treat it as app-owned UI:
-    agent-device snapshot -i
-    agent-device press 'label="Allow"'
-  Do not use settings permission to answer a dialog already on screen. Reserve settings permission for setup/resetting permission state before a flow.
-
-Diagnostics and traces:
-  Use --debug for CLI/daemon diagnostic ids and log paths.
-  Use AGENT_DEVICE_EXEC_TRACE=1 when you need host-tool spawn timing without full debug streaming; it flushes the full request diagnostics file on successful requests that spawn host tools.
-  Open output includes Session state; JSON also includes runnerLogPath and requestLogPath.
-  For open timing under --debug, run open --debug --json and inspect requestLogPath for the open_timing event.
-  Session requests/<request-id>.ndjson holds daemon request diagnostics; session runner.log holds Apple runner/xcodebuild output.
-  Against a remote daemon the Diagnostics Log path is always local: the failing request's record is fetched to <state-dir>/remote-diagnostics/, and if it cannot be fetched the line reads "unavailable" with the reason instead of a daemon-host path.
-  daemon.log is global daemon lifecycle evidence, not the primary per-run log.
-  Use trace for low-level session diagnostics around one repro:
-    agent-device trace start ./traces/diagnostics.trace
-    agent-device press 'id="load-diagnostics"'
-    agent-device trace stop ./traces/diagnostics.trace
-  The trace path is positional. Do not use --path for trace start or trace stop.
-  Use perf xctrace only for Apple native CPU/profile or Animation Hitches artifacts:
-    agent-device perf cpu profile start --kind xctrace --template "Time Profiler" --out ./artifacts/app.trace
-    agent-device perf cpu profile stop --kind xctrace --out ./artifacts/app.trace
-    agent-device perf cpu profile report --kind xctrace --out ./artifacts/app-profile.json
-    agent-device perf trace start --kind xctrace --template "Animation Hitches" --out ./artifacts/hitches.trace
-    agent-device perf trace stop --kind xctrace --out ./artifacts/hitches.trace
-  perf xctrace keeps the .trace artifact on disk; CPU report returns a bounded weighted top-function summary. Do not dump .trace contents into context.
-  For Android native CPU/trace evidence, use perf artifacts instead of raw adb/simpleperf/perfetto output:
-    agent-device perf cpu profile start --kind simpleperf --out /tmp/cpu.perf.data
-    agent-device perf cpu profile stop --kind simpleperf
-    agent-device perf cpu profile report --kind simpleperf --out /tmp/cpu-report.json
-    agent-device perf trace start --kind perfetto --out /tmp/app.perfetto-trace
-    agent-device perf trace stop --kind perfetto
-  Treat native perf output as the agent evidence: for example, state=stopped, outPath=/tmp/app.perfetto-trace, sizeBytes=5392410, method=adb-shell-perfetto. The 5.3 MB raw trace stays in the artifact.
-  CPU reports return at most ten top functions in structured data and print five in default CLI output.
-  Use explicit perf frames, perf memory, perf cpu, or perf trace forms. Aggregate perf was removed in 0.21: bare perf, perf sample, perf metrics, and metrics fail with exact replacements.
-  Startup duration belongs to the open command's startup result; read it there.
-
-Memory diagnostics:
-  Use perf memory when the symptom is leak/growth/OOM suspicion and you need agent-readable evidence.
-    agent-device perf memory sample --json
-    agent-device perf memory snapshot --kind android-hprof --out ./artifacts/app.hprof
-    agent-device perf memory snapshot --kind memgraph --out ./artifacts/app.memgraph
-  Example sample shape:
-    {"metrics":{"memory":{"available":true,"totalPssKb":562958,"totalRssKb":570304,"topConsumers":[{"name":"Dalvik Heap","pssKb":213456}]}}}
-  Example default snapshot output:
-    Memory artifact (android-hprof): /tmp/app.hprof (42MB)
-  Prefer perf memory sample over raw dumpsys/leaks output for first-pass agent diagnosis: it keeps arrays bounded and returns only relevant memory evidence.
-  Prefer perf memory snapshot over printing heap/memgraph data: snapshots return path, size, kind, method, and support metadata while the large artifact stays on disk for external inspection.
-  Unsupported platforms return artifact.available=false with reason/hint; do not pretend a heap or memgraph was captured.
-
-Stabilizers:
-  Android animation-sensitive flows:
-    agent-device settings animations off
-    agent-device snapshot
-    agent-device settings animations on
-  Re-enable settings you changed before finishing.
-
-Text-entry quirks:
-  iOS Allow Paste cannot be exercised under XCUITest; prefill with clipboard write "some text" instead and test the system prompt manually.
-  Android Gboard handwriting/stylus UI can capture text in an IME-owned input instead of the app field. If fill reports that input was captured by the keyboard/IME, use the diagnostic targetInput/actualInput details, inspect keyboard status/get if needed, and switch or disable handwriting outside the command plan before retrying. Do not keep retrying fill/type against the same field while the IME owns focus. If the exact target changes but app-owned formatting prevents raw equality, fill succeeds with verification: "unconfirmed" plus target-bound requested/before/after evidence; inspect that evidence instead of retrying the same mutation.
-
-React Native internals:
-  If the question is about React Native performance, profiling, props, state, hooks, render causes, slow components, or rerenders, use help react-devtools instead of inferring from screenshots or logs.`},"react-devtools":{summary:`React Native performance, profiling, and component internals`,body:`agent-device help react-devtools
+  Do not assume press/click @ref works on Android TV, tvOS, or Vega OS until the desired element is focused.`},...S,"react-devtools":{summary:`React Native performance, profiling, and component internals`,body:`agent-device help react-devtools
 
 Use this for React Native performance/profiling and internals that the accessibility tree cannot expose: components, props, state, hooks, ownership, slow renders, and rerenders.
 
@@ -678,23 +773,7 @@ Rules:
   Do not hard-code Edit/Done/Add Widget or other SpringBoard label text into a plan as a fixed assumption; take them from the latest snapshot -i so the plan survives iOS version/locale differences.
   A real system permission alert can appear mid-flow; it composes with this workflow normally, so handle it with alert wait/accept/dismiss or by pressing the visible label like any other step.
   Prefer refs/selectors from the fresh snapshot for every step except the two documented coordinate fallbacks (empty-space long-press to enter edit mode, and the gallery search-result tap).
-  This topic covers what already works by opening SpringBoard as the session app. It does not yet cover keeping an app session open while alternating individual commands against SpringBoard, or Live Activity/Dynamic Island semantics; those land separately.`},foldable:{summary:`Foldable Apple devices: panels, pose, and which screen you are on`,body:`agent-device help foldable
-
-A foldable Apple device (iPhone Duo) carries two integrated panels, which Apple calls the outer display and the inner display. Only one is lit at a time, and which one is lit is the device pose.
-
-Screens are handled for you:
-  Each iOS simulator capture resolves the CoreDevice display table, captures the lit panel explicitly, and normalizes density with that panel's own point scale. Do not add a screen flag to the normal loop; there is none, because the lit panel is always the only capturable one: the dark panel yields an all-black PNG.
-  The two panels are different sizes (iPhone Duo: 466x678 points closed on the outer panel, 669x951 open on the inner). A pose change therefore invalidates every ref and coordinate. Re-snapshot after any pose change and never carry coordinates or refs across one.
-  Check which panel is lit before trusting a geometry claim: agent-device screenshot reports its point size, and 466x678 versus 669x951 says which panel you captured.
-
-Changing the pose:
-  agent-device fold closed | half-open | open
-  fold sends a private HID hinge event inside the selected simulator and then reads the hinge angle back from CoreDevice until it agrees: closed is 0 degrees, open is 180, and half-open is any angle between them (requested at 130 degrees). An angle in that interval only proves the category, so half-open is reported once two consecutive readings both fall inside it and agree within 0.5 degrees. The response reports the verified pose, the hinge angle, and the panel the device now lights with its native panel point size, marked coordinateSpace "native-panel". That point size is the panel's own geometry, not the next snapshot's viewport, so it cannot place a tap: the active app window can differ (a 669x951 inner panel hosts a 951x669 window). A hinge whose last reading is some other pose fails with COMMAND_FAILED and reason fold-pose-unverified, naming the angle CoreDevice still reports; a hinge seen half-open but never at rest fails with reason fold-pose-unsettled, naming the observed and previous angles. A single-panel simulator fails with UNSUPPORTED_OPERATION. A simulator scoped to a non-default set with --ios-simulator-device-set is refused before any hinge is touched, with UNSUPPORTED_OPERATION and reason unsupported-device-scope: the HID send honors the set, but CoreDevice's display inventory and hinge-angle readback resolve a scoped simulator as not found, so the pose could not be verified. Run fold without --ios-simulator-device-set (in the default set).
-  Expect a fold to take 10-16 seconds: each hinge read is a five-second devicectl stream, and half-open waits for the hinge to stop moving. Re-snapshot after every fold; refs and coordinates from before it are stale, and the command's message says so.
-  Timed motion: fold --keyframes '[{"atMs":0,"angle":0},{"atMs":5000,"angle":180}]'. Use 2–64 frames starting at 0ms, increasing integer timestamps up to 60000ms, and angles from 0 to 180. The last timestamp sets motion duration, excluding setup and verification. Equal angles hold; cancellation stops motion. See the fold examples in the command and Node API documentation for trajectories.
-
-  Requirements: an iOS simulator session on a foldable device and an Xcode toolchain with the iOS simulator SDK and foldable HID support (verified on Xcode 27.1). Device Hub and host Accessibility permission are not required. The command runs a small helper through simctl spawn for the session UDID; the helper is built once per Fold.m source hash and Xcode toolchain, cached under ~/.agent-device/fold-helper, and rebuilt only when the source or the toolchain changes. Build or dispatch failures are reported without a UI fallback. The app under test reads the resulting pose as UIHinge.status.
-  If a task asserts behavior for more than one pose, fold to each pose and re-snapshot, and report which poses the run covered.`},remote:{summary:`Direct proxy, cloud profiles, and remote config`,body:`agent-device help remote
+  This topic covers what already works by opening SpringBoard as the session app. It does not yet cover keeping an app session open while alternating individual commands against SpringBoard, or Live Activity/Dynamic Island semantics; those land separately.`},foldable:o,remote:{summary:`Direct proxy, cloud profiles, and remote config`,body:`agent-device help remote
 
 Remote connection providers use the same lifecycle:
   connect -> install/open -> commands -> close -> disconnect
@@ -888,126 +967,33 @@ Out of scope for agent-device web support:
 Rules:
   Do not claim web e2e CI exists unless a project workflow explicitly provides it.
   Do not use native mobile or desktop setup commands such as boot, apps, install, settings, alert, keyboard, perf, logs, or react-devtools for --platform web.
-  Keep browser plans session-scoped: open a URL, inspect refs, act on refs/selectors, verify with wait/get/is/snapshot, capture screenshot only when visual evidence is needed, then close.`},dogfood:{summary:`Exploratory QA workflow with reproducible evidence`,body:`agent-device help dogfood
-
-Use this when asked to dogfood, exploratory test, bug hunt, QA, or find issues in an app.
-
-Goal:
-  Find user-visible issues from runtime behavior. Do not read app source or invent findings from code.
-  Produce a concise report with severity, repro commands, expected/actual behavior, and evidence paths.
-
-Loop:
-  1. Identify target app/platform; ask only if missing.
-  2. Create output dirs and open the app. If auth or OTP is required, sign in or ask the user for the code.
-  3. Capture baseline snapshot -i and screenshot.
-  4. Map top-level navigation, then exercise primary flows and edge states.
-  5. For each issue, capture evidence and write the finding immediately, then continue.
-  6. Close the session and reconcile the report summary.
-  Keep stateful commands serial within the same session. Parallel runs can pollute text fields, focus, alerts, and navigation state.
-
-Coverage:
-  Navigation, forms, empty/error/loading states, offline or retry behavior, permissions, settings, accessibility labels, orientation/keyboard, and obvious performance stalls.
-  React Native warning/error overlays can be real findings or test blockers. Capture them, use react-native dismiss-overlay if unrelated, re-snapshot, and report them.
-  Expo Go/dev-client shells: use the provided exp:// or dev-client URL and record whether the shell, project load, or app UI is being tested. On iOS dogfood, prefer agent-device open "Expo Go" <url> when Expo Go is the known shell, then snapshot -i to confirm the project UI rather than the runner splash.
-  Android RN/Expo/Re.Pack dev server: direct Android localhost URL opens with a port auto-configure host reachability.
-  Categories: visual, functional, UX, content, performance, diagnostics, permissions, accessibility.
-  Severity: critical blocks a core flow/data/crashes; high breaks a major feature; medium has friction or workaround; low is polish.
-
-Evidence commands:
-  mkdir -p ./dogfood-output/screenshots ./dogfood-output/videos ./dogfood-output/traces
-  agent-device open <app> --platform ios
-  agent-device snapshot -i
-  agent-device screenshot ./dogfood-output/screenshots/initial.png
-  agent-device screenshot ./dogfood-output/screenshots/issue-001.png --overlay-refs
-  agent-device logs clear --restart
-  agent-device logs mark "issue-001 repro"
-  agent-device logs path
-  agent-device record start ./dogfood-output/videos/issue-001.mp4
-  agent-device record start ./dogfood-output/videos/benchmark.mp4 --hide-touches
-  agent-device record stop
-  agent-device close
-
-Evidence rules:
-  Interactive/behavioral issues need step screenshots and usually a repro video.
-  Static/on-load issues can use one screenshot; set repro video to N/A.
-  Use screenshot --overlay-refs when showing the tappable target or broken state helps repro.
-
-Report shape:
-  ./dogfood-output/report.md
-  Include date, platform, target app, session, scope, severity counts, and issues.
-  For each finding: ID, severity, category, title, affected flow/screen, repro commands, expected, actual, evidence files, notes.
-  Target 5-10 well-evidenced issues when available. If no issues are found, report coverage completed and residual risk instead of claiming the app is bug-free.
-
-Rules:
-  Findings must come from observed runtime behavior, not source reads.
-  After each mutation, use the --settle diff as evidence when available; otherwise re-snapshot.
-  Wait timeouts are integer milliseconds in the trailing positional: agent-device wait 'role=tab' 10000. Do not write duration suffixes such as 10s.
-  scroll takes a selector-less direction+amount form: agent-device scroll down 0.8. One gesture cannot travel further than 0.8 of the viewport axis, so a larger amount saturates rather than covering more ground; to cross several screens use agent-device scroll down --until <selector> or scroll bottom. Use --settle to wait for the UI to go quiet and get the settled diff.
-  Keep commands in the report reproducible; use selectors or refs from fresh snapshots, not guessed coordinates.
-  Prefer refs for exploration and selectors for deterministic replay.
-  Use logs, network, screenshot --overlay-refs, trace, perf frames, perf memory, native profiles, or react-devtools only when they add evidence to a specific issue.
-  Never delete screenshots, videos, traces, or report artifacts during a session.
-  Escalate to help debugging or help react-devtools when runtime symptoms require those tools.`},validate:{summary:`Engineering self-validation with device evidence and cleanup`,body:`agent-device help validate
-
-Use this when validating a code change, release candidate, performance fix, visual behavior, logging path, replay, or device-facing regression.
-
-Contract:
-  Prove the changed behavior through public agent-device surfaces. Do not validate against stale dist output, a retained stale daemon, or a runner built before the change.
-  Keep evidence reproducible: exact commands, target device/app, observed output, artifact paths, and cleanup status.
-
-Required freshness gate before device verification:
-  For a TypeScript runtime or CLI output change, start with pnpm build. For non-Android device verification, run pnpm clean:daemon next.
-  Before local Android verification, run pnpm build:android before pnpm clean:daemon so the bundled helpers match current source.
-  For an Apple runner change, run pnpm build:xcuitest and avoid inherited retained runners from older source. Do not build the Apple runner for TypeScript-only changes.
-  Use open --relaunch when startup state matters. Use a purpose-specific --session for multi-step validation.
-  CI may cache ~/.agent-device/apple-runner/derived with an exact key that includes the agent-device package and Xcode version. Runner reuse is authorized only by the cache metadata's content manifest, so a restore that fails validation rebuilds; prepare ios-runner already recovers one retryable non-connecting runner launch.
-
-Loop:
-  1. Build or prepare the changed surface with the repo command that owns it.
-  2. Open the target app/device state explicitly.
-  3. Use snapshot -i and press/fill/click/longpress --settle for UI-driving steps.
-  4. Use the settled diff as evidence when it shows the changed behavior; otherwise verify with wait/get/is/find, screenshot, logs, network, perf, or trace based on the claim.
-  5. Record timings, token/output size, screenshots/videos, logs, or perf artifacts only when they answer the validation question.
-  6. Close sessions and release leases before finishing.
-
-Evidence:
-  CLI/runtime freshness: pnpm build, pnpm clean:daemon, then agent-device --version or the command under test.
-  Apple runner freshness: pnpm build:xcuitest, then a live agent-device command on the target simulator/device.
-  Visual claim: screenshot, optionally screenshot --overlay-refs when target mapping matters.
-  Runtime/logging claim: logs clear --restart, logs mark, reproduce, logs path.
-  Network claim: network dump --include headers when headers are relevant.
-  Performance claim: perf frames, perf memory sample, native profile reports, or trace artifacts with bounded output.
-  Replay/regression claim: replay or test through the public command path.
-
-Report:
-  Summarize what changed, exact validation commands, pass/fail observations, artifact paths, and residual risk.
-  If live validation is blocked, state the blocker, device/session, and exact next command needed.`}};function E(e,t,n){let r=n.endsWith(`?`),i=r?n.slice(0,-1):n,a=/^[a-z-]+(?:\|[a-z-]+)+$/i.test(i),o=a||t.usageOverride!==void 0&&t.usageOverride.startsWith(`${e} ${i}`);return r?a?`[${i}]`:o?i:`[${i}]`:o?i:`<${i}>`}function D(e,t){return t.listUsageOverride?t.listUsageOverride:[e,...(t.positionalArgs??[]).map(n=>E(e,t,n))].join(` `)}function O(){return y()}function k(){return`agent-device help commands
+  Keep browser plans session-scoped: open a URL, inspect refs, act on refs/selectors, verify with wait/get/is/snapshot, capture screenshot only when visual evidence is needed, then close.`},...C};function A(e,t,n){let r=n.endsWith(`?`),i=r?n.slice(0,-1):n,a=/^[a-z-]+(?:\|[a-z-]+)+$/i.test(i),o=a||t.usageOverride!==void 0&&t.usageOverride.startsWith(`${e} ${i}`);return r?a?`[${i}]`:o?i:`[${i}]`:o?i:`<${i}>`}function j(e,t){return t.listUsageOverride?t.listUsageOverride:[e,...(t.positionalArgs??[]).map(n=>A(e,t,n))].join(` `)}function M(){return w()}function N(){return`agent-device help commands
 
 Full command catalog. Use agent-device help <command> for exact flags and behavior.
 
-${I(n().map(e=>{let t=c(e);return{name:e,schema:t,usage:D(e,t)}}))}
+${B(n().map(e=>{let t=l(e);return{name:e,schema:t,usage:j(e,t)}}))}
 
-${N(`Device Selection (shared by device commands; help <command> lists each command's flags):`,j(o))}
+${L(`Device Selection (shared by device commands; help <command> lists each command's flags):`,F(i))}
 
-${N(`Global Flags:`,j(i))}
+${L(`Global Flags:`,F(s))}
 
-${F(`Configuration:`,x)}
+${z(`Configuration:`,E)}
 
-${P(`Environment:`,S)}
+${R(`Environment:`,D)}
 
-${F(`Examples:`,C)}
-`}function A(){return O()}function j(e){return r().filter(t=>e.has(t.key)&&t.usageLabel!==void 0&&t.usageDescription!==void 0)}function M(e,t){return t?e.map(e=>{let n=t[e.key];return n===void 0?e:{...e,usageDescription:n}}):e}function N(e,t){return P(e,t.map(e=>({label:e.usageLabel??``,description:e.usageDescription??``})))}function P(e,t){if(t.length===0)return`${e}\n  (none)`;let n=Math.max(...t.map(e=>Math.min(e.label.length,26)))+2,r=[e];for(let e of t){let t=e.label.length<=26?e.label.padEnd(n):`${e.label}  `;r.push(`  ${t}${e.description}`)}return r.join(`
-`)}function F(e,t){return t.length===0?`${e}\n  (none)`:[e,...t.map(e=>`  ${e}`)].join(`
-`)}function I(e){return P(`Commands:`,e.map(e=>({label:e.usage,description:e.schema.text.summary})))}function L(e){let t=B(e);if(t)return t;let n=l(e);if(!n)return null;let r=v(e,n),i=M(j(new Set(n.allowedFlags??[])),n.flagDescriptionOverrides),o=[];i.length>0&&o.push(N(`Command flags:`,i));let s=o.length>0?`\n\n${o.join(`
+${z(`Examples:`,O)}
+`}function P(){return M()}function F(e){return r().filter(t=>e.has(t.key)&&t.usageLabel!==void 0&&t.usageDescription!==void 0)}function I(e,t){return t?e.map(e=>{let n=t[e.key];return n===void 0?e:{...e,usageDescription:n}}):e}function L(e,t){return R(e,t.map(e=>({label:e.usageLabel??``,description:e.usageDescription??``})))}function R(e,t){if(t.length===0)return`${e}\n  (none)`;let n=Math.max(...t.map(e=>Math.min(e.label.length,26)))+2,r=[e];for(let e of t){let t=e.label.length<=26?e.label.padEnd(n):`${e.label}  `;r.push(`  ${t}${e.description}`)}return r.join(`
+`)}function z(e,t){return t.length===0?`${e}\n  (none)`:[e,...t.map(e=>`  ${e}`)].join(`
+`)}function B(e){return R(`Commands:`,e.map(e=>({label:e.usage,description:e.schema.text.summary})))}function V(e){let t=W(e);if(t)return t;let n=u(e);if(!n)return null;let r=y(e,n),i=I(F(new Set(n.allowedFlags??[])),n.flagDescriptionOverrides),o=[];i.length>0&&o.push(L(`Command flags:`,i));let s=o.length>0?`\n\n${o.join(`
 
 `)}`:``;return`Usage:
   agent-device ${r}
 
 ${a(n.text)}${s}
-`}function R(e){return L(u(e))}function z(){return Object.keys(T)}function B(e){let t=T[e];return t?`${V(e,e===`commands`?k():t.body)}
+`}function H(e){return V(d(e))}function U(){return Object.keys(k)}function W(e){let t=k[e];return t?`${G(e,e===`commands`?N():t.body)}
 
 Related:
   agent-device help <command>   command-specific flags
   agent-device help manual-qa   routine QA loop
   agent-device help workflow    full automation reference
-`:null}function V(e,t){let n=`agent-device help ${e}`;return t.startsWith(n)?`agent-device ${s()} — ${e}${t.slice(n.length)}`:t}export{R as i,b as n,z as r,A as t};
+`:null}function G(e,t){let n=`agent-device help ${e}`;return t.startsWith(n)?`agent-device ${c()} — ${e}${t.slice(n.length)}`:t}export{H as i,T as n,U as r,P as t};