@swmansion/argent 0.32.0 → 0.32.1-next.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swmansion/argent",
-  "version": "0.32.0",
+  "version": "0.32.1-next.1",
   "mcpName": "io.github.software-mansion/argent",
   "description": "MCP server for iOS Simulator and Android Emulator control",
   "license": "Apache-2.0",

package/rules/argent.md

@@ -1,198 +1,34 @@
 ---
-description: Argent iOS Simulator and Android Emulator Agent, always-on guidance for methodology and tools for working with, interacting, testing and profiling mobile app work
+description: Always-on Argent rules for driving, testing and profiling apps on simulators, emulators, phones, TVs and Chromium
 alwaysApply: true
 ---
 
-<description>
-If argent is installed and configured in this environment, its MCP tools are the preferred form of interaction with the application for iOS simulator, physical iPhone, Android emulator, Chromium (CDP) app, and Vega (Amazon Fire TV) device control; otherwise see `<availability_check>` below before attempting any argent workflow. A "Chromium (CDP) app" is any Chromium runtime exposing a Chrome DevTools Protocol endpoint: an Electron app, or any Chromium-family browser (Chrome/Brave/Edge) launched with `--remote-debugging-port`; all are driven through the same tool surface and tagged `platform: "chromium"`. A "Vega device" is a virtual device (VVD) or physical unit, driven by tv-remote (D-pad) and tagged `platform: "vega"`. Physical iPhones (iPads are not supported) appear in `list-devices` as iOS entries with kind `"device"`; they are driven over USB cable only, and the on-device runner's signing is auto-detected from the Mac's keychain (`ARGENT_IOS_TEAM_ID` overrides). Automation there is app-scoped: `launch-app` registers the target app before anything else can act. Read `argent-ios-device-setup` to get one connected and `argent-ios-device-interact` before interacting.
-Running MCP server and managing the Argent toolkit utilises `argent` command - if asked use `argent --help` for reference.
-To check current version of MCP server run `argent --version` command.
+Argent - general rules:
 
-Use cases:
-
-- User mentions iOS simulator, Android emulator, device, or app interaction
-- The app user is working with is a mobile application which can be run in a simulator/emulator
-- Any tapping, swiping, typing, screenshotting, or inspecting a running app
-- Any code change that affects visible mobile UI, layout, styling, copy, navigation, or screen composition
-- Any request to execute manual QA, UI QA, or visual behavior validation for a mobile app
-- Running, debugging, or testing a React Native app (iOS, Android or Vega)
-- Profiling performance or diagnosing re-renders in a React Native app (iOS or Android)
-- Running, debugging, or testing a Chromium (CDP) app: an Electron app (boot with `boot-device` + `electronAppPath`) or a Chromium browser exposing CDP (auto-discovered on port `9222` / `ARGENT_CHROMIUM_PORTS`); on Chromium scroll with `gesture-scroll` and drag with `gesture-drag`; `gesture-swipe` is touch-only
-  </description>
+- do not derive tap coordinates from screenshot pixels; use inspection tools that give coordinates
+- use the platform the user named; otherwise prefer a device `list-devices` shows already running, and don't default to iOS; in a single-platform project boot that platform.
+- if tap fails twice, stop retrying and re-run a discovery tool
+- Prefer mcp-tool calls over raw commands like `xcrun` or `adb`; use them as fallback.
+- Interaction tools return screenshot and element tree automatically.
+- prefer `launch-app` or `open-url` than tapping icons on home screen.
+- If a task can require a saved e2e test, load `argent-create-e2e` (`argent-qa-e2e` for acceptance tests) before the first launch or in-app action; recording is not retroactive.
+- Load the matching `argent-*` skill before React Native build/debug, profiling, a physical phone or a TV.
+- Do not stop simulator servers when a task finishes: the next task reuses them. Call `stop-all-simulator-servers` when the user asks to clean up or ends the session, or when a skill tells you to recycle a device's services, with devices this session used. One tool-server is shared by every other agent, so unscoped call tears down their devices too. Never stop a Metro the user started unless they ask.
+- Use the `await-ui-element` tool to block until the UI settles instead of polling using screenshot.
+- The `argent` CLI manages the toolkit: `argent --help` lists commands, `argent --version` shows the installed version.
 
 <availability_check>
-<important>Run this check once per session, before the first argent tool call or `argent` command. Do not re-probe before later calls.</important>
-
+Run this check once per session. Do not re-probe before later calls.
 Confirm argent is available:
 
-1. Are `mcp__argent__*` tools in your tool list? If none are present, argent is not available.
-2. If still unsure, run `command -v argent`. A non-zero exit means the CLI is not on PATH.
+1. Are `mcp__argent__*` tools in your tool list? If none, argent is not available.
+2. If unsure, run `command -v argent`. Non-zero exit = the CLI is not on PATH.
 
 If argent IS available, ignore the rest of this block and follow this rule normally.
 
