@bastani/atomic 0.9.28-alpha.3 → 0.9.28-alpha.5

package/dist/builtin/subagents/skills/cua-driver/MACOS.md

@@ -1,4 +1,4 @@
-# cua-driver — macOS specifics
+# cua-driver: macOS specifics
 
 This file is the macOS-specific extension to `SKILL.md`.
 The cross-platform core (snapshot invariant, CLI/MCP defaults,
@@ -8,12 +8,14 @@ you're driving an app on macOS.
 
 ## The no-foreground contract
 
-**The user's frontmost app MUST NOT change.** This is the whole
+**Background window actions must preserve the user's frontmost app.**
+Foreground and desktop actions follow the authorization boundary in
+[RUNTIME.md](RUNTIME.md#foreground-boundary). This is the whole
 reason cua-driver exists. Users pay for the right to keep typing in
 their editor while an agent drives another app in the background.
 Violate this rule and every other nice property the driver gives
 you (no cursor warp, no Space switch, no window raise) stops
-mattering — you just shipped the Accessibility Inspector with extra
+mattering: you just shipped the Accessibility Inspector with extra
 steps.
 
 Before running any shell command, ask: **"does this raise,
@@ -22,21 +24,21 @@ Every one of the commands below activates the target on macOS and
 is therefore forbidden unless the user **explicitly** asked for
 frontmost state:
 
-- **Every form of the `open` CLI — `open -a <App>`, `open -b
+- **Every form of the `open` CLI: `open -a <App>`, `open -b
 <bundle-id>`, `open <file>`, `open <path-to-App.app>`, `open
-<url>` — always activates.** macOS routes all forms through
+<url>`: always activates.** macOS routes all forms through
   LaunchServices, which unhides and foregrounds the target
   regardless of whether you passed an app name, a bundle id, a
   document, a URL, or the bundle path itself. The activation
   happens even when the only intent was "start the process."
   **Never use `open` for any app launch.** This includes launching
   a just-built .app from a local build dir (e.g. `open
-build/Build/Products/Debug/MyApp.app`) — resolve the
+build/Build/Products/Debug/MyApp.app`): resolve the
   `CFBundleIdentifier` from `Info.plist` and use `launch_app`
   with that id. See "The narrow carve-out" below for why
   `launch_app` is safe even when the app internally calls
   `NSApp.activate`.
-- `osascript -e 'tell application "X" to activate'` —
+- `osascript -e 'tell application "X" to activate'`:
   activates by design. Same for `... to open <file>`,
   `... to launch`, and anything with `activate` in the tell block.
 - `osascript -e 'tell application "System Events" to ... frontmost'`
@@ -44,7 +46,7 @@ build/Build/Products/Debug/MyApp.app`) — resolve the
 - AppleScript files that invoke `activate`, `launch`, or `open`
   against the target app.
 - `cliclick` (moves the user's real cursor to the target coords
-  before clicking — a focus-steal-equivalent even if the app's
+  before clicking: a focus-steal-equivalent even if the app's
   window state is unchanged).
 - `CGEventPost` with `cghidEventTap` targeting a coordinate over
   a different app's window (warps the cursor, possibly activates
@@ -52,13 +54,13 @@ build/Build/Products/Debug/MyApp.app`) — resolve the
 - `AppleScriptTask`, `NSAppleScript`, `Process` wrapping `osascript`
   that contains any of the above.
 - `NSRunningApplication.activate(options:)` called from your own
-  helper binary — same class.
-- Dock clicks and any `open` invocation (see the first bullet —
+  helper binary: same class.
+- Dock clicks and any `open` invocation (see the first bullet;
   every form of `open` goes through LaunchServices which
   activates, full stop).
-- **Keyboard shortcuts that semantically mean "focus here" —
+- **Keyboard shortcuts that semantically mean "focus here":
   most notably Chrome / Safari / Arc's `⌘L` (focus omnibox) and
-  Finder's `⌘⇧G` (Go to Folder).** These aren't pure key events —
+  Finder's `⌘⇧G` (Go to Folder).** These aren't pure key events:
   the receiving app interprets "user wants to type here" as
   activation intent and raises its window to be key. Even when
   delivered to a backgrounded pid via `hotkey`, the downstream app
@@ -78,7 +80,7 @@ Reading frontmost state is fine (`osascript -e 'tell application
 "System Events" to get name of first application process whose
 frontmost is true'`). Mutating it is not.
 
-**Corollary — the AXMenuBar rule.** Do not manually drive a background
+**Corollary: the AXMenuBar rule.** Do not manually drive a background
 application's `AXMenuBarItem`: the visible macOS menu bar belongs to the
 frontmost app, and command items may be disabled otherwise. Use `invoke_menu`
 for a known application-menu path. It owns the necessary temporary activation,
@@ -89,7 +91,7 @@ menu bars” below.
 
 **"Open \<app\>" in user speech means launch, not activate.**
 `cua-driver launch_app` is the one correct path for process
-startup — it's idempotent (no-op on a running app), returns the
+startup: it's idempotent (no-op on a running app), returns the
 pid, and has an internal `FocusRestoreGuard` that catches
 `NSApp.activate(ignoringOtherApps:)` calls the target makes during
 `application(_:open:)` and clobbers the frontmost back to what it
@@ -104,43 +106,40 @@ is safe even for apps that normally foreground on media-load
 | ------------------------------------- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
 | Open / launch an app                  | `launch_app({bundle_id})` or `launch_app({bundle_id, urls:[...]})`                     | `open -a`, `osascript 'tell app … to launch/activate/open'` |
 | Find a pid                            | `list_apps` or `launch_app`'s return                                                   | `pgrep`, `ps`, `osascript frontmost`                        |
-| Enumerate an app's windows            | `list_windows({pid})` — or read the `windows` array `launch_app` already returns       | `osascript 'every window of app …'`                         |
+| Enumerate an app's windows            | `list_windows({pid})`: or read the `windows` array `launch_app` already returns       | `osascript 'every window of app …'`                         |
 | Move or resize one exact window       | `set_window_frame({pid, window_id, x, y, width, height})`                              | `osascript` position/size writes or title-bar dragging      |
 | Click / type / scroll / keys          | `click`, `type_text`, `scroll`, `press_key`, `hotkey`                                  | `osascript`, `cliclick`, raw `CGEvent`, `open <url>`        |
-| Drag / drag-and-drop / marquee select | `drag({pid, from_x, from_y, to_x, to_y})` (pixel-only — macOS AX has no semantic drag) | `cliclick dd:`, `osascript drag`                            |
-| Screenshot                            | `screenshot` or the PNG in `get_window_state`                                          | `screencapture`                                             |
+| Drag / drag-and-drop / marquee select | `drag({pid, window_id, from_x, from_y, to_x, to_y, delivery_mode:"foreground"})` (pixel-only and foreground-only: macOS AX has no semantic drag, and there is no background drag) | `cliclick dd:`, `osascript drag`                            |
+| Screenshot                            | `get_window_state` (window) or authorized `get_desktop_state` (desktop)                | `screencapture`                                             |
 | Quit an app                           | ask the user first, then `hotkey({pid, keys:["cmd","q"]})`                             | `kill`, `killall`, `pkill`                                  |
 | Hand a file/URL to an app             | `launch_app({bundle_id, urls:[<path>]})`                                               | `open -a <App> <path>`, `open <url>`                        |
 
 ### The narrow carve-out
 
-The **only** legitimate use of `osascript -e 'tell app X to
-activate'` is when the user **explicitly** asked for frontmost
-state ("bring Chrome to the front", "make it frontmost", "I want
-to see X"). Reaching for it because a tool call returned something
-confusing is wrong — that's the skill's classic foot-in-the-door
-failure mode and it steals focus every time.
+For authorized foreground input, use the Cua action's
+`delivery_mode:"foreground"`. For requested persistent foreground state, use
+`bring_to_front`. Neither requires a shell activation workaround.
 
 When a cua-driver call surprises you, diagnose cua-driver first:
 
 - **Empty `tree_markdown`?** `get_window_state` returns **both** the
-  AX tree and a screenshot by default — there's nothing to configure and
+  AX tree and a screenshot by default: there's nothing to configure and
   no capture mode to pick. An empty tree means the surface isn't AX (a
   non-AX surface: Electron/Chromium/canvas), and the response carries
-  `degraded: true` — so act by **`px`** off the screenshot that's
+  `degraded: true`, so act by **`px`** off the screenshot that's
   already in the same response. `capture_mode` is **deprecated and
   ignored** (still accepted so old callers don't error, but it has no
-  effect — tree + screenshot come back regardless); don't reach for
+  effect; tree + screenshot come back regardless); don't reach for
   `get_config` to "switch modes," there is no mode to switch.
 - **`has_screenshot: false`?** The window capture failed (transient
   race against a close, or the window has no backing store yet).
   Re-snapshot; if persistent, pick a different `window_id` via
   `list_windows`.
