prowl-tools 0.1.4 → 0.1.6

package/NOTICE

@@ -12,6 +12,16 @@ attributions are provided for the benefit of downstream users.
 Direct Runtime Dependencies
 -------------------------------------------------------------------------------
 
+appium-uiautomator2-server
+  License: Apache-2.0
+  Copyright (c) Appium Contributors
+  https://github.com/appium/appium-uiautomator2-server
+
+appium-webdriveragent
+  License: Apache-2.0
+  Copyright (c) Appium Contributors
+  https://github.com/appium/WebDriverAgent
+
 chalk
   License: MIT
   https://github.com/chalk/chalk

package/README.md

@@ -55,6 +55,29 @@ Prowl uses Playwright under the hood. Install the browser:
 npx playwright install chromium
 ```
 
+The on-device agents for the experimental Android/iOS targets
+(`appium-uiautomator2-server`, `appium-webdriveragent`) are **optional
+dependencies** — installed by default so mobile testing works out of the box,
+but skippable for a leaner web-only install:
+
+```bash
+npm install -g prowl-tools --omit=optional
+```
+
+If a mobile target later needs an omitted agent, it fails with exact recovery
+commands for global and local installs. For a global npm install, restore the
+agents with:
+
+```bash
+npm install -g appium-uiautomator2-server@10.6.2 appium-webdriveragent@16.4.0
+```
+
+For a local project install, omit `-g`:
+
+```bash
+npm install appium-uiautomator2-server@10.6.2 appium-webdriveragent@16.4.0
+```
+
 ### 2. Initialize
 
 ```bash