-If argent is ABSENT, treat it as an expected state, not an error to retry. Do not call `mcp__argent__*` tools, do not run `argent` commands, and do not attempt any argent workflow. Tell the user once, and ask if you should continue without argent:
+If argent is ABSENT, treat it as an expected state, not an error to retry. Do not call `mcp__argent__*` tools, do not run `argent` commands, do not attempt any argent workflow.
+Tell the user once, and ask if you should continue without argent:
 
 > Argent isn't installed in this environment. To enable the mobile/Chromium tooling this repo is configured for, run `npx @swmansion/argent@latest init -y` (or `npm i -g @swmansion/argent@latest && argent init -y`).
-> </availability_check>
-
-<tapping_rule>
-<important>**Never** derive tap coordinates from screenshot pixels</important>
-Interaction tools (`gesture-tap`, `gesture-swipe`, `keyboard`, `button`, `launch-app`, `open-url`, `run-sequence`, `await-ui-element`, …) return the screen **after** the action: a screenshot AND the accessibility element tree (`--- Elements after action (describe) ---`, the same format `describe` prints, with normalized 0–1 frames). Take tap coordinates from that tree: the centre of the element's frame (`x + width/2`, `y + height/2`). You do not need a separate discovery call before a tap when the last result already lists the target.
-
-Call a discovery tool yourself only when you have no fresh tree for the current screen: before the first action on a screen you have not touched yet, after waiting for something to load without `await-ui-element`, or when the last tree did not list your target. Preferred tools are, in order:
-
-- `describe` - native app-level components and safely targetable foreground apps (iOS and Android).
-- `native-describe-screen` - accessibility screen description via injected native devtools (iOS only)
-- `debugger-component-tree` - react-native specific components
-
-`native-user-interactable-view-at-point` / `native-view-at-point` are follow-up diagnostics once you already have a candidate point (iOS only).
-
-If a **tap fails twice** at the same coordinates, **stop retrying** and re-run a discovery tool.
-
-If `describe` fails, **read the exact error before reacting**, follow the recovery guidance in `argent-device-interact` to choose the correct next action.
-
-Before starting to interact with the app, read the `argent-device-interact` skill first.
-</tapping_rule>
-
-<device_selection_rule>
-Before booting, running, or interacting with any app, call `list-devices` first - prefer running devices.
-
-Decision order:
-
-1. **Explicit user intent** - choose the user named platform or device. Look for words "simulator" and "emulator".
-2. **Prefer a running device.** iOS simulators - state `Booted` and Android devices - `state: "device"` come first in `list-devices`; Chromium (CDP) apps appear as `platform: "chromium"`, `state: "Running"`. A cabled physical iPhone (`platform: "ios"`, `kind: "device"`, `state: "connected"`) is listed first too, but it is not a running simulator: never pick it because it is there. Use it only when the user names the phone, a physical or real device, or hardware testing. With nothing else booted, boot a simulator or ask which target the user means.
-3. **Single-platform project:** (per `argent-environment-inspector` flags `is_native_ios`/`is_native_android`, or RN with only one platform configured) → boot that platform.
-   </device_selection_rule>
-
-<skill_reading_rule>
-<important>Always read relevant skills for guidance before executing argent-mcp tool - read skill_routing reference</important>
-</skill_reading_rule>
-
-<general_rules>
-
-- All simulator/emulator interactions go through argent MCP tools; never use `xcrun simctl`,
-  raw `curl` to simulator ports, or the simulator-server binary directly.
-- Before calling any gesture tool for the first time, use ToolSearch to load its schema.
-- Interaction tools (`gesture-tap`, `gesture-swipe`, `gesture-pinch`, `gesture-rotate`, `gesture-custom`, `launch-app`, etc.) return a screenshot and the element tree automatically.
-  Call `screenshot` or `describe` separately only for a baseline before any action or after a delay.
-- Always open apps with `launch-app` or `open-url`; never tap home screen icons.
-- If a task can require a saved e2e test, choose `argent-create-e2e` or `argent-qa-e2e` before the first launch or in-app action. Start the recorder before walking the path; recording is not retroactive.
-- Always use `run-sequence` when performing multiple sequential device actions where you don't need to observe the screen between steps. More in `argent-device-interact` skill.
-- Do not stop simulator servers when a task finishes: the next task reuses them, and stopping them makes its
-  first device action start cold again. Call `stop-all-simulator-servers` when the user asks to clean up or
-  ends the session, or when a skill tells you to recycle a device's services (e.g. before a QA proof pass).
-  Always pass `devices: [...]` naming the devices this session used. One tool-server is shared by every other
-  agent using this argent install, so an unscoped call tears down their devices too; reserve that form for a
-  deliberate machine-wide cleanup.
-  Never stop a Metro the user started unless they ask (`stop-metro`, specify the port if not 8081).
-- If tools provided by mcp-server are not sufficient and action can be done using `xcrun`, `adb`, or other commands, use the command. Examples: changing device options, performing a device action such as lock, shake, etc. Not on a physical iPhone.
-- When waiting for an action, do not call `screenshot` repeatedly without a proper wait mechanism. Use the `await-ui-element` tool to block until the UI settles (e.g. wait for an element to become `visible`/`hidden`, or to contain expected `text`) instead of polling.
-  </general_rules>
-
-<react_native_detection>
-Project type is determined by the `argent-environment-inspector` subagent (see `subagents` section).
-When the subagent result is available, use its `is_react_native` field as the authoritative
-source; do not re-inspect files manually.
-
-If the subagent has not run yet and project type is unknown, run it first before proceeding. Always use subagents if available to run `gather-workspace-data` data tool, if possible do not run yourself.
-
-When `is_react_native` is true: load `argent-react-native-app-workflow` skill. Use `debugger-component-tree` for element discovery - if the responses are large or unhelpful, try `describe`.
-</react_native_detection>
-
-<skill_routing>
-Load the matching skill before starting work and executing tools from argent-mcp: skills contain the full step-by-step
-procedure and edge-case handling for each workflow.
-
-PLATFORM DETECTION
-If the user did not specify a platform, call `list-devices` first and pick the booted target; do not default to iOS. Vega (Amazon Fire TV) devices appear as `platform:"vega"`, when present load `argent-tv-interact`
-
-iOS SIMULATOR SETUP
-Skill: `argent-ios-simulator-setup`
-When: Beginning a task that involves the iOS simulator, no simulator booted yet, need UDID or simulator-server.
-
-ANDROID EMULATOR SETUP
-Skill: `argent-android-emulator-setup`
-When: Beginning a task that involves the Android emulator, no emulator running yet, need an adb serial, or about to install an APK.
-
-PHYSICAL iPHONE (USB)
-Skills: `argent-ios-device-setup` (cable, trust, signing), then `argent-ios-device-interact` (the app-scoped interaction contract)
-When: The user names a physical iPhone, a real device, or hardware, or the target `list-devices` iOS entry has kind `"device"`. Never for a simulator, and never because a cabled phone is listed first. On hardware every interaction starts with `launch-app`; `paste`, `settings-permissions`, `rotate`, `shake`, screen recording, `debugger-*`, `react-profiler-*`, `native-profiler-*` and `native-*` do not exist there.
-Prompt keywords: physical iPhone, real device, on my phone, USB, hardware
-
-TAPPING, SWIPING, TYPING, GESTURES, SCREENSHOTS, SCROLLING
-Skill: `argent-device-interact`
-When: Performing touch interactions, typing, pressing hardware buttons, launching/restarting apps, opening URLs, rotating or folding the device, taking standalone screenshots, or verifying a visible UI code change. Covers phone/tablet iOS and Android simulators and emulators plus Chromium (CDP) apps: for any TV target use the TV skill below, and for a physical iPhone use the entry above.
-
-APP PERMISSIONS (GRANT / DENY / RESET WITHOUT THE SETTINGS UI)
-Skill: `argent-settings-permissions`
-When: You must change an app runtime permission (camera, microphone, photos, contacts, notifications, calendar, location, location-always, media-library, motion, reminders) that the app itself can't flip: pre-authorize or deny it before the app asks, re-enable one the user already denied (iOS never re-prompts), or reset it so the first-run dialog reappears. Works on the iOS simulator and Android emulator/device. Do NOT use it when the app has an in-app toggle or is showing its own permission dialog; tap that instead (see `argent-device-interact`); nor for permissions/settings outside that list.
-Prompt keywords: permission, grant, deny, revoke, reset permission, privacy, camera access, location access, TCC
-
-TV INTERACTION (APPLE TV / ANDROID TV / FIRE TV)
-Skill: `argent-tv-interact`
-When: Any TV target: a `list-devices` entry with `runtimeKind: "tv"` (Apple TV simulator or Android TV emulator) or `platform:"vega"` / `kind:"vvd"` (Amazon Fire TV / VVD), or the user mentions Apple TV / tvOS / Android TV / leanback / Vega / Fire TV. A TV UI is focus-driven, not touch-driven: drive it with `describe` (read focus) + `tv-remote` (D-pad presses) + `keyboard` (type); `gesture-*` tools do NOT apply. Covers booting the target, app lifecycle, focus navigation, typing, screenshots, and (Vega) VVD lifecycle + Fast Refresh + JS-runtime debugging (evaluate, console logs, network inspector).
-Prompt keywords: apple tv, tvos, android tv, leanback, vega, fire tv, vvd, d-pad
-Saved artifacts: on Vega, a replayable path is `argent-create-e2e` and an acceptance-criteria regression test is `argent-qa-e2e`; both record D-pad navigation as `tool: tv-remote` steps. Apple TV and Android TV have no e2e support; report that limitation.
-
-SCREENSHOT DIFF & VISUAL REGRESSION
-Skill: `argent-screenshot-diff`
-When: Explicit visual regression, screenshot diff, compare screenshots, before/after visual comparison requests, or visible UI changes where stable pixel comparison would add useful evidence.
-
-SCREEN RECORDING (VIDEO CAPTURE)
-Skill: `argent-screen-recording`
-When: The user wants an mp4 of an interaction, animation, or bug reproduction. Use `argent-create-e2e` instead for a replayable sequence.
-Prompt keywords: record, recording, screen recording, video, capture video, clip, mp4
-
-RUNNING / BUILDING / DEBUGGING REACT NATIVE APP
-Skill: `argent-react-native-app-workflow`
-When: Project is react-native, starting Metro or running the iOS or Android app, build failures, pod issues, lost Metro connection, reading logs, reloading JS bundle, reinstalling app.
-
-JS EVALUATION, METRO CONNECTION, REACT NATIVE
-Skill: `argent-metro-debugger`
-When: evaluating expressions, inspecting React component tree at source level, finding element placement via `debugger-component-tree`.
-
-REACT APP & COMPONENT PROFILING
-Use skill: `argent-react-native-profiler`
-When: To measure performance of specific components, to find app-wide bottlenecks. Investigating re-renders or CPU hotspots, producing ranked performance reports.
-
-NATIVE PROFILING
-Use skill: `argent-native-profiler`
-When: Profiling native performance (CPU hotspots, UI hangs, memory leaks). iOS only today; Android on the roadmap. Useful as a reference for platform-specific investigation when running dual profiling via `argent-react-native-profiler`.
-
-PERFORMANCE OPTIMIZATION
-Use skill: `argent-react-native-optimization`
-When: App feels slow, user asks to optimize, reducing bundle size, improving startup time, fixing re-renders, optimizing lists/images/navigation, or any performance-related task. This is the entry-point skill for all performance work; it delegates to `argent-react-native-profiler` for measurement.
-
-INTERACTIVE UI TESTING (ONE-OFF, NOT SAVED)
-Skill: `argent-test-ui-flow`
-When: Running a one-off interact → screenshot → verify check with no saved regression artifact.
-
-RECORDING & REPLAYING E2E TESTS
-Use skill: `argent-create-e2e`
-When: Saving or replaying a repeatable path for profiling, A/B comparison, retry, or reuse. For acceptance-driven regression tests, use `argent-qa-e2e`.
-Prompt keywords: record e2e, replay e2e, run e2e, flow, repeat, test X times
-
-GENERATED QA REGRESSION TESTS
-Use skill: `argent-qa-e2e`
-When: Saving a test case, ticket, or acceptance criteria as a repeatable regression test. Requires stable evidence and two unchanged full passes. iOS, Android, Chromium, and Vega (D-pad navigation records as `tool: tv-remote` steps); not Apple TV or Android TV.
-Prompt keywords: QA test, regression test, test case, automate an e2e test, write an e2e test, generate a test
-Routing: one-off check → `argent-test-ui-flow`; saved path → `argent-create-e2e`; saved acceptance test → `argent-qa-e2e`.
-
-PROPOSING DESIGN VARIANTS FOR HUMAN SELECTION
-Use skill: `argent-lens`
-When: The user asks for design alternatives / options / A-B choices for a screen or component, or you have produced more than one candidate look for an element and want a human to pick before committing. Covers the build → navigate → screenshot → propose_variant loop and the single blocking await_user_selection call. (Gated behind the `argent-lens` flag, off by default; run `argent enable argent-lens` first.)
-Prompt keywords: variant, design option, alternative, A/B, "let me pick", "show me options"
-</skill_routing>
 