-- **`snapshot_id_required` / `stale_element_token` / no cached AX state?**
-  Re-snapshot the exact window and use the new `element_token`, or pair its
-  `snapshot_id` with the matching `element_index`. A new snapshot of that
-  window invalidates older targets immediately.
-- **Sparse Chromium AX tree?** Retry `get_window_state` once — the
+- **`stale_element_token` / no cached AX state?**
+  Re-snapshot the exact window and use the new `element_token`. A new
+  snapshot of that window invalidates older targets immediately; the refusal
+  names the current snapshots so you can tell whether you already hold one.
+- **Sparse Chromium AX tree?** Retry `get_window_state` once: the
   tree populates on second call.
 
 Only after those are ruled out, and only if the user's action
@@ -152,30 +151,30 @@ briefly bring Chrome to the front because …").
 
 There is no `ax`/`vision` capture toggle. **Every `get_window_state`
 returns both the AX tree and a screenshot** (default), so verifying that
-an action **landed** never means "go grab a screenshot" — it means
+an action **landed** never means "go grab a screenshot": it means
 cross-check the tree diff against the pixels you already have in the same
 response, and only switch _dispatch rung_ on a real signal:
 
-1. **Re-snapshot and read the tree diff** — a changed `AXValue`, a new
+1. **Re-snapshot and read the tree diff**: a changed `AXValue`, a new
    element, a collapsed menu, a disabled button. If the tree shows the
    change, you're done. When you only need the tree diff and don't need
