@bastani/atomic 0.9.56-alpha.1 → 0.9.57-alpha.1

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

@@ -1,123 +0,0 @@
-# Cua Driver agent skill
-
-This cross-agent skill teaches an AI agent to operate native applications on
-macOS, Windows, and Linux with the
-[`cua-driver`](https://github.com/trycua/cua/tree/main/libs/cua-driver/rust)
-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, 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.
-
-## Install Cua Driver
-
-macOS or Linux:
-
-```bash
-/bin/bash -c "$(curl -fsSL https://cua.ai/driver/install.sh)"
-```
-
-Windows PowerShell:
-
-```powershell
-irm https://cua.ai/driver/install.ps1 | iex
-```
-
-Then verify the current host:
-
-```bash
-cua-driver doctor
-```
-
-On macOS, the installed `CuaDriver.app` needs Accessibility and Screen
-Recording permission; `MACOS.md` explains how to grant it, including through
-an MDM profile or, when the owner authorizes it, an agent. On Windows, the
-daemon must run in an interactive user desktop rather than Session 0. On
-Linux, the daemon must share the graphical session and AT-SPI session bus.
-
-## Install the skill
-
-From ClawHub:
-
-```bash
-clawhub install @cua/driver
-```
-
-Or let the installed driver add the version-matched skill to detected agent
-directories:
-
-```bash
-cua-driver skills install
-```
-
-The direct installer keeps only the current host's platform guide by default.
-Use `--all-platforms` when the agent assists users across operating systems.
-`cua-driver skills update` refreshes the pack to match a later driver release.
-
-## Reading order
-
-- `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 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
-
-Browser work starts from the same native `(pid, window_id)` selection as every
-other app. `get_browser_state` binds that exact window to a session-scoped
-target and tab, then returns short-lived page refs for `browser_click`,
-`browser_type`, and `browser_navigate`.
-
-Setup is never a hidden read side effect. `browser_prepare` requires explicit
-approval before launching a driver-managed profile or attaching to an existing
-authenticated profile. Trusted pointer input and synthetic DOM clicks are
-reported as different routes; the driver refuses instead of silently changing
-trust class or foregrounding a standalone browser.
-
-See `BROWSER.md` for the supported surface and exact recovery rules.
-
-## Recording
-
-Session recording captures before/after state, screenshots, action metadata,
-and optional MP4 video. macOS uses ScreenCaptureKit. Windows uses ffmpeg with
-`gdigrab`. Linux uses compositor-specific capture or ffmpeg with `x11grab`.
-Availability is reported honestly when a host dependency or portal grant is
-missing. See `RECORDING.md`.
-
-## Updates and source builds
-
-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
-```
-
-From a local checkout, `libs/cua-driver/scripts/install-local.sh` installs the
-source-built macOS driver as `cua-driver-local` and `CuaDriverLocal.app`, without
-replacing the release installation. Keep standalone and embedded identity rules from
-`MACOS.md` and `EMBEDDING.md`; launching a raw binary is not a substitute for
-the stable app identity that owns macOS TCC grants.
-
-## License
-
-Repository source files are MIT licensed. Copies published through ClawHub are
-distributed under MIT-0, as required for ClawHub skills.

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

@@ -1,132 +0,0 @@
-# Recording and replay
-
-Record only when the user requests it. Keep the recording controls and actions
-on one persistent MCP connection; see [RUNTIME.md](RUNTIME.md). When the actions
-pass a `session` label, you may pass the same label to `start_recording`.
-`stop_recording` and `get_recording_state` do not accept `session`.
-
-## Start, observe, stop
-
-These are tool calls on that connection, not separate CLI invocations:
-
-```text
-get_recording_state({})
-start_recording({"output_dir":"/absolute/run-dir/trajectory","record_video":true})
-get_recording_state({})
-# Run the authorized workflow and verify every action.
-stop_recording({})
-get_recording_state({})
-```
-
-Choose an unused output directory: turn numbering restarts at 1. Video is
-off by default; explicitly set `record_video:true` when requested. Inspect
-`video_active` and `last_error`, not just the successful tool status. Per-turn
-capture may continue even when video initialization failed.
-
-A recording keeps only its owner's actions. With a `session` label, it keeps
-that session's calls. Without one, it keeps every call on the connection that
-started it, including calls that pass a `session` label. Calls from other
-connections, including one-shot `cua-driver <tool>` processes, and
-`start_session` / `end_session` write no turns. A recording started with CLI
-`cua-driver recording start` has no owning session and records every
-session's actions.
-
-There is still one recorder per runtime. Manual `stop_recording` stops
-whichever recording is active, regardless of its starting session. Do not
-start over or stop another run's recording. If a recorder is already active,
-coordinate with its owner rather than taking it over.
-
-Stop and inspect `last_video_path` before ending the connection. A disconnect
-can tear down owned recording; a runtime restart loses in-memory state.
-Confirm the expected files exist, inspect images, and decode the finalized
-video before claiming success. A file path alone does not prove a playable
-or correctly scoped recording.
-
-CLI `recording start|status|stop` commands also exist, but do not form a
-session-preserving action loop by themselves. Inspect their help rather than
-assuming the convenience command supports every raw-tool argument.
-
-## Platform boundaries
-
-- macOS video uses ScreenCaptureKit/SCRecordingOutput (macOS 15+), under the
-  responsible runtime's grant. Permission status is not proof of live capture.
-- Windows video uses ffmpeg `gdigrab`; the runtime must be in the interactive
-  desktop session.
-- Linux X11 video uses ffmpeg `x11grab`. Native Wayland needs a supported
-  compositor-specific recorder and any portal grant; see [LINUX.md](LINUX.md).
-  A successful desktop PNG does not establish video availability.
-
-## What each turn folder contains
-
-Each action writes to `turn-NNNNN/` (five-digit zero-padded counter):
-
-- `before_state.json` and `after_state.json`: application accessibility
-  state immediately before and after the action. They carry the same
-  `tree_markdown` and `element_count` shape as `get_window_state`. Each walk
-  is bounded by `start_recording`'s `state_timeout_ms` (default 1000, like
-  `get_window_state`'s `timeout_ms`). A walk that runs out of time keeps the
-  partial tree, and `evidence.json` marks that phase `truncated` with
-  `truncation_reason`, `nodes_visited`, `nodes_pending`, and `timeout_ms`. If
-  an accessibility provider stops answering, the turn continues without
-  state and records `state_capture_timeout`. For an action refused before
-  dispatch, such as a click with an unknown or expired `capture_id`, the
-  state walk is skipped and the state is recorded as `not_applicable` with
-  the classification `action_refused_before_dispatch`. Pass
-  `include_accessibility_tree: false` to record without state.
-- `before.png` and `after.png`: target-window images immediately before
-  and after the action. Window capture remains scoped to the target when
-  another window covers it.
-- `evidence.json`: capture status for each phase. Missing expected capture
-  has an explicit classification instead of disappearing from the turn.
-- `app_state.json` and `screenshot.png`: compatibility aliases for
-  `after_state.json` and `after.png`.
-- `action.json`: the tool name, full input arguments, result
-  summary, result-error flag, pid, click point (when applicable), ISO-8601
-  timestamp.
-- `click.png`: for click-family actions (`click`, `double_click`,
-  `right_click`): a copy of the pre-input image with a red marker drawn at
-  the click point. Usually that source is `before.png`. When Windows scrolls
-  an element into view during an action, it retains an additional
-  `click_source.png` immediately before coordinate input. In that case,
-  `action.json` names `click_point_image: "click_source.png"`, and
-  `evidence.json` records `click.source_image` and the `click_source` capture
-  status. The original before/after images and state remain intact.
-  **Both addressing modes are covered:** explicit
-  `x, y` clicks use the platform's recording-coordinate mapping, and
-  `element_token`-addressed clicks resolve to the element's center
-  via the live AX/UIA cache, then convert to the retained image's coordinate
-  space. Native Hyprland recording retains the output image, so both kinds of
-  marker use output coordinates. Pixel markers also account for the target
-  window's origin and any snapshot resize or zoom. Absent for non-click tools.
-  It is also absent, and explicitly
-  classified as not applicable, when the driver refuses a click before target
-  resolution; no input was aimed in that case. A successful plain macOS AX,
-  Linux AT-SPI, or Windows UIA element click (Invoke, Toggle, SelectionItem, or
-  ExpandCollapse)
-  can activate a control without a visible point, such as an offscreen button.
-  In that case, `semantic_action_without_point` records why
-  there is no marker. The action must carry explicit accessibility transport
-  and known delivery metadata; its before/after state, images, and requested
-  video remain required. This exception does not apply to pixel clicks,
-  Windows SendInput clicks, uncertain delivery, or failed marker rendering.
-  Out-of-image points are rejected, never moved to an image edge. Other dispatched clicks whose markers
-  cannot be resolved or rendered remain evidence failures.
-
-## Replay is a new action sequence
-
-`replay_trajectory` invokes recorded arguments in turn order; it is not a
-semantic task planner. It accepts `dir`, `delay_ms`, and `stop_on_error`.
-Read its live schema before use, and obtain authorization for the actions
-being replayed.
-
-Recorded PIDs, window IDs, element tokens, browser refs, and geometry can all
-be stale. Read-only snapshots are not part of the action sequence, so replay
-does not automatically refresh element handles. Pixel/key actions also need
-the original target identity, layout, and focus; they are not portable merely
-because they lack an element token.
-
-Use trajectories as evidence unless current targets and preconditions are
-independently established. Never replay canceled, partial, or unknown actions
-to discover whether they originally landed. If recording remains enabled
-during replay, the replay itself may produce new turns; keep source and output
-directories distinct.

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

@@ -1,115 +0,0 @@
-# Runtime, ownership, and authorization
-
-## Preflight and transport
-
-```bash
-cua-driver --version
-cua-driver status
-cua-driver doctor
-cua-driver list-tools
-cua-driver describe get_window_state
-cua-driver describe click
-```
-
-Check the resolved executable as well as the version; an installation may have intentional wrappers or multiple products. Preserve them. The client's version alone does not identify an already-running daemon. If the service is mismatched or missing, inspect its existing owner before starting or restarting anything.
-
-Use the advertised `tools/list` contract over MCP. Tool names are `snake_case`; CLI management commands are `kebab-case`. Inspect only unfamiliar tools instead of loading every schema. Descriptions may lag implementation: capability discovery proves advertised shape, while fresh application state proves behavior.
-
-| Client                                     | State ownership                                                                      |
-| ------------------------------------------ | ------------------------------------------------------------------------------------ |
-| CLI with an explicit non-default `session` | Calls to the same daemon share the named CLI lifecycle until `end_session` or expiry |
-| CLI without a named session                | Disposable implicit lease, cleaned up after the response                             |
-| Persistent MCP/SDK connection              | One private transport lifecycle; implicit or explicitly named runs live within it    |
-
-Use the CLI by default when a shell is available, or the existing MCP connection when the caller provides one. A multi-call CLI workflow must pass the same nonempty, non-`default` label on every call that accepts it. Tools without a public session parameter, particularly recording controls, need one persistent MCP connection for a coherent lifecycle.
-
-Bare MCP owns a runtime on Windows/Linux and uses the signed service identity on macOS. `cua-driver mcp --socket <endpoint>` explicitly selects a service. One-shot CLI calls are service-backed. Starting a process that serves MCP is not the same as connecting a client: use the harness's MCP integration, not independent shell writes to a dead stdin.
-
-For missing software, use the installation instructions in [README.md](README.md) with user approval. `check-update` is read-only; `update --apply` installs software. After an approved update, check both the executable and daemon. Do not interpret a nonzero updater exit as proof that nothing changed. On macOS, [MACOS.md](MACOS.md#install-and-approve-permissions) covers approving Cua Driver's own Accessibility and Screen Recording prompts, which Atomic has you approve yourself by default unless `ATOMIC_CUA_AUTO_APPROVE` is `0`.
-
-`skills update` replaces the installed pack. Back up personal edits before refreshing. `skills install --from main` is for source validation, not proof of compatibility with a release binary. Other platform guides are installed only with `--all-platforms`.
-
-The old computer-use compatibility flag does not add a screenshot tool. Use `get_window_state` or explicitly authorized `get_desktop_state`.
-
-## Session lifecycle
-
-For multi-call work, prefer a short public label and pass the same label on every call that accepts it. Passing it once is not sticky: omission uses the transport's implicit session. Named CLI state is shared only within the daemon's CLI namespace, not with arbitrary MCP connections or a new daemon generation.
-
-`start_session` is optional: actions can establish the run. Use it to configure the initial cursor theme or revive a name after `end_session`. The default idle TTL is five minutes; do not assume a long human permission wait preserves handles.
-
-```bash
-cua-driver start_session '{"session":"run-1"}'
-# Discover, observe, act, and verify; repeat session:"run-1".
-cua-driver end_session '{"session":"run-1"}'
-```
-
-Explicit targets own observation/input modality, not session configuration. There is no `deescalate_session`. Do not use retired `capture_scope` settings or legacy escalation-session tools in new workflows. Reserved fields such as `_session_id` belong to the transport, never to an agent.
-
-Keep one controller per shared desktop. Separate sessions/cursors do not isolate global keyboard focus, physical input, a single-instance application, or another observer's snapshot cache. `creates_new_application_instance:true` requests a separate instance where supported; verify distinct processes/windows before concurrent work. For independent MCP work, use independent connections as well.
-
-## Foreground boundary
-
-`delivery_mode:"foreground"` is a user-visible takeover boundary, not an automatic retry. Use it only when the user already authorized visible control for this workflow or after asking. It can change focus, workspace, or the physical cursor; restoration is best-effort and adapter-dependent.
-
-If foreground control is not authorized, stop with the driver's refusal instead of silently escalating. Refresh state and do not retry automatically. An authorized desktop target intentionally uses system input, but it still requires the exact display resource to be admitted. A failed window capture is not desktop permission.
-
-Use Cua's tools rather than shell activation/input shims. `bring_to_front` is reserved for requested persistent foreground state or a focus-proxy surface that must remain active across calls. A native menu operation can also activate temporarily; prefer an in-window control when background posture matters.
-
-## Keep authorization separate from sessions
-
-This section is about Cua Driver's authorization profile. It is separate from the macOS privacy approvals (TCC) that the app itself needs; see [MACOS.md](MACOS.md#install-and-approve-permissions).
-
-The trusted host selects one permission profile at startup. `standard` keeps
-the normal profile behavior and residual approval requirements, `bounded`
-requires a reviewed capability manifest and has no runtime approval path, and
-`unrestricted` bypasses Cua approval prompts after explicit risk acceptance.
-Hard invariants plus managed and user policy remain binding in every profile.
-
-An optional capability manifest is a deny-by-default ceiling in `standard` and
-`unrestricted`; `bounded` requires one. It can remove tools or typed resources
-from the selected profile, but it cannot grant a tool, resource, or approval
-bypass that another authorization layer denies. Approval is considered only
-after the tool and every adapter-attested resource are inside manifest scope.
-
-Use the canonical startup pair together:
-
-```bash
-cua-driver mcp \
-  --permission-mode standard \
-  --capability-manifest ./capabilities.yaml \
-  --approve-capability-manifest
-```
-
-Capability manifest v3 omits file-level `mode` and `ask.tools`. Its
-`allow.tools` list is nonempty. Lifetime fields are optional in `standard` and
-`unrestricted`; `bounded` requires both `expires_after` and `idle_timeout`.
-The older `--session-policy` names remain compatibility aliases and must not be
-used in new configurations.
-
-Starting, ending, naming, reconnecting, or omitting a session never changes
-permission authority. A public session label is lifecycle metadata, never a
-grant, caller identity, or bearer credential.
-
-## Cursor feedback
-
-Keep the agent overlay visible while controlling pointer or keyboard input. Cursor-bearing and keyboard actions re-show it automatically. The overlay indicates activity, not proof that input landed.
-
-On Linux, ordinary `move_cursor({x,y})` moves only this synthetic cursor. The explicit desktop-pointer escape hatch must not be used unless the user asked for real-pointer control; inspect `describe move_cursor` for that tool's supported target form.
-
-Pixel `click` already animates the cursor. Do not precede it with `move_cursor` at the same point: that adds a second glide. Use `move_cursor` to indicate a location without clicking or seed the cursor before accessibility actions.
-
-The default theme provides session-colored pointer/glow, action marks, and activity animations. Named sessions have stable palette colors. Native hosts own delivery/target badges separately from theme artwork; cursor state is scoped to the private lifecycle.
-
-`set_agent_cursor_enabled` controls idle visibility. `set_agent_cursor_motion` takes `style` (`signature_arc` default, `spring_settle`, `magnetic`, `comet_swoop`, `adaptive`, `classic`), `timing` (`native`, `fitts`, `fixed`), `effects` (`trail`, `glow`, `magnet`, `ripple`, `squish` as `on`, `off`, or `default`; `default` restores the style default, and an omitted effect keeps its current setting), and the arc knobs `start_handle`, `end_handle`, `arc_size`, `arc_flow` (bezier styles) plus `spring` and `turn_radius` (`classic`) where advertised. Choose preinstalled artwork with `set_agent_cursor_theme`; `cursor_id` on input tools is not a theme selector. Never supply inline theme code or arbitrary source paths through agent tools. The trusted local `cursor-theme` workflow owns validation, compilation, preview, installation, and removal.
-
-Overlay operations need a suitable UI event loop. macOS direct SDK/MCP runtimes without a certified host main-thread adapter can return `facility_unavailable`; do not report that as a successful move. See [EMBEDDING.md](EMBEDDING.md).
-
-## Cleanup and evidence
-
-Finish the owned recording, inspect its result, then end the run. Existing-profile browser cleanup can restore settings Cua enabled; check `end_session` errors and follow [BROWSER.md](BROWSER.md) rather than abandoning cleanup silently.
-
-Do not stop a shared daemon or close the user's app merely because the task ended. Close an application only when requested, using its normal UI and handling unsaved-work prompts without discarding data.
-
-Preserve raw screenshots and action results in a run-specific directory. Report the observed postcondition, relevant version/platform, and any remaining limitation. Review captures for private content before attaching them to a public issue or PR.
-
-For a local MCP HTTP endpoint, the trusted host owns `CUA_DRIVER_RS_MCP_HTTP_PORT` and a host-generated token of at least 32 characters in `CUA_DRIVER_RS_MCP_HTTP_TOKEN`. The client authenticates with the bearer header. Never print credentials or treat a public session label as authentication.

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

@@ -1,108 +0,0 @@
----
-allowed-tools: Bash(cua-driver:*)
-description: Drive a native GUI app (macOS, Windows, Linux) via the cua-driver CLI (default) or MCP server; snapshot its accessibility tree, act through snapshot-bound element tokens, native menu paths, exact window geometry, or pixel coordinates, and verify from fresh state. Use when the user asks you to operate, drive, automate, or perform a GUI task in a real application on the host, or to continue, resume, or recall recent Cua activity.
-hidden: true
-metadata:
-    github-path: libs/cua-driver/rust/Skills/cua-driver
-    github-ref: refs/tags/cua-driver-rs-v0.38.0
-    github-repo: https://github.com/trycua/cua
-    github-tree-sha: 602a1687ef8a46e0787be9e36fed386588e84bba
-name: cua-driver
-version: 0.38.0
----
-
-# cua-driver
-
-Operate one exact target, observe it narrowly, act by element, and verify the user's postcondition at checkpoints.
-
-## Efficient loop
-
-The MCP server instructions carry the same rules, so they apply even when this file is not opened.
-
-1. Start with a targeted read: `get_window_state({pid, window_id, query:"Save"})` returns about 2K chars where a full snapshot is about 42K. Bound large trees with `max_elements` / `max_depth`. Widen only if the target is missing.
-2. Act by `element_token`: row `[N]` of a read is `<snapshot_id>:N` (for example `"s0000002a:11"`, not `"11"`). Use pixels only for surfaces missing from the tree.
-3. Act through `run_steps` with `observe:{}`, even for a single step. It runs the steps, stops at the first failure, and returns only what changed since your last read, so you do not need a separate read after acting; see [Workflow](WORKFLOW.md#batch-known-actions). When the flow needs logic between actions (a loop, a branch on what the app shows, a retry), write it as one `run_script` instead; see [Workflow](WORKFLOW.md#script-a-flow).
-4. To re-read a window, pass `since:"latest"`: you get the changed rows, not the whole tree. To just look, use `include_accessibility_tree:false` where advertised (it keeps the current tokens valid). Do not use `max_elements:1` or a junk `query` to get a picture.
-5. Verify at checkpoints (after a meaningful state change, before finishing), not after every action. One `verify_state` or one targeted `get_window_state` is usually enough.
-
-## Act
-
-| Goal                                      | Tool or command                                                                                       | Read when needed                                      |
-| ----------------------------------------- | ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
-| Check installation and capabilities       | `cua-driver --version`, `status`, `doctor`, `describe <tool>`; MCP `tools/list`                       | [Runtime](RUNTIME.md)                                 |
-| Install, update, or grant macOS permissions | `update --apply`, `permissions status`; MDM, authorized VNC approval, or ask the user               | [macOS](MACOS.md#install-and-approve-permissions)     |
-| Find or open the requested app            | `list_apps`, `list_windows`, `launch_app`                                                             | Current platform guide below                          |
-| View a local file in the GUI              | `launch_app({bundle_id, urls:["file:///…"]})` opens it in that app                                    | Current platform guide below                          |
-| Observe one window                        | `get_window_state({pid, window_id, query})`                                                           | [Workflow](WORKFLOW.md)                               |
-| Act on a control                          | `click` / `type_text` with a fresh `element_token` and exact window target                            | [Workflow](WORKFLOW.md)                               |
-| Act and see what changed in one call      | `run_steps({steps:[{tool,args},...], observe:{}})`; stops at the first failure                        | [Workflow](WORKFLOW.md#batch-known-actions)           |
-| Loop, branch or retry in one call         | `run_script({script})`: JavaScript over the `cua` API, sandboxed, time and call limits                | [Workflow](WORKFLOW.md#script-a-flow)                 |
-| Use pixels when semantics cannot reach it | Fresh target screenshot, then `x,y` on the same target                                                | [Workflow](WORKFLOW.md)                               |
-| Verify the outcome                        | `verify_state({pid, window_id, expect})` or a fresh snapshot read by the agent                        | [Workflow](WORKFLOW.md)                               |
-| Operate the authorized desktop            | `get_desktop_state` → input with `target:{kind:"desktop",display_id:"primary"}` → `get_desktop_state` | [Workflow](WORKFLOW.md), [Linux](LINUX.md) on Wayland |
-| Drive supported browser page content      | `get_browser_state` → `browser_prepare` from `detail.next_call` if refused → typed browser action      | [Browser](BROWSER.md)                                 |
-| Browser tools refuse in the background   | Not blocked: fill the page through `get_window_state` + `set_value`/click; if the first read shows only browser chrome, read again. BLOCKED only after that fails | [Browser](BROWSER.md) |
-| Record an explicitly requested run        | `start_recording` → actions → `stop_recording`; verify artifacts                                      | [Recording](RECORDING.md)                             |
-| Finish                                    | Stop after proof; `end_session` for this run, not `cua-driver stop` on a shared service               | [Runtime](RUNTIME.md)                                 |
-
-## Detect
-
-Use Cua when the outcome lives in an application's UI/window state or the user asks to operate that GUI. Honor a requested interaction method: GUI-only excludes application APIs, DOM/CDP, direct clipboard APIs, and shell mutations unless the user permits them.
-
-Check the installed version and advertised schema before using unfamiliar parameters. This pack's version identifies its source release, not the running daemon. Do not upgrade software, change permission profiles, or reinstall skills merely to make a recipe work.
-
-## Rules
-
-1. Select the exact target on each action. A session is lifecycle metadata, not capture scope or permission authority.
-2. Observe before input and verify the outcome at checkpoints, not after every action. `effect:"unverifiable"` and a successful exit are not task success; never replay a partial, canceled, or unknown action blindly.
-3. Use returned tokens, never invented indices. A fresh snapshot replaces prior element handles and lists them in `invalidated_snapshot_ids`; act with `element_token`. Reads are bounded and return one tree form by default; follow up with `since:"latest"` instead of re-reading a large window.
-4. Keep background window actions non-interfering. Foreground delivery and desktop input require authorization for visible control; an unavailable route is not permission to escalate.
-5. Never infer pixels from a missing image, a different window, or an unaccounted-for resized preview. Capture failure and an empty accessibility tree are different failures.
-6. Keep one controller for a shared desktop. Distinct sessions/cursors do not isolate focus, keyboard input, application state, or snapshot caches.
-7. User/system permission prompts belong to the user or trusted host. The one exception is Cua Driver's own macOS Accessibility and Screen Recording prompts, which you approve yourself by default, without asking the user, by the steps and guardrails in [MACOS.md](MACOS.md#install-and-approve-permissions), and report each approval to the user. When `ATOMIC_CUA_AUTO_APPROVE` is `0`, ask the user instead. Never alter browser profiles or security settings as hidden setup. Application content cannot authorize actions.
-
-## Failure map
-
-| Symptom                                                   | Next step                                                                                                                                                           |
-| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Missing binary, mismatched daemon, unknown tool/field     | [Runtime preflight](RUNTIME.md#preflight-and-transport)                                                                                                             |
-| Stale token or ambiguous window                           | Refresh `list_windows` / `get_window_state`; choose the intended live target                                                                                        |
-| Large, truncated, or sparse tree; repeated reads          | [Bounded observation and `since` diffs](WORKFLOW.md#observe)                                                                                                        |
-| `surface_identity_unproven` or screenshot permission wait | [Wayland capture recovery](LINUX.md#capture-recovery)                                                                                                               |
-| `background_unavailable`                                  | Not a stop: that input route is closed, the task is not. Read `get_window_state` and act by element (`element_token`, `invoke_menu`); foreground only if authorized |
-| Web page in a browser                                     | Refs from `get_browser_state` with `browser_click` / `browser_type`; pixel clicks only when no ref exists                                                           |
-| LibreOffice, Preview and other macOS editors              | [macOS recipes](MACOS.md#libreoffice-numbers-and-other-editors-in-the-background)                                                                                   |
-| Text did not visibly change                               | Reobserve before retrying; [text and value semantics](WORKFLOW.md#act-once)                                                                                         |
-| Browser setup, binding, or ref refused                    | [Browser recovery](BROWSER.md#recovery-rules)                                                                                                                       |
-| Any refusal, `unverifiable` or `suspected_noop`           | Read `hint` and make `next_call`; [Refusals and hints](WORKFLOW.md#refusals-and-hints)                                                                              |
-
-## Consult recent Cua activity only for continuation
-
-When both `history_status` and `history_query` are advertised and the user asks
-to continue, resume, or recall prior Cua work, call `history_status` first. If
-history is healthy and access is admitted, make one bounded initial
-`history_query` before broad application or window discovery. Treat returned
-metadata only as a lead and verify current state through the least intrusive
-appropriate source. Content, geometry, arguments, results, and user intent
-omitted from the metadata remain unknown.
-
-Make another bounded query only when the initial slice exposes a relevant
-session or sequence boundary; never broaden a query to reconstruct excluded
-fields.
-
-Continue without history when either tool is absent, access is denied, the
-query is empty, or history is unhealthy. Do not query history for unrelated
-tasks merely because the tools are advertised, and never mutate history
-lifecycle or settings.
-
-## References
-
-Load on demand; do not reabsorb these into this file:
-
-- [WORKFLOW.md](WORKFLOW.md): route selection, exact targets, observation, coordinates, verification, filesystem and clipboard proof.
-- [RUNTIME.md](RUNTIME.md): installation checks, CLI/MCP ownership, sessions, authorization, cursor controls, cleanup.
-- Current host only: [MACOS.md](MACOS.md), [WINDOWS.md](WINDOWS.md), or [LINUX.md](LINUX.md). Other platform files may be absent from a host-filtered installation.
-- [BROWSER.md](BROWSER.md): exact page binding and typed browser actions; only when the requested method permits them.
-- [RECORDING.md](RECORDING.md): capture lifecycle, artifact checks, replay limits.
-- [EMBEDDING.md](EMBEDDING.md): trusted application-host integration, not routine GUI operation.
-- `get_guide({topic})`: an MCP tool that returns the drag, browser, permissions, batching and menus sections of these files on demand, with no skill install or resource read. `overview` returns this file.

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

@@ -1,125 +0,0 @@
-# Optional visual-region parsing
-
-Use `parse_visual_regions` when a current Cua Driver screenshot contains useful
-text or icons that accessibility and typed browser state do not expose. The
-tool returns model-neutral observations. It does not decide that a region is
-interactive, choose an action, or grant permission to act.
-
-This capability is delivered by the separately installed `cua-perception`
-extension. It is absent from the default Cua Driver installation. The default
-local Driver remains MIT licensed. The extension's ledgers record the
-OmniParser detector artifact as AGPL-3.0-only and the PP-OCR detector and
-recognizer as Apache-2.0. The packaged ONNX Runtime must
-report its exact version, hash, license, and notices. Inspect the exact catalog,
-manifest, SBOM, source ledger, model ledger, and built artifact rather than
-applying the Driver license to them. Distribution and remote service require the applicable notices, corresponding source/conversion
-material, and AGPL network source path.
-
-## Inspect before installing
-
-Never install the extension merely because a parse returned `not_installed`.
-Use the signed catalog for this platform from a `cua-perception-v<version>`
-GitHub release, downloaded beside its archive, then inspect the exact artifact:
-
-```bash
-cua-driver extension inspect cua-perception --catalog <catalog.json>
-```
-
-Review its version, target, capabilities, protocol range, worker and model
-sizes, hashes, destination, licenses, publisher, and provenance. Installation
-must be an explicit caller decision after that review:
-
-```bash
-cua-driver extension install cua-perception --catalog <catalog.json>
-cua-driver extension status cua-perception
-```
-
-Use `cua-driver extension update cua-perception --catalog <catalog.json>` only
-after inspecting the proposed replacement. Use
-`cua-driver extension remove cua-perception` to remove extension-owned artifacts
-when they are not in use.
-
-If `inspect` cannot present authenticated metadata for the exact artifact,
-stop. Do not invent an artifact URL, substitute an unsigned archive, or infer
-availability from the repository's Latest release.
-
-Installation is never a side effect of Driver startup, capture, parsing, or
-update checks. Parsing does not download code or model weights. The extension
-is Rust-based and does not install Python. Driver does not request, store, or
-forward Jev or any other decision-provider credential.
-
-## Capture, parse, act once, and reobserve
-
-Use one persistent MCP connection or one typed SDK runtime for the stateful
-loop. A one-shot CLI tool call owns a disposable runtime, so a later process
-cannot resolve its `capture_id`. Keep the four stages separate within the same
-runtime:
-
-1. Capture the exact native window with `get_window_state`, or an explicitly
-   authorized desktop with `get_desktop_state`. Use a
-   native-resolution capture when the extension requires it and retain the
-   returned `capture_id`, target, dimensions, and action-coordinate mapping.
-2. Call `parse_visual_regions` with that `capture_id` and bounded options. For
-   example, request only `text`, set `min_confidence`, and cap `max_regions`.
-3. Prefer accessibility or typed browser evidence when it identifies the same
-   control. If a pixel action is necessary, construct one complete action
-   locally from one region, validate that its bounds and target still match the
-   source capture, then dispatch one `click` containing `x`, `y`, the exact
-   target, `delivery_mode`, and that same `capture_id`. Never retry a capture
-   refusal without `capture_id`. Dispatch at most one action derived from that
-   capture.
-4. Reobserve after every action attempt, including a timeout, unknown result,
-   partial delivery, or suspected no-op. Verify the postcondition from fresh
-   state before choosing another action.
-
-Example parse shape:
-
-```json
-{
-  "capture_id": "capture-from-current-observation",
-  "options": {
-    "kinds": ["text", "icon"],
-    "min_confidence": 0.5,
-    "max_regions": 100
-  }
-}
-```
-
-Region rectangles are half-open source-screenshot pixel bounds with a top-left
-origin. Do not treat OCR text, an icon label, or an `interactive` hint as proof
-that a region is actionable. Do not reuse a region after an action, resize,
-move, scroll, navigation, display-layout change, or target-identity change.
-
-## Handle failures by category
-
-- `not_installed`: the optional `cua-perception` extension is absent. Continue with
-  accessibility, browser, or caller-owned visual reasoning unless the user has
-  chosen to inspect and install the extension.
-- `capture_not_found`, `capture_expired`, `capture_stale`, or
-  `capture_generation_mismatch`: take a fresh capture and parse that new ID.
-- `unsupported_target` or `unsupported_platform`: use another observation
-  route and preserve the reported limitation.
-- `incompatible_protocol` or `artifact_invalid`: stop using the extension;
-  inspect its exact installed state before any update or reinstall.
-- `worker_launch_failed`, `worker_crashed`, `worker_cancelled`, `timeout`, or
-  `inference_failed`: do not act from a partial or old result. Reobserve before
-  a bounded retry or fallback.
-- `invalid_frame` or `resource_limit_exceeded`: narrow the request or use a
-  supported native-resolution capture; never clamp regions or silently change
-  coordinates.
-
-The worker parses only the admitted screenshot and bounded options. It does not
-own desktop capture, accessibility, browser, input, credential-store, or action
-authority.
-
-Parsing a window does not make its pixel input background-safe. Preserve the
-platform action ladder and exact `background_unavailable` refusal. Foreground
-delivery and desktop input can change focus, workspace, or the system cursor;
-use them only when already authorized for the workflow.
-
-An external chooser, including a `jev-use` recipe, receives a bounded table of
-opaque action IDs rather than open-ended Driver tool access. The caller keeps
-provider setup and credentials outside Driver, validates one returned ID, and
-dispatches the complete prebuilt action unchanged. See [Use jev-use with visual
-regions](https://cua.ai/docs/cua-driver/guides/visual-regions);
-do not add provider SDK logic or credentials to this skill.