-<subagents>
-ENVIRONMENT INSPECTION AT SESSION START
-Use subagent: `argent-environment-inspector`
-When:
-- Environment context of the project is not yet known
-- No "Project Environment" section exists in project memory / `MEMORY.md` or you lack information about basic setup workflows
-- Need to determine build commands, startup scripts, metro port, platform support, or QA tooling
-  If the subagent already ran this session (result in memory), use that context directly; do NOT re-run.
-Rules:
-  - Run the `argent-environment-inspector` subagent if possible. Never call `gather-workspace-data` yourself - do only if subagent is not available.
-  - The main agent is responsible for persisting the subagent's JSON result to project memory
-</subagents>
+</availability_check>

package/skills/argent-android-emulator-setup/SKILL.md

@@ -5,26 +5,18 @@ description: Set up and connect to an Android emulator using argent MCP tools. U
 
 ## 1. Prerequisites
 
-- **Android SDK Platform Tools** on PATH: provides `adb`.
-- **Android Emulator** on PATH: needed to boot AVDs. If you will only use an already-running emulator or a physical device, adb alone is sufficient.
-- An AVD created via Android Studio or `avdmanager create avd`.
-
-Verify with `adb version` and `emulator -list-avds`.
+The Android SDK (platform tools and emulator) and an AVD, created in Android Studio or with `avdmanager create avd`. If `list-devices` returns no Android devices and no `avds`, either no AVD exists or Argent can't find the SDK. Then run `argent config set android.sdkRoot <sdk-path>` and call `list-devices` again after a minute: a failed SDK lookup is cached that long. Exporting `ANDROID_HOME` in your shell doesn't reach the tool-server that is already running.
 
 ## 2. Setup
 