-   fresh pixels, pass `include_screenshot:false` to skip the grab — a
+   fresh pixels, pass `include_screenshot:false` to skip the grab: a
    **perf** knob, not a mode flip.
 2. **Trust the screenshot and do an element px action** when the tree
-   **lies** — the action response carried `effect:"suspected_noop"`, the
+   **lies**: the action response carried `effect:"suspected_noop"`, the
    re-snapshot came back `degraded` (empty tree), or the tree looks
    unchanged/unreadable / disagrees with the pixels on a surface where
    it's known to lie:
-   - **Canvas-backed editors** — Monaco (VSCode, Cursor), xterm, Figma,
+   - **Canvas-backed editors**: Monaco (VSCode, Cursor), xterm, Figma,
      WebGL. The AX tree shows the chrome but nothing for the canvas
      content; a snapshot's tree can look unchanged after a successful
      edit while the pixels show it landed.
-   - **Catalyst / iOS-on-Mac text views** — see "Known text-input
+   - **Catalyst / iOS-on-Mac text views**: see "Known text-input
      limits" above. `AXValue` can lag the rendered pixels or report the
      placeholder while the field is actually populated.
 
 On these surfaces you read the result off the screenshot already in the
-response, then address the target by `x,y` — an **element px action**.
+response, then address the target by `x,y`: an **element px action**.
 `px` is your **conscious switch to the pixel addressing path**, not a
 different capture: the screenshot was always there, you just change _how
 you address_ the target. The point is to catch the "type → AX-check
@@ -184,10 +183,10 @@ the surfaces that warrant it.
 
 Rule of thumb:
 
-- **element ax action** (default) — the element lookup before a click
-  AND the first verify after it; you address by `[N]` `element_index`
+- **element ax action** (default): the element lookup before a click
+  AND the first verify after it; you address by the `[N]` row's `element_token`
   and read the tree diff.
