prowl-tools 0.1.5 → 0.1.7

package/README.md

@@ -1,12 +1,53 @@
 # Prowl
 
-CLI-first QA testing tool for deterministic web testing with Playwright.
+End-to-end testing for **native macOS apps and web apps** — from the same
+declarative YAML.
 
 <!-- ILLUSTRATION: Prowl raccoon mascot hero image — cyan raccoon with terminal window showing pass/fail output -->
 
-Write tests in YAML. Run them from the terminal. Get screenshots, traces, and reports automatically.
+Write a test (a "hunt") in YAML, run it from the terminal, and get screenshots,
+traces, and reports automatically. The same step vocabulary — `click`, `fill`,
+`assert` — drives a macOS app through Apple's Accessibility API and a web app
+through Playwright. One tool, one file format, both targets.
+
+**Desktop-first.** The macOS target — menu-bar extras (`NSStatusItem`) included —
+is the gap no other tool fills: [Maestro](https://maestro.mobile.dev) targets
+mobile and web, [Playwright](https://playwright.dev) is web-only, and
+[XCUITest](https://developer.apple.com/documentation/xctest) means Swift and
+Xcode. Web is Prowl's second first-class target; iOS and Android are
+experimental. The macOS target is **experimental today** — install its signed
+helper with `prowl macdriver install` (see
+[macOS Target](#macos-target-experimental)) — but it's where Prowl leads.
+
+**Native macOS app** — driven through the Accessibility API:
+
+```yaml
+# .prowl/config.yml → target: { type: macos, app: "com.example.App" }
+# .prowl/hunts/save-note.yml
+name: save-note
+steps:
+  - click: "id=newNote"
+  - type: "Buy milk"
+  - click: "id=saveButton"
+  - assert:
+      visible: "Saved"
+```
+
+```text
+  ● Running hunt: save-note
+    ✓ click "id=newNote" (90ms)
+    ✓ type "Buy milk" (40ms)
+    ✓ click "id=saveButton" (110ms)
+    ✓ assert visible "Saved" (12ms)
+
+  PASS save-note (252ms) 4/4 steps
+  Artifacts: .prowl/runs/2026-02-09_10-30-45
+```
+
+**Web app** — driven through Playwright:
 
 ```yaml
+# .prowl/config.yml → target: { type: web, url: "http://localhost:3000" }
 # .prowl/hunts/login-flow.yml
 name: login-flow
 steps:
@@ -20,7 +61,7 @@ steps:
       visible: "Dashboard"
 ```
 
-```
+```text
   ● Running hunt: login-flow
     ✓ navigate "/login" (120ms)
     ✓ fill "Email" (85ms)
@@ -32,6 +73,23 @@ steps:
   Artifacts: .prowl/runs/2026-02-09_10-30-45
 ```
 
+## Why Prowl
+
+- **Desktop-first, from the same YAML.** Native macOS apps (Accessibility API)
+  and web apps (Playwright) share one step vocabulary, one config, one report
+  format. No incumbent covers the Mac desktop the way Prowl aims to.
+- **Deterministic.** Explicit scripted steps — no natural-language guessing.
+- **Developer-ready artifacts.** Every run writes screenshots, a Playwright
+  trace, a console log, and both human- (`summary.md`) and machine-readable
+  (`result.json`) reports.
+- **Self-sovereign & file-based.** Hunts, run history, and baselines live in
+  your repo. No database, no account, no service to sign up for.
+- **Guardrails built in.** Allowed domains/apps, forbidden selectors, and step
+  caps keep runs scoped and safe.
+
+Additional experimental targets — iOS Simulator and Android — follow the same
+hunt format; see their sections below.
+
 ---
 
 ## Getting Started
@@ -87,20 +145,23 @@ prowl init
 
 <!-- ILLUSTRATION: Terminal screenshot showing `prowl init` output with raccoon mascot and file listing -->
 
-This creates a `.prowl/` directory with a config file and 8 example hunts:
+This creates a `.prowl/` directory with a config file and two starter hunts:
 
 ```text
 .prowl/
-├── config.yml              # Target URL, browser settings, guardrails
+├── config.yml         # Target URL, browser settings, guardrails
+├── .gitignore         # Keeps runs/, auth-state.json, and .env out of git
 └── hunts/
-    ├── homepage.yml         # Basic page load smoke test
-    ├── login-flow.yml       # Email/password authentication
-    ├── signup-flow.yml      # Registration with validation
-    ├── form-submit.yml      # Form fill and submit
-    ├── form-validation.yml  # Validation errors and resubmit
-    ├── crud-cycle.yml       # Create, read, update, delete lifecycle
-    ├── checkout-flow.yml    # E-commerce checkout
-    └── onboarding-wizard.yml # Multi-step SaaS onboarding
+    ├── hello.yml       # Minimal smoke test — verifies the app loads
+    └── login-flow.yml  # Fuller example — auth, secrets, assertions
+```
+
+`prowl init` finishes by pointing you at the first hunt:
+
+```text
+  Initialized .prowl directory.
+  Run prowl run hello to get started.
+  See .prowl/hunts/login-flow.yml for a fuller example.
 ```
 
 ### 3. Configure
@@ -112,11 +173,26 @@ target:
   url: "http://localhost:3000"
 ```
 
-### 4. Write Your First Hunt
+### 4. Run the starter hunt
+
+Run the bundled `hello` hunt to confirm your app is reachable:
+
+```bash
+prowl run hello
+```
+
+<!-- ILLUSTRATION: Terminal screenshot showing colorized pass/fail output with step timings -->
+
+A hunt's name is its **file name** under `.prowl/hunts/` — `hello` runs
+`.prowl/hunts/hello.yml`.
+
+### 5. Write your own hunt
 
-Edit `.prowl/hunts/homepage.yml` or create a new file:
+Create a new file `.prowl/hunts/smoke-test.yml`. The file name *is* the hunt
+name, so this hunt runs as `smoke-test`:
 
 ```yaml
+# .prowl/hunts/smoke-test.yml
 name: smoke-test
 steps:
   - navigate: "/"
@@ -127,18 +203,226 @@ assertions:
   - noConsoleErrors: true
 ```
 
-### 5. Run
+Run it by file name:
 
 ```bash
 prowl run smoke-test
 ```
 
-<!-- ILLUSTRATION: Terminal screenshot showing colorized pass/fail output with step timings -->
-
 That's it. You're testing.
 
 ---
 
+## macOS Target (Experimental)
+
+> **Experimental (PROWL-048).** Prowl can drive **native macOS apps** — including
+> menu bar extras (`NSStatusItem` + `NSMenu`) — through Apple's Accessibility API,
+> in addition to the web. The API, selector dialect, and step coverage may change.
+
+### Enabling it
+
+1. **Install the helper** (recommended — no Xcode, no Swift toolchain):
+
+   ```bash
+   prowl macdriver install
+   ```
+
+   This downloads the pinned, **signed and notarized** `prowl-macdriver` binary
+   from GitHub Releases, verifies its SHA-256 against the released checksum, and
+   installs it to `~/.prowl/macdriver/<version>/prowl-macdriver`. Check what's
+   resolved at any time with `prowl macdriver status`.
+
+   > **Until the first signed release is cut, `prowl macdriver install` returns a
+   > 404** (the maintainer publishes the first `macdriver-v*` release and
+   > verifies the flow before this becomes the default path). In the meantime,
+   > build from source as below.
+
+   **Contributors / pre-release — build from source** (requires the Swift
+   toolchain / Xcode CLT):
+
+   ```bash
+   cd macdriver
+   swift build -c release
+   ```
+
+   **Binary search order.** Prowl resolves the helper via, in order:
+   1. `$PROWL_MACDRIVER_BIN` (absolute path to a binary), then
+   2. the user-level install at `~/.prowl/macdriver/<version>/prowl-macdriver`
+      (what `prowl macdriver install` writes), then
+   3. the repo-local source build at `macdriver/.build/release/prowl-macdriver`
+      (then `.../debug/...`).
+
+   If none is found, Prowl fails with a clear message pointing at
+   `prowl macdriver install` (with the source build as the contributor fallback)
+   rather than crashing.
+
+2. **Point your config at a macOS target:**
+
+   ```yaml
+   target:
+     type: macos
+     app: "com.example.App"        # bundle id, or an absolute /path/to/App.app
+   guardrails:
+     allowedApps:                   # optional scope; empty = allow the target app
+       - "com.example.App"
+   ```
+
+   When `target.app` is an app path, `allowedApps` may list the exact `.app`
+   path, the app bundle name (`Example` for `Example.app`), or the bundle id
+   from `Contents/Info.plist` when that file is readable.
+
+3. **Grant Accessibility permission** (see below), then run a hunt as usual:
+   `prowl run my-macos-hunt`.
+
+### Accessibility & Screen Recording permission
+
+The **process that hosts** Prowl (your terminal — Terminal, iTerm, VS Code, or a CI
+agent) must be granted **Accessibility** permission: **System Settings → Privacy &
+Security → Accessibility**, then enable that app. macOS attributes the grant to the
+hosting app, not to `prowl-macdriver`. `prowl macdriver status` prints the
+resolved binary path, installed versions, and this permission guidance. Preflight
+the Accessibility grant directly from the helper (use the path `status` reports,
+or the source build):
+
+```bash
+MACDRIVER_VERSION=0.1.0  # replace with the version shown by `prowl macdriver status`
+~/.prowl/macdriver/$MACDRIVER_VERSION/prowl-macdriver check
+# or: macdriver/.build/release/prowl-macdriver check
+# prints {"trusted": <bool>}; prompts on first run
+```
+
+The `screenshot`/`assertScreenshot` steps additionally need **Screen Recording**
+permission for the hosting app.
+
+**CI notes (macOS runners):** headless CI cannot click "Allow" in a dialog, so grant
+the permissions non-interactively before the run. On a self-hosted runner you can
+pre-authorize the agent's host app with a TCC profile via MDM, or (on ephemeral
+runners where it's acceptable) seed the TCC database, e.g.:
+
+```bash
+sudo sqlite3 "/Library/Application Support/com.apple.TCC/TCC.db" \
+  "INSERT OR REPLACE INTO access VALUES('kTCCServiceAccessibility','<runner-app-bundle-id>',0,2,2,1,NULL,NULL,NULL,'UNUSED',NULL,0,1,NULL,NULL,NULL);"
+```
+
+GitHub-hosted macOS runners do not grant Accessibility, so the macOS target is aimed
+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 |
+|---|---|
+| `id=openSettings` | element whose `AXIdentifier` equals `openSettings` |
+| `role=button[name="Save"]` | an `AXButton` whose title/description/value contains `Save` |
+| `label="Email"` | element whose accessibility label equals `Email` |
+| `text="Save"` or bare `Save` | element whose title/description/value contains the text |
+| `statusItem` | opens the app's menu bar status-item menu |
+| `menu=Preferences…` | opens the status-item menu and clicks that item |
+
+`forbiddenSelectors` still applies (text patterns match via the same substring
+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
+macOS target (with a clear error), and `prowl login` / URL guardrails do not apply.
+
+| Portable (web + macOS) | Web-only (rejected on macOS) |
+|---|---|
+| `click`, `fill`, `type`, `press` | `navigate`, `waitForUrl`, `waitForNetworkIdle` |
+| `wait`, `waitForSelector` | `mockRoute` / `unmockRoute` |
+| `assert: visible` / `notVisible` | `evalScript`, `runScript` |
+| `screenshot`, `assertScreenshot` | `onDialog`, `select` / `selectOption` |
+| `hover`, `scrollTo` | `setInputFiles`, `waitForDownload` |
+| `repeat`, `if`, `runHunt`, `copyText` | `scroll` (directional), `assert: urlIncludes` / `urlEquals` |
+
+Notes: `press` accepts the same key vocabulary as the web target — single printable
+characters, `Enter`/`Return`/`Space`, `Tab`, `Escape`, `Backspace`, `Delete`, `Home`,
+`End`, `PageUp`, `PageDown`, arrows (`ArrowUp`/`ArrowDown`/`ArrowLeft`/`ArrowRight`),
+`F1`–`F12`, and `+`-joined modifier combos (`Control`, `Shift`, `Alt`, `Meta`,
+`ControlOrMeta`; aliases: `Ctrl`, `Option`, `Cmd`, `Command`; `ControlOrMeta` maps
+to Command on macOS), e.g. `Shift+Tab`, `ControlOrMeta+a`, or `Meta+a`; unknown keys
+error clearly. A bare `Enter`/`Return`/`Space` uses the element's activate action when
+available, otherwise keystrokes are synthesized and posted to the target app (activated
+first) so they never land elsewhere — the existing Accessibility grant already covers
+this, no new permission prompt. `type` fills the focused control; app teardown quits the
+target app after the run.
+
+#### Hunt-level assertion compatibility
+
+Hunt-level `assertions:` are evaluated after the steps complete (even when a step
+failed, matching the web path). Selector assertions run on every target; URL, console,
+and network assertions are web-only and are reported as **`skipped`** on a native
+target — visible in `result.json` / `summary.md` / JUnit, never silently dropped and
+never a hard error.
+
+| Assertion | Web | macOS | Android | iOS |
+|---|---|---|---|---|
+| `selectorExists`, `selectorNotExists` | ✅ runs | ✅ runs | ✅ runs | ✅ runs |
+| `urlIncludes`, `urlEquals` | ✅ runs | ⏭️ skipped (web-only) | ⏭️ skipped | ⏭️ skipped |
+| `noConsoleErrors`, `noNetworkErrors` | ✅ runs | ⏭️ skipped (web-only) | ⏭️ skipped | ⏭️ skipped |
+
+A web-only assertion a hunt explicitly authored also prints a console warning naming
+the target; the `noConsoleErrors` / `noNetworkErrors` config defaults are surfaced as
+`skipped` but do not warn on every run. For per-step checks on a native target, use
+inline `assert: visible` / `notVisible` steps.
+
+> Docs follow-up: the customer-facing docs site (`prowl-docs`) should gain a "macOS
+> target" page mirroring this section (target type + step-compatibility matrix +
+> assertion-compatibility matrix + permission setup); tracked separately from this repo.
+
+---
+
 ## Step Type Reference
 
 Prowl supports both **shorthand** and **explicit** syntax for most step types. Shorthand is concise and readable. Explicit gives you full control over selectors.
@@ -200,6 +484,14 @@ Press a keyboard key on a specific element.
     key: "Enter"
 ```
 
+Key names follow the web (Playwright) vocabulary — e.g. `Enter`, `Escape`, `Tab`,
+`Backspace`, `Delete`, arrows, `F1`–`F12`, single characters, and modifier combos like
+`Control+a`, `ControlOrMeta+a`, or `Shift+Tab`. The macOS target accepts the same names
+(see the macOS target notes above); `ControlOrMeta` maps to Command, and
+`Cmd`/`Command`/`Option` are also accepted there as aliases for `Meta`/`Alt`.
+On macOS, a shortcut letter in a combo (e.g. `Meta+s`) is synthesized against the US/ANSI
+physical keyboard layout — the standard trade-off for synthesized keystrokes.
+
 ### select / selectOption
 
 Select a dropdown value. Shorthand finds by label, explicit uses a selector.
@@ -438,6 +730,10 @@ assertions:
   - noNetworkErrors: true              # No HTTP responses >= 400
 ```
 
+On native targets (macOS / Android / iOS) the selector assertions run and the
+URL/console/network ones are reported as `skipped` — see the
+[hunt-level assertion compatibility matrix](#hunt-level-assertion-compatibility).
+
 ---
 
 ## Config Reference
@@ -699,9 +995,17 @@ spans. When the app emits no trace headers, nothing is recorded (no noise).
 
 ## CLI Reference
 
+A `<hunt-name>` is a hunt's file name under `.prowl/hunts/` — `homepage` for
+`.prowl/hunts/homepage.yml`, or `admin/users` for a nested
+`.prowl/hunts/admin/users.yml`. `run`, `watch`, and `history` also accept
+supported `.yml` path forms (`.prowl/hunts/homepage.yml` or
+`hunts/homepage.yml`) and a bare `.yml` file name (`homepage.yml`); they resolve
+to the same hunt.
+
 ```bash
 # Run a hunt
 prowl run <hunt-name>
+prowl run .prowl/hunts/homepage.yml     # A literal path resolves to `homepage`
 prowl run <hunt-name> --headed          # Show browser window
 prowl run <hunt-name> --trace           # Capture Playwright trace
 prowl run <hunt-name> --slow-mo 500     # Slow down actions (ms)
@@ -927,164 +1231,40 @@ CLI Commands
 
 ---
 
-## Community Hub
-
-Browse and contribute hunt templates through the internal community registry (contact ops for access).
-
-Templates cover auth flows (OAuth, 2FA), e-commerce (Stripe), admin panels, SaaS patterns, and more. Each template is heavily commented and ready to customize.
-
----
-
-## macOS Target (Experimental)
-
-> **Experimental (PROWL-048).** Prowl can drive **native macOS apps** — including
-> menu bar extras (`NSStatusItem` + `NSMenu`) — through Apple's Accessibility API,
-> in addition to the web. The API, selector dialect, and step coverage may change.
-> **Distribution is deferred:** the required helper binary is **not** shipped in the
-> npm package; you build it locally (below).
-
-### Enabling it
-
-1. **Build the helper** (one time; requires the Swift toolchain / Xcode CLT):
-
-   ```bash
-   cd macdriver
-   swift build -c release
-   ```
-
-   Prowl finds the binary at `macdriver/.build/release/prowl-macdriver`, or at
-   `$PROWL_MACDRIVER_BIN` if set. If it is missing, Prowl fails with a clear
-   "build the helper" message rather than crashing.
-
-2. **Point your config at a macOS target:**
-
-   ```yaml
-   target:
-     type: macos
-     app: "com.example.App"        # bundle id, or an absolute /path/to/App.app
-   guardrails:
-     allowedApps:                   # optional scope; empty = allow the target app
-       - "com.example.App"
-   ```
-
-   When `target.app` is an app path, `allowedApps` may list the exact `.app`
-   path, the app bundle name (`Example` for `Example.app`), or the bundle id
-   from `Contents/Info.plist` when that file is readable.
-
-3. **Grant Accessibility permission** (see below), then run a hunt as usual:
-   `prowl run my-macos-hunt`.
-
-### Accessibility & Screen Recording permission
-
-The **process that hosts** Prowl (your terminal — Terminal, iTerm, VS Code, or a CI
-agent) must be granted **Accessibility** permission: **System Settings → Privacy &
-Security → Accessibility**, then enable that app. macOS attributes the grant to the
-hosting app, not to `prowl-macdriver`. Preflight from the helper:
-
-```bash
-macdriver/.build/release/prowl-macdriver check   # prints {"trusted": <bool>}; prompts on first run
-```
-
-The `screenshot`/`assertScreenshot` steps additionally need **Screen Recording**
-permission for the hosting app.
-
-**CI notes (macOS runners):** headless CI cannot click "Allow" in a dialog, so grant
-the permissions non-interactively before the run. On a self-hosted runner you can
-pre-authorize the agent's host app with a TCC profile via MDM, or (on ephemeral
-runners where it's acceptable) seed the TCC database, e.g.:
-
-```bash
-sudo sqlite3 "/Library/Application Support/com.apple.TCC/TCC.db" \
-  "INSERT OR REPLACE INTO access VALUES('kTCCServiceAccessibility','<runner-app-bundle-id>',0,2,2,1,NULL,NULL,NULL,'UNUSED',NULL,0,1,NULL,NULL,NULL);"
-```
-
-GitHub-hosted macOS runners do not grant Accessibility, so the macOS target is aimed
-at self-hosted / MDM-managed runners for now.
-
-### Selector dialect (macOS)
-
-Native selectors address accessibility identifiers, roles, and labels:
-
-| Selector | Matches |
-|---|---|
-| `id=openSettings` | element whose `AXIdentifier` equals `openSettings` |
-| `role=button[name="Save"]` | an `AXButton` whose title/description/value contains `Save` |
-| `label="Email"` | element whose accessibility label equals `Email` |
-| `text="Save"` or bare `Save` | element whose title/description/value contains the text |
-| `statusItem` | opens the app's menu bar status-item menu |
-| `menu=Preferences…` | opens the status-item menu and clicks that item |
-
-`forbiddenSelectors` still applies (text patterns match via the same substring
-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
-macOS target (with a clear error), and `prowl login` / URL guardrails do not apply.
-
-| Portable (web + macOS) | Web-only (rejected on macOS) |
-|---|---|
-| `click`, `fill`, `type`, `press` | `navigate`, `waitForUrl`, `waitForNetworkIdle` |
-| `wait`, `waitForSelector` | `mockRoute` / `unmockRoute` |
-| `assert: visible` / `notVisible` | `evalScript`, `runScript` |
-| `screenshot`, `assertScreenshot` | `onDialog`, `select` / `selectOption` |
-| `hover`, `scrollTo` | `setInputFiles`, `waitForDownload` |
-| `repeat`, `if`, `runHunt`, `copyText` | `scroll` (directional), `assert: urlIncludes` / `urlEquals` |
-
-Notes: `press` maps Enter/Return/Space onto the element's activate action (other keys
-are unsupported); `type` fills the focused control; app teardown quits the target app
-after the run.
-
-> Docs follow-up: the customer-facing docs site (`prowl-docs`) should gain a "macOS
-> target" page mirroring this section (target type + step-compatibility matrix +
-> permission setup); tracked separately from this repo.
+## 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 above, the Compose
+`testTagsAsResourceId` caveat on Android below) live in each target's own section.
 
 ---
 
@@ -1139,8 +1319,10 @@ validates it before installing.
 ### Selector dialect (Android)
 
 Native selectors address `resource-id`, `content-desc`, visible text, and widget
-class. Semantics match the macOS target so a selector means the same thing on both
-native targets:
+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 |
 |---|---|
@@ -1178,9 +1360,57 @@ equivalent yet and are rejected with a clear message; scroll-gesture support is
 follow-up. A degraded pure-`adb` fallback (`uiautomator dump` + `input tap`) is a
 possible future diagnostic mode, not the primary path.
 
-> Out of scope for PROWL-058 (tracked separately): `prowl analyze` for Android and
-> CI recipes (PROWL-061), the unified native selector engine (PROWL-060), and real
-> iOS devices (PROWL-062). The iOS **simulator** target ships below.
+Hunt-level `assertions:` behave as on macOS — `selectorExists` / `selectorNotExists`
+run against the device; `urlIncludes` / `urlEquals` / `noConsoleErrors` /
+`noNetworkErrors` are web-only and reported as `skipped`. See the
+[hunt-level assertion compatibility matrix](#hunt-level-assertion-compatibility).
+
+### 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").
 
 ---
 
@@ -1242,7 +1472,9 @@ treated as a **bundle id** unless a directory of that name exists, so bundle ids
 
 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:
+native targets — see the
+[Native Selector Dialect matrix](#native-selector-dialect-compatibility-matrix)
+(and the `label=` exact-match trap):
 
 | Selector | Matches |
 |---|---|
@@ -1278,9 +1510,170 @@ message. Screenshots are captured with `simctl` (not WDA), so artifacts still wo
 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.
 
-> Out of scope for PROWL-059 (tracked separately): `prowl analyze` for iOS and CI
-> recipes (PROWL-061), the unified native selector engine (PROWL-060), and real iOS
-> devices (PROWL-062).
+Hunt-level `assertions:` behave as on macOS — `selectorExists` / `selectorNotExists`
+run against the simulator; `urlIncludes` / `urlEquals` / `noConsoleErrors` /
+`noNetworkErrors` are web-only and reported as `skipped`. See the
+[hunt-level assertion compatibility matrix](#hunt-level-assertion-compatibility).
+
+### 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.
 
 ---