-1. **Find a ready device**: call `list-devices`. Filter for entries with `platform: "android"`. Ready devices (`state: "device"`) come first. Pick the first `serial` (e.g. `emulator-5554`) unless the user specified one. If the result has a `hint` about the adb server, prefix every `adb` command that you run yourself, as the hint shows.
-2. **Boot if needed**: if nothing Android is ready, call `boot-device` with `avdName: <name>` from the same call's `avds` list. The tool transparently picks hot vs cold boot: it probes the AVD's `default_boot` snapshot, restores it under a tight deadline when usable, and falls back to a full cold boot otherwise. Hot path is typically ~30s; cold path takes 2–10 min. On any stage failure the tool kills the emulator process it started so your next call starts from a clean state.
-3. **Metro (for React Native)**: once a device is up, run `adb -s <serial> reverse tcp:8081 tcp:8081` so the device can reach Metro on your host. Repeat if the device restarts.
+1. **Find a ready device**: call `list-devices`. Filter for entries with `platform: "android"`. Ready devices (`state: "device"`) come first. If the user named a device, use it. Otherwise pick the first `kind: "emulator"` that fits the task. Take a physical phone (`kind: "device"`) only when the user asks for one. If the result has a `hint` about the adb server, prefix every `adb` command that you run yourself, as the hint shows.
+2. **Boot if needed**: if no such emulator is ready, call `boot-device` with `avdName: <name>` from the same call's `avds` list. `avds` doesn't mark TV images: for a TV task, pick the AVD by its name.
 
 ## 3. Using the device
 