-- **element px action** — when the tree is unreadable / `suspected_noop`
+- **element px action**: when the tree is unreadable / `suspected_noop`
   / `degraded` / disagrees with the pixels, or for pure visual
   inspection (reading a chart). You address by `x,y` off the screenshot
   that's already in the snapshot response.
@@ -198,27 +197,27 @@ Before every `Bash` call whose command line touches any macOS app
 (launching, opening, clicking, typing, scripting, screenshotting),
 run the self-check:
 
-1. **Does this command foreground the target?** If yes — stop and
+1. **Does this command foreground the target?** If yes: stop and
    translate to the cua-driver equivalent from the mapping table.
 2. **Does this command move the user's real cursor?** (`cliclick`,
    any `CGEventPost` at `cghidEventTap` over another app's window).
-   If yes — stop; use `click({pid, x, y})` which routes per-pid
+   If yes: stop; use `click({pid, x, y})` which routes per-pid
    via SkyLight and never warps the cursor.
 3. **Does this command bypass cua-driver entirely?** (`osascript`
    mutating GUI state, AppleScript files, external helpers.) If
-   yes — stop; find the cua-driver tool that does the intent.
+   yes: stop; find the cua-driver tool that does the intent.
 
 If all three are "no," the command is safe. If you can't answer,
 default to stop and ask rather than proceed. A single `open -a`
 run by accident kills the demo, the trust, and the user's in-flight
 editor state.
 
-## Prerequisites — macOS
+## Prerequisites: macOS
 
 1. `cua-driver` is on `$PATH` (`which cua-driver`). If not, point the
    user at `scripts/install-local.sh` and stop.
 2. Start the daemon with `open -n -g -a CuaDriver --args serve` (the
-   recommended form — goes through LaunchServices so TCC attributes
+   recommended form: goes through LaunchServices so TCC attributes
    the process to CuaDriver.app). `cua-driver serve &` also works;
    the CLI auto-relaunches through `open -n -g -a CuaDriver` when it
    detects a wrong-TCC context (any IDE-spawned shell: Claude Code,
@@ -232,7 +231,7 @@ editor state.
      tell the user to run `cua-driver permissions grant` and approve it.
    - If Screen Recording is `false`, continue only when the task can be
      completed and verified from the AX tree. Call `get_window_state` with
-     `include_screenshot:false` and use element-indexed AX actions. Do not use
+     `include_screenshot:false` and use `element_token` AX actions. Do not use
      screenshots, pixel coordinates, or pixel-based verification.
    - If the task materially needs pixels, stop and ask the user to run
      `cua-driver permissions grant`. That command explains and deliberately
@@ -243,26 +242,26 @@ editor state.
      the user should click **+**, add `/Applications/CuaDriver.app` (or
      `/Applications/CuaDriverLocal.app`), enable it, and rerun the command.
 
-## Resolve target pid — always via `launch_app`
+## Resolve the requested application
 
-**Always start with `launch_app`**, whether or not the target is already
-running. It's idempotent (relaunching returns the existing pid with no
-side effects) and gives you the pid in one call — no `list_apps` hop.
+Reuse a discovered live target when available. Otherwise use `launch_app`
+when launch is requested or implied, then select the returned window. If the
+window has not appeared yet, bound retries of `list_windows`.
 
-- `launch_app({bundle_id: "com.apple.finder"})` — preferred, unambiguous.
-- `launch_app({name: "Calculator"})` — when bundle_id isn't known.
+- `launch_app({bundle_id: "com.apple.finder"})`, preferred, unambiguous.
+- `launch_app({name: "Calculator"})`, when bundle_id isn't known.
 
-`launch_app` is a **hidden-launch primitive by design** — that's the
+`launch_app` is a **hidden-launch primitive by design**: that's the
 entire point of cua-driver: agents drive apps in the background while
 the user keeps typing in their real foreground app. The target's
 window is initialized (AX tree fully populated, clickable via
-`element_index`, the pid appears in `list_apps`) but not drawn on
+`element_token`, the pid appears in `list_apps`) but not drawn on
 screen. The driver never activates or unhides apps on its own; that
 would violate the no-foreground contract the whole driver exists to
 protect.
 
 If the user explicitly wants the window visible (usually for a demo
-or recording), they unhide it themselves — Dock click, Cmd-Tab, or
+or recording), they unhide it themselves: Dock click, Cmd-Tab, or
 Spotlight. Do not reach for `open` / `osascript activate` as a
 shortcut to make the window visible; those paths break the backgrounded
 invariant on every call, not just the call that "needed" the