@@ -424,11 +447,21 @@ Config lives at `.prowl/config.yml`. All options with defaults:
 ```yaml
 # Execution target. Defaults to the web target; existing configs work unchanged.
 target:
-  type: "web"                         # "web" (default) or "macos" (experimental)
+  type: "web"                         # "web" (default), "macos", "android", or "ios" (experimental)
   url: "http://localhost:3000"        # Required for web targets
   # For the experimental macOS target instead:
   #   type: "macos"
   #   app: "com.example.App"          # bundle id or /path/to/App.app  (see "macOS Target")
+  # For the experimental Android target instead:
+  #   type: "android"
+  #   app: "com.example.app"          # package name or /path/to/app.apk  (see "Android Target")
+  #   deviceSerial: "emulator-5554"   # optional; required only with several devices attached
+  #   coldStart: false                # optional; pm clear before launch
+  # For the experimental iOS simulator target instead:
+  #   type: "ios"
+  #   app: "com.example.App"          # bundle id or /path/to/App.app  (see "iOS Target")
+  #   udid: "..."                     # optional; required only with several booted simulators
+  #   coldStart: false                # optional; uninstall+reinstall before launch (needs a .app)
 
 # Browser settings
 browser:
@@ -458,7 +491,7 @@ guardrails:
   forbiddenSelectors:                  # selectors that steps cannot use
     - "[data-danger]"
     - ".delete-btn"
-  allowedApps: []                      # macOS target only: bundle IDs, bundle names, or .app paths
+  allowedApps: []                      # native targets only: macOS bundle IDs/names/.app paths, Android package IDs/canonical APK paths, or iOS bundle IDs/.app paths
 
 # Auth state from `prowl login`
 auth:
@@ -902,6 +935,43 @@ Templates cover auth flows (OAuth, 2FA), e-commerce (Stripe), admin panels, SaaS
 
 ---
 
+## Native Selector Dialect (compatibility matrix)
+
+Android and iOS now consume one shared selector dialect implementation, so `id=`
+/ `label=` / `text=` / `role=` mean the same *shape* of thing on both mobile
+targets. That shared grammar, per-platform attribute mapping, ranking order, and
+host-side matching live in `src/selector/native.ts`. macOS remains on its existing
+driver/analyzer implementation for now, with migration deferred, but follows the
+same documented selector shape. The web target speaks Playwright's own selector
+engines and is shown for contrast.
+
+| Kind | Web (Playwright) | macOS (AX) | Android (uiautomator2) | iOS (WebDriverAgent) |
+|---|---|---|---|---|
+| `id=` | use CSS `#id` / `[data-testid]` | `AXIdentifier`, exact | `resource-id`, exact (bare names are package-qualified: `save` → `<pkg>:id/save`) | accessibility id (the `name` attribute), exact |
+| `label=` | *(no native kind; analyzer surfaces the associated `<label>` text)* | `title`/`description`, **exact** | `content-desc`, **exact** | `accessibilityLabel`, **exact** |
+| `text=` (or bare) | text engine, substring, case-insensitive | `title`/`description`/`value`, substring | visible `text`, substring | `label` **or** `value`, substring |
+| `role=` | ARIA role engine | AX role (e.g. `AXButton`) | widget class (e.g. `android.widget.Button`) | element type (`XCUIElementType…`; shorthand `Button` accepted) |
+| `role=X[name="Y"]` | role + accessible name (substring) | role + name (substring) | class + visible-text (substring) | type + (`label` or `value`) substring |
+| `:focus` | *(n/a)* | focused element | `UiSelector().focused(true)` | `hasKeyboardFocus == 1` |
+
+**The `label=`-in-assertions trap.** On every native target `label=` is an **exact**
+match on the accessibility label — unlike `text=`, which is a substring match, and
+unlike the web, where text matching is forgiving. So `assert: selectorExists:
+label="Save"` will **not** match an element whose real label is "Save changes"; it
+silently fails rather than partially matching. Use `text=` when you want substring
+behavior in an assertion, and keep `label=` for the exact accessibility label. On
+iOS there is a second trap: WDA's page source exposes a single `name` attribute that
+is the `accessibilityIdentifier` when one is set and otherwise the label. Prowl's
+analyzer only recommends `id=` when `name` differs from `label`, so it does not emit
+label-shaped ids, but runtime and host-side matching still resolve `id=` against
+WDA's `name`.
+
+Prefer `id=` on every native target — the native analog of `data-testid`. Per-target
+specifics (escaping, `statusItem`/`menu=` on macOS, the Compose `testTagsAsResourceId`
+caveat on Android) follow in each target's own section below.
+
+---
+
 ## macOS Target (Experimental)
 
 > **Experimental (PROWL-048).** Prowl can drive **native macOS apps** — including
@@ -970,6 +1040,8 @@ at self-hosted / MDM-managed runners for now.
 
 ### Selector dialect (macOS)
 
+See the [Native Selector Dialect matrix](#native-selector-dialect-compatibility-matrix)
+for how these compare across native targets (and the `label=` exact-match trap).
 Native selectors address accessibility identifiers, roles, and labels:
 
 | Selector | Matches |
@@ -985,6 +1057,52 @@ Native selectors address accessibility identifiers, roles, and labels:
 semantics as the web target). Prefer `id=` (accessibility identifiers) — the native
 analog of `data-testid`.
 
+### Finding selectors
+
+Don't guess selectors — dump them. `prowl analyze` works on the macOS target the
+same way it does on the web: it launches/attaches to the app, walks the
+Accessibility tree, and prints every interactive element with **ranked selector
+candidates** (best first) plus the app's windows and status-item menu contents.
+It is read-only (the only interaction is opening and closing the status menu),
+honors `guardrails.allowedApps`, and leaves the app running when done.
+
+```bash
+# Uses the macOS target from .prowl/config.yml:
+prowl analyze
+
+# …or point it at any app without a config:
+prowl analyze --app com.example.App
+prowl analyze --app "/Applications/Example.app"
+
+# Machine-readable output for agents:
+prowl analyze --app com.example.App --json
+```
+
+Example (human-readable) output:
+
+```text
+  App Analysis: com.example.App
+
+  Windows:
+    "Main Window" id=mainWindow
+
+  Interactive Elements:
+    AXButton id=saveButton "Save"
+    AXTextField label="Email" "Email"
+    AXCheckBox label="Remember me" "Remember me" (disabled)
+
+  Menu Bar:
+    AXMenuItem id=preferences "Preferences…"
+    AXMenuItem label="Quit" "Quit"
+
+  3 elements, 1 windows, 2 menu items
+```
+
+Selectors are ranked `id=` > `label=` > `role=…[name="…"]` > `text=` — copy the
+first (most durable) candidate into your hunt. Status-item menu identifiers
+(`id=preferences` above) are especially valuable, since menu titles often carry
+ellipses or localized text that are awkward to match by substring.
+
 ### Step compatibility
 
 Portable steps run on **both** targets; web-only steps are rejected up front on the