-Pass the Android serial as `udid` to the unified interaction tools: `gesture-tap`, `gesture-swipe`, `describe`, `screenshot`, `launch-app`, `keyboard`, etc. Dispatch is automatic based on the id shape. See `argent-device-interact` for platform-neutral interaction tooling and the Android-specific gotchas section at the bottom of that skill.
+Pass the Android serial as `udid` to the same interaction tools as on iOS. See `argent-device-interact` for interaction tooling and the Android notes at the bottom of that skill. If a React Native app can't reach Metro, see `argent-metro-debugger` §1.
 
 ## 4. Notes
 
-- **Android TV / leanback AVDs** boot through this exact flow (same `boot-device` + `avdName`), but they are **focus-driven, not touch-driven**; do not use `gesture-tap`/`gesture-swipe` on them. `list-devices` tags a leanback device with `runtimeKind: "tv"` (detected via the system feature list, not the serial: a TV AVD's serial looks just like a phone's). When you see `runtimeKind: "tv"`, drive it with the focus-driven tools (`describe` / `tv-remote` / `keyboard`) and the `argent-tv-interact` skill (it covers Android TV as well as Apple TV, including the full TV setup flow).
-- Serials are the adb device id. iOS UDIDs and Android serials are not interchangeable, but you do NOT need to tell the tools which platform: dispatch is automatic.
-- `describe` on Android returns a shallower tree than iOS (no accessibility-service equivalent), but covers most tap-target discovery.
-- `reinstall-app` on Android always installs with `-g` so first-launch runtime permissions are pre-granted.
+- **Android TV / leanback AVDs** boot through this exact flow, but `list-devices` tags them `runtimeKind: "tv"` and they are focus-driven: use the `argent-tv-interact` skill, not the gesture tools.
 - To stop the emulator, run `adb -s <serial> emu kill` from a shell (clean shutdown). Never `pkill -9`/`kill -9` qemu: a hard kill leaves the userdata image dirty, after which cold boots can hang for many minutes doing recovery (runaway writes, `boot_completed` never flips). If an image gets into that state, boot once with `-wipe-data` to reset it.

package/skills/argent-create-e2e/SKILL.md

@@ -13,7 +13,7 @@ For a saved QA test case, ticket, or acceptance criterion, load `argent-qa-e2e`
 
 - Before creating or changing an e2e test, read [Live authoring](references/live-authoring.md) completely.
 - When polishing, composing, or manually reviewing YAML, read [E2E YAML](references/e2e-yaml.md). For Vega, read its platform limits before recording remote or keyboard tools.
-- E2E tests run on physical iPhones (an iOS `list-devices` entry with kind `"device"`), but replay never auto-binds one, even when no simulator is booted: pass the phone's udid as `device` (CLI `--device`), and only a `connected` phone can run. `pinch`/`rotate` steps run there as two-finger gestures, in apps drawn in portrait. On hardware the runner tree is the `describe` tree: same ids and roles, no UIView hierarchy. See `argent-ios-device-interact` for the hardware contract.
+- E2E tests run on physical iPhones (an iOS `list-devices` entry with kind `"device"`), but replay never auto-binds one, even when no simulator is booted: pass the phone's udid as `device` (CLI `--device`), and only a `connected` phone can run. `pinch`/`rotate` steps need the app drawn in portrait. On hardware the runner tree is the `describe` tree: same ids and roles, no UIView hierarchy. See `argent-ios-device-interact` for the hardware contract.
 - On capture warnings, raw coordinates, unavailable trees, mistimed transitions, overlays, or replay failures, read [Reliability and recovery](references/reliability-and-recovery.md).
 
 ## Non-negotiable rules