@@ -270,7 +269,7 @@ foreground. Say out loud what the user needs to do ("click the
 Todo app in your Dock to bring it forward") and let them do it.
 
 Never shell out to **any** form of `open` (including `open
-<path-to-App.app>` for a just-built binary — resolve the bundle id
+<path-to-App.app>` for a just-built binary: resolve the bundle id
 from `Info.plist` and use `launch_app` with that), `osascript 'tell
 app … to launch/open'`, or similar. Those paths activate the target,
 bypass the driver's focus-restore guard, and require a Bash
@@ -280,7 +279,7 @@ permission prompt the agent loop shouldn't be burning on app launch.
 
 The pixel click is routed through SkyLight's per-pid event path
 (`SLEventPostToPid`), not the system HID stream. The dispatch recipe
-is the backgrounded "noraise" sequence: yabai's focus-without-raise
+is the backgrounded "noraise" sequence: focus-without-raise
 SLPS event records followed by an off-screen user-activation primer
 and the real click. The target app becomes AppKit-active for event
 routing but its window does **not** rise to the front of the
@@ -292,25 +291,43 @@ and the companion `FocusWithoutRaise.swift`.
 ### `delivery_mode` on the pointer family (macOS)
 
 `click`, `double_click`, `right_click`, `drag`, and `scroll` accept
-`delivery_mode` (`"background"` default / `"foreground"`) — matching the
+`delivery_mode` (`"background"` default / `"foreground"`): matching the
 breadth Windows and Linux already exposed (`type_text` / `press_key` /
 `hotkey` carry it too). `"background"` is the SkyLight per-pid path above:
 no raise, no focus steal. `"foreground"` briefly fronts the owning app,
-acts, then restores the prior frontmost — the explicit last resort for a
+acts, then restores the prior frontmost: the explicit last resort for a
 surface that only accepts events while frontmost (the canvas/viewport/game
-case below). Unmodified element-indexed (AX) actions remain background-capable
+case below). Unmodified `element_token` (AX) actions remain background-capable
 and hold the no-foreground contract without the flag.
 
+`drag` is the exception: macOS has no background drag. A window-scoped
+`drag` needs `delivery_mode:"foreground"` and `window_id`; without them it
+refuses with `background_unavailable` and sends nothing. The foreground drag
+fronts the exact window, moves the physical pointer along the path, and then
+restores the prior frontmost app. Use it only when a drag is the task, and
+expect the hardware pointer to move.
+
+A foreground window-scoped **pixel** `click`, `double_click`, or
+`right_click` (`x`/`y` with `window_id`) is delivered like a desktop-scope click, not through the per-pid path: Cua Driver
+activates the exact window (refusing with `foreground_unavailable` when that
+window never becomes focused), moves the hardware pointer to the mapped
+screen point, and posts through the HID event tap. The pointer stays at the
+target afterward, matching Windows `SendInput` and X11 XTest foreground
+clicks, and the prior frontmost app is restored. The result reports
+`route: "global_input"` and says the pointer moved.
+
 Modified clicks are the deliberate exception: pass
 `delivery_mode:"foreground"` and a concrete `window_id`. macOS applications
 can discard PID-routed modifier state after initially publishing a transient
 selection, so Cua Driver refuses that background combination. The foreground
-rung holds physical HID modifier keys around the click, restores the hardware
-cursor and prior foreground app, and confirms list-like selection changes with
-a stable AX readback.
+rung holds physical HID modifier keys around the click, restores the prior
+foreground app, and confirms list-like selection changes with a stable AX
+readback. Element-addressed modified clicks also restore the hardware cursor;
+pixel modified clicks leave it at the target like other foreground pixel
+clicks.
 
 macOS-specific residuals worth knowing (the rest of the capture/dispatch/
-addressing params are a shared cross-platform contract — see `SKILL.md` →
+addressing params are a shared cross-platform contract: see `SKILL.md` →
 _Cross-platform parameter contract_):
 
 - **`check_permissions.prompt` is macOS-only and public calls are
@@ -334,37 +351,44 @@ _Cross-platform parameter contract_):
 ### Canvases, viewports, games (Blender, Unity, GHOST, Qt, wxWidgets)
 
 Apps whose main surface is an OpenGL / Metal / Qt / wxWidgets
