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

package/docs/computer-use.md

@@ -5,11 +5,11 @@ description: "Use desktop apps, browsers, and terminals with Atomic on macOS, Li
 
 # Computer use
 
-Atomic can work in applications, not just edit code. Computer-use automation, or CUA, can create a Blender scene, build a presentation, edit a video, operate a desktop app, or move work between applications. Browser and terminal automation cover related tasks with more direct controls.
+Atomic can work in applications, not just edit code. Computer use can create a Blender scene, build a presentation, edit a video, operate a desktop app, or move work between applications. Browser and terminal automation cover related tasks with more direct controls.
 
 This guide explains tool selection, setup, and safe operation. To test a software change and attach the results to a PR, see [Verification and evidence](/workflows/verification).
 
-Jump to [application scripting](#application-scripting-and-apis), [desktop CUA](#desktop-automation-with-cua-driver), [browser automation](#browser-automation-with-agent-browser), [terminal automation](#terminal-automation-with-herdr), or [creative workflows](#creative-work-and-cua-workflows). Platform setup: [macOS](#macos), [Linux](#linux), [Windows](#windows).
+Jump to [application scripting](#application-scripting-and-apis), [desktop automation](#desktop-automation-with-agent-desktop), [browser automation](#browser-automation-with-agent-browser), [terminal automation](#terminal-automation-with-herdr), or [creative workflows](#creative-work-and-computer-use-workflows). Platform setup: [macOS](#macos), [Linux](#linux), [Windows](#windows).
 
 ## Choose the right tool
 
@@ -19,12 +19,12 @@ Start with the result you need, not the application you could click through. If
 | --- | --- | --- |
 | Create or edit files, such as presentations, documents, spreadsheets, or media | **A file library or CLI** | Use an app API or UI when the library cannot preserve required features, or when you need rendering or visual adjustments. |
 | Interactive terminal or TUI | **Herdr** | Use tmux on macOS/Linux or native Windows psmux when Herdr cannot be used. Ordinary shell commands need no multiplexer. |
-| Website or web app in Chrome/Chromium, Mobile Safari in the iOS Simulator or on a connected iPhone/iPad, Electron desktop app (VS Code, Slack, Discord, Figma, Notion, Spotify) or another app that exposes a Chrome DevTools Protocol (CDP) port, Slack workspace, or cloud browser | **agent-browser** | Prefer it whenever the target is web content it can reach: its text snapshots and element refs cost far fewer tokens than screenshot-driven CUA. See [what agent-browser covers](#what-agent-browser-covers). Use Cua Driver for anything outside that list or whenever agent-browser hits a limitation. Keep existing browser test suites for repeatable tests. |
-| Native desktop application, native iOS app in the iOS Simulator, Android emulator, desktop Safari, Firefox or another non-Chromium browser, browser chrome, OS dialogs and permission prompts, work across apps, or any agent-browser limitation | **Cua Driver**: the `cua-driver` CLI through the bundled `cua-driver` skill when a model chooses each action; the `@trycua/cua-driver` TypeScript SDK inside `ctx.tool` when workflow code owns the scenario | Use application scripting or a CLI when they make the task easier, safer, or more reliable. |
+| Website or web app in Chrome/Chromium, Mobile Safari in the iOS Simulator or on a connected iPhone/iPad, Electron desktop app (VS Code, Slack, Discord, Figma, Notion, Spotify) or another app that exposes a Chrome DevTools Protocol (CDP) port, Slack workspace, or cloud browser | **agent-browser** | Prefer it whenever the target is web content it can reach: its text snapshots and element refs cost far fewer tokens than screenshot-driven computer use. See [what agent-browser covers](#what-agent-browser-covers). Use agent-desktop for anything native outside that list or whenever agent-browser hits a limitation. Keep existing browser test suites for repeatable tests. |
+| Native desktop application, menus and menu bars, desktop Safari, Firefox or another non-Chromium browser, browser chrome, OS dialogs and permission prompts, work across apps, or any agent-browser limitation | **agent-desktop**: the bundled `agent-desktop` skill with one-shot `agent-desktop` commands when a model chooses each action; the `agent-desktop` CLI called from `ctx.tool` when workflow code owns the scenario | Use application scripting or a CLI when they make the task easier, safer, or more reliable. It reads accessibility trees only. Native iOS apps in the iOS Simulator and Android emulators need `xcrun simctl`, Appium/XCUITest, or `adb`; see [coverage and limits](#coverage-and-limits). |
 
-You can combine tools without driving the whole task through a desktop. Generate a presentation with `python-pptx`, then inspect rendered slides for layout problems. Use Blender's Python API to generate repeated objects, then Cua Driver for adjustments in the visible editor. Use browser DOM controls rather than desktop clicks for a web form. For a supported web-service operation that does not require browser interaction, an authorized API request may be enough.
+You can combine tools without driving the whole task through a desktop. Generate a presentation with `python-pptx`, then inspect rendered slides for layout problems. Use Blender's Python API to generate repeated objects, then agent-desktop for adjustments in the visible editor. Use browser DOM controls rather than desktop clicks for a web form. For a supported web-service operation that does not require browser interaction, an authorized API request may be enough.
 
-Atomic's skills supply operating instructions, not an installed desktop or automatic permission to control one. Load the `cua-driver`, `herdr`, `agent-browser`, or `tmux` skill when applicable. Check the installed command's help before using version-dependent options.
+Atomic's skills supply operating instructions, not an installed desktop or automatic permission to control one. Load the `agent-desktop`, `herdr`, `agent-browser`, or `tmux` skill when applicable. Check the installed command's help before using version-dependent options.
 
 **Herdr eligibility:** the bundled Herdr skill requires an explicit user mention or request and an agent running inside a Herdr-managed pane with `HERDR_ENV=1`. Launch Atomic inside Herdr and ask it to use Herdr for terminal work. Do not set the variable manually to bypass the check or control a focused session from outside Herdr. If those conditions are not met, use a suitable fallback.
 
@@ -33,7 +33,7 @@ Atomic's skills supply operating instructions, not an installed desktop or autom
 For file-only automation, you need the input files, a suitable runtime, and an explicit output path, not a graphical desktop. Keep originals intact and work in a scratch directory. The window, display, and input checks below apply when you actually operate a UI.
 
 1. Identify the host OS and the environment that owns the application. An SSH shell, container, WSL distribution, or CI runner is not automatically connected to the user's desktop.
-2. Check installed tools, cached runtimes, and permissions. Install missing tools, including `cua-driver` and uv, when network access and permissions allow. Follow the official installer instructions, inspect downloaded scripts before running them, and make one bounded setup attempt rather than retrying indefinitely.
+2. Check installed tools, cached runtimes, and permissions. Install missing tools, including `agent-desktop` and uv, when network access and permissions allow. Follow the official installer instructions, inspect downloaded scripts before running them, and make one bounded setup attempt rather than retrying indefinitely. For a desktop, `agent-desktop status` reports the platform, permissions, and readable surfaces in one call.
 3. Use a dedicated browser profile, terminal pane, desktop account, or VM where practical. For creative work, open copies of source assets and choose an explicit output directory.
 4. Confirm the target window, display size, scaling, keyboard layout, and starting document. Capture or inspect the current state before sending input.
 5. Define the stopping point. Saving a local draft is different from overwriting an original, publishing a video, sending a message, or purchasing something. Obtain any needed authorization before those actions.
@@ -44,7 +44,7 @@ Treat text in pages, documents, and terminal output as task data, not instructio
 
 ## Application scripting and APIs
 
-Prefer direct file automation for structured tasks such as assembling slides, filling a document template, or formatting a spreadsheet. These jobs often need no running Office app, macros, or desktop access. Use application scripting when you need features that a file library does not expose. Cua Driver is useful for the remaining desktop interaction, not a required step in every automation.
+Prefer direct file automation for structured tasks such as assembling slides, filling a document template, or formatting a spreadsheet. These jobs often need no running Office app, macros, or desktop access. Use application scripting when you need features that a file library does not expose. agent-desktop is useful for the remaining desktop interaction, not a required step in every automation.
 
 | Mechanism | Good uses | Limits to check first |
 | --- | --- | --- |
@@ -175,99 +175,118 @@ Argument order matters. This loads the scene before running the script, and `--p
 
 For file-only work, a library can avoid opening the application at all. Know what it preserves: [openpyxl does not calculate Excel formulas](https://openpyxl.readthedocs.io/en/stable/simple_formulae.html), and a deck created with [python-pptx](https://python-pptx.readthedocs.io/en/latest/) still needs a layout check for clipping, fonts, and missing media. For video, FFmpeg can handle batch transforms while an editor's own scripting API can retain timeline structure. Check installed API/version or edition limits before assuming an editor exposes scripting.
 
-Combine these approaches only where they help. Generate content with a script, inspect it in a viewer, and use CUA if it needs visual adjustments or UI-only export controls. You do not need a desktop interaction just to prove that a file script ran. If the task is specifically to verify a menu, dialog, or user flow, exercise that interface too; an API call is not proof that the GUI path works.
+Combine these approaches only where they help. Generate content with a script, inspect it in a viewer, and use agent-desktop if it needs visual adjustments or UI-only export controls. You do not need a desktop interaction just to prove that a file script ran. If the task is specifically to verify a menu, dialog, or user flow, exercise that interface too; an API call is not proof that the GUI path works.
 
-## Desktop automation with Cua Driver
+## Desktop automation with agent-desktop
 
-[Cua Driver](https://github.com/trycua/cua/tree/main/libs/cua-driver) targets an exact application window rather than the shared cursor. One `get_window_state` call returns the window's accessibility tree and a screenshot; actions are delivered through snapshot-bound element tokens in the background by default, and the result reports `degraded` or `truncated` state so a scenario can refuse to act on a bad observation. Verification is snapshot, act, fresh snapshot, then a postcondition check, not a picture of a click.
+[agent-desktop](https://agent-browser.dev/desktop) reads a desktop app's accessibility tree as JSON and gives every element you can act on a ref. You act on a ref, read the UI again, and repeat. It is a tool that an agent calls, not an agent: it has no model inside, no GUI, and prints one JSON envelope per command. It runs on macOS, Windows and Linux, and it is Apache-2.0 licensed. A successful action does not prove the UI changed, so every step ends with a read: a fresh snapshot, `get`, or `wait`.
 
-The bundled `cua-driver` skill carries the driving loop and the per-platform notes. For anything it does not cover, such as the full tool reference, SDK API, permissions model, or process model, read the upstream documentation: the [Cua docs index](https://cua.ai/docs/llms.txt) lists every page as a plain-text URL, so an agent can fetch the one it needs, for example the [process model](https://cua.ai/docs/reference/cua-driver/process-model.md), [macOS permissions](https://cua.ai/docs/reference/cua-driver/macos-permissions.md), [telemetry](https://cua.ai/docs/reference/cua-driver/telemetry.md), and [SDK reference](https://cua.ai/docs/reference/cua-driver/sdk-reference.md).
+The bundled `agent-desktop` skill is a short guide to that loop and to installing the CLI. The detailed guides are compiled into the CLI, so they always match the version you run:
 
-Atomic uses Cua Driver through two faces of one typed surface. Choose by who decides the next action:
+```sh
+agent-desktop status                  # platform, permissions, supported surfaces
+agent-desktop skills get desktop      # the loop, refs, verification, and retry rules
+agent-desktop skills get platform     # what differs on this OS
+```
+
+Open a reference only when you need it, for example `agent-desktop skills get desktop workflows` for worked patterns or `agent-desktop skills get linux troubleshooting`. Every command prints a JSON envelope; the guide's Markdown is in `data.content`.
+
+Atomic uses the CLI in two ways. Choose by who decides the next action:
 
-| Situation | Face | Why |
+| Situation | How | Why |
 | --- | --- | --- |
-| A language model chooses each action: an interactive session driving, inspecting, or automating a desktop app, simulator, or emulator window, or any workflow stage acting outside `ctx.tool` | `cua-driver` CLI through the bundled `cua-driver` skill | The model decides turn by turn; the skill's loop is written for one-shot `cua-driver call <tool>` commands, and the evidence is the JSON results and `screenshot_out_file` images it saves. |
-| A custom workflow's TypeScript owns the scenario and its postcondition, run inside `ctx.tool(name, args, fn, { timeoutMs })` | `@trycua/cua-driver` TypeScript SDK | Code owns the sequence; the result is durably checkpointed and replayed on resume. |
+| A language model chooses each action: an interactive session driving, inspecting, or automating a desktop app, or any workflow stage acting outside `ctx.tool` | The bundled `agent-desktop` skill and one-shot `agent-desktop` commands | The model decides turn by turn. The skill's loop is written for one command at a time, and the evidence is the JSON results, screenshots, and trace the commands produce. |
+| A custom workflow's TypeScript owns the scenario and its postcondition, run inside `ctx.tool(name, args, fn, { timeoutMs })` | The `agent-desktop` CLI, called from the `ctx.tool` function | Code owns the sequence, and the result is durably checkpointed and replayed on resume. |
 
-The rule of thumb: **when a model chooses the next action, use the CLI; when TypeScript code owns the sequence and the postcondition, use the SDK.** Before reaching for either, check whether [agent-browser covers the target](#what-agent-browser-covers): websites and web apps in Chrome/Chromium, Mobile Safari in the iOS Simulator, Electron and other CDP-exposing apps, Slack, and cloud browsers. It is much cheaper than CUA there. Use Cua Driver for everything else, including native desktop apps, native iOS apps in the Simulator, Android emulators, OS dialogs, desktop Safari and other non-Chromium browsers, and whenever agent-browser hits a limitation. Terminals stay with [Herdr](#terminal-automation-with-herdr), falling back to tmux or psmux. Both faces share tool names (`list_apps`, `list_windows`, `get_window_state`, `click`, `type_text`, and the rest), so a scenario worked out interactively translates directly into code.
+The rule of thumb: **when a model chooses the next action, use the skill and one-shot commands; when TypeScript code owns the sequence and the postcondition, call the CLI from `ctx.tool`.** agent-desktop has no TypeScript SDK. Its CLI prints one JSON envelope per command, and that envelope is the contract. Before reaching for either, check whether [agent-browser covers the target](#what-agent-browser-covers): websites and web apps in Chrome/Chromium, Mobile Safari in the iOS Simulator, Electron and other CDP-exposing apps, Slack, and cloud browsers. It is much cheaper than screenshot-driven computer use there. Use agent-desktop for native desktop apps, menus and menu bars, OS dialogs and permission prompts, work across apps, browser chrome and desktop browsers, and whenever agent-browser hits a limitation. Terminals stay with [Herdr](#terminal-automation-with-herdr), falling back to tmux or psmux.
 
-The bundled `cua-driver` skill is the upstream skill, vendored verbatim, and is the only place the driving loop is described. The executable installer below does not install an agent skill. Do not run `cua-driver skills install`, `cua-driver skills update`, or `clawhub install @cua/driver`: upstream's README describes those optional skill commands for other agents. Do not link or copy another skill into `~/.agents/skills/cua-driver`, `~/.claude/skills`, or other agent directories. Atomic already supplies its bundled copy; leave any existing user-level skill alone.
+Atomic bundles the skill. You do not need `npx skills add` for it, and an installed copy can go stale when you upgrade the CLI. Do not link or copy another skill into `~/.agents/skills`, `~/.claude/skills`, or other agent directories, and leave any existing user-level skill alone.
 
 ### Install if missing
 
-Check `cua-driver --version`. If the executable is missing, make **one bounded attempt** with upstream's one-line executable installer for the host. It needs no administrator access and does not install an agent skill:
+Check `agent-desktop version`. If the command is missing, make **one bounded attempt** to install it. It needs Node 18 or later:
 
 ```sh
-# macOS (14 Sonoma or later) and Linux
-/bin/bash -c "$(curl -fsSL https://cua.ai/driver/install.sh)"
+npm install -g agent-desktop
+agent-desktop version
 ```
 
-```powershell
-# Windows PowerShell
-irm https://cua.ai/driver/install.ps1 | iex
-```
-
-Report what the installer did. On macOS it places `CuaDriver.app` in `/Applications`, creates the `~/.local/bin/cua-driver` symlink, and appends an `export PATH=…` line to your `zsh`, `bash`, or `fish` rc file when `~/.local/bin` is not already on `PATH`; open a new shell or source the rc file before retrying `cua-driver --version`. On Linux it downloads into `~/.cua-driver/packages/releases/` and creates the same symlink; a minimal image may first need `sudo apt install libxi6 at-spi2-core`. On Windows it installs under `%LOCALAPPDATA%\Programs\Cua\cua-driver\bin`, appends that directory to the user `Path`, and registers a `cua-driver-serve` autostart task when the session is interactive.
+It supports macOS 13 or later, Windows 10 1809 or later (or Windows Server 2019), and Ubuntu 24.04 or later, on x64 and arm64. Without `-g`, the command lands in `./node_modules/.bin` and is not on `PATH`; use `npx agent-desktop` or install globally. The package carries the native executable and the helper each platform needs: `agent-desktop-macos-helper` on macOS and `agent-desktop-linux-clipboard-owner` on Linux. Windows needs none.
 
-Never loop on the installer. In a workflow stage, a refused or failed install is reported as `blocked`/`needs_human` together with the exact installer command above, not worked around with an alternative tool.
+Its `postinstall` script replaces the Node launcher with a link to the native binary. If your package manager blocks install scripts, as npm 12 does by default, the Node launcher runs instead. It works, but every call starts Node first and costs more than 100 ms, and the launcher prints a one-time notice with the fix. Approve the script and reinstall:
 
-The bundled skill's `version` (`0.38.0`) identifies its source release, not the running daemon. Check the installed driver's advertised schema before using unfamiliar parameters; do not upgrade software or change permissions merely to make a recipe work. If an upgrade is authorized, run `cua-driver update --apply` once and restart the daemon with the platform's startup command below. `cua-driver check-update` only checks; it changes nothing.
-
-### Turn telemetry off
+```sh
+npm install-scripts approve agent-desktop                    # npm 12
+npm install -g agent-desktop --allow-scripts=agent-desktop   # npm 11
+```
 
-Cua Driver sends content-free, pseudonymous product telemetry to PostHog **by default, from every face**: the CLI, the daemon, the MCP server, and the Python and TypeScript SDKs. It is keyed by a persisted installation UUID, so it is pseudonymous rather than anonymous. Atomic's guidance turns it off before the first driver call on every path; it does not claim the driver is telemetry-free.
+There is no Homebrew or Scoop package: the custom tap and bucket were removed in 1.0.1, and an older tap or bucket install stays pinned to its version and can shadow the npm command. If `agent-desktop version` is older than expected, check which executable runs with `command -v agent-desktop` (PowerShell: `Get-Command agent-desktop`) and uninstall the old one with the package manager that installed it. Upgrade by running the npm install again.
 
-- **Every invocation.** Run every `cua-driver` command, every SDK scenario, and every `ctx.tool` child process with `CUA_DRIVER_RS_TELEMETRY_ENABLED=false` in the environment. The environment override takes precedence over any saved preference and needs no executable, so it is the control Atomic standardizes on.
-- **After an executable install.** Additionally run `cua-driver telemetry disable` once, so the preference persists for daemon-owned sessions Atomic does not spawn (on macOS the daemon is launched through `open`, which does not inherit the agent's shell environment). Confirm with `cua-driver telemetry status --json`.
-- Never post the installation UUID from `telemetry status` in an issue, an evidence artifact, or a transcript.
+Report what the install did. Never loop on it. In a workflow stage, a refused or failed install is reported as `blocked`/`needs_human` together with the exact command above, not worked around with an alternative tool.
 
-The startup update check is separate from telemetry. It carries no installation ID or usage data, fires only on `mcp`, `serve`, and `doctor` with a 20-hour cache, and is how you learn that `cua-driver update --apply` is warranted. Atomic leaves it at the upstream default. If you want the GitHub request gone, set `CUA_DRIVER_RS_UPDATE_CHECK=false` for one invocation, or run `cua-driver config set update_check_enabled false` to persist it.
+agent-desktop's documentation describes no telemetry or update check, so Atomic's guidance sets no opt-out environment variable. Check the release notes when you upgrade.
 
 ### Check readiness
 
 A version string verifies the binary, not desktop access. Before the first action:
 
 ```sh
-export CUA_DRIVER_RS_TELEMETRY_ENABLED=false
-cua-driver status          # the daemon is running
-cua-driver doctor          # session, display, accessibility bus, telemetry setup
-cua-driver call list_apps  # a GUI app you recognize appears
+agent-desktop status
 ```
 
-`cua-driver call <tool>` is call-owned: it connects to the running daemon, prints one result, and exits. When no daemon is reachable it fails rather than executing in the CLI process, so a stopped daemon looks like a failed call. `list-tools`, `describe <tool>`, and `dump-docs` read the tool inventory without a runtime.
+`data.permissions` reports `accessibility`, `automation`, and `screen_recording`, each with a state such as `granted`, `denied`, `unknown`, or `not_required`. `data.supported_surfaces` lists the overlay kinds this OS can read (`window`, `sheet`, `alert`, `menu`, and on some platforms shell surfaces), and `data.state_root` is where sessions and traces live (`~/.agent-desktop`; the absolute path in `AGENT_DESKTOP_HOME` moves it). Then load the platform guide with `agent-desktop skills get platform`.
 
-- **macOS.** Start a stopped daemon with `open -n -g -a CuaDriver --args serve`, never with a bare `cua-driver serve` from a terminal: LaunchServices attributes the process to `CuaDriver.app` (`com.trycua.driver`), so the Accessibility and Screen Recording grants attach to the app and survive upgrades, while a terminal-launched daemon is attributed to the terminal app. Then run `cua-driver permissions status`; it reads the daemon's grants and reports `unknown` when no daemon is running. To grant, run `cua-driver permissions grant`, then toggle CuaDriver on under System Settings → Privacy & Security → Accessibility and under Screen & System Audio Recording. The prompt only registers the app; the toggle grants. macOS does not always raise both prompts in one pass, so rerun the pair and relaunch the daemon afterwards.
-- **Windows.** The daemon must run in the interactive user session; Session 0 cannot see the desktop. If the autostart task was not registered, run `cua-driver serve` in an interactive desktop terminal and use a second terminal for the checks. Standard-user automation cannot drive elevated apps or the UAC secure desktop.
-- **Linux.** Require a graphical X11 or XWayland session with `DISPLAY` set and AT-SPI available, and run `cua-driver serve` in the foreground inside that session. Native Wayland is opt-in with `CUA_DRIVER_RS_ENABLE_WAYLAND=1` and has compositor-specific limits; do not claim full Wayland support.
+- **macOS.** Accessibility permission must be granted to the app that launches the command (Terminal, iTerm2, Warp, VS Code). Screen Recording is needed only for `screenshot` and for session screenshot artifacts. Run `agent-desktop permissions` to read the state and `agent-desktop permissions --guide` to open the right System Settings page with a panel that shows which app to add; the user confirms with Touch ID or a password. A new grant is seen by the next call, so the launching app does not need a restart.
+- **Windows.** No permission dialog exists. Run the command in the interactive desktop session of the signed-in user: Session 0 services, the UAC secure desktop, the sign-in screen, a locked desktop, and another user's session are not supported. Windows blocks input from a non-elevated terminal into an elevated app (UIPI), so stop for the user or use an authorized non-elevated path rather than escalating just to force input through.
+- **Linux.** Run the command inside the graphical session of the user who owns the apps, with a running AT-SPI bus, so the session bus, display, and runtime directory come from its environment. Ubuntu 24.04 or later is the supported base; other distributions need the at-spi2-core bridge fix noted in the platform guide. An empty `supported_surfaces` means the bus did not answer. A TTY login, an SSH shell without the session variables, or a container without a bus sees no apps. X11 and Wayland sessions both work and differ in input, capture, and window control.
 
-A missing macOS Accessibility or Screen Recording grant, a non-interactive Windows session, or no graphical Linux session is a `blocked`/`needs_human` finding in a workflow stage. Report the exact fix from the list above and re-run the readiness check on resume. Let the user grant permissions; do not script around consent dialogs. The one exception is Cua Driver's own macOS Accessibility and Screen Recording prompts. By default the agent approves those itself, without asking, by clicking them through the host's VNC or Screen Sharing server when credentials for it are available (for example `CUA_VNC_SERVER`, `CUA_VNC_USER` and `CUA_VNC_PASSWORD`), and reports each approval and when it happened. It never approves any other permission or another app's dialog, and types a password only when you supplied one. Set `ATOMIC_CUA_AUTO_APPROVE=0` in Atomic's environment to turn this off; the agent then asks you to grant the permissions.
+A missing macOS permission, a non-interactive Windows session, or no graphical Linux session with an accessibility bus is a `blocked`/`needs_human` finding in a workflow stage. Report the exact fix from the list above and re-run `agent-desktop status` on resume. Let the user grant permissions; do not script around consent dialogs.
 
-### Drive a window from the shell
+### Drive an app from the shell
 
-Load the `cua-driver` skill and follow its loop. For a multi-call CLI run, choose a short, non-default session label and repeat it on every call that accepts `session`; omitting it uses a disposable implicit lease rather than preserving the prior call's state. The shape, with `CUA_DRIVER_RS_TELEMETRY_ENABLED=false` exported as above, is:
+Load the `agent-desktop` skill and follow its loop. Map the app with a shallow skeleton, drill into the region you need, act on a ref, and verify. Refs are qualified with the snapshot that produced them and are valid for that snapshot only:
 
 ```sh
-cua-driver call list_apps
-cua-driver call list_windows '{"pid":844}'
-cua-driver call get_window_state '{"pid":844,"window_id":10725,"session":"run-1","screenshot_out_file":"artifacts/before.png"}' > artifacts/before.json
-# Pick one element_token from before.json, then act on that exact window in the background.
-cua-driver call click '{"target":{"kind":"window","pid":844,"window_id":10725},"element_token":"s0000002a:14","session":"run-1","delivery_mode":"background"}'
-cua-driver call get_window_state '{"pid":844,"window_id":10725,"session":"run-1","screenshot_out_file":"artifacts/after.png"}' > artifacts/after.json
+agent-desktop snapshot --app "Notes" --skeleton -i --compact   # map: children_count on cut branches
+agent-desktop snapshot --root @s8f3k2p9:e3 -i --compact        # drill into one region
+agent-desktop click @s8f3k2p9:e12                              # act on a qualified ref
+agent-desktop wait --element @s8f3k2p9:e5 --predicate value --value "Done" --timeout 5000   # verify
+agent-desktop get @s8f3k2p9:e5 --property value                # read it back
 ```
 
-Replace the pid, window id, token, and session label with values for your own run; tokens are bound to the snapshot that produced them and must be re-read after any UI change. Check the postcondition in `after.json` with a bounded poll deadline, never a fixed sleep and never a repeated click. A `degraded` or `truncated` snapshot is a reason to stop and re-observe. If background delivery is refused, refresh state and ask before foreground or desktop control unless it was already authorized; do not retry automatically. End only your run with `cua-driver call end_session '{"session":"run-1"}'`, not `cua-driver stop` on a shared service. Keep the JSON results and the `screenshot_out_file` images as evidence. When the work ends in a PR, attach the before/after PNGs to the PR body (`gh pr create --body-file body.md --attach 'before.png#Before' --attach 'after.png#After'` on supported GitHub) next to the scenario they prove, and cite the JSON by name as a local artifact; see [Verification and evidence](/workflows/verification#native-github-media).
+Replace the app name and refs with values from your own run, and do not reuse an example ref without discovering what it points to. `find --app "Notes" --role button --name "Save" --exact` is cheaper than a snapshot when you know the role and name.
+
+- **Verify with a read.** Use `wait`, not a sleep, after an asynchronous step. A successful action reports `data.disposition`; retry or substitute an action only when `disposition.retry` is `safe`, because any other delivery value means the action may have landed and a repeat can click or submit twice. Read the live state first.
+- **Stale and ambiguous refs.** `STALE_REF` means the UI changed: snapshot again. `AMBIGUOUS_TARGET` means several elements match: narrow the target with `find --role --name --exact` or `--root`.
+- **Overlays.** An action that opens a menu, sheet, or alert lists it in `data.surfaces`. Snapshot that surface, not the window behind it.
+- **Headless first.** Ref actions use semantic accessibility calls and do not take focus, move the cursor, or use the clipboard. Add the global `--headed` flag only when the user permits physical input such as double-click, hover, drag, or focus, and never to recover from a headless failure. Dangerous shortcuts such as quit and lock are refused without `--force`.
+- **PowerShell.** Quote every ref (`'@s8f3k2p9:e12'`), because a bare `@token` is the splatting operator.
+- **Sessions.** For a multi-command run, `agent-desktop session start --name run-1` returns a session id; pass it with `--session` or `AGENT_DESKTOP_SESSION` on every command so refs and traces stay in your namespace, and end only your own session with `agent-desktop session end <id>`. `agent-desktop batch '[...]'` runs several commands in one process and is not a transaction.
+- **Evidence.** Keep the JSON results and save `agent-desktop screenshot --app "Notes" after.png`; a session with tracing on can export an HTML timeline with `agent-desktop trace export`. A screenshot is evidence for you, not proof that an action worked. When the work ends in a PR, attach the before and after PNGs to the PR body (`gh pr create --body-file body.md --attach 'before.png#Before' --attach 'after.png#After'` on supported GitHub) next to the scenario they prove, and cite the JSON by name as a local artifact; see [Verification and evidence](/workflows/verification#native-github-media).
+
+For the web contents of a Chromium or Electron app that you launch, `agent-desktop launch "Obsidian" --cdp` starts it fresh with a loopback-only debugging port and prints the port; `agent-browser connect <port>` then drives its pages (`agent-browser skills get electron` has the guide). The port exists only for a fresh process, so a running app must be closed first, which loses its state: ask before you do that. Keep the native menu bar, file dialogs and sheets, window management, notifications, screenshots, and any app you did not launch on agent-desktop. While the port is open, any local process of the same user can control the app's web contents, so request `--cdp` only for the step that needs it; `close-app` ends the exposure.
 
 ### Run a scenario from workflow code
 
-When a custom workflow owns the scenario, use the `@trycua/cua-driver` TypeScript SDK inside `ctx.tool` so the observe → act → re-observe → assert loop is a durable, replayable node. The [workflow authoring guide](/workflows/authoring#desktop-verification-with-cua-driver-in-ctx-tool) has the runnable example; the summary is:
+When a custom workflow owns the scenario, call the `agent-desktop` CLI from inside `ctx.tool` so the observe, act, verify loop is a durable, replayable node. The [workflow authoring guide](/workflows/authoring#desktop-verification-with-agent-desktop-in-ctx-tool) has the runnable example; the summary is:
+
+- **Prerequisite.** `agent-desktop` on the host, installed by [the steps above](#install-if-missing). The preflight below reports it missing as a limitation rather than installing during the run.
+- **One process per command.** Spawn `agent-desktop`, parse the one JSON envelope it prints, and branch on `ok`, `error.code`, and `disposition`, never on message text. Forward the `signal` and give `ctx.tool` a positive finite `timeoutMs`.
+- **Readiness preflight.** A first `ctx.tool` checks `agent-desktop version` and `agent-desktop status`, and calls `ctx.exit({ status: "blocked", reason })` for a missing macOS permission, an absent Linux accessibility bus, or a missing install.
+- **Loop.** `snapshot` (check `data.complete`) → resolve exactly one element with `find` → act on the ref → `wait` for the postcondition → read it back. Re-drill after any UI change.
+- **Result.** Machine-readable `verified` / `refuted` / `blocked` / `unknown`; the wrapper maps anything but `verified` to a nonzero outcome. An action whose delivery is not `not_delivered`, or that times out before its response, is `unknown`, resolved by reading the state, never by replaying the mutation.
 
-- **Prerequisite.** `node` (preferred) or `bun` on the host. If neither is present, install one in a bounded attempt (Node via [fnm](https://github.com/Schniz/fnm) with `fnm install --lts` or the host's package manager, Bun via `curl -fsSL https://bun.sh/install | bash`) and report what the installer did; if the install is refused or fails, report that as the limitation rather than retrying.
-- **Install.** `npm install @trycua/cua-driver@<exact pin matching cua-driver --version>` into a scratch directory outside the user's repository, one bounded attempt. The package ships per-platform native optional dependencies, so it is self-contained. Pin the exact driver version: daemon-backed clients verify contract, tool-schema, capability, and protocol versions before each action and refuse on mismatch.
-- **Acquire the driver.** When `cua-driver status` reports a running daemon, use `CuaDriver.connect(undefined)` so the scenario reuses the daemon's permission identity (on macOS, `CuaDriver.app`'s grants) and the persisted telemetry-off preference; upstream describes `connect()` as a compatibility and app-hosting path, and that is exactly the role it plays here. Only when no daemon is reachable, fall back to `CuaDriver.create(undefined)`, which loads the runtime into the node process. On macOS that in-process fallback attributes Accessibility and Screen Recording to the node host, normally the terminal app, as a **separate grant**; `checkPermissions` is then read-only, and the host must fully quit and relaunch after granting.
-- **Telemetry.** Set `CUA_DRIVER_RS_TELEMETRY_ENABLED=false` in the child environment before constructing the driver.
-- **Loop.** `listApps` → `listWindows` → `getWindowState` (refuse `degraded`/`truncated`) → resolve exactly one element → act by `elementToken` with `InputDeliveryMode.Background` → `getWindowState` again → bounded-poll the postcondition. `shutdown()` in `finally`, then `uniffiDestroy()` when present.
-- **Result.** Machine-readable `verified` / `refuted` / `blocked` / `unknown`; the wrapper maps anything but `verified` to a nonzero outcome. An action that times out before its response is `unknown`, resolved by the postcondition, never by replaying the mutation.
+### Coverage and limits
+
+agent-desktop reads accessibility trees and acts through the operating system's accessibility APIs. State these limits instead of working around them:
+
+- **No pixel matching.** It cannot see a UI that publishes no accessibility tree, such as a custom-drawn canvas, a game, or some remote-desktop windows. For those it can only take a `screenshot` you judge yourself and, with the user's permission, send coordinate input (`--headed mouse-click --xy X,Y`). Say what stayed unverified. Prefer a ref whenever one exists.
+- **No native iOS or Android support.** agent-desktop has no Simulator or emulator support of its own. It treats the iOS Simulator and Android emulators as ordinary desktop windows and sees only what their accessibility trees expose, which may not include the simulated device's UI. Use `xcrun simctl` (including `simctl io booted recordVideo`), Appium with XCUITest, or `adb` with UI Automator for native mobile apps, and report the gap when none is installed. For Mobile Safari, [agent-browser's iOS mode](#what-agent-browser-covers) remains the route.
+- **Browsers other than Chromium.** Desktop Safari, Firefox, and other browsers expose whatever their accessibility trees publish. Web content there can be thin, so check with a snapshot, and use agent-browser for any page it can reach.
+- **Reserved input.** `key-down`, `key-up`, `mouse-down`, and `mouse-up` never deliver input on any platform. Use `press`, `mouse-click`, or `drag`.
+- **Per-platform differences.** Which actions need `--headed`, and what each OS refuses, is in `agent-desktop skills get platform`; read it before relying on a command.
+
+agent-desktop also ships as a C library for embedding; Atomic's guidance does not use it.
 
 ### Stay safe
 
@@ -275,7 +294,7 @@ One controller owns a desktop at a time. Use a dedicated session or account wher
 
 ## Browser automation with agent-browser
 
-Prefer [agent-browser](https://agent-browser.dev/) for any target it can reach. Its `snapshot` returns a compact text accessibility tree with `@eN` element refs, usually a few hundred tokens, so each step costs far less context than a screenshot-driven CUA step, and actions land on real controls rather than screen coordinates. Anything outside the scope below, or a limitation you hit inside it, goes to [Cua Driver](#desktop-automation-with-cua-driver). For data retrieval or batch operations, consider a supported API first when it meets the request and you have permission to use it.
+Prefer [agent-browser](https://agent-browser.dev/) for any target it can reach. Its `snapshot` returns a compact text accessibility tree with `@eN` element refs, usually a few hundred tokens, so each step costs far less context than a screenshot-driven computer-use step, and actions land on real controls rather than screen coordinates. Anything outside the scope below, or a limitation you hit inside it, goes to [agent-desktop](#desktop-automation-with-agent-desktop). For data retrieval or batch operations, consider a supported API first when it meets the request and you have permission to use it.
 
 ### What agent-browser covers
 
@@ -290,15 +309,16 @@ Prefer [agent-browser](https://agent-browser.dev/) for any target it can reach.
 | Cloud and sandboxed browsers | `-p browserbase`, `browserless`, `browseruse`, `kernel`, or `agentcore`; `agent-browser skills get vercel-sandbox` | Provider credentials come from the provider's environment variables. |
 | Local HTML or PDF files | `agent-browser --allow-file-access open file:///path/to/file` | Chromium only. |
 
-Hand the task to Cua Driver when it needs any of these:
+Hand the task to agent-desktop when it needs any of these:
 
-- A native desktop app that exposes no CDP port (AppKit, SwiftUI, Win32/WPF, GTK, Qt), or an Electron app that cannot be relaunched with remote debugging.
-- A native iOS app in the Simulator. agent-browser's iOS mode drives Mobile Safari only. Android emulators are not supported by agent-browser at all.
-- Desktop Safari, Firefox, or another browser that is neither Chromium-based nor iOS Safari.
+- A native desktop app that exposes no CDP port (AppKit, SwiftUI, Win32/WPF, GTK, Qt), or an Electron app that is already running. For an Electron or Chromium app you can launch fresh, `agent-desktop launch <app> --cdp` opens a port that `agent-browser connect <port>` drives, and agent-desktop keeps the native menus, dialogs, and windows.
+- Desktop Safari, Firefox, or another browser that is neither Chromium-based nor iOS Safari. agent-desktop sees what their accessibility trees expose, so check the snapshot.
 - Browser chrome outside the page: the toolbar, extension popups, native print or save dialogs, or permission prompts.
 - OS dialogs and pickers the page cannot bypass. Try `agent-browser upload` for file inputs first.
 - Work across several applications, or a capability the installed agent-browser version rejects.
 
+A native iOS app in the Simulator, or an Android emulator, is outside both tools: agent-browser's iOS mode drives Mobile Safari only, and agent-desktop sees a simulator window as an ordinary app. Use `xcrun simctl`, Appium with XCUITest, or `adb` with UI Automator, and report the gap when none is available.
+
 Check the installed CLI (`agent-browser --help`, `agent-browser skills get core`) before relying on a version-dependent command.
 
 ### Setup and first session
@@ -330,10 +350,10 @@ For a real task, act between the snapshot and final capture. Read element refere
 - Prefer a fresh profile. Attach to an existing personal browser only when authorized; stored sessions can expose private tabs and credentials.
 - Use headed mode for visual work. Headless mode can verify DOM behavior, but does not establish that desktop integration or native dialogs work.
 - Inspect visible results and relevant console/network output (`agent-browser console`, `agent-browser errors`, `agent-browser network requests`). Keep semantic locators and assertions in a maintained browser test suite for repeatable regression coverage.
-- Use the CLI's file-upload support for supported file inputs rather than driving an OS file picker. Switch to Cua Driver or native tooling only for UI outside the page, and then recheck focus before returning to browser control.
+- Use the CLI's file-upload support for supported file inputs rather than driving an OS file picker. Switch to agent-desktop or native tooling only for UI outside the page, and then recheck focus before returning to browser control.
 - Treat cookies, saved authentication state, and network logs as sensitive. Do not commit or attach a browser profile as evidence.
 - Keep `screenshot` PNGs and `record` recordings from the verified flow; when the work ends in a PR, attach them to the PR body with `gh pr create --attach` on supported GitHub, each next to the scenario it proves. See [Verification and evidence](/workflows/verification#native-github-media).
-- `set device` emulates a mobile viewport in Chromium; `-p ios` runs real Mobile Safari. Neither exercises a native Android or iOS app, which needs Cua Driver.
+- `set device` emulates a mobile viewport in Chromium; `-p ios` runs real Mobile Safari. Neither exercises a native Android or iOS app, which needs `adb`, `xcrun simctl`, or Appium and XCUITest.
 
 For verification captures and recordings, see [browser evidence](/workflows/verification#browser-changes).
 
@@ -394,12 +414,10 @@ For modified-key setup in Atomic, see [tmux setup](/tmux). For behavioral checks
 
 ### Desktop and native tools
 
-- Install a missing `cua-driver` with the [one-line installer](#install-if-missing) (macOS 14 Sonoma or later), run `cua-driver telemetry disable` once, and open a new shell so `~/.local/bin` is on `PATH`. Install missing uv with `brew install uv` when Homebrew is available, or use the reviewed macOS installer from [uv installation](https://docs.astral.sh/uv/getting-started/installation/).
-- The daemon is `CuaDriver.app`. Start it with `open -n -g -a CuaDriver --args serve` so macOS attributes the process, and its Accessibility and Screen Recording grants, to `com.trycua.driver` rather than to Terminal or your IDE. A daemon started from a terminal is the right binary with the wrong privacy identity.
-- Grant with `cua-driver permissions grant`, then toggle CuaDriver on under System Settings > Privacy & Security > Accessibility and under Screen & System Audio Recording, and relaunch the daemon. Confirm with `cua-driver permissions status`. If CuaDriver is missing from either list, click **+** and add `/Applications/CuaDriver.app`.
-- An in-process `CuaDriver.create()` runtime is attributed to the node host that imported it, normally the terminal app. That is a separate grant from the app's, `checkPermissions` is read-only there, and the host must fully quit and relaunch after a change.
-- AppleScript automation may also prompt for Automation permission to control another app. Let the user grant permissions; do not script around consent dialogs. Only Cua Driver's own Accessibility and Screen Recording prompts are approved by the agent, over VNC, unless `ATOMIC_CUA_AUTO_APPROVE=0` (see [Check readiness](#check-readiness) above).
-- Window screenshots use the window's own coordinate space and report their scale factor; act by element token where possible and read dimensions from the same snapshot before any pixel action. A black or incomplete capture usually needs permission or display troubleshooting, not more clicks.
+- Install a missing `agent-desktop` with [`npm install -g agent-desktop`](#install-if-missing) (macOS 13 or later; Intel or Apple Silicon). Install missing uv with `brew install uv` when Homebrew is available, or use the reviewed macOS installer from [uv installation](https://docs.astral.sh/uv/getting-started/installation/).
+- Accessibility permission belongs to the app that launches the command (Terminal, iTerm2, Warp, VS Code). Run `agent-desktop permissions` to read it and `agent-desktop permissions --guide` to open System Settings with a panel that shows the user which app to add; the user confirms with Touch ID or a password. macOS 27 and later name the list Device Control and Data Access. If System Settings also lists the `agent-desktop` binary, grant it too. Screen Recording is needed only for `screenshot`.
+- AppleScript automation may also prompt for Automation permission to control another app, and `agent-desktop permissions` reports it as `unknown` until macOS would prompt. Let the user grant permissions; do not script around consent dialogs.
+- Act by ref where possible. Read `bounds` from the same snapshot before any coordinate action, and check that they are live (`get --property bounds` reports `data.live`). A black or incomplete capture usually needs permission or display troubleshooting, not more clicks.
 
 Use `osascript` for AppleScript or JavaScript for Automation when an app's scripting dictionary exposes the operation you need. See [application scripting and recipes](#application-scripting-and-apis) for a runnable example and Office automation choices. `System Events` UI scripting and native accessibility APIs can address menus and controls more reliably than coordinates; consult Apple's [UI scripting guide](https://developer.apple.com/library/archive/documentation/LanguagesUtilities/Conceptual/MacAutomationScriptingGuide/AutomatetheUserInterface.html).
 
@@ -407,7 +425,7 @@ Use `osascript` for AppleScript or JavaScript for Automation when an app's scrip
 
 ### Browser and terminal
 
-agent-browser's default session is Chrome/Chromium, which is not proof of Safari-specific behavior. For Mobile Safari, use `agent-browser -p ios` against an iOS Simulator (requires Xcode, Appium, and the XCUITest driver). For desktop Safari, use Cua Driver.
+agent-browser's default session is Chrome/Chromium, which is not proof of Safari-specific behavior. For Mobile Safari, use `agent-browser -p ios` against an iOS Simulator (requires Xcode, Appium, and the XCUITest driver). For desktop Safari, use agent-desktop and check what its accessibility tree exposes.
 
 Herdr is the first choice for interactive terminals when eligible. Homebrew provides Herdr and tmux. Preserve the shell, terminal dimensions, and keyboard behavior relevant to the task rather than silently changing them to make a scenario pass.
 
@@ -415,12 +433,12 @@ Herdr is the first choice for interactive terminals when eligible. Homebrew prov
 
 ### Desktop and native tools
 
-- Install a missing `cua-driver` with the [one-line installer](#install-if-missing); a minimal image may first need `sudo apt install libxi6 at-spi2-core`. Run `cua-driver telemetry disable` once and open a new shell so `~/.local/bin` is on `PATH`. Install missing uv through the [official Linux installer](https://docs.astral.sh/uv/getting-started/installation/) or an available distribution package.
-- Installing the binary does not start the daemon or create a desktop session. Run `cua-driver serve` in the foreground in a terminal inside the graphical session that owns the apps, with the same `DISPLAY` and AT-SPI session bus, and run `cua-driver doctor` from a second terminal in that session.
-- X11 and XWayland are the supported routes by default; toolkit-specific limits apply. Native Wayland is opt-in with `CUA_DRIVER_RS_ENABLE_WAYLAND=1` and depends on the compositor. Do not weaken session security or claim full Wayland support.
-- For unattended X11 work, a dedicated virtual display such as Xvfb with a desktop session (for example `xfce4`) can be useful. It does not prove behavior on a real Wayland desktop, GPU configuration, or physical display. Creative applications may require working graphics acceleration.
+- Install a missing `agent-desktop` with [`npm install -g agent-desktop`](#install-if-missing) (Ubuntu 24.04 or later on x86_64 or aarch64; other distributions need the at-spi2-core bridge fix named in `agent-desktop skills get linux`). Install missing uv through the [official Linux installer](https://docs.astral.sh/uv/getting-started/installation/) or an available distribution package.
+- Installing the binary does not create a desktop session. Run `agent-desktop status` in a terminal inside the graphical session that owns the apps, so the session bus, display, and runtime directory come from its environment. An empty `supported_surfaces` means the AT-SPI bus did not answer; a TTY login, an SSH shell without the session variables, or a container without a bus sees no apps.
+- Observation and semantic actions work on X11 and Wayland through AT-SPI and need no helper tool. Pointer gestures (`double-click`, `hover`, `drag`) and wheel scrolling are X11 and `--headed` only, and on Wayland they refuse with `ACTION_NOT_SUPPORTED`. Do not weaken session security or claim full Wayland support.
+- For unattended X11 work, a dedicated virtual display such as Xvfb with a desktop session (for example `xfce4`) and a session bus can be useful. It does not prove behavior on a real Wayland desktop, GPU configuration, or physical display. Creative applications may require working graphics acceleration.
 
-[AT-SPI](https://gnome.pages.gitlab.gnome.org/at-spi2-core/) can expose named controls in accessible applications. `xdotool` and `wmctrl` can help with focus and window placement on X11; they are not general Wayland replacements. On Wayland, choose tools for the actual compositor and inspect their permission requirements. Use app APIs where custom canvases do not expose useful accessibility controls.
+[AT-SPI](https://gnome.pages.gitlab.gnome.org/at-spi2-core/) can expose named controls in accessible applications. `xdotool` and `wmctrl` can help with focus and window placement on X11 when agent-desktop's window commands are not enough; they are not general Wayland replacements. On Wayland, choose tools for the actual compositor and inspect their permission requirements. Use app APIs where custom canvases do not expose useful accessibility controls.
 
 For recordings, use a supported desktop recorder or OBS with the appropriate display or portal source. Confirm the saved file contains the intended window, not a blank capture.
 
@@ -434,14 +452,14 @@ Herdr is preferred when eligible; tmux is a practical fallback on local or remot
 
 ### Desktop and native tools
 
-- Install a missing `cua-driver` with the [PowerShell one-liner](#install-if-missing) and run `cua-driver telemetry disable` once. Open a new shell if `Path` changed, then run `cua-driver --version`. Install missing uv with `winget install --id=astral-sh.uv -e` or use the reviewed PowerShell installer from [uv installation](https://docs.astral.sh/uv/getting-started/installation/).
-- The daemon must run in the interactive user session (Session 1 or later); Session 0 services cannot see the desktop. The installer registers a `cua-driver-serve` autostart task when the session is interactive; otherwise run `cua-driver serve` in an interactive desktop terminal and use a second terminal for the checks.
-- Run `cua-driver` in the Windows graphical session that owns the app. Running it inside WSL does not control native Windows windows.
+- Install a missing `agent-desktop` with [`npm install -g agent-desktop`](#install-if-missing) from PowerShell and run `agent-desktop version`; open a new shell if `Path` changed. Install missing uv with `winget install --id=astral-sh.uv -e` or use the reviewed PowerShell installer from [uv installation](https://docs.astral.sh/uv/getting-started/installation/).
+- Run `agent-desktop` in the interactive desktop session of the signed-in user (Windows 10 1809 or later, or Windows Server 2019 or later). Session 0 services, Server Core, the UAC secure desktop, the sign-in screen, a locked desktop, and another user's session are not supported. No permission dialog exists, and `agent-desktop status` reports `automation` as `not_required`.
+- In PowerShell, quote every ref (`'@s8f3k2p9:e1'`) and use `$env:NAME = 'value'` instead of `export`. A minimized window is not drivable: `agent-desktop restore --app <name>`, then snapshot again. `type` needs `--headed`; prefer `set-value`.
 - Keep the session unlocked and available during automation. A disconnected or minimized Remote Desktop session can change rendering or input behavior; verify the actual remote-session setup before relying on it.
 - Use a consistent display scale and primary monitor. Check coordinates again after moving a window between displays with different DPI settings.
-- Standard-user automation cannot reliably drive elevated apps or the UAC secure desktop. Stop for the user or choose an authorized non-elevated path rather than escalating just to force input through.
+- Windows blocks input from a non-elevated terminal into an elevated app (UIPI) and the UAC secure desktop is out of reach. Stop for the user or choose an authorized non-elevated path rather than escalating just to force input through.
 
-[Windows UI Automation](https://learn.microsoft.com/en-us/dotnet/framework/ui-automation/ui-automation-overview) exposes controls by name and automation ID. Cua Driver reads that UIA tree in `get_window_state` and acts on it in the background, so prefer element tokens over pixel matching for accessible Windows apps. For structured document operations, start with [file libraries and app scripting](#application-scripting-and-apis). Use Cua Driver for the remaining visual interactions.
+[Windows UI Automation](https://learn.microsoft.com/en-us/dotnet/framework/ui-automation/ui-automation-overview) exposes controls by name and automation ID. agent-desktop reads that UIA tree in `snapshot` and acts on it through semantic calls, so prefer refs over pixel matching for accessible Windows apps. For structured document operations, start with [file libraries and app scripting](#application-scripting-and-apis). Use agent-desktop for the remaining visual interactions.
 
 Snipping Tool or OBS can capture desktop evidence. Check the selected window and saved recording before sharing it.
 
@@ -453,28 +471,28 @@ Prefer native Herdr when eligible. In PowerShell, check `$env:HERDR_ENV -eq '1'`
 
 See [Windows setup](/windows) for Atomic's shell requirements.
 
-## Creative work and CUA workflows
+## Creative work and computer-use workflows
 
 Choose the deliverable first. A library or application API may produce it without computer use at all. Add visual interaction when it helps create or inspect the result.
 
 | Task | Practical approach | Useful deliverables |
 | --- | --- | --- |
-| Blender 3D modeling | Use Blender Python for repeatable geometry or scene setup; use Cua Driver for visible editor operations and visual inspection. | Editable `.blend` file, exported model if requested, preview render. |
-| Presentations | Generate structured slides with `python-pptx`, inspect them in a compatible viewer, and use CUA for visual refinements or slideshow interaction when needed. | Editable deck plus PDF or slide previews exported through a compatible application. |
-| Video editing | Use the editor's scripting API or media CLI for repetitive operations; use CUA to adjust the timeline, inspect transitions, and review playback. | Editable project, required source references, final export. |
-| Work across applications | Use native scripting for named windows and file operations; use Cua Driver where the task needs visual interaction, addressing each window by pid and window id. | Saved documents and a concise record of completed steps. |
+| Blender 3D modeling | Use Blender Python for repeatable geometry or scene setup; use agent-desktop for visible editor operations and visual inspection. | Editable `.blend` file, exported model if requested, preview render. |
+| Presentations | Generate structured slides with `python-pptx`, inspect them in a compatible viewer, and use agent-desktop for visual refinements or slideshow interaction when needed. | Editable deck plus PDF or slide previews exported through a compatible application. |
+| Video editing | Use the editor's scripting API or media CLI for repetitive operations; use agent-desktop to adjust the timeline, inspect transitions, and review playback. | Editable project, required source references, final export. |
+| Work across applications | Use native scripting for named windows and file operations; use agent-desktop where the task needs visual interaction, addressing each window by app name and window id. | Saved documents and a concise record of completed steps. |
 
 Do not substitute a screenshot for the editable project or final export the user requested. Reopen saved files, check missing assets and fonts, and inspect the actual export. For video, check audio and timing as well as a still frame. Keep originals intact and use explicit save paths. Rendering, uploading, or exporting through a paid service may need separate authorization.
 
-When the user specifically wants a CUA workflow, give the stage that operates the desktop the `cua-driver` skill, or put a code-owned scenario in `ctx.tool` with the SDK. For artifact-only requests, keep script-based work outside the desktop session and omit UI stages that add no useful operation or check. A desktop sequence is:
+When the user specifically wants a computer-use workflow, give the stage that operates the desktop the `agent-desktop` skill, or put a code-owned scenario in `ctx.tool` that calls the `agent-desktop` CLI. For artifact-only requests, keep script-based work outside the desktop session and omit UI stages that add no useful operation or check. A desktop sequence is:
 
 1. Prepare assets and confirm the intended application, output formats, and permissions.
 2. Open the dedicated desktop and inspect its starting state.
-3. Create or edit with Cua Driver and suitable native/app APIs, saving checkpoints.
+3. Create or edit with agent-desktop and suitable native/app APIs, saving checkpoints.
 4. Reopen and inspect the deliverables, then make bounded corrections if needed.
 5. Hand off local files. Publish or upload only to an authorized target.
 
-Pass scripts, project files, and artifact paths between stages rather than long click transcripts. Give one stage exclusive desktop ownership and use finite deadlines for renders and exports. Stop on unexpected dialogs, degraded or truncated snapshots, missing permissions, or failed observations. On resume, inspect the app and files before repeating an action.
+Pass scripts, project files, and artifact paths between stages rather than long click transcripts. Give one stage exclusive desktop ownership and use finite deadlines for renders and exports. Stop on unexpected dialogs, incomplete snapshots (`data.complete` is `false`), missing permissions, or failed observations. On resume, inspect the app and files before repeating an action.
 
 See [workflow authoring](/workflows/authoring) for stages and human-input gates. Use durable `ctx.tool` calls for workflow-owned external operations, with finite timeouts and cancellation; model stages can use the appropriate automation tools to operate the app. If the user asks to work inline, keep the same safety and deliverable checks without creating a workflow.
 
@@ -482,11 +500,14 @@ See [workflow authoring](/workflows/authoring) for stages and human-input gates.
 
 | Symptom | What to check |
 | --- | --- |
-| `cua-driver`, uv, or another command is missing | Install it when permitted with one bounded attempt, refresh PATH, and check its version in the same shell that will launch automation. |
-| `cua-driver call` fails or `permissions status` reports `unknown` | The daemon is not running. Start it with `open -n -g -a CuaDriver --args serve` on macOS, an interactive-session `cua-driver serve` on Windows, or a foreground `cua-driver serve` inside the graphical session on Linux, then rerun `cua-driver status`. |
-| Grants look correct but actions or captures are refused | Stale TCC grants. Toggle CuaDriver off and on under Accessibility and Screen & System Audio Recording, or click **+** and re-add `/Applications/CuaDriver.app`, then fully relaunch the daemon. An in-process SDK runtime needs the node host relaunched instead. |
-| Contract, schema, or protocol mismatch | Version skew between the `@trycua/cua-driver` SDK pin and the running driver. Check `cua-driver --version` and reinstall the SDK at that exact version. The bundled skill (`0.38.0`) identifies its source release, not the daemon's protocol. If a driver upgrade is authorized, run `cua-driver update --apply` once and restart the daemon. |
-| Snapshot reports `degraded` or `truncated` | Do not act on it. Re-observe, narrow the query, or fall back to a pixel action from the same snapshot only where the skill allows it. |
+| `agent-desktop`, uv, or another command is missing | Install it when permitted with one bounded attempt, refresh PATH, and check its version in the same shell that will launch automation. |
+| Every `agent-desktop` call is slow, or a notice mentions the Node launcher | npm blocked the package's install script. Approve it (`npm install-scripts approve agent-desktop` on npm 12, or `npm install -g agent-desktop --allow-scripts=agent-desktop` on npm 11) and reinstall. |
+| `agent-desktop version` is older than expected, or `command -v agent-desktop` names an unexpected path | An older Homebrew tap or Scoop bucket install can shadow the npm command. Uninstall it with the package manager that installed it, then run the npm install again. |
+| `permissions` shows `denied`, an app's tree is empty, or `PERM_DENIED` | On macOS, run `agent-desktop permissions --guide` and let the user grant Accessibility (and Screen Recording for screenshots) to the app that launched the command. A missing permission looks like an empty tree, so check `status` before concluding the app has no UI. |
+| `supported_surfaces` is empty on Linux, or no apps appear | The AT-SPI bus did not answer. Run the command inside the user's graphical session, not a TTY, bare SSH shell, or container, then rerun `agent-desktop status`. |
+| `STALE_REF`, `AMBIGUOUS_TARGET`, or `SNAPSHOT_NOT_FOUND` | The UI changed, several elements match, or the snapshot expired. Snapshot again, narrow with `find --role --name --exact` or `--root`, and use the new ref. |
+| An action succeeded but the UI looks unchanged | Delivery is not proof. `wait` for the postcondition or read the state again; retry only when `disposition.retry` is `safe`. |
+| A snapshot is thin or `data.complete` is `false` | Do not act on a partial tree. Drill with `--root`, or raise `--timeout-ms`; a cold Chromium or Electron app can take 10 to 25 seconds to expose its web tree. |
 | Black screenshot or no desktop | Check screen permissions, display/session ownership, X11 versus Wayland, and remote-session state. |
 | Input reaches the wrong app | Stop. Confirm focus, window identity, scaling, and that no other controller shares the desktop. |
 | Browser element reference no longer works | Take a fresh snapshot and locate the current control. |

package/docs/getting-started/first-session.md

@@ -115,7 +115,7 @@ Skills are reusable expert instructions. Trigger one with `/skill:<name>` follow
 | `tdd` | Test-first feature or bug work. | `/skill:tdd` |
 | `impeccable` | Critique or refine web/native frontend and product UI; includes detector hooks, framework-aware live review, and mount-failure recovery. | `/skill:impeccable` |
 | `agent-browser` | Drive a real browser for end-to-end UI checks, screenshots, and reviewable proof videos. | `/skill:agent-browser` |
-| `cua-driver` | Drive a native desktop app, simulator, or emulator window through Cua Driver: accessibility snapshot, element-token actions, and a fresh snapshot to verify. | `/skill:cua-driver` |
+| `agent-desktop` | Drive a native desktop app through its accessibility tree with the agent-desktop CLI: snapshot, act on a ref, and wait for the postcondition to verify. | `/skill:agent-desktop` |
 | `qlty` | Lint, auto-format, and measure code quality — complexity, duplication, and code smells — through one CLI across the repository's languages. | `/skill:qlty check this branch before I hand it off` |
 | `liteparse` | Pull text, tables, or values out of PDF, DOCX, PPTX, XLSX, and image files locally. | `/skill:liteparse` |
 | `show-me` | Explain a topic visually with concise diagrams, code-shape sketches, or focused HTML artifacts. HumanLayer, MIT licensed. | `/skill:show-me` |

package/docs/skills.md

@@ -115,9 +115,9 @@ Offline, `qlty metrics` and `qlty smells` still work through built-in static ana
 
 ### Built-in computer-use and automation guidance
 
-Load `/skill:agent-browser` first for anything it covers: websites and web apps in Chrome/Chromium, Mobile Safari in the iOS Simulator (`agent-browser -p ios`), Electron and other apps that expose a CDP port, Slack, and cloud browsers. Its text snapshots cost far fewer tokens than screenshot-driven CUA. For everything else, including native desktop apps, native iOS apps in the Simulator, Android emulators, OS dialogs, and desktop Safari or other non-Chromium browsers, load `/skill:cua-driver` and drive the exact window with one-shot `cua-driver call <tool>` commands; when a custom workflow's TypeScript owns the scenario, use the `@trycua/cua-driver` SDK inside `ctx.tool` instead. See [what agent-browser covers](/computer-use#what-agent-browser-covers) for the full split, and [Computer use](/computer-use#desktop-automation-with-cua-driver) for installing the Cua Driver executable, turning telemetry off, readiness, and permissions. For terminal automation/testing, prefer `/skill:herdr` on macOS, Linux and Windows. Install Herdr if missing when network access and permissions permit; fall back to `/skill:tmux` or native Windows psmux when installation or use is not possible. Preserve the upstream skill's explicit-request and managed-pane requirements. These are separate interfaces, not interchangeable command names. See [verification and desktop safety](/workflows/verification) for installation, permissions, dedicated sessions and evidence.
+Load `/skill:agent-browser` first for anything it covers: websites and web apps in Chrome/Chromium, Mobile Safari in the iOS Simulator (`agent-browser -p ios`), Electron and other apps that expose a CDP port, Slack, and cloud browsers. Its text snapshots cost far fewer tokens than desktop accessibility trees and screenshots. For native desktop apps, menus and menu bars, OS dialogs and permission prompts, desktop Safari and other non-Chromium browsers, and work across apps, load `/skill:agent-desktop` and drive the app with one-shot `agent-desktop` commands; when a custom workflow's TypeScript owns the scenario, call the `agent-desktop` CLI from `ctx.tool` instead. Native iOS apps in the Simulator and Android emulators need native mobile tooling; agent-desktop sees them only as desktop windows. See [what agent-browser covers](/computer-use#what-agent-browser-covers) for the full split, and [Computer use](/computer-use#desktop-automation-with-agent-desktop) for installing the agent-desktop CLI, readiness, permissions, and [coverage limits](/computer-use#coverage-and-limits). For terminal automation/testing, prefer `/skill:herdr` on macOS, Linux and Windows. Install Herdr if missing when network access and permissions permit; fall back to `/skill:tmux` or native Windows psmux when installation or use is not possible. Preserve the upstream skill's explicit-request and managed-pane requirements. These are separate interfaces, not interchangeable command names. See [verification and desktop safety](/workflows/verification) for installation, permissions, dedicated sessions and evidence.
 
-The bundled [Cua Driver skill](https://github.com/trycua/cua/tree/cua-driver-rs-v0.38.0/libs/cua-driver/rust/Skills/cua-driver) is upstream's `libs/cua-driver/rust/Skills/cua-driver` at tag `cua-driver-rs-v0.38.0`, vendored with all three platform guides (`MACOS.md`, `WINDOWS.md`, `LINUX.md`) plus `WORKFLOW.md`, `RUNTIME.md`, `VISUAL.md`, `BROWSER.md`, `RECORDING.md`, and `EMBEDDING.md`; Atomic owns the `SKILL.md` frontmatter and adapts the macOS permission-approval guidance described below. MIT licensed, © 2025 Cua AI, Inc. Its core guide routes to focused references for authorization, exact targets, observation, and outcome verification. It does not install the `cua-driver` executable or turn telemetry off, and Atomic never runs `cua-driver skills install`. Other permission prompts stay with you. The one exception, on by default: the agent approves Cua Driver's own macOS Accessibility and Screen Recording prompts itself over the host's VNC or Screen Sharing when credentials for it are available, and reports each approval. It never approves any other permission or another app's dialog. Set `ATOMIC_CUA_AUTO_APPROVE=0` to turn this off and have the agent ask you instead. Chromium browsers, Mobile Safari, and CDP-exposing apps stay with `agent-browser` even though the vendored `BROWSER.md` describes upstream's browser route; that route applies only to browsers agent-browser cannot reach, such as desktop Safari or Firefox.
+The bundled [agent-desktop skill](https://github.com/vercel-labs/agent-desktop/tree/v1.0.2/skills/agent-desktop) is upstream's `skills/agent-desktop/SKILL.md` at tag `v1.0.2`, Apache-2.0 licensed. Atomic owns its frontmatter and adds one section, "Install and permissions", with the bounded install attempt and the readiness check; the rest is upstream's text. It is a short guide: the detailed guides and every reference are compiled into the CLI and printed by `agent-desktop skills get desktop`, `agent-desktop skills get platform`, and `agent-desktop skills get desktop <reference>`, so they always match the installed version. The skill does not install the `agent-desktop` executable, and Atomic never runs `npx skills add` for it. Permission prompts stay with you: on macOS the agent opens `agent-desktop permissions --guide` and you approve it.
 
 The bundled [Herdr skill](https://github.com/herdrdev/herdr/blob/v0.9.5/skills/herdr/SKILL.md) requires an explicit Herdr mention or request and `HERDR_ENV=1`; it stops outside a Herdr-managed pane. It does not install Herdr or authorize control of unrelated panes. Use returned pane IDs, and check completion separately from command submission.
 

package/docs/usage.md

@@ -181,7 +181,7 @@ User-preference: keep PRs under 500 changed lines
 Co-authored-by: Ada Lovelace <ada@example.com>
 ```
 
-Tasks done without a workflow record `Assistant-workflow: inline`. Each `Assistant-verification` line names one check that ran or was attempted, such as unit or E2E tests, agent-browser, Cua Driver, Herdr terminal automation, or the qlty CLI, with its outcome (`passed`, `failed`, or `unavailable`). Each preference carries a `Co-authored-by` line naming the user who expressed it. Before choosing between a workflow and inline work, deciding how to verify a change, or estimating how long a task will take, the agent looks up comparable records with your version control system and its hosting CLI (for example `git log` and `gh` on GitHub) and uses them as a guide alongside your request. A lack of workflow history, or a history of mostly inline tasks, does not make the agent default to inline work: it still judges from the task itself whether a workflow would help unless you have stated or recorded a preference. For verification, it starts from the checks that proved similar changes and skips setups previously recorded as unavailable unless something has changed, while still running the project's required checks. It applies your own recorded preferences first and falls back to other contributors' preferences as repository conventions only when yours don't cover the situation, so you can always override a convention by stating your preference. To turn off any of these records, such as only preferences or all of them, say so in your request, a context file, or `APPEND_SYSTEM.md`.
+Tasks done without a workflow record `Assistant-workflow: inline`. Each `Assistant-verification` line names one check that ran or was attempted, such as unit or E2E tests, agent-browser, agent-desktop, Herdr terminal automation, or the qlty CLI, with its outcome (`passed`, `failed`, or `unavailable`). Each preference carries a `Co-authored-by` line naming the user who expressed it. Before choosing between a workflow and inline work, deciding how to verify a change, or estimating how long a task will take, the agent looks up comparable records with your version control system and its hosting CLI (for example `git log` and `gh` on GitHub) and uses them as a guide alongside your request. A lack of workflow history, or a history of mostly inline tasks, does not make the agent default to inline work: it still judges from the task itself whether a workflow would help unless you have stated or recorded a preference. For verification, it starts from the checks that proved similar changes and skips setups previously recorded as unavailable unless something has changed, while still running the project's required checks. It applies your own recorded preferences first and falls back to other contributors' preferences as repository conventions only when yours don't cover the situation, so you can always override a convention by stating your preference. To turn off any of these records, such as only preferences or all of them, say so in your request, a context file, or `APPEND_SYSTEM.md`.
 
 ## Exporting and Sharing Sessions