package/skills/argent-create-e2e/references/e2e-yaml.md

@@ -67,22 +67,22 @@ YAML selectors and live discovery use different screen projections:
 
 | Platform | Runner tree                                               | `describe` / `await-ui-element` | Important difference                                   |
 | -------- | --------------------------------------------------------- | ------------------------------- | ------------------------------------------------------ |
-| iOS      | projected UIView hierarchy                                | accessibility tree              | `native-full-hierarchy` is raw; nodes and roles differ |
+| iOS sim  | projected UIView hierarchy                                | accessibility tree              | `native-full-hierarchy` is raw; nodes and roles differ |
 | Android  | full accessibility hierarchy                              | trimmed interactables           | Discovery can omit testID containers or merge nodes    |
 | Chromium | filtered DOM nodes with id, label, value, click, or focus | shorter DOM walk                | Projections and node limits differ (12,000 vs. 5,000)  |
 | Vega     | toolkit page source                                       | same source                     | Same elements, different shape                         |
 
-On iOS, Android, and Chromium, an id absent from `describe` can still resolve in an e2e test. Verify it in a scratch fragment. Chromium exposes password fields to the runner as `[password]`; select them by id or role.
+On an iOS simulator, Android, and Chromium, an id absent from `describe` can still resolve in an e2e test. Verify it in a scratch fragment. Chromium exposes password fields to the runner as `[password]`; select them by id or role.
 