-viewport expose **no useful AX tree** — the whole surface is one
+viewport expose **no useful AX tree**: the whole surface is one
 opaque `AXGroup` or `AXWindow` from AX's perspective. Per-pid event
 paths (`SLEventPostToPid`, `CGEvent.postToPid`) are filtered by the
-viewport's own event-source check and silently dropped — the event
+viewport's own event-source check and silently dropped: the event
 loop wants "real HID origin".
 
 The working pattern:
 
-1. Bring the target frontmost (a brief `osascript activate` is
-   acceptable here — this is the carve-out the skill's osascript
-   gate allows).
-2. `CGEvent.post(tap: .cghidEventTap)` with a leading `mouseMoved`
-   event (~30 ms before the click). `cua-driver click` when the
-   target is frontmost automatically takes this path.
-3. Accept that the real cursor visibly moves — `cghidEventTap` is
-   the system HID stream, the cursor warps to the click point.
+1. Observe the target and the background route's refusal or lack of effect.
+2. Obtain authorization for visible foreground control if not already given.
+3. Retry only the necessary Cua action with `delivery_mode:"foreground"`,
+   then verify from fresh state. Do not inject raw CGEvents or use shell activation.
 
 There is no backgrounded path that reaches these apps today.
 
 ### Known pixel-click limits
 
+- **Toolkits that read the hardware pointer (Tk, some Java and game
+  toolkits)** derive a click's location from the real pointer position, not
+  from the delivered event. Background delivery never moves the pointer, so a
+  background pixel click lands wherever the pointer happens to be. When the
+  target maps a Tk library or Python's `_tkinter`, a background window pixel
+  click returns `background_unavailable` with `reason:
+  "pointer_reading_toolkit"`. Other pointer-reading apps cannot be detected
+  cheaply; their background result stays "not driver-verified" and says the
+  pointer was not moved. Retry with `delivery_mode:"foreground"`, which moves
+  the pointer first.
+
 - **Chromium `<video>` play/pause**: pixel click is often rejected
   by HTML5's click-to-play handler on some builds. Use keyboard
   instead: `press_key({pid, key: "k"})` (YouTube) or
   `press_key({pid, key: "space"})` (generic). Keyboard events
   travel through a different auth envelope.
 - **Pixel right-click on Chromium web content** coerces to a
-  left-click — a known Chromium renderer-IPC limitation that affects
+  left-click: a known Chromium renderer-IPC limitation that affects
   every non-HID-tap synthesis path. For context menus on
   AX-addressable elements (links, buttons, toolbar items), use
-  `right_click({pid, element_index})` instead.
+  `right_click({pid, element_token})` instead.
 
 ### Known text-input limits (Catalyst + Electron)
 
@@ -373,7 +397,7 @@ anything in `/Applications` that's actually `iOSAppOnMac.app`) and
 **Electron** apps (VS Code's Monaco editor, Slack composer, Discord,
 Linear), an AX `type_text` can't reach the rendered text view: the
 `AXSetAttribute(kAXSelectedText)` write succeeds on the AX shim, but
-the UIKit/Chromium view that owns the input never observes it — and on
+the UIKit/Chromium view that owns the input never observes it. On
 Electron the shim _echoes the value straight back through `AXValue`_,
 so a naive read-back "confirms" a value that isn't really there.
 
@@ -383,11 +407,11 @@ AX-path `type_text` on an Electron app returns `effect:"unverifiable"` +
 false `effect:"confirmed"`.
 (On Catalyst the AX value reads back unreadable, so it reports
 unverified too.) Bottom line: on these surfaces **do not trust the AX