@@ -1009,6 +1127,405 @@ after the run.
 
 ---
 
+## Android Target (Experimental)
+
+> **Experimental (PROWL-058).** Prowl can drive **native Android apps** on an
+> emulator or a USB-connected device, in addition to the web and macOS targets.
+> It follows the same "external agent + JSON protocol" shape as the macOS target:
+> `adb` handles device lifecycle and the on-device
+> [`appium-uiautomator2-server`](https://github.com/appium/appium-uiautomator2-driver)
+> (Apache-2.0) handles UI interaction over a plain HTTP/JSON API driven with raw
+> `fetch`. The API, selector dialect, and step coverage may change.
+
+### Requirements
+
+- **`adb`** on your `PATH` (from the Android SDK platform-tools), plus at least
+  one **booted emulator or device** (`adb devices -l` should list it as `device`).
+- The two prebuilt agent APKs ship inside the `appium-uiautomator2-server` npm
+  dependency and are installed onto the device automatically — **nothing to build**.
+  No Appium server, no JVM, no gRPC.
+- If `target.app` is an **`.apk`**, Android build-tools **`aapt`/`aapt2`** must be
+  on `PATH` so Prowl can read the package name (or set `target.app` to the package
+  name directly and install the APK yourself).
+
+### Enabling it
+
+Point your config at an Android target:
+
+```yaml
+target:
+  type: android
+  app: "com.example.app"        # a package name, or a path to an .apk to install
+  # deviceSerial: "emulator-5554"  # required only when several devices are attached
+  # coldStart: true                # `pm clear` before launch for a deterministic start (default off)
+guardrails:
+  allowedApps:                     # optional scope; empty = allow the target app
+    - "com.example.app"
+```
+
+Then run a hunt as usual: `prowl run my-android-hunt`.
+
+On launch Prowl selects the device (failing with an actionable error, listing
+serials, if several are attached and no `deviceSerial` is set), installs the app
+(when given an `.apk`) and the agent, starts the agent via `am instrument`,
+port-forwards it on a **dynamically allocated** local port (so parallel sessions /
+CI jobs don't collide), and waits for the agent to report ready. Everything is
+torn down (agent session, instrumentation, port forward, `am force-stop`) after
+the run. `guardrails.allowedApps` accepts Android package IDs or canonical full
+`.apk` paths; when `target.app` is an APK, Prowl resolves its package ID and
+validates it before installing.
+
+### Selector dialect (Android)
+
+Native selectors address `resource-id`, `content-desc`, visible text, and widget
+class. Semantics match the macOS and iOS targets so a selector means the same thing
+across native targets — see the
+[Native Selector Dialect matrix](#native-selector-dialect-compatibility-matrix)
+(and the `label=` exact-match trap):
+
+| Selector | Matches |
+|---|---|
+| `id=save` | element whose `resource-id` is `save` — a bare name is auto-qualified with the target app's package (`com.pkg:id/save`); ids in other namespaces need the full form (e.g. `id=android:id/title`) |
+| `label="Submit"` | element whose `content-desc` equals `Submit` (exact) |
+| `role=android.widget.Button` | element of that widget class |
+| `role=android.widget.Button[name="Save"]` | that widget class whose visible text contains `Save` |
+| `text="Save"` or bare `Save` | element whose visible text contains the text (substring) |
+
+Prefer `id=` (the native analog of `data-testid`). **Jetpack Compose caveat:**
+Compose nodes only expose a `resource-id` when the app sets
+`Modifier.testTag(...)` **and** enables `testTagsAsResourceId = true`; otherwise
+match Compose UI with `text=` or `label=` (from `Modifier.semantics { contentDescription = ... }`).
+`forbiddenSelectors` still applies (text patterns use the same substring semantics
+as the other targets).
+
+### Step compatibility
+
+Portable steps run on the Android target; web-only steps are rejected up front
+(with a clear error), and `prowl login` / URL guardrails do not apply.
+
+| Portable (Android) | Not supported on Android |
+|---|---|
+| `click`, `fill`, `type`, `press` | `navigate`, `waitForUrl`, `waitForNetworkIdle` |
+| `wait`, `waitForSelector` | `mockRoute` / `unmockRoute`, `evalScript`, `runScript` |
+| `assert: visible` / `notVisible` | `onDialog`, `select` / `selectOption`, `setInputFiles` |
+| `screenshot`, `assertScreenshot` | `waitForDownload`, `scroll`, `assert: urlIncludes` / `urlEquals` |
+| `repeat`, `if`, `runHunt`, `copyText` | `hover`, `scrollTo` (no touch equivalent yet — see below) |
+
+Notes: `type` and `fill` set text on the focused / matched field **unicode-safely**
+(via the agent's `element/value`, not `adb shell input text`); `press` maps key
+names (`Enter`, `Tab`, `Backspace`, `Back`, `Home`, arrow keys, …) onto Android key
+codes and dispatches them to the focused view. `hover` and `scrollTo` have no touch
+equivalent yet and are rejected with a clear message; scroll-gesture support is a
+follow-up. A degraded pure-`adb` fallback (`uiautomator dump` + `input tap`) is a
+possible future diagnostic mode, not the primary path.
+
+### Finding selectors (Android)
+
+Don't guess selectors — dump them. `prowl analyze` works on the Android target the
+same way it does on the web and macOS: it attaches to the running app, reads the
+uiautomator UI hierarchy, and prints every interactive element with **ranked
+selector candidates** (best first). It is read-only, honors
+`guardrails.allowedApps`, and leaves the app running when done. Point it at a
+booted emulator/device:
+
+```bash
+# Uses the Android target from .prowl/config.yml:
+prowl analyze
+
+# …or force the Android target explicitly:
+prowl analyze --app com.android.settings --platform android
+prowl analyze --app ./app-debug.apk               # an .apk implies Android
+prowl analyze --app com.example.app --device emulator-5556   # pick a device
+
+# Machine-readable output for agents:
+prowl analyze --app com.android.settings --platform android --json
+```
+
+Ranking (best → last resort): `id=` (the package-qualified `resource-id`, the
+native `data-testid`) > `label=` (content-desc) > `role=<class>[name="<text>"]` >
+`text=`. Example (human-readable) output:
+
+```text
+  App Analysis: com.android.settings
+
+  Interactive Elements:
+    android.widget.EditText id=com.android.settings:id/search_src_text "Search settings"
+    android.widget.LinearLayout text="Network & internet" "Network & internet"
+    android.widget.Switch id=com.android.settings:id/switch_widget (disabled)
+
+  3 elements
+```
+
+> Platform selection for `--app`: an `.apk` implies Android; otherwise pass
+> `--platform android` (a bare bundle-id / package is ambiguous with the macOS and
+> iOS targets, which default to macOS unless a config `target.type` or `--platform`
+> says otherwise). With an Android `target.type` in `.prowl/config.yml`, a bare
+> `prowl analyze` needs no flag.
+>
+> Out of scope for PROWL-058 (tracked separately): the unified native selector
+> engine (PROWL-060) and real iOS devices (PROWL-062). `prowl analyze` for Android
+> and the CI recipes shipped in PROWL-061 (above, and see "Mobile targets in CI").
+
+---
+
+## iOS Target (Experimental)
+
+> **Experimental (PROWL-059).** Prowl can drive **native iOS apps** on a **booted
+> iOS Simulator**, in addition to the web, macOS, and Android targets. It follows
+> the same "external agent + JSON protocol" shape: `xcrun simctl` handles simulator
+> lifecycle and screenshots, and the on-simulator
+> [WebDriverAgent](https://github.com/appium/WebDriverAgent) (Apache-2.0) handles UI
+> interaction over its W3C-shaped HTTP/JSON API driven with raw `fetch`. The API,
+> selector dialect, and step coverage may change. **Real devices are out of scope**
+> (PROWL-062) — simulators only.
+
+### Requirements
+
+- **macOS with a full Xcode** (not just the command-line tools) installed and
+  selected (`xcode-select -p`), so `xcrun simctl` and `xcodebuild` are available.
+- At least one **booted simulator** (`xcrun simctl list devices | grep Booted`, or
+  boot one with `xcrun simctl boot <udid>` / from Xcode).
+- The **WebDriverAgent** runner is built **once** from the `appium-webdriveragent`
+  npm dependency (`xcodebuild build-for-testing`) and cached under
+  `~/.prowl/wda/<wda-version>-xcode<xcode-version>/`; the first run prints a one-time
+  "building WebDriverAgent…" notice and can take a few minutes. Simulators need **no
+  code signing**. Set `PROWL_WDA_RUNNER` to a prebuilt `WebDriverAgentRunner-Runner.app`
+  to skip the build (e.g. in CI with a cached runner).
+
+### Enabling it
+
+Point your config at an iOS target:
+
+```yaml
+target:
+  type: ios
+  app: "com.example.App"          # a bundle id, or a path to a built .app to install
+  # udid: "ABCD-1234"                # required only when several simulators are booted
+  # coldStart: true                  # uninstall+reinstall before launch (requires a .app path)
+guardrails:
+  allowedApps:                       # optional scope; empty = allow the target app
+    - "com.example.App"
+```
+
+Then run a hunt as usual: `prowl run my-ios-hunt`.
+
+On launch Prowl selects the booted simulator (failing with an actionable error,
+listing candidates, if several are booted and no `udid` is set), installs the app
+(when given a `.app`, reading its bundle id from the bundle's **root** `Info.plist`),
+builds/caches and installs the WebDriverAgent runner, launches it on a
+**dynamically allocated** port (passed via `SIMCTL_CHILD_USE_PORT` so parallel
+sessions / CI jobs don't collide), launches the target app, and waits for WDA to
+report ready. Everything is torn down (WDA session, `simctl terminate` of the runner
+and the app) after the run. `guardrails.allowedApps` accepts iOS bundle ids or
+`.app` paths; a `.app` path is authorized by its path, bundle name, or the bundle id
+read from its root `Info.plist`. Note: a bare `target.app` ending in `.app` is
+treated as a **bundle id** unless a directory of that name exists, so bundle ids like
+`com.company.app` are not mistaken for paths.
+
+### Selector dialect (iOS)
+
+Native selectors address accessibility ids, labels, visible text, and element type.
+Semantics match the macOS/Android targets so a selector means the same thing across
+native targets — see the
+[Native Selector Dialect matrix](#native-selector-dialect-compatibility-matrix)
+(and the `label=` exact-match trap):
+
+| Selector | Matches |
+|---|---|
+| `id=save` | element whose accessibility id (`accessibilityIdentifier` / name) is `save` |
+| `label="Submit"` | element whose `accessibilityLabel` equals `Submit` (exact) |
+| `role=XCUIElementTypeButton` | element of that type (shorthand `role=Button` works too) |
+| `role=Button[name="Save"]` | that type whose visible `label`/`value` contains `Save` |
+| `text="Save"` or bare `Save` | element whose `label` or `value` contains the text (substring) |
+| `:focus` | the element with keyboard focus (`hasKeyboardFocus == 1`) |
+
+Prefer `id=` (set `accessibilityIdentifier` in your app — the native analog of
+`data-testid`). Text/label/role+name selectors compile to WDA NSPredicate strings
+(quotes and backslashes are escaped). `forbiddenSelectors` still applies.
+
+### Step compatibility
+
+Portable steps run on the iOS target; web-only steps are rejected up front (with a
+clear error), and URL guardrails do not apply.
+
+| Portable (iOS) | Not supported on iOS |
+|---|---|
+| `click`, `fill`, `type`, `press` | `navigate`, `waitForUrl`, `waitForNetworkIdle` |
+| `wait`, `waitForSelector` | `mockRoute` / `unmockRoute`, `evalScript`, `runScript` |
+| `assert: visible` / `notVisible` | `onDialog`, `select` / `selectOption`, `setInputFiles` |
+| `screenshot`, `assertScreenshot` | `waitForDownload`, `scroll`, `assert: urlIncludes` / `urlEquals` |
+| `repeat`, `if`, `runHunt`, `copyText` | `hover`, `scrollTo` (no touch equivalent yet) |
+
+Notes: `type` and `fill` set text on the focused / matched field via WDA's
+`element/value`; `press` supports a small honest key set — `enter`/`return` and
+`delete`/`backspace` (sent through WDA's key endpoint to the focused element) and
+`home` (returns to the springboard) — and rejects other keys with the supported-keys
+message. Screenshots are captured with `simctl` (not WDA), so artifacts still work
+even if the agent wedges. `hover` and `scrollTo` have no touch equivalent yet and are
+rejected with a clear message; scroll-gesture support is a follow-up.
+
+### Finding selectors (iOS)
+
+Don't guess selectors — dump them. `prowl analyze` works on the iOS target the
+same way it does on the web, macOS, and Android: it attaches to the running app on
+a booted simulator, reads WebDriverAgent's UI hierarchy, and prints every
+interactive element (plus the app's windows) with **ranked selector candidates**
+(best first). It is read-only, honors `guardrails.allowedApps`, and leaves the app
+running when done:
+
+```bash
+# Uses the iOS target from .prowl/config.yml:
+prowl analyze
+
+# …or force the iOS target explicitly:
+prowl analyze --app com.apple.Preferences --platform ios
+prowl analyze --app com.example.App --platform ios --udid <SIM-UDID>
+
+# Machine-readable output for agents:
+prowl analyze --app com.apple.Preferences --platform ios --json
+```
+
+Ranking (best → last resort): `id=` (accessibility id) > `label=` > `role=<Type>
+[name="<text>"]` > `text=`. Because WDA's page source exposes only a single `name`
+attribute — the accessibility identifier when set, otherwise the label — `id=` is
+offered only when that `name` differs from the element's label. Example output:
+
+```text
+  App Analysis: com.apple.Preferences
+
+  Windows:
+    (untitled) role=Window
+
+  Interactive Elements:
+    XCUIElementTypeButton id=general_button "General"
+    XCUIElementTypeCell label="Wi-Fi" "Wi-Fi"
+    XCUIElementTypeSwitch label="Airplane Mode" "Airplane Mode" (disabled)
+
+  3 elements, 1 windows
+```
+
+> A bare bundle-id `--app` is ambiguous with the macOS target (which is the
+> default), so pass `--platform ios`. With an iOS `target.type` in
+> `.prowl/config.yml`, a bare `prowl analyze` needs no flag.
+>
+> Out of scope for PROWL-059 (tracked separately): the unified native selector
+> engine (PROWL-060) and real iOS devices (PROWL-062). `prowl analyze` for iOS and
+> the CI recipes shipped in PROWL-061 (above, and see "Mobile targets in CI").
+
+---
+
+## Mobile targets in CI
+
+The Android and iOS targets run in continuous integration, either on GitHub-hosted
+runners or on a self-hosted Mac. Every recipe runs the real `prowl` CLI against a
+booted emulator/simulator and uploads run artifacts (screenshots, JUnit, reports).
+
+### Android on `ubuntu-latest` (GitHub-hosted)
+
+GitHub's Linux runners support KVM, so a hardware-accelerated emulator boots in the
+job via [`reactivecircus/android-emulator-runner`](https://github.com/ReactiveCircus/android-emulator-runner).
+Prowl installs the uiautomator2 agent APKs from its optional dependency automatically.
+
+```yaml
+name: Android E2E
+on: [push, pull_request]
+jobs:
+  android:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci
+      - run: npm run build
+
+      # KVM must be accessible for a fast emulator.
+      - name: Enable KVM
+        run: |
+          echo 'KERNEL=="kvm", GROUP="kvm", MODE="0666", OPTIONS+="static_node=kvm"' \
+            | sudo tee /etc/udev/rules.d/99-kvm4all.rules
+          sudo udevadm control --reload-rules
+          sudo udevadm trigger --name-match=kvm
+
+      - name: Run hunts against the emulator
+        uses: reactivecircus/android-emulator-runner@v2
+        with:
+          api-level: 34
+          arch: x86_64
+          force-avd-creation: false
+          emulator-options: -no-window -no-audio -no-boot-anim -no-snapshot -gpu swiftshader_indirect
+          disable-animations: true
+          # `prowl` is your installed CLI (e.g. `npx prowl` or a global install);
+          # the emulator is booted and on adb by the time this runs.
+          script: npx prowl ci --junit
+
+      - name: Upload artifacts
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: android-artifacts
+          path: .prowl/runs/**
+          if-no-files-found: ignore
+```
+
+### iOS simulators on `macos-*` (GitHub-hosted)
+
+macOS runners ship Xcode and the iOS simulator runtimes. Boot a simulator with
+`xcrun simctl`, and cache the one-time WebDriverAgent build (`~/.prowl/wda/`, keyed
+on the WDA + Xcode versions) so subsequent runs skip the ~2-minute `xcodebuild`.
+
+```yaml
+name: iOS E2E
+on: [push, pull_request]
+jobs:
+  ios:
+    runs-on: macos-15
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci
+      - run: npm run build
+
+      # Cache the built WebDriverAgent runner across runs.
+      - name: Cache WebDriverAgent
+        uses: actions/cache@v4
+        with:
+          path: ~/.prowl/wda
+          key: prowl-wda-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
+
+      - name: Boot a simulator
+        run: |
+          xcrun simctl boot "iPhone 16" || true
+          xcrun simctl bootstatus "iPhone 16"
+
+      - name: Run hunts against the simulator
+        run: npx prowl ci --junit
+
+      - name: Upload artifacts
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: ios-artifacts
+          path: .prowl/runs/**
+          if-no-files-found: ignore
+```
+
+### Self-hosted device-verification gate
+
+This repo also ships `.github/workflows/mobile-e2e.yml`, a real end-to-end gate on
+the Prowl Tools self-hosted Mac (labels `self-hosted, macOS, prowl-mobile`) that
+boots both a headless emulator and a simulator and drives Settings on each through
+the real CLI. It runs on `workflow_dispatch` (the owner's post-merge verification)
+and on same-repo pull requests, skipping cleanly (green) for forks/outside PRs that
+can't reach the runner, and uses its own `concurrency` group so it never collides
+with other jobs on the shared box. It is the machine-run version of the manual
+smoke tests that caught the uiautomator2 wire-shape bug and the WDA readiness hang.
+
+---
+
 ## Troubleshooting
 
 ### "Could not find .prowl/config.yml"