-The recorder rechecks each successful `await-ui-element` against the runner tree. Follow any `message` warning and replay each conversion. On Vega, a mismatch usually means the screen changed. A `text` check can also select different elements from the same source. See [Live waits and checks](live-authoring.md#live-waits-and-checks).
+For the recorder's cross-tree warning on a recorded wait, see [Live waits and checks](live-authoring.md#live-waits-and-checks). On Vega both read the same source, so a mismatch usually means the screen changed or a `text` check selected a different element.
 
-**On iOS, a `launch:` step also decides which app the runner reads.** A successful `launch:` pins later runner-tree reads to that app, so a read probes only that app instead of fanning out over every connected one to find the frontmost. A pinned read still refuses, naming the reason, when the app has no foreground presence left, when it stops answering after an earlier read got through, when its devtools connection dropped, or when the pinned id is a `com.apple.*` system app.
+**On an iOS simulator, a `launch:` step also decides which app the runner reads.** A successful `launch:` pins later runner-tree reads to that app, so a read probes only that app instead of fanning out over every connected one to find the frontmost. A pinned read still refuses, naming the reason, when the app has no foreground presence left, when it stops answering after an earlier read got through, when its devtools connection dropped, or when the pinned id is a `com.apple.*` system app.
 
 Any raw `tool:` step ends the pin, because its effect on the screen is opaque to the runner, and reads auto-detect the frontmost app again until the next `launch:` re-pins. A tool that cannot change the foreground app leaves the launched id as an unpinned fallback, which takes the read only when auto-detection times out and the launched app vouches for itself with a probe of its own. `launch-app`, `restart-app`, `reinstall-app`, `open-url`, and `button` drop even that; `launch-app` and `restart-app` replace it with the app they just started, still unpinned. Nested `run:` fragments inherit both the pin and its clearing.
 
-So on iOS recording and replay can read different apps, not only different projections: recording has no run state and always auto-detects the frontmost connected app, while a replay read between a `launch:` and the next raw `tool:` step reads the launched app.
+So on an iOS simulator, recording and replay can read different apps, not only different projections: recording has no run state and always auto-detects the frontmost connected app, while a replay read between a `launch:` and the next raw `tool:` step reads the launched app.
 
-**On iOS, never copy a `role` from `describe` into a YAML selector.** The runner derives iOS roles from the UIView class name and `describe` from accessibility traits, so a React Native `Pressable` (class `RCTView`) is `AXGroup` to the runner and `AXButton` to `describe`. Select on `id`/`text`, or confirm the role against the runner's own tree.
+**On an iOS simulator, never copy a `role` from `describe` into a YAML selector.** The runner derives iOS roles from the UIView class name and `describe` from accessibility traits, so a React Native `Pressable` (class `RCTView`) is `AXGroup` to the runner and `AXButton` to `describe`. Select on `id`/`text`, or confirm the role against the runner's own tree.
 
 When several nodes match, the directive decides:
 
@@ -118,7 +118,7 @@ Directives stop the test on failure and skip later steps. The available directiv
 - iOS: unfolded, the UI is landscape. `swipe` and `scroll-to` directions and the reading order stay as the user sees the UI. Coordinates stay in the space of the `describe` frames.
 - iOS: a fold between two angles that are not `closed` or `open` can keep the current panel. The step passes, and the report names the panel. To change panels, fold to `closed` or `open`.
 
-Use the launch map for cross-platform tests. A bare launch applies everywhere and becomes an app path on Chromium. The map takes `native:`, `ios:`, `android:`, `vega:`, and `chromium:`. `native:` is one id shared by iOS, Android, and Vega, and a per-platform key overrides it for that platform. `chromium:` accepts a relative or absolute app path. `ios:` also accepts `{ app, args }`; a simulator passes `args` to the app at launch. A launch that declares no id for the run's platform is an error, not a cue to switch platforms. A run on a remote simulator uses the `ios:` id, or the `native:` id when the map has no `ios:` key, so no test needs a key for a remote run. On iOS, a successful launch also pins later tree reads to that app until the next raw `tool:` step, so read [The runner tree is not the discovery tree](#the-runner-tree-is-not-the-discovery-tree) when a read describes the wrong screen.
+Use the launch map for cross-platform tests. A bare launch applies everywhere and becomes an app path on Chromium. The map takes `native:`, `ios:`, `android:`, `vega:`, and `chromium:`. `native:` is one id shared by iOS, Android, and Vega, and a per-platform key overrides it for that platform. `chromium:` accepts a relative or absolute app path. `ios:` also accepts `{ app, args }`; Argent passes `args` to the app at launch. A launch that declares no id for the run's platform is an error, not a cue to switch platforms. A run on a remote simulator uses the `ios:` id, or the `native:` id when the map has no `ios:` key, so no test needs a key for a remote run. On an iOS simulator, a successful launch also pins later tree reads to that app until the next raw `tool:` step, so read [The runner tree is not the discovery tree](#the-runner-tree-is-not-the-discovery-tree) when a read describes the wrong screen.
 
 ```yaml
 - launch: { native: com.acme.app, chromium: ../../app }
@@ -156,9 +156,9 @@ Only the direction presets carry OS-edge margins. A resolved `from` point is use
 
 On Chromium a swipe is a mouse drag (`gesture-drag`), so a `from` on an `<img>`, an `<a href>` or a `draggable="true"` node starts the browser's native drag-and-drop: the page gets `pointerdown` then `pointercancel` and sees no travel. On Vega, `swipe` fails upfront like the other touch directives.
 
-`type` presses Enter in a second `keyboard` call unless `submit: false`. A polished focus tap plus one text-only `keyboard` call usually needs `submit: false`. Store external values as `{{secret:NAME}}`. The runner uses the first source that defines the name: environment `ARGENT_SECRET_NAME`; project `.argent/secrets.env`; project `.env.local`, then `.env`; then `~/.argent/secrets.env`. Over a link with `forward-secrets` on, the same sources on the client's machine come first. The two `secrets.env` files accept the bare `NAME`, but the shared dotenv files expose only `ARGENT_SECRET_`-prefixed keys, so a bare `NAME=…` in `.env` or `.env.local` stays unresolved. The runner redacts every resolved value, so do not use a placeholder for content a report must show.
+`type` presses Enter in a second `keyboard` call unless `submit: false`. A polished focus tap plus one text-only `keyboard` call usually needs `submit: false`. Store external values as `{{secret:NAME}}`; the runner resolves them from the same sources as the `keyboard` tool. The runner redacts every resolved value, so do not use a placeholder for content a report must show.
 
-A **selector-less gesture** (a coordinate `tap`/`long-press`/`swipe`, or a `pinch`/`rotate` with no `on:`) resolves no frame, so a tree source it cannot read does not fail it. It settles best effort, dispatches anyway, and the step **passes carrying a warning** that quotes the source's own error. That green says the gesture was sent, not that it landed: one aimed at a moving element can miss it entirely. Restore the tree source, usually by relaunching the app so the instrumentation loads. Accept the warning only where the app serves no tree at all, and put an explicit `wait:` before a gesture that follows a transition. The first such gesture proves the outage and later ones spend that verdict without paying the settle window again. A tree read that comes back, or a relaunch, retires that verdict, which only makes the next gesture pay a fresh window, and it warns again if the source is still down.
+A **selector-less gesture** (a coordinate `tap`/`long-press`/`swipe`, or a `pinch`/`rotate` with no `on:`) resolves no frame, so a tree source it cannot read does not fail it. It settles best effort, dispatches anyway, and the step **passes carrying a warning** that quotes the source's own error. That green says the gesture was sent, not that it landed: one aimed at a moving element can miss it entirely. Restore the tree source, usually by relaunching the app so the instrumentation loads. Accept the warning only where the app serves no tree at all, and put an explicit `wait:` before a gesture that follows a transition: after the first such gesture, later ones skip the settle window until a tree read succeeds again or the app relaunches.
 
 ## Verification conditions
 
@@ -209,7 +209,7 @@ It **never fails a run.** Every outcome short of a clean settle passes with a wa
 - **a small part of it was still changing**: a spinner, caret, or progress dot moved through the hold. Too small to count as the screen moving, so the settle completed anyway.
 - **the screen was still for the last Nms**: the wait ran out mid-hold, so no settle was confirmed. It names the term that was short: a second agreeing interval, or the rest of `stableFor`. Raise this step's `timeout:`, because the wait was too short rather than the screen too busy.
 - **the tree stayed empty**: the screen rendered no accessible content: a canvas or video surface, or a screen that never arrived.
-- **settled on the UI tree alone**: no screenshot pair could be read, so presentation-layer animation was never waited out.
+- **settled on the UI tree alone**: no screenshot pair could be read, so presentation-layer animation was never waited out. Inspect the capture path rather than the app's rendering.
 - **too few reads**: a settle needs three reads across two intervals and this step got fewer, so it ended with no evidence either way.
 
 Only a tree source this step could not read stops the run, as an errored step: one still failing when the wait ends, one that wedges after answering, one that answers with an empty tree it flags as degraded (an unattached Vega toolkit, an AX service asking to be relaunched), or one that never answers (raise `timeout` before suspecting the app). The run is then not ok and every later step is skipped. A single failed read is not that: the hold restarts from the next good read. The same outage stops no [selector-less gesture](#directives), which needs no frame and passes with its own warning instead.
@@ -241,8 +241,6 @@ A `run:` target is a YAML path resolved against the directory of the test file c
 
 ## Local scripts
 
-Use a local `.mjs` script only when the user requests one. Record it with `e2e-add-script` at the point where it must run.
-
 ```yaml
 - script: { path: ../../scripts/seed-order.mjs }
 - script: { path: ../../scripts/seed-order.mjs, timeout: 60000 }
@@ -250,13 +248,10 @@ Use a local `.mjs` script only when the user requests one. Record it with `e2e-a
 
 Use the map form shown above. A bare `script: scripts/seed.mjs` is invalid.
 
-- **`path`** is relative to the test file that contains the step. Include `.mjs` and match the file name's letter case.
-- **`timeout`** is optional and uses milliseconds. The default is 30000. The minimum is 100.
+`path` is relative to the test file that contains the step. Include `.mjs` and match the file name's letter case. `timeout` is in milliseconds, as in `e2e-add-script`.
 
 Over a link (`argent link` or `ARGENT_TOOLS_URL`, also to 127.0.0.1), `e2e-add-script` refuses the call, and a replay rejects a test with a `script:` step. Record and replay a test with a script without a link.
 
-If a script fails, check its changes before you retry.
-
 ## Snapshots and CLI runs
 
 `argent e2e run <name> [--device <id>] [--platform ios|android|chromium|vega|ios-remote] [--update-baselines] [--output <dir>] [--json]` runs without an LLM and exits non-zero on failure.
@@ -267,7 +262,7 @@ Do not use a snapshot as the only proof of navigation, persistence, data, access
 
 Baselines live beside the test, under `.argent/e2e/__baselines__/<name>/` and are keyed by platform and full-capture geometry; `cropOn` also contributes its selector. A run on a remote simulator uses `ios` in the key, so it uses the same baseline as a local iOS run with the same capture geometry. Seed from a known-good state with `--update-baselines`. A test that a `tool: e2e-execute` step runs keeps its own baselines, and `--update-baselines` updates them too unless the step sets `updateBaselines` itself. A run on a remote simulator with `--update-baselines` rewrites the same baseline file that a local run uses, and its step reason says that a remote simulator wrote it. Inspect every baseline and require user review. Do not commit it yourself. Baseline creation or update is not a test pass. Never update a baseline only to make a diff pass. The default `maxMismatch` is 0.5 percent.
 
-Pin `--platform` and `--device` for iOS, Android, or Vega. For Chromium the device class is the window's own pixel size, which the app sets and no launch argument changes: pass `--platform chromium` and omit `--device` so the runner boots the declared app path instead of attaching to a running window of another size. A window sized from host or session state produces a key CI cannot reproduce, and the step fails for a missing baseline. The runner pins mobile status bars during visual runs. `--output <dir>` writes failed baseline, current, and diff images under `<dir>/<name>/` for CI artifact upload.
+Pin `--platform` and `--device` for iOS, Android, or Vega. For Chromium the device class is the window's own pixel size, which the app sets and no launch argument changes: pass `--platform chromium` and omit `--device` so the runner boots the declared app path instead of attaching to a running window of another size. A window sized from host or session state produces a key CI cannot reproduce, and the step fails for a missing baseline. The runner pins mobile status bars during visual runs. `--output <dir>` writes failed snapshots' images and failed steps' screenshots under `<dir>/<name>/` for CI artifact upload.
 
 ## YAML safety