-confirm — the screenshot in the same response is the only truth.**
+confirm. The screenshot in the same response is the only truth.**
 
-Fix — **one call**: `type_text({pid, window_id, x, y, text})`. Passing
-`x,y` (no `element_index`) is the **element px action** form of
-`type_text` — the tool pixel-clicks at `(x,y)` to give the Chromium /
+Fix, in **one call**: `type_text({pid, window_id, x, y, text})`. Passing
+`x,y` (no `element_token`) is the **element px action** form of
+`type_text`: the tool pixel-clicks at `(x,y)` to give the Chromium /
 UIKit renderer the real keyboard focus the AX layer can't, then types
 into the now-focused field. Read `x,y` straight off the screenshot in
 the `get_window_state` response (same convention as `click`). This is
@@ -399,22 +423,22 @@ content. Send Cmd+V only after that read-back succeeds.
 
 0. **If the control is CLOSED, open it first.** A px focus-click won't
    reliably _open and focus_ a closed control (a search button, a
-   collapsed field) — it lands on whatever is already focused (e.g.
+   collapsed field): it lands on whatever is already focused (e.g.
    the message composer), so your text leaks there. **AX-press to
    open/activate the control first** (AX actions work in the
    background), then px-type into the now-open field.
-1. **`type_text({pid, window_id, x, y, text})`** — focus + type in a
+1. **`type_text({pid, window_id, x, y, text})`**: focus + type in a
    single call. Re-snapshot and read the text off the screenshot to
    confirm; the AX value can still lag on Catalyst/Electron.
 2. Only if the keystrokes _still_ drop (a focus-polling app), escalate
    that one `type_text` with `delivery_mode:"foreground"`.
 
-The `x,y` (px) form is **mutually exclusive** with `element_index`
-(ax) — pass one or the other, not both. Why not `Cmd+V` / `hotkey`: a
+The `x,y` (px) form is **mutually exclusive** with `element_token`
+(ax): pass one or the other, not both. Why not `Cmd+V` / `hotkey`: a
 keyboard combo does **not** focus a text field, and `hotkey` /
 `press_key` no longer raise the window on their own (raising is gated
 on `delivery_mode:"foreground"`, like every other tool). The reliable
-move is the px form of `type_text` — focus and type in one call.
+move is the px form of `type_text`: focus and type in one call.
 
 ## Navigating native menu bars (AXMenuBar)
 
@@ -426,6 +450,10 @@ application, resolves each immediate child from live AX state, uses only
 on a best-effort basis.
 It refuses missing, duplicate, disabled, or non-actionable segments and never
 falls back to pixels.
