prowl-tools 0.1.6 → 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
 
-Edit `.prowl/hunts/homepage.yml` or create a new file:
+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
+
+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,14 +1231,6 @@ 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.
-
----
-
 ## Native Selector Dialect (compatibility matrix)
 
 Android and iOS now consume one shared selector dialect implementation, so `id=`
@@ -967,163 +1263,8 @@ 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
-> 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)
-
-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` 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.
+specifics (escaping, `statusItem`/`menu=` on macOS above, the Compose
+`testTagsAsResourceId` caveat on Android below) live in each target's own section.
 
 ---
 
@@ -1219,6 +1360,11 @@ 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.
 
+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
@@ -1364,6 +1510,11 @@ 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.
 
+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

package/dist/{chunk-WHAMB4TY.js → chunk-O3OUTZ2P.js}

@@ -12,13 +12,28 @@ var SUPPORTED_BROWSER_ENGINES = ["chromium", "firefox", "webkit"];
 
 // src/config/hunt-name.ts
 var HUNT_NAME_PATTERN = /^[A-Za-z0-9_-]+(?:\/[A-Za-z0-9_-]+)*$/;
+var HUNT_FILE_EXTENSION_PATTERN = /\.yml$/i;
 function isValidHuntName(name) {
   return HUNT_NAME_PATTERN.test(name);
 }
+function normalizeHuntName(input) {
+  let name = input.trim();
+  if (name.startsWith("./")) {
+    name = name.slice(2);
+  }
+  const isSupportedHuntPath = HUNT_FILE_EXTENSION_PATTERN.test(name);
+  if (isSupportedHuntPath && name.startsWith(".prowl/hunts/")) {
+    name = name.slice(".prowl/hunts/".length);
+  } else if (isSupportedHuntPath && name.startsWith("hunts/")) {
+    name = name.slice("hunts/".length);
+  }
+  name = name.replace(HUNT_FILE_EXTENSION_PATTERN, "");
+  return name;
+}
 function assertValidHuntName(name) {
   if (!isValidHuntName(name)) {
     throw new Error(
-      `Invalid hunt name: "${name}". Use only letters, numbers, hyphens, underscores, and forward slashes.`
+      `Invalid hunt name: "${name}". A hunt name is its file name under .prowl/hunts/ (letters, numbers, hyphens, underscores, and forward slashes for nested hunts). Accepted forms: a bare name (homepage), a nested name (admin/users), or a path (.prowl/hunts/homepage.yml or hunts/homepage.yml).`
     );
   }
 }
@@ -593,6 +608,7 @@ function listHunts(configDir) {
 
 export {
   SUPPORTED_BROWSER_ENGINES,
+  normalizeHuntName,
   configSchema,
   stepSchema,
   huntSchema,
@@ -608,4 +624,4 @@ export {
   loadHuntMeta,
   listHunts
 };
-//# sourceMappingURL=chunk-WHAMB4TY.js.map
+//# sourceMappingURL=chunk-O3OUTZ2P.js.map