+When a path fails after the tool already opened a menu, it cancels that menu
+and the refusal says whether any menu window it opened is still on screen. If
+the refusal says the menu may still be open, press `escape` on the window
+before other input.
 
 ```bash
 cua-driver invoke_menu \
@@ -488,7 +516,10 @@ starting point for new browser workflows.
 | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | macOS system-alert beep on `press_key` with no visible change | Target window is minimized; Return / Space / Tab commits don't establish real renderer focus on minimized windows | AX-click a clickable equivalent (Go button, Submit button, checkbox) instead of pressing the key; see "Keyboard commits on minimized windows" under the Browser section                                                             |
 | `Accessibility permission not granted`                        | TCC not granted                                                                                                   | Stop; tell user to grant in System Settings                                                                                                                                                                                         |
-| `Screen Recording permission not granted`                     | TCC not granted for capture                                                                                       | Screenshots and pixel actions are unavailable. If the task is AX-completable, use `get_window_state({include_screenshot:false})` and element-indexed actions; otherwise stop and ask the user to run `cua-driver permissions grant` |
+| `Screen Recording permission not granted`                     | TCC not granted for capture                                                                                       | Screenshots and pixel actions are unavailable. If the task is AX-completable, use `get_window_state({include_screenshot:false})` and `element_token` actions; otherwise stop and ask the user to run `cua-driver permissions grant` |
+| `AX action failed: ... returned -25200` (or -25205, -25206)   | The app may have acted anyway: some AppKit controls return these after a press they performed                     | Re-read with `get_window_state` before retrying; a second press on a checkbox toggles it back. A radio button or checkbox whose AXValue settles on the pressed state is reported as performed, naming the error                     |
+| `set_value refused (file_name_needs_rename)`                  | A file's name as Finder lists it: an AXValue write changes only the list, never the file                          | `click` the item, then with Finder frontmost send `press_key` return, `hotkey` cmd+a, `type_text` the full new name, `press_key` return, each with `scope:"desktop"`; re-read to confirm                                            |
+| `set_value refused (file_name_needs_rename)`                  | A file's name in Finder's Get Info window (AXIdentifier `Name`): an AXValue write changes only the field          | foreground `click` at the field's centre in screenshot pixels (with its `capture_id`), then `hotkey` cmd+a, `type_text` the full new name with its extension, `press_key` return, each with `delivery_mode:"foreground"`; a changed extension asks for confirmation first; check the folder listing |
 
 ## Example end-to-end task (macOS)
 
@@ -497,7 +528,7 @@ starting point for new browser workflows.
 1. `launch_app({bundle_id: "com.apple.finder", urls: ["~/Downloads"]})`
    → `{pid: 844, windows: [{window_id: 6123, title: "Downloads", ...}]}`.
    Idempotent launch; plus Finder opens a hidden window rooted at
-   `~/Downloads` via `application(_:open:)` — zero activation, no
+   `~/Downloads` via `application(_:open:)`: zero activation, no
    focus steal. The `windows` array lets you skip a `list_windows` hop.
 2. `get_window_state({pid: 844, window_id: 6123})` → verify an
    `AXWindow` whose title contains "Downloads" is present with a

package/dist/builtin/subagents/skills/cua-driver/README.md

@@ -7,7 +7,8 @@ CLI or MCP server.
 
 It covers the canonical snapshot-action-verify loop, exact window addressing,
 accessibility and pixel actions, background/foreground delivery, typed browser
-automation, session recording, and platform-specific limitations. The skill
+automation, optional visual-region parsing, session recording, and
+platform-specific limitations. The skill
 defaults to background delivery and requires structured refusal or observed
 failure before a caller escalates to foreground input.
 
@@ -57,17 +58,23 @@ Use `--all-platforms` when the agent assists users across operating systems.
 
 ## Reading order
 
-- `SKILL.md`: shared contract, tool selection, session identity,
-  snapshot-action-verify loop, action ladder, and failure handling.
+- `SKILL.md`: lean entrypoint, mandatory safety rules, and task-based routing.
+- `WORKFLOW.md`: exact targets, bounded snapshots, coordinates, action semantics,
+  verification, filesystem and clipboard proof.
+- `RUNTIME.md`: preflight, transport/session ownership, authorization, cursor,
+  and cleanup.
 - `MACOS.md`, `WINDOWS.md`, or `LINUX.md`: host-specific launch, capture,
   accessibility, input delivery, permissions, and refusal boundaries.
 - `BROWSER.md`: exact browser-window binding, explicit profile preparation,
   page refs, trust-classified click/type/navigation, and native fallbacks.
+- `VISUAL.md`: optional model-neutral parsing of one retained screenshot into
+  capture-bound text and icon regions.
 - `RECORDING.md`: trajectory evidence, MP4 capture, and replay.
 - `EMBEDDING.md`: embedding the driver into another host application.
 
-The agent should load `SKILL.md`, the current platform guide, and only the
-cross-cutting guide needed for the task.
+The agent loads `SKILL.md`, then only the linked guide needed for its next
+step. Every reference ships in the pack; no separate skill installation or
+repository checkout is required. The installer keeps the flat Markdown layout.
 
 ## Browser model
 
@@ -94,8 +101,10 @@ missing. See `RECORDING.md`.
 
 ## Updates and source builds
 
-The skill is versioned with Cua Driver releases. For bleeding-edge validation
-against `main`:
+The skill is versioned with Cua Driver releases. Back up personal edits before updating: updates replace the installed pack.
+The pack version does not identify the running daemon; inspect the live tool
+schema when versions differ. For bleeding-edge validation against a matching
+source build (not an arbitrary installed release):
 
 ```bash
 cua-driver skills install --from main