Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

docs: one reference page per command group for the CLI, Driver, Lume and Bench (CUA-1863) (#5466)

Francesco Bonacci087239822a3b
diff --git a/.github/scripts/tests/test_sync_lume_release_docs.py b/.github/scripts/tests/test_sync_lume_release_docs.py
index ae510820a1..c03f7b5557 100644
--- a/.github/scripts/tests/test_sync_lume_release_docs.py
+++ b/.github/scripts/tests/test_sync_lume_release_docs.py
@@ -25,7 +25,7 @@ def test_sync_lume_release_docs_updates_every_generated_marker(tmp_path: Path):
paths = lume_reference_paths(tmp_path)
assert f"{DOCS}/http-api.mdx" in paths
- assert any("/cli/" in relative for relative in paths)
+ assert f"{DOCS}/cli.mdx" in paths
for relative in paths:
assert "Version: 9.9.9" in (tmp_path / relative).read_text()
assert "Documented against Lume **9.9.9**." in (tmp_path / DOCS / "http-api.mdx").read_text()
diff --git a/docs/content/docs/cua-bench/guides/benchmarks.mdx b/docs/content/docs/cua-bench/guides/benchmarks.mdx
index 693b3fd6d9..b9b40685c7 100644
--- a/docs/content/docs/cua-bench/guides/benchmarks.mdx
+++ b/docs/content/docs/cua-bench/guides/benchmarks.mdx
@@ -74,7 +74,7 @@ cb run info <run-id>
Each run writes `summary.json` (mean reward, pass@k) and one directory per
variant with `result.json`, `run.log` and the agent's `trajectory.json`
(ATIF, with screenshots), under `~/.local/share/cua-bench/runs`. Every key is
-in [Results](/cua-bench/reference/results).
+in [Results](/cua-bench/reference/task-definition#result-files).
## Try a task by hand
@@ -144,4 +144,4 @@ screen evidence for amd64 need a native amd64 host.
- [Adapter benchmarks](/cua-bench/guides/adapter-benchmarks):
OSWorld-Verified, MiniWoB++, WebVoyager, Online-Mind2Web, WebGym and the
grounding sets, through adapters.
-- [`cb run` reference](/cua-bench/reference/cli/run)
+- [`cb run` reference](/cua-bench/reference/cli#cb-run)
diff --git a/docs/content/docs/cua-bench/reference/cli/run.mdx b/docs/content/docs/cua-bench/reference/cli.mdx
similarity index 50%
rename from docs/content/docs/cua-bench/reference/cli/run.mdx
rename to docs/content/docs/cua-bench/reference/cli.mdx
index d662ceee3c..c6e8dade68 100644
--- a/docs/content/docs/cua-bench/reference/cli/run.mdx
+++ b/docs/content/docs/cua-bench/reference/cli.mdx
@@ -1,6 +1,6 @@
---
-title: "cb run"
-description: "Run a task or dataset with an agent or the oracle, run one interactively, and follow runs."
+title: "cb CLI"
+description: "cua-bench: run computer-use tasks and benchmark datasets on local and cloud sandboxes."
---
{/*
@@ -10,6 +10,14 @@ description: "Run a task or dataset with an agent or the oracle, run one interac
Version: 0.3.1
*/}
+```text output
+cb <COMMAND> [OPTIONS]
+```
+
+Run `cb <command> --help` for the build you have.
+
+## Commands
+
| Command | Description |
| --- | --- |
| [`cb run`](#cb-run) | Run a task or dataset, and manage runs. |
@@ -21,8 +29,37 @@ description: "Run a task or dataset with an agent or the oracle, run one interac
| [`cb run stop`](#cb-run-stop) | Stop a run and release its sandboxes. |
| [`cb run logs`](#cb-run-logs) | View combined logs from a run or session. |
| [`cb interact`](#cb-interact) | Run a task's setup with its desktop visible, then evaluate. |
-
-Every command also accepts the [global options](/cua-bench/reference/cli#global-options).
+| [`cb task`](#cb-task) | Inspect and manage task environments. |
+| [`cb task info`](#cb-task-info) | Show detailed information about a task. |
+| [`cb task list`](#cb-task-list) | List tasks in a directory. |
+| [`cb task create`](#cb-task-create) | Scaffold a new task environment. |
+| [`cb task generate`](#cb-task-generate) | Generate a task from a prompt using Claude. |
+| [`cb dataset`](#cb-dataset) | Manage datasets and build from outputs. |
+| [`cb dataset list`](#cb-dataset-list) | List available datasets from registry. |
+| [`cb dataset build`](#cb-dataset-build) | Build a dataset from batch outputs. |
+| [`cb trace`](#cb-trace) | View and analyze trace datasets. |
+| [`cb trace view`](#cb-trace-view) | View a single trace in browser. |
+| [`cb trace traj`](#cb-trace-traj) | View agent trajectories from a run in cua.ai/trajectory-viewer. |
+| [`cb env`](#cb-env) | List or garbage-collect sandboxes and pools. |
+| [`cb env ls`](#cb-env-ls) | List managed cloud pools and claims. |
+| [`cb env gc`](#cb-env-gc) | Delete idle managed pools and stuck claims. |
+| [`cb login`](#cb-login) | Removed: Cua Cloud has ended. |
+| [`cb status`](#cb-status) | Show system status dashboard. |
+| [`cb prune`](#cb-prune) | Clean up cua-bench run data (and 0.2.x image leftovers). |
+| [`cb agent`](#cb-agent) | Scaffold custom agents. |
+| [`cb agent init`](#cb-agent-init) | Create a new agent from template. |
+| [`cb agent build`](#cb-agent-build) | Deprecated: cb run executes agents in-process. |
+| [`cb agent push`](#cb-agent-push) | Deprecated: agent images are no longer used. |
+| [`cb image`](#cb-image) | Show the canonical images (the local image store is deprecated). |
+| [`cb image list`](#cb-image-list) | List all images. |
+| [`cb image info`](#cb-image-info) | Show image details. |
+| [`cb image create`](#cb-image-create) | Deprecated: create an image from a platform. |
+| [`cb image delete`](#cb-image-delete) | Deprecated: delete a stored image. |
+| [`cb image clone`](#cb-image-clone) | Deprecated: clone a stored image. |
+| [`cb image shell`](#cb-image-shell) | Deprecated: interactive shell into a stored image. |
+| [`cb platform`](#cb-platform) | Show available platform configurations. |
+| [`cb platform list`](#cb-platform-list) | List all available platforms. |
+| [`cb platform info`](#cb-platform-info) | Show platform details. |
## `cb run`
@@ -296,6 +333,652 @@ cb interact ./tasks/hello_file_env --variant-id 1 --oracle --screenshot shot.png
cb interact click-button --dataset cua-bench-basic
```
+## `cb task`
+
+Inspect and manage task environments.
+
+```text output
+cb task [COMMAND]
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cb-task"
+# List the tasks in a directory
+cb task list ./tasks
+
+# Inspect one task
+cb task info ./tasks/hello_file_env
+```
+
+### `cb task info`
+
+Show detailed information about a task.
+
+```text output
+cb task info <path>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<path>` | string | required | Path to task directory (containing main.py). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cb-task-info"
+# Inspect a task's variants and lifecycle functions
+cb task info ./tasks/hello_file_env
+```
+
+### `cb task list`
+
+List tasks in a directory.
+
+```text output
+cb task list [<path>]
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<path>` | string | `.` | Path to directory containing tasks (default: current directory). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cb-task-list"
+# List tasks here
+cb task list
+
+# List tasks in a directory
+cb task list ./tasks
+```
+
+### `cb task create`
+
+Scaffold a new task environment.
+
+```text output
+cb task create [<path>]
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<path>` | string | `.` | Target directory to create the task in (default: current directory). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cb-task-create"
+# Scaffold a task interactively under ./tasks
+cb task create ./tasks
+```
+
+### `cb task generate`
+
+Generate a task from a prompt using Claude.
+
+```text output
+cb task generate [OPTIONS] <prompt> [<output>]
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<prompt>` | string | required | Natural language description of the task to generate (e.g., "2048 game"). |
+| `<output>` | string | optional | Output directory (default: named after the prompt). |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cb-task-generate--no-interaction"></span>`--no-interaction` | boolean | `false` | Skip interactive prompts and run Claude non-interactively. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cb-task-generate"
+# Generate a task
+cb task generate '2048 game'
+
+# Generate into a directory without prompts
+cb task generate 'Sort a spreadsheet column' ./tasks/sort_column --no-interaction
+```
+
+## `cb dataset`
+
+Manage datasets and build from outputs.
+
+```text output
+cb dataset [COMMAND]
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cb-dataset"
+# List registry datasets
+cb dataset list
+
+# Build a training dataset from run outputs
+cb dataset build ./outputs
+```
+
+### `cb dataset list`
+
+List available datasets from registry.
+
+```text output
+cb dataset list
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cb-dataset-list"
+# List registry datasets
+cb dataset list
+```
+
+### `cb dataset build`
+
+Build a dataset from batch outputs.
+
+```text output
+cb dataset build [OPTIONS] <outputs_path> [<max_samples>]
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<outputs_path>` | string | required | Path to outputs folder from batch dump (e.g., ./outputs or /tmp/td_output). |
+| `<max_samples>` | integer | optional | Limit number of samples processed (useful for testing). |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cb-dataset-build--mode"></span>`--mode` | string | `aguvis-stage-1` | Processing mode: aguvis-stage-1 (action augmentation) or gui-r1 (low-level click). |
+| <span id="cb-dataset-build--dataset-name"></span>`--dataset-name` | string | | Dataset name when saving to disk (default: td_&lt;mode&gt;_dataset). |
+| <span id="cb-dataset-build--save-dir"></span>`--save-dir` | string | | Directory to save a JSONL dataset (default: &lt;outputs&gt;/processed if not pushing). |
+| <span id="cb-dataset-build--repo-id"></span>`--repo-id` | string | | HF Hub repository ID (e.g., username/repo). Required with --push-to-hub. |
+| <span id="cb-dataset-build--push-to-hub"></span>`--push-to-hub` | boolean | `false` | Push the dataset to the Hugging Face Hub. |
+| <span id="cb-dataset-build--private"></span>`--private` | boolean | `false` | When pushing to hub, create/update the repo as private. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cb-dataset-build"
+# Build an aguvis-stage-1 dataset from run outputs
+cb dataset build ./outputs
+
+# Build 100 gui-r1 samples
+cb dataset build ./outputs 100 --mode gui-r1
+
+# Push a private dataset to the Hugging Face Hub
+cb dataset build ./outputs --push-to-hub --repo-id me/cua-clicks --private
+```
+
+## `cb trace`
+
+View and analyze trace datasets.
+
+```text output
+cb trace [COMMAND]
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cb-trace"
+# Open a run's trace in the browser
+cb trace view 30c12572
+
+# Open a run's agent trajectories
+cb trace traj 30c12572
+```
+
+### `cb trace view`
+
+View a single trace in browser.
+
+```text output
+cb trace view <identifier>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<identifier>` | string | required | Run ID or session ID (e.g., "30c12572" or "task-30c12572-click-button-v0"). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cb-trace-view"
+# Open a run's trace
+cb trace view 30c12572
+
+# Open one session's trace
+cb trace view task-30c12572-click-button-v0
+```
+
+### `cb trace traj`
+
+View agent trajectories from a run in cua.ai/trajectory-viewer.
+
+```text output
+cb trace traj [OPTIONS] <identifier>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<identifier>` | string | required | Run ID (e.g., "30c12572"). |
+
+| Flag | Short | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| <span id="cb-trace-traj--port"></span>`--port` | `-p` | integer | `8090` | Local file server port (default: 8090). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cb-trace-traj"
+# Open a run's trajectories
+cb trace traj 30c12572
+
+# Serve the files on another port
+cb trace traj 30c12572 --port 9000
+```
+
+## Sandboxes and account
+
+Cloud pools and local sandboxes, sign-in, status and cleanup.
+
+### `cb env`
+
+List or garbage-collect sandboxes and pools.
+
+```text output
+cb env [COMMAND]
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cb-env"
+# List managed cloud pools and claims
+cb env ls
+
+# Delete pools idle for an hour
+cb env gc --idle 1h
+```
+
+#### `cb env ls`
+
+List managed cloud pools and claims.
+
+```text output
+cb env ls [OPTIONS]
+```
+
+Alias: `cb env list`.
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cb-env-ls--local"></span>`--local` | boolean | `false` | List local sandboxes instead. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cb-env-ls"
+# List managed cloud pools and claims
+cb env ls
+
+# List local sandboxes
+cb env ls --local
+```
+
+#### `cb env gc`
+
+Delete idle managed pools and stuck claims.
+
+```text output
+cb env gc [OPTIONS]
+```
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cb-env-gc--idle"></span>`--idle` | string | `30m` | Delete pools unused for this long (default 30m). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cb-env-gc"
+# Delete pools unused for 30 minutes
+cb env gc
+
+# Delete pools idle for two hours
+cb env gc --idle 2h
+```
+
+### `cb login`
+
+Removed: Cua Cloud has ended.
+
+```text output
+cb login [OPTIONS]
+```
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cb-login--no-browser"></span>`--no-browser` | boolean | `false` | Print the sign-in URL only. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cb-login"
+# Sign in with a browser
+cb login
+
+# Print the sign-in URL instead of opening a browser
+cb login --no-browser
+```
+
+### `cb status`
+
+Show system status dashboard.
+
+```text output
+cb status
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cb-status"
+# Show runs, sandboxes and credentials at a glance
+cb status
+```
+
+### `cb prune`
+
+Clean up cua-bench run data (and 0.2.x image leftovers).
+
+```text output
+cb prune [OPTIONS]
+```
+
+| Flag | Short | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| <span id="cb-prune--keep"></span>`--keep` | | integer | | With --runs: keep the N newest runs and remove only older ones. |
+| <span id="cb-prune--older-than"></span>`--older-than` | | number | | With --runs: remove only runs older than DAYS. |
+| <span id="cb-prune--all"></span>`--all` | `-a` | boolean | `false` | Remove runs and 0.2.x image leftovers. |
+| <span id="cb-prune--images"></span>`--images` | | boolean | `false` | Remove 0.2.x stored images (deprecated store). |
+| <span id="cb-prune--overlays"></span>`--overlays` | | boolean | `false` | Remove 0.2.x task overlays (deprecated store). |
+| <span id="cb-prune--runs"></span>`--runs` | | boolean | `false` | Remove run logs and registry. |
+| <span id="cb-prune--docker"></span>`--docker` | | boolean | `false` | Deprecated: cua-bench no longer creates Docker resources. |
+| <span id="cb-prune--dry-run"></span>`--dry-run` | | boolean | `false` | Show what would be deleted without deleting. |
+| <span id="cb-prune--force"></span>`--force` | `-f` | boolean | `false` | Skip confirmation prompts. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cb-prune"
+# Preview what would be removed
+cb prune --all --dry-run
+
+# Remove run logs without asking
+cb prune --runs --force
+
+# Keep the 20 newest runs, delete the rest
+cb prune --runs --keep 20
+
+# Delete runs older than 30 days
+cb prune --runs --older-than 30
+```
+
+## `cb agent`
+
+Scaffold custom agents.
+
+Create and manage custom agents for cua-bench.
+
+```text output
+cb agent [COMMAND]
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cb-agent"
+# Scaffold an agent in ./my-agent
+cb agent init my-agent
+```
+
+### `cb agent init`
+
+Create a new agent from template.
+
+Scaffold a new custom agent with working sample code.
+
+```text output
+cb agent init [OPTIONS] <name>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<name>` | string | required | Agent name (e.g., 'my-agent'). |
+
+| Flag | Short | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| <span id="cb-agent-init--output-dir"></span>`--output-dir` | `-o` | string | | Output directory (default: ./&lt;name&gt;). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cb-agent-init"
+# Scaffold an agent in ./my-agent
+cb agent init my-agent
+
+# Scaffold it into another directory
+cb agent init my-agent --output-dir ./agents/my-agent
+```
+
+### `cb agent build`
+
+Deprecated: cb run executes agents in-process.
+
+Build a Docker image for an agent directory containing a Dockerfile.
+
+```text output
+cb agent build [OPTIONS] <path>
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cb-agent-build"
+# Build an agent image (deprecated)
+cb agent build ./my-agent --tag my-agent:dev
+```
+
+### `cb agent push`
+
+Deprecated: agent images are no longer used.
+
+Push a Docker image through the CUA API proxy with workspace namespacing.
+
+```text output
+cb agent push [OPTIONS] [<image_name>]
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cb-agent-push"
+# Push an agent image (deprecated)
+cb agent push my-agent:dev
+```
+
+## Images and platforms
+
+The canonical images and platform configurations.
+
+### `cb image`
+
+Show the canonical images (the local image store is deprecated).
+
+```text output
+cb image [COMMAND]
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cb-image"
+# List the canonical images
+cb image
+
+# Show one image
+cb image info linux
+```
+
+#### `cb image list`
+
+List all images.
+
+```text output
+cb image list [OPTIONS]
+```
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cb-image-list--platform"></span>`--platform` | string | | Filter by platform. |
+| <span id="cb-image-list--format"></span>`--format` | `table` \| `json` | `table` | Output format. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cb-image-list"
+# List images
+cb image list
+
+# List one platform's images as JSON
+cb image list --platform linux-docker --format json
+```
+
+#### `cb image info`
+
+Show image details.
+
+```text output
+cb image info <name>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<name>` | string | required | Image name. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cb-image-info"
+# Show one image
+cb image info linux
+```
+
+#### `cb image create`
+
+Deprecated: create an image from a platform.
+
+```text output
+cb image create [OPTIONS] <platform>
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cb-image-create"
+# Create a Linux image (deprecated)
+cb image create linux-docker --name my-linux
+```
+
+#### `cb image delete`
+
+Deprecated: delete a stored image.
+
+```text output
+cb image delete [OPTIONS] <name>
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cb-image-delete"
+# Delete a stored image (deprecated)
+cb image delete my-linux --force
+```
+
+#### `cb image clone`
+
+Deprecated: clone a stored image.
+
+```text output
+cb image clone [OPTIONS] <source> <target>
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cb-image-clone"
+# Clone a stored image (deprecated)
+cb image clone my-linux my-linux-2
+```
+
+#### `cb image shell`
+
+Deprecated: interactive shell into a stored image.
+
+```text output
+cb image shell [OPTIONS] <name>
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cb-image-shell"
+# Open a shell in a stored image (deprecated)
+cb image shell my-linux
+```
+
+### `cb platform`
+
+Show available platform configurations.
+
+```text output
+cb platform [COMMAND]
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cb-platform"
+# List platforms
+cb platform
+
+# Show one platform
+cb platform info linux-docker
+```
+
+#### `cb platform list`
+
+List all available platforms.
+
+```text output
+cb platform list [OPTIONS]
+```
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cb-platform-list--format"></span>`--format` | `table` \| `json` | `table` | Output format. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cb-platform-list"
+# List platforms
+cb platform list
+
+# As JSON
+cb platform list --format json
+```
+
+#### `cb platform info`
+
+Show platform details.
+
+```text output
+cb platform info <platform>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<platform>` | string | required | Platform name (e.g., linux-docker, windows-qemu). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cb-platform-info"
+# Show one platform
+cb platform info windows-qemu
+```
+
+## Global options
+
+`--help` prints help for any command; `--version` prints the version.
+
## Exit codes
| Code | Meaning |
diff --git a/docs/content/docs/cua-bench/reference/cli/agent.mdx b/docs/content/docs/cua-bench/reference/cli/agent.mdx
deleted file mode 100644
index 8bca0485f8..0000000000
--- a/docs/content/docs/cua-bench/reference/cli/agent.mdx
+++ /dev/null
@@ -1,107 +0,0 @@
----
-title: "cb agent"
-description: "Scaffold custom agents."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-bench
- Source: scripts/docs-generators/extract_cb_docs.py (cua_bench)
- Version: 0.3.1
-*/}
-
-| Command | Description |
-| --- | --- |
-| [`cb agent init`](#cb-agent-init) | Create a new agent from template. |
-| [`cb agent build`](#cb-agent-build) | Deprecated: cb run executes agents in-process. |
-| [`cb agent push`](#cb-agent-push) | Deprecated: agent images are no longer used. |
-
-Every command also accepts the [global options](/cua-bench/reference/cli#global-options).
-
-<span id="cb-agent"></span>
-
-Scaffold custom agents.
-
-Create and manage custom agents for cua-bench.
-
-```text output
-cb agent [COMMAND]
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cb-agent"
-# Scaffold an agent in ./my-agent
-cb agent init my-agent
-```
-
-## `cb agent init`
-
-Create a new agent from template.
-
-Scaffold a new custom agent with working sample code.
-
-```text output
-cb agent init [OPTIONS] <name>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<name>` | string | required | Agent name (e.g., 'my-agent'). |
-
-| Flag | Short | Type | Default | Description |
-| --- | --- | --- | --- | --- |
-| <span id="cb-agent-init--output-dir"></span>`--output-dir` | `-o` | string | | Output directory (default: ./&lt;name&gt;). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cb-agent-init"
-# Scaffold an agent in ./my-agent
-cb agent init my-agent
-
-# Scaffold it into another directory
-cb agent init my-agent --output-dir ./agents/my-agent
-```
-
-## `cb agent build`
-
-Deprecated: cb run executes agents in-process.
-
-Build a Docker image for an agent directory containing a Dockerfile.
-
-```text output
-cb agent build [OPTIONS] <path>
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cb-agent-build"
-# Build an agent image (deprecated)
-cb agent build ./my-agent --tag my-agent:dev
-```
-
-## `cb agent push`
-
-Deprecated: agent images are no longer used.
-
-Push a Docker image through the CUA API proxy with workspace namespacing.
-
-```text output
-cb agent push [OPTIONS] [<image_name>]
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cb-agent-push"
-# Push an agent image (deprecated)
-cb agent push my-agent:dev
-```
-
-## Exit codes
-
-| Code | Meaning |
-| --- | --- |
-| `0` | Success: every variant completed. |
-| `1` | Failure: a variant failed or was cancelled, or the command could not run. |
-| `2` | Usage error: an unknown command, flag or value. |
-| `130` | Interrupted (Ctrl-C); running variants are cancelled. |
diff --git a/docs/content/docs/cua-bench/reference/cli/dataset.mdx b/docs/content/docs/cua-bench/reference/cli/dataset.mdx
deleted file mode 100644
index 7d27783608..0000000000
--- a/docs/content/docs/cua-bench/reference/cli/dataset.mdx
+++ /dev/null
@@ -1,95 +0,0 @@
----
-title: "cb dataset"
-description: "List registry datasets and build training data from runs."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-bench
- Source: scripts/docs-generators/extract_cb_docs.py (cua_bench)
- Version: 0.3.1
-*/}
-
-| Command | Description |
-| --- | --- |
-| [`cb dataset list`](#cb-dataset-list) | List available datasets from registry. |
-| [`cb dataset build`](#cb-dataset-build) | Build a dataset from batch outputs. |
-
-Every command also accepts the [global options](/cua-bench/reference/cli#global-options).
-
-<span id="cb-dataset"></span>
-
-Manage datasets and build from outputs.
-
-```text output
-cb dataset [COMMAND]
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cb-dataset"
-# List registry datasets
-cb dataset list
-
-# Build a training dataset from run outputs
-cb dataset build ./outputs
-```
-
-## `cb dataset list`
-
-List available datasets from registry.
-
-```text output
-cb dataset list
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cb-dataset-list"
-# List registry datasets
-cb dataset list
-```
-
-## `cb dataset build`
-
-Build a dataset from batch outputs.
-
-```text output
-cb dataset build [OPTIONS] <outputs_path> [<max_samples>]
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<outputs_path>` | string | required | Path to outputs folder from batch dump (e.g., ./outputs or /tmp/td_output). |
-| `<max_samples>` | integer | optional | Limit number of samples processed (useful for testing). |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cb-dataset-build--mode"></span>`--mode` | string | `aguvis-stage-1` | Processing mode: aguvis-stage-1 (action augmentation) or gui-r1 (low-level click). |
-| <span id="cb-dataset-build--dataset-name"></span>`--dataset-name` | string | | Dataset name when saving to disk (default: td_&lt;mode&gt;_dataset). |
-| <span id="cb-dataset-build--save-dir"></span>`--save-dir` | string | | Directory to save a JSONL dataset (default: &lt;outputs&gt;/processed if not pushing). |
-| <span id="cb-dataset-build--repo-id"></span>`--repo-id` | string | | HF Hub repository ID (e.g., username/repo). Required with --push-to-hub. |
-| <span id="cb-dataset-build--push-to-hub"></span>`--push-to-hub` | boolean | `false` | Push the dataset to the Hugging Face Hub. |
-| <span id="cb-dataset-build--private"></span>`--private` | boolean | `false` | When pushing to hub, create/update the repo as private. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cb-dataset-build"
-# Build an aguvis-stage-1 dataset from run outputs
-cb dataset build ./outputs
-
-# Build 100 gui-r1 samples
-cb dataset build ./outputs 100 --mode gui-r1
-
-# Push a private dataset to the Hugging Face Hub
-cb dataset build ./outputs --push-to-hub --repo-id me/cua-clicks --private
-```
-
-## Exit codes
-
-| Code | Meaning |
-| --- | --- |
-| `0` | Success: every variant completed. |
-| `1` | Failure: a variant failed or was cancelled, or the command could not run. |
-| `2` | Usage error: an unknown command, flag or value. |
-| `130` | Interrupted (Ctrl-C); running variants are cancelled. |
diff --git a/docs/content/docs/cua-bench/reference/cli/env.mdx b/docs/content/docs/cua-bench/reference/cli/env.mdx
deleted file mode 100644
index f5981436dd..0000000000
--- a/docs/content/docs/cua-bench/reference/cli/env.mdx
+++ /dev/null
@@ -1,168 +0,0 @@
----
-title: "Sandboxes and account"
-description: "Cloud pools and local sandboxes, sign-in, status and cleanup."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-bench
- Source: scripts/docs-generators/extract_cb_docs.py (cua_bench)
- Version: 0.3.1
-*/}
-
-| Command | Description |
-| --- | --- |
-| [`cb env`](#cb-env) | List or garbage-collect sandboxes and pools. |
-| [`cb env ls`](#cb-env-ls) | List managed cloud pools and claims. |
-| [`cb env gc`](#cb-env-gc) | Delete idle managed pools and stuck claims. |
-| [`cb login`](#cb-login) | Removed: Cua Cloud has ended. |
-| [`cb status`](#cb-status) | Show system status dashboard. |
-| [`cb prune`](#cb-prune) | Clean up cua-bench run data (and 0.2.x image leftovers). |
-
-Every command also accepts the [global options](/cua-bench/reference/cli#global-options).
-
-## `cb env`
-
-List or garbage-collect sandboxes and pools.
-
-```text output
-cb env [COMMAND]
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cb-env"
-# List managed cloud pools and claims
-cb env ls
-
-# Delete pools idle for an hour
-cb env gc --idle 1h
-```
-
-### `cb env ls`
-
-List managed cloud pools and claims.
-
-```text output
-cb env ls [OPTIONS]
-```
-
-Alias: `cb env list`.
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cb-env-ls--local"></span>`--local` | boolean | `false` | List local sandboxes instead. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cb-env-ls"
-# List managed cloud pools and claims
-cb env ls
-
-# List local sandboxes
-cb env ls --local
-```
-
-### `cb env gc`
-
-Delete idle managed pools and stuck claims.
-
-```text output
-cb env gc [OPTIONS]
-```
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cb-env-gc--idle"></span>`--idle` | string | `30m` | Delete pools unused for this long (default 30m). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cb-env-gc"
-# Delete pools unused for 30 minutes
-cb env gc
-
-# Delete pools idle for two hours
-cb env gc --idle 2h
-```
-
-## `cb login`
-
-Removed: Cua Cloud has ended.
-
-```text output
-cb login [OPTIONS]
-```
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cb-login--no-browser"></span>`--no-browser` | boolean | `false` | Print the sign-in URL only. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cb-login"
-# Sign in with a browser
-cb login
-
-# Print the sign-in URL instead of opening a browser
-cb login --no-browser
-```
-
-## `cb status`
-
-Show system status dashboard.
-
-```text output
-cb status
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cb-status"
-# Show runs, sandboxes and credentials at a glance
-cb status
-```
-
-## `cb prune`
-
-Clean up cua-bench run data (and 0.2.x image leftovers).
-
-```text output
-cb prune [OPTIONS]
-```
-
-| Flag | Short | Type | Default | Description |
-| --- | --- | --- | --- | --- |
-| <span id="cb-prune--keep"></span>`--keep` | | integer | | With --runs: keep the N newest runs and remove only older ones. |
-| <span id="cb-prune--older-than"></span>`--older-than` | | number | | With --runs: remove only runs older than DAYS. |
-| <span id="cb-prune--all"></span>`--all` | `-a` | boolean | `false` | Remove runs and 0.2.x image leftovers. |
-| <span id="cb-prune--images"></span>`--images` | | boolean | `false` | Remove 0.2.x stored images (deprecated store). |
-| <span id="cb-prune--overlays"></span>`--overlays` | | boolean | `false` | Remove 0.2.x task overlays (deprecated store). |
-| <span id="cb-prune--runs"></span>`--runs` | | boolean | `false` | Remove run logs and registry. |
-| <span id="cb-prune--docker"></span>`--docker` | | boolean | `false` | Deprecated: cua-bench no longer creates Docker resources. |
-| <span id="cb-prune--dry-run"></span>`--dry-run` | | boolean | `false` | Show what would be deleted without deleting. |
-| <span id="cb-prune--force"></span>`--force` | `-f` | boolean | `false` | Skip confirmation prompts. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cb-prune"
-# Preview what would be removed
-cb prune --all --dry-run
-
-# Remove run logs without asking
-cb prune --runs --force
-
-# Keep the 20 newest runs, delete the rest
-cb prune --runs --keep 20
-
-# Delete runs older than 30 days
-cb prune --runs --older-than 30
-```
-
-## Exit codes
-
-| Code | Meaning |
-| --- | --- |
-| `0` | Success: every variant completed. |
-| `1` | Failure: a variant failed or was cancelled, or the command could not run. |
-| `2` | Usage error: an unknown command, flag or value. |
-| `130` | Interrupted (Ctrl-C); running variants are cancelled. |
diff --git a/docs/content/docs/cua-bench/reference/cli/images.mdx b/docs/content/docs/cua-bench/reference/cli/images.mdx
deleted file mode 100644
index fe009b35d6..0000000000
--- a/docs/content/docs/cua-bench/reference/cli/images.mdx
+++ /dev/null
@@ -1,214 +0,0 @@
----
-title: "Images and platforms"
-description: "The canonical images and platform configurations."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-bench
- Source: scripts/docs-generators/extract_cb_docs.py (cua_bench)
- Version: 0.3.1
-*/}
-
-| Command | Description |
-| --- | --- |
-| [`cb image`](#cb-image) | Show the canonical images (the local image store is deprecated). |
-| [`cb image list`](#cb-image-list) | List all images. |
-| [`cb image info`](#cb-image-info) | Show image details. |
-| [`cb image create`](#cb-image-create) | Deprecated: create an image from a platform. |
-| [`cb image delete`](#cb-image-delete) | Deprecated: delete a stored image. |
-| [`cb image clone`](#cb-image-clone) | Deprecated: clone a stored image. |
-| [`cb image shell`](#cb-image-shell) | Deprecated: interactive shell into a stored image. |
-| [`cb platform`](#cb-platform) | Show available platform configurations. |
-| [`cb platform list`](#cb-platform-list) | List all available platforms. |
-| [`cb platform info`](#cb-platform-info) | Show platform details. |
-
-Every command also accepts the [global options](/cua-bench/reference/cli#global-options).
-
-## `cb image`
-
-Show the canonical images (the local image store is deprecated).
-
-```text output
-cb image [COMMAND]
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cb-image"
-# List the canonical images
-cb image
-
-# Show one image
-cb image info linux
-```
-
-### `cb image list`
-
-List all images.
-
-```text output
-cb image list [OPTIONS]
-```
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cb-image-list--platform"></span>`--platform` | string | | Filter by platform. |
-| <span id="cb-image-list--format"></span>`--format` | `table` \| `json` | `table` | Output format. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cb-image-list"
-# List images
-cb image list
-
-# List one platform's images as JSON
-cb image list --platform linux-docker --format json
-```
-
-### `cb image info`
-
-Show image details.
-
-```text output
-cb image info <name>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<name>` | string | required | Image name. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cb-image-info"
-# Show one image
-cb image info linux
-```
-
-### `cb image create`
-
-Deprecated: create an image from a platform.
-
-```text output
-cb image create [OPTIONS] <platform>
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cb-image-create"
-# Create a Linux image (deprecated)
-cb image create linux-docker --name my-linux
-```
-
-### `cb image delete`
-
-Deprecated: delete a stored image.
-
-```text output
-cb image delete [OPTIONS] <name>
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cb-image-delete"
-# Delete a stored image (deprecated)
-cb image delete my-linux --force
-```
-
-### `cb image clone`
-
-Deprecated: clone a stored image.
-
-```text output
-cb image clone [OPTIONS] <source> <target>
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cb-image-clone"
-# Clone a stored image (deprecated)
-cb image clone my-linux my-linux-2
-```
-
-### `cb image shell`
-
-Deprecated: interactive shell into a stored image.
-
-```text output
-cb image shell [OPTIONS] <name>
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cb-image-shell"
-# Open a shell in a stored image (deprecated)
-cb image shell my-linux
-```
-
-## `cb platform`
-
-Show available platform configurations.
-
-```text output
-cb platform [COMMAND]
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cb-platform"
-# List platforms
-cb platform
-
-# Show one platform
-cb platform info linux-docker
-```
-
-### `cb platform list`
-
-List all available platforms.
-
-```text output
-cb platform list [OPTIONS]
-```
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cb-platform-list--format"></span>`--format` | `table` \| `json` | `table` | Output format. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cb-platform-list"
-# List platforms
-cb platform list
-
-# As JSON
-cb platform list --format json
-```
-
-### `cb platform info`
-
-Show platform details.
-
-```text output
-cb platform info <platform>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<platform>` | string | required | Platform name (e.g., linux-docker, windows-qemu). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cb-platform-info"
-# Show one platform
-cb platform info windows-qemu
-```
-
-## Exit codes
-
-| Code | Meaning |
-| --- | --- |
-| `0` | Success: every variant completed. |
-| `1` | Failure: a variant failed or was cancelled, or the command could not run. |
-| `2` | Usage error: an unknown command, flag or value. |
-| `130` | Interrupted (Ctrl-C); running variants are cancelled. |
diff --git a/docs/content/docs/cua-bench/reference/cli/index.mdx b/docs/content/docs/cua-bench/reference/cli/index.mdx
deleted file mode 100644
index 33bbc4707a..0000000000
--- a/docs/content/docs/cua-bench/reference/cli/index.mdx
+++ /dev/null
@@ -1,121 +0,0 @@
----
-title: "cb"
-description: "cua-bench: run computer-use tasks and benchmark datasets on local and cloud sandboxes."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-bench
- Source: scripts/docs-generators/extract_cb_docs.py (cua_bench)
- Version: 0.3.1
-*/}
-
-```text output
-cb <COMMAND> [OPTIONS]
-```
-
-Run `cb <command> --help` for the build you have.
-
-## Commands
-
-### `cb run`
-
-Run a task or dataset with an agent or the oracle, run one interactively, and follow runs. [Reference](/cua-bench/reference/cli/run).
-
-| Command | Description |
-| --- | --- |
-| [`cb run`](/cua-bench/reference/cli/run#cb-run) | Run a task or dataset, and manage runs. |
-| <span id="cb-run-task"></span>[`cb run task`](/cua-bench/reference/cli/run#cb-run-task) | Run one task variant. |
-| <span id="cb-run-dataset"></span>[`cb run dataset`](/cua-bench/reference/cli/run#cb-run-dataset) | Run every task and variant of a dataset in parallel. |
-| <span id="cb-run-list"></span>[`cb run list`](/cua-bench/reference/cli/run#cb-run-list) | List all runs with status. |
-| <span id="cb-run-info"></span>[`cb run info`](/cua-bench/reference/cli/run#cb-run-info) | Show detailed info about a run. |
-| <span id="cb-run-watch"></span>[`cb run watch`](/cua-bench/reference/cli/run#cb-run-watch) | Watch a run in real-time with live updates. |
-| <span id="cb-run-stop"></span>[`cb run stop`](/cua-bench/reference/cli/run#cb-run-stop) | Stop a run and release its sandboxes. |
-| <span id="cb-run-logs"></span>[`cb run logs`](/cua-bench/reference/cli/run#cb-run-logs) | View combined logs from a run or session. |
-| <span id="cb-interact"></span>[`cb interact`](/cua-bench/reference/cli/run#cb-interact) | Run a task's setup with its desktop visible, then evaluate. |
-
-### `cb task`
-
-Inspect, list, scaffold and generate tasks. [Reference](/cua-bench/reference/cli/task).
-
-| Command | Description |
-| --- | --- |
-| [`cb task`](/cua-bench/reference/cli/task#cb-task) | Inspect and manage task environments. |
-| <span id="cb-task-info"></span>[`cb task info`](/cua-bench/reference/cli/task#cb-task-info) | Show detailed information about a task. |
-| <span id="cb-task-list"></span>[`cb task list`](/cua-bench/reference/cli/task#cb-task-list) | List tasks in a directory. |
-| <span id="cb-task-create"></span>[`cb task create`](/cua-bench/reference/cli/task#cb-task-create) | Scaffold a new task environment. |
-| <span id="cb-task-generate"></span>[`cb task generate`](/cua-bench/reference/cli/task#cb-task-generate) | Generate a task from a prompt using Claude. |
-
-### `cb dataset`
-
-List registry datasets and build training data from runs. [Reference](/cua-bench/reference/cli/dataset).
-
-| Command | Description |
-| --- | --- |
-| [`cb dataset`](/cua-bench/reference/cli/dataset#cb-dataset) | Manage datasets and build from outputs. |
-| <span id="cb-dataset-list"></span>[`cb dataset list`](/cua-bench/reference/cli/dataset#cb-dataset-list) | List available datasets from registry. |
-| <span id="cb-dataset-build"></span>[`cb dataset build`](/cua-bench/reference/cli/dataset#cb-dataset-build) | Build a dataset from batch outputs. |
-
-### `cb trace`
-
-View traces and agent trajectories. [Reference](/cua-bench/reference/cli/trace).
-
-| Command | Description |
-| --- | --- |
-| [`cb trace`](/cua-bench/reference/cli/trace#cb-trace) | View and analyze trace datasets. |
-| <span id="cb-trace-view"></span>[`cb trace view`](/cua-bench/reference/cli/trace#cb-trace-view) | View a single trace in browser. |
-| <span id="cb-trace-traj"></span>[`cb trace traj`](/cua-bench/reference/cli/trace#cb-trace-traj) | View agent trajectories from a run in cua.ai/trajectory-viewer. |
-
-### Sandboxes and account
-
-Cloud pools and local sandboxes, sign-in, status and cleanup. [Reference](/cua-bench/reference/cli/env).
-
-| Command | Description |
-| --- | --- |
-| <span id="cb-env"></span>[`cb env`](/cua-bench/reference/cli/env#cb-env) | List or garbage-collect sandboxes and pools. |
-| <span id="cb-env-ls"></span>[`cb env ls`](/cua-bench/reference/cli/env#cb-env-ls) | List managed cloud pools and claims. |
-| <span id="cb-env-gc"></span>[`cb env gc`](/cua-bench/reference/cli/env#cb-env-gc) | Delete idle managed pools and stuck claims. |
-| <span id="cb-login"></span>[`cb login`](/cua-bench/reference/cli/env#cb-login) | Removed: Cua Cloud has ended. |
-| <span id="cb-status"></span>[`cb status`](/cua-bench/reference/cli/env#cb-status) | Show system status dashboard. |
-| <span id="cb-prune"></span>[`cb prune`](/cua-bench/reference/cli/env#cb-prune) | Clean up cua-bench run data (and 0.2.x image leftovers). |
-
-### `cb agent`
-
-Scaffold custom agents. [Reference](/cua-bench/reference/cli/agent).
-
-| Command | Description |
-| --- | --- |
-| [`cb agent`](/cua-bench/reference/cli/agent#cb-agent) | Scaffold custom agents. |
-| <span id="cb-agent-init"></span>[`cb agent init`](/cua-bench/reference/cli/agent#cb-agent-init) | Create a new agent from template. |
-| <span id="cb-agent-build"></span>[`cb agent build`](/cua-bench/reference/cli/agent#cb-agent-build) | Deprecated: cb run executes agents in-process. |
-| <span id="cb-agent-push"></span>[`cb agent push`](/cua-bench/reference/cli/agent#cb-agent-push) | Deprecated: agent images are no longer used. |
-
-### Images and platforms
-
-The canonical images and platform configurations. [Reference](/cua-bench/reference/cli/images).
-
-| Command | Description |
-| --- | --- |
-| <span id="cb-image"></span>[`cb image`](/cua-bench/reference/cli/images#cb-image) | Show the canonical images (the local image store is deprecated). |
-| <span id="cb-image-list"></span>[`cb image list`](/cua-bench/reference/cli/images#cb-image-list) | List all images. |
-| <span id="cb-image-info"></span>[`cb image info`](/cua-bench/reference/cli/images#cb-image-info) | Show image details. |
-| <span id="cb-image-create"></span>[`cb image create`](/cua-bench/reference/cli/images#cb-image-create) | Deprecated: create an image from a platform. |
-| <span id="cb-image-delete"></span>[`cb image delete`](/cua-bench/reference/cli/images#cb-image-delete) | Deprecated: delete a stored image. |
-| <span id="cb-image-clone"></span>[`cb image clone`](/cua-bench/reference/cli/images#cb-image-clone) | Deprecated: clone a stored image. |
-| <span id="cb-image-shell"></span>[`cb image shell`](/cua-bench/reference/cli/images#cb-image-shell) | Deprecated: interactive shell into a stored image. |
-| <span id="cb-platform"></span>[`cb platform`](/cua-bench/reference/cli/images#cb-platform) | Show available platform configurations. |
-| <span id="cb-platform-list"></span>[`cb platform list`](/cua-bench/reference/cli/images#cb-platform-list) | List all available platforms. |
-| <span id="cb-platform-info"></span>[`cb platform info`](/cua-bench/reference/cli/images#cb-platform-info) | Show platform details. |
-
-## Global options
-
-`--help` prints help for any command; `--version` prints the version.
-
-## Exit codes
-
-| Code | Meaning |
-| --- | --- |
-| `0` | Success: every variant completed. |
-| `1` | Failure: a variant failed or was cancelled, or the command could not run. |
-| `2` | Usage error: an unknown command, flag or value. |
-| `130` | Interrupted (Ctrl-C); running variants are cancelled. |
diff --git a/docs/content/docs/cua-bench/reference/cli/meta.json b/docs/content/docs/cua-bench/reference/cli/meta.json
deleted file mode 100644
index 9c920d846a..0000000000
--- a/docs/content/docs/cua-bench/reference/cli/meta.json
+++ /dev/null
@@ -1,13 +0,0 @@
-{
- "title": "CLI",
- "pages": [
- "index",
- "run",
- "task",
- "dataset",
- "trace",
- "env",
- "agent",
- "images"
- ]
-}
diff --git a/docs/content/docs/cua-bench/reference/cli/task.mdx b/docs/content/docs/cua-bench/reference/cli/task.mdx
deleted file mode 100644
index dee69003b3..0000000000
--- a/docs/content/docs/cua-bench/reference/cli/task.mdx
+++ /dev/null
@@ -1,134 +0,0 @@
----
-title: "cb task"
-description: "Inspect, list, scaffold and generate tasks."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-bench
- Source: scripts/docs-generators/extract_cb_docs.py (cua_bench)
- Version: 0.3.1
-*/}
-
-| Command | Description |
-| --- | --- |
-| [`cb task info`](#cb-task-info) | Show detailed information about a task. |
-| [`cb task list`](#cb-task-list) | List tasks in a directory. |
-| [`cb task create`](#cb-task-create) | Scaffold a new task environment. |
-| [`cb task generate`](#cb-task-generate) | Generate a task from a prompt using Claude. |
-
-Every command also accepts the [global options](/cua-bench/reference/cli#global-options).
-
-<span id="cb-task"></span>
-
-Inspect and manage task environments.
-
-```text output
-cb task [COMMAND]
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cb-task"
-# List the tasks in a directory
-cb task list ./tasks
-
-# Inspect one task
-cb task info ./tasks/hello_file_env
-```
-
-## `cb task info`
-
-Show detailed information about a task.
-
-```text output
-cb task info <path>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<path>` | string | required | Path to task directory (containing main.py). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cb-task-info"
-# Inspect a task's variants and lifecycle functions
-cb task info ./tasks/hello_file_env
-```
-
-## `cb task list`
-
-List tasks in a directory.
-
-```text output
-cb task list [<path>]
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<path>` | string | `.` | Path to directory containing tasks (default: current directory). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cb-task-list"
-# List tasks here
-cb task list
-
-# List tasks in a directory
-cb task list ./tasks
-```
-
-## `cb task create`
-
-Scaffold a new task environment.
-
-```text output
-cb task create [<path>]
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<path>` | string | `.` | Target directory to create the task in (default: current directory). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cb-task-create"
-# Scaffold a task interactively under ./tasks
-cb task create ./tasks
-```
-
-## `cb task generate`
-
-Generate a task from a prompt using Claude.
-
-```text output
-cb task generate [OPTIONS] <prompt> [<output>]
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<prompt>` | string | required | Natural language description of the task to generate (e.g., "2048 game"). |
-| `<output>` | string | optional | Output directory (default: named after the prompt). |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cb-task-generate--no-interaction"></span>`--no-interaction` | boolean | `false` | Skip interactive prompts and run Claude non-interactively. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cb-task-generate"
-# Generate a task
-cb task generate '2048 game'
-
-# Generate into a directory without prompts
-cb task generate 'Sort a spreadsheet column' ./tasks/sort_column --no-interaction
-```
-
-## Exit codes
-
-| Code | Meaning |
-| --- | --- |
-| `0` | Success: every variant completed. |
-| `1` | Failure: a variant failed or was cancelled, or the command could not run. |
-| `2` | Usage error: an unknown command, flag or value. |
-| `130` | Interrupted (Ctrl-C); running variants are cancelled. |
diff --git a/docs/content/docs/cua-bench/reference/cli/trace.mdx b/docs/content/docs/cua-bench/reference/cli/trace.mdx
deleted file mode 100644
index b68f15acae..0000000000
--- a/docs/content/docs/cua-bench/reference/cli/trace.mdx
+++ /dev/null
@@ -1,93 +0,0 @@
----
-title: "cb trace"
-description: "View traces and agent trajectories."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-bench
- Source: scripts/docs-generators/extract_cb_docs.py (cua_bench)
- Version: 0.3.1
-*/}
-
-| Command | Description |
-| --- | --- |
-| [`cb trace view`](#cb-trace-view) | View a single trace in browser. |
-| [`cb trace traj`](#cb-trace-traj) | View agent trajectories from a run in cua.ai/trajectory-viewer. |
-
-Every command also accepts the [global options](/cua-bench/reference/cli#global-options).
-
-<span id="cb-trace"></span>
-
-View and analyze trace datasets.
-
-```text output
-cb trace [COMMAND]
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cb-trace"
-# Open a run's trace in the browser
-cb trace view 30c12572
-
-# Open a run's agent trajectories
-cb trace traj 30c12572
-```
-
-## `cb trace view`
-
-View a single trace in browser.
-
-```text output
-cb trace view <identifier>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<identifier>` | string | required | Run ID or session ID (e.g., "30c12572" or "task-30c12572-click-button-v0"). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cb-trace-view"
-# Open a run's trace
-cb trace view 30c12572
-
-# Open one session's trace
-cb trace view task-30c12572-click-button-v0
-```
-
-## `cb trace traj`
-
-View agent trajectories from a run in cua.ai/trajectory-viewer.
-
-```text output
-cb trace traj [OPTIONS] <identifier>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<identifier>` | string | required | Run ID (e.g., "30c12572"). |
-
-| Flag | Short | Type | Default | Description |
-| --- | --- | --- | --- | --- |
-| <span id="cb-trace-traj--port"></span>`--port` | `-p` | integer | `8090` | Local file server port (default: 8090). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cb-trace-traj"
-# Open a run's trajectories
-cb trace traj 30c12572
-
-# Serve the files on another port
-cb trace traj 30c12572 --port 9000
-```
-
-## Exit codes
-
-| Code | Meaning |
-| --- | --- |
-| `0` | Success: every variant completed. |
-| `1` | Failure: a variant failed or was cancelled, or the command could not run. |
-| `2` | Usage error: an unknown command, flag or value. |
-| `130` | Interrupted (Ctrl-C); running variants are cancelled. |
diff --git a/docs/content/docs/cua-bench/reference/index.mdx b/docs/content/docs/cua-bench/reference/index.mdx
index b8a1ba6348..2808499378 100644
--- a/docs/content/docs/cua-bench/reference/index.mdx
+++ b/docs/content/docs/cua-bench/reference/index.mdx
@@ -15,17 +15,17 @@ description: "Every cb command, the task module contract and the result files, g
| Command group | Description |
| --- | --- |
| [`cb`](/cua-bench/reference/cli) | Synopsis, global options, exit codes and every command. |
-| [`cb run`](/cua-bench/reference/cli/run) | Run a task or dataset with an agent or the oracle, run one interactively, and follow runs. |
-| [`cb task`](/cua-bench/reference/cli/task) | Inspect, list, scaffold and generate tasks. |
-| [`cb dataset`](/cua-bench/reference/cli/dataset) | List registry datasets and build training data from runs. |
-| [`cb trace`](/cua-bench/reference/cli/trace) | View traces and agent trajectories. |
-| [Sandboxes and account](/cua-bench/reference/cli/env) | Cloud pools and local sandboxes, sign-in, status and cleanup. |
-| [`cb agent`](/cua-bench/reference/cli/agent) | Scaffold custom agents. |
-| [Images and platforms](/cua-bench/reference/cli/images) | The canonical images and platform configurations. |
+| [`cb run`](/cua-bench/reference/cli#cb-run) | Run a task or dataset with an agent or the oracle, run one interactively, and follow runs. |
+| [`cb task`](/cua-bench/reference/cli#cb-task) | Inspect, list, scaffold and generate tasks. |
+| [`cb dataset`](/cua-bench/reference/cli#cb-dataset) | List registry datasets and build training data from runs. |
+| [`cb trace`](/cua-bench/reference/cli#cb-trace) | View traces and agent trajectories. |
+| [Sandboxes and account](/cua-bench/reference/cli#sandboxes-and-account) | Cloud pools and local sandboxes, sign-in, status and cleanup. |
+| [`cb agent`](/cua-bench/reference/cli#cb-agent) | Scaffold custom agents. |
+| [Images and platforms](/cua-bench/reference/cli#images-and-platforms) | The canonical images and platform configurations. |
## Schemas
| Schema | Description |
| --- | --- |
| [Task definition](/cua-bench/reference/task-definition) | cb.Task, setup_config, the lifecycle decorators, the session API and actions. |
-| [Results](/cua-bench/reference/results) | Every key of result.json and summary.json. |
+| [Results](/cua-bench/reference/task-definition#result-files) | Every key of result.json and summary.json. |
diff --git a/docs/content/docs/cua-bench/reference/meta.json b/docs/content/docs/cua-bench/reference/meta.json
index 6002f03495..8fd4fdee22 100644
--- a/docs/content/docs/cua-bench/reference/meta.json
+++ b/docs/content/docs/cua-bench/reference/meta.json
@@ -3,7 +3,6 @@
"pages": [
"index",
"cli",
- "task-definition",
- "results"
+ "task-definition"
]
}
diff --git a/docs/content/docs/cua-bench/reference/results.mdx b/docs/content/docs/cua-bench/reference/results.mdx
deleted file mode 100644
index 0085d5c12f..0000000000
--- a/docs/content/docs/cua-bench/reference/results.mdx
+++ /dev/null
@@ -1,130 +0,0 @@
----
-title: "Results"
-description: "The result.json and summary.json a run writes: every key, its type and meaning."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-bench
- Source: scripts/docs-generators/extract_cb_docs.py (cua_bench)
- Version: 0.3.1
-*/}
-
-A run writes one directory per variant and a `summary.json` next to them:
-
-```text output
-<output-dir>/
- summary.json
- <task>_v<variant>/ (with _a<attempt> for --attempts repeats)
- result.json
- run.log
- trajectory.json (ATIF-v1.8, screenshots under imgs/)
- task_<variant>_trace/ (a Hugging Face dataset of the trace events)
-```
-
-Both files carry `schema_version`; new keys are additive, and a rename or removal bumps the version.
-
-## `result.json`
-
-One variant's outcome: the cua-bench fields of its `result.json`.
-
-| Key | Type | Description |
-| --- | --- | --- |
-| `schema_version` | `int` | Layout version; a rename or removal bumps it, new keys do not. |
-| `session_id` | `str` | The session id (also the variant's log and trace key). |
-| `task` | `str` | Task directory name. |
-| `variant` | `int` | Variant index (`--variant-id`). |
-| `status` | `str` | `completed`, `failed` or `cancelled`. |
-| `reward` | `float \| null` | The mean of the evaluation's numbers (`true` counts as 1), or `null` when evaluation did not run. |
-| `evaluation` | `any` | What `@cb.evaluate_task` returned (commonly a list of floats). |
-| `error` | `str \| null` | The error message when the variant failed. |
-| `duration_s` | `float` | Wall time of the variant in seconds. |
-| `on` | `str` | Where it ran: `local` or `cloud`. |
-| `backend` | `str` | What ran it, `<location>-<engine>` (`local-gvisor`, `local-qemu`, `cloud-gvisor`, `cloud-kubevirt`, `cloud-pool:<name>`). |
-| `image` | `str \| null` | The image as the task or `--image` named it. |
-| `pool` | `str \| null` | The pool that served the sandbox (unused: always `None` since Cua Cloud ended). |
-| `output_dir` | `str` | The variant's output directory. |
-| `extra` | `dict` | Extra values the task or agent reported. |
-| `kind` | `str \| null` | `container` or `vm`. |
-| `runtime` | `str \| null` | The engine (`gvisor`, `runc`, `qemu`, `lume`, `kubevirt`) when one was chosen; `None`: the SDK picked. |
-| `image_ref` | `str \| null` | The resolved image reference. |
-| `image_variant` | `str \| null` | The image variant that ran: `rootfs`, `containerdisk` or `lume`. |
-| `image_digest` | `str \| null` | The pinned `repo@sha256:...` when the SDK reports it. |
-| `arch` | `str \| null` | Guest architecture, when known. |
-| `attempt` | `int` | The `--attempts` repeat index (0 for the first). |
-| `retries` | `int` | How many infrastructure retries (`--retries`) the variant took. |
-| `sandbox` | `str \| null` | The sandbox's qualified ref (`local:<name>`, `cloud:<name>`), when known. |
-| `id` | `str` | A random id for this trial. |
-| `task_name` | `str` | The task directory name. |
-| `trial_name` | `str` | `<task>_v<variant>`, with `_a<attempt>` for repeats. |
-| `trial_uri` | `str \| null` | `file://` URI of the variant's output directory. |
-| `source` | `str` | Always `cua-bench`. |
-| `agent_info` | `dict` | The agent label, version and model (`{name, provider}`). |
-| `verifier_result` | `dict \| null` | `{"rewards": {"reward": <float>, ...}}` (numeric evaluation keys included), or `null`. |
-| `exception_info` | `dict \| null` | Exception type, message, traceback and time when the variant raised, else `null`. |
-| `started_at` | `str \| null` | When the trial started. |
-| `finished_at` | `str \| null` | When the trial finished. |
-| `environment_setup` | `Span \| null` | Sandbox start and task setup. |
-| `agent_setup` | `null` | Always `null` (agents run in the cb process). |
-| `agent_execution` | `Span \| null` | The agent's (or the oracle's) run. |
-| `verifier` | `Span \| null` | The evaluation. |
-
-Phase spans (`environment_setup`, `agent_execution`, `verifier`) are `started_at` and `finished_at` timestamps (ISO 8601, UTC).
-
-## `summary.json`
-
-`summary.json`: the run's totals, written next to each variant's directory.
-
-| Key | Type | Description |
-| --- | --- | --- |
-| `schema_version` | `int` | Layout version; a rename or removal bumps it, new keys do not. |
-| `total` | `int` | Variants run. |
-| `completed` | `int` | Variants that completed. |
-| `failed` | `int` | Variants that failed or were cancelled. |
-| `avg_reward` | `float \| null` | Mean reward over variants with a reward, or `null`. |
-| `results` | `list[SummaryResult]` | One row per variant (`SummaryResult`). |
-| `n_total_trials` | `int` | The number of trials (Harbor), equal to `total`. |
-| `stats` | `SummaryStats` | Harbor-compatible statistics (`SummaryStats`). |
-| `pass_at_k` | `dict \| null` | `{"<k>": <pass@k>}` with `--attempts` above 1 (binary rewards, unbiased estimator), else `null`. |
-| `targets` | `list[SummaryTarget]` | Where the variants ran (`SummaryTarget`). |
-
-### `results[]`
-
-One row of `summary.json` `results`: a variant's outcome.
-
-| Key | Type | Description |
-| --- | --- | --- |
-| `results[].task` | `str` | Task directory name. |
-| `results[].variant` | `int` | Variant index (`--variant-id`). |
-| `results[].status` | `str` | `completed`, `failed` or `cancelled`. |
-| `results[].reward` | `float \| null` | The mean of the evaluation's numbers (`true` counts as 1), or `null` when evaluation did not run. |
-| `results[].pool` | `str \| null` | The pool that served the sandbox (unused: always `None` since Cua Cloud ended). |
-| `results[].duration_s` | `float` | Wall time of the variant in seconds. |
-| `results[].error` | `str \| null` | The error message when the variant failed. |
-| `results[].kind` | `str \| null` | `container` or `vm`. |
-| `results[].runtime` | `str \| null` | The engine (gvisor, runc, qemu, lume, kubevirt) when one was chosen, else `null` (the SDK picked). |
-| `results[].image_variant` | `str \| null` | The image variant that ran: `rootfs`, `containerdisk` or `lume`. |
-| `results[].image_digest` | `str \| null` | The pinned `repo@sha256:...` when the SDK reports it. |
-| `results[].attempt` | `int` | The `--attempts` repeat index (0 for the first). |
-| `results[].retries` | `int` | How many infrastructure retries (`--retries`) the variant took. |
-
-### `stats`
-
-| Key | Type | Description |
-| --- | --- | --- |
-| `stats.n_completed` | `int` | Variants that completed. |
-| `stats.n_errored` | `int` | Variants with no reward that did not complete (the run broke). |
-| `stats.n_retries` | `int` | Infrastructure retries across the run. |
-
-### `targets[]`
-
-Where variants ran: one row per (on, kind, runtime, image variant, image).
-
-| Key | Type | Description |
-| --- | --- | --- |
-| `targets[].on` | `str` | Where it ran: `local` or `cloud`. |
-| `targets[].kind` | `str \| null` | `container` or `vm`. |
-| `targets[].runtime` | `str \| null` | The engine (`gvisor`, `runc`, `qemu`, `lume`, `kubevirt`) when one was chosen; `None`: the SDK picked. |
-| `targets[].image_variant` | `str \| null` | The image variant that ran: `rootfs`, `containerdisk` or `lume`. |
-| `targets[].image` | `str \| null` | The pinned digest when known, else the image reference. |
-| `targets[].count` | `int` | Variants that ran there. |
diff --git a/docs/content/docs/cua-bench/reference/task-definition.mdx b/docs/content/docs/cua-bench/reference/task-definition.mdx
index 9cf52665e6..2f7ecface0 100644
--- a/docs/content/docs/cua-bench/reference/task-definition.mdx
+++ b/docs/content/docs/cua-bench/reference/task-definition.mdx
@@ -1,6 +1,6 @@
---
-title: "Task definition"
-description: "The task module contract: cb.Task, setup_config, the lifecycle decorators, the session API and actions."
+title: "Tasks and results"
+description: "The task module contract (cb.Task, setup_config, the lifecycle decorators, the session API and actions) and the result.json and summary.json a run writes."
---
{/*
@@ -168,3 +168,124 @@ async def evaluate(task_cfg, session: cb.DesktopSession) -> list[float]:
answer = (await session.read_file("/tmp/cb_answer.txt")).strip()
return [1.0 if answer == task_cfg.metadata["word"] else 0.0]
```
+
+## Result files
+
+A run writes one directory per variant and a `summary.json` next to them:
+
+```text output
+<output-dir>/
+ summary.json
+ <task>_v<variant>/ (with _a<attempt> for --attempts repeats)
+ result.json
+ run.log
+ trajectory.json (ATIF-v1.8, screenshots under imgs/)
+ task_<variant>_trace/ (a Hugging Face dataset of the trace events)
+```
+
+Both files carry `schema_version`; new keys are additive, and a rename or removal bumps the version.
+
+### `result.json`
+
+One variant's outcome: the cua-bench fields of its `result.json`.
+
+| Key | Type | Description |
+| --- | --- | --- |
+| `schema_version` | `int` | Layout version; a rename or removal bumps it, new keys do not. |
+| `session_id` | `str` | The session id (also the variant's log and trace key). |
+| `task` | `str` | Task directory name. |
+| `variant` | `int` | Variant index (`--variant-id`). |
+| `status` | `str` | `completed`, `failed` or `cancelled`. |
+| `reward` | `float \| null` | The mean of the evaluation's numbers (`true` counts as 1), or `null` when evaluation did not run. |
+| `evaluation` | `any` | What `@cb.evaluate_task` returned (commonly a list of floats). |
+| `error` | `str \| null` | The error message when the variant failed. |
+| `duration_s` | `float` | Wall time of the variant in seconds. |
+| `on` | `str` | Where it ran: `local` or `cloud`. |
+| `backend` | `str` | What ran it, `<location>-<engine>` (`local-gvisor`, `local-qemu`, `cloud-gvisor`, `cloud-kubevirt`, `cloud-pool:<name>`). |
+| `image` | `str \| null` | The image as the task or `--image` named it. |
+| `pool` | `str \| null` | The pool that served the sandbox (unused: always `None` since Cua Cloud ended). |
+| `output_dir` | `str` | The variant's output directory. |
+| `extra` | `dict` | Extra values the task or agent reported. |
+| `kind` | `str \| null` | `container` or `vm`. |
+| `runtime` | `str \| null` | The engine (`gvisor`, `runc`, `qemu`, `lume`, `kubevirt`) when one was chosen; `None`: the SDK picked. |
+| `image_ref` | `str \| null` | The resolved image reference. |
+| `image_variant` | `str \| null` | The image variant that ran: `rootfs`, `containerdisk` or `lume`. |
+| `image_digest` | `str \| null` | The pinned `repo@sha256:...` when the SDK reports it. |
+| `arch` | `str \| null` | Guest architecture, when known. |
+| `attempt` | `int` | The `--attempts` repeat index (0 for the first). |
+| `retries` | `int` | How many infrastructure retries (`--retries`) the variant took. |
+| `sandbox` | `str \| null` | The sandbox's qualified ref (`local:<name>`, `cloud:<name>`), when known. |
+| `id` | `str` | A random id for this trial. |
+| `task_name` | `str` | The task directory name. |
+| `trial_name` | `str` | `<task>_v<variant>`, with `_a<attempt>` for repeats. |
+| `trial_uri` | `str \| null` | `file://` URI of the variant's output directory. |
+| `source` | `str` | Always `cua-bench`. |
+| `agent_info` | `dict` | The agent label, version and model (`{name, provider}`). |
+| `verifier_result` | `dict \| null` | `{"rewards": {"reward": <float>, ...}}` (numeric evaluation keys included), or `null`. |
+| `exception_info` | `dict \| null` | Exception type, message, traceback and time when the variant raised, else `null`. |
+| `started_at` | `str \| null` | When the trial started. |
+| `finished_at` | `str \| null` | When the trial finished. |
+| `environment_setup` | `Span \| null` | Sandbox start and task setup. |
+| `agent_setup` | `null` | Always `null` (agents run in the cb process). |
+| `agent_execution` | `Span \| null` | The agent's (or the oracle's) run. |
+| `verifier` | `Span \| null` | The evaluation. |
+
+Phase spans (`environment_setup`, `agent_execution`, `verifier`) are `started_at` and `finished_at` timestamps (ISO 8601, UTC).
+
+### `summary.json`
+
+`summary.json`: the run's totals, written next to each variant's directory.
+
+| Key | Type | Description |
+| --- | --- | --- |
+| `schema_version` | `int` | Layout version; a rename or removal bumps it, new keys do not. |
+| `total` | `int` | Variants run. |
+| `completed` | `int` | Variants that completed. |
+| `failed` | `int` | Variants that failed or were cancelled. |
+| `avg_reward` | `float \| null` | Mean reward over variants with a reward, or `null`. |
+| `results` | `list[SummaryResult]` | One row per variant (`SummaryResult`). |
+| `n_total_trials` | `int` | The number of trials (Harbor), equal to `total`. |
+| `stats` | `SummaryStats` | Harbor-compatible statistics (`SummaryStats`). |
+| `pass_at_k` | `dict \| null` | `{"<k>": <pass@k>}` with `--attempts` above 1 (binary rewards, unbiased estimator), else `null`. |
+| `targets` | `list[SummaryTarget]` | Where the variants ran (`SummaryTarget`). |
+
+#### `results[]`
+
+One row of `summary.json` `results`: a variant's outcome.
+
+| Key | Type | Description |
+| --- | --- | --- |
+| `results[].task` | `str` | Task directory name. |
+| `results[].variant` | `int` | Variant index (`--variant-id`). |
+| `results[].status` | `str` | `completed`, `failed` or `cancelled`. |
+| `results[].reward` | `float \| null` | The mean of the evaluation's numbers (`true` counts as 1), or `null` when evaluation did not run. |
+| `results[].pool` | `str \| null` | The pool that served the sandbox (unused: always `None` since Cua Cloud ended). |
+| `results[].duration_s` | `float` | Wall time of the variant in seconds. |
+| `results[].error` | `str \| null` | The error message when the variant failed. |
+| `results[].kind` | `str \| null` | `container` or `vm`. |
+| `results[].runtime` | `str \| null` | The engine (gvisor, runc, qemu, lume, kubevirt) when one was chosen, else `null` (the SDK picked). |
+| `results[].image_variant` | `str \| null` | The image variant that ran: `rootfs`, `containerdisk` or `lume`. |
+| `results[].image_digest` | `str \| null` | The pinned `repo@sha256:...` when the SDK reports it. |
+| `results[].attempt` | `int` | The `--attempts` repeat index (0 for the first). |
+| `results[].retries` | `int` | How many infrastructure retries (`--retries`) the variant took. |
+
+#### `stats`
+
+| Key | Type | Description |
+| --- | --- | --- |
+| `stats.n_completed` | `int` | Variants that completed. |
+| `stats.n_errored` | `int` | Variants with no reward that did not complete (the run broke). |
+| `stats.n_retries` | `int` | Infrastructure retries across the run. |
+
+#### `targets[]`
+
+Where variants ran: one row per (on, kind, runtime, image variant, image).
+
+| Key | Type | Description |
+| --- | --- | --- |
+| `targets[].on` | `str` | Where it ran: `local` or `cloud`. |
+| `targets[].kind` | `str \| null` | `container` or `vm`. |
+| `targets[].runtime` | `str \| null` | The engine (`gvisor`, `runc`, `qemu`, `lume`, `kubevirt`) when one was chosen; `None`: the SDK picked. |
+| `targets[].image_variant` | `str \| null` | The image variant that ran: `rootfs`, `containerdisk` or `lume`. |
+| `targets[].image` | `str \| null` | The pinned digest when known, else the image reference. |
+| `targets[].count` | `int` | Variants that ran there. |
diff --git a/docs/content/docs/cua-cli/reference/cli/account-and-setup.mdx b/docs/content/docs/cua-cli/reference/cli/account-and-setup.mdx
new file mode 100644
index 0000000000..8f0788e0ec
--- /dev/null
+++ b/docs/content/docs/cua-cli/reference/cli/account-and-setup.mdx
@@ -0,0 +1,574 @@
+---
+title: "Account and setup"
+description: "Sign in and out, user defaults, the cua daemon, health checks and usage telemetry."
+---
+
+{/*
+ AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
+ Generated by: pnpm --dir docs docs:generate:cua-cli
+ Source: cua dump-docs --type cli
+ Version: 0.5.0
+*/}
+
+| Command | Description |
+| --- | --- |
+| [`cua auth`](#cua-auth) | Log in to Cua and manage the signed-in session. |
+| [`cua auth login`](#cua-auth-login) | Log in (browser sign-in; `--remote` for a device code), then offer to set up your AI coding agents. |
+| [`cua auth logout`](#cua-auth-logout) | Revoke and remove the local session. |
+| [`cua auth status`](#cua-auth-status) | Local session state (no network). |
+| [`cua auth whoami`](#cua-auth-whoami) | Who is signed in: the account, its plan and its teams. |
+| [`cua auth provider`](#cua-auth-provider) | Keys of the contrib sandbox providers (`--on e2b`, `--on daytona`, `--on modal`). |
+| [`cua auth provider ls`](#cua-auth-provider-ls) | Providers, whether this build has them and where their keys come from (never the values). |
+| [`cua auth provider set`](#cua-auth-provider-set) | Store a provider key, read from stdin (no echo on a terminal). |
+| [`cua auth provider rm`](#cua-auth-provider-rm) | Remove a provider's stored keys. |
+| [`cua config`](#cua-config) | User defaults (~/.cua/config.toml): where sandboxes run when --on is not given (default.on), the default kind and runtime. |
+| [`cua config list`](#cua-config-list) | Every setting: its effective value and where it comes from (env, config or default). |
+| [`cua config get`](#cua-config-get) | One setting's effective value. |
+| [`cua config set`](#cua-config-set) | Write a setting to the config file. |
+| [`cua config unset`](#cua-config-unset) | Remove a setting from the config file (the environment variable or the built-in default applies again). |
+| [`cua config path`](#cua-config-path) | The config file's path. |
+| [`cua daemon`](#cua-daemon) | The cua daemon. |
+| [`cua daemon start`](#cua-daemon-start) | Start the daemon (in the background unless --foreground). |
+| [`cua daemon stop`](#cua-daemon-stop) | Stop the daemon. |
+| [`cua daemon status`](#cua-daemon-status) | Show daemon status. |
+| [`cua daemon mcp`](#cua-daemon-mcp) | Stdio MCP server backed by the daemon (started if needed): the Spaces contract tools plus the sandbox/computer/skills tools (same server as `cua mcp`). |
+| [`cua doctor`](#cua-doctor) | Check the host, an image and a sandbox's guest in one report (`cua doctor [REF]`), or eval parity between two variants (`cua doctor parity A B`). |
+| [`cua doctor parity`](#cua-doctor-parity) | Eval parity between two variants of one image (rootfs vs containerDisk): doctor on both, fidelity diff, task outcomes. |
+| [`cua telemetry`](#cua-telemetry) | Anonymous usage telemetry (status, on, off, show-last, reset-id, schema). |
+| [`cua telemetry status`](#cua-telemetry-status) | Whether telemetry is on, why, and the exact properties every event carries. |
+| [`cua telemetry on`](#cua-telemetry-on) | Turn usage telemetry on (writes [telemetry] enabled = \"on\" to ~/.cua/config.toml). |
+| [`cua telemetry off`](#cua-telemetry-off) | Turn usage telemetry off (same as `cua config set telemetry off`). |
+| [`cua telemetry show-last`](#cua-telemetry-show-last) | Print the last events this machine queued or sent, exactly as sent. |
+| [`cua telemetry reset-id`](#cua-telemetry-reset-id) | Delete the anonymous install id and salt (new ones are created on the next event). |
+| [`cua telemetry schema`](#cua-telemetry-schema) | Every event and property that may be sent, with its allowed values. |
+
+Every command also accepts the [global options](/cua-cli/reference/cli#global-options).
+
+## `cua auth`
+
+Log in to Cua and manage the signed-in session.
+
+```text output
+cua auth [OPTIONS] <COMMAND>
+```
+
+### `cua auth login`
+
+Log in (browser sign-in; `--remote` for a device code), then offer to set up your AI coding agents.
+
+```text output
+cua auth login [OPTIONS]
+```
+
+| Flag | Short | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| <span id="cua-auth-login--agents"></span>`--agents` | | string | | Agents: `all` (installed), `none`, or ids such as `claude,codex,hermes` (`cua agents detect` lists every supported agent). |
+| <span id="cua-auth-login--mcp-command"></span>`--mcp-command` | | string | | Command agents launch for the MCP server (default: the `cua` on PATH, else this binary). |
+| <span id="cua-auth-login--no-browser"></span>`--no-browser` | | boolean | `false` | Do not open a browser; print the URL. |
+| <span id="cua-auth-login--remote"></span>`--remote` | | boolean | `false` | Sign in from another device with a code (for SSH sessions and machines without a browser). |
+| <span id="cua-auth-login--no-onboarding"></span>`--no-onboarding` | | boolean | `false` | Skip the agent onboarding prompt. |
+| <span id="cua-auth-login--skills-only"></span>`--skills-only` | | boolean | `false` | Only install skills. Alias: `--no-mcp`. |
+| <span id="cua-auth-login--mcp-only"></span>`--mcp-only` | | boolean | `false` | Only configure the MCP server. Alias: `--no-skills`. |
+| <span id="cua-auth-login--yes"></span>`--yes` | `-y` | boolean | `false` | Answer yes to every prompt. |
+| <span id="cua-auth-login--force"></span>`--force` | | boolean | `false` | Replace skill folders cua did not write (the old one is backed up). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-auth-login"
+# Sign in with the browser
+cua auth login
+
+# Sign in over SSH with a device code
+cua auth login --remote
+
+# Sign in and set up Claude Code without prompts
+cua auth login --agents claude -y
+```
+
+### `cua auth logout`
+
+Revoke and remove the local session.
+
+```text output
+cua auth logout [OPTIONS]
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-auth-logout"
+cua auth logout
+```
+
+### `cua auth status`
+
+Local session state (no network).
+
+```text output
+cua auth status [OPTIONS]
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-auth-status"
+cua auth status
+cua auth status --json
+```
+
+### `cua auth whoami`
+
+Who is signed in: the account, its plan and its teams.
+
+```text output
+cua auth whoami [OPTIONS]
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-auth-whoami"
+cua auth whoami
+cua auth whoami --json
+```
+
+### `cua auth provider`
+
+Keys of the contrib sandbox providers (`--on e2b`, `--on daytona`, `--on modal`).
+
+```text output
+cua auth provider [OPTIONS] <COMMAND>
+```
+
+#### `cua auth provider ls`
+
+Providers, whether this build has them and where their keys come from (never the values).
+
+```text output
+cua auth provider ls [OPTIONS]
+```
+
+Alias: `cua auth provider list`.
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-auth-provider-ls"
+cua auth provider ls
+cua auth provider ls --json
+```
+
+#### `cua auth provider set`
+
+Store a provider key, read from stdin (no echo on a terminal). An environment variable of the same name wins over the stored key.
+
+```text output
+cua auth provider set [OPTIONS] <NAME>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<NAME>` | string | required | Provider (`e2b`, `daytona`, `modal`). |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-auth-provider-set--var"></span>`--var` | string | | Only this variable (for example MODAL_TOKEN_SECRET). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-auth-provider-set"
+# Prompt for E2B_API_KEY (no echo)
+cua auth provider set e2b
+
+# One variable only
+cua auth provider set daytona --var DAYTONA_API_KEY
+```
+
+#### `cua auth provider rm`
+
+Remove a provider's stored keys.
+
+```text output
+cua auth provider rm [OPTIONS] <NAME>
+```
+
+Alias: `cua auth provider delete`.
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<NAME>` | string | required | Provider. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-auth-provider-rm"
+cua auth provider rm e2b
+```
+
+## `cua config`
+
+User defaults (~/.cua/config.toml): where sandboxes run when --on is not given (default.on), the default kind and runtime.
+
+```text output
+cua config [OPTIONS] <COMMAND>
+```
+
+### `cua config list`
+
+Every setting: its effective value and where it comes from (env, config or default).
+
+```text output
+cua config list [OPTIONS]
+```
+
+Alias: `cua config ls`.
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-config-list"
+cua config list
+cua config list --json
+```
+
+### `cua config get`
+
+One setting's effective value.
+
+```text output
+cua config get [OPTIONS] <KEY>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<KEY>` | string | required | Setting (`default.on`, `default.kind`, `default.runtime`). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-config-get"
+cua config get default.on
+```
+
+### `cua config set`
+
+Write a setting to the config file.
+
+```text output
+cua config set [OPTIONS] <KEY> <VALUE>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<KEY>` | string | required | Setting. |
+| `<VALUE>` | string | required | Value (checked: `default.on` takes local, aws, gcp, modal or a provider). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-config-set"
+# Create sandboxes in your AWS account unless --on says otherwise
+cua config set default.on aws
+
+# Back to this machine
+cua config set default.on local
+
+# Prefer VMs when the image offers both
+cua config set default.kind vm
+```
+
+### `cua config unset`
+
+Remove a setting from the config file (the environment variable or the built-in default applies again).
+
+```text output
+cua config unset [OPTIONS] <KEY>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<KEY>` | string | required | Setting. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-config-unset"
+cua config unset default.on
+```
+
+### `cua config path`
+
+The config file's path.
+
+```text output
+cua config path [OPTIONS]
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-config-path"
+cua config path
+```
+
+## `cua daemon`
+
+The cua daemon.
+
+```text output
+cua daemon [OPTIONS] <COMMAND>
+```
+
+### `cua daemon start`
+
+Start the daemon (in the background unless --foreground).
+
+```text output
+cua daemon start [OPTIONS]
+```
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-daemon-start--socket"></span>`--socket` | path | | Unix socket (default ~/.cua/cua.sock). |
+| <span id="cua-daemon-start--loopback"></span>`--loopback` | string | `127.0.0.1:0` | Loopback address (default 127.0.0.1:0; "off" disables). |
+| <span id="cua-daemon-start--foreground"></span>`--foreground` | boolean | `false` | Stay in the foreground. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-daemon-start"
+cua daemon start
+
+# In the foreground, for a service manager
+cua daemon start --foreground
+```
+
+### `cua daemon stop`
+
+Stop the daemon.
+
+```text output
+cua daemon stop [OPTIONS]
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-daemon-stop"
+cua daemon stop
+```
+
+### `cua daemon status`
+
+Show daemon status.
+
+```text output
+cua daemon status [OPTIONS]
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-daemon-status"
+cua daemon status
+```
+
+### `cua daemon mcp`
+
+Stdio MCP server backed by the daemon (started if needed): the Spaces contract tools plus the sandbox/computer/skills tools (same server as `cua mcp`).
+
+```text output
+cua daemon mcp [OPTIONS]
+```
+
+| Flag | Type | Default | Env var | Description |
+| --- | --- | --- | --- | --- |
+| <span id="cua-daemon-mcp--permissions"></span>`--permissions` | string | | `CUA_MCP_PERMISSIONS` | Comma-separated permissions or groups (default: all). |
+| <span id="cua-daemon-mcp--sandbox"></span>`--sandbox` | string | | `CUA_SANDBOX` | Default sandbox for computer tools. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-daemon-mcp"
+cua daemon mcp
+cua daemon mcp --permissions spaces:all
+```
+
+## `cua doctor`
+
+Check the host, an image and a sandbox's guest in one report (`cua doctor [REF]`), or eval parity between two variants (`cua doctor parity A B`).
+
+```text output
+cua doctor [OPTIONS] [TARGET]
+ cua doctor <COMMAND>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<TARGET>` | string | optional | Sandbox to check: `local:<name>`, `direct:<host:port>`, a bare name, or a spacesd URL. Omit for the host checks only. |
+
+| Flag | Type | Default | Env var | Description |
+| --- | --- | --- | --- | --- |
+| <span id="cua-doctor--image"></span>`--image` | string | | | Image to resolve for the image checks (default: the sandbox's). |
+| <span id="cua-doctor--arch"></span>`--arch` | string | | | Architecture to resolve the image for (default: the sandbox's, else this host's). |
+| <span id="cua-doctor--format"></span>`--format` | `human` \| `json` \| `junit` | `human` | | Output format (`--json` selects json). |
+| <span id="cua-doctor--effects"></span>`--effects` | `none` \| `virtual` | `none` | | Which guest checks may act on the guest. |
+| <span id="cua-doctor--only"></span>`--only` | string | | | Guest check ids or groups to run (comma separated). Repeatable. |
+| <span id="cua-doctor--skip"></span>`--skip` | string | | | Guest check ids or groups to skip. Repeatable. |
+| <span id="cua-doctor--timeout"></span>`--timeout` | integer | `240` | | Guest budget in seconds. |
+| <span id="cua-doctor--token"></span>`--token` | string | | `CUA_ENV_TOKEN` | spacesd token for a URL target (default: CUA_ENV_TOKEN). |
+| <span id="cua-doctor--shim"></span>`--shim` | string | | | Check an image without cua-spacesd through its own API instead: `computer-server=<url>`, `osworld=<url>` or `mcp=<url>`. |
+| <span id="cua-doctor--expect-manifest"></span>`--expect-manifest` | path | | | The image's claims (manifest JSON), for the shim or to override the guest's own. |
+| <span id="cua-doctor--out"></span>`--out` | path | | | Also write the JSON report here. |
+| <span id="cua-doctor--junit"></span>`--junit` | path | | | Also write JUnit XML here. |
+| <span id="cua-doctor--expect"></span>`--expect` | string | | | Fail unless the build running in the guest is the expected one: COMPONENT=WANT with WANT `sha256:<hex>` (the executable), `git:<sha>` or a version (repeatable). Components: cua-spacesd, cua-driver, or an overlay name. `cua sb create --overlay` prints the sha256 to pass. |
+| <span id="cua-doctor--strict"></span>`--strict` | boolean | `false` | | Fail on warnings and on required checks that were skipped. |
+| <span id="cua-doctor--no-host"></span>`--no-host` | boolean | `false` | | Skip the host checks. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-doctor"
+# Host checks only
+cua doctor
+
+# Host, image and guest checks for the sandbox dev
+cua doctor dev
+
+# CI: fail on warnings, write JUnit XML
+cua doctor local:dev --strict --junit doctor.xml
+```
+
+### `cua doctor parity`
+
+Eval parity between two variants of one image (rootfs vs containerDisk): doctor on both, fidelity diff, task outcomes.
+
+```text output
+cua doctor parity [OPTIONS] <A> <B>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<A>` | string | required | First variant (a sandbox ref or a spacesd URL). |
+| `<B>` | string | required | Second variant. |
+
+| Flag | Type | Default | Env var | Description |
+| --- | --- | --- | --- | --- |
+| <span id="cua-doctor-parity--token"></span>`--token` | string | | `CUA_ENV_TOKEN` | Token for URL targets (both), default CUA_ENV_TOKEN. |
+| <span id="cua-doctor-parity--token-b"></span>`--token-b` | string | | | Token for B when it differs from A's. |
+| <span id="cua-doctor-parity--tasks"></span>`--tasks` | string | `builtin:form,builtin:file` | | Tasks (`builtin:form`, `builtin:file`), comma separated. Repeatable. |
+| <span id="cua-doctor-parity--allow-diff"></span>`--allow-diff` | string | | | Extra fidelity keys allowed to differ. Repeatable. |
+| <span id="cua-doctor-parity--out"></span>`--out` | path | | | Write parity.json here. |
+| <span id="cua-doctor-parity--timeout"></span>`--timeout` | integer | `240` | | Doctor budget per variant, seconds. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-doctor-parity"
+cua doctor parity local:linux-rootfs local:linux-vm
+cua doctor parity local:linux-rootfs local:linux-vm --out parity.json
+```
+
+## `cua telemetry`
+
+Anonymous usage telemetry (status, on, off, show-last, reset-id, schema). What is sent: https://cua.ai/docs/cua-sdk/concepts/telemetry.
+
+```text output
+cua telemetry [OPTIONS] <COMMAND>
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-telemetry"
+cua telemetry status
+cua telemetry off
+cua telemetry show-last
+```
+
+### `cua telemetry status`
+
+Whether telemetry is on, why, and the exact properties every event carries.
+
+```text output
+cua telemetry status [OPTIONS]
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-telemetry-status"
+cua telemetry status
+cua telemetry status --json
+```
+
+### `cua telemetry on`
+
+Turn usage telemetry on (writes [telemetry] enabled = \"on\" to ~/.cua/config.toml).
+
+```text output
+cua telemetry on [OPTIONS]
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-telemetry-on"
+cua telemetry on
+```
+
+### `cua telemetry off`
+
+Turn usage telemetry off (same as `cua config set telemetry off`).
+
+```text output
+cua telemetry off [OPTIONS]
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-telemetry-off"
+cua telemetry off
+```
+
+### `cua telemetry show-last`
+
+Print the last events this machine queued or sent, exactly as sent.
+
+```text output
+cua telemetry show-last [OPTIONS]
+```
+
+| Flag | Short | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| <span id="cua-telemetry-show-last--limit"></span>`--limit` | `-n` | integer | `20` | How many. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-telemetry-show-last"
+cua telemetry show-last
+cua telemetry show-last -n 5 --json
+```
+
+### `cua telemetry reset-id`
+
+Delete the anonymous install id and salt (new ones are created on the next event).
+
+```text output
+cua telemetry reset-id [OPTIONS]
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-telemetry-reset-id"
+cua telemetry reset-id
+```
+
+### `cua telemetry schema`
+
+Every event and property that may be sent, with its allowed values.
+
+```text output
+cua telemetry schema [OPTIONS]
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-telemetry-schema"
+cua telemetry schema --json
+```
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| `0` | Success. |
+| `1` | Failure, or `cua do` reported an error. |
+| `2` | Invalid argument, or an ambiguous sandbox name (qualify it: `local:NAME`). |
+| `3` | Not found: sandbox, window, skill or image (or an image not published yet). |
+| `4` | Not supported, or not configured (for example no provider credentials). |
+| `5` | No cua-spacesd answered, or a transport failure. |
+| `6` | Unauthenticated or permission denied (by Cua or your cloud account). |
+| `7` | Not enough free disk space (see `cua cache`). |
+| `130` | Cancelled (Ctrl-C during a create): what it made was removed. |
diff --git a/docs/content/docs/cua-cli/reference/cli/agent.mdx b/docs/content/docs/cua-cli/reference/cli/agent.mdx
deleted file mode 100644
index 201ae4e8d1..0000000000
--- a/docs/content/docs/cua-cli/reference/cli/agent.mdx
+++ /dev/null
@@ -1,716 +0,0 @@
----
-title: "cua agent"
-description: "Run coding agents (Claude Code, Codex, Gemini CLI, ...) inside a sandbox and follow, continue or stop them."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-cli
- Source: cua dump-docs --type cli
- Version: 0.5.0
-*/}
-
-| Command | Description |
-| --- | --- |
-| [`cua agent run`](#cua-agent-run) | Start a coding agent in a sandbox (returns at once unless --follow). |
-| [`cua agent ls`](#cua-agent-ls) | List runs in a sandbox. |
-| [`cua agent logs`](#cua-agent-logs) | Print a run's normalized events (--follow to stream). |
-| [`cua agent send`](#cua-agent-send) | Send a follow-up (queued while a turn runs). |
-| [`cua agent interrupt`](#cua-agent-interrupt) | Cancel the turn in flight (the session stays open). |
-| [`cua agent stop`](#cua-agent-stop) | Stop a run and verify it is gone. |
-| [`cua agent status`](#cua-agent-status) | A run's status and last result. |
-| [`cua agent rm`](#cua-agent-rm) | Stop a run and delete its record (secrets included). |
-| [`cua agent ensure`](#cua-agent-ensure) | Install harnesses or apps now (`claude-code`, `blender`, ...). |
-| [`cua agent harnesses`](#cua-agent-harnesses) | The harnesses: readiness, installs, key variables, limits. |
-| [`cua agent keys`](#cua-agent-keys) | The provider keys agents get, kept in the Keychain by the Cua daemon (Cua Spaces → Settings → Agents). |
-| [`cua agent keys ls`](#cua-agent-keys-ls) | List the saved keys (never their values). |
-| [`cua agent keys set`](#cua-agent-keys-set) | Add or replace a key, read from stdin. |
-| [`cua agent keys rm`](#cua-agent-keys-rm) | Remove the key a run gets as ENV. |
-| [`cua agent create`](#cua-agent-create) | Create a persistent agent: a named harness whose memory lives in the Cua Volume (agents/NAME/) and outlives its Space. |
-| [`cua agent persistent`](#cua-agent-persistent) | List persistent agents. |
-| [`cua agent tell`](#cua-agent-tell) | Give a persistent agent a turn (starts a run with its home restored, or follows up on its idle run). |
-| [`cua agent save`](#cua-agent-save) | Save a persistent agent's home into the drive now. |
-| [`cua agent pause`](#cua-agent-pause) | Pause a persistent agent: its run, its routines, and its Space (suspended when local; a cloud Space is released after the home is saved). |
-| [`cua agent resume`](#cua-agent-resume) | Resume a paused persistent agent. |
-| [`cua agent forget`](#cua-agent-forget) | Forget a persistent agent (its home stays in the drive). |
-| [`cua agent routine`](#cua-agent-routine) | A persistent agent's routines, fired by the daemon with or without the app open. |
-| [`cua agent routine add`](#cua-agent-routine-add) | Add a routine (give one of --every, --daily, --weekly). |
-| [`cua agent routine ls`](#cua-agent-routine-ls) | List routines. |
-| [`cua agent routine rm`](#cua-agent-routine-rm) | Delete a routine. |
-| [`cua agent routine enable`](#cua-agent-routine-enable) | Turn a routine on. |
-| [`cua agent routine disable`](#cua-agent-routine-disable) | Turn a routine off. |
-| [`cua agent allow-computer`](#cua-agent-allow-computer) | Let a persistent agent use one of your computers (asks for presence). |
-| [`cua agent revoke-computer`](#cua-agent-revoke-computer) | Take a persistent agent's computer access back. |
-| [`cua agent computer-access`](#cua-agent-computer-access) | Which agents may use which computers, and the audit log. |
-| [`cua agent notifications`](#cua-agent-notifications) | The notifications the Cua app shows (turn ends, notify_user, requests). |
-
-Every command also accepts the [global options](/cua-cli/reference/cli#global-options).
-
-<span id="cua-agent"></span>
-
-Run coding agents inside a sandbox: run, ls, logs, send, interrupt, stop.
-
-```text output
-cua agent [OPTIONS] <COMMAND>
-```
-
-## `cua agent run`
-
-Start a coding agent in a sandbox (returns at once unless --follow).
-
-```text output
-cua agent run [OPTIONS] <SANDBOX> <HARNESS> <PROMPT>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<SANDBOX>` | string | required | Sandbox (`local:NAME`, `direct:HOST:PORT`, or NAME). |
-| `<HARNESS>` | string | required | Harness (`cua agent harnesses`). |
-| `<PROMPT>` | string | required | The task. |
-
-| Flag | Short | Type | Default | Description |
-| --- | --- | --- | --- | --- |
-| <span id="cua-agent-run--env-from-host"></span>`--env-from-host` | | string | | Forward a provider key from this shell's environment (repeatable), for example ANTHROPIC_API_KEY. The value never appears in argv. |
-| <span id="cua-agent-run--repo"></span>`--repo` | | string | | Git repository cloned into the working directory first. |
-| <span id="cua-agent-run--branch"></span>`--branch` | | string | | |
-| <span id="cua-agent-run--cwd"></span>`--cwd` | | string | | Working directory in the sandbox. |
-| <span id="cua-agent-run--model"></span>`--model` | | string | | |
-| <span id="cua-agent-run--base-url"></span>`--base-url` | | string | | A custom model endpoint (proxy or compatible server). |
-| <span id="cua-agent-run--wire"></span>`--wire` | | string | | Its wire format: anthropic, openai-responses, openai-chat, gemini. |
-| <span id="cua-agent-run--mcp"></span>`--mcp` | | string | | An MCP server for the agent: NAME=URL (HTTP, as reachable inside the sandbox) or NAME=cmd:COMMAND ARGS... (stdio, run in the sandbox). Repeatable. |
-| <span id="cua-agent-run--file"></span>`--file` | | path | | Attach a local file to the prompt (repeatable). |
-| <span id="cua-agent-run--label"></span>`--label` | | string | | |
-| <span id="cua-agent-run--local"></span>`--local` | | boolean | `false` | Look NAME up among local sandboxes only (same as `local:NAME`). |
-| <span id="cua-agent-run--no-sandbox-mcp"></span>`--no-sandbox-mcp` | | boolean | `false` | Do not give the agent the sandbox's own MCP tools. |
-| <span id="cua-agent-run--no-skills"></span>`--no-skills` | | boolean | `false` | Do not copy the cua skills into the harness. |
-| <span id="cua-agent-run--exit-when-idle"></span>`--exit-when-idle` | | boolean | `false` | Stop (resumably) once the prompt is answered. |
-| <span id="cua-agent-run--follow"></span>`--follow` | `-f` | boolean | `false` | Stream events until the turn ends. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-agent-run"
-cua agent run local:dev claude-code "fix the failing test" --env-from-host ANTHROPIC_API_KEY -f
-cua agent run local:ci openai-codex "add tests" --repo https://github.com/org/repo --exit-when-idle
-```
-
-## `cua agent ls`
-
-List runs in a sandbox.
-
-```text output
-cua agent ls [OPTIONS] <SANDBOX>
-```
-
-Alias: `cua agent list`.
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<SANDBOX>` | string | required | Sandbox (`local:NAME`, `direct:HOST:PORT`, or NAME). |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-agent-ls--local"></span>`--local` | boolean | `false` | Look NAME up among local sandboxes only (same as `local:NAME`). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-agent-ls"
-cua agent ls local:dev
-```
-
-## `cua agent logs`
-
-Print a run's normalized events (--follow to stream).
-
-```text output
-cua agent logs [OPTIONS] <SANDBOX> <RUN_ID>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<SANDBOX>` | string | required | |
-| `<RUN_ID>` | string | required | |
-
-| Flag | Short | Type | Default | Description |
-| --- | --- | --- | --- | --- |
-| <span id="cua-agent-logs--local"></span>`--local` | | boolean | `false` | Look NAME up among local sandboxes only (same as `local:NAME`). |
-| <span id="cua-agent-logs--follow"></span>`--follow` | `-f` | boolean | `false` | Keep streaming until the turn ends. |
-| <span id="cua-agent-logs--raw"></span>`--raw` | | boolean | `false` | Print each event's JSON (raw ACP payload included). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-agent-logs"
-cua agent logs local:dev run-1a2b3c4d -f
-```
-
-## `cua agent send`
-
-Send a follow-up (queued while a turn runs).
-
-```text output
-cua agent send [OPTIONS] <SANDBOX> <RUN_ID> <TEXT>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<SANDBOX>` | string | required | |
-| `<RUN_ID>` | string | required | |
-| `<TEXT>` | string | required | |
-
-| Flag | Short | Type | Default | Description |
-| --- | --- | --- | --- | --- |
-| <span id="cua-agent-send--local"></span>`--local` | | boolean | `false` | Look NAME up among local sandboxes only (same as `local:NAME`). |
-| <span id="cua-agent-send--follow"></span>`--follow` | `-f` | boolean | `false` | |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-agent-send"
-cua agent send local:dev run-1a2b3c4d "now add a regression test" -f
-```
-
-## `cua agent interrupt`
-
-Cancel the turn in flight (the session stays open).
-
-```text output
-cua agent interrupt [OPTIONS] <SANDBOX> <RUN_ID>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<SANDBOX>` | string | required | |
-| `<RUN_ID>` | string | required | |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-agent-interrupt--local"></span>`--local` | boolean | `false` | Look NAME up among local sandboxes only (same as `local:NAME`). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-agent-interrupt"
-cua agent interrupt local:dev run-1a2b3c4d
-```
-
-## `cua agent stop`
-
-Stop a run and verify it is gone.
-
-```text output
-cua agent stop [OPTIONS] <SANDBOX> <RUN_ID>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<SANDBOX>` | string | required | |
-| `<RUN_ID>` | string | required | |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-agent-stop--local"></span>`--local` | boolean | `false` | Look NAME up among local sandboxes only (same as `local:NAME`). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-agent-stop"
-cua agent stop local:dev run-1a2b3c4d
-```
-
-## `cua agent status`
-
-A run's status and last result.
-
-```text output
-cua agent status [OPTIONS] <SANDBOX> <RUN_ID>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<SANDBOX>` | string | required | |
-| `<RUN_ID>` | string | required | |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-agent-status--local"></span>`--local` | boolean | `false` | Look NAME up among local sandboxes only (same as `local:NAME`). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-agent-status"
-cua agent status local:dev run-1a2b3c4d
-```
-
-## `cua agent rm`
-
-Stop a run and delete its record (secrets included).
-
-```text output
-cua agent rm [OPTIONS] <SANDBOX> <RUN_ID>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<SANDBOX>` | string | required | |
-| `<RUN_ID>` | string | required | |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-agent-rm--local"></span>`--local` | boolean | `false` | Look NAME up among local sandboxes only (same as `local:NAME`). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-agent-rm"
-cua agent rm local:dev run-1a2b3c4d
-```
-
-## `cua agent ensure`
-
-Install harnesses or apps now (`claude-code`, `blender`, ...).
-
-```text output
-cua agent ensure [OPTIONS] <SANDBOX> <IDS>...
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<SANDBOX>` | string | required | |
-| `<IDS>...` | string | required | Repeatable. |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-agent-ensure--local"></span>`--local` | boolean | `false` | Look NAME up among local sandboxes only (same as `local:NAME`). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-agent-ensure"
-cua agent ensure local:dev claude-code vscode
-```
-
-## `cua agent harnesses`
-
-The harnesses: readiness, installs, key variables, limits.
-
-```text output
-cua agent harnesses [OPTIONS]
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-agent-harnesses"
-cua agent harnesses
-cua --json agent harnesses
-```
-
-## `cua agent keys`
-
-The provider keys agents get, kept in the Keychain by the Cua daemon (Cua Spaces → Settings → Agents). Values are read from stdin and never printed.
-
-```text output
-cua agent keys [OPTIONS] [COMMAND]
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-agent-keys"
-cua agent keys
-cua agent keys set anthropic
-cua agent keys rm OPENAI_API_KEY
-```
-
-### `cua agent keys ls`
-
-List the saved keys (never their values).
-
-```text output
-cua agent keys ls [OPTIONS]
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-agent-keys-ls"
-cua agent keys ls
-cua --json agent keys ls
-```
-
-### `cua agent keys set`
-
-Add or replace a key, read from stdin. PROVIDER: anthropic, openai or other (with --env). Pipe the key in (`pbpaste | cua agent keys set anthropic`); a terminal is refused so the key isn't echoed.
-
-```text output
-cua agent keys set [OPTIONS] <PROVIDER>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<PROVIDER>` | string | required | |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-agent-keys-set--env"></span>`--env` | string | | The variable an Other key is given to runs as. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-agent-keys-set"
-cua agent keys set anthropic
-cua agent keys set other --env GEMINI_API_KEY
-```
-
-### `cua agent keys rm`
-
-Remove the key a run gets as ENV.
-
-```text output
-cua agent keys rm [OPTIONS] <ENV>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<ENV>` | string | required | |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-agent-keys-rm"
-cua agent keys rm ANTHROPIC_API_KEY
-```
-
-## `cua agent create`
-
-Create a persistent agent: a named harness whose memory lives in the Cua Volume (agents/NAME/) and outlives its Space.
-
-```text output
-cua agent create [OPTIONS] --harness <HARNESS> --in <SPACE> <NAME>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<NAME>` | string | required | |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-agent-create--harness"></span>`--harness` | string | required | Harness id (`cua agent harnesses`). |
-| <span id="cua-agent-create--in"></span>`--in` | string | required | The Space it works in. |
-| <span id="cua-agent-create--model"></span>`--model` | string | | |
-| <span id="cua-agent-create--base-url"></span>`--base-url` | string | | |
-| <span id="cua-agent-create--env-from-host"></span>`--env-from-host` | string | | Provider key variable to forward at each start. Repeatable. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-agent-create"
-cua agent create ada --harness hermes --in local:dev --env-from-host OPENAI_API_KEY
-cua agent create scout --harness claude-code --in local:scout --env-from-host ANTHROPIC_API_KEY
-```
-
-## `cua agent persistent`
-
-List persistent agents.
-
-```text output
-cua agent persistent [OPTIONS]
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-agent-persistent"
-cua agent persistent
-```
-
-## `cua agent tell`
-
-Give a persistent agent a turn (starts a run with its home restored, or follows up on its idle run).
-
-```text output
-cua agent tell [OPTIONS] <NAME> <TEXT>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<NAME>` | string | required | |
-| `<TEXT>` | string | required | |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-agent-tell"
-cua agent tell ada "what did you learn yesterday?"
-```
-
-## `cua agent save`
-
-Save a persistent agent's home into the drive now.
-
-```text output
-cua agent save [OPTIONS] <NAME>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<NAME>` | string | required | |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-agent-save"
-cua agent save ada
-```
-
-## `cua agent pause`
-
-Pause a persistent agent: its run, its routines, and its Space (suspended when local; a cloud Space is released after the home is saved).
-
-```text output
-cua agent pause [OPTIONS] <NAME>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<NAME>` | string | required | |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-agent-pause"
-cua agent pause ada
-```
-
-## `cua agent resume`
-
-Resume a paused persistent agent.
-
-```text output
-cua agent resume [OPTIONS] <NAME>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<NAME>` | string | required | |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-agent-resume--prompt"></span>`--prompt` | string | | |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-agent-resume"
-cua agent resume ada
-cua agent resume ada --prompt "pick up where you left off"
-```
-
-## `cua agent forget`
-
-Forget a persistent agent (its home stays in the drive).
-
-```text output
-cua agent forget [OPTIONS] <NAME>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<NAME>` | string | required | |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-agent-forget"
-cua agent forget ada
-```
-
-## `cua agent routine`
-
-A persistent agent's routines, fired by the daemon with or without the app open.
-
-```text output
-cua agent routine [OPTIONS] <COMMAND>
-```
-
-### `cua agent routine add`
-
-Add a routine (give one of --every, --daily, --weekly).
-
-```text output
-cua agent routine add [OPTIONS] --title <TITLE> --prompt <PROMPT> <AGENT>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<AGENT>` | string | required | |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-agent-routine-add--title"></span>`--title` | string | required | |
-| <span id="cua-agent-routine-add--prompt"></span>`--prompt` | string | required | |
-| <span id="cua-agent-routine-add--every"></span>`--every` | integer | | Every N minutes. |
-| <span id="cua-agent-routine-add--daily"></span>`--daily` | string | | Every day at HH:MM. |
-| <span id="cua-agent-routine-add--weekly"></span>`--weekly` | string | | Every week, `mon 09:00`. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-agent-routine-add"
-cua agent routine add ada --title "Inbox sweep" --prompt "Triage new issues" --every 60
-cua agent routine add ada --title "Morning" --prompt "Plan the day" --daily 08:00
-```
-
-### `cua agent routine ls`
-
-List routines.
-
-```text output
-cua agent routine ls [OPTIONS] [AGENT]
-```
-
-Alias: `cua agent routine list`.
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<AGENT>` | string | optional | |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-agent-routine-ls"
-cua agent routine ls
-cua agent routine ls ada
-```
-
-### `cua agent routine rm`
-
-Delete a routine.
-
-```text output
-cua agent routine rm [OPTIONS] <ID>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<ID>` | string | required | |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-agent-routine-rm"
-cua agent routine rm 0F3A2C1E-8B7D-4E6F-9A1B-2C3D4E5F6A7B
-```
-
-### `cua agent routine enable`
-
-Turn a routine on.
-
-```text output
-cua agent routine enable [OPTIONS] <ID>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<ID>` | string | required | |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-agent-routine-enable"
-cua agent routine enable 0F3A2C1E-8B7D-4E6F-9A1B-2C3D4E5F6A7B
-```
-
-### `cua agent routine disable`
-
-Turn a routine off.
-
-```text output
-cua agent routine disable [OPTIONS] <ID>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<ID>` | string | required | |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-agent-routine-disable"
-cua agent routine disable 0F3A2C1E-8B7D-4E6F-9A1B-2C3D4E5F6A7B
-```
-
-## `cua agent allow-computer`
-
-Let a persistent agent use one of your computers (asks for presence).
-
-```text output
-cua agent allow-computer [OPTIONS] <NAME> <MACHINE>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<NAME>` | string | required | |
-| `<MACHINE>` | string | required | The machine's Space id (`cua host status` shows this machine's). |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-agent-allow-computer--for"></span>`--for` | integer | | End the grant after this many seconds. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-agent-allow-computer"
-cua agent allow-computer ada relay:0123456789abcdef
-```
-
-## `cua agent revoke-computer`
-
-Take a persistent agent's computer access back.
-
-```text output
-cua agent revoke-computer [OPTIONS] <NAME> [MACHINE]
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<NAME>` | string | required | |
-| `<MACHINE>` | string | optional | |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-agent-revoke-computer"
-cua agent revoke-computer ada
-cua agent revoke-computer ada relay:0123456789abcdef
-```
-
-## `cua agent computer-access`
-
-Which agents may use which computers, and the audit log.
-
-```text output
-cua agent computer-access [OPTIONS] [NAME]
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<NAME>` | string | optional | |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-agent-computer-access--audit"></span>`--audit` | integer | `0` | Also print this many audit entries. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-agent-computer-access"
-cua agent computer-access --audit 20
-```
-
-## `cua agent notifications`
-
-The notifications the Cua app shows (turn ends, notify_user, requests).
-
-```text output
-cua agent notifications [OPTIONS]
-```
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-agent-notifications--unread"></span>`--unread` | boolean | `false` | |
-| <span id="cua-agent-notifications--mark-read"></span>`--mark-read` | boolean | `false` | Mark every notification read. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-agent-notifications"
-cua agent notifications --unread
-cua agent notifications --mark-read
-```
-
-## Exit codes
-
-| Code | Meaning |
-| --- | --- |
-| `0` | Success. |
-| `1` | Failure, or `cua do` reported an error. |
-| `2` | Invalid argument, or an ambiguous sandbox name (qualify it: `local:NAME`). |
-| `3` | Not found: sandbox, window, skill or image (or an image not published yet). |
-| `4` | Not supported, or not configured (for example no provider credentials). |
-| `5` | No cua-spacesd answered, or a transport failure. |
-| `6` | Unauthenticated or permission denied (by Cua or your cloud account). |
-| `7` | Not enough free disk space (see `cua cache`). |
-| `130` | Cancelled (Ctrl-C during a create): what it made was removed. |
diff --git a/docs/content/docs/cua-cli/reference/cli/agents.mdx b/docs/content/docs/cua-cli/reference/cli/agents.mdx
index 6e90fd230b..671ffd1ff5 100644
--- a/docs/content/docs/cua-cli/reference/cli/agents.mdx
+++ b/docs/content/docs/cua-cli/reference/cli/agents.mdx
@@ -1,6 +1,6 @@
---
-title: "cua agents"
-description: "Install cua skills and the cua MCP server into AI coding agents."
+title: "Agents, MCP and skills"
+description: "Run coding agents in a sandbox, set up your AI agents, the stdio MCP server, and recorded skills."
---
{/*
@@ -12,15 +12,711 @@ description: "Install cua skills and the cua MCP server into AI coding agents."
| Command | Description |
| --- | --- |
+| [`cua agent`](#cua-agent) | Run coding agents inside a sandbox: run, ls, logs, send, interrupt, stop. |
+| [`cua agent run`](#cua-agent-run) | Start a coding agent in a sandbox (returns at once unless --follow). |
+| [`cua agent ls`](#cua-agent-ls) | List runs in a sandbox. |
+| [`cua agent logs`](#cua-agent-logs) | Print a run's normalized events (--follow to stream). |
+| [`cua agent send`](#cua-agent-send) | Send a follow-up (queued while a turn runs). |
+| [`cua agent interrupt`](#cua-agent-interrupt) | Cancel the turn in flight (the session stays open). |
+| [`cua agent stop`](#cua-agent-stop) | Stop a run and verify it is gone. |
+| [`cua agent status`](#cua-agent-status) | A run's status and last result. |
+| [`cua agent rm`](#cua-agent-rm) | Stop a run and delete its record (secrets included). |
+| [`cua agent ensure`](#cua-agent-ensure) | Install harnesses or apps now (`claude-code`, `blender`, ...). |
+| [`cua agent harnesses`](#cua-agent-harnesses) | The harnesses: readiness, installs, key variables, limits. |
+| [`cua agent keys`](#cua-agent-keys) | The provider keys agents get, kept in the Keychain by the Cua daemon (Cua Spaces → Settings → Agents). |
+| [`cua agent keys ls`](#cua-agent-keys-ls) | List the saved keys (never their values). |
+| [`cua agent keys set`](#cua-agent-keys-set) | Add or replace a key, read from stdin. |
+| [`cua agent keys rm`](#cua-agent-keys-rm) | Remove the key a run gets as ENV. |
+| [`cua agent create`](#cua-agent-create) | Create a persistent agent: a named harness whose memory lives in the Cua Volume (agents/NAME/) and outlives its Space. |
+| [`cua agent persistent`](#cua-agent-persistent) | List persistent agents. |
+| [`cua agent tell`](#cua-agent-tell) | Give a persistent agent a turn (starts a run with its home restored, or follows up on its idle run). |
+| [`cua agent save`](#cua-agent-save) | Save a persistent agent's home into the drive now. |
+| [`cua agent pause`](#cua-agent-pause) | Pause a persistent agent: its run, its routines, and its Space (suspended when local; a cloud Space is released after the home is saved). |
+| [`cua agent resume`](#cua-agent-resume) | Resume a paused persistent agent. |
+| [`cua agent forget`](#cua-agent-forget) | Forget a persistent agent (its home stays in the drive). |
+| [`cua agent routine`](#cua-agent-routine) | A persistent agent's routines, fired by the daemon with or without the app open. |
+| [`cua agent routine add`](#cua-agent-routine-add) | Add a routine (give one of --every, --daily, --weekly). |
+| [`cua agent routine ls`](#cua-agent-routine-ls) | List routines. |
+| [`cua agent routine rm`](#cua-agent-routine-rm) | Delete a routine. |
+| [`cua agent routine enable`](#cua-agent-routine-enable) | Turn a routine on. |
+| [`cua agent routine disable`](#cua-agent-routine-disable) | Turn a routine off. |
+| [`cua agent allow-computer`](#cua-agent-allow-computer) | Let a persistent agent use one of your computers (asks for presence). |
+| [`cua agent revoke-computer`](#cua-agent-revoke-computer) | Take a persistent agent's computer access back. |
+| [`cua agent computer-access`](#cua-agent-computer-access) | Which agents may use which computers, and the audit log. |
+| [`cua agent notifications`](#cua-agent-notifications) | The notifications the Cua app shows (turn ends, notify_user, requests). |
+| [`cua agents`](#cua-agents) | AI coding agents on this machine: install cua skills and configure the cua MCP server. |
| [`cua agents detect`](#cua-agents-detect) | List supported AI coding agents and which are installed (read-only). |
| [`cua agents setup`](#cua-agents-setup) | Install the default cua skills and configure the cua MCP server. |
| [`cua agents status`](#cua-agents-status) | What cua configured for each agent. |
| [`cua agents remove`](#cua-agents-remove) | Remove the skills and MCP entries cua added (nothing else). |
| [`cua agents update`](#cua-agents-update) | Refresh installed cua skills and managed MCP entries to this version. |
+| [`cua mcp`](#cua-mcp) | Stdio MCP server exposing sandboxes, computer control and skills. |
+| [`cua skills`](#cua-skills) | Recorded demonstrations (skills) for agents. |
+| [`cua skills list`](#cua-skills-list) | List saved skills. |
+| [`cua skills read`](#cua-skills-read) | Print a skill. |
+| [`cua skills replay`](#cua-skills-replay) | Open a skill's video recording. |
+| [`cua skills delete`](#cua-skills-delete) | Delete a skill. |
+| [`cua skills clean`](#cua-skills-clean) | Delete every skill (asks first). |
+| [`cua skills record`](#cua-skills-record) | Record a demonstration in the HTML5 viewer (it records the screen and your input). |
Every command also accepts the [global options](/cua-cli/reference/cli#global-options).
-<span id="cua-agents"></span>
+## `cua agent`
+
+Run coding agents inside a sandbox: run, ls, logs, send, interrupt, stop.
+
+```text output
+cua agent [OPTIONS] <COMMAND>
+```
+
+### `cua agent run`
+
+Start a coding agent in a sandbox (returns at once unless --follow).
+
+```text output
+cua agent run [OPTIONS] <SANDBOX> <HARNESS> <PROMPT>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<SANDBOX>` | string | required | Sandbox (`local:NAME`, `direct:HOST:PORT`, or NAME). |
+| `<HARNESS>` | string | required | Harness (`cua agent harnesses`). |
+| `<PROMPT>` | string | required | The task. |
+
+| Flag | Short | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| <span id="cua-agent-run--env-from-host"></span>`--env-from-host` | | string | | Forward a provider key from this shell's environment (repeatable), for example ANTHROPIC_API_KEY. The value never appears in argv. |
+| <span id="cua-agent-run--repo"></span>`--repo` | | string | | Git repository cloned into the working directory first. |
+| <span id="cua-agent-run--branch"></span>`--branch` | | string | | |
+| <span id="cua-agent-run--cwd"></span>`--cwd` | | string | | Working directory in the sandbox. |
+| <span id="cua-agent-run--model"></span>`--model` | | string | | |
+| <span id="cua-agent-run--base-url"></span>`--base-url` | | string | | A custom model endpoint (proxy or compatible server). |
+| <span id="cua-agent-run--wire"></span>`--wire` | | string | | Its wire format: anthropic, openai-responses, openai-chat, gemini. |
+| <span id="cua-agent-run--mcp"></span>`--mcp` | | string | | An MCP server for the agent: NAME=URL (HTTP, as reachable inside the sandbox) or NAME=cmd:COMMAND ARGS... (stdio, run in the sandbox). Repeatable. |
+| <span id="cua-agent-run--file"></span>`--file` | | path | | Attach a local file to the prompt (repeatable). |
+| <span id="cua-agent-run--label"></span>`--label` | | string | | |
+| <span id="cua-agent-run--local"></span>`--local` | | boolean | `false` | Look NAME up among local sandboxes only (same as `local:NAME`). |
+| <span id="cua-agent-run--no-sandbox-mcp"></span>`--no-sandbox-mcp` | | boolean | `false` | Do not give the agent the sandbox's own MCP tools. |
+| <span id="cua-agent-run--no-skills"></span>`--no-skills` | | boolean | `false` | Do not copy the cua skills into the harness. |
+| <span id="cua-agent-run--exit-when-idle"></span>`--exit-when-idle` | | boolean | `false` | Stop (resumably) once the prompt is answered. |
+| <span id="cua-agent-run--follow"></span>`--follow` | `-f` | boolean | `false` | Stream events until the turn ends. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-agent-run"
+cua agent run local:dev claude-code "fix the failing test" --env-from-host ANTHROPIC_API_KEY -f
+cua agent run local:ci openai-codex "add tests" --repo https://github.com/org/repo --exit-when-idle
+```
+
+### `cua agent ls`
+
+List runs in a sandbox.
+
+```text output
+cua agent ls [OPTIONS] <SANDBOX>
+```
+
+Alias: `cua agent list`.
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<SANDBOX>` | string | required | Sandbox (`local:NAME`, `direct:HOST:PORT`, or NAME). |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-agent-ls--local"></span>`--local` | boolean | `false` | Look NAME up among local sandboxes only (same as `local:NAME`). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-agent-ls"
+cua agent ls local:dev
+```
+
+### `cua agent logs`
+
+Print a run's normalized events (--follow to stream).
+
+```text output
+cua agent logs [OPTIONS] <SANDBOX> <RUN_ID>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<SANDBOX>` | string | required | |
+| `<RUN_ID>` | string | required | |
+
+| Flag | Short | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| <span id="cua-agent-logs--local"></span>`--local` | | boolean | `false` | Look NAME up among local sandboxes only (same as `local:NAME`). |
+| <span id="cua-agent-logs--follow"></span>`--follow` | `-f` | boolean | `false` | Keep streaming until the turn ends. |
+| <span id="cua-agent-logs--raw"></span>`--raw` | | boolean | `false` | Print each event's JSON (raw ACP payload included). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-agent-logs"
+cua agent logs local:dev run-1a2b3c4d -f
+```
+
+### `cua agent send`
+
+Send a follow-up (queued while a turn runs).
+
+```text output
+cua agent send [OPTIONS] <SANDBOX> <RUN_ID> <TEXT>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<SANDBOX>` | string | required | |
+| `<RUN_ID>` | string | required | |
+| `<TEXT>` | string | required | |
+
+| Flag | Short | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| <span id="cua-agent-send--local"></span>`--local` | | boolean | `false` | Look NAME up among local sandboxes only (same as `local:NAME`). |
+| <span id="cua-agent-send--follow"></span>`--follow` | `-f` | boolean | `false` | |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-agent-send"
+cua agent send local:dev run-1a2b3c4d "now add a regression test" -f
+```
+
+### `cua agent interrupt`
+
+Cancel the turn in flight (the session stays open).
+
+```text output
+cua agent interrupt [OPTIONS] <SANDBOX> <RUN_ID>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<SANDBOX>` | string | required | |
+| `<RUN_ID>` | string | required | |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-agent-interrupt--local"></span>`--local` | boolean | `false` | Look NAME up among local sandboxes only (same as `local:NAME`). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-agent-interrupt"
+cua agent interrupt local:dev run-1a2b3c4d
+```
+
+### `cua agent stop`
+
+Stop a run and verify it is gone.
+
+```text output
+cua agent stop [OPTIONS] <SANDBOX> <RUN_ID>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<SANDBOX>` | string | required | |
+| `<RUN_ID>` | string | required | |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-agent-stop--local"></span>`--local` | boolean | `false` | Look NAME up among local sandboxes only (same as `local:NAME`). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-agent-stop"
+cua agent stop local:dev run-1a2b3c4d
+```
+
+### `cua agent status`
+
+A run's status and last result.
+
+```text output
+cua agent status [OPTIONS] <SANDBOX> <RUN_ID>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<SANDBOX>` | string | required | |
+| `<RUN_ID>` | string | required | |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-agent-status--local"></span>`--local` | boolean | `false` | Look NAME up among local sandboxes only (same as `local:NAME`). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-agent-status"
+cua agent status local:dev run-1a2b3c4d
+```
+
+### `cua agent rm`
+
+Stop a run and delete its record (secrets included).
+
+```text output
+cua agent rm [OPTIONS] <SANDBOX> <RUN_ID>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<SANDBOX>` | string | required | |
+| `<RUN_ID>` | string | required | |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-agent-rm--local"></span>`--local` | boolean | `false` | Look NAME up among local sandboxes only (same as `local:NAME`). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-agent-rm"
+cua agent rm local:dev run-1a2b3c4d
+```
+
+### `cua agent ensure`
+
+Install harnesses or apps now (`claude-code`, `blender`, ...).
+
+```text output
+cua agent ensure [OPTIONS] <SANDBOX> <IDS>...
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<SANDBOX>` | string | required | |
+| `<IDS>...` | string | required | Repeatable. |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-agent-ensure--local"></span>`--local` | boolean | `false` | Look NAME up among local sandboxes only (same as `local:NAME`). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-agent-ensure"
+cua agent ensure local:dev claude-code vscode
+```
+
+### `cua agent harnesses`
+
+The harnesses: readiness, installs, key variables, limits.
+
+```text output
+cua agent harnesses [OPTIONS]
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-agent-harnesses"
+cua agent harnesses
+cua --json agent harnesses
+```
+
+### `cua agent keys`
+
+The provider keys agents get, kept in the Keychain by the Cua daemon (Cua Spaces → Settings → Agents). Values are read from stdin and never printed.
+
+```text output
+cua agent keys [OPTIONS] [COMMAND]
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-agent-keys"
+cua agent keys
+cua agent keys set anthropic
+cua agent keys rm OPENAI_API_KEY
+```
+
+#### `cua agent keys ls`
+
+List the saved keys (never their values).
+
+```text output
+cua agent keys ls [OPTIONS]
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-agent-keys-ls"
+cua agent keys ls
+cua --json agent keys ls
+```
+
+#### `cua agent keys set`
+
+Add or replace a key, read from stdin. PROVIDER: anthropic, openai or other (with --env). Pipe the key in (`pbpaste | cua agent keys set anthropic`); a terminal is refused so the key isn't echoed.
+
+```text output
+cua agent keys set [OPTIONS] <PROVIDER>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<PROVIDER>` | string | required | |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-agent-keys-set--env"></span>`--env` | string | | The variable an Other key is given to runs as. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-agent-keys-set"
+cua agent keys set anthropic
+cua agent keys set other --env GEMINI_API_KEY
+```
+
+#### `cua agent keys rm`
+
+Remove the key a run gets as ENV.
+
+```text output
+cua agent keys rm [OPTIONS] <ENV>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<ENV>` | string | required | |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-agent-keys-rm"
+cua agent keys rm ANTHROPIC_API_KEY
+```
+
+### `cua agent create`
+
+Create a persistent agent: a named harness whose memory lives in the Cua Volume (agents/NAME/) and outlives its Space.
+
+```text output
+cua agent create [OPTIONS] --harness <HARNESS> --in <SPACE> <NAME>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<NAME>` | string | required | |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-agent-create--harness"></span>`--harness` | string | required | Harness id (`cua agent harnesses`). |
+| <span id="cua-agent-create--in"></span>`--in` | string | required | The Space it works in. |
+| <span id="cua-agent-create--model"></span>`--model` | string | | |
+| <span id="cua-agent-create--base-url"></span>`--base-url` | string | | |
+| <span id="cua-agent-create--env-from-host"></span>`--env-from-host` | string | | Provider key variable to forward at each start. Repeatable. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-agent-create"
+cua agent create ada --harness hermes --in local:dev --env-from-host OPENAI_API_KEY
+cua agent create scout --harness claude-code --in local:scout --env-from-host ANTHROPIC_API_KEY
+```
+
+### `cua agent persistent`
+
+List persistent agents.
+
+```text output
+cua agent persistent [OPTIONS]
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-agent-persistent"
+cua agent persistent
+```
+
+### `cua agent tell`
+
+Give a persistent agent a turn (starts a run with its home restored, or follows up on its idle run).
+
+```text output
+cua agent tell [OPTIONS] <NAME> <TEXT>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<NAME>` | string | required | |
+| `<TEXT>` | string | required | |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-agent-tell"
+cua agent tell ada "what did you learn yesterday?"
+```
+
+### `cua agent save`
+
+Save a persistent agent's home into the drive now.
+
+```text output
+cua agent save [OPTIONS] <NAME>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<NAME>` | string | required | |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-agent-save"
+cua agent save ada
+```
+
+### `cua agent pause`
+
+Pause a persistent agent: its run, its routines, and its Space (suspended when local; a cloud Space is released after the home is saved).
+
+```text output
+cua agent pause [OPTIONS] <NAME>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<NAME>` | string | required | |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-agent-pause"
+cua agent pause ada
+```
+
+### `cua agent resume`
+
+Resume a paused persistent agent.
+
+```text output
+cua agent resume [OPTIONS] <NAME>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<NAME>` | string | required | |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-agent-resume--prompt"></span>`--prompt` | string | | |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-agent-resume"
+cua agent resume ada
+cua agent resume ada --prompt "pick up where you left off"
+```
+
+### `cua agent forget`
+
+Forget a persistent agent (its home stays in the drive).
+
+```text output
+cua agent forget [OPTIONS] <NAME>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<NAME>` | string | required | |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-agent-forget"
+cua agent forget ada
+```
+
+### `cua agent routine`
+
+A persistent agent's routines, fired by the daemon with or without the app open.
+
+```text output
+cua agent routine [OPTIONS] <COMMAND>
+```
+
+#### `cua agent routine add`
+
+Add a routine (give one of --every, --daily, --weekly).
+
+```text output
+cua agent routine add [OPTIONS] --title <TITLE> --prompt <PROMPT> <AGENT>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<AGENT>` | string | required | |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-agent-routine-add--title"></span>`--title` | string | required | |
+| <span id="cua-agent-routine-add--prompt"></span>`--prompt` | string | required | |
+| <span id="cua-agent-routine-add--every"></span>`--every` | integer | | Every N minutes. |
+| <span id="cua-agent-routine-add--daily"></span>`--daily` | string | | Every day at HH:MM. |
+| <span id="cua-agent-routine-add--weekly"></span>`--weekly` | string | | Every week, `mon 09:00`. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-agent-routine-add"
+cua agent routine add ada --title "Inbox sweep" --prompt "Triage new issues" --every 60
+cua agent routine add ada --title "Morning" --prompt "Plan the day" --daily 08:00
+```
+
+#### `cua agent routine ls`
+
+List routines.
+
+```text output
+cua agent routine ls [OPTIONS] [AGENT]
+```
+
+Alias: `cua agent routine list`.
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<AGENT>` | string | optional | |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-agent-routine-ls"
+cua agent routine ls
+cua agent routine ls ada
+```
+
+#### `cua agent routine rm`
+
+Delete a routine.
+
+```text output
+cua agent routine rm [OPTIONS] <ID>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<ID>` | string | required | |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-agent-routine-rm"
+cua agent routine rm 0F3A2C1E-8B7D-4E6F-9A1B-2C3D4E5F6A7B
+```
+
+#### `cua agent routine enable`
+
+Turn a routine on.
+
+```text output
+cua agent routine enable [OPTIONS] <ID>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<ID>` | string | required | |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-agent-routine-enable"
+cua agent routine enable 0F3A2C1E-8B7D-4E6F-9A1B-2C3D4E5F6A7B
+```
+
+#### `cua agent routine disable`
+
+Turn a routine off.
+
+```text output
+cua agent routine disable [OPTIONS] <ID>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<ID>` | string | required | |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-agent-routine-disable"
+cua agent routine disable 0F3A2C1E-8B7D-4E6F-9A1B-2C3D4E5F6A7B
+```
+
+### `cua agent allow-computer`
+
+Let a persistent agent use one of your computers (asks for presence).
+
+```text output
+cua agent allow-computer [OPTIONS] <NAME> <MACHINE>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<NAME>` | string | required | |
+| `<MACHINE>` | string | required | The machine's Space id (`cua host status` shows this machine's). |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-agent-allow-computer--for"></span>`--for` | integer | | End the grant after this many seconds. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-agent-allow-computer"
+cua agent allow-computer ada relay:0123456789abcdef
+```
+
+### `cua agent revoke-computer`
+
+Take a persistent agent's computer access back.
+
+```text output
+cua agent revoke-computer [OPTIONS] <NAME> [MACHINE]
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<NAME>` | string | required | |
+| `<MACHINE>` | string | optional | |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-agent-revoke-computer"
+cua agent revoke-computer ada
+cua agent revoke-computer ada relay:0123456789abcdef
+```
+
+### `cua agent computer-access`
+
+Which agents may use which computers, and the audit log.
+
+```text output
+cua agent computer-access [OPTIONS] [NAME]
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<NAME>` | string | optional | |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-agent-computer-access--audit"></span>`--audit` | integer | `0` | Also print this many audit entries. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-agent-computer-access"
+cua agent computer-access --audit 20
+```
+
+### `cua agent notifications`
+
+The notifications the Cua app shows (turn ends, notify_user, requests).
+
+```text output
+cua agent notifications [OPTIONS]
+```
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-agent-notifications--unread"></span>`--unread` | boolean | `false` | |
+| <span id="cua-agent-notifications--mark-read"></span>`--mark-read` | boolean | `false` | Mark every notification read. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-agent-notifications"
+cua agent notifications --unread
+cua agent notifications --mark-read
+```
+
+## `cua agents`
AI coding agents on this machine: install cua skills and configure the cua MCP server.
@@ -28,7 +724,7 @@ AI coding agents on this machine: install cua skills and configure the cua MCP s
cua agents [OPTIONS] <COMMAND>
```
-## `cua agents detect`
+### `cua agents detect`
List supported AI coding agents and which are installed (read-only).
@@ -42,7 +738,7 @@ cua agents detect [OPTIONS]
cua agents detect
```
-## `cua agents setup`
+### `cua agents setup`
Install the default cua skills and configure the cua MCP server.
@@ -79,7 +775,7 @@ cua agents setup --mcp-only
cua agents setup --cua-driver --agents all -y
```
-## `cua agents status`
+### `cua agents status`
What cua configured for each agent.
@@ -93,7 +789,7 @@ cua agents status [OPTIONS]
cua agents status
```
-## `cua agents remove`
+### `cua agents remove`
Remove the skills and MCP entries cua added (nothing else).
@@ -115,7 +811,7 @@ cua agents remove
cua agents remove --agents codex --skills-only -y
```
-## `cua agents update`
+### `cua agents update`
Refresh installed cua skills and managed MCP entries to this version.
@@ -129,6 +825,160 @@ cua agents update [OPTIONS]
cua agents update
```
+## `cua mcp`
+
+Stdio MCP server exposing sandboxes, computer control and skills.
+
+```text output
+cua mcp [OPTIONS]
+```
+
+Alias: `cua serve-mcp`.
+
+| Flag | Type | Default | Env var | Description |
+| --- | --- | --- | --- | --- |
+| <span id="cua-mcp--permissions"></span>`--permissions` | string | | `CUA_MCP_PERMISSIONS` | Comma-separated permissions or groups (default: all). |
+| <span id="cua-mcp--sandbox"></span>`--sandbox` | string | | `CUA_SANDBOX` | Default sandbox for computer tools. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-mcp"
+# Serve every tool over stdio (what MCP clients launch)
+cua mcp
+
+# Read-only sandbox tools, computer tools on the sandbox dev
+cua mcp --permissions sandbox:readonly,computer:all --sandbox dev
+```
+
+## `cua skills`
+
+Recorded demonstrations (skills) for agents.
+
+```text output
+cua skills [OPTIONS] <COMMAND>
+```
+
+### `cua skills list`
+
+List saved skills.
+
+```text output
+cua skills list [OPTIONS]
+```
+
+Alias: `cua skills ls`.
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-skills-list"
+cua skills list
+```
+
+### `cua skills read`
+
+Print a skill.
+
+```text output
+cua skills read [OPTIONS] <NAME>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<NAME>` | string | required | Skill name. |
+
+| Flag | Short | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| <span id="cua-skills-read--format"></span>`--format` | `-f` | `md` \| `json` | `md` | Output format. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-skills-read"
+cua skills read export-invoice
+cua skills read export-invoice --format json
+```
+
+### `cua skills replay`
+
+Open a skill's video recording.
+
+```text output
+cua skills replay [OPTIONS] <NAME>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<NAME>` | string | required | Skill name. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-skills-replay"
+cua skills replay export-invoice
+```
+
+### `cua skills delete`
+
+Delete a skill.
+
+```text output
+cua skills delete [OPTIONS] <NAME>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<NAME>` | string | required | Skill name. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-skills-delete"
+cua skills delete export-invoice
+```
+
+### `cua skills clean`
+
+Delete every skill (asks first).
+
+```text output
+cua skills clean [OPTIONS]
+```
+
+| Flag | Short | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| <span id="cua-skills-clean--yes"></span>`--yes` | `-y` | boolean | `false` | Do not ask for confirmation. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-skills-clean"
+cua skills clean
+
+# Without the prompt
+cua skills clean --yes
+```
+
+### `cua skills record`
+
+Record a demonstration in the HTML5 viewer (it records the screen and your input).
+
+```text output
+cua skills record [OPTIONS]
+```
+
+| Flag | Short | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| <span id="cua-skills-record--sandbox"></span>`--sandbox` | `-s` | string | | Sandbox whose display service to record. |
+| <span id="cua-skills-record--viewer-url"></span>`--viewer-url` | `-u` | string | | Viewer URL to record (a `cua sb view --no-open` link). Alias: `--vnc-url`. |
+| <span id="cua-skills-record--provider"></span>`--provider` | `-p` | `anthropic` \| `openai` | `anthropic` | Captioning provider. |
+| <span id="cua-skills-record--model"></span>`--model` | `-m` | string | | Captioning model. |
+| <span id="cua-skills-record--api-key"></span>`--api-key` | `-k` | string | | API key for the captioning provider. |
+| <span id="cua-skills-record--name"></span>`--name` | `-n` | string | | Skill name. |
+| <span id="cua-skills-record--description"></span>`--description` | `-d` | string | | Skill description. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-skills-record"
+# Record on the sandbox dev and caption with Anthropic
+cua skills record --sandbox dev --name export-invoice
+```
+
## Exit codes
| Code | Meaning |
diff --git a/docs/content/docs/cua-cli/reference/cli/auth.mdx b/docs/content/docs/cua-cli/reference/cli/auth.mdx
deleted file mode 100644
index dde5bfc08b..0000000000
--- a/docs/content/docs/cua-cli/reference/cli/auth.mdx
+++ /dev/null
@@ -1,194 +0,0 @@
----
-title: "cua auth"
-description: "Sign in and out, see who is signed in, and store sandbox provider keys."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-cli
- Source: cua dump-docs --type cli
- Version: 0.5.0
-*/}
-
-| Command | Description |
-| --- | --- |
-| [`cua auth login`](#cua-auth-login) | Log in (browser sign-in; `--remote` for a device code), then offer to set up your AI coding agents. |
-| [`cua auth logout`](#cua-auth-logout) | Revoke and remove the local session. |
-| [`cua auth status`](#cua-auth-status) | Local session state (no network). |
-| [`cua auth whoami`](#cua-auth-whoami) | Who is signed in: the account, its plan and its teams. |
-| [`cua auth provider`](#cua-auth-provider) | Keys of the contrib sandbox providers (`--on e2b`, `--on daytona`, `--on modal`). |
-| [`cua auth provider ls`](#cua-auth-provider-ls) | Providers, whether this build has them and where their keys come from (never the values). |
-| [`cua auth provider set`](#cua-auth-provider-set) | Store a provider key, read from stdin (no echo on a terminal). |
-| [`cua auth provider rm`](#cua-auth-provider-rm) | Remove a provider's stored keys. |
-
-Every command also accepts the [global options](/cua-cli/reference/cli#global-options).
-
-<span id="cua-auth"></span>
-
-Log in to Cua and manage the signed-in session.
-
-```text output
-cua auth [OPTIONS] <COMMAND>
-```
-
-## `cua auth login`
-
-Log in (browser sign-in; `--remote` for a device code), then offer to set up your AI coding agents.
-
-```text output
-cua auth login [OPTIONS]
-```
-
-| Flag | Short | Type | Default | Description |
-| --- | --- | --- | --- | --- |
-| <span id="cua-auth-login--agents"></span>`--agents` | | string | | Agents: `all` (installed), `none`, or ids such as `claude,codex,hermes` (`cua agents detect` lists every supported agent). |
-| <span id="cua-auth-login--mcp-command"></span>`--mcp-command` | | string | | Command agents launch for the MCP server (default: the `cua` on PATH, else this binary). |
-| <span id="cua-auth-login--no-browser"></span>`--no-browser` | | boolean | `false` | Do not open a browser; print the URL. |
-| <span id="cua-auth-login--remote"></span>`--remote` | | boolean | `false` | Sign in from another device with a code (for SSH sessions and machines without a browser). |
-| <span id="cua-auth-login--no-onboarding"></span>`--no-onboarding` | | boolean | `false` | Skip the agent onboarding prompt. |
-| <span id="cua-auth-login--skills-only"></span>`--skills-only` | | boolean | `false` | Only install skills. Alias: `--no-mcp`. |
-| <span id="cua-auth-login--mcp-only"></span>`--mcp-only` | | boolean | `false` | Only configure the MCP server. Alias: `--no-skills`. |
-| <span id="cua-auth-login--yes"></span>`--yes` | `-y` | boolean | `false` | Answer yes to every prompt. |
-| <span id="cua-auth-login--force"></span>`--force` | | boolean | `false` | Replace skill folders cua did not write (the old one is backed up). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-auth-login"
-# Sign in with the browser
-cua auth login
-
-# Sign in over SSH with a device code
-cua auth login --remote
-
-# Sign in and set up Claude Code without prompts
-cua auth login --agents claude -y
-```
-
-## `cua auth logout`
-
-Revoke and remove the local session.
-
-```text output
-cua auth logout [OPTIONS]
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-auth-logout"
-cua auth logout
-```
-
-## `cua auth status`
-
-Local session state (no network).
-
-```text output
-cua auth status [OPTIONS]
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-auth-status"
-cua auth status
-cua auth status --json
-```
-
-## `cua auth whoami`
-
-Who is signed in: the account, its plan and its teams.
-
-```text output
-cua auth whoami [OPTIONS]
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-auth-whoami"
-cua auth whoami
-cua auth whoami --json
-```
-
-## `cua auth provider`
-
-Keys of the contrib sandbox providers (`--on e2b`, `--on daytona`, `--on modal`).
-
-```text output
-cua auth provider [OPTIONS] <COMMAND>
-```
-
-### `cua auth provider ls`
-
-Providers, whether this build has them and where their keys come from (never the values).
-
-```text output
-cua auth provider ls [OPTIONS]
-```
-
-Alias: `cua auth provider list`.
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-auth-provider-ls"
-cua auth provider ls
-cua auth provider ls --json
-```
-
-### `cua auth provider set`
-
-Store a provider key, read from stdin (no echo on a terminal). An environment variable of the same name wins over the stored key.
-
-```text output
-cua auth provider set [OPTIONS] <NAME>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<NAME>` | string | required | Provider (`e2b`, `daytona`, `modal`). |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-auth-provider-set--var"></span>`--var` | string | | Only this variable (for example MODAL_TOKEN_SECRET). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-auth-provider-set"
-# Prompt for E2B_API_KEY (no echo)
-cua auth provider set e2b
-
-# One variable only
-cua auth provider set daytona --var DAYTONA_API_KEY
-```
-
-### `cua auth provider rm`
-
-Remove a provider's stored keys.
-
-```text output
-cua auth provider rm [OPTIONS] <NAME>
-```
-
-Alias: `cua auth provider delete`.
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<NAME>` | string | required | Provider. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-auth-provider-rm"
-cua auth provider rm e2b
-```
-
-## Exit codes
-
-| Code | Meaning |
-| --- | --- |
-| `0` | Success. |
-| `1` | Failure, or `cua do` reported an error. |
-| `2` | Invalid argument, or an ambiguous sandbox name (qualify it: `local:NAME`). |
-| `3` | Not found: sandbox, window, skill or image (or an image not published yet). |
-| `4` | Not supported, or not configured (for example no provider credentials). |
-| `5` | No cua-spacesd answered, or a transport failure. |
-| `6` | Unauthenticated or permission denied (by Cua or your cloud account). |
-| `7` | Not enough free disk space (see `cua cache`). |
-| `130` | Cancelled (Ctrl-C during a create): what it made was removed. |
diff --git a/docs/content/docs/cua-cli/reference/cli/cache.mdx b/docs/content/docs/cua-cli/reference/cli/cache.mdx
deleted file mode 100644
index d255d84e15..0000000000
--- a/docs/content/docs/cua-cli/reference/cli/cache.mdx
+++ /dev/null
@@ -1,130 +0,0 @@
----
-title: "cua cache"
-description: "See and reclaim the disk used by images, sandboxes, builds and logs."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-cli
- Source: cua dump-docs --type cli
- Version: 0.5.0
-*/}
-
-| Command | Description |
-| --- | --- |
-| [`cua cache ls`](#cua-cache-ls) | List what the SDK keeps on disk, one row per image, sandbox, build output, install archive or log. |
-| [`cua cache du`](#cua-cache-du) | Disk usage per category, the cache budget and free space. |
-| [`cua cache prune`](#cua-cache-prune) | Reap orphaned ephemeral sandboxes, remove orphans (abandoned downloads, unused layers) and evict least-recently-used cache down to the budget. |
-| [`cua cache config`](#cua-cache-config) | Show or set the cache settings (`$CUA_HOME/cache.json`; the CUA_CACHE_BUDGET, CUA_DISK_MIN_FREE, CUA_DISK_WARN_FREE and CUA_ORPHAN_REAP_MINUTES environment variables win). |
-
-Every command also accepts the [global options](/cua-cli/reference/cli#global-options).
-
-<span id="cua-cache"></span>
-
-Disk used by images, sandboxes, builds and logs, and its cleanup.
-
-```text output
-cua cache [OPTIONS] <COMMAND>
-```
-
-## `cua cache ls`
-
-List what the SDK keeps on disk, one row per image, sandbox, build output, install archive or log.
-
-```text output
-cua cache ls [OPTIONS]
-```
-
-Alias: `cua cache list`.
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-cache-ls--category"></span>`--category` | string | | Only this category (images, docker-images, lume-bases, builds, installables, icons, sandboxes, checkpoints, logs, data, legacy). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-cache-ls"
-cua cache ls
-
-# Only cached images
-cua cache ls --category images
-```
-
-## `cua cache du`
-
-Disk usage per category, the cache budget and free space.
-
-```text output
-cua cache du [OPTIONS]
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-cache-du"
-cua cache du
-cua cache du --json
-```
-
-## `cua cache prune`
-
-Reap orphaned ephemeral sandboxes, remove orphans (abandoned downloads, unused layers) and evict least-recently-used cache down to the budget. Never removes a sandbox or anything one uses.
-
-```text output
-cua cache prune [OPTIONS]
-```
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-cache-prune--budget"></span>`--budget` | string | | Budget for this run (`auto`, `off` or a size such as `20G`). |
-| <span id="cua-cache-prune--all"></span>`--all` | boolean | `false` | Evict every unused cache entry, not only down to the budget. |
-| <span id="cua-cache-prune--dry-run"></span>`--dry-run` | boolean | `false` | Show what would be removed; remove nothing. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-cache-prune"
-# See what a cleanup would remove
-cua cache prune --dry-run
-
-# Evict every unused cache entry
-cua cache prune --all
-```
-
-## `cua cache config`
-
-Show or set the cache settings (`$CUA_HOME/cache.json`; the CUA_CACHE_BUDGET, CUA_DISK_MIN_FREE, CUA_DISK_WARN_FREE and CUA_ORPHAN_REAP_MINUTES environment variables win).
-
-```text output
-cua cache config [OPTIONS]
-```
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-cache-config--budget"></span>`--budget` | string | | Cache budget: `auto` (min of 30 GiB and 10% of free space plus cache), `off`, or a size. |
-| <span id="cua-cache-config--min-free"></span>`--min-free` | string | | Free space pulls, builds and VM creates always leave (size). |
-| <span id="cua-cache-config--warn-free"></span>`--warn-free` | string | | Warn when free space drops under this (size). |
-| <span id="cua-cache-config--orphan-reap-minutes"></span>`--orphan-reap-minutes` | integer | | Minutes before an ephemeral sandbox whose process died is reaped. |
-| <span id="cua-cache-config--auto-gc"></span>`--auto-gc` | `true` \| `false` | | Clean up automatically after pulls and builds and on daemon idle. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-cache-config"
-# Show the settings
-cua cache config
-
-# Cap the cache at 20 GB and keep 10 GB free
-cua cache config --budget 20G --min-free 10G
-```
-
-## Exit codes
-
-| Code | Meaning |
-| --- | --- |
-| `0` | Success. |
-| `1` | Failure, or `cua do` reported an error. |
-| `2` | Invalid argument, or an ambiguous sandbox name (qualify it: `local:NAME`). |
-| `3` | Not found: sandbox, window, skill or image (or an image not published yet). |
-| `4` | Not supported, or not configured (for example no provider credentials). |
-| `5` | No cua-spacesd answered, or a transport failure. |
-| `6` | Unauthenticated or permission denied (by Cua or your cloud account). |
-| `7` | Not enough free disk space (see `cua cache`). |
-| `130` | Cancelled (Ctrl-C during a create): what it made was removed. |
diff --git a/docs/content/docs/cua-cli/reference/cli/cloud.mdx b/docs/content/docs/cua-cli/reference/cli/cloud.mdx
deleted file mode 100644
index 9cb4ce09d3..0000000000
--- a/docs/content/docs/cua-cli/reference/cli/cloud.mdx
+++ /dev/null
@@ -1,177 +0,0 @@
----
-title: "cua cloud"
-description: "Your own AWS, Google Cloud or Modal account as a place for sandboxes and Spaces: connect, test, status, sweep."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-cli
- Source: cua dump-docs --type cli
- Version: 0.5.0
-*/}
-
-| Command | Description |
-| --- | --- |
-| [`cua cloud status`](#cua-cloud-status) | Your clouds: found credentials, the connected account and region, what each runs at what hourly cost, and what Cua created there. |
-| [`cua cloud connect`](#cua-cloud-connect) | Connect a cloud account Spaces can be created in (after the checks `cua cloud test` runs). |
-| [`cua cloud test`](#cua-cloud-test) | Check a cloud account without creating anything: credentials, permissions (by dry run), quota, the region and machine types. |
-| [`cua cloud disconnect`](#cua-cloud-disconnect) | Forget a connected cloud (nothing in it is deleted). |
-| [`cua cloud sweep`](#cua-cloud-sweep) | Find what Cua left in your clouds: expired Spaces and resources whose Space is gone (with --all, every Cua resource). |
-
-Every command also accepts the [global options](/cua-cli/reference/cli#global-options).
-
-<span id="cua-cloud"></span>
-
-Spaces in your own cloud account (AWS, Google Cloud, Modal): connect, status, test, disconnect, sweep.
-
-```text output
-cua cloud [OPTIONS] <COMMAND>
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-cloud"
-cua cloud status
-cua cloud connect aws --region us-west-2 --default
-cua spaces create --on aws
-cua cloud sweep
-```
-
-## `cua cloud status`
-
-Your clouds: found credentials, the connected account and region, what each runs at what hourly cost, and what Cua created there.
-
-```text output
-cua cloud status [OPTIONS] [PROVIDER]
-```
-
-Alias: `cua cloud ls`.
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<PROVIDER>` | string | optional | Only this cloud (`aws`, `gcp`, `modal`). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-cloud-status"
-cua cloud status
-cua cloud status aws --json
-```
-
-## `cua cloud connect`
-
-Connect a cloud account Spaces can be created in (after the checks `cua cloud test` runs). Credentials stay in the cloud's own CLI; Cua stores only the profile, region, project or environment names.
-
-```text output
-cua cloud connect [OPTIONS] <PROVIDER>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<PROVIDER>` | string | required | `aws`, `gcp` or `modal`. |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-cloud-connect--profile"></span>`--profile` | string | | AWS profile (`~/.aws/config`) or Modal profile (`~/.modal.toml`). |
-| <span id="cua-cloud-connect--region"></span>`--region` | string | | AWS or Google Cloud region. |
-| <span id="cua-cloud-connect--zone"></span>`--zone` | string | | Google Cloud zone (default: the region's `-a` zone). |
-| <span id="cua-cloud-connect--project"></span>`--project` | string | | Google Cloud project (default: `gcloud config get project`). |
-| <span id="cua-cloud-connect--environment"></span>`--environment` | string | | Modal environment (default: the profile's). |
-| <span id="cua-cloud-connect--ttl-hours"></span>`--ttl-hours` | integer | | Delete each Space there after this many hours (default 8; 0: never; Modal caps a sandbox at 24). |
-| <span id="cua-cloud-connect--default"></span>`--default` | boolean | `false` | Also make it the default location (`default.on`). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-cloud-connect"
-cua cloud connect aws --region us-west-2 --default
-cua cloud connect aws --profile sandbox
-cua cloud connect gcp --project my-project --region us-central1
-cua cloud connect modal --environment spaces
-
-# Spaces there delete themselves after 4 hours (default 8; 0: never)
-cua cloud connect aws --ttl-hours 4
-```
-
-## `cua cloud test`
-
-Check a cloud account without creating anything: credentials, permissions (by dry run), quota, the region and machine types.
-
-```text output
-cua cloud test [OPTIONS] <PROVIDER>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<PROVIDER>` | string | required | `aws`, `gcp` or `modal`. |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-cloud-test--profile"></span>`--profile` | string | | AWS profile (`~/.aws/config`) or Modal profile (`~/.modal.toml`). |
-| <span id="cua-cloud-test--region"></span>`--region` | string | | AWS or Google Cloud region. |
-| <span id="cua-cloud-test--zone"></span>`--zone` | string | | Google Cloud zone (default: the region's `-a` zone). |
-| <span id="cua-cloud-test--project"></span>`--project` | string | | Google Cloud project (default: `gcloud config get project`). |
-| <span id="cua-cloud-test--environment"></span>`--environment` | string | | Modal environment (default: the profile's). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-cloud-test"
-cua cloud test aws
-cua cloud test gcp --project my-project
-```
-
-## `cua cloud disconnect`
-
-Forget a connected cloud (nothing in it is deleted).
-
-```text output
-cua cloud disconnect [OPTIONS] <PROVIDER>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<PROVIDER>` | string | required | `aws`, `gcp` or `modal`. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-cloud-disconnect"
-cua cloud disconnect aws
-```
-
-## `cua cloud sweep`
-
-Find what Cua left in your clouds: expired Spaces and resources whose Space is gone (with --all, every Cua resource). Lists them unless --delete. Only resources Cua tagged and recorded are ever touched.
-
-```text output
-cua cloud sweep [OPTIONS] [PROVIDER]
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<PROVIDER>` | string | optional | Only this cloud. |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-cloud-sweep--delete"></span>`--delete` | boolean | `false` | Delete what it finds (default: list only). |
-| <span id="cua-cloud-sweep--all"></span>`--all` | boolean | `false` | Include Cua resources that have not expired (every Space there). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-cloud-sweep"
-cua cloud sweep
-cua cloud sweep aws --delete
-cua cloud sweep --all --delete
-```
-
-## Exit codes
-
-| Code | Meaning |
-| --- | --- |
-| `0` | Success. |
-| `1` | Failure, or `cua do` reported an error. |
-| `2` | Invalid argument, or an ambiguous sandbox name (qualify it: `local:NAME`). |
-| `3` | Not found: sandbox, window, skill or image (or an image not published yet). |
-| `4` | Not supported, or not configured (for example no provider credentials). |
-| `5` | No cua-spacesd answered, or a transport failure. |
-| `6` | Unauthenticated or permission denied (by Cua or your cloud account). |
-| `7` | Not enough free disk space (see `cua cache`). |
-| `130` | Cancelled (Ctrl-C during a create): what it made was removed. |
diff --git a/docs/content/docs/cua-cli/reference/cli/do.mdx b/docs/content/docs/cua-cli/reference/cli/computer-actions.mdx
similarity index 88%
rename from docs/content/docs/cua-cli/reference/cli/do.mdx
rename to docs/content/docs/cua-cli/reference/cli/computer-actions.mdx
index 3a819fbfaa..f23a55b7c5 100644
--- a/docs/content/docs/cua-cli/reference/cli/do.mdx
+++ b/docs/content/docs/cua-cli/reference/cli/computer-actions.mdx
@@ -1,6 +1,6 @@
---
-title: "cua do"
-description: "One-shot computer actions (screenshot, click, type, windows) against a selected target."
+title: "Computer actions"
+description: "One-shot computer actions (screenshot, click, type, windows) against a selected target, and their recorded trajectories."
---
{/*
@@ -51,6 +51,11 @@ description: "One-shot computer actions (screenshot, click, type, windows) again
| [`cua do clipboard get`](#cua-do-clipboard-get) | Print clipboard text. |
| [`cua do clipboard set`](#cua-do-clipboard-set) | Set clipboard text. |
| [`cua do-host-consent`](#cua-do-host-consent) | Grant consent for `cua do switch host`. |
+| [`cua trajectory`](#cua-trajectory) | Recorded `cua do` trajectories. |
+| [`cua trajectory ls`](#cua-trajectory-ls) | List sessions. |
+| [`cua trajectory view`](#cua-trajectory-view) | Zip, serve on loopback and open the hosted viewer. |
+| [`cua trajectory stop`](#cua-trajectory-stop) | Stop the file server started by `view`. |
+| [`cua trajectory clean`](#cua-trajectory-clean) | Delete sessions. |
Every command also accepts the [global options](/cua-cli/reference/cli#global-options).
@@ -763,6 +768,96 @@ cua do-host-consent [OPTIONS]
cua do-host-consent
```
+## `cua trajectory`
+
+Recorded `cua do` trajectories.
+
+```text output
+cua trajectory [OPTIONS] <COMMAND>
+```
+
+Alias: `cua traj`.
+
+### `cua trajectory ls`
+
+List sessions.
+
+```text output
+cua trajectory ls [OPTIONS] [MACHINE]
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<MACHINE>` | string | optional | Only sessions of this target (sandbox name or `host`). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-trajectory-ls"
+cua traj ls
+
+# Only the sessions recorded on the sandbox dev
+cua traj ls dev
+```
+
+### `cua trajectory view`
+
+Zip, serve on loopback and open the hosted viewer.
+
+```text output
+cua trajectory view [OPTIONS] [TARGET]
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<TARGET>` | string | optional | Session id or target name (default: the latest session). |
+
+| Flag | Short | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| <span id="cua-trajectory-view--port"></span>`--port` | `-p` | integer | `8089` | Loopback port of the file server. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-trajectory-view"
+# The latest session
+cua traj view
+cua traj view <session> --port 8090
+```
+
+### `cua trajectory stop`
+
+Stop the file server started by `view`.
+
+```text output
+cua trajectory stop [OPTIONS]
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-trajectory-stop"
+cua traj stop
+```
+
+### `cua trajectory clean`
+
+Delete sessions.
+
+```text output
+cua trajectory clean [OPTIONS]
+```
+
+| Flag | Short | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| <span id="cua-trajectory-clean--older-than"></span>`--older-than` | | integer | | Only sessions older than this many days. |
+| <span id="cua-trajectory-clean--machine"></span>`--machine` | | string | | Only sessions of this target. |
+| <span id="cua-trajectory-clean--yes"></span>`--yes` | `-y` | boolean | `false` | Do not ask for confirmation. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-trajectory-clean"
+# Sessions older than a week, without the prompt
+cua traj clean --older-than 7 --yes
+```
+
## Exit codes
| Code | Meaning |
diff --git a/docs/content/docs/cua-cli/reference/cli/config.mdx b/docs/content/docs/cua-cli/reference/cli/config.mdx
deleted file mode 100644
index 9f718f4581..0000000000
--- a/docs/content/docs/cua-cli/reference/cli/config.mdx
+++ /dev/null
@@ -1,136 +0,0 @@
----
-title: "cua config"
-description: "User defaults: where sandboxes run (`default.on`), the default kind and runtime."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-cli
- Source: cua dump-docs --type cli
- Version: 0.5.0
-*/}
-
-| Command | Description |
-| --- | --- |
-| [`cua config list`](#cua-config-list) | Every setting: its effective value and where it comes from (env, config or default). |
-| [`cua config get`](#cua-config-get) | One setting's effective value. |
-| [`cua config set`](#cua-config-set) | Write a setting to the config file. |
-| [`cua config unset`](#cua-config-unset) | Remove a setting from the config file (the environment variable or the built-in default applies again). |
-| [`cua config path`](#cua-config-path) | The config file's path. |
-
-Every command also accepts the [global options](/cua-cli/reference/cli#global-options).
-
-<span id="cua-config"></span>
-
-User defaults (~/.cua/config.toml): where sandboxes run when --on is not given (default.on), the default kind and runtime.
-
-```text output
-cua config [OPTIONS] <COMMAND>
-```
-
-## `cua config list`
-
-Every setting: its effective value and where it comes from (env, config or default).
-
-```text output
-cua config list [OPTIONS]
-```
-
-Alias: `cua config ls`.
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-config-list"
-cua config list
-cua config list --json
-```
-
-## `cua config get`
-
-One setting's effective value.
-
-```text output
-cua config get [OPTIONS] <KEY>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<KEY>` | string | required | Setting (`default.on`, `default.kind`, `default.runtime`). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-config-get"
-cua config get default.on
-```
-
-## `cua config set`
-
-Write a setting to the config file.
-
-```text output
-cua config set [OPTIONS] <KEY> <VALUE>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<KEY>` | string | required | Setting. |
-| `<VALUE>` | string | required | Value (checked: `default.on` takes local, aws, gcp, modal or a provider). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-config-set"
-# Create sandboxes in your AWS account unless --on says otherwise
-cua config set default.on aws
-
-# Back to this machine
-cua config set default.on local
-
-# Prefer VMs when the image offers both
-cua config set default.kind vm
-```
-
-## `cua config unset`
-
-Remove a setting from the config file (the environment variable or the built-in default applies again).
-
-```text output
-cua config unset [OPTIONS] <KEY>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<KEY>` | string | required | Setting. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-config-unset"
-cua config unset default.on
-```
-
-## `cua config path`
-
-The config file's path.
-
-```text output
-cua config path [OPTIONS]
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-config-path"
-cua config path
-```
-
-## Exit codes
-
-| Code | Meaning |
-| --- | --- |
-| `0` | Success. |
-| `1` | Failure, or `cua do` reported an error. |
-| `2` | Invalid argument, or an ambiguous sandbox name (qualify it: `local:NAME`). |
-| `3` | Not found: sandbox, window, skill or image (or an image not published yet). |
-| `4` | Not supported, or not configured (for example no provider credentials). |
-| `5` | No cua-spacesd answered, or a transport failure. |
-| `6` | Unauthenticated or permission denied (by Cua or your cloud account). |
-| `7` | Not enough free disk space (see `cua cache`). |
-| `130` | Cancelled (Ctrl-C during a create): what it made was removed. |
diff --git a/docs/content/docs/cua-cli/reference/cli/daemon.mdx b/docs/content/docs/cua-cli/reference/cli/daemon.mdx
deleted file mode 100644
index 764be40455..0000000000
--- a/docs/content/docs/cua-cli/reference/cli/daemon.mdx
+++ /dev/null
@@ -1,113 +0,0 @@
----
-title: "cua daemon"
-description: "Start, stop and inspect the cua daemon."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-cli
- Source: cua dump-docs --type cli
- Version: 0.5.0
-*/}
-
-| Command | Description |
-| --- | --- |
-| [`cua daemon start`](#cua-daemon-start) | Start the daemon (in the background unless --foreground). |
-| [`cua daemon stop`](#cua-daemon-stop) | Stop the daemon. |
-| [`cua daemon status`](#cua-daemon-status) | Show daemon status. |
-| [`cua daemon mcp`](#cua-daemon-mcp) | Stdio MCP server backed by the daemon (started if needed): the Spaces contract tools plus the sandbox/computer/skills tools (same server as `cua mcp`). |
-
-Every command also accepts the [global options](/cua-cli/reference/cli#global-options).
-
-<span id="cua-daemon"></span>
-
-The cua daemon.
-
-```text output
-cua daemon [OPTIONS] <COMMAND>
-```
-
-## `cua daemon start`
-
-Start the daemon (in the background unless --foreground).
-
-```text output
-cua daemon start [OPTIONS]
-```
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-daemon-start--socket"></span>`--socket` | path | | Unix socket (default ~/.cua/cua.sock). |
-| <span id="cua-daemon-start--loopback"></span>`--loopback` | string | `127.0.0.1:0` | Loopback address (default 127.0.0.1:0; "off" disables). |
-| <span id="cua-daemon-start--foreground"></span>`--foreground` | boolean | `false` | Stay in the foreground. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-daemon-start"
-cua daemon start
-
-# In the foreground, for a service manager
-cua daemon start --foreground
-```
-
-## `cua daemon stop`
-
-Stop the daemon.
-
-```text output
-cua daemon stop [OPTIONS]
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-daemon-stop"
-cua daemon stop
-```
-
-## `cua daemon status`
-
-Show daemon status.
-
-```text output
-cua daemon status [OPTIONS]
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-daemon-status"
-cua daemon status
-```
-
-## `cua daemon mcp`
-
-Stdio MCP server backed by the daemon (started if needed): the Spaces contract tools plus the sandbox/computer/skills tools (same server as `cua mcp`).
-
-```text output
-cua daemon mcp [OPTIONS]
-```
-
-| Flag | Type | Default | Env var | Description |
-| --- | --- | --- | --- | --- |
-| <span id="cua-daemon-mcp--permissions"></span>`--permissions` | string | | `CUA_MCP_PERMISSIONS` | Comma-separated permissions or groups (default: all). |
-| <span id="cua-daemon-mcp--sandbox"></span>`--sandbox` | string | | `CUA_SANDBOX` | Default sandbox for computer tools. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-daemon-mcp"
-cua daemon mcp
-cua daemon mcp --permissions spaces:all
-```
-
-## Exit codes
-
-| Code | Meaning |
-| --- | --- |
-| `0` | Success. |
-| `1` | Failure, or `cua do` reported an error. |
-| `2` | Invalid argument, or an ambiguous sandbox name (qualify it: `local:NAME`). |
-| `3` | Not found: sandbox, window, skill or image (or an image not published yet). |
-| `4` | Not supported, or not configured (for example no provider credentials). |
-| `5` | No cua-spacesd answered, or a transport failure. |
-| `6` | Unauthenticated or permission denied (by Cua or your cloud account). |
-| `7` | Not enough free disk space (see `cua cache`). |
-| `130` | Cancelled (Ctrl-C during a create): what it made was removed. |
diff --git a/docs/content/docs/cua-cli/reference/cli/devices.mdx b/docs/content/docs/cua-cli/reference/cli/devices.mdx
deleted file mode 100644
index 47ccf8a547..0000000000
--- a/docs/content/docs/cua-cli/reference/cli/devices.mdx
+++ /dev/null
@@ -1,205 +0,0 @@
----
-title: "cua devices"
-description: "Enroll this device on the relay, approve, rename and revoke devices, and read the access log."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-cli
- Source: cua dump-docs --type cli
- Version: 0.5.0
-*/}
-
-| Command | Description |
-| --- | --- |
-| [`cua devices status`](#cua-devices-status) | This device: enrolled, waiting for approval, or not enrolled. |
-| [`cua devices enroll`](#cua-devices-enroll) | Enroll this device. |
-| [`cua devices approve`](#cua-devices-approve) | Approve a new device (or re-verify an expired one) from this enrolled device, by the code it shows or by its id. |
-| [`cua devices ls`](#cua-devices-ls) | Your devices and their state. |
-| [`cua devices rename`](#cua-devices-rename) | Rename a device. |
-| [`cua devices revoke`](#cua-devices-revoke) | Revoke a device: it can no longer list or reach your machines. |
-| [`cua devices audit`](#cua-devices-audit) | Who accessed what, and when: enrollments, device sessions, machine access (yours and by accounts you share with), sharing changes. |
-
-Every command also accepts the [global options](/cua-cli/reference/cli#global-options).
-
-<span id="cua-devices"></span>
-
-This device as a client of your cua.ai account on the relay: enroll (second factor), approve other devices, list, rename, revoke, and the audit log of who accessed what.
-
-```text output
-cua devices [OPTIONS] <COMMAND>
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-devices"
-cua devices enroll
-cua devices approve K7QX-M2RP
-cua devices ls
-cua devices audit
-```
-
-## `cua devices status`
-
-This device: enrolled, waiting for approval, or not enrolled.
-
-```text output
-cua devices status [OPTIONS]
-```
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-devices-status--relay"></span>`--relay` | string | | Relay URL (default $CUA_RELAY_URL, else the CUA_ENV relay, https://relay.cua.ai in production). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-devices-status"
-cua devices status
-```
-
-## `cua devices enroll`
-
-Enroll this device. Right after a fresh `cua auth login` it enrolls at once (and replaces this machine's older device key, if any); otherwise it shows a one-time code to approve from an enrolled device (`cua devices approve <code>` or the Cua Spaces app).
-
-```text output
-cua devices enroll [OPTIONS]
-```
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-devices-enroll--name"></span>`--name` | string | | Display name (default: the host name). |
-| <span id="cua-devices-enroll--relay"></span>`--relay` | string | | Relay URL. |
-| <span id="cua-devices-enroll--wait"></span>`--wait` | boolean | `false` | Wait (up to 10 minutes) until an enrolled device approves. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-devices-enroll"
-cua devices enroll
-cua devices enroll --name "work laptop" --wait
-```
-
-## `cua devices approve`
-
-Approve a new device (or re-verify an expired one) from this enrolled device, by the code it shows or by its id.
-
-```text output
-cua devices approve [OPTIONS] [CODE]
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<CODE>` | string | optional | The one-time code the new device shows, or its device id (`dev_…`, from `cua devices ls`). |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-devices-approve--device"></span>`--device` | string | | Or the device id (`cua devices ls`). |
-| <span id="cua-devices-approve--relay"></span>`--relay` | string | | Relay URL. |
-| <span id="cua-devices-approve--yes"></span>`--yes` | boolean | `false` | Do not ask for confirmation. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-devices-approve"
-cua devices approve K7QX-M2RP
-cua devices approve dev_0123456789abcdef01234567
-```
-
-## `cua devices ls`
-
-Your devices and their state.
-
-```text output
-cua devices ls [OPTIONS]
-```
-
-Alias: `cua devices list`.
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-devices-ls--relay"></span>`--relay` | string | | Relay URL. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-devices-ls"
-cua devices ls
-cua devices ls --json
-```
-
-## `cua devices rename`
-
-Rename a device.
-
-```text output
-cua devices rename [OPTIONS] <ID> <NAME>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<ID>` | string | required | Device id. |
-| `<NAME>` | string | required | New name. |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-devices-rename--relay"></span>`--relay` | string | | Relay URL. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-devices-rename"
-cua devices rename dev_0123456789abcdef01234567 "work phone"
-```
-
-## `cua devices revoke`
-
-Revoke a device: it can no longer list or reach your machines.
-
-```text output
-cua devices revoke [OPTIONS] <ID>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<ID>` | string | required | Device id. |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-devices-revoke--relay"></span>`--relay` | string | | Relay URL. |
-| <span id="cua-devices-revoke--yes"></span>`--yes` | boolean | `false` | Do not ask for confirmation. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-devices-revoke"
-cua devices revoke dev_0123456789abcdef01234567
-```
-
-## `cua devices audit`
-
-Who accessed what, and when: enrollments, device sessions, machine access (yours and by accounts you share with), sharing changes.
-
-```text output
-cua devices audit [OPTIONS]
-```
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-devices-audit--limit"></span>`--limit` | integer | `50` | Newest events to show. |
-| <span id="cua-devices-audit--relay"></span>`--relay` | string | | Relay URL. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-devices-audit"
-cua devices audit
-cua devices audit --limit 20 --json
-```
-
-## Exit codes
-
-| Code | Meaning |
-| --- | --- |
-| `0` | Success. |
-| `1` | Failure, or `cua do` reported an error. |
-| `2` | Invalid argument, or an ambiguous sandbox name (qualify it: `local:NAME`). |
-| `3` | Not found: sandbox, window, skill or image (or an image not published yet). |
-| `4` | Not supported, or not configured (for example no provider credentials). |
-| `5` | No cua-spacesd answered, or a transport failure. |
-| `6` | Unauthenticated or permission denied (by Cua or your cloud account). |
-| `7` | Not enough free disk space (see `cua cache`). |
-| `130` | Cancelled (Ctrl-C during a create): what it made was removed. |
diff --git a/docs/content/docs/cua-cli/reference/cli/doctor.mdx b/docs/content/docs/cua-cli/reference/cli/doctor.mdx
deleted file mode 100644
index f8db808f9f..0000000000
--- a/docs/content/docs/cua-cli/reference/cli/doctor.mdx
+++ /dev/null
@@ -1,100 +0,0 @@
----
-title: "cua doctor"
-description: "Check the host, an image and a sandbox guest, or eval parity between image variants."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-cli
- Source: cua dump-docs --type cli
- Version: 0.5.0
-*/}
-
-Every command also accepts the [global options](/cua-cli/reference/cli#global-options).
-
-<span id="cua-doctor"></span>
-
-Check the host, an image and a sandbox's guest in one report (`cua doctor [REF]`), or eval parity between two variants (`cua doctor parity A B`).
-
-```text output
-cua doctor [OPTIONS] [TARGET]
- cua doctor <COMMAND>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<TARGET>` | string | optional | Sandbox to check: `local:<name>`, `direct:<host:port>`, a bare name, or a spacesd URL. Omit for the host checks only. |
-
-| Flag | Type | Default | Env var | Description |
-| --- | --- | --- | --- | --- |
-| <span id="cua-doctor--image"></span>`--image` | string | | | Image to resolve for the image checks (default: the sandbox's). |
-| <span id="cua-doctor--arch"></span>`--arch` | string | | | Architecture to resolve the image for (default: the sandbox's, else this host's). |
-| <span id="cua-doctor--format"></span>`--format` | `human` \| `json` \| `junit` | `human` | | Output format (`--json` selects json). |
-| <span id="cua-doctor--effects"></span>`--effects` | `none` \| `virtual` | `none` | | Which guest checks may act on the guest. |
-| <span id="cua-doctor--only"></span>`--only` | string | | | Guest check ids or groups to run (comma separated). Repeatable. |
-| <span id="cua-doctor--skip"></span>`--skip` | string | | | Guest check ids or groups to skip. Repeatable. |
-| <span id="cua-doctor--timeout"></span>`--timeout` | integer | `240` | | Guest budget in seconds. |
-| <span id="cua-doctor--token"></span>`--token` | string | | `CUA_ENV_TOKEN` | spacesd token for a URL target (default: CUA_ENV_TOKEN). |
-| <span id="cua-doctor--shim"></span>`--shim` | string | | | Check an image without cua-spacesd through its own API instead: `computer-server=<url>`, `osworld=<url>` or `mcp=<url>`. |
-| <span id="cua-doctor--expect-manifest"></span>`--expect-manifest` | path | | | The image's claims (manifest JSON), for the shim or to override the guest's own. |
-| <span id="cua-doctor--out"></span>`--out` | path | | | Also write the JSON report here. |
-| <span id="cua-doctor--junit"></span>`--junit` | path | | | Also write JUnit XML here. |
-| <span id="cua-doctor--expect"></span>`--expect` | string | | | Fail unless the build running in the guest is the expected one: COMPONENT=WANT with WANT `sha256:<hex>` (the executable), `git:<sha>` or a version (repeatable). Components: cua-spacesd, cua-driver, or an overlay name. `cua sb create --overlay` prints the sha256 to pass. |
-| <span id="cua-doctor--strict"></span>`--strict` | boolean | `false` | | Fail on warnings and on required checks that were skipped. |
-| <span id="cua-doctor--no-host"></span>`--no-host` | boolean | `false` | | Skip the host checks. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-doctor"
-# Host checks only
-cua doctor
-
-# Host, image and guest checks for the sandbox dev
-cua doctor dev
-
-# CI: fail on warnings, write JUnit XML
-cua doctor local:dev --strict --junit doctor.xml
-```
-
-## `cua doctor parity`
-
-Eval parity between two variants of one image (rootfs vs containerDisk): doctor on both, fidelity diff, task outcomes.
-
-```text output
-cua doctor parity [OPTIONS] <A> <B>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<A>` | string | required | First variant (a sandbox ref or a spacesd URL). |
-| `<B>` | string | required | Second variant. |
-
-| Flag | Type | Default | Env var | Description |
-| --- | --- | --- | --- | --- |
-| <span id="cua-doctor-parity--token"></span>`--token` | string | | `CUA_ENV_TOKEN` | Token for URL targets (both), default CUA_ENV_TOKEN. |
-| <span id="cua-doctor-parity--token-b"></span>`--token-b` | string | | | Token for B when it differs from A's. |
-| <span id="cua-doctor-parity--tasks"></span>`--tasks` | string | `builtin:form,builtin:file` | | Tasks (`builtin:form`, `builtin:file`), comma separated. Repeatable. |
-| <span id="cua-doctor-parity--allow-diff"></span>`--allow-diff` | string | | | Extra fidelity keys allowed to differ. Repeatable. |
-| <span id="cua-doctor-parity--out"></span>`--out` | path | | | Write parity.json here. |
-| <span id="cua-doctor-parity--timeout"></span>`--timeout` | integer | `240` | | Doctor budget per variant, seconds. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-doctor-parity"
-cua doctor parity local:linux-rootfs local:linux-vm
-cua doctor parity local:linux-rootfs local:linux-vm --out parity.json
-```
-
-## Exit codes
-
-| Code | Meaning |
-| --- | --- |
-| `0` | Success. |
-| `1` | Failure, or `cua do` reported an error. |
-| `2` | Invalid argument, or an ambiguous sandbox name (qualify it: `local:NAME`). |
-| `3` | Not found: sandbox, window, skill or image (or an image not published yet). |
-| `4` | Not supported, or not configured (for example no provider credentials). |
-| `5` | No cua-spacesd answered, or a transport failure. |
-| `6` | Unauthenticated or permission denied (by Cua or your cloud account). |
-| `7` | Not enough free disk space (see `cua cache`). |
-| `130` | Cancelled (Ctrl-C during a create): what it made was removed. |
diff --git a/docs/content/docs/cua-cli/reference/cli/files-teleport-and-keys.mdx b/docs/content/docs/cua-cli/reference/cli/files-teleport-and-keys.mdx
new file mode 100644
index 0000000000..a0b2ffc595
--- /dev/null
+++ b/docs/content/docs/cua-cli/reference/cli/files-teleport-and-keys.mdx
@@ -0,0 +1,743 @@
+---
+title: "Files, teleport and keys"
+description: "Cua Volume files and sharing, moving an app session into a sandbox, and the Cua Keyvault."
+---
+
+{/*
+ AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
+ Generated by: pnpm --dir docs docs:generate:cua-cli
+ Source: cua dump-docs --type cli
+ Version: 0.5.0
+*/}
+
+| Command | Description |
+| --- | --- |
+| [`cua volume`](#cua-volume) | Cua Volume: the versioned volume every Space and agent shares (public/, agents/&lt;agent&gt;/, spaces/&lt;space&gt;/), its grants and audit. |
+| [`cua volume ls`](#cua-volume-ls) | List a folder (default: the root). |
+| [`cua volume cat`](#cua-volume-cat) | Print a file (or one of its versions) to stdout. |
+| [`cua volume put`](#cua-volume-put) | Write a file from a local file, or from stdin with `-`. |
+| [`cua volume rm`](#cua-volume-rm) | Delete a file (its history stays). |
+| [`cua volume history`](#cua-volume-history) | A file's versions, newest first. |
+| [`cua volume restore`](#cua-volume-restore) | Make an old version current again (a new version). |
+| [`cua volume grant`](#cua-volume-grant) | Let an agent or a Space read (or, with --rw, write) a folder beyond its defaults. |
+| [`cua volume revoke`](#cua-volume-revoke) | Revoke a grant. |
+| [`cua volume grants`](#cua-volume-grants) | The grants (live ones; --all includes expired and revoked). |
+| [`cua volume requests`](#cua-volume-requests) | Access requests agents filed, waiting for you. |
+| [`cua volume approve`](#cua-volume-approve) | Turn a request into a grant. |
+| [`cua volume deny`](#cua-volume-deny) | Decline a request. |
+| [`cua volume audit`](#cua-volume-audit) | The audit log, newest first, and whether its hash chain verified. |
+| [`cua volume mount`](#cua-volume-mount) | Show the drive as a volume (Finder on macOS, FUSE on Linux). |
+| [`cua volume unmount`](#cua-volume-unmount) | Turn the volume off (files still uploading land first). |
+| [`cua volume status`](#cua-volume-status) | The volume, sync across devices, and the block cache. |
+| [`cua volume config`](#cua-volume-config) | Which store the drive uses (fs, s3). |
+| [`cua volume config show`](#cua-volume-config-show) | The backend and bucket settings in effect (never keys). |
+| [`cua volume config set`](#cua-volume-config-set) | Choose the backend. |
+| [`cua volume config set-keys`](#cua-volume-config-set-keys) | Save S3 keys in the credential store: the access key id and the secret, one per line on stdin. |
+| [`cua teleport`](#cua-teleport) | Move a desktop app session (tabs, profile, sign-in) into a sandbox. |
+| [`cua teleport providers`](#cua-teleport-providers) | List the apps this machine can teleport (JSON). |
+| [`cua teleport manifest`](#cua-teleport-manifest) | Describe what teleporting an app would move (JSON). |
+| [`cua teleport push`](#cua-teleport-push) | Teleport an app session into a sandbox. |
+| [`cua keyvault`](#cua-keyvault) | The Cua Keyvault the daemon hosts: status, init, unlock, lock, saved passwords and approvals. |
+| [`cua keyvault status`](#cua-keyvault-status) | Whether the Keyvault exists and is unlocked, and which protectors (Touch ID with the OS key store, a passphrase) the daemon can use. |
+| [`cua keyvault init`](#cua-keyvault-init) | Create the Keyvault and print its recovery key once. |
+| [`cua keyvault unlock`](#cua-keyvault-unlock) | Unlock the Keyvault with the OS key store, or with its passphrase. |
+| [`cua keyvault lock`](#cua-keyvault-lock) | Lock the Keyvault (unlocking needs the OS key store or the passphrase again). |
+| [`cua keyvault import-passwords`](#cua-keyvault-import-passwords) | Import a browser's saved passwords into the Keyvault, one item per site. |
+| [`cua keyvault import-session`](#cua-keyvault-import-session) | Import a signed-in session (cookies, or a single-app session like Slack's) into the Keyvault, without delivering it anywhere. |
+| [`cua keyvault requests`](#cua-keyvault-requests) | Requests waiting for your approval (site logins, teleports). |
+| [`cua keyvault approve`](#cua-keyvault-approve) | Approve a waiting request (the daemon asks for Touch ID or your login password). |
+| [`cua keyvault deny`](#cua-keyvault-deny) | Decline a waiting request. |
+
+Every command also accepts the [global options](/cua-cli/reference/cli#global-options).
+
+## `cua volume`
+
+Cua Volume: the versioned volume every Space and agent shares (public/, agents/&lt;agent&gt;/, spaces/&lt;space&gt;/), its grants and audit. (`cua volume` still works for one release.).
+
+```text output
+cua volume [OPTIONS] <COMMAND>
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-volume"
+cua volume ls agents/
+cua volume cat agents/ada/memory/MEMORY.md
+cua volume put public/rules.md ./rules.md
+cua volume grant agent:researcher agents/writer/outputs/
+cua volume audit
+```
+
+### `cua volume ls`
+
+List a folder (default: the root).
+
+```text output
+cua volume ls [OPTIONS] [PATH]
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<PATH>` | string | optional | |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-volume-ls--as"></span>`--as` | string | | View the drive as this persistent agent does (`agent:ada` or `ada`). |
+| <span id="cua-volume-ls--space"></span>`--space` | string | | With --as: the Space the agent is in (its `spaces/<space>/` folder). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-volume-ls"
+cua volume ls
+cua volume ls agents/ada/
+cua volume ls --as agent:ada --space local:work
+```
+
+### `cua volume cat`
+
+Print a file (or one of its versions) to stdout.
+
+```text output
+cua volume cat [OPTIONS] <PATH>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<PATH>` | string | required | |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-volume-cat--version"></span>`--version` | string | | |
+| <span id="cua-volume-cat--as"></span>`--as` | string | | View the drive as this persistent agent does (`agent:ada` or `ada`). |
+| <span id="cua-volume-cat--space"></span>`--space` | string | | With --as: the Space the agent is in (its `spaces/<space>/` folder). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-volume-cat"
+cua volume cat agents/ada/memory/MEMORY.md
+cua volume cat public/rules.md --version 0001790683200000-1a2b3c4d
+```
+
+### `cua volume put`
+
+Write a file from a local file, or from stdin with `-`.
+
+```text output
+cua volume put [OPTIONS] <PATH> <SOURCE>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<PATH>` | string | required | |
+| `<SOURCE>` | string | required | Local file, or `-` for stdin. |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-volume-put--if-etag"></span>`--if-etag` | string | | Write only if the current version has this etag. |
+| <span id="cua-volume-put--as"></span>`--as` | string | | View the drive as this persistent agent does (`agent:ada` or `ada`). |
+| <span id="cua-volume-put--space"></span>`--space` | string | | With --as: the Space the agent is in (its `spaces/<space>/` folder). |
+| <span id="cua-volume-put--create-only"></span>`--create-only` | boolean | `false` | Write only if nothing is at the path yet. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-volume-put"
+cua volume put public/rules.md ./rules.md
+cua volume put public/rules.md -
+cua volume put agents/ada/inbox/brief.md ./brief.md --create-only
+```
+
+### `cua volume rm`
+
+Delete a file (its history stays).
+
+```text output
+cua volume rm [OPTIONS] <PATH>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<PATH>` | string | required | |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-volume-rm--if-etag"></span>`--if-etag` | string | | |
+| <span id="cua-volume-rm--as"></span>`--as` | string | | View the drive as this persistent agent does (`agent:ada` or `ada`). |
+| <span id="cua-volume-rm--space"></span>`--space` | string | | With --as: the Space the agent is in (its `spaces/<space>/` folder). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-volume-rm"
+cua volume rm spaces/local-work/scratch.txt
+```
+
+### `cua volume history`
+
+A file's versions, newest first.
+
+```text output
+cua volume history [OPTIONS] <PATH>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<PATH>` | string | required | |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-volume-history--as"></span>`--as` | string | | View the drive as this persistent agent does (`agent:ada` or `ada`). |
+| <span id="cua-volume-history--space"></span>`--space` | string | | With --as: the Space the agent is in (its `spaces/<space>/` folder). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-volume-history"
+cua volume history agents/ada/memory/MEMORY.md
+```
+
+### `cua volume restore`
+
+Make an old version current again (a new version).
+
+```text output
+cua volume restore [OPTIONS] <PATH> <VERSION>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<PATH>` | string | required | |
+| `<VERSION>` | string | required | |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-volume-restore--as"></span>`--as` | string | | View the drive as this persistent agent does (`agent:ada` or `ada`). |
+| <span id="cua-volume-restore--space"></span>`--space` | string | | With --as: the Space the agent is in (its `spaces/<space>/` folder). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-volume-restore"
+cua volume restore agents/ada/memory/MEMORY.md 0001790683200000-1a2b3c4d
+```
+
+### `cua volume grant`
+
+Let an agent or a Space read (or, with --rw, write) a folder beyond its defaults. Asks for Touch ID or your passphrase.
+
+```text output
+cua volume grant [OPTIONS] <PRINCIPAL> <PREFIX>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<PRINCIPAL>` | string | required | `agent:<name>` or `space:<id>`. |
+| `<PREFIX>` | string | required | A folder (ending in /) or one file. |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-volume-grant--for"></span>`--for` | string | | Lifetime (`30m`, `2h`, `7d`). Default: until revoked. |
+| <span id="cua-volume-grant--note"></span>`--note` | string | | A note shown next to the grant. |
+| <span id="cua-volume-grant--rw"></span>`--rw` | boolean | `false` | Read and write (default: read only). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-volume-grant"
+cua volume grant agent:researcher agents/writer/outputs/
+cua volume grant space:local-build public/datasets/ --rw --for 2h
+```
+
+### `cua volume revoke`
+
+Revoke a grant.
+
+```text output
+cua volume revoke [OPTIONS] <GRANT_ID>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<GRANT_ID>` | string | required | |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-volume-revoke"
+cua volume revoke 5f2c9a0b1d3e4f67
+```
+
+### `cua volume grants`
+
+The grants (live ones; --all includes expired and revoked).
+
+```text output
+cua volume grants [OPTIONS]
+```
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-volume-grants--all"></span>`--all` | boolean | `false` | |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-volume-grants"
+cua volume grants
+```
+
+### `cua volume requests`
+
+Access requests agents filed, waiting for you.
+
+```text output
+cua volume requests [OPTIONS]
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-volume-requests"
+cua volume requests
+```
+
+### `cua volume approve`
+
+Turn a request into a grant. Asks for Touch ID or your passphrase.
+
+```text output
+cua volume approve [OPTIONS] <REQUEST_ID>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<REQUEST_ID>` | string | required | |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-volume-approve--for"></span>`--for` | string | | |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-volume-approve"
+cua volume approve 5f2c9a0b1d3e4f67
+cua volume approve 5f2c9a0b1d3e4f67 --for 1d
+```
+
+### `cua volume deny`
+
+Decline a request.
+
+```text output
+cua volume deny [OPTIONS] <REQUEST_ID>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<REQUEST_ID>` | string | required | |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-volume-deny"
+cua volume deny 5f2c9a0b1d3e4f67
+```
+
+### `cua volume audit`
+
+The audit log, newest first, and whether its hash chain verified.
+
+```text output
+cua volume audit [OPTIONS]
+```
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-volume-audit--limit"></span>`--limit` | integer | `50` | |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-volume-audit"
+cua volume audit
+cua volume audit --limit 200 --json
+```
+
+### `cua volume mount`
+
+Show the drive as a volume (Finder on macOS, FUSE on Linux). Off until turned on; stays on across restarts.
+
+```text output
+cua volume mount [OPTIONS]
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-volume-mount"
+cua volume mount
+cua volume mount --json
+```
+
+### `cua volume unmount`
+
+Turn the volume off (files still uploading land first).
+
+```text output
+cua volume unmount [OPTIONS]
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-volume-unmount"
+cua volume unmount
+```
+
+### `cua volume status`
+
+The volume, sync across devices, and the block cache.
+
+```text output
+cua volume status [OPTIONS]
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-volume-status"
+cua volume status
+cua volume status --json
+```
+
+### `cua volume config`
+
+Which store the drive uses (fs, s3).
+
+```text output
+cua volume config [OPTIONS] <COMMAND>
+```
+
+#### `cua volume config show`
+
+The backend and bucket settings in effect (never keys).
+
+```text output
+cua volume config show [OPTIONS]
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-volume-config-show"
+cua volume config show
+```
+
+#### `cua volume config set`
+
+Choose the backend. Keys are never arguments: see set-keys.
+
+```text output
+cua volume config set [OPTIONS] --backend <BACKEND>
+```
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-volume-config-set--backend"></span>`--backend` | string | required | `fs` (default) or `s3`. |
+| <span id="cua-volume-config-set--endpoint"></span>`--endpoint` | string | | |
+| <span id="cua-volume-config-set--region"></span>`--region` | string | | |
+| <span id="cua-volume-config-set--bucket"></span>`--bucket` | string | | |
+| <span id="cua-volume-config-set--root"></span>`--root` | string | | A key prefix every drive key lives under. |
+| <span id="cua-volume-config-set--path-style"></span>`--path-style` | boolean | `false` | |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-volume-config-set"
+cua volume config set --backend fs
+cua volume config set --backend s3 --endpoint http://127.0.0.1:9000 --bucket cua-volume --path-style
+```
+
+#### `cua volume config set-keys`
+
+Save S3 keys in the credential store: the access key id and the secret, one per line on stdin.
+
+```text output
+cua volume config set-keys [OPTIONS]
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-volume-config-set-keys"
+cua volume config set-keys
+```
+
+## `cua teleport`
+
+Move a desktop app session (tabs, profile, sign-in) into a sandbox.
+
+```text output
+cua teleport [OPTIONS] <COMMAND>
+```
+
+### `cua teleport providers`
+
+List the apps this machine can teleport (JSON).
+
+```text output
+cua teleport providers [OPTIONS]
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-teleport-providers"
+cua teleport providers
+```
+
+### `cua teleport manifest`
+
+Describe what teleporting an app would move (JSON).
+
+```text output
+cua teleport manifest [OPTIONS] --app <APP>
+```
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-teleport-manifest--app"></span>`--app` | string | required | App: a bundle id or app name ("com.google.Chrome", "Slack", "claude-code"). |
+| <span id="cua-teleport-manifest--scope"></span>`--scope` | string | `full` | `tabs` (open tabs and session state) or `full` (the whole profile). |
+| <span id="cua-teleport-manifest--profile"></span>`--profile` | string | | Chrome profile to capture: a name ("Profile 1") or a path. |
+| <span id="cua-teleport-manifest--display-name"></span>`--display-name` | string | | Display name for the app (UI only). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-teleport-manifest"
+cua teleport manifest --app com.google.Chrome --scope tabs
+```
+
+### `cua teleport push`
+
+Teleport an app session into a sandbox.
+
+```text output
+cua teleport push [OPTIONS] --app <APP>
+```
+
+| Flag | Short | Type | Default | Env var | Description |
+| --- | --- | --- | --- | --- | --- |
+| <span id="cua-teleport-push--app"></span>`--app` | | string | required | | App: a bundle id or app name ("com.google.Chrome", "Slack", "claude-code"). |
+| <span id="cua-teleport-push--scope"></span>`--scope` | | string | `full` | | `tabs` (open tabs and session state) or `full` (the whole profile). |
+| <span id="cua-teleport-push--profile"></span>`--profile` | | string | | | Chrome profile to capture: a name ("Profile 1") or a path. |
+| <span id="cua-teleport-push--display-name"></span>`--display-name` | | string | | | Display name for the app (UI only). |
+| <span id="cua-teleport-push--sandbox"></span>`--sandbox` | `-s` | string | | | Destination sandbox (name). |
+| <span id="cua-teleport-push--url"></span>`--url` | | string | | | Destination cua-spacesd URL instead of a sandbox. |
+| <span id="cua-teleport-push--token"></span>`--token` | | string | | `CUA_ENV_TOKEN` | Token for `--url`. |
+| <span id="cua-teleport-push--include"></span>`--include` | | string | | | Send exactly this manifest item (repeatable; see `manifest`). Default: the provider's default selection, which leaves credentials-heavy or bulky items (cookies, transcripts) out unless named here. |
+| <span id="cua-teleport-push--all"></span>`--all` | | boolean | `false` | | Send every item the scope offers. |
+| <span id="cua-teleport-push--no-launch"></span>`--no-launch` | | boolean | `false` | | Do not launch the app in the sandbox after importing. |
+| <span id="cua-teleport-push--progress"></span>`--progress` | | boolean | `false` | | Print `progress <sent> <total>` lines while uploading. |
+| <span id="cua-teleport-push--relay-plaintext-ack"></span>`--relay-plaintext-ack` | | boolean | `false` | | Send over a `relay:` destination even though this Space's image predates end-to-end sealing (S1): without this, such a send refuses before reading or uploading anything. Set it only after you understand that relay.cua.ai (or a self-hosted cua-relay) could read this delivery in the clear; local and direct destinations are unaffected either way. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-teleport-push"
+# Chrome's open tabs into the sandbox dev
+cua teleport push --app com.google.Chrome --scope tabs --sandbox dev
+
+# The whole Slack profile, every item
+cua teleport push --app Slack --sandbox dev --all
+```
+
+## `cua keyvault`
+
+The Cua Keyvault the daemon hosts: status, init, unlock, lock, saved passwords and approvals. Passphrases are prompted for (or read from stdin), never arguments.
+
+```text output
+cua keyvault [OPTIONS] <COMMAND>
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-keyvault"
+cua keyvault status
+cua keyvault init --passphrase
+cua keyvault unlock --passphrase
+cua keyvault import-passwords --browser chrome
+cua keyvault requests
+cua keyvault approve <request-id>
+cua keyvault lock
+```
+
+### `cua keyvault status`
+
+Whether the Keyvault exists and is unlocked, and which protectors (Touch ID with the OS key store, a passphrase) the daemon can use.
+
+```text output
+cua keyvault status [OPTIONS]
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-keyvault-status"
+cua keyvault status
+cua keyvault status --json
+```
+
+### `cua keyvault init`
+
+Create the Keyvault and print its recovery key once. Uses the OS key store (Touch ID confirms) unless --passphrase or --passphrase-stdin.
+
+```text output
+cua keyvault init [OPTIONS]
+```
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-keyvault-init--passphrase"></span>`--passphrase` | boolean | `false` | Use a passphrase, typed at a terminal prompt with echo off. |
+| <span id="cua-keyvault-init--passphrase-stdin"></span>`--passphrase-stdin` | boolean | `false` | Use a passphrase read from the first line of stdin (scripts). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-keyvault-init"
+# The OS key store (the signed Cua daemon only)
+cua keyvault init
+
+# A passphrase, typed twice at a prompt
+cua keyvault init --passphrase
+
+# Scripts: the passphrase is the first line of stdin
+cua keyvault init --passphrase-stdin
+```
+
+### `cua keyvault unlock`
+
+Unlock the Keyvault with the OS key store, or with its passphrase.
+
+```text output
+cua keyvault unlock [OPTIONS]
+```
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-keyvault-unlock--passphrase"></span>`--passphrase` | boolean | `false` | Use a passphrase, typed at a terminal prompt with echo off. |
+| <span id="cua-keyvault-unlock--passphrase-stdin"></span>`--passphrase-stdin` | boolean | `false` | Use a passphrase read from the first line of stdin (scripts). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-keyvault-unlock"
+cua keyvault unlock
+cua keyvault unlock --passphrase
+```
+
+### `cua keyvault lock`
+
+Lock the Keyvault (unlocking needs the OS key store or the passphrase again).
+
+```text output
+cua keyvault lock [OPTIONS]
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-keyvault-lock"
+cua keyvault lock
+```
+
+### `cua keyvault import-passwords`
+
+Import a browser's saved passwords into the Keyvault, one item per site. They stay sealed: agents sign in with them through `request_site_login` after you approve, and never see them. The daemon asks for Touch ID or your login password.
+
+```text output
+cua keyvault import-passwords [OPTIONS]
+```
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-keyvault-import-passwords--browser"></span>`--browser` | `chrome` | `chrome` | The browser to import from. |
+| <span id="cua-keyvault-import-passwords--profile"></span>`--profile` | string | | The browser profile (name or path); default: the default profile. |
+| <span id="cua-keyvault-import-passwords--site"></span>`--site` | string | | Only this site (a registrable domain such as github.com). Repeatable; default: every saved site. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-keyvault-import-passwords"
+cua keyvault import-passwords --browser chrome
+cua keyvault import-passwords --browser chrome --site github.com --site example.com
+cua keyvault import-passwords --browser chrome --profile "Profile 1"
+```
+
+### `cua keyvault import-session`
+
+Import a signed-in session (cookies, or a single-app session like Slack's) into the Keyvault, without delivering it anywhere. A later `cua teleport push --sandbox NAME` (or the review sheet's "Save to Keyvault") can deliver it; it stays sealed until then. The daemon asks for Touch ID or your login password.
+
+```text output
+cua keyvault import-session [OPTIONS] --app <APP>
+```
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-keyvault-import-session--app"></span>`--app` | string | required | The app to import from (a teleport provider id: `chrome`, `firefox`, `slack`, ...; `cua teleport providers` lists every one on this machine). |
+| <span id="cua-keyvault-import-session--profile"></span>`--profile` | string | | The browser profile (name or path); default: the default profile. Ignored for a single-app provider (Slack, Discord, ...). |
+| <span id="cua-keyvault-import-session--site"></span>`--site` | string | | Only this site's cookies (a registrable domain such as github.com). Repeatable; a browser with none named imports every site's cookies. Ignored (the whole session is one item) for a single-app provider. |
+| <span id="cua-keyvault-import-session--include-storage"></span>`--include-storage` | boolean | `false` | Also carry each named site's localStorage / IndexedDB origins. |
+| <span id="cua-keyvault-import-session--include-passwords"></span>`--include-passwords` | boolean | `false` | Also carry each named site's saved passwords, as part of this same session item (`cua keyvault import-passwords` keeps them as their own items instead, one per site). |
+| <span id="cua-keyvault-import-session--session-only"></span>`--session-only` | boolean | `false` | Only session cookies: drop every persistent cookie. |
+| <span id="cua-keyvault-import-session--drop-long-lived"></span>`--drop-long-lived` | boolean | `false` | Drop persistent cookies that expire more than 30 days out (long-lived refresh tokens), keeping short sessions. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-keyvault-import-session"
+cua keyvault import-session --app chrome
+cua keyvault import-session --app chrome --site github.com --site example.com
+cua keyvault import-session --app firefox --profile "Profile 1"
+cua keyvault import-session --app slack
+```
+
+### `cua keyvault requests`
+
+Requests waiting for your approval (site logins, teleports).
+
+```text output
+cua keyvault requests [OPTIONS]
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-keyvault-requests"
+cua keyvault requests
+cua keyvault requests --json
+```
+
+### `cua keyvault approve`
+
+Approve a waiting request (the daemon asks for Touch ID or your login password). A site login is approved for one sign-in.
+
+```text output
+cua keyvault approve [OPTIONS] <ID>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<ID>` | string | required | The request id (`cua keyvault requests`). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-keyvault-approve"
+cua keyvault approve 5f2c9a0e
+```
+
+### `cua keyvault deny`
+
+Decline a waiting request.
+
+```text output
+cua keyvault deny [OPTIONS] <ID>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<ID>` | string | required | The request id. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-keyvault-deny"
+cua keyvault deny 5f2c9a0e
+```
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| `0` | Success. |
+| `1` | Failure, or `cua do` reported an error. |
+| `2` | Invalid argument, or an ambiguous sandbox name (qualify it: `local:NAME`). |
+| `3` | Not found: sandbox, window, skill or image (or an image not published yet). |
+| `4` | Not supported, or not configured (for example no provider credentials). |
+| `5` | No cua-spacesd answered, or a transport failure. |
+| `6` | Unauthenticated or permission denied (by Cua or your cloud account). |
+| `7` | Not enough free disk space (see `cua cache`). |
+| `130` | Cancelled (Ctrl-C during a create): what it made was removed. |
diff --git a/docs/content/docs/cua-cli/reference/cli/host.mdx b/docs/content/docs/cua-cli/reference/cli/host.mdx
deleted file mode 100644
index 6c5857bf31..0000000000
--- a/docs/content/docs/cua-cli/reference/cli/host.mdx
+++ /dev/null
@@ -1,260 +0,0 @@
----
-title: "cua host"
-description: "Set this machine up for unattended access."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-cli
- Source: cua dump-docs --type cli
- Version: 0.5.0
-*/}
-
-| Command | Description |
-| --- | --- |
-| [`cua host setup`](#cua-host-setup) | Set this machine up for unattended access: install cua-spacesd as a service that joins the cua.ai relay as your account (default) or serves on a direct ip:port. |
-| [`cua host pair`](#cua-host-pair) | Make a one-time code (with a link and the install command) that adds another computer to your account: run the command it prints on that computer. |
-| [`cua host config`](#cua-host-config) | Show or change what this machine shares: its own desktop, and whether it creates Spaces for your other devices. |
-| [`cua host status`](#cua-host-status) | Show whether this machine is set up, the service, and who is connected. |
-| [`cua host stop`](#cua-host-stop) | Stop sharing: disconnect everyone and refuse new connections. |
-| [`cua host start`](#cua-host-start) | Start sharing again after `stop`. |
-| [`cua host share`](#cua-host-share) | Share a relay machine (this one, or `--machine`) with other cua.ai accounts (id or verified email). |
-| [`cua host unshare`](#cua-host-unshare) | Stop sharing a relay machine with accounts; their open connections are cut. |
-| [`cua host remove`](#cua-host-remove) | Unregister from the relay, uninstall the service and delete the host configuration (asks first). |
-
-Every command also accepts the [global options](/cua-cli/reference/cli#global-options).
-
-<span id="cua-host"></span>
-
-Unattended access to this machine (setup, status, stop, start, remove).
-
-```text output
-cua host [OPTIONS] <COMMAND>
-```
-
-## `cua host setup`
-
-Set this machine up for unattended access: install cua-spacesd as a service that joins the cua.ai relay as your account (default) or serves on a direct ip:port.
-
-```text output
-cua host setup [OPTIONS]
-```
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-host-setup--relay"></span>`--relay` | string | | Relay URL (default $CUA_RELAY_URL, else the CUA_ENV relay, https://relay.cua.ai in production). |
-| <span id="cua-host-setup--pair"></span>`--pair` | string | | Join with a one-time pairing code (or add-machine link) made in the Cua Spaces app or with `cua host pair`, instead of signing in here. The machine joins the account (or team) that made it. |
-| <span id="cua-host-setup--direct"></span>`--direct` | string | | Serve directly on ip:port with a local env token (LAN / port-forwarded) instead of joining a relay. |
-| <span id="cua-host-setup--name"></span>`--name` | string | | Display name (default: the host name). |
-| <span id="cua-host-setup--allow"></span>`--allow` | string | | Also allow this account (id or email). Repeatable. |
-| <span id="cua-host-setup--driver-bin"></span>`--driver-bin` | path | | cua-spacesd binary (default $CUA_SPACESD_BIN, a bundled one, or the release download). |
-| <span id="cua-host-setup--runner"></span>`--runner` | string | `auto` | auto \| systemd \| launchd \| windows-task \| process. |
-| <span id="cua-host-setup--profile"></span>`--profile` | `desktop` \| `spare` | `desktop` | What this machine is for: `desktop` (share this desktop; the default) or `spare` (do not share the desktop; provide Spaces). |
-| <span id="cua-host-setup--max-spaces"></span>`--max-spaces` | integer | | Provided Spaces at once (default 4; 0: no limit). |
-| <span id="cua-host-setup--remote"></span>`--remote` | boolean | `false` | When sign-in is needed, use a device code to approve it in a browser on another machine. The account session is not saved. |
-| <span id="cua-host-setup--desktop"></span>`--desktop` | boolean | `false` | Share this machine's own desktop as a Space. |
-| <span id="cua-host-setup--no-desktop"></span>`--no-desktop` | boolean | `false` | Do not share this machine's own desktop (screen, input, shell, files): relayed callers reach only the Spaces it provides. |
-| <span id="cua-host-setup--provide-spaces"></span>`--provide-spaces` | boolean | `false` | Create Spaces for your enrolled devices on this machine's runtimes (Lume macOS VMs, Docker Linux containers). |
-| <span id="cua-host-setup--no-provide-spaces"></span>`--no-provide-spaces` | boolean | `false` | Do not create Spaces for other devices. |
-| <span id="cua-host-setup--allow-any-address"></span>`--allow-any-address` | boolean | `false` | With --direct and Spaces: take host calls, and connections to the Spaces this machine forwards, from any address (and allow a public --direct address). By default only loopback, Tailscale and private LAN addresses may. The direct listener is plaintext and its token is a shell on this machine: prefer Tailscale. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-host-setup"
-# Join the cua.ai relay as your account (shares this desktop)
-cua host setup
-
-# A spare machine: do not share its desktop, run Spaces for your devices
-cua host setup --profile spare --name "Mac mini (spare)"
-cua host setup --no-desktop --provide-spaces
-
-# Serve on the LAN instead of the relay
-cua host setup --direct 0.0.0.0:3211 --name studio-mac
-
-# A spare Mac on your tailnet that runs Spaces, without the relay (prints the command that adds it on your laptop)
-cua host setup --direct 100.101.102.103:3211 --profile spare
-
-# Add this machine with a one-time code from the Cua Spaces app (Add a machine) or `cua host pair`: no sign-in needed here
-cua host setup --pair K7QM-4XPB-2RHD
-```
-
-## `cua host pair`
-
-Make a one-time code (with a link and the install command) that adds another computer to your account: run the command it prints on that computer. Codes work once and expire (30 minutes by default). Run from an enrolled device.
-
-```text output
-cua host pair [OPTIONS]
-```
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-host-pair--team"></span>`--team` | string | | Add the machine to this team (id, alias or name; owner or admin): waits until the machine joins, then makes it a team machine. |
-| <span id="cua-host-pair--name"></span>`--name` | string | | Name the machine gets (default: its own host name). |
-| <span id="cua-host-pair--expires"></span>`--expires` | integer | `30` | Minutes until the code expires (1 to 1440). |
-| <span id="cua-host-pair--revoke"></span>`--revoke` | string | | Revoke an unused code by id (`pc_…`). |
-| <span id="cua-host-pair--relay"></span>`--relay` | string | | Relay URL (default $CUA_RELAY_URL, else the CUA_ENV relay, https://relay.cua.ai in production). |
-| <span id="cua-host-pair--no-wait"></span>`--no-wait` | boolean | `false` | With --team: print the code and exit instead of waiting; add the machine later with `cua team add-machine <team> relay:<id>`. |
-| <span id="cua-host-pair--list"></span>`--list` | boolean | `false` | List your codes (used, unused, revoked, expired) instead. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-host-pair"
-cua host pair
-cua host pair --name build-box --expires 60
-cua host pair --list
-cua host pair --revoke pc_0123456789abcdef
-
-# Add the machine to a team: waits for it to join, then adds it
-cua host pair --team AIGIS
-```
-
-## `cua host config`
-
-Show or change what this machine shares: its own desktop, and whether it creates Spaces for your other devices.
-
-```text output
-cua host config [OPTIONS]
-```
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-host-config--desktop"></span>`--desktop` | `on` \| `off` | | Share this machine's own desktop: on \| off. |
-| <span id="cua-host-config--provide-spaces"></span>`--provide-spaces` | `on` \| `off` | | Create Spaces for your enrolled devices: on \| off. |
-| <span id="cua-host-config--max-spaces"></span>`--max-spaces` | integer | | Provided Spaces at once (0: no limit). |
-| <span id="cua-host-config--max-macos-vms"></span>`--max-macos-vms` | integer | | macOS VMs at once, 0 to 2 (Apple's license allows two per Mac). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-host-config"
-cua host config
-
-# Stop sharing this desktop; keep providing Spaces
-cua host config --desktop off --provide-spaces on
-cua host config --max-spaces 6
-```
-
-## `cua host status`
-
-Show whether this machine is set up, the service, and who is connected.
-
-```text output
-cua host status [OPTIONS]
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-host-status"
-cua host status
-```
-
-## `cua host stop`
-
-Stop sharing: disconnect everyone and refuse new connections.
-
-```text output
-cua host stop [OPTIONS]
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-host-stop"
-cua host stop
-```
-
-## `cua host start`
-
-Start sharing again after `stop`.
-
-```text output
-cua host start [OPTIONS]
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-host-start"
-cua host start
-```
-
-## `cua host share`
-
-Share a relay machine (this one, or `--machine`) with other cua.ai accounts (id or verified email). Run from an enrolled device; every change is in the owner's audit log (`cua devices audit`).
-
-```text output
-cua host share [OPTIONS] <WHO>...
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<WHO>...` | string | required | Accounts to add. Repeatable. Repeatable. |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-host-share--machine"></span>`--machine` | string | | Machine id (default: this machine). |
-| <span id="cua-host-share--relay"></span>`--relay` | string | | Relay URL (default: the one this machine joined, else $CUA_RELAY_URL / https://relay.cua.ai). |
-| <span id="cua-host-share--yes"></span>`--yes` | boolean | `false` | Do not ask for confirmation. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-host-share"
-cua host share [email protected]
-cua host share [email protected] --machine 0123abcd4567ef89 --yes
-```
-
-## `cua host unshare`
-
-Stop sharing a relay machine with accounts; their open connections are cut.
-
-```text output
-cua host unshare [OPTIONS] <WHO>...
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<WHO>...` | string | required | Accounts to remove. Repeatable. Repeatable. |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-host-unshare--machine"></span>`--machine` | string | | Machine id (default: this machine). |
-| <span id="cua-host-unshare--relay"></span>`--relay` | string | | Relay URL. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-host-unshare"
-cua host unshare [email protected]
-```
-
-## `cua host remove`
-
-Unregister from the relay, uninstall the service and delete the host configuration (asks first).
-
-```text output
-cua host remove [OPTIONS]
-```
-
-| Flag | Short | Type | Default | Description |
-| --- | --- | --- | --- | --- |
-| <span id="cua-host-remove--force"></span>`--force` | `-f` | boolean | `false` | Skip the confirmation prompt. Required when there is no terminal to ask on (scripts, agents): without it nothing is removed. |
-| <span id="cua-host-remove--uninstalling"></span>`--uninstalling` | | boolean | `false` | For an uninstall of Cua Spaces: turns off the Spaces this machine provides and takes them off the relay too, instead of refusing while it provides any. The Spaces and their data stay on this machine. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-host-remove"
-cua host remove
-
-# Without the prompt (required in scripts and agents)
-cua host remove --force
-```
-
-## Exit codes
-
-| Code | Meaning |
-| --- | --- |
-| `0` | Success. |
-| `1` | Failure, or `cua do` reported an error. |
-| `2` | Invalid argument, or an ambiguous sandbox name (qualify it: `local:NAME`). |
-| `3` | Not found: sandbox, window, skill or image (or an image not published yet). |
-| `4` | Not supported, or not configured (for example no provider credentials). |
-| `5` | No cua-spacesd answered, or a transport failure. |
-| `6` | Unauthenticated or permission denied (by Cua or your cloud account). |
-| `7` | Not enough free disk space (see `cua cache`). |
-| `130` | Cancelled (Ctrl-C during a create): what it made was removed. |
diff --git a/docs/content/docs/cua-cli/reference/cli/image.mdx b/docs/content/docs/cua-cli/reference/cli/image.mdx
deleted file mode 100644
index d9c11c0667..0000000000
--- a/docs/content/docs/cua-cli/reference/cli/image.mdx
+++ /dev/null
@@ -1,348 +0,0 @@
----
-title: "cua image"
-description: "Pull, build and push OCI images; list the image catalog."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-cli
- Source: cua dump-docs --type cli
- Version: 0.5.0
-*/}
-
-| Command | Description |
-| --- | --- |
-| [`cua image`](#cua-image) | Images: local OCI pull/build/push. |
-| [`cua image pull`](#cua-image-pull) | Pull an image into the local cache. |
-| [`cua image build`](#cua-image-build) | Build an image from an images.cua.ai/v1alpha1 Image resource (JSON). |
-| [`cua image push`](#cua-image-push) | Copy an image (host architecture) to another registry reference. |
-| [`cua images`](#cua-images) | The sandbox image catalog (the images the docs list): which exist, their variants, and which ship cua-spacesd and a browser. |
-| [`cua images ls`](#cua-images-ls) | List the catalog: ref, OS, container or VM, local runtime, cua-spacesd, browsers, summary. |
-| [`cua images info`](#cua-images-info) | Show one catalog entry (a ref or an alias such as `linux`). |
-| [`cua images build`](#cua-images-build) | Build a sandbox image definition (a libs/images directory): the rootfs, the bootable VM disk and the KubeVirt containerDisk. |
-| [`cua images pack`](#cua-images-pack) | Pack the disks `cua images build --outputs disk` wrote as KubeVirt containerDisks `<repo>:<tag>-<arch>` (push, or load into docker). |
-| [`cua images publish`](#cua-images-publish) | Publish a built image as immutable pins `<series>-<stamp>` and `<series>-disk-<stamp>`, refusing any that exist. |
-| [`cua images release`](#cua-images-release) | Run an image's release pipeline (its release.json): build, doctor lanes, content digest, save; with --publish push, publish pins and verify; with --promote move the floating tags. |
-| [`cua images promote`](#cua-images-promote) | Move a series' moving tags (`edge`, `edge-disk`) to the pins a `cua images publish` record names, after the gates passed. |
-
-Every command also accepts the [global options](/cua-cli/reference/cli#global-options).
-
-## `cua image`
-
-Images: local OCI pull/build/push.
-
-```text output
-cua image [OPTIONS] <COMMAND>
-```
-
-Alias: `cua img`.
-
-### `cua image pull`
-
-Pull an image into the local cache.
-
-```text output
-cua image pull [OPTIONS] <REFERENCE>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<REFERENCE>` | string | required | Image reference or alias. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-image-pull"
-cua image pull linux
-cua image pull ghcr.io/trycua/linux:24.04
-```
-
-### `cua image build`
-
-Build an image from an images.cua.ai/v1alpha1 Image resource (JSON).
-
-```text output
-cua image build [OPTIONS] --base <BASE> <SPEC>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<SPEC>` | path | required | Image resource file (JSON). |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-image-build--base"></span>`--base` | string | required | Base image (`container:<ref>`, `vm:<ref>`, `disk:<path>`). |
-| <span id="cua-image-build--push"></span>`--push` | string | | Push the result to this reference. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-image-build"
-cua image build image.json --base container:ubuntu:24.04
-cua image build image.json --base container:ubuntu:24.04 --push ghcr.io/acme/desktop:1
-```
-
-### `cua image push`
-
-Copy an image (host architecture) to another registry reference.
-
-```text output
-cua image push [OPTIONS] <REFERENCE> <DESTINATION>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<REFERENCE>` | string | required | Source image reference or alias. |
-| `<DESTINATION>` | string | required | Destination registry reference. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-image-push"
-cua image push linux ghcr.io/acme/desktop:1
-```
-
-## `cua images`
-
-The sandbox image catalog (the images the docs list): which exist, their variants, and which ship cua-spacesd and a browser.
-
-```text output
-cua images [OPTIONS] <COMMAND>
-```
-
-### `cua images ls`
-
-List the catalog: ref, OS, container or VM, local runtime, cua-spacesd, browsers, summary.
-
-```text output
-cua images ls [OPTIONS]
-```
-
-Alias: `cua images list`.
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-images-ls--os"></span>`--os` | string | | Only this OS: linux, windows or macos. |
-| <span id="cua-images-ls--all"></span>`--all` | boolean | `false` | Include unpublished entries (benchmark images). |
-| <span id="cua-images-ls--browser"></span>`--browser` | boolean | `false` | Only images with a browser the cua-driver browser tools drive. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-images-ls"
-cua images ls
-
-# Images whose browser the cua-driver browser tools drive
-cua images ls --browser
-cua images ls --all --json
-```
-
-### `cua images info`
-
-Show one catalog entry (a ref or an alias such as `linux`).
-
-```text output
-cua images info [OPTIONS] <REFERENCE>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<REFERENCE>` | string | required | Image ref or alias. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-images-info"
-cua images info linux
-```
-
-### `cua images build`
-
-Build a sandbox image definition (a libs/images directory): the rootfs, the bootable VM disk and the KubeVirt containerDisk.
-
-Outputs: rootfs &lt;repo&gt;:docker-&lt;tag&gt;-&lt;arch&gt;; disk &lt;out&gt;/&lt;name&gt;/&lt;arch&gt;/disk.img;
-containerdisk &lt;repo&gt;:&lt;tag&gt;-&lt;arch&gt;. --push pushes the outputs the image.json
-lists (a VM-only image never pushes its rootfs).
-
-```text output
-cua images build [OPTIONS] <DIR>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<DIR>` | path | required | Image definition directory (Dockerfile, image.json). |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-images-build--platform"></span>`--platform` | string | | Platforms, comma separated (default: the host's, or the image's only one). |
-| <span id="cua-images-build--tag"></span>`--tag` | string | `local` | Tag for the per-arch outputs. |
-| <span id="cua-images-build--repo"></span>`--repo` | string | | Repository (default: image.json `repository`, else cua-e2e-local/&lt;name&gt;). |
-| <span id="cua-images-build--outputs"></span>`--outputs` | string | `rootfs` | Outputs: rootfs, disk, containerdisk (comma separated). |
-| <span id="cua-images-build--build-arg"></span>`--build-arg` | string | | Docker build argument KEY=VALUE (repeatable). |
-| <span id="cua-images-build--build-context"></span>`--build-context` | string | | Named build context NAME=PATH (repeatable). |
-| <span id="cua-images-build--label"></span>`--label` | string | | Extra rootfs label KEY=VALUE (repeatable). |
-| <span id="cua-images-build--out"></span>`--out` | path | | Where disks go (default: $CUA_IMAGES_OUT or ~/.cache/cua-images). |
-| <span id="cua-images-build--disk-size"></span>`--disk-size` | string | `20G` | Virtual size of the disk. |
-| <span id="cua-images-build--target"></span>`--target` | string | | Dockerfile stage to build (a tier: `slim`, `full`); disks go to &lt;out&gt;/&lt;name&gt;-&lt;target&gt;/&lt;arch&gt;. Default: the Dockerfile's last stage. |
-| <span id="cua-images-build--push"></span>`--push` | boolean | `false` | Push the published outputs. |
-| <span id="cua-images-build--dry-run"></span>`--dry-run` | boolean | `false` | Print the steps without running them. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-images-build"
-cua images build libs/images/omarchy --outputs rootfs,disk
-cua images build libs/images/omarchy --tag build-1a2b3c4d --outputs containerdisk --push
-cua images build libs/images/linux --target slim --tag 24.04-slim-local --outputs rootfs,disk
-cua images build libs/images/linux --platform linux/amd64,linux/arm64 --dry-run
-```
-
-### `cua images pack`
-
-Pack the disks `cua images build --outputs disk` wrote as KubeVirt containerDisks `<repo>:<tag>-<arch>` (push, or load into docker).
-
-Packs exactly the disk the doctor checked, so the pushed bytes are the
-tested ones.
-
-```text output
-cua images pack [OPTIONS] <DIR>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<DIR>` | path | required | Image definition directory. |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-images-pack--platform"></span>`--platform` | string | | Platforms, comma separated (default: the host's, or the image's only one). |
-| <span id="cua-images-pack--tag"></span>`--tag` | string | `local` | Tag for the per-arch containerDisks. |
-| <span id="cua-images-pack--repo"></span>`--repo` | string | | Repository (default: image.json `repository`, else cua-e2e-local/&lt;name&gt;). |
-| <span id="cua-images-pack--out"></span>`--out` | path | | Where the disks are (default: $CUA_IMAGES_OUT or ~/.cache/cua-images). |
-| <span id="cua-images-pack--target"></span>`--target` | string | | The `--target` the disks were built with (their &lt;name&gt;-&lt;target&gt; dir). |
-| <span id="cua-images-pack--push"></span>`--push` | boolean | `false` | Push instead of loading into docker. |
-| <span id="cua-images-pack--dry-run"></span>`--dry-run` | boolean | `false` | Print what would be packed. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-images-pack"
-cua images pack libs/images/omarchy --tag ci-1a2b3c4d --push --json
-```
-
-### `cua images publish`
-
-Publish a built image as immutable pins `<series>-<stamp>` and `<series>-disk-<stamp>`, refusing any that exist. Moves nothing.
-
-Reads the per-arch images `cua images build --tag TAG --push` wrote
-(&lt;repo&gt;:&lt;tag&gt;-&lt;arch&gt;, and &lt;repo&gt;:docker-&lt;tag&gt;-&lt;arch&gt; when the image has a rootfs
-output). Writes the record `cua images promote` takes.
-
-```text output
-cua images publish [OPTIONS] --tag <TAG> --series <SERIES> <DIR>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<DIR>` | path | required | Image definition directory. |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-images-publish--tag"></span>`--tag` | string | required | The build tag the per-arch images were pushed under. |
-| <span id="cua-images-publish--series"></span>`--series` | string | required | Series / channel (`edge`, `24.04`). |
-| <span id="cua-images-publish--stamp"></span>`--stamp` | string | | Pin stamp `<yyyymmdd>-<sha7>` (default: today and git HEAD). |
-| <span id="cua-images-publish--repo"></span>`--repo` | string | | Repository (default: image.json `repository`). |
-| <span id="cua-images-publish--platform"></span>`--platform` | string | | Platforms (default: image.json `platforms`). |
-| <span id="cua-images-publish--annotation"></span>`--annotation` | string | | Extra index annotation KEY=VALUE (repeatable). |
-| <span id="cua-images-publish--descriptor-annotation"></span>`--descriptor-annotation` | string | | Annotation on one child's descriptor, VARIANT/ARCH:KEY=VALUE (`rootfs/amd64:ai.cua.doctor.status=pass`; repeatable). |
-| <span id="cua-images-publish--record"></span>`--record` | path | | Write the publish record (JSON) here. |
-| <span id="cua-images-publish--dry-run"></span>`--dry-run` | boolean | `false` | Resolve and print, push nothing. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-images-publish"
-cua images publish libs/images/omarchy --tag build-1a2b3c4d --series edge --record pins.json
-cua images publish libs/images/linux --tag build-20260925-1a2b3c4 --series 24.04 --descriptor-annotation rootfs/amd64:ai.cua.doctor.status=pass
-cua images publish libs/images/omarchy --tag build-1a2b3c4d --series edge --dry-run
-```
-
-### `cua images release`
-
-Run an image's release pipeline (its release.json): build, doctor lanes, content digest, save; with --publish push, publish pins and verify; with --promote move the floating tags. The same command runs locally and in CI.
-
-Phases: prepare, build, gate (doctor lanes), stage, push, publish, verify,
-promote. Push refuses unless every required gate passed (this run, or a
-state-*.json merged from other jobs in &lt;work&gt;/evidence). Evidence, logs and
-the summary go to &lt;work&gt;/evidence (a plain directory CI uploads as-is).
-
-```text output
-cua images release [OPTIONS] <DIR>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<DIR>` | path | required | Image directory with a release.json. |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-images-release--tier"></span>`--tier` | string | | Tier (`slim`, `full`) for images that have tiers. |
-| <span id="cua-images-release--arch"></span>`--arch` | string | | Arches, comma separated (default: release.json `arches`). Repeatable. |
-| <span id="cua-images-release--stamp"></span>`--stamp` | string | | Pin stamp `<yyyymmdd>-<sha7>` (default: today and git HEAD). |
-| <span id="cua-images-release--work"></span>`--work` | path | | Work directory (default: $CUA_RELEASE_WORK, else under the cua build cache, which `cua cache prune` manages). |
-| <span id="cua-images-release--steps"></span>`--steps` | string | | Only these steps: phase names or step-id prefixes (comma separated). Repeatable. |
-| <span id="cua-images-release--from"></span>`--from` | string | | Rerun from this phase or step; the steps before it must have passed. |
-| <span id="cua-images-release--var"></span>`--var` | string | | Variable KEY=VALUE for release.json templates (repeatable). |
-| <span id="cua-images-release--assume"></span>`--assume` | string | | Treat a host capability as present (`kvm`) or absent (`!runsc`). Repeatable. |
-| <span id="cua-images-release--scope"></span>`--scope` | string | | This run's state file name, state-&lt;scope&gt;.json (default: the arches); CI jobs sharing an evidence directory use distinct scopes. |
-| <span id="cua-images-release--resume"></span>`--resume` | boolean | `false` | Skip steps that passed with the same inputs and whose outputs exist. |
-| <span id="cua-images-release--dry-run"></span>`--dry-run` | boolean | `false` | Print the plan; run nothing. |
-| <span id="cua-images-release--publish"></span>`--publish` | boolean | `false` | Also push, publish immutable pins and verify them. |
-| <span id="cua-images-release--promote"></span>`--promote` | boolean | `false` | Also move the floating tags to the pins. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-images-release"
-# Plan only
-cua images release libs/images/linux --tier slim --dry-run
-
-# Build and doctor amd64 locally; resume after a failure
-cua images release libs/images/linux --tier slim --arch amd64 --resume
-
-# Rerun from the doctor lanes (the build must have passed)
-cua images release libs/images/linux --tier slim --from gate
-
-# One CI job's slice
-cua images release libs/images/linux --tier full --arch arm64 --steps build,gate,stage --work release
-
-# Publish and promote (the gates must have passed)
-cua images release libs/images/omarchy --publish --promote --resume
-```
-
-### `cua images promote`
-
-Move a series' moving tags (`edge`, `edge-disk`) to the pins a `cua images publish` record names, after the gates passed.
-
-```text output
-cua images promote [OPTIONS] <RECORD>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<RECORD>` | path | required | Record written by `cua images publish --record`. |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-images-promote--dry-run"></span>`--dry-run` | boolean | `false` | Check and print, move nothing. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-images-promote"
-cua images promote pins.json
-cua images promote pins.json --dry-run
-```
-
-## Exit codes
-
-| Code | Meaning |
-| --- | --- |
-| `0` | Success. |
-| `1` | Failure, or `cua do` reported an error. |
-| `2` | Invalid argument, or an ambiguous sandbox name (qualify it: `local:NAME`). |
-| `3` | Not found: sandbox, window, skill or image (or an image not published yet). |
-| `4` | Not supported, or not configured (for example no provider credentials). |
-| `5` | No cua-spacesd answered, or a transport failure. |
-| `6` | Unauthenticated or permission denied (by Cua or your cloud account). |
-| `7` | Not enough free disk space (see `cua cache`). |
-| `130` | Cancelled (Ctrl-C during a create): what it made was removed. |
diff --git a/docs/content/docs/cua-cli/reference/cli/index.mdx b/docs/content/docs/cua-cli/reference/cli/index.mdx
index 0776c565be..fde8eb8a68 100644
--- a/docs/content/docs/cua-cli/reference/cli/index.mdx
+++ b/docs/content/docs/cua-cli/reference/cli/index.mdx
@@ -18,232 +18,75 @@ Run `cua <command> --help` for the build you have.
## Commands
-### `cua auth`
+### Spaces, computers and teams
-Sign in and out, see who is signed in, and store sandbox provider keys. [Reference](/cua-cli/reference/cli/auth).
+Your Spaces and machines, unattended access on this machine, devices, teams, your remote use this month, and a cua-spacesd by URL. [Reference](/cua-cli/reference/cli/spaces-and-computers).
| Command | Description | Subcommands |
| --- | --- | --- |
-| <span id="cua-auth-login"></span><span id="cua-auth-logout"></span><span id="cua-auth-status"></span><span id="cua-auth-whoami"></span><span id="cua-auth-provider"></span><span id="cua-auth-provider-ls"></span><span id="cua-auth-provider-set"></span><span id="cua-auth-provider-rm"></span>[`cua auth`](/cua-cli/reference/cli/auth#cua-auth) | Log in to Cua and manage the signed-in session. | [`login`](/cua-cli/reference/cli/auth#cua-auth-login), [`logout`](/cua-cli/reference/cli/auth#cua-auth-logout), [`status`](/cua-cli/reference/cli/auth#cua-auth-status), [`whoami`](/cua-cli/reference/cli/auth#cua-auth-whoami), [`provider`](/cua-cli/reference/cli/auth#cua-auth-provider), [`provider ls`](/cua-cli/reference/cli/auth#cua-auth-provider-ls), [`provider set`](/cua-cli/reference/cli/auth#cua-auth-provider-set), [`provider rm`](/cua-cli/reference/cli/auth#cua-auth-provider-rm) |
+| <span id="cua-spaces"></span><span id="cua-spaces-ls"></span><span id="cua-spaces-add"></span><span id="cua-spaces-create"></span><span id="cua-spaces-cancel"></span><span id="cua-spaces-gpus"></span><span id="cua-spaces-delete"></span><span id="cua-spaces-stop"></span><span id="cua-spaces-start"></span><span id="cua-spaces-rm"></span><span id="cua-spaces-share"></span><span id="cua-spaces-unshare"></span><span id="cua-spaces-shares"></span><span id="cua-spaces-relay-register"></span><span id="cua-spaces-relay-unregister"></span>[`cua spaces`](/cua-cli/reference/cli/spaces-and-computers#cua-spaces) | Spaces: registered ones and your machines on the relay. | [`ls`](/cua-cli/reference/cli/spaces-and-computers#cua-spaces-ls), [`add`](/cua-cli/reference/cli/spaces-and-computers#cua-spaces-add), [`create`](/cua-cli/reference/cli/spaces-and-computers#cua-spaces-create), [`cancel`](/cua-cli/reference/cli/spaces-and-computers#cua-spaces-cancel), [`gpus`](/cua-cli/reference/cli/spaces-and-computers#cua-spaces-gpus), [`delete`](/cua-cli/reference/cli/spaces-and-computers#cua-spaces-delete), [`stop`](/cua-cli/reference/cli/spaces-and-computers#cua-spaces-stop), [`start`](/cua-cli/reference/cli/spaces-and-computers#cua-spaces-start), [`rm`](/cua-cli/reference/cli/spaces-and-computers#cua-spaces-rm), [`share`](/cua-cli/reference/cli/spaces-and-computers#cua-spaces-share), [`unshare`](/cua-cli/reference/cli/spaces-and-computers#cua-spaces-unshare), [`shares`](/cua-cli/reference/cli/spaces-and-computers#cua-spaces-shares), [`relay-register`](/cua-cli/reference/cli/spaces-and-computers#cua-spaces-relay-register), [`relay-unregister`](/cua-cli/reference/cli/spaces-and-computers#cua-spaces-relay-unregister) |
+| <span id="cua-host"></span><span id="cua-host-setup"></span><span id="cua-host-pair"></span><span id="cua-host-config"></span><span id="cua-host-status"></span><span id="cua-host-stop"></span><span id="cua-host-start"></span><span id="cua-host-share"></span><span id="cua-host-unshare"></span><span id="cua-host-remove"></span>[`cua host`](/cua-cli/reference/cli/spaces-and-computers#cua-host) | Unattended access to this machine (setup, status, stop, start, remove). | [`setup`](/cua-cli/reference/cli/spaces-and-computers#cua-host-setup), [`pair`](/cua-cli/reference/cli/spaces-and-computers#cua-host-pair), [`config`](/cua-cli/reference/cli/spaces-and-computers#cua-host-config), [`status`](/cua-cli/reference/cli/spaces-and-computers#cua-host-status), [`stop`](/cua-cli/reference/cli/spaces-and-computers#cua-host-stop), [`start`](/cua-cli/reference/cli/spaces-and-computers#cua-host-start), [`share`](/cua-cli/reference/cli/spaces-and-computers#cua-host-share), [`unshare`](/cua-cli/reference/cli/spaces-and-computers#cua-host-unshare), [`remove`](/cua-cli/reference/cli/spaces-and-computers#cua-host-remove) |
+| <span id="cua-devices"></span><span id="cua-devices-status"></span><span id="cua-devices-enroll"></span><span id="cua-devices-approve"></span><span id="cua-devices-ls"></span><span id="cua-devices-rename"></span><span id="cua-devices-revoke"></span><span id="cua-devices-audit"></span>[`cua devices`](/cua-cli/reference/cli/spaces-and-computers#cua-devices) | This device as a client of your cua.ai account on the relay: enroll (second factor), approve other devices, list, rename, revoke, and the audit log of who accessed what. | [`status`](/cua-cli/reference/cli/spaces-and-computers#cua-devices-status), [`enroll`](/cua-cli/reference/cli/spaces-and-computers#cua-devices-enroll), [`approve`](/cua-cli/reference/cli/spaces-and-computers#cua-devices-approve), [`ls`](/cua-cli/reference/cli/spaces-and-computers#cua-devices-ls), [`rename`](/cua-cli/reference/cli/spaces-and-computers#cua-devices-rename), [`revoke`](/cua-cli/reference/cli/spaces-and-computers#cua-devices-revoke), [`audit`](/cua-cli/reference/cli/spaces-and-computers#cua-devices-audit) |
+| <span id="cua-team"></span><span id="cua-team-create"></span><span id="cua-team-ls"></span><span id="cua-team-show"></span><span id="cua-team-invite"></span><span id="cua-team-join"></span><span id="cua-team-leave"></span><span id="cua-team-remove-member"></span><span id="cua-team-set-role"></span><span id="cua-team-devices"></span><span id="cua-team-approve"></span><span id="cua-team-deny"></span><span id="cua-team-request"></span><span id="cua-team-add-machine"></span><span id="cua-team-remove-machine"></span><span id="cua-team-audit"></span><span id="cua-team-delete"></span>[`cua team`](/cua-cli/reference/cli/spaces-and-computers#cua-team) | Teams (organizations of your cua.ai account) share machines with every member and their agents. | [`create`](/cua-cli/reference/cli/spaces-and-computers#cua-team-create), [`ls`](/cua-cli/reference/cli/spaces-and-computers#cua-team-ls), [`show`](/cua-cli/reference/cli/spaces-and-computers#cua-team-show), [`invite`](/cua-cli/reference/cli/spaces-and-computers#cua-team-invite), [`join`](/cua-cli/reference/cli/spaces-and-computers#cua-team-join), [`leave`](/cua-cli/reference/cli/spaces-and-computers#cua-team-leave), [`remove-member`](/cua-cli/reference/cli/spaces-and-computers#cua-team-remove-member), [`set-role`](/cua-cli/reference/cli/spaces-and-computers#cua-team-set-role), [`devices`](/cua-cli/reference/cli/spaces-and-computers#cua-team-devices), [`approve`](/cua-cli/reference/cli/spaces-and-computers#cua-team-approve), [`deny`](/cua-cli/reference/cli/spaces-and-computers#cua-team-deny), [`request`](/cua-cli/reference/cli/spaces-and-computers#cua-team-request), [`add-machine`](/cua-cli/reference/cli/spaces-and-computers#cua-team-add-machine), [`remove-machine`](/cua-cli/reference/cli/spaces-and-computers#cua-team-remove-machine), [`audit`](/cua-cli/reference/cli/spaces-and-computers#cua-team-audit), [`delete`](/cua-cli/reference/cli/spaces-and-computers#cua-team-delete) |
+| <span id="cua-usage"></span>[`cua usage`](/cua-cli/reference/cli/spaces-and-computers#cua-usage) | Your relay allowance this month: live sessions, relay hours, and your plan. | |
+| <span id="cua-spacesd"></span><span id="cua-spacesd-caps"></span><span id="cua-spacesd-exec"></span><span id="cua-spacesd-cp"></span><span id="cua-spacesd-shell"></span><span id="cua-spacesd-targets"></span><span id="cua-spacesd-call"></span>[`cua spacesd`](/cua-cli/reference/cli/spaces-and-computers#cua-spacesd) | Talk to a cua-spacesd directly by URL. | [`caps`](/cua-cli/reference/cli/spaces-and-computers#cua-spacesd-caps), [`exec`](/cua-cli/reference/cli/spaces-and-computers#cua-spacesd-exec), [`cp`](/cua-cli/reference/cli/spaces-and-computers#cua-spacesd-cp), [`shell`](/cua-cli/reference/cli/spaces-and-computers#cua-spacesd-shell), [`targets`](/cua-cli/reference/cli/spaces-and-computers#cua-spacesd-targets), [`call`](/cua-cli/reference/cli/spaces-and-computers#cua-spacesd-call) |
-### `cua sandbox`
+### Files, teleport and keys
-Create, list, connect to, suspend and delete sandboxes, local or on your own machines. [Reference](/cua-cli/reference/cli/sandbox).
+Cua Volume files and sharing, moving an app session into a sandbox, and the Cua Keyvault. [Reference](/cua-cli/reference/cli/files-teleport-and-keys).
| Command | Description | Subcommands |
| --- | --- | --- |
-| <span id="cua-sandbox-create"></span><span id="cua-sandbox-launch"></span><span id="cua-sandbox-connect"></span><span id="cua-sandbox-ls"></span><span id="cua-sandbox-info"></span><span id="cua-sandbox-suspend"></span><span id="cua-sandbox-resume"></span><span id="cua-sandbox-restart"></span><span id="cua-sandbox-rm"></span>[`cua sandbox`](/cua-cli/reference/cli/sandbox#cua-sandbox) | Sandboxes: local or an existing machine (direct). | [`create`](/cua-cli/reference/cli/sandbox#cua-sandbox-create), [`launch`](/cua-cli/reference/cli/sandbox#cua-sandbox-launch), [`connect`](/cua-cli/reference/cli/sandbox#cua-sandbox-connect), [`ls`](/cua-cli/reference/cli/sandbox#cua-sandbox-ls), [`info`](/cua-cli/reference/cli/sandbox#cua-sandbox-info), [`suspend`](/cua-cli/reference/cli/sandbox#cua-sandbox-suspend), [`resume`](/cua-cli/reference/cli/sandbox#cua-sandbox-resume), [`restart`](/cua-cli/reference/cli/sandbox#cua-sandbox-restart), [`rm`](/cua-cli/reference/cli/sandbox#cua-sandbox-rm) |
+| <span id="cua-volume"></span><span id="cua-volume-ls"></span><span id="cua-volume-cat"></span><span id="cua-volume-put"></span><span id="cua-volume-rm"></span><span id="cua-volume-history"></span><span id="cua-volume-restore"></span><span id="cua-volume-grant"></span><span id="cua-volume-revoke"></span><span id="cua-volume-grants"></span><span id="cua-volume-requests"></span><span id="cua-volume-approve"></span><span id="cua-volume-deny"></span><span id="cua-volume-audit"></span><span id="cua-volume-mount"></span><span id="cua-volume-unmount"></span><span id="cua-volume-status"></span><span id="cua-volume-config"></span><span id="cua-volume-config-show"></span><span id="cua-volume-config-set"></span><span id="cua-volume-config-set-keys"></span>[`cua volume`](/cua-cli/reference/cli/files-teleport-and-keys#cua-volume) | Cua Volume: the versioned volume every Space and agent shares (public/, agents/&lt;agent&gt;/, spaces/&lt;space&gt;/), its grants and audit. | [`ls`](/cua-cli/reference/cli/files-teleport-and-keys#cua-volume-ls), [`cat`](/cua-cli/reference/cli/files-teleport-and-keys#cua-volume-cat), [`put`](/cua-cli/reference/cli/files-teleport-and-keys#cua-volume-put), [`rm`](/cua-cli/reference/cli/files-teleport-and-keys#cua-volume-rm), [`history`](/cua-cli/reference/cli/files-teleport-and-keys#cua-volume-history), [`restore`](/cua-cli/reference/cli/files-teleport-and-keys#cua-volume-restore), [`grant`](/cua-cli/reference/cli/files-teleport-and-keys#cua-volume-grant), [`revoke`](/cua-cli/reference/cli/files-teleport-and-keys#cua-volume-revoke), [`grants`](/cua-cli/reference/cli/files-teleport-and-keys#cua-volume-grants), [`requests`](/cua-cli/reference/cli/files-teleport-and-keys#cua-volume-requests), [`approve`](/cua-cli/reference/cli/files-teleport-and-keys#cua-volume-approve), [`deny`](/cua-cli/reference/cli/files-teleport-and-keys#cua-volume-deny), [`audit`](/cua-cli/reference/cli/files-teleport-and-keys#cua-volume-audit), [`mount`](/cua-cli/reference/cli/files-teleport-and-keys#cua-volume-mount), [`unmount`](/cua-cli/reference/cli/files-teleport-and-keys#cua-volume-unmount), [`status`](/cua-cli/reference/cli/files-teleport-and-keys#cua-volume-status), [`config`](/cua-cli/reference/cli/files-teleport-and-keys#cua-volume-config), [`config show`](/cua-cli/reference/cli/files-teleport-and-keys#cua-volume-config-show), [`config set`](/cua-cli/reference/cli/files-teleport-and-keys#cua-volume-config-set), [`config set-keys`](/cua-cli/reference/cli/files-teleport-and-keys#cua-volume-config-set-keys) |
+| <span id="cua-teleport"></span><span id="cua-teleport-providers"></span><span id="cua-teleport-manifest"></span><span id="cua-teleport-push"></span>[`cua teleport`](/cua-cli/reference/cli/files-teleport-and-keys#cua-teleport) | Move a desktop app session (tabs, profile, sign-in) into a sandbox. | [`providers`](/cua-cli/reference/cli/files-teleport-and-keys#cua-teleport-providers), [`manifest`](/cua-cli/reference/cli/files-teleport-and-keys#cua-teleport-manifest), [`push`](/cua-cli/reference/cli/files-teleport-and-keys#cua-teleport-push) |
+| <span id="cua-keyvault"></span><span id="cua-keyvault-status"></span><span id="cua-keyvault-init"></span><span id="cua-keyvault-unlock"></span><span id="cua-keyvault-lock"></span><span id="cua-keyvault-import-passwords"></span><span id="cua-keyvault-import-session"></span><span id="cua-keyvault-requests"></span><span id="cua-keyvault-approve"></span><span id="cua-keyvault-deny"></span>[`cua keyvault`](/cua-cli/reference/cli/files-teleport-and-keys#cua-keyvault) | The Cua Keyvault the daemon hosts: status, init, unlock, lock, saved passwords and approvals. | [`status`](/cua-cli/reference/cli/files-teleport-and-keys#cua-keyvault-status), [`init`](/cua-cli/reference/cli/files-teleport-and-keys#cua-keyvault-init), [`unlock`](/cua-cli/reference/cli/files-teleport-and-keys#cua-keyvault-unlock), [`lock`](/cua-cli/reference/cli/files-teleport-and-keys#cua-keyvault-lock), [`import-passwords`](/cua-cli/reference/cli/files-teleport-and-keys#cua-keyvault-import-passwords), [`import-session`](/cua-cli/reference/cli/files-teleport-and-keys#cua-keyvault-import-session), [`requests`](/cua-cli/reference/cli/files-teleport-and-keys#cua-keyvault-requests), [`approve`](/cua-cli/reference/cli/files-teleport-and-keys#cua-keyvault-approve), [`deny`](/cua-cli/reference/cli/files-teleport-and-keys#cua-keyvault-deny) |
-### Sandbox access
+### Sandboxes and images
-Run commands, copy files, forward ports, take screenshots, reach the MCP and view a sandbox (`cua sandbox exec`, `cp`, `view`, ...). [Reference](/cua-cli/reference/cli/sandbox-access).
+Create, reach and delete sandboxes; pull, build and push images; local runtimes, disk cleanup, your own cloud account and the sandbox viewer. [Reference](/cua-cli/reference/cli/sandboxes).
| Command | Description | Subcommands |
| --- | --- | --- |
-| <span id="cua-sandbox-exec"></span>[`cua sandbox exec`](/cua-cli/reference/cli/sandbox-access#cua-sandbox-exec) | Run a command (joined into one shell line, as `sh -c`). | |
-| <span id="cua-sandbox-shell"></span>[`cua sandbox shell`](/cua-cli/reference/cli/sandbox-access#cua-sandbox-shell) | Interactive shell (PTY), or run a command in a PTY. | |
-| <span id="cua-sandbox-cp"></span>[`cua sandbox cp`](/cua-cli/reference/cli/sandbox-access#cua-sandbox-cp) | Copy files: `cp NAME:/guest/path LOCAL` or `cp LOCAL NAME:/guest/path` (NAME may be a ref: `cp local:box:/tmp/x .`). | |
-| <span id="cua-sandbox-overlay"></span>[`cua sandbox overlay`](/cua-cli/reference/cli/sandbox-access#cua-sandbox-overlay) | Inject freshly built binaries into a running sandbox (see `create --overlay`): NAME=PATH or NAME=PATH:GUEST_PATH. | |
-| <span id="cua-sandbox-logs"></span>[`cua sandbox logs`](/cua-cli/reference/cli/sandbox-access#cua-sandbox-logs) | Show logs: the backend console (QEMU serial, container) when there is one, else the guest system log through the spacesd. | |
-| <span id="cua-sandbox-port-forward"></span>[`cua sandbox port-forward`](/cua-cli/reference/cli/sandbox-access#cua-sandbox-port-forward) | Forward a guest port: `port-forward NAME PORT[:LOCAL]` (a local sandbox's port not published at create tunnels through cua-spacesd when the image has it). | |
-| <span id="cua-sandbox-url"></span>[`cua sandbox url`](/cua-cli/reference/cli/sandbox-access#cua-sandbox-url) | Print a URL for a named service: usable from this machine (default), or `--public` for a shareable URL that expires (`--ttl`, default 1h; a token URL served by the cua daemon). | |
-| <span id="cua-sandbox-screenshot"></span>[`cua sandbox screenshot`](/cua-cli/reference/cli/sandbox-access#cua-sandbox-screenshot) | Save a screenshot (PNG). | |
-| <span id="cua-sandbox-mcp"></span><span id="cua-sandbox-mcp-config"></span><span id="cua-sandbox-mcp-info"></span><span id="cua-sandbox-mcp-tools"></span><span id="cua-sandbox-mcp-call"></span><span id="cua-sandbox-mcp-resources"></span><span id="cua-sandbox-mcp-templates"></span><span id="cua-sandbox-mcp-read"></span><span id="cua-sandbox-mcp-prompts"></span><span id="cua-sandbox-mcp-prompt"></span><span id="cua-sandbox-mcp-request"></span>[`cua sandbox mcp`](/cua-cli/reference/cli/sandbox-access#cua-sandbox-mcp) | Talk to an MCP server a sandbox serves: `mcp NAME SERVICE tools`, `mcp NAME SERVICE call TOOL '{"a":1}'`. | [`config`](/cua-cli/reference/cli/sandbox-access#cua-sandbox-mcp-config), [`info`](/cua-cli/reference/cli/sandbox-access#cua-sandbox-mcp-info), [`tools`](/cua-cli/reference/cli/sandbox-access#cua-sandbox-mcp-tools), [`call`](/cua-cli/reference/cli/sandbox-access#cua-sandbox-mcp-call), [`resources`](/cua-cli/reference/cli/sandbox-access#cua-sandbox-mcp-resources), [`templates`](/cua-cli/reference/cli/sandbox-access#cua-sandbox-mcp-templates), [`read`](/cua-cli/reference/cli/sandbox-access#cua-sandbox-mcp-read), [`prompts`](/cua-cli/reference/cli/sandbox-access#cua-sandbox-mcp-prompts), [`prompt`](/cua-cli/reference/cli/sandbox-access#cua-sandbox-mcp-prompt), [`request`](/cua-cli/reference/cli/sandbox-access#cua-sandbox-mcp-request) |
-| <span id="cua-sandbox-view"></span>[`cua sandbox view`](/cua-cli/reference/cli/sandbox-access#cua-sandbox-view) | Open the sandbox desktop in the browser (the cua-spacesd HTML5 viewer). | |
+| <span id="cua-sandbox"></span><span id="cua-sandbox-create"></span><span id="cua-sandbox-launch"></span><span id="cua-sandbox-connect"></span><span id="cua-sandbox-ls"></span><span id="cua-sandbox-info"></span><span id="cua-sandbox-suspend"></span><span id="cua-sandbox-resume"></span><span id="cua-sandbox-restart"></span><span id="cua-sandbox-rm"></span><span id="cua-sandbox-exec"></span><span id="cua-sandbox-shell"></span><span id="cua-sandbox-cp"></span><span id="cua-sandbox-overlay"></span><span id="cua-sandbox-logs"></span><span id="cua-sandbox-port-forward"></span><span id="cua-sandbox-url"></span><span id="cua-sandbox-screenshot"></span><span id="cua-sandbox-mcp"></span><span id="cua-sandbox-mcp-config"></span><span id="cua-sandbox-mcp-info"></span><span id="cua-sandbox-mcp-tools"></span><span id="cua-sandbox-mcp-call"></span><span id="cua-sandbox-mcp-resources"></span><span id="cua-sandbox-mcp-templates"></span><span id="cua-sandbox-mcp-read"></span><span id="cua-sandbox-mcp-prompts"></span><span id="cua-sandbox-mcp-prompt"></span><span id="cua-sandbox-mcp-request"></span><span id="cua-sandbox-view"></span>[`cua sandbox`](/cua-cli/reference/cli/sandboxes#cua-sandbox) | Sandboxes: local or an existing machine (direct). | [`create`](/cua-cli/reference/cli/sandboxes#cua-sandbox-create), [`launch`](/cua-cli/reference/cli/sandboxes#cua-sandbox-launch), [`connect`](/cua-cli/reference/cli/sandboxes#cua-sandbox-connect), [`ls`](/cua-cli/reference/cli/sandboxes#cua-sandbox-ls), [`info`](/cua-cli/reference/cli/sandboxes#cua-sandbox-info), [`suspend`](/cua-cli/reference/cli/sandboxes#cua-sandbox-suspend), [`resume`](/cua-cli/reference/cli/sandboxes#cua-sandbox-resume), [`restart`](/cua-cli/reference/cli/sandboxes#cua-sandbox-restart), [`rm`](/cua-cli/reference/cli/sandboxes#cua-sandbox-rm), [`exec`](/cua-cli/reference/cli/sandboxes#cua-sandbox-exec), [`shell`](/cua-cli/reference/cli/sandboxes#cua-sandbox-shell), [`cp`](/cua-cli/reference/cli/sandboxes#cua-sandbox-cp), [`overlay`](/cua-cli/reference/cli/sandboxes#cua-sandbox-overlay), [`logs`](/cua-cli/reference/cli/sandboxes#cua-sandbox-logs), [`port-forward`](/cua-cli/reference/cli/sandboxes#cua-sandbox-port-forward), [`url`](/cua-cli/reference/cli/sandboxes#cua-sandbox-url), [`screenshot`](/cua-cli/reference/cli/sandboxes#cua-sandbox-screenshot), [`mcp`](/cua-cli/reference/cli/sandboxes#cua-sandbox-mcp), [`mcp config`](/cua-cli/reference/cli/sandboxes#cua-sandbox-mcp-config), [`mcp info`](/cua-cli/reference/cli/sandboxes#cua-sandbox-mcp-info), [`mcp tools`](/cua-cli/reference/cli/sandboxes#cua-sandbox-mcp-tools), [`mcp call`](/cua-cli/reference/cli/sandboxes#cua-sandbox-mcp-call), [`mcp resources`](/cua-cli/reference/cli/sandboxes#cua-sandbox-mcp-resources), [`mcp templates`](/cua-cli/reference/cli/sandboxes#cua-sandbox-mcp-templates), [`mcp read`](/cua-cli/reference/cli/sandboxes#cua-sandbox-mcp-read), [`mcp prompts`](/cua-cli/reference/cli/sandboxes#cua-sandbox-mcp-prompts), [`mcp prompt`](/cua-cli/reference/cli/sandboxes#cua-sandbox-mcp-prompt), [`mcp request`](/cua-cli/reference/cli/sandboxes#cua-sandbox-mcp-request), [`view`](/cua-cli/reference/cli/sandboxes#cua-sandbox-view) |
+| <span id="cua-image"></span><span id="cua-image-pull"></span><span id="cua-image-build"></span><span id="cua-image-push"></span>[`cua image`](/cua-cli/reference/cli/sandboxes#cua-image) | Images: local OCI pull/build/push. | [`pull`](/cua-cli/reference/cli/sandboxes#cua-image-pull), [`build`](/cua-cli/reference/cli/sandboxes#cua-image-build), [`push`](/cua-cli/reference/cli/sandboxes#cua-image-push) |
+| <span id="cua-images"></span><span id="cua-images-ls"></span><span id="cua-images-info"></span><span id="cua-images-build"></span><span id="cua-images-pack"></span><span id="cua-images-publish"></span><span id="cua-images-release"></span><span id="cua-images-promote"></span>[`cua images`](/cua-cli/reference/cli/sandboxes#cua-images) | The sandbox image catalog (the images the docs list): which exist, their variants, and which ship cua-spacesd and a browser. | [`ls`](/cua-cli/reference/cli/sandboxes#cua-images-ls), [`info`](/cua-cli/reference/cli/sandboxes#cua-images-info), [`build`](/cua-cli/reference/cli/sandboxes#cua-images-build), [`pack`](/cua-cli/reference/cli/sandboxes#cua-images-pack), [`publish`](/cua-cli/reference/cli/sandboxes#cua-images-publish), [`release`](/cua-cli/reference/cli/sandboxes#cua-images-release), [`promote`](/cua-cli/reference/cli/sandboxes#cua-images-promote) |
+| <span id="cua-runtime"></span><span id="cua-runtime-doctor"></span><span id="cua-runtime-setup"></span>[`cua runtime`](/cua-cli/reference/cli/sandboxes#cua-runtime) | Local runtimes (cua-vmm). | [`doctor`](/cua-cli/reference/cli/sandboxes#cua-runtime-doctor), [`setup`](/cua-cli/reference/cli/sandboxes#cua-runtime-setup) |
+| <span id="cua-cache"></span><span id="cua-cache-ls"></span><span id="cua-cache-du"></span><span id="cua-cache-prune"></span><span id="cua-cache-config"></span>[`cua cache`](/cua-cli/reference/cli/sandboxes#cua-cache) | Disk used by images, sandboxes, builds and logs, and its cleanup. | [`ls`](/cua-cli/reference/cli/sandboxes#cua-cache-ls), [`du`](/cua-cli/reference/cli/sandboxes#cua-cache-du), [`prune`](/cua-cli/reference/cli/sandboxes#cua-cache-prune), [`config`](/cua-cli/reference/cli/sandboxes#cua-cache-config) |
+| <span id="cua-cloud"></span><span id="cua-cloud-status"></span><span id="cua-cloud-connect"></span><span id="cua-cloud-test"></span><span id="cua-cloud-disconnect"></span><span id="cua-cloud-sweep"></span>[`cua cloud`](/cua-cli/reference/cli/sandboxes#cua-cloud) | Spaces in your own cloud account (AWS, Google Cloud, Modal): connect, status, test, disconnect, sweep. | [`status`](/cua-cli/reference/cli/sandboxes#cua-cloud-status), [`connect`](/cua-cli/reference/cli/sandboxes#cua-cloud-connect), [`test`](/cua-cli/reference/cli/sandboxes#cua-cloud-test), [`disconnect`](/cua-cli/reference/cli/sandboxes#cua-cloud-disconnect), [`sweep`](/cua-cli/reference/cli/sandboxes#cua-cloud-sweep) |
+| <span id="cua-viewer"></span>[`cua viewer`](/cua-cli/reference/cli/sandboxes#cua-viewer) | Serve the HTML5 viewer for every sandbox on one loopback port. | |
-### `cua config`
+### Computer actions
-User defaults: where sandboxes run (`default.on`), the default kind and runtime. [Reference](/cua-cli/reference/cli/config).
+One-shot computer actions (screenshot, click, type, windows) against a selected target, and their recorded trajectories. [Reference](/cua-cli/reference/cli/computer-actions).
| Command | Description | Subcommands |
| --- | --- | --- |
-| <span id="cua-config-list"></span><span id="cua-config-get"></span><span id="cua-config-set"></span><span id="cua-config-unset"></span><span id="cua-config-path"></span>[`cua config`](/cua-cli/reference/cli/config#cua-config) | User defaults (~/.cua/config.toml): where sandboxes run when --on is not given (default.on), the default kind and runtime. | [`list`](/cua-cli/reference/cli/config#cua-config-list), [`get`](/cua-cli/reference/cli/config#cua-config-get), [`set`](/cua-cli/reference/cli/config#cua-config-set), [`unset`](/cua-cli/reference/cli/config#cua-config-unset), [`path`](/cua-cli/reference/cli/config#cua-config-path) |
+| <span id="cua-do"></span><span id="cua-do-switch"></span><span id="cua-do-status"></span><span id="cua-do-ls"></span><span id="cua-do-zoom"></span><span id="cua-do-unzoom"></span><span id="cua-do-screenshot"></span><span id="cua-do-snapshot"></span><span id="cua-do-click"></span><span id="cua-do-dclick"></span><span id="cua-do-move"></span><span id="cua-do-type"></span><span id="cua-do-key"></span><span id="cua-do-hotkey"></span><span id="cua-do-scroll"></span><span id="cua-do-drag"></span><span id="cua-do-shell"></span><span id="cua-do-open"></span><span id="cua-do-launch"></span><span id="cua-do-window"></span><span id="cua-do-window-ls"></span><span id="cua-do-window-unfocus"></span><span id="cua-do-window-focus"></span><span id="cua-do-window-minimize"></span><span id="cua-do-window-maximize"></span><span id="cua-do-window-restore"></span><span id="cua-do-window-close"></span><span id="cua-do-window-resize"></span><span id="cua-do-window-move"></span><span id="cua-do-window-info"></span><span id="cua-do-a11y"></span><span id="cua-do-a11y-tree"></span><span id="cua-do-a11y-find"></span><span id="cua-do-a11y-act"></span><span id="cua-do-cursor"></span><span id="cua-do-clipboard"></span><span id="cua-do-clipboard-get"></span><span id="cua-do-clipboard-set"></span>[`cua do`](/cua-cli/reference/cli/computer-actions#cua-do) | One-shot computer actions against the selected target. | [`switch`](/cua-cli/reference/cli/computer-actions#cua-do-switch), [`status`](/cua-cli/reference/cli/computer-actions#cua-do-status), [`ls`](/cua-cli/reference/cli/computer-actions#cua-do-ls), [`zoom`](/cua-cli/reference/cli/computer-actions#cua-do-zoom), [`unzoom`](/cua-cli/reference/cli/computer-actions#cua-do-unzoom), [`screenshot`](/cua-cli/reference/cli/computer-actions#cua-do-screenshot), [`snapshot`](/cua-cli/reference/cli/computer-actions#cua-do-snapshot), [`click`](/cua-cli/reference/cli/computer-actions#cua-do-click), [`dclick`](/cua-cli/reference/cli/computer-actions#cua-do-dclick), [`move`](/cua-cli/reference/cli/computer-actions#cua-do-move), [`type`](/cua-cli/reference/cli/computer-actions#cua-do-type), [`key`](/cua-cli/reference/cli/computer-actions#cua-do-key), [`hotkey`](/cua-cli/reference/cli/computer-actions#cua-do-hotkey), [`scroll`](/cua-cli/reference/cli/computer-actions#cua-do-scroll), [`drag`](/cua-cli/reference/cli/computer-actions#cua-do-drag), [`shell`](/cua-cli/reference/cli/computer-actions#cua-do-shell), [`open`](/cua-cli/reference/cli/computer-actions#cua-do-open), [`launch`](/cua-cli/reference/cli/computer-actions#cua-do-launch), [`window`](/cua-cli/reference/cli/computer-actions#cua-do-window), [`window ls`](/cua-cli/reference/cli/computer-actions#cua-do-window-ls), [`window unfocus`](/cua-cli/reference/cli/computer-actions#cua-do-window-unfocus), [`window focus`](/cua-cli/reference/cli/computer-actions#cua-do-window-focus), [`window minimize`](/cua-cli/reference/cli/computer-actions#cua-do-window-minimize), [`window maximize`](/cua-cli/reference/cli/computer-actions#cua-do-window-maximize), [`window restore`](/cua-cli/reference/cli/computer-actions#cua-do-window-restore), [`window close`](/cua-cli/reference/cli/computer-actions#cua-do-window-close), [`window resize`](/cua-cli/reference/cli/computer-actions#cua-do-window-resize), [`window move`](/cua-cli/reference/cli/computer-actions#cua-do-window-move), [`window info`](/cua-cli/reference/cli/computer-actions#cua-do-window-info), [`a11y`](/cua-cli/reference/cli/computer-actions#cua-do-a11y), [`a11y tree`](/cua-cli/reference/cli/computer-actions#cua-do-a11y-tree), [`a11y find`](/cua-cli/reference/cli/computer-actions#cua-do-a11y-find), [`a11y act`](/cua-cli/reference/cli/computer-actions#cua-do-a11y-act), [`cursor`](/cua-cli/reference/cli/computer-actions#cua-do-cursor), [`clipboard`](/cua-cli/reference/cli/computer-actions#cua-do-clipboard), [`clipboard get`](/cua-cli/reference/cli/computer-actions#cua-do-clipboard-get), [`clipboard set`](/cua-cli/reference/cli/computer-actions#cua-do-clipboard-set) |
+| <span id="cua-do-host-consent"></span>[`cua do-host-consent`](/cua-cli/reference/cli/computer-actions#cua-do-host-consent) | Grant consent for `cua do switch host`. | |
+| <span id="cua-trajectory"></span><span id="cua-trajectory-ls"></span><span id="cua-trajectory-view"></span><span id="cua-trajectory-stop"></span><span id="cua-trajectory-clean"></span>[`cua trajectory`](/cua-cli/reference/cli/computer-actions#cua-trajectory) | Recorded `cua do` trajectories. | [`ls`](/cua-cli/reference/cli/computer-actions#cua-trajectory-ls), [`view`](/cua-cli/reference/cli/computer-actions#cua-trajectory-view), [`stop`](/cua-cli/reference/cli/computer-actions#cua-trajectory-stop), [`clean`](/cua-cli/reference/cli/computer-actions#cua-trajectory-clean) |
-### `cua viewer`
+### Agents, MCP and skills
-One local browser page that lists every sandbox and opens its viewer. [Reference](/cua-cli/reference/cli/viewer).
+Run coding agents in a sandbox, set up your AI agents, the stdio MCP server, and recorded skills. [Reference](/cua-cli/reference/cli/agents).
| Command | Description | Subcommands |
| --- | --- | --- |
-| [`cua viewer`](/cua-cli/reference/cli/viewer#cua-viewer) | Serve the HTML5 viewer for every sandbox on one loopback port. | |
+| <span id="cua-agent"></span><span id="cua-agent-run"></span><span id="cua-agent-ls"></span><span id="cua-agent-logs"></span><span id="cua-agent-send"></span><span id="cua-agent-interrupt"></span><span id="cua-agent-stop"></span><span id="cua-agent-status"></span><span id="cua-agent-rm"></span><span id="cua-agent-ensure"></span><span id="cua-agent-harnesses"></span><span id="cua-agent-keys"></span><span id="cua-agent-keys-ls"></span><span id="cua-agent-keys-set"></span><span id="cua-agent-keys-rm"></span><span id="cua-agent-create"></span><span id="cua-agent-persistent"></span><span id="cua-agent-tell"></span><span id="cua-agent-save"></span><span id="cua-agent-pause"></span><span id="cua-agent-resume"></span><span id="cua-agent-forget"></span><span id="cua-agent-routine"></span><span id="cua-agent-routine-add"></span><span id="cua-agent-routine-ls"></span><span id="cua-agent-routine-rm"></span><span id="cua-agent-routine-enable"></span><span id="cua-agent-routine-disable"></span><span id="cua-agent-allow-computer"></span><span id="cua-agent-revoke-computer"></span><span id="cua-agent-computer-access"></span><span id="cua-agent-notifications"></span>[`cua agent`](/cua-cli/reference/cli/agents#cua-agent) | Run coding agents inside a sandbox: run, ls, logs, send, interrupt, stop. | [`run`](/cua-cli/reference/cli/agents#cua-agent-run), [`ls`](/cua-cli/reference/cli/agents#cua-agent-ls), [`logs`](/cua-cli/reference/cli/agents#cua-agent-logs), [`send`](/cua-cli/reference/cli/agents#cua-agent-send), [`interrupt`](/cua-cli/reference/cli/agents#cua-agent-interrupt), [`stop`](/cua-cli/reference/cli/agents#cua-agent-stop), [`status`](/cua-cli/reference/cli/agents#cua-agent-status), [`rm`](/cua-cli/reference/cli/agents#cua-agent-rm), [`ensure`](/cua-cli/reference/cli/agents#cua-agent-ensure), [`harnesses`](/cua-cli/reference/cli/agents#cua-agent-harnesses), [`keys`](/cua-cli/reference/cli/agents#cua-agent-keys), [`keys ls`](/cua-cli/reference/cli/agents#cua-agent-keys-ls), [`keys set`](/cua-cli/reference/cli/agents#cua-agent-keys-set), [`keys rm`](/cua-cli/reference/cli/agents#cua-agent-keys-rm), [`create`](/cua-cli/reference/cli/agents#cua-agent-create), [`persistent`](/cua-cli/reference/cli/agents#cua-agent-persistent), [`tell`](/cua-cli/reference/cli/agents#cua-agent-tell), [`save`](/cua-cli/reference/cli/agents#cua-agent-save), [`pause`](/cua-cli/reference/cli/agents#cua-agent-pause), [`resume`](/cua-cli/reference/cli/agents#cua-agent-resume), [`forget`](/cua-cli/reference/cli/agents#cua-agent-forget), [`routine`](/cua-cli/reference/cli/agents#cua-agent-routine), [`routine add`](/cua-cli/reference/cli/agents#cua-agent-routine-add), [`routine ls`](/cua-cli/reference/cli/agents#cua-agent-routine-ls), [`routine rm`](/cua-cli/reference/cli/agents#cua-agent-routine-rm), [`routine enable`](/cua-cli/reference/cli/agents#cua-agent-routine-enable), [`routine disable`](/cua-cli/reference/cli/agents#cua-agent-routine-disable), [`allow-computer`](/cua-cli/reference/cli/agents#cua-agent-allow-computer), [`revoke-computer`](/cua-cli/reference/cli/agents#cua-agent-revoke-computer), [`computer-access`](/cua-cli/reference/cli/agents#cua-agent-computer-access), [`notifications`](/cua-cli/reference/cli/agents#cua-agent-notifications) |
+| <span id="cua-agents"></span><span id="cua-agents-detect"></span><span id="cua-agents-setup"></span><span id="cua-agents-status"></span><span id="cua-agents-remove"></span><span id="cua-agents-update"></span>[`cua agents`](/cua-cli/reference/cli/agents#cua-agents) | AI coding agents on this machine: install cua skills and configure the cua MCP server. | [`detect`](/cua-cli/reference/cli/agents#cua-agents-detect), [`setup`](/cua-cli/reference/cli/agents#cua-agents-setup), [`status`](/cua-cli/reference/cli/agents#cua-agents-status), [`remove`](/cua-cli/reference/cli/agents#cua-agents-remove), [`update`](/cua-cli/reference/cli/agents#cua-agents-update) |
+| <span id="cua-mcp"></span>[`cua mcp`](/cua-cli/reference/cli/agents#cua-mcp) | Stdio MCP server exposing sandboxes, computer control and skills. | |
+| <span id="cua-skills"></span><span id="cua-skills-list"></span><span id="cua-skills-read"></span><span id="cua-skills-replay"></span><span id="cua-skills-delete"></span><span id="cua-skills-clean"></span><span id="cua-skills-record"></span>[`cua skills`](/cua-cli/reference/cli/agents#cua-skills) | Recorded demonstrations (skills) for agents. | [`list`](/cua-cli/reference/cli/agents#cua-skills-list), [`read`](/cua-cli/reference/cli/agents#cua-skills-read), [`replay`](/cua-cli/reference/cli/agents#cua-skills-replay), [`delete`](/cua-cli/reference/cli/agents#cua-skills-delete), [`clean`](/cua-cli/reference/cli/agents#cua-skills-clean), [`record`](/cua-cli/reference/cli/agents#cua-skills-record) |
-### `cua do`
+### Account and setup
-One-shot computer actions (screenshot, click, type, windows) against a selected target. [Reference](/cua-cli/reference/cli/do).
+Sign in and out, user defaults, the cua daemon, health checks and usage telemetry. [Reference](/cua-cli/reference/cli/account-and-setup).
| Command | Description | Subcommands |
| --- | --- | --- |
-| <span id="cua-do-switch"></span><span id="cua-do-status"></span><span id="cua-do-ls"></span><span id="cua-do-zoom"></span><span id="cua-do-unzoom"></span><span id="cua-do-screenshot"></span><span id="cua-do-snapshot"></span><span id="cua-do-click"></span><span id="cua-do-dclick"></span><span id="cua-do-move"></span><span id="cua-do-type"></span><span id="cua-do-key"></span><span id="cua-do-hotkey"></span><span id="cua-do-scroll"></span><span id="cua-do-drag"></span><span id="cua-do-shell"></span><span id="cua-do-open"></span><span id="cua-do-launch"></span><span id="cua-do-window"></span><span id="cua-do-window-ls"></span><span id="cua-do-window-unfocus"></span><span id="cua-do-window-focus"></span><span id="cua-do-window-minimize"></span><span id="cua-do-window-maximize"></span><span id="cua-do-window-restore"></span><span id="cua-do-window-close"></span><span id="cua-do-window-resize"></span><span id="cua-do-window-move"></span><span id="cua-do-window-info"></span><span id="cua-do-a11y"></span><span id="cua-do-a11y-tree"></span><span id="cua-do-a11y-find"></span><span id="cua-do-a11y-act"></span><span id="cua-do-cursor"></span><span id="cua-do-clipboard"></span><span id="cua-do-clipboard-get"></span><span id="cua-do-clipboard-set"></span>[`cua do`](/cua-cli/reference/cli/do#cua-do) | One-shot computer actions against the selected target. | [`switch`](/cua-cli/reference/cli/do#cua-do-switch), [`status`](/cua-cli/reference/cli/do#cua-do-status), [`ls`](/cua-cli/reference/cli/do#cua-do-ls), [`zoom`](/cua-cli/reference/cli/do#cua-do-zoom), [`unzoom`](/cua-cli/reference/cli/do#cua-do-unzoom), [`screenshot`](/cua-cli/reference/cli/do#cua-do-screenshot), [`snapshot`](/cua-cli/reference/cli/do#cua-do-snapshot), [`click`](/cua-cli/reference/cli/do#cua-do-click), [`dclick`](/cua-cli/reference/cli/do#cua-do-dclick), [`move`](/cua-cli/reference/cli/do#cua-do-move), [`type`](/cua-cli/reference/cli/do#cua-do-type), [`key`](/cua-cli/reference/cli/do#cua-do-key), [`hotkey`](/cua-cli/reference/cli/do#cua-do-hotkey), [`scroll`](/cua-cli/reference/cli/do#cua-do-scroll), [`drag`](/cua-cli/reference/cli/do#cua-do-drag), [`shell`](/cua-cli/reference/cli/do#cua-do-shell), [`open`](/cua-cli/reference/cli/do#cua-do-open), [`launch`](/cua-cli/reference/cli/do#cua-do-launch), [`window`](/cua-cli/reference/cli/do#cua-do-window), [`window ls`](/cua-cli/reference/cli/do#cua-do-window-ls), [`window unfocus`](/cua-cli/reference/cli/do#cua-do-window-unfocus), [`window focus`](/cua-cli/reference/cli/do#cua-do-window-focus), [`window minimize`](/cua-cli/reference/cli/do#cua-do-window-minimize), [`window maximize`](/cua-cli/reference/cli/do#cua-do-window-maximize), [`window restore`](/cua-cli/reference/cli/do#cua-do-window-restore), [`window close`](/cua-cli/reference/cli/do#cua-do-window-close), [`window resize`](/cua-cli/reference/cli/do#cua-do-window-resize), [`window move`](/cua-cli/reference/cli/do#cua-do-window-move), [`window info`](/cua-cli/reference/cli/do#cua-do-window-info), [`a11y`](/cua-cli/reference/cli/do#cua-do-a11y), [`a11y tree`](/cua-cli/reference/cli/do#cua-do-a11y-tree), [`a11y find`](/cua-cli/reference/cli/do#cua-do-a11y-find), [`a11y act`](/cua-cli/reference/cli/do#cua-do-a11y-act), [`cursor`](/cua-cli/reference/cli/do#cua-do-cursor), [`clipboard`](/cua-cli/reference/cli/do#cua-do-clipboard), [`clipboard get`](/cua-cli/reference/cli/do#cua-do-clipboard-get), [`clipboard set`](/cua-cli/reference/cli/do#cua-do-clipboard-set) |
-| <span id="cua-do-host-consent"></span>[`cua do-host-consent`](/cua-cli/reference/cli/do#cua-do-host-consent) | Grant consent for `cua do switch host`. | |
-
-### `cua image`
-
-Pull, build and push OCI images; list the image catalog. [Reference](/cua-cli/reference/cli/image).
-
-| Command | Description | Subcommands |
-| --- | --- | --- |
-| <span id="cua-image-pull"></span><span id="cua-image-build"></span><span id="cua-image-push"></span>[`cua image`](/cua-cli/reference/cli/image#cua-image) | Images: local OCI pull/build/push. | [`pull`](/cua-cli/reference/cli/image#cua-image-pull), [`build`](/cua-cli/reference/cli/image#cua-image-build), [`push`](/cua-cli/reference/cli/image#cua-image-push) |
-| <span id="cua-images"></span><span id="cua-images-ls"></span><span id="cua-images-info"></span><span id="cua-images-build"></span><span id="cua-images-pack"></span><span id="cua-images-publish"></span><span id="cua-images-release"></span><span id="cua-images-promote"></span>[`cua images`](/cua-cli/reference/cli/image#cua-images) | The sandbox image catalog (the images the docs list): which exist, their variants, and which ship cua-spacesd and a browser. | [`ls`](/cua-cli/reference/cli/image#cua-images-ls), [`info`](/cua-cli/reference/cli/image#cua-images-info), [`build`](/cua-cli/reference/cli/image#cua-images-build), [`pack`](/cua-cli/reference/cli/image#cua-images-pack), [`publish`](/cua-cli/reference/cli/image#cua-images-publish), [`release`](/cua-cli/reference/cli/image#cua-images-release), [`promote`](/cua-cli/reference/cli/image#cua-images-promote) |
-
-### `cua mcp`
-
-The stdio MCP server for AI assistants. [Reference](/cua-cli/reference/cli/mcp).
-
-| Command | Description | Subcommands |
-| --- | --- | --- |
-| [`cua mcp`](/cua-cli/reference/cli/mcp#cua-mcp) | Stdio MCP server exposing sandboxes, computer control and skills. | |
-
-### `cua agent`
-
-Run coding agents (Claude Code, Codex, Gemini CLI, ...) inside a sandbox and follow, continue or stop them. [Reference](/cua-cli/reference/cli/agent).
-
-| Command | Description | Subcommands |
-| --- | --- | --- |
-| <span id="cua-agent-run"></span><span id="cua-agent-ls"></span><span id="cua-agent-logs"></span><span id="cua-agent-send"></span><span id="cua-agent-interrupt"></span><span id="cua-agent-stop"></span><span id="cua-agent-status"></span><span id="cua-agent-rm"></span><span id="cua-agent-ensure"></span><span id="cua-agent-harnesses"></span><span id="cua-agent-keys"></span><span id="cua-agent-keys-ls"></span><span id="cua-agent-keys-set"></span><span id="cua-agent-keys-rm"></span><span id="cua-agent-create"></span><span id="cua-agent-persistent"></span><span id="cua-agent-tell"></span><span id="cua-agent-save"></span><span id="cua-agent-pause"></span><span id="cua-agent-resume"></span><span id="cua-agent-forget"></span><span id="cua-agent-routine"></span><span id="cua-agent-routine-add"></span><span id="cua-agent-routine-ls"></span><span id="cua-agent-routine-rm"></span><span id="cua-agent-routine-enable"></span><span id="cua-agent-routine-disable"></span><span id="cua-agent-allow-computer"></span><span id="cua-agent-revoke-computer"></span><span id="cua-agent-computer-access"></span><span id="cua-agent-notifications"></span>[`cua agent`](/cua-cli/reference/cli/agent#cua-agent) | Run coding agents inside a sandbox: run, ls, logs, send, interrupt, stop. | [`run`](/cua-cli/reference/cli/agent#cua-agent-run), [`ls`](/cua-cli/reference/cli/agent#cua-agent-ls), [`logs`](/cua-cli/reference/cli/agent#cua-agent-logs), [`send`](/cua-cli/reference/cli/agent#cua-agent-send), [`interrupt`](/cua-cli/reference/cli/agent#cua-agent-interrupt), [`stop`](/cua-cli/reference/cli/agent#cua-agent-stop), [`status`](/cua-cli/reference/cli/agent#cua-agent-status), [`rm`](/cua-cli/reference/cli/agent#cua-agent-rm), [`ensure`](/cua-cli/reference/cli/agent#cua-agent-ensure), [`harnesses`](/cua-cli/reference/cli/agent#cua-agent-harnesses), [`keys`](/cua-cli/reference/cli/agent#cua-agent-keys), [`keys ls`](/cua-cli/reference/cli/agent#cua-agent-keys-ls), [`keys set`](/cua-cli/reference/cli/agent#cua-agent-keys-set), [`keys rm`](/cua-cli/reference/cli/agent#cua-agent-keys-rm), [`create`](/cua-cli/reference/cli/agent#cua-agent-create), [`persistent`](/cua-cli/reference/cli/agent#cua-agent-persistent), [`tell`](/cua-cli/reference/cli/agent#cua-agent-tell), [`save`](/cua-cli/reference/cli/agent#cua-agent-save), [`pause`](/cua-cli/reference/cli/agent#cua-agent-pause), [`resume`](/cua-cli/reference/cli/agent#cua-agent-resume), [`forget`](/cua-cli/reference/cli/agent#cua-agent-forget), [`routine`](/cua-cli/reference/cli/agent#cua-agent-routine), [`routine add`](/cua-cli/reference/cli/agent#cua-agent-routine-add), [`routine ls`](/cua-cli/reference/cli/agent#cua-agent-routine-ls), [`routine rm`](/cua-cli/reference/cli/agent#cua-agent-routine-rm), [`routine enable`](/cua-cli/reference/cli/agent#cua-agent-routine-enable), [`routine disable`](/cua-cli/reference/cli/agent#cua-agent-routine-disable), [`allow-computer`](/cua-cli/reference/cli/agent#cua-agent-allow-computer), [`revoke-computer`](/cua-cli/reference/cli/agent#cua-agent-revoke-computer), [`computer-access`](/cua-cli/reference/cli/agent#cua-agent-computer-access), [`notifications`](/cua-cli/reference/cli/agent#cua-agent-notifications) |
-
-### `cua agents`
-
-Install cua skills and the cua MCP server into AI coding agents. [Reference](/cua-cli/reference/cli/agents).
-
-| Command | Description | Subcommands |
-| --- | --- | --- |
-| <span id="cua-agents-detect"></span><span id="cua-agents-setup"></span><span id="cua-agents-status"></span><span id="cua-agents-remove"></span><span id="cua-agents-update"></span>[`cua agents`](/cua-cli/reference/cli/agents#cua-agents) | AI coding agents on this machine: install cua skills and configure the cua MCP server. | [`detect`](/cua-cli/reference/cli/agents#cua-agents-detect), [`setup`](/cua-cli/reference/cli/agents#cua-agents-setup), [`status`](/cua-cli/reference/cli/agents#cua-agents-status), [`remove`](/cua-cli/reference/cli/agents#cua-agents-remove), [`update`](/cua-cli/reference/cli/agents#cua-agents-update) |
-
-### `cua skills`
-
-Record, list and replay demonstrations (skills). [Reference](/cua-cli/reference/cli/skills).
-
-| Command | Description | Subcommands |
-| --- | --- | --- |
-| <span id="cua-skills-list"></span><span id="cua-skills-read"></span><span id="cua-skills-replay"></span><span id="cua-skills-delete"></span><span id="cua-skills-clean"></span><span id="cua-skills-record"></span>[`cua skills`](/cua-cli/reference/cli/skills#cua-skills) | Recorded demonstrations (skills) for agents. | [`list`](/cua-cli/reference/cli/skills#cua-skills-list), [`read`](/cua-cli/reference/cli/skills#cua-skills-read), [`replay`](/cua-cli/reference/cli/skills#cua-skills-replay), [`delete`](/cua-cli/reference/cli/skills#cua-skills-delete), [`clean`](/cua-cli/reference/cli/skills#cua-skills-clean), [`record`](/cua-cli/reference/cli/skills#cua-skills-record) |
-
-### `cua trajectory`
-
-Recorded `cua do` trajectories. [Reference](/cua-cli/reference/cli/trajectory).
-
-| Command | Description | Subcommands |
-| --- | --- | --- |
-| <span id="cua-trajectory-ls"></span><span id="cua-trajectory-view"></span><span id="cua-trajectory-stop"></span><span id="cua-trajectory-clean"></span>[`cua trajectory`](/cua-cli/reference/cli/trajectory#cua-trajectory) | Recorded `cua do` trajectories. | [`ls`](/cua-cli/reference/cli/trajectory#cua-trajectory-ls), [`view`](/cua-cli/reference/cli/trajectory#cua-trajectory-view), [`stop`](/cua-cli/reference/cli/trajectory#cua-trajectory-stop), [`clean`](/cua-cli/reference/cli/trajectory#cua-trajectory-clean) |
-
-### `cua spaces`
-
-Registered Spaces and your machines on the relay. [Reference](/cua-cli/reference/cli/spaces).
-
-| Command | Description | Subcommands |
-| --- | --- | --- |
-| <span id="cua-spaces-ls"></span><span id="cua-spaces-add"></span><span id="cua-spaces-create"></span><span id="cua-spaces-cancel"></span><span id="cua-spaces-gpus"></span><span id="cua-spaces-delete"></span><span id="cua-spaces-stop"></span><span id="cua-spaces-start"></span><span id="cua-spaces-rm"></span><span id="cua-spaces-share"></span><span id="cua-spaces-unshare"></span><span id="cua-spaces-shares"></span><span id="cua-spaces-relay-register"></span><span id="cua-spaces-relay-unregister"></span>[`cua spaces`](/cua-cli/reference/cli/spaces#cua-spaces) | Spaces: registered ones and your machines on the relay. | [`ls`](/cua-cli/reference/cli/spaces#cua-spaces-ls), [`add`](/cua-cli/reference/cli/spaces#cua-spaces-add), [`create`](/cua-cli/reference/cli/spaces#cua-spaces-create), [`cancel`](/cua-cli/reference/cli/spaces#cua-spaces-cancel), [`gpus`](/cua-cli/reference/cli/spaces#cua-spaces-gpus), [`delete`](/cua-cli/reference/cli/spaces#cua-spaces-delete), [`stop`](/cua-cli/reference/cli/spaces#cua-spaces-stop), [`start`](/cua-cli/reference/cli/spaces#cua-spaces-start), [`rm`](/cua-cli/reference/cli/spaces#cua-spaces-rm), [`share`](/cua-cli/reference/cli/spaces#cua-spaces-share), [`unshare`](/cua-cli/reference/cli/spaces#cua-spaces-unshare), [`shares`](/cua-cli/reference/cli/spaces#cua-spaces-shares), [`relay-register`](/cua-cli/reference/cli/spaces#cua-spaces-relay-register), [`relay-unregister`](/cua-cli/reference/cli/spaces#cua-spaces-relay-unregister) |
-
-### `cua cloud`
-
-Your own AWS, Google Cloud or Modal account as a place for sandboxes and Spaces: connect, test, status, sweep. [Reference](/cua-cli/reference/cli/cloud).
-
-| Command | Description | Subcommands |
-| --- | --- | --- |
-| <span id="cua-cloud-status"></span><span id="cua-cloud-connect"></span><span id="cua-cloud-test"></span><span id="cua-cloud-disconnect"></span><span id="cua-cloud-sweep"></span>[`cua cloud`](/cua-cli/reference/cli/cloud#cua-cloud) | Spaces in your own cloud account (AWS, Google Cloud, Modal): connect, status, test, disconnect, sweep. | [`status`](/cua-cli/reference/cli/cloud#cua-cloud-status), [`connect`](/cua-cli/reference/cli/cloud#cua-cloud-connect), [`test`](/cua-cli/reference/cli/cloud#cua-cloud-test), [`disconnect`](/cua-cli/reference/cli/cloud#cua-cloud-disconnect), [`sweep`](/cua-cli/reference/cli/cloud#cua-cloud-sweep) |
-
-### `cua host`
-
-Set this machine up for unattended access. [Reference](/cua-cli/reference/cli/host).
-
-| Command | Description | Subcommands |
-| --- | --- | --- |
-| <span id="cua-host-setup"></span><span id="cua-host-pair"></span><span id="cua-host-config"></span><span id="cua-host-status"></span><span id="cua-host-stop"></span><span id="cua-host-start"></span><span id="cua-host-share"></span><span id="cua-host-unshare"></span><span id="cua-host-remove"></span>[`cua host`](/cua-cli/reference/cli/host#cua-host) | Unattended access to this machine (setup, status, stop, start, remove). | [`setup`](/cua-cli/reference/cli/host#cua-host-setup), [`pair`](/cua-cli/reference/cli/host#cua-host-pair), [`config`](/cua-cli/reference/cli/host#cua-host-config), [`status`](/cua-cli/reference/cli/host#cua-host-status), [`stop`](/cua-cli/reference/cli/host#cua-host-stop), [`start`](/cua-cli/reference/cli/host#cua-host-start), [`share`](/cua-cli/reference/cli/host#cua-host-share), [`unshare`](/cua-cli/reference/cli/host#cua-host-unshare), [`remove`](/cua-cli/reference/cli/host#cua-host-remove) |
-
-### `cua devices`
-
-Enroll this device on the relay, approve, rename and revoke devices, and read the access log. [Reference](/cua-cli/reference/cli/devices).
-
-| Command | Description | Subcommands |
-| --- | --- | --- |
-| <span id="cua-devices-status"></span><span id="cua-devices-enroll"></span><span id="cua-devices-approve"></span><span id="cua-devices-ls"></span><span id="cua-devices-rename"></span><span id="cua-devices-revoke"></span><span id="cua-devices-audit"></span>[`cua devices`](/cua-cli/reference/cli/devices#cua-devices) | This device as a client of your cua.ai account on the relay: enroll (second factor), approve other devices, list, rename, revoke, and the audit log of who accessed what. | [`status`](/cua-cli/reference/cli/devices#cua-devices-status), [`enroll`](/cua-cli/reference/cli/devices#cua-devices-enroll), [`approve`](/cua-cli/reference/cli/devices#cua-devices-approve), [`ls`](/cua-cli/reference/cli/devices#cua-devices-ls), [`rename`](/cua-cli/reference/cli/devices#cua-devices-rename), [`revoke`](/cua-cli/reference/cli/devices#cua-devices-revoke), [`audit`](/cua-cli/reference/cli/devices#cua-devices-audit) |
-
-### `cua team`
-
-Teams (organizations), their members, machines and device approvals. [Reference](/cua-cli/reference/cli/team).
-
-| Command | Description | Subcommands |
-| --- | --- | --- |
-| <span id="cua-team-create"></span><span id="cua-team-ls"></span><span id="cua-team-show"></span><span id="cua-team-invite"></span><span id="cua-team-join"></span><span id="cua-team-leave"></span><span id="cua-team-remove-member"></span><span id="cua-team-set-role"></span><span id="cua-team-devices"></span><span id="cua-team-approve"></span><span id="cua-team-deny"></span><span id="cua-team-request"></span><span id="cua-team-add-machine"></span><span id="cua-team-remove-machine"></span><span id="cua-team-audit"></span><span id="cua-team-delete"></span>[`cua team`](/cua-cli/reference/cli/team#cua-team) | Teams (organizations of your cua.ai account) share machines with every member and their agents. | [`create`](/cua-cli/reference/cli/team#cua-team-create), [`ls`](/cua-cli/reference/cli/team#cua-team-ls), [`show`](/cua-cli/reference/cli/team#cua-team-show), [`invite`](/cua-cli/reference/cli/team#cua-team-invite), [`join`](/cua-cli/reference/cli/team#cua-team-join), [`leave`](/cua-cli/reference/cli/team#cua-team-leave), [`remove-member`](/cua-cli/reference/cli/team#cua-team-remove-member), [`set-role`](/cua-cli/reference/cli/team#cua-team-set-role), [`devices`](/cua-cli/reference/cli/team#cua-team-devices), [`approve`](/cua-cli/reference/cli/team#cua-team-approve), [`deny`](/cua-cli/reference/cli/team#cua-team-deny), [`request`](/cua-cli/reference/cli/team#cua-team-request), [`add-machine`](/cua-cli/reference/cli/team#cua-team-add-machine), [`remove-machine`](/cua-cli/reference/cli/team#cua-team-remove-machine), [`audit`](/cua-cli/reference/cli/team#cua-team-audit), [`delete`](/cua-cli/reference/cli/team#cua-team-delete) |
-
-### `cua usage`
-
-Your hosted relay allowance this month: live sessions and relay hours. [Reference](/cua-cli/reference/cli/usage).
-
-| Command | Description | Subcommands |
-| --- | --- | --- |
-| [`cua usage`](/cua-cli/reference/cli/usage#cua-usage) | Your relay allowance this month: live sessions, relay hours, and your plan. | |
-
-### `cua teleport`
-
-Move a desktop app session into a sandbox. [Reference](/cua-cli/reference/cli/teleport).
-
-| Command | Description | Subcommands |
-| --- | --- | --- |
-| <span id="cua-teleport-providers"></span><span id="cua-teleport-manifest"></span><span id="cua-teleport-push"></span>[`cua teleport`](/cua-cli/reference/cli/teleport#cua-teleport) | Move a desktop app session (tabs, profile, sign-in) into a sandbox. | [`providers`](/cua-cli/reference/cli/teleport#cua-teleport-providers), [`manifest`](/cua-cli/reference/cli/teleport#cua-teleport-manifest), [`push`](/cua-cli/reference/cli/teleport#cua-teleport-push) |
-
-### `cua volume`
-
-Cua Volume: files, versions, grants, access requests and audit of the volume every Space and agent shares. [Reference](/cua-cli/reference/cli/volume).
-
-| Command | Description | Subcommands |
-| --- | --- | --- |
-| <span id="cua-volume-ls"></span><span id="cua-volume-cat"></span><span id="cua-volume-put"></span><span id="cua-volume-rm"></span><span id="cua-volume-history"></span><span id="cua-volume-restore"></span><span id="cua-volume-grant"></span><span id="cua-volume-revoke"></span><span id="cua-volume-grants"></span><span id="cua-volume-requests"></span><span id="cua-volume-approve"></span><span id="cua-volume-deny"></span><span id="cua-volume-audit"></span><span id="cua-volume-mount"></span><span id="cua-volume-unmount"></span><span id="cua-volume-status"></span><span id="cua-volume-config"></span><span id="cua-volume-config-show"></span><span id="cua-volume-config-set"></span><span id="cua-volume-config-set-keys"></span>[`cua volume`](/cua-cli/reference/cli/volume#cua-volume) | Cua Volume: the versioned volume every Space and agent shares (public/, agents/&lt;agent&gt;/, spaces/&lt;space&gt;/), its grants and audit. | [`ls`](/cua-cli/reference/cli/volume#cua-volume-ls), [`cat`](/cua-cli/reference/cli/volume#cua-volume-cat), [`put`](/cua-cli/reference/cli/volume#cua-volume-put), [`rm`](/cua-cli/reference/cli/volume#cua-volume-rm), [`history`](/cua-cli/reference/cli/volume#cua-volume-history), [`restore`](/cua-cli/reference/cli/volume#cua-volume-restore), [`grant`](/cua-cli/reference/cli/volume#cua-volume-grant), [`revoke`](/cua-cli/reference/cli/volume#cua-volume-revoke), [`grants`](/cua-cli/reference/cli/volume#cua-volume-grants), [`requests`](/cua-cli/reference/cli/volume#cua-volume-requests), [`approve`](/cua-cli/reference/cli/volume#cua-volume-approve), [`deny`](/cua-cli/reference/cli/volume#cua-volume-deny), [`audit`](/cua-cli/reference/cli/volume#cua-volume-audit), [`mount`](/cua-cli/reference/cli/volume#cua-volume-mount), [`unmount`](/cua-cli/reference/cli/volume#cua-volume-unmount), [`status`](/cua-cli/reference/cli/volume#cua-volume-status), [`config`](/cua-cli/reference/cli/volume#cua-volume-config), [`config show`](/cua-cli/reference/cli/volume#cua-volume-config-show), [`config set`](/cua-cli/reference/cli/volume#cua-volume-config-set), [`config set-keys`](/cua-cli/reference/cli/volume#cua-volume-config-set-keys) |
-
-### `cua keyvault`
-
-Set up, unlock and lock the Cua Keyvault, with the OS key store or a passphrase. [Reference](/cua-cli/reference/cli/keyvault).
-
-| Command | Description | Subcommands |
-| --- | --- | --- |
-| <span id="cua-keyvault-status"></span><span id="cua-keyvault-init"></span><span id="cua-keyvault-unlock"></span><span id="cua-keyvault-lock"></span><span id="cua-keyvault-import-passwords"></span><span id="cua-keyvault-import-session"></span><span id="cua-keyvault-requests"></span><span id="cua-keyvault-approve"></span><span id="cua-keyvault-deny"></span>[`cua keyvault`](/cua-cli/reference/cli/keyvault#cua-keyvault) | The Cua Keyvault the daemon hosts: status, init, unlock, lock, saved passwords and approvals. | [`status`](/cua-cli/reference/cli/keyvault#cua-keyvault-status), [`init`](/cua-cli/reference/cli/keyvault#cua-keyvault-init), [`unlock`](/cua-cli/reference/cli/keyvault#cua-keyvault-unlock), [`lock`](/cua-cli/reference/cli/keyvault#cua-keyvault-lock), [`import-passwords`](/cua-cli/reference/cli/keyvault#cua-keyvault-import-passwords), [`import-session`](/cua-cli/reference/cli/keyvault#cua-keyvault-import-session), [`requests`](/cua-cli/reference/cli/keyvault#cua-keyvault-requests), [`approve`](/cua-cli/reference/cli/keyvault#cua-keyvault-approve), [`deny`](/cua-cli/reference/cli/keyvault#cua-keyvault-deny) |
-
-### `cua spacesd`
-
-Talk to a cua-spacesd directly by URL. [Reference](/cua-cli/reference/cli/spacesd).
-
-| Command | Description | Subcommands |
-| --- | --- | --- |
-| <span id="cua-spacesd-caps"></span><span id="cua-spacesd-exec"></span><span id="cua-spacesd-cp"></span><span id="cua-spacesd-shell"></span><span id="cua-spacesd-targets"></span><span id="cua-spacesd-call"></span>[`cua spacesd`](/cua-cli/reference/cli/spacesd#cua-spacesd) | Talk to a cua-spacesd directly by URL. | [`caps`](/cua-cli/reference/cli/spacesd#cua-spacesd-caps), [`exec`](/cua-cli/reference/cli/spacesd#cua-spacesd-exec), [`cp`](/cua-cli/reference/cli/spacesd#cua-spacesd-cp), [`shell`](/cua-cli/reference/cli/spacesd#cua-spacesd-shell), [`targets`](/cua-cli/reference/cli/spacesd#cua-spacesd-targets), [`call`](/cua-cli/reference/cli/spacesd#cua-spacesd-call) |
-
-### `cua daemon`
-
-Start, stop and inspect the cua daemon. [Reference](/cua-cli/reference/cli/daemon).
-
-| Command | Description | Subcommands |
-| --- | --- | --- |
-| <span id="cua-daemon-start"></span><span id="cua-daemon-stop"></span><span id="cua-daemon-status"></span><span id="cua-daemon-mcp"></span>[`cua daemon`](/cua-cli/reference/cli/daemon#cua-daemon) | The cua daemon. | [`start`](/cua-cli/reference/cli/daemon#cua-daemon-start), [`stop`](/cua-cli/reference/cli/daemon#cua-daemon-stop), [`status`](/cua-cli/reference/cli/daemon#cua-daemon-status), [`mcp`](/cua-cli/reference/cli/daemon#cua-daemon-mcp) |
-
-### `cua cache`
-
-See and reclaim the disk used by images, sandboxes, builds and logs. [Reference](/cua-cli/reference/cli/cache).
-
-| Command | Description | Subcommands |
-| --- | --- | --- |
-| <span id="cua-cache-ls"></span><span id="cua-cache-du"></span><span id="cua-cache-prune"></span><span id="cua-cache-config"></span>[`cua cache`](/cua-cli/reference/cli/cache#cua-cache) | Disk used by images, sandboxes, builds and logs, and its cleanup. | [`ls`](/cua-cli/reference/cli/cache#cua-cache-ls), [`du`](/cua-cli/reference/cli/cache#cua-cache-du), [`prune`](/cua-cli/reference/cli/cache#cua-cache-prune), [`config`](/cua-cli/reference/cli/cache#cua-cache-config) |
-
-### `cua runtime`
-
-Inspect and provision local runtimes. [Reference](/cua-cli/reference/cli/runtime).
-
-| Command | Description | Subcommands |
-| --- | --- | --- |
-| <span id="cua-runtime-doctor"></span><span id="cua-runtime-setup"></span>[`cua runtime`](/cua-cli/reference/cli/runtime#cua-runtime) | Local runtimes (cua-vmm). | [`doctor`](/cua-cli/reference/cli/runtime#cua-runtime-doctor), [`setup`](/cua-cli/reference/cli/runtime#cua-runtime-setup) |
-
-### `cua doctor`
-
-Check the host, an image and a sandbox guest, or eval parity between image variants. [Reference](/cua-cli/reference/cli/doctor).
-
-| Command | Description | Subcommands |
-| --- | --- | --- |
-| <span id="cua-doctor-parity"></span>[`cua doctor`](/cua-cli/reference/cli/doctor#cua-doctor) | Check the host, an image and a sandbox's guest in one report (`cua doctor [REF]`), or eval parity between two variants (`cua doctor parity A B`). | [`parity`](/cua-cli/reference/cli/doctor#cua-doctor-parity) |
-
-### `cua telemetry`
-
-Anonymous usage telemetry (status, off, show-last). [Reference](/cua-cli/reference/cli/telemetry).
-
-| Command | Description | Subcommands |
-| --- | --- | --- |
-| <span id="cua-telemetry-status"></span><span id="cua-telemetry-on"></span><span id="cua-telemetry-off"></span><span id="cua-telemetry-show-last"></span><span id="cua-telemetry-reset-id"></span><span id="cua-telemetry-schema"></span>[`cua telemetry`](/cua-cli/reference/cli/telemetry#cua-telemetry) | Anonymous usage telemetry (status, on, off, show-last, reset-id, schema). | [`status`](/cua-cli/reference/cli/telemetry#cua-telemetry-status), [`on`](/cua-cli/reference/cli/telemetry#cua-telemetry-on), [`off`](/cua-cli/reference/cli/telemetry#cua-telemetry-off), [`show-last`](/cua-cli/reference/cli/telemetry#cua-telemetry-show-last), [`reset-id`](/cua-cli/reference/cli/telemetry#cua-telemetry-reset-id), [`schema`](/cua-cli/reference/cli/telemetry#cua-telemetry-schema) |
+| <span id="cua-auth"></span><span id="cua-auth-login"></span><span id="cua-auth-logout"></span><span id="cua-auth-status"></span><span id="cua-auth-whoami"></span><span id="cua-auth-provider"></span><span id="cua-auth-provider-ls"></span><span id="cua-auth-provider-set"></span><span id="cua-auth-provider-rm"></span>[`cua auth`](/cua-cli/reference/cli/account-and-setup#cua-auth) | Log in to Cua and manage the signed-in session. | [`login`](/cua-cli/reference/cli/account-and-setup#cua-auth-login), [`logout`](/cua-cli/reference/cli/account-and-setup#cua-auth-logout), [`status`](/cua-cli/reference/cli/account-and-setup#cua-auth-status), [`whoami`](/cua-cli/reference/cli/account-and-setup#cua-auth-whoami), [`provider`](/cua-cli/reference/cli/account-and-setup#cua-auth-provider), [`provider ls`](/cua-cli/reference/cli/account-and-setup#cua-auth-provider-ls), [`provider set`](/cua-cli/reference/cli/account-and-setup#cua-auth-provider-set), [`provider rm`](/cua-cli/reference/cli/account-and-setup#cua-auth-provider-rm) |
+| <span id="cua-config"></span><span id="cua-config-list"></span><span id="cua-config-get"></span><span id="cua-config-set"></span><span id="cua-config-unset"></span><span id="cua-config-path"></span>[`cua config`](/cua-cli/reference/cli/account-and-setup#cua-config) | User defaults (~/.cua/config.toml): where sandboxes run when --on is not given (default.on), the default kind and runtime. | [`list`](/cua-cli/reference/cli/account-and-setup#cua-config-list), [`get`](/cua-cli/reference/cli/account-and-setup#cua-config-get), [`set`](/cua-cli/reference/cli/account-and-setup#cua-config-set), [`unset`](/cua-cli/reference/cli/account-and-setup#cua-config-unset), [`path`](/cua-cli/reference/cli/account-and-setup#cua-config-path) |
+| <span id="cua-daemon"></span><span id="cua-daemon-start"></span><span id="cua-daemon-stop"></span><span id="cua-daemon-status"></span><span id="cua-daemon-mcp"></span>[`cua daemon`](/cua-cli/reference/cli/account-and-setup#cua-daemon) | The cua daemon. | [`start`](/cua-cli/reference/cli/account-and-setup#cua-daemon-start), [`stop`](/cua-cli/reference/cli/account-and-setup#cua-daemon-stop), [`status`](/cua-cli/reference/cli/account-and-setup#cua-daemon-status), [`mcp`](/cua-cli/reference/cli/account-and-setup#cua-daemon-mcp) |
+| <span id="cua-doctor"></span><span id="cua-doctor-parity"></span>[`cua doctor`](/cua-cli/reference/cli/account-and-setup#cua-doctor) | Check the host, an image and a sandbox's guest in one report (`cua doctor [REF]`), or eval parity between two variants (`cua doctor parity A B`). | [`parity`](/cua-cli/reference/cli/account-and-setup#cua-doctor-parity) |
+| <span id="cua-telemetry"></span><span id="cua-telemetry-status"></span><span id="cua-telemetry-on"></span><span id="cua-telemetry-off"></span><span id="cua-telemetry-show-last"></span><span id="cua-telemetry-reset-id"></span><span id="cua-telemetry-schema"></span>[`cua telemetry`](/cua-cli/reference/cli/account-and-setup#cua-telemetry) | Anonymous usage telemetry (status, on, off, show-last, reset-id, schema). | [`status`](/cua-cli/reference/cli/account-and-setup#cua-telemetry-status), [`on`](/cua-cli/reference/cli/account-and-setup#cua-telemetry-on), [`off`](/cua-cli/reference/cli/account-and-setup#cua-telemetry-off), [`show-last`](/cua-cli/reference/cli/account-and-setup#cua-telemetry-show-last), [`reset-id`](/cua-cli/reference/cli/account-and-setup#cua-telemetry-reset-id), [`schema`](/cua-cli/reference/cli/account-and-setup#cua-telemetry-schema) |
## Global options
diff --git a/docs/content/docs/cua-cli/reference/cli/keyvault.mdx b/docs/content/docs/cua-cli/reference/cli/keyvault.mdx
deleted file mode 100644
index 9481402d78..0000000000
--- a/docs/content/docs/cua-cli/reference/cli/keyvault.mdx
+++ /dev/null
@@ -1,234 +0,0 @@
----
-title: "cua keyvault"
-description: "Set up, unlock and lock the Cua Keyvault, with the OS key store or a passphrase."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-cli
- Source: cua dump-docs --type cli
- Version: 0.5.0
-*/}
-
-| Command | Description |
-| --- | --- |
-| [`cua keyvault status`](#cua-keyvault-status) | Whether the Keyvault exists and is unlocked, and which protectors (Touch ID with the OS key store, a passphrase) the daemon can use. |
-| [`cua keyvault init`](#cua-keyvault-init) | Create the Keyvault and print its recovery key once. |
-| [`cua keyvault unlock`](#cua-keyvault-unlock) | Unlock the Keyvault with the OS key store, or with its passphrase. |
-| [`cua keyvault lock`](#cua-keyvault-lock) | Lock the Keyvault (unlocking needs the OS key store or the passphrase again). |
-| [`cua keyvault import-passwords`](#cua-keyvault-import-passwords) | Import a browser's saved passwords into the Keyvault, one item per site. |
-| [`cua keyvault import-session`](#cua-keyvault-import-session) | Import a signed-in session (cookies, or a single-app session like Slack's) into the Keyvault, without delivering it anywhere. |
-| [`cua keyvault requests`](#cua-keyvault-requests) | Requests waiting for your approval (site logins, teleports). |
-| [`cua keyvault approve`](#cua-keyvault-approve) | Approve a waiting request (the daemon asks for Touch ID or your login password). |
-| [`cua keyvault deny`](#cua-keyvault-deny) | Decline a waiting request. |
-
-Every command also accepts the [global options](/cua-cli/reference/cli#global-options).
-
-<span id="cua-keyvault"></span>
-
-The Cua Keyvault the daemon hosts: status, init, unlock, lock, saved passwords and approvals. Passphrases are prompted for (or read from stdin), never arguments.
-
-```text output
-cua keyvault [OPTIONS] <COMMAND>
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-keyvault"
-cua keyvault status
-cua keyvault init --passphrase
-cua keyvault unlock --passphrase
-cua keyvault import-passwords --browser chrome
-cua keyvault requests
-cua keyvault approve <request-id>
-cua keyvault lock
-```
-
-## `cua keyvault status`
-
-Whether the Keyvault exists and is unlocked, and which protectors (Touch ID with the OS key store, a passphrase) the daemon can use.
-
-```text output
-cua keyvault status [OPTIONS]
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-keyvault-status"
-cua keyvault status
-cua keyvault status --json
-```
-
-## `cua keyvault init`
-
-Create the Keyvault and print its recovery key once. Uses the OS key store (Touch ID confirms) unless --passphrase or --passphrase-stdin.
-
-```text output
-cua keyvault init [OPTIONS]
-```
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-keyvault-init--passphrase"></span>`--passphrase` | boolean | `false` | Use a passphrase, typed at a terminal prompt with echo off. |
-| <span id="cua-keyvault-init--passphrase-stdin"></span>`--passphrase-stdin` | boolean | `false` | Use a passphrase read from the first line of stdin (scripts). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-keyvault-init"
-# The OS key store (the signed Cua daemon only)
-cua keyvault init
-
-# A passphrase, typed twice at a prompt
-cua keyvault init --passphrase
-
-# Scripts: the passphrase is the first line of stdin
-cua keyvault init --passphrase-stdin
-```
-
-## `cua keyvault unlock`
-
-Unlock the Keyvault with the OS key store, or with its passphrase.
-
-```text output
-cua keyvault unlock [OPTIONS]
-```
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-keyvault-unlock--passphrase"></span>`--passphrase` | boolean | `false` | Use a passphrase, typed at a terminal prompt with echo off. |
-| <span id="cua-keyvault-unlock--passphrase-stdin"></span>`--passphrase-stdin` | boolean | `false` | Use a passphrase read from the first line of stdin (scripts). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-keyvault-unlock"
-cua keyvault unlock
-cua keyvault unlock --passphrase
-```
-
-## `cua keyvault lock`
-
-Lock the Keyvault (unlocking needs the OS key store or the passphrase again).
-
-```text output
-cua keyvault lock [OPTIONS]
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-keyvault-lock"
-cua keyvault lock
-```
-
-## `cua keyvault import-passwords`
-
-Import a browser's saved passwords into the Keyvault, one item per site. They stay sealed: agents sign in with them through `request_site_login` after you approve, and never see them. The daemon asks for Touch ID or your login password.
-
-```text output
-cua keyvault import-passwords [OPTIONS]
-```
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-keyvault-import-passwords--browser"></span>`--browser` | `chrome` | `chrome` | The browser to import from. |
-| <span id="cua-keyvault-import-passwords--profile"></span>`--profile` | string | | The browser profile (name or path); default: the default profile. |
-| <span id="cua-keyvault-import-passwords--site"></span>`--site` | string | | Only this site (a registrable domain such as github.com). Repeatable; default: every saved site. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-keyvault-import-passwords"
-cua keyvault import-passwords --browser chrome
-cua keyvault import-passwords --browser chrome --site github.com --site example.com
-cua keyvault import-passwords --browser chrome --profile "Profile 1"
-```
-
-## `cua keyvault import-session`
-
-Import a signed-in session (cookies, or a single-app session like Slack's) into the Keyvault, without delivering it anywhere. A later `cua teleport push --sandbox NAME` (or the review sheet's "Save to Keyvault") can deliver it; it stays sealed until then. The daemon asks for Touch ID or your login password.
-
-```text output
-cua keyvault import-session [OPTIONS] --app <APP>
-```
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-keyvault-import-session--app"></span>`--app` | string | required | The app to import from (a teleport provider id: `chrome`, `firefox`, `slack`, ...; `cua teleport providers` lists every one on this machine). |
-| <span id="cua-keyvault-import-session--profile"></span>`--profile` | string | | The browser profile (name or path); default: the default profile. Ignored for a single-app provider (Slack, Discord, ...). |
-| <span id="cua-keyvault-import-session--site"></span>`--site` | string | | Only this site's cookies (a registrable domain such as github.com). Repeatable; a browser with none named imports every site's cookies. Ignored (the whole session is one item) for a single-app provider. |
-| <span id="cua-keyvault-import-session--include-storage"></span>`--include-storage` | boolean | `false` | Also carry each named site's localStorage / IndexedDB origins. |
-| <span id="cua-keyvault-import-session--include-passwords"></span>`--include-passwords` | boolean | `false` | Also carry each named site's saved passwords, as part of this same session item (`cua keyvault import-passwords` keeps them as their own items instead, one per site). |
-| <span id="cua-keyvault-import-session--session-only"></span>`--session-only` | boolean | `false` | Only session cookies: drop every persistent cookie. |
-| <span id="cua-keyvault-import-session--drop-long-lived"></span>`--drop-long-lived` | boolean | `false` | Drop persistent cookies that expire more than 30 days out (long-lived refresh tokens), keeping short sessions. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-keyvault-import-session"
-cua keyvault import-session --app chrome
-cua keyvault import-session --app chrome --site github.com --site example.com
-cua keyvault import-session --app firefox --profile "Profile 1"
-cua keyvault import-session --app slack
-```
-
-## `cua keyvault requests`
-
-Requests waiting for your approval (site logins, teleports).
-
-```text output
-cua keyvault requests [OPTIONS]
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-keyvault-requests"
-cua keyvault requests
-cua keyvault requests --json
-```
-
-## `cua keyvault approve`
-
-Approve a waiting request (the daemon asks for Touch ID or your login password). A site login is approved for one sign-in.
-
-```text output
-cua keyvault approve [OPTIONS] <ID>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<ID>` | string | required | The request id (`cua keyvault requests`). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-keyvault-approve"
-cua keyvault approve 5f2c9a0e
-```
-
-## `cua keyvault deny`
-
-Decline a waiting request.
-
-```text output
-cua keyvault deny [OPTIONS] <ID>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<ID>` | string | required | The request id. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-keyvault-deny"
-cua keyvault deny 5f2c9a0e
-```
-
-## Exit codes
-
-| Code | Meaning |
-| --- | --- |
-| `0` | Success. |
-| `1` | Failure, or `cua do` reported an error. |
-| `2` | Invalid argument, or an ambiguous sandbox name (qualify it: `local:NAME`). |
-| `3` | Not found: sandbox, window, skill or image (or an image not published yet). |
-| `4` | Not supported, or not configured (for example no provider credentials). |
-| `5` | No cua-spacesd answered, or a transport failure. |
-| `6` | Unauthenticated or permission denied (by Cua or your cloud account). |
-| `7` | Not enough free disk space (see `cua cache`). |
-| `130` | Cancelled (Ctrl-C during a create): what it made was removed. |
diff --git a/docs/content/docs/cua-cli/reference/cli/mcp.mdx b/docs/content/docs/cua-cli/reference/cli/mcp.mdx
deleted file mode 100644
index c6e875bafd..0000000000
--- a/docs/content/docs/cua-cli/reference/cli/mcp.mdx
+++ /dev/null
@@ -1,52 +0,0 @@
----
-title: "cua mcp"
-description: "The stdio MCP server for AI assistants."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-cli
- Source: cua dump-docs --type cli
- Version: 0.5.0
-*/}
-
-Every command also accepts the [global options](/cua-cli/reference/cli#global-options).
-
-<span id="cua-mcp"></span>
-
-Stdio MCP server exposing sandboxes, computer control and skills.
-
-```text output
-cua mcp [OPTIONS]
-```
-
-Alias: `cua serve-mcp`.
-
-| Flag | Type | Default | Env var | Description |
-| --- | --- | --- | --- | --- |
-| <span id="cua-mcp--permissions"></span>`--permissions` | string | | `CUA_MCP_PERMISSIONS` | Comma-separated permissions or groups (default: all). |
-| <span id="cua-mcp--sandbox"></span>`--sandbox` | string | | `CUA_SANDBOX` | Default sandbox for computer tools. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-mcp"
-# Serve every tool over stdio (what MCP clients launch)
-cua mcp
-
-# Read-only sandbox tools, computer tools on the sandbox dev
-cua mcp --permissions sandbox:readonly,computer:all --sandbox dev
-```
-
-## Exit codes
-
-| Code | Meaning |
-| --- | --- |
-| `0` | Success. |
-| `1` | Failure, or `cua do` reported an error. |
-| `2` | Invalid argument, or an ambiguous sandbox name (qualify it: `local:NAME`). |
-| `3` | Not found: sandbox, window, skill or image (or an image not published yet). |
-| `4` | Not supported, or not configured (for example no provider credentials). |
-| `5` | No cua-spacesd answered, or a transport failure. |
-| `6` | Unauthenticated or permission denied (by Cua or your cloud account). |
-| `7` | Not enough free disk space (see `cua cache`). |
-| `130` | Cancelled (Ctrl-C during a create): what it made was removed. |
diff --git a/docs/content/docs/cua-cli/reference/cli/meta.json b/docs/content/docs/cua-cli/reference/cli/meta.json
index 9745491d51..0fb25b4b0e 100644
--- a/docs/content/docs/cua-cli/reference/cli/meta.json
+++ b/docs/content/docs/cua-cli/reference/cli/meta.json
@@ -2,32 +2,11 @@
"title": "CLI",
"pages": [
"index",
- "auth",
- "sandbox",
- "sandbox-access",
- "config",
- "viewer",
- "do",
- "image",
- "mcp",
- "agent",
+ "spaces-and-computers",
+ "files-teleport-and-keys",
+ "sandboxes",
+ "computer-actions",
"agents",
- "skills",
- "trajectory",
- "spaces",
- "cloud",
- "host",
- "devices",
- "team",
- "usage",
- "teleport",
- "volume",
- "keyvault",
- "spacesd",
- "daemon",
- "cache",
- "runtime",
- "doctor",
- "telemetry"
+ "account-and-setup"
]
}
diff --git a/docs/content/docs/cua-cli/reference/cli/runtime.mdx b/docs/content/docs/cua-cli/reference/cli/runtime.mdx
deleted file mode 100644
index b3756795c8..0000000000
--- a/docs/content/docs/cua-cli/reference/cli/runtime.mdx
+++ /dev/null
@@ -1,78 +0,0 @@
----
-title: "cua runtime"
-description: "Inspect and provision local runtimes."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-cli
- Source: cua dump-docs --type cli
- Version: 0.5.0
-*/}
-
-| Command | Description |
-| --- | --- |
-| [`cua runtime doctor`](#cua-runtime-doctor) | Inspect local runtimes (read-only). |
-| [`cua runtime setup`](#cua-runtime-setup) | Provision local runtimes. |
-
-Every command also accepts the [global options](/cua-cli/reference/cli#global-options).
-
-<span id="cua-runtime"></span>
-
-Local runtimes (cua-vmm).
-
-```text output
-cua runtime [OPTIONS] <COMMAND>
-```
-
-## `cua runtime doctor`
-
-Inspect local runtimes (read-only).
-
-```text output
-cua runtime doctor [OPTIONS]
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-runtime-doctor"
-cua runtime doctor
-```
-
-## `cua runtime setup`
-
-Provision local runtimes.
-
-```text output
-cua runtime setup [OPTIONS] [COMPONENTS]...
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<COMPONENTS>...` | string | optional | Components: `qemu`, `lume`, `runsc` (default: everything provisionable). Repeatable. |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-runtime-setup--dry-run"></span>`--dry-run` | boolean | `false` | Only report what would be done. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-runtime-setup"
-# See what would be installed
-cua runtime setup --dry-run
-cua runtime setup qemu
-```
-
-## Exit codes
-
-| Code | Meaning |
-| --- | --- |
-| `0` | Success. |
-| `1` | Failure, or `cua do` reported an error. |
-| `2` | Invalid argument, or an ambiguous sandbox name (qualify it: `local:NAME`). |
-| `3` | Not found: sandbox, window, skill or image (or an image not published yet). |
-| `4` | Not supported, or not configured (for example no provider credentials). |
-| `5` | No cua-spacesd answered, or a transport failure. |
-| `6` | Unauthenticated or permission denied (by Cua or your cloud account). |
-| `7` | Not enough free disk space (see `cua cache`). |
-| `130` | Cancelled (Ctrl-C during a create): what it made was removed. |
diff --git a/docs/content/docs/cua-cli/reference/cli/sandbox-access.mdx b/docs/content/docs/cua-cli/reference/cli/sandbox-access.mdx
deleted file mode 100644
index 2e87f1ec3d..0000000000
--- a/docs/content/docs/cua-cli/reference/cli/sandbox-access.mdx
+++ /dev/null
@@ -1,492 +0,0 @@
----
-title: "Sandbox access"
-description: "Run commands, copy files, forward ports, take screenshots, reach the MCP and view a sandbox (`cua sandbox exec`, `cp`, `view`, ...)."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-cli
- Source: cua dump-docs --type cli
- Version: 0.5.0
-*/}
-
-| Command | Description |
-| --- | --- |
-| [`cua sandbox exec`](#cua-sandbox-exec) | Run a command (joined into one shell line, as `sh -c`). |
-| [`cua sandbox shell`](#cua-sandbox-shell) | Interactive shell (PTY), or run a command in a PTY. |
-| [`cua sandbox cp`](#cua-sandbox-cp) | Copy files: `cp NAME:/guest/path LOCAL` or `cp LOCAL NAME:/guest/path` (NAME may be a ref: `cp local:box:/tmp/x .`). |
-| [`cua sandbox overlay`](#cua-sandbox-overlay) | Inject freshly built binaries into a running sandbox (see `create --overlay`): NAME=PATH or NAME=PATH:GUEST_PATH. |
-| [`cua sandbox logs`](#cua-sandbox-logs) | Show logs: the backend console (QEMU serial, container) when there is one, else the guest system log through the spacesd. |
-| [`cua sandbox port-forward`](#cua-sandbox-port-forward) | Forward a guest port: `port-forward NAME PORT[:LOCAL]` (a local sandbox's port not published at create tunnels through cua-spacesd when the image has it). |
-| [`cua sandbox url`](#cua-sandbox-url) | Print a URL for a named service: usable from this machine (default), or `--public` for a shareable URL that expires (`--ttl`, default 1h; a token URL served by the cua daemon). |
-| [`cua sandbox screenshot`](#cua-sandbox-screenshot) | Save a screenshot (PNG). |
-| [`cua sandbox mcp`](#cua-sandbox-mcp) | Talk to an MCP server a sandbox serves: `mcp NAME SERVICE tools`, `mcp NAME SERVICE call TOOL '{"a":1}'`. |
-| [`cua sandbox mcp config`](#cua-sandbox-mcp-config) | The endpoint URL and headers, for any MCP client. |
-| [`cua sandbox mcp info`](#cua-sandbox-mcp-info) | Server name, version and negotiated protocol revision. |
-| [`cua sandbox mcp tools`](#cua-sandbox-mcp-tools) | List tools. |
-| [`cua sandbox mcp call`](#cua-sandbox-mcp-call) | Call a tool with a JSON object of arguments. |
-| [`cua sandbox mcp resources`](#cua-sandbox-mcp-resources) | List resources. |
-| [`cua sandbox mcp templates`](#cua-sandbox-mcp-templates) | List resource templates. |
-| [`cua sandbox mcp read`](#cua-sandbox-mcp-read) | Read a resource. |
-| [`cua sandbox mcp prompts`](#cua-sandbox-mcp-prompts) | List prompts. |
-| [`cua sandbox mcp prompt`](#cua-sandbox-mcp-prompt) | Render a prompt with a JSON object of string arguments. |
-| [`cua sandbox mcp request`](#cua-sandbox-mcp-request) | Any other method (for example `skills/list`), printing the result. |
-| [`cua sandbox view`](#cua-sandbox-view) | Open the sandbox desktop in the browser (the cua-spacesd HTML5 viewer). |
-
-Every command also accepts the [global options](/cua-cli/reference/cli#global-options).
-
-## `cua sandbox exec`
-
-Run a command (joined into one shell line, as `sh -c`). Exits with the command's own status. A local Lume sandbox without cua-spacesd runs it via SSH (`lume ssh`).
-
-```text output
-cua sandbox exec [OPTIONS] <NAME> <COMMAND>...
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<NAME>` | string | required | Sandbox name or ref (`local:NAME`). |
-| `<COMMAND>...` | string | required | Command and arguments. Repeatable. |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-sandbox-exec--local"></span>`--local` | boolean | `false` | Look NAME up among local sandboxes only (same as `local:NAME`). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-sandbox-exec"
-cua sb exec dev uname -a
-cua sb exec dev 'ls /tmp | wc -l'
-```
-
-## `cua sandbox shell`
-
-Interactive shell (PTY), or run a command in a PTY.
-
-```text output
-cua sandbox shell [OPTIONS] <NAME> [COMMAND]...
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<NAME>` | string | required | Sandbox name or ref (`local:NAME`). |
-| `<COMMAND>...` | string | optional | Command to run instead of the login shell. Repeatable. |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-sandbox-shell--cols"></span>`--cols` | integer | | Terminal width (default: this terminal's). |
-| <span id="cua-sandbox-shell--rows"></span>`--rows` | integer | | Terminal height (default: this terminal's). |
-| <span id="cua-sandbox-shell--local"></span>`--local` | boolean | `false` | Look NAME up among local sandboxes only (same as `local:NAME`). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-sandbox-shell"
-cua sb shell dev
-cua sb shell dev top
-```
-
-## `cua sandbox cp`
-
-Copy files: `cp NAME:/guest/path LOCAL` or `cp LOCAL NAME:/guest/path` (NAME may be a ref: `cp local:box:/tmp/x .`).
-
-```text output
-cua sandbox cp [OPTIONS] <SRC> <DST>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<SRC>` | string | required | Source: a local path or `NAME:/guest/path`. |
-| `<DST>` | string | required | Destination: a local path or `NAME:/guest/path`. |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-sandbox-cp--local"></span>`--local` | boolean | `false` | Look NAME up among local sandboxes only (same as `local:NAME`). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-sandbox-cp"
-# Upload
-cua sb cp ./notes.txt dev:/tmp/notes.txt
-
-# Download
-cua sb cp dev:/tmp/notes.txt .
-```
-
-## `cua sandbox overlay`
-
-Inject freshly built binaries into a running sandbox (see `create --overlay`): NAME=PATH or NAME=PATH:GUEST_PATH.
-
-```text output
-cua sandbox overlay [OPTIONS] <NAME> <OVERLAYS>...
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<NAME>` | string | required | Sandbox name or ref (`local:NAME`). |
-| `<OVERLAYS>...` | string | required | NAME=PATH[:GUEST_PATH] (repeatable). Repeatable. |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-sandbox-overlay--timeout"></span>`--timeout` | integer | `180` | Budget for a cua-spacesd restart, in seconds. |
-| <span id="cua-sandbox-overlay--local"></span>`--local` | boolean | `false` | Look NAME up among local sandboxes only (same as `local:NAME`). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-sandbox-overlay"
-# The cua-driver under test, then check that it is what runs
-cua sb overlay dev cua-driver=./target/release/cua-driver
-cua doctor dev --expect cua-driver=sha256:<sha256>
-
-# The daemon too (restarts it and waits for the new build)
-cua sb overlay dev cua-spacesd=./target/release/cua-spacesd
-```
-
-## `cua sandbox logs`
-
-Show logs: the backend console (QEMU serial, container) when there is one, else the guest system log through the spacesd.
-
-```text output
-cua sandbox logs [OPTIONS] <NAME>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<NAME>` | string | required | Sandbox name or ref (`local:NAME`). |
-
-| Flag | Short | Type | Default | Description |
-| --- | --- | --- | --- | --- |
-| <span id="cua-sandbox-logs--tail"></span>`--tail` | `-n` | integer | `200` | Lines from the end. |
-| <span id="cua-sandbox-logs--source"></span>`--source` | | string | `auto` | auto, console or guest. |
-| <span id="cua-sandbox-logs--local"></span>`--local` | | boolean | `false` | Look NAME up among local sandboxes only (same as `local:NAME`). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-sandbox-logs"
-cua sb logs dev
-cua sb logs dev -n 50 --source guest
-```
-
-## `cua sandbox port-forward`
-
-Forward a guest port: `port-forward NAME PORT[:LOCAL]` (a local sandbox's port not published at create tunnels through cua-spacesd when the image has it).
-
-```text output
-cua sandbox port-forward [OPTIONS] <NAME> <SPEC>
-```
-
-Alias: `cua sandbox forward`.
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<NAME>` | string | required | Sandbox name or ref (`local:NAME`). |
-| `<SPEC>` | string | required | PORT or PORT:LOCAL_PORT. |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-sandbox-port-forward--local"></span>`--local` | boolean | `false` | Look NAME up among local sandboxes only (same as `local:NAME`). |
-| <span id="cua-sandbox-port-forward--no-wait"></span>`--no-wait` | boolean | `false` | Print the target and exit instead of forwarding until Ctrl-C. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-sandbox-port-forward"
-# Guest port 8080 on localhost:8080 until Ctrl-C
-cua sb port-forward dev 8080
-
-# Guest port 5432 on localhost:15432
-cua sb port-forward local:dev 5432:15432
-```
-
-## `cua sandbox url`
-
-Print a URL for a named service: usable from this machine (default), or `--public` for a shareable URL that expires (`--ttl`, default 1h; a token URL served by the cua daemon).
-
-```text output
-cua sandbox url [OPTIONS] <NAME> <SERVICE>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<NAME>` | string | required | Sandbox name or ref (`local:NAME`). |
-| `<SERVICE>` | string | required | Service name (from `--service` at create time). |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-sandbox-url--ttl"></span>`--ttl` | integer | | Lifetime of a --public URL (`10m`, `1h`, `3600`; 60 s to 24 h). |
-| <span id="cua-sandbox-url--local"></span>`--local` | boolean | `false` | Look NAME up among local sandboxes only (same as `local:NAME`). |
-| <span id="cua-sandbox-url--public"></span>`--public` | boolean | `false` | A shareable URL that expires. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-sandbox-url"
-cua sb url dev web
-
-# A shareable URL for 10 minutes
-cua sb url local:dev web --public --ttl 10m
-```
-
-## `cua sandbox screenshot`
-
-Save a screenshot (PNG). A local Lume sandbox without cua-spacesd is captured via VNC.
-
-```text output
-cua sandbox screenshot [OPTIONS] <NAME>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<NAME>` | string | required | Sandbox name or ref (`local:NAME`). |
-
-| Flag | Short | Type | Default | Description |
-| --- | --- | --- | --- | --- |
-| <span id="cua-sandbox-screenshot--output"></span>`--output` | `-o` | path | `screenshot.png` | Output file (PNG). |
-| <span id="cua-sandbox-screenshot--local"></span>`--local` | | boolean | `false` | Look NAME up among local sandboxes only (same as `local:NAME`). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-sandbox-screenshot"
-cua sb screenshot dev -o desktop.png
-```
-
-## `cua sandbox mcp`
-
-Talk to an MCP server a sandbox serves: `mcp NAME SERVICE tools`, `mcp NAME SERVICE call TOOL '{"a":1}'`. Generic streamable HTTP over the service; no cua-spacesd needed.
-
-```text output
-cua sandbox mcp [OPTIONS] <NAME> <SERVICE> <COMMAND>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<NAME>` | string | required | Sandbox name or ref (`local:NAME`). |
-| `<SERVICE>` | string | required | Service name (for example `mcp`, or `port-8765`). |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-sandbox-mcp--path"></span>`--path` | string | `/mcp` | Endpoint path on the service. |
-| <span id="cua-sandbox-mcp--local"></span>`--local` | boolean | `false` | Look NAME up among local sandboxes only (same as `local:NAME`). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-sandbox-mcp"
-cua sb mcp dev mcp tools
-cua sb mcp dev mcp call echo '{"text":"hi"}'
-```
-
-### `cua sandbox mcp config`
-
-The endpoint URL and headers, for any MCP client. Credential headers print masked (`Bearer ****`) unless `--show-secrets`.
-
-```text output
-cua sandbox mcp <NAME> <SERVICE> config [OPTIONS]
-```
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-sandbox-mcp-config--show-secrets"></span>`--show-secrets` | boolean | `false` | Print credential header values in full. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-sandbox-mcp-config"
-cua sb mcp dev mcp config
-```
-
-### `cua sandbox mcp info`
-
-Server name, version and negotiated protocol revision.
-
-```text output
-cua sandbox mcp <NAME> <SERVICE> info [OPTIONS]
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-sandbox-mcp-info"
-cua sb mcp dev mcp info
-```
-
-### `cua sandbox mcp tools`
-
-List tools.
-
-```text output
-cua sandbox mcp <NAME> <SERVICE> tools [OPTIONS]
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-sandbox-mcp-tools"
-cua sb mcp dev mcp tools
-```
-
-### `cua sandbox mcp call`
-
-Call a tool with a JSON object of arguments.
-
-```text output
-cua sandbox mcp <NAME> <SERVICE> call [OPTIONS] <TOOL> [ARGUMENTS]
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<TOOL>` | string | required | Tool name. |
-| `<ARGUMENTS>` | string | optional | Arguments (JSON object). Default `{}`. |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-sandbox-mcp-call--out"></span>`--out` | path | | Save image, audio and blob content here instead of summarizing. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-sandbox-mcp-call"
-cua sb mcp dev mcp call echo '{"text":"hi"}'
-cua sb mcp dev mcp call screenshot --out ./shots
-```
-
-### `cua sandbox mcp resources`
-
-List resources.
-
-```text output
-cua sandbox mcp <NAME> <SERVICE> resources [OPTIONS]
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-sandbox-mcp-resources"
-cua sb mcp dev mcp resources
-```
-
-### `cua sandbox mcp templates`
-
-List resource templates.
-
-```text output
-cua sandbox mcp <NAME> <SERVICE> templates [OPTIONS]
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-sandbox-mcp-templates"
-cua sb mcp dev mcp templates
-```
-
-### `cua sandbox mcp read`
-
-Read a resource.
-
-```text output
-cua sandbox mcp <NAME> <SERVICE> read [OPTIONS] <URI>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<URI>` | string | required | Resource URI. |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-sandbox-mcp-read--out"></span>`--out` | path | | Save blob contents here instead of summarizing. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-sandbox-mcp-read"
-cua sb mcp dev mcp read file:///tmp/report.txt
-```
-
-### `cua sandbox mcp prompts`
-
-List prompts.
-
-```text output
-cua sandbox mcp <NAME> <SERVICE> prompts [OPTIONS]
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-sandbox-mcp-prompts"
-cua sb mcp dev mcp prompts
-```
-
-### `cua sandbox mcp prompt`
-
-Render a prompt with a JSON object of string arguments.
-
-```text output
-cua sandbox mcp <NAME> <SERVICE> prompt [OPTIONS] <NAME> [ARGUMENTS]
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<NAME>` | string | required | Prompt name. |
-| `<ARGUMENTS>` | string | optional | Arguments (JSON object of strings). Default `{}`. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-sandbox-mcp-prompt"
-cua sb mcp dev mcp prompt summarize '{"topic":"logs"}'
-```
-
-### `cua sandbox mcp request`
-
-Any other method (for example `skills/list`), printing the result.
-
-```text output
-cua sandbox mcp <NAME> <SERVICE> request [OPTIONS] <METHOD> [PARAMS]
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<METHOD>` | string | required | JSON-RPC method. |
-| `<PARAMS>` | string | optional | Params (JSON object). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-sandbox-mcp-request"
-cua sb mcp dev mcp request skills/list
-```
-
-## `cua sandbox view`
-
-Open the sandbox desktop in the browser (the cua-spacesd HTML5 viewer). A local Lume sandbox without cua-spacesd opens its VNC display with `lume attach`.
-
-```text output
-cua sandbox view [OPTIONS] <NAME>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<NAME>` | string | required | Sandbox name or ref (`local:NAME`). |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-sandbox-view--service"></span>`--service` | string | | Open this web service of the sandbox instead of the viewer (for images without cua-spacesd that serve their own display page). |
-| <span id="cua-sandbox-view--files"></span>`--files` | string | | Guest folder for uploads and folder sharing (default `~`; `none` turns files off). |
-| <span id="cua-sandbox-view--ttl"></span>`--ttl` | string | | Link lifetime (for example `1h`, `30m`). Default 1h. |
-| <span id="cua-sandbox-view--view-only"></span>`--view-only` | boolean | `false` | Watch only: no input, clipboard, files or microphone. |
-| <span id="cua-sandbox-view--no-open"></span>`--no-open` | boolean | `false` | Print the link without opening a browser. |
-| <span id="cua-sandbox-view--local"></span>`--local` | boolean | `false` | Look NAME up among local sandboxes only (same as `local:NAME`). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-sandbox-view"
-cua sb view dev
-
-# Watch only, print the link instead of opening it
-cua sb view dev --view-only --no-open
-
-# An image that ships its own web display instead of cua-spacesd
-cua sb view old-box --service web
-```
-
-## Exit codes
-
-| Code | Meaning |
-| --- | --- |
-| `0` | Success. |
-| `1` | Failure, or `cua do` reported an error. |
-| `2` | Invalid argument, or an ambiguous sandbox name (qualify it: `local:NAME`). |
-| `3` | Not found: sandbox, window, skill or image (or an image not published yet). |
-| `4` | Not supported, or not configured (for example no provider credentials). |
-| `5` | No cua-spacesd answered, or a transport failure. |
-| `6` | Unauthenticated or permission denied (by Cua or your cloud account). |
-| `7` | Not enough free disk space (see `cua cache`). |
-| `130` | Cancelled (Ctrl-C during a create): what it made was removed. |
diff --git a/docs/content/docs/cua-cli/reference/cli/sandbox.mdx b/docs/content/docs/cua-cli/reference/cli/sandbox.mdx
deleted file mode 100644
index b84447e334..0000000000
--- a/docs/content/docs/cua-cli/reference/cli/sandbox.mdx
+++ /dev/null
@@ -1,279 +0,0 @@
----
-title: "cua sandbox"
-description: "Create, list, connect to, suspend and delete sandboxes, local or on your own machines."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-cli
- Source: cua dump-docs --type cli
- Version: 0.5.0
-*/}
-
-| Command | Description |
-| --- | --- |
-| [`cua sandbox create`](#cua-sandbox-create) | Create a sandbox: `cua sb create IMAGE [--on local\|direct:<addr>] [--kind auto\|container\|vm] [--runtime auto\|gvisor\|runc\|qemu\|lume]`. |
-| [`cua sandbox launch`](#cua-sandbox-launch) | Deprecated alias of `create`. |
-| [`cua sandbox connect`](#cua-sandbox-connect) | Reattach to a sandbox (NAME or a ref such as `local:NAME`) and print it. |
-| [`cua sandbox ls`](#cua-sandbox-ls) | List sandboxes: local and direct, each with its `location`; `--local` filters. |
-| [`cua sandbox info`](#cua-sandbox-info) | Show one sandbox. |
-| [`cua sandbox suspend`](#cua-sandbox-suspend) | Suspend (pause/snapshot). |
-| [`cua sandbox resume`](#cua-sandbox-resume) | Resume. |
-| [`cua sandbox restart`](#cua-sandbox-restart) | Restart. |
-| [`cua sandbox rm`](#cua-sandbox-rm) | Delete a sandbox. |
-
-Every command also accepts the [global options](/cua-cli/reference/cli#global-options).
-
-<span id="cua-sandbox"></span>
-
-Sandboxes: local or an existing machine (direct).
-
-```text output
-cua sandbox [OPTIONS] <COMMAND>
-```
-
-Alias: `cua sb`.
-
-## `cua sandbox create`
-
-Create a sandbox: `cua sb create IMAGE [--on local|direct:<addr>] [--kind auto|container|vm] [--runtime auto|gvisor|runc|qemu|lume]`.
-
-```text output
-cua sandbox create [OPTIONS] [IMAGE] [-- <COMMAND>...]
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<IMAGE>` | string | optional | Image: a registry reference (`ghcr.io/org/image:tag`), an alias (`linux`, `ubuntu`, `windows`, `macos[:tahoe\|sequoia]`, `omarchy`). |
-| `<COMMAND>...` | string | optional | The sandbox's command, after `--` (replaces the image's entrypoint): `cua sb create python:3.12-slim --service mcp=8765 -- python -m srv`. Repeatable. |
-
-| Flag | Type | Default | Env var | Description |
-| --- | --- | --- | --- | --- |
-| <span id="cua-sandbox-create--on"></span>`--on` | string | | | Where it runs: local, direct:&lt;addr&gt; (an existing machine running cua-spacesd), or a registered provider. Default: `cua config get default.on` (`CUA_DEFAULT_ON`), else local. |
-| <span id="cua-sandbox-create--kind"></span>`--kind` | string | | | What kind of machine: auto (from the image: a container when it has a container rootfs; macOS, Windows and disk-only images are VMs), container or vm. |
-| <span id="cua-sandbox-create--runtime"></span>`--runtime` | string | | | Which engine: auto (the safest available) or one the location offers for the kind. Local: gvisor or runc (containers), qemu or lume (VMs). A local sandbox with --sidecar needs `--runtime runc` where gVisor would run (separate gVisor containers cannot share a network namespace). |
-| <span id="cua-sandbox-create--tier"></span>`--tier` | string | | | Image tier for an alias: `slim`, `full` (default) or macOS `xcode`. |
-| <span id="cua-sandbox-create--name"></span>`--name` | string | | | Sandbox name (generated when omitted). |
-| <span id="cua-sandbox-create--open"></span>`--open` | string | | | With --browser: open this URL. |
-| <span id="cua-sandbox-create--install"></span>`--install` | string | | | Install these into the sandbox once it is up: harness ids (`claude-code`) or installables (`blender`, `vscode`, `node`), pinned and checksum-verified (`cua agent ensure` later does the same). Repeatable. |
-| <span id="cua-sandbox-create--cpu"></span>`--cpu` | integer | | | vCPUs. Alias: `--cpus`. |
-| <span id="cua-sandbox-create--memory"></span>`--memory` | string | | | Memory, e.g. 8GB or 4096MB (a bare number is GB). |
-| <span id="cua-sandbox-create--network"></span>`--network` | `default` \| `none` | | | Guest network: `default` (outbound network, like a Docker container) or `none` (no egress; published ports still work). `none` needs a local QEMU VM; containers and Lume reject it. |
-| <span id="cua-sandbox-create--disk"></span>`--disk` | string | | | Disk size (accepted; the image decides today). |
-| <span id="cua-sandbox-create--port"></span>`--port` | string | | | Expose a guest port: NAME=PORT (a named service) or PORT (repeatable). Alias: `--service`. |
-| <span id="cua-sandbox-create--wait"></span>`--wait` | string | | | Wait until ready: tcp:SERVICE, http:SERVICE/path, a guest port (tcp:PORT, http:PORT/path), or `desktop` (the desktop session takes input: display, window manager and cua-driver) (repeatable). Alias: `--wait-for`. |
-| <span id="cua-sandbox-create--ready-timeout"></span>`--ready-timeout` | integer | | | Readiness budget in seconds, counted once the image is downloaded, the wait for the image's cua-spacesd included (default 600, plus up to 120 for cua-spacesd). |
-| <span id="cua-sandbox-create--overlay"></span>`--overlay` | string | | | Inject a freshly built binary once the sandbox is up: NAME=PATH (`cua-driver`, `cua-spacesd`) or NAME=PATH:GUEST_PATH (repeatable). It replaces the guest file atomically, is recorded with its sha256 (checked by `cua doctor`) and what runs it is restarted. Needs cua-spacesd in the image. |
-| <span id="cua-sandbox-create--env"></span>`--env` | string | | | Environment KEY=VALUE for the sandbox (repeatable). |
-| <span id="cua-sandbox-create--sidecar"></span>`--sidecar` | string | | | A sidecar container, reachable from the sandbox at its name (it reaches the sandbox at `main`): IMAGE[,port=PORT][,env=K=V][,name=NAME] (repeatable; `port=` and `env=` repeat too). Local containers; it needs `--runtime runc` where gVisor would run. With sidecars the service names main, sidecars and sc are reserved. |
-| <span id="cua-sandbox-create--registry-secret"></span>`--registry-secret` | string | | | Credentials for a private image: env:USER_VAR:PASSWORD_VAR (read from this environment) or aws-ecr[:REGION] (the AWS CLI's login token). |
-| <span id="cua-sandbox-create--token"></span>`--token` | string | | `CUA_ENV_TOKEN` | spacesd token (direct: sandboxes). |
-| <span id="cua-sandbox-create--gpu"></span>`--gpu` | string | | | A GPU: the runtime's own (`--gpu`), or an option `cua spaces gpus` lists (`paravirtual`: GPU acceleration for a macOS VM on Lume, experimental; `virgl`: QEMU on Linux; `nvidia`: a runc container on Linux; a provider's GPU type). |
-| <span id="cua-sandbox-create--browser"></span>`--browser` | boolean | `false` | | Start Chromium in it for the cua-driver browser tools (IMAGE defaults to `linux`). |
-| <span id="cua-sandbox-create--view"></span>`--view` | boolean | `false` | | Open the desktop in the HTML5 viewer once the sandbox is ready (`cua sb view`). |
-| <span id="cua-sandbox-create--keep-on-failure"></span>`--keep-on-failure` | boolean | `false` | | Keep the sandbox (VM or container) when it fails to become ready, to debug it; the ref and how to delete it are printed. Default: a failed create deletes it. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-sandbox-create"
-# A Linux desktop on this machine (a gVisor container)
-cua sb create linux --name dev
-
-# A web server container, ready when its HTTP service answers
-cua sb create python:3.12-slim --service web=8000 --wait http:web/ -- python -m http.server 8000
-
-# The same Linux image as a VM
-cua sb create linux --kind vm --name dev
-```
-
-## `cua sandbox launch`
-
-Deprecated alias of `create`.
-
-```text output
-cua sandbox launch [OPTIONS] [IMAGE]
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-sandbox-launch"
-cua sb launch linux --name dev
-```
-
-## `cua sandbox connect`
-
-Reattach to a sandbox (NAME or a ref such as `local:NAME`) and print it.
-
-```text output
-cua sandbox connect [OPTIONS] <NAME>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<NAME>` | string | required | Sandbox name or ref (`local:NAME`). |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-sandbox-connect--local"></span>`--local` | boolean | `false` | Look NAME up among local sandboxes only (same as `local:NAME`). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-sandbox-connect"
-cua sb connect dev
-cua sb connect local:dev
-```
-
-## `cua sandbox ls`
-
-List sandboxes: local and direct, each with its `location`; `--local` filters.
-
-```text output
-cua sandbox ls [OPTIONS]
-```
-
-Alias: `cua sandbox list`.
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-sandbox-ls--local"></span>`--local` | boolean | `false` | Only local sandboxes. |
-| <span id="cua-sandbox-ls--no-size"></span>`--no-size` | boolean | `false` | Skip the SIZE column (disk used by each local sandbox), which reads the VM, container and Lume stores. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-sandbox-ls"
-cua sb ls
-cua sb ls --local --json
-```
-
-## `cua sandbox info`
-
-Show one sandbox.
-
-```text output
-cua sandbox info [OPTIONS] <NAME>
-```
-
-Alias: `cua sandbox get`.
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<NAME>` | string | required | Sandbox name or ref (`local:NAME`). |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-sandbox-info--local"></span>`--local` | boolean | `false` | Look NAME up among local sandboxes only (same as `local:NAME`). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-sandbox-info"
-cua sb info dev
-cua sb info local:dev --json
-```
-
-## `cua sandbox suspend`
-
-Suspend (pause/snapshot).
-
-```text output
-cua sandbox suspend [OPTIONS] <NAME>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<NAME>` | string | required | Sandbox name or ref (`local:NAME`). |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-sandbox-suspend--local"></span>`--local` | boolean | `false` | Look NAME up among local sandboxes only (same as `local:NAME`). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-sandbox-suspend"
-cua sb suspend dev
-```
-
-## `cua sandbox resume`
-
-Resume.
-
-```text output
-cua sandbox resume [OPTIONS] <NAME>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<NAME>` | string | required | Sandbox name or ref (`local:NAME`). |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-sandbox-resume--local"></span>`--local` | boolean | `false` | Look NAME up among local sandboxes only (same as `local:NAME`). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-sandbox-resume"
-cua sb resume dev
-```
-
-## `cua sandbox restart`
-
-Restart.
-
-```text output
-cua sandbox restart [OPTIONS] <NAME>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<NAME>` | string | required | Sandbox name or ref (`local:NAME`). |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-sandbox-restart--local"></span>`--local` | boolean | `false` | Look NAME up among local sandboxes only (same as `local:NAME`). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-sandbox-restart"
-cua sb restart dev
-```
-
-## `cua sandbox rm`
-
-Delete a sandbox.
-
-```text output
-cua sandbox rm [OPTIONS] <NAME>
-```
-
-Alias: `cua sandbox delete`.
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<NAME>` | string | required | Sandbox name or ref (`local:NAME`). |
-
-| Flag | Short | Type | Default | Description |
-| --- | --- | --- | --- | --- |
-| <span id="cua-sandbox-rm--force"></span>`--force` | `-f` | boolean | `false` | Skip the confirmation prompt. Required when there is no terminal to ask on (scripts, agents): without it nothing is deleted. |
-| <span id="cua-sandbox-rm--local"></span>`--local` | | boolean | `false` | Look NAME up among local sandboxes only (same as `local:NAME`). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-sandbox-rm"
-cua sb rm dev
-
-# Without the prompt (required in scripts and agents)
-cua sb rm local:dev --force
-```
-
-## Exit codes
-
-| Code | Meaning |
-| --- | --- |
-| `0` | Success. |
-| `1` | Failure, or `cua do` reported an error. |
-| `2` | Invalid argument, or an ambiguous sandbox name (qualify it: `local:NAME`). |
-| `3` | Not found: sandbox, window, skill or image (or an image not published yet). |
-| `4` | Not supported, or not configured (for example no provider credentials). |
-| `5` | No cua-spacesd answered, or a transport failure. |
-| `6` | Unauthenticated or permission denied (by Cua or your cloud account). |
-| `7` | Not enough free disk space (see `cua cache`). |
-| `130` | Cancelled (Ctrl-C during a create): what it made was removed. |
diff --git a/docs/content/docs/cua-cli/reference/cli/sandboxes.mdx b/docs/content/docs/cua-cli/reference/cli/sandboxes.mdx
new file mode 100644
index 0000000000..991c5a7606
--- /dev/null
+++ b/docs/content/docs/cua-cli/reference/cli/sandboxes.mdx
@@ -0,0 +1,1382 @@
+---
+title: "Sandboxes and images"
+description: "Create, reach and delete sandboxes; pull, build and push images; local runtimes, disk cleanup, your own cloud account and the sandbox viewer."
+---
+
+{/*
+ AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
+ Generated by: pnpm --dir docs docs:generate:cua-cli
+ Source: cua dump-docs --type cli
+ Version: 0.5.0
+*/}
+
+| Command | Description |
+| --- | --- |
+| [`cua sandbox`](#cua-sandbox) | Sandboxes: local or an existing machine (direct). |
+| [`cua sandbox create`](#cua-sandbox-create) | Create a sandbox: `cua sb create IMAGE [--on local\|direct:<addr>] [--kind auto\|container\|vm] [--runtime auto\|gvisor\|runc\|qemu\|lume]`. |
+| [`cua sandbox launch`](#cua-sandbox-launch) | Deprecated alias of `create`. |
+| [`cua sandbox connect`](#cua-sandbox-connect) | Reattach to a sandbox (NAME or a ref such as `local:NAME`) and print it. |
+| [`cua sandbox ls`](#cua-sandbox-ls) | List sandboxes: local and direct, each with its `location`; `--local` filters. |
+| [`cua sandbox info`](#cua-sandbox-info) | Show one sandbox. |
+| [`cua sandbox suspend`](#cua-sandbox-suspend) | Suspend (pause/snapshot). |
+| [`cua sandbox resume`](#cua-sandbox-resume) | Resume. |
+| [`cua sandbox restart`](#cua-sandbox-restart) | Restart. |
+| [`cua sandbox rm`](#cua-sandbox-rm) | Delete a sandbox. |
+| [`cua sandbox exec`](#cua-sandbox-exec) | Run a command (joined into one shell line, as `sh -c`). |
+| [`cua sandbox shell`](#cua-sandbox-shell) | Interactive shell (PTY), or run a command in a PTY. |
+| [`cua sandbox cp`](#cua-sandbox-cp) | Copy files: `cp NAME:/guest/path LOCAL` or `cp LOCAL NAME:/guest/path` (NAME may be a ref: `cp local:box:/tmp/x .`). |
+| [`cua sandbox overlay`](#cua-sandbox-overlay) | Inject freshly built binaries into a running sandbox (see `create --overlay`): NAME=PATH or NAME=PATH:GUEST_PATH. |
+| [`cua sandbox logs`](#cua-sandbox-logs) | Show logs: the backend console (QEMU serial, container) when there is one, else the guest system log through the spacesd. |
+| [`cua sandbox port-forward`](#cua-sandbox-port-forward) | Forward a guest port: `port-forward NAME PORT[:LOCAL]` (a local sandbox's port not published at create tunnels through cua-spacesd when the image has it). |
+| [`cua sandbox url`](#cua-sandbox-url) | Print a URL for a named service: usable from this machine (default), or `--public` for a shareable URL that expires (`--ttl`, default 1h; a token URL served by the cua daemon). |
+| [`cua sandbox screenshot`](#cua-sandbox-screenshot) | Save a screenshot (PNG). |
+| [`cua sandbox mcp`](#cua-sandbox-mcp) | Talk to an MCP server a sandbox serves: `mcp NAME SERVICE tools`, `mcp NAME SERVICE call TOOL '{"a":1}'`. |
+| [`cua sandbox mcp config`](#cua-sandbox-mcp-config) | The endpoint URL and headers, for any MCP client. |
+| [`cua sandbox mcp info`](#cua-sandbox-mcp-info) | Server name, version and negotiated protocol revision. |
+| [`cua sandbox mcp tools`](#cua-sandbox-mcp-tools) | List tools. |
+| [`cua sandbox mcp call`](#cua-sandbox-mcp-call) | Call a tool with a JSON object of arguments. |
+| [`cua sandbox mcp resources`](#cua-sandbox-mcp-resources) | List resources. |
+| [`cua sandbox mcp templates`](#cua-sandbox-mcp-templates) | List resource templates. |
+| [`cua sandbox mcp read`](#cua-sandbox-mcp-read) | Read a resource. |
+| [`cua sandbox mcp prompts`](#cua-sandbox-mcp-prompts) | List prompts. |
+| [`cua sandbox mcp prompt`](#cua-sandbox-mcp-prompt) | Render a prompt with a JSON object of string arguments. |
+| [`cua sandbox mcp request`](#cua-sandbox-mcp-request) | Any other method (for example `skills/list`), printing the result. |
+| [`cua sandbox view`](#cua-sandbox-view) | Open the sandbox desktop in the browser (the cua-spacesd HTML5 viewer). |
+| [`cua image`](#cua-image) | Images: local OCI pull/build/push. |
+| [`cua image pull`](#cua-image-pull) | Pull an image into the local cache. |
+| [`cua image build`](#cua-image-build) | Build an image from an images.cua.ai/v1alpha1 Image resource (JSON). |
+| [`cua image push`](#cua-image-push) | Copy an image (host architecture) to another registry reference. |
+| [`cua images`](#cua-images) | The sandbox image catalog (the images the docs list): which exist, their variants, and which ship cua-spacesd and a browser. |
+| [`cua images ls`](#cua-images-ls) | List the catalog: ref, OS, container or VM, local runtime, cua-spacesd, browsers, summary. |
+| [`cua images info`](#cua-images-info) | Show one catalog entry (a ref or an alias such as `linux`). |
+| [`cua images build`](#cua-images-build) | Build a sandbox image definition (a libs/images directory): the rootfs, the bootable VM disk and the KubeVirt containerDisk. |
+| [`cua images pack`](#cua-images-pack) | Pack the disks `cua images build --outputs disk` wrote as KubeVirt containerDisks `<repo>:<tag>-<arch>` (push, or load into docker). |
+| [`cua images publish`](#cua-images-publish) | Publish a built image as immutable pins `<series>-<stamp>` and `<series>-disk-<stamp>`, refusing any that exist. |
+| [`cua images release`](#cua-images-release) | Run an image's release pipeline (its release.json): build, doctor lanes, content digest, save; with --publish push, publish pins and verify; with --promote move the floating tags. |
+| [`cua images promote`](#cua-images-promote) | Move a series' moving tags (`edge`, `edge-disk`) to the pins a `cua images publish` record names, after the gates passed. |
+| [`cua runtime`](#cua-runtime) | Local runtimes (cua-vmm). |
+| [`cua runtime doctor`](#cua-runtime-doctor) | Inspect local runtimes (read-only). |
+| [`cua runtime setup`](#cua-runtime-setup) | Provision local runtimes. |
+| [`cua cache`](#cua-cache) | Disk used by images, sandboxes, builds and logs, and its cleanup. |
+| [`cua cache ls`](#cua-cache-ls) | List what the SDK keeps on disk, one row per image, sandbox, build output, install archive or log. |
+| [`cua cache du`](#cua-cache-du) | Disk usage per category, the cache budget and free space. |
+| [`cua cache prune`](#cua-cache-prune) | Reap orphaned ephemeral sandboxes, remove orphans (abandoned downloads, unused layers) and evict least-recently-used cache down to the budget. |
+| [`cua cache config`](#cua-cache-config) | Show or set the cache settings (`$CUA_HOME/cache.json`; the CUA_CACHE_BUDGET, CUA_DISK_MIN_FREE, CUA_DISK_WARN_FREE and CUA_ORPHAN_REAP_MINUTES environment variables win). |
+| [`cua cloud`](#cua-cloud) | Spaces in your own cloud account (AWS, Google Cloud, Modal): connect, status, test, disconnect, sweep. |
+| [`cua cloud status`](#cua-cloud-status) | Your clouds: found credentials, the connected account and region, what each runs at what hourly cost, and what Cua created there. |
+| [`cua cloud connect`](#cua-cloud-connect) | Connect a cloud account Spaces can be created in (after the checks `cua cloud test` runs). |
+| [`cua cloud test`](#cua-cloud-test) | Check a cloud account without creating anything: credentials, permissions (by dry run), quota, the region and machine types. |
+| [`cua cloud disconnect`](#cua-cloud-disconnect) | Forget a connected cloud (nothing in it is deleted). |
+| [`cua cloud sweep`](#cua-cloud-sweep) | Find what Cua left in your clouds: expired Spaces and resources whose Space is gone (with --all, every Cua resource). |
+| [`cua viewer`](#cua-viewer) | Serve the HTML5 viewer for every sandbox on one loopback port. |
+
+Every command also accepts the [global options](/cua-cli/reference/cli#global-options).
+
+## `cua sandbox`
+
+Sandboxes: local or an existing machine (direct).
+
+```text output
+cua sandbox [OPTIONS] <COMMAND>
+```
+
+Alias: `cua sb`.
+
+### `cua sandbox create`
+
+Create a sandbox: `cua sb create IMAGE [--on local|direct:<addr>] [--kind auto|container|vm] [--runtime auto|gvisor|runc|qemu|lume]`.
+
+```text output
+cua sandbox create [OPTIONS] [IMAGE] [-- <COMMAND>...]
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<IMAGE>` | string | optional | Image: a registry reference (`ghcr.io/org/image:tag`), an alias (`linux`, `ubuntu`, `windows`, `macos[:tahoe\|sequoia]`, `omarchy`). |
+| `<COMMAND>...` | string | optional | The sandbox's command, after `--` (replaces the image's entrypoint): `cua sb create python:3.12-slim --service mcp=8765 -- python -m srv`. Repeatable. |
+
+| Flag | Type | Default | Env var | Description |
+| --- | --- | --- | --- | --- |
+| <span id="cua-sandbox-create--on"></span>`--on` | string | | | Where it runs: local, direct:&lt;addr&gt; (an existing machine running cua-spacesd), or a registered provider. Default: `cua config get default.on` (`CUA_DEFAULT_ON`), else local. |
+| <span id="cua-sandbox-create--kind"></span>`--kind` | string | | | What kind of machine: auto (from the image: a container when it has a container rootfs; macOS, Windows and disk-only images are VMs), container or vm. |
+| <span id="cua-sandbox-create--runtime"></span>`--runtime` | string | | | Which engine: auto (the safest available) or one the location offers for the kind. Local: gvisor or runc (containers), qemu or lume (VMs). A local sandbox with --sidecar needs `--runtime runc` where gVisor would run (separate gVisor containers cannot share a network namespace). |
+| <span id="cua-sandbox-create--tier"></span>`--tier` | string | | | Image tier for an alias: `slim`, `full` (default) or macOS `xcode`. |
+| <span id="cua-sandbox-create--name"></span>`--name` | string | | | Sandbox name (generated when omitted). |
+| <span id="cua-sandbox-create--open"></span>`--open` | string | | | With --browser: open this URL. |
+| <span id="cua-sandbox-create--install"></span>`--install` | string | | | Install these into the sandbox once it is up: harness ids (`claude-code`) or installables (`blender`, `vscode`, `node`), pinned and checksum-verified (`cua agent ensure` later does the same). Repeatable. |
+| <span id="cua-sandbox-create--cpu"></span>`--cpu` | integer | | | vCPUs. Alias: `--cpus`. |
+| <span id="cua-sandbox-create--memory"></span>`--memory` | string | | | Memory, e.g. 8GB or 4096MB (a bare number is GB). |
+| <span id="cua-sandbox-create--network"></span>`--network` | `default` \| `none` | | | Guest network: `default` (outbound network, like a Docker container) or `none` (no egress; published ports still work). `none` needs a local QEMU VM; containers and Lume reject it. |
+| <span id="cua-sandbox-create--disk"></span>`--disk` | string | | | Disk size (accepted; the image decides today). |
+| <span id="cua-sandbox-create--port"></span>`--port` | string | | | Expose a guest port: NAME=PORT (a named service) or PORT (repeatable). Alias: `--service`. |
+| <span id="cua-sandbox-create--wait"></span>`--wait` | string | | | Wait until ready: tcp:SERVICE, http:SERVICE/path, a guest port (tcp:PORT, http:PORT/path), or `desktop` (the desktop session takes input: display, window manager and cua-driver) (repeatable). Alias: `--wait-for`. |
+| <span id="cua-sandbox-create--ready-timeout"></span>`--ready-timeout` | integer | | | Readiness budget in seconds, counted once the image is downloaded, the wait for the image's cua-spacesd included (default 600, plus up to 120 for cua-spacesd). |
+| <span id="cua-sandbox-create--overlay"></span>`--overlay` | string | | | Inject a freshly built binary once the sandbox is up: NAME=PATH (`cua-driver`, `cua-spacesd`) or NAME=PATH:GUEST_PATH (repeatable). It replaces the guest file atomically, is recorded with its sha256 (checked by `cua doctor`) and what runs it is restarted. Needs cua-spacesd in the image. |
+| <span id="cua-sandbox-create--env"></span>`--env` | string | | | Environment KEY=VALUE for the sandbox (repeatable). |
+| <span id="cua-sandbox-create--sidecar"></span>`--sidecar` | string | | | A sidecar container, reachable from the sandbox at its name (it reaches the sandbox at `main`): IMAGE[,port=PORT][,env=K=V][,name=NAME] (repeatable; `port=` and `env=` repeat too). Local containers; it needs `--runtime runc` where gVisor would run. With sidecars the service names main, sidecars and sc are reserved. |
+| <span id="cua-sandbox-create--registry-secret"></span>`--registry-secret` | string | | | Credentials for a private image: env:USER_VAR:PASSWORD_VAR (read from this environment) or aws-ecr[:REGION] (the AWS CLI's login token). |
+| <span id="cua-sandbox-create--token"></span>`--token` | string | | `CUA_ENV_TOKEN` | spacesd token (direct: sandboxes). |
+| <span id="cua-sandbox-create--gpu"></span>`--gpu` | string | | | A GPU: the runtime's own (`--gpu`), or an option `cua spaces gpus` lists (`paravirtual`: GPU acceleration for a macOS VM on Lume, experimental; `virgl`: QEMU on Linux; `nvidia`: a runc container on Linux; a provider's GPU type). |
+| <span id="cua-sandbox-create--browser"></span>`--browser` | boolean | `false` | | Start Chromium in it for the cua-driver browser tools (IMAGE defaults to `linux`). |
+| <span id="cua-sandbox-create--view"></span>`--view` | boolean | `false` | | Open the desktop in the HTML5 viewer once the sandbox is ready (`cua sb view`). |
+| <span id="cua-sandbox-create--keep-on-failure"></span>`--keep-on-failure` | boolean | `false` | | Keep the sandbox (VM or container) when it fails to become ready, to debug it; the ref and how to delete it are printed. Default: a failed create deletes it. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-sandbox-create"
+# A Linux desktop on this machine (a gVisor container)
+cua sb create linux --name dev
+
+# A web server container, ready when its HTTP service answers
+cua sb create python:3.12-slim --service web=8000 --wait http:web/ -- python -m http.server 8000
+
+# The same Linux image as a VM
+cua sb create linux --kind vm --name dev
+```
+
+### `cua sandbox launch`
+
+Deprecated alias of `create`.
+
+```text output
+cua sandbox launch [OPTIONS] [IMAGE]
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-sandbox-launch"
+cua sb launch linux --name dev
+```
+
+### `cua sandbox connect`
+
+Reattach to a sandbox (NAME or a ref such as `local:NAME`) and print it.
+
+```text output
+cua sandbox connect [OPTIONS] <NAME>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<NAME>` | string | required | Sandbox name or ref (`local:NAME`). |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-sandbox-connect--local"></span>`--local` | boolean | `false` | Look NAME up among local sandboxes only (same as `local:NAME`). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-sandbox-connect"
+cua sb connect dev
+cua sb connect local:dev
+```
+
+### `cua sandbox ls`
+
+List sandboxes: local and direct, each with its `location`; `--local` filters.
+
+```text output
+cua sandbox ls [OPTIONS]
+```
+
+Alias: `cua sandbox list`.
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-sandbox-ls--local"></span>`--local` | boolean | `false` | Only local sandboxes. |
+| <span id="cua-sandbox-ls--no-size"></span>`--no-size` | boolean | `false` | Skip the SIZE column (disk used by each local sandbox), which reads the VM, container and Lume stores. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-sandbox-ls"
+cua sb ls
+cua sb ls --local --json
+```
+
+### `cua sandbox info`
+
+Show one sandbox.
+
+```text output
+cua sandbox info [OPTIONS] <NAME>
+```
+
+Alias: `cua sandbox get`.
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<NAME>` | string | required | Sandbox name or ref (`local:NAME`). |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-sandbox-info--local"></span>`--local` | boolean | `false` | Look NAME up among local sandboxes only (same as `local:NAME`). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-sandbox-info"
+cua sb info dev
+cua sb info local:dev --json
+```
+
+### `cua sandbox suspend`
+
+Suspend (pause/snapshot).
+
+```text output
+cua sandbox suspend [OPTIONS] <NAME>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<NAME>` | string | required | Sandbox name or ref (`local:NAME`). |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-sandbox-suspend--local"></span>`--local` | boolean | `false` | Look NAME up among local sandboxes only (same as `local:NAME`). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-sandbox-suspend"
+cua sb suspend dev
+```
+
+### `cua sandbox resume`
+
+Resume.
+
+```text output
+cua sandbox resume [OPTIONS] <NAME>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<NAME>` | string | required | Sandbox name or ref (`local:NAME`). |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-sandbox-resume--local"></span>`--local` | boolean | `false` | Look NAME up among local sandboxes only (same as `local:NAME`). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-sandbox-resume"
+cua sb resume dev
+```
+
+### `cua sandbox restart`
+
+Restart.
+
+```text output
+cua sandbox restart [OPTIONS] <NAME>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<NAME>` | string | required | Sandbox name or ref (`local:NAME`). |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-sandbox-restart--local"></span>`--local` | boolean | `false` | Look NAME up among local sandboxes only (same as `local:NAME`). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-sandbox-restart"
+cua sb restart dev
+```
+
+### `cua sandbox rm`
+
+Delete a sandbox.
+
+```text output
+cua sandbox rm [OPTIONS] <NAME>
+```
+
+Alias: `cua sandbox delete`.
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<NAME>` | string | required | Sandbox name or ref (`local:NAME`). |
+
+| Flag | Short | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| <span id="cua-sandbox-rm--force"></span>`--force` | `-f` | boolean | `false` | Skip the confirmation prompt. Required when there is no terminal to ask on (scripts, agents): without it nothing is deleted. |
+| <span id="cua-sandbox-rm--local"></span>`--local` | | boolean | `false` | Look NAME up among local sandboxes only (same as `local:NAME`). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-sandbox-rm"
+cua sb rm dev
+
+# Without the prompt (required in scripts and agents)
+cua sb rm local:dev --force
+```
+
+### `cua sandbox exec`
+
+Run a command (joined into one shell line, as `sh -c`). Exits with the command's own status. A local Lume sandbox without cua-spacesd runs it via SSH (`lume ssh`).
+
+```text output
+cua sandbox exec [OPTIONS] <NAME> <COMMAND>...
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<NAME>` | string | required | Sandbox name or ref (`local:NAME`). |
+| `<COMMAND>...` | string | required | Command and arguments. Repeatable. |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-sandbox-exec--local"></span>`--local` | boolean | `false` | Look NAME up among local sandboxes only (same as `local:NAME`). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-sandbox-exec"
+cua sb exec dev uname -a
+cua sb exec dev 'ls /tmp | wc -l'
+```
+
+### `cua sandbox shell`
+
+Interactive shell (PTY), or run a command in a PTY.
+
+```text output
+cua sandbox shell [OPTIONS] <NAME> [COMMAND]...
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<NAME>` | string | required | Sandbox name or ref (`local:NAME`). |
+| `<COMMAND>...` | string | optional | Command to run instead of the login shell. Repeatable. |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-sandbox-shell--cols"></span>`--cols` | integer | | Terminal width (default: this terminal's). |
+| <span id="cua-sandbox-shell--rows"></span>`--rows` | integer | | Terminal height (default: this terminal's). |
+| <span id="cua-sandbox-shell--local"></span>`--local` | boolean | `false` | Look NAME up among local sandboxes only (same as `local:NAME`). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-sandbox-shell"
+cua sb shell dev
+cua sb shell dev top
+```
+
+### `cua sandbox cp`
+
+Copy files: `cp NAME:/guest/path LOCAL` or `cp LOCAL NAME:/guest/path` (NAME may be a ref: `cp local:box:/tmp/x .`).
+
+```text output
+cua sandbox cp [OPTIONS] <SRC> <DST>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<SRC>` | string | required | Source: a local path or `NAME:/guest/path`. |
+| `<DST>` | string | required | Destination: a local path or `NAME:/guest/path`. |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-sandbox-cp--local"></span>`--local` | boolean | `false` | Look NAME up among local sandboxes only (same as `local:NAME`). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-sandbox-cp"
+# Upload
+cua sb cp ./notes.txt dev:/tmp/notes.txt
+
+# Download
+cua sb cp dev:/tmp/notes.txt .
+```
+
+### `cua sandbox overlay`
+
+Inject freshly built binaries into a running sandbox (see `create --overlay`): NAME=PATH or NAME=PATH:GUEST_PATH.
+
+```text output
+cua sandbox overlay [OPTIONS] <NAME> <OVERLAYS>...
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<NAME>` | string | required | Sandbox name or ref (`local:NAME`). |
+| `<OVERLAYS>...` | string | required | NAME=PATH[:GUEST_PATH] (repeatable). Repeatable. |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-sandbox-overlay--timeout"></span>`--timeout` | integer | `180` | Budget for a cua-spacesd restart, in seconds. |
+| <span id="cua-sandbox-overlay--local"></span>`--local` | boolean | `false` | Look NAME up among local sandboxes only (same as `local:NAME`). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-sandbox-overlay"
+# The cua-driver under test, then check that it is what runs
+cua sb overlay dev cua-driver=./target/release/cua-driver
+cua doctor dev --expect cua-driver=sha256:<sha256>
+
+# The daemon too (restarts it and waits for the new build)
+cua sb overlay dev cua-spacesd=./target/release/cua-spacesd
+```
+
+### `cua sandbox logs`
+
+Show logs: the backend console (QEMU serial, container) when there is one, else the guest system log through the spacesd.
+
+```text output
+cua sandbox logs [OPTIONS] <NAME>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<NAME>` | string | required | Sandbox name or ref (`local:NAME`). |
+
+| Flag | Short | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| <span id="cua-sandbox-logs--tail"></span>`--tail` | `-n` | integer | `200` | Lines from the end. |
+| <span id="cua-sandbox-logs--source"></span>`--source` | | string | `auto` | auto, console or guest. |
+| <span id="cua-sandbox-logs--local"></span>`--local` | | boolean | `false` | Look NAME up among local sandboxes only (same as `local:NAME`). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-sandbox-logs"
+cua sb logs dev
+cua sb logs dev -n 50 --source guest
+```
+
+### `cua sandbox port-forward`
+
+Forward a guest port: `port-forward NAME PORT[:LOCAL]` (a local sandbox's port not published at create tunnels through cua-spacesd when the image has it).
+
+```text output
+cua sandbox port-forward [OPTIONS] <NAME> <SPEC>
+```
+
+Alias: `cua sandbox forward`.
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<NAME>` | string | required | Sandbox name or ref (`local:NAME`). |
+| `<SPEC>` | string | required | PORT or PORT:LOCAL_PORT. |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-sandbox-port-forward--local"></span>`--local` | boolean | `false` | Look NAME up among local sandboxes only (same as `local:NAME`). |
+| <span id="cua-sandbox-port-forward--no-wait"></span>`--no-wait` | boolean | `false` | Print the target and exit instead of forwarding until Ctrl-C. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-sandbox-port-forward"
+# Guest port 8080 on localhost:8080 until Ctrl-C
+cua sb port-forward dev 8080
+
+# Guest port 5432 on localhost:15432
+cua sb port-forward local:dev 5432:15432
+```
+
+### `cua sandbox url`
+
+Print a URL for a named service: usable from this machine (default), or `--public` for a shareable URL that expires (`--ttl`, default 1h; a token URL served by the cua daemon).
+
+```text output
+cua sandbox url [OPTIONS] <NAME> <SERVICE>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<NAME>` | string | required | Sandbox name or ref (`local:NAME`). |
+| `<SERVICE>` | string | required | Service name (from `--service` at create time). |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-sandbox-url--ttl"></span>`--ttl` | integer | | Lifetime of a --public URL (`10m`, `1h`, `3600`; 60 s to 24 h). |
+| <span id="cua-sandbox-url--local"></span>`--local` | boolean | `false` | Look NAME up among local sandboxes only (same as `local:NAME`). |
+| <span id="cua-sandbox-url--public"></span>`--public` | boolean | `false` | A shareable URL that expires. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-sandbox-url"
+cua sb url dev web
+
+# A shareable URL for 10 minutes
+cua sb url local:dev web --public --ttl 10m
+```
+
+### `cua sandbox screenshot`
+
+Save a screenshot (PNG). A local Lume sandbox without cua-spacesd is captured via VNC.
+
+```text output
+cua sandbox screenshot [OPTIONS] <NAME>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<NAME>` | string | required | Sandbox name or ref (`local:NAME`). |
+
+| Flag | Short | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| <span id="cua-sandbox-screenshot--output"></span>`--output` | `-o` | path | `screenshot.png` | Output file (PNG). |
+| <span id="cua-sandbox-screenshot--local"></span>`--local` | | boolean | `false` | Look NAME up among local sandboxes only (same as `local:NAME`). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-sandbox-screenshot"
+cua sb screenshot dev -o desktop.png
+```
+
+### `cua sandbox mcp`
+
+Talk to an MCP server a sandbox serves: `mcp NAME SERVICE tools`, `mcp NAME SERVICE call TOOL '{"a":1}'`. Generic streamable HTTP over the service; no cua-spacesd needed.
+
+```text output
+cua sandbox mcp [OPTIONS] <NAME> <SERVICE> <COMMAND>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<NAME>` | string | required | Sandbox name or ref (`local:NAME`). |
+| `<SERVICE>` | string | required | Service name (for example `mcp`, or `port-8765`). |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-sandbox-mcp--path"></span>`--path` | string | `/mcp` | Endpoint path on the service. |
+| <span id="cua-sandbox-mcp--local"></span>`--local` | boolean | `false` | Look NAME up among local sandboxes only (same as `local:NAME`). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-sandbox-mcp"
+cua sb mcp dev mcp tools
+cua sb mcp dev mcp call echo '{"text":"hi"}'
+```
+
+#### `cua sandbox mcp config`
+
+The endpoint URL and headers, for any MCP client. Credential headers print masked (`Bearer ****`) unless `--show-secrets`.
+
+```text output
+cua sandbox mcp <NAME> <SERVICE> config [OPTIONS]
+```
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-sandbox-mcp-config--show-secrets"></span>`--show-secrets` | boolean | `false` | Print credential header values in full. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-sandbox-mcp-config"
+cua sb mcp dev mcp config
+```
+
+#### `cua sandbox mcp info`
+
+Server name, version and negotiated protocol revision.
+
+```text output
+cua sandbox mcp <NAME> <SERVICE> info [OPTIONS]
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-sandbox-mcp-info"
+cua sb mcp dev mcp info
+```
+
+#### `cua sandbox mcp tools`
+
+List tools.
+
+```text output
+cua sandbox mcp <NAME> <SERVICE> tools [OPTIONS]
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-sandbox-mcp-tools"
+cua sb mcp dev mcp tools
+```
+
+#### `cua sandbox mcp call`
+
+Call a tool with a JSON object of arguments.
+
+```text output
+cua sandbox mcp <NAME> <SERVICE> call [OPTIONS] <TOOL> [ARGUMENTS]
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<TOOL>` | string | required | Tool name. |
+| `<ARGUMENTS>` | string | optional | Arguments (JSON object). Default `{}`. |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-sandbox-mcp-call--out"></span>`--out` | path | | Save image, audio and blob content here instead of summarizing. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-sandbox-mcp-call"
+cua sb mcp dev mcp call echo '{"text":"hi"}'
+cua sb mcp dev mcp call screenshot --out ./shots
+```
+
+#### `cua sandbox mcp resources`
+
+List resources.
+
+```text output
+cua sandbox mcp <NAME> <SERVICE> resources [OPTIONS]
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-sandbox-mcp-resources"
+cua sb mcp dev mcp resources
+```
+
+#### `cua sandbox mcp templates`
+
+List resource templates.
+
+```text output
+cua sandbox mcp <NAME> <SERVICE> templates [OPTIONS]
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-sandbox-mcp-templates"
+cua sb mcp dev mcp templates
+```
+
+#### `cua sandbox mcp read`
+
+Read a resource.
+
+```text output
+cua sandbox mcp <NAME> <SERVICE> read [OPTIONS] <URI>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<URI>` | string | required | Resource URI. |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-sandbox-mcp-read--out"></span>`--out` | path | | Save blob contents here instead of summarizing. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-sandbox-mcp-read"
+cua sb mcp dev mcp read file:///tmp/report.txt
+```
+
+#### `cua sandbox mcp prompts`
+
+List prompts.
+
+```text output
+cua sandbox mcp <NAME> <SERVICE> prompts [OPTIONS]
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-sandbox-mcp-prompts"
+cua sb mcp dev mcp prompts
+```
+
+#### `cua sandbox mcp prompt`
+
+Render a prompt with a JSON object of string arguments.
+
+```text output
+cua sandbox mcp <NAME> <SERVICE> prompt [OPTIONS] <NAME> [ARGUMENTS]
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<NAME>` | string | required | Prompt name. |
+| `<ARGUMENTS>` | string | optional | Arguments (JSON object of strings). Default `{}`. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-sandbox-mcp-prompt"
+cua sb mcp dev mcp prompt summarize '{"topic":"logs"}'
+```
+
+#### `cua sandbox mcp request`
+
+Any other method (for example `skills/list`), printing the result.
+
+```text output
+cua sandbox mcp <NAME> <SERVICE> request [OPTIONS] <METHOD> [PARAMS]
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<METHOD>` | string | required | JSON-RPC method. |
+| `<PARAMS>` | string | optional | Params (JSON object). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-sandbox-mcp-request"
+cua sb mcp dev mcp request skills/list
+```
+
+### `cua sandbox view`
+
+Open the sandbox desktop in the browser (the cua-spacesd HTML5 viewer). A local Lume sandbox without cua-spacesd opens its VNC display with `lume attach`.
+
+```text output
+cua sandbox view [OPTIONS] <NAME>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<NAME>` | string | required | Sandbox name or ref (`local:NAME`). |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-sandbox-view--service"></span>`--service` | string | | Open this web service of the sandbox instead of the viewer (for images without cua-spacesd that serve their own display page). |
+| <span id="cua-sandbox-view--files"></span>`--files` | string | | Guest folder for uploads and folder sharing (default `~`; `none` turns files off). |
+| <span id="cua-sandbox-view--ttl"></span>`--ttl` | string | | Link lifetime (for example `1h`, `30m`). Default 1h. |
+| <span id="cua-sandbox-view--view-only"></span>`--view-only` | boolean | `false` | Watch only: no input, clipboard, files or microphone. |
+| <span id="cua-sandbox-view--no-open"></span>`--no-open` | boolean | `false` | Print the link without opening a browser. |
+| <span id="cua-sandbox-view--local"></span>`--local` | boolean | `false` | Look NAME up among local sandboxes only (same as `local:NAME`). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-sandbox-view"
+cua sb view dev
+
+# Watch only, print the link instead of opening it
+cua sb view dev --view-only --no-open
+
+# An image that ships its own web display instead of cua-spacesd
+cua sb view old-box --service web
+```
+
+## `cua image`
+
+Images: local OCI pull/build/push.
+
+```text output
+cua image [OPTIONS] <COMMAND>
+```
+
+Alias: `cua img`.
+
+### `cua image pull`
+
+Pull an image into the local cache.
+
+```text output
+cua image pull [OPTIONS] <REFERENCE>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<REFERENCE>` | string | required | Image reference or alias. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-image-pull"
+cua image pull linux
+cua image pull ghcr.io/trycua/linux:24.04
+```
+
+### `cua image build`
+
+Build an image from an images.cua.ai/v1alpha1 Image resource (JSON).
+
+```text output
+cua image build [OPTIONS] --base <BASE> <SPEC>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<SPEC>` | path | required | Image resource file (JSON). |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-image-build--base"></span>`--base` | string | required | Base image (`container:<ref>`, `vm:<ref>`, `disk:<path>`). |
+| <span id="cua-image-build--push"></span>`--push` | string | | Push the result to this reference. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-image-build"
+cua image build image.json --base container:ubuntu:24.04
+cua image build image.json --base container:ubuntu:24.04 --push ghcr.io/acme/desktop:1
+```
+
+### `cua image push`
+
+Copy an image (host architecture) to another registry reference.
+
+```text output
+cua image push [OPTIONS] <REFERENCE> <DESTINATION>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<REFERENCE>` | string | required | Source image reference or alias. |
+| `<DESTINATION>` | string | required | Destination registry reference. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-image-push"
+cua image push linux ghcr.io/acme/desktop:1
+```
+
+## `cua images`
+
+The sandbox image catalog (the images the docs list): which exist, their variants, and which ship cua-spacesd and a browser.
+
+```text output
+cua images [OPTIONS] <COMMAND>
+```
+
+### `cua images ls`
+
+List the catalog: ref, OS, container or VM, local runtime, cua-spacesd, browsers, summary.
+
+```text output
+cua images ls [OPTIONS]
+```
+
+Alias: `cua images list`.
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-images-ls--os"></span>`--os` | string | | Only this OS: linux, windows or macos. |
+| <span id="cua-images-ls--all"></span>`--all` | boolean | `false` | Include unpublished entries (benchmark images). |
+| <span id="cua-images-ls--browser"></span>`--browser` | boolean | `false` | Only images with a browser the cua-driver browser tools drive. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-images-ls"
+cua images ls
+
+# Images whose browser the cua-driver browser tools drive
+cua images ls --browser
+cua images ls --all --json
+```
+
+### `cua images info`
+
+Show one catalog entry (a ref or an alias such as `linux`).
+
+```text output
+cua images info [OPTIONS] <REFERENCE>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<REFERENCE>` | string | required | Image ref or alias. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-images-info"
+cua images info linux
+```
+
+### `cua images build`
+
+Build a sandbox image definition (a libs/images directory): the rootfs, the bootable VM disk and the KubeVirt containerDisk.
+
+Outputs: rootfs &lt;repo&gt;:docker-&lt;tag&gt;-&lt;arch&gt;; disk &lt;out&gt;/&lt;name&gt;/&lt;arch&gt;/disk.img;
+containerdisk &lt;repo&gt;:&lt;tag&gt;-&lt;arch&gt;. --push pushes the outputs the image.json
+lists (a VM-only image never pushes its rootfs).
+
+```text output
+cua images build [OPTIONS] <DIR>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<DIR>` | path | required | Image definition directory (Dockerfile, image.json). |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-images-build--platform"></span>`--platform` | string | | Platforms, comma separated (default: the host's, or the image's only one). |
+| <span id="cua-images-build--tag"></span>`--tag` | string | `local` | Tag for the per-arch outputs. |
+| <span id="cua-images-build--repo"></span>`--repo` | string | | Repository (default: image.json `repository`, else cua-e2e-local/&lt;name&gt;). |
+| <span id="cua-images-build--outputs"></span>`--outputs` | string | `rootfs` | Outputs: rootfs, disk, containerdisk (comma separated). |
+| <span id="cua-images-build--build-arg"></span>`--build-arg` | string | | Docker build argument KEY=VALUE (repeatable). |
+| <span id="cua-images-build--build-context"></span>`--build-context` | string | | Named build context NAME=PATH (repeatable). |
+| <span id="cua-images-build--label"></span>`--label` | string | | Extra rootfs label KEY=VALUE (repeatable). |
+| <span id="cua-images-build--out"></span>`--out` | path | | Where disks go (default: $CUA_IMAGES_OUT or ~/.cache/cua-images). |
+| <span id="cua-images-build--disk-size"></span>`--disk-size` | string | `20G` | Virtual size of the disk. |
+| <span id="cua-images-build--target"></span>`--target` | string | | Dockerfile stage to build (a tier: `slim`, `full`); disks go to &lt;out&gt;/&lt;name&gt;-&lt;target&gt;/&lt;arch&gt;. Default: the Dockerfile's last stage. |
+| <span id="cua-images-build--push"></span>`--push` | boolean | `false` | Push the published outputs. |
+| <span id="cua-images-build--dry-run"></span>`--dry-run` | boolean | `false` | Print the steps without running them. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-images-build"
+cua images build libs/images/omarchy --outputs rootfs,disk
+cua images build libs/images/omarchy --tag build-1a2b3c4d --outputs containerdisk --push
+cua images build libs/images/linux --target slim --tag 24.04-slim-local --outputs rootfs,disk
+cua images build libs/images/linux --platform linux/amd64,linux/arm64 --dry-run
+```
+
+### `cua images pack`
+
+Pack the disks `cua images build --outputs disk` wrote as KubeVirt containerDisks `<repo>:<tag>-<arch>` (push, or load into docker).
+
+Packs exactly the disk the doctor checked, so the pushed bytes are the
+tested ones.
+
+```text output
+cua images pack [OPTIONS] <DIR>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<DIR>` | path | required | Image definition directory. |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-images-pack--platform"></span>`--platform` | string | | Platforms, comma separated (default: the host's, or the image's only one). |
+| <span id="cua-images-pack--tag"></span>`--tag` | string | `local` | Tag for the per-arch containerDisks. |
+| <span id="cua-images-pack--repo"></span>`--repo` | string | | Repository (default: image.json `repository`, else cua-e2e-local/&lt;name&gt;). |
+| <span id="cua-images-pack--out"></span>`--out` | path | | Where the disks are (default: $CUA_IMAGES_OUT or ~/.cache/cua-images). |
+| <span id="cua-images-pack--target"></span>`--target` | string | | The `--target` the disks were built with (their &lt;name&gt;-&lt;target&gt; dir). |
+| <span id="cua-images-pack--push"></span>`--push` | boolean | `false` | Push instead of loading into docker. |
+| <span id="cua-images-pack--dry-run"></span>`--dry-run` | boolean | `false` | Print what would be packed. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-images-pack"
+cua images pack libs/images/omarchy --tag ci-1a2b3c4d --push --json
+```
+
+### `cua images publish`
+
+Publish a built image as immutable pins `<series>-<stamp>` and `<series>-disk-<stamp>`, refusing any that exist. Moves nothing.
+
+Reads the per-arch images `cua images build --tag TAG --push` wrote
+(&lt;repo&gt;:&lt;tag&gt;-&lt;arch&gt;, and &lt;repo&gt;:docker-&lt;tag&gt;-&lt;arch&gt; when the image has a rootfs
+output). Writes the record `cua images promote` takes.
+
+```text output
+cua images publish [OPTIONS] --tag <TAG> --series <SERIES> <DIR>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<DIR>` | path | required | Image definition directory. |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-images-publish--tag"></span>`--tag` | string | required | The build tag the per-arch images were pushed under. |
+| <span id="cua-images-publish--series"></span>`--series` | string | required | Series / channel (`edge`, `24.04`). |
+| <span id="cua-images-publish--stamp"></span>`--stamp` | string | | Pin stamp `<yyyymmdd>-<sha7>` (default: today and git HEAD). |
+| <span id="cua-images-publish--repo"></span>`--repo` | string | | Repository (default: image.json `repository`). |
+| <span id="cua-images-publish--platform"></span>`--platform` | string | | Platforms (default: image.json `platforms`). |
+| <span id="cua-images-publish--annotation"></span>`--annotation` | string | | Extra index annotation KEY=VALUE (repeatable). |
+| <span id="cua-images-publish--descriptor-annotation"></span>`--descriptor-annotation` | string | | Annotation on one child's descriptor, VARIANT/ARCH:KEY=VALUE (`rootfs/amd64:ai.cua.doctor.status=pass`; repeatable). |
+| <span id="cua-images-publish--record"></span>`--record` | path | | Write the publish record (JSON) here. |
+| <span id="cua-images-publish--dry-run"></span>`--dry-run` | boolean | `false` | Resolve and print, push nothing. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-images-publish"
+cua images publish libs/images/omarchy --tag build-1a2b3c4d --series edge --record pins.json
+cua images publish libs/images/linux --tag build-20260925-1a2b3c4 --series 24.04 --descriptor-annotation rootfs/amd64:ai.cua.doctor.status=pass
+cua images publish libs/images/omarchy --tag build-1a2b3c4d --series edge --dry-run
+```
+
+### `cua images release`
+
+Run an image's release pipeline (its release.json): build, doctor lanes, content digest, save; with --publish push, publish pins and verify; with --promote move the floating tags. The same command runs locally and in CI.
+
+Phases: prepare, build, gate (doctor lanes), stage, push, publish, verify,
+promote. Push refuses unless every required gate passed (this run, or a
+state-*.json merged from other jobs in &lt;work&gt;/evidence). Evidence, logs and
+the summary go to &lt;work&gt;/evidence (a plain directory CI uploads as-is).
+
+```text output
+cua images release [OPTIONS] <DIR>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<DIR>` | path | required | Image directory with a release.json. |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-images-release--tier"></span>`--tier` | string | | Tier (`slim`, `full`) for images that have tiers. |
+| <span id="cua-images-release--arch"></span>`--arch` | string | | Arches, comma separated (default: release.json `arches`). Repeatable. |
+| <span id="cua-images-release--stamp"></span>`--stamp` | string | | Pin stamp `<yyyymmdd>-<sha7>` (default: today and git HEAD). |
+| <span id="cua-images-release--work"></span>`--work` | path | | Work directory (default: $CUA_RELEASE_WORK, else under the cua build cache, which `cua cache prune` manages). |
+| <span id="cua-images-release--steps"></span>`--steps` | string | | Only these steps: phase names or step-id prefixes (comma separated). Repeatable. |
+| <span id="cua-images-release--from"></span>`--from` | string | | Rerun from this phase or step; the steps before it must have passed. |
+| <span id="cua-images-release--var"></span>`--var` | string | | Variable KEY=VALUE for release.json templates (repeatable). |
+| <span id="cua-images-release--assume"></span>`--assume` | string | | Treat a host capability as present (`kvm`) or absent (`!runsc`). Repeatable. |
+| <span id="cua-images-release--scope"></span>`--scope` | string | | This run's state file name, state-&lt;scope&gt;.json (default: the arches); CI jobs sharing an evidence directory use distinct scopes. |
+| <span id="cua-images-release--resume"></span>`--resume` | boolean | `false` | Skip steps that passed with the same inputs and whose outputs exist. |
+| <span id="cua-images-release--dry-run"></span>`--dry-run` | boolean | `false` | Print the plan; run nothing. |
+| <span id="cua-images-release--publish"></span>`--publish` | boolean | `false` | Also push, publish immutable pins and verify them. |
+| <span id="cua-images-release--promote"></span>`--promote` | boolean | `false` | Also move the floating tags to the pins. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-images-release"
+# Plan only
+cua images release libs/images/linux --tier slim --dry-run
+
+# Build and doctor amd64 locally; resume after a failure
+cua images release libs/images/linux --tier slim --arch amd64 --resume
+
+# Rerun from the doctor lanes (the build must have passed)
+cua images release libs/images/linux --tier slim --from gate
+
+# One CI job's slice
+cua images release libs/images/linux --tier full --arch arm64 --steps build,gate,stage --work release
+
+# Publish and promote (the gates must have passed)
+cua images release libs/images/omarchy --publish --promote --resume
+```
+
+### `cua images promote`
+
+Move a series' moving tags (`edge`, `edge-disk`) to the pins a `cua images publish` record names, after the gates passed.
+
+```text output
+cua images promote [OPTIONS] <RECORD>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<RECORD>` | path | required | Record written by `cua images publish --record`. |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-images-promote--dry-run"></span>`--dry-run` | boolean | `false` | Check and print, move nothing. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-images-promote"
+cua images promote pins.json
+cua images promote pins.json --dry-run
+```
+
+## `cua runtime`
+
+Local runtimes (cua-vmm).
+
+```text output
+cua runtime [OPTIONS] <COMMAND>
+```
+
+### `cua runtime doctor`
+
+Inspect local runtimes (read-only).
+
+```text output
+cua runtime doctor [OPTIONS]
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-runtime-doctor"
+cua runtime doctor
+```
+
+### `cua runtime setup`
+
+Provision local runtimes.
+
+```text output
+cua runtime setup [OPTIONS] [COMPONENTS]...
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<COMPONENTS>...` | string | optional | Components: `qemu`, `lume`, `runsc` (default: everything provisionable). Repeatable. |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-runtime-setup--dry-run"></span>`--dry-run` | boolean | `false` | Only report what would be done. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-runtime-setup"
+# See what would be installed
+cua runtime setup --dry-run
+cua runtime setup qemu
+```
+
+## `cua cache`
+
+Disk used by images, sandboxes, builds and logs, and its cleanup.
+
+```text output
+cua cache [OPTIONS] <COMMAND>
+```
+
+### `cua cache ls`
+
+List what the SDK keeps on disk, one row per image, sandbox, build output, install archive or log.
+
+```text output
+cua cache ls [OPTIONS]
+```
+
+Alias: `cua cache list`.
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-cache-ls--category"></span>`--category` | string | | Only this category (images, docker-images, lume-bases, builds, installables, icons, sandboxes, checkpoints, logs, data, legacy). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-cache-ls"
+cua cache ls
+
+# Only cached images
+cua cache ls --category images
+```
+
+### `cua cache du`
+
+Disk usage per category, the cache budget and free space.
+
+```text output
+cua cache du [OPTIONS]
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-cache-du"
+cua cache du
+cua cache du --json
+```
+
+### `cua cache prune`
+
+Reap orphaned ephemeral sandboxes, remove orphans (abandoned downloads, unused layers) and evict least-recently-used cache down to the budget. Never removes a sandbox or anything one uses.
+
+```text output
+cua cache prune [OPTIONS]
+```
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-cache-prune--budget"></span>`--budget` | string | | Budget for this run (`auto`, `off` or a size such as `20G`). |
+| <span id="cua-cache-prune--all"></span>`--all` | boolean | `false` | Evict every unused cache entry, not only down to the budget. |
+| <span id="cua-cache-prune--dry-run"></span>`--dry-run` | boolean | `false` | Show what would be removed; remove nothing. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-cache-prune"
+# See what a cleanup would remove
+cua cache prune --dry-run
+
+# Evict every unused cache entry
+cua cache prune --all
+```
+
+### `cua cache config`
+
+Show or set the cache settings (`$CUA_HOME/cache.json`; the CUA_CACHE_BUDGET, CUA_DISK_MIN_FREE, CUA_DISK_WARN_FREE and CUA_ORPHAN_REAP_MINUTES environment variables win).
+
+```text output
+cua cache config [OPTIONS]
+```
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-cache-config--budget"></span>`--budget` | string | | Cache budget: `auto` (min of 30 GiB and 10% of free space plus cache), `off`, or a size. |
+| <span id="cua-cache-config--min-free"></span>`--min-free` | string | | Free space pulls, builds and VM creates always leave (size). |
+| <span id="cua-cache-config--warn-free"></span>`--warn-free` | string | | Warn when free space drops under this (size). |
+| <span id="cua-cache-config--orphan-reap-minutes"></span>`--orphan-reap-minutes` | integer | | Minutes before an ephemeral sandbox whose process died is reaped. |
+| <span id="cua-cache-config--auto-gc"></span>`--auto-gc` | `true` \| `false` | | Clean up automatically after pulls and builds and on daemon idle. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-cache-config"
+# Show the settings
+cua cache config
+
+# Cap the cache at 20 GB and keep 10 GB free
+cua cache config --budget 20G --min-free 10G
+```
+
+## `cua cloud`
+
+Spaces in your own cloud account (AWS, Google Cloud, Modal): connect, status, test, disconnect, sweep.
+
+```text output
+cua cloud [OPTIONS] <COMMAND>
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-cloud"
+cua cloud status
+cua cloud connect aws --region us-west-2 --default
+cua spaces create --on aws
+cua cloud sweep
+```
+
+### `cua cloud status`
+
+Your clouds: found credentials, the connected account and region, what each runs at what hourly cost, and what Cua created there.
+
+```text output
+cua cloud status [OPTIONS] [PROVIDER]
+```
+
+Alias: `cua cloud ls`.
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<PROVIDER>` | string | optional | Only this cloud (`aws`, `gcp`, `modal`). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-cloud-status"
+cua cloud status
+cua cloud status aws --json
+```
+
+### `cua cloud connect`
+
+Connect a cloud account Spaces can be created in (after the checks `cua cloud test` runs). Credentials stay in the cloud's own CLI; Cua stores only the profile, region, project or environment names.
+
+```text output
+cua cloud connect [OPTIONS] <PROVIDER>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<PROVIDER>` | string | required | `aws`, `gcp` or `modal`. |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-cloud-connect--profile"></span>`--profile` | string | | AWS profile (`~/.aws/config`) or Modal profile (`~/.modal.toml`). |
+| <span id="cua-cloud-connect--region"></span>`--region` | string | | AWS or Google Cloud region. |
+| <span id="cua-cloud-connect--zone"></span>`--zone` | string | | Google Cloud zone (default: the region's `-a` zone). |
+| <span id="cua-cloud-connect--project"></span>`--project` | string | | Google Cloud project (default: `gcloud config get project`). |
+| <span id="cua-cloud-connect--environment"></span>`--environment` | string | | Modal environment (default: the profile's). |
+| <span id="cua-cloud-connect--ttl-hours"></span>`--ttl-hours` | integer | | Delete each Space there after this many hours (default 8; 0: never; Modal caps a sandbox at 24). |
+| <span id="cua-cloud-connect--default"></span>`--default` | boolean | `false` | Also make it the default location (`default.on`). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-cloud-connect"
+cua cloud connect aws --region us-west-2 --default
+cua cloud connect aws --profile sandbox
+cua cloud connect gcp --project my-project --region us-central1
+cua cloud connect modal --environment spaces
+
+# Spaces there delete themselves after 4 hours (default 8; 0: never)
+cua cloud connect aws --ttl-hours 4
+```
+
+### `cua cloud test`
+
+Check a cloud account without creating anything: credentials, permissions (by dry run), quota, the region and machine types.
+
+```text output
+cua cloud test [OPTIONS] <PROVIDER>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<PROVIDER>` | string | required | `aws`, `gcp` or `modal`. |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-cloud-test--profile"></span>`--profile` | string | | AWS profile (`~/.aws/config`) or Modal profile (`~/.modal.toml`). |
+| <span id="cua-cloud-test--region"></span>`--region` | string | | AWS or Google Cloud region. |
+| <span id="cua-cloud-test--zone"></span>`--zone` | string | | Google Cloud zone (default: the region's `-a` zone). |
+| <span id="cua-cloud-test--project"></span>`--project` | string | | Google Cloud project (default: `gcloud config get project`). |
+| <span id="cua-cloud-test--environment"></span>`--environment` | string | | Modal environment (default: the profile's). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-cloud-test"
+cua cloud test aws
+cua cloud test gcp --project my-project
+```
+
+### `cua cloud disconnect`
+
+Forget a connected cloud (nothing in it is deleted).
+
+```text output
+cua cloud disconnect [OPTIONS] <PROVIDER>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<PROVIDER>` | string | required | `aws`, `gcp` or `modal`. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-cloud-disconnect"
+cua cloud disconnect aws
+```
+
+### `cua cloud sweep`
+
+Find what Cua left in your clouds: expired Spaces and resources whose Space is gone (with --all, every Cua resource). Lists them unless --delete. Only resources Cua tagged and recorded are ever touched.
+
+```text output
+cua cloud sweep [OPTIONS] [PROVIDER]
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<PROVIDER>` | string | optional | Only this cloud. |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-cloud-sweep--delete"></span>`--delete` | boolean | `false` | Delete what it finds (default: list only). |
+| <span id="cua-cloud-sweep--all"></span>`--all` | boolean | `false` | Include Cua resources that have not expired (every Space there). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-cloud-sweep"
+cua cloud sweep
+cua cloud sweep aws --delete
+cua cloud sweep --all --delete
+```
+
+## `cua viewer`
+
+Serve the HTML5 viewer for every sandbox on one loopback port.
+
+```text output
+cua viewer [OPTIONS]
+```
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-viewer--listen"></span>`--listen` | string | `127.0.0.1:0` | Address to listen on (loopback only). |
+| <span id="cua-viewer--no-open"></span>`--no-open` | boolean | `false` | Print the URL without opening a browser. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-viewer"
+# List your sandboxes in the browser and open any of them
+cua viewer
+
+# Fixed port, print the URL only
+cua viewer --listen 127.0.0.1:8211 --no-open
+```
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| `0` | Success. |
+| `1` | Failure, or `cua do` reported an error. |
+| `2` | Invalid argument, or an ambiguous sandbox name (qualify it: `local:NAME`). |
+| `3` | Not found: sandbox, window, skill or image (or an image not published yet). |
+| `4` | Not supported, or not configured (for example no provider credentials). |
+| `5` | No cua-spacesd answered, or a transport failure. |
+| `6` | Unauthenticated or permission denied (by Cua or your cloud account). |
+| `7` | Not enough free disk space (see `cua cache`). |
+| `130` | Cancelled (Ctrl-C during a create): what it made was removed. |
diff --git a/docs/content/docs/cua-cli/reference/cli/skills.mdx b/docs/content/docs/cua-cli/reference/cli/skills.mdx
deleted file mode 100644
index 0964b334ac..0000000000
--- a/docs/content/docs/cua-cli/reference/cli/skills.mdx
+++ /dev/null
@@ -1,165 +0,0 @@
----
-title: "cua skills"
-description: "Record, list and replay demonstrations (skills)."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-cli
- Source: cua dump-docs --type cli
- Version: 0.5.0
-*/}
-
-| Command | Description |
-| --- | --- |
-| [`cua skills list`](#cua-skills-list) | List saved skills. |
-| [`cua skills read`](#cua-skills-read) | Print a skill. |
-| [`cua skills replay`](#cua-skills-replay) | Open a skill's video recording. |
-| [`cua skills delete`](#cua-skills-delete) | Delete a skill. |
-| [`cua skills clean`](#cua-skills-clean) | Delete every skill (asks first). |
-| [`cua skills record`](#cua-skills-record) | Record a demonstration in the HTML5 viewer (it records the screen and your input). |
-
-Every command also accepts the [global options](/cua-cli/reference/cli#global-options).
-
-<span id="cua-skills"></span>
-
-Recorded demonstrations (skills) for agents.
-
-```text output
-cua skills [OPTIONS] <COMMAND>
-```
-
-## `cua skills list`
-
-List saved skills.
-
-```text output
-cua skills list [OPTIONS]
-```
-
-Alias: `cua skills ls`.
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-skills-list"
-cua skills list
-```
-
-## `cua skills read`
-
-Print a skill.
-
-```text output
-cua skills read [OPTIONS] <NAME>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<NAME>` | string | required | Skill name. |
-
-| Flag | Short | Type | Default | Description |
-| --- | --- | --- | --- | --- |
-| <span id="cua-skills-read--format"></span>`--format` | `-f` | `md` \| `json` | `md` | Output format. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-skills-read"
-cua skills read export-invoice
-cua skills read export-invoice --format json
-```
-
-## `cua skills replay`
-
-Open a skill's video recording.
-
-```text output
-cua skills replay [OPTIONS] <NAME>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<NAME>` | string | required | Skill name. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-skills-replay"
-cua skills replay export-invoice
-```
-
-## `cua skills delete`
-
-Delete a skill.
-
-```text output
-cua skills delete [OPTIONS] <NAME>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<NAME>` | string | required | Skill name. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-skills-delete"
-cua skills delete export-invoice
-```
-
-## `cua skills clean`
-
-Delete every skill (asks first).
-
-```text output
-cua skills clean [OPTIONS]
-```
-
-| Flag | Short | Type | Default | Description |
-| --- | --- | --- | --- | --- |
-| <span id="cua-skills-clean--yes"></span>`--yes` | `-y` | boolean | `false` | Do not ask for confirmation. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-skills-clean"
-cua skills clean
-
-# Without the prompt
-cua skills clean --yes
-```
-
-## `cua skills record`
-
-Record a demonstration in the HTML5 viewer (it records the screen and your input).
-
-```text output
-cua skills record [OPTIONS]
-```
-
-| Flag | Short | Type | Default | Description |
-| --- | --- | --- | --- | --- |
-| <span id="cua-skills-record--sandbox"></span>`--sandbox` | `-s` | string | | Sandbox whose display service to record. |
-| <span id="cua-skills-record--viewer-url"></span>`--viewer-url` | `-u` | string | | Viewer URL to record (a `cua sb view --no-open` link). Alias: `--vnc-url`. |
-| <span id="cua-skills-record--provider"></span>`--provider` | `-p` | `anthropic` \| `openai` | `anthropic` | Captioning provider. |
-| <span id="cua-skills-record--model"></span>`--model` | `-m` | string | | Captioning model. |
-| <span id="cua-skills-record--api-key"></span>`--api-key` | `-k` | string | | API key for the captioning provider. |
-| <span id="cua-skills-record--name"></span>`--name` | `-n` | string | | Skill name. |
-| <span id="cua-skills-record--description"></span>`--description` | `-d` | string | | Skill description. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-skills-record"
-# Record on the sandbox dev and caption with Anthropic
-cua skills record --sandbox dev --name export-invoice
-```
-
-## Exit codes
-
-| Code | Meaning |
-| --- | --- |
-| `0` | Success. |
-| `1` | Failure, or `cua do` reported an error. |
-| `2` | Invalid argument, or an ambiguous sandbox name (qualify it: `local:NAME`). |
-| `3` | Not found: sandbox, window, skill or image (or an image not published yet). |
-| `4` | Not supported, or not configured (for example no provider credentials). |
-| `5` | No cua-spacesd answered, or a transport failure. |
-| `6` | Unauthenticated or permission denied (by Cua or your cloud account). |
-| `7` | Not enough free disk space (see `cua cache`). |
-| `130` | Cancelled (Ctrl-C during a create): what it made was removed. |
diff --git a/docs/content/docs/cua-cli/reference/cli/spaces-and-computers.mdx b/docs/content/docs/cua-cli/reference/cli/spaces-and-computers.mdx
new file mode 100644
index 0000000000..1b852894f4
--- /dev/null
+++ b/docs/content/docs/cua-cli/reference/cli/spaces-and-computers.mdx
@@ -0,0 +1,1299 @@
+---
+title: "Spaces, computers and teams"
+description: "Your Spaces and machines, unattended access on this machine, devices, teams, your remote use this month, and a cua-spacesd by URL."
+---
+
+{/*
+ AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
+ Generated by: pnpm --dir docs docs:generate:cua-cli
+ Source: cua dump-docs --type cli
+ Version: 0.5.0
+*/}
+
+| Command | Description |
+| --- | --- |
+| [`cua spaces`](#cua-spaces) | Spaces: registered ones and your machines on the relay. |
+| [`cua spaces ls`](#cua-spaces-ls) | Registered Spaces and your machines on the relay. |
+| [`cua spaces add`](#cua-spaces-add) | Register a Space after a capabilities handshake with its cua-spacesd (or, for another URL, an MCP initialize). |
+| [`cua spaces create`](#cua-spaces-create) | Create Spaces: on this machine, on one of your machines that provides Spaces (`cua host setup --provide-spaces` there), or in your own cloud account. |
+| [`cua spaces cancel`](#cua-spaces-cancel) | Cancel a create that is still running (here, in the daemon, or in another terminal): it stops and what it made is removed. |
+| [`cua spaces gpus`](#cua-spaces-gpus) | The GPU options each runtime offers on this machine (or in your own cloud account). |
+| [`cua spaces delete`](#cua-spaces-delete) | Delete a Space's sandbox (on this machine, on the machine that provides it, or in your own cloud account) and forget it (asks first). |
+| [`cua spaces stop`](#cua-spaces-stop) | Turn a Space off: a local container or QEMU VM is suspended (its memory is kept), a Lume VM or a Space one of your machines provides is stopped (its disk is kept), and so is a Space in your own cloud (`--on aws`, `gcp`; compute billing stops). |
+| [`cua spaces start`](#cua-spaces-start) | Turn a Space back on: resume a suspended one or boot a stopped one. |
+| [`cua spaces rm`](#cua-spaces-rm) | Forget a registered Space and its stored token. |
+| [`cua spaces share`](#cua-spaces-share) | Let another cua.ai account watch (viewer) or use (editor) a Space, through the relay. |
+| [`cua spaces unshare`](#cua-spaces-unshare) | Stop sharing a Space with one account at once, or with everyone. |
+| [`cua spaces shares`](#cua-spaces-shares) | Who a Space is shared with, and who of them is connected now. |
+| [`cua spaces relay-register`](#cua-spaces-relay-register) | Publish a Space on the relay for your other devices (a phone off this network): its own driver dials out, as `cua host setup` does for this computer. |
+| [`cua spaces relay-unregister`](#cua-spaces-relay-unregister) | Take a Space off the relay (every share with it ends). |
+| [`cua host`](#cua-host) | Unattended access to this machine (setup, status, stop, start, remove). |
+| [`cua host setup`](#cua-host-setup) | Set this machine up for unattended access: install cua-spacesd as a service that joins the cua.ai relay as your account (default) or serves on a direct ip:port. |
+| [`cua host pair`](#cua-host-pair) | Make a one-time code (with a link and the install command) that adds another computer to your account: run the command it prints on that computer. |
+| [`cua host config`](#cua-host-config) | Show or change what this machine shares: its own desktop, and whether it creates Spaces for your other devices. |
+| [`cua host status`](#cua-host-status) | Show whether this machine is set up, the service, and who is connected. |
+| [`cua host stop`](#cua-host-stop) | Stop sharing: disconnect everyone and refuse new connections. |
+| [`cua host start`](#cua-host-start) | Start sharing again after `stop`. |
+| [`cua host share`](#cua-host-share) | Share a relay machine (this one, or `--machine`) with other cua.ai accounts (id or verified email). |
+| [`cua host unshare`](#cua-host-unshare) | Stop sharing a relay machine with accounts; their open connections are cut. |
+| [`cua host remove`](#cua-host-remove) | Unregister from the relay, uninstall the service and delete the host configuration (asks first). |
+| [`cua devices`](#cua-devices) | This device as a client of your cua.ai account on the relay: enroll (second factor), approve other devices, list, rename, revoke, and the audit log of who accessed what. |
+| [`cua devices status`](#cua-devices-status) | This device: enrolled, waiting for approval, or not enrolled. |
+| [`cua devices enroll`](#cua-devices-enroll) | Enroll this device. |
+| [`cua devices approve`](#cua-devices-approve) | Approve a new device (or re-verify an expired one) from this enrolled device, by the code it shows or by its id. |
+| [`cua devices ls`](#cua-devices-ls) | Your devices and their state. |
+| [`cua devices rename`](#cua-devices-rename) | Rename a device. |
+| [`cua devices revoke`](#cua-devices-revoke) | Revoke a device: it can no longer list or reach your machines. |
+| [`cua devices audit`](#cua-devices-audit) | Who accessed what, and when: enrollments, device sessions, machine access (yours and by accounts you share with), sharing changes. |
+| [`cua team`](#cua-team) | Teams (organizations of your cua.ai account) share machines with every member and their agents. |
+| [`cua team create`](#cua-team-create) | Create a team; you are its owner. |
+| [`cua team ls`](#cua-team-ls) | Your teams. |
+| [`cua team show`](#cua-team-show) | A team: plan, members, machines, open invites and devices. |
+| [`cua team invite`](#cua-team-invite) | Invite someone by email: cua.ai emails them an invitation. |
+| [`cua team join`](#cua-team-join) | After accepting an emailed invitation: take the role it offered. |
+| [`cua team leave`](#cua-team-leave) | Leave a team. |
+| [`cua team remove-member`](#cua-team-remove-member) | Remove a member (owner or admin; admins cannot remove admins). |
+| [`cua team set-role`](#cua-team-set-role) | Make a member an admin, or an admin a member (owner). |
+| [`cua team devices`](#cua-team-devices) | Member devices and whether they may open team machines. |
+| [`cua team approve`](#cua-team-approve) | Approve a member device so it can open team machines. |
+| [`cua team deny`](#cua-team-deny) | Decline a member device (it can no longer open team machines). |
+| [`cua team request`](#cua-team-request) | Ask the team's admins to approve this device. |
+| [`cua team add-machine`](#cua-team-add-machine) | Make a Space (or a machine you host) a team machine: every member and their agents see it and can open it. |
+| [`cua team remove-machine`](#cua-team-remove-machine) | Take a machine off the team. |
+| [`cua team audit`](#cua-team-audit) | The team's audit log. |
+| [`cua team delete`](#cua-team-delete) | Delete a team (owner; cancel its subscription first). |
+| [`cua usage`](#cua-usage) | Your relay allowance this month: live sessions, relay hours, and your plan. |
+| [`cua spacesd`](#cua-spacesd) | Talk to a cua-spacesd directly by URL. |
+| [`cua spacesd caps`](#cua-spacesd-caps) | Print capabilities. |
+| [`cua spacesd exec`](#cua-spacesd-exec) | Run a command (argv, no shell). |
+| [`cua spacesd cp`](#cua-spacesd-cp) | Copy files: `cua spacesd cp <URL> local :remote` uploads, `cua spacesd cp <URL> :remote local` downloads. |
+| [`cua spacesd shell`](#cua-spacesd-shell) | Interactive shell (PTY). |
+| [`cua spacesd targets`](#cua-spacesd-targets) | List streamable targets (displays, and windows with --windows). |
+| [`cua spacesd call`](#cua-spacesd-call) | Call any cua.env.v1 RPC with a proto3-JSON body. |
+
+Every command also accepts the [global options](/cua-cli/reference/cli#global-options).
+
+## `cua spaces`
+
+Spaces: registered ones and your machines on the relay.
+
+```text output
+cua spaces [OPTIONS] <COMMAND>
+```
+
+### `cua spaces ls`
+
+Registered Spaces and your machines on the relay.
+
+```text output
+cua spaces ls [OPTIONS]
+```
+
+Alias: `cua spaces list`.
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-spaces-ls--relay"></span>`--relay` | string | | Relay URL (default $CUA_RELAY_URL, else the CUA_ENV relay, https://relay.cua.ai in production). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-spaces-ls"
+cua spaces ls
+cua spaces ls --json
+```
+
+### `cua spaces add`
+
+Register a Space after a capabilities handshake with its cua-spacesd (or, for another URL, an MCP initialize). Re-adding an address updates it. The token is stored apart from the registry, 0600.
+
+```text output
+cua spaces add [OPTIONS] <URL>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<URL>` | string | required | The Space's cua-spacesd (`http(s)://host:port`, `host:port`, default port 3211), a Space id (`local:<name>`), or any MCP endpoint URL. |
+
+| Flag | Type | Default | Env var | Description |
+| --- | --- | --- | --- | --- |
+| <span id="cua-spaces-add--token"></span>`--token` | string | | `CUA_ENV_TOKEN` | spacesd token (or the bearer an MCP endpoint needs). |
+| <span id="cua-spaces-add--name"></span>`--name` | string | | | Display name (default: the guest's hostname). |
+| <span id="cua-spaces-add--service"></span>`--service` | string | | | For an MCP endpoint URL: the service name to register it under (default `mcp`). |
+| <span id="cua-spaces-add--host"></span>`--host` | boolean | `false` | | It is a machine that provides Spaces over its direct address (Tailscale or LAN): `--on host:<name>` finds it without the relay. Its token is stored like any direct Space's. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-spaces-add"
+cua spaces add 10.0.0.5:3211 --token "$TOKEN" --name studio
+cua spaces add local:my-sandbox
+cua spaces add http://127.0.0.1:8765/mcp --service tools
+
+# A machine that provides Spaces over Tailscale, without the relay (`cua host setup --direct ... --provide-spaces` on it prints this)
+cua spaces add 100.101.102.103:3211 --host --name "Mac mini (spare)" --token "$TOKEN"
+```
+
+### `cua spaces create`
+
+Create Spaces: on this machine, on one of your machines that provides Spaces (`cua host setup --provide-spaces` there), or in your own cloud account.
+
+```text output
+cua spaces create [OPTIONS] [IMAGE]
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<IMAGE>` | string | optional | Image: an alias (`linux`, `macos`, `macos:26`) or a registry reference. Default: the canonical Linux image. |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-spaces-create--on"></span>`--on` | string | | Where: `local`, `aws`, `gcp`, `host:<machine>`, or a machine name (`mac-mini`, "spare mac mini"). Default: your default location. |
+| <span id="cua-spaces-create--count"></span>`--count` | integer | `1` | How many (1 to 8). |
+| <span id="cua-spaces-create--name"></span>`--name` | string | | Name (with --count, `-2`, `-3`, ... are appended). |
+| <span id="cua-spaces-create--kind"></span>`--kind` | string | | auto \| container \| vm. |
+| <span id="cua-spaces-create--runtime"></span>`--runtime` | string | | auto, or an engine the location offers (lume, runc, gvisor, qemu). |
+| <span id="cua-spaces-create--cpus"></span>`--cpus` | integer | | vCPUs. |
+| <span id="cua-spaces-create--memory-mb"></span>`--memory-mb` | integer | | Memory in MiB. |
+| <span id="cua-spaces-create--disk-gb"></span>`--disk-gb` | integer | | Grow a VM's disk to this many GiB. |
+| <span id="cua-spaces-create--gpu"></span>`--gpu` | string | | A GPU: the runtime's own (`--gpu`), or an option `cua spaces gpus` lists. macOS VMs: GPU acceleration (experimental, Apple silicon; https://cua.ai/docs/lume/guides/gpu-passthrough). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-spaces-create"
+cua spaces create linux
+
+# Two macOS VMs on your spare Mac mini (matched by name)
+cua spaces create macos:26 --on "spare mac mini" --count 2
+cua spaces create --on host:0123abcd4567ef89 linux --json
+```
+
+### `cua spaces cancel`
+
+Cancel a create that is still running (here, in the daemon, or in another terminal): it stops and what it made is removed. Finished image downloads stay cached. Ctrl-C during `cua spaces create` does the same.
+
+```text output
+cua spaces cancel [OPTIONS] <SPACE>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<SPACE>` | string | required | The id the Space will have (`local:<name>`, printed when the create starts) or its name. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-spaces-cancel"
+cua spaces cancel local:space-1a2b3c
+cua spaces cancel studio
+```
+
+### `cua spaces gpus`
+
+The GPU options each runtime offers on this machine (or in your own cloud account).
+
+```text output
+cua spaces gpus [OPTIONS]
+```
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-spaces-gpus--on"></span>`--on` | string | | `local` (default), `aws`, `gcp` or `modal`. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-spaces-gpus"
+cua spaces gpus
+cua spaces gpus --json
+```
+
+### `cua spaces delete`
+
+Delete a Space's sandbox (on this machine, on the machine that provides it, or in your own cloud account) and forget it (asks first).
+
+```text output
+cua spaces delete [OPTIONS] <SPACE>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<SPACE>` | string | required | Space id or name. |
+
+| Flag | Short | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| <span id="cua-spaces-delete--force"></span>`--force` | `-f` | boolean | `false` | Skip the confirmation (required without a terminal). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-spaces-delete"
+cua spaces delete relay:space-0123456789abcdef
+cua spaces delete local:studio --force
+```
+
+### `cua spaces stop`
+
+Turn a Space off: a local container or QEMU VM is suspended (its memory is kept), a Lume VM or a Space one of your machines provides is stopped (its disk is kept), and so is a Space in your own cloud (`--on aws`, `gcp`; compute billing stops). Modal sandboxes and Spaces added by address cannot be turned off.
+
+```text output
+cua spaces stop [OPTIONS] <SPACE>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<SPACE>` | string | required | Space id or name. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-spaces-stop"
+cua spaces stop local:studio
+cua spaces stop relay:space-0123456789abcdef --json
+```
+
+### `cua spaces start`
+
+Turn a Space back on: resume a suspended one or boot a stopped one.
+
+```text output
+cua spaces start [OPTIONS] <SPACE>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<SPACE>` | string | required | Space id or name. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-spaces-start"
+cua spaces start local:studio
+cua spaces start studio --json
+```
+
+### `cua spaces rm`
+
+Forget a registered Space and its stored token. The sandbox keeps running. The `relay:<machine>` record of a Space that registered itself and is gone (not connected) also leaves your relay directory.
+
+```text output
+cua spaces rm [OPTIONS] <SPACE>
+```
+
+Alias: `cua spaces remove`.
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<SPACE>` | string | required | Space id, address or display name (as `cua spaces ls` shows). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-spaces-rm"
+cua spaces rm direct:10.0.0.5:3211
+cua spaces rm studio
+```
+
+### `cua spaces share`
+
+Let another cua.ai account watch (viewer) or use (editor) a Space, through the relay. They open it as `relay:<machine>`.
+
+```text output
+cua spaces share [OPTIONS] <SPACE> <WHO>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<SPACE>` | string | required | Space id, address or display name. |
+| `<WHO>` | string | required | Their email (verified by cua.ai) or account id. |
+
+| Flag | Short | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| <span id="cua-spaces-share--role"></span>`--role` | | `viewer` \| `editor` | `viewer` | `viewer`: presence and a view-only stream. `editor`: full use. |
+| <span id="cua-spaces-share--yes"></span>`--yes` | `-y` | boolean | `false` | Confirm without a terminal prompt. Without a daemon the share happens at once. A running daemon still asks with Touch ID or your password on this computer; without a terminal, `--yes` says someone will answer there (otherwise the command fails at once instead of waiting for a prompt nobody sees). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-spaces-share"
+cua spaces share local:studio [email protected]
+cua spaces share local:studio [email protected] --role editor
+cua spaces share relay:0123abcd4567ef89 acct-42 --role viewer
+
+# From a script or agent: confirm with Touch ID or your password here
+cua spaces share local:studio [email protected] --yes
+```
+
+### `cua spaces unshare`
+
+Stop sharing a Space with one account at once, or with everyone.
+
+```text output
+cua spaces unshare [OPTIONS] <SPACE> [WHO]
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<SPACE>` | string | required | Space id, address or display name. |
+| `<WHO>` | string | optional | Their email or account id. |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-spaces-unshare--all"></span>`--all` | boolean | `false` | Stop sharing with everyone (the Space leaves the relay). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-spaces-unshare"
+cua spaces unshare local:studio [email protected]
+cua spaces unshare local:studio --all
+```
+
+### `cua spaces shares`
+
+Who a Space is shared with, and who of them is connected now.
+
+```text output
+cua spaces shares [OPTIONS] <SPACE>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<SPACE>` | string | required | Space id, address or display name. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-spaces-shares"
+cua spaces shares local:studio
+cua spaces shares local:studio --json
+```
+
+### `cua spaces relay-register`
+
+Publish a Space on the relay for your other devices (a phone off this network): its own driver dials out, as `cua host setup` does for this computer. Nobody else gets in until you share it.
+
+```text output
+cua spaces relay-register [OPTIONS] <SPACE>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<SPACE>` | string | required | Space id, address or display name. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-spaces-relay-register"
+cua spaces relay-register local:studio
+```
+
+### `cua spaces relay-unregister`
+
+Take a Space off the relay (every share with it ends). With a `relay:<machine>` id, removes that machine's record from your relay directory: a Space that registered itself (also after it was deleted), or a machine of yours that is gone. Only its owner can.
+
+```text output
+cua spaces relay-unregister [OPTIONS] <SPACE>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<SPACE>` | string | required | Space id, address or display name. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-spaces-relay-unregister"
+cua spaces relay-unregister local:studio
+cua spaces relay-unregister relay:space-0123abcd4567ef89
+```
+
+## `cua host`
+
+Unattended access to this machine (setup, status, stop, start, remove).
+
+```text output
+cua host [OPTIONS] <COMMAND>
+```
+
+### `cua host setup`
+
+Set this machine up for unattended access: install cua-spacesd as a service that joins the cua.ai relay as your account (default) or serves on a direct ip:port.
+
+```text output
+cua host setup [OPTIONS]
+```
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-host-setup--relay"></span>`--relay` | string | | Relay URL (default $CUA_RELAY_URL, else the CUA_ENV relay, https://relay.cua.ai in production). |
+| <span id="cua-host-setup--pair"></span>`--pair` | string | | Join with a one-time pairing code (or add-machine link) made in the Cua Spaces app or with `cua host pair`, instead of signing in here. The machine joins the account (or team) that made it. |
+| <span id="cua-host-setup--direct"></span>`--direct` | string | | Serve directly on ip:port with a local env token (LAN / port-forwarded) instead of joining a relay. |
+| <span id="cua-host-setup--name"></span>`--name` | string | | Display name (default: the host name). |
+| <span id="cua-host-setup--allow"></span>`--allow` | string | | Also allow this account (id or email). Repeatable. |
+| <span id="cua-host-setup--driver-bin"></span>`--driver-bin` | path | | cua-spacesd binary (default $CUA_SPACESD_BIN, a bundled one, or the release download). |
+| <span id="cua-host-setup--runner"></span>`--runner` | string | `auto` | auto \| systemd \| launchd \| windows-task \| process. |
+| <span id="cua-host-setup--profile"></span>`--profile` | `desktop` \| `spare` | `desktop` | What this machine is for: `desktop` (share this desktop; the default) or `spare` (do not share the desktop; provide Spaces). |
+| <span id="cua-host-setup--max-spaces"></span>`--max-spaces` | integer | | Provided Spaces at once (default 4; 0: no limit). |
+| <span id="cua-host-setup--remote"></span>`--remote` | boolean | `false` | When sign-in is needed, use a device code to approve it in a browser on another machine. The account session is not saved. |
+| <span id="cua-host-setup--desktop"></span>`--desktop` | boolean | `false` | Share this machine's own desktop as a Space. |
+| <span id="cua-host-setup--no-desktop"></span>`--no-desktop` | boolean | `false` | Do not share this machine's own desktop (screen, input, shell, files): relayed callers reach only the Spaces it provides. |
+| <span id="cua-host-setup--provide-spaces"></span>`--provide-spaces` | boolean | `false` | Create Spaces for your enrolled devices on this machine's runtimes (Lume macOS VMs, Docker Linux containers). |
+| <span id="cua-host-setup--no-provide-spaces"></span>`--no-provide-spaces` | boolean | `false` | Do not create Spaces for other devices. |
+| <span id="cua-host-setup--allow-any-address"></span>`--allow-any-address` | boolean | `false` | With --direct and Spaces: take host calls, and connections to the Spaces this machine forwards, from any address (and allow a public --direct address). By default only loopback, Tailscale and private LAN addresses may. The direct listener is plaintext and its token is a shell on this machine: prefer Tailscale. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-host-setup"
+# Join the cua.ai relay as your account (shares this desktop)
+cua host setup
+
+# A spare machine: do not share its desktop, run Spaces for your devices
+cua host setup --profile spare --name "Mac mini (spare)"
+cua host setup --no-desktop --provide-spaces
+
+# Serve on the LAN instead of the relay
+cua host setup --direct 0.0.0.0:3211 --name studio-mac
+
+# A spare Mac on your tailnet that runs Spaces, without the relay (prints the command that adds it on your laptop)
+cua host setup --direct 100.101.102.103:3211 --profile spare
+
+# Add this machine with a one-time code from the Cua Spaces app (Add a machine) or `cua host pair`: no sign-in needed here
+cua host setup --pair K7QM-4XPB-2RHD
+```
+
+### `cua host pair`
+
+Make a one-time code (with a link and the install command) that adds another computer to your account: run the command it prints on that computer. Codes work once and expire (30 minutes by default). Run from an enrolled device.
+
+```text output
+cua host pair [OPTIONS]
+```
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-host-pair--team"></span>`--team` | string | | Add the machine to this team (id, alias or name; owner or admin): waits until the machine joins, then makes it a team machine. |
+| <span id="cua-host-pair--name"></span>`--name` | string | | Name the machine gets (default: its own host name). |
+| <span id="cua-host-pair--expires"></span>`--expires` | integer | `30` | Minutes until the code expires (1 to 1440). |
+| <span id="cua-host-pair--revoke"></span>`--revoke` | string | | Revoke an unused code by id (`pc_…`). |
+| <span id="cua-host-pair--relay"></span>`--relay` | string | | Relay URL (default $CUA_RELAY_URL, else the CUA_ENV relay, https://relay.cua.ai in production). |
+| <span id="cua-host-pair--no-wait"></span>`--no-wait` | boolean | `false` | With --team: print the code and exit instead of waiting; add the machine later with `cua team add-machine <team> relay:<id>`. |
+| <span id="cua-host-pair--list"></span>`--list` | boolean | `false` | List your codes (used, unused, revoked, expired) instead. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-host-pair"
+cua host pair
+cua host pair --name build-box --expires 60
+cua host pair --list
+cua host pair --revoke pc_0123456789abcdef
+
+# Add the machine to a team: waits for it to join, then adds it
+cua host pair --team AIGIS
+```
+
+### `cua host config`
+
+Show or change what this machine shares: its own desktop, and whether it creates Spaces for your other devices.
+
+```text output
+cua host config [OPTIONS]
+```
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-host-config--desktop"></span>`--desktop` | `on` \| `off` | | Share this machine's own desktop: on \| off. |
+| <span id="cua-host-config--provide-spaces"></span>`--provide-spaces` | `on` \| `off` | | Create Spaces for your enrolled devices: on \| off. |
+| <span id="cua-host-config--max-spaces"></span>`--max-spaces` | integer | | Provided Spaces at once (0: no limit). |
+| <span id="cua-host-config--max-macos-vms"></span>`--max-macos-vms` | integer | | macOS VMs at once, 0 to 2 (Apple's license allows two per Mac). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-host-config"
+cua host config
+
+# Stop sharing this desktop; keep providing Spaces
+cua host config --desktop off --provide-spaces on
+cua host config --max-spaces 6
+```
+
+### `cua host status`
+
+Show whether this machine is set up, the service, and who is connected.
+
+```text output
+cua host status [OPTIONS]
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-host-status"
+cua host status
+```
+
+### `cua host stop`
+
+Stop sharing: disconnect everyone and refuse new connections.
+
+```text output
+cua host stop [OPTIONS]
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-host-stop"
+cua host stop
+```
+
+### `cua host start`
+
+Start sharing again after `stop`.
+
+```text output
+cua host start [OPTIONS]
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-host-start"
+cua host start
+```
+
+### `cua host share`
+
+Share a relay machine (this one, or `--machine`) with other cua.ai accounts (id or verified email). Run from an enrolled device; every change is in the owner's audit log (`cua devices audit`).
+
+```text output
+cua host share [OPTIONS] <WHO>...
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<WHO>...` | string | required | Accounts to add. Repeatable. Repeatable. |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-host-share--machine"></span>`--machine` | string | | Machine id (default: this machine). |
+| <span id="cua-host-share--relay"></span>`--relay` | string | | Relay URL (default: the one this machine joined, else $CUA_RELAY_URL / https://relay.cua.ai). |
+| <span id="cua-host-share--yes"></span>`--yes` | boolean | `false` | Do not ask for confirmation. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-host-share"
+cua host share [email protected]
+cua host share [email protected] --machine 0123abcd4567ef89 --yes
+```
+
+### `cua host unshare`
+
+Stop sharing a relay machine with accounts; their open connections are cut.
+
+```text output
+cua host unshare [OPTIONS] <WHO>...
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<WHO>...` | string | required | Accounts to remove. Repeatable. Repeatable. |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-host-unshare--machine"></span>`--machine` | string | | Machine id (default: this machine). |
+| <span id="cua-host-unshare--relay"></span>`--relay` | string | | Relay URL. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-host-unshare"
+cua host unshare [email protected]
+```
+
+### `cua host remove`
+
+Unregister from the relay, uninstall the service and delete the host configuration (asks first).
+
+```text output
+cua host remove [OPTIONS]
+```
+
+| Flag | Short | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| <span id="cua-host-remove--force"></span>`--force` | `-f` | boolean | `false` | Skip the confirmation prompt. Required when there is no terminal to ask on (scripts, agents): without it nothing is removed. |
+| <span id="cua-host-remove--uninstalling"></span>`--uninstalling` | | boolean | `false` | For an uninstall of Cua Spaces: turns off the Spaces this machine provides and takes them off the relay too, instead of refusing while it provides any. The Spaces and their data stay on this machine. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-host-remove"
+cua host remove
+
+# Without the prompt (required in scripts and agents)
+cua host remove --force
+```
+
+## `cua devices`
+
+This device as a client of your cua.ai account on the relay: enroll (second factor), approve other devices, list, rename, revoke, and the audit log of who accessed what.
+
+```text output
+cua devices [OPTIONS] <COMMAND>
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-devices"
+cua devices enroll
+cua devices approve K7QX-M2RP
+cua devices ls
+cua devices audit
+```
+
+### `cua devices status`
+
+This device: enrolled, waiting for approval, or not enrolled.
+
+```text output
+cua devices status [OPTIONS]
+```
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-devices-status--relay"></span>`--relay` | string | | Relay URL (default $CUA_RELAY_URL, else the CUA_ENV relay, https://relay.cua.ai in production). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-devices-status"
+cua devices status
+```
+
+### `cua devices enroll`
+
+Enroll this device. Right after a fresh `cua auth login` it enrolls at once (and replaces this machine's older device key, if any); otherwise it shows a one-time code to approve from an enrolled device (`cua devices approve <code>` or the Cua Spaces app).
+
+```text output
+cua devices enroll [OPTIONS]
+```
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-devices-enroll--name"></span>`--name` | string | | Display name (default: the host name). |
+| <span id="cua-devices-enroll--relay"></span>`--relay` | string | | Relay URL. |
+| <span id="cua-devices-enroll--wait"></span>`--wait` | boolean | `false` | Wait (up to 10 minutes) until an enrolled device approves. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-devices-enroll"
+cua devices enroll
+cua devices enroll --name "work laptop" --wait
+```
+
+### `cua devices approve`
+
+Approve a new device (or re-verify an expired one) from this enrolled device, by the code it shows or by its id.
+
+```text output
+cua devices approve [OPTIONS] [CODE]
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<CODE>` | string | optional | The one-time code the new device shows, or its device id (`dev_…`, from `cua devices ls`). |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-devices-approve--device"></span>`--device` | string | | Or the device id (`cua devices ls`). |
+| <span id="cua-devices-approve--relay"></span>`--relay` | string | | Relay URL. |
+| <span id="cua-devices-approve--yes"></span>`--yes` | boolean | `false` | Do not ask for confirmation. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-devices-approve"
+cua devices approve K7QX-M2RP
+cua devices approve dev_0123456789abcdef01234567
+```
+
+### `cua devices ls`
+
+Your devices and their state.
+
+```text output
+cua devices ls [OPTIONS]
+```
+
+Alias: `cua devices list`.
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-devices-ls--relay"></span>`--relay` | string | | Relay URL. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-devices-ls"
+cua devices ls
+cua devices ls --json
+```
+
+### `cua devices rename`
+
+Rename a device.
+
+```text output
+cua devices rename [OPTIONS] <ID> <NAME>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<ID>` | string | required | Device id. |
+| `<NAME>` | string | required | New name. |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-devices-rename--relay"></span>`--relay` | string | | Relay URL. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-devices-rename"
+cua devices rename dev_0123456789abcdef01234567 "work phone"
+```
+
+### `cua devices revoke`
+
+Revoke a device: it can no longer list or reach your machines.
+
+```text output
+cua devices revoke [OPTIONS] <ID>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<ID>` | string | required | Device id. |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-devices-revoke--relay"></span>`--relay` | string | | Relay URL. |
+| <span id="cua-devices-revoke--yes"></span>`--yes` | boolean | `false` | Do not ask for confirmation. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-devices-revoke"
+cua devices revoke dev_0123456789abcdef01234567
+```
+
+### `cua devices audit`
+
+Who accessed what, and when: enrollments, device sessions, machine access (yours and by accounts you share with), sharing changes.
+
+```text output
+cua devices audit [OPTIONS]
+```
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-devices-audit--limit"></span>`--limit` | integer | `50` | Newest events to show. |
+| <span id="cua-devices-audit--relay"></span>`--relay` | string | | Relay URL. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-devices-audit"
+cua devices audit
+cua devices audit --limit 20 --json
+```
+
+## `cua team`
+
+Teams (organizations of your cua.ai account) share machines with every member and their agents. Owners and admins invite by email, approve member devices and add machines.
+
+```text output
+cua team [OPTIONS] <COMMAND>
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-team"
+cua team create AIGIS
+cua team invite AIGIS [email protected]
+cua team add-machine AIGIS local:build-box
+cua team approve AIGIS dev_0123456789abcdef01234567
+cua team show AIGIS
+```
+
+### `cua team create`
+
+Create a team; you are its owner. Buy Teams for it at app.cua.ai to add machines.
+
+```text output
+cua team create [OPTIONS] <NAME>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<NAME>` | string | required | Team name. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-team-create"
+cua team create "AIGIS"
+```
+
+### `cua team ls`
+
+Your teams.
+
+```text output
+cua team ls [OPTIONS]
+```
+
+Alias: `cua team list`.
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-team-ls"
+cua team ls
+cua team ls --json
+```
+
+### `cua team show`
+
+A team: plan, members, machines, open invites and devices.
+
+```text output
+cua team show [OPTIONS] <TEAM>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<TEAM>` | string | required | Team id, alias or name. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-team-show"
+cua team show AIGIS
+```
+
+### `cua team invite`
+
+Invite someone by email: cua.ai emails them an invitation. Manage invites at app.cua.ai/team.
+
+```text output
+cua team invite [OPTIONS] <TEAM> <EMAIL>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<TEAM>` | string | required | Team id, alias or name. |
+| `<EMAIL>` | string | required | Their email. |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-team-invite--role"></span>`--role` | `member` \| `admin` | `member` | `member` or `admin` (only the owner invites admins). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-team-invite"
+cua team invite AIGIS [email protected]
+cua team invite AIGIS [email protected] --role admin
+```
+
+### `cua team join`
+
+After accepting an emailed invitation: take the role it offered. Run `cua auth login` first so your session lists the team.
+
+```text output
+cua team join [OPTIONS] <TEAM>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<TEAM>` | string | required | Team id, alias or name. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-team-join"
+cua team join AIGIS
+```
+
+### `cua team leave`
+
+Leave a team.
+
+```text output
+cua team leave [OPTIONS] <TEAM>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<TEAM>` | string | required | Team id, alias or name. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-team-leave"
+cua team leave AIGIS
+```
+
+### `cua team remove-member`
+
+Remove a member (owner or admin; admins cannot remove admins).
+
+```text output
+cua team remove-member [OPTIONS] <TEAM> <WHO>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<TEAM>` | string | required | Team id, alias or name. |
+| `<WHO>` | string | required | Their email or account id. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-team-remove-member"
+cua team remove-member AIGIS [email protected]
+```
+
+### `cua team set-role`
+
+Make a member an admin, or an admin a member (owner).
+
+```text output
+cua team set-role [OPTIONS] <TEAM> <WHO> <ROLE>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<TEAM>` | string | required | Team id, alias or name. |
+| `<WHO>` | string | required | Their email or account id. |
+| `<ROLE>` | `member` \| `admin` | required | `member` or `admin`. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-team-set-role"
+cua team set-role AIGIS [email protected] admin
+```
+
+### `cua team devices`
+
+Member devices and whether they may open team machines.
+
+```text output
+cua team devices [OPTIONS] <TEAM>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<TEAM>` | string | required | Team id, alias or name. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-team-devices"
+cua team devices AIGIS
+```
+
+### `cua team approve`
+
+Approve a member device so it can open team machines.
+
+```text output
+cua team approve [OPTIONS] <TEAM> <DEVICE>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<TEAM>` | string | required | Team id, alias or name. |
+| `<DEVICE>` | string | required | Device id (`cua team devices`). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-team-approve"
+cua team approve AIGIS dev_0123456789abcdef01234567
+```
+
+### `cua team deny`
+
+Decline a member device (it can no longer open team machines).
+
+```text output
+cua team deny [OPTIONS] <TEAM> <DEVICE>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<TEAM>` | string | required | Team id, alias or name. |
+| `<DEVICE>` | string | required | Device id. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-team-deny"
+cua team deny AIGIS dev_0123456789abcdef01234567
+```
+
+### `cua team request`
+
+Ask the team's admins to approve this device.
+
+```text output
+cua team request [OPTIONS] <TEAM>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<TEAM>` | string | required | Team id, alias or name. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-team-request"
+cua team request AIGIS
+```
+
+### `cua team add-machine`
+
+Make a Space (or a machine you host) a team machine: every member and their agents see it and can open it. Macs, Linux and Windows machines all can. Each Space is added on its own: adding a host does not add the Spaces it provides.
+
+```text output
+cua team add-machine [OPTIONS] <TEAM> <SPACE>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<TEAM>` | string | required | Team id, alias or name. |
+| `<SPACE>` | string | required | Space id or name (`relay:<id>` for a machine you host). |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-team-add-machine--yes"></span>`--yes` | boolean | `false` | Confirm without a prompt. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-team-add-machine"
+cua team add-machine AIGIS local:build-box
+cua team add-machine AIGIS relay:0123abcd4567ef89 --yes
+```
+
+### `cua team remove-machine`
+
+Take a machine off the team.
+
+```text output
+cua team remove-machine [OPTIONS] <TEAM> <MACHINE>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<TEAM>` | string | required | Team id, alias or name. |
+| `<MACHINE>` | string | required | The machine (`relay:<id>` or its id, as `cua team show` lists it). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-team-remove-machine"
+cua team remove-machine AIGIS relay:0123abcd4567ef89
+```
+
+### `cua team audit`
+
+The team's audit log. Audit export is coming soon; for now see the account app (app.cua.ai).
+
+```text output
+cua team audit [OPTIONS] <TEAM>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<TEAM>` | string | required | Team id, alias or name. |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-team-audit--limit"></span>`--limit` | integer | `50` | Newest events to show (when export arrives). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-team-audit"
+cua team audit AIGIS
+```
+
+### `cua team delete`
+
+Delete a team (owner; cancel its subscription first). Its machines stay yours.
+
+```text output
+cua team delete [OPTIONS] <TEAM>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<TEAM>` | string | required | Team id, alias or name. |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-team-delete--yes"></span>`--yes` | boolean | `false` | Do not ask for confirmation. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-team-delete"
+cua team delete AIGIS --yes
+```
+
+## `cua usage`
+
+Your relay allowance this month: live sessions, relay hours, and your plan. Spaces on your own network use none of it.
+
+```text output
+cua usage [OPTIONS]
+```
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-usage--relay"></span>`--relay` | string | | Relay URL (default $CUA_RELAY_URL, else the CUA_ENV relay, https://relay.cua.ai in production). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-usage"
+cua usage
+cua usage --json
+```
+
+## `cua spacesd`
+
+Talk to a cua-spacesd directly by URL.
+
+```text output
+cua spacesd [OPTIONS] <COMMAND>
+```
+
+### `cua spacesd caps`
+
+Print capabilities.
+
+```text output
+cua spacesd caps [OPTIONS] <URL>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<URL>` | string | required | spacesd URL (`http://host:port`). |
+
+| Flag | Type | Default | Env var | Description |
+| --- | --- | --- | --- | --- |
+| <span id="cua-spacesd-caps--token"></span>`--token` | string | | `CUA_ENV_TOKEN` | spacesd token. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-spacesd-caps"
+cua spacesd caps http://127.0.0.1:3211
+```
+
+### `cua spacesd exec`
+
+Run a command (argv, no shell).
+
+```text output
+cua spacesd exec [OPTIONS] <URL> <COMMAND>...
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<URL>` | string | required | spacesd URL (`http://host:port`). |
+| `<COMMAND>...` | string | required | Program and arguments. Repeatable. |
+
+| Flag | Type | Default | Env var | Description |
+| --- | --- | --- | --- | --- |
+| <span id="cua-spacesd-exec--token"></span>`--token` | string | | `CUA_ENV_TOKEN` | spacesd token. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-spacesd-exec"
+cua spacesd exec http://127.0.0.1:3211 uname -a
+```
+
+### `cua spacesd cp`
+
+Copy files: `cua spacesd cp <URL> local :remote` uploads, `cua spacesd cp <URL> :remote local` downloads.
+
+```text output
+cua spacesd cp [OPTIONS] <URL> <SRC> <DST>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<URL>` | string | required | spacesd URL (`http://host:port`). |
+| `<SRC>` | string | required | Source: a local path, or `:/guest/path`. |
+| `<DST>` | string | required | Destination: a local path, or `:/guest/path`. |
+
+| Flag | Type | Default | Env var | Description |
+| --- | --- | --- | --- | --- |
+| <span id="cua-spacesd-cp--token"></span>`--token` | string | | `CUA_ENV_TOKEN` | spacesd token. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-spacesd-cp"
+# Upload
+cua spacesd cp http://127.0.0.1:3211 ./notes.txt :/tmp/notes.txt
+
+# Download
+cua spacesd cp http://127.0.0.1:3211 :/tmp/notes.txt ./notes.txt
+```
+
+### `cua spacesd shell`
+
+Interactive shell (PTY).
+
+```text output
+cua spacesd shell [OPTIONS] <URL>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<URL>` | string | required | spacesd URL (`http://host:port`). |
+
+| Flag | Type | Default | Env var | Description |
+| --- | --- | --- | --- | --- |
+| <span id="cua-spacesd-shell--token"></span>`--token` | string | | `CUA_ENV_TOKEN` | spacesd token. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-spacesd-shell"
+cua spacesd shell http://127.0.0.1:3211
+```
+
+### `cua spacesd targets`
+
+List streamable targets (displays, and windows with --windows).
+
+```text output
+cua spacesd targets [OPTIONS] <URL>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<URL>` | string | required | spacesd URL (`http://host:port`). |
+
+| Flag | Type | Default | Env var | Description |
+| --- | --- | --- | --- | --- |
+| <span id="cua-spacesd-targets--token"></span>`--token` | string | | `CUA_ENV_TOKEN` | spacesd token. |
+| <span id="cua-spacesd-targets--windows"></span>`--windows` | boolean | `false` | | Include window targets. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-spacesd-targets"
+cua spacesd targets http://127.0.0.1:3211 --windows
+```
+
+### `cua spacesd call`
+
+Call any cua.env.v1 RPC with a proto3-JSON body.
+
+```text output
+cua spacesd call [OPTIONS] <URL> <METHOD> [BODY]
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<URL>` | string | required | spacesd URL (`http://host:port`). |
+| `<METHOD>` | string | required | `Service/Method`. |
+| `<BODY>` | string | `{}` | Request body (proto3 JSON). |
+
+| Flag | Type | Default | Env var | Description |
+| --- | --- | --- | --- | --- |
+| <span id="cua-spacesd-call--token"></span>`--token` | string | | `CUA_ENV_TOKEN` | spacesd token. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-spacesd-call"
+cua spacesd call http://127.0.0.1:3211 SystemService/GetCapabilities
+```
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| `0` | Success. |
+| `1` | Failure, or `cua do` reported an error. |
+| `2` | Invalid argument, or an ambiguous sandbox name (qualify it: `local:NAME`). |
+| `3` | Not found: sandbox, window, skill or image (or an image not published yet). |
+| `4` | Not supported, or not configured (for example no provider credentials). |
+| `5` | No cua-spacesd answered, or a transport failure. |
+| `6` | Unauthenticated or permission denied (by Cua or your cloud account). |
+| `7` | Not enough free disk space (see `cua cache`). |
+| `130` | Cancelled (Ctrl-C during a create): what it made was removed. |
diff --git a/docs/content/docs/cua-cli/reference/cli/spaces.mdx b/docs/content/docs/cua-cli/reference/cli/spaces.mdx
deleted file mode 100644
index 17eefac3a9..0000000000
--- a/docs/content/docs/cua-cli/reference/cli/spaces.mdx
+++ /dev/null
@@ -1,366 +0,0 @@
----
-title: "cua spaces"
-description: "Registered Spaces and your machines on the relay."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-cli
- Source: cua dump-docs --type cli
- Version: 0.5.0
-*/}
-
-| Command | Description |
-| --- | --- |
-| [`cua spaces ls`](#cua-spaces-ls) | Registered Spaces and your machines on the relay. |
-| [`cua spaces add`](#cua-spaces-add) | Register a Space after a capabilities handshake with its cua-spacesd (or, for another URL, an MCP initialize). |
-| [`cua spaces create`](#cua-spaces-create) | Create Spaces: on this machine, on one of your machines that provides Spaces (`cua host setup --provide-spaces` there), or in your own cloud account. |
-| [`cua spaces cancel`](#cua-spaces-cancel) | Cancel a create that is still running (here, in the daemon, or in another terminal): it stops and what it made is removed. |
-| [`cua spaces gpus`](#cua-spaces-gpus) | The GPU options each runtime offers on this machine (or in your own cloud account). |
-| [`cua spaces delete`](#cua-spaces-delete) | Delete a Space's sandbox (on this machine, on the machine that provides it, or in your own cloud account) and forget it (asks first). |
-| [`cua spaces stop`](#cua-spaces-stop) | Turn a Space off: a local container or QEMU VM is suspended (its memory is kept), a Lume VM or a Space one of your machines provides is stopped (its disk is kept), and so is a Space in your own cloud (`--on aws`, `gcp`; compute billing stops). |
-| [`cua spaces start`](#cua-spaces-start) | Turn a Space back on: resume a suspended one or boot a stopped one. |
-| [`cua spaces rm`](#cua-spaces-rm) | Forget a registered Space and its stored token. |
-| [`cua spaces share`](#cua-spaces-share) | Let another cua.ai account watch (viewer) or use (editor) a Space, through the relay. |
-| [`cua spaces unshare`](#cua-spaces-unshare) | Stop sharing a Space with one account at once, or with everyone. |
-| [`cua spaces shares`](#cua-spaces-shares) | Who a Space is shared with, and who of them is connected now. |
-| [`cua spaces relay-register`](#cua-spaces-relay-register) | Publish a Space on the relay for your other devices (a phone off this network): its own driver dials out, as `cua host setup` does for this computer. |
-| [`cua spaces relay-unregister`](#cua-spaces-relay-unregister) | Take a Space off the relay (every share with it ends). |
-
-Every command also accepts the [global options](/cua-cli/reference/cli#global-options).
-
-<span id="cua-spaces"></span>
-
-Spaces: registered ones and your machines on the relay.
-
-```text output
-cua spaces [OPTIONS] <COMMAND>
-```
-
-## `cua spaces ls`
-
-Registered Spaces and your machines on the relay.
-
-```text output
-cua spaces ls [OPTIONS]
-```
-
-Alias: `cua spaces list`.
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-spaces-ls--relay"></span>`--relay` | string | | Relay URL (default $CUA_RELAY_URL, else the CUA_ENV relay, https://relay.cua.ai in production). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-spaces-ls"
-cua spaces ls
-cua spaces ls --json
-```
-
-## `cua spaces add`
-
-Register a Space after a capabilities handshake with its cua-spacesd (or, for another URL, an MCP initialize). Re-adding an address updates it. The token is stored apart from the registry, 0600.
-
-```text output
-cua spaces add [OPTIONS] <URL>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<URL>` | string | required | The Space's cua-spacesd (`http(s)://host:port`, `host:port`, default port 3211), a Space id (`local:<name>`), or any MCP endpoint URL. |
-
-| Flag | Type | Default | Env var | Description |
-| --- | --- | --- | --- | --- |
-| <span id="cua-spaces-add--token"></span>`--token` | string | | `CUA_ENV_TOKEN` | spacesd token (or the bearer an MCP endpoint needs). |
-| <span id="cua-spaces-add--name"></span>`--name` | string | | | Display name (default: the guest's hostname). |
-| <span id="cua-spaces-add--service"></span>`--service` | string | | | For an MCP endpoint URL: the service name to register it under (default `mcp`). |
-| <span id="cua-spaces-add--host"></span>`--host` | boolean | `false` | | It is a machine that provides Spaces over its direct address (Tailscale or LAN): `--on host:<name>` finds it without the relay. Its token is stored like any direct Space's. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-spaces-add"
-cua spaces add 10.0.0.5:3211 --token "$TOKEN" --name studio
-cua spaces add local:my-sandbox
-cua spaces add http://127.0.0.1:8765/mcp --service tools
-
-# A machine that provides Spaces over Tailscale, without the relay (`cua host setup --direct ... --provide-spaces` on it prints this)
-cua spaces add 100.101.102.103:3211 --host --name "Mac mini (spare)" --token "$TOKEN"
-```
-
-## `cua spaces create`
-
-Create Spaces: on this machine, on one of your machines that provides Spaces (`cua host setup --provide-spaces` there), or in your own cloud account.
-
-```text output
-cua spaces create [OPTIONS] [IMAGE]
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<IMAGE>` | string | optional | Image: an alias (`linux`, `macos`, `macos:26`) or a registry reference. Default: the canonical Linux image. |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-spaces-create--on"></span>`--on` | string | | Where: `local`, `aws`, `gcp`, `host:<machine>`, or a machine name (`mac-mini`, "spare mac mini"). Default: your default location. |
-| <span id="cua-spaces-create--count"></span>`--count` | integer | `1` | How many (1 to 8). |
-| <span id="cua-spaces-create--name"></span>`--name` | string | | Name (with --count, `-2`, `-3`, ... are appended). |
-| <span id="cua-spaces-create--kind"></span>`--kind` | string | | auto \| container \| vm. |
-| <span id="cua-spaces-create--runtime"></span>`--runtime` | string | | auto, or an engine the location offers (lume, runc, gvisor, qemu). |
-| <span id="cua-spaces-create--cpus"></span>`--cpus` | integer | | vCPUs. |
-| <span id="cua-spaces-create--memory-mb"></span>`--memory-mb` | integer | | Memory in MiB. |
-| <span id="cua-spaces-create--disk-gb"></span>`--disk-gb` | integer | | Grow a VM's disk to this many GiB. |
-| <span id="cua-spaces-create--gpu"></span>`--gpu` | string | | A GPU: the runtime's own (`--gpu`), or an option `cua spaces gpus` lists. macOS VMs: GPU acceleration (experimental, Apple silicon; https://cua.ai/docs/lume/guides/gpu-passthrough). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-spaces-create"
-cua spaces create linux
-
-# Two macOS VMs on your spare Mac mini (matched by name)
-cua spaces create macos:26 --on "spare mac mini" --count 2
-cua spaces create --on host:0123abcd4567ef89 linux --json
-```
-
-## `cua spaces cancel`
-
-Cancel a create that is still running (here, in the daemon, or in another terminal): it stops and what it made is removed. Finished image downloads stay cached. Ctrl-C during `cua spaces create` does the same.
-
-```text output
-cua spaces cancel [OPTIONS] <SPACE>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<SPACE>` | string | required | The id the Space will have (`local:<name>`, printed when the create starts) or its name. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-spaces-cancel"
-cua spaces cancel local:space-1a2b3c
-cua spaces cancel studio
-```
-
-## `cua spaces gpus`
-
-The GPU options each runtime offers on this machine (or in your own cloud account).
-
-```text output
-cua spaces gpus [OPTIONS]
-```
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-spaces-gpus--on"></span>`--on` | string | | `local` (default), `aws`, `gcp` or `modal`. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-spaces-gpus"
-cua spaces gpus
-cua spaces gpus --json
-```
-
-## `cua spaces delete`
-
-Delete a Space's sandbox (on this machine, on the machine that provides it, or in your own cloud account) and forget it (asks first).
-
-```text output
-cua spaces delete [OPTIONS] <SPACE>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<SPACE>` | string | required | Space id or name. |
-
-| Flag | Short | Type | Default | Description |
-| --- | --- | --- | --- | --- |
-| <span id="cua-spaces-delete--force"></span>`--force` | `-f` | boolean | `false` | Skip the confirmation (required without a terminal). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-spaces-delete"
-cua spaces delete relay:space-0123456789abcdef
-cua spaces delete local:studio --force
-```
-
-## `cua spaces stop`
-
-Turn a Space off: a local container or QEMU VM is suspended (its memory is kept), a Lume VM or a Space one of your machines provides is stopped (its disk is kept), and so is a Space in your own cloud (`--on aws`, `gcp`; compute billing stops). Modal sandboxes and Spaces added by address cannot be turned off.
-
-```text output
-cua spaces stop [OPTIONS] <SPACE>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<SPACE>` | string | required | Space id or name. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-spaces-stop"
-cua spaces stop local:studio
-cua spaces stop relay:space-0123456789abcdef --json
-```
-
-## `cua spaces start`
-
-Turn a Space back on: resume a suspended one or boot a stopped one.
-
-```text output
-cua spaces start [OPTIONS] <SPACE>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<SPACE>` | string | required | Space id or name. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-spaces-start"
-cua spaces start local:studio
-cua spaces start studio --json
-```
-
-## `cua spaces rm`
-
-Forget a registered Space and its stored token. The sandbox keeps running. The `relay:<machine>` record of a Space that registered itself and is gone (not connected) also leaves your relay directory.
-
-```text output
-cua spaces rm [OPTIONS] <SPACE>
-```
-
-Alias: `cua spaces remove`.
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<SPACE>` | string | required | Space id, address or display name (as `cua spaces ls` shows). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-spaces-rm"
-cua spaces rm direct:10.0.0.5:3211
-cua spaces rm studio
-```
-
-## `cua spaces share`
-
-Let another cua.ai account watch (viewer) or use (editor) a Space, through the relay. They open it as `relay:<machine>`.
-
-```text output
-cua spaces share [OPTIONS] <SPACE> <WHO>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<SPACE>` | string | required | Space id, address or display name. |
-| `<WHO>` | string | required | Their email (verified by cua.ai) or account id. |
-
-| Flag | Short | Type | Default | Description |
-| --- | --- | --- | --- | --- |
-| <span id="cua-spaces-share--role"></span>`--role` | | `viewer` \| `editor` | `viewer` | `viewer`: presence and a view-only stream. `editor`: full use. |
-| <span id="cua-spaces-share--yes"></span>`--yes` | `-y` | boolean | `false` | Confirm without a terminal prompt. Without a daemon the share happens at once. A running daemon still asks with Touch ID or your password on this computer; without a terminal, `--yes` says someone will answer there (otherwise the command fails at once instead of waiting for a prompt nobody sees). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-spaces-share"
-cua spaces share local:studio [email protected]
-cua spaces share local:studio [email protected] --role editor
-cua spaces share relay:0123abcd4567ef89 acct-42 --role viewer
-
-# From a script or agent: confirm with Touch ID or your password here
-cua spaces share local:studio [email protected] --yes
-```
-
-## `cua spaces unshare`
-
-Stop sharing a Space with one account at once, or with everyone.
-
-```text output
-cua spaces unshare [OPTIONS] <SPACE> [WHO]
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<SPACE>` | string | required | Space id, address or display name. |
-| `<WHO>` | string | optional | Their email or account id. |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-spaces-unshare--all"></span>`--all` | boolean | `false` | Stop sharing with everyone (the Space leaves the relay). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-spaces-unshare"
-cua spaces unshare local:studio [email protected]
-cua spaces unshare local:studio --all
-```
-
-## `cua spaces shares`
-
-Who a Space is shared with, and who of them is connected now.
-
-```text output
-cua spaces shares [OPTIONS] <SPACE>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<SPACE>` | string | required | Space id, address or display name. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-spaces-shares"
-cua spaces shares local:studio
-cua spaces shares local:studio --json
-```
-
-## `cua spaces relay-register`
-
-Publish a Space on the relay for your other devices (a phone off this network): its own driver dials out, as `cua host setup` does for this computer. Nobody else gets in until you share it.
-
-```text output
-cua spaces relay-register [OPTIONS] <SPACE>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<SPACE>` | string | required | Space id, address or display name. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-spaces-relay-register"
-cua spaces relay-register local:studio
-```
-
-## `cua spaces relay-unregister`
-
-Take a Space off the relay (every share with it ends). With a `relay:<machine>` id, removes that machine's record from your relay directory: a Space that registered itself (also after it was deleted), or a machine of yours that is gone. Only its owner can.
-
-```text output
-cua spaces relay-unregister [OPTIONS] <SPACE>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<SPACE>` | string | required | Space id, address or display name. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-spaces-relay-unregister"
-cua spaces relay-unregister local:studio
-cua spaces relay-unregister relay:space-0123abcd4567ef89
-```
-
-## Exit codes
-
-| Code | Meaning |
-| --- | --- |
-| `0` | Success. |
-| `1` | Failure, or `cua do` reported an error. |
-| `2` | Invalid argument, or an ambiguous sandbox name (qualify it: `local:NAME`). |
-| `3` | Not found: sandbox, window, skill or image (or an image not published yet). |
-| `4` | Not supported, or not configured (for example no provider credentials). |
-| `5` | No cua-spacesd answered, or a transport failure. |
-| `6` | Unauthenticated or permission denied (by Cua or your cloud account). |
-| `7` | Not enough free disk space (see `cua cache`). |
-| `130` | Cancelled (Ctrl-C during a create): what it made was removed. |
diff --git a/docs/content/docs/cua-cli/reference/cli/spacesd.mdx b/docs/content/docs/cua-cli/reference/cli/spacesd.mdx
deleted file mode 100644
index b95bffca77..0000000000
--- a/docs/content/docs/cua-cli/reference/cli/spacesd.mdx
+++ /dev/null
@@ -1,186 +0,0 @@
----
-title: "cua spacesd"
-description: "Talk to a cua-spacesd directly by URL."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-cli
- Source: cua dump-docs --type cli
- Version: 0.5.0
-*/}
-
-| Command | Description |
-| --- | --- |
-| [`cua spacesd caps`](#cua-spacesd-caps) | Print capabilities. |
-| [`cua spacesd exec`](#cua-spacesd-exec) | Run a command (argv, no shell). |
-| [`cua spacesd cp`](#cua-spacesd-cp) | Copy files: `cua spacesd cp <URL> local :remote` uploads, `cua spacesd cp <URL> :remote local` downloads. |
-| [`cua spacesd shell`](#cua-spacesd-shell) | Interactive shell (PTY). |
-| [`cua spacesd targets`](#cua-spacesd-targets) | List streamable targets (displays, and windows with --windows). |
-| [`cua spacesd call`](#cua-spacesd-call) | Call any cua.env.v1 RPC with a proto3-JSON body. |
-
-Every command also accepts the [global options](/cua-cli/reference/cli#global-options).
-
-<span id="cua-spacesd"></span>
-
-Talk to a cua-spacesd directly by URL.
-
-```text output
-cua spacesd [OPTIONS] <COMMAND>
-```
-
-## `cua spacesd caps`
-
-Print capabilities.
-
-```text output
-cua spacesd caps [OPTIONS] <URL>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<URL>` | string | required | spacesd URL (`http://host:port`). |
-
-| Flag | Type | Default | Env var | Description |
-| --- | --- | --- | --- | --- |
-| <span id="cua-spacesd-caps--token"></span>`--token` | string | | `CUA_ENV_TOKEN` | spacesd token. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-spacesd-caps"
-cua spacesd caps http://127.0.0.1:3211
-```
-
-## `cua spacesd exec`
-
-Run a command (argv, no shell).
-
-```text output
-cua spacesd exec [OPTIONS] <URL> <COMMAND>...
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<URL>` | string | required | spacesd URL (`http://host:port`). |
-| `<COMMAND>...` | string | required | Program and arguments. Repeatable. |
-
-| Flag | Type | Default | Env var | Description |
-| --- | --- | --- | --- | --- |
-| <span id="cua-spacesd-exec--token"></span>`--token` | string | | `CUA_ENV_TOKEN` | spacesd token. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-spacesd-exec"
-cua spacesd exec http://127.0.0.1:3211 uname -a
-```
-
-## `cua spacesd cp`
-
-Copy files: `cua spacesd cp <URL> local :remote` uploads, `cua spacesd cp <URL> :remote local` downloads.
-
-```text output
-cua spacesd cp [OPTIONS] <URL> <SRC> <DST>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<URL>` | string | required | spacesd URL (`http://host:port`). |
-| `<SRC>` | string | required | Source: a local path, or `:/guest/path`. |
-| `<DST>` | string | required | Destination: a local path, or `:/guest/path`. |
-
-| Flag | Type | Default | Env var | Description |
-| --- | --- | --- | --- | --- |
-| <span id="cua-spacesd-cp--token"></span>`--token` | string | | `CUA_ENV_TOKEN` | spacesd token. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-spacesd-cp"
-# Upload
-cua spacesd cp http://127.0.0.1:3211 ./notes.txt :/tmp/notes.txt
-
-# Download
-cua spacesd cp http://127.0.0.1:3211 :/tmp/notes.txt ./notes.txt
-```
-
-## `cua spacesd shell`
-
-Interactive shell (PTY).
-
-```text output
-cua spacesd shell [OPTIONS] <URL>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<URL>` | string | required | spacesd URL (`http://host:port`). |
-
-| Flag | Type | Default | Env var | Description |
-| --- | --- | --- | --- | --- |
-| <span id="cua-spacesd-shell--token"></span>`--token` | string | | `CUA_ENV_TOKEN` | spacesd token. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-spacesd-shell"
-cua spacesd shell http://127.0.0.1:3211
-```
-
-## `cua spacesd targets`
-
-List streamable targets (displays, and windows with --windows).
-
-```text output
-cua spacesd targets [OPTIONS] <URL>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<URL>` | string | required | spacesd URL (`http://host:port`). |
-
-| Flag | Type | Default | Env var | Description |
-| --- | --- | --- | --- | --- |
-| <span id="cua-spacesd-targets--token"></span>`--token` | string | | `CUA_ENV_TOKEN` | spacesd token. |
-| <span id="cua-spacesd-targets--windows"></span>`--windows` | boolean | `false` | | Include window targets. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-spacesd-targets"
-cua spacesd targets http://127.0.0.1:3211 --windows
-```
-
-## `cua spacesd call`
-
-Call any cua.env.v1 RPC with a proto3-JSON body.
-
-```text output
-cua spacesd call [OPTIONS] <URL> <METHOD> [BODY]
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<URL>` | string | required | spacesd URL (`http://host:port`). |
-| `<METHOD>` | string | required | `Service/Method`. |
-| `<BODY>` | string | `{}` | Request body (proto3 JSON). |
-
-| Flag | Type | Default | Env var | Description |
-| --- | --- | --- | --- | --- |
-| <span id="cua-spacesd-call--token"></span>`--token` | string | | `CUA_ENV_TOKEN` | spacesd token. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-spacesd-call"
-cua spacesd call http://127.0.0.1:3211 SystemService/GetCapabilities
-```
-
-## Exit codes
-
-| Code | Meaning |
-| --- | --- |
-| `0` | Success. |
-| `1` | Failure, or `cua do` reported an error. |
-| `2` | Invalid argument, or an ambiguous sandbox name (qualify it: `local:NAME`). |
-| `3` | Not found: sandbox, window, skill or image (or an image not published yet). |
-| `4` | Not supported, or not configured (for example no provider credentials). |
-| `5` | No cua-spacesd answered, or a transport failure. |
-| `6` | Unauthenticated or permission denied (by Cua or your cloud account). |
-| `7` | Not enough free disk space (see `cua cache`). |
-| `130` | Cancelled (Ctrl-C during a create): what it made was removed. |
diff --git a/docs/content/docs/cua-cli/reference/cli/team.mdx b/docs/content/docs/cua-cli/reference/cli/team.mdx
deleted file mode 100644
index fc2d428e32..0000000000
--- a/docs/content/docs/cua-cli/reference/cli/team.mdx
+++ /dev/null
@@ -1,377 +0,0 @@
----
-title: "cua team"
-description: "Teams (organizations), their members, machines and device approvals."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-cli
- Source: cua dump-docs --type cli
- Version: 0.5.0
-*/}
-
-| Command | Description |
-| --- | --- |
-| [`cua team create`](#cua-team-create) | Create a team; you are its owner. |
-| [`cua team ls`](#cua-team-ls) | Your teams. |
-| [`cua team show`](#cua-team-show) | A team: plan, members, machines, open invites and devices. |
-| [`cua team invite`](#cua-team-invite) | Invite someone by email: cua.ai emails them an invitation. |
-| [`cua team join`](#cua-team-join) | After accepting an emailed invitation: take the role it offered. |
-| [`cua team leave`](#cua-team-leave) | Leave a team. |
-| [`cua team remove-member`](#cua-team-remove-member) | Remove a member (owner or admin; admins cannot remove admins). |
-| [`cua team set-role`](#cua-team-set-role) | Make a member an admin, or an admin a member (owner). |
-| [`cua team devices`](#cua-team-devices) | Member devices and whether they may open team machines. |
-| [`cua team approve`](#cua-team-approve) | Approve a member device so it can open team machines. |
-| [`cua team deny`](#cua-team-deny) | Decline a member device (it can no longer open team machines). |
-| [`cua team request`](#cua-team-request) | Ask the team's admins to approve this device. |
-| [`cua team add-machine`](#cua-team-add-machine) | Make a Space (or a machine you host) a team machine: every member and their agents see it and can open it. |
-| [`cua team remove-machine`](#cua-team-remove-machine) | Take a machine off the team. |
-| [`cua team audit`](#cua-team-audit) | The team's audit log. |
-| [`cua team delete`](#cua-team-delete) | Delete a team (owner; cancel its subscription first). |
-
-Every command also accepts the [global options](/cua-cli/reference/cli#global-options).
-
-<span id="cua-team"></span>
-
-Teams (organizations of your cua.ai account) share machines with every member and their agents. Owners and admins invite by email, approve member devices and add machines.
-
-```text output
-cua team [OPTIONS] <COMMAND>
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-team"
-cua team create AIGIS
-cua team invite AIGIS [email protected]
-cua team add-machine AIGIS local:build-box
-cua team approve AIGIS dev_0123456789abcdef01234567
-cua team show AIGIS
-```
-
-## `cua team create`
-
-Create a team; you are its owner. Buy Teams for it at app.cua.ai to add machines.
-
-```text output
-cua team create [OPTIONS] <NAME>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<NAME>` | string | required | Team name. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-team-create"
-cua team create "AIGIS"
-```
-
-## `cua team ls`
-
-Your teams.
-
-```text output
-cua team ls [OPTIONS]
-```
-
-Alias: `cua team list`.
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-team-ls"
-cua team ls
-cua team ls --json
-```
-
-## `cua team show`
-
-A team: plan, members, machines, open invites and devices.
-
-```text output
-cua team show [OPTIONS] <TEAM>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<TEAM>` | string | required | Team id, alias or name. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-team-show"
-cua team show AIGIS
-```
-
-## `cua team invite`
-
-Invite someone by email: cua.ai emails them an invitation. Manage invites at app.cua.ai/team.
-
-```text output
-cua team invite [OPTIONS] <TEAM> <EMAIL>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<TEAM>` | string | required | Team id, alias or name. |
-| `<EMAIL>` | string | required | Their email. |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-team-invite--role"></span>`--role` | `member` \| `admin` | `member` | `member` or `admin` (only the owner invites admins). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-team-invite"
-cua team invite AIGIS [email protected]
-cua team invite AIGIS [email protected] --role admin
-```
-
-## `cua team join`
-
-After accepting an emailed invitation: take the role it offered. Run `cua auth login` first so your session lists the team.
-
-```text output
-cua team join [OPTIONS] <TEAM>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<TEAM>` | string | required | Team id, alias or name. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-team-join"
-cua team join AIGIS
-```
-
-## `cua team leave`
-
-Leave a team.
-
-```text output
-cua team leave [OPTIONS] <TEAM>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<TEAM>` | string | required | Team id, alias or name. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-team-leave"
-cua team leave AIGIS
-```
-
-## `cua team remove-member`
-
-Remove a member (owner or admin; admins cannot remove admins).
-
-```text output
-cua team remove-member [OPTIONS] <TEAM> <WHO>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<TEAM>` | string | required | Team id, alias or name. |
-| `<WHO>` | string | required | Their email or account id. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-team-remove-member"
-cua team remove-member AIGIS [email protected]
-```
-
-## `cua team set-role`
-
-Make a member an admin, or an admin a member (owner).
-
-```text output
-cua team set-role [OPTIONS] <TEAM> <WHO> <ROLE>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<TEAM>` | string | required | Team id, alias or name. |
-| `<WHO>` | string | required | Their email or account id. |
-| `<ROLE>` | `member` \| `admin` | required | `member` or `admin`. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-team-set-role"
-cua team set-role AIGIS [email protected] admin
-```
-
-## `cua team devices`
-
-Member devices and whether they may open team machines.
-
-```text output
-cua team devices [OPTIONS] <TEAM>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<TEAM>` | string | required | Team id, alias or name. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-team-devices"
-cua team devices AIGIS
-```
-
-## `cua team approve`
-
-Approve a member device so it can open team machines.
-
-```text output
-cua team approve [OPTIONS] <TEAM> <DEVICE>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<TEAM>` | string | required | Team id, alias or name. |
-| `<DEVICE>` | string | required | Device id (`cua team devices`). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-team-approve"
-cua team approve AIGIS dev_0123456789abcdef01234567
-```
-
-## `cua team deny`
-
-Decline a member device (it can no longer open team machines).
-
-```text output
-cua team deny [OPTIONS] <TEAM> <DEVICE>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<TEAM>` | string | required | Team id, alias or name. |
-| `<DEVICE>` | string | required | Device id. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-team-deny"
-cua team deny AIGIS dev_0123456789abcdef01234567
-```
-
-## `cua team request`
-
-Ask the team's admins to approve this device.
-
-```text output
-cua team request [OPTIONS] <TEAM>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<TEAM>` | string | required | Team id, alias or name. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-team-request"
-cua team request AIGIS
-```
-
-## `cua team add-machine`
-
-Make a Space (or a machine you host) a team machine: every member and their agents see it and can open it. Macs, Linux and Windows machines all can. Each Space is added on its own: adding a host does not add the Spaces it provides.
-
-```text output
-cua team add-machine [OPTIONS] <TEAM> <SPACE>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<TEAM>` | string | required | Team id, alias or name. |
-| `<SPACE>` | string | required | Space id or name (`relay:<id>` for a machine you host). |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-team-add-machine--yes"></span>`--yes` | boolean | `false` | Confirm without a prompt. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-team-add-machine"
-cua team add-machine AIGIS local:build-box
-cua team add-machine AIGIS relay:0123abcd4567ef89 --yes
-```
-
-## `cua team remove-machine`
-
-Take a machine off the team.
-
-```text output
-cua team remove-machine [OPTIONS] <TEAM> <MACHINE>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<TEAM>` | string | required | Team id, alias or name. |
-| `<MACHINE>` | string | required | The machine (`relay:<id>` or its id, as `cua team show` lists it). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-team-remove-machine"
-cua team remove-machine AIGIS relay:0123abcd4567ef89
-```
-
-## `cua team audit`
-
-The team's audit log. Audit export is coming soon; for now see the account app (app.cua.ai).
-
-```text output
-cua team audit [OPTIONS] <TEAM>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<TEAM>` | string | required | Team id, alias or name. |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-team-audit--limit"></span>`--limit` | integer | `50` | Newest events to show (when export arrives). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-team-audit"
-cua team audit AIGIS
-```
-
-## `cua team delete`
-
-Delete a team (owner; cancel its subscription first). Its machines stay yours.
-
-```text output
-cua team delete [OPTIONS] <TEAM>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<TEAM>` | string | required | Team id, alias or name. |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-team-delete--yes"></span>`--yes` | boolean | `false` | Do not ask for confirmation. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-team-delete"
-cua team delete AIGIS --yes
-```
-
-## Exit codes
-
-| Code | Meaning |
-| --- | --- |
-| `0` | Success. |
-| `1` | Failure, or `cua do` reported an error. |
-| `2` | Invalid argument, or an ambiguous sandbox name (qualify it: `local:NAME`). |
-| `3` | Not found: sandbox, window, skill or image (or an image not published yet). |
-| `4` | Not supported, or not configured (for example no provider credentials). |
-| `5` | No cua-spacesd answered, or a transport failure. |
-| `6` | Unauthenticated or permission denied (by Cua or your cloud account). |
-| `7` | Not enough free disk space (see `cua cache`). |
-| `130` | Cancelled (Ctrl-C during a create): what it made was removed. |
diff --git a/docs/content/docs/cua-cli/reference/cli/telemetry.mdx b/docs/content/docs/cua-cli/reference/cli/telemetry.mdx
deleted file mode 100644
index 8437f8aedc..0000000000
--- a/docs/content/docs/cua-cli/reference/cli/telemetry.mdx
+++ /dev/null
@@ -1,142 +0,0 @@
----
-title: "cua telemetry"
-description: "Anonymous usage telemetry (status, off, show-last)."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-cli
- Source: cua dump-docs --type cli
- Version: 0.5.0
-*/}
-
-| Command | Description |
-| --- | --- |
-| [`cua telemetry status`](#cua-telemetry-status) | Whether telemetry is on, why, and the exact properties every event carries. |
-| [`cua telemetry on`](#cua-telemetry-on) | Turn usage telemetry on (writes [telemetry] enabled = \"on\" to ~/.cua/config.toml). |
-| [`cua telemetry off`](#cua-telemetry-off) | Turn usage telemetry off (same as `cua config set telemetry off`). |
-| [`cua telemetry show-last`](#cua-telemetry-show-last) | Print the last events this machine queued or sent, exactly as sent. |
-| [`cua telemetry reset-id`](#cua-telemetry-reset-id) | Delete the anonymous install id and salt (new ones are created on the next event). |
-| [`cua telemetry schema`](#cua-telemetry-schema) | Every event and property that may be sent, with its allowed values. |
-
-Every command also accepts the [global options](/cua-cli/reference/cli#global-options).
-
-<span id="cua-telemetry"></span>
-
-Anonymous usage telemetry (status, on, off, show-last, reset-id, schema). What is sent: https://cua.ai/docs/cua-sdk/concepts/telemetry.
-
-```text output
-cua telemetry [OPTIONS] <COMMAND>
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-telemetry"
-cua telemetry status
-cua telemetry off
-cua telemetry show-last
-```
-
-## `cua telemetry status`
-
-Whether telemetry is on, why, and the exact properties every event carries.
-
-```text output
-cua telemetry status [OPTIONS]
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-telemetry-status"
-cua telemetry status
-cua telemetry status --json
-```
-
-## `cua telemetry on`
-
-Turn usage telemetry on (writes [telemetry] enabled = \"on\" to ~/.cua/config.toml).
-
-```text output
-cua telemetry on [OPTIONS]
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-telemetry-on"
-cua telemetry on
-```
-
-## `cua telemetry off`
-
-Turn usage telemetry off (same as `cua config set telemetry off`).
-
-```text output
-cua telemetry off [OPTIONS]
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-telemetry-off"
-cua telemetry off
-```
-
-## `cua telemetry show-last`
-
-Print the last events this machine queued or sent, exactly as sent.
-
-```text output
-cua telemetry show-last [OPTIONS]
-```
-
-| Flag | Short | Type | Default | Description |
-| --- | --- | --- | --- | --- |
-| <span id="cua-telemetry-show-last--limit"></span>`--limit` | `-n` | integer | `20` | How many. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-telemetry-show-last"
-cua telemetry show-last
-cua telemetry show-last -n 5 --json
-```
-
-## `cua telemetry reset-id`
-
-Delete the anonymous install id and salt (new ones are created on the next event).
-
-```text output
-cua telemetry reset-id [OPTIONS]
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-telemetry-reset-id"
-cua telemetry reset-id
-```
-
-## `cua telemetry schema`
-
-Every event and property that may be sent, with its allowed values.
-
-```text output
-cua telemetry schema [OPTIONS]
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-telemetry-schema"
-cua telemetry schema --json
-```
-
-## Exit codes
-
-| Code | Meaning |
-| --- | --- |
-| `0` | Success. |
-| `1` | Failure, or `cua do` reported an error. |
-| `2` | Invalid argument, or an ambiguous sandbox name (qualify it: `local:NAME`). |
-| `3` | Not found: sandbox, window, skill or image (or an image not published yet). |
-| `4` | Not supported, or not configured (for example no provider credentials). |
-| `5` | No cua-spacesd answered, or a transport failure. |
-| `6` | Unauthenticated or permission denied (by Cua or your cloud account). |
-| `7` | Not enough free disk space (see `cua cache`). |
-| `130` | Cancelled (Ctrl-C during a create): what it made was removed. |
diff --git a/docs/content/docs/cua-cli/reference/cli/teleport.mdx b/docs/content/docs/cua-cli/reference/cli/teleport.mdx
deleted file mode 100644
index 1dcad4a040..0000000000
--- a/docs/content/docs/cua-cli/reference/cli/teleport.mdx
+++ /dev/null
@@ -1,109 +0,0 @@
----
-title: "cua teleport"
-description: "Move a desktop app session into a sandbox."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-cli
- Source: cua dump-docs --type cli
- Version: 0.5.0
-*/}
-
-| Command | Description |
-| --- | --- |
-| [`cua teleport providers`](#cua-teleport-providers) | List the apps this machine can teleport (JSON). |
-| [`cua teleport manifest`](#cua-teleport-manifest) | Describe what teleporting an app would move (JSON). |
-| [`cua teleport push`](#cua-teleport-push) | Teleport an app session into a sandbox. |
-
-Every command also accepts the [global options](/cua-cli/reference/cli#global-options).
-
-<span id="cua-teleport"></span>
-
-Move a desktop app session (tabs, profile, sign-in) into a sandbox.
-
-```text output
-cua teleport [OPTIONS] <COMMAND>
-```
-
-## `cua teleport providers`
-
-List the apps this machine can teleport (JSON).
-
-```text output
-cua teleport providers [OPTIONS]
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-teleport-providers"
-cua teleport providers
-```
-
-## `cua teleport manifest`
-
-Describe what teleporting an app would move (JSON).
-
-```text output
-cua teleport manifest [OPTIONS] --app <APP>
-```
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-teleport-manifest--app"></span>`--app` | string | required | App: a bundle id or app name ("com.google.Chrome", "Slack", "claude-code"). |
-| <span id="cua-teleport-manifest--scope"></span>`--scope` | string | `full` | `tabs` (open tabs and session state) or `full` (the whole profile). |
-| <span id="cua-teleport-manifest--profile"></span>`--profile` | string | | Chrome profile to capture: a name ("Profile 1") or a path. |
-| <span id="cua-teleport-manifest--display-name"></span>`--display-name` | string | | Display name for the app (UI only). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-teleport-manifest"
-cua teleport manifest --app com.google.Chrome --scope tabs
-```
-
-## `cua teleport push`
-
-Teleport an app session into a sandbox.
-
-```text output
-cua teleport push [OPTIONS] --app <APP>
-```
-
-| Flag | Short | Type | Default | Env var | Description |
-| --- | --- | --- | --- | --- | --- |
-| <span id="cua-teleport-push--app"></span>`--app` | | string | required | | App: a bundle id or app name ("com.google.Chrome", "Slack", "claude-code"). |
-| <span id="cua-teleport-push--scope"></span>`--scope` | | string | `full` | | `tabs` (open tabs and session state) or `full` (the whole profile). |
-| <span id="cua-teleport-push--profile"></span>`--profile` | | string | | | Chrome profile to capture: a name ("Profile 1") or a path. |
-| <span id="cua-teleport-push--display-name"></span>`--display-name` | | string | | | Display name for the app (UI only). |
-| <span id="cua-teleport-push--sandbox"></span>`--sandbox` | `-s` | string | | | Destination sandbox (name). |
-| <span id="cua-teleport-push--url"></span>`--url` | | string | | | Destination cua-spacesd URL instead of a sandbox. |
-| <span id="cua-teleport-push--token"></span>`--token` | | string | | `CUA_ENV_TOKEN` | Token for `--url`. |
-| <span id="cua-teleport-push--include"></span>`--include` | | string | | | Send exactly this manifest item (repeatable; see `manifest`). Default: the provider's default selection, which leaves credentials-heavy or bulky items (cookies, transcripts) out unless named here. |
-| <span id="cua-teleport-push--all"></span>`--all` | | boolean | `false` | | Send every item the scope offers. |
-| <span id="cua-teleport-push--no-launch"></span>`--no-launch` | | boolean | `false` | | Do not launch the app in the sandbox after importing. |
-| <span id="cua-teleport-push--progress"></span>`--progress` | | boolean | `false` | | Print `progress <sent> <total>` lines while uploading. |
-| <span id="cua-teleport-push--relay-plaintext-ack"></span>`--relay-plaintext-ack` | | boolean | `false` | | Send over a `relay:` destination even though this Space's image predates end-to-end sealing (S1): without this, such a send refuses before reading or uploading anything. Set it only after you understand that relay.cua.ai (or a self-hosted cua-relay) could read this delivery in the clear; local and direct destinations are unaffected either way. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-teleport-push"
-# Chrome's open tabs into the sandbox dev
-cua teleport push --app com.google.Chrome --scope tabs --sandbox dev
-
-# The whole Slack profile, every item
-cua teleport push --app Slack --sandbox dev --all
-```
-
-## Exit codes
-
-| Code | Meaning |
-| --- | --- |
-| `0` | Success. |
-| `1` | Failure, or `cua do` reported an error. |
-| `2` | Invalid argument, or an ambiguous sandbox name (qualify it: `local:NAME`). |
-| `3` | Not found: sandbox, window, skill or image (or an image not published yet). |
-| `4` | Not supported, or not configured (for example no provider credentials). |
-| `5` | No cua-spacesd answered, or a transport failure. |
-| `6` | Unauthenticated or permission denied (by Cua or your cloud account). |
-| `7` | Not enough free disk space (see `cua cache`). |
-| `130` | Cancelled (Ctrl-C during a create): what it made was removed. |
diff --git a/docs/content/docs/cua-cli/reference/cli/trajectory.mdx b/docs/content/docs/cua-cli/reference/cli/trajectory.mdx
deleted file mode 100644
index 0d2c0f804a..0000000000
--- a/docs/content/docs/cua-cli/reference/cli/trajectory.mdx
+++ /dev/null
@@ -1,124 +0,0 @@
----
-title: "cua trajectory"
-description: "Recorded `cua do` trajectories."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-cli
- Source: cua dump-docs --type cli
- Version: 0.5.0
-*/}
-
-| Command | Description |
-| --- | --- |
-| [`cua trajectory ls`](#cua-trajectory-ls) | List sessions. |
-| [`cua trajectory view`](#cua-trajectory-view) | Zip, serve on loopback and open the hosted viewer. |
-| [`cua trajectory stop`](#cua-trajectory-stop) | Stop the file server started by `view`. |
-| [`cua trajectory clean`](#cua-trajectory-clean) | Delete sessions. |
-
-Every command also accepts the [global options](/cua-cli/reference/cli#global-options).
-
-<span id="cua-trajectory"></span>
-
-Recorded `cua do` trajectories.
-
-```text output
-cua trajectory [OPTIONS] <COMMAND>
-```
-
-Alias: `cua traj`.
-
-## `cua trajectory ls`
-
-List sessions.
-
-```text output
-cua trajectory ls [OPTIONS] [MACHINE]
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<MACHINE>` | string | optional | Only sessions of this target (sandbox name or `host`). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-trajectory-ls"
-cua traj ls
-
-# Only the sessions recorded on the sandbox dev
-cua traj ls dev
-```
-
-## `cua trajectory view`
-
-Zip, serve on loopback and open the hosted viewer.
-
-```text output
-cua trajectory view [OPTIONS] [TARGET]
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<TARGET>` | string | optional | Session id or target name (default: the latest session). |
-
-| Flag | Short | Type | Default | Description |
-| --- | --- | --- | --- | --- |
-| <span id="cua-trajectory-view--port"></span>`--port` | `-p` | integer | `8089` | Loopback port of the file server. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-trajectory-view"
-# The latest session
-cua traj view
-cua traj view <session> --port 8090
-```
-
-## `cua trajectory stop`
-
-Stop the file server started by `view`.
-
-```text output
-cua trajectory stop [OPTIONS]
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-trajectory-stop"
-cua traj stop
-```
-
-## `cua trajectory clean`
-
-Delete sessions.
-
-```text output
-cua trajectory clean [OPTIONS]
-```
-
-| Flag | Short | Type | Default | Description |
-| --- | --- | --- | --- | --- |
-| <span id="cua-trajectory-clean--older-than"></span>`--older-than` | | integer | | Only sessions older than this many days. |
-| <span id="cua-trajectory-clean--machine"></span>`--machine` | | string | | Only sessions of this target. |
-| <span id="cua-trajectory-clean--yes"></span>`--yes` | `-y` | boolean | `false` | Do not ask for confirmation. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-trajectory-clean"
-# Sessions older than a week, without the prompt
-cua traj clean --older-than 7 --yes
-```
-
-## Exit codes
-
-| Code | Meaning |
-| --- | --- |
-| `0` | Success. |
-| `1` | Failure, or `cua do` reported an error. |
-| `2` | Invalid argument, or an ambiguous sandbox name (qualify it: `local:NAME`). |
-| `3` | Not found: sandbox, window, skill or image (or an image not published yet). |
-| `4` | Not supported, or not configured (for example no provider credentials). |
-| `5` | No cua-spacesd answered, or a transport failure. |
-| `6` | Unauthenticated or permission denied (by Cua or your cloud account). |
-| `7` | Not enough free disk space (see `cua cache`). |
-| `130` | Cancelled (Ctrl-C during a create): what it made was removed. |
diff --git a/docs/content/docs/cua-cli/reference/cli/usage.mdx b/docs/content/docs/cua-cli/reference/cli/usage.mdx
deleted file mode 100644
index 0d38dbd912..0000000000
--- a/docs/content/docs/cua-cli/reference/cli/usage.mdx
+++ /dev/null
@@ -1,46 +0,0 @@
----
-title: "cua usage"
-description: "Your hosted relay allowance this month: live sessions and relay hours."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-cli
- Source: cua dump-docs --type cli
- Version: 0.5.0
-*/}
-
-Every command also accepts the [global options](/cua-cli/reference/cli#global-options).
-
-<span id="cua-usage"></span>
-
-Your relay allowance this month: live sessions, relay hours, and your plan. Spaces on your own network use none of it.
-
-```text output
-cua usage [OPTIONS]
-```
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-usage--relay"></span>`--relay` | string | | Relay URL (default $CUA_RELAY_URL, else the CUA_ENV relay, https://relay.cua.ai in production). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-usage"
-cua usage
-cua usage --json
-```
-
-## Exit codes
-
-| Code | Meaning |
-| --- | --- |
-| `0` | Success. |
-| `1` | Failure, or `cua do` reported an error. |
-| `2` | Invalid argument, or an ambiguous sandbox name (qualify it: `local:NAME`). |
-| `3` | Not found: sandbox, window, skill or image (or an image not published yet). |
-| `4` | Not supported, or not configured (for example no provider credentials). |
-| `5` | No cua-spacesd answered, or a transport failure. |
-| `6` | Unauthenticated or permission denied (by Cua or your cloud account). |
-| `7` | Not enough free disk space (see `cua cache`). |
-| `130` | Cancelled (Ctrl-C during a create): what it made was removed. |
diff --git a/docs/content/docs/cua-cli/reference/cli/viewer.mdx b/docs/content/docs/cua-cli/reference/cli/viewer.mdx
deleted file mode 100644
index 593a7d9057..0000000000
--- a/docs/content/docs/cua-cli/reference/cli/viewer.mdx
+++ /dev/null
@@ -1,50 +0,0 @@
----
-title: "cua viewer"
-description: "One local browser page that lists every sandbox and opens its viewer."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-cli
- Source: cua dump-docs --type cli
- Version: 0.5.0
-*/}
-
-Every command also accepts the [global options](/cua-cli/reference/cli#global-options).
-
-<span id="cua-viewer"></span>
-
-Serve the HTML5 viewer for every sandbox on one loopback port.
-
-```text output
-cua viewer [OPTIONS]
-```
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-viewer--listen"></span>`--listen` | string | `127.0.0.1:0` | Address to listen on (loopback only). |
-| <span id="cua-viewer--no-open"></span>`--no-open` | boolean | `false` | Print the URL without opening a browser. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-viewer"
-# List your sandboxes in the browser and open any of them
-cua viewer
-
-# Fixed port, print the URL only
-cua viewer --listen 127.0.0.1:8211 --no-open
-```
-
-## Exit codes
-
-| Code | Meaning |
-| --- | --- |
-| `0` | Success. |
-| `1` | Failure, or `cua do` reported an error. |
-| `2` | Invalid argument, or an ambiguous sandbox name (qualify it: `local:NAME`). |
-| `3` | Not found: sandbox, window, skill or image (or an image not published yet). |
-| `4` | Not supported, or not configured (for example no provider credentials). |
-| `5` | No cua-spacesd answered, or a transport failure. |
-| `6` | Unauthenticated or permission denied (by Cua or your cloud account). |
-| `7` | Not enough free disk space (see `cua cache`). |
-| `130` | Cancelled (Ctrl-C during a create): what it made was removed. |
diff --git a/docs/content/docs/cua-cli/reference/cli/volume.mdx b/docs/content/docs/cua-cli/reference/cli/volume.mdx
deleted file mode 100644
index 1a519c82aa..0000000000
--- a/docs/content/docs/cua-cli/reference/cli/volume.mdx
+++ /dev/null
@@ -1,457 +0,0 @@
----
-title: "cua volume"
-description: "Cua Volume: files, versions, grants, access requests and audit of the volume every Space and agent shares."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-cli
- Source: cua dump-docs --type cli
- Version: 0.5.0
-*/}
-
-| Command | Description |
-| --- | --- |
-| [`cua volume ls`](#cua-volume-ls) | List a folder (default: the root). |
-| [`cua volume cat`](#cua-volume-cat) | Print a file (or one of its versions) to stdout. |
-| [`cua volume put`](#cua-volume-put) | Write a file from a local file, or from stdin with `-`. |
-| [`cua volume rm`](#cua-volume-rm) | Delete a file (its history stays). |
-| [`cua volume history`](#cua-volume-history) | A file's versions, newest first. |
-| [`cua volume restore`](#cua-volume-restore) | Make an old version current again (a new version). |
-| [`cua volume grant`](#cua-volume-grant) | Let an agent or a Space read (or, with --rw, write) a folder beyond its defaults. |
-| [`cua volume revoke`](#cua-volume-revoke) | Revoke a grant. |
-| [`cua volume grants`](#cua-volume-grants) | The grants (live ones; --all includes expired and revoked). |
-| [`cua volume requests`](#cua-volume-requests) | Access requests agents filed, waiting for you. |
-| [`cua volume approve`](#cua-volume-approve) | Turn a request into a grant. |
-| [`cua volume deny`](#cua-volume-deny) | Decline a request. |
-| [`cua volume audit`](#cua-volume-audit) | The audit log, newest first, and whether its hash chain verified. |
-| [`cua volume mount`](#cua-volume-mount) | Show the drive as a volume (Finder on macOS, FUSE on Linux). |
-| [`cua volume unmount`](#cua-volume-unmount) | Turn the volume off (files still uploading land first). |
-| [`cua volume status`](#cua-volume-status) | The volume, sync across devices, and the block cache. |
-| [`cua volume config`](#cua-volume-config) | Which store the drive uses (fs, s3). |
-| [`cua volume config show`](#cua-volume-config-show) | The backend and bucket settings in effect (never keys). |
-| [`cua volume config set`](#cua-volume-config-set) | Choose the backend. |
-| [`cua volume config set-keys`](#cua-volume-config-set-keys) | Save S3 keys in the credential store: the access key id and the secret, one per line on stdin. |
-
-Every command also accepts the [global options](/cua-cli/reference/cli#global-options).
-
-<span id="cua-volume"></span>
-
-Cua Volume: the versioned volume every Space and agent shares (public/, agents/&lt;agent&gt;/, spaces/&lt;space&gt;/), its grants and audit. (`cua volume` still works for one release.).
-
-```text output
-cua volume [OPTIONS] <COMMAND>
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-volume"
-cua volume ls agents/
-cua volume cat agents/ada/memory/MEMORY.md
-cua volume put public/rules.md ./rules.md
-cua volume grant agent:researcher agents/writer/outputs/
-cua volume audit
-```
-
-## `cua volume ls`
-
-List a folder (default: the root).
-
-```text output
-cua volume ls [OPTIONS] [PATH]
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<PATH>` | string | optional | |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-volume-ls--as"></span>`--as` | string | | View the drive as this persistent agent does (`agent:ada` or `ada`). |
-| <span id="cua-volume-ls--space"></span>`--space` | string | | With --as: the Space the agent is in (its `spaces/<space>/` folder). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-volume-ls"
-cua volume ls
-cua volume ls agents/ada/
-cua volume ls --as agent:ada --space local:work
-```
-
-## `cua volume cat`
-
-Print a file (or one of its versions) to stdout.
-
-```text output
-cua volume cat [OPTIONS] <PATH>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<PATH>` | string | required | |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-volume-cat--version"></span>`--version` | string | | |
-| <span id="cua-volume-cat--as"></span>`--as` | string | | View the drive as this persistent agent does (`agent:ada` or `ada`). |
-| <span id="cua-volume-cat--space"></span>`--space` | string | | With --as: the Space the agent is in (its `spaces/<space>/` folder). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-volume-cat"
-cua volume cat agents/ada/memory/MEMORY.md
-cua volume cat public/rules.md --version 0001790683200000-1a2b3c4d
-```
-
-## `cua volume put`
-
-Write a file from a local file, or from stdin with `-`.
-
-```text output
-cua volume put [OPTIONS] <PATH> <SOURCE>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<PATH>` | string | required | |
-| `<SOURCE>` | string | required | Local file, or `-` for stdin. |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-volume-put--if-etag"></span>`--if-etag` | string | | Write only if the current version has this etag. |
-| <span id="cua-volume-put--as"></span>`--as` | string | | View the drive as this persistent agent does (`agent:ada` or `ada`). |
-| <span id="cua-volume-put--space"></span>`--space` | string | | With --as: the Space the agent is in (its `spaces/<space>/` folder). |
-| <span id="cua-volume-put--create-only"></span>`--create-only` | boolean | `false` | Write only if nothing is at the path yet. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-volume-put"
-cua volume put public/rules.md ./rules.md
-cua volume put public/rules.md -
-cua volume put agents/ada/inbox/brief.md ./brief.md --create-only
-```
-
-## `cua volume rm`
-
-Delete a file (its history stays).
-
-```text output
-cua volume rm [OPTIONS] <PATH>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<PATH>` | string | required | |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-volume-rm--if-etag"></span>`--if-etag` | string | | |
-| <span id="cua-volume-rm--as"></span>`--as` | string | | View the drive as this persistent agent does (`agent:ada` or `ada`). |
-| <span id="cua-volume-rm--space"></span>`--space` | string | | With --as: the Space the agent is in (its `spaces/<space>/` folder). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-volume-rm"
-cua volume rm spaces/local-work/scratch.txt
-```
-
-## `cua volume history`
-
-A file's versions, newest first.
-
-```text output
-cua volume history [OPTIONS] <PATH>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<PATH>` | string | required | |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-volume-history--as"></span>`--as` | string | | View the drive as this persistent agent does (`agent:ada` or `ada`). |
-| <span id="cua-volume-history--space"></span>`--space` | string | | With --as: the Space the agent is in (its `spaces/<space>/` folder). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-volume-history"
-cua volume history agents/ada/memory/MEMORY.md
-```
-
-## `cua volume restore`
-
-Make an old version current again (a new version).
-
-```text output
-cua volume restore [OPTIONS] <PATH> <VERSION>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<PATH>` | string | required | |
-| `<VERSION>` | string | required | |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-volume-restore--as"></span>`--as` | string | | View the drive as this persistent agent does (`agent:ada` or `ada`). |
-| <span id="cua-volume-restore--space"></span>`--space` | string | | With --as: the Space the agent is in (its `spaces/<space>/` folder). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-volume-restore"
-cua volume restore agents/ada/memory/MEMORY.md 0001790683200000-1a2b3c4d
-```
-
-## `cua volume grant`
-
-Let an agent or a Space read (or, with --rw, write) a folder beyond its defaults. Asks for Touch ID or your passphrase.
-
-```text output
-cua volume grant [OPTIONS] <PRINCIPAL> <PREFIX>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<PRINCIPAL>` | string | required | `agent:<name>` or `space:<id>`. |
-| `<PREFIX>` | string | required | A folder (ending in /) or one file. |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-volume-grant--for"></span>`--for` | string | | Lifetime (`30m`, `2h`, `7d`). Default: until revoked. |
-| <span id="cua-volume-grant--note"></span>`--note` | string | | A note shown next to the grant. |
-| <span id="cua-volume-grant--rw"></span>`--rw` | boolean | `false` | Read and write (default: read only). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-volume-grant"
-cua volume grant agent:researcher agents/writer/outputs/
-cua volume grant space:local-build public/datasets/ --rw --for 2h
-```
-
-## `cua volume revoke`
-
-Revoke a grant.
-
-```text output
-cua volume revoke [OPTIONS] <GRANT_ID>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<GRANT_ID>` | string | required | |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-volume-revoke"
-cua volume revoke 5f2c9a0b1d3e4f67
-```
-
-## `cua volume grants`
-
-The grants (live ones; --all includes expired and revoked).
-
-```text output
-cua volume grants [OPTIONS]
-```
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-volume-grants--all"></span>`--all` | boolean | `false` | |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-volume-grants"
-cua volume grants
-```
-
-## `cua volume requests`
-
-Access requests agents filed, waiting for you.
-
-```text output
-cua volume requests [OPTIONS]
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-volume-requests"
-cua volume requests
-```
-
-## `cua volume approve`
-
-Turn a request into a grant. Asks for Touch ID or your passphrase.
-
-```text output
-cua volume approve [OPTIONS] <REQUEST_ID>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<REQUEST_ID>` | string | required | |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-volume-approve--for"></span>`--for` | string | | |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-volume-approve"
-cua volume approve 5f2c9a0b1d3e4f67
-cua volume approve 5f2c9a0b1d3e4f67 --for 1d
-```
-
-## `cua volume deny`
-
-Decline a request.
-
-```text output
-cua volume deny [OPTIONS] <REQUEST_ID>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<REQUEST_ID>` | string | required | |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-volume-deny"
-cua volume deny 5f2c9a0b1d3e4f67
-```
-
-## `cua volume audit`
-
-The audit log, newest first, and whether its hash chain verified.
-
-```text output
-cua volume audit [OPTIONS]
-```
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-volume-audit--limit"></span>`--limit` | integer | `50` | |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-volume-audit"
-cua volume audit
-cua volume audit --limit 200 --json
-```
-
-## `cua volume mount`
-
-Show the drive as a volume (Finder on macOS, FUSE on Linux). Off until turned on; stays on across restarts.
-
-```text output
-cua volume mount [OPTIONS]
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-volume-mount"
-cua volume mount
-cua volume mount --json
-```
-
-## `cua volume unmount`
-
-Turn the volume off (files still uploading land first).
-
-```text output
-cua volume unmount [OPTIONS]
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-volume-unmount"
-cua volume unmount
-```
-
-## `cua volume status`
-
-The volume, sync across devices, and the block cache.
-
-```text output
-cua volume status [OPTIONS]
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-volume-status"
-cua volume status
-cua volume status --json
-```
-
-## `cua volume config`
-
-Which store the drive uses (fs, s3).
-
-```text output
-cua volume config [OPTIONS] <COMMAND>
-```
-
-### `cua volume config show`
-
-The backend and bucket settings in effect (never keys).
-
-```text output
-cua volume config show [OPTIONS]
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-volume-config-show"
-cua volume config show
-```
-
-### `cua volume config set`
-
-Choose the backend. Keys are never arguments: see set-keys.
-
-```text output
-cua volume config set [OPTIONS] --backend <BACKEND>
-```
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-volume-config-set--backend"></span>`--backend` | string | required | `fs` (default) or `s3`. |
-| <span id="cua-volume-config-set--endpoint"></span>`--endpoint` | string | | |
-| <span id="cua-volume-config-set--region"></span>`--region` | string | | |
-| <span id="cua-volume-config-set--bucket"></span>`--bucket` | string | | |
-| <span id="cua-volume-config-set--root"></span>`--root` | string | | A key prefix every drive key lives under. |
-| <span id="cua-volume-config-set--path-style"></span>`--path-style` | boolean | `false` | |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-volume-config-set"
-cua volume config set --backend fs
-cua volume config set --backend s3 --endpoint http://127.0.0.1:9000 --bucket cua-volume --path-style
-```
-
-### `cua volume config set-keys`
-
-Save S3 keys in the credential store: the access key id and the secret, one per line on stdin.
-
-```text output
-cua volume config set-keys [OPTIONS]
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-volume-config-set-keys"
-cua volume config set-keys
-```
-
-## Exit codes
-
-| Code | Meaning |
-| --- | --- |
-| `0` | Success. |
-| `1` | Failure, or `cua do` reported an error. |
-| `2` | Invalid argument, or an ambiguous sandbox name (qualify it: `local:NAME`). |
-| `3` | Not found: sandbox, window, skill or image (or an image not published yet). |
-| `4` | Not supported, or not configured (for example no provider credentials). |
-| `5` | No cua-spacesd answered, or a transport failure. |
-| `6` | Unauthenticated or permission denied (by Cua or your cloud account). |
-| `7` | Not enough free disk space (see `cua cache`). |
-| `130` | Cancelled (Ctrl-C during a create): what it made was removed. |
diff --git a/docs/content/docs/cua-cli/reference/index.mdx b/docs/content/docs/cua-cli/reference/index.mdx
index 956c73c99d..c7ba794a7e 100644
--- a/docs/content/docs/cua-cli/reference/index.mdx
+++ b/docs/content/docs/cua-cli/reference/index.mdx
@@ -15,42 +15,15 @@ description: "Every cua command and every cua MCP tool, generated from the CLI d
| Command group | Description |
| --- | --- |
| [`cua`](/cua-cli/reference/cli) | Synopsis, global options, exit codes and every command. |
-| [`cua auth`](/cua-cli/reference/cli/auth) | Sign in and out, see who is signed in, and store sandbox provider keys. |
-| [`cua sandbox`](/cua-cli/reference/cli/sandbox) | Create, list, connect to, suspend and delete sandboxes, local or on your own machines. |
-| [Sandbox access](/cua-cli/reference/cli/sandbox-access) | Run commands, copy files, forward ports, take screenshots, reach the MCP and view a sandbox (`cua sandbox exec`, `cp`, `view`, ...). |
-| [`cua config`](/cua-cli/reference/cli/config) | User defaults: where sandboxes run (`default.on`), the default kind and runtime. |
-| [`cua viewer`](/cua-cli/reference/cli/viewer) | One local browser page that lists every sandbox and opens its viewer. |
-| [`cua do`](/cua-cli/reference/cli/do) | One-shot computer actions (screenshot, click, type, windows) against a selected target. |
-| [`cua image`](/cua-cli/reference/cli/image) | Pull, build and push OCI images; list the image catalog. |
-| [`cua mcp`](/cua-cli/reference/cli/mcp) | The stdio MCP server for AI assistants. |
-| [`cua agent`](/cua-cli/reference/cli/agent) | Run coding agents (Claude Code, Codex, Gemini CLI, ...) inside a sandbox and follow, continue or stop them. |
-| [`cua agents`](/cua-cli/reference/cli/agents) | Install cua skills and the cua MCP server into AI coding agents. |
-| [`cua skills`](/cua-cli/reference/cli/skills) | Record, list and replay demonstrations (skills). |
-| [`cua trajectory`](/cua-cli/reference/cli/trajectory) | Recorded `cua do` trajectories. |
-| [`cua spaces`](/cua-cli/reference/cli/spaces) | Registered Spaces and your machines on the relay. |
-| [`cua cloud`](/cua-cli/reference/cli/cloud) | Your own AWS, Google Cloud or Modal account as a place for sandboxes and Spaces: connect, test, status, sweep. |
-| [`cua host`](/cua-cli/reference/cli/host) | Set this machine up for unattended access. |
-| [`cua devices`](/cua-cli/reference/cli/devices) | Enroll this device on the relay, approve, rename and revoke devices, and read the access log. |
-| [`cua team`](/cua-cli/reference/cli/team) | Teams (organizations), their members, machines and device approvals. |
-| [`cua usage`](/cua-cli/reference/cli/usage) | Your hosted relay allowance this month: live sessions and relay hours. |
-| [`cua teleport`](/cua-cli/reference/cli/teleport) | Move a desktop app session into a sandbox. |
-| [`cua volume`](/cua-cli/reference/cli/volume) | Cua Volume: files, versions, grants, access requests and audit of the volume every Space and agent shares. |
-| [`cua keyvault`](/cua-cli/reference/cli/keyvault) | Set up, unlock and lock the Cua Keyvault, with the OS key store or a passphrase. |
-| [`cua spacesd`](/cua-cli/reference/cli/spacesd) | Talk to a cua-spacesd directly by URL. |
-| [`cua daemon`](/cua-cli/reference/cli/daemon) | Start, stop and inspect the cua daemon. |
-| [`cua cache`](/cua-cli/reference/cli/cache) | See and reclaim the disk used by images, sandboxes, builds and logs. |
-| [`cua runtime`](/cua-cli/reference/cli/runtime) | Inspect and provision local runtimes. |
-| [`cua doctor`](/cua-cli/reference/cli/doctor) | Check the host, an image and a sandbox guest, or eval parity between image variants. |
-| [`cua telemetry`](/cua-cli/reference/cli/telemetry) | Anonymous usage telemetry (status, off, show-last). |
+| [Spaces, computers and teams](/cua-cli/reference/cli/spaces-and-computers) | Your Spaces and machines, unattended access on this machine, devices, teams, your remote use this month, and a cua-spacesd by URL. |
+| [Files, teleport and keys](/cua-cli/reference/cli/files-teleport-and-keys) | Cua Volume files and sharing, moving an app session into a sandbox, and the Cua Keyvault. |
+| [Sandboxes and images](/cua-cli/reference/cli/sandboxes) | Create, reach and delete sandboxes; pull, build and push images; local runtimes, disk cleanup, your own cloud account and the sandbox viewer. |
+| [Computer actions](/cua-cli/reference/cli/computer-actions) | One-shot computer actions (screenshot, click, type, windows) against a selected target, and their recorded trajectories. |
+| [Agents, MCP and skills](/cua-cli/reference/cli/agents) | Run coding agents in a sandbox, set up your AI agents, the stdio MCP server, and recorded skills. |
+| [Account and setup](/cua-cli/reference/cli/account-and-setup) | Sign in and out, user defaults, the cua daemon, health checks and usage telemetry. |
## MCP tools
| Tools | Description |
| --- | --- |
-| [All tools](/cua-cli/reference/mcp-tools) | Every `cua mcp` tool with a one-line summary. |
-| [Spaces tools](/cua-cli/reference/mcp-tools/spaces) | The Spaces contract: register, claim and release Spaces, run commands, move files, stream, run agents and teleport. 86 tools. |
-| [Image tools](/cua-cli/reference/mcp-tools/images) | The sandbox image catalog: which images exist and which ship a browser. 1 tools. |
-| [Sandbox tools](/cua-cli/reference/mcp-tools/sandbox) | Create and manage sandboxes, local or on your own machines. 11 tools. |
-| [Teleport tools](/cua-cli/reference/mcp-tools/teleport) | Move a signed-in browser session, per site, into a sandbox through the Cua Keyvault, with consent. 1 tools. |
-| [Computer tools](/cua-cli/reference/mcp-tools/computer) | Screenshots, input, windows, files and shell on a sandbox desktop. 35 tools. |
-| [Skills tools](/cua-cli/reference/mcp-tools/skills) | List, read, record and delete skills (recorded demonstrations). 4 tools. |
+| [MCP tools](/cua-cli/reference/mcp-tools) | Every tool the cua MCP server exposes, with its permission and parameters. |
diff --git a/docs/content/docs/cua-cli/reference/mcp-tools.mdx b/docs/content/docs/cua-cli/reference/mcp-tools.mdx
new file mode 100644
index 0000000000..c5ece2fe79
--- /dev/null
+++ b/docs/content/docs/cua-cli/reference/mcp-tools.mdx
@@ -0,0 +1,1032 @@
+---
+title: "MCP tools"
+description: "Every tool the cua MCP server exposes, with its permission and parameters."
+---
+
+{/*
+ AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
+ Generated by: pnpm --dir docs docs:generate:cua-cli
+ Source: cua dump-docs --type mcp
+ Version: 0.5.0
+*/}
+
+`cua mcp` (and `cua daemon mcp`, the same server backed by the cua daemon) serves these tools over stdio. See [MCP server](/cua-cli/guides/mcp-server) for client setup.
+
+Contract version 0.7.0; MCP protocol revision 2025-06-18.
+
+## Spaces tools
+
+The Spaces contract: register, claim and release Spaces, run commands, move files, stream, run agents and teleport.
+
+These tools are the [Spaces contract](/spaces/reference), with the same names and schemas on every surface. Each links to its entry there (parameters, result, errors, providers, metering); `cua mcp` gates each one behind the permission `spaces:<tool>`.
+
+### Space lifecycle
+
+Full entries: [Space lifecycle](/spaces/reference/lifecycle).
+
+| Tool | Description |
+| --- | --- |
+| <span id="add_space"></span>[`add_space`](/spaces/reference/lifecycle#add_space) | Add an existing machine as a Space by address and token. |
+| <span id="remove_space"></span>[`remove_space`](/spaces/reference/lifecycle#remove_space) | Forget a registered Space without touching it. |
+| <span id="list_spaces"></span>[`list_spaces`](/spaces/reference/lifecycle#list_spaces) | List the Spaces this connection can see. |
+| <span id="create_space"></span>[`create_space`](/spaces/reference/lifecycle#create_space) | Create a Space: a new sandbox on this machine, on one of your machines, or in the cloud. |
+| <span id="delete_space"></span>[`delete_space`](/spaces/reference/lifecycle#delete_space) | Delete a Space's sandbox and forget it. |
+| <span id="stop_space"></span>[`stop_space`](/spaces/reference/lifecycle#stop_space) | Turn a Space off: suspend it (memory kept) or stop it (disk kept). |
+| <span id="start_space"></span>[`start_space`](/spaces/reference/lifecycle#start_space) | Turn a Space back on: resume or boot it. |
+
+### Commands and files
+
+Full entries: [Commands and files](/spaces/reference/commands-and-files).
+
+| Tool | Description |
+| --- | --- |
+| <span id="space_bash"></span>[`space_bash`](/spaces/reference/commands-and-files#space_bash) | Run a shell command inside the Space. |
+| <span id="space_write"></span>[`space_write`](/spaces/reference/commands-and-files#space_write) | Write literal text to a path inside the Space. |
+| <span id="upload"></span>[`upload`](/spaces/reference/commands-and-files#upload) | Send a local file or folder into the Space. |
+| <span id="send_file"></span>[`send_file`](/spaces/reference/commands-and-files#send_file) | Send a host file or folder into the Space's Downloads, verified by sha256 on arrival. |
+| <span id="download"></span>[`download`](/spaces/reference/commands-and-files#download) | Fetch a file or folder out of the Space. |
+
+### Streams and display
+
+Full entries: [Streams and display](/spaces/reference/streams-and-display).
+
+| Tool | Description |
+| --- | --- |
+| <span id="stream_endpoint"></span>[`stream_endpoint`](/spaces/reference/streams-and-display#stream_endpoint) | Return a ticketed media endpoint for the Space's desktop or one window. |
+| <span id="list_space_windows"></span>[`list_space_windows`](/spaces/reference/streams-and-display#list_space_windows) | List the windows open inside the Space. |
+| <span id="stream_space_window"></span>[`stream_space_window`](/spaces/reference/streams-and-display#stream_space_window) | Draw one Space window on the operator's desktop. |
+| <span id="show_space_pip"></span>[`show_space_pip`](/spaces/reference/streams-and-display#show_space_pip) | Pin the Space as picture-in-picture on the operator's desktop. |
+| <span id="hide_space_pip"></span>[`hide_space_pip`](/spaces/reference/streams-and-display#hide_space_pip) | Unpin the picture-in-picture window. |
+| <span id="open_space_viewer"></span>[`open_space_viewer`](/spaces/reference/streams-and-display#open_space_viewer) | Open the full Space viewer on the operator's desktop. |
+
+### Services
+
+Full entries: [Services](/spaces/reference/services).
+
+| Tool | Description |
+| --- | --- |
+| <span id="list_tools"></span>[`list_tools`](/spaces/reference/services#list_tools) | List the MCP services and tools reachable inside the Space. |
+| <span id="call_tool"></span>[`call_tool`](/spaces/reference/services#call_tool) | Call a service tool inside the Space. |
+
+### Agents
+
+Full entries: [Agents](/spaces/reference/agents).
+
+| Tool | Description |
+| --- | --- |
+| <span id="agent_start"></span>[`agent_start`](/spaces/reference/agents#agent_start) | Start a coding agent in the Space. |
+| <span id="agent_message"></span>[`agent_message`](/spaces/reference/agents#agent_message) | Send a follow-up to an agent run. |
+| <span id="agent_events"></span>[`agent_events`](/spaces/reference/agents#agent_events) | Read an agent run's events after a cursor. |
+| <span id="agent_status"></span>[`agent_status`](/spaces/reference/agents#agent_status) | Read an agent run's status and result. |
+| <span id="agent_interrupt"></span>[`agent_interrupt`](/spaces/reference/agents#agent_interrupt) | Interrupt an agent run's current turn. |
+| <span id="agent_stop"></span>[`agent_stop`](/spaces/reference/agents#agent_stop) | Stop an agent run. |
+| <span id="agent_list"></span>[`agent_list`](/spaces/reference/agents#agent_list) | List agent runs in the Space. |
+| <span id="agent_capabilities"></span>[`agent_capabilities`](/spaces/reference/agents#agent_capabilities) | Report what the agent harnesses support. |
+
+### Persistent agents
+
+Full entries: [Persistent agents](/spaces/reference/persistent-agents).
+
+| Tool | Description |
+| --- | --- |
+| <span id="persistent_agent_create"></span>[`persistent_agent_create`](/spaces/reference/persistent-agents#persistent_agent_create) | Create a named agent whose memory outlives its Space. |
+| <span id="persistent_agent_list"></span>[`persistent_agent_list`](/spaces/reference/persistent-agents#persistent_agent_list) | List persistent agents. |
+| <span id="persistent_agent_remove"></span>[`persistent_agent_remove`](/spaces/reference/persistent-agents#persistent_agent_remove) | Forget a persistent agent. |
+| <span id="persistent_agent_send"></span>[`persistent_agent_send`](/spaces/reference/persistent-agents#persistent_agent_send) | Give a persistent agent a turn. |
+| <span id="persistent_agent_save"></span>[`persistent_agent_save`](/spaces/reference/persistent-agents#persistent_agent_save) | Save a persistent agent's home now. |
+| <span id="agent_pause"></span>[`agent_pause`](/spaces/reference/persistent-agents#agent_pause) | Pause a persistent agent: its run, its routines and its Space. |
+| <span id="agent_resume"></span>[`agent_resume`](/spaces/reference/persistent-agents#agent_resume) | Resume a paused persistent agent. |
+| <span id="routine_add"></span>[`routine_add`](/spaces/reference/persistent-agents#routine_add) | Schedule a recurring turn for a persistent agent. |
+| <span id="routine_list"></span>[`routine_list`](/spaces/reference/persistent-agents#routine_list) | List routines. |
+| <span id="routine_remove"></span>[`routine_remove`](/spaces/reference/persistent-agents#routine_remove) | Delete a routine. |
+| <span id="routine_set_enabled"></span>[`routine_set_enabled`](/spaces/reference/persistent-agents#routine_set_enabled) | Turn a routine on or off. |
+| <span id="notify_user"></span>[`notify_user`](/spaces/reference/persistent-agents#notify_user) | Tell the user something in the Cua app. |
+| <span id="notifications_list"></span>[`notifications_list`](/spaces/reference/persistent-agents#notifications_list) | Read the notifications feed. |
+| <span id="notifications_ack"></span>[`notifications_ack`](/spaces/reference/persistent-agents#notifications_ack) | Mark notifications read. |
+| <span id="computer_access_grant"></span>[`computer_access_grant`](/spaces/reference/persistent-agents#computer_access_grant) | Let a persistent agent use one of the user's computers. |
+| <span id="computer_access_revoke"></span>[`computer_access_revoke`](/spaces/reference/persistent-agents#computer_access_revoke) | Take back a persistent agent's access to a computer. |
+| <span id="computer_access_list"></span>[`computer_access_list`](/spaces/reference/persistent-agents#computer_access_list) | List per-agent computer access. |
+
+### Session teleport
+
+Full entries: [Session teleport](/spaces/reference/teleport).
+
+| Tool | Description |
+| --- | --- |
+| <span id="teleport_manifest"></span>[`teleport_manifest`](/spaces/reference/teleport#teleport_manifest) | Describe what a session teleport would move. |
+| <span id="teleport_app"></span>[`teleport_app`](/spaces/reference/teleport#teleport_app) | Move an app session into the Space. |
+
+### Keyvault
+
+Full entries: [Keyvault](/spaces/reference/keyvault).
+
+| Tool | Description |
+| --- | --- |
+| <span id="request_site_login"></span>[`request_site_login`](/spaces/reference/keyvault#request_site_login) | Sign in to a site in the Space with the user's saved password. |
+
+### Hotspot
+
+Full entries: [Hotspot](/spaces/reference/hotspot).
+
+| Tool | Description |
+| --- | --- |
+| <span id="hotspot_start"></span>[`hotspot_start`](/spaces/reference/hotspot#hotspot_start) | Start sharing this machine's network with a Space. |
+| <span id="hotspot_stop"></span>[`hotspot_stop`](/spaces/reference/hotspot#hotspot_stop) | Stop sharing this machine's network. |
+| <span id="hotspot_status"></span>[`hotspot_status`](/spaces/reference/hotspot#hotspot_status) | Report which Spaces are sharing this machine's network, with counters. |
+
+### Cua Volume
+
+Full entries: [Cua Volume](/spaces/reference/volume).
+
+| Tool | Description |
+| --- | --- |
+| <span id="volume_ls"></span>[`volume_ls`](/spaces/reference/volume#volume_ls) | List a folder of the Cua Volume. |
+| <span id="volume_read"></span>[`volume_read`](/spaces/reference/volume#volume_read) | Read a file from the Cua Volume. |
+| <span id="volume_write"></span>[`volume_write`](/spaces/reference/volume#volume_write) | Write a file to the Cua Volume. |
+| <span id="volume_delete"></span>[`volume_delete`](/spaces/reference/volume#volume_delete) | Delete a file from the Cua Volume. |
+| <span id="volume_history"></span>[`volume_history`](/spaces/reference/volume#volume_history) | List a Cua Volume file's versions. |
+| <span id="volume_restore"></span>[`volume_restore`](/spaces/reference/volume#volume_restore) | Restore an old version of a Cua Volume file. |
+| <span id="volume_grant"></span>[`volume_grant`](/spaces/reference/volume#volume_grant) | Grant an agent or Space more Cua Volume access. |
+| <span id="volume_revoke"></span>[`volume_revoke`](/spaces/reference/volume#volume_revoke) | Revoke a Cua Volume grant. |
+| <span id="volume_grants"></span>[`volume_grants`](/spaces/reference/volume#volume_grants) | List Cua Volume grants. |
+| <span id="volume_request_access"></span>[`volume_request_access`](/spaces/reference/volume#volume_request_access) | Ask the user for more Cua Volume access. |
+| <span id="volume_requests"></span>[`volume_requests`](/spaces/reference/volume#volume_requests) | List Cua Volume access requests waiting for the user. |
+| <span id="volume_approve"></span>[`volume_approve`](/spaces/reference/volume#volume_approve) | Approve a Cua Volume access request. |
+| <span id="volume_deny"></span>[`volume_deny`](/spaces/reference/volume#volume_deny) | Decline a Cua Volume access request. |
+| <span id="volume_audit"></span>[`volume_audit`](/spaces/reference/volume#volume_audit) | Read the Cua Volume audit log. |
+| <span id="volume_storage"></span>[`volume_storage`](/spaces/reference/volume#volume_storage) | Show where the Cua Volume keeps its bytes. |
+| <span id="volume_storage_set"></span>[`volume_storage_set`](/spaces/reference/volume#volume_storage_set) | Test or change where the Cua Volume keeps its bytes. |
+| <span id="volume_mount_status"></span>[`volume_mount_status`](/spaces/reference/volume#volume_mount_status) | Show whether the Cua Volume is mounted as a volume. |
+| <span id="volume_mount"></span>[`volume_mount`](/spaces/reference/volume#volume_mount) | Mount the Cua Volume as a volume. |
+| <span id="volume_unmount"></span>[`volume_unmount`](/spaces/reference/volume#volume_unmount) | Unmount the Cua Volume volume. |
+| <span id="volume_sync_status"></span>[`volume_sync_status`](/spaces/reference/volume#volume_sync_status) | Show the Cua Volume's sync state across devices. |
+| <span id="volume_sync_events"></span>[`volume_sync_events`](/spaces/reference/volume#volume_sync_events) | Wait for Cua Volume sync events. |
+| <span id="volume_sync_resolve"></span>[`volume_sync_resolve`](/spaces/reference/volume#volume_sync_resolve) | Mark a Cua Volume sync conflict as seen. |
+| <span id="volume_cache_stats"></span>[`volume_cache_stats`](/spaces/reference/volume#volume_cache_stats) | Show the Cua Volume block cache. |
+| <span id="volume_cache_set"></span>[`volume_cache_set`](/spaces/reference/volume#volume_cache_set) | Set the Cua Volume block cache's size cap. |
+| <span id="volume_cache_clear"></span>[`volume_cache_clear`](/spaces/reference/volume#volume_cache_clear) | Clear the Cua Volume block cache. |
+
+### Sharing
+
+Full entries: [Sharing](/spaces/reference/sharing).
+
+| Tool | Description |
+| --- | --- |
+| <span id="share_space"></span>[`share_space`](/spaces/reference/sharing#share_space) | Let another cua.ai account watch or edit a Space. |
+| <span id="unshare_space"></span>[`unshare_space`](/spaces/reference/sharing#unshare_space) | Stop sharing a Space with an account, or with everyone. |
+| <span id="space_shares"></span>[`space_shares`](/spaces/reference/sharing#space_shares) | List who a Space is shared with. |
+| <span id="relay_register_space"></span>[`relay_register_space`](/spaces/reference/sharing#relay_register_space) | Publish a Space on the relay for the account's other devices. |
+| <span id="relay_unregister_space"></span>[`relay_unregister_space`](/spaces/reference/sharing#relay_unregister_space) | Take a Space off the relay. |
+
+### Your cloud
+
+Full entries: [Your cloud](/spaces/reference/cloud).
+
+| Tool | Description |
+| --- | --- |
+| <span id="cloud_status"></span>[`cloud_status`](/spaces/reference/cloud#cloud_status) | List your clouds (AWS, Google Cloud, Modal): found credentials, the connected account and region, what each can run at what hourly cost, and what Cua created there. |
+| <span id="cloud_connect"></span>[`cloud_connect`](/spaces/reference/cloud#cloud_connect) | Connect a cloud account Spaces can be created in. |
+| <span id="cloud_test"></span>[`cloud_test`](/spaces/reference/cloud#cloud_test) | Check a cloud account without creating anything. |
+| <span id="cloud_disconnect"></span>[`cloud_disconnect`](/spaces/reference/cloud#cloud_disconnect) | Forget a connected cloud account. |
+| <span id="cloud_sweep"></span>[`cloud_sweep`](/spaces/reference/cloud#cloud_sweep) | Find and delete what Cua left in your clouds. |
+
+## Image tools
+
+### `images_list`
+
+List the sandbox image catalog (the images the docs list): ref, OS, container or VM, local runtime, whether it ships cua-spacesd and which browsers, its other variants, and the command that creates it. browser_tools=true means the in-sandbox cua-driver browser tools can drive its browser. Call this first to choose an image.
+
+Permission: `images:list`.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="images_list--all"></span>`all` | `boolean` | | Include unpublished entries (benchmark images). |
+| <span id="images_list--browser"></span>`browser` | `boolean` | | Only images whose browser the cua-driver browser tools drive. |
+| <span id="images_list--os"></span>`os` | `string` | | Only this OS: linux, windows or macos. |
+
+## Sandbox tools
+
+### `sandbox_list`
+
+List sandboxes: local and direct ones by default, each row with location (local or direct). Pass location to list only one kind.
+
+Permission: `sandbox:list`.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="sandbox_list--location"></span>`location` | `"local" \| "direct"` | | Only sandboxes in this location: local or direct (default: all). |
+
+### `sandbox_create`
+
+Create a sandbox from any image. `on` says where (local, the default unless the user configured another with `cua config set default.on`), `kind` what (auto, container, vm) and `runtime` which engine (auto, or gvisor, runc, qemu, lume); an impossible combination fails and lists the valid values. To browse the web, pass browser=true (and optionally url): it starts the canonical Linux image, registers it as a Space, launches Chromium with a throwaway profile inside it and returns the space, session, target_id and tab_id to pass to call_tool with the in-sandbox browser tools (browser_navigate, get_browser_state, browser_click, browser_type). Pass command, env and services to run a server in it, for example an MCP server: services &#123;"mcp": 8765&#125;. Without browser=true it does not register a Space: to reach its MCP server with list_tools/call_tool (service="mcp"), use create_space instead (same arguments), or add this one with add_space (address local:&lt;name&gt;).
+
+Permission: `sandbox:create`.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="sandbox_create--browser"></span>`browser` | `boolean` | | Start a browser in it, ready for the cua-driver browser tools (default image: the canonical Linux image). |
+| <span id="sandbox_create--command"></span>`command` | `string[]` | | Entrypoint override (argv), for example ["python", "-m", "my_mcp"]. |
+| <span id="sandbox_create--env"></span>`env` | `object` | | Environment variables (string values). |
+| <span id="sandbox_create--image"></span>`image` | `string` | | Image reference, any registry (overrides os_type). |
+| <span id="sandbox_create--kind"></span>`kind` | `"auto" \| "container" \| "vm"` | | What kind of machine: auto (default; from the image), container or vm. |
+| <span id="sandbox_create--name"></span>`name` | `string` | | Sandbox name. |
+| <span id="sandbox_create--on"></span>`on` | `string` | | Where it runs: local (default: the user's default location, else local). |
+| <span id="sandbox_create--os_type"></span>`os_type` | `string` | | linux (default) or macos. |
+| <span id="sandbox_create--runtime"></span>`runtime` | `string` | | Which engine: auto (default) or one the location offers for the kind (gvisor, runc, qemu, lume). |
+| <span id="sandbox_create--services"></span>`services` | `object` | | Named services: name to guest port, for example &#123;"mcp": 8765&#125;; each is probed for readiness. |
+| <span id="sandbox_create--url"></span>`url` | `string` | | With browser=true: open this URL first. |
+
+### `sandbox_get`
+
+Get details for a sandbox.
+
+Permission: `sandbox:get`.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="sandbox_get--name"></span>`name` | `string` | required | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations. |
+
+**Example arguments**
+
+```json
+{"name":"<name>"}
+```
+
+### `sandbox_start`
+
+Start (resume) a sandbox.
+
+Permission: `sandbox:start`.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="sandbox_start--name"></span>`name` | `string` | required | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations. |
+
+**Example arguments**
+
+```json
+{"name":"<name>"}
+```
+
+### `sandbox_stop`
+
+Stop (suspend) a sandbox.
+
+Permission: `sandbox:stop`.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="sandbox_stop--name"></span>`name` | `string` | required | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations. |
+
+**Example arguments**
+
+```json
+{"name":"<name>"}
+```
+
+### `sandbox_restart`
+
+Restart a sandbox.
+
+Permission: `sandbox:restart`.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="sandbox_restart--name"></span>`name` | `string` | required | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations. |
+
+**Example arguments**
+
+```json
+{"name":"<name>"}
+```
+
+### `sandbox_suspend`
+
+Suspend a sandbox.
+
+Permission: `sandbox:suspend`.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="sandbox_suspend--name"></span>`name` | `string` | required | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations. |
+
+**Example arguments**
+
+```json
+{"name":"<name>"}
+```
+
+### `sandbox_delete`
+
+Delete a sandbox.
+
+Permission: `sandbox:delete`.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="sandbox_delete--name"></span>`name` | `string` | required | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations. |
+
+**Example arguments**
+
+```json
+{"name":"<name>"}
+```
+
+### `sandbox_view`
+
+Get a browser link to the sandbox desktop in the cua-spacesd HTML5 viewer (video, audio, input, clipboard, files). The link expires after an hour.
+
+Permission: `sandbox:view`.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="sandbox_view--name"></span>`name` | `string` | required | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations. |
+
+**Example arguments**
+
+```json
+{"name":"<name>"}
+```
+
+### `sandbox_vnc`
+
+Deprecated: use sandbox_view. Returns the same viewer link.
+
+Permission: `sandbox:view`.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="sandbox_vnc--name"></span>`name` | `string` | required | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations. |
+
+**Example arguments**
+
+```json
+{"name":"<name>"}
+```
+
+### `sandbox_open_browser`
+
+Launch Chromium with a fresh throwaway profile inside an existing sandbox (an image with cua-spacesd and Chromium, see images_list), bind it and optionally open a URL. Returns the space, session, target_id and tab_id for call_tool with the in-sandbox browser tools. sandbox_create with browser=true already does this.
+
+Permission: `sandbox:browser`.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="sandbox_open_browser--name"></span>`name` | `string` | required | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations. |
+| <span id="sandbox_open_browser--session"></span>`session` | `string` | | cua-driver session label to use on every later browser call (default: browse). |
+| <span id="sandbox_open_browser--url"></span>`url` | `string` | | Open this URL first. |
+
+**Example arguments**
+
+```json
+{"name":"<name>"}
+```
+
+## Teleport tools
+
+### `teleport_browser_session`
+
+Teleport the user's signed-in session for specific sites (for example github.com) from their Firefox or Chrome into a sandbox, through the Cua Keyvault. Name each site: nothing is selected by default and there is no all-sessions option. The first call moves nothing: it files a Keyvault request and returns consent_required, a summary and a request_id. Show the summary to the user; they approve it in Cua (Touch ID or password). Then call again with the request_id to move exactly those sites. Use it only when the user asks to browse as themselves.
+
+Permission: `teleport:browser`.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="teleport_browser_session--browser"></span>`browser` | `"firefox" \| "chrome"` | required | firefox or chrome (chromium, brave and edge profiles use chrome). |
+| <span id="teleport_browser_session--duration_minutes"></span>`duration_minutes` | `integer` | | How long the sandbox may keep them (default 15, at most 1440). |
+| <span id="teleport_browser_session--name"></span>`name` | `string` | required | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations. |
+| <span id="teleport_browser_session--reason"></span>`reason` | `string` | | Why, in a few words; shown to the user as unverified. |
+| <span id="teleport_browser_session--request_id"></span>`request_id` | `string` | | The request_id from the first call, after the user approved it in Cua. |
+| <span id="teleport_browser_session--sites"></span>`sites` | `string[]` | required | The exact sites to teleport, for example ["github.com"]. |
+
+**Example arguments**
+
+```json
+{"name":"<name>","browser":"firefox","sites":["<site>"]}
+```
+
+## Computer tools
+
+Computer tools act on a sandbox desktop through its cua-spacesd. Coordinates are in the pixel space of the last `computer_screenshot` of that sandbox.
+
+### `computer_screenshot`
+
+Take a screenshot (long edge at most 1200 px). Later coordinates are in its pixel space.
+
+Permission: `computer:screenshot`.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="computer_screenshot--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
+
+### `computer_click`
+
+Click at screenshot coordinates.
+
+Permission: `computer:click`.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="computer_click--button"></span>`button` | `string` | | left (default), right or middle. |
+| <span id="computer_click--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
+| <span id="computer_click--x"></span>`x` | `integer` | required | X in screenshot pixels. |
+| <span id="computer_click--y"></span>`y` | `integer` | required | Y in screenshot pixels. |
+
+**Example arguments**
+
+```json
+{"x":100,"y":200}
+```
+
+### `computer_double_click`
+
+Double-click at screenshot coordinates.
+
+Permission: `computer:click`.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="computer_double_click--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
+| <span id="computer_double_click--x"></span>`x` | `integer` | required | X in screenshot pixels. |
+| <span id="computer_double_click--y"></span>`y` | `integer` | required | Y in screenshot pixels. |
+
+**Example arguments**
+
+```json
+{"x":100,"y":200}
+```
+
+### `computer_move_cursor`
+
+Move the cursor.
+
+Permission: `computer:click`.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="computer_move_cursor--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
+| <span id="computer_move_cursor--x"></span>`x` | `integer` | required | X in screenshot pixels. |
+| <span id="computer_move_cursor--y"></span>`y` | `integer` | required | Y in screenshot pixels. |
+
+**Example arguments**
+
+```json
+{"x":100,"y":200}
+```
+
+### `computer_mouse_down`
+
+Press a mouse button.
+
+Permission: `computer:click`.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="computer_mouse_down--button"></span>`button` | `string` | | left, right or middle. |
+| <span id="computer_mouse_down--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
+| <span id="computer_mouse_down--x"></span>`x` | `integer` | required | X in screenshot pixels. |
+| <span id="computer_mouse_down--y"></span>`y` | `integer` | required | Y in screenshot pixels. |
+
+**Example arguments**
+
+```json
+{"x":100,"y":200}
+```
+
+### `computer_mouse_up`
+
+Release a mouse button.
+
+Permission: `computer:click`.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="computer_mouse_up--button"></span>`button` | `string` | | left, right or middle. |
+| <span id="computer_mouse_up--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
+| <span id="computer_mouse_up--x"></span>`x` | `integer` | required | X in screenshot pixels. |
+| <span id="computer_mouse_up--y"></span>`y` | `integer` | required | Y in screenshot pixels. |
+
+**Example arguments**
+
+```json
+{"x":100,"y":200}
+```
+
+### `computer_type`
+
+Type text.
+
+Permission: `computer:type`.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="computer_type--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
+| <span id="computer_type--text"></span>`text` | `string` | required | Text. |
+
+**Example arguments**
+
+```json
+{"text":"<text>"}
+```
+
+### `computer_key`
+
+Press a key (enter, escape, tab, a, ...).
+
+Permission: `computer:key`.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="computer_key--key"></span>`key` | `string` | required | Key. |
+| <span id="computer_key--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
+
+**Example arguments**
+
+```json
+{"key":"<key>"}
+```
+
+### `computer_key_down`
+
+Hold a key.
+
+Permission: `computer:key`.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="computer_key_down--key"></span>`key` | `string` | required | Key. |
+| <span id="computer_key_down--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
+
+**Example arguments**
+
+```json
+{"key":"<key>"}
+```
+
+### `computer_key_up`
+
+Release a key.
+
+Permission: `computer:key`.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="computer_key_up--key"></span>`key` | `string` | required | Key. |
+| <span id="computer_key_up--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
+
+**Example arguments**
+
+```json
+{"key":"<key>"}
+```
+
+### `computer_hotkey`
+
+Press a shortcut such as ctrl+c or cmd+shift+s.
+
+Permission: `computer:hotkey`.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="computer_hotkey--keys"></span>`keys` | `string` | required | Keys joined by +. |
+| <span id="computer_hotkey--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
+
+**Example arguments**
+
+```json
+{"keys":"<keys>"}
+```
+
+### `computer_scroll`
+
+Scroll up, down, left or right.
+
+Permission: `computer:scroll`.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="computer_scroll--amount"></span>`amount` | `integer` | | Lines (default 3). |
+| <span id="computer_scroll--direction"></span>`direction` | `string` | | down (default), up, left, right. |
+| <span id="computer_scroll--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
+
+### `computer_drag`
+
+Drag between two points.
+
+Permission: `computer:drag`.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="computer_drag--end_x"></span>`end_x` | `integer` | required | End X. |
+| <span id="computer_drag--end_y"></span>`end_y` | `integer` | required | End Y. |
+| <span id="computer_drag--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
+| <span id="computer_drag--start_x"></span>`start_x` | `integer` | required | Start X. |
+| <span id="computer_drag--start_y"></span>`start_y` | `integer` | required | Start Y. |
+
+**Example arguments**
+
+```json
+{"start_x":100,"start_y":200,"end_x":100,"end_y":200}
+```
+
+### `computer_clipboard_get`
+
+Read clipboard text.
+
+Permission: `computer:clipboard`.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="computer_clipboard_get--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
+
+### `computer_clipboard_set`
+
+Set clipboard text.
+
+Permission: `computer:clipboard`.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="computer_clipboard_set--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
+| <span id="computer_clipboard_set--text"></span>`text` | `string` | required | Text. |
+
+**Example arguments**
+
+```json
+{"text":"<text>"}
+```
+
+### `computer_file_read`
+
+Read a text file.
+
+Permission: `computer:file`.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="computer_file_read--path"></span>`path` | `string` | required | Path. |
+| <span id="computer_file_read--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
+
+**Example arguments**
+
+```json
+{"path":"<path>"}
+```
+
+### `computer_file_write`
+
+Write a text file (the Spaces `space_write` implementation, on this sandbox).
+
+Permission: `computer:file`.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="computer_file_write--content"></span>`content` | `string` | required | Content. |
+| <span id="computer_file_write--path"></span>`path` | `string` | required | Path. |
+| <span id="computer_file_write--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
+
+**Example arguments**
+
+```json
+{"path":"<path>","content":"<content>"}
+```
+
+### `computer_file_list`
+
+List a directory.
+
+Permission: `computer:file`.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="computer_file_list--path"></span>`path` | `string` | | Path (default .). |
+| <span id="computer_file_list--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
+
+### `computer_shell`
+
+Run a shell command (sh -c, 120 s timeout; the Spaces `space_bash` implementation, on this sandbox).
+
+Permission: `computer:shell`.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="computer_shell--command"></span>`command` | `string` | required | Command line. |
+| <span id="computer_shell--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
+
+**Example arguments**
+
+```json
+{"command":"<command>"}
+```
+
+### `computer_window_list`
+
+List windows.
+
+Permission: `computer:window`.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="computer_window_list--app"></span>`app` | `string` | | Filter by app or title. |
+| <span id="computer_window_list--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
+
+### `computer_window_open`
+
+Open a file or URL.
+
+Permission: `computer:window`.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="computer_window_open--path"></span>`path` | `string` | required | Path or URL. |
+| <span id="computer_window_open--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
+
+**Example arguments**
+
+```json
+{"path":"<path>"}
+```
+
+### `computer_window_focus`
+
+Focus a window.
+
+Permission: `computer:window`.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="computer_window_focus--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
+| <span id="computer_window_focus--window_id"></span>`window_id` | `string` | required | Window id. |
+
+**Example arguments**
+
+```json
+{"window_id":"<window_id>"}
+```
+
+### `computer_window_unfocus`
+
+Remove focus from the current window (Escape).
+
+Permission: `computer:window`.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="computer_window_unfocus--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
+
+### `computer_window_minimize`
+
+Minimize a window.
+
+Permission: `computer:window`.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="computer_window_minimize--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
+| <span id="computer_window_minimize--window_id"></span>`window_id` | `string` | required | Window id. |
+
+**Example arguments**
+
+```json
+{"window_id":"<window_id>"}
+```
+
+### `computer_window_maximize`
+
+Maximize a window.
+
+Permission: `computer:window`.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="computer_window_maximize--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
+| <span id="computer_window_maximize--window_id"></span>`window_id` | `string` | required | Window id. |
+
+**Example arguments**
+
+```json
+{"window_id":"<window_id>"}
+```
+
+### `computer_window_close`
+
+Close a window.
+
+Permission: `computer:window`.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="computer_window_close--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
+| <span id="computer_window_close--window_id"></span>`window_id` | `string` | required | Window id. |
+
+**Example arguments**
+
+```json
+{"window_id":"<window_id>"}
+```
+
+### `computer_window_resize`
+
+Resize a window.
+
+Permission: `computer:window`.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="computer_window_resize--height"></span>`height` | `integer` | required | Height. |
+| <span id="computer_window_resize--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
+| <span id="computer_window_resize--width"></span>`width` | `integer` | required | Width. |
+| <span id="computer_window_resize--window_id"></span>`window_id` | `string` | required | Window id. |
+
+**Example arguments**
+
+```json
+{"window_id":"<window_id>","width":1,"height":1}
+```
+
+### `computer_window_move`
+
+Move a window.
+
+Permission: `computer:window`.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="computer_window_move--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
+| <span id="computer_window_move--window_id"></span>`window_id` | `string` | required | Window id. |
+| <span id="computer_window_move--x"></span>`x` | `integer` | required | X. |
+| <span id="computer_window_move--y"></span>`y` | `integer` | required | Y. |
+
+**Example arguments**
+
+```json
+{"window_id":"<window_id>","x":100,"y":200}
+```
+
+### `computer_window_get_info`
+
+Get a window's title, position and size.
+
+Permission: `computer:window`.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="computer_window_get_info--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
+| <span id="computer_window_get_info--window_id"></span>`window_id` | `string` | required | Window id. |
+
+**Example arguments**
+
+```json
+{"window_id":"<window_id>"}
+```
+
+### `computer_launch`
+
+Launch an application.
+
+Permission: `computer:window`.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="computer_launch--app"></span>`app` | `string` | required | App name. |
+| <span id="computer_launch--args"></span>`args` | `string[]` | | Arguments. |
+| <span id="computer_launch--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
+
+**Example arguments**
+
+```json
+{"app":"<app>"}
+```
+
+### `computer_get_screen_size`
+
+Primary display size in points.
+
+Permission: `computer:screenshot`.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="computer_get_screen_size--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
+
+### `computer_get_cursor_position`
+
+Cursor position in points.
+
+Permission: `computer:screenshot`.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="computer_get_cursor_position--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
+
+### `computer_get_current_window`
+
+The focused window's id and title.
+
+Permission: `computer:screenshot`.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="computer_get_current_window--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
+
+### `computer_get_accessibility_tree`
+
+Accessibility tree of the focused (or given) window.
+
+Permission: `computer:screenshot`.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="computer_get_accessibility_tree--max_depth"></span>`max_depth` | `integer` | | Depth limit. |
+| <span id="computer_get_accessibility_tree--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
+| <span id="computer_get_accessibility_tree--window_id"></span>`window_id` | `string` | | Window id. |
+
+### `computer_accessibility_act`
+
+Act on an accessibility element (press, focus, set_value, ...).
+
+Permission: `computer:accessibility`.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="computer_accessibility_act--action"></span>`action` | `string` | | press (default), focus, set_value, ... |
+| <span id="computer_accessibility_act--element_id"></span>`element_id` | `string` | required | Element id. |
+| <span id="computer_accessibility_act--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
+| <span id="computer_accessibility_act--snapshot_id"></span>`snapshot_id` | `string` | | Snapshot id from the tree. |
+| <span id="computer_accessibility_act--value"></span>`value` | `string` | | Value for set_value. |
+
+**Example arguments**
+
+```json
+{"element_id":"<element_id>"}
+```
+
+## Skills tools
+
+### `skills_list`
+
+List recorded skills.
+
+Permission: `skills:list`.
+
+No parameters.
+
+### `skills_read`
+
+Read a skill and its steps.
+
+Permission: `skills:read`.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="skills_read--name"></span>`name` | `string` | required | Skill name. |
+
+**Example arguments**
+
+```json
+{"name":"<name>"}
+```
+
+### `skills_delete`
+
+Delete a skill.
+
+Permission: `skills:delete`.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="skills_delete--name"></span>`name` | `string` | required | Skill name. |
+
+**Example arguments**
+
+```json
+{"name":"<name>"}
+```
+
+### `skills_record`
+
+How to record a skill (recording is interactive: cua skills record).
+
+Permission: `skills:record`.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="skills_record--name"></span>`name` | `string` | required | Skill name. |
+
+**Example arguments**
+
+```json
+{"name":"<name>"}
+```
+
+## Permissions
+
+Tools are gated by `--permissions` (or `CUA_MCP_PERMISSIONS`), a comma-separated list of permissions and groups; the default is `all`. Each group has an `all` and a `readonly` form (`sandbox:readonly`); each tool lists its own permission.
+
+| Group | Grants | `:readonly` grants |
+| --- | --- | --- |
+| `computer:all` | 12 permissions | `computer:screenshot` |
+| `images:all` | `images:list` | `images:list` |
+| `sandbox:all` | 10 permissions | `sandbox:list`, `sandbox:get` |
+| `skills:all` | `skills:list`, `skills:read`, `skills:record`, `skills:delete` | `skills:list`, `skills:read` |
+| `spaces:all` | 86 permissions | 28 permissions |
+| `teleport:all` | `teleport:browser` | none |
diff --git a/docs/content/docs/cua-cli/reference/mcp-tools/computer.mdx b/docs/content/docs/cua-cli/reference/mcp-tools/computer.mdx
deleted file mode 100644
index e601704d7d..0000000000
--- a/docs/content/docs/cua-cli/reference/mcp-tools/computer.mdx
+++ /dev/null
@@ -1,604 +0,0 @@
----
-title: "Computer tools"
-description: "Screenshots, input, windows, files and shell on a sandbox desktop."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-cli
- Source: cua dump-docs --type mcp
- Version: 0.5.0
-*/}
-
-| Tool | Description |
-| --- | --- |
-| [`computer_screenshot`](#computer_screenshot) | Take a screenshot (long edge at most 1200 px). |
-| [`computer_click`](#computer_click) | Click at screenshot coordinates. |
-| [`computer_double_click`](#computer_double_click) | Double-click at screenshot coordinates. |
-| [`computer_move_cursor`](#computer_move_cursor) | Move the cursor. |
-| [`computer_mouse_down`](#computer_mouse_down) | Press a mouse button. |
-| [`computer_mouse_up`](#computer_mouse_up) | Release a mouse button. |
-| [`computer_type`](#computer_type) | Type text. |
-| [`computer_key`](#computer_key) | Press a key (enter, escape, tab, a, ...). |
-| [`computer_key_down`](#computer_key_down) | Hold a key. |
-| [`computer_key_up`](#computer_key_up) | Release a key. |
-| [`computer_hotkey`](#computer_hotkey) | Press a shortcut such as ctrl+c or cmd+shift+s. |
-| [`computer_scroll`](#computer_scroll) | Scroll up, down, left or right. |
-| [`computer_drag`](#computer_drag) | Drag between two points. |
-| [`computer_clipboard_get`](#computer_clipboard_get) | Read clipboard text. |
-| [`computer_clipboard_set`](#computer_clipboard_set) | Set clipboard text. |
-| [`computer_file_read`](#computer_file_read) | Read a text file. |
-| [`computer_file_write`](#computer_file_write) | Write a text file (the Spaces `space_write` implementation, on this sandbox). |
-| [`computer_file_list`](#computer_file_list) | List a directory. |
-| [`computer_shell`](#computer_shell) | Run a shell command (sh -c, 120 s timeout; the Spaces `space_bash` implementation, on this sandbox). |
-| [`computer_window_list`](#computer_window_list) | List windows. |
-| [`computer_window_open`](#computer_window_open) | Open a file or URL. |
-| [`computer_window_focus`](#computer_window_focus) | Focus a window. |
-| [`computer_window_unfocus`](#computer_window_unfocus) | Remove focus from the current window (Escape). |
-| [`computer_window_minimize`](#computer_window_minimize) | Minimize a window. |
-| [`computer_window_maximize`](#computer_window_maximize) | Maximize a window. |
-| [`computer_window_close`](#computer_window_close) | Close a window. |
-| [`computer_window_resize`](#computer_window_resize) | Resize a window. |
-| [`computer_window_move`](#computer_window_move) | Move a window. |
-| [`computer_window_get_info`](#computer_window_get_info) | Get a window's title, position and size. |
-| [`computer_launch`](#computer_launch) | Launch an application. |
-| [`computer_get_screen_size`](#computer_get_screen_size) | Primary display size in points. |
-| [`computer_get_cursor_position`](#computer_get_cursor_position) | Cursor position in points. |
-| [`computer_get_current_window`](#computer_get_current_window) | The focused window's id and title. |
-| [`computer_get_accessibility_tree`](#computer_get_accessibility_tree) | Accessibility tree of the focused (or given) window. |
-| [`computer_accessibility_act`](#computer_accessibility_act) | Act on an accessibility element (press, focus, set_value, ...). |
-
-Computer tools act on a sandbox desktop through its cua-spacesd. Coordinates are in the pixel space of the last `computer_screenshot` of that sandbox.
-
-Served by `cua mcp`; see [MCP tools](/cua-cli/reference/mcp-tools) for every tool.
-
-## `computer_screenshot`
-
-Take a screenshot (long edge at most 1200 px). Later coordinates are in its pixel space.
-
-Permission: `computer:screenshot`.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="computer_screenshot--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
-
-## `computer_click`
-
-Click at screenshot coordinates.
-
-Permission: `computer:click`.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="computer_click--button"></span>`button` | `string` | | left (default), right or middle. |
-| <span id="computer_click--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
-| <span id="computer_click--x"></span>`x` | `integer` | required | X in screenshot pixels. |
-| <span id="computer_click--y"></span>`y` | `integer` | required | Y in screenshot pixels. |
-
-**Example arguments**
-
-```json
-{"x":100,"y":200}
-```
-
-## `computer_double_click`
-
-Double-click at screenshot coordinates.
-
-Permission: `computer:click`.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="computer_double_click--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
-| <span id="computer_double_click--x"></span>`x` | `integer` | required | X in screenshot pixels. |
-| <span id="computer_double_click--y"></span>`y` | `integer` | required | Y in screenshot pixels. |
-
-**Example arguments**
-
-```json
-{"x":100,"y":200}
-```
-
-## `computer_move_cursor`
-
-Move the cursor.
-
-Permission: `computer:click`.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="computer_move_cursor--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
-| <span id="computer_move_cursor--x"></span>`x` | `integer` | required | X in screenshot pixels. |
-| <span id="computer_move_cursor--y"></span>`y` | `integer` | required | Y in screenshot pixels. |
-
-**Example arguments**
-
-```json
-{"x":100,"y":200}
-```
-
-## `computer_mouse_down`
-
-Press a mouse button.
-
-Permission: `computer:click`.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="computer_mouse_down--button"></span>`button` | `string` | | left, right or middle. |
-| <span id="computer_mouse_down--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
-| <span id="computer_mouse_down--x"></span>`x` | `integer` | required | X in screenshot pixels. |
-| <span id="computer_mouse_down--y"></span>`y` | `integer` | required | Y in screenshot pixels. |
-
-**Example arguments**
-
-```json
-{"x":100,"y":200}
-```
-
-## `computer_mouse_up`
-
-Release a mouse button.
-
-Permission: `computer:click`.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="computer_mouse_up--button"></span>`button` | `string` | | left, right or middle. |
-| <span id="computer_mouse_up--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
-| <span id="computer_mouse_up--x"></span>`x` | `integer` | required | X in screenshot pixels. |
-| <span id="computer_mouse_up--y"></span>`y` | `integer` | required | Y in screenshot pixels. |
-
-**Example arguments**
-
-```json
-{"x":100,"y":200}
-```
-
-## `computer_type`
-
-Type text.
-
-Permission: `computer:type`.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="computer_type--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
-| <span id="computer_type--text"></span>`text` | `string` | required | Text. |
-
-**Example arguments**
-
-```json
-{"text":"<text>"}
-```
-
-## `computer_key`
-
-Press a key (enter, escape, tab, a, ...).
-
-Permission: `computer:key`.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="computer_key--key"></span>`key` | `string` | required | Key. |
-| <span id="computer_key--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
-
-**Example arguments**
-
-```json
-{"key":"<key>"}
-```
-
-## `computer_key_down`
-
-Hold a key.
-
-Permission: `computer:key`.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="computer_key_down--key"></span>`key` | `string` | required | Key. |
-| <span id="computer_key_down--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
-
-**Example arguments**
-
-```json
-{"key":"<key>"}
-```
-
-## `computer_key_up`
-
-Release a key.
-
-Permission: `computer:key`.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="computer_key_up--key"></span>`key` | `string` | required | Key. |
-| <span id="computer_key_up--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
-
-**Example arguments**
-
-```json
-{"key":"<key>"}
-```
-
-## `computer_hotkey`
-
-Press a shortcut such as ctrl+c or cmd+shift+s.
-
-Permission: `computer:hotkey`.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="computer_hotkey--keys"></span>`keys` | `string` | required | Keys joined by +. |
-| <span id="computer_hotkey--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
-
-**Example arguments**
-
-```json
-{"keys":"<keys>"}
-```
-
-## `computer_scroll`
-
-Scroll up, down, left or right.
-
-Permission: `computer:scroll`.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="computer_scroll--amount"></span>`amount` | `integer` | | Lines (default 3). |
-| <span id="computer_scroll--direction"></span>`direction` | `string` | | down (default), up, left, right. |
-| <span id="computer_scroll--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
-
-## `computer_drag`
-
-Drag between two points.
-
-Permission: `computer:drag`.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="computer_drag--end_x"></span>`end_x` | `integer` | required | End X. |
-| <span id="computer_drag--end_y"></span>`end_y` | `integer` | required | End Y. |
-| <span id="computer_drag--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
-| <span id="computer_drag--start_x"></span>`start_x` | `integer` | required | Start X. |
-| <span id="computer_drag--start_y"></span>`start_y` | `integer` | required | Start Y. |
-
-**Example arguments**
-
-```json
-{"start_x":100,"start_y":200,"end_x":100,"end_y":200}
-```
-
-## `computer_clipboard_get`
-
-Read clipboard text.
-
-Permission: `computer:clipboard`.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="computer_clipboard_get--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
-
-## `computer_clipboard_set`
-
-Set clipboard text.
-
-Permission: `computer:clipboard`.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="computer_clipboard_set--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
-| <span id="computer_clipboard_set--text"></span>`text` | `string` | required | Text. |
-
-**Example arguments**
-
-```json
-{"text":"<text>"}
-```
-
-## `computer_file_read`
-
-Read a text file.
-
-Permission: `computer:file`.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="computer_file_read--path"></span>`path` | `string` | required | Path. |
-| <span id="computer_file_read--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
-
-**Example arguments**
-
-```json
-{"path":"<path>"}
-```
-
-## `computer_file_write`
-
-Write a text file (the Spaces `space_write` implementation, on this sandbox).
-
-Permission: `computer:file`.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="computer_file_write--content"></span>`content` | `string` | required | Content. |
-| <span id="computer_file_write--path"></span>`path` | `string` | required | Path. |
-| <span id="computer_file_write--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
-
-**Example arguments**
-
-```json
-{"path":"<path>","content":"<content>"}
-```
-
-## `computer_file_list`
-
-List a directory.
-
-Permission: `computer:file`.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="computer_file_list--path"></span>`path` | `string` | | Path (default .). |
-| <span id="computer_file_list--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
-
-## `computer_shell`
-
-Run a shell command (sh -c, 120 s timeout; the Spaces `space_bash` implementation, on this sandbox).
-
-Permission: `computer:shell`.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="computer_shell--command"></span>`command` | `string` | required | Command line. |
-| <span id="computer_shell--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
-
-**Example arguments**
-
-```json
-{"command":"<command>"}
-```
-
-## `computer_window_list`
-
-List windows.
-
-Permission: `computer:window`.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="computer_window_list--app"></span>`app` | `string` | | Filter by app or title. |
-| <span id="computer_window_list--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
-
-## `computer_window_open`
-
-Open a file or URL.
-
-Permission: `computer:window`.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="computer_window_open--path"></span>`path` | `string` | required | Path or URL. |
-| <span id="computer_window_open--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
-
-**Example arguments**
-
-```json
-{"path":"<path>"}
-```
-
-## `computer_window_focus`
-
-Focus a window.
-
-Permission: `computer:window`.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="computer_window_focus--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
-| <span id="computer_window_focus--window_id"></span>`window_id` | `string` | required | Window id. |
-
-**Example arguments**
-
-```json
-{"window_id":"<window_id>"}
-```
-
-## `computer_window_unfocus`
-
-Remove focus from the current window (Escape).
-
-Permission: `computer:window`.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="computer_window_unfocus--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
-
-## `computer_window_minimize`
-
-Minimize a window.
-
-Permission: `computer:window`.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="computer_window_minimize--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
-| <span id="computer_window_minimize--window_id"></span>`window_id` | `string` | required | Window id. |
-
-**Example arguments**
-
-```json
-{"window_id":"<window_id>"}
-```
-
-## `computer_window_maximize`
-
-Maximize a window.
-
-Permission: `computer:window`.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="computer_window_maximize--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
-| <span id="computer_window_maximize--window_id"></span>`window_id` | `string` | required | Window id. |
-
-**Example arguments**
-
-```json
-{"window_id":"<window_id>"}
-```
-
-## `computer_window_close`
-
-Close a window.
-
-Permission: `computer:window`.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="computer_window_close--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
-| <span id="computer_window_close--window_id"></span>`window_id` | `string` | required | Window id. |
-
-**Example arguments**
-
-```json
-{"window_id":"<window_id>"}
-```
-
-## `computer_window_resize`
-
-Resize a window.
-
-Permission: `computer:window`.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="computer_window_resize--height"></span>`height` | `integer` | required | Height. |
-| <span id="computer_window_resize--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
-| <span id="computer_window_resize--width"></span>`width` | `integer` | required | Width. |
-| <span id="computer_window_resize--window_id"></span>`window_id` | `string` | required | Window id. |
-
-**Example arguments**
-
-```json
-{"window_id":"<window_id>","width":1,"height":1}
-```
-
-## `computer_window_move`
-
-Move a window.
-
-Permission: `computer:window`.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="computer_window_move--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
-| <span id="computer_window_move--window_id"></span>`window_id` | `string` | required | Window id. |
-| <span id="computer_window_move--x"></span>`x` | `integer` | required | X. |
-| <span id="computer_window_move--y"></span>`y` | `integer` | required | Y. |
-
-**Example arguments**
-
-```json
-{"window_id":"<window_id>","x":100,"y":200}
-```
-
-## `computer_window_get_info`
-
-Get a window's title, position and size.
-
-Permission: `computer:window`.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="computer_window_get_info--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
-| <span id="computer_window_get_info--window_id"></span>`window_id` | `string` | required | Window id. |
-
-**Example arguments**
-
-```json
-{"window_id":"<window_id>"}
-```
-
-## `computer_launch`
-
-Launch an application.
-
-Permission: `computer:window`.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="computer_launch--app"></span>`app` | `string` | required | App name. |
-| <span id="computer_launch--args"></span>`args` | `string[]` | | Arguments. |
-| <span id="computer_launch--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
-
-**Example arguments**
-
-```json
-{"app":"<app>"}
-```
-
-## `computer_get_screen_size`
-
-Primary display size in points.
-
-Permission: `computer:screenshot`.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="computer_get_screen_size--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
-
-## `computer_get_cursor_position`
-
-Cursor position in points.
-
-Permission: `computer:screenshot`.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="computer_get_cursor_position--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
-
-## `computer_get_current_window`
-
-The focused window's id and title.
-
-Permission: `computer:screenshot`.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="computer_get_current_window--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
-
-## `computer_get_accessibility_tree`
-
-Accessibility tree of the focused (or given) window.
-
-Permission: `computer:screenshot`.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="computer_get_accessibility_tree--max_depth"></span>`max_depth` | `integer` | | Depth limit. |
-| <span id="computer_get_accessibility_tree--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
-| <span id="computer_get_accessibility_tree--window_id"></span>`window_id` | `string` | | Window id. |
-
-## `computer_accessibility_act`
-
-Act on an accessibility element (press, focus, set_value, ...).
-
-Permission: `computer:accessibility`.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="computer_accessibility_act--action"></span>`action` | `string` | | press (default), focus, set_value, ... |
-| <span id="computer_accessibility_act--element_id"></span>`element_id` | `string` | required | Element id. |
-| <span id="computer_accessibility_act--sandbox"></span>`sandbox` | `string` | | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations (default: --sandbox / CUA_SANDBOX). |
-| <span id="computer_accessibility_act--snapshot_id"></span>`snapshot_id` | `string` | | Snapshot id from the tree. |
-| <span id="computer_accessibility_act--value"></span>`value` | `string` | | Value for set_value. |
-
-**Example arguments**
-
-```json
-{"element_id":"<element_id>"}
-```
diff --git a/docs/content/docs/cua-cli/reference/mcp-tools/images.mdx b/docs/content/docs/cua-cli/reference/mcp-tools/images.mdx
deleted file mode 100644
index ab3ea85f7e..0000000000
--- a/docs/content/docs/cua-cli/reference/mcp-tools/images.mdx
+++ /dev/null
@@ -1,25 +0,0 @@
----
-title: "Image tools"
-description: "The sandbox image catalog: which images exist and which ship a browser."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-cli
- Source: cua dump-docs --type mcp
- Version: 0.5.0
-*/}
-
-Served by `cua mcp`; see [MCP tools](/cua-cli/reference/mcp-tools) for every tool.
-
-## `images_list`
-
-List the sandbox image catalog (the images the docs list): ref, OS, container or VM, local runtime, whether it ships cua-spacesd and which browsers, its other variants, and the command that creates it. browser_tools=true means the in-sandbox cua-driver browser tools can drive its browser. Call this first to choose an image.
-
-Permission: `images:list`.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="images_list--all"></span>`all` | `boolean` | | Include unpublished entries (benchmark images). |
-| <span id="images_list--browser"></span>`browser` | `boolean` | | Only images whose browser the cua-driver browser tools drive. |
-| <span id="images_list--os"></span>`os` | `string` | | Only this OS: linux, windows or macos. |
diff --git a/docs/content/docs/cua-cli/reference/mcp-tools/index.mdx b/docs/content/docs/cua-cli/reference/mcp-tools/index.mdx
deleted file mode 100644
index 50566c39f8..0000000000
--- a/docs/content/docs/cua-cli/reference/mcp-tools/index.mdx
+++ /dev/null
@@ -1,208 +0,0 @@
----
-title: "All tools"
-description: "Every tool the cua MCP server exposes, with its permission and parameters."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-cli
- Source: cua dump-docs --type mcp
- Version: 0.5.0
-*/}
-
-`cua mcp` (and `cua daemon mcp`, the same server backed by the cua daemon) serves these tools over stdio. See [MCP server](/cua-cli/guides/mcp-server) for client setup.
-
-Contract version 0.7.0; MCP protocol revision 2025-06-18.
-
-## Spaces tools
-
-The Spaces contract: register, claim and release Spaces, run commands, move files, stream, run agents and teleport. [Reference](/cua-cli/reference/mcp-tools/spaces).
-
-| Tool | Description |
-| --- | --- |
-| <span id="add_space"></span>[`add_space`](/spaces/reference/lifecycle#add_space) | Add an existing machine as a Space by address and token. |
-| <span id="remove_space"></span>[`remove_space`](/spaces/reference/lifecycle#remove_space) | Forget a registered Space without touching it. |
-| <span id="list_spaces"></span>[`list_spaces`](/spaces/reference/lifecycle#list_spaces) | List the Spaces this connection can see. |
-| <span id="create_space"></span>[`create_space`](/spaces/reference/lifecycle#create_space) | Create a Space: a new sandbox on this machine, on one of your machines, or in the cloud. |
-| <span id="delete_space"></span>[`delete_space`](/spaces/reference/lifecycle#delete_space) | Delete a Space's sandbox and forget it. |
-| <span id="stop_space"></span>[`stop_space`](/spaces/reference/lifecycle#stop_space) | Turn a Space off: suspend it (memory kept) or stop it (disk kept). |
-| <span id="start_space"></span>[`start_space`](/spaces/reference/lifecycle#start_space) | Turn a Space back on: resume or boot it. |
-| <span id="space_bash"></span>[`space_bash`](/spaces/reference/commands-and-files#space_bash) | Run a shell command inside the Space. |
-| <span id="space_write"></span>[`space_write`](/spaces/reference/commands-and-files#space_write) | Write literal text to a path inside the Space. |
-| <span id="upload"></span>[`upload`](/spaces/reference/commands-and-files#upload) | Send a local file or folder into the Space. |
-| <span id="send_file"></span>[`send_file`](/spaces/reference/commands-and-files#send_file) | Send a host file or folder into the Space's Downloads, verified by sha256 on arrival. |
-| <span id="download"></span>[`download`](/spaces/reference/commands-and-files#download) | Fetch a file or folder out of the Space. |
-| <span id="stream_endpoint"></span>[`stream_endpoint`](/spaces/reference/streams-and-display#stream_endpoint) | Return a ticketed media endpoint for the Space's desktop or one window. |
-| <span id="list_space_windows"></span>[`list_space_windows`](/spaces/reference/streams-and-display#list_space_windows) | List the windows open inside the Space. |
-| <span id="stream_space_window"></span>[`stream_space_window`](/spaces/reference/streams-and-display#stream_space_window) | Draw one Space window on the operator's desktop. |
-| <span id="show_space_pip"></span>[`show_space_pip`](/spaces/reference/streams-and-display#show_space_pip) | Pin the Space as picture-in-picture on the operator's desktop. |
-| <span id="hide_space_pip"></span>[`hide_space_pip`](/spaces/reference/streams-and-display#hide_space_pip) | Unpin the picture-in-picture window. |
-| <span id="open_space_viewer"></span>[`open_space_viewer`](/spaces/reference/streams-and-display#open_space_viewer) | Open the full Space viewer on the operator's desktop. |
-| <span id="list_tools"></span>[`list_tools`](/spaces/reference/services#list_tools) | List the MCP services and tools reachable inside the Space. |
-| <span id="call_tool"></span>[`call_tool`](/spaces/reference/services#call_tool) | Call a service tool inside the Space. |
-| <span id="agent_start"></span>[`agent_start`](/spaces/reference/agents#agent_start) | Start a coding agent in the Space. |
-| <span id="agent_message"></span>[`agent_message`](/spaces/reference/agents#agent_message) | Send a follow-up to an agent run. |
-| <span id="agent_events"></span>[`agent_events`](/spaces/reference/agents#agent_events) | Read an agent run's events after a cursor. |
-| <span id="agent_status"></span>[`agent_status`](/spaces/reference/agents#agent_status) | Read an agent run's status and result. |
-| <span id="agent_interrupt"></span>[`agent_interrupt`](/spaces/reference/agents#agent_interrupt) | Interrupt an agent run's current turn. |
-| <span id="agent_stop"></span>[`agent_stop`](/spaces/reference/agents#agent_stop) | Stop an agent run. |
-| <span id="agent_list"></span>[`agent_list`](/spaces/reference/agents#agent_list) | List agent runs in the Space. |
-| <span id="agent_capabilities"></span>[`agent_capabilities`](/spaces/reference/agents#agent_capabilities) | Report what the agent harnesses support. |
-| <span id="persistent_agent_create"></span>[`persistent_agent_create`](/spaces/reference/persistent-agents#persistent_agent_create) | Create a named agent whose memory outlives its Space. |
-| <span id="persistent_agent_list"></span>[`persistent_agent_list`](/spaces/reference/persistent-agents#persistent_agent_list) | List persistent agents. |
-| <span id="persistent_agent_remove"></span>[`persistent_agent_remove`](/spaces/reference/persistent-agents#persistent_agent_remove) | Forget a persistent agent. |
-| <span id="persistent_agent_send"></span>[`persistent_agent_send`](/spaces/reference/persistent-agents#persistent_agent_send) | Give a persistent agent a turn. |
-| <span id="persistent_agent_save"></span>[`persistent_agent_save`](/spaces/reference/persistent-agents#persistent_agent_save) | Save a persistent agent's home now. |
-| <span id="agent_pause"></span>[`agent_pause`](/spaces/reference/persistent-agents#agent_pause) | Pause a persistent agent: its run, its routines and its Space. |
-| <span id="agent_resume"></span>[`agent_resume`](/spaces/reference/persistent-agents#agent_resume) | Resume a paused persistent agent. |
-| <span id="routine_add"></span>[`routine_add`](/spaces/reference/persistent-agents#routine_add) | Schedule a recurring turn for a persistent agent. |
-| <span id="routine_list"></span>[`routine_list`](/spaces/reference/persistent-agents#routine_list) | List routines. |
-| <span id="routine_remove"></span>[`routine_remove`](/spaces/reference/persistent-agents#routine_remove) | Delete a routine. |
-| <span id="routine_set_enabled"></span>[`routine_set_enabled`](/spaces/reference/persistent-agents#routine_set_enabled) | Turn a routine on or off. |
-| <span id="notify_user"></span>[`notify_user`](/spaces/reference/persistent-agents#notify_user) | Tell the user something in the Cua app. |
-| <span id="notifications_list"></span>[`notifications_list`](/spaces/reference/persistent-agents#notifications_list) | Read the notifications feed. |
-| <span id="notifications_ack"></span>[`notifications_ack`](/spaces/reference/persistent-agents#notifications_ack) | Mark notifications read. |
-| <span id="computer_access_grant"></span>[`computer_access_grant`](/spaces/reference/persistent-agents#computer_access_grant) | Let a persistent agent use one of the user's computers. |
-| <span id="computer_access_revoke"></span>[`computer_access_revoke`](/spaces/reference/persistent-agents#computer_access_revoke) | Take back a persistent agent's access to a computer. |
-| <span id="computer_access_list"></span>[`computer_access_list`](/spaces/reference/persistent-agents#computer_access_list) | List per-agent computer access. |
-| <span id="teleport_manifest"></span>[`teleport_manifest`](/spaces/reference/teleport#teleport_manifest) | Describe what a session teleport would move. |
-| <span id="teleport_app"></span>[`teleport_app`](/spaces/reference/teleport#teleport_app) | Move an app session into the Space. |
-| <span id="request_site_login"></span>[`request_site_login`](/spaces/reference/keyvault#request_site_login) | Sign in to a site in the Space with the user's saved password. |
-| <span id="hotspot_start"></span>[`hotspot_start`](/spaces/reference/hotspot#hotspot_start) | Start sharing this machine's network with a Space. |
-| <span id="hotspot_stop"></span>[`hotspot_stop`](/spaces/reference/hotspot#hotspot_stop) | Stop sharing this machine's network. |
-| <span id="hotspot_status"></span>[`hotspot_status`](/spaces/reference/hotspot#hotspot_status) | Report which Spaces are sharing this machine's network, with counters. |
-| <span id="volume_ls"></span>[`volume_ls`](/spaces/reference/volume#volume_ls) | List a folder of the Cua Volume. |
-| <span id="volume_read"></span>[`volume_read`](/spaces/reference/volume#volume_read) | Read a file from the Cua Volume. |
-| <span id="volume_write"></span>[`volume_write`](/spaces/reference/volume#volume_write) | Write a file to the Cua Volume. |
-| <span id="volume_delete"></span>[`volume_delete`](/spaces/reference/volume#volume_delete) | Delete a file from the Cua Volume. |
-| <span id="volume_history"></span>[`volume_history`](/spaces/reference/volume#volume_history) | List a Cua Volume file's versions. |
-| <span id="volume_restore"></span>[`volume_restore`](/spaces/reference/volume#volume_restore) | Restore an old version of a Cua Volume file. |
-| <span id="volume_grant"></span>[`volume_grant`](/spaces/reference/volume#volume_grant) | Grant an agent or Space more Cua Volume access. |
-| <span id="volume_revoke"></span>[`volume_revoke`](/spaces/reference/volume#volume_revoke) | Revoke a Cua Volume grant. |
-| <span id="volume_grants"></span>[`volume_grants`](/spaces/reference/volume#volume_grants) | List Cua Volume grants. |
-| <span id="volume_request_access"></span>[`volume_request_access`](/spaces/reference/volume#volume_request_access) | Ask the user for more Cua Volume access. |
-| <span id="volume_requests"></span>[`volume_requests`](/spaces/reference/volume#volume_requests) | List Cua Volume access requests waiting for the user. |
-| <span id="volume_approve"></span>[`volume_approve`](/spaces/reference/volume#volume_approve) | Approve a Cua Volume access request. |
-| <span id="volume_deny"></span>[`volume_deny`](/spaces/reference/volume#volume_deny) | Decline a Cua Volume access request. |
-| <span id="volume_audit"></span>[`volume_audit`](/spaces/reference/volume#volume_audit) | Read the Cua Volume audit log. |
-| <span id="volume_storage"></span>[`volume_storage`](/spaces/reference/volume#volume_storage) | Show where the Cua Volume keeps its bytes. |
-| <span id="volume_storage_set"></span>[`volume_storage_set`](/spaces/reference/volume#volume_storage_set) | Test or change where the Cua Volume keeps its bytes. |
-| <span id="volume_mount_status"></span>[`volume_mount_status`](/spaces/reference/volume#volume_mount_status) | Show whether the Cua Volume is mounted as a volume. |
-| <span id="volume_mount"></span>[`volume_mount`](/spaces/reference/volume#volume_mount) | Mount the Cua Volume as a volume. |
-| <span id="volume_unmount"></span>[`volume_unmount`](/spaces/reference/volume#volume_unmount) | Unmount the Cua Volume volume. |
-| <span id="volume_sync_status"></span>[`volume_sync_status`](/spaces/reference/volume#volume_sync_status) | Show the Cua Volume's sync state across devices. |
-| <span id="volume_sync_events"></span>[`volume_sync_events`](/spaces/reference/volume#volume_sync_events) | Wait for Cua Volume sync events. |
-| <span id="volume_sync_resolve"></span>[`volume_sync_resolve`](/spaces/reference/volume#volume_sync_resolve) | Mark a Cua Volume sync conflict as seen. |
-| <span id="volume_cache_stats"></span>[`volume_cache_stats`](/spaces/reference/volume#volume_cache_stats) | Show the Cua Volume block cache. |
-| <span id="volume_cache_set"></span>[`volume_cache_set`](/spaces/reference/volume#volume_cache_set) | Set the Cua Volume block cache's size cap. |
-| <span id="volume_cache_clear"></span>[`volume_cache_clear`](/spaces/reference/volume#volume_cache_clear) | Clear the Cua Volume block cache. |
-| <span id="share_space"></span>[`share_space`](/spaces/reference/sharing#share_space) | Let another cua.ai account watch or edit a Space. |
-| <span id="unshare_space"></span>[`unshare_space`](/spaces/reference/sharing#unshare_space) | Stop sharing a Space with an account, or with everyone. |
-| <span id="space_shares"></span>[`space_shares`](/spaces/reference/sharing#space_shares) | List who a Space is shared with. |
-| <span id="relay_register_space"></span>[`relay_register_space`](/spaces/reference/sharing#relay_register_space) | Publish a Space on the relay for the account's other devices. |
-| <span id="relay_unregister_space"></span>[`relay_unregister_space`](/spaces/reference/sharing#relay_unregister_space) | Take a Space off the relay. |
-| <span id="cloud_status"></span>[`cloud_status`](/spaces/reference/cloud#cloud_status) | List your clouds (AWS, Google Cloud, Modal): found credentials, the connected account and region, what each can run at what hourly cost, and what Cua created there. |
-| <span id="cloud_connect"></span>[`cloud_connect`](/spaces/reference/cloud#cloud_connect) | Connect a cloud account Spaces can be created in. |
-| <span id="cloud_test"></span>[`cloud_test`](/spaces/reference/cloud#cloud_test) | Check a cloud account without creating anything. |
-| <span id="cloud_disconnect"></span>[`cloud_disconnect`](/spaces/reference/cloud#cloud_disconnect) | Forget a connected cloud account. |
-| <span id="cloud_sweep"></span>[`cloud_sweep`](/spaces/reference/cloud#cloud_sweep) | Find and delete what Cua left in your clouds. |
-
-## Image tools
-
-The sandbox image catalog: which images exist and which ship a browser. [Reference](/cua-cli/reference/mcp-tools/images).
-
-| Tool | Description |
-| --- | --- |
-| <span id="images_list"></span>[`images_list`](/cua-cli/reference/mcp-tools/images#images_list) | List the sandbox image catalog (the images the docs list): ref, OS, container or VM, local runtime, whether it ships cua-spacesd and which browsers, its other variants, and the command that creates it. |
-
-## Sandbox tools
-
-Create and manage sandboxes, local or on your own machines. [Reference](/cua-cli/reference/mcp-tools/sandbox).
-
-| Tool | Description |
-| --- | --- |
-| <span id="sandbox_list"></span>[`sandbox_list`](/cua-cli/reference/mcp-tools/sandbox#sandbox_list) | List sandboxes: local and direct ones by default, each row with location (local or direct). |
-| <span id="sandbox_create"></span>[`sandbox_create`](/cua-cli/reference/mcp-tools/sandbox#sandbox_create) | Create a sandbox from any image. |
-| <span id="sandbox_get"></span>[`sandbox_get`](/cua-cli/reference/mcp-tools/sandbox#sandbox_get) | Get details for a sandbox. |
-| <span id="sandbox_start"></span>[`sandbox_start`](/cua-cli/reference/mcp-tools/sandbox#sandbox_start) | Start (resume) a sandbox. |
-| <span id="sandbox_stop"></span>[`sandbox_stop`](/cua-cli/reference/mcp-tools/sandbox#sandbox_stop) | Stop (suspend) a sandbox. |
-| <span id="sandbox_restart"></span>[`sandbox_restart`](/cua-cli/reference/mcp-tools/sandbox#sandbox_restart) | Restart a sandbox. |
-| <span id="sandbox_suspend"></span>[`sandbox_suspend`](/cua-cli/reference/mcp-tools/sandbox#sandbox_suspend) | Suspend a sandbox. |
-| <span id="sandbox_delete"></span>[`sandbox_delete`](/cua-cli/reference/mcp-tools/sandbox#sandbox_delete) | Delete a sandbox. |
-| <span id="sandbox_view"></span>[`sandbox_view`](/cua-cli/reference/mcp-tools/sandbox#sandbox_view) | Get a browser link to the sandbox desktop in the cua-spacesd HTML5 viewer (video, audio, input, clipboard, files). |
-| <span id="sandbox_vnc"></span>[`sandbox_vnc`](/cua-cli/reference/mcp-tools/sandbox#sandbox_vnc) | Deprecated: use sandbox_view. |
-| <span id="sandbox_open_browser"></span>[`sandbox_open_browser`](/cua-cli/reference/mcp-tools/sandbox#sandbox_open_browser) | Launch Chromium with a fresh throwaway profile inside an existing sandbox (an image with cua-spacesd and Chromium, see images_list), bind it and optionally open a URL. |
-
-## Teleport tools
-
-Move a signed-in browser session, per site, into a sandbox through the Cua Keyvault, with consent. [Reference](/cua-cli/reference/mcp-tools/teleport).
-
-| Tool | Description |
-| --- | --- |
-| <span id="teleport_browser_session"></span>[`teleport_browser_session`](/cua-cli/reference/mcp-tools/teleport#teleport_browser_session) | Teleport the user's signed-in session for specific sites (for example github.com) from their Firefox or Chrome into a sandbox, through the Cua Keyvault. |
-
-## Computer tools
-
-Screenshots, input, windows, files and shell on a sandbox desktop. [Reference](/cua-cli/reference/mcp-tools/computer).
-
-| Tool | Description |
-| --- | --- |
-| <span id="computer_screenshot"></span>[`computer_screenshot`](/cua-cli/reference/mcp-tools/computer#computer_screenshot) | Take a screenshot (long edge at most 1200 px). |
-| <span id="computer_click"></span>[`computer_click`](/cua-cli/reference/mcp-tools/computer#computer_click) | Click at screenshot coordinates. |
-| <span id="computer_double_click"></span>[`computer_double_click`](/cua-cli/reference/mcp-tools/computer#computer_double_click) | Double-click at screenshot coordinates. |
-| <span id="computer_move_cursor"></span>[`computer_move_cursor`](/cua-cli/reference/mcp-tools/computer#computer_move_cursor) | Move the cursor. |
-| <span id="computer_mouse_down"></span>[`computer_mouse_down`](/cua-cli/reference/mcp-tools/computer#computer_mouse_down) | Press a mouse button. |
-| <span id="computer_mouse_up"></span>[`computer_mouse_up`](/cua-cli/reference/mcp-tools/computer#computer_mouse_up) | Release a mouse button. |
-| <span id="computer_type"></span>[`computer_type`](/cua-cli/reference/mcp-tools/computer#computer_type) | Type text. |
-| <span id="computer_key"></span>[`computer_key`](/cua-cli/reference/mcp-tools/computer#computer_key) | Press a key (enter, escape, tab, a, ...). |
-| <span id="computer_key_down"></span>[`computer_key_down`](/cua-cli/reference/mcp-tools/computer#computer_key_down) | Hold a key. |
-| <span id="computer_key_up"></span>[`computer_key_up`](/cua-cli/reference/mcp-tools/computer#computer_key_up) | Release a key. |
-| <span id="computer_hotkey"></span>[`computer_hotkey`](/cua-cli/reference/mcp-tools/computer#computer_hotkey) | Press a shortcut such as ctrl+c or cmd+shift+s. |
-| <span id="computer_scroll"></span>[`computer_scroll`](/cua-cli/reference/mcp-tools/computer#computer_scroll) | Scroll up, down, left or right. |
-| <span id="computer_drag"></span>[`computer_drag`](/cua-cli/reference/mcp-tools/computer#computer_drag) | Drag between two points. |
-| <span id="computer_clipboard_get"></span>[`computer_clipboard_get`](/cua-cli/reference/mcp-tools/computer#computer_clipboard_get) | Read clipboard text. |
-| <span id="computer_clipboard_set"></span>[`computer_clipboard_set`](/cua-cli/reference/mcp-tools/computer#computer_clipboard_set) | Set clipboard text. |
-| <span id="computer_file_read"></span>[`computer_file_read`](/cua-cli/reference/mcp-tools/computer#computer_file_read) | Read a text file. |
-| <span id="computer_file_write"></span>[`computer_file_write`](/cua-cli/reference/mcp-tools/computer#computer_file_write) | Write a text file (the Spaces `space_write` implementation, on this sandbox). |
-| <span id="computer_file_list"></span>[`computer_file_list`](/cua-cli/reference/mcp-tools/computer#computer_file_list) | List a directory. |
-| <span id="computer_shell"></span>[`computer_shell`](/cua-cli/reference/mcp-tools/computer#computer_shell) | Run a shell command (sh -c, 120 s timeout; the Spaces `space_bash` implementation, on this sandbox). |
-| <span id="computer_window_list"></span>[`computer_window_list`](/cua-cli/reference/mcp-tools/computer#computer_window_list) | List windows. |
-| <span id="computer_window_open"></span>[`computer_window_open`](/cua-cli/reference/mcp-tools/computer#computer_window_open) | Open a file or URL. |
-| <span id="computer_window_focus"></span>[`computer_window_focus`](/cua-cli/reference/mcp-tools/computer#computer_window_focus) | Focus a window. |
-| <span id="computer_window_unfocus"></span>[`computer_window_unfocus`](/cua-cli/reference/mcp-tools/computer#computer_window_unfocus) | Remove focus from the current window (Escape). |
-| <span id="computer_window_minimize"></span>[`computer_window_minimize`](/cua-cli/reference/mcp-tools/computer#computer_window_minimize) | Minimize a window. |
-| <span id="computer_window_maximize"></span>[`computer_window_maximize`](/cua-cli/reference/mcp-tools/computer#computer_window_maximize) | Maximize a window. |
-| <span id="computer_window_close"></span>[`computer_window_close`](/cua-cli/reference/mcp-tools/computer#computer_window_close) | Close a window. |
-| <span id="computer_window_resize"></span>[`computer_window_resize`](/cua-cli/reference/mcp-tools/computer#computer_window_resize) | Resize a window. |
-| <span id="computer_window_move"></span>[`computer_window_move`](/cua-cli/reference/mcp-tools/computer#computer_window_move) | Move a window. |
-| <span id="computer_window_get_info"></span>[`computer_window_get_info`](/cua-cli/reference/mcp-tools/computer#computer_window_get_info) | Get a window's title, position and size. |
-| <span id="computer_launch"></span>[`computer_launch`](/cua-cli/reference/mcp-tools/computer#computer_launch) | Launch an application. |
-| <span id="computer_get_screen_size"></span>[`computer_get_screen_size`](/cua-cli/reference/mcp-tools/computer#computer_get_screen_size) | Primary display size in points. |
-| <span id="computer_get_cursor_position"></span>[`computer_get_cursor_position`](/cua-cli/reference/mcp-tools/computer#computer_get_cursor_position) | Cursor position in points. |
-| <span id="computer_get_current_window"></span>[`computer_get_current_window`](/cua-cli/reference/mcp-tools/computer#computer_get_current_window) | The focused window's id and title. |
-| <span id="computer_get_accessibility_tree"></span>[`computer_get_accessibility_tree`](/cua-cli/reference/mcp-tools/computer#computer_get_accessibility_tree) | Accessibility tree of the focused (or given) window. |
-| <span id="computer_accessibility_act"></span>[`computer_accessibility_act`](/cua-cli/reference/mcp-tools/computer#computer_accessibility_act) | Act on an accessibility element (press, focus, set_value, ...). |
-
-## Skills tools
-
-List, read, record and delete skills (recorded demonstrations). [Reference](/cua-cli/reference/mcp-tools/skills).
-
-| Tool | Description |
-| --- | --- |
-| <span id="skills_list"></span>[`skills_list`](/cua-cli/reference/mcp-tools/skills#skills_list) | List recorded skills. |
-| <span id="skills_read"></span>[`skills_read`](/cua-cli/reference/mcp-tools/skills#skills_read) | Read a skill and its steps. |
-| <span id="skills_delete"></span>[`skills_delete`](/cua-cli/reference/mcp-tools/skills#skills_delete) | Delete a skill. |
-| <span id="skills_record"></span>[`skills_record`](/cua-cli/reference/mcp-tools/skills#skills_record) | How to record a skill (recording is interactive: cua skills record). |
-
-## Permissions
-
-Tools are gated by `--permissions` (or `CUA_MCP_PERMISSIONS`), a comma-separated list of permissions and groups; the default is `all`. Each group has an `all` and a `readonly` form (`sandbox:readonly`); each tool lists its own permission.
-
-| Group | Grants | `:readonly` grants |
-| --- | --- | --- |
-| `computer:all` | 12 permissions | `computer:screenshot` |
-| `images:all` | `images:list` | `images:list` |
-| `sandbox:all` | 10 permissions | `sandbox:list`, `sandbox:get` |
-| `skills:all` | `skills:list`, `skills:read`, `skills:record`, `skills:delete` | `skills:list`, `skills:read` |
-| `spaces:all` | 86 permissions | 28 permissions |
-| `teleport:all` | `teleport:browser` | none |
diff --git a/docs/content/docs/cua-cli/reference/mcp-tools/meta.json b/docs/content/docs/cua-cli/reference/mcp-tools/meta.json
deleted file mode 100644
index 0096a28964..0000000000
--- a/docs/content/docs/cua-cli/reference/mcp-tools/meta.json
+++ /dev/null
@@ -1,12 +0,0 @@
-{
- "title": "MCP tools",
- "pages": [
- "index",
- "spaces",
- "images",
- "sandbox",
- "teleport",
- "computer",
- "skills"
- ]
-}
diff --git a/docs/content/docs/cua-cli/reference/mcp-tools/sandbox.mdx b/docs/content/docs/cua-cli/reference/mcp-tools/sandbox.mdx
deleted file mode 100644
index 61134e0815..0000000000
--- a/docs/content/docs/cua-cli/reference/mcp-tools/sandbox.mdx
+++ /dev/null
@@ -1,203 +0,0 @@
----
-title: "Sandbox tools"
-description: "Create and manage sandboxes, local or on your own machines."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-cli
- Source: cua dump-docs --type mcp
- Version: 0.5.0
-*/}
-
-| Tool | Description |
-| --- | --- |
-| [`sandbox_list`](#sandbox_list) | List sandboxes: local and direct ones by default, each row with location (local or direct). |
-| [`sandbox_create`](#sandbox_create) | Create a sandbox from any image. |
-| [`sandbox_get`](#sandbox_get) | Get details for a sandbox. |
-| [`sandbox_start`](#sandbox_start) | Start (resume) a sandbox. |
-| [`sandbox_stop`](#sandbox_stop) | Stop (suspend) a sandbox. |
-| [`sandbox_restart`](#sandbox_restart) | Restart a sandbox. |
-| [`sandbox_suspend`](#sandbox_suspend) | Suspend a sandbox. |
-| [`sandbox_delete`](#sandbox_delete) | Delete a sandbox. |
-| [`sandbox_view`](#sandbox_view) | Get a browser link to the sandbox desktop in the cua-spacesd HTML5 viewer (video, audio, input, clipboard, files). |
-| [`sandbox_vnc`](#sandbox_vnc) | Deprecated: use sandbox_view. |
-| [`sandbox_open_browser`](#sandbox_open_browser) | Launch Chromium with a fresh throwaway profile inside an existing sandbox (an image with cua-spacesd and Chromium, see images_list), bind it and optionally open a URL. |
-
-Served by `cua mcp`; see [MCP tools](/cua-cli/reference/mcp-tools) for every tool.
-
-## `sandbox_list`
-
-List sandboxes: local and direct ones by default, each row with location (local or direct). Pass location to list only one kind.
-
-Permission: `sandbox:list`.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="sandbox_list--location"></span>`location` | `"local" \| "direct"` | | Only sandboxes in this location: local or direct (default: all). |
-
-## `sandbox_create`
-
-Create a sandbox from any image. `on` says where (local, the default unless the user configured another with `cua config set default.on`), `kind` what (auto, container, vm) and `runtime` which engine (auto, or gvisor, runc, qemu, lume); an impossible combination fails and lists the valid values. To browse the web, pass browser=true (and optionally url): it starts the canonical Linux image, registers it as a Space, launches Chromium with a throwaway profile inside it and returns the space, session, target_id and tab_id to pass to call_tool with the in-sandbox browser tools (browser_navigate, get_browser_state, browser_click, browser_type). Pass command, env and services to run a server in it, for example an MCP server: services &#123;"mcp": 8765&#125;. Without browser=true it does not register a Space: to reach its MCP server with list_tools/call_tool (service="mcp"), use create_space instead (same arguments), or add this one with add_space (address local:&lt;name&gt;).
-
-Permission: `sandbox:create`.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="sandbox_create--browser"></span>`browser` | `boolean` | | Start a browser in it, ready for the cua-driver browser tools (default image: the canonical Linux image). |
-| <span id="sandbox_create--command"></span>`command` | `string[]` | | Entrypoint override (argv), for example ["python", "-m", "my_mcp"]. |
-| <span id="sandbox_create--env"></span>`env` | `object` | | Environment variables (string values). |
-| <span id="sandbox_create--image"></span>`image` | `string` | | Image reference, any registry (overrides os_type). |
-| <span id="sandbox_create--kind"></span>`kind` | `"auto" \| "container" \| "vm"` | | What kind of machine: auto (default; from the image), container or vm. |
-| <span id="sandbox_create--name"></span>`name` | `string` | | Sandbox name. |
-| <span id="sandbox_create--on"></span>`on` | `string` | | Where it runs: local (default: the user's default location, else local). |
-| <span id="sandbox_create--os_type"></span>`os_type` | `string` | | linux (default) or macos. |
-| <span id="sandbox_create--runtime"></span>`runtime` | `string` | | Which engine: auto (default) or one the location offers for the kind (gvisor, runc, qemu, lume). |
-| <span id="sandbox_create--services"></span>`services` | `object` | | Named services: name to guest port, for example &#123;"mcp": 8765&#125;; each is probed for readiness. |
-| <span id="sandbox_create--url"></span>`url` | `string` | | With browser=true: open this URL first. |
-
-## `sandbox_get`
-
-Get details for a sandbox.
-
-Permission: `sandbox:get`.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="sandbox_get--name"></span>`name` | `string` | required | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations. |
-
-**Example arguments**
-
-```json
-{"name":"<name>"}
-```
-
-## `sandbox_start`
-
-Start (resume) a sandbox.
-
-Permission: `sandbox:start`.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="sandbox_start--name"></span>`name` | `string` | required | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations. |
-
-**Example arguments**
-
-```json
-{"name":"<name>"}
-```
-
-## `sandbox_stop`
-
-Stop (suspend) a sandbox.
-
-Permission: `sandbox:stop`.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="sandbox_stop--name"></span>`name` | `string` | required | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations. |
-
-**Example arguments**
-
-```json
-{"name":"<name>"}
-```
-
-## `sandbox_restart`
-
-Restart a sandbox.
-
-Permission: `sandbox:restart`.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="sandbox_restart--name"></span>`name` | `string` | required | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations. |
-
-**Example arguments**
-
-```json
-{"name":"<name>"}
-```
-
-## `sandbox_suspend`
-
-Suspend a sandbox.
-
-Permission: `sandbox:suspend`.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="sandbox_suspend--name"></span>`name` | `string` | required | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations. |
-
-**Example arguments**
-
-```json
-{"name":"<name>"}
-```
-
-## `sandbox_delete`
-
-Delete a sandbox.
-
-Permission: `sandbox:delete`.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="sandbox_delete--name"></span>`name` | `string` | required | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations. |
-
-**Example arguments**
-
-```json
-{"name":"<name>"}
-```
-
-## `sandbox_view`
-
-Get a browser link to the sandbox desktop in the cua-spacesd HTML5 viewer (video, audio, input, clipboard, files). The link expires after an hour.
-
-Permission: `sandbox:view`.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="sandbox_view--name"></span>`name` | `string` | required | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations. |
-
-**Example arguments**
-
-```json
-{"name":"<name>"}
-```
-
-## `sandbox_vnc`
-
-Deprecated: use sandbox_view. Returns the same viewer link.
-
-Permission: `sandbox:view`.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="sandbox_vnc--name"></span>`name` | `string` | required | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations. |
-
-**Example arguments**
-
-```json
-{"name":"<name>"}
-```
-
-## `sandbox_open_browser`
-
-Launch Chromium with a fresh throwaway profile inside an existing sandbox (an image with cua-spacesd and Chromium, see images_list), bind it and optionally open a URL. Returns the space, session, target_id and tab_id for call_tool with the in-sandbox browser tools. sandbox_create with browser=true already does this.
-
-Permission: `sandbox:browser`.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="sandbox_open_browser--name"></span>`name` | `string` | required | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations. |
-| <span id="sandbox_open_browser--session"></span>`session` | `string` | | cua-driver session label to use on every later browser call (default: browse). |
-| <span id="sandbox_open_browser--url"></span>`url` | `string` | | Open this URL first. |
-
-**Example arguments**
-
-```json
-{"name":"<name>"}
-```
diff --git a/docs/content/docs/cua-cli/reference/mcp-tools/skills.mdx b/docs/content/docs/cua-cli/reference/mcp-tools/skills.mdx
deleted file mode 100644
index b6624b2684..0000000000
--- a/docs/content/docs/cua-cli/reference/mcp-tools/skills.mdx
+++ /dev/null
@@ -1,76 +0,0 @@
----
-title: "Skills tools"
-description: "List, read, record and delete skills (recorded demonstrations)."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-cli
- Source: cua dump-docs --type mcp
- Version: 0.5.0
-*/}
-
-| Tool | Description |
-| --- | --- |
-| [`skills_list`](#skills_list) | List recorded skills. |
-| [`skills_read`](#skills_read) | Read a skill and its steps. |
-| [`skills_delete`](#skills_delete) | Delete a skill. |
-| [`skills_record`](#skills_record) | How to record a skill (recording is interactive: cua skills record). |
-
-Served by `cua mcp`; see [MCP tools](/cua-cli/reference/mcp-tools) for every tool.
-
-## `skills_list`
-
-List recorded skills.
-
-Permission: `skills:list`.
-
-No parameters.
-
-## `skills_read`
-
-Read a skill and its steps.
-
-Permission: `skills:read`.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="skills_read--name"></span>`name` | `string` | required | Skill name. |
-
-**Example arguments**
-
-```json
-{"name":"<name>"}
-```
-
-## `skills_delete`
-
-Delete a skill.
-
-Permission: `skills:delete`.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="skills_delete--name"></span>`name` | `string` | required | Skill name. |
-
-**Example arguments**
-
-```json
-{"name":"<name>"}
-```
-
-## `skills_record`
-
-How to record a skill (recording is interactive: cua skills record).
-
-Permission: `skills:record`.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="skills_record--name"></span>`name` | `string` | required | Skill name. |
-
-**Example arguments**
-
-```json
-{"name":"<name>"}
-```
diff --git a/docs/content/docs/cua-cli/reference/mcp-tools/spaces.mdx b/docs/content/docs/cua-cli/reference/mcp-tools/spaces.mdx
deleted file mode 100644
index f0c29af5e6..0000000000
--- a/docs/content/docs/cua-cli/reference/mcp-tools/spaces.mdx
+++ /dev/null
@@ -1,185 +0,0 @@
----
-title: "Spaces tools"
-description: "The Spaces contract: register, claim and release Spaces, run commands, move files, stream, run agents and teleport."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-cli
- Source: cua dump-docs --type mcp
- Version: 0.5.0
-*/}
-
-These tools are the [Spaces contract](/spaces/reference), with the same names and schemas on every surface. Each links to its entry there (parameters, result, errors, providers, metering); `cua mcp` gates each one behind the permission `spaces:<tool>`.
-
-## Space lifecycle
-
-Full entries: [Space lifecycle](/spaces/reference/lifecycle).
-
-| Tool | Description |
-| --- | --- |
-| <span id="add_space"></span>[`add_space`](/spaces/reference/lifecycle#add_space) | Add an existing machine as a Space by address and token. |
-| <span id="remove_space"></span>[`remove_space`](/spaces/reference/lifecycle#remove_space) | Forget a registered Space without touching it. |
-| <span id="list_spaces"></span>[`list_spaces`](/spaces/reference/lifecycle#list_spaces) | List the Spaces this connection can see. |
-| <span id="create_space"></span>[`create_space`](/spaces/reference/lifecycle#create_space) | Create a Space: a new sandbox on this machine, on one of your machines, or in the cloud. |
-| <span id="delete_space"></span>[`delete_space`](/spaces/reference/lifecycle#delete_space) | Delete a Space's sandbox and forget it. |
-| <span id="stop_space"></span>[`stop_space`](/spaces/reference/lifecycle#stop_space) | Turn a Space off: suspend it (memory kept) or stop it (disk kept). |
-| <span id="start_space"></span>[`start_space`](/spaces/reference/lifecycle#start_space) | Turn a Space back on: resume or boot it. |
-
-## Commands and files
-
-Full entries: [Commands and files](/spaces/reference/commands-and-files).
-
-| Tool | Description |
-| --- | --- |
-| <span id="space_bash"></span>[`space_bash`](/spaces/reference/commands-and-files#space_bash) | Run a shell command inside the Space. |
-| <span id="space_write"></span>[`space_write`](/spaces/reference/commands-and-files#space_write) | Write literal text to a path inside the Space. |
-| <span id="upload"></span>[`upload`](/spaces/reference/commands-and-files#upload) | Send a local file or folder into the Space. |
-| <span id="send_file"></span>[`send_file`](/spaces/reference/commands-and-files#send_file) | Send a host file or folder into the Space's Downloads, verified by sha256 on arrival. |
-| <span id="download"></span>[`download`](/spaces/reference/commands-and-files#download) | Fetch a file or folder out of the Space. |
-
-## Streams and display
-
-Full entries: [Streams and display](/spaces/reference/streams-and-display).
-
-| Tool | Description |
-| --- | --- |
-| <span id="stream_endpoint"></span>[`stream_endpoint`](/spaces/reference/streams-and-display#stream_endpoint) | Return a ticketed media endpoint for the Space's desktop or one window. |
-| <span id="list_space_windows"></span>[`list_space_windows`](/spaces/reference/streams-and-display#list_space_windows) | List the windows open inside the Space. |
-| <span id="stream_space_window"></span>[`stream_space_window`](/spaces/reference/streams-and-display#stream_space_window) | Draw one Space window on the operator's desktop. |
-| <span id="show_space_pip"></span>[`show_space_pip`](/spaces/reference/streams-and-display#show_space_pip) | Pin the Space as picture-in-picture on the operator's desktop. |
-| <span id="hide_space_pip"></span>[`hide_space_pip`](/spaces/reference/streams-and-display#hide_space_pip) | Unpin the picture-in-picture window. |
-| <span id="open_space_viewer"></span>[`open_space_viewer`](/spaces/reference/streams-and-display#open_space_viewer) | Open the full Space viewer on the operator's desktop. |
-
-## Services
-
-Full entries: [Services](/spaces/reference/services).
-
-| Tool | Description |
-| --- | --- |
-| <span id="list_tools"></span>[`list_tools`](/spaces/reference/services#list_tools) | List the MCP services and tools reachable inside the Space. |
-| <span id="call_tool"></span>[`call_tool`](/spaces/reference/services#call_tool) | Call a service tool inside the Space. |
-
-## Agents
-
-Full entries: [Agents](/spaces/reference/agents).
-
-| Tool | Description |
-| --- | --- |
-| <span id="agent_start"></span>[`agent_start`](/spaces/reference/agents#agent_start) | Start a coding agent in the Space. |
-| <span id="agent_message"></span>[`agent_message`](/spaces/reference/agents#agent_message) | Send a follow-up to an agent run. |
-| <span id="agent_events"></span>[`agent_events`](/spaces/reference/agents#agent_events) | Read an agent run's events after a cursor. |
-| <span id="agent_status"></span>[`agent_status`](/spaces/reference/agents#agent_status) | Read an agent run's status and result. |
-| <span id="agent_interrupt"></span>[`agent_interrupt`](/spaces/reference/agents#agent_interrupt) | Interrupt an agent run's current turn. |
-| <span id="agent_stop"></span>[`agent_stop`](/spaces/reference/agents#agent_stop) | Stop an agent run. |
-| <span id="agent_list"></span>[`agent_list`](/spaces/reference/agents#agent_list) | List agent runs in the Space. |
-| <span id="agent_capabilities"></span>[`agent_capabilities`](/spaces/reference/agents#agent_capabilities) | Report what the agent harnesses support. |
-
-## Persistent agents
-
-Full entries: [Persistent agents](/spaces/reference/persistent-agents).
-
-| Tool | Description |
-| --- | --- |
-| <span id="persistent_agent_create"></span>[`persistent_agent_create`](/spaces/reference/persistent-agents#persistent_agent_create) | Create a named agent whose memory outlives its Space. |
-| <span id="persistent_agent_list"></span>[`persistent_agent_list`](/spaces/reference/persistent-agents#persistent_agent_list) | List persistent agents. |
-| <span id="persistent_agent_remove"></span>[`persistent_agent_remove`](/spaces/reference/persistent-agents#persistent_agent_remove) | Forget a persistent agent. |
-| <span id="persistent_agent_send"></span>[`persistent_agent_send`](/spaces/reference/persistent-agents#persistent_agent_send) | Give a persistent agent a turn. |
-| <span id="persistent_agent_save"></span>[`persistent_agent_save`](/spaces/reference/persistent-agents#persistent_agent_save) | Save a persistent agent's home now. |
-| <span id="agent_pause"></span>[`agent_pause`](/spaces/reference/persistent-agents#agent_pause) | Pause a persistent agent: its run, its routines and its Space. |
-| <span id="agent_resume"></span>[`agent_resume`](/spaces/reference/persistent-agents#agent_resume) | Resume a paused persistent agent. |
-| <span id="routine_add"></span>[`routine_add`](/spaces/reference/persistent-agents#routine_add) | Schedule a recurring turn for a persistent agent. |
-| <span id="routine_list"></span>[`routine_list`](/spaces/reference/persistent-agents#routine_list) | List routines. |
-| <span id="routine_remove"></span>[`routine_remove`](/spaces/reference/persistent-agents#routine_remove) | Delete a routine. |
-| <span id="routine_set_enabled"></span>[`routine_set_enabled`](/spaces/reference/persistent-agents#routine_set_enabled) | Turn a routine on or off. |
-| <span id="notify_user"></span>[`notify_user`](/spaces/reference/persistent-agents#notify_user) | Tell the user something in the Cua app. |
-| <span id="notifications_list"></span>[`notifications_list`](/spaces/reference/persistent-agents#notifications_list) | Read the notifications feed. |
-| <span id="notifications_ack"></span>[`notifications_ack`](/spaces/reference/persistent-agents#notifications_ack) | Mark notifications read. |
-| <span id="computer_access_grant"></span>[`computer_access_grant`](/spaces/reference/persistent-agents#computer_access_grant) | Let a persistent agent use one of the user's computers. |
-| <span id="computer_access_revoke"></span>[`computer_access_revoke`](/spaces/reference/persistent-agents#computer_access_revoke) | Take back a persistent agent's access to a computer. |
-| <span id="computer_access_list"></span>[`computer_access_list`](/spaces/reference/persistent-agents#computer_access_list) | List per-agent computer access. |
-
-## Session teleport
-
-Full entries: [Session teleport](/spaces/reference/teleport).
-
-| Tool | Description |
-| --- | --- |
-| <span id="teleport_manifest"></span>[`teleport_manifest`](/spaces/reference/teleport#teleport_manifest) | Describe what a session teleport would move. |
-| <span id="teleport_app"></span>[`teleport_app`](/spaces/reference/teleport#teleport_app) | Move an app session into the Space. |
-
-## Keyvault
-
-Full entries: [Keyvault](/spaces/reference/keyvault).
-
-| Tool | Description |
-| --- | --- |
-| <span id="request_site_login"></span>[`request_site_login`](/spaces/reference/keyvault#request_site_login) | Sign in to a site in the Space with the user's saved password. |
-
-## Hotspot
-
-Full entries: [Hotspot](/spaces/reference/hotspot).
-
-| Tool | Description |
-| --- | --- |
-| <span id="hotspot_start"></span>[`hotspot_start`](/spaces/reference/hotspot#hotspot_start) | Start sharing this machine's network with a Space. |
-| <span id="hotspot_stop"></span>[`hotspot_stop`](/spaces/reference/hotspot#hotspot_stop) | Stop sharing this machine's network. |
-| <span id="hotspot_status"></span>[`hotspot_status`](/spaces/reference/hotspot#hotspot_status) | Report which Spaces are sharing this machine's network, with counters. |
-
-## Cua Volume
-
-Full entries: [Cua Volume](/spaces/reference/volume).
-
-| Tool | Description |
-| --- | --- |
-| <span id="volume_ls"></span>[`volume_ls`](/spaces/reference/volume#volume_ls) | List a folder of the Cua Volume. |
-| <span id="volume_read"></span>[`volume_read`](/spaces/reference/volume#volume_read) | Read a file from the Cua Volume. |
-| <span id="volume_write"></span>[`volume_write`](/spaces/reference/volume#volume_write) | Write a file to the Cua Volume. |
-| <span id="volume_delete"></span>[`volume_delete`](/spaces/reference/volume#volume_delete) | Delete a file from the Cua Volume. |
-| <span id="volume_history"></span>[`volume_history`](/spaces/reference/volume#volume_history) | List a Cua Volume file's versions. |
-| <span id="volume_restore"></span>[`volume_restore`](/spaces/reference/volume#volume_restore) | Restore an old version of a Cua Volume file. |
-| <span id="volume_grant"></span>[`volume_grant`](/spaces/reference/volume#volume_grant) | Grant an agent or Space more Cua Volume access. |
-| <span id="volume_revoke"></span>[`volume_revoke`](/spaces/reference/volume#volume_revoke) | Revoke a Cua Volume grant. |
-| <span id="volume_grants"></span>[`volume_grants`](/spaces/reference/volume#volume_grants) | List Cua Volume grants. |
-| <span id="volume_request_access"></span>[`volume_request_access`](/spaces/reference/volume#volume_request_access) | Ask the user for more Cua Volume access. |
-| <span id="volume_requests"></span>[`volume_requests`](/spaces/reference/volume#volume_requests) | List Cua Volume access requests waiting for the user. |
-| <span id="volume_approve"></span>[`volume_approve`](/spaces/reference/volume#volume_approve) | Approve a Cua Volume access request. |
-| <span id="volume_deny"></span>[`volume_deny`](/spaces/reference/volume#volume_deny) | Decline a Cua Volume access request. |
-| <span id="volume_audit"></span>[`volume_audit`](/spaces/reference/volume#volume_audit) | Read the Cua Volume audit log. |
-| <span id="volume_storage"></span>[`volume_storage`](/spaces/reference/volume#volume_storage) | Show where the Cua Volume keeps its bytes. |
-| <span id="volume_storage_set"></span>[`volume_storage_set`](/spaces/reference/volume#volume_storage_set) | Test or change where the Cua Volume keeps its bytes. |
-| <span id="volume_mount_status"></span>[`volume_mount_status`](/spaces/reference/volume#volume_mount_status) | Show whether the Cua Volume is mounted as a volume. |
-| <span id="volume_mount"></span>[`volume_mount`](/spaces/reference/volume#volume_mount) | Mount the Cua Volume as a volume. |
-| <span id="volume_unmount"></span>[`volume_unmount`](/spaces/reference/volume#volume_unmount) | Unmount the Cua Volume volume. |
-| <span id="volume_sync_status"></span>[`volume_sync_status`](/spaces/reference/volume#volume_sync_status) | Show the Cua Volume's sync state across devices. |
-| <span id="volume_sync_events"></span>[`volume_sync_events`](/spaces/reference/volume#volume_sync_events) | Wait for Cua Volume sync events. |
-| <span id="volume_sync_resolve"></span>[`volume_sync_resolve`](/spaces/reference/volume#volume_sync_resolve) | Mark a Cua Volume sync conflict as seen. |
-| <span id="volume_cache_stats"></span>[`volume_cache_stats`](/spaces/reference/volume#volume_cache_stats) | Show the Cua Volume block cache. |
-| <span id="volume_cache_set"></span>[`volume_cache_set`](/spaces/reference/volume#volume_cache_set) | Set the Cua Volume block cache's size cap. |
-| <span id="volume_cache_clear"></span>[`volume_cache_clear`](/spaces/reference/volume#volume_cache_clear) | Clear the Cua Volume block cache. |
-
-## Sharing
-
-Full entries: [Sharing](/spaces/reference/sharing).
-
-| Tool | Description |
-| --- | --- |
-| <span id="share_space"></span>[`share_space`](/spaces/reference/sharing#share_space) | Let another cua.ai account watch or edit a Space. |
-| <span id="unshare_space"></span>[`unshare_space`](/spaces/reference/sharing#unshare_space) | Stop sharing a Space with an account, or with everyone. |
-| <span id="space_shares"></span>[`space_shares`](/spaces/reference/sharing#space_shares) | List who a Space is shared with. |
-| <span id="relay_register_space"></span>[`relay_register_space`](/spaces/reference/sharing#relay_register_space) | Publish a Space on the relay for the account's other devices. |
-| <span id="relay_unregister_space"></span>[`relay_unregister_space`](/spaces/reference/sharing#relay_unregister_space) | Take a Space off the relay. |
-
-## Your cloud
-
-Full entries: [Your cloud](/spaces/reference/cloud).
-
-| Tool | Description |
-| --- | --- |
-| <span id="cloud_status"></span>[`cloud_status`](/spaces/reference/cloud#cloud_status) | List your clouds (AWS, Google Cloud, Modal): found credentials, the connected account and region, what each can run at what hourly cost, and what Cua created there. |
-| <span id="cloud_connect"></span>[`cloud_connect`](/spaces/reference/cloud#cloud_connect) | Connect a cloud account Spaces can be created in. |
-| <span id="cloud_test"></span>[`cloud_test`](/spaces/reference/cloud#cloud_test) | Check a cloud account without creating anything. |
-| <span id="cloud_disconnect"></span>[`cloud_disconnect`](/spaces/reference/cloud#cloud_disconnect) | Forget a connected cloud account. |
-| <span id="cloud_sweep"></span>[`cloud_sweep`](/spaces/reference/cloud#cloud_sweep) | Find and delete what Cua left in your clouds. |
-
-Served by `cua mcp`; see [MCP tools](/cua-cli/reference/mcp-tools) for every tool.
diff --git a/docs/content/docs/cua-cli/reference/mcp-tools/teleport.mdx b/docs/content/docs/cua-cli/reference/mcp-tools/teleport.mdx
deleted file mode 100644
index ba9be0e219..0000000000
--- a/docs/content/docs/cua-cli/reference/mcp-tools/teleport.mdx
+++ /dev/null
@@ -1,34 +0,0 @@
----
-title: "Teleport tools"
-description: "Move a signed-in browser session, per site, into a sandbox through the Cua Keyvault, with consent."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-cli
- Source: cua dump-docs --type mcp
- Version: 0.5.0
-*/}
-
-Served by `cua mcp`; see [MCP tools](/cua-cli/reference/mcp-tools) for every tool.
-
-## `teleport_browser_session`
-
-Teleport the user's signed-in session for specific sites (for example github.com) from their Firefox or Chrome into a sandbox, through the Cua Keyvault. Name each site: nothing is selected by default and there is no all-sessions option. The first call moves nothing: it files a Keyvault request and returns consent_required, a summary and a request_id. Show the summary to the user; they approve it in Cua (Touch ID or password). Then call again with the request_id to move exactly those sites. Use it only when the user asks to browse as themselves.
-
-Permission: `teleport:browser`.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="teleport_browser_session--browser"></span>`browser` | `"firefox" \| "chrome"` | required | firefox or chrome (chromium, brave and edge profiles use chrome). |
-| <span id="teleport_browser_session--duration_minutes"></span>`duration_minutes` | `integer` | | How long the sandbox may keep them (default 15, at most 1440). |
-| <span id="teleport_browser_session--name"></span>`name` | `string` | required | Sandbox ref (local:&lt;name&gt;, direct:&lt;host:port&gt;) or a name unique across locations. |
-| <span id="teleport_browser_session--reason"></span>`reason` | `string` | | Why, in a few words; shown to the user as unverified. |
-| <span id="teleport_browser_session--request_id"></span>`request_id` | `string` | | The request_id from the first call, after the user approved it in Cua. |
-| <span id="teleport_browser_session--sites"></span>`sites` | `string[]` | required | The exact sites to teleport, for example ["github.com"]. |
-
-**Example arguments**
-
-```json
-{"name":"<name>","browser":"firefox","sites":["<site>"]}
-```
diff --git a/docs/content/docs/cua-driver/reference/cli/config.mdx b/docs/content/docs/cua-driver/reference/cli/config.mdx
deleted file mode 100644
index 9c8e1d9be1..0000000000
--- a/docs/content/docs/cua-driver/reference/cli/config.mdx
+++ /dev/null
@@ -1,480 +0,0 @@
----
-title: "Configuration"
-description: "Driver configuration, telemetry, cursor themes and cursor motion."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-driver
- Source: cua-driver dump-docs --type cli
- Version: 0.36.0
-*/}
-
-| Command | Description |
-| --- | --- |
-| [`cua-driver config`](#cua-driver-config) | Read or mutate persistent driver configuration. |
-| [`cua-driver config show`](#cua-driver-config-show) | Print the full config. |
-| [`cua-driver config get`](#cua-driver-config-get) | Print one config key. |
-| [`cua-driver config set`](#cua-driver-config-set) | Set one config key. |
-| [`cua-driver config reset`](#cua-driver-config-reset) | Reset config to defaults. |
-| [`cua-driver telemetry`](#cua-driver-telemetry) | Inspect or change content-free product telemetry. |
-| [`cua-driver telemetry enable`](#cua-driver-telemetry-enable) | Persistently enable telemetry. |
-| [`cua-driver telemetry disable`](#cua-driver-telemetry-disable) | Persistently disable every telemetry request. |
-| [`cua-driver telemetry status`](#cua-driver-telemetry-status) | Show the effective setting and redacted identity state. |
-| [`cua-driver telemetry reset-id`](#cua-driver-telemetry-reset-id) | Erase the installation ID and event markers. |
-| [`cua-driver telemetry inspect`](#cua-driver-telemetry-inspect) | Build a fixed event payload without sending it. |
-| [`cua-driver cursor-theme`](#cua-driver-cursor-theme) | Validate, compile, inspect, preview, install, or remove a local cursor theme. |
-| [`cua-driver cursor-theme validate`](#cua-driver-cursor-theme-validate) | Validate a bounded dotLottie source archive. |
-| [`cua-driver cursor-theme build`](#cua-driver-cursor-theme-build) | Compile a validated dotLottie archive into a bounded .cua-theme artifact. |
-| [`cua-driver cursor-theme inspect`](#cua-driver-cursor-theme-inspect) | Inspect metadata in a compiled .cua-theme artifact. |
-| [`cua-driver cursor-theme preview`](#cua-driver-cursor-theme-preview) | Render a compiled theme's representative still frames to a directory. |
-| [`cua-driver cursor-theme install`](#cua-driver-cursor-theme-install) | Install a compiled theme into the current user's theme store. |
-| [`cua-driver cursor-theme list`](#cua-driver-cursor-theme-list) | List the built-in and installed cursor themes. |
-| [`cua-driver cursor-theme uninstall`](#cua-driver-cursor-theme-uninstall) | Remove a custom theme from the current user's theme store. |
-| [`cua-driver cursor`](#cua-driver-cursor) | Configure a session's agent cursor from the command line. |
-| [`cua-driver cursor motion`](#cua-driver-cursor-motion) | Set the cursor's motion style, timing and effects. |
-
-Every command also accepts the [global options](/cua-driver/reference/cli#global-options).
-
-## `cua-driver config`
-
-Read or mutate persistent driver configuration.
-
-Without a subcommand, prints the full config.
-
-```text output
-cua-driver config [OPTIONS] [COMMAND]
-```
-
-Without a subcommand, runs `cua-driver config show`.
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-driver-config--socket"></span>`--socket` | string | | Override the daemon socket or named-pipe path. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-config"
-# Print the full config
-cua-driver config
-```
-
-### `cua-driver config show`
-
-Print the full config.
-
-```text output
-cua-driver config show
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-config-show"
-# Print the full config
-cua-driver config show
-```
-
-### `cua-driver config get`
-
-Print one config key.
-
-```text output
-cua-driver config get <key>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<key>` | string | required | Config key to read. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-config-get"
-# Print one key
-cua-driver config get max_image_dimension
-```
-
-### `cua-driver config set`
-
-Set one config key.
-
-Cursor motion defaults are saved keys that apply to sessions started afterwards: cursor.motion.style (signature_arc, spring_settle, magnetic, comet_swoop, adaptive, classic), cursor.motion.timing (native, fitts, fixed) and cursor.motion.effects.&lt;trail|glow|magnet|ripple|squish&gt; (on, off, default). Use default for a key to clear it, or cursor.motion default to clear all. A start_session cursor_motion or a set_agent_cursor_motion call overrides the saved default. cursor.badges (minimal, verbose, off) sets the agent cursor badge for every cursor at once; minimal is the default.
-
-```text output
-cua-driver config set <key> <value>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<key>` | string | required | Config key to write. |
-| `<value>` | string | required | Value to store. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-config-set"
-# Downscale screenshots to at most 1568 px
-cua-driver config set max_image_dimension 1568
-
-# Make magnetic the default cursor motion for new sessions
-cua-driver config set cursor.motion.style magnetic
-
-# Scale cursor move time with distance and target size
-cua-driver config set cursor.motion.timing fitts
-
-# Drop the 600 ms floor of the default steady timing
-cua-driver config set cursor.motion.timing native
-
-# Turn the cursor trail on by default
-cua-driver config set cursor.motion.effects.trail true
-```
-
-### `cua-driver config reset`
-
-Reset config to defaults.
-
-```text output
-cua-driver config reset
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-config-reset"
-# Restore the defaults
-cua-driver config reset
-```
-
-## `cua-driver telemetry`
-
-Inspect or change content-free product telemetry.
-
-Telemetry is default-on. Disable retains the pseudonymous installation ID; reset-id erases the ID and event markers while preserving the preference.
-
-```text output
-cua-driver telemetry <COMMAND>
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-telemetry"
-# Show the effective telemetry setting
-cua-driver telemetry status
-```
-
-### `cua-driver telemetry enable`
-
-Persistently enable telemetry.
-
-```text output
-cua-driver telemetry enable
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-telemetry-enable"
-# Enable telemetry
-cua-driver telemetry enable
-```
-
-### `cua-driver telemetry disable`
-
-Persistently disable every telemetry request.
-
-Retains the local installation ID.
-
-```text output
-cua-driver telemetry disable
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-telemetry-disable"
-# Disable every telemetry request
-cua-driver telemetry disable
-```
-
-### `cua-driver telemetry status`
-
-Show the effective setting and redacted identity state.
-
-```text output
-cua-driver telemetry status [OPTIONS]
-```
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-driver-telemetry-status--json"></span>`--json` | boolean | `false` | Emit JSON. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-telemetry-status"
-# Show the setting as JSON
-cua-driver telemetry status --json
-```
-
-### `cua-driver telemetry reset-id`
-
-Erase the installation ID and event markers.
-
-The persisted enabled/disabled preference is retained.
-
-```text output
-cua-driver telemetry reset-id
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-telemetry-reset-id"
-# Erase the installation ID
-cua-driver telemetry reset-id
-```
-
-### `cua-driver telemetry inspect`
-
-Build a fixed event payload without sending it.
-
-The distinct ID is replaced with a redacted placeholder.
-
-```text output
-cua-driver telemetry inspect [OPTIONS] <event>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<event>` | string | required | Fixed telemetry event name. |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-driver-telemetry-inspect--json"></span>`--json` | boolean | `false` | Emit JSON (the only output format; pass it for forward compatibility). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-telemetry-inspect"
-# Show the payload of one event without sending it
-cua-driver telemetry inspect cua_driver_cli_completed --json
-```
-
-## `cua-driver cursor-theme`
-
-Validate, compile, inspect, preview, install, or remove a local cursor theme.
-
-This is a trusted local authoring workflow. Agent-facing tools may select an installed theme id, but cannot install source or compiled theme data.
-
-```text output
-cua-driver cursor-theme <COMMAND>
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-cursor-theme"
-# List cursor themes
-cua-driver cursor-theme list
-```
-
-### `cua-driver cursor-theme validate`
-
-Validate a bounded dotLottie source archive.
-
-```text output
-cua-driver cursor-theme validate [OPTIONS] <source>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<source>` | path | required | Path to the source .lottie archive. |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-driver-cursor-theme-validate--development"></span>`--development` | boolean | `false` | Allow the reserved com.example development namespace. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-cursor-theme-validate"
-# Validate a source archive
-cua-driver cursor-theme validate my-cursor.lottie
-```
-
-### `cua-driver cursor-theme build`
-
-Compile a validated dotLottie archive into a bounded .cua-theme artifact.
-
-```text output
-cua-driver cursor-theme build [OPTIONS] <source>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<source>` | path | required | Path to the source .lottie archive. |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-driver-cursor-theme-build--output"></span>`--output` | path | required | Output .cua-theme path. |
-| <span id="cua-driver-cursor-theme-build--development"></span>`--development` | boolean | `false` | Allow the reserved com.example development namespace. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-cursor-theme-build"
-# Compile a theme
-cua-driver cursor-theme build my-cursor.lottie --output my-cursor.cua-theme
-```
-
-### `cua-driver cursor-theme inspect`
-
-Inspect metadata in a compiled .cua-theme artifact.
-
-```text output
-cua-driver cursor-theme inspect [OPTIONS] <theme>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<theme>` | path | required | Path to the compiled .cua-theme artifact. |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-driver-cursor-theme-inspect--json"></span>`--json` | boolean | `false` | Emit machine-readable JSON. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-cursor-theme-inspect"
-# Print a theme's metadata
-cua-driver cursor-theme inspect my-cursor.cua-theme --json
-```
-
-### `cua-driver cursor-theme preview`
-
-Render a compiled theme's representative still frames to a directory.
-
-```text output
-cua-driver cursor-theme preview [OPTIONS] <theme>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<theme>` | path | required | Path to the compiled .cua-theme artifact. |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-driver-cursor-theme-preview--output"></span>`--output` | path | required | Preview output directory. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-cursor-theme-preview"
-# Render still frames
-cua-driver cursor-theme preview my-cursor.cua-theme --output preview
-```
-
-### `cua-driver cursor-theme install`
-
-Install a compiled theme into the current user's theme store.
-
-```text output
-cua-driver cursor-theme install <theme>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<theme>` | path | required | Path to the compiled .cua-theme artifact. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-cursor-theme-install"
-# Install a theme
-cua-driver cursor-theme install my-cursor.cua-theme
-```
-
-### `cua-driver cursor-theme list`
-
-List the built-in and installed cursor themes.
-
-```text output
-cua-driver cursor-theme list [OPTIONS]
-```
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-driver-cursor-theme-list--json"></span>`--json` | boolean | `false` | Emit machine-readable JSON. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-cursor-theme-list"
-# List themes as JSON
-cua-driver cursor-theme list --json
-```
-
-### `cua-driver cursor-theme uninstall`
-
-Remove a custom theme from the current user's theme store.
-
-The built-in cua.default theme cannot be removed.
-
-```text output
-cua-driver cursor-theme uninstall <theme-id>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<theme-id>` | string | required | Installed custom theme id. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-cursor-theme-uninstall"
-# Remove an installed theme
-cua-driver cursor-theme uninstall com.example.my-cursor
-```
-
-## `cua-driver cursor`
-
-Configure a session's agent cursor from the command line.
-
-Forwards to the set_agent_cursor_motion tool on the running daemon. Fields you leave out keep their current value.
-
-```text output
-cua-driver cursor <COMMAND>
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-cursor"
-# Use the magnetic cursor motion
-cua-driver cursor motion --session demo --style magnetic
-```
-
-### `cua-driver cursor motion`
-
-Set the cursor's motion style, timing and effects.
-
-Effects take on, off, or default (the style's own choice).
-
-```text output
-cua-driver cursor motion [OPTIONS]
-```
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-driver-cursor-motion--session"></span>`--session` | string | required | Public label of the session that owns the cursor. |
-| <span id="cua-driver-cursor-motion--style"></span>`--style` | string | | signature_arc, spring_settle, magnetic, comet_swoop, adaptive, or classic. |
-| <span id="cua-driver-cursor-motion--timing"></span>`--timing` | string | | native, fitts, or fixed. |
-| <span id="cua-driver-cursor-motion--effects"></span>`--effects` | string | | Comma-separated name=on\|off\|default for trail, glow, magnet, ripple, squish. |
-| <span id="cua-driver-cursor-motion--glide-ms"></span>`--glide-ms` | number | | Move duration in milliseconds for fixed timing (1430 when 0). |
-| <span id="cua-driver-cursor-motion--socket"></span>`--socket` | path | | Override the daemon socket path. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-cursor-motion"
-# Use the comet swoop cursor motion
-cua-driver cursor motion --session demo --style comet_swoop
-
-# Make every move take 900 ms
-cua-driver cursor motion --session demo --timing fixed --glide-ms 900
-
-# Turn off the trail and reset the click ripple
-cua-driver cursor motion --session demo --effects trail=off,ripple=default
-```
-
-## Exit codes
-
-| Code | Meaning |
-| --- | --- |
-| `0` | Success. |
-| `1` | Failure: the daemon is not running or is incompatible, a tool call returned an error, or the operation failed. `call` and direct tool invocations exit with the daemon's result code (1 on a tool error); `update --apply` passes through the installer's status. |
-| `2` | Invalid input: tool arguments that are not valid JSON, an unknown `mcp-config` client, or an `update --apply` refused on a local development install. |
-| `64` | Usage error: an unknown or missing subcommand or argument, or conflicting flags (for example `revoke` without exactly one of `--session` or `--all`, or an authorization flag passed to `mcp`). |
diff --git a/docs/content/docs/cua-driver/reference/cli/daemon.mdx b/docs/content/docs/cua-driver/reference/cli/daemon.mdx
deleted file mode 100644
index 1dee1637b9..0000000000
--- a/docs/content/docs/cua-driver/reference/cli/daemon.mdx
+++ /dev/null
@@ -1,266 +0,0 @@
----
-title: "Daemon"
-description: "Run, stop and inspect the daemon, its sessions and autostart."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-driver
- Source: cua-driver dump-docs --type cli
- Version: 0.36.0
-*/}
-
-| Command | Description |
-| --- | --- |
-| [`cua-driver serve`](#cua-driver-serve) | Run Cua Driver as a long-running daemon. |
-| [`cua-driver stop`](#cua-driver-stop) | Ask the running daemon to exit gracefully. |
-| [`cua-driver status`](#cua-driver-status) | Report whether a Cua Driver daemon is running. |
-| [`cua-driver sessions`](#cua-driver-sessions) | List content-free lifecycle summaries for sessions owned by the daemon runtime. |
-| [`cua-driver sessions list`](#cua-driver-sessions-list) | List live sessions. |
-| [`cua-driver revoke`](#cua-driver-revoke) | Revoke one or all live authorization/session scopes. |
-| [`cua-driver autostart`](#cua-driver-autostart) | Manage platform-native daemon autostart. |
-| [`cua-driver autostart enable`](#cua-driver-autostart-enable) | Register the autostart entry. |
-| [`cua-driver autostart disable`](#cua-driver-autostart-disable) | Remove the autostart entry. |
-| [`cua-driver autostart status`](#cua-driver-autostart-status) | Print whether autostart is registered and running. |
-| [`cua-driver autostart kick`](#cua-driver-autostart-kick) | Start the autostart entry now without re-logging. |
-
-Every command also accepts the [global options](/cua-driver/reference/cli#global-options).
-
-## `cua-driver serve`
-
-Run Cua Driver as a long-running daemon.
-
-The daemon owns per-process state such as accessibility snapshots, recording state, and cursor overlay state.
-
-```text output
-cua-driver serve [OPTIONS]
-```
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-driver-serve--socket"></span>`--socket` | string | | Override the daemon socket or named-pipe path. |
-| <span id="cua-driver-serve--pid-file"></span>`--pid-file` | path | | Override the pid-file path. |
-| <span id="cua-driver-serve--permission-mode"></span>`--permission-mode` | string | `standard` | Immutable agent authorization mode: standard, bounded, or unrestricted. |
-| <span id="cua-driver-serve--grant"></span>`--grant` | string | | Pre-authorize a residual standard-mode boundary. Repeatable; supported value: existing-profile. |
-| <span id="cua-driver-serve--capability-manifest"></span>`--capability-manifest` | path | | Optional narrow-only tool/resource ceiling; required in bounded mode. |
-| <span id="cua-driver-serve--session-policy"></span>`--session-policy` | path | | Deprecated alias for capability-manifest. |
-| <span id="cua-driver-serve--host-bundle-id"></span>`--host-bundle-id` | string | | Advisory host bundle id label echoed in check_permissions output (embedded mode). |
-| <span id="cua-driver-serve--cursor-theme"></span>`--cursor-theme` | string | `cua.default` | Installed cursor theme id for the agent cursor overlay. |
-| <span id="cua-driver-serve--cursor-reduced-motion"></span>`--cursor-reduced-motion` | string | `auto` | Agent cursor motion: auto follows the OS setting, on forces still frames, off allows animation. |
-| <span id="cua-driver-serve--glide-ms"></span>`--glide-ms` | number | | Override the agent cursor glide duration, in milliseconds. |
-| <span id="cua-driver-serve--dwell-ms"></span>`--dwell-ms` | number | | Override how long the agent cursor dwells after a click, in milliseconds. |
-| <span id="cua-driver-serve--idle-hide-ms"></span>`--idle-hide-ms` | number | | Override how long an idle agent cursor stays visible, in milliseconds. |
-| <span id="cua-driver-serve--experimental-pip-geometry"></span>`--experimental-pip-geometry` | string | | Size and optional top-left origin of the experimental preview window: WxH or WxH+X+Y (default 480x360, top-right of the main display). |
-| <span id="cua-driver-serve--claude-code-computer-use-compat"></span>`--claude-code-computer-use-compat` | boolean | `false` | Select the Claude Code computer-use compatibility surface (forwarded by `mcp` when it launches the daemon). |
-| <span id="cua-driver-serve--experimental-pip"></span>`--experimental-pip` | boolean | `false` | Show a small always-on-top window with the latest post-action screenshot and a one-line label (macOS only). |
-| <span id="cua-driver-serve--dangerously-bypass-approvals"></span>`--dangerously-bypass-approvals` | boolean | `false` | Select unrestricted mode and acknowledge its risk. |
-| <span id="cua-driver-serve--approve-capability-manifest"></span>`--approve-capability-manifest` | boolean | `false` | Trusted-launcher confirmation that the exact capability manifest was reviewed. |
-| <span id="cua-driver-serve--approve-session-policy"></span>`--approve-session-policy` | boolean | `false` | Deprecated alias for approve-capability-manifest. |
-| <span id="cua-driver-serve--no-permissions-gate"></span>`--no-permissions-gate` | boolean | `false` | Skip the macOS first-launch permissions gate. |
-| <span id="cua-driver-serve--embedded"></span>`--embedded` | boolean | `false` | Run embedded inside a host app: inherit the host's TCC grants, never prompt or relaunch. Also CUA_DRIVER_EMBEDDED=1. |
-| <span id="cua-driver-serve--no-overlay"></span>`--no-overlay` | boolean | `false` | Disable the agent cursor overlay for this daemon. |
-| <span id="cua-driver-serve--experimental-history"></span>`--experimental-history` | boolean | `false` | Admit the encrypted local Computer History early preview for this daemon launch. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-serve"
-# Run the daemon in the foreground
-cua-driver serve
-
-# Start a bounded daemon with a reviewed capability manifest
-cua-driver serve --permission-mode bounded --capability-manifest manifest.yaml --approve-capability-manifest
-
-# Run without the agent cursor overlay
-cua-driver serve --no-overlay
-```
-
-## `cua-driver stop`
-
-Ask the running daemon to exit gracefully.
-
-```text output
-cua-driver stop [OPTIONS]
-```
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-driver-stop--socket"></span>`--socket` | string | | Override the daemon socket or named-pipe path. |
-| <span id="cua-driver-stop--expected-pid"></span>`--expected-pid` | number | | Stop only if the daemon's process id is this one (a positive integer). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-stop"
-# Ask the running daemon to exit
-cua-driver stop
-```
-
-## `cua-driver status`
-
-Report whether a Cua Driver daemon is running.
-
-```text output
-cua-driver status [OPTIONS]
-```
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-driver-status--socket"></span>`--socket` | string | | Override the daemon socket or named-pipe path. |
-| <span id="cua-driver-status--pid-file"></span>`--pid-file` | path | | Override the pid-file path. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-status"
-# Check whether the daemon is running
-cua-driver status
-```
-
-## `cua-driver sessions`
-
-List content-free lifecycle summaries for sessions owned by the daemon runtime.
-
-```text output
-cua-driver sessions [OPTIONS] [COMMAND]
-```
-
-Without a subcommand, runs `cua-driver sessions list`.
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-driver-sessions--socket"></span>`--socket` | string | | Override the daemon socket or named-pipe path. |
-| <span id="cua-driver-sessions--json"></span>`--json` | boolean | `false` | Emit the machine-readable session summary. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-sessions"
-# List live sessions as JSON
-cua-driver sessions --json
-```
-
-### `cua-driver sessions list`
-
-List live sessions. The default subcommand.
-
-```text output
-cua-driver sessions list
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-sessions-list"
-# List live sessions
-cua-driver sessions list
-```
-
-## `cua-driver revoke`
-
-Revoke one or all live authorization/session scopes.
-
-Revocation is deny-only and never accepts an approval token.
-
-```text output
-cua-driver revoke [OPTIONS]
-```
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-driver-revoke--session"></span>`--session` | string | | Exact session id to stop and revoke. |
-| <span id="cua-driver-revoke--socket"></span>`--socket` | string | | Override the daemon socket or named-pipe path. |
-| <span id="cua-driver-revoke--all"></span>`--all` | boolean | `false` | Stop and revoke every live session. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-revoke"
-# Stop and revoke one session
-cua-driver revoke --session 3f9c2a
-
-# Stop and revoke every live session
-cua-driver revoke --all
-```
-
-## `cua-driver autostart`
-
-Manage platform-native daemon autostart.
-
-Windows registers a logon Scheduled Task. macOS and Linux currently print manual-recipe guidance.
-
-```text output
-cua-driver autostart <COMMAND>
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-autostart"
-# Check the autostart entry
-cua-driver autostart status
-```
-
-### `cua-driver autostart enable`
-
-Register the autostart entry.
-
-```text output
-cua-driver autostart enable
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-autostart-enable"
-# Start the daemon at every logon
-cua-driver autostart enable
-```
-
-### `cua-driver autostart disable`
-
-Remove the autostart entry.
-
-```text output
-cua-driver autostart disable
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-autostart-disable"
-# Remove the autostart entry
-cua-driver autostart disable
-```
-
-### `cua-driver autostart status`
-
-Print whether autostart is registered and running.
-
-`not-registered` is emitted only when Task Scheduler explicitly reports that the named task does not exist. If the task cannot be inspected, the command exits non-zero and reports `permission-denied` or `unknown` together with the original diagnostic.
-
-```text output
-cua-driver autostart status
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-autostart-status"
-# Check the autostart entry
-cua-driver autostart status
-```
-
-### `cua-driver autostart kick`
-
-Start the autostart entry now without re-logging.
-
-```text output
-cua-driver autostart kick
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-autostart-kick"
-# Start the entry now
-cua-driver autostart kick
-```
-
-## Exit codes
-
-| Code | Meaning |
-| --- | --- |
-| `0` | Success. |
-| `1` | Failure: the daemon is not running or is incompatible, a tool call returned an error, or the operation failed. `call` and direct tool invocations exit with the daemon's result code (1 on a tool error); `update --apply` passes through the installer's status. |
-| `2` | Invalid input: tool arguments that are not valid JSON, an unknown `mcp-config` client, or an `update --apply` refused on a local development install. |
-| `64` | Usage error: an unknown or missing subcommand or argument, or conflicting flags (for example `revoke` without exactly one of `--session` or `--all`, or an authorization flag passed to `mcp`). |
diff --git a/docs/content/docs/cua-driver/reference/cli/history.mdx b/docs/content/docs/cua-driver/reference/cli/history.mdx
deleted file mode 100644
index 88824220c9..0000000000
--- a/docs/content/docs/cua-driver/reference/cli/history.mdx
+++ /dev/null
@@ -1,217 +0,0 @@
----
-title: "Computer History"
-description: "The encrypted, metadata-only Computer History preview."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-driver
- Source: cua-driver dump-docs --type cli
- Version: 0.36.0
-*/}
-
-| Command | Description |
-| --- | --- |
-| [`cua-driver history enable`](#cua-driver-history-enable) | Turn on the Computer History preview (admits it on a local daemon if needed). |
-| [`cua-driver history disable`](#cua-driver-history-disable) | Turn Computer History off; recorded chunks stay until deleted. |
-| [`cua-driver history pause`](#cua-driver-history-pause) | Pause recording without turning the preview off. |
-| [`cua-driver history resume`](#cua-driver-history-resume) | Resume recording after pause. |
-| [`cua-driver history status`](#cua-driver-history-status) | Print the Computer History state. |
-| [`cua-driver history flush`](#cua-driver-history-flush) | Seal the current chunk to disk now. |
-| [`cua-driver history list`](#cua-driver-history-list) | List recent metadata-only events. |
-| [`cua-driver history show`](#cua-driver-history-show) | Print one event by its sequence number. |
-| [`cua-driver history delete`](#cua-driver-history-delete) | Delete the encrypted chunks and their native credential-store key. |
-
-Every command also accepts the [global options](/cua-driver/reference/cli#global-options).
-
-<span id="cua-driver-history"></span>
-
-Encrypted, metadata-only Computer History early preview: lifecycle and local inspection.
-
-The daemon must be admitted for the preview (`cua-driver serve --experimental-history`); `enable` restarts a local daemon with it when needed.
-
-```text output
-cua-driver history [OPTIONS] [COMMAND]
-```
-
-Without a subcommand, runs `cua-driver history status`.
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-driver-history--socket"></span>`--socket` | string | | Override the daemon socket or named-pipe path. |
-| <span id="cua-driver-history--json"></span>`--json` | boolean | `false` | Emit machine-readable output. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-history"
-# Print the Computer History state
-cua-driver history
-```
-
-## `cua-driver history enable`
-
-Turn on the Computer History preview (admits it on a local daemon if needed).
-
-```text output
-cua-driver history enable
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-history-enable"
-# Turn on the Computer History preview
-cua-driver history enable
-```
-
-## `cua-driver history disable`
-
-Turn Computer History off; recorded chunks stay until deleted.
-
-```text output
-cua-driver history disable
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-history-disable"
-# Turn Computer History off
-cua-driver history disable
-```
-
-## `cua-driver history pause`
-
-Pause recording without turning the preview off.
-
-```text output
-cua-driver history pause
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-history-pause"
-# Pause recording
-cua-driver history pause
-```
-
-## `cua-driver history resume`
-
-Resume recording after pause.
-
-```text output
-cua-driver history resume
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-history-resume"
-# Resume recording
-cua-driver history resume
-```
-
-## `cua-driver history status`
-
-Print the Computer History state. The default subcommand.
-
-```text output
-cua-driver history status [OPTIONS]
-```
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-driver-history-status--json"></span>`--json` | boolean | `false` | Emit machine-readable output. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-history-status"
-# Print the state as JSON
-cua-driver history status --json
-```
-
-## `cua-driver history flush`
-
-Seal the current chunk to disk now.
-
-```text output
-cua-driver history flush
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-history-flush"
-# Seal the current chunk now
-cua-driver history flush
-```
-
-## `cua-driver history list`
-
-List recent metadata-only events.
-
-```text output
-cua-driver history list [OPTIONS] [<limit>]
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<limit>` | number | optional | Most events to print. |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-driver-history-list--json"></span>`--json` | boolean | `false` | Emit machine-readable output. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-history-list"
-# List the 20 most recent events
-cua-driver history list 20
-```
-
-## `cua-driver history show`
-
-Print one event by its sequence number.
-
-```text output
-cua-driver history show [OPTIONS] <sequence>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<sequence>` | number | required | Event sequence number. |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-driver-history-show--json"></span>`--json` | boolean | `false` | Emit machine-readable output. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-history-show"
-# Print event 42 as JSON
-cua-driver history show 42 --json
-```
-
-## `cua-driver history delete`
-
-Delete the encrypted chunks and their native credential-store key. Needs --yes.
-
-```text output
-cua-driver history delete [OPTIONS]
-```
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-driver-history-delete--yes"></span>`--yes` | boolean | `false` | Confirm irreversible deletion of encrypted chunks and their native credential-store key. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-history-delete"
-# Delete every recorded chunk and its key
-cua-driver history delete --yes
-```
-
-## Exit codes
-
-| Code | Meaning |
-| --- | --- |
-| `0` | Success. |
-| `1` | Failure: the daemon is not running or is incompatible, a tool call returned an error, or the operation failed. `call` and direct tool invocations exit with the daemon's result code (1 on a tool error); `update --apply` passes through the installer's status. |
-| `2` | Invalid input: tool arguments that are not valid JSON, an unknown `mcp-config` client, or an `update --apply` refused on a local development install. |
-| `64` | Usage error: an unknown or missing subcommand or argument, or conflicting flags (for example `revoke` without exactly one of `--session` or `--all`, or an authorization flag passed to `mcp`). |
diff --git a/docs/content/docs/cua-driver/reference/cli/index.mdx b/docs/content/docs/cua-driver/reference/cli/index.mdx
index 843e25750f..11de84aa75 100644
--- a/docs/content/docs/cua-driver/reference/cli/index.mdx
+++ b/docs/content/docs/cua-driver/reference/cli/index.mdx
@@ -18,142 +18,100 @@ Run `cua-driver <command> --help` for the build you have.
## Commands
-### Tools and MCP
+### Serve, configure and update
-Serve MCP, print client config, and list, describe or call tools from the shell. [Reference](/cua-driver/reference/cli/mcp).
+Serve MCP and call tools from the shell; run the daemon; grant permissions and diagnose; configure the driver, telemetry and cursor; update and pick a release channel. [Reference](/cua-driver/reference/cli/serve-and-configure).
| Command | Description |
| --- | --- |
-| <span id="cua-driver-mcp"></span>[`cua-driver mcp`](/cua-driver/reference/cli/mcp#cua-driver-mcp) | Run the stdio MCP server. |
-| <span id="cua-driver-mcp-config"></span>[`cua-driver mcp-config`](/cua-driver/reference/cli/mcp#cua-driver-mcp-config) | Print client-specific connection guidance (MCP config where supported) and install the skill pack for that agent. |
-| <span id="cua-driver-list-tools"></span>[`cua-driver list-tools`](/cua-driver/reference/cli/mcp#cua-driver-list-tools) | List every registered MCP tool with a one-line description. |
-| <span id="cua-driver-describe"></span>[`cua-driver describe`](/cua-driver/reference/cli/mcp#cua-driver-describe) | Print a tool's full description and JSON input schema. |
-| <span id="cua-driver-call"></span>[`cua-driver call`](/cua-driver/reference/cli/mcp#cua-driver-call) | Invoke an MCP tool through the running daemon. |
-| <span id="cua-driver-manifest"></span>[`cua-driver manifest`](/cua-driver/reference/cli/mcp#cua-driver-manifest) | Emit a stable JSON description of the CLI surface. |
-| <span id="cua-driver-dump-docs"></span>[`cua-driver dump-docs`](/cua-driver/reference/cli/mcp#cua-driver-dump-docs) | Output machine-readable CLI and MCP documentation JSON. |
-
-### Daemon
-
-Run, stop and inspect the daemon, its sessions and autostart. [Reference](/cua-driver/reference/cli/daemon).
-
-| Command | Description |
-| --- | --- |
-| <span id="cua-driver-serve"></span>[`cua-driver serve`](/cua-driver/reference/cli/daemon#cua-driver-serve) | Run Cua Driver as a long-running daemon. |
-| <span id="cua-driver-stop"></span>[`cua-driver stop`](/cua-driver/reference/cli/daemon#cua-driver-stop) | Ask the running daemon to exit gracefully. |
-| <span id="cua-driver-status"></span>[`cua-driver status`](/cua-driver/reference/cli/daemon#cua-driver-status) | Report whether a Cua Driver daemon is running. |
-| <span id="cua-driver-sessions"></span>[`cua-driver sessions`](/cua-driver/reference/cli/daemon#cua-driver-sessions) | List content-free lifecycle summaries for sessions owned by the daemon runtime. |
-| <span id="cua-driver-sessions-list"></span>[`cua-driver sessions list`](/cua-driver/reference/cli/daemon#cua-driver-sessions-list) | List live sessions. |
-| <span id="cua-driver-revoke"></span>[`cua-driver revoke`](/cua-driver/reference/cli/daemon#cua-driver-revoke) | Revoke one or all live authorization/session scopes. |
-| <span id="cua-driver-autostart"></span>[`cua-driver autostart`](/cua-driver/reference/cli/daemon#cua-driver-autostart) | Manage platform-native daemon autostart. |
-| <span id="cua-driver-autostart-enable"></span>[`cua-driver autostart enable`](/cua-driver/reference/cli/daemon#cua-driver-autostart-enable) | Register the autostart entry. |
-| <span id="cua-driver-autostart-disable"></span>[`cua-driver autostart disable`](/cua-driver/reference/cli/daemon#cua-driver-autostart-disable) | Remove the autostart entry. |
-| <span id="cua-driver-autostart-status"></span>[`cua-driver autostart status`](/cua-driver/reference/cli/daemon#cua-driver-autostart-status) | Print whether autostart is registered and running. |
-| <span id="cua-driver-autostart-kick"></span>[`cua-driver autostart kick`](/cua-driver/reference/cli/daemon#cua-driver-autostart-kick) | Start the autostart entry now without re-logging. |
-
-### Permissions and diagnostics
-
-macOS permission grants, diagnostic probes and install reports. [Reference](/cua-driver/reference/cli/permissions).
-
-| Command | Description |
-| --- | --- |
-| <span id="cua-driver-permissions"></span>[`cua-driver permissions`](/cua-driver/reference/cli/permissions#cua-driver-permissions) | Inspect or raise macOS TCC permission grants (macOS only). |
-| <span id="cua-driver-permissions-status"></span>[`cua-driver permissions status`](/cua-driver/reference/cli/permissions#cua-driver-permissions-status) | Report Accessibility and Screen Recording status through a running daemon (read-only, no prompt). |
-| <span id="cua-driver-permissions-grant"></span>[`cua-driver permissions grant`](/cua-driver/reference/cli/permissions#cua-driver-permissions-grant) | Launch CuaDriver through LaunchServices so the permission prompts are attributed to the app. |
-| <span id="cua-driver-doctor"></span>[`cua-driver doctor`](/cua-driver/reference/cli/permissions#cua-driver-doctor) | Run platform-aware diagnostic probes. |
-| <span id="cua-driver-diagnose"></span>[`cua-driver diagnose`](/cua-driver/reference/cli/permissions#cua-driver-diagnose) | Print a pasteable install-layout and permission-attribution report. |
-
-### Trajectory recording
-
-Record, inspect and render action trajectories. [Reference](/cua-driver/reference/cli/recording).
-
-| Command | Description |
-| --- | --- |
-| <span id="cua-driver-recording"></span>[`cua-driver recording`](/cua-driver/reference/cli/recording#cua-driver-recording) | Control trajectory recording on a running daemon. |
-| <span id="cua-driver-recording-start"></span>[`cua-driver recording start`](/cua-driver/reference/cli/recording#cua-driver-recording-start) | Start trajectory recording to a directory. |
-| <span id="cua-driver-recording-stop"></span>[`cua-driver recording stop`](/cua-driver/reference/cli/recording#cua-driver-recording-stop) | Stop trajectory recording. |
-| <span id="cua-driver-recording-status"></span>[`cua-driver recording status`](/cua-driver/reference/cli/recording#cua-driver-recording-status) | Print the current recording state. |
-| <span id="cua-driver-recording-render"></span>[`cua-driver recording render`](/cua-driver/reference/cli/recording#cua-driver-recording-render) | Render a recorded trajectory directory to an MP4. |
-
-### Computer History
-
-The encrypted, metadata-only Computer History preview. [Reference](/cua-driver/reference/cli/history).
-
-| Command | Description |
-| --- | --- |
-| <span id="cua-driver-history"></span>[`cua-driver history`](/cua-driver/reference/cli/history#cua-driver-history) | Encrypted, metadata-only Computer History early preview: lifecycle and local inspection. |
-| <span id="cua-driver-history-enable"></span>[`cua-driver history enable`](/cua-driver/reference/cli/history#cua-driver-history-enable) | Turn on the Computer History preview (admits it on a local daemon if needed). |
-| <span id="cua-driver-history-disable"></span>[`cua-driver history disable`](/cua-driver/reference/cli/history#cua-driver-history-disable) | Turn Computer History off; recorded chunks stay until deleted. |
-| <span id="cua-driver-history-pause"></span>[`cua-driver history pause`](/cua-driver/reference/cli/history#cua-driver-history-pause) | Pause recording without turning the preview off. |
-| <span id="cua-driver-history-resume"></span>[`cua-driver history resume`](/cua-driver/reference/cli/history#cua-driver-history-resume) | Resume recording after pause. |
-| <span id="cua-driver-history-status"></span>[`cua-driver history status`](/cua-driver/reference/cli/history#cua-driver-history-status) | Print the Computer History state. |
-| <span id="cua-driver-history-flush"></span>[`cua-driver history flush`](/cua-driver/reference/cli/history#cua-driver-history-flush) | Seal the current chunk to disk now. |
-| <span id="cua-driver-history-list"></span>[`cua-driver history list`](/cua-driver/reference/cli/history#cua-driver-history-list) | List recent metadata-only events. |
-| <span id="cua-driver-history-show"></span>[`cua-driver history show`](/cua-driver/reference/cli/history#cua-driver-history-show) | Print one event by its sequence number. |
-| <span id="cua-driver-history-delete"></span>[`cua-driver history delete`](/cua-driver/reference/cli/history#cua-driver-history-delete) | Delete the encrypted chunks and their native credential-store key. |
-
-### Configuration
-
-Driver configuration, telemetry, cursor themes and cursor motion. [Reference](/cua-driver/reference/cli/config).
-
-| Command | Description |
-| --- | --- |
-| <span id="cua-driver-config"></span>[`cua-driver config`](/cua-driver/reference/cli/config#cua-driver-config) | Read or mutate persistent driver configuration. |
-| <span id="cua-driver-config-show"></span>[`cua-driver config show`](/cua-driver/reference/cli/config#cua-driver-config-show) | Print the full config. |
-| <span id="cua-driver-config-get"></span>[`cua-driver config get`](/cua-driver/reference/cli/config#cua-driver-config-get) | Print one config key. |
-| <span id="cua-driver-config-set"></span>[`cua-driver config set`](/cua-driver/reference/cli/config#cua-driver-config-set) | Set one config key. |
-| <span id="cua-driver-config-reset"></span>[`cua-driver config reset`](/cua-driver/reference/cli/config#cua-driver-config-reset) | Reset config to defaults. |
-| <span id="cua-driver-telemetry"></span>[`cua-driver telemetry`](/cua-driver/reference/cli/config#cua-driver-telemetry) | Inspect or change content-free product telemetry. |
-| <span id="cua-driver-telemetry-enable"></span>[`cua-driver telemetry enable`](/cua-driver/reference/cli/config#cua-driver-telemetry-enable) | Persistently enable telemetry. |
-| <span id="cua-driver-telemetry-disable"></span>[`cua-driver telemetry disable`](/cua-driver/reference/cli/config#cua-driver-telemetry-disable) | Persistently disable every telemetry request. |
-| <span id="cua-driver-telemetry-status"></span>[`cua-driver telemetry status`](/cua-driver/reference/cli/config#cua-driver-telemetry-status) | Show the effective setting and redacted identity state. |
-| <span id="cua-driver-telemetry-reset-id"></span>[`cua-driver telemetry reset-id`](/cua-driver/reference/cli/config#cua-driver-telemetry-reset-id) | Erase the installation ID and event markers. |
-| <span id="cua-driver-telemetry-inspect"></span>[`cua-driver telemetry inspect`](/cua-driver/reference/cli/config#cua-driver-telemetry-inspect) | Build a fixed event payload without sending it. |
-| <span id="cua-driver-cursor-theme"></span>[`cua-driver cursor-theme`](/cua-driver/reference/cli/config#cua-driver-cursor-theme) | Validate, compile, inspect, preview, install, or remove a local cursor theme. |
-| <span id="cua-driver-cursor-theme-validate"></span>[`cua-driver cursor-theme validate`](/cua-driver/reference/cli/config#cua-driver-cursor-theme-validate) | Validate a bounded dotLottie source archive. |
-| <span id="cua-driver-cursor-theme-build"></span>[`cua-driver cursor-theme build`](/cua-driver/reference/cli/config#cua-driver-cursor-theme-build) | Compile a validated dotLottie archive into a bounded .cua-theme artifact. |
-| <span id="cua-driver-cursor-theme-inspect"></span>[`cua-driver cursor-theme inspect`](/cua-driver/reference/cli/config#cua-driver-cursor-theme-inspect) | Inspect metadata in a compiled .cua-theme artifact. |
-| <span id="cua-driver-cursor-theme-preview"></span>[`cua-driver cursor-theme preview`](/cua-driver/reference/cli/config#cua-driver-cursor-theme-preview) | Render a compiled theme's representative still frames to a directory. |
-| <span id="cua-driver-cursor-theme-install"></span>[`cua-driver cursor-theme install`](/cua-driver/reference/cli/config#cua-driver-cursor-theme-install) | Install a compiled theme into the current user's theme store. |
-| <span id="cua-driver-cursor-theme-list"></span>[`cua-driver cursor-theme list`](/cua-driver/reference/cli/config#cua-driver-cursor-theme-list) | List the built-in and installed cursor themes. |
-| <span id="cua-driver-cursor-theme-uninstall"></span>[`cua-driver cursor-theme uninstall`](/cua-driver/reference/cli/config#cua-driver-cursor-theme-uninstall) | Remove a custom theme from the current user's theme store. |
-| <span id="cua-driver-cursor"></span>[`cua-driver cursor`](/cua-driver/reference/cli/config#cua-driver-cursor) | Configure a session's agent cursor from the command line. |
-| <span id="cua-driver-cursor-motion"></span>[`cua-driver cursor motion`](/cua-driver/reference/cli/config#cua-driver-cursor-motion) | Set the cursor's motion style, timing and effects. |
-
-### Skills and extensions
-
-The agent skill pack, signed extensions and the perception parser. [Reference](/cua-driver/reference/cli/extensions).
-
-| Command | Description |
-| --- | --- |
-| <span id="cua-driver-skills"></span>[`cua-driver skills`](/cua-driver/reference/cli/extensions#cua-driver-skills) | Install, update, inspect, or remove the optional agent skill pack. |
-| <span id="cua-driver-skills-install"></span>[`cua-driver skills install`](/cua-driver/reference/cli/extensions#cua-driver-skills-install) | Fetch the versioned skill pack and link detected agents. |
-| <span id="cua-driver-skills-update"></span>[`cua-driver skills update`](/cua-driver/reference/cli/extensions#cua-driver-skills-update) | Refresh the local skill pack and links. |
-| <span id="cua-driver-skills-uninstall"></span>[`cua-driver skills uninstall`](/cua-driver/reference/cli/extensions#cua-driver-skills-uninstall) | Remove agent skill links. |
-| <span id="cua-driver-skills-status"></span>[`cua-driver skills status`](/cua-driver/reference/cli/extensions#cua-driver-skills-status) | Report local skill-pack and per-agent link state. |
-| <span id="cua-driver-skills-path"></span>[`cua-driver skills path`](/cua-driver/reference/cli/extensions#cua-driver-skills-path) | Print the local skill-pack path. |
-| <span id="cua-driver-extension"></span>[`cua-driver extension`](/cua-driver/reference/cli/extensions#cua-driver-extension) | Inspect and manage signed, target-specific optional extensions. |
-| <span id="cua-driver-extension-list"></span>[`cua-driver extension list`](/cua-driver/reference/cli/extensions#cua-driver-extension-list) | List registry-known extensions and local state. |
-| <span id="cua-driver-extension-info"></span>[`cua-driver extension info`](/cua-driver/reference/cli/extensions#cua-driver-extension-info) | Compatibility alias for installed extension status. |
-| <span id="cua-driver-extension-inspect"></span>[`cua-driver extension inspect`](/cua-driver/reference/cli/extensions#cua-driver-extension-inspect) | Verify and preview license, source, provenance, and hashes without mutation. |
-| <span id="cua-driver-extension-status"></span>[`cua-driver extension status`](/cua-driver/reference/cli/extensions#cua-driver-extension-status) | Verify installed integrity and optionally run the self-test hook. |
-| <span id="cua-driver-extension-install"></span>[`cua-driver extension install`](/cua-driver/reference/cli/extensions#cua-driver-extension-install) | Verify, stage, and durably activate an extension. |
-| <span id="cua-driver-extension-update"></span>[`cua-driver extension update`](/cua-driver/reference/cli/extensions#cua-driver-extension-update) | Verify and atomically activate a newer extension version. |
-| <span id="cua-driver-extension-remove"></span>[`cua-driver extension remove`](/cua-driver/reference/cli/extensions#cua-driver-extension-remove) | Remove only a fully validated, manager-owned extension tree. |
-| <span id="cua-driver-extension-path"></span>[`cua-driver extension path`](/cua-driver/reference/cli/extensions#cua-driver-extension-path) | Compatibility command that prints the exact active version directory. |
-| <span id="cua-driver-perception"></span>[`cua-driver perception`](/cua-driver/reference/cli/extensions#cua-driver-perception) | Parse a local PNG with the installed optional perception extension. |
-| <span id="cua-driver-perception-parse"></span>[`cua-driver perception parse`](/cua-driver/reference/cli/extensions#cua-driver-perception-parse) | Parse one local PNG into canonical visual regions. |
-
-### Updates
-
-Check for and apply updates, and choose the release channel. [Reference](/cua-driver/reference/cli/updates).
+| <span id="cua-driver-mcp"></span>[`cua-driver mcp`](/cua-driver/reference/cli/serve-and-configure#cua-driver-mcp) | Run the stdio MCP server. |
+| <span id="cua-driver-mcp-config"></span>[`cua-driver mcp-config`](/cua-driver/reference/cli/serve-and-configure#cua-driver-mcp-config) | Print client-specific connection guidance (MCP config where supported) and install the skill pack for that agent. |
+| <span id="cua-driver-list-tools"></span>[`cua-driver list-tools`](/cua-driver/reference/cli/serve-and-configure#cua-driver-list-tools) | List every registered MCP tool with a one-line description. |
+| <span id="cua-driver-describe"></span>[`cua-driver describe`](/cua-driver/reference/cli/serve-and-configure#cua-driver-describe) | Print a tool's full description and JSON input schema. |
+| <span id="cua-driver-call"></span>[`cua-driver call`](/cua-driver/reference/cli/serve-and-configure#cua-driver-call) | Invoke an MCP tool through the running daemon. |
+| <span id="cua-driver-manifest"></span>[`cua-driver manifest`](/cua-driver/reference/cli/serve-and-configure#cua-driver-manifest) | Emit a stable JSON description of the CLI surface. |
+| <span id="cua-driver-dump-docs"></span>[`cua-driver dump-docs`](/cua-driver/reference/cli/serve-and-configure#cua-driver-dump-docs) | Output machine-readable CLI and MCP documentation JSON. |
+| <span id="cua-driver-serve"></span>[`cua-driver serve`](/cua-driver/reference/cli/serve-and-configure#cua-driver-serve) | Run Cua Driver as a long-running daemon. |
+| <span id="cua-driver-stop"></span>[`cua-driver stop`](/cua-driver/reference/cli/serve-and-configure#cua-driver-stop) | Ask the running daemon to exit gracefully. |
+| <span id="cua-driver-status"></span>[`cua-driver status`](/cua-driver/reference/cli/serve-and-configure#cua-driver-status) | Report whether a Cua Driver daemon is running. |
+| <span id="cua-driver-sessions"></span>[`cua-driver sessions`](/cua-driver/reference/cli/serve-and-configure#cua-driver-sessions) | List content-free lifecycle summaries for sessions owned by the daemon runtime. |
+| <span id="cua-driver-sessions-list"></span>[`cua-driver sessions list`](/cua-driver/reference/cli/serve-and-configure#cua-driver-sessions-list) | List live sessions. |
+| <span id="cua-driver-revoke"></span>[`cua-driver revoke`](/cua-driver/reference/cli/serve-and-configure#cua-driver-revoke) | Revoke one or all live authorization/session scopes. |
+| <span id="cua-driver-autostart"></span>[`cua-driver autostart`](/cua-driver/reference/cli/serve-and-configure#cua-driver-autostart) | Manage platform-native daemon autostart. |
+| <span id="cua-driver-autostart-enable"></span>[`cua-driver autostart enable`](/cua-driver/reference/cli/serve-and-configure#cua-driver-autostart-enable) | Register the autostart entry. |
+| <span id="cua-driver-autostart-disable"></span>[`cua-driver autostart disable`](/cua-driver/reference/cli/serve-and-configure#cua-driver-autostart-disable) | Remove the autostart entry. |
+| <span id="cua-driver-autostart-status"></span>[`cua-driver autostart status`](/cua-driver/reference/cli/serve-and-configure#cua-driver-autostart-status) | Print whether autostart is registered and running. |
+| <span id="cua-driver-autostart-kick"></span>[`cua-driver autostart kick`](/cua-driver/reference/cli/serve-and-configure#cua-driver-autostart-kick) | Start the autostart entry now without re-logging. |
+| <span id="cua-driver-permissions"></span>[`cua-driver permissions`](/cua-driver/reference/cli/serve-and-configure#cua-driver-permissions) | Inspect or raise macOS TCC permission grants (macOS only). |
+| <span id="cua-driver-permissions-status"></span>[`cua-driver permissions status`](/cua-driver/reference/cli/serve-and-configure#cua-driver-permissions-status) | Report Accessibility and Screen Recording status through a running daemon (read-only, no prompt). |
+| <span id="cua-driver-permissions-grant"></span>[`cua-driver permissions grant`](/cua-driver/reference/cli/serve-and-configure#cua-driver-permissions-grant) | Launch CuaDriver through LaunchServices so the permission prompts are attributed to the app. |
+| <span id="cua-driver-doctor"></span>[`cua-driver doctor`](/cua-driver/reference/cli/serve-and-configure#cua-driver-doctor) | Run platform-aware diagnostic probes. |
+| <span id="cua-driver-diagnose"></span>[`cua-driver diagnose`](/cua-driver/reference/cli/serve-and-configure#cua-driver-diagnose) | Print a pasteable install-layout and permission-attribution report. |
+| <span id="cua-driver-config"></span>[`cua-driver config`](/cua-driver/reference/cli/serve-and-configure#cua-driver-config) | Read or mutate persistent driver configuration. |
+| <span id="cua-driver-config-show"></span>[`cua-driver config show`](/cua-driver/reference/cli/serve-and-configure#cua-driver-config-show) | Print the full config. |
+| <span id="cua-driver-config-get"></span>[`cua-driver config get`](/cua-driver/reference/cli/serve-and-configure#cua-driver-config-get) | Print one config key. |
+| <span id="cua-driver-config-set"></span>[`cua-driver config set`](/cua-driver/reference/cli/serve-and-configure#cua-driver-config-set) | Set one config key. |
+| <span id="cua-driver-config-reset"></span>[`cua-driver config reset`](/cua-driver/reference/cli/serve-and-configure#cua-driver-config-reset) | Reset config to defaults. |
+| <span id="cua-driver-telemetry"></span>[`cua-driver telemetry`](/cua-driver/reference/cli/serve-and-configure#cua-driver-telemetry) | Inspect or change content-free product telemetry. |
+| <span id="cua-driver-telemetry-enable"></span>[`cua-driver telemetry enable`](/cua-driver/reference/cli/serve-and-configure#cua-driver-telemetry-enable) | Persistently enable telemetry. |
+| <span id="cua-driver-telemetry-disable"></span>[`cua-driver telemetry disable`](/cua-driver/reference/cli/serve-and-configure#cua-driver-telemetry-disable) | Persistently disable every telemetry request. |
+| <span id="cua-driver-telemetry-status"></span>[`cua-driver telemetry status`](/cua-driver/reference/cli/serve-and-configure#cua-driver-telemetry-status) | Show the effective setting and redacted identity state. |
+| <span id="cua-driver-telemetry-reset-id"></span>[`cua-driver telemetry reset-id`](/cua-driver/reference/cli/serve-and-configure#cua-driver-telemetry-reset-id) | Erase the installation ID and event markers. |
+| <span id="cua-driver-telemetry-inspect"></span>[`cua-driver telemetry inspect`](/cua-driver/reference/cli/serve-and-configure#cua-driver-telemetry-inspect) | Build a fixed event payload without sending it. |
+| <span id="cua-driver-cursor-theme"></span>[`cua-driver cursor-theme`](/cua-driver/reference/cli/serve-and-configure#cua-driver-cursor-theme) | Validate, compile, inspect, preview, install, or remove a local cursor theme. |
+| <span id="cua-driver-cursor-theme-validate"></span>[`cua-driver cursor-theme validate`](/cua-driver/reference/cli/serve-and-configure#cua-driver-cursor-theme-validate) | Validate a bounded dotLottie source archive. |
+| <span id="cua-driver-cursor-theme-build"></span>[`cua-driver cursor-theme build`](/cua-driver/reference/cli/serve-and-configure#cua-driver-cursor-theme-build) | Compile a validated dotLottie archive into a bounded .cua-theme artifact. |
+| <span id="cua-driver-cursor-theme-inspect"></span>[`cua-driver cursor-theme inspect`](/cua-driver/reference/cli/serve-and-configure#cua-driver-cursor-theme-inspect) | Inspect metadata in a compiled .cua-theme artifact. |
+| <span id="cua-driver-cursor-theme-preview"></span>[`cua-driver cursor-theme preview`](/cua-driver/reference/cli/serve-and-configure#cua-driver-cursor-theme-preview) | Render a compiled theme's representative still frames to a directory. |
+| <span id="cua-driver-cursor-theme-install"></span>[`cua-driver cursor-theme install`](/cua-driver/reference/cli/serve-and-configure#cua-driver-cursor-theme-install) | Install a compiled theme into the current user's theme store. |
+| <span id="cua-driver-cursor-theme-list"></span>[`cua-driver cursor-theme list`](/cua-driver/reference/cli/serve-and-configure#cua-driver-cursor-theme-list) | List the built-in and installed cursor themes. |
+| <span id="cua-driver-cursor-theme-uninstall"></span>[`cua-driver cursor-theme uninstall`](/cua-driver/reference/cli/serve-and-configure#cua-driver-cursor-theme-uninstall) | Remove a custom theme from the current user's theme store. |
+| <span id="cua-driver-cursor"></span>[`cua-driver cursor`](/cua-driver/reference/cli/serve-and-configure#cua-driver-cursor) | Configure a session's agent cursor from the command line. |
+| <span id="cua-driver-cursor-motion"></span>[`cua-driver cursor motion`](/cua-driver/reference/cli/serve-and-configure#cua-driver-cursor-motion) | Set the cursor's motion style, timing and effects. |
+| <span id="cua-driver-check-update"></span>[`cua-driver check-update`](/cua-driver/reference/cli/serve-and-configure#cua-driver-check-update) | Check whether a newer cua-driver release is available. |
+| <span id="cua-driver-update"></span>[`cua-driver update`](/cua-driver/reference/cli/serve-and-configure#cua-driver-update) | Check for an update and optionally apply it. |
+| <span id="cua-driver-channel"></span>[`cua-driver channel`](/cua-driver/reference/cli/serve-and-configure#cua-driver-channel) | Inspect or change the stable/nightly update channel. |
+| <span id="cua-driver-channel-status"></span>[`cua-driver channel status`](/cua-driver/reference/cli/serve-and-configure#cua-driver-channel-status) | Show selected and current release channels. |
+| <span id="cua-driver-channel-set"></span>[`cua-driver channel set`](/cua-driver/reference/cli/serve-and-configure#cua-driver-channel-set) | Save stable or nightly as the update channel. |
+
+### Skills, recording and history
+
+The agent skill pack, signed extensions and the perception parser; trajectory recording; the Computer History preview. [Reference](/cua-driver/reference/cli/skills-recording-and-history).
| Command | Description |
| --- | --- |
-| <span id="cua-driver-check-update"></span>[`cua-driver check-update`](/cua-driver/reference/cli/updates#cua-driver-check-update) | Check whether a newer cua-driver release is available. |
-| <span id="cua-driver-update"></span>[`cua-driver update`](/cua-driver/reference/cli/updates#cua-driver-update) | Check for an update and optionally apply it. |
-| <span id="cua-driver-channel"></span>[`cua-driver channel`](/cua-driver/reference/cli/updates#cua-driver-channel) | Inspect or change the stable/nightly update channel. |
-| <span id="cua-driver-channel-status"></span>[`cua-driver channel status`](/cua-driver/reference/cli/updates#cua-driver-channel-status) | Show selected and current release channels. |
-| <span id="cua-driver-channel-set"></span>[`cua-driver channel set`](/cua-driver/reference/cli/updates#cua-driver-channel-set) | Save stable or nightly as the update channel. |
+| <span id="cua-driver-skills"></span>[`cua-driver skills`](/cua-driver/reference/cli/skills-recording-and-history#cua-driver-skills) | Install, update, inspect, or remove the optional agent skill pack. |
+| <span id="cua-driver-skills-install"></span>[`cua-driver skills install`](/cua-driver/reference/cli/skills-recording-and-history#cua-driver-skills-install) | Fetch the versioned skill pack and link detected agents. |
+| <span id="cua-driver-skills-update"></span>[`cua-driver skills update`](/cua-driver/reference/cli/skills-recording-and-history#cua-driver-skills-update) | Refresh the local skill pack and links. |
+| <span id="cua-driver-skills-uninstall"></span>[`cua-driver skills uninstall`](/cua-driver/reference/cli/skills-recording-and-history#cua-driver-skills-uninstall) | Remove agent skill links. |
+| <span id="cua-driver-skills-status"></span>[`cua-driver skills status`](/cua-driver/reference/cli/skills-recording-and-history#cua-driver-skills-status) | Report local skill-pack and per-agent link state. |
+| <span id="cua-driver-skills-path"></span>[`cua-driver skills path`](/cua-driver/reference/cli/skills-recording-and-history#cua-driver-skills-path) | Print the local skill-pack path. |
+| <span id="cua-driver-extension"></span>[`cua-driver extension`](/cua-driver/reference/cli/skills-recording-and-history#cua-driver-extension) | Inspect and manage signed, target-specific optional extensions. |
+| <span id="cua-driver-extension-list"></span>[`cua-driver extension list`](/cua-driver/reference/cli/skills-recording-and-history#cua-driver-extension-list) | List registry-known extensions and local state. |
+| <span id="cua-driver-extension-info"></span>[`cua-driver extension info`](/cua-driver/reference/cli/skills-recording-and-history#cua-driver-extension-info) | Compatibility alias for installed extension status. |
+| <span id="cua-driver-extension-inspect"></span>[`cua-driver extension inspect`](/cua-driver/reference/cli/skills-recording-and-history#cua-driver-extension-inspect) | Verify and preview license, source, provenance, and hashes without mutation. |
+| <span id="cua-driver-extension-status"></span>[`cua-driver extension status`](/cua-driver/reference/cli/skills-recording-and-history#cua-driver-extension-status) | Verify installed integrity and optionally run the self-test hook. |
+| <span id="cua-driver-extension-install"></span>[`cua-driver extension install`](/cua-driver/reference/cli/skills-recording-and-history#cua-driver-extension-install) | Verify, stage, and durably activate an extension. |
+| <span id="cua-driver-extension-update"></span>[`cua-driver extension update`](/cua-driver/reference/cli/skills-recording-and-history#cua-driver-extension-update) | Verify and atomically activate a newer extension version. |
+| <span id="cua-driver-extension-remove"></span>[`cua-driver extension remove`](/cua-driver/reference/cli/skills-recording-and-history#cua-driver-extension-remove) | Remove only a fully validated, manager-owned extension tree. |
+| <span id="cua-driver-extension-path"></span>[`cua-driver extension path`](/cua-driver/reference/cli/skills-recording-and-history#cua-driver-extension-path) | Compatibility command that prints the exact active version directory. |
+| <span id="cua-driver-perception"></span>[`cua-driver perception`](/cua-driver/reference/cli/skills-recording-and-history#cua-driver-perception) | Parse a local PNG with the installed optional perception extension. |
+| <span id="cua-driver-perception-parse"></span>[`cua-driver perception parse`](/cua-driver/reference/cli/skills-recording-and-history#cua-driver-perception-parse) | Parse one local PNG into canonical visual regions. |
+| <span id="cua-driver-recording"></span>[`cua-driver recording`](/cua-driver/reference/cli/skills-recording-and-history#cua-driver-recording) | Control trajectory recording on a running daemon. |
+| <span id="cua-driver-recording-start"></span>[`cua-driver recording start`](/cua-driver/reference/cli/skills-recording-and-history#cua-driver-recording-start) | Start trajectory recording to a directory. |
+| <span id="cua-driver-recording-stop"></span>[`cua-driver recording stop`](/cua-driver/reference/cli/skills-recording-and-history#cua-driver-recording-stop) | Stop trajectory recording. |
+| <span id="cua-driver-recording-status"></span>[`cua-driver recording status`](/cua-driver/reference/cli/skills-recording-and-history#cua-driver-recording-status) | Print the current recording state. |
+| <span id="cua-driver-recording-render"></span>[`cua-driver recording render`](/cua-driver/reference/cli/skills-recording-and-history#cua-driver-recording-render) | Render a recorded trajectory directory to an MP4. |
+| <span id="cua-driver-history"></span>[`cua-driver history`](/cua-driver/reference/cli/skills-recording-and-history#cua-driver-history) | Encrypted, metadata-only Computer History early preview: lifecycle and local inspection. |
+| <span id="cua-driver-history-enable"></span>[`cua-driver history enable`](/cua-driver/reference/cli/skills-recording-and-history#cua-driver-history-enable) | Turn on the Computer History preview (admits it on a local daemon if needed). |
+| <span id="cua-driver-history-disable"></span>[`cua-driver history disable`](/cua-driver/reference/cli/skills-recording-and-history#cua-driver-history-disable) | Turn Computer History off; recorded chunks stay until deleted. |
+| <span id="cua-driver-history-pause"></span>[`cua-driver history pause`](/cua-driver/reference/cli/skills-recording-and-history#cua-driver-history-pause) | Pause recording without turning the preview off. |
+| <span id="cua-driver-history-resume"></span>[`cua-driver history resume`](/cua-driver/reference/cli/skills-recording-and-history#cua-driver-history-resume) | Resume recording after pause. |
+| <span id="cua-driver-history-status"></span>[`cua-driver history status`](/cua-driver/reference/cli/skills-recording-and-history#cua-driver-history-status) | Print the Computer History state. |
+| <span id="cua-driver-history-flush"></span>[`cua-driver history flush`](/cua-driver/reference/cli/skills-recording-and-history#cua-driver-history-flush) | Seal the current chunk to disk now. |
+| <span id="cua-driver-history-list"></span>[`cua-driver history list`](/cua-driver/reference/cli/skills-recording-and-history#cua-driver-history-list) | List recent metadata-only events. |
+| <span id="cua-driver-history-show"></span>[`cua-driver history show`](/cua-driver/reference/cli/skills-recording-and-history#cua-driver-history-show) | Print one event by its sequence number. |
+| <span id="cua-driver-history-delete"></span>[`cua-driver history delete`](/cua-driver/reference/cli/skills-recording-and-history#cua-driver-history-delete) | Delete the encrypted chunks and their native credential-store key. |
## Global options
diff --git a/docs/content/docs/cua-driver/reference/cli/mcp.mdx b/docs/content/docs/cua-driver/reference/cli/mcp.mdx
deleted file mode 100644
index 7b3470d07d..0000000000
--- a/docs/content/docs/cua-driver/reference/cli/mcp.mdx
+++ /dev/null
@@ -1,207 +0,0 @@
----
-title: "Tools and MCP"
-description: "Serve MCP, print client config, and list, describe or call tools from the shell."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-driver
- Source: cua-driver dump-docs --type cli
- Version: 0.36.0
-*/}
-
-| Command | Description |
-| --- | --- |
-| [`cua-driver mcp`](#cua-driver-mcp) | Run the stdio MCP server. |
-| [`cua-driver mcp-config`](#cua-driver-mcp-config) | Print client-specific connection guidance (MCP config where supported) and install the skill pack for that agent. |
-| [`cua-driver list-tools`](#cua-driver-list-tools) | List every registered MCP tool with a one-line description. |
-| [`cua-driver describe`](#cua-driver-describe) | Print a tool's full description and JSON input schema. |
-| [`cua-driver call`](#cua-driver-call) | Invoke an MCP tool through the running daemon. |
-| [`cua-driver manifest`](#cua-driver-manifest) | Emit a stable JSON description of the CLI surface. |
-| [`cua-driver dump-docs`](#cua-driver-dump-docs) | Output machine-readable CLI and MCP documentation JSON. |
-
-Every command also accepts the [global options](/cua-driver/reference/cli#global-options).
-
-## `cua-driver mcp`
-
-Run the stdio MCP server.
-
-On Windows and Linux, bare cua-driver mcp owns its runtime directly and shuts it down on stdin EOF. On macOS it proxies to CuaDriver.app so desktop permissions retain the app identity. Pass --direct to make the macOS MCP process own the runtime and TCC attribution, or --socket to select an explicit daemon endpoint.
-
-```text output
-cua-driver mcp [OPTIONS]
-```
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-driver-mcp--socket"></span>`--socket` | string | | Select an explicit daemon socket or named-pipe endpoint. |
-| <span id="cua-driver-mcp--host-bundle-id"></span>`--host-bundle-id` | string | | Advisory host bundle id label echoed in check_permissions output (embedded mode). |
-| <span id="cua-driver-mcp--cursor-theme"></span>`--cursor-theme` | string | `cua.default` | Select an installed cursor theme id. |
-| <span id="cua-driver-mcp--cursor-reduced-motion"></span>`--cursor-reduced-motion` | string | `auto` | Follow the OS setting, force still frames, or allow animation: auto, on, or off. |
-| <span id="cua-driver-mcp--grant"></span>`--grant` | string | | Pre-authorize a residual standard-mode boundary for a newly launched runtime. Repeatable; supported value: existing-profile. |
-| <span id="cua-driver-mcp--direct"></span>`--direct` | boolean | `false` | Own the runtime in this MCP process; mutually exclusive with --socket. |
-| <span id="cua-driver-mcp--claude-code-computer-use-compat"></span>`--claude-code-computer-use-compat` | boolean | `false` | Accepted for older Claude Code setup snippets; there is no standalone screenshot tool; use get_window_state for window screenshots. |
-| <span id="cua-driver-mcp--embedded"></span>`--embedded` | boolean | `false` | Declare embedding-host mode. Without --direct, require the host's private service through --socket instead of auto-launching the standalone app. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-mcp"
-# Run the stdio MCP server (what MCP clients launch)
-cua-driver mcp
-
-# Connect to a daemon on an explicit socket
-cua-driver mcp --socket /tmp/cua-driver.sock
-```
-
-## `cua-driver mcp-config`
-
-Print client-specific connection guidance (MCP config where supported) and install the skill pack for that agent.
-
-Supported clients include claude, codex, cursor, antigravity, openclaw, opencode, hermes, pi, prime-agent, qwen, droid, and zcode. With --client, the cua-driver skill pack is also installed for that agent (not for qwen, droid or zcode, which have no skills folder), and one line on stderr says where; --no-skills skips it.
-
-```text output
-cua-driver mcp-config [OPTIONS]
-```
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-driver-mcp-config--client"></span>`--client` | string | | Client name to print configuration for. |
-| <span id="cua-driver-mcp-config--no-skills"></span>`--no-skills` | boolean | `false` | With --client, do not install the cua-driver skill pack for that agent. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-mcp-config"
-# Print a generic mcpServers entry
-cua-driver mcp-config
-
-# Print setup for Codex and install its skill pack
-cua-driver mcp-config --client codex
-
-# Print setup for Codex only
-cua-driver mcp-config --client codex --no-skills
-```
-
-## `cua-driver list-tools`
-
-List every registered MCP tool with a one-line description.
-
-```text output
-cua-driver list-tools
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-list-tools"
-# List every tool with a one-line description
-cua-driver list-tools
-```
-
-## `cua-driver describe`
-
-Print a tool's full description and JSON input schema.
-
-```text output
-cua-driver describe <tool-name>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<tool-name>` | string | required | Name of the MCP tool to describe. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-describe"
-# Print a tool's description and input schema
-cua-driver describe click
-```
-
-## `cua-driver call`
-
-Invoke an MCP tool through the running daemon.
-
-Requires a Cua Driver daemon. JSON arguments may be passed as a positional JSON object or through stdin.
-
-```text output
-cua-driver call [OPTIONS] <tool-name> [<json-args>]
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<tool-name>` | string | required | Name of the MCP tool to invoke. |
-| `<json-args>` | string | optional | JSON object for the tool input schema. If omitted, stdin is read when piped. |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-driver-call--screenshot-out-file"></span>`--screenshot-out-file` | path | | Write the first image content block from the response to this path. |
-| <span id="cua-driver-call--socket"></span>`--socket` | string | | Override the daemon socket or named-pipe path. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-call"
-# Call a tool with no arguments
-cua-driver call list_apps
-
-# Click at window coordinates
-cua-driver call click '{"pid":844,"x":100,"y":200}'
-
-# Save the screenshot from a tool response
-cua-driver call get_window_state '{"pid":844,"window_id":10725}' --screenshot-out-file state.png
-
-# Read only what changed since an earlier snapshot_id
-cua-driver call get_window_state '{"pid":844,"window_id":10725,"since":"s0000002a"}'
-
-# Return the structured elements instead of the markdown tree
-cua-driver call get_window_state '{"pid":844,"window_id":10725,"tree_format":"elements"}'
-```
-
-## `cua-driver manifest`
-
-Emit a stable JSON description of the CLI surface.
-
-Consumers can use this instead of hardcoding launch arguments such as the MCP invocation.
-
-```text output
-cua-driver manifest [OPTIONS]
-```
-
-| Flag | Short | Type | Default | Description |
-| --- | --- | --- | --- | --- |
-| <span id="cua-driver-manifest--pretty"></span>`--pretty` | `-p` | boolean | `false` | Pretty-print JSON. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-manifest"
-# Print the CLI surface as JSON
-cua-driver manifest --pretty
-```
-
-## `cua-driver dump-docs`
-
-Output machine-readable CLI and MCP documentation JSON.
-
-Used by the docs generator to keep reference pages in sync with the live binary.
-
-```text output
-cua-driver dump-docs [OPTIONS]
-```
-
-| Flag | Short | Type | Default | Description |
-| --- | --- | --- | --- | --- |
-| <span id="cua-driver-dump-docs--type"></span>`--type` | | string | `all` | Which docs to emit: all, cli, or mcp. |
-| <span id="cua-driver-dump-docs--pretty"></span>`--pretty` | `-p` | boolean | `false` | Pretty-print JSON. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-dump-docs"
-# Print the CLI documentation JSON
-cua-driver dump-docs --type cli --pretty
-```
-
-## Exit codes
-
-| Code | Meaning |
-| --- | --- |
-| `0` | Success. |
-| `1` | Failure: the daemon is not running or is incompatible, a tool call returned an error, or the operation failed. `call` and direct tool invocations exit with the daemon's result code (1 on a tool error); `update --apply` passes through the installer's status. |
-| `2` | Invalid input: tool arguments that are not valid JSON, an unknown `mcp-config` client, or an `update --apply` refused on a local development install. |
-| `64` | Usage error: an unknown or missing subcommand or argument, or conflicting flags (for example `revoke` without exactly one of `--session` or `--all`, or an authorization flag passed to `mcp`). |
diff --git a/docs/content/docs/cua-driver/reference/cli/meta.json b/docs/content/docs/cua-driver/reference/cli/meta.json
index 0d876c5a44..e4587cf2f2 100644
--- a/docs/content/docs/cua-driver/reference/cli/meta.json
+++ b/docs/content/docs/cua-driver/reference/cli/meta.json
@@ -2,13 +2,7 @@
"title": "CLI",
"pages": [
"index",
- "mcp",
- "daemon",
- "permissions",
- "recording",
- "history",
- "config",
- "extensions",
- "updates"
+ "serve-and-configure",
+ "skills-recording-and-history"
]
}
diff --git a/docs/content/docs/cua-driver/reference/cli/permissions.mdx b/docs/content/docs/cua-driver/reference/cli/permissions.mdx
deleted file mode 100644
index 348bd8da14..0000000000
--- a/docs/content/docs/cua-driver/reference/cli/permissions.mdx
+++ /dev/null
@@ -1,131 +0,0 @@
----
-title: "Permissions and diagnostics"
-description: "macOS permission grants, diagnostic probes and install reports."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-driver
- Source: cua-driver dump-docs --type cli
- Version: 0.36.0
-*/}
-
-| Command | Description |
-| --- | --- |
-| [`cua-driver permissions`](#cua-driver-permissions) | Inspect or raise macOS TCC permission grants (macOS only). |
-| [`cua-driver permissions status`](#cua-driver-permissions-status) | Report Accessibility and Screen Recording status through a running daemon (read-only, no prompt). |
-| [`cua-driver permissions grant`](#cua-driver-permissions-grant) | Launch CuaDriver through LaunchServices so the permission prompts are attributed to the app. |
-| [`cua-driver doctor`](#cua-driver-doctor) | Run platform-aware diagnostic probes. |
-| [`cua-driver diagnose`](#cua-driver-diagnose) | Print a pasteable install-layout and permission-attribution report. |
-
-`cua-driver permissions` exists on macOS only; Windows and Linux have no TCC equivalent.
-
-- `permissions status` is read-only and never prompts. It does not run the ScreenCaptureKit probe (macOS Tahoe can show a separate dialog for it), so it reports `screen_recording_capturable: null` and `direct_capture_status: "not_checked"`, plus the last successful `permissions grant` verification when one is recorded for the running driver identity.
-- `permissions grant` launches the installed `CuaDriver.app` through LaunchServices so the prompts attribute to the app, then requires a successful live capture probe. It never sends a prompt-capable request over the daemon socket.
-- Embedded hosts, in-process `CuaDriver.create()` runtimes and `cua-driver mcp --direct` own their own prompts: there, `check_permissions` stays read-only even with `{"prompt": true}`.
-- After a grant changes, quit and relaunch the responsible app (`CuaDriver.app`, or the host of a direct runtime).
-
-See [Permissions](/cua-driver/guides/permissions) for the grant flow and recovery.
-
-Every command also accepts the [global options](/cua-driver/reference/cli#global-options).
-
-## `cua-driver permissions`
-
-Inspect or raise macOS TCC permission grants (macOS only).
-
-macOS only: Accessibility and Screen Recording are macOS TCC grants. See the macOS permissions reference.
-
-```text output
-cua-driver permissions [COMMAND]
-```
-
-Without a subcommand, runs `cua-driver permissions status`.
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-permissions"
-# Report Accessibility and Screen Recording status
-cua-driver permissions
-```
-
-### `cua-driver permissions status`
-
-Report Accessibility and Screen Recording status through a running daemon (read-only, no prompt). The default subcommand.
-
-```text output
-cua-driver permissions status [OPTIONS]
-```
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-driver-permissions-status--json"></span>`--json` | boolean | `false` | Emit machine-readable output. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-permissions-status"
-# Report the grants as JSON
-cua-driver permissions status --json
-```
-
-### `cua-driver permissions grant`
-
-Launch CuaDriver through LaunchServices so the permission prompts are attributed to the app.
-
-```text output
-cua-driver permissions grant
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-permissions-grant"
-# Request the grants for CuaDriver.app
-cua-driver permissions grant
-```
-
-## `cua-driver doctor`
-
-Run platform-aware diagnostic probes.
-
-Exit code is non-zero when any probe is an error.
-
-```text output
-cua-driver doctor [OPTIONS]
-```
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-driver-doctor--json"></span>`--json` | boolean | `false` | Emit the probe report as JSON. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-doctor"
-# Run the diagnostic probes
-cua-driver doctor
-
-# Emit the probe report as JSON
-cua-driver doctor --json
-```
-
-## `cua-driver diagnose`
-
-Print a pasteable install-layout and permission-attribution report.
-
-```text output
-cua-driver diagnose
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-diagnose"
-# Print an install and permission report to paste into an issue
-cua-driver diagnose
-```
-
-## Exit codes
-
-| Code | Meaning |
-| --- | --- |
-| `0` | Success. |
-| `1` | Failure: the daemon is not running or is incompatible, a tool call returned an error, or the operation failed. `call` and direct tool invocations exit with the daemon's result code (1 on a tool error); `update --apply` passes through the installer's status. |
-| `2` | Invalid input: tool arguments that are not valid JSON, an unknown `mcp-config` client, or an `update --apply` refused on a local development install. |
-| `64` | Usage error: an unknown or missing subcommand or argument, or conflicting flags (for example `revoke` without exactly one of `--session` or `--all`, or an authorization flag passed to `mcp`). |
diff --git a/docs/content/docs/cua-driver/reference/cli/recording.mdx b/docs/content/docs/cua-driver/reference/cli/recording.mdx
deleted file mode 100644
index 03d3c9ff1f..0000000000
--- a/docs/content/docs/cua-driver/reference/cli/recording.mdx
+++ /dev/null
@@ -1,128 +0,0 @@
----
-title: "Trajectory recording"
-description: "Record, inspect and render action trajectories."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-driver
- Source: cua-driver dump-docs --type cli
- Version: 0.36.0
-*/}
-
-| Command | Description |
-| --- | --- |
-| [`cua-driver recording start`](#cua-driver-recording-start) | Start trajectory recording to a directory. |
-| [`cua-driver recording stop`](#cua-driver-recording-stop) | Stop trajectory recording. |
-| [`cua-driver recording status`](#cua-driver-recording-status) | Print the current recording state. |
-| [`cua-driver recording render`](#cua-driver-recording-render) | Render a recorded trajectory directory to an MP4. |
-
-Every command also accepts the [global options](/cua-driver/reference/cli#global-options).
-
-<span id="cua-driver-recording"></span>
-
-Control trajectory recording on a running daemon.
-
-Recording state lives in the required daemon and survives client reconnects.
-
-```text output
-cua-driver recording [OPTIONS] [COMMAND]
-```
-
-Without a subcommand, runs `cua-driver recording status`.
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-driver-recording--socket"></span>`--socket` | string | | Override the daemon socket or named-pipe path. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-recording"
-# Print the current recording state
-cua-driver recording
-```
-
-## `cua-driver recording start`
-
-Start trajectory recording to a directory.
-
-```text output
-cua-driver recording start <output-dir>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<output-dir>` | path | required | Directory to write turn folders into. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-recording-start"
-# Record turns into a directory
-cua-driver recording start ~/cua-trajectories/demo1
-```
-
-## `cua-driver recording stop`
-
-Stop trajectory recording.
-
-```text output
-cua-driver recording stop
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-recording-stop"
-# Stop recording
-cua-driver recording stop
-```
-
-## `cua-driver recording status`
-
-Print the current recording state.
-
-```text output
-cua-driver recording status
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-recording-status"
-# Print the recording state
-cua-driver recording status
-```
-
-## `cua-driver recording render`
-
-Render a recorded trajectory directory to an MP4.
-
-This pure file-to-file path does not require a running daemon.
-
-```text output
-cua-driver recording render [OPTIONS] <input-dir> <out-mp4>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<input-dir>` | path | required | Trajectory directory containing recorded turn folders. |
-| `<out-mp4>` | path | required | Output MP4 path. |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-driver-recording-render--scale"></span>`--scale` | number | | Scale factor for rendered frames. |
-| <span id="cua-driver-recording-render--no-zoom"></span>`--no-zoom` | boolean | `false` | Disable cursor/action zoom effects in the rendered video. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-recording-render"
-# Render a recorded trajectory to MP4
-cua-driver recording render ~/cua-trajectories/demo1 demo1.mp4
-```
-
-## Exit codes
-
-| Code | Meaning |
-| --- | --- |
-| `0` | Success. |
-| `1` | Failure: the daemon is not running or is incompatible, a tool call returned an error, or the operation failed. `call` and direct tool invocations exit with the daemon's result code (1 on a tool error); `update --apply` passes through the installer's status. |
-| `2` | Invalid input: tool arguments that are not valid JSON, an unknown `mcp-config` client, or an `update --apply` refused on a local development install. |
-| `64` | Usage error: an unknown or missing subcommand or argument, or conflicting flags (for example `revoke` without exactly one of `--session` or `--all`, or an authorization flag passed to `mcp`). |
diff --git a/docs/content/docs/cua-driver/reference/cli/serve-and-configure.mdx b/docs/content/docs/cua-driver/reference/cli/serve-and-configure.mdx
new file mode 100644
index 0000000000..7cbafdc611
--- /dev/null
+++ b/docs/content/docs/cua-driver/reference/cli/serve-and-configure.mdx
@@ -0,0 +1,1125 @@
+---
+title: "Serve, configure and update"
+description: "Serve MCP and call tools from the shell; run the daemon; grant permissions and diagnose; configure the driver, telemetry and cursor; update and pick a release channel."
+---
+
+{/*
+ AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
+ Generated by: pnpm --dir docs docs:generate:cua-driver
+ Source: cua-driver dump-docs --type cli
+ Version: 0.36.0
+*/}
+
+| Command | Description |
+| --- | --- |
+| [`cua-driver mcp`](#cua-driver-mcp) | Run the stdio MCP server. |
+| [`cua-driver mcp-config`](#cua-driver-mcp-config) | Print client-specific connection guidance (MCP config where supported) and install the skill pack for that agent. |
+| [`cua-driver list-tools`](#cua-driver-list-tools) | List every registered MCP tool with a one-line description. |
+| [`cua-driver describe`](#cua-driver-describe) | Print a tool's full description and JSON input schema. |
+| [`cua-driver call`](#cua-driver-call) | Invoke an MCP tool through the running daemon. |
+| [`cua-driver manifest`](#cua-driver-manifest) | Emit a stable JSON description of the CLI surface. |
+| [`cua-driver dump-docs`](#cua-driver-dump-docs) | Output machine-readable CLI and MCP documentation JSON. |
+| [`cua-driver serve`](#cua-driver-serve) | Run Cua Driver as a long-running daemon. |
+| [`cua-driver stop`](#cua-driver-stop) | Ask the running daemon to exit gracefully. |
+| [`cua-driver status`](#cua-driver-status) | Report whether a Cua Driver daemon is running. |
+| [`cua-driver sessions`](#cua-driver-sessions) | List content-free lifecycle summaries for sessions owned by the daemon runtime. |
+| [`cua-driver sessions list`](#cua-driver-sessions-list) | List live sessions. |
+| [`cua-driver revoke`](#cua-driver-revoke) | Revoke one or all live authorization/session scopes. |
+| [`cua-driver autostart`](#cua-driver-autostart) | Manage platform-native daemon autostart. |
+| [`cua-driver autostart enable`](#cua-driver-autostart-enable) | Register the autostart entry. |
+| [`cua-driver autostart disable`](#cua-driver-autostart-disable) | Remove the autostart entry. |
+| [`cua-driver autostart status`](#cua-driver-autostart-status) | Print whether autostart is registered and running. |
+| [`cua-driver autostart kick`](#cua-driver-autostart-kick) | Start the autostart entry now without re-logging. |
+| [`cua-driver permissions`](#cua-driver-permissions) | Inspect or raise macOS TCC permission grants (macOS only). |
+| [`cua-driver permissions status`](#cua-driver-permissions-status) | Report Accessibility and Screen Recording status through a running daemon (read-only, no prompt). |
+| [`cua-driver permissions grant`](#cua-driver-permissions-grant) | Launch CuaDriver through LaunchServices so the permission prompts are attributed to the app. |
+| [`cua-driver doctor`](#cua-driver-doctor) | Run platform-aware diagnostic probes. |
+| [`cua-driver diagnose`](#cua-driver-diagnose) | Print a pasteable install-layout and permission-attribution report. |
+| [`cua-driver config`](#cua-driver-config) | Read or mutate persistent driver configuration. |
+| [`cua-driver config show`](#cua-driver-config-show) | Print the full config. |
+| [`cua-driver config get`](#cua-driver-config-get) | Print one config key. |
+| [`cua-driver config set`](#cua-driver-config-set) | Set one config key. |
+| [`cua-driver config reset`](#cua-driver-config-reset) | Reset config to defaults. |
+| [`cua-driver telemetry`](#cua-driver-telemetry) | Inspect or change content-free product telemetry. |
+| [`cua-driver telemetry enable`](#cua-driver-telemetry-enable) | Persistently enable telemetry. |
+| [`cua-driver telemetry disable`](#cua-driver-telemetry-disable) | Persistently disable every telemetry request. |
+| [`cua-driver telemetry status`](#cua-driver-telemetry-status) | Show the effective setting and redacted identity state. |
+| [`cua-driver telemetry reset-id`](#cua-driver-telemetry-reset-id) | Erase the installation ID and event markers. |
+| [`cua-driver telemetry inspect`](#cua-driver-telemetry-inspect) | Build a fixed event payload without sending it. |
+| [`cua-driver cursor-theme`](#cua-driver-cursor-theme) | Validate, compile, inspect, preview, install, or remove a local cursor theme. |
+| [`cua-driver cursor-theme validate`](#cua-driver-cursor-theme-validate) | Validate a bounded dotLottie source archive. |
+| [`cua-driver cursor-theme build`](#cua-driver-cursor-theme-build) | Compile a validated dotLottie archive into a bounded .cua-theme artifact. |
+| [`cua-driver cursor-theme inspect`](#cua-driver-cursor-theme-inspect) | Inspect metadata in a compiled .cua-theme artifact. |
+| [`cua-driver cursor-theme preview`](#cua-driver-cursor-theme-preview) | Render a compiled theme's representative still frames to a directory. |
+| [`cua-driver cursor-theme install`](#cua-driver-cursor-theme-install) | Install a compiled theme into the current user's theme store. |
+| [`cua-driver cursor-theme list`](#cua-driver-cursor-theme-list) | List the built-in and installed cursor themes. |
+| [`cua-driver cursor-theme uninstall`](#cua-driver-cursor-theme-uninstall) | Remove a custom theme from the current user's theme store. |
+| [`cua-driver cursor`](#cua-driver-cursor) | Configure a session's agent cursor from the command line. |
+| [`cua-driver cursor motion`](#cua-driver-cursor-motion) | Set the cursor's motion style, timing and effects. |
+| [`cua-driver check-update`](#cua-driver-check-update) | Check whether a newer cua-driver release is available. |
+| [`cua-driver update`](#cua-driver-update) | Check for an update and optionally apply it. |
+| [`cua-driver channel`](#cua-driver-channel) | Inspect or change the stable/nightly update channel. |
+| [`cua-driver channel status`](#cua-driver-channel-status) | Show selected and current release channels. |
+| [`cua-driver channel set`](#cua-driver-channel-set) | Save stable or nightly as the update channel. |
+
+Every command also accepts the [global options](/cua-driver/reference/cli#global-options).
+
+## `cua-driver mcp`
+
+Run the stdio MCP server.
+
+On Windows and Linux, bare cua-driver mcp owns its runtime directly and shuts it down on stdin EOF. On macOS it proxies to CuaDriver.app so desktop permissions retain the app identity. Pass --direct to make the macOS MCP process own the runtime and TCC attribution, or --socket to select an explicit daemon endpoint.
+
+```text output
+cua-driver mcp [OPTIONS]
+```
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-driver-mcp--socket"></span>`--socket` | string | | Select an explicit daemon socket or named-pipe endpoint. |
+| <span id="cua-driver-mcp--host-bundle-id"></span>`--host-bundle-id` | string | | Advisory host bundle id label echoed in check_permissions output (embedded mode). |
+| <span id="cua-driver-mcp--cursor-theme"></span>`--cursor-theme` | string | `cua.default` | Select an installed cursor theme id. |
+| <span id="cua-driver-mcp--cursor-reduced-motion"></span>`--cursor-reduced-motion` | string | `auto` | Follow the OS setting, force still frames, or allow animation: auto, on, or off. |
+| <span id="cua-driver-mcp--grant"></span>`--grant` | string | | Pre-authorize a residual standard-mode boundary for a newly launched runtime. Repeatable; supported value: existing-profile. |
+| <span id="cua-driver-mcp--direct"></span>`--direct` | boolean | `false` | Own the runtime in this MCP process; mutually exclusive with --socket. |
+| <span id="cua-driver-mcp--claude-code-computer-use-compat"></span>`--claude-code-computer-use-compat` | boolean | `false` | Accepted for older Claude Code setup snippets; there is no standalone screenshot tool; use get_window_state for window screenshots. |
+| <span id="cua-driver-mcp--embedded"></span>`--embedded` | boolean | `false` | Declare embedding-host mode. Without --direct, require the host's private service through --socket instead of auto-launching the standalone app. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-mcp"
+# Run the stdio MCP server (what MCP clients launch)
+cua-driver mcp
+
+# Connect to a daemon on an explicit socket
+cua-driver mcp --socket /tmp/cua-driver.sock
+```
+
+## `cua-driver mcp-config`
+
+Print client-specific connection guidance (MCP config where supported) and install the skill pack for that agent.
+
+Supported clients include claude, codex, cursor, antigravity, openclaw, opencode, hermes, pi, prime-agent, qwen, droid, and zcode. With --client, the cua-driver skill pack is also installed for that agent (not for qwen, droid or zcode, which have no skills folder), and one line on stderr says where; --no-skills skips it.
+
+```text output
+cua-driver mcp-config [OPTIONS]
+```
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-driver-mcp-config--client"></span>`--client` | string | | Client name to print configuration for. |
+| <span id="cua-driver-mcp-config--no-skills"></span>`--no-skills` | boolean | `false` | With --client, do not install the cua-driver skill pack for that agent. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-mcp-config"
+# Print a generic mcpServers entry
+cua-driver mcp-config
+
+# Print setup for Codex and install its skill pack
+cua-driver mcp-config --client codex
+
+# Print setup for Codex only
+cua-driver mcp-config --client codex --no-skills
+```
+
+## `cua-driver list-tools`
+
+List every registered MCP tool with a one-line description.
+
+```text output
+cua-driver list-tools
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-list-tools"
+# List every tool with a one-line description
+cua-driver list-tools
+```
+
+## `cua-driver describe`
+
+Print a tool's full description and JSON input schema.
+
+```text output
+cua-driver describe <tool-name>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<tool-name>` | string | required | Name of the MCP tool to describe. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-describe"
+# Print a tool's description and input schema
+cua-driver describe click
+```
+
+## `cua-driver call`
+
+Invoke an MCP tool through the running daemon.
+
+Requires a Cua Driver daemon. JSON arguments may be passed as a positional JSON object or through stdin.
+
+```text output
+cua-driver call [OPTIONS] <tool-name> [<json-args>]
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<tool-name>` | string | required | Name of the MCP tool to invoke. |
+| `<json-args>` | string | optional | JSON object for the tool input schema. If omitted, stdin is read when piped. |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-driver-call--screenshot-out-file"></span>`--screenshot-out-file` | path | | Write the first image content block from the response to this path. |
+| <span id="cua-driver-call--socket"></span>`--socket` | string | | Override the daemon socket or named-pipe path. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-call"
+# Call a tool with no arguments
+cua-driver call list_apps
+
+# Click at window coordinates
+cua-driver call click '{"pid":844,"x":100,"y":200}'
+
+# Save the screenshot from a tool response
+cua-driver call get_window_state '{"pid":844,"window_id":10725}' --screenshot-out-file state.png
+
+# Read only what changed since an earlier snapshot_id
+cua-driver call get_window_state '{"pid":844,"window_id":10725,"since":"s0000002a"}'
+
+# Return the structured elements instead of the markdown tree
+cua-driver call get_window_state '{"pid":844,"window_id":10725,"tree_format":"elements"}'
+```
+
+## `cua-driver manifest`
+
+Emit a stable JSON description of the CLI surface.
+
+Consumers can use this instead of hardcoding launch arguments such as the MCP invocation.
+
+```text output
+cua-driver manifest [OPTIONS]
+```
+
+| Flag | Short | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| <span id="cua-driver-manifest--pretty"></span>`--pretty` | `-p` | boolean | `false` | Pretty-print JSON. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-manifest"
+# Print the CLI surface as JSON
+cua-driver manifest --pretty
+```
+
+## `cua-driver dump-docs`
+
+Output machine-readable CLI and MCP documentation JSON.
+
+Used by the docs generator to keep reference pages in sync with the live binary.
+
+```text output
+cua-driver dump-docs [OPTIONS]
+```
+
+| Flag | Short | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| <span id="cua-driver-dump-docs--type"></span>`--type` | | string | `all` | Which docs to emit: all, cli, or mcp. |
+| <span id="cua-driver-dump-docs--pretty"></span>`--pretty` | `-p` | boolean | `false` | Pretty-print JSON. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-dump-docs"
+# Print the CLI documentation JSON
+cua-driver dump-docs --type cli --pretty
+```
+
+## `cua-driver serve`
+
+Run Cua Driver as a long-running daemon.
+
+The daemon owns per-process state such as accessibility snapshots, recording state, and cursor overlay state.
+
+```text output
+cua-driver serve [OPTIONS]
+```
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-driver-serve--socket"></span>`--socket` | string | | Override the daemon socket or named-pipe path. |
+| <span id="cua-driver-serve--pid-file"></span>`--pid-file` | path | | Override the pid-file path. |
+| <span id="cua-driver-serve--permission-mode"></span>`--permission-mode` | string | `standard` | Immutable agent authorization mode: standard, bounded, or unrestricted. |
+| <span id="cua-driver-serve--grant"></span>`--grant` | string | | Pre-authorize a residual standard-mode boundary. Repeatable; supported value: existing-profile. |
+| <span id="cua-driver-serve--capability-manifest"></span>`--capability-manifest` | path | | Optional narrow-only tool/resource ceiling; required in bounded mode. |
+| <span id="cua-driver-serve--session-policy"></span>`--session-policy` | path | | Deprecated alias for capability-manifest. |
+| <span id="cua-driver-serve--host-bundle-id"></span>`--host-bundle-id` | string | | Advisory host bundle id label echoed in check_permissions output (embedded mode). |
+| <span id="cua-driver-serve--cursor-theme"></span>`--cursor-theme` | string | `cua.default` | Installed cursor theme id for the agent cursor overlay. |
+| <span id="cua-driver-serve--cursor-reduced-motion"></span>`--cursor-reduced-motion` | string | `auto` | Agent cursor motion: auto follows the OS setting, on forces still frames, off allows animation. |
+| <span id="cua-driver-serve--glide-ms"></span>`--glide-ms` | number | | Override the agent cursor glide duration, in milliseconds. |
+| <span id="cua-driver-serve--dwell-ms"></span>`--dwell-ms` | number | | Override how long the agent cursor dwells after a click, in milliseconds. |
+| <span id="cua-driver-serve--idle-hide-ms"></span>`--idle-hide-ms` | number | | Override how long an idle agent cursor stays visible, in milliseconds. |
+| <span id="cua-driver-serve--experimental-pip-geometry"></span>`--experimental-pip-geometry` | string | | Size and optional top-left origin of the experimental preview window: WxH or WxH+X+Y (default 480x360, top-right of the main display). |
+| <span id="cua-driver-serve--claude-code-computer-use-compat"></span>`--claude-code-computer-use-compat` | boolean | `false` | Select the Claude Code computer-use compatibility surface (forwarded by `mcp` when it launches the daemon). |
+| <span id="cua-driver-serve--experimental-pip"></span>`--experimental-pip` | boolean | `false` | Show a small always-on-top window with the latest post-action screenshot and a one-line label (macOS only). |
+| <span id="cua-driver-serve--dangerously-bypass-approvals"></span>`--dangerously-bypass-approvals` | boolean | `false` | Select unrestricted mode and acknowledge its risk. |
+| <span id="cua-driver-serve--approve-capability-manifest"></span>`--approve-capability-manifest` | boolean | `false` | Trusted-launcher confirmation that the exact capability manifest was reviewed. |
+| <span id="cua-driver-serve--approve-session-policy"></span>`--approve-session-policy` | boolean | `false` | Deprecated alias for approve-capability-manifest. |
+| <span id="cua-driver-serve--no-permissions-gate"></span>`--no-permissions-gate` | boolean | `false` | Skip the macOS first-launch permissions gate. |
+| <span id="cua-driver-serve--embedded"></span>`--embedded` | boolean | `false` | Run embedded inside a host app: inherit the host's TCC grants, never prompt or relaunch. Also CUA_DRIVER_EMBEDDED=1. |
+| <span id="cua-driver-serve--no-overlay"></span>`--no-overlay` | boolean | `false` | Disable the agent cursor overlay for this daemon. |
+| <span id="cua-driver-serve--experimental-history"></span>`--experimental-history` | boolean | `false` | Admit the encrypted local Computer History early preview for this daemon launch. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-serve"
+# Run the daemon in the foreground
+cua-driver serve
+
+# Start a bounded daemon with a reviewed capability manifest
+cua-driver serve --permission-mode bounded --capability-manifest manifest.yaml --approve-capability-manifest
+
+# Run without the agent cursor overlay
+cua-driver serve --no-overlay
+```
+
+## `cua-driver stop`
+
+Ask the running daemon to exit gracefully.
+
+```text output
+cua-driver stop [OPTIONS]
+```
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-driver-stop--socket"></span>`--socket` | string | | Override the daemon socket or named-pipe path. |
+| <span id="cua-driver-stop--expected-pid"></span>`--expected-pid` | number | | Stop only if the daemon's process id is this one (a positive integer). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-stop"
+# Ask the running daemon to exit
+cua-driver stop
+```
+
+## `cua-driver status`
+
+Report whether a Cua Driver daemon is running.
+
+```text output
+cua-driver status [OPTIONS]
+```
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-driver-status--socket"></span>`--socket` | string | | Override the daemon socket or named-pipe path. |
+| <span id="cua-driver-status--pid-file"></span>`--pid-file` | path | | Override the pid-file path. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-status"
+# Check whether the daemon is running
+cua-driver status
+```
+
+## `cua-driver sessions`
+
+List content-free lifecycle summaries for sessions owned by the daemon runtime.
+
+```text output
+cua-driver sessions [OPTIONS] [COMMAND]
+```
+
+Without a subcommand, runs `cua-driver sessions list`.
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-driver-sessions--socket"></span>`--socket` | string | | Override the daemon socket or named-pipe path. |
+| <span id="cua-driver-sessions--json"></span>`--json` | boolean | `false` | Emit the machine-readable session summary. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-sessions"
+# List live sessions as JSON
+cua-driver sessions --json
+```
+
+### `cua-driver sessions list`
+
+List live sessions. The default subcommand.
+
+```text output
+cua-driver sessions list
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-sessions-list"
+# List live sessions
+cua-driver sessions list
+```
+
+## `cua-driver revoke`
+
+Revoke one or all live authorization/session scopes.
+
+Revocation is deny-only and never accepts an approval token.
+
+```text output
+cua-driver revoke [OPTIONS]
+```
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-driver-revoke--session"></span>`--session` | string | | Exact session id to stop and revoke. |
+| <span id="cua-driver-revoke--socket"></span>`--socket` | string | | Override the daemon socket or named-pipe path. |
+| <span id="cua-driver-revoke--all"></span>`--all` | boolean | `false` | Stop and revoke every live session. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-revoke"
+# Stop and revoke one session
+cua-driver revoke --session 3f9c2a
+
+# Stop and revoke every live session
+cua-driver revoke --all
+```
+
+## `cua-driver autostart`
+
+Manage platform-native daemon autostart.
+
+Windows registers a logon Scheduled Task. macOS and Linux currently print manual-recipe guidance.
+
+```text output
+cua-driver autostart <COMMAND>
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-autostart"
+# Check the autostart entry
+cua-driver autostart status
+```
+
+### `cua-driver autostart enable`
+
+Register the autostart entry.
+
+```text output
+cua-driver autostart enable
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-autostart-enable"
+# Start the daemon at every logon
+cua-driver autostart enable
+```
+
+### `cua-driver autostart disable`
+
+Remove the autostart entry.
+
+```text output
+cua-driver autostart disable
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-autostart-disable"
+# Remove the autostart entry
+cua-driver autostart disable
+```
+
+### `cua-driver autostart status`
+
+Print whether autostart is registered and running.
+
+`not-registered` is emitted only when Task Scheduler explicitly reports that the named task does not exist. If the task cannot be inspected, the command exits non-zero and reports `permission-denied` or `unknown` together with the original diagnostic.
+
+```text output
+cua-driver autostart status
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-autostart-status"
+# Check the autostart entry
+cua-driver autostart status
+```
+
+### `cua-driver autostart kick`
+
+Start the autostart entry now without re-logging.
+
+```text output
+cua-driver autostart kick
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-autostart-kick"
+# Start the entry now
+cua-driver autostart kick
+```
+
+## `cua-driver permissions`
+
+`cua-driver permissions` exists on macOS only; Windows and Linux have no TCC equivalent.
+
+- `permissions status` is read-only and never prompts. It does not run the ScreenCaptureKit probe (macOS Tahoe can show a separate dialog for it), so it reports `screen_recording_capturable: null` and `direct_capture_status: "not_checked"`, plus the last successful `permissions grant` verification when one is recorded for the running driver identity.
+- `permissions grant` launches the installed `CuaDriver.app` through LaunchServices so the prompts attribute to the app, then requires a successful live capture probe. It never sends a prompt-capable request over the daemon socket.
+- Embedded hosts, in-process `CuaDriver.create()` runtimes and `cua-driver mcp --direct` own their own prompts: there, `check_permissions` stays read-only even with `{"prompt": true}`.
+- After a grant changes, quit and relaunch the responsible app (`CuaDriver.app`, or the host of a direct runtime).
+
+See [Permissions](/cua-driver/guides/permissions) for the grant flow and recovery.
+
+Inspect or raise macOS TCC permission grants (macOS only).
+
+macOS only: Accessibility and Screen Recording are macOS TCC grants. See the macOS permissions reference.
+
+```text output
+cua-driver permissions [COMMAND]
+```
+
+Without a subcommand, runs `cua-driver permissions status`.
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-permissions"
+# Report Accessibility and Screen Recording status
+cua-driver permissions
+```
+
+### `cua-driver permissions status`
+
+Report Accessibility and Screen Recording status through a running daemon (read-only, no prompt). The default subcommand.
+
+```text output
+cua-driver permissions status [OPTIONS]
+```
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-driver-permissions-status--json"></span>`--json` | boolean | `false` | Emit machine-readable output. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-permissions-status"
+# Report the grants as JSON
+cua-driver permissions status --json
+```
+
+### `cua-driver permissions grant`
+
+Launch CuaDriver through LaunchServices so the permission prompts are attributed to the app.
+
+```text output
+cua-driver permissions grant
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-permissions-grant"
+# Request the grants for CuaDriver.app
+cua-driver permissions grant
+```
+
+## `cua-driver doctor`
+
+Run platform-aware diagnostic probes.
+
+Exit code is non-zero when any probe is an error.
+
+```text output
+cua-driver doctor [OPTIONS]
+```
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-driver-doctor--json"></span>`--json` | boolean | `false` | Emit the probe report as JSON. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-doctor"
+# Run the diagnostic probes
+cua-driver doctor
+
+# Emit the probe report as JSON
+cua-driver doctor --json
+```
+
+## `cua-driver diagnose`
+
+Print a pasteable install-layout and permission-attribution report.
+
+```text output
+cua-driver diagnose
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-diagnose"
+# Print an install and permission report to paste into an issue
+cua-driver diagnose
+```
+
+## `cua-driver config`
+
+Read or mutate persistent driver configuration.
+
+Without a subcommand, prints the full config.
+
+```text output
+cua-driver config [OPTIONS] [COMMAND]
+```
+
+Without a subcommand, runs `cua-driver config show`.
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-driver-config--socket"></span>`--socket` | string | | Override the daemon socket or named-pipe path. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-config"
+# Print the full config
+cua-driver config
+```
+
+### `cua-driver config show`
+
+Print the full config.
+
+```text output
+cua-driver config show
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-config-show"
+# Print the full config
+cua-driver config show
+```
+
+### `cua-driver config get`
+
+Print one config key.
+
+```text output
+cua-driver config get <key>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<key>` | string | required | Config key to read. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-config-get"
+# Print one key
+cua-driver config get max_image_dimension
+```
+
+### `cua-driver config set`
+
+Set one config key.
+
+Cursor motion defaults are saved keys that apply to sessions started afterwards: cursor.motion.style (signature_arc, spring_settle, magnetic, comet_swoop, adaptive, classic), cursor.motion.timing (native, fitts, fixed) and cursor.motion.effects.&lt;trail|glow|magnet|ripple|squish&gt; (on, off, default). Use default for a key to clear it, or cursor.motion default to clear all. A start_session cursor_motion or a set_agent_cursor_motion call overrides the saved default. cursor.badges (minimal, verbose, off) sets the agent cursor badge for every cursor at once; minimal is the default.
+
+```text output
+cua-driver config set <key> <value>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<key>` | string | required | Config key to write. |
+| `<value>` | string | required | Value to store. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-config-set"
+# Downscale screenshots to at most 1568 px
+cua-driver config set max_image_dimension 1568
+
+# Make magnetic the default cursor motion for new sessions
+cua-driver config set cursor.motion.style magnetic
+
+# Scale cursor move time with distance and target size
+cua-driver config set cursor.motion.timing fitts
+
+# Drop the 600 ms floor of the default steady timing
+cua-driver config set cursor.motion.timing native
+
+# Turn the cursor trail on by default
+cua-driver config set cursor.motion.effects.trail true
+```
+
+### `cua-driver config reset`
+
+Reset config to defaults.
+
+```text output
+cua-driver config reset
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-config-reset"
+# Restore the defaults
+cua-driver config reset
+```
+
+## `cua-driver telemetry`
+
+Inspect or change content-free product telemetry.
+
+Telemetry is default-on. Disable retains the pseudonymous installation ID; reset-id erases the ID and event markers while preserving the preference.
+
+```text output
+cua-driver telemetry <COMMAND>
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-telemetry"
+# Show the effective telemetry setting
+cua-driver telemetry status
+```
+
+### `cua-driver telemetry enable`
+
+Persistently enable telemetry.
+
+```text output
+cua-driver telemetry enable
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-telemetry-enable"
+# Enable telemetry
+cua-driver telemetry enable
+```
+
+### `cua-driver telemetry disable`
+
+Persistently disable every telemetry request.
+
+Retains the local installation ID.
+
+```text output
+cua-driver telemetry disable
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-telemetry-disable"
+# Disable every telemetry request
+cua-driver telemetry disable
+```
+
+### `cua-driver telemetry status`
+
+Show the effective setting and redacted identity state.
+
+```text output
+cua-driver telemetry status [OPTIONS]
+```
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-driver-telemetry-status--json"></span>`--json` | boolean | `false` | Emit JSON. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-telemetry-status"
+# Show the setting as JSON
+cua-driver telemetry status --json
+```
+
+### `cua-driver telemetry reset-id`
+
+Erase the installation ID and event markers.
+
+The persisted enabled/disabled preference is retained.
+
+```text output
+cua-driver telemetry reset-id
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-telemetry-reset-id"
+# Erase the installation ID
+cua-driver telemetry reset-id
+```
+
+### `cua-driver telemetry inspect`
+
+Build a fixed event payload without sending it.
+
+The distinct ID is replaced with a redacted placeholder.
+
+```text output
+cua-driver telemetry inspect [OPTIONS] <event>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<event>` | string | required | Fixed telemetry event name. |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-driver-telemetry-inspect--json"></span>`--json` | boolean | `false` | Emit JSON (the only output format; pass it for forward compatibility). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-telemetry-inspect"
+# Show the payload of one event without sending it
+cua-driver telemetry inspect cua_driver_cli_completed --json
+```
+
+## `cua-driver cursor-theme`
+
+Validate, compile, inspect, preview, install, or remove a local cursor theme.
+
+This is a trusted local authoring workflow. Agent-facing tools may select an installed theme id, but cannot install source or compiled theme data.
+
+```text output
+cua-driver cursor-theme <COMMAND>
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-cursor-theme"
+# List cursor themes
+cua-driver cursor-theme list
+```
+
+### `cua-driver cursor-theme validate`
+
+Validate a bounded dotLottie source archive.
+
+```text output
+cua-driver cursor-theme validate [OPTIONS] <source>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<source>` | path | required | Path to the source .lottie archive. |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-driver-cursor-theme-validate--development"></span>`--development` | boolean | `false` | Allow the reserved com.example development namespace. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-cursor-theme-validate"
+# Validate a source archive
+cua-driver cursor-theme validate my-cursor.lottie
+```
+
+### `cua-driver cursor-theme build`
+
+Compile a validated dotLottie archive into a bounded .cua-theme artifact.
+
+```text output
+cua-driver cursor-theme build [OPTIONS] <source>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<source>` | path | required | Path to the source .lottie archive. |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-driver-cursor-theme-build--output"></span>`--output` | path | required | Output .cua-theme path. |
+| <span id="cua-driver-cursor-theme-build--development"></span>`--development` | boolean | `false` | Allow the reserved com.example development namespace. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-cursor-theme-build"
+# Compile a theme
+cua-driver cursor-theme build my-cursor.lottie --output my-cursor.cua-theme
+```
+
+### `cua-driver cursor-theme inspect`
+
+Inspect metadata in a compiled .cua-theme artifact.
+
+```text output
+cua-driver cursor-theme inspect [OPTIONS] <theme>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<theme>` | path | required | Path to the compiled .cua-theme artifact. |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-driver-cursor-theme-inspect--json"></span>`--json` | boolean | `false` | Emit machine-readable JSON. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-cursor-theme-inspect"
+# Print a theme's metadata
+cua-driver cursor-theme inspect my-cursor.cua-theme --json
+```
+
+### `cua-driver cursor-theme preview`
+
+Render a compiled theme's representative still frames to a directory.
+
+```text output
+cua-driver cursor-theme preview [OPTIONS] <theme>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<theme>` | path | required | Path to the compiled .cua-theme artifact. |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-driver-cursor-theme-preview--output"></span>`--output` | path | required | Preview output directory. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-cursor-theme-preview"
+# Render still frames
+cua-driver cursor-theme preview my-cursor.cua-theme --output preview
+```
+
+### `cua-driver cursor-theme install`
+
+Install a compiled theme into the current user's theme store.
+
+```text output
+cua-driver cursor-theme install <theme>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<theme>` | path | required | Path to the compiled .cua-theme artifact. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-cursor-theme-install"
+# Install a theme
+cua-driver cursor-theme install my-cursor.cua-theme
+```
+
+### `cua-driver cursor-theme list`
+
+List the built-in and installed cursor themes.
+
+```text output
+cua-driver cursor-theme list [OPTIONS]
+```
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-driver-cursor-theme-list--json"></span>`--json` | boolean | `false` | Emit machine-readable JSON. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-cursor-theme-list"
+# List themes as JSON
+cua-driver cursor-theme list --json
+```
+
+### `cua-driver cursor-theme uninstall`
+
+Remove a custom theme from the current user's theme store.
+
+The built-in cua.default theme cannot be removed.
+
+```text output
+cua-driver cursor-theme uninstall <theme-id>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<theme-id>` | string | required | Installed custom theme id. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-cursor-theme-uninstall"
+# Remove an installed theme
+cua-driver cursor-theme uninstall com.example.my-cursor
+```
+
+## `cua-driver cursor`
+
+Configure a session's agent cursor from the command line.
+
+Forwards to the set_agent_cursor_motion tool on the running daemon. Fields you leave out keep their current value.
+
+```text output
+cua-driver cursor <COMMAND>
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-cursor"
+# Use the magnetic cursor motion
+cua-driver cursor motion --session demo --style magnetic
+```
+
+### `cua-driver cursor motion`
+
+Set the cursor's motion style, timing and effects.
+
+Effects take on, off, or default (the style's own choice).
+
+```text output
+cua-driver cursor motion [OPTIONS]
+```
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-driver-cursor-motion--session"></span>`--session` | string | required | Public label of the session that owns the cursor. |
+| <span id="cua-driver-cursor-motion--style"></span>`--style` | string | | signature_arc, spring_settle, magnetic, comet_swoop, adaptive, or classic. |
+| <span id="cua-driver-cursor-motion--timing"></span>`--timing` | string | | native, fitts, or fixed. |
+| <span id="cua-driver-cursor-motion--effects"></span>`--effects` | string | | Comma-separated name=on\|off\|default for trail, glow, magnet, ripple, squish. |
+| <span id="cua-driver-cursor-motion--glide-ms"></span>`--glide-ms` | number | | Move duration in milliseconds for fixed timing (1430 when 0). |
+| <span id="cua-driver-cursor-motion--socket"></span>`--socket` | path | | Override the daemon socket path. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-cursor-motion"
+# Use the comet swoop cursor motion
+cua-driver cursor motion --session demo --style comet_swoop
+
+# Make every move take 900 ms
+cua-driver cursor motion --session demo --timing fixed --glide-ms 900
+
+# Turn off the trail and reset the click ripple
+cua-driver cursor motion --session demo --effects trail=off,ripple=default
+```
+
+## `cua-driver check-update`
+
+Check whether a newer cua-driver release is available.
+
+Read-only. Uses the same update-state payload as the check_for_update MCP tool.
+
+```text output
+cua-driver check-update [OPTIONS]
+```
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-driver-check-update--json"></span>`--json` | boolean | `false` | Emit a machine-readable JSON payload. |
+| <span id="cua-driver-check-update--no-cache"></span>`--no-cache` | boolean | `false` | Skip the 1-hour on-disk cache and look up the latest release again. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-check-update"
+# Check for a newer release
+cua-driver check-update
+
+# Check now, as JSON
+cua-driver check-update --json --no-cache
+```
+
+## `cua-driver update`
+
+Check for an update and optionally apply it.
+
+The apply path delegates to the canonical platform installer scripts.
+
+```text output
+cua-driver update [OPTIONS]
+```
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-driver-update--apply"></span>`--apply` | boolean | `false` | Download and install the latest release when one is available. |
+| <span id="cua-driver-update--json"></span>`--json` | boolean | `false` | Emit the structured update-state payload. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-update"
+# Check and print the install command
+cua-driver update
+
+# Install the latest release
+cua-driver update --apply
+```
+
+## `cua-driver channel`
+
+Inspect or change the stable/nightly update channel.
+
+Selection is persistent but never installs by itself; use cua-driver update --apply after changing it.
+
+```text output
+cua-driver channel [COMMAND]
+```
+
+Without a subcommand, runs `cua-driver channel status`.
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-channel"
+# Show the selected release channel
+cua-driver channel
+```
+
+### `cua-driver channel status`
+
+Show selected and current release channels.
+
+```text output
+cua-driver channel status [OPTIONS]
+```
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-driver-channel-status--json"></span>`--json` | boolean | `false` | Emit machine-readable channel state. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-channel-status"
+# Show the channels as JSON
+cua-driver channel status --json
+```
+
+### `cua-driver channel set`
+
+Save stable or nightly as the update channel.
+
+```text output
+cua-driver channel set [OPTIONS] <channel>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<channel>` | string | required | Release channel: stable or nightly. |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-driver-channel-set--json"></span>`--json` | boolean | `false` | Emit machine-readable channel state. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-channel-set"
+# Follow nightly builds (then run update --apply)
+cua-driver channel set nightly
+```
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| `0` | Success. |
+| `1` | Failure: the daemon is not running or is incompatible, a tool call returned an error, or the operation failed. `call` and direct tool invocations exit with the daemon's result code (1 on a tool error); `update --apply` passes through the installer's status. |
+| `2` | Invalid input: tool arguments that are not valid JSON, an unknown `mcp-config` client, or an `update --apply` refused on a local development install. |
+| `64` | Usage error: an unknown or missing subcommand or argument, or conflicting flags (for example `revoke` without exactly one of `--session` or `--all`, or an authorization flag passed to `mcp`). |
diff --git a/docs/content/docs/cua-driver/reference/cli/extensions.mdx b/docs/content/docs/cua-driver/reference/cli/skills-recording-and-history.mdx
similarity index 62%
rename from docs/content/docs/cua-driver/reference/cli/extensions.mdx
rename to docs/content/docs/cua-driver/reference/cli/skills-recording-and-history.mdx
index a086a3cc73..950b1b5bf7 100644
--- a/docs/content/docs/cua-driver/reference/cli/extensions.mdx
+++ b/docs/content/docs/cua-driver/reference/cli/skills-recording-and-history.mdx
@@ -1,6 +1,6 @@
---
-title: "Skills and extensions"
-description: "The agent skill pack, signed extensions and the perception parser."
+title: "Skills, recording and history"
+description: "The agent skill pack, signed extensions and the perception parser; trajectory recording; the Computer History preview."
---
{/*
@@ -29,6 +29,21 @@ description: "The agent skill pack, signed extensions and the perception parser.
| [`cua-driver extension path`](#cua-driver-extension-path) | Compatibility command that prints the exact active version directory. |
| [`cua-driver perception`](#cua-driver-perception) | Parse a local PNG with the installed optional perception extension. |
| [`cua-driver perception parse`](#cua-driver-perception-parse) | Parse one local PNG into canonical visual regions. |
+| [`cua-driver recording`](#cua-driver-recording) | Control trajectory recording on a running daemon. |
+| [`cua-driver recording start`](#cua-driver-recording-start) | Start trajectory recording to a directory. |
+| [`cua-driver recording stop`](#cua-driver-recording-stop) | Stop trajectory recording. |
+| [`cua-driver recording status`](#cua-driver-recording-status) | Print the current recording state. |
+| [`cua-driver recording render`](#cua-driver-recording-render) | Render a recorded trajectory directory to an MP4. |
+| [`cua-driver history`](#cua-driver-history) | Encrypted, metadata-only Computer History early preview: lifecycle and local inspection. |
+| [`cua-driver history enable`](#cua-driver-history-enable) | Turn on the Computer History preview (admits it on a local daemon if needed). |
+| [`cua-driver history disable`](#cua-driver-history-disable) | Turn Computer History off; recorded chunks stay until deleted. |
+| [`cua-driver history pause`](#cua-driver-history-pause) | Pause recording without turning the preview off. |
+| [`cua-driver history resume`](#cua-driver-history-resume) | Resume recording after pause. |
+| [`cua-driver history status`](#cua-driver-history-status) | Print the Computer History state. |
+| [`cua-driver history flush`](#cua-driver-history-flush) | Seal the current chunk to disk now. |
+| [`cua-driver history list`](#cua-driver-history-list) | List recent metadata-only events. |
+| [`cua-driver history show`](#cua-driver-history-show) | Print one event by its sequence number. |
+| [`cua-driver history delete`](#cua-driver-history-delete) | Delete the encrypted chunks and their native credential-store key. |
Every command also accepts the [global options](/cua-driver/reference/cli#global-options).
@@ -391,6 +406,288 @@ cua-driver perception parse [OPTIONS]
cua-driver perception parse --image screen.png --capture capture.json --json
```
+## `cua-driver recording`
+
+Control trajectory recording on a running daemon.
+
+Recording state lives in the required daemon and survives client reconnects.
+
+```text output
+cua-driver recording [OPTIONS] [COMMAND]
+```
+
+Without a subcommand, runs `cua-driver recording status`.
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-driver-recording--socket"></span>`--socket` | string | | Override the daemon socket or named-pipe path. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-recording"
+# Print the current recording state
+cua-driver recording
+```
+
+### `cua-driver recording start`
+
+Start trajectory recording to a directory.
+
+```text output
+cua-driver recording start <output-dir>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<output-dir>` | path | required | Directory to write turn folders into. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-recording-start"
+# Record turns into a directory
+cua-driver recording start ~/cua-trajectories/demo1
+```
+
+### `cua-driver recording stop`
+
+Stop trajectory recording.
+
+```text output
+cua-driver recording stop
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-recording-stop"
+# Stop recording
+cua-driver recording stop
+```
+
+### `cua-driver recording status`
+
+Print the current recording state.
+
+```text output
+cua-driver recording status
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-recording-status"
+# Print the recording state
+cua-driver recording status
+```
+
+### `cua-driver recording render`
+
+Render a recorded trajectory directory to an MP4.
+
+This pure file-to-file path does not require a running daemon.
+
+```text output
+cua-driver recording render [OPTIONS] <input-dir> <out-mp4>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<input-dir>` | path | required | Trajectory directory containing recorded turn folders. |
+| `<out-mp4>` | path | required | Output MP4 path. |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-driver-recording-render--scale"></span>`--scale` | number | | Scale factor for rendered frames. |
+| <span id="cua-driver-recording-render--no-zoom"></span>`--no-zoom` | boolean | `false` | Disable cursor/action zoom effects in the rendered video. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-recording-render"
+# Render a recorded trajectory to MP4
+cua-driver recording render ~/cua-trajectories/demo1 demo1.mp4
+```
+
+## `cua-driver history`
+
+Encrypted, metadata-only Computer History early preview: lifecycle and local inspection.
+
+The daemon must be admitted for the preview (`cua-driver serve --experimental-history`); `enable` restarts a local daemon with it when needed.
+
+```text output
+cua-driver history [OPTIONS] [COMMAND]
+```
+
+Without a subcommand, runs `cua-driver history status`.
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-driver-history--socket"></span>`--socket` | string | | Override the daemon socket or named-pipe path. |
+| <span id="cua-driver-history--json"></span>`--json` | boolean | `false` | Emit machine-readable output. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-history"
+# Print the Computer History state
+cua-driver history
+```
+
+### `cua-driver history enable`
+
+Turn on the Computer History preview (admits it on a local daemon if needed).
+
+```text output
+cua-driver history enable
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-history-enable"
+# Turn on the Computer History preview
+cua-driver history enable
+```
+
+### `cua-driver history disable`
+
+Turn Computer History off; recorded chunks stay until deleted.
+
+```text output
+cua-driver history disable
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-history-disable"
+# Turn Computer History off
+cua-driver history disable
+```
+
+### `cua-driver history pause`
+
+Pause recording without turning the preview off.
+
+```text output
+cua-driver history pause
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-history-pause"
+# Pause recording
+cua-driver history pause
+```
+
+### `cua-driver history resume`
+
+Resume recording after pause.
+
+```text output
+cua-driver history resume
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-history-resume"
+# Resume recording
+cua-driver history resume
+```
+
+### `cua-driver history status`
+
+Print the Computer History state. The default subcommand.
+
+```text output
+cua-driver history status [OPTIONS]
+```
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-driver-history-status--json"></span>`--json` | boolean | `false` | Emit machine-readable output. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-history-status"
+# Print the state as JSON
+cua-driver history status --json
+```
+
+### `cua-driver history flush`
+
+Seal the current chunk to disk now.
+
+```text output
+cua-driver history flush
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-history-flush"
+# Seal the current chunk now
+cua-driver history flush
+```
+
+### `cua-driver history list`
+
+List recent metadata-only events.
+
+```text output
+cua-driver history list [OPTIONS] [<limit>]
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<limit>` | number | optional | Most events to print. |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-driver-history-list--json"></span>`--json` | boolean | `false` | Emit machine-readable output. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-history-list"
+# List the 20 most recent events
+cua-driver history list 20
+```
+
+### `cua-driver history show`
+
+Print one event by its sequence number.
+
+```text output
+cua-driver history show [OPTIONS] <sequence>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<sequence>` | number | required | Event sequence number. |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-driver-history-show--json"></span>`--json` | boolean | `false` | Emit machine-readable output. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-history-show"
+# Print event 42 as JSON
+cua-driver history show 42 --json
+```
+
+### `cua-driver history delete`
+
+Delete the encrypted chunks and their native credential-store key. Needs --yes.
+
+```text output
+cua-driver history delete [OPTIONS]
+```
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="cua-driver-history-delete--yes"></span>`--yes` | boolean | `false` | Confirm irreversible deletion of encrypted chunks and their native credential-store key. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-cua-driver-history-delete"
+# Delete every recorded chunk and its key
+cua-driver history delete --yes
+```
+
## Exit codes
| Code | Meaning |
diff --git a/docs/content/docs/cua-driver/reference/cli/updates.mdx b/docs/content/docs/cua-driver/reference/cli/updates.mdx
deleted file mode 100644
index 786f78b089..0000000000
--- a/docs/content/docs/cua-driver/reference/cli/updates.mdx
+++ /dev/null
@@ -1,141 +0,0 @@
----
-title: "Updates"
-description: "Check for and apply updates, and choose the release channel."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-driver
- Source: cua-driver dump-docs --type cli
- Version: 0.36.0
-*/}
-
-| Command | Description |
-| --- | --- |
-| [`cua-driver check-update`](#cua-driver-check-update) | Check whether a newer cua-driver release is available. |
-| [`cua-driver update`](#cua-driver-update) | Check for an update and optionally apply it. |
-| [`cua-driver channel`](#cua-driver-channel) | Inspect or change the stable/nightly update channel. |
-| [`cua-driver channel status`](#cua-driver-channel-status) | Show selected and current release channels. |
-| [`cua-driver channel set`](#cua-driver-channel-set) | Save stable or nightly as the update channel. |
-
-Every command also accepts the [global options](/cua-driver/reference/cli#global-options).
-
-## `cua-driver check-update`
-
-Check whether a newer cua-driver release is available.
-
-Read-only. Uses the same update-state payload as the check_for_update MCP tool.
-
-```text output
-cua-driver check-update [OPTIONS]
-```
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-driver-check-update--json"></span>`--json` | boolean | `false` | Emit a machine-readable JSON payload. |
-| <span id="cua-driver-check-update--no-cache"></span>`--no-cache` | boolean | `false` | Skip the 1-hour on-disk cache and look up the latest release again. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-check-update"
-# Check for a newer release
-cua-driver check-update
-
-# Check now, as JSON
-cua-driver check-update --json --no-cache
-```
-
-## `cua-driver update`
-
-Check for an update and optionally apply it.
-
-The apply path delegates to the canonical platform installer scripts.
-
-```text output
-cua-driver update [OPTIONS]
-```
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-driver-update--apply"></span>`--apply` | boolean | `false` | Download and install the latest release when one is available. |
-| <span id="cua-driver-update--json"></span>`--json` | boolean | `false` | Emit the structured update-state payload. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-update"
-# Check and print the install command
-cua-driver update
-
-# Install the latest release
-cua-driver update --apply
-```
-
-## `cua-driver channel`
-
-Inspect or change the stable/nightly update channel.
-
-Selection is persistent but never installs by itself; use cua-driver update --apply after changing it.
-
-```text output
-cua-driver channel [COMMAND]
-```
-
-Without a subcommand, runs `cua-driver channel status`.
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-channel"
-# Show the selected release channel
-cua-driver channel
-```
-
-### `cua-driver channel status`
-
-Show selected and current release channels.
-
-```text output
-cua-driver channel status [OPTIONS]
-```
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-driver-channel-status--json"></span>`--json` | boolean | `false` | Emit machine-readable channel state. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-channel-status"
-# Show the channels as JSON
-cua-driver channel status --json
-```
-
-### `cua-driver channel set`
-
-Save stable or nightly as the update channel.
-
-```text output
-cua-driver channel set [OPTIONS] <channel>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<channel>` | string | required | Release channel: stable or nightly. |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="cua-driver-channel-set--json"></span>`--json` | boolean | `false` | Emit machine-readable channel state. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-cua-driver-channel-set"
-# Follow nightly builds (then run update --apply)
-cua-driver channel set nightly
-```
-
-## Exit codes
-
-| Code | Meaning |
-| --- | --- |
-| `0` | Success. |
-| `1` | Failure: the daemon is not running or is incompatible, a tool call returned an error, or the operation failed. `call` and direct tool invocations exit with the daemon's result code (1 on a tool error); `update --apply` passes through the installer's status. |
-| `2` | Invalid input: tool arguments that are not valid JSON, an unknown `mcp-config` client, or an `update --apply` refused on a local development install. |
-| `64` | Usage error: an unknown or missing subcommand or argument, or conflicting flags (for example `revoke` without exactly one of `--session` or `--all`, or an authorization flag passed to `mcp`). |
diff --git a/docs/content/docs/cua-driver/reference/index.mdx b/docs/content/docs/cua-driver/reference/index.mdx
index 34ed8a9610..1f97f600f2 100644
--- a/docs/content/docs/cua-driver/reference/index.mdx
+++ b/docs/content/docs/cua-driver/reference/index.mdx
@@ -15,33 +15,15 @@ description: "Every cua-driver command and every MCP tool on macOS, Linux and Wi
| Command group | Description |
| --- | --- |
| [`cua-driver`](/cua-driver/reference/cli) | Synopsis, global options, exit codes and every command. |
-| [Tools and MCP](/cua-driver/reference/cli/mcp) | Serve MCP, print client config, and list, describe or call tools from the shell. |
-| [Daemon](/cua-driver/reference/cli/daemon) | Run, stop and inspect the daemon, its sessions and autostart. |
-| [Permissions and diagnostics](/cua-driver/reference/cli/permissions) | macOS permission grants, diagnostic probes and install reports. |
-| [Trajectory recording](/cua-driver/reference/cli/recording) | Record, inspect and render action trajectories. |
-| [Computer History](/cua-driver/reference/cli/history) | The encrypted, metadata-only Computer History preview. |
-| [Configuration](/cua-driver/reference/cli/config) | Driver configuration, telemetry, cursor themes and cursor motion. |
-| [Skills and extensions](/cua-driver/reference/cli/extensions) | The agent skill pack, signed extensions and the perception parser. |
-| [Updates](/cua-driver/reference/cli/updates) | Check for and apply updates, and choose the release channel. |
+| [Serve, configure and update](/cua-driver/reference/cli/serve-and-configure) | Serve MCP and call tools from the shell; run the daemon; grant permissions and diagnose; configure the driver, telemetry and cursor; update and pick a release channel. |
+| [Skills, recording and history](/cua-driver/reference/cli/skills-recording-and-history) | The agent skill pack, signed extensions and the perception parser; trajectory recording; the Computer History preview. |
## MCP tools
| Tools | Description |
| --- | --- |
| [All tools](/cua-driver/reference/mcp-tools) | Every `cua-driver mcp` tool with a one-line summary. |
-| [App and window tools](/cua-driver/reference/mcp-tools/apps-and-windows) | List, launch, quit, front and arrange apps and windows. 8 tools. |
-| [Window state tools](/cua-driver/reference/mcp-tools/window-state) | Screenshots, accessibility trees, verification and visual regions of a window. 4 tools. |
-| [Screen tools](/cua-driver/reference/mcp-tools/screen) | The desktop, screen size, cursor position and zoomed crops. 4 tools. |
-| [Click tool](/cua-driver/reference/mcp-tools/click) | Click by element or pixel. 1 tools. |
-| [Double-click and right-click tools](/cua-driver/reference/mcp-tools/double-and-right-click) | Double-click and right-click by element or pixel. 2 tools. |
-| [Pointer tools](/cua-driver/reference/mcp-tools/pointer) | Drag, scroll, move the pointer, and press or release buttons. 7 tools. |
-| [Typing tools](/cua-driver/reference/mcp-tools/keyboard) | Type text into a field or window. 1 tools. |
-| [Key and shortcut tools](/cua-driver/reference/mcp-tools/keys-and-shortcuts) | Press keys and keyboard shortcuts. 2 tools. |
-| [Value and clipboard tools](/cua-driver/reference/mcp-tools/values-and-clipboard) | Set element values and read or write the clipboard. 3 tools. |
-| [Batch and script tools](/cua-driver/reference/mcp-tools/batch) | Run several action tools, or a script that drives them, in one call. 2 tools. |
-| [Page tools](/cua-driver/reference/mcp-tools/page) | Read and act on web pages, and prepare and navigate browsers. 4 tools. |
-| [Browser input tools](/cua-driver/reference/mcp-tools/browser-input) | Exact browser input over CDP: clicks, typing, pointer, dialogs, files and downloads. 7 tools. |
-| [Session tools](/cua-driver/reference/mcp-tools/sessions) | Start, escalate, inspect and end lifecycle sessions. 6 tools. |
-| [Agent cursor tools](/cua-driver/reference/mcp-tools/agent-cursor) | Show, animate and style the agent cursor. 4 tools. |
-| [Recording tools](/cua-driver/reference/mcp-tools/recording) | Record and replay trajectories. 5 tools. |
-| [Configuration and maintenance tools](/cua-driver/reference/mcp-tools/maintenance) | Configuration, permissions, health, updates, extensions and on-demand guides. 7 tools. |
+| [Apps, windows and screen](/cua-driver/reference/mcp-tools/apps-windows-and-screen) | Apps and windows, window state and screenshots, the screen, and lifecycle sessions. 22 tools. |
+| [Click and type](/cua-driver/reference/mcp-tools/click-and-type) | Clicks, typing, keys and shortcuts, element values and the clipboard. 9 tools. |
+| [Pointer, cursor and browser](/cua-driver/reference/mcp-tools/pointer-cursor-and-browser) | Drag, scroll and move the pointer; the agent cursor; web pages and browser input. 22 tools. |
+| [Batch, recording and settings](/cua-driver/reference/mcp-tools/batch-recording-and-settings) | Run several actions in one call, record and replay trajectories, and configuration and maintenance. 14 tools. |
diff --git a/docs/content/docs/cua-driver/reference/mcp-tools/agent-cursor.mdx b/docs/content/docs/cua-driver/reference/mcp-tools/agent-cursor.mdx
deleted file mode 100644
index 4d701f9562..0000000000
--- a/docs/content/docs/cua-driver/reference/mcp-tools/agent-cursor.mdx
+++ /dev/null
@@ -1,104 +0,0 @@
----
-title: "Agent cursor tools"
-description: "Show, animate and style the agent cursor."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-driver
- Source: cua-driver dump-docs --type mcp (macOS, Linux and Windows registries)
- Version: 0.36.0
-*/}
-
-| Tool | Description | Platforms |
-| --- | --- | --- |
-| [`set_agent_cursor_enabled`](#set_agent_cursor_enabled) | Show or hide the agent cursor owned by a session. | macOS, Linux, Windows |
-| [`set_agent_cursor_motion`](#set_agent_cursor_motion) | Configure the movement style, timing, effects and visibility timing for a session cursor. | macOS, Linux, Windows |
-| [`set_agent_cursor_theme`](#set_agent_cursor_theme) | Select an already-installed cursor theme for a session. | macOS, Linux, Windows |
-| [`get_agent_cursor_state`](#get_agent_cursor_state) | Return the session cursor's theme, semantic playback, position, visibility, and motion. | macOS, Linux, Windows |
-
-Served by `cua-driver mcp`; see [MCP tools](/cua-driver/reference/mcp-tools) for every tool.
-
-## `set_agent_cursor_enabled`
-
-Show or hide the agent cursor owned by a session.
-
-Effect: mutating, idempotent. Platforms: macOS, Linux, Windows.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="set_agent_cursor_enabled--enabled"></span>`enabled` | `boolean` | required | `true` shows the session's agent cursor overlay; `false` hides it. |
-| <span id="set_agent_cursor_enabled--session"></span>`session` | `string` | required | Public label of the session that owns the cursor. |
-
-**Example arguments**
-
-```json
-{"session":"<session>","enabled":false}
-```
-
-## `set_agent_cursor_motion`
-
-Configure the movement style, timing, effects and visibility timing for a session cursor.
-
-Effect: mutating, idempotent. Platforms: macOS, Linux, Windows.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="set_agent_cursor_motion--arc_flow"></span>`arc_flow` | `number` | | Added to the arc asymmetry of `signature_arc`, `spring_settle` and `comet_swoop`: positive moves the apex toward the destination. Clamped to -1..1 (default 0). |
-| <span id="set_agent_cursor_motion--arc_size"></span>`arc_size` | `number` | | Scales the arc of `signature_arc`, `spring_settle` and `comet_swoop`: 0.25 (default) keeps the style's arc, 0 is a straight line, 0.5 doubles it. Clamped to 0..1. |
-| <span id="set_agent_cursor_motion--dwell_after_click_ms"></span>`dwell_after_click_ms` | `number` | | Pause after a click animation, in milliseconds. Clamped to 0..5000 (default 80). |
-| <span id="set_agent_cursor_motion--effects"></span>`effects` | `object` | | Turn effects on or off. Omit a field to keep it; `"default"` restores the style default. |
-| <span id="set_agent_cursor_motion--effects-glow"></span>`effects.glow` | `"on" \| "off" \| "default"` | | Soft glow around the cursor that grows with speed. |
-| <span id="set_agent_cursor_motion--effects-magnet"></span>`effects.magnet` | `"on" \| "off" \| "default"` | | Target glow when the `magnetic` style locks on. |
-| <span id="set_agent_cursor_motion--effects-ripple"></span>`effects.ripple` | `"on" \| "off" \| "default"` | | Ring that expands from the hotspot on click. |
-| <span id="set_agent_cursor_motion--effects-squish"></span>`effects.squish` | `"on" \| "off" \| "default"` | | Brief scale-down of the cursor on click. |
-| <span id="set_agent_cursor_motion--effects-trail"></span>`effects.trail` | `"on" \| "off" \| "default"` | | Short fading trail behind the cursor. |
-| <span id="set_agent_cursor_motion--end_handle"></span>`end_handle` | `number` | | Arc control-point offset from the end, as a fraction of the distance, for `signature_arc`, `spring_settle` and `comet_swoop`. Clamped to 0..1 (default 0.3). |
-| <span id="set_agent_cursor_motion--glide_duration_ms"></span>`glide_duration_ms` | `number` | | Move duration in milliseconds for `fixed` timing (1430 ms when 0, the default). A nonzero value with `native` or the default `steady` timing also fixes the duration. Clamped to 0..5000. |
-| <span id="set_agent_cursor_motion--idle_hide_ms"></span>`idle_hide_ms` | `number` | | Hide the cursor after this many idle milliseconds; 0 never hides it. Clamped to 0..60000 (default 15000). |
-| <span id="set_agent_cursor_motion--session"></span>`session` | `string` | required | Public label of the session that owns the cursor. Omitted or null motion fields keep their current value. |
-| <span id="set_agent_cursor_motion--spring"></span>`spring` | `number` | | Arrival spring damping for `classic`: 1 is critically damped, 0.3 is bouncy. Clamped to 0.3..1 (default 0.72). |
-| <span id="set_agent_cursor_motion--start_handle"></span>`start_handle` | `number` | | Arc control-point offset from the start, as a fraction of the distance, for `signature_arc`, `spring_settle` and `comet_swoop`. Clamped to 0..1 (default 0.3). |
-| <span id="set_agent_cursor_motion--style"></span>`style` | `"signature_arc" \| "spring_settle" \| "magnetic" \| "comet_swoop" \| "adaptive" \| "classic"` | | Trajectory style. `signature_arc` (default) is one arc with a small follow-through; `spring_settle` lands with one soft bounce; `magnetic` is pulled into the target; `comet_swoop` is a wide arc with a short trail; `adaptive` picks a careful approach for small targets and a swoop for long moves; `classic` is the previous Dubins glide. When the theme's reduced motion is on, every move is a short straight glide with no effects. |
-| <span id="set_agent_cursor_motion--timing"></span>`timing` | `"native" \| "fitts" \| "fixed" \| "relaxed" \| "steady" \| "calm" \| "deliberate"` | | `steady` (default) keeps the style's timing but makes every move take at least 600 ms, with a gentler ease; `relaxed` and `calm` do the same with a 450 or 750 ms floor. `native` uses the style's own timing; `fitts` scales the move time with distance and target size; `deliberate` is a slower Fitts curve (450..1300 ms); `fixed` uses glide_duration_ms (1430 ms when 0). |
-| <span id="set_agent_cursor_motion--turn_radius"></span>`turn_radius` | `number` | | Minimum turning radius of the `classic` glide path, in points; smaller turns tighter. Clamped to 1..1000 (default 80). |
-
-**Example arguments**
-
-```json
-{"session":"<session>"}
-```
-
-## `set_agent_cursor_theme`
-
-Select an already-installed cursor theme for a session.
-
-Effect: mutating, idempotent. Platforms: macOS, Linux, Windows.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="set_agent_cursor_theme--reduced_motion"></span>`reduced_motion` | `"auto" \| "on" \| "off"` | `"auto"` | Theme animation policy: `on` uses the theme's reduced-motion frames, `off` always animates, `auto` (default) leaves the choice to the host. |
-| <span id="set_agent_cursor_theme--session"></span>`session` | `string` | required | Public label of the session that owns the cursor. |
-| <span id="set_agent_cursor_theme--theme_id"></span>`theme_id` | `string` | required | Id of an installed cursor theme (see `cua-driver cursor-theme list`). |
-
-**Example arguments**
-
-```json
-{"session":"<session>","theme_id":"<theme_id>"}
-```
-
-## `get_agent_cursor_state`
-
-Return the session cursor's theme, semantic playback, position, visibility, and motion.
-
-Effect: read-only, idempotent. Platforms: macOS, Linux, Windows.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="get_agent_cursor_state--session"></span>`session` | `string` | required | Public label of the session whose cursor to inspect. |
-
-**Example arguments**
-
-```json
-{"session":"<session>"}
-```
diff --git a/docs/content/docs/cua-driver/reference/mcp-tools/apps-and-windows.mdx b/docs/content/docs/cua-driver/reference/mcp-tools/apps-and-windows.mdx
deleted file mode 100644
index 9cc290ffe2..0000000000
--- a/docs/content/docs/cua-driver/reference/mcp-tools/apps-and-windows.mdx
+++ /dev/null
@@ -1,386 +0,0 @@
----
-title: "App and window tools"
-description: "List, launch, quit, front and arrange apps and windows."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-driver
- Source: cua-driver dump-docs --type mcp (macOS, Linux and Windows registries)
- Version: 0.36.0
-*/}
-
-import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
-
-| Tool | Description | Platforms |
-| --- | --- | --- |
-| [`list_apps`](#list_apps) | List macOS apps, both currently running and installed-but-not-running, with per-app state flags: - running: is a process for this app live? | macOS, Linux, Windows |
-| [`list_windows`](#list_windows) | List top-level windows known to WindowServer, including off-screen ones (minimized, other Space, hidden): layer-0 only without `pid`, every layer with `pid`. | macOS, Linux, Windows |
-| [`launch_app`](#launch_app) | Launch a macOS app in the background: the target does NOT come to the foreground. | macOS, Linux, Windows |
-| [`kill_app`](#kill_app) | Force-terminate a process by pid (kill -9 equivalent on macOS / Linux; taskkill /F equivalent on Windows). | macOS, Linux, Windows |
-| [`bring_to_front`](#bring_to_front) | Persistently activate an app and leave it in the foreground. | macOS, Linux, Windows |
-| [`set_window_frame`](#set_window_frame) | Set one exact top-level window's frame in the desktop-coordinate space reported by list_windows and verify the resulting geometry through an independent readback. | macOS, Linux, Windows |
-| [`invoke_menu`](#invoke_menu) | Resolve an exact application-menu path one live native level at a time and invoke its final item through accessibility APIs. | macOS, Linux, Windows |
-| [`debug_window_info`](#debug_window_info) | Diagnostic: dump everything cua-driver sees about a pid's top-level windows from the daemon's session perspective. | Windows |
-
-Served by `cua-driver mcp`; see [MCP tools](/cua-driver/reference/mcp-tools) for every tool.
-
-## `list_apps`
-
-Effect: read-only, idempotent. Platforms: macOS, Linux, Windows.
-
-<Tabs items={['macOS', 'Linux', 'Windows']} groupId="platform" persist>
-<Tab value="macOS">
-
-List macOS apps, both currently running and installed-but-not-running, with per-app state flags:
-
-- running: is a process for this app live? (pid is 0 when false)
-- active: is it the system-frontmost app? (implies running)
-- launch_path: filesystem path to the `.app` bundle, when known. Pass this to `launch_app` to start the app cold.
-- kind: `"desktop"` for `.app` bundles on macOS.
-- last_used: RFC3339 timestamp from the bundle's filesystem mtime, when readable.
-
-Optional fields (bundle_id, launch_path, kind, last_used) are omitted when unknown, never null.
-
-Standalone running entries include only apps with NSApplicationActivationPolicyRegular: background helpers and system UI agents are filtered out. Installed apps resolve their running/pid state against all live processes by bundle identifier, so an installed app whose process runs as an accessory (LSUIElement / menu-bar apps, e.g. Cua Driver itself) still reports its live pid. Installed apps come from scanning /Applications, /Applications/Utilities, ~/Applications, /System/Applications, and /System/Applications/Utilities.
-
-Use this for "is X installed?" as well as "is X running?"; the list includes every installed app. To get an open app's pid and window_id, call list_windows(&#123;app: "Name"&#125;) instead, which also gives per-window state (on-screen, on-current-Space, minimized, window titles). For just opening an app, running or not, call launch_app(&#123;bundle_id: ...&#125;) directly; list_apps is not a prerequisite.
-
-</Tab>
-<Tab value="Linux">
-
-List Linux apps, both currently running and installed-but-not-running, with per-app state flags:
-
-- running: is a process for this app live? (pid is 0 when false)
-- active: reserved (Linux X11/Wayland focus model differs from frontmost-app); always false.
-- kind: `"desktop"` for XDG `.desktop` launcher entries.
-- launch_path: the launcher command from `Exec=` (field codes stripped). Pass to `launch_app(launch_path=...)`.
-- bundle_id: the XDG "desktop file id"; the `.desktop` file's path relative to its XDG `applications/` root with the `.desktop` suffix stripped and path separators replaced with `-` (e.g. `kde4/konqbrowser.desktop` → `kde4-konqbrowser`).
-- last_used: RFC3339 mtime of the `.desktop` file, when readable.
-- windows: the app's current top-level windows (same records as list_windows); empty for a process without one.
-
-Running apps come from `/proc`. Installed apps come from XDG Desktop Entry files in $XDG_DATA_HOME/applications and each $XDG_DATA_DIRS entry's applications/ subdir. Entries with `NoDisplay=true` or `Hidden=true` are filtered. A `.desktop` file whose launcher matches a running process (by basename), or whose WM_CLASS a top-level window carries, is merged into a single entry with `running: true`.
-
-Use this for "is X installed?" as well as "is X running?". For per-window state, visibility, geometry, titles, call list_windows instead.
-
-</Tab>
-<Tab value="Windows">
-
-List Windows apps, both currently running and installed-but-not-running, with per-app state flags:
-
-- running: is a process for this app live? (pid is 0 when false)
-- active: is it the system-frontmost app? (implies running)
-- kind: `"desktop"` for `.exe`-backed apps (resolved from Start-Menu shortcuts) or `"uwp"` for packaged store apps.
-- launch_path: what `launch_app` would consume.
-* desktop: full `.exe` commandline (path + any arguments preserved from the source `.lnk`; the exe is quoted when it contains whitespace).
-* uwp: `shell:appsFolder\{PackageFamilyName}!{AppId}` where `{AppId}` falls back to `App` when the package manifest does not expose a specific Application.Id.
-- last_used: RFC3339 mtime of the launcher (`.lnk` for desktop, package install location for UWP), when readable.
-
-Running apps are derived from visible top-level windows + the foreground pid (mirrors NSApplicationActivationPolicyRegular's intent: background services and console processes are excluded). Installed apps are merged from Start-Menu `.lnk` enumeration and the WinRT PackageManager: running processes whose executable matches a Start-Menu target are folded into a single entry with `running: true`.
-
-Use this for "is X installed?" as well as "is X running?". For per-window state, on-screen, minimized, window titles, call list_windows instead. For just opening an app, running or not, call launch_app(&#123;path: ...&#125;) directly; list_apps is not a prerequisite.
-
-</Tab>
-</Tabs>
-
-**Parameters on every platform**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="list_apps--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
-
-## `list_windows`
-
-Effect: read-only, idempotent. Platforms: macOS, Linux, Windows.
-
-<Tabs items={['macOS', 'Linux', 'Windows']} groupId="platform" persist>
-<Tab value="macOS">
-
-List top-level windows known to WindowServer, including off-screen ones (minimized, other Space, hidden): layer-0 only without `pid`, every layer with `pid`. Use it to find a `pid` and `window_id` for get_window_state; filter with `app` or `pid`, because an unfiltered call lists every window on the host. AppKit-internal helper windows and the driver's own overlay are omitted.
-
-Per record: window_id, pid, app_name, title, bounds, layer, z_index, is_on_screen, space_ids, current_space_id, on_current_space. For the frontmost window take the maximum integer z_index; null means stacking is unavailable, so do not infer it from array order.
-
-**macOS parameters**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="list_windows--macos--on_screen_only"></span>`on_screen_only` | `boolean` | | Drop windows not on the current Space. |
-| <span id="list_windows--macos--pid"></span>`pid` | `integer` | | Only this pid's windows, on every layer. |
-
-</Tab>
-<Tab value="Linux">
-
-List top-level windows. Each record includes z_index (integer or null; higher values are closer to the front; null means stacking order is unavailable and callers must not infer one). To select a frontmost candidate, take the maximum integer z_index; if every value is null, use an explicit fallback instead of relying on array order. Filter with `app` or `pid`: an unfiltered call lists every window on the host.
-
-**Linux parameters**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="list_windows--linux--on_screen_only"></span>`on_screen_only` | `boolean` | | When true, filter to visible windows only. Default false. |
-| <span id="list_windows--linux--pid"></span>`pid` | `integer` | | Only list windows owned by this process ID. |
-
-</Tab>
-<Tab value="Windows">
-
-List every top-level window currently known to the window manager. Each record self-contains its owning app identity so the caller never has to join back against list_apps.
-
-Use this, not list_apps, for any window-level reasoning: "does this app have a visible window right now?", "which of this pid's windows is the main one?".
-
-Per-record fields: window_id (HWND), pid + app_name, title, bounds &#123;x, y, width, height&#125;, layer (always 0), z_index (integer or null; higher values are closer to the front; null means stacking order is unavailable and callers must not infer one), is_on_screen, minimized. To select a frontmost candidate, take the maximum integer z_index; if every value is null, use an explicit fallback instead of relying on array order. The macOS-specific on_current_space / space_ids fields are omitted on Windows; current_space_id is null.
-
-Inputs: pid (optional pid filter), app (app-name filter), on_screen_only (bool, default false). Filter with app or pid: an unfiltered call lists every window.
-
-**Windows parameters**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="list_windows--windows--on_screen_only"></span>`on_screen_only` | `boolean` | | When true, drop windows that aren't currently on-screen. Default false. |
-| <span id="list_windows--windows--pid"></span>`pid` | `integer` | | Optional pid filter. When set, only this pid's windows are returned. |
-
-</Tab>
-</Tabs>
-
-**Parameters on every platform**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="list_windows--app"></span>`app` | `string` | | Only windows of apps whose name contains this text (case-insensitive), or whose bundle id equals it. Prefer this or `pid` over an unfiltered call, which returns every window on the host. |
-| <span id="list_windows--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
-
-## `launch_app`
-
-Effect: mutating, idempotent. Platforms: macOS, Linux, Windows.
-
-<Tabs items={['macOS', 'Linux', 'Windows']} groupId="platform" persist>
-<Tab value="macOS">
-
-Launch a macOS app in the background: the target does NOT come to the foreground.
-
-Provide either `bundle_id` (preferred: unambiguous, e.g. `com.apple.calculator`) or `name` (e.g. "Calculator"). If both are given, bundle_id wins.
-
-Optional `urls` are handed to the app as open targets: for Finder, pass a folder path to open a backgrounded Finder window there.
-
-Browser DevTools setup belongs to `browser_prepare`, which can prove that a separate isolated profile is driver-owned before enabling CDP.
-
-Optional `webkit_inspector_port`: opens a WebKit inspector server on the specified port (sets WEBKIT_INSPECTOR_SERVER=127.0.0.1:N + TAURI_WEBVIEW_AUTOMATION=1). Use this for Tauri/WebKit-based apps.
-
-Optional `creates_new_application_instance`: when true, forces a new app instance even if one is already running (passes -n to open). Reach for this when another agent or session may drive the SAME app concurrently: it returns a fresh pid + window so each session acts on its own isolated window instead of clobbering one shared instance. Without it, single-instance apps (Calculator, many utilities) hand every caller the same window, so two sessions fight over it.
-
-Optional `additional_arguments`: extra argv strings appended after --args.
-
-Returns the launched app's pid, bundle_id, name, and a `windows` array (same shape as `list_windows`) so callers can skip an extra round-trip before `get_window_state(pid, window_id)`. `launch_state` distinguishes whether the request was sent, the process is running, and a window is ready. When the focus-steal belt-and-braces demotion check ran (target pid ≠ prior frontmost), the response also includes `self_activation_suppressed: bool`; true if focus stayed with the prior frontmost, false if the launched app held focus despite the re-demote attempt.
-
-**macOS parameters**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="launch_app--macos--additional_arguments"></span>`additional_arguments` | `string[]` | | Extra arguments appended after --args when launching. |
-| <span id="launch_app--macos--bundle_id"></span>`bundle_id` | `string` | | App bundle identifier, e.g. com.apple.calculator. Preferred over name. |
-| <span id="launch_app--macos--creates_new_application_instance"></span>`creates_new_application_instance` | `boolean` | | When true, force a new app instance even if already running (open -n). Use for concurrent multi-agent/multi-session work so each session gets an isolated instance + window instead of sharing one: on single-instance apps (e.g. Calculator) every caller otherwise gets the same window and the sessions clobber each other. |
-| <span id="launch_app--macos--name"></span>`name` | `string` | | App display name. Used only when bundle_id is absent. |
-| <span id="launch_app--macos--urls"></span>`urls` | `string[]` | | Optional file paths or URLs to open with the app (e.g. a folder path for Finder). |
-| <span id="launch_app--macos--webkit_inspector_port"></span>`webkit_inspector_port` | `integer` | | Open a WebKit inspector server on this port (sets WEBKIT_INSPECTOR_SERVER env var). |
-
-</Tab>
-<Tab value="Linux">
-
-Launch a Linux app in the background. Provide launch_path (preferred: round-trip the value from list_apps), name (tried as a direct command, then matched against installed .desktop applications, then handed to xdg-open if it is a URL or existing file path), bundle_id (ignored on Linux), or urls (list of URLs to open). Resolution precedence: launch_path &gt; name &gt; bundle_id. Errors when the name resolves to nothing launchable.
-
-**Linux parameters**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="launch_app--linux--additional_arguments"></span>`additional_arguments` | `string[]` | | Extra command-line arguments passed to the launched process. |
-| <span id="launch_app--linux--bundle_id"></span>`bundle_id` | `string` | | Ignored on Linux (macOS/Windows concept). |
-| <span id="launch_app--linux--launch_path"></span>`launch_path` | `string` | | Round-trip the `launch_path` returned by `list_apps`: the Exec= command from the .desktop file with XDG field codes already stripped. Highest precedence on Linux; spawned directly via the system shell. |
-| <span id="launch_app--linux--name"></span>`name` | `string` | | App name or command to launch. Tried as a direct command first, then matched against installed .desktop applications (exact display name, desktop-file id, or Exec basename; else an unambiguous display-name substring). |
-| <span id="launch_app--linux--urls"></span>`urls` | `string[]` | | URLs to open via xdg-open. |
-
-</Tab>
-<Tab value="Windows">
-
-Launch a Windows app hidden: the driver never brings the target to the foreground, the target's window is launched with SW_SHOWNOACTIVATE so it does not steal focus from whatever is currently frontmost.
-
-Provide either `bundle_id` / `name` / `aumid` (resolved as below) or `path` (full path to an executable). If both `name` and `path` are given, `path` wins. `urls` opens each URL in the default browser without activating it.
-
-Routing order: explicit `aumid` (or a `bundle_id` containing `!`) activates the packaged app via `IApplicationActivationManager::ActivateApplication`, returning the real packaged-process pid; required on Win11 for built-in apps like Notepad, Calculator, and Paint, which now ship as Microsoft Store packages where the legacy .exe in System32 is a ~7 KB stub that exits immediately. A plain `name` first attempts a `shell:AppsFolder` lookup; packaged matches use the activation manager while desktop registrations are launched through their shell parsing path. A miss falls back to ShellExecuteEx's PATH search.
-
-Returns the launched app's pid, name, active flag, AND a `windows` array: same per-window shape `list_windows` returns. When the launch settles but no window has materialized yet (transient; rare), `windows` comes back empty: call `list_windows(pid)` explicitly a moment later. `bundle_id` in the response is set to the AUMID actually used for packaged-app launches and `null` for ShellExecuteEx launches.
-
-Windows-only field: `path` (Swift uses `bundle_id` since macOS apps resolve via LaunchServices; Windows has no LaunchServices, so `path` is the canonical form). The macOS-specific `webkit_inspector_port`, `creates_new_application_instance`, and `additional_arguments` fields are accepted; `additional_arguments` is honored (forwarded as ShellExecuteEx parameters or as the AUMID activation arguments string). The remaining macOS-only fields currently no-op on Windows.
-
-**Windows parameters**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="launch_app--windows--additional_arguments"></span>`additional_arguments` | `string[]` | | Extra command-line arguments passed to the launched process (or activation arguments for packaged apps). |
-| <span id="launch_app--windows--aumid"></span>`aumid` | `string` | | Explicit AUMID for a packaged app. Cleaner alternative to overloading `bundle_id`. Takes precedence over `bundle_id` / `name` when present. |
-| <span id="launch_app--windows--bundle_id"></span>`bundle_id` | `string` | | App User Model ID (AUMID) for a packaged app: pattern `{PackageFamilyName}!{ApplicationId}`, e.g. `Microsoft.WindowsNotepad_8wekyb3d8bbwe!App`. Falls back to a `name` alias if no `!` is present. Either bundle_id, name, aumid, path, or launch_path must be provided. |
-| <span id="launch_app--windows--creates_new_application_instance"></span>`creates_new_application_instance` | `boolean` | | Accepted for parity; no-op on Windows (ShellExecuteEx always creates a new process). |
-| <span id="launch_app--windows--launch_path"></span>`launch_path` | `string` | | Round-trip the `launch_path` returned by `list_apps`. Highest precedence: when set, this exact string is handed to ShellExecuteEx unchanged. For Windows desktop apps it's the full `.exe` commandline (path + arguments preserved from the source shortcut); for UWP apps it's `shell:appsFolder\{PackageFamilyName}!{AppId}`. For precise UWP pid capture, prefer `aumid` over `launch_path`. |
-| <span id="launch_app--windows--name"></span>`name` | `string` | | App display name. Tried against the `shell:AppsFolder` index first for packaged-app lookup; on a miss, passed to ShellExecuteEx's PATH search. |
-| <span id="launch_app--windows--path"></span>`path` | `string` | | Full path to executable. Windows-only; takes precedence over name/bundle_id/aumid (but not over `launch_path`). |
-| <span id="launch_app--windows--start_minimized"></span>`start_minimized` | `boolean` | | When true, launch the app's window minimized to the taskbar instead of restored-but-not-activated. Use this when the agent wants to drive the app entirely in the background: the user's previously-frontmost window (e.g. terminal) stays visually on top. Desktop launches hold the foreground lock through startup and use SW_SHOWMINNOACTIVE; packaged-app activation remains broker-controlled and receives a best-effort SW_SHOWMINNOACTIVE post-pass. UIA / background dispatch still work on a minimized window; only `screenshot` and `delivery_mode:"foreground"` need it restored. |
-| <span id="launch_app--windows--urls"></span>`urls` | `string[]` | | URLs to open in the default browser via ShellExecuteEx (no activation). |
-| <span id="launch_app--windows--webkit_inspector_port"></span>`webkit_inspector_port` | `integer` | | Accepted for cross-platform parity; no-op on Windows. |
-
-</Tab>
-</Tabs>
-
-**Parameters on every platform**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="launch_app--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
-
-## `kill_app`
-
-Effect: destructive, idempotent. Platforms: macOS, Linux, Windows.
-
-<Tabs items={['macOS', 'Linux', 'Windows']} groupId="platform" persist>
-<Tab value="macOS">
-
-Force-terminate a process by pid (kill -9 equivalent on macOS / Linux; taskkill /F equivalent on Windows). Use as escalation when the cooperative close path (hotkey cmd+q on macOS, click-the-X on Windows) failed to make the process exit. Unsaved state is lost: prefer the cooperative path first.
-
-</Tab>
-<Tab value="Linux">
-
-Force-terminate a process by pid (kill -9 equivalent on Linux). Use as escalation when the cooperative close path failed to make the process exit. Unsaved state is lost: prefer the cooperative path first.
-
-</Tab>
-<Tab value="Windows">
-
-Force-terminate a process by pid. Use when the standard close path (Alt+F4 / WM_CLOSE via `click` on the X button) fails to make the process exit: typical for UWP / WinUI3 apps (Calculator, Photos, modern Notepad) that route WM_CLOSE into a suspended-but-resident state. Equivalent to `taskkill /F /PID <pid>`. Unsaved state is lost. Prefer the click-the-X path first; only escalate to `kill_app` when polite close didn't terminate.
-
-</Tab>
-</Tabs>
-
-**Parameters on every platform**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="kill_app--pid"></span>`pid` | `integer` | required | PID of the process to terminate. |
-| <span id="kill_app--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
-
-**Example arguments**
-
-```json
-{"pid":1}
-```
-
-## `bring_to_front`
-
-Effect: mutating, idempotent. Platforms: macOS, Linux, Windows.
-
-<Tabs items={['macOS', 'Linux', 'Windows']} groupId="platform" persist>
-<Tab value="macOS">
-
-Persistently activate an app and leave it in the foreground. Most input does not need this; use it only for a focus-proxy surface that must remain foreground across interactions. With window_id, success means the exact ordinary macOS window was independently verified as the frontmost process's focused window and the front window of that process on the display it sits on. `exact_window_effect.frontmost_ordinary` additionally reports whether it is first in the global WindowServer layer-0 order; another application (an always-raised utility window, another display's front window) can hold that spot without the requested window losing keyboard focus, so it is reported and not required. Request acceptance alone is reported as a partial result, never as activation. This DOES steal foreground and does NOT restore the previously frontmost application.
-
-**macOS parameters**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="bring_to_front--macos--pid"></span>`pid` | `integer` | required | Process ID of the app to activate. |
-| <span id="bring_to_front--macos--window_id"></span>`window_id` | `integer` | | CGWindowID to verify as the focused, frontmost window. Omit to activate the app only. |
-
-</Tab>
-<Tab value="Linux">
-
-Persistently activate a window so subsequent input lands on it. This deliberately breaks the no-foreground contract and is not part of the normal input ladder. For an ordinary `background_unavailable` response, retry only the refused action with `delivery_mode:"foreground"`; the input tool performs its own activate, act, and restore sequence. Use `bring_to_front` only for a focus-proxy surface that must remain foreground across multiple calls, such as a remote desktop session, or when repeated action-scoped activation prevents the remote surface from accepting input. X11: EWMH _NET_ACTIVE_WINDOW activation (the `wmctrl -a` equivalent, with proper timestamp handling to beat focus-stealing prevention). Wayland: activates through a target-addressable compositor adapter (wlroots foreign-toplevel or the GNOME Shell helper) and refuses when the compositor offers no safe adapter. Matches the macOS / Windows bring_to_front rung.
-
-**Linux parameters**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="bring_to_front--linux--pid"></span>`pid` | `integer` | required | Process ID of the app to activate. |
-| <span id="bring_to_front--linux--window_id"></span>`window_id` | `integer` | | X11 window id (xid) to activate. If omitted, the first window of `pid` is used. |
-
-</Tab>
-<Tab value="Windows">
-
-Activate `pid`'s window (or `window_id` if specified) -- bring it to the OS foreground.
-
-**This deliberately breaks the no-foreground contract.** It is not part of the normal input ladder. For an ordinary `background_unavailable` response, retry only the refused action with `delivery_mode:"foreground"`; the input tool performs its own activate, act, and restore sequence. Use `bring_to_front` only for a focus-proxy surface that must remain foreground across multiple calls, such as an RDP or Windows App session, or when repeated action-scoped activation prevents the remote surface from accepting input.
-
-Implementation uses the `AttachThreadInput` trick to bypass Windows' foreground-lock when the daemon is not at UIAccess integrity. Returns structured `{previous_fg_hwnd, now_fg_hwnd}` so callers can later restore. Windows only; macOS / Linux return an error pointing at platform-native alternatives.
-
-**Windows parameters**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="bring_to_front--windows--pid"></span>`pid` | `integer` | required | Target process ID. |
-| <span id="bring_to_front--windows--window_id"></span>`window_id` | `integer` | | Optional HWND. Defaults to pid's first visible top-level window. |
-
-</Tab>
-</Tabs>
-
-**Parameters on every platform**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="bring_to_front--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
-
-**Example arguments**
-
-```json
-{"pid":1}
-```
-
-## `set_window_frame`
-
-Set one exact top-level window's frame in the desktop-coordinate space reported by list_windows and verify the resulting geometry through an independent readback.
-
-Effect: mutating, idempotent. Platforms: macOS, Linux, Windows.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="set_window_frame--height"></span>`height` | `number` | required | New height, in the same units as list_windows bounds. Minimum: 1. |
-| <span id="set_window_frame--pid"></span>`pid` | `integer` | required | Process ID that owns the window. Minimum: 1. |
-| <span id="set_window_frame--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
-| <span id="set_window_frame--width"></span>`width` | `number` | required | New width, in the same units as list_windows bounds. Minimum: 1. |
-| <span id="set_window_frame--window_id"></span>`window_id` | `integer` | required | Window ID from list_windows. Minimum: 1. |
-| <span id="set_window_frame--x"></span>`x` | `number` | required | New left edge in the desktop coordinate space reported by list_windows. |
-| <span id="set_window_frame--y"></span>`y` | `number` | required | New top edge in the desktop coordinate space reported by list_windows. |
-
-**Example arguments**
-
-```json
-{"pid":1,"window_id":1,"x":100,"y":200,"width":1,"height":1}
-```
-
-## `invoke_menu`
-
-Resolve an exact application-menu path one live native level at a time and invoke its final item through accessibility APIs. Missing, ambiguous, disabled, or structurally mismatched segments fail closed; this tool never falls back to pixels. Menu paths and refusals: `get_guide({topic:"menus"})`.
-
-Effect: destructive. Platforms: macOS, Linux, Windows.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="invoke_menu--path"></span>`path` | `string[]` | required | Menu labels from the top-level menu to the item, e.g. `["File", "Save As..."]` (1 to 16 labels). Items: 1 to 16. |
-| <span id="invoke_menu--pid"></span>`pid` | `integer` | required | Process ID of the application that owns the menu. Minimum: 1. |
-| <span id="invoke_menu--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
-| <span id="invoke_menu--window_id"></span>`window_id` | `integer` | required | Window ID from list_windows whose menu is invoked. Minimum: 1. |
-
-**Example arguments**
-
-```json
-{"pid":1,"window_id":1,"path":["<path>"]}
-```
-
-## `debug_window_info`
-
-Diagnostic: dump everything cua-driver sees about a pid's top-level windows from the daemon's session perspective. Returns window class names, owning .exe basename + path, and, when CUIAutomation succeeds, the focused UIA element with the list of patterns it supports (ValuePattern, InvokePattern, TextPattern, TogglePattern, etc.). Used to design / debug input routing for XAML / UWP / WinUI3 targets; see CUA-543.
-
-Effect: read-only, idempotent. Platforms: Windows.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="debug_window_info--pid"></span>`pid` | `integer` | required | PID of the process to inspect. |
-| <span id="debug_window_info--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
-
-**Example arguments**
-
-```json
-{"pid":1}
-```
diff --git a/docs/content/docs/cua-driver/reference/mcp-tools/apps-windows-and-screen.mdx b/docs/content/docs/cua-driver/reference/mcp-tools/apps-windows-and-screen.mdx
new file mode 100644
index 0000000000..f6fd826152
--- /dev/null
+++ b/docs/content/docs/cua-driver/reference/mcp-tools/apps-windows-and-screen.mdx
@@ -0,0 +1,862 @@
+---
+title: "Apps, windows and screen"
+description: "Apps and windows, window state and screenshots, the screen, and lifecycle sessions."
+---
+
+{/*
+ AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
+ Generated by: pnpm --dir docs docs:generate:cua-driver
+ Source: cua-driver dump-docs --type mcp (macOS, Linux and Windows registries)
+ Version: 0.36.0
+*/}
+
+import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
+
+| Tool | Description | Platforms |
+| --- | --- | --- |
+| [`list_apps`](#list_apps) | List macOS apps, both currently running and installed-but-not-running, with per-app state flags: - running: is a process for this app live? | macOS, Linux, Windows |
+| [`list_windows`](#list_windows) | List top-level windows known to WindowServer, including off-screen ones (minimized, other Space, hidden): layer-0 only without `pid`, every layer with `pid`. | macOS, Linux, Windows |
+| [`launch_app`](#launch_app) | Launch a macOS app in the background: the target does NOT come to the foreground. | macOS, Linux, Windows |
+| [`kill_app`](#kill_app) | Force-terminate a process by pid (kill -9 equivalent on macOS / Linux; taskkill /F equivalent on Windows). | macOS, Linux, Windows |
+| [`bring_to_front`](#bring_to_front) | Persistently activate an app and leave it in the foreground. | macOS, Linux, Windows |
+| [`set_window_frame`](#set_window_frame) | Set one exact top-level window's frame in the desktop-coordinate space reported by list_windows and verify the resulting geometry through an independent readback. | macOS, Linux, Windows |
+| [`invoke_menu`](#invoke_menu) | Resolve an exact application-menu path one live native level at a time and invoke its final item through accessibility APIs. | macOS, Linux, Windows |
+| [`debug_window_info`](#debug_window_info) | Diagnostic: dump everything cua-driver sees about a pid's top-level windows from the daemon's session perspective. | Windows |
+| [`get_window_state`](#get_window_state) | Snapshot a window: the accessibility tree plus a screenshot. | macOS, Linux, Windows |
+| [`get_accessibility_tree`](#get_accessibility_tree) | Return a lightweight snapshot of the desktop: running regular apps and on-screen visible windows with their bounds, z-order, and owner pid. | macOS, Linux, Windows |
+| [`verify_state`](#verify_state) | Deterministically verify bounded predicates against one exact window. | macOS, Linux, Windows |
+| [`parse_visual_regions`](#parse_visual_regions) | Parse one immutable registered capture into model-neutral text and icon regions. | macOS, Linux, Windows |
+| [`get_desktop_state`](#get_desktop_state) | Capture the full display. | macOS, Linux, Windows |
+| [`get_screen_size`](#get_screen_size) | Return the logical size of the main display in points plus its backing scale factor. | macOS, Linux, Windows |
+| [`get_cursor_position`](#get_cursor_position) | Return the current mouse cursor position in screen points (origin top-left). | macOS, Linux, Windows |
+| [`zoom`](#zoom) | Capture a cropped JPEG of a window region (x1,y1)–(x2,y2) in screenshot pixel coordinates, with 20% padding added on each side. | macOS, Linux, Windows |
+| [`start_session`](#start_session) | Optionally create or return a lifecycle session before acting. | macOS, Linux, Windows |
+| [`escalate_session`](#escalate_session) | Deprecated compatibility tool for legacy capture-scope sessions. | macOS, Linux, Windows |
+| [`get_session`](#get_session) | Read content-free lifecycle, cursor, recording, and idle status for one session visible to this authenticated transport. | macOS, Linux, Windows |
+| [`list_sessions`](#list_sessions) | List content-free lifecycle summaries attached to this authenticated transport lease. | macOS, Linux, Windows |
+| [`get_session_state`](#get_session_state) | Deprecated compatibility alias that reads a live legacy session's capture policy. | macOS, Linux, Windows |
+| [`end_session`](#end_session) | End one visible lifecycle session and run its cursor, recording, configuration, and other cleanup hooks exactly once. | macOS, Linux, Windows |
+
+Served by `cua-driver mcp`; see [MCP tools](/cua-driver/reference/mcp-tools) for every tool.
+
+## App and window tools
+
+List, launch, quit, front and arrange apps and windows.
+
+### `list_apps`
+
+Effect: read-only, idempotent. Platforms: macOS, Linux, Windows.
+
+<Tabs items={['macOS', 'Linux', 'Windows']} groupId="platform" persist>
+<Tab value="macOS">
+
+List macOS apps, both currently running and installed-but-not-running, with per-app state flags:
+
+- running: is a process for this app live? (pid is 0 when false)
+- active: is it the system-frontmost app? (implies running)
+- launch_path: filesystem path to the `.app` bundle, when known. Pass this to `launch_app` to start the app cold.
+- kind: `"desktop"` for `.app` bundles on macOS.
+- last_used: RFC3339 timestamp from the bundle's filesystem mtime, when readable.
+
+Optional fields (bundle_id, launch_path, kind, last_used) are omitted when unknown, never null.
+
+Standalone running entries include only apps with NSApplicationActivationPolicyRegular: background helpers and system UI agents are filtered out. Installed apps resolve their running/pid state against all live processes by bundle identifier, so an installed app whose process runs as an accessory (LSUIElement / menu-bar apps, e.g. Cua Driver itself) still reports its live pid. Installed apps come from scanning /Applications, /Applications/Utilities, ~/Applications, /System/Applications, and /System/Applications/Utilities.
+
+Use this for "is X installed?" as well as "is X running?"; the list includes every installed app. To get an open app's pid and window_id, call list_windows(&#123;app: "Name"&#125;) instead, which also gives per-window state (on-screen, on-current-Space, minimized, window titles). For just opening an app, running or not, call launch_app(&#123;bundle_id: ...&#125;) directly; list_apps is not a prerequisite.
+
+</Tab>
+<Tab value="Linux">
+
+List Linux apps, both currently running and installed-but-not-running, with per-app state flags:
+
+- running: is a process for this app live? (pid is 0 when false)
+- active: reserved (Linux X11/Wayland focus model differs from frontmost-app); always false.
+- kind: `"desktop"` for XDG `.desktop` launcher entries.
+- launch_path: the launcher command from `Exec=` (field codes stripped). Pass to `launch_app(launch_path=...)`.
+- bundle_id: the XDG "desktop file id"; the `.desktop` file's path relative to its XDG `applications/` root with the `.desktop` suffix stripped and path separators replaced with `-` (e.g. `kde4/konqbrowser.desktop` → `kde4-konqbrowser`).
+- last_used: RFC3339 mtime of the `.desktop` file, when readable.
+- windows: the app's current top-level windows (same records as list_windows); empty for a process without one.
+
+Running apps come from `/proc`. Installed apps come from XDG Desktop Entry files in $XDG_DATA_HOME/applications and each $XDG_DATA_DIRS entry's applications/ subdir. Entries with `NoDisplay=true` or `Hidden=true` are filtered. A `.desktop` file whose launcher matches a running process (by basename), or whose WM_CLASS a top-level window carries, is merged into a single entry with `running: true`.
+
+Use this for "is X installed?" as well as "is X running?". For per-window state, visibility, geometry, titles, call list_windows instead.
+
+</Tab>
+<Tab value="Windows">
+
+List Windows apps, both currently running and installed-but-not-running, with per-app state flags:
+
+- running: is a process for this app live? (pid is 0 when false)
+- active: is it the system-frontmost app? (implies running)
+- kind: `"desktop"` for `.exe`-backed apps (resolved from Start-Menu shortcuts) or `"uwp"` for packaged store apps.
+- launch_path: what `launch_app` would consume.
+* desktop: full `.exe` commandline (path + any arguments preserved from the source `.lnk`; the exe is quoted when it contains whitespace).
+* uwp: `shell:appsFolder\{PackageFamilyName}!{AppId}` where `{AppId}` falls back to `App` when the package manifest does not expose a specific Application.Id.
+- last_used: RFC3339 mtime of the launcher (`.lnk` for desktop, package install location for UWP), when readable.
+
+Running apps are derived from visible top-level windows + the foreground pid (mirrors NSApplicationActivationPolicyRegular's intent: background services and console processes are excluded). Installed apps are merged from Start-Menu `.lnk` enumeration and the WinRT PackageManager: running processes whose executable matches a Start-Menu target are folded into a single entry with `running: true`.
+
+Use this for "is X installed?" as well as "is X running?". For per-window state, on-screen, minimized, window titles, call list_windows instead. For just opening an app, running or not, call launch_app(&#123;path: ...&#125;) directly; list_apps is not a prerequisite.
+
+</Tab>
+</Tabs>
+
+**Parameters on every platform**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="list_apps--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
+
+### `list_windows`
+
+Effect: read-only, idempotent. Platforms: macOS, Linux, Windows.
+
+<Tabs items={['macOS', 'Linux', 'Windows']} groupId="platform" persist>
+<Tab value="macOS">
+
+List top-level windows known to WindowServer, including off-screen ones (minimized, other Space, hidden): layer-0 only without `pid`, every layer with `pid`. Use it to find a `pid` and `window_id` for get_window_state; filter with `app` or `pid`, because an unfiltered call lists every window on the host. AppKit-internal helper windows and the driver's own overlay are omitted.
+
+Per record: window_id, pid, app_name, title, bounds, layer, z_index, is_on_screen, space_ids, current_space_id, on_current_space. For the frontmost window take the maximum integer z_index; null means stacking is unavailable, so do not infer it from array order.
+
+**macOS parameters**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="list_windows--macos--on_screen_only"></span>`on_screen_only` | `boolean` | | Drop windows not on the current Space. |
+| <span id="list_windows--macos--pid"></span>`pid` | `integer` | | Only this pid's windows, on every layer. |
+
+</Tab>
+<Tab value="Linux">
+
+List top-level windows. Each record includes z_index (integer or null; higher values are closer to the front; null means stacking order is unavailable and callers must not infer one). To select a frontmost candidate, take the maximum integer z_index; if every value is null, use an explicit fallback instead of relying on array order. Filter with `app` or `pid`: an unfiltered call lists every window on the host.
+
+**Linux parameters**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="list_windows--linux--on_screen_only"></span>`on_screen_only` | `boolean` | | When true, filter to visible windows only. Default false. |
+| <span id="list_windows--linux--pid"></span>`pid` | `integer` | | Only list windows owned by this process ID. |
+
+</Tab>
+<Tab value="Windows">
+
+List every top-level window currently known to the window manager. Each record self-contains its owning app identity so the caller never has to join back against list_apps.
+
+Use this, not list_apps, for any window-level reasoning: "does this app have a visible window right now?", "which of this pid's windows is the main one?".
+
+Per-record fields: window_id (HWND), pid + app_name, title, bounds &#123;x, y, width, height&#125;, layer (always 0), z_index (integer or null; higher values are closer to the front; null means stacking order is unavailable and callers must not infer one), is_on_screen, minimized. To select a frontmost candidate, take the maximum integer z_index; if every value is null, use an explicit fallback instead of relying on array order. The macOS-specific on_current_space / space_ids fields are omitted on Windows; current_space_id is null.
+
+Inputs: pid (optional pid filter), app (app-name filter), on_screen_only (bool, default false). Filter with app or pid: an unfiltered call lists every window.
+
+**Windows parameters**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="list_windows--windows--on_screen_only"></span>`on_screen_only` | `boolean` | | When true, drop windows that aren't currently on-screen. Default false. |
+| <span id="list_windows--windows--pid"></span>`pid` | `integer` | | Optional pid filter. When set, only this pid's windows are returned. |
+
+</Tab>
+</Tabs>
+
+**Parameters on every platform**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="list_windows--app"></span>`app` | `string` | | Only windows of apps whose name contains this text (case-insensitive), or whose bundle id equals it. Prefer this or `pid` over an unfiltered call, which returns every window on the host. |
+| <span id="list_windows--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
+
+### `launch_app`
+
+Effect: mutating, idempotent. Platforms: macOS, Linux, Windows.
+
+<Tabs items={['macOS', 'Linux', 'Windows']} groupId="platform" persist>
+<Tab value="macOS">
+
+Launch a macOS app in the background: the target does NOT come to the foreground.
+
+Provide either `bundle_id` (preferred: unambiguous, e.g. `com.apple.calculator`) or `name` (e.g. "Calculator"). If both are given, bundle_id wins.
+
+Optional `urls` are handed to the app as open targets: for Finder, pass a folder path to open a backgrounded Finder window there.
+
+Browser DevTools setup belongs to `browser_prepare`, which can prove that a separate isolated profile is driver-owned before enabling CDP.
+
+Optional `webkit_inspector_port`: opens a WebKit inspector server on the specified port (sets WEBKIT_INSPECTOR_SERVER=127.0.0.1:N + TAURI_WEBVIEW_AUTOMATION=1). Use this for Tauri/WebKit-based apps.
+
+Optional `creates_new_application_instance`: when true, forces a new app instance even if one is already running (passes -n to open). Reach for this when another agent or session may drive the SAME app concurrently: it returns a fresh pid + window so each session acts on its own isolated window instead of clobbering one shared instance. Without it, single-instance apps (Calculator, many utilities) hand every caller the same window, so two sessions fight over it.
+
+Optional `additional_arguments`: extra argv strings appended after --args.
+
+Returns the launched app's pid, bundle_id, name, and a `windows` array (same shape as `list_windows`) so callers can skip an extra round-trip before `get_window_state(pid, window_id)`. `launch_state` distinguishes whether the request was sent, the process is running, and a window is ready. When the focus-steal belt-and-braces demotion check ran (target pid ≠ prior frontmost), the response also includes `self_activation_suppressed: bool`; true if focus stayed with the prior frontmost, false if the launched app held focus despite the re-demote attempt.
+
+**macOS parameters**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="launch_app--macos--additional_arguments"></span>`additional_arguments` | `string[]` | | Extra arguments appended after --args when launching. |
+| <span id="launch_app--macos--bundle_id"></span>`bundle_id` | `string` | | App bundle identifier, e.g. com.apple.calculator. Preferred over name. |
+| <span id="launch_app--macos--creates_new_application_instance"></span>`creates_new_application_instance` | `boolean` | | When true, force a new app instance even if already running (open -n). Use for concurrent multi-agent/multi-session work so each session gets an isolated instance + window instead of sharing one: on single-instance apps (e.g. Calculator) every caller otherwise gets the same window and the sessions clobber each other. |
+| <span id="launch_app--macos--name"></span>`name` | `string` | | App display name. Used only when bundle_id is absent. |
+| <span id="launch_app--macos--urls"></span>`urls` | `string[]` | | Optional file paths or URLs to open with the app (e.g. a folder path for Finder). |
+| <span id="launch_app--macos--webkit_inspector_port"></span>`webkit_inspector_port` | `integer` | | Open a WebKit inspector server on this port (sets WEBKIT_INSPECTOR_SERVER env var). |
+
+</Tab>
+<Tab value="Linux">
+
+Launch a Linux app in the background. Provide launch_path (preferred: round-trip the value from list_apps), name (tried as a direct command, then matched against installed .desktop applications, then handed to xdg-open if it is a URL or existing file path), bundle_id (ignored on Linux), or urls (list of URLs to open). Resolution precedence: launch_path &gt; name &gt; bundle_id. Errors when the name resolves to nothing launchable.
+
+**Linux parameters**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="launch_app--linux--additional_arguments"></span>`additional_arguments` | `string[]` | | Extra command-line arguments passed to the launched process. |
+| <span id="launch_app--linux--bundle_id"></span>`bundle_id` | `string` | | Ignored on Linux (macOS/Windows concept). |
+| <span id="launch_app--linux--launch_path"></span>`launch_path` | `string` | | Round-trip the `launch_path` returned by `list_apps`: the Exec= command from the .desktop file with XDG field codes already stripped. Highest precedence on Linux; spawned directly via the system shell. |
+| <span id="launch_app--linux--name"></span>`name` | `string` | | App name or command to launch. Tried as a direct command first, then matched against installed .desktop applications (exact display name, desktop-file id, or Exec basename; else an unambiguous display-name substring). |
+| <span id="launch_app--linux--urls"></span>`urls` | `string[]` | | URLs to open via xdg-open. |
+
+</Tab>
+<Tab value="Windows">
+
+Launch a Windows app hidden: the driver never brings the target to the foreground, the target's window is launched with SW_SHOWNOACTIVATE so it does not steal focus from whatever is currently frontmost.
+
+Provide either `bundle_id` / `name` / `aumid` (resolved as below) or `path` (full path to an executable). If both `name` and `path` are given, `path` wins. `urls` opens each URL in the default browser without activating it.
+
+Routing order: explicit `aumid` (or a `bundle_id` containing `!`) activates the packaged app via `IApplicationActivationManager::ActivateApplication`, returning the real packaged-process pid; required on Win11 for built-in apps like Notepad, Calculator, and Paint, which now ship as Microsoft Store packages where the legacy .exe in System32 is a ~7 KB stub that exits immediately. A plain `name` first attempts a `shell:AppsFolder` lookup; packaged matches use the activation manager while desktop registrations are launched through their shell parsing path. A miss falls back to ShellExecuteEx's PATH search.
+
+Returns the launched app's pid, name, active flag, AND a `windows` array: same per-window shape `list_windows` returns. When the launch settles but no window has materialized yet (transient; rare), `windows` comes back empty: call `list_windows(pid)` explicitly a moment later. `bundle_id` in the response is set to the AUMID actually used for packaged-app launches and `null` for ShellExecuteEx launches.
+
+Windows-only field: `path` (Swift uses `bundle_id` since macOS apps resolve via LaunchServices; Windows has no LaunchServices, so `path` is the canonical form). The macOS-specific `webkit_inspector_port`, `creates_new_application_instance`, and `additional_arguments` fields are accepted; `additional_arguments` is honored (forwarded as ShellExecuteEx parameters or as the AUMID activation arguments string). The remaining macOS-only fields currently no-op on Windows.
+
+**Windows parameters**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="launch_app--windows--additional_arguments"></span>`additional_arguments` | `string[]` | | Extra command-line arguments passed to the launched process (or activation arguments for packaged apps). |
+| <span id="launch_app--windows--aumid"></span>`aumid` | `string` | | Explicit AUMID for a packaged app. Cleaner alternative to overloading `bundle_id`. Takes precedence over `bundle_id` / `name` when present. |
+| <span id="launch_app--windows--bundle_id"></span>`bundle_id` | `string` | | App User Model ID (AUMID) for a packaged app: pattern `{PackageFamilyName}!{ApplicationId}`, e.g. `Microsoft.WindowsNotepad_8wekyb3d8bbwe!App`. Falls back to a `name` alias if no `!` is present. Either bundle_id, name, aumid, path, or launch_path must be provided. |
+| <span id="launch_app--windows--creates_new_application_instance"></span>`creates_new_application_instance` | `boolean` | | Accepted for parity; no-op on Windows (ShellExecuteEx always creates a new process). |
+| <span id="launch_app--windows--launch_path"></span>`launch_path` | `string` | | Round-trip the `launch_path` returned by `list_apps`. Highest precedence: when set, this exact string is handed to ShellExecuteEx unchanged. For Windows desktop apps it's the full `.exe` commandline (path + arguments preserved from the source shortcut); for UWP apps it's `shell:appsFolder\{PackageFamilyName}!{AppId}`. For precise UWP pid capture, prefer `aumid` over `launch_path`. |
+| <span id="launch_app--windows--name"></span>`name` | `string` | | App display name. Tried against the `shell:AppsFolder` index first for packaged-app lookup; on a miss, passed to ShellExecuteEx's PATH search. |
+| <span id="launch_app--windows--path"></span>`path` | `string` | | Full path to executable. Windows-only; takes precedence over name/bundle_id/aumid (but not over `launch_path`). |
+| <span id="launch_app--windows--start_minimized"></span>`start_minimized` | `boolean` | | When true, launch the app's window minimized to the taskbar instead of restored-but-not-activated. Use this when the agent wants to drive the app entirely in the background: the user's previously-frontmost window (e.g. terminal) stays visually on top. Desktop launches hold the foreground lock through startup and use SW_SHOWMINNOACTIVE; packaged-app activation remains broker-controlled and receives a best-effort SW_SHOWMINNOACTIVE post-pass. UIA / background dispatch still work on a minimized window; only `screenshot` and `delivery_mode:"foreground"` need it restored. |
+| <span id="launch_app--windows--urls"></span>`urls` | `string[]` | | URLs to open in the default browser via ShellExecuteEx (no activation). |
+| <span id="launch_app--windows--webkit_inspector_port"></span>`webkit_inspector_port` | `integer` | | Accepted for cross-platform parity; no-op on Windows. |
+
+</Tab>
+</Tabs>
+
+**Parameters on every platform**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="launch_app--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
+
+### `kill_app`
+
+Effect: destructive, idempotent. Platforms: macOS, Linux, Windows.
+
+<Tabs items={['macOS', 'Linux', 'Windows']} groupId="platform" persist>
+<Tab value="macOS">
+
+Force-terminate a process by pid (kill -9 equivalent on macOS / Linux; taskkill /F equivalent on Windows). Use as escalation when the cooperative close path (hotkey cmd+q on macOS, click-the-X on Windows) failed to make the process exit. Unsaved state is lost: prefer the cooperative path first.
+
+</Tab>
+<Tab value="Linux">
+
+Force-terminate a process by pid (kill -9 equivalent on Linux). Use as escalation when the cooperative close path failed to make the process exit. Unsaved state is lost: prefer the cooperative path first.
+
+</Tab>
+<Tab value="Windows">
+
+Force-terminate a process by pid. Use when the standard close path (Alt+F4 / WM_CLOSE via `click` on the X button) fails to make the process exit: typical for UWP / WinUI3 apps (Calculator, Photos, modern Notepad) that route WM_CLOSE into a suspended-but-resident state. Equivalent to `taskkill /F /PID <pid>`. Unsaved state is lost. Prefer the click-the-X path first; only escalate to `kill_app` when polite close didn't terminate.
+
+</Tab>
+</Tabs>
+
+**Parameters on every platform**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="kill_app--pid"></span>`pid` | `integer` | required | PID of the process to terminate. |
+| <span id="kill_app--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
+
+**Example arguments**
+
+```json
+{"pid":1}
+```
+
+### `bring_to_front`
+
+Effect: mutating, idempotent. Platforms: macOS, Linux, Windows.
+
+<Tabs items={['macOS', 'Linux', 'Windows']} groupId="platform" persist>
+<Tab value="macOS">
+
+Persistently activate an app and leave it in the foreground. Most input does not need this; use it only for a focus-proxy surface that must remain foreground across interactions. With window_id, success means the exact ordinary macOS window was independently verified as the frontmost process's focused window and the front window of that process on the display it sits on. `exact_window_effect.frontmost_ordinary` additionally reports whether it is first in the global WindowServer layer-0 order; another application (an always-raised utility window, another display's front window) can hold that spot without the requested window losing keyboard focus, so it is reported and not required. Request acceptance alone is reported as a partial result, never as activation. This DOES steal foreground and does NOT restore the previously frontmost application.
+
+**macOS parameters**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="bring_to_front--macos--pid"></span>`pid` | `integer` | required | Process ID of the app to activate. |
+| <span id="bring_to_front--macos--window_id"></span>`window_id` | `integer` | | CGWindowID to verify as the focused, frontmost window. Omit to activate the app only. |
+
+</Tab>
+<Tab value="Linux">
+
+Persistently activate a window so subsequent input lands on it. This deliberately breaks the no-foreground contract and is not part of the normal input ladder. For an ordinary `background_unavailable` response, retry only the refused action with `delivery_mode:"foreground"`; the input tool performs its own activate, act, and restore sequence. Use `bring_to_front` only for a focus-proxy surface that must remain foreground across multiple calls, such as a remote desktop session, or when repeated action-scoped activation prevents the remote surface from accepting input. X11: EWMH _NET_ACTIVE_WINDOW activation (the `wmctrl -a` equivalent, with proper timestamp handling to beat focus-stealing prevention). Wayland: activates through a target-addressable compositor adapter (wlroots foreign-toplevel or the GNOME Shell helper) and refuses when the compositor offers no safe adapter. Matches the macOS / Windows bring_to_front rung.
+
+**Linux parameters**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="bring_to_front--linux--pid"></span>`pid` | `integer` | required | Process ID of the app to activate. |
+| <span id="bring_to_front--linux--window_id"></span>`window_id` | `integer` | | X11 window id (xid) to activate. If omitted, the first window of `pid` is used. |
+
+</Tab>
+<Tab value="Windows">
+
+Activate `pid`'s window (or `window_id` if specified) -- bring it to the OS foreground.
+
+**This deliberately breaks the no-foreground contract.** It is not part of the normal input ladder. For an ordinary `background_unavailable` response, retry only the refused action with `delivery_mode:"foreground"`; the input tool performs its own activate, act, and restore sequence. Use `bring_to_front` only for a focus-proxy surface that must remain foreground across multiple calls, such as an RDP or Windows App session, or when repeated action-scoped activation prevents the remote surface from accepting input.
+
+Implementation uses the `AttachThreadInput` trick to bypass Windows' foreground-lock when the daemon is not at UIAccess integrity. Returns structured `{previous_fg_hwnd, now_fg_hwnd}` so callers can later restore. Windows only; macOS / Linux return an error pointing at platform-native alternatives.
+
+**Windows parameters**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="bring_to_front--windows--pid"></span>`pid` | `integer` | required | Target process ID. |
+| <span id="bring_to_front--windows--window_id"></span>`window_id` | `integer` | | Optional HWND. Defaults to pid's first visible top-level window. |
+
+</Tab>
+</Tabs>
+
+**Parameters on every platform**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="bring_to_front--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
+
+**Example arguments**
+
+```json
+{"pid":1}
+```
+
+### `set_window_frame`
+
+Set one exact top-level window's frame in the desktop-coordinate space reported by list_windows and verify the resulting geometry through an independent readback.
+
+Effect: mutating, idempotent. Platforms: macOS, Linux, Windows.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="set_window_frame--height"></span>`height` | `number` | required | New height, in the same units as list_windows bounds. Minimum: 1. |
+| <span id="set_window_frame--pid"></span>`pid` | `integer` | required | Process ID that owns the window. Minimum: 1. |
+| <span id="set_window_frame--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
+| <span id="set_window_frame--width"></span>`width` | `number` | required | New width, in the same units as list_windows bounds. Minimum: 1. |
+| <span id="set_window_frame--window_id"></span>`window_id` | `integer` | required | Window ID from list_windows. Minimum: 1. |
+| <span id="set_window_frame--x"></span>`x` | `number` | required | New left edge in the desktop coordinate space reported by list_windows. |
+| <span id="set_window_frame--y"></span>`y` | `number` | required | New top edge in the desktop coordinate space reported by list_windows. |
+
+**Example arguments**
+
+```json
+{"pid":1,"window_id":1,"x":100,"y":200,"width":1,"height":1}
+```
+
+### `invoke_menu`
+
+Resolve an exact application-menu path one live native level at a time and invoke its final item through accessibility APIs. Missing, ambiguous, disabled, or structurally mismatched segments fail closed; this tool never falls back to pixels. Menu paths and refusals: `get_guide({topic:"menus"})`.
+
+Effect: destructive. Platforms: macOS, Linux, Windows.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="invoke_menu--path"></span>`path` | `string[]` | required | Menu labels from the top-level menu to the item, e.g. `["File", "Save As..."]` (1 to 16 labels). Items: 1 to 16. |
+| <span id="invoke_menu--pid"></span>`pid` | `integer` | required | Process ID of the application that owns the menu. Minimum: 1. |
+| <span id="invoke_menu--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
+| <span id="invoke_menu--window_id"></span>`window_id` | `integer` | required | Window ID from list_windows whose menu is invoked. Minimum: 1. |
+
+**Example arguments**
+
+```json
+{"pid":1,"window_id":1,"path":["<path>"]}
+```
+
+### `debug_window_info`
+
+Diagnostic: dump everything cua-driver sees about a pid's top-level windows from the daemon's session perspective. Returns window class names, owning .exe basename + path, and, when CUIAutomation succeeds, the focused UIA element with the list of patterns it supports (ValuePattern, InvokePattern, TextPattern, TogglePattern, etc.). Used to design / debug input routing for XAML / UWP / WinUI3 targets; see CUA-543.
+
+Effect: read-only, idempotent. Platforms: Windows.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="debug_window_info--pid"></span>`pid` | `integer` | required | PID of the process to inspect. |
+| <span id="debug_window_info--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
+
+**Example arguments**
+
+```json
+{"pid":1}
+```
+
+## Window state tools
+
+Screenshots, accessibility trees, verification and visual regions of a window.
+
+### `get_window_state`
+
+Effect: read-only. Platforms: macOS, Linux, Windows.
+
+<Tabs items={['macOS', 'Linux', 'Windows']} groupId="platform" persist>
+<Tab value="macOS">
+
+Snapshot a window: the accessibility tree plus a screenshot. By default the tree is ONE compact Markdown rendering (`tree_format:"markdown"`): a row `[N]` is addressed with `element_token` `<snapshot_id>:N`, where `snapshot_id` is in the response header and in structuredContent. `tree_format:"elements"` returns the structured `elements` array instead (`element_index`, `element_token`, `role`, `label`, `value`, `actions`, `frame`, `parent_index`, `depth`); `"both"` returns both (about twice the size). Pass the token to click, type_text, press_key, etc.
+
+START NARROW: a read walks at most 250 nodes by default and says `Tree truncated at max_elements=…` (`truncated:true`) when it stops; raise `max_elements`, or use `query` (case-insensitive substring; matching rows plus ancestors) and `max_depth`. Indices and tokens stay valid for the whole snapshot. `verbose:true` adds `_note` and the full `background_input` report; `full_output:true` restores the previous full response (both representations, all metadata, ≤2 000 nodes).
+
+DIFF READS (use them for every re-read after acting): `since:"latest"`, or `since:<snapshot_id>` from an earlier read of the same window, returns only what changed: `+` added, `~` changed, `-` removed rows (removed ids are the old snapshot's), a `reindexed:` line if indices shifted, or `no change since …; focused element is …`. The response carries a NEW snapshot_id: use it in tokens. An unknown, expired, other-window or differently-scoped (query/max_elements/max_depth) `since` falls back to a full read; `since_status` says why.
+
+A new snapshot of the same (pid, window_id) replaces the previous one and stales its tokens (`invalidated_snapshot_ids`). `include_screenshot:false` returns the tree only and keeps the last screenshot's pixel frame while the window keeps its size; `include_accessibility_tree:false` returns only the screenshot and keeps the current snapshot's rows and tokens valid (use it, not `max_elements:1`, when you just need to look); adding `display_only:true` (live previews) also leaves the pixel frame alone. The tree can lie on some surfaces (Electron, Catalyst, virtualized rows with `h:1` frames): cross-check the screenshot, and use pixel x,y at action time only for elements missing from the tree.
+
+Refusals: `window_id_not_found`; `window_owner_pid_mismatch` names the real `owner_pid` (sandboxed Open/Save panels belong to a panel service). `degraded_reason` `ax_window_unresolved` or `ax_app_launching` (the latter with `truncation_reason: app_lookup_timeout`) means an empty tree: re-snapshot, or act with `delivery_mode:"foreground"`. `degraded_reason` `screen_locked` means the screen saver, display sleep or a lock hid every window from accessibility: wake and unlock the Mac, then re-snapshot; foreground input would reach the lock screen. `px_frame_mismatch` / `px_capture_unavailable` omit the unprovable screenshot; the AX payload stays valid.
+
+**macOS parameters**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="get_window_state--macos--include_accessibility_tree"></span>`include_accessibility_tree` | `boolean` | | Default true. False skips the AX walk and returns the screenshot plus window metadata. Both this and include_screenshot false is an error. |
+| <span id="get_window_state--macos--include_screenshot"></span>`include_screenshot` | `boolean` | | Default true. False returns the tree only (saves image tokens and latency); screenshot_out_file still forces a capture. |
+| <span id="get_window_state--macos--max_depth"></span>`max_depth` | `integer` | | Cap on walk depth. Default 25. Minimum: 1. |
+| <span id="get_window_state--macos--max_dimension"></span>`max_dimension` | `integer` | | Optional cap on the returned screenshot's long edge, in pixels (aspect ratio preserved): the cheap path for a small preview / thumbnail. Applied on top of the session/global max_image_dimension ceiling; the tighter of the two wins. Omit for the configured default. Minimum: 1. |
+| <span id="get_window_state--macos--max_elements"></span>`max_elements` | `integer` | | Cap on AX nodes walked (depth-first; markdown and elements truncate together). Default 250 (2 000 with full_output:true); the response states when the tree was cut. Minimum: 1. |
+| <span id="get_window_state--macos--max_image_dimension"></span>`max_image_dimension` | `integer` | | Per-call override for the returned screenshot's long edge in pixels. An explicit value wins over the session/global setting; 0 returns native resolution. Omit to preserve configured behavior. Minimum: 0. |
+| <span id="get_window_state--macos--pid"></span>`pid` | `integer` | required | Target process ID. |
+| <span id="get_window_state--macos--query"></span>`query` | `string` | | Case-insensitive substring filter: returns matching rows plus ancestors; element_index values are not renumbered. Try this before a full read. |
+| <span id="get_window_state--macos--screenshot_out_file"></span>`screenshot_out_file` | `string` | | When set, write the PNG to this file path (~ expanded) instead of embedding base64 in the response. The structured output will contain screenshot_file_path instead. |
+| <span id="get_window_state--macos--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. |
+| <span id="get_window_state--macos--window_id"></span>`window_id` | `integer` | required | Target window ID from list_windows. |
+
+</Tab>
+<Tab value="Linux">
+
+Walk a running app's AT-SPI tree and return it ONCE, as compact Markdown by default (`tree_format:"markdown"`). Every actionable element is tagged `[N]` (an element_index); its element_token is `<snapshot_id>:N`, where `snapshot_id` is printed in the response header and returned in structuredContent. Pass `tree_format:"elements"` for the structured `elements` array instead (explicit `element_token`, `role`, `label`, `value`, `enabled`, `selected`, `actions`, `frame: {x,y,w,h}` when AT-SPI reports usable bounds, `parent_index`, `depth`), or `"both"` for both (about twice the size). Set `query` to project the tree to matching rows plus their ancestor chain while preserving original indices; `total_element_count` reports the complete snapshot.
+
+Size: a read is bounded by default (`max_elements` 250 actionable nodes). When the walk stops at that budget the response says `Tree truncated at max_elements=…` and `truncated: true`; pass a larger `max_elements`, or `query` / `max_depth`, to reach the rest. `_note` is omitted unless `verbose:true`. `full_output:true` restores the previous full response: both representations, all metadata, and the walker's own limits (≤5 000 nodes).
+
+DIFF READS: pass `since: <snapshot_id>` from an earlier read of the same window to get only what changed: `+` added rows, `~` changed rows, `-` removed rows (their ids are the old snapshot's), or `no change since …`. Rows not listed keep their previous `[N]` unless a `reindexed:` line says otherwise. The response carries a NEW snapshot_id: use it in element_tokens. An unknown, expired, other-window or differently-scoped (query/max_elements/max_depth) `since` falls back to a full read and `since_status` says why. The focused element is not reported on Linux yet.
+
+Always returns BOTH the element tree AND a screenshot: ground on both and cross-check (the tree lies on some surfaces). Choose the modality at ACTION time: an element ax action (element_token → accessibility rung) or an element px action (x,y → pixel rung off this screenshot). capture_mode is deprecated and ignored. On Wayland, where output capture cannot prove the requested surface's identity, the truthful tree is returned without a screenshot and `screenshot_error.code` is `surface_identity_unproven`.
+
+The mirror image: pass `include_accessibility_tree:false` to SKIP the AT-SPI walk entirely and return just the screenshot plus window metadata (window_bounds, app_name, window_title); the capture-only path for a live window preview / picture-in-picture. Setting BOTH `include_accessibility_tree:false` and `include_screenshot:false` is an error. Optional `max_dimension` caps the returned screenshot's long edge in pixels for a cheap thumbnail.
+
+Optional `max_elements` / `max_depth` bound the AT-SPI walk (Electron / large web apps produce 10k+ element trees). Markdown and structured elements are truncated identically. Default: `max_elements` 250.
+
+TIME BUDGET: `timeout_ms` (default 1000) bounds the whole AT-SPI walk. When omitted, a window's first snapshot gets a 2000 ms cold-start budget so Chromium/Electron can finish publishing its initial tree. Explicit values are always honored. Large apps (LibreOffice, GIMP, file managers) can exceed the budget; the call then returns the PARTIAL tree with `truncated: true`, `truncation_reason`, `nodes_visited`/`nodes_pending` and `elements_complete: false`. Every element listed is real and clickable; elements after the cut are simply missing. Retry with a larger `timeout_ms` (e.g. 5000) or narrow with `query`/`max_depth` when the element you need is absent.
+
+SCREENSHOT SCALE: the screenshot is delivered at or below 1.15 megapixels (long edge &lt;= max_image_dimension, 1568 by default), because larger images are downsized before a model reads them and its pixel coordinates would then be uniformly short. Element `screenshot_frame`s and x/y for the pointer tools are pixels of the delivered screenshot (`frame` stays in screen coordinates, as on every platform); `frame_scale` &lt; 1 reports the downsizing. An explicit per-call `max_image_dimension` (0 = native) replaces this cap.
+
+POPUP MENUS: a context menu / popover / combo list is an override-redirect window that list_windows never shows. A click or right_click that opened one names it in its result (`popup: {window_id, bounds, title}`); pass that window_id here to walk the popup's own AT-SPI toplevel so its menu items get element indices (then click them by element_token). Omitting window_id while a popup of this pid is open walks that popup.
+
+**Linux parameters**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="get_window_state--linux--include_accessibility_tree"></span>`include_accessibility_tree` | `boolean` | | Default true: walk the AT-SPI tree and return it (per `tree_format`) alongside the screenshot. Set false to SKIP the AT-SPI walk entirely and return just the screenshot plus window metadata (window_bounds, app_name, window_title): the capture-only path for a live window preview / picture-in-picture. Mirrors include_screenshot. Setting BOTH include_accessibility_tree:false AND include_screenshot:false is an error (nothing to return). |
+| <span id="get_window_state--linux--include_screenshot"></span>`include_screenshot` | `boolean` | | Default true: returns a grounding screenshot alongside the tree. Set false to skip the grab and return tree only (the cheap path for re-indexing before an element ax action). |
+| <span id="get_window_state--linux--max_depth"></span>`max_depth` | `integer` | | Cap on the AT-SPI tree walk depth. Omit for the default (uncapped). Lower for deeply nested apps. Minimum: 1. |
+| <span id="get_window_state--linux--max_dimension"></span>`max_dimension` | `integer` | | Legacy optional cap on the returned screenshot's long edge. Applied on top of the configured max_image_dimension ceiling when max_image_dimension is omitted. Minimum: 1. |
+| <span id="get_window_state--linux--max_elements"></span>`max_elements` | `integer` | | Cap on total AT-SPI nodes walked. Default 250 (5 000 with full_output:true); the response states when the tree was cut. Raise it to read further into a large window. Minimum: 1. |
+| <span id="get_window_state--linux--max_image_dimension"></span>`max_image_dimension` | `integer` | | Per-call long-edge override. This value wins over configured and legacy limits; 0 returns native-resolution PNG bytes. Omit to preserve configured behavior. Minimum: 0. |
+| <span id="get_window_state--linux--pid"></span>`pid` | `integer` | required | Process ID that owns the window. |
+| <span id="get_window_state--linux--query"></span>`query` | `string` | | Optional case-insensitive substring. Projects both tree_markdown and structured elements to matches plus ancestors while preserving original indices. Compare total_element_count with returned_element_count. |
+| <span id="get_window_state--linux--screenshot_out_file"></span>`screenshot_out_file` | `string` | | When set, write the PNG to this file path (~ expanded) instead of embedding base64 in the response. The structured output carries screenshot_file_path instead. |
+| <span id="get_window_state--linux--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
+| <span id="get_window_state--linux--window_id"></span>`window_id` | `integer` | | Native window identifier from list_windows, or the `popup.window_id` a click / right_click result named (an open context menu / popover; its menu items then get element indices). Omitted: the pid's open popup menu when one is mapped, else its focused / active / largest window. |
+
+</Tab>
+<Tab value="Windows">
+
+Walk a running app's UIA tree and return it ONCE, as compact Markdown by default (`tree_format:"markdown"`). Every actionable element is tagged `[N]` (an element_index); its element_token is `<snapshot_id>:N`, where `snapshot_id` is printed in the response header and returned in structuredContent. Pass `tree_format:"elements"` for the structured `elements` array instead (explicit `element_token`, `frame`, `parent_index`, `value`, `actions` per row), or `"both"` for both (about twice the size).
+
+Size: a read is bounded by default (`max_elements` 250). When the walk stops at that budget the response says `Tree truncated at max_elements=…` and `truncated: true`; pass a larger `max_elements`, or `query` / `max_depth`, to reach the rest. `_note` is omitted unless `verbose:true`. `full_output:true` restores the previous full response: both representations, all metadata, and the platform's walk limits (≤5 000 elements, depth ≤25).
+
+DIFF READS: pass `since: <snapshot_id>` from an earlier read of the same window to get only what changed: `+` added rows, `~` changed rows, `-` removed rows (their ids are the old snapshot's), or `no change since …`. Rows not listed keep their previous `[N]` unless a `reindexed:` line says otherwise. The response carries a NEW snapshot_id: use it in element_tokens. An unknown, expired, other-window or differently-scoped (query/max_elements/max_depth) `since` falls back to a full read and `since_status` says why. The focused element is not reported on Windows yet.
+
+INVARIANT: call `get_window_state` once per turn per (pid, window_id) before any element action against that window. The next snapshot of the same (pid, window_id) replaces this one, stales its element tokens, and lists the replaced ids in `invalidated_snapshot_ids`. A screenshot-only read (`include_accessibility_tree:false`) keeps the current snapshot's rows and tokens valid, and `display_only:true` also leaves its pixel frame alone.
+
+The UIA tree walked is the window's tree (HWND-scoped); the screenshot and window bounds reported come from the same `window_id`. This is the source of truth for which window the caller intends to reason about: the driver never picks a window implicitly.
+
+`window_id` MUST belong to `pid`; the call returns `isError: true` otherwise. The driver does not auto-fall-back to a different window.
+
+Set `query` to a case-insensitive substring to project the tree to matching rows plus their ancestor chain. Original element indices are preserved. `total_element_count` reports the complete snapshot; `returned_element_count` reports the projection.
+
+Always returns BOTH the element tree AND a screenshot: ground on both and cross-check (the tree lies on some surfaces). Choose the modality at ACTION time: an element ax action (element_token → accessibility rung) or an element px action (x,y → pixel rung off this screenshot). capture_mode is deprecated and ignored.
+
+The mirror image: pass `include_accessibility_tree:false` to SKIP the UIA walk entirely and return just the screenshot plus window metadata (window_bounds, app_name, window_title); the capture-only path for a live window preview / picture-in-picture. Setting BOTH `include_accessibility_tree:false` and `include_screenshot:false` is an error. Optional `max_image_dimension` overrides the configured screenshot long-edge limit for this call; pass 0 for native resolution. Legacy `max_dimension` remains a cap on the configured limit.
+
+Uses `IUIAutomationCacheRequest` to batch-fetch all element properties in a single COM call (Chrome's ~5000-element tree returns in ~2-3s instead of timing out at 4s with per-property RPCs).
+
+Optional `max_elements` / `max_depth` bound the UIA walk (Electron / large web apps produce 10k+ element trees). Markdown and structured elements are truncated identically. Default: `max_elements` 250, depth ≤25.
+
+CHROMIUM COVERAGE: a browser-owned permission bubble can be composited outside the requested native window. Chromium-family snapshots therefore describe this limit in structuredContent.capture_coverage. After a verified ineffective window action, call escalate_session, take a fresh get_desktop_state snapshot, act explicitly in desktop scope if needed, then verify with another fresh desktop snapshot. This is separate from page JavaScript dialogs, which remain on browser_dialog.
+
+Windows requires no special permissions.
+
+**Windows parameters**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="get_window_state--windows--include_accessibility_tree"></span>`include_accessibility_tree` | `boolean` | | Default true: walk the UIA tree and return it (per `tree_format`) alongside the screenshot. Set false to SKIP the UIA walk entirely and return just the screenshot plus window metadata (window_bounds, app_name, window_title): the capture-only path for a live window preview / picture-in-picture. Mirrors include_screenshot. Setting BOTH include_accessibility_tree:false AND include_screenshot:false is an error (nothing to return). |
+| <span id="get_window_state--windows--include_screenshot"></span>`include_screenshot` | `boolean` | | Default true: returns a grounding screenshot alongside the tree. Set false to skip the grab and return tree only (the cheap path for re-indexing before an element ax action). |
+| <span id="get_window_state--windows--max_depth"></span>`max_depth` | `integer` | | Cap on the UIA-tree walk depth. Nodes whose rendered indent would exceed this are omitted. Omit for the default (25). Lower for deep menu / Electron trees. Minimum: 1. |
+| <span id="get_window_state--windows--max_dimension"></span>`max_dimension` | `integer` | | Legacy optional cap on the returned screenshot's long edge, in pixels (aspect ratio preserved). Applied on top of the configured max_image_dimension ceiling when max_image_dimension is omitted; the tighter wins. Minimum: 1. |
+| <span id="get_window_state--windows--max_elements"></span>`max_elements` | `integer` | | Cap on the total number of UIA nodes walked. Truncates depth-first; markdown and structured elements truncate together. Default 250 (5 000 with full_output:true); the response states when the tree was cut. Raise it to read further into a large window. Minimum: 1. |
+| <span id="get_window_state--windows--max_image_dimension"></span>`max_image_dimension` | `integer` | | Per-call long-edge limit for the returned screenshot, in pixels (aspect ratio preserved). Explicit values override configured behavior; 0 returns native resolution. Omit to preserve the configured default. Minimum: 0. |
+| <span id="get_window_state--windows--pid"></span>`pid` | `integer` | required | Process ID from `list_apps`. |
+| <span id="get_window_state--windows--query"></span>`query` | `string` | | Optional case-insensitive substring. Projects both tree_markdown and structured elements to matches plus ancestors while preserving original indices. Compare total_element_count with returned_element_count. |
+| <span id="get_window_state--windows--screenshot_out_file"></span>`screenshot_out_file` | `string` | | When set, write the PNG to this file path instead of embedding base64 in the response. The structured output will contain `screenshot_file_path` instead. |
+| <span id="get_window_state--windows--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
+| <span id="get_window_state--windows--window_id"></span>`window_id` | `integer` | required | HWND of the target window. Must belong to `pid`. Enumerate via `list_windows` or read from `launch_app`'s `windows` array. |
+
+</Tab>
+</Tabs>
+
+**Parameters on every platform**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="get_window_state--capture_mode"></span>`capture_mode` | `"ax" \| "vision"` | | DEPRECATED and ignored. get_window_state always returns BOTH the element tree and a screenshot: ground on both. The modality is chosen at action time by how you address the target: an element ax action (element_token) or an element px action (x,y). Any value (including the old "som"/"screenshot" aliases) is accepted but has no effect. |
+| <span id="get_window_state--display_only"></span>`display_only` | `boolean` | | Default false. With include_accessibility_tree:false, returns pixels for display without registering an action capture or replacing the agent snapshot. The image cannot ground input actions. |
+| <span id="get_window_state--full_output"></span>`full_output` | `boolean` | | Default false. Set true to restore the previous full response: both `elements` and `tree_markdown`, all metadata, and the platform's own walk limits unless max_elements / max_depth are passed. Does not combine with `since`. |
+| <span id="get_window_state--since"></span>`since` | `string` | | A `snapshot_id` from an earlier get_window_state of the same window, or "latest" for this window's most recent read with the same query/max_elements/max_depth. Use it on every re-read after acting. Returns only what changed against that snapshot: `+` added rows, `~` changed rows, `-` removed rows (removed ids are the old snapshot's), or `no change`. Falls back to a full read when the snapshot is unknown, expired, belongs to another window, or was read with a different query/max_elements/max_depth; `since_status` says which. The response still carries a NEW snapshot_id and its element_tokens; rows not listed keep their previous [N] unless a `reindexed:` line says otherwise. |
+| <span id="get_window_state--timeout_ms"></span>`timeout_ms` | `integer` | `1000` | Wall-clock budget in milliseconds for the accessibility-tree walk (default 1000, min 100, max 120000). Bounds the WHOLE walk. When the budget runs out the tool returns the PARTIAL tree it has, flagged with `truncated: true`, `truncation_reason`, `nodes_visited`, `nodes_pending` and `elements_complete: false`; retry with a larger value (e.g. 5000) or narrow with `query` / `max_depth`. Range: 100 to 120000. |
+| <span id="get_window_state--tree_format"></span>`tree_format` | `"markdown" \| "elements" \| "both"` | | Which tree representation to return. Default "markdown": the compact `tree_markdown` only, where a row `[N]` is addressed with element_token `<snapshot_id>:N`. "elements": the structured `elements` array only (per-element element_token, frame, parent_index, value). "both": the two together, as before; roughly doubles the size. |
+| <span id="get_window_state--verbose"></span>`verbose` | `boolean` | | Default false. Set true to include the `_note` string and the full `background_input` capability report (macOS), which are omitted by default to save context. |
+
+**Example arguments**
+
+```json
+{"pid":1,"window_id":1}
+```
+
+### `get_accessibility_tree`
+
+Effect: read-only, idempotent. Platforms: macOS, Linux, Windows.
+
+<Tabs items={['macOS', 'Linux', 'Windows']} groupId="platform" persist>
+<Tab value="macOS">
+
+Return a lightweight snapshot of the desktop: running regular apps and on-screen visible windows with their bounds, z-order, and owner pid.
+
+For the full AX subtree of a single window (with interactive element indices you can click by), use `get_window_state` instead: that's the heavy per-window tool. This one is a fast discovery read that needs no TCC grants.
+
+</Tab>
+<Tab value="Linux">
+
+Return a lightweight snapshot of the desktop: running processes and on-screen visible X11 windows with their bounds and owner pid.
+
+For the full AT-SPI subtree of a single window (with interactive element indices you can click by), use get_window_state instead: this is a fast discovery read.
+
+</Tab>
+<Tab value="Windows">
+
+Return a lightweight snapshot of the desktop: running processes and on-screen visible windows with their bounds and owner pid.
+
+For the full UIA subtree of a single window (with interactive element indices you can click by), use get_window_state instead: this is a fast discovery read.
+
+</Tab>
+</Tabs>
+
+**Parameters on every platform**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="get_accessibility_tree--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
+
+### `verify_state`
+
+Deterministically verify bounded predicates against one exact window. The driver evaluates structured window/accessibility state and may return the final screenshot as uninterpreted visual evidence for a multimodal caller. Predicate results are satisfied, unsatisfied, or unknown; unknown never implies success. Accessibility projections are conservative: absence remains unknown unless the observed search domain is proven exhaustive.
+
+Effect: read-only. Platforms: macOS, Linux, Windows.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="verify_state--expect"></span>`expect` | `object[]` | required | One to eight predicates, combined with logical AND. Items: 1 to 8. |
+| <span id="verify_state--include_screenshot"></span>`include_screenshot` | `boolean` | | Return the final window screenshot as image content for a multimodal caller. The driver does not interpret that image. |
+| <span id="verify_state--pid"></span>`pid` | `integer` | required | Exact process whose window may be observed. Minimum: 1. |
+| <span id="verify_state--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. This field never selects capture modality or authorization. |
+| <span id="verify_state--stable_samples"></span>`stable_samples` | `integer` | `2` | Consecutive satisfied samples required before returning success. Range: 1 to 5. |
+| <span id="verify_state--timeout_ms"></span>`timeout_ms` | `integer` | `5000` | Bounded wait. Zero performs one sample. Range: 0 to 10000. |
+| <span id="verify_state--window_id"></span>`window_id` | `integer` | required | Exact native window identifier. |
+
+**Example arguments**
+
+```json
+{"pid":1,"window_id":1,"expect":[{}]}
+```
+
+### `parse_visual_regions`
+
+Parse one immutable registered capture into model-neutral text and icon regions.
+
+Effect: read-only, idempotent. Platforms: macOS, Linux, Windows.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="parse_visual_regions--capture_id"></span>`capture_id` | `string` | required | `capture_id` of a screenshot returned by get_window_state or get_desktop_state. |
+| <span id="parse_visual_regions--options"></span>`options` | `object` | `{}` | Optional, model-neutral controls for one bounded parse. |
+| <span id="parse_visual_regions--options-kinds"></span>`options.kinds` | `"text" \| "icon"[]` | | Region kinds to return (`text`, `icon`). Omit for all kinds. Items: 1 to 2. |
+| <span id="parse_visual_regions--options-max_regions"></span>`options.max_regions` | `integer` | | Return at most this many regions. Minimum: 1. |
+| <span id="parse_visual_regions--options-min_confidence"></span>`options.min_confidence` | `number` | | Drop regions below this confidence (0 to 1). Range: 0 to 1. |
+| <span id="parse_visual_regions--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
+
+**Example arguments**
+
+```json
+{"capture_id":"<capture_id>"}
+```
+
+## Screen tools
+
+The desktop, screen size, cursor position and zoomed crops.
+
+### `get_desktop_state`
+
+Effect: read-only. Platforms: macOS, Linux, Windows.
+
+<Tabs items={['macOS', 'Linux', 'Windows']} groupId="platform" persist>
+<Tab value="macOS">
+
+Capture the full display. The long edge is capped at `max_image_dimension` (the configured default unless given); pixels of the returned image map back to the screen through its capture. Use its PNG as the coordinate source for actions whose target is &#123;kind:"desktop",display_id:"primary"&#125;. Returns the true screen size and backing scale factor. Vision-only: no AX tree walk.
+
+</Tab>
+<Tab value="Linux">
+
+Capture the full display in the desktop action coordinate frame. Use the returned PNG directly as the coordinate source for actions whose target is &#123;kind:"desktop",display_id:"primary"&#125;. No AT-SPI walk.
+
+</Tab>
+<Tab value="Windows">
+
+Capture the full display in true screen pixels, full size unless `max_image_dimension` caps it. Use its PNG as the coordinate source for actions whose target is &#123;kind:"desktop",display_id:"primary"&#125;. Returns the true screen size. Vision-only: no UIA tree walk.
+
+</Tab>
+</Tabs>
+
+**Parameters on every platform**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="get_desktop_state--max_image_dimension"></span>`max_image_dimension` | `integer` | | Optional long-edge cap for the returned PNG, in pixels (aspect ratio preserved). Omitted or 0 returns the full-size capture. When the cap downsizes the image, the response reports `screenshot_original_width/height`, and x/y read off it for this session's later scope:"desktop" actions (or passed with its `capture_id`) are mapped back to the full-size frame automatically. Minimum: 0. |
+| <span id="get_desktop_state--screenshot_out_file"></span>`screenshot_out_file` | `string` | | Write PNG here instead of base64. |
+| <span id="get_desktop_state--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
+
+### `get_screen_size`
+
+Effect: read-only, idempotent. Platforms: macOS, Linux, Windows.
+
+<Tabs items={['macOS', 'Linux', 'Windows']} groupId="platform" persist>
+<Tab value="macOS">
+
+Return the logical size of the main display in points plus its backing scale factor. Agents click in points; Retina displays have scale_factor 2.0. Requires no TCC permissions.
+
+</Tab>
+<Tab value="Linux">
+
+Return the logical size of the main display in points plus its backing scale factor. Agents click in points; Retina displays have scale_factor 2.0. Requires no TCC permissions.
+
+</Tab>
+<Tab value="Windows">
+
+Return the size of the main display in physical pixels plus its display scale factor. On Windows, screenshots and pixel clicks use this same physical-pixel coordinate space. Requires no special permissions.
+
+</Tab>
+</Tabs>
+
+**Parameters on every platform**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="get_screen_size--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
+
+### `get_cursor_position`
+
+Return the current mouse cursor position in screen points (origin top-left).
+
+Effect: read-only, idempotent. Platforms: macOS, Linux, Windows.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="get_cursor_position--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
+
+### `zoom`
+
+Effect: read-only, idempotent. Platforms: macOS, Linux, Windows.
+
+<Tabs items={['macOS', 'Linux', 'Windows']} groupId="platform" persist>
+<Tab value="macOS">
+
+Capture a cropped JPEG of a window region (x1,y1)–(x2,y2) in screenshot pixel coordinates, with 20% padding added on each side. The output image is at most 500 px wide. Corners, not a size: x1,y1 is the top-left and x2,y2 the bottom-right (x,y,width,height is also accepted and converted).
+
+After a zoom, pass `from_zoom=true` to click/type_text to auto-translate coordinates back to full-window space. Coordinate actions return `screenshot_context_missing` when no current snapshot contains a screenshot owned by this session. `from_zoom` actions return `zoom_context_missing` when the zoom was never created or was replaced; call `get_window_state`, then `zoom`, again on the same connection.
+
+**macOS parameters**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="zoom--macos--pid"></span>`pid` | `integer` | | Optional target pid. When omitted, the driver resolves the unique current snapshot for this session and window. |
+| <span id="zoom--macos--window_id"></span>`window_id` | `integer` | required | CGWindowID from list_windows. |
+| <span id="zoom--macos--x1"></span>`x1` | `number` | required | Left edge of region in screenshot pixels. |
+| <span id="zoom--macos--x2"></span>`x2` | `number` | required | Right edge of region in screenshot pixels. |
+| <span id="zoom--macos--y1"></span>`y1` | `number` | required | Top edge of region in screenshot pixels. |
+| <span id="zoom--macos--y2"></span>`y2` | `number` | required | Bottom edge of region in screenshot pixels. |
+
+</Tab>
+<Tab value="Linux">
+
+Capture a cropped JPEG of a window region (x1,y1)–(x2,y2) in screenshot pixels, with 20% padding. Output is at most 500 px wide. Corners, not a size: x1,y1 is the top-left and x2,y2 the bottom-right (x,y,width,height is also accepted and converted).
+
+After a zoom, pass from_zoom=true to click/type_text to auto-translate coordinates back to full-window space. Coordinate actions return `screenshot_context_missing` when no current snapshot contains a screenshot owned by this session. `from_zoom` actions return `zoom_context_missing` when the zoom was never created or was replaced; call `get_window_state`, then `zoom`, again on the same connection.
+
+**Linux parameters**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="zoom--linux--pid"></span>`pid` | `integer` | | Optional target pid. When omitted, the driver resolves the unique current snapshot for this session and window. |
+| <span id="zoom--linux--window_id"></span>`window_id` | `integer` | required | Window id of the window captured by get_window_state. |
+| <span id="zoom--linux--x1"></span>`x1` | `number` | required | Left edge of the region in window-local screenshot pixels. |
+| <span id="zoom--linux--x2"></span>`x2` | `number` | required | Right edge of the region in window-local screenshot pixels. |
+| <span id="zoom--linux--y1"></span>`y1` | `number` | required | Top edge of the region in window-local screenshot pixels. |
+| <span id="zoom--linux--y2"></span>`y2` | `number` | required | Bottom edge of the region in window-local screenshot pixels. |
+
+</Tab>
+<Tab value="Windows">
+
+Zoom into a rectangular region of a window screenshot at full (native) resolution. Use this when `get_window_state` returned a resized image and you need to read small text, identify icons, or verify UI details.
+
+Corners, not a size: x1,y1 is the top-left and x2,y2 the bottom-right (x,y,width,height is also accepted and converted). Coordinates `x1, y1, x2, y2` are in the same pixel space as the screenshot returned by `get_window_state` (i.e. the resized image if `max_image_dimension` is active). The maximum zoom region width is 500 px in scaled-image coordinates.
+
+A 20% padding is automatically added on every side of the requested region so the target remains visible even if the caller's coordinates are slightly off.
+
+After a zoom, pass `from_zoom=true` to click/type_text to auto-translate coordinates back to full-window space. Coordinate actions return `screenshot_context_missing` when no current snapshot contains a screenshot owned by this session. `from_zoom` actions return `zoom_context_missing` when the zoom was never created or was replaced; call `get_window_state`, then `zoom`, again on the same connection.
+
+Windows-specific: `window_id` is the canonical addressing field (HWND). `pid` is preferred when available; otherwise the driver resolves the unique current snapshot owned by this session and window.
+
+**Windows parameters**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="zoom--windows--pid"></span>`pid` | `integer` | | Optional target process ID. When omitted, the unique current snapshot for this session and HWND is used. |
+| <span id="zoom--windows--window_id"></span>`window_id` | `integer` | required | HWND of the target window. |
+| <span id="zoom--windows--x1"></span>`x1` | `number` | required | Left edge of the region (resized-image pixels). |
+| <span id="zoom--windows--x2"></span>`x2` | `number` | required | Right edge of the region (resized-image pixels). |
+| <span id="zoom--windows--y1"></span>`y1` | `number` | required | Top edge of the region (resized-image pixels). |
+| <span id="zoom--windows--y2"></span>`y2` | `number` | required | Bottom edge of the region (resized-image pixels). |
+
+</Tab>
+</Tabs>
+
+**Parameters on every platform**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="zoom--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
+
+**Example arguments**
+
+```json
+{"window_id":1,"x1":100,"y1":200,"x2":100,"y2":200}
+```
+
+## Session tools
+
+Start, escalate, inspect and end lifecycle sessions.
+
+### `start_session`
+
+Optionally create or return a lifecycle session before acting. For multi-call work, prefer a short public `session` label and repeat it on every call that accepts it; an omitted value uses the authenticated transport lease's implicit session instead. This tool is optional because an ordinary action can create or reuse a named run directly. Use it to set the initial cursor theme before acting or to revive a public name after it has ended; ordinary actions never revive ended names. `capture_scope` is deprecated compatibility input; new callers select window or desktop modality per action. Idempotent.
+
+Effect: mutating, idempotent. Platforms: macOS, Linux, Windows.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="start_session--capture_scope"></span>`capture_scope` | `"auto" \| "window" \| "desktop"` | | Deprecated compatibility policy. New callers select window or desktop modality on each action instead of storing it on the session. |
+| <span id="start_session--cursor_motion"></span>`cursor_motion` | `object` | | Optional initial cursor motion (style, timing, effects and tuning). The host applies it before the cursor is first made visible. A later `set_agent_cursor_motion` call wins; this wins over the saved default (`cursor.motion.*` in the driver config) and the built-in `signature_arc`. Reduced motion always wins. |
+| <span id="start_session--cursor_motion-arc_flow"></span>`cursor_motion.arc_flow` | `number` | | Added to the arc asymmetry of `signature_arc`, `spring_settle` and `comet_swoop`: positive moves the apex toward the destination. Clamped to -1..1 (default 0). |
+| <span id="start_session--cursor_motion-arc_size"></span>`cursor_motion.arc_size` | `number` | | Scales the arc of `signature_arc`, `spring_settle` and `comet_swoop`: 0.25 (default) keeps the style's arc, 0 is a straight line, 0.5 doubles it. Clamped to 0..1. |
+| <span id="start_session--cursor_motion-dwell_after_click_ms"></span>`cursor_motion.dwell_after_click_ms` | `number` | | Pause after a click animation, in milliseconds. Clamped to 0..5000 (default 80). |
+| <span id="start_session--cursor_motion-effects"></span>`cursor_motion.effects` | `object` | | Turn effects on or off. Omit a field to keep it; `"default"` restores the style default. |
+| <span id="start_session--cursor_motion-end_handle"></span>`cursor_motion.end_handle` | `number` | | Arc control-point offset from the end, as a fraction of the distance, for `signature_arc`, `spring_settle` and `comet_swoop`. Clamped to 0..1 (default 0.3). |
+| <span id="start_session--cursor_motion-glide_duration_ms"></span>`cursor_motion.glide_duration_ms` | `number` | | Move duration in milliseconds for `fixed` timing (1430 ms when 0, the default). A nonzero value with `native` or the default `steady` timing also fixes the duration. Clamped to 0..5000. |
+| <span id="start_session--cursor_motion-idle_hide_ms"></span>`cursor_motion.idle_hide_ms` | `number` | | Hide the cursor after this many idle milliseconds; 0 never hides it. Clamped to 0..60000 (default 15000). |
+| <span id="start_session--cursor_motion-spring"></span>`cursor_motion.spring` | `number` | | Arrival spring damping for `classic`: 1 is critically damped, 0.3 is bouncy. Clamped to 0.3..1 (default 0.72). |
+| <span id="start_session--cursor_motion-start_handle"></span>`cursor_motion.start_handle` | `number` | | Arc control-point offset from the start, as a fraction of the distance, for `signature_arc`, `spring_settle` and `comet_swoop`. Clamped to 0..1 (default 0.3). |
+| <span id="start_session--cursor_motion-style"></span>`cursor_motion.style` | `"signature_arc" \| "spring_settle" \| "magnetic" \| "comet_swoop" \| "adaptive" \| "classic"` | | Trajectory style. `signature_arc` (default) is one arc with a small follow-through; `spring_settle` lands with one soft bounce; `magnetic` is pulled into the target; `comet_swoop` is a wide arc with a short trail; `adaptive` picks a careful approach for small targets and a swoop for long moves; `classic` is the previous Dubins glide. When the theme's reduced motion is on, every move is a short straight glide with no effects. |
+| <span id="start_session--cursor_motion-timing"></span>`cursor_motion.timing` | `"native" \| "fitts" \| "fixed" \| "relaxed" \| "steady" \| "calm" \| "deliberate"` | | `steady` (default) keeps the style's timing but makes every move take at least 600 ms, with a gentler ease; `relaxed` and `calm` do the same with a 450 or 750 ms floor. `native` uses the style's own timing; `fitts` scales the move time with distance and target size; `deliberate` is a slower Fitts curve (450..1300 ms); `fixed` uses glide_duration_ms (1430 ms when 0). |
+| <span id="start_session--cursor_motion-turn_radius"></span>`cursor_motion.turn_radius` | `number` | | Minimum turning radius of the `classic` glide path, in points; smaller turns tighter. Clamped to 1..1000 (default 80). |
+| <span id="start_session--cursor_theme"></span>`cursor_theme` | `object` | | Optional initial cursor theme. The host applies it before the cursor is first made visible, avoiding a flash of the default theme. |
+| <span id="start_session--cursor_theme-reduced_motion"></span>`cursor_theme.reduced_motion` | `"auto" \| "on" \| "off"` | `"auto"` | |
+| <span id="start_session--cursor_theme-theme_id"></span>`cursor_theme.theme_id` | `string` | | |
+| <span id="start_session--session"></span>`session` | `string` | | Optional stable public label for this run (e.g. "research-run-1"). When omitted, the authenticated transport lease's implicit session is created or returned. |
+
+### `escalate_session`
+
+Deprecated compatibility tool for legacy capture-scope sessions. New callers select window or desktop modality on each action. No deescalate_session tool exists.
+
+Effect: mutating. Platforms: macOS, Linux, Windows.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="escalate_session--detail"></span>`detail` | `string` | | Optional bounded diagnostic detail. Never use secrets or page content. |
+| <span id="escalate_session--reason"></span>`reason` | `"ax_tree_pixel_mismatch" \| "background_delivery_failed" \| "foreground_ineffective" \| "no_window_target" \| "other"` | required | Why the window-scoped attempt failed and desktop capture is needed. |
+| <span id="escalate_session--session"></span>`session` | `string` | required | Public label of the legacy capture-scope session to escalate. |
+
+**Example arguments**
+
+```json
+{"session":"<session>","reason":"ax_tree_pixel_mismatch"}
+```
+
+### `get_session`
+
+Read content-free lifecycle, cursor, recording, and idle status for one session visible to this authenticated transport. Omit `session` to inspect its implicit session.
+
+Effect: read-only, idempotent. Platforms: macOS, Linux, Windows.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="get_session--session"></span>`session` | `string` | | Optional public label. When omitted, inspect the caller's attached implicit session. |
+
+### `list_sessions`
+
+List content-free lifecycle summaries attached to this authenticated transport lease. It does not enumerate other callers' sessions.
+
+Effect: read-only, idempotent. Platforms: macOS, Linux, Windows.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="list_sessions--cursor"></span>`cursor` | `string` | | Opaque continuation cursor returned by a previous call. |
+| <span id="list_sessions--limit"></span>`limit` | `integer` | | Maximum number of content-free summaries to return (default 50, max 100). Ordinary agent transports are scoped to their own lease. Minimum: 0. |
+
+### `get_session_state`
+
+Deprecated compatibility alias that reads a live legacy session's capture policy. Use get_session for lifecycle state.
+
+Effect: read-only, idempotent. Platforms: macOS, Linux, Windows.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="get_session_state--session"></span>`session` | `string` | | Optional public label. When omitted, inspect the caller's attached implicit session. |
+
+### `end_session`
+
+End one visible lifecycle session and run its cursor, recording, configuration, and other cleanup hooks exactly once. Omit `session` to end the authenticated transport's implicit session. Idempotent.
+
+Effect: destructive, idempotent. Platforms: macOS, Linux, Windows.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="end_session--session"></span>`session` | `string` | | Optional public label to end. When omitted, end the caller's attached implicit session. |
diff --git a/docs/content/docs/cua-driver/reference/mcp-tools/batch-recording-and-settings.mdx b/docs/content/docs/cua-driver/reference/mcp-tools/batch-recording-and-settings.mdx
new file mode 100644
index 0000000000..5c56776248
--- /dev/null
+++ b/docs/content/docs/cua-driver/reference/mcp-tools/batch-recording-and-settings.mdx
@@ -0,0 +1,499 @@
+---
+title: "Batch, recording and settings"
+description: "Run several actions in one call, record and replay trajectories, and configuration and maintenance."
+---
+
+{/*
+ AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
+ Generated by: pnpm --dir docs docs:generate:cua-driver
+ Source: cua-driver dump-docs --type mcp (macOS, Linux and Windows registries)
+ Version: 0.36.0
+*/}
+
+import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
+
+| Tool | Description | Platforms |
+| --- | --- | --- |
+| [`run_steps`](#run_steps) | The default way to act: run one or more action tools in ONE call, in order, stop at the first failure, and (with `observe`) get what changed in the same response. | macOS, Linux, Windows |
+| [`run_script`](#run_script) | Run a JavaScript program that drives apps through Cua Driver, in ONE call: loops, conditions, reads and checks between actions, and only the result comes back. | macOS, Linux, Windows |
+| [`start_recording`](#start_recording) | Start trajectory recording for the calling session. | macOS, Linux, Windows |
+| [`stop_recording`](#stop_recording) | Stop trajectory recording. | macOS, Linux, Windows |
+| [`get_recording_state`](#get_recording_state) | Report the current trajectory recorder state: whether recording is enabled, the output directory (when enabled), and the 1-based counter for the next turn folder that will be written. | macOS, Linux, Windows |
+| [`replay_trajectory`](#replay_trajectory) | Replay a recorded trajectory by re-invoking every turn's tool call in lexical order. | macOS, Linux, Windows |
+| [`install_ffmpeg`](#install_ffmpeg) | Install the ffmpeg binary used by start_recording's video capture (Linux/Windows; macOS records natively and needs no ffmpeg). | macOS, Linux, Windows |
+| [`get_config`](#get_config) | Return the current cua-driver-rs configuration. | macOS, Linux, Windows |
+| [`set_config`](#set_config) | Update cua-driver-rs configuration. | macOS, Linux, Windows |
+| [`check_permissions`](#check_permissions) | Report TCC permission status for Accessibility and Screen Recording. | macOS, Linux, Windows |
+| [`health_report`](#health_report) | Single-call end-to-end driver diagnostics. | macOS, Linux, Windows |
+| [`check_for_update`](#check_for_update) | Check the saved stable/nightly Cua Driver channel for a release on GitHub. | macOS, Linux, Windows |
+| [`install_extension`](#install_extension) | Preview or install one Driver-managed optional extension. | macOS, Linux, Windows |
+| [`get_guide`](#get_guide) | Read Cua Driver guidance on demand, taken from the guide bundled with this driver (no skill install needed). | macOS, Linux, Windows |
+
+Served by `cua-driver mcp`; see [MCP tools](/cua-driver/reference/mcp-tools) for every tool.
+
+## Batch and script tools
+
+Run several action tools, or a script that drives them, in one call.
+
+Use `run_steps` for a fixed list of actions you have already decided. Use `run_script` when the flow needs
+logic between actions (a loop over rows, a branch on what the app shows, a retry): it runs a JavaScript
+program over the driver's own tools in one call and returns only its result. Every driver call either
+tool makes passes the same session, permission and approval checks as a direct call.
+
+`run_script` runs in a QuickJS sandbox with no filesystem, network, process, timers or environment.
+Limits: `timeout_ms` (default 30 s, max 120 s), `max_calls` (default 100, max 500), a 32 MiB heap and
+a 64 KiB script. It is on by default. Whoever runs the driver turns it off with
+`CUA_DRIVER_DISABLE_RUN_SCRIPT=1` or `"disable_run_script": true` in `~/.cua-driver/config.json`
+(`CUA_DRIVER_EXPERIMENTAL_SCRIPT=0` and `"experimental_script": false` also work); `set_config` cannot
+change it.
+
+### `run_steps`
+
+The default way to act: run one or more action tools in ONE call, in order, stop at the first failure, and (with `observe`) get what changed in the same response. Use it whenever you know the next action(s) and would otherwise re-read the window after them: fill three fields, click, and see the result in one call instead of five. Even a single step plus `observe:{}` replaces an action call followed by a get_window_state call. Each step is `{tool, args}` where `tool` is one of click, double_click, right_click, set_value, type_text, press_key, hotkey, scroll, drag, move_cursor and `args` are exactly that tool's arguments. `pid` and `window_id` (or `app`/`window`) on run_steps itself are the default window of every step that names none. Reads (get_window_state, zoom) do not run between steps: one there is skipped; a get_window_state last is the `observe`, a zoom last runs after it. Every step goes through the same session, permission and approval checks as a direct call; a batch grants nothing extra. All steps are validated before the first one runs, so a malformed step 4 changes nothing. Element tokens and element_index values come from a get_window_state read before the batch; a step that changes the UI can invalidate later element targets, so put element-targeted actions before the actions that reshuffle the window, or target later steps by role/name. A token that went stale is retried once on the element with the same role and label, if exactly one matches.
+
+Returns per-step status (`ok` or the error message) and, when `observe` is given, ONE bounded get_window_state read after the last executed step (after a failure caused by a dialog holding focus, that dialog is read, even without `observe`). A step refused because its app ignores background input says how to re-send it; `foreground_fallback:true` retries such steps in the foreground once (the window is activated). That read is a `since:"latest"` diff by default: only the rows that changed since your last read of the window, plus a new snapshot_id. Without `observe` nothing is read. The batch uses one session: steps may omit `session` or repeat the batch's. `delay_ms` pauses between steps (max 2000). At most 64 steps; `delivery_mode` on run_steps is the default for its steps.
+
+TARGET BY NAME (no earlier read needed, so one batch can cross screens): a step can be written `{"click": {...args}}` as well as `{tool, args}`, and its args may name the target instead of carrying a token: `role` (button, textfield, link, checkbox, menuitem, ...; AX/UIA/AT-SPI names also work), `name` (the element's label; exact match wins over substring, case-insensitive), `nth` (0-based, when several match), and `app` (app name or bundle id) and/or `window` (title substring) instead of pid/window_id. The batch reads the window fresh, waits up to 3 s (step `timeout_ms`, max 10000) for the element to appear, and acts on it; with only `app` it uses that app's frontmost window, so a dialog that opened on top is found. Later steps inherit the window, so name `app` once. The first lookup in a window also reads it once for `observe`, so the end diff shows what the batch changed even in a window you never read. Several matches fail with the candidates listed; add `nth` or a fuller name.
+
+WAITS AND CHECKS: a step may add `wait_for` (checked before its action) and `expect` (one check or up to 4, checked after it); a step may also be only a check. A check is &#123;role?, name?, text?, gone?, value?, value_contains?, enabled?, selected?, app?, window?, timeout_ms?&#125;: `text` matches any row of the tree, static text included; `gone:true` waits for it to disappear. Checks poll until they hold or time out (wait_for 5 s, expect 2 s, max 10 s), and a check that does not hold fails the step with what was found instead. The report says which step failed, in which phase (wait_for, find, action, expect) and why. Whole batch: at most 60 s.
+
+Example (fill a form, submit, confirm the dialog, check the result):
+&#123;"steps":[&#123;"set_value":&#123;"app":"Safari","role":"textfield","name":"Email","value":"[email protected]"&#125;&#125;,&#123;"click":&#123;"role":"button","name":"Submit"&#125;,"expect":[&#123;"role":"button","name":"Confirm"&#125;]&#125;,&#123;"click":&#123;"role":"button","name":"Confirm"&#125;,"expect":[&#123;"name":"Confirm","gone":true&#125;,&#123;"text":"Thanks"&#125;]&#125;],"observe":&#123;&#125;&#125; Batching rules: `get_guide({topic:"batching"})`.
+
+Effect: destructive. Platforms: macOS, Linux, Windows.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="run_steps--app"></span>`app` | `string` | | Default app (name or bundle id) for steps that name no window. |
+| <span id="run_steps--delay_ms"></span>`delay_ms` | `integer` | | Pause between steps in milliseconds (not after the last). Default 0. Range: 0 to 2000. |
+| <span id="run_steps--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | | Default delivery_mode for steps whose tool takes one and that set none. |
+| <span id="run_steps--foreground_fallback"></span>`foreground_fallback` | `boolean` | | When a step is refused because its target ignores background input (Electron, LibreOffice and other toolkits), retry it once with delivery_mode:"foreground": the window is activated and the pointer may move. Default false. |
+| <span id="run_steps--observe"></span>`observe` | `object` | | Optional end-of-batch observation: arguments for ONE get_window_state call. `pid` and `window_id` default to those of the last step that names both. Defaults to since="latest" (only what changed since your last read of that window with the same query/max_elements/max_depth; a full read when there is none), include_screenshot=false and max_elements=250; pass include_screenshot=true to see the window, or since=null for a full read. Omit to read nothing. &#123;&#125; observes the last window. |
+| <span id="run_steps--pid"></span>`pid` | `integer` | | Default pid for steps that name no window (a step's own pid/window_id/app/window wins). |
+| <span id="run_steps--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
+| <span id="run_steps--steps"></span>`steps` | `object[]` | required | Ordered actions. Execution stops at the first failing step. Each step is &#123;tool, args&#125; or &#123;&lt;tool&gt;: args&#125;, plus optional wait_for / expect / timeout_ms; a step may also be only a wait_for or expect check. Items: 1 to 64. |
+| <span id="run_steps--window"></span>`window` | `string` | | Default window title substring for steps that name no window. |
+| <span id="run_steps--window_id"></span>`window_id` | `integer` | | Default window_id for steps that name no window, with `pid`. |
+
+**Example arguments**
+
+```json
+{"steps":[{}]}
+```
+
+### `run_script`
+
+Run a JavaScript program that drives apps through Cua Driver, in ONE call: loops, conditions, reads and checks between actions, and only the result comes back. Use it when the flow needs logic (a loop over rows, a branch on what the app shows, a retry); use run_steps for a fixed list of steps.
+
+The script is the body of an async function: use `await`, and `return` a JSON value. It runs in a sandbox with no filesystem, network, process, timers or environment; the only API is `cua`:
+- `await cua.getApp("TextEdit" | "com.apple.TextEdit" | {pid, windowId})` → app (follows the app's frontmost window unless a windowId is given)
+- `await cua.launch(nameOrBundleId)` → app; `cua.listApps()`, `cua.listWindows({pid?})`, `cua.sleep(ms)`, `cua.computer.target`
+- app.getState(opts?) → get_window_state result (`tree_markdown` or `tree_diff`, `snapshot_id`; pass get_window_state options such as &#123;since:"latest"&#125;)
+- app.query(&#123;role?, name?, text?&#125;) → matching elements across the app's windows &#123;element_token, role, label, value, enabled, selected, frame&#125;, then matching static-text rows &#123;role, label, value, text, display_only&#125; (read text such as a status line from their `value`)
+- app.waitFor(&#123;role?, name?, text?, gone?, value?, timeout_ms?&#125;) and app.verify(predicate | predicates) (verify_state)
+- app.click(t), doubleClick(t), rightClick(t), typeText(text, t?), pressKey("return" | "cmd+s", t?), hotkey(["cmd","s"]), scroll(t, direction, amount?), setValue(t, value), drag([x,y], [x,y]), zoom([x1,y1,x2,y2])
+where a target `t` is &#123;role, name, nth?&#125; (found fresh, waits up to 3 s), an element_token string, a row number from this app's last getState(), or [x, y] window pixels.
+- `cua.call(tool, args)` for any other allowed tool: click, double_click, right_click, set_value, type_text, press_key, hotkey, scroll, drag, launch_app, list_apps, list_windows, get_window_state, verify_state, zoom.
+A failed driver call throws a CuaError (catch it to recover). Every call goes through the same session, permission and approval checks as a direct call.
+
+Limits: `timeout_ms` wall time (default 30000, max 120000), `max_calls` driver calls (default 100, max 500), 32 MiB heap. Returns the return value, console output, and a per-call log; an error names the script line, the call and the reason.
+
+Example:
+const app = await cua.getApp("Calculator");
+for (const key of ["7", "multiply", "6", "equals"]) await app.click(&#123;role: "button", name: key&#125;);
+const [display] = await app.query(&#123;role: "statictext"&#125;);
+return display.value; Batching rules: `get_guide({topic:"batching"})`.
+
+Effect: destructive. Platforms: macOS, Linux, Windows.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="run_script--max_calls"></span>`max_calls` | `integer` | | Most driver calls the script may make. Default 100. Range: 1 to 500. |
+| <span id="run_script--script"></span>`script` | `string` | required | JavaScript: the body of an async function. `return` the result. |
+| <span id="run_script--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
+| <span id="run_script--timeout_ms"></span>`timeout_ms` | `integer` | | Wall-time limit. Default 30000. Range: 100 to 120000. |
+
+**Example arguments**
+
+```json
+{"script":"<script>"}
+```
+
+## Recording tools
+
+Record and replay trajectories.
+
+### `start_recording`
+
+Start trajectory recording for the calling session. Each action-tool invocation (click, right_click, scroll, type_text, press_key, hotkey, set_value) from that session writes a turn folder under `output_dir`. Without `session`, every call on the same connection is recorded, including named-session calls. Other connections and session lifecycle calls (`start_session` / `end_session`) are not recorded. CLI recordings started with `cua-driver recording start` are daemon-wide.
+
+Each turn folder holds:
+
+- `before_state.json` / `after_state.json`: application AX/UIA/AT-SPI state immediately before and after the action.
+- `before.png` / `after.png`: target-window screenshots immediately before and after the action.
+- `evidence.json`: capture status and a stable classification when an expected artifact could not be captured.
+- `app_state.json`: post-action AX/UIA snapshot for the target pid.
+- `screenshot.png`: compatibility alias of `after.png`.
+- `action.json`: tool name, full input arguments, result summary, result-error flag, pid, click point (when applicable), ISO-8601 timestamp.
+- `click.png`: for dispatched click-family actions only, `before.png` with a red marker at the click point. A call refused before target resolution is explicitly not applicable instead.
+
+The per-turn accessibility walk is bounded like `get_window_state`: `state_timeout_ms` (default 1000) caps each before/after walk, a walk that runs out of budget records the PARTIAL tree, and `evidence.json` carries `truncated`, `truncation_reason`, `nodes_visited`, `nodes_pending` and `timeout_ms` for that phase. A provider that stops answering is abandoned after the budget plus a short grace and the phase is classified `state_capture_timeout`. Actions refused before dispatch (for example an unknown or expired `capture_id`) skip the state walk; their state is classified `not_applicable` / `action_refused_before_dispatch`. Pass `include_accessibility_tree: false` to record screenshots and actions without state.
+
+Turn folders are named `turn-00001/`, `turn-00002/`, etc. Turn numbering restarts at 1 each time recording is (re-)started.
+
+**Video is off by default.** Pass `record_video: true` to also capture the main display to `<output_dir>/recording.mp4` (H.264 / 30 fps) for the lifetime of the session. The recording is torn down automatically when the MCP client disconnects.
+
+**macOS uses native ScreenCaptureKit** (daemon-owned SCStream + SCRecordingOutput) under the daemon's Screen Recording grant, with no ffmpeg subprocess. Requires macOS 15.0+. On macOS 26 (Tahoe), the first direct capture can also show a one-time consent asking to let Cua Driver bypass the system private window picker and directly access your screen and audio; choose Allow, or run `cua-driver permissions grant` beforehand to answer it up front. The recorder captures screen video only and does not enable system-audio capture.
+
+**Windows + Linux use an ffmpeg subprocess** (`gdigrab` / `x11grab` + libx264). Requires ffmpeg on PATH (winget install Gyan.FFmpeg / apt install ffmpeg); when ffmpeg is missing or fails on startup the per-turn capture (screenshots + action.json) still runs and the session's `last_error` field carries the diagnostic.
+
+State persists for the life of the daemon; a restart resets to disabled with no on-disk state. Call `stop_recording` to disable + finalize the mp4.
+
+Effect: mutating, idempotent. Platforms: macOS, Linux, Windows.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="start_recording--include_accessibility_tree"></span>`include_accessibility_tree` | `boolean` | `true` | Default true. Set false to skip the per-turn before/after accessibility walks entirely; screenshots, click markers and action.json are still recorded and state is classified `state_capture_disabled`. |
+| <span id="start_recording--output_dir"></span>`output_dir` | `string` | required | Absolute or ~-rooted directory where turn folders and (when enabled) the video file are written. |
+| <span id="start_recording--record_video"></span>`record_video` | `boolean` | | Capture the main display to &lt;output_dir&gt;/recording.mp4. Default: false. Set to true to also capture the main display to recording.mp4 (otherwise only the per-turn screenshots + JSON are recorded). On macOS this uses native ScreenCaptureKit (macOS 15.0+); macOS 26 can show a one-time direct screen-capture consent on first use (see `cua-driver permissions grant`). On Windows + Linux it requires ffmpeg on PATH. |
+| <span id="start_recording--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
+| <span id="start_recording--state_timeout_ms"></span>`state_timeout_ms` | `integer` | `1000` | Wall-clock budget in milliseconds for EACH per-turn before/after accessibility walk (same default and bounds as get_window_state's timeout_ms). A walk that runs out records the partial tree and marks it truncated in evidence.json. Range: 100 to 120000. |
+
+**Example arguments**
+
+```json
+{"output_dir":"<output_dir>"}
+```
+
+### `stop_recording`
+
+Stop trajectory recording. Disables further per-turn capture and, when video was enabled, gracefully terminates the ffmpeg subprocess so the mp4's moov atom is finalized (the file is playable). Calling stop on an already-stopped session is a no-op. The response carries `last_video_path` pointing at the finalized mp4 (when video was on).
+
+A manual `stop_recording` is **unconditional**: it stops whatever recording is active regardless of which session started it. Ownership-scoped teardown (so one client disconnecting can't stop a recording a later client started) is handled by the registry's `session_end` lifecycle hook, not by this tool.
+
+Effect: mutating, idempotent. Platforms: macOS, Linux, Windows.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="stop_recording--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
+
+### `get_recording_state`
+
+Report the current trajectory recorder state: whether recording is enabled, the output directory (when enabled), and the 1-based counter for the next turn folder that will be written. Counter increments on every recorded action tool call and resets to 1 each time recording is (re-)enabled.
+
+Pure read-only.
+
+Effect: read-only, idempotent. Platforms: macOS, Linux, Windows.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="get_recording_state--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
+
+### `replay_trajectory`
+
+Replay a recorded trajectory by re-invoking every turn's tool call in lexical order. `dir` must point at a directory previously written by `start_recording`. Each `turn-NNNNN/` is parsed for `action.json`, and the recorded tool is called with its recorded `arguments` via the same dispatch path an MCP / CLI call uses.
+
+Caveats:
+- Element-token actions (`click({pid, element_token})` etc.) will fail because element tokens are per-snapshot and don't survive across sessions. Pixel clicks (`click({pid, x, y})`) and all keyboard tools replay cleanly. Failures are reported but don't stop replay unless `stop_on_error` is true.
+- `get_window_state` and other read-only tools are NOT currently recorded, so replays do not re-populate the per-(pid, window_id) element cache.
+- If recording is ENABLED while replay runs, the replay itself is recorded into the currently configured output directory. That's deliberate: recording a replay against a new build and diffing the two trajectories is the regression-test workflow.
+
+Effect: destructive. Platforms: macOS, Linux, Windows.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="replay_trajectory--delay_ms"></span>`delay_ms` | `integer` | | Milliseconds to sleep between turns, for human-observable pacing. Default 500. Range: 0 to 10000. |
+| <span id="replay_trajectory--dir"></span>`dir` | `string` | required | Trajectory directory previously written by `start_recording`. Absolute or ~-rooted. |
+| <span id="replay_trajectory--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
+| <span id="replay_trajectory--stop_on_error"></span>`stop_on_error` | `boolean` | | Stop replay on the first tool-call error. Default true: set false to best-effort through the full trajectory. |
+
+**Example arguments**
+
+```json
+{"dir":"<dir>"}
+```
+
+### `install_ffmpeg`
+
+Install the ffmpeg binary used by start_recording's video capture (Linux/Windows; macOS records natively and needs no ffmpeg). Two-step and confirmed: called without `confirm` it only REPORTS the exact install command for this platform's package manager; pass `confirm: true` to actually run it. No-op if ffmpeg is already on PATH. ffmpeg is run as a separate process, never linked into the driver.
+
+Effect: destructive. Platforms: macOS, Linux, Windows.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="install_ffmpeg--confirm"></span>`confirm` | `boolean` | | Run the install command. Without it, only the planned command is reported. |
+| <span id="install_ffmpeg--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
+
+## Configuration and maintenance tools
+
+Configuration, permissions, health, updates, extensions and on-demand guides.
+
+### `get_config`
+
+Effect: read-only, idempotent. Platforms: macOS, Linux, Windows.
+
+<Tabs items={['macOS', 'Linux', 'Windows']} groupId="platform" persist>
+<Tab value="macOS">
+
+Return the current cua-driver-rs configuration.
+
+</Tab>
+<Tab value="Linux">
+
+Return current cua-driver-rs configuration.
+
+</Tab>
+<Tab value="Windows">
+
+Report the current persistent driver config.
+
+Pure read-only. Returns defaults when the underlying state is unset: same fallback the daemon uses at startup. Sibling to `set_config`.
+
+Current schema (Windows):
+
+ &#123;
+ "schema_version": 1,
+ "version": "&lt;crate version&gt;",
+ "source_sha": "&lt;maintainer build commit or null&gt;",
+ "platform": "windows",
+ "capture_mode": "ax" | "vision" (DEPRECATED, ignored),
+ "max_image_dimension": 0
+ &#125;
+
+`capture_mode` is deprecated and no longer affects behavior: `get_window_state` always returns both the UIA tree and a screenshot.
+
+</Tab>
+</Tabs>
+
+**Parameters on every platform**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="get_config--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
+
+### `set_config`
+
+Effect: mutating, idempotent. Platforms: macOS, Linux, Windows.
+
+<Tabs items={['macOS', 'Linux', 'Windows']} groupId="platform" persist>
+<Tab value="macOS">
+
+Update cua-driver-rs configuration. Changes to max_image_dimension take effect immediately. The experimental_pip keys are persisted to ~/.cua-driver/config.json and take effect on the next daemon restart (the PiP backend is initialised once at startup).
+
+Note: capture_mode is a per-call param (on get_window_state / click), not a stored setting. Capture modality is selected by each action's target; the old capture_scope config key is retired.
+
+Cursor motion defaults: cursor.motion.style, cursor.motion.timing and cursor.motion.effects.&lt;trail|glow|magnet|ripple|squish&gt; are saved to ~/.cua-driver/config.json and seed sessions started afterwards. start_session cursor_motion and set_agent_cursor_motion override them; reduced motion always wins.
+
+Agent cursor badge: cursor.badges is minimal (default), verbose or off, saved to ~/.cua-driver/config.json and applied to every cursor at once.
+
+**macOS parameters**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="set_config--macos--experimental_pip"></span>`experimental_pip` | `boolean` | | Enable the experimental picture-in-picture preview window. Applies on next daemon restart. |
+| <span id="set_config--macos--experimental_pip_geometry"></span>`experimental_pip_geometry` | `string` | | PiP window size + optional position in `WxH` or `WxH+X+Y` form (e.g. `320x200+24+24`). Applies on next daemon restart. |
+
+</Tab>
+<Tab value="Linux">
+
+Update cua-driver-rs configuration. capture_mode / max_image_dimension take effect immediately.
+
+Pass each setting as its own field: `{"capture_mode": "som", "max_image_dimension": 0}`.
+
+The experimental_pip keys persist to ~/.cua-driver/config.json and apply on next daemon restart (the PiP backend is initialised once at startup; Linux ships only the trait stub today: see issue #1729).
+
+`cursor.motion.style`, `cursor.motion.timing` and `cursor.motion.effects.<name>` (`on`, `off`, or `default`) save the default cursor motion for sessions started afterwards. `cursor.motion: "default"` clears every saved cursor motion default.
+
+`cursor.badges` (`minimal` default, `verbose`, or `off`) sets the agent cursor badge for every cursor at once.
+
+**Linux parameters**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="set_config--linux--capture_mode"></span>`capture_mode` | `"ax" \| "vision"` | | Default capture mode for get_window_state. ("som"/"screenshot" still decode as deprecated aliases.). |
+| <span id="set_config--linux--experimental_pip"></span>`experimental_pip` | `boolean` | | Enable the experimental PiP preview window (applies next restart; Linux backend stubbed). |
+| <span id="set_config--linux--experimental_pip_geometry"></span>`experimental_pip_geometry` | `string` | | PiP window size + optional position in `WxH` or `WxH+X+Y` form. |
+
+</Tab>
+<Tab value="Windows">
+
+Write a setting into the persistent driver config. Values take effect immediately. Pass each setting as its own field.
+
+Known keys:
+- `capture_mode` (string: `vision` | `ax` | `som`); DEPRECATED and ignored; `get_window_state` always returns both the UIA tree and a screenshot. Still accepted/persisted for back-compat but has no effect.
+- `max_image_dimension` (integer)
+- `experimental_pip` (boolean; persisted to config.json, applies on next daemon restart: Windows backend stubbed today, see issue #1729)
+- `experimental_pip_geometry` (string `WxH` or `WxH+X+Y`; persisted; applies on next daemon restart)
+
+- `cursor.motion.style`, `cursor.motion.timing`, `cursor.motion.effects.<name>` (`on`, `off`, or `default`): saved default cursor motion for sessions started afterwards. `cursor.motion: "default"` clears every saved cursor motion default.
+- `cursor.badges` (`minimal` default, `verbose`, or `off`): agent cursor badge; applies to every cursor at once.
+
+Returns the full updated config in the same shape as `get_config`.
+
+**Windows parameters**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="set_config--windows--capture_mode"></span>`capture_mode` | `"ax" \| "vision"` | | DEPRECATED and ignored: get_window_state always returns both the UIA tree and a screenshot. Still accepted/persisted for back-compat but has no effect. ("som"/"screenshot" still decode as deprecated aliases.). |
+| <span id="set_config--windows--experimental_pip"></span>`experimental_pip` | `boolean` | | Enables PiP preview (applies next restart). |
+| <span id="set_config--windows--experimental_pip_geometry"></span>`experimental_pip_geometry` | `string` | | PiP window size + optional position. |
+
+</Tab>
+</Tabs>
+
+**Parameters on every platform**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="set_config--cursor-badges"></span>`cursor.badges` | `"minimal" \| "verbose" \| "off" \| "default"` | | Agent cursor badge. minimal (default): no badge at rest; a brief chip for a foreground moment or a key combo, and the session name on hover or when two or more agent cursors are on screen. verbose: the earlier badge with the session name and delivery/target chips on every action. off: no badge. Applies immediately to every cursor. |
+| <span id="set_config--cursor-motion"></span>`cursor.motion` | `"default"` | | Pass `default` to clear every saved cursor motion default. |
+| <span id="set_config--cursor-motion-effects-glow"></span>`cursor.motion.effects.glow` | `"on" \| "off" \| "default"` | | Saved default for the `glow` cursor effect: on, off, or default (the style's own). Omit the key to leave it unchanged. |
+| <span id="set_config--cursor-motion-effects-magnet"></span>`cursor.motion.effects.magnet` | `"on" \| "off" \| "default"` | | Saved default for the `magnet` cursor effect: on, off, or default (the style's own). Omit the key to leave it unchanged. |
+| <span id="set_config--cursor-motion-effects-ripple"></span>`cursor.motion.effects.ripple` | `"on" \| "off" \| "default"` | | Saved default for the `ripple` cursor effect: on, off, or default (the style's own). Omit the key to leave it unchanged. |
+| <span id="set_config--cursor-motion-effects-squish"></span>`cursor.motion.effects.squish` | `"on" \| "off" \| "default"` | | Saved default for the `squish` cursor effect: on, off, or default (the style's own). Omit the key to leave it unchanged. |
+| <span id="set_config--cursor-motion-effects-trail"></span>`cursor.motion.effects.trail` | `"on" \| "off" \| "default"` | | Saved default for the `trail` cursor effect: on, off, or default (the style's own). Omit the key to leave it unchanged. |
+| <span id="set_config--cursor-motion-style"></span>`cursor.motion.style` | `"signature_arc" \| "spring_settle" \| "magnetic" \| "comet_swoop" \| "adaptive" \| "classic"` | | Saved default cursor motion style for new sessions. Overridden by start_session cursor_motion and set_agent_cursor_motion; reduced motion always wins. Built-in default: signature_arc. |
+| <span id="set_config--cursor-motion-timing"></span>`cursor.motion.timing` | `"native" \| "fitts" \| "fixed" \| "relaxed" \| "steady" \| "calm" \| "deliberate"` | | Saved default cursor move timing for new sessions. Built-in default: steady (a 600 ms floor on every move). |
+| <span id="set_config--max_image_dimension"></span>`max_image_dimension` | `integer` | | Max dimension for screenshot resizing (0 = no limit). |
+| <span id="set_config--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
+
+### `check_permissions`
+
+Effect: mutating, idempotent. Platforms: macOS, Linux, Windows.
+
+<Tabs items={['macOS', 'Linux', 'Windows']} groupId="platform" persist>
+<Tab value="macOS">
+
+Report TCC permission status for Accessibility and Screen Recording. By default also raises the system permission dialogs for any missing grants: Apple's request APIs are no-ops when the grant is already active, so this is safe to call repeatedly. Pass &#123;"prompt": false&#125; for a purely read-only status check.
+
+Returns: `accessibility` + `screen_recording` (booleans from the TCC preflight APIs), `screen_recording_capturable` (a live ScreenCaptureKit probe when `prompt` is true; null on read-only calls), `direct_capture_status` (`ready`, `unavailable`, `timed_out`, `probe_failed`, `blocked_by_screen_recording`, or `not_checked`), `direct_capture_error` (a structured timeout/probe failure when applicable), `direct_capture_verification` (validated source, UTC time, and bundle identity from an explicit grant probe), and `source` (which TCC identity the booleans reflect: the CuaDriver daemon vs the launching terminal/IDE). macOS attributes grants to the responsible process, so a standalone call from a terminal reports the terminal's grants, not the driver's. The prompt-capable ScreenCaptureKit probe never runs when `prompt` is false. Pass `probe_direct_capture:false` with `prompt:true` to register/request only the two required TCC grants before separately explaining Tahoe's direct-capture consent. How to get them granted: `get_guide({topic:"permissions"})`.
+
+**macOS parameters**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="check_permissions--macos--probe_direct_capture"></span>`probe_direct_capture` | `boolean` | | When prompting and Screen Recording is granted, also run the live ScreenCaptureKit probe that may raise Tahoe's direct-capture consent. Default true. Set false for a staged Accessibility/Screen Recording request. |
+| <span id="check_permissions--macos--prompt"></span>`prompt` | `boolean` | `false` | Raise the system permission prompts for missing grants. Default false; only a trusted host setup route may set true. |
+
+</Tab>
+<Tab value="Linux">
+
+Check required permissions for cua-driver-rs on Linux. How to get them granted: `get_guide({topic:"permissions"})`.
+
+**Linux parameters**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="check_permissions--linux--prompt"></span>`prompt` | `boolean` | | Ignored: Linux has no permission prompts. |
+
+</Tab>
+<Tab value="Windows">
+
+Check required permissions for cua-driver-rs on Windows. How to get them granted: `get_guide({topic:"permissions"})`.
+
+**Windows parameters**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="check_permissions--windows--prompt"></span>`prompt` | `boolean` | | Ignored: Windows has no permission prompts. |
+
+</Tab>
+</Tabs>
+
+**Parameters on every platform**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="check_permissions--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
+
+### `health_report`
+
+Single-call end-to-end driver diagnostics. Designed to let downstream consumers ship one stable call instead of stitching together check_permissions, doctor, version, bundle attribution, and platform capability status. On macOS, prompt-capable direct capture is deliberately skipped. For standalone CuaDriver, use `cua-driver permissions grant` to verify it explicitly. For an embedded or linked driver, use the host's permission flow for the app or executable macOS attributes this process's permission request to; the standalone command does not verify the host's capture readiness. cua-driver owns the health model; consumers stay thin.
+
+Input: all optional:
+ &#123;
+ "include": ["&lt;check_name&gt;", ...], // run only these
+ "skip": ["&lt;check_name&gt;", ...] // skip these
+ &#125;
+If both are given, `include` wins.
+
+Canonical check names:
+ macOS : binary_version, platform_supported, session_active,
+ bundle_identity, tcc_accessibility, tcc_screen_recording,
+ ax_capability, screen_capture_capability, windowserver_connection
+ Windows: binary_version, platform_supported, session_active,
+ ax_capability (via UIA), screen_capture_capability (via DXGI)
+ Linux : binary_version, platform_supported, session_active,
+ ax_capability (via AT-SPI), screen_capture_capability (via X11)
+
+Output: stable contract, schema_version="1":
+ &#123;
+ "schema_version": "1",
+ "platform": "darwin" | "win32" | "linux",
+ "driver_version": "&lt;semver&gt;",
+ "overall": "ok" | "degraded" | "failed",
+ "checks": [
+ &#123;
+ "name": "&lt;one of the canonical names above&gt;",
+ "status": "pass" | "fail" | "skip",
+ "message": "&lt;one-line summary, always present&gt;",
+ "hint": "&lt;remediation step, present when status=fail&gt;",
+ "data": &#123; /* check-specific structured fields */ &#125;
+ &#125;,
+ ...
+ ]
+ &#125;
+
+`overall` rules:
+ - `ok` : every non-skipped check passes
+ - `degraded`: at least one non-core check fails (binary is still usable)
+ - `failed` : any core check fails (binary_version, platform_supported, session_active)
+
+Stability: schema_version="1" is the contract. Future breaking changes will be `"2"`. Adding new check names under the same schema_version is non-breaking; consumers must tolerate unknown check names.
+
+Effect: read-only, idempotent. Platforms: macOS, Linux, Windows.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="health_report--include"></span>`include` | `string[]` | | Only run these checks (canonical names). Wins over `skip`. |
+| <span id="health_report--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
+| <span id="health_report--skip"></span>`skip` | `string[]` | | Skip these checks (canonical names). Ignored when `include` is set. |
+
+### `check_for_update`
+
+Check the saved stable/nightly Cua Driver channel for a release on GitHub. Returns current and selected channels, current and latest versions, an `update_available` boolean, the install one-liner, and the release notes URL. Read-only: never installs. Pacman-owned Linux executables return package-manager guidance without checking GitHub. Mirror of `cua-driver check-update --json`.
+
+Effect: read-only, idempotent. Platforms: macOS, Linux, Windows.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="check_for_update--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
+
+### `install_extension`
+
+Preview or install one Driver-managed optional extension. The first call without confirm returns the exact signed artifact, destination, license, source, and trust plan without mutation. Re-call with confirm=true to perform that exact verified installation.
+
+Effect: destructive. Platforms: macOS, Linux, Windows.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="install_extension--confirm"></span>`confirm` | `boolean` | | Install the previewed extension. Omit or false for a read-only plan. |
+| <span id="install_extension--name"></span>`name` | `"perception"` | required | Extension to preview or install. Only perception (the local visual-region parser used by parse_visual_regions) is available. |
+| <span id="install_extension--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
+
+**Example arguments**
+
+```json
+{"name":"perception"}
+```
+
+### `get_guide`
+
+Read Cua Driver guidance on demand, taken from the guide bundled with this driver (no skill install needed). Topics: overview, drag, browser, permissions, batching, menus. Call with no topic to list them. Read-only.
+
+Effect: read-only, idempotent. Platforms: macOS, Linux, Windows.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="get_guide--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
+| <span id="get_guide--topic"></span>`topic` | `string` | | One of: overview, drag, browser, permissions, batching, menus. Omit to list the topics. |
diff --git a/docs/content/docs/cua-driver/reference/mcp-tools/batch.mdx b/docs/content/docs/cua-driver/reference/mcp-tools/batch.mdx
deleted file mode 100644
index b1400a5fa1..0000000000
--- a/docs/content/docs/cua-driver/reference/mcp-tools/batch.mdx
+++ /dev/null
@@ -1,102 +0,0 @@
----
-title: "Batch and script tools"
-description: "Run several action tools, or a script that drives them, in one call."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-driver
- Source: cua-driver dump-docs --type mcp (macOS, Linux and Windows registries)
- Version: 0.36.0
-*/}
-
-| Tool | Description | Platforms |
-| --- | --- | --- |
-| [`run_steps`](#run_steps) | The default way to act: run one or more action tools in ONE call, in order, stop at the first failure, and (with `observe`) get what changed in the same response. | macOS, Linux, Windows |
-| [`run_script`](#run_script) | Run a JavaScript program that drives apps through Cua Driver, in ONE call: loops, conditions, reads and checks between actions, and only the result comes back. | macOS, Linux, Windows |
-
-Use `run_steps` for a fixed list of actions you have already decided. Use `run_script` when the flow needs
-logic between actions (a loop over rows, a branch on what the app shows, a retry): it runs a JavaScript
-program over the driver's own tools in one call and returns only its result. Every driver call either
-tool makes passes the same session, permission and approval checks as a direct call.
-
-`run_script` runs in a QuickJS sandbox with no filesystem, network, process, timers or environment.
-Limits: `timeout_ms` (default 30 s, max 120 s), `max_calls` (default 100, max 500), a 32 MiB heap and
-a 64 KiB script. It is on by default. Whoever runs the driver turns it off with
-`CUA_DRIVER_DISABLE_RUN_SCRIPT=1` or `"disable_run_script": true` in `~/.cua-driver/config.json`
-(`CUA_DRIVER_EXPERIMENTAL_SCRIPT=0` and `"experimental_script": false` also work); `set_config` cannot
-change it.
-
-Served by `cua-driver mcp`; see [MCP tools](/cua-driver/reference/mcp-tools) for every tool.
-
-## `run_steps`
-
-The default way to act: run one or more action tools in ONE call, in order, stop at the first failure, and (with `observe`) get what changed in the same response. Use it whenever you know the next action(s) and would otherwise re-read the window after them: fill three fields, click, and see the result in one call instead of five. Even a single step plus `observe:{}` replaces an action call followed by a get_window_state call. Each step is `{tool, args}` where `tool` is one of click, double_click, right_click, set_value, type_text, press_key, hotkey, scroll, drag, move_cursor and `args` are exactly that tool's arguments. `pid` and `window_id` (or `app`/`window`) on run_steps itself are the default window of every step that names none. Reads (get_window_state, zoom) do not run between steps: one there is skipped; a get_window_state last is the `observe`, a zoom last runs after it. Every step goes through the same session, permission and approval checks as a direct call; a batch grants nothing extra. All steps are validated before the first one runs, so a malformed step 4 changes nothing. Element tokens and element_index values come from a get_window_state read before the batch; a step that changes the UI can invalidate later element targets, so put element-targeted actions before the actions that reshuffle the window, or target later steps by role/name. A token that went stale is retried once on the element with the same role and label, if exactly one matches.
-
-Returns per-step status (`ok` or the error message) and, when `observe` is given, ONE bounded get_window_state read after the last executed step (after a failure caused by a dialog holding focus, that dialog is read, even without `observe`). A step refused because its app ignores background input says how to re-send it; `foreground_fallback:true` retries such steps in the foreground once (the window is activated). That read is a `since:"latest"` diff by default: only the rows that changed since your last read of the window, plus a new snapshot_id. Without `observe` nothing is read. The batch uses one session: steps may omit `session` or repeat the batch's. `delay_ms` pauses between steps (max 2000). At most 64 steps; `delivery_mode` on run_steps is the default for its steps.
-
-TARGET BY NAME (no earlier read needed, so one batch can cross screens): a step can be written `{"click": {...args}}` as well as `{tool, args}`, and its args may name the target instead of carrying a token: `role` (button, textfield, link, checkbox, menuitem, ...; AX/UIA/AT-SPI names also work), `name` (the element's label; exact match wins over substring, case-insensitive), `nth` (0-based, when several match), and `app` (app name or bundle id) and/or `window` (title substring) instead of pid/window_id. The batch reads the window fresh, waits up to 3 s (step `timeout_ms`, max 10000) for the element to appear, and acts on it; with only `app` it uses that app's frontmost window, so a dialog that opened on top is found. Later steps inherit the window, so name `app` once. The first lookup in a window also reads it once for `observe`, so the end diff shows what the batch changed even in a window you never read. Several matches fail with the candidates listed; add `nth` or a fuller name.
-
-WAITS AND CHECKS: a step may add `wait_for` (checked before its action) and `expect` (one check or up to 4, checked after it); a step may also be only a check. A check is &#123;role?, name?, text?, gone?, value?, value_contains?, enabled?, selected?, app?, window?, timeout_ms?&#125;: `text` matches any row of the tree, static text included; `gone:true` waits for it to disappear. Checks poll until they hold or time out (wait_for 5 s, expect 2 s, max 10 s), and a check that does not hold fails the step with what was found instead. The report says which step failed, in which phase (wait_for, find, action, expect) and why. Whole batch: at most 60 s.
-
-Example (fill a form, submit, confirm the dialog, check the result):
-&#123;"steps":[&#123;"set_value":&#123;"app":"Safari","role":"textfield","name":"Email","value":"[email protected]"&#125;&#125;,&#123;"click":&#123;"role":"button","name":"Submit"&#125;,"expect":[&#123;"role":"button","name":"Confirm"&#125;]&#125;,&#123;"click":&#123;"role":"button","name":"Confirm"&#125;,"expect":[&#123;"name":"Confirm","gone":true&#125;,&#123;"text":"Thanks"&#125;]&#125;],"observe":&#123;&#125;&#125; Batching rules: `get_guide({topic:"batching"})`.
-
-Effect: destructive. Platforms: macOS, Linux, Windows.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="run_steps--app"></span>`app` | `string` | | Default app (name or bundle id) for steps that name no window. |
-| <span id="run_steps--delay_ms"></span>`delay_ms` | `integer` | | Pause between steps in milliseconds (not after the last). Default 0. Range: 0 to 2000. |
-| <span id="run_steps--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | | Default delivery_mode for steps whose tool takes one and that set none. |
-| <span id="run_steps--foreground_fallback"></span>`foreground_fallback` | `boolean` | | When a step is refused because its target ignores background input (Electron, LibreOffice and other toolkits), retry it once with delivery_mode:"foreground": the window is activated and the pointer may move. Default false. |
-| <span id="run_steps--observe"></span>`observe` | `object` | | Optional end-of-batch observation: arguments for ONE get_window_state call. `pid` and `window_id` default to those of the last step that names both. Defaults to since="latest" (only what changed since your last read of that window with the same query/max_elements/max_depth; a full read when there is none), include_screenshot=false and max_elements=250; pass include_screenshot=true to see the window, or since=null for a full read. Omit to read nothing. &#123;&#125; observes the last window. |
-| <span id="run_steps--pid"></span>`pid` | `integer` | | Default pid for steps that name no window (a step's own pid/window_id/app/window wins). |
-| <span id="run_steps--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
-| <span id="run_steps--steps"></span>`steps` | `object[]` | required | Ordered actions. Execution stops at the first failing step. Each step is &#123;tool, args&#125; or &#123;&lt;tool&gt;: args&#125;, plus optional wait_for / expect / timeout_ms; a step may also be only a wait_for or expect check. Items: 1 to 64. |
-| <span id="run_steps--window"></span>`window` | `string` | | Default window title substring for steps that name no window. |
-| <span id="run_steps--window_id"></span>`window_id` | `integer` | | Default window_id for steps that name no window, with `pid`. |
-
-**Example arguments**
-
-```json
-{"steps":[{}]}
-```
-
-## `run_script`
-
-Run a JavaScript program that drives apps through Cua Driver, in ONE call: loops, conditions, reads and checks between actions, and only the result comes back. Use it when the flow needs logic (a loop over rows, a branch on what the app shows, a retry); use run_steps for a fixed list of steps.
-
-The script is the body of an async function: use `await`, and `return` a JSON value. It runs in a sandbox with no filesystem, network, process, timers or environment; the only API is `cua`:
-- `await cua.getApp("TextEdit" | "com.apple.TextEdit" | {pid, windowId})` → app (follows the app's frontmost window unless a windowId is given)
-- `await cua.launch(nameOrBundleId)` → app; `cua.listApps()`, `cua.listWindows({pid?})`, `cua.sleep(ms)`, `cua.computer.target`
-- app.getState(opts?) → get_window_state result (`tree_markdown` or `tree_diff`, `snapshot_id`; pass get_window_state options such as &#123;since:"latest"&#125;)
-- app.query(&#123;role?, name?, text?&#125;) → matching elements across the app's windows &#123;element_token, role, label, value, enabled, selected, frame&#125;, then matching static-text rows &#123;role, label, value, text, display_only&#125; (read text such as a status line from their `value`)
-- app.waitFor(&#123;role?, name?, text?, gone?, value?, timeout_ms?&#125;) and app.verify(predicate | predicates) (verify_state)
-- app.click(t), doubleClick(t), rightClick(t), typeText(text, t?), pressKey("return" | "cmd+s", t?), hotkey(["cmd","s"]), scroll(t, direction, amount?), setValue(t, value), drag([x,y], [x,y]), zoom([x1,y1,x2,y2])
-where a target `t` is &#123;role, name, nth?&#125; (found fresh, waits up to 3 s), an element_token string, a row number from this app's last getState(), or [x, y] window pixels.
-- `cua.call(tool, args)` for any other allowed tool: click, double_click, right_click, set_value, type_text, press_key, hotkey, scroll, drag, launch_app, list_apps, list_windows, get_window_state, verify_state, zoom.
-A failed driver call throws a CuaError (catch it to recover). Every call goes through the same session, permission and approval checks as a direct call.
-
-Limits: `timeout_ms` wall time (default 30000, max 120000), `max_calls` driver calls (default 100, max 500), 32 MiB heap. Returns the return value, console output, and a per-call log; an error names the script line, the call and the reason.
-
-Example:
-const app = await cua.getApp("Calculator");
-for (const key of ["7", "multiply", "6", "equals"]) await app.click(&#123;role: "button", name: key&#125;);
-const [display] = await app.query(&#123;role: "statictext"&#125;);
-return display.value; Batching rules: `get_guide({topic:"batching"})`.
-
-Effect: destructive. Platforms: macOS, Linux, Windows.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="run_script--max_calls"></span>`max_calls` | `integer` | | Most driver calls the script may make. Default 100. Range: 1 to 500. |
-| <span id="run_script--script"></span>`script` | `string` | required | JavaScript: the body of an async function. `return` the result. |
-| <span id="run_script--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
-| <span id="run_script--timeout_ms"></span>`timeout_ms` | `integer` | | Wall-time limit. Default 30000. Range: 100 to 120000. |
-
-**Example arguments**
-
-```json
-{"script":"<script>"}
-```
diff --git a/docs/content/docs/cua-driver/reference/mcp-tools/browser-input.mdx b/docs/content/docs/cua-driver/reference/mcp-tools/browser-input.mdx
deleted file mode 100644
index b3ab49e0a2..0000000000
--- a/docs/content/docs/cua-driver/reference/mcp-tools/browser-input.mdx
+++ /dev/null
@@ -1,180 +0,0 @@
----
-title: "Browser input tools"
-description: "Exact browser input over CDP: clicks, typing, pointer, dialogs, files and downloads."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-driver
- Source: cua-driver dump-docs --type mcp (macOS, Linux and Windows registries)
- Version: 0.36.0
-*/}
-
-| Tool | Description | Platforms |
-| --- | --- | --- |
-| [`browser_click`](#browser_click) | Click a page element (by ref) or viewport coordinates in an exactly-bound tab. | macOS, Linux, Windows |
-| [`browser_type`](#browser_type) | Type text into an exactly-bound tab via the Input domain. | macOS, Linux, Windows |
-| [`browser_select`](#browser_select) | Select one option of a native HTML &lt;select&gt; ref on an exactly-bound tab without opening its popup. | macOS, Linux, Windows |
-| [`browser_pointer`](#browser_pointer) | Perform hover, right-click, double-click, scroll, or drag in an exactly-bound browser tab. | macOS, Linux, Windows |
-| [`browser_dialog`](#browser_dialog) | Inspect or resolve a page-owned JavaScript alert, confirm, prompt, or beforeunload dialog on one exactly-bound tab. | macOS, Linux, Windows |
-| [`browser_set_input_files`](#browser_set_input_files) | Assign one or more explicit absolute local files to an exact live &lt;input type=file&gt; ref through CDP. | macOS, Linux, Windows |
-| [`browser_download`](#browser_download) | Trigger one download through an exact live browser ref and save it inside an explicitly approved directory. | macOS, Linux, Windows |
-
-Served by `cua-driver mcp`; see [MCP tools](/cua-driver/reference/mcp-tools) for every tool.
-
-## `browser_click`
-
-Click a page element (by ref) or viewport coordinates in an exactly-bound tab. Default route is trusted hardware-like input (Input.dispatchMouseEvent), and refuses where that route cannot preserve standalone-browser background posture unless delivery_mode="foreground" accepts that the browser window may activate (including Linux Chromium configurations whose trusted route cannot stay in the background; for example a browser inside a sandbox). input_route="dom_event" (synthetic pointer and mouse down/up/click sequence at the element's center, ref required) is used only when explicitly requested; it proves dispatch, not control activation, because trust-gated controls may ignore synthetic events. Refused for heuristic bindings.
-
-Effect: mutating. Platforms: macOS, Linux, Windows.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="browser_click--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | `"background"` | background (default) refuses trusted input where it would activate the browser window, including Linux Chromium and macOS Chromium configurations whose trusted route cannot stay in the background. foreground accepts that activation, for a browser whose window nobody else is using (for example inside a sandbox). |
-| <span id="browser_click--input_route"></span>`input_route` | `"trusted" \| "dom_event"` | | "trusted" (default): Input.dispatchMouseEvent. It refuses rather than foregrounding a standalone browser. "dom_event": synthetic full-background DOM click, only when explicitly requested. Dispatch does not prove the control activated; refresh page state and verify the expected postcondition. |
-| <span id="browser_click--ref"></span>`ref` | `string` | | Page element ref in the p&lt;snapshot&gt;:&lt;index&gt; namespace from get_browser_state. Refs are invalidated by navigation and by newer snapshots of the same tab. |
-| <span id="browser_click--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. Browser targets, tabs, and refs belong to the resolved lifecycle session. |
-| <span id="browser_click--tab_id"></span>`tab_id` | `string` | required | Opaque tab id from get_browser_state (session-scoped). |
-| <span id="browser_click--target_id"></span>`target_id` | `string` | required | Opaque browser target id minted by get_browser_state (session-scoped; never a CDP id). |
-| <span id="browser_click--x"></span>`x` | `number` | | Viewport x (CSS px): alternative to ref. |
-| <span id="browser_click--y"></span>`y` | `number` | | Viewport y (CSS px): alternative to ref. |
-
-**Example arguments**
-
-```json
-{"target_id":"<target_id>","tab_id":"<tab_id>"}
-```
-
-## `browser_type`
-
-Type text into an exactly-bound tab via the Input domain. mode="insert_text" (default) uses Input.insertText; mode="keystrokes" dispatches per-character key events. Both insert at the caret, so typing into a field that already holds text appends to it; pass replace=true to set the field instead, or to clear it by typing an empty string. Pass a ref to an editable element from the latest snapshot. A ref is required; heuristic bindings are refused.
-
-Effect: mutating. Platforms: macOS, Linux, Windows.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="browser_type--mode"></span>`mode` | `"insert_text" \| "keystrokes"` | | insert_text (default): bulk Input.insertText. keystrokes: per-character Input.dispatchKeyEvent. |
-| <span id="browser_type--ref"></span>`ref` | `string` | required | Page element ref in the p&lt;snapshot&gt;:&lt;index&gt; namespace from get_browser_state. Refs are invalidated by navigation and by newer snapshots of the same tab. |
-| <span id="browser_type--replace"></span>`replace` | `boolean` | | false (default): insert at the caret, appending to whatever the field already holds. true: select the element's whole content first so the text replaces it; with an empty text this clears the field. Replacement goes through the selection, so beforeinput/input still fire and framework state stays consistent. |
-| <span id="browser_type--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. Browser targets, tabs, and refs belong to the resolved lifecycle session. |
-| <span id="browser_type--tab_id"></span>`tab_id` | `string` | required | Opaque tab id from get_browser_state (session-scoped). |
-| <span id="browser_type--target_id"></span>`target_id` | `string` | required | Opaque browser target id minted by get_browser_state (session-scoped; never a CDP id). |
-| <span id="browser_type--text"></span>`text` | `string` | required | Text to type. |
-
-**Example arguments**
-
-```json
-{"target_id":"<target_id>","tab_id":"<tab_id>","ref":"<ref>","text":"<text>"}
-```
-
-## `browser_select`
-
-Select one option of a native HTML &lt;select&gt; ref on an exactly-bound tab without opening its popup. Pass exactly one of label or value; exactly one option must equal it. Refuses non-native, multiple-selection, and disabled selects, disabled options, and zero or ambiguous matches before changing anything. A change dispatches bubbling input and change events; they are synthetic, so verify the page accepted the selection. Selecting the option that is already selected dispatches no events.
-
-Effect: mutating. Platforms: macOS, Linux, Windows.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="browser_select--label"></span>`label` | `string` | | Exact visible label of the option to select. |
-| <span id="browser_select--ref"></span>`ref` | `string` | required | Page element ref in the p&lt;snapshot&gt;:&lt;index&gt; namespace from get_browser_state. Refs are invalidated by navigation and by newer snapshots of the same tab. |
-| <span id="browser_select--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. Browser targets, tabs, and refs belong to the resolved lifecycle session. |
-| <span id="browser_select--tab_id"></span>`tab_id` | `string` | required | Opaque tab id from get_browser_state (session-scoped). |
-| <span id="browser_select--target_id"></span>`target_id` | `string` | required | Opaque browser target id minted by get_browser_state (session-scoped; never a CDP id). |
-| <span id="browser_select--value"></span>`value` | `string` | | Exact value attribute of the option to select. |
-
-**Example arguments**
-
-```json
-{"target_id":"<target_id>","tab_id":"<tab_id>","ref":"<ref>"}
-```
-
-## `browser_pointer`
-
-Perform hover, right-click, double-click, scroll, or drag in an exactly-bound browser tab. Semantic refs must declare pointer for hover, right-click, double-click, and drag; scroll accepts a scroll or pointer capability. The trusted route uses CDP Input events and refuses if standalone background posture cannot be preserved. The explicit dom_event route requires a page ref and synthesizes full-background DOM events. Never activates or brings a tab to the foreground.
-
-Effect: mutating. Platforms: macOS, Linux, Windows.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="browser_pointer--action"></span>`action` | `"hover" \| "right_click" \| "double_click" \| "scroll" \| "drag"` | required | Pointer gesture. scroll needs delta_x or delta_y; drag needs destination_ref or to_x/to_y. |
-| <span id="browser_pointer--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | `"background"` | background (default) refuses trusted input where it would activate the browser window, including Linux Chromium and macOS Chromium configurations whose trusted route cannot stay in the background. foreground accepts that activation, for a browser whose window nobody else is using (for example inside a sandbox). |
-| <span id="browser_pointer--delta_x"></span>`delta_x` | `number` | | Horizontal scroll delta in CSS pixels. |
-| <span id="browser_pointer--delta_y"></span>`delta_y` | `number` | | Vertical scroll delta in CSS pixels. |
-| <span id="browser_pointer--destination_ref"></span>`destination_ref` | `string` | | Drag destination page ref in the exact same frame. |
-| <span id="browser_pointer--input_route"></span>`input_route` | `"trusted" \| "dom_event"` | `"trusted"` | trusted sends CDP Input events; dom_event synthesizes DOM events in the page and requires ref. |
-| <span id="browser_pointer--ref"></span>`ref` | `string` | | Origin page ref. Alternative to x/y. |
-| <span id="browser_pointer--session"></span>`session` | `string` | required | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. This tool requires the label that owns its browser target, tab, and refs. |
-| <span id="browser_pointer--tab_id"></span>`tab_id` | `string` | required | Opaque tab id minted by get_browser_state. |
-| <span id="browser_pointer--target_id"></span>`target_id` | `string` | required | Opaque target id minted by get_browser_state. |
-| <span id="browser_pointer--to_x"></span>`to_x` | `number` | | Drag destination viewport x in CSS pixels. |
-| <span id="browser_pointer--to_y"></span>`to_y` | `number` | | Drag destination viewport y in CSS pixels. |
-| <span id="browser_pointer--x"></span>`x` | `number` | | Origin viewport x in CSS pixels. |
-| <span id="browser_pointer--y"></span>`y` | `number` | | Origin viewport y in CSS pixels. |
-
-**Example arguments**
-
-```json
-{"target_id":"<target_id>","tab_id":"<tab_id>","session":"<session>","action":"hover"}
-```
-
-## `browser_dialog`
-
-Inspect or resolve a page-owned JavaScript alert, confirm, prompt, or beforeunload dialog on one exactly-bound tab. This never handles browser permission UI, extension UI, native dialogs, or file pickers. Inspect returns an opaque dialog_id; accept/dismiss require that exact current id. Resolution defaults to background delivery; Linux callers must explicitly request foreground delivery because Chromium's native modal cannot be resolved there without changing foreground posture.
-
-Effect: mutating. Platforms: macOS, Linux, Windows.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="browser_dialog--action"></span>`action` | `"inspect" \| "accept" \| "dismiss"` | required | inspect returns the current dialog and its dialog_id; accept or dismiss resolves that exact dialog. |
-| <span id="browser_dialog--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | `"background"` | Requested foreground posture for accept/dismiss. Linux Chromium requires foreground; inspect is read-only. |
-| <span id="browser_dialog--dialog_id"></span>`dialog_id` | `string` | | Opaque current dialog generation returned by action=inspect. |
-| <span id="browser_dialog--prompt_text"></span>`prompt_text` | `string` | | Sensitive response text, valid only when accepting a prompt dialog. |
-| <span id="browser_dialog--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. Browser targets, tabs, and refs belong to the resolved lifecycle session. |
-| <span id="browser_dialog--tab_id"></span>`tab_id` | `string` | required | Opaque tab id from get_browser_state (session-scoped). |
-| <span id="browser_dialog--target_id"></span>`target_id` | `string` | required | Opaque browser target id minted by get_browser_state (session-scoped; never a CDP id). |
-
-**Example arguments**
-
-```json
-{"target_id":"<target_id>","tab_id":"<tab_id>","action":"inspect"}
-```
-
-## `browser_set_input_files`
-
-Assign one or more explicit absolute local files to an exact live &lt;input type=file&gt; ref through CDP. This bypasses native file pickers, rejects symlinks and non-regular files, and never returns local paths.
-
-Effect: mutating. Platforms: macOS, Linux, Windows.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="browser_set_input_files--files"></span>`files` | `string[]` | required | Absolute paths of 1 to 32 local regular files to assign to the input. Items: 1 to 32. |
-| <span id="browser_set_input_files--ref"></span>`ref` | `string` | required | Page element ref in the p&lt;snapshot&gt;:&lt;index&gt; namespace from get_browser_state. Refs are invalidated by navigation and by newer snapshots of the same tab. |
-| <span id="browser_set_input_files--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. Browser targets, tabs, and refs belong to the resolved lifecycle session. |
-| <span id="browser_set_input_files--tab_id"></span>`tab_id` | `string` | required | Opaque tab id from get_browser_state (session-scoped). |
-| <span id="browser_set_input_files--target_id"></span>`target_id` | `string` | required | Opaque browser target id minted by get_browser_state (session-scoped; never a CDP id). |
-
-**Example arguments**
-
-```json
-{"target_id":"<target_id>","tab_id":"<tab_id>","ref":"<ref>","files":["<file>"]}
-```
-
-## `browser_download`
-
-Trigger one download through an exact live browser ref and save it inside an explicitly approved directory. Requires MCP-host destructive-tool approval, refuses ambiguous or stale capabilities, and never returns the source URL, filename, or destination path.
-
-Effect: destructive. Platforms: macOS, Linux, Windows.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="browser_download--destination_root"></span>`destination_root` | `string` | required | Absolute, existing, canonical directory approved to receive the download. |
-| <span id="browser_download--ref"></span>`ref` | `string` | required | Live page ref whose activation initiates the download. |
-| <span id="browser_download--session"></span>`session` | `string` | required | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. This tool requires the label that owns its browser target, tab, and refs. |
-| <span id="browser_download--tab_id"></span>`tab_id` | `string` | required | Opaque exact tab id from get_browser_state. |
-| <span id="browser_download--target_id"></span>`target_id` | `string` | required | Opaque exact browser target id from get_browser_state. |
-
-**Example arguments**
-
-```json
-{"session":"<session>","target_id":"<target_id>","tab_id":"<tab_id>","ref":"<ref>","destination_root":"<destination_root>"}
-```
diff --git a/docs/content/docs/cua-driver/reference/mcp-tools/click-and-type.mdx b/docs/content/docs/cua-driver/reference/mcp-tools/click-and-type.mdx
new file mode 100644
index 0000000000..761010a1ad
--- /dev/null
+++ b/docs/content/docs/cua-driver/reference/mcp-tools/click-and-type.mdx
@@ -0,0 +1,678 @@
+---
+title: "Click and type"
+description: "Clicks, typing, keys and shortcuts, element values and the clipboard."
+---
+
+{/*
+ AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
+ Generated by: pnpm --dir docs docs:generate:cua-driver
+ Source: cua-driver dump-docs --type mcp (macOS, Linux and Windows registries)
+ Version: 0.36.0
+*/}
+
+import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
+
+| Tool | Description | Platforms |
+| --- | --- | --- |
+| [`click`](#click) | Click a target pid. | macOS, Linux, Windows |
+| [`double_click`](#double_click) | Double-click at (x, y) or on an AX element identified by element_token. | macOS, Linux, Windows |
+| [`right_click`](#right_click) | Right-click against a target pid. | macOS, Linux, Windows |
+| [`type_text`](#type_text) | Insert text via `AXSetAttribute(kAXSelectedText)` into the element given by `element_token`, or the pid's focused element. | macOS, Linux, Windows |
+| [`press_key`](#press_key) | Press and release one key. | macOS, Linux, Windows |
+| [`hotkey`](#hotkey) | Press a key combination: e.g. | macOS, Linux, Windows |
+| [`set_value`](#set_value) | Set an element's value by `element_token`. | macOS, Linux, Windows |
+| [`clipboard_read`](#clipboard_read) | List available system clipboard types and optionally return privacy-sensitive plain text. | macOS, Linux, Windows |
+| [`clipboard_write`](#clipboard_write) | Replace the system clipboard with exactly one value: plain text, an image from an absolute local path, or a file URL from an absolute local path. | macOS, Linux, Windows |
+
+Served by `cua-driver mcp`; see [MCP tools](/cua-driver/reference/mcp-tools) for every tool.
+
+## Click tool
+
+Click by element or pixel.
+
+### `click`
+
+Effect: destructive. Platforms: macOS, Linux, Windows.
+
+<Tabs items={['macOS', 'Linux', 'Windows']} groupId="platform" persist>
+<Tab value="macOS">
+
+Click a target pid. Prefer `element_token` (from get_window_state): it identifies one snapshot element, works on backgrounded, minimized or off-Space windows, and moves no cursor or focus. Use `x, y` only for canvas / video / WebGL / custom-drawn surfaces missing from the AX tree.
+
+- element_token: AX action path. Tokens are scoped to (pid, window_id) and stale once the window is snapshotted again.
+- x, y: window-local pixels of the get_window_state screenshot, sent as CGEvent mouse events. Needs a visible window. `modifier` takes cmd/shift/option/ctrl.
+
+`button` defaults to left; on the AX path "right" maps to AXShowMenu and "middle" falls back to a pixel click at the element center. `action`: press (default), show_menu, pick, confirm, cancel, open, show_alternate_ui, show_default_ui; an element listing showalternateui reveals its hover-only controls with show_alternate_ui, in the background and without the pointer. `from_zoom:true` translates zoom-image pixels after a `zoom` call. Pressing a popup button opens its menu and leaves it open until an item is chosen or it is dismissed; in the background the user's front window keeps key focus meanwhile. To choose an option in one call use `set_value`. In the background a web `<select>` (Chrome, Electron) is not opened, because its menu would raise the browser window: the click is refused with `select_menu_would_raise_window`; use `set_value`.
+
+**macOS parameters**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="click--macos--action"></span>`action` | `string` | | AX action: press (default), show_menu, pick, confirm, cancel, open, show_alternate_ui, show_default_ui. show_alternate_ui reveals hover-only controls on an element that lists it, without the pointer. |
+| <span id="click--macos--button"></span>`button` | `"left" \| "right" \| "middle"` | | Mouse button. Default left. |
+| <span id="click--macos--capture_id"></span>`capture_id` | `string` | | Optional capture ID from get_window_state or get_desktop_state. With x,y it is consumed atomically; stale or mismatched captures are refused. |
+| <span id="click--macos--count"></span>`count` | `integer` | | Click count (pixel path only). Default 1. |
+| <span id="click--macos--debug_image_out"></span>`debug_image_out` | `string` | | Write a screenshot with a crosshair at (x, y) to this path. Needs window_id; not with from_zoom. |
+| <span id="click--macos--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | | Default "background" (no fronting). "foreground" briefly fronts the window, acts, then restores the prior app; needs window_id and is required for modified clicks. Escalate in order: AX element_token, background pixel, foreground, checking state between rungs; a click has no read-back except list-row selection. |
+| <span id="click--macos--from_zoom"></span>`from_zoom` | `boolean` | | x and y are in the last zoom image for this pid. |
+| <span id="click--macos--modifier"></span>`modifier` | `string[]` | | Modifier keys: cmd, shift, option/alt, ctrl. |
+| <span id="click--macos--pid"></span>`pid` | `integer` | | Target process ID. Optional with element_token (it carries the pid). |
+| <span id="click--macos--scope"></span>`scope` | `"window" \| "desktop"` | | Default "window". "desktop": x,y with no pid/window_id are true screen pixels from get_desktop_state. |
+| <span id="click--macos--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. |
+| <span id="click--macos--window_id"></span>`window_id` | `integer` | | Target window ID. Omit with element_token. |
+| <span id="click--macos--x"></span>`x` | `number` | | X in screenshot pixels (get_window_state PNG, or get_desktop_state PNG for a desktop target). |
+| <span id="click--macos--y"></span>`y` | `number` | | Y in screenshot pixels from the image selected by target. |
+
+</Tab>
+<Tab value="Linux">
+
+Click against a target pid. **Prefer `element_token` over pixel coordinates**: element_token works on backgrounded / hidden windows, surfaces a stable handle, and tells you what you're clicking via the cached AT-SPI element's role + label. Reach for `x, y` only when the target is a canvas / custom-drawn surface that doesn't appear in the AT-SPI tree.
+
+Provide either (window_id + x/y) or (pid + element_token). x/y are WINDOW-LOCAL pixels of window_id (the get_window_state screenshot frame); a point outside the window is refused (point_outside_window) and every pixel result reports the resolved window_point / screen_point. Background delivery first resolves the accessible under the point and fires its action (the result says `hit: <role> "<name>" action=...`; a file / list item is selected through its container: `selected: ...`), else presses the real virtual pointer there. A click that opens a popup menu names it (`popup: {window_id, bounds}`): pass that window_id to get_window_state to index its items. The token is stale once the next get_window_state of the same window replaces its snapshot: re-snapshot every turn before clicking.
+
+After a zoom call, pass from_zoom=true to auto-translate zoom-image coords back to full-window space.
+
+`count`: 1 (default), 2 for a double-click, 3 for a triple-click (selects a line / paragraph in editors); one press train with real double-click cadence, in background and foreground alike; there is no separate triple_click tool.
+
+button: "left" (default), "right", or "middle". Defaults to left so the field is fully back-compat. X11: routes through XSendEvent ButtonPress/Release with the matching button code. Native Wayland: only left-button is supported via the virtual-pointer protocol; right/middle return an error rather than silently degrading to left. `modifier` holds ctrl/shift/alt/super for the click on X11. Native Wayland refuses modified pointer clicks until its input protocol can carry keyboard modifier state.
+
+**Linux parameters**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="click--linux--button"></span>`button` | `"left" \| "right" \| "middle"` | | Mouse button. Default: "left" (legacy back-compat). X11: routed via ButtonPress/Release with the matching evdev code. Native Wayland: only left-button is supported via the virtual-pointer protocol; right/middle return an error. |
+| <span id="click--linux--capture_id"></span>`capture_id` | `string` | | Optional one-shot binding to the exact PNG returned by get_window_state or get_desktop_state. When present, x/y are interpreted in that capture and admitted before native dispatch. |
+| <span id="click--linux--coordinate_frame"></span>`coordinate_frame` | `"window" \| "desktop"` | | Frame of x/y (and from_x/from_y/to_x/to_y). Default "window": window-local screenshot pixels as returned by get_window_state. "desktop": full-screen pixels as returned by get_desktop_state, translated to the target window. Passing scope:"desktop" together with pid/window_id means the same thing. |
+| <span id="click--linux--count"></span>`count` | `integer` | | Number of clicks in one press train: 1 (default), 2 = double-click, 3 = triple-click (line/paragraph selection). There is no separate triple_click tool: pass count: 3 here. Minimum: 1. |
+| <span id="click--linux--cursor_id"></span>`cursor_id` | `string` | | Optional multi-cursor instance id. Default: 'default'. |
+| <span id="click--linux--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | `"background"` | Input delivery mode. 'background' (default) never activates or raises the target window. On X11 it injects via XTEST / the XInput2 master pointer (no focus steal). On Wayland it goes through libei + xdg-desktop-portal, which injects to the compositor's input focus: Wayland's security model has no per-window background targeting, so a specific non-focused window cannot be aimed at; when no libei backend is available the tool returns a structured background_unavailable error. 'foreground' is the explicit escalation: activate the target (X11 _NET_ACTIVE_WINDOW; Wayland compositor activate), inject, then restore the prior active window; a brief focus swap unless the target was already active. Matches the macOS / Windows delivery_mode surface. |
+| <span id="click--linux--from_zoom"></span>`from_zoom` | `boolean` | | Set true after a zoom call to auto-translate zoom-image pixel coordinates back to full-window space. |
+| <span id="click--linux--modifier"></span>`modifier` | `string[]` | | Modifier keys held during the action: cmd, shift, option/alt, ctrl. |
+| <span id="click--linux--pid"></span>`pid` | `integer` | | Target process ID. Required unless scope is "desktop" or element_token is supplied (the token carries the pid). |
+| <span id="click--linux--scope"></span>`scope` | `"window" \| "desktop"` | `"window"` | Coordinate frame (default "window"). Pass "desktop" with x,y and no pid/window_id for a screen-absolute click in get_desktop_state coordinates. |
+| <span id="click--linux--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
+| <span id="click--linux--window_id"></span>`window_id` | `integer` | | Window id from list_windows. Required with x/y or element_index; optional with element_token (the token carries it). |
+| <span id="click--linux--x"></span>`x` | `number` | | Window-local pixel X of the target window's own get_window_state screenshot (0..screenshot_width). For get_desktop_state pixels pass scope:"desktop" (or coordinate_frame:"desktop"). |
+| <span id="click--linux--y"></span>`y` | `number` | | Window-local pixel Y of the target window's own get_window_state screenshot (0..screenshot_height); see x. |
+
+</Tab>
+<Tab value="Windows">
+
+Left-click against a target pid. **Prefer `element_token` over pixel coordinates**: element_token works on backgrounded / minimized / hidden / off-desktop windows, surfaces a stable handle that survives rebuilds, and tells you what you're clicking via the cached element's role + label. Reach for `x, y` only when the target is a canvas / video / WebGL / custom-drawn surface that doesn't appear in the UIA tree.
+
+Two addressing modes:
+
+- `element_token` (from the last `get_window_state` snapshot of that window): performs the UIA Invoke pattern on the cached element via PostMessage. No cursor move, no focus steal. Requires a prior `get_window_state(pid, window_id)` in this turn; the token is stale once the next snapshot of the same window replaces it.
+
+- `x`, `y` (window-local screenshot pixels, top-left origin of the PNG returned by `get_window_state`). On `delivery_mode:"background"` (the default), cua-driver FIRST does a UIA hit-test at the resolved screen position: if the deepest invokable element under that point exposes `InvokePattern`, it's invoked through the accessibility channel; same background-safe path as the `element_token` mode, no foreground swap, no visible flash. **This makes pixel clicks on UWP / WinUI3 / Win11 packaged apps work flash-free out of the box**: agents should default to `delivery_mode:"background"` even on XAML hosts whose CoreInput dispatcher drops raw PostMessage. The PostMessage(WM_LBUTTONDOWN/UP) fallback only runs when the UIA hit-test misses (canvas / video / WebGL / custom-drawn surfaces with no UIA peer), and on those targets `delivery_mode:"background"` returns a structured `background_unavailable` error if PostMessage is known to drop too: at which point you switch to `delivery_mode:"foreground"`. **Always try the default `background` click first and let that error be your signal: do NOT pass `foreground` preemptively because the target 'looks like' GTK/Chromium/etc. The driver decides when background is impossible; a guessed foreground click needlessly steals the user's focus.** `count: 2` posts two down/up pairs for a double-click. Pixel clicks need a visible on-screen window to anchor the coordinate conversion (errors with `pid X has no on-screen window` otherwise).
+
+Exactly one of `element_token` or (`x` AND `y`) must be provided. `pid` is required for window scope and omitted for desktop scope. After a `zoom` call, pass `from_zoom=true` to auto-translate zoom-image coords back to full-window space.
+
+Windows-only convenience: `button: "left"|"right"|"middle"` switches the mouse button (Swift exposes right-click as a separate `right_click` tool). `action: "expand"` on an `element_token` opens the element through UIA ExpandCollapsePattern (the dropdown half of an MSAA split button); other actions use the default invoke. `debug_image_out` isn't supported yet.
+
+**Windows parameters**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="click--windows--action"></span>`action` | `string` | | Accessibility action for an element_token target. "expand" opens the element through UIA ExpandCollapsePattern, or clicks the dropdown half of an MSAA split button. Omit for the default invoke. |
+| <span id="click--windows--button"></span>`button` | `"left" \| "right" \| "middle"` | | Mouse button. Default "left". |
+| <span id="click--windows--capture_id"></span>`capture_id` | `string` | | Optional ID from get_window_state or get_desktop_state. When present, x and y are admitted against that exact capture and the ID is consumed before native dispatch. |
+| <span id="click--windows--count"></span>`count` | `integer` | | Click count: 1 (single), 2 (double), 3 (triple). Default 1. Range: 1 to 3. |
+| <span id="click--windows--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | | Input delivery mode. 'background' (default) never swaps foreground: it routes through UIA Invoke / PostMessage and the window is never raised. For targets whose input stack silently drops posted events (Chromium/Electron content, GTK buttons, VCL/LibreOffice accelerators) the tool returns a structured background_unavailable error rather than fronting. 'foreground' is the explicit escalation: a brief SetForegroundWindow swap + SendInput, restoring the prior foreground afterward. IMPORTANT: 'background' is not a hint to weigh; it is the mandatory first attempt. Do NOT pass 'foreground' preemptively because a target 'looks like' GTK/Chromium/Electron; the DRIVER decides when background is impossible and tells you so via a background_unavailable error (or a verified no-op). Only THEN re-issue the same action with 'foreground'. The lists above are the driver's detectors, not a checklist for you to front on a guess: fronting up-front needlessly steals the user's focus and is a bug, not a shortcut. Matches the macOS delivery_mode surface. |
+| <span id="click--windows--from_zoom"></span>`from_zoom` | `boolean` | | When true, x and y are pixel coordinates in the last `zoom` image for this pid. The driver maps them back to window coords. |
+| <span id="click--windows--modifier"></span>`modifier` | `string[]` | | Modifier keys held during the action: cmd, shift, option/alt, ctrl. |
+| <span id="click--windows--pid"></span>`pid` | `integer` | | Target process ID for window scope. Optional with element_token (the token carries the pid). Omit with scope=desktop for screen-absolute coordinates from get_desktop_state. |
+| <span id="click--windows--scope"></span>`scope` | `"window" \| "desktop"` | `"window"` | Coordinate frame (default "window"). Pass "desktop" with x,y and no pid/window_id for a screen-absolute click in get_desktop_state coordinates. |
+| <span id="click--windows--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
+| <span id="click--windows--window_id"></span>`window_id` | `integer` | | HWND of the target window. Omit when element_token is supplied (the token carries it). |
+| <span id="click--windows--x"></span>`x` | `number` | | X in window-local screenshot pixels: same space as the PNG get_window_state returns. Must be provided together with y. |
+| <span id="click--windows--y"></span>`y` | `number` | | Y in window-local screenshot pixels. Must be provided together with x. |
+
+</Tab>
+</Tabs>
+
+**Parameters on every platform**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="click--element_token"></span>`element_token` | `string` | | Element handle `<snapshot_id>:<row>` from get_window_state: row `[11]` of a read whose snapshot_id is s0000002a is "s0000002a:11" (also in `structuredContent.elements[].element_token`). Returns an explicit stale error naming the current snapshots once a newer read supersedes it. |
+| <span id="click--target"></span>`target` | `object` | | Exact window (kind "window", with pid and window_id) or desktop (kind "desktop", with display_id). "primary" is the portable desktop target. |
+| <span id="click--target-display_id"></span>`target.display_id` | `string` | | Display id. Required when kind is desktop; use "primary". |
+| <span id="click--target-kind"></span>`target.kind` | `"window" \| "desktop"` | | window requires pid and window_id; desktop requires display_id. |
+| <span id="click--target-pid"></span>`target.pid` | `integer` | | Process id. Required when kind is window. Minimum: 0. |
+| <span id="click--target-window_id"></span>`target.window_id` | `integer` | | Window id from list_windows. Required when kind is window. Minimum: 0. |
+
+## Double-click and right-click tools
+
+Double-click and right-click by element or pixel.
+
+### `double_click`
+
+Effect: destructive. Platforms: macOS, Linux, Windows.
+
+<Tabs items={['macOS', 'Linux', 'Windows']} groupId="platform" persist>
+<Tab value="macOS">
+
+Double-click at (x, y) or on an AX element identified by element_token.
+
+AX path (element_token provided): performs `AXOpen` when the element advertises it (Finder items, openable list rows/cells); otherwise resolves the element's on-screen center and falls back to a pixel double-click there.
+
+Pixel path (x, y provided): two down/up pairs ~80 ms apart at the given coordinates.
+
+**macOS parameters**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="double_click--macos--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | | Best-effort-background ladder rung (default "background"). "background": inject without fronting or raising the target; no focus steal. "foreground": briefly front the target, act, then restore the prior frontmost; the explicit last resort when a background attempt didn't land. Re-call with "foreground" only for the action that needs it. |
+| <span id="double_click--macos--window_id"></span>`window_id` | `integer` | | CGWindowID. Omit when element_token is supplied (the token carries it). |
+| <span id="double_click--macos--x"></span>`x` | `number` | | Screen X coordinate (pixel path). |
+| <span id="double_click--macos--y"></span>`y` | `number` | | Screen Y coordinate (pixel path). |
+
+</Tab>
+<Tab value="Linux">
+
+Double-click at (x,y) or an element_token (AT-SPI bounds). Background delivery on X11 sends real button events from the session's virtual master pointer (path mpx_pointer); a point covered by another application's window is refused (target_occluded), one covered by this app's own dialog is retargeted to it (retargeted_to). No focus steal. Provide either (window_id + x/y) or (pid + element_token). After a zoom call, pass from_zoom=true to auto-translate zoom-image coords.
+
+**Linux parameters**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="double_click--linux--coordinate_frame"></span>`coordinate_frame` | `"window" \| "desktop"` | | Frame of x/y (and from_x/from_y/to_x/to_y). Default "window": window-local screenshot pixels as returned by get_window_state. "desktop": full-screen pixels as returned by get_desktop_state, translated to the target window. Passing scope:"desktop" together with pid/window_id means the same thing. |
+| <span id="double_click--linux--cursor_id"></span>`cursor_id` | `string` | | Optional multi-cursor instance id. Default: 'default'. |
+| <span id="double_click--linux--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | `"background"` | Input delivery mode. 'background' (default) never activates or raises the target window. On X11 it injects via XTEST / the XInput2 master pointer (no focus steal). On Wayland it goes through libei + xdg-desktop-portal, which injects to the compositor's input focus: Wayland's security model has no per-window background targeting, so a specific non-focused window cannot be aimed at; when no libei backend is available the tool returns a structured background_unavailable error. 'foreground' is the explicit escalation: activate the target (X11 _NET_ACTIVE_WINDOW; Wayland compositor activate), inject, then restore the prior active window; a brief focus swap unless the target was already active. Matches the macOS / Windows delivery_mode surface. |
+| <span id="double_click--linux--from_zoom"></span>`from_zoom` | `boolean` | | Set true after a zoom call to auto-translate zoom-image pixel coordinates back to full-window space. |
+| <span id="double_click--linux--window_id"></span>`window_id` | `integer` | | Window id from list_windows. Required with x/y or element_index; optional with element_token (the token carries it). |
+| <span id="double_click--linux--x"></span>`x` | `number` | | Window-local pixel X of the target window's own get_window_state screenshot (0..screenshot_width). For get_desktop_state pixels pass scope:"desktop" (or coordinate_frame:"desktop"). |
+| <span id="double_click--linux--y"></span>`y` | `number` | | Window-local pixel Y of the target window's own get_window_state screenshot (0..screenshot_height); see x. |
+
+</Tab>
+<Tab value="Windows">
+
+Double-click against a target pid. Two addressing modes:
+
+- `element_token` (from the last `get_window_state` snapshot of that window): synthesizes a stamped pixel double-click at the element's cached on-screen center via PostMessage. (Windows has no AXOpen analogue; Swift's AXOpen-first path falls through to the same pixel recipe when the element doesn't advertise AXOpen, so the user-visible behavior matches.)
+
+- `x`, `y` (window-local screenshot pixels, top-left origin of the PNG returned by `get_window_state`): posts two WM_LBUTTONDOWN/UP pairs in quick succession to the deepest child window at that point.
+
+Exactly one of `element_token` or (`x` AND `y`) must be provided. `pid` is required with `x`, `y`; an `element_token` carries its own pid. The macOS-only `modifier` field is accepted for parity (no-op on Windows: PostMessage doesn't propagate modifier-key state).
+
+**Windows parameters**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="double_click--windows--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | | Input delivery mode. 'background' (default) never swaps foreground: it routes through UIA Invoke / PostMessage and the window is never raised. For targets whose input stack silently drops posted events (Chromium/Electron content, GTK buttons, VCL/LibreOffice accelerators) the tool returns a structured background_unavailable error rather than fronting. 'foreground' is the explicit escalation: a brief SetForegroundWindow swap + SendInput, restoring the prior foreground afterward. IMPORTANT: 'background' is not a hint to weigh; it is the mandatory first attempt. Do NOT pass 'foreground' preemptively because a target 'looks like' GTK/Chromium/Electron; the DRIVER decides when background is impossible and tells you so via a background_unavailable error (or a verified no-op). Only THEN re-issue the same action with 'foreground'. The lists above are the driver's detectors, not a checklist for you to front on a guess: fronting up-front needlessly steals the user's focus and is a bug, not a shortcut. Matches the macOS delivery_mode surface. |
+| <span id="double_click--windows--from_zoom"></span>`from_zoom` | `boolean` | | After a zoom call, pass true to translate zoom-image coords back to window space. |
+| <span id="double_click--windows--modifier"></span>`modifier` | `string[]` | | Modifier keys held during the action: cmd, shift, option/alt, ctrl. |
+| <span id="double_click--windows--window_id"></span>`window_id` | `integer` | | HWND for the target window. Omit when element_token is supplied (the token carries it). |
+| <span id="double_click--windows--x"></span>`x` | `number` | | X in window-local screenshot pixels. Must be provided together with y. |
+| <span id="double_click--windows--y"></span>`y` | `number` | | Y in window-local screenshot pixels. Must be provided together with x. |
+
+</Tab>
+</Tabs>
+
+**Parameters on every platform**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="double_click--element_token"></span>`element_token` | `string` | | Element handle `<snapshot_id>:<row>` from get_window_state: row `[11]` of a read whose snapshot_id is s0000002a is "s0000002a:11" (also in `structuredContent.elements[].element_token`). Returns an explicit stale error naming the current snapshots once a newer read supersedes it. |
+| <span id="double_click--pid"></span>`pid` | `integer` | | Target process ID. Optional with element_token (the token carries the pid). |
+| <span id="double_click--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
+
+### `right_click`
+
+Effect: destructive. Platforms: macOS, Linux, Windows.
+
+<Tabs items={['macOS', 'Linux', 'Windows']} groupId="platform" persist>
+<Tab value="macOS">
+
+Right-click against a target pid. Two addressing modes:
+
+- `element_token` (from the last `get_window_state` snapshot): performs `AXShowMenu` on the cached element. Pure AX RPC, works on backgrounded / hidden windows, no cursor move or focus steal. Requires a prior `get_window_state(pid, window_id)` in this turn.
+
+- `x`, `y`: synthesizes `rightMouseDown` / `rightMouseUp` CGEvent pair posted to the pid. Driver converts image-pixel → screen-point internally. `modifier` forces the CGEvent path (AX actions don't propagate modifier keys).
+
+Exactly one of `element_token` or (`x` AND `y`) must be provided. `pid` is required with `x`, `y`; an `element_token` carries its own pid.
+
+**macOS parameters**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="right_click--macos--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | | Best-effort-background ladder rung (default "background"). "background": inject without fronting or raising the target; no focus steal. "foreground": briefly front the target, act, then restore the prior frontmost; the explicit last resort when a background attempt didn't land. Re-call with "foreground" only for the action that needs it. |
+| <span id="right_click--macos--modifier"></span>`modifier` | `string[]` | | Modifier keys held during the right-click: cmd/shift/option/ctrl. Pixel path only. |
+| <span id="right_click--macos--window_id"></span>`window_id` | `integer` | | CGWindowID. Omit when element_token is supplied (the token carries it). |
+| <span id="right_click--macos--x"></span>`x` | `number` | | X in window-local screenshot pixels. Must be provided together with y. |
+| <span id="right_click--macos--y"></span>`y` | `number` | | Y in window-local screenshot pixels. Must be provided together with x. |
+
+</Tab>
+<Tab value="Linux">
+
+Right-click at (x,y) or an element_token (AT-SPI bounds). Background delivery on X11 sends real button events from the session's virtual master pointer (path mpx_pointer); a point covered by another application's window is refused (target_occluded), one covered by this app's own dialog is retargeted to it (retargeted_to), one outside the window is refused (point_outside_window; x/y are window-local pixels, the result reports window_point / screen_point). No focus steal. When a context menu opens, the result names it (`popup: {window_id, bounds, title}`): call get_window_state(pid, window_id=&lt;that id&gt;) to index its menu items and click them by element_token. Provide either (window_id + x/y) or (pid + element_token). After a zoom call, pass from_zoom=true to auto-translate zoom-image coords.
+
+**Linux parameters**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="right_click--linux--coordinate_frame"></span>`coordinate_frame` | `"window" \| "desktop"` | | Frame of x/y (and from_x/from_y/to_x/to_y). Default "window": window-local screenshot pixels as returned by get_window_state. "desktop": full-screen pixels as returned by get_desktop_state, translated to the target window. Passing scope:"desktop" together with pid/window_id means the same thing. |
+| <span id="right_click--linux--cursor_id"></span>`cursor_id` | `string` | | Optional multi-cursor instance id. Default: 'default'. |
+| <span id="right_click--linux--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | `"background"` | Input delivery mode. 'background' (default) never activates or raises the target window. On X11 it injects via XTEST / the XInput2 master pointer (no focus steal). On Wayland it goes through libei + xdg-desktop-portal, which injects to the compositor's input focus: Wayland's security model has no per-window background targeting, so a specific non-focused window cannot be aimed at; when no libei backend is available the tool returns a structured background_unavailable error. 'foreground' is the explicit escalation: activate the target (X11 _NET_ACTIVE_WINDOW; Wayland compositor activate), inject, then restore the prior active window; a brief focus swap unless the target was already active. Matches the macOS / Windows delivery_mode surface. |
+| <span id="right_click--linux--from_zoom"></span>`from_zoom` | `boolean` | | Set true after a zoom call to auto-translate zoom-image pixel coordinates back to full-window space. |
+| <span id="right_click--linux--modifier"></span>`modifier` | `string[]` | | Modifier keys held during the action: cmd, shift, option/alt, ctrl. |
+| <span id="right_click--linux--window_id"></span>`window_id` | `integer` | | Window id from list_windows. Required with x/y or element_index; optional with element_token (the token carries it). |
+| <span id="right_click--linux--x"></span>`x` | `number` | | Window-local pixel X of the target window's own get_window_state screenshot (0..screenshot_width). For get_desktop_state pixels pass scope:"desktop" (or coordinate_frame:"desktop"). |
+| <span id="right_click--linux--y"></span>`y` | `number` | | Window-local pixel Y of the target window's own get_window_state screenshot (0..screenshot_height); see x. |
+
+</Tab>
+<Tab value="Windows">
+
+Right-click against a target pid. Two addressing modes:
+
+- `element_token` (from the last `get_window_state` snapshot of that window): posts WM_RBUTTONDOWN/UP at the element's cached on-screen center via PostMessage. (Windows has no AXShowMenu analogue wired up yet; Swift's AX-action path falls through to the same pixel recipe on non-advertising elements, so user-visible behavior matches.)
+
+- `x`, `y` (window-local screenshot pixels, top-left origin of the PNG returned by `get_window_state`): posts WM_RBUTTONDOWN/UP to the deepest child window at that point.
+
+Exactly one of `element_token` or (`x` AND `y`) must be provided. `pid` is required with `x`, `y`; an `element_token` carries its own pid. `modifier` is accepted for parity (no-op on Windows: PostMessage doesn't propagate modifier-key state).
+
+**Windows parameters**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="right_click--windows--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | | Input delivery mode. 'background' (default) never swaps foreground: it routes through UIA Invoke / PostMessage and the window is never raised. For targets whose input stack silently drops posted events (Chromium/Electron content, GTK buttons, VCL/LibreOffice accelerators) the tool returns a structured background_unavailable error rather than fronting. 'foreground' is the explicit escalation: a brief SetForegroundWindow swap + SendInput, restoring the prior foreground afterward. IMPORTANT: 'background' is not a hint to weigh; it is the mandatory first attempt. Do NOT pass 'foreground' preemptively because a target 'looks like' GTK/Chromium/Electron; the DRIVER decides when background is impossible and tells you so via a background_unavailable error (or a verified no-op). Only THEN re-issue the same action with 'foreground'. The lists above are the driver's detectors, not a checklist for you to front on a guess: fronting up-front needlessly steals the user's focus and is a bug, not a shortcut. Matches the macOS delivery_mode surface. |
+| <span id="right_click--windows--from_zoom"></span>`from_zoom` | `boolean` | | After a zoom call, pass true to translate zoom-image coords back to window space. |
+| <span id="right_click--windows--modifier"></span>`modifier` | `string[]` | | Modifier keys held during the action: cmd, shift, option/alt, ctrl. |
+| <span id="right_click--windows--window_id"></span>`window_id` | `integer` | | HWND for the target window. Omit when element_token is supplied (the token carries it). |
+| <span id="right_click--windows--x"></span>`x` | `number` | | X in window-local screenshot pixels. Must be provided together with y. |
+| <span id="right_click--windows--y"></span>`y` | `number` | | Y in window-local screenshot pixels. Must be provided together with x. |
+
+</Tab>
+</Tabs>
+
+**Parameters on every platform**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="right_click--element_token"></span>`element_token` | `string` | | Element handle `<snapshot_id>:<row>` from get_window_state: row `[11]` of a read whose snapshot_id is s0000002a is "s0000002a:11" (also in `structuredContent.elements[].element_token`). Returns an explicit stale error naming the current snapshots once a newer read supersedes it. |
+| <span id="right_click--pid"></span>`pid` | `integer` | | Target process ID. Optional with element_token (the token carries the pid). |
+| <span id="right_click--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
+
+## Typing tools
+
+Type text into a field or window.
+
+### `type_text`
+
+Effect: destructive. Platforms: macOS, Linux, Windows.
+
+<Tabs items={['macOS', 'Linux', 'Windows']} groupId="platform" persist>
+<Tab value="macOS">
+
+Insert text via `AXSetAttribute(kAXSelectedText)` into the element given by `element_token`, or the pid's focused element. Does not press keys: use `press_key` / `hotkey` for Return, Escape, arrows. If AX insertion is unsupported (Chromium/Electron), it falls back to CGEvent typing when the route fits the transport budget; longer routes are refused with a safe chunk size.
+
+Web content (browser tabs, Slack, VS Code): AXValue is not proof the DOM saw the text, so the result is `effect:"unverifiable"` and Electron web content refuses background delivery. For a browser tab use the `page` tool. For an embedded web view pass `x, y` (no element_token) to pixel-click the field then type in one call; a pixel click will not reliably open a closed control, so AX-press it open first. Confirm from the screenshot, and use `delivery_mode:"foreground"` only if background still drops the text.
+
+**macOS parameters**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="type_text--macos--delay_ms"></span>`delay_ms` | `integer` | | Ms between characters in the CGEvent fallback. Default 30. Range: 0 to 200. |
+| <span id="type_text--macos--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | | Default "background": AX insert, then CGEvent keys, no focus steal. "foreground": front the window, type, restore; last resort for surfaces (WhatsApp/Catalyst) where background keys do not land. |
+| <span id="type_text--macos--element_token"></span>`element_token` | `string` | | Element handle `<snapshot_id>:<row>` from get_window_state: row `[11]` of a read whose snapshot_id is s0000002a is "s0000002a:11" (also in `structuredContent.elements[].element_token`). Returns an explicit stale error naming the current snapshots once a newer read supersedes it. |
+| <span id="type_text--macos--pid"></span>`pid` | `integer` | | Target process ID. |
+| <span id="type_text--macos--scope"></span>`scope` | `"window" \| "desktop"` | `"window"` | "desktop" with no pid/window_id types into the frontmost app. |
+| <span id="type_text--macos--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. |
+| <span id="type_text--macos--text"></span>`text` | `string` | required | Text to insert. |
+| <span id="type_text--macos--window_id"></span>`window_id` | `integer` | | Window ID. Omit with element_token. |
+| <span id="type_text--macos--x"></span>`x` | `number` | | Screenshot-pixel X of the field (get_window_state PNG, as in click). With y and no element_token, pixel-clicks to focus, then types. |
+| <span id="type_text--macos--y"></span>`y` | `number` | | Screenshot-pixel Y (see x). |
+
+</Tab>
+<Tab value="Linux">
+
+Type text to a window via XSendEvent (KeyPress/KeyRelease). No focus steal.
+
+**Linux parameters**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="type_text--linux--coordinate_frame"></span>`coordinate_frame` | `"window" \| "desktop"` | | Frame of x/y (and from_x/from_y/to_x/to_y). Default "window": window-local screenshot pixels as returned by get_window_state. "desktop": full-screen pixels as returned by get_desktop_state, translated to the target window. Passing scope:"desktop" together with pid/window_id means the same thing. |
+| <span id="type_text--linux--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | `"background"` | Input delivery mode. 'background' (default) never activates or raises the target window. On X11 it injects via XTEST / the XInput2 master pointer (no focus steal). On Wayland it goes through libei + xdg-desktop-portal, which injects to the compositor's input focus: Wayland's security model has no per-window background targeting, so a specific non-focused window cannot be aimed at; when no libei backend is available the tool returns a structured background_unavailable error. 'foreground' is the explicit escalation: activate the target (X11 _NET_ACTIVE_WINDOW; Wayland compositor activate), inject, then restore the prior active window; a brief focus swap unless the target was already active. Matches the macOS / Windows delivery_mode surface. |
+| <span id="type_text--linux--element_token"></span>`element_token` | `string` | | Element handle `<snapshot_id>:<row>` from get_window_state: row `[11]` of a read whose snapshot_id is s0000002a is "s0000002a:11" (also in `structuredContent.elements[].element_token`). Returns an explicit stale error naming the current snapshots once a newer read supersedes it. |
+| <span id="type_text--linux--pid"></span>`pid` | `integer` | | Target process ID. Omit with scope "desktop" to type into the focused application. |
+| <span id="type_text--linux--scope"></span>`scope` | `"window" \| "desktop"` | `"window"` | Use "desktop" with no pid to type into the focused application. Default "window". |
+| <span id="type_text--linux--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
+| <span id="type_text--linux--text"></span>`text` | `string` | required | Text to type. |
+| <span id="type_text--linux--window_id"></span>`window_id` | `integer` | | Window id from list_windows. Required with x/y; optional with element_token (the token carries it). |
+| <span id="type_text--linux--x"></span>`x` | `number` | | Pixel X of the field to type into: the element px action form. Pass x,y (no element_token) and the tool pixel-clicks there to establish real renderer focus, then types. Use for Chromium/Electron inputs the AX path can't reach. Window-local pixels of the target window's own get_window_state screenshot by default (same convention as click); for get_desktop_state pixels pass scope:"desktop" (or coordinate_frame:"desktop"): a bare pid+x/y is otherwise misinterpreted as window-local and can focus the wrong widget. |
+| <span id="type_text--linux--y"></span>`y` | `number` | | Pixel Y of the field (see x). |
+
+</Tab>
+<Tab value="Windows">
+
+Insert text into the target pid via character-by-character PostMessage(WM_CHAR) to the focused window. No focus steal.
+
+Special keys (Return, Escape, arrows, Tab) go through `press_key` / `hotkey`: they are not text.
+
+**Routing on Windows.** When the target's owning EXE or top-level window class identifies it as a XAML / WinUI3 / UWP host (modern Notepad, Calculator, Photos, Settings, etc.), the tool requires `element_token` and routes through UI Automation's `ValuePattern.SetValue`: same backend as the `set_value` tool. PostMessage WM_CHAR doesn't reach those hosts (their CoreInput dispatcher only consumes events from the system input queue), so the fallback path silently dropped chars. If you call `type_text(pid, text)` on a XAML host without `element_token`, the tool returns an actionable error pointing you at `get_window_state` first. Native ConsoleHost on Windows ARM64 is hard-refused because it can accept synthesized Unicode events without delivering them; use a process or PTY setup channel instead. Legacy Win32 apps still use the PostMessage path, preserving the no-focus-steal property.
+
+`delay_ms` (0–200, default 30) spaces successive characters on the PostMessage path so autocomplete and IME can keep up. Ignored on the UIA path (SetValue is atomic).
+
+**Windows parameters**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="type_text--windows--delay_ms"></span>`delay_ms` | `integer` | | Milliseconds between characters. Default 30. Range: 0 to 200. |
+| <span id="type_text--windows--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | | Input delivery mode. 'background' (default) never swaps foreground: it routes through UIA Invoke / PostMessage and the window is never raised. For targets whose input stack silently drops posted events (Chromium/Electron content, GTK buttons, VCL/LibreOffice accelerators) the tool returns a structured background_unavailable error rather than fronting. 'foreground' is the explicit escalation: a brief SetForegroundWindow swap + SendInput, restoring the prior foreground afterward. IMPORTANT: 'background' is not a hint to weigh; it is the mandatory first attempt. Do NOT pass 'foreground' preemptively because a target 'looks like' GTK/Chromium/Electron; the DRIVER decides when background is impossible and tells you so via a background_unavailable error (or a verified no-op). Only THEN re-issue the same action with 'foreground'. The lists above are the driver's detectors, not a checklist for you to front on a guess: fronting up-front needlessly steals the user's focus and is a bug, not a shortcut. Matches the macOS delivery_mode surface. |
+| <span id="type_text--windows--element_token"></span>`element_token` | `string` | | Opaque element handle from get_window_state. When supplied, type_text writes through UIA ValuePattern and reads that exact element back by handle. The shared ActionResult is confirmed only when the complete expected value is synchronously visible. If SetValue succeeds but read-back is stale or unavailable, the result is unverifiable with no escalation; take a fresh snapshot before retrying because deferred providers may publish only after this call returns. |
+| <span id="type_text--windows--pid"></span>`pid` | `integer` | | Target process ID. |
+| <span id="type_text--windows--scope"></span>`scope` | `"window" \| "desktop"` | | Use desktop with no pid/window_id to type into the current foreground application. |
+| <span id="type_text--windows--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
+| <span id="type_text--windows--text"></span>`text` | `string` | required | Text to insert at the focused element's cursor. |
+| <span id="type_text--windows--window_id"></span>`window_id` | `integer` | | HWND of the target window. Omit when element_token is supplied (the token carries it). |
+| <span id="type_text--windows--x"></span>`x` | `number` | | Window-local screenshot-pixel X of the field to type into: the element px action form. Pass x,y (no element_token) and the tool pixel-clicks there to establish real renderer focus, then types. Use for Chromium/Electron inputs the UIA/WM_CHAR path can't reach. Read straight off the get_window_state PNG, same convention as click. |
+| <span id="type_text--windows--y"></span>`y` | `number` | | Window-local screenshot-pixel Y of the field (see x). |
+
+</Tab>
+</Tabs>
+
+**Parameters on every platform**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="type_text--target"></span>`target` | `object` | | Preferred per-call target: an exact window (`kind="window"`, `pid`, `window_id`) or the primary desktop (`kind="desktop"`, `display_id="primary"`). |
+| <span id="type_text--target-display_id"></span>`target.display_id` | `string` | | Display id. Required when kind is desktop; use "primary". |
+| <span id="type_text--target-kind"></span>`target.kind` | `"window" \| "desktop"` | | window requires pid and window_id; desktop requires display_id. |
+| <span id="type_text--target-pid"></span>`target.pid` | `integer` | | Process id. Required when kind is window. Minimum: 0. |
+| <span id="type_text--target-window_id"></span>`target.window_id` | `integer` | | Window id from list_windows. Required when kind is window. Minimum: 0. |
+
+**Example arguments**
+
+```json
+{"text":"<text>"}
+```
+
+## Key and shortcut tools
+
+Press keys and keyboard shortcuts.
+
+### `press_key`
+
+Effect: destructive. Platforms: macOS, Linux, Windows.
+
+<Tabs items={['macOS', 'Linux', 'Windows']} groupId="platform" persist>
+<Tab value="macOS">
+
+Press and release one key. `delivery_mode` as in click/type_text.
+- `background` (default): posts to the pid without raising the window; with `element_token` it focuses that element first.
+- `foreground`: fronts the exact window (needs `window_id`), sends a real HID key transition (Chromium content, inline editors, menu equivalents), then restores the prior app.
+
+An element target whose focus cannot be confirmed is refused with `target_focus_unconfirmed`, effect "refused", and no key dispatched.
+Confirmed only when a native AX value/selection read-back changes; otherwise `effect:"unverifiable"` (not a delivery failure). Keys: return, tab, escape, up/down/left/right, space, delete, home, end, pageup, pagedown, f1-f12, any letter or digit.
+
+**macOS parameters**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="press_key--macos--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | | Default "background": no fronting or focus steal. "foreground": briefly front the window, act, restore the prior app; last resort when background did not land. |
+| <span id="press_key--macos--key"></span>`key` | `string` | required | Key name. |
+| <span id="press_key--macos--modifiers"></span>`modifiers` | `string[]` | | cmd, shift, option/alt, ctrl, fn. |
+| <span id="press_key--macos--pid"></span>`pid` | `integer` | | Target process ID. |
+| <span id="press_key--macos--scope"></span>`scope` | `"window" \| "desktop"` | `"window"` | "desktop" with no pid/window_id sends to the frontmost app. |
+| <span id="press_key--macos--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. |
+| <span id="press_key--macos--window_id"></span>`window_id` | `integer` | | Target window; required for foreground. Does not raise by itself. |
+| <span id="press_key--macos--x"></span>`x` | `number` | | Screenshot-pixel X: pixel-click to focus, then send the key. With y, no element_token. |
+| <span id="press_key--macos--y"></span>`y` | `number` | | Screenshot-pixel Y (see x). |
+
+</Tab>
+<Tab value="Linux">
+
+Press a key via XSendEvent to a window. No focus steal.
+
+**Linux parameters**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="press_key--linux--coordinate_frame"></span>`coordinate_frame` | `"window" \| "desktop"` | | Frame of x/y (and from_x/from_y/to_x/to_y). Default "window": window-local screenshot pixels as returned by get_window_state. "desktop": full-screen pixels as returned by get_desktop_state, translated to the target window. Passing scope:"desktop" together with pid/window_id means the same thing. |
+| <span id="press_key--linux--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | `"background"` | Input delivery mode. 'background' (default) never activates or raises the target window. On X11 it injects via XTEST / the XInput2 master pointer (no focus steal). On Wayland it goes through libei + xdg-desktop-portal, which injects to the compositor's input focus: Wayland's security model has no per-window background targeting, so a specific non-focused window cannot be aimed at; when no libei backend is available the tool returns a structured background_unavailable error. 'foreground' is the explicit escalation: activate the target (X11 _NET_ACTIVE_WINDOW; Wayland compositor activate), inject, then restore the prior active window; a brief focus swap unless the target was already active. Matches the macOS / Windows delivery_mode surface. |
+| <span id="press_key--linux--key"></span>`key` | `string` | required | Key name: enter/return, tab, escape, space, backspace, delete, insert, home, end, pageup, pagedown, up, down, left, right, f1-f12, or any single ASCII character. |
+| <span id="press_key--linux--modifiers"></span>`modifiers` | `string[]` | | Modifier keys held while the key is pressed: ctrl, shift, alt, super. |
+| <span id="press_key--linux--pid"></span>`pid` | `integer` | | Target process ID. Omit with scope "desktop" to send the key to the focused application. |
+| <span id="press_key--linux--scope"></span>`scope` | `"window" \| "desktop"` | `"window"` | Use "desktop" with no pid to send the key to the focused application. Default "window". |
+| <span id="press_key--linux--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
+| <span id="press_key--linux--window_id"></span>`window_id` | `integer` | | Window id from list_windows. Required with x/y or element_index; optional with element_token (the token carries it). |
+| <span id="press_key--linux--x"></span>`x` | `number` | | Pixel X: the element px action form: pixel-click there to focus, then send the key. Use when the key must go to a Chromium/Electron surface the AX path can't focus. Pass with y, no element_token. Window-local pixels by default (same convention as click); for get_desktop_state pixels pass scope:"desktop" (or coordinate_frame:"desktop"). |
+| <span id="press_key--linux--y"></span>`y` | `number` | | Pixel Y (see x). |
+
+</Tab>
+<Tab value="Windows">
+
+Press and release a single key, delivered directly to the target pid's top-level window via PostMessage(WM_KEYDOWN/WM_KEYUP). The target does NOT need to be frontmost: no focus steal.
+
+Optional `window_id` selects a specific HWND when the pid owns more than one; without it the first visible top-level window for the pid is used.
+
+Key vocabulary: return, tab, escape, up/down/left/right, space, delete, home, end, pageup, pagedown, f1-f12, plus any letter or digit. Optional `modifiers` array takes ctrl/shift/alt/win. For true combinations (ctrl+c), `hotkey` is a cleaner surface.
+
+`element_token` focuses the cached UIA element before sending the key; the top-level window remains backgrounded when delivery_mode is background.
+
+**Windows parameters**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="press_key--windows--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | | Input delivery mode. 'background' (default) never swaps foreground: it routes through UIA Invoke / PostMessage and the window is never raised. For targets whose input stack silently drops posted events (Chromium/Electron content, GTK buttons, VCL/LibreOffice accelerators) the tool returns a structured background_unavailable error rather than fronting. 'foreground' is the explicit escalation: a brief SetForegroundWindow swap + SendInput, restoring the prior foreground afterward. IMPORTANT: 'background' is not a hint to weigh; it is the mandatory first attempt. Do NOT pass 'foreground' preemptively because a target 'looks like' GTK/Chromium/Electron; the DRIVER decides when background is impossible and tells you so via a background_unavailable error (or a verified no-op). Only THEN re-issue the same action with 'foreground'. The lists above are the driver's detectors, not a checklist for you to front on a guess: fronting up-front needlessly steals the user's focus and is a bug, not a shortcut. Matches the macOS delivery_mode surface. |
+| <span id="press_key--windows--key"></span>`key` | `string` | required | Key name (return, tab, escape, up, down, left, right, space, delete, home, end, pageup, pagedown, f1-f12, letter, digit). |
+| <span id="press_key--windows--modifiers"></span>`modifiers` | `string[]` | | Optional modifier names held while the key is pressed (ctrl/shift/alt/win). |
+| <span id="press_key--windows--pid"></span>`pid` | `integer` | | Target process ID. |
+| <span id="press_key--windows--scope"></span>`scope` | `"window" \| "desktop"` | | Use desktop with no pid/window_id to send the key to the current foreground application. |
+| <span id="press_key--windows--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
+| <span id="press_key--windows--window_id"></span>`window_id` | `integer` | | HWND for the target window. Omit when element_token is supplied; otherwise auto-resolves the pid's first visible window. |
+| <span id="press_key--windows--x"></span>`x` | `number` | | Window-local screenshot-pixel X: the element px action form: pixel-click there to focus, then send the key. Use when the key must go to a Chromium/Electron surface the UIA path can't focus. Pass with y, no element_token. |
+| <span id="press_key--windows--y"></span>`y` | `number` | | Window-local screenshot-pixel Y (see x). |
+
+</Tab>
+</Tabs>
+
+**Parameters on every platform**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="press_key--element_token"></span>`element_token` | `string` | | Element handle `<snapshot_id>:<row>` from get_window_state: row `[11]` of a read whose snapshot_id is s0000002a is "s0000002a:11" (also in `structuredContent.elements[].element_token`). Returns an explicit stale error naming the current snapshots once a newer read supersedes it. |
+| <span id="press_key--target"></span>`target` | `object` | | Preferred per-call target: an exact window (`kind="window"`, `pid`, `window_id`) or the primary desktop (`kind="desktop"`, `display_id="primary"`). |
+| <span id="press_key--target-display_id"></span>`target.display_id` | `string` | | Display id. Required when kind is desktop; use "primary". |
+| <span id="press_key--target-kind"></span>`target.kind` | `"window" \| "desktop"` | | window requires pid and window_id; desktop requires display_id. |
+| <span id="press_key--target-pid"></span>`target.pid` | `integer` | | Process id. Required when kind is window. Minimum: 0. |
+| <span id="press_key--target-window_id"></span>`target.window_id` | `integer` | | Window id from list_windows. Required when kind is window. Minimum: 0. |
+
+**Example arguments**
+
+```json
+{"key":"<key>"}
+```
+
+### `hotkey`
+
+Effect: destructive. Platforms: macOS, Linux, Windows.
+
+<Tabs items={['macOS', 'Linux', 'Windows']} groupId="platform" persist>
+<Tab value="macOS">
+
+Press a key combination: e.g. `["cmd", "c"]` for Copy, `["cmd", "shift", "4"]` for screenshot selection. Follows the same `delivery_mode` ladder as click/type_text: it does NOT raise the window by default:
+• `background` (default): post the combo to the target pid WITHOUT fronting or raising it; uses the macOS 14+ auth-message envelope so Chromium/Electron accept it as trusted live input. With an AX target, focus that exact element first. No top-level focus steal. `window_id` here only targets the combo; it does not raise. Background key events never reach a native app's menus, so when the combo is a menu item's key equivalent (cmd+s, cmd+w, ...) and the app is not in front, that menu item runs through accessibility instead (a disabled Save is saved through the app's scripting interface and verified on disk); a menu item macOS keeps disabled in the background is refused with `background_unavailable`, and no keys are sent.
+• `foreground`: briefly front the window (NSMenu path, &lt; 1 ms via SLPSSetFrontProcessWithOptions) so native menu key-equivalents (Cmd+Z, Cmd+W) dispatch, then restore the prior frontmost; the explicit escalation for menu-bar shortcuts on non-Chromium apps that ignore a background combo. With an AX target or x,y, the focused field receives the chord through the foreground HID queue (needed by native Chromium fields such as the omnibox). Requires window_id.
+
+A combo is never driver-verifiable (no read-back) → effect:"unverifiable"; confirm via screenshot. NOTE: a keyboard combo does NOT focus a text field; to type into a backgrounded Electron input, establish real renderer focus with a PIXEL click first, then `type_text`. If an app only accepts paste, call `clipboard_write`, then `clipboard_read` and verify its types (and text when applicable) before selecting or replacing editor content; only then send Cmd+V.
+
+Recognized modifiers: cmd/command, shift, option/alt, ctrl/control, fn. Non-modifier keys use the same vocabulary as `press_key`. Order: modifiers first, one non-modifier last.
+
+**macOS parameters**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="hotkey--macos--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | | Best-effort-background ladder rung (default "background"). "background": inject without fronting or raising the target; no focus steal. "foreground": briefly front the target, act, then restore the prior frontmost; the explicit last resort when a background attempt didn't land. Re-call with "foreground" only for the action that needs it. |
+| <span id="hotkey--macos--keys"></span>`keys` | `string[]` | required | Modifier(s) and one non-modifier key, e.g. ["cmd", "c"]. Items: 2 to any. |
+| <span id="hotkey--macos--pid"></span>`pid` | `integer` | | Target process ID. Required with x, y; optional with element_token (the token carries the pid). |
+| <span id="hotkey--macos--scope"></span>`scope` | `"window" \| "desktop"` | `"window"` | Use desktop with no pid/window_id to send the chord to the frontmost application. |
+| <span id="hotkey--macos--window_id"></span>`window_id` | `integer` | | Target window. Required for delivery_mode:"foreground" (the NSMenu activation needs a window). Does NOT itself raise the window: raising is gated on delivery_mode. |
+| <span id="hotkey--macos--x"></span>`x` | `number` | | Screenshot-pixel X: the element px action form: pixel-click there to focus, then send the combo (so e.g. Cmd+V pastes into that field). Pass with y. Use for Chromium/Electron surfaces the background combo can't reach. |
+| <span id="hotkey--macos--y"></span>`y` | `number` | | Screenshot-pixel Y (see x). |
+
+</Tab>
+<Tab value="Linux">
+
+Press a combination of keys simultaneously, e.g. ["ctrl","c"] for Copy. Delivered to the target window without focus steal (real key events from a virtual master keyboard on X11); target does NOT need to be frontmost. Window-manager chords cannot reach the WM that way: alt+F4 on a window target closes that window through the WM (_NET_CLOSE_WINDOW, effect confirmed when it unmaps); super+*, alt+tab, ctrl+alt+* and other WM bindings are refused with code wm_chord_unavailable; use bring_to_front / list_windows / kill_app or delivery_mode:"foreground" instead.
+
+**Linux parameters**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="hotkey--linux--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | `"background"` | Input delivery mode. 'background' (default) never activates or raises the target window. On X11 it injects via XTEST / the XInput2 master pointer (no focus steal). On Wayland it goes through libei + xdg-desktop-portal, which injects to the compositor's input focus: Wayland's security model has no per-window background targeting, so a specific non-focused window cannot be aimed at; when no libei backend is available the tool returns a structured background_unavailable error. 'foreground' is the explicit escalation: activate the target (X11 _NET_ACTIVE_WINDOW; Wayland compositor activate), inject, then restore the prior active window; a brief focus swap unless the target was already active. Matches the macOS / Windows delivery_mode surface. |
+| <span id="hotkey--linux--keys"></span>`keys` | `string[]` | required | Modifier(s) + one non-modifier key, e.g. ["ctrl","c"]. Items: 2 to any. |
+| <span id="hotkey--linux--pid"></span>`pid` | `integer` | | Target process ID. Omit with scope "desktop" to send the chord to the focused application. |
+| <span id="hotkey--linux--scope"></span>`scope` | `"window" \| "desktop"` | `"window"` | Use "desktop" with no pid to send the chord to the focused application. Default "window". |
+| <span id="hotkey--linux--window_id"></span>`window_id` | `integer` | | Window id from list_windows. Required with x/y or element_index; optional with element_token (the token carries it). |
+| <span id="hotkey--linux--x"></span>`x` | `number` | | Screenshot-pixel X: the element px action form: pixel-click there to focus, then send the combo (so e.g. Ctrl+V pastes into that field). Pass with y. Use for Chromium/Electron surfaces the background combo can't reach. |
+| <span id="hotkey--linux--y"></span>`y` | `number` | | Screenshot-pixel Y (see x). |
+
+</Tab>
+<Tab value="Windows">
+
+Press a combination of keys simultaneously: e.g. `["ctrl", "c"]` for Copy, `["ctrl", "shift", "t"]` for reopen-closed-tab. Dispatch is target-aware:
+
+- **Modern XAML / WinUI / UWP targets** route through UI Automation: the driver walks the target's accessibility subtree, finds a descendant whose AcceleratorKey matches the combo, and invokes it. No focus steal, no system-queue input.
+
+- **Legacy Win32 targets with modifiers** (Ctrl+S, Alt+Tab, etc.) route through `SendInput` against the system input queue, with a brief `SetForegroundWindow` swap so the events land on the target. This path is necessary because PostMessage(WM_KEYDOWN, VK_CONTROL) does NOT update the OS-wide modifier state visible to `GetKeyState` / `TranslateAccelerator`, so Win32 apps that bind accelerators via `TranslateAccelerator` (LibreOffice, FAR, classic Notepad, etc.) never see the combo as a real accelerator on the PostMessage-only path. Trade-off: brief foreground swap (mitigated by restoring the previous foreground after the keystrokes flush). Requires the daemon to have UIAccess integrity so `SetForegroundWindow` is permitted: the MCP proxy auto-prefers the `cua-driver-uia.exe` worker pipe when both daemons are running.
+
+- **Legacy Win32 targets without modifiers** (plain `enter`, `tab`, `f5`, etc.) route through `PostMessage(WM_KEYDOWN/UP)`: no focus steal, no need to update modifier state.
+
+The target does NOT need to be frontmost in any branch.
+
+**`window_id`** (optional): explicit HWND when the pid owns more than one window; otherwise the pid's first visible window is used.
+
+Recognized modifiers: ctrl/control, shift, alt, win/windows. Non-modifier keys use the same vocabulary as `press_key` (return, tab, escape, up/down/left/right, space, delete, home, end, pageup, pagedown, f1-f12, letters, digits). Order: modifiers first, one non-modifier last.
+
+**Windows parameters**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="hotkey--windows--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | | Input delivery mode. 'background' (default) never swaps foreground: it routes through UIA Invoke / PostMessage and the window is never raised. For targets whose input stack silently drops posted events (Chromium/Electron content, GTK buttons, VCL/LibreOffice accelerators) the tool returns a structured background_unavailable error rather than fronting. 'foreground' is the explicit escalation: a brief SetForegroundWindow swap + SendInput, restoring the prior foreground afterward. IMPORTANT: 'background' is not a hint to weigh; it is the mandatory first attempt. Do NOT pass 'foreground' preemptively because a target 'looks like' GTK/Chromium/Electron; the DRIVER decides when background is impossible and tells you so via a background_unavailable error (or a verified no-op). Only THEN re-issue the same action with 'foreground'. The lists above are the driver's detectors, not a checklist for you to front on a guess: fronting up-front needlessly steals the user's focus and is a bug, not a shortcut. Matches the macOS delivery_mode surface. |
+| <span id="hotkey--windows--keys"></span>`keys` | `string[]` | required | Modifier(s) and one non-modifier key, e.g. ["ctrl", "c"]. Items: 2 to any. |
+| <span id="hotkey--windows--pid"></span>`pid` | `integer` | | Target process ID. |
+| <span id="hotkey--windows--scope"></span>`scope` | `"window" \| "desktop"` | | Use desktop with no pid/window_id to send the hotkey to the current foreground application. |
+| <span id="hotkey--windows--window_id"></span>`window_id` | `integer` | | Explicit HWND when the pid owns multiple windows. |
+| <span id="hotkey--windows--x"></span>`x` | `number` | | Window-local screenshot-pixel X: the element px action form: pixel-click there to focus, then send the combo (so e.g. Ctrl+V pastes into that field). Pass with y. Use for Chromium/Electron surfaces the background combo can't reach. |
+| <span id="hotkey--windows--y"></span>`y` | `number` | | Window-local screenshot-pixel Y (see x). |
+
+</Tab>
+</Tabs>
+
+**Parameters on every platform**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="hotkey--element_token"></span>`element_token` | `string` | | Element handle `<snapshot_id>:<row>` from get_window_state: row `[11]` of a read whose snapshot_id is s0000002a is "s0000002a:11" (also in `structuredContent.elements[].element_token`). Returns an explicit stale error naming the current snapshots once a newer read supersedes it. |
+| <span id="hotkey--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
+| <span id="hotkey--target"></span>`target` | `object` | | Preferred per-call target: an exact window (`kind="window"`, `pid`, `window_id`) or the primary desktop (`kind="desktop"`, `display_id="primary"`). |
+| <span id="hotkey--target-display_id"></span>`target.display_id` | `string` | | Display id. Required when kind is desktop; use "primary". |
+| <span id="hotkey--target-kind"></span>`target.kind` | `"window" \| "desktop"` | | window requires pid and window_id; desktop requires display_id. |
+| <span id="hotkey--target-pid"></span>`target.pid` | `integer` | | Process id. Required when kind is window. Minimum: 0. |
+| <span id="hotkey--target-window_id"></span>`target.window_id` | `integer` | | Window id from list_windows. Required when kind is window. Minimum: 0. |
+
+**Example arguments**
+
+```json
+{"keys":["<key>","<key>"]}
+```
+
+## Value and clipboard tools
+
+Set element values and read or write the clipboard.
+
+### `set_value`
+
+Effect: destructive, idempotent. Platforms: macOS, Linux, Windows.
+
+<Tabs items={['macOS', 'Linux', 'Windows']} groupId="platform" persist>
+<Tab value="macOS">
+
+Set an element's value by `element_token`. A popup button / select dropdown: selects the menu item whose title or value matches `value` (case-insensitive). Safari `<select>` is set through the DOM; AppKit and Chromium popups list items only while open, so the menu is opened, the item pressed and the menu closed again (in the background the user's front window keeps key focus). An unknown value lists the options. Any other element: writes AXValue (sliders, steppers, date pickers, native text fields).
+
+A Finder file name cell (list or icon view, not being edited) is renamed through Finder's scripting interface with Finder left in the background, and the new name is read back from disk; the value is the full new name with its extension. macOS asks the user once to allow Cua Driver to control Finder. Finder's Get Info `Name` field is refused with `file_name_needs_rename`. For free-form text in web inputs use `type_text_chars`: WebKit ignores AXValue writes.
+
+**macOS parameters**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="set_value--macos--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. |
+| <span id="set_value--macos--value"></span>`value` | `string` | required | New value, coerced to the element's type. |
+| <span id="set_value--macos--window_id"></span>`window_id` | `integer` | | Window ID. Omit with element_token. |
+
+</Tab>
+<Tab value="Linux">
+
+Set value of an AT-SPI element via SetValue action.
+
+**Linux parameters**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="set_value--linux--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | `"background"` | Input delivery mode. 'background' (default) never activates or raises the target window. On X11 it injects via XTEST / the XInput2 master pointer (no focus steal). On Wayland it goes through libei + xdg-desktop-portal, which injects to the compositor's input focus: Wayland's security model has no per-window background targeting, so a specific non-focused window cannot be aimed at; when no libei backend is available the tool returns a structured background_unavailable error. 'foreground' is the explicit escalation: activate the target (X11 _NET_ACTIVE_WINDOW; Wayland compositor activate), inject, then restore the prior active window; a brief focus swap unless the target was already active. Matches the macOS / Windows delivery_mode surface. |
+| <span id="set_value--linux--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
+| <span id="set_value--linux--value"></span>`value` | `string` | required | New value. Written through AT-SPI EditableText/Value when the element exposes them; otherwise (GTK2 spin scales, VCL spin buttons) the field is clicked with the session's real pointer, its text selected and replaced through the virtual keyboard and committed with Tab, then read back. |
+| <span id="set_value--linux--window_id"></span>`window_id` | `integer` | | Omit when element_token is supplied (the token carries it). |
+
+</Tab>
+<Tab value="Windows">
+
+Set a value on a UIA element via the ValuePattern interface.
+
+Two semantic modes (matching Swift's split):
+- **Standard input** (text fields, sliders, combo box edit): writes the value directly through UIA `IUIAutomationValuePattern::SetValue`. This is the canonical Windows write path, equivalent to Swift's `AXValue` write.
+- **ComboBox**: on a native Win32 combo box (WinForms, MFC, dialogs) selects the option whose text matches `value` and sends the app the notifications a user's choice sends (CBN_SELENDOK, CBN_SELCHANGE), without focusing the window; an editable combo gets the text typed into its edit field. A drop-down list without that option is refused with the list of options. Other combo boxes get a UIA value write, which the app may not treat as a selection.
+
+For free-form text entry that the target accepts via keystrokes only, prefer `type_text`: UIA ValuePattern writes are ignored by some web inputs (same caveat as Swift's `AXValue`-vs-WebKit).
+
+**Windows parameters**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="set_value--windows--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | | Input delivery mode. 'background' (default) never swaps foreground: it routes through UIA Invoke / PostMessage and the window is never raised. For targets whose input stack silently drops posted events (Chromium/Electron content, GTK buttons, VCL/LibreOffice accelerators) the tool returns a structured background_unavailable error rather than fronting. 'foreground' is the explicit escalation: a brief SetForegroundWindow swap + SendInput, restoring the prior foreground afterward. IMPORTANT: 'background' is not a hint to weigh; it is the mandatory first attempt. Do NOT pass 'foreground' preemptively because a target 'looks like' GTK/Chromium/Electron; the DRIVER decides when background is impossible and tells you so via a background_unavailable error (or a verified no-op). Only THEN re-issue the same action with 'foreground'. The lists above are the driver's detectors, not a checklist for you to front on a guess: fronting up-front needlessly steals the user's focus and is a bug, not a shortcut. Matches the macOS delivery_mode surface. |
+| <span id="set_value--windows--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
+| <span id="set_value--windows--value"></span>`value` | `string` | required | New value. UIA will coerce to the element's native type. |
+| <span id="set_value--windows--window_id"></span>`window_id` | `integer` | | HWND of the window. Omit when element_token is supplied (the token carries it). |
+
+</Tab>
+</Tabs>
+
+**Parameters on every platform**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="set_value--element_token"></span>`element_token` | `string` | | Element handle `<snapshot_id>:<row>` from get_window_state: row `[11]` of a read whose snapshot_id is s0000002a is "s0000002a:11" (also in `structuredContent.elements[].element_token`). Returns an explicit stale error naming the current snapshots once a newer read supersedes it. |
+| <span id="set_value--pid"></span>`pid` | `integer` | | Target process ID. Optional with element_token (the token carries the pid). |
+
+**Example arguments**
+
+```json
+{"value":"<value>"}
+```
+
+### `clipboard_read`
+
+List available system clipboard types and optionally return privacy-sensitive plain text. Clipboard content is never retained in telemetry.
+
+Effect: read-only. Platforms: macOS, Linux, Windows.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="clipboard_read--include_text"></span>`include_text` | `boolean` | `false` | Return plain-text clipboard content in addition to the available types. Clipboard content is privacy-sensitive and is never retained in telemetry. |
+| <span id="clipboard_read--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
+
+### `clipboard_write`
+
+Replace the system clipboard with exactly one value: plain text, an image from an absolute local path, or a file URL from an absolute local path. Returns the available types for read-back before paste.
+
+Effect: destructive, idempotent. Platforms: macOS, Linux, Windows.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="clipboard_write--file_path"></span>`file_path` | `string` | | Absolute path to a local file to place on the clipboard as a file URL. |
+| <span id="clipboard_write--image_path"></span>`image_path` | `string` | | Absolute path to a local image to place on the clipboard. |
+| <span id="clipboard_write--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
+| <span id="clipboard_write--text"></span>`text` | `string` | | Plain text to place on the clipboard. |
diff --git a/docs/content/docs/cua-driver/reference/mcp-tools/click.mdx b/docs/content/docs/cua-driver/reference/mcp-tools/click.mdx
deleted file mode 100644
index be41898bd0..0000000000
--- a/docs/content/docs/cua-driver/reference/mcp-tools/click.mdx
+++ /dev/null
@@ -1,127 +0,0 @@
----
-title: "Click tool"
-description: "Click by element or pixel."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-driver
- Source: cua-driver dump-docs --type mcp (macOS, Linux and Windows registries)
- Version: 0.36.0
-*/}
-
-import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
-
-Served by `cua-driver mcp`; see [MCP tools](/cua-driver/reference/mcp-tools) for every tool.
-
-## `click`
-
-Effect: destructive. Platforms: macOS, Linux, Windows.
-
-<Tabs items={['macOS', 'Linux', 'Windows']} groupId="platform" persist>
-<Tab value="macOS">
-
-Click a target pid. Prefer `element_token` (from get_window_state): it identifies one snapshot element, works on backgrounded, minimized or off-Space windows, and moves no cursor or focus. Use `x, y` only for canvas / video / WebGL / custom-drawn surfaces missing from the AX tree.
-
-- element_token: AX action path. Tokens are scoped to (pid, window_id) and stale once the window is snapshotted again.
-- x, y: window-local pixels of the get_window_state screenshot, sent as CGEvent mouse events. Needs a visible window. `modifier` takes cmd/shift/option/ctrl.
-
-`button` defaults to left; on the AX path "right" maps to AXShowMenu and "middle" falls back to a pixel click at the element center. `action`: press (default), show_menu, pick, confirm, cancel, open, show_alternate_ui, show_default_ui; an element listing showalternateui reveals its hover-only controls with show_alternate_ui, in the background and without the pointer. `from_zoom:true` translates zoom-image pixels after a `zoom` call. Pressing a popup button opens its menu and leaves it open until an item is chosen or it is dismissed; in the background the user's front window keeps key focus meanwhile. To choose an option in one call use `set_value`. In the background a web `<select>` (Chrome, Electron) is not opened, because its menu would raise the browser window: the click is refused with `select_menu_would_raise_window`; use `set_value`.
-
-**macOS parameters**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="click--macos--action"></span>`action` | `string` | | AX action: press (default), show_menu, pick, confirm, cancel, open, show_alternate_ui, show_default_ui. show_alternate_ui reveals hover-only controls on an element that lists it, without the pointer. |
-| <span id="click--macos--button"></span>`button` | `"left" \| "right" \| "middle"` | | Mouse button. Default left. |
-| <span id="click--macos--capture_id"></span>`capture_id` | `string` | | Optional capture ID from get_window_state or get_desktop_state. With x,y it is consumed atomically; stale or mismatched captures are refused. |
-| <span id="click--macos--count"></span>`count` | `integer` | | Click count (pixel path only). Default 1. |
-| <span id="click--macos--debug_image_out"></span>`debug_image_out` | `string` | | Write a screenshot with a crosshair at (x, y) to this path. Needs window_id; not with from_zoom. |
-| <span id="click--macos--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | | Default "background" (no fronting). "foreground" briefly fronts the window, acts, then restores the prior app; needs window_id and is required for modified clicks. Escalate in order: AX element_token, background pixel, foreground, checking state between rungs; a click has no read-back except list-row selection. |
-| <span id="click--macos--from_zoom"></span>`from_zoom` | `boolean` | | x and y are in the last zoom image for this pid. |
-| <span id="click--macos--modifier"></span>`modifier` | `string[]` | | Modifier keys: cmd, shift, option/alt, ctrl. |
-| <span id="click--macos--pid"></span>`pid` | `integer` | | Target process ID. Optional with element_token (it carries the pid). |
-| <span id="click--macos--scope"></span>`scope` | `"window" \| "desktop"` | | Default "window". "desktop": x,y with no pid/window_id are true screen pixels from get_desktop_state. |
-| <span id="click--macos--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. |
-| <span id="click--macos--window_id"></span>`window_id` | `integer` | | Target window ID. Omit with element_token. |
-| <span id="click--macos--x"></span>`x` | `number` | | X in screenshot pixels (get_window_state PNG, or get_desktop_state PNG for a desktop target). |
-| <span id="click--macos--y"></span>`y` | `number` | | Y in screenshot pixels from the image selected by target. |
-
-</Tab>
-<Tab value="Linux">
-
-Click against a target pid. **Prefer `element_token` over pixel coordinates**: element_token works on backgrounded / hidden windows, surfaces a stable handle, and tells you what you're clicking via the cached AT-SPI element's role + label. Reach for `x, y` only when the target is a canvas / custom-drawn surface that doesn't appear in the AT-SPI tree.
-
-Provide either (window_id + x/y) or (pid + element_token). x/y are WINDOW-LOCAL pixels of window_id (the get_window_state screenshot frame); a point outside the window is refused (point_outside_window) and every pixel result reports the resolved window_point / screen_point. Background delivery first resolves the accessible under the point and fires its action (the result says `hit: <role> "<name>" action=...`; a file / list item is selected through its container: `selected: ...`), else presses the real virtual pointer there. A click that opens a popup menu names it (`popup: {window_id, bounds}`): pass that window_id to get_window_state to index its items. The token is stale once the next get_window_state of the same window replaces its snapshot: re-snapshot every turn before clicking.
-
-After a zoom call, pass from_zoom=true to auto-translate zoom-image coords back to full-window space.
-
-`count`: 1 (default), 2 for a double-click, 3 for a triple-click (selects a line / paragraph in editors); one press train with real double-click cadence, in background and foreground alike; there is no separate triple_click tool.
-
-button: "left" (default), "right", or "middle". Defaults to left so the field is fully back-compat. X11: routes through XSendEvent ButtonPress/Release with the matching button code. Native Wayland: only left-button is supported via the virtual-pointer protocol; right/middle return an error rather than silently degrading to left. `modifier` holds ctrl/shift/alt/super for the click on X11. Native Wayland refuses modified pointer clicks until its input protocol can carry keyboard modifier state.
-
-**Linux parameters**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="click--linux--button"></span>`button` | `"left" \| "right" \| "middle"` | | Mouse button. Default: "left" (legacy back-compat). X11: routed via ButtonPress/Release with the matching evdev code. Native Wayland: only left-button is supported via the virtual-pointer protocol; right/middle return an error. |
-| <span id="click--linux--capture_id"></span>`capture_id` | `string` | | Optional one-shot binding to the exact PNG returned by get_window_state or get_desktop_state. When present, x/y are interpreted in that capture and admitted before native dispatch. |
-| <span id="click--linux--coordinate_frame"></span>`coordinate_frame` | `"window" \| "desktop"` | | Frame of x/y (and from_x/from_y/to_x/to_y). Default "window": window-local screenshot pixels as returned by get_window_state. "desktop": full-screen pixels as returned by get_desktop_state, translated to the target window. Passing scope:"desktop" together with pid/window_id means the same thing. |
-| <span id="click--linux--count"></span>`count` | `integer` | | Number of clicks in one press train: 1 (default), 2 = double-click, 3 = triple-click (line/paragraph selection). There is no separate triple_click tool: pass count: 3 here. Minimum: 1. |
-| <span id="click--linux--cursor_id"></span>`cursor_id` | `string` | | Optional multi-cursor instance id. Default: 'default'. |
-| <span id="click--linux--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | `"background"` | Input delivery mode. 'background' (default) never activates or raises the target window. On X11 it injects via XTEST / the XInput2 master pointer (no focus steal). On Wayland it goes through libei + xdg-desktop-portal, which injects to the compositor's input focus: Wayland's security model has no per-window background targeting, so a specific non-focused window cannot be aimed at; when no libei backend is available the tool returns a structured background_unavailable error. 'foreground' is the explicit escalation: activate the target (X11 _NET_ACTIVE_WINDOW; Wayland compositor activate), inject, then restore the prior active window; a brief focus swap unless the target was already active. Matches the macOS / Windows delivery_mode surface. |
-| <span id="click--linux--from_zoom"></span>`from_zoom` | `boolean` | | Set true after a zoom call to auto-translate zoom-image pixel coordinates back to full-window space. |
-| <span id="click--linux--modifier"></span>`modifier` | `string[]` | | Modifier keys held during the action: cmd, shift, option/alt, ctrl. |
-| <span id="click--linux--pid"></span>`pid` | `integer` | | Target process ID. Required unless scope is "desktop" or element_token is supplied (the token carries the pid). |
-| <span id="click--linux--scope"></span>`scope` | `"window" \| "desktop"` | `"window"` | Coordinate frame (default "window"). Pass "desktop" with x,y and no pid/window_id for a screen-absolute click in get_desktop_state coordinates. |
-| <span id="click--linux--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
-| <span id="click--linux--window_id"></span>`window_id` | `integer` | | Window id from list_windows. Required with x/y or element_index; optional with element_token (the token carries it). |
-| <span id="click--linux--x"></span>`x` | `number` | | Window-local pixel X of the target window's own get_window_state screenshot (0..screenshot_width). For get_desktop_state pixels pass scope:"desktop" (or coordinate_frame:"desktop"). |
-| <span id="click--linux--y"></span>`y` | `number` | | Window-local pixel Y of the target window's own get_window_state screenshot (0..screenshot_height); see x. |
-
-</Tab>
-<Tab value="Windows">
-
-Left-click against a target pid. **Prefer `element_token` over pixel coordinates**: element_token works on backgrounded / minimized / hidden / off-desktop windows, surfaces a stable handle that survives rebuilds, and tells you what you're clicking via the cached element's role + label. Reach for `x, y` only when the target is a canvas / video / WebGL / custom-drawn surface that doesn't appear in the UIA tree.
-
-Two addressing modes:
-
-- `element_token` (from the last `get_window_state` snapshot of that window): performs the UIA Invoke pattern on the cached element via PostMessage. No cursor move, no focus steal. Requires a prior `get_window_state(pid, window_id)` in this turn; the token is stale once the next snapshot of the same window replaces it.
-
-- `x`, `y` (window-local screenshot pixels, top-left origin of the PNG returned by `get_window_state`). On `delivery_mode:"background"` (the default), cua-driver FIRST does a UIA hit-test at the resolved screen position: if the deepest invokable element under that point exposes `InvokePattern`, it's invoked through the accessibility channel; same background-safe path as the `element_token` mode, no foreground swap, no visible flash. **This makes pixel clicks on UWP / WinUI3 / Win11 packaged apps work flash-free out of the box**: agents should default to `delivery_mode:"background"` even on XAML hosts whose CoreInput dispatcher drops raw PostMessage. The PostMessage(WM_LBUTTONDOWN/UP) fallback only runs when the UIA hit-test misses (canvas / video / WebGL / custom-drawn surfaces with no UIA peer), and on those targets `delivery_mode:"background"` returns a structured `background_unavailable` error if PostMessage is known to drop too: at which point you switch to `delivery_mode:"foreground"`. **Always try the default `background` click first and let that error be your signal: do NOT pass `foreground` preemptively because the target 'looks like' GTK/Chromium/etc. The driver decides when background is impossible; a guessed foreground click needlessly steals the user's focus.** `count: 2` posts two down/up pairs for a double-click. Pixel clicks need a visible on-screen window to anchor the coordinate conversion (errors with `pid X has no on-screen window` otherwise).
-
-Exactly one of `element_token` or (`x` AND `y`) must be provided. `pid` is required for window scope and omitted for desktop scope. After a `zoom` call, pass `from_zoom=true` to auto-translate zoom-image coords back to full-window space.
-
-Windows-only convenience: `button: "left"|"right"|"middle"` switches the mouse button (Swift exposes right-click as a separate `right_click` tool). `action: "expand"` on an `element_token` opens the element through UIA ExpandCollapsePattern (the dropdown half of an MSAA split button); other actions use the default invoke. `debug_image_out` isn't supported yet.
-
-**Windows parameters**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="click--windows--action"></span>`action` | `string` | | Accessibility action for an element_token target. "expand" opens the element through UIA ExpandCollapsePattern, or clicks the dropdown half of an MSAA split button. Omit for the default invoke. |
-| <span id="click--windows--button"></span>`button` | `"left" \| "right" \| "middle"` | | Mouse button. Default "left". |
-| <span id="click--windows--capture_id"></span>`capture_id` | `string` | | Optional ID from get_window_state or get_desktop_state. When present, x and y are admitted against that exact capture and the ID is consumed before native dispatch. |
-| <span id="click--windows--count"></span>`count` | `integer` | | Click count: 1 (single), 2 (double), 3 (triple). Default 1. Range: 1 to 3. |
-| <span id="click--windows--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | | Input delivery mode. 'background' (default) never swaps foreground: it routes through UIA Invoke / PostMessage and the window is never raised. For targets whose input stack silently drops posted events (Chromium/Electron content, GTK buttons, VCL/LibreOffice accelerators) the tool returns a structured background_unavailable error rather than fronting. 'foreground' is the explicit escalation: a brief SetForegroundWindow swap + SendInput, restoring the prior foreground afterward. IMPORTANT: 'background' is not a hint to weigh; it is the mandatory first attempt. Do NOT pass 'foreground' preemptively because a target 'looks like' GTK/Chromium/Electron; the DRIVER decides when background is impossible and tells you so via a background_unavailable error (or a verified no-op). Only THEN re-issue the same action with 'foreground'. The lists above are the driver's detectors, not a checklist for you to front on a guess: fronting up-front needlessly steals the user's focus and is a bug, not a shortcut. Matches the macOS delivery_mode surface. |
-| <span id="click--windows--from_zoom"></span>`from_zoom` | `boolean` | | When true, x and y are pixel coordinates in the last `zoom` image for this pid. The driver maps them back to window coords. |
-| <span id="click--windows--modifier"></span>`modifier` | `string[]` | | Modifier keys held during the action: cmd, shift, option/alt, ctrl. |
-| <span id="click--windows--pid"></span>`pid` | `integer` | | Target process ID for window scope. Optional with element_token (the token carries the pid). Omit with scope=desktop for screen-absolute coordinates from get_desktop_state. |
-| <span id="click--windows--scope"></span>`scope` | `"window" \| "desktop"` | `"window"` | Coordinate frame (default "window"). Pass "desktop" with x,y and no pid/window_id for a screen-absolute click in get_desktop_state coordinates. |
-| <span id="click--windows--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
-| <span id="click--windows--window_id"></span>`window_id` | `integer` | | HWND of the target window. Omit when element_token is supplied (the token carries it). |
-| <span id="click--windows--x"></span>`x` | `number` | | X in window-local screenshot pixels: same space as the PNG get_window_state returns. Must be provided together with y. |
-| <span id="click--windows--y"></span>`y` | `number` | | Y in window-local screenshot pixels. Must be provided together with x. |
-
-</Tab>
-</Tabs>
-
-**Parameters on every platform**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="click--element_token"></span>`element_token` | `string` | | Element handle `<snapshot_id>:<row>` from get_window_state: row `[11]` of a read whose snapshot_id is s0000002a is "s0000002a:11" (also in `structuredContent.elements[].element_token`). Returns an explicit stale error naming the current snapshots once a newer read supersedes it. |
-| <span id="click--target"></span>`target` | `object` | | Exact window (kind "window", with pid and window_id) or desktop (kind "desktop", with display_id). "primary" is the portable desktop target. |
-| <span id="click--target-display_id"></span>`target.display_id` | `string` | | Display id. Required when kind is desktop; use "primary". |
-| <span id="click--target-kind"></span>`target.kind` | `"window" \| "desktop"` | | window requires pid and window_id; desktop requires display_id. |
-| <span id="click--target-pid"></span>`target.pid` | `integer` | | Process id. Required when kind is window. Minimum: 0. |
-| <span id="click--target-window_id"></span>`target.window_id` | `integer` | | Window id from list_windows. Required when kind is window. Minimum: 0. |
diff --git a/docs/content/docs/cua-driver/reference/mcp-tools/double-and-right-click.mdx b/docs/content/docs/cua-driver/reference/mcp-tools/double-and-right-click.mdx
deleted file mode 100644
index f92bfa9bed..0000000000
--- a/docs/content/docs/cua-driver/reference/mcp-tools/double-and-right-click.mdx
+++ /dev/null
@@ -1,168 +0,0 @@
----
-title: "Double-click and right-click tools"
-description: "Double-click and right-click by element or pixel."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-driver
- Source: cua-driver dump-docs --type mcp (macOS, Linux and Windows registries)
- Version: 0.36.0
-*/}
-
-import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
-
-| Tool | Description | Platforms |
-| --- | --- | --- |
-| [`double_click`](#double_click) | Double-click at (x, y) or on an AX element identified by element_token. | macOS, Linux, Windows |
-| [`right_click`](#right_click) | Right-click against a target pid. | macOS, Linux, Windows |
-
-Served by `cua-driver mcp`; see [MCP tools](/cua-driver/reference/mcp-tools) for every tool.
-
-## `double_click`
-
-Effect: destructive. Platforms: macOS, Linux, Windows.
-
-<Tabs items={['macOS', 'Linux', 'Windows']} groupId="platform" persist>
-<Tab value="macOS">
-
-Double-click at (x, y) or on an AX element identified by element_token.
-
-AX path (element_token provided): performs `AXOpen` when the element advertises it (Finder items, openable list rows/cells); otherwise resolves the element's on-screen center and falls back to a pixel double-click there.
-
-Pixel path (x, y provided): two down/up pairs ~80 ms apart at the given coordinates.
-
-**macOS parameters**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="double_click--macos--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | | Best-effort-background ladder rung (default "background"). "background": inject without fronting or raising the target; no focus steal. "foreground": briefly front the target, act, then restore the prior frontmost; the explicit last resort when a background attempt didn't land. Re-call with "foreground" only for the action that needs it. |
-| <span id="double_click--macos--window_id"></span>`window_id` | `integer` | | CGWindowID. Omit when element_token is supplied (the token carries it). |
-| <span id="double_click--macos--x"></span>`x` | `number` | | Screen X coordinate (pixel path). |
-| <span id="double_click--macos--y"></span>`y` | `number` | | Screen Y coordinate (pixel path). |
-
-</Tab>
-<Tab value="Linux">
-
-Double-click at (x,y) or an element_token (AT-SPI bounds). Background delivery on X11 sends real button events from the session's virtual master pointer (path mpx_pointer); a point covered by another application's window is refused (target_occluded), one covered by this app's own dialog is retargeted to it (retargeted_to). No focus steal. Provide either (window_id + x/y) or (pid + element_token). After a zoom call, pass from_zoom=true to auto-translate zoom-image coords.
-
-**Linux parameters**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="double_click--linux--coordinate_frame"></span>`coordinate_frame` | `"window" \| "desktop"` | | Frame of x/y (and from_x/from_y/to_x/to_y). Default "window": window-local screenshot pixels as returned by get_window_state. "desktop": full-screen pixels as returned by get_desktop_state, translated to the target window. Passing scope:"desktop" together with pid/window_id means the same thing. |
-| <span id="double_click--linux--cursor_id"></span>`cursor_id` | `string` | | Optional multi-cursor instance id. Default: 'default'. |
-| <span id="double_click--linux--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | `"background"` | Input delivery mode. 'background' (default) never activates or raises the target window. On X11 it injects via XTEST / the XInput2 master pointer (no focus steal). On Wayland it goes through libei + xdg-desktop-portal, which injects to the compositor's input focus: Wayland's security model has no per-window background targeting, so a specific non-focused window cannot be aimed at; when no libei backend is available the tool returns a structured background_unavailable error. 'foreground' is the explicit escalation: activate the target (X11 _NET_ACTIVE_WINDOW; Wayland compositor activate), inject, then restore the prior active window; a brief focus swap unless the target was already active. Matches the macOS / Windows delivery_mode surface. |
-| <span id="double_click--linux--from_zoom"></span>`from_zoom` | `boolean` | | Set true after a zoom call to auto-translate zoom-image pixel coordinates back to full-window space. |
-| <span id="double_click--linux--window_id"></span>`window_id` | `integer` | | Window id from list_windows. Required with x/y or element_index; optional with element_token (the token carries it). |
-| <span id="double_click--linux--x"></span>`x` | `number` | | Window-local pixel X of the target window's own get_window_state screenshot (0..screenshot_width). For get_desktop_state pixels pass scope:"desktop" (or coordinate_frame:"desktop"). |
-| <span id="double_click--linux--y"></span>`y` | `number` | | Window-local pixel Y of the target window's own get_window_state screenshot (0..screenshot_height); see x. |
-
-</Tab>
-<Tab value="Windows">
-
-Double-click against a target pid. Two addressing modes:
-
-- `element_token` (from the last `get_window_state` snapshot of that window): synthesizes a stamped pixel double-click at the element's cached on-screen center via PostMessage. (Windows has no AXOpen analogue; Swift's AXOpen-first path falls through to the same pixel recipe when the element doesn't advertise AXOpen, so the user-visible behavior matches.)
-
-- `x`, `y` (window-local screenshot pixels, top-left origin of the PNG returned by `get_window_state`): posts two WM_LBUTTONDOWN/UP pairs in quick succession to the deepest child window at that point.
-
-Exactly one of `element_token` or (`x` AND `y`) must be provided. `pid` is required with `x`, `y`; an `element_token` carries its own pid. The macOS-only `modifier` field is accepted for parity (no-op on Windows: PostMessage doesn't propagate modifier-key state).
-
-**Windows parameters**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="double_click--windows--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | | Input delivery mode. 'background' (default) never swaps foreground: it routes through UIA Invoke / PostMessage and the window is never raised. For targets whose input stack silently drops posted events (Chromium/Electron content, GTK buttons, VCL/LibreOffice accelerators) the tool returns a structured background_unavailable error rather than fronting. 'foreground' is the explicit escalation: a brief SetForegroundWindow swap + SendInput, restoring the prior foreground afterward. IMPORTANT: 'background' is not a hint to weigh; it is the mandatory first attempt. Do NOT pass 'foreground' preemptively because a target 'looks like' GTK/Chromium/Electron; the DRIVER decides when background is impossible and tells you so via a background_unavailable error (or a verified no-op). Only THEN re-issue the same action with 'foreground'. The lists above are the driver's detectors, not a checklist for you to front on a guess: fronting up-front needlessly steals the user's focus and is a bug, not a shortcut. Matches the macOS delivery_mode surface. |
-| <span id="double_click--windows--from_zoom"></span>`from_zoom` | `boolean` | | After a zoom call, pass true to translate zoom-image coords back to window space. |
-| <span id="double_click--windows--modifier"></span>`modifier` | `string[]` | | Modifier keys held during the action: cmd, shift, option/alt, ctrl. |
-| <span id="double_click--windows--window_id"></span>`window_id` | `integer` | | HWND for the target window. Omit when element_token is supplied (the token carries it). |
-| <span id="double_click--windows--x"></span>`x` | `number` | | X in window-local screenshot pixels. Must be provided together with y. |
-| <span id="double_click--windows--y"></span>`y` | `number` | | Y in window-local screenshot pixels. Must be provided together with x. |
-
-</Tab>
-</Tabs>
-
-**Parameters on every platform**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="double_click--element_token"></span>`element_token` | `string` | | Element handle `<snapshot_id>:<row>` from get_window_state: row `[11]` of a read whose snapshot_id is s0000002a is "s0000002a:11" (also in `structuredContent.elements[].element_token`). Returns an explicit stale error naming the current snapshots once a newer read supersedes it. |
-| <span id="double_click--pid"></span>`pid` | `integer` | | Target process ID. Optional with element_token (the token carries the pid). |
-| <span id="double_click--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
-
-## `right_click`
-
-Effect: destructive. Platforms: macOS, Linux, Windows.
-
-<Tabs items={['macOS', 'Linux', 'Windows']} groupId="platform" persist>
-<Tab value="macOS">
-
-Right-click against a target pid. Two addressing modes:
-
-- `element_token` (from the last `get_window_state` snapshot): performs `AXShowMenu` on the cached element. Pure AX RPC, works on backgrounded / hidden windows, no cursor move or focus steal. Requires a prior `get_window_state(pid, window_id)` in this turn.
-
-- `x`, `y`: synthesizes `rightMouseDown` / `rightMouseUp` CGEvent pair posted to the pid. Driver converts image-pixel → screen-point internally. `modifier` forces the CGEvent path (AX actions don't propagate modifier keys).
-
-Exactly one of `element_token` or (`x` AND `y`) must be provided. `pid` is required with `x`, `y`; an `element_token` carries its own pid.
-
-**macOS parameters**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="right_click--macos--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | | Best-effort-background ladder rung (default "background"). "background": inject without fronting or raising the target; no focus steal. "foreground": briefly front the target, act, then restore the prior frontmost; the explicit last resort when a background attempt didn't land. Re-call with "foreground" only for the action that needs it. |
-| <span id="right_click--macos--modifier"></span>`modifier` | `string[]` | | Modifier keys held during the right-click: cmd/shift/option/ctrl. Pixel path only. |
-| <span id="right_click--macos--window_id"></span>`window_id` | `integer` | | CGWindowID. Omit when element_token is supplied (the token carries it). |
-| <span id="right_click--macos--x"></span>`x` | `number` | | X in window-local screenshot pixels. Must be provided together with y. |
-| <span id="right_click--macos--y"></span>`y` | `number` | | Y in window-local screenshot pixels. Must be provided together with x. |
-
-</Tab>
-<Tab value="Linux">
-
-Right-click at (x,y) or an element_token (AT-SPI bounds). Background delivery on X11 sends real button events from the session's virtual master pointer (path mpx_pointer); a point covered by another application's window is refused (target_occluded), one covered by this app's own dialog is retargeted to it (retargeted_to), one outside the window is refused (point_outside_window; x/y are window-local pixels, the result reports window_point / screen_point). No focus steal. When a context menu opens, the result names it (`popup: {window_id, bounds, title}`): call get_window_state(pid, window_id=&lt;that id&gt;) to index its menu items and click them by element_token. Provide either (window_id + x/y) or (pid + element_token). After a zoom call, pass from_zoom=true to auto-translate zoom-image coords.
-
-**Linux parameters**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="right_click--linux--coordinate_frame"></span>`coordinate_frame` | `"window" \| "desktop"` | | Frame of x/y (and from_x/from_y/to_x/to_y). Default "window": window-local screenshot pixels as returned by get_window_state. "desktop": full-screen pixels as returned by get_desktop_state, translated to the target window. Passing scope:"desktop" together with pid/window_id means the same thing. |
-| <span id="right_click--linux--cursor_id"></span>`cursor_id` | `string` | | Optional multi-cursor instance id. Default: 'default'. |
-| <span id="right_click--linux--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | `"background"` | Input delivery mode. 'background' (default) never activates or raises the target window. On X11 it injects via XTEST / the XInput2 master pointer (no focus steal). On Wayland it goes through libei + xdg-desktop-portal, which injects to the compositor's input focus: Wayland's security model has no per-window background targeting, so a specific non-focused window cannot be aimed at; when no libei backend is available the tool returns a structured background_unavailable error. 'foreground' is the explicit escalation: activate the target (X11 _NET_ACTIVE_WINDOW; Wayland compositor activate), inject, then restore the prior active window; a brief focus swap unless the target was already active. Matches the macOS / Windows delivery_mode surface. |
-| <span id="right_click--linux--from_zoom"></span>`from_zoom` | `boolean` | | Set true after a zoom call to auto-translate zoom-image pixel coordinates back to full-window space. |
-| <span id="right_click--linux--modifier"></span>`modifier` | `string[]` | | Modifier keys held during the action: cmd, shift, option/alt, ctrl. |
-| <span id="right_click--linux--window_id"></span>`window_id` | `integer` | | Window id from list_windows. Required with x/y or element_index; optional with element_token (the token carries it). |
-| <span id="right_click--linux--x"></span>`x` | `number` | | Window-local pixel X of the target window's own get_window_state screenshot (0..screenshot_width). For get_desktop_state pixels pass scope:"desktop" (or coordinate_frame:"desktop"). |
-| <span id="right_click--linux--y"></span>`y` | `number` | | Window-local pixel Y of the target window's own get_window_state screenshot (0..screenshot_height); see x. |
-
-</Tab>
-<Tab value="Windows">
-
-Right-click against a target pid. Two addressing modes:
-
-- `element_token` (from the last `get_window_state` snapshot of that window): posts WM_RBUTTONDOWN/UP at the element's cached on-screen center via PostMessage. (Windows has no AXShowMenu analogue wired up yet; Swift's AX-action path falls through to the same pixel recipe on non-advertising elements, so user-visible behavior matches.)
-
-- `x`, `y` (window-local screenshot pixels, top-left origin of the PNG returned by `get_window_state`): posts WM_RBUTTONDOWN/UP to the deepest child window at that point.
-
-Exactly one of `element_token` or (`x` AND `y`) must be provided. `pid` is required with `x`, `y`; an `element_token` carries its own pid. `modifier` is accepted for parity (no-op on Windows: PostMessage doesn't propagate modifier-key state).
-
-**Windows parameters**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="right_click--windows--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | | Input delivery mode. 'background' (default) never swaps foreground: it routes through UIA Invoke / PostMessage and the window is never raised. For targets whose input stack silently drops posted events (Chromium/Electron content, GTK buttons, VCL/LibreOffice accelerators) the tool returns a structured background_unavailable error rather than fronting. 'foreground' is the explicit escalation: a brief SetForegroundWindow swap + SendInput, restoring the prior foreground afterward. IMPORTANT: 'background' is not a hint to weigh; it is the mandatory first attempt. Do NOT pass 'foreground' preemptively because a target 'looks like' GTK/Chromium/Electron; the DRIVER decides when background is impossible and tells you so via a background_unavailable error (or a verified no-op). Only THEN re-issue the same action with 'foreground'. The lists above are the driver's detectors, not a checklist for you to front on a guess: fronting up-front needlessly steals the user's focus and is a bug, not a shortcut. Matches the macOS delivery_mode surface. |
-| <span id="right_click--windows--from_zoom"></span>`from_zoom` | `boolean` | | After a zoom call, pass true to translate zoom-image coords back to window space. |
-| <span id="right_click--windows--modifier"></span>`modifier` | `string[]` | | Modifier keys held during the action: cmd, shift, option/alt, ctrl. |
-| <span id="right_click--windows--window_id"></span>`window_id` | `integer` | | HWND for the target window. Omit when element_token is supplied (the token carries it). |
-| <span id="right_click--windows--x"></span>`x` | `number` | | X in window-local screenshot pixels. Must be provided together with y. |
-| <span id="right_click--windows--y"></span>`y` | `number` | | Y in window-local screenshot pixels. Must be provided together with x. |
-
-</Tab>
-</Tabs>
-
-**Parameters on every platform**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="right_click--element_token"></span>`element_token` | `string` | | Element handle `<snapshot_id>:<row>` from get_window_state: row `[11]` of a read whose snapshot_id is s0000002a is "s0000002a:11" (also in `structuredContent.elements[].element_token`). Returns an explicit stale error naming the current snapshots once a newer read supersedes it. |
-| <span id="right_click--pid"></span>`pid` | `integer` | | Target process ID. Optional with element_token (the token carries the pid). |
-| <span id="right_click--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
diff --git a/docs/content/docs/cua-driver/reference/mcp-tools/index.mdx b/docs/content/docs/cua-driver/reference/mcp-tools/index.mdx
index 5665cfc345..688bc965c1 100644
--- a/docs/content/docs/cua-driver/reference/mcp-tools/index.mdx
+++ b/docs/content/docs/cua-driver/reference/mcp-tools/index.mdx
@@ -50,179 +50,179 @@ A window action may omit `window_id` only when its `pid` owns exactly one eligib
## App and window tools
-List, launch, quit, front and arrange apps and windows. [Reference](/cua-driver/reference/mcp-tools/apps-and-windows).
+List, launch, quit, front and arrange apps and windows. [Reference](/cua-driver/reference/mcp-tools/apps-windows-and-screen#app-and-window-tools).
| Tool | Description | Platforms |
| --- | --- | --- |
-| <span id="list_apps"></span>[`list_apps`](/cua-driver/reference/mcp-tools/apps-and-windows#list_apps) | List macOS apps, both currently running and installed-but-not-running, with per-app state flags: - running: is a process for this app live? | macOS, Linux, Windows |
-| <span id="list_windows"></span>[`list_windows`](/cua-driver/reference/mcp-tools/apps-and-windows#list_windows) | List top-level windows known to WindowServer, including off-screen ones (minimized, other Space, hidden): layer-0 only without `pid`, every layer with `pid`. | macOS, Linux, Windows |
-| <span id="launch_app"></span>[`launch_app`](/cua-driver/reference/mcp-tools/apps-and-windows#launch_app) | Launch a macOS app in the background: the target does NOT come to the foreground. | macOS, Linux, Windows |
-| <span id="kill_app"></span>[`kill_app`](/cua-driver/reference/mcp-tools/apps-and-windows#kill_app) | Force-terminate a process by pid (kill -9 equivalent on macOS / Linux; taskkill /F equivalent on Windows). | macOS, Linux, Windows |
-| <span id="bring_to_front"></span>[`bring_to_front`](/cua-driver/reference/mcp-tools/apps-and-windows#bring_to_front) | Persistently activate an app and leave it in the foreground. | macOS, Linux, Windows |
-| <span id="set_window_frame"></span>[`set_window_frame`](/cua-driver/reference/mcp-tools/apps-and-windows#set_window_frame) | Set one exact top-level window's frame in the desktop-coordinate space reported by list_windows and verify the resulting geometry through an independent readback. | macOS, Linux, Windows |
-| <span id="invoke_menu"></span>[`invoke_menu`](/cua-driver/reference/mcp-tools/apps-and-windows#invoke_menu) | Resolve an exact application-menu path one live native level at a time and invoke its final item through accessibility APIs. | macOS, Linux, Windows |
-| <span id="debug_window_info"></span>[`debug_window_info`](/cua-driver/reference/mcp-tools/apps-and-windows#debug_window_info) | Diagnostic: dump everything cua-driver sees about a pid's top-level windows from the daemon's session perspective. | Windows |
+| <span id="list_apps"></span>[`list_apps`](/cua-driver/reference/mcp-tools/apps-windows-and-screen#list_apps) | List macOS apps, both currently running and installed-but-not-running, with per-app state flags: - running: is a process for this app live? | macOS, Linux, Windows |
+| <span id="list_windows"></span>[`list_windows`](/cua-driver/reference/mcp-tools/apps-windows-and-screen#list_windows) | List top-level windows known to WindowServer, including off-screen ones (minimized, other Space, hidden): layer-0 only without `pid`, every layer with `pid`. | macOS, Linux, Windows |
+| <span id="launch_app"></span>[`launch_app`](/cua-driver/reference/mcp-tools/apps-windows-and-screen#launch_app) | Launch a macOS app in the background: the target does NOT come to the foreground. | macOS, Linux, Windows |
+| <span id="kill_app"></span>[`kill_app`](/cua-driver/reference/mcp-tools/apps-windows-and-screen#kill_app) | Force-terminate a process by pid (kill -9 equivalent on macOS / Linux; taskkill /F equivalent on Windows). | macOS, Linux, Windows |
+| <span id="bring_to_front"></span>[`bring_to_front`](/cua-driver/reference/mcp-tools/apps-windows-and-screen#bring_to_front) | Persistently activate an app and leave it in the foreground. | macOS, Linux, Windows |
+| <span id="set_window_frame"></span>[`set_window_frame`](/cua-driver/reference/mcp-tools/apps-windows-and-screen#set_window_frame) | Set one exact top-level window's frame in the desktop-coordinate space reported by list_windows and verify the resulting geometry through an independent readback. | macOS, Linux, Windows |
+| <span id="invoke_menu"></span>[`invoke_menu`](/cua-driver/reference/mcp-tools/apps-windows-and-screen#invoke_menu) | Resolve an exact application-menu path one live native level at a time and invoke its final item through accessibility APIs. | macOS, Linux, Windows |
+| <span id="debug_window_info"></span>[`debug_window_info`](/cua-driver/reference/mcp-tools/apps-windows-and-screen#debug_window_info) | Diagnostic: dump everything cua-driver sees about a pid's top-level windows from the daemon's session perspective. | Windows |
## Window state tools
-Screenshots, accessibility trees, verification and visual regions of a window. [Reference](/cua-driver/reference/mcp-tools/window-state).
+Screenshots, accessibility trees, verification and visual regions of a window. [Reference](/cua-driver/reference/mcp-tools/apps-windows-and-screen#window-state-tools).
| Tool | Description | Platforms |
| --- | --- | --- |
-| <span id="get_window_state"></span>[`get_window_state`](/cua-driver/reference/mcp-tools/window-state#get_window_state) | Snapshot a window: the accessibility tree plus a screenshot. | macOS, Linux, Windows |
-| <span id="get_accessibility_tree"></span>[`get_accessibility_tree`](/cua-driver/reference/mcp-tools/window-state#get_accessibility_tree) | Return a lightweight snapshot of the desktop: running regular apps and on-screen visible windows with their bounds, z-order, and owner pid. | macOS, Linux, Windows |
-| <span id="verify_state"></span>[`verify_state`](/cua-driver/reference/mcp-tools/window-state#verify_state) | Deterministically verify bounded predicates against one exact window. | macOS, Linux, Windows |
-| <span id="parse_visual_regions"></span>[`parse_visual_regions`](/cua-driver/reference/mcp-tools/window-state#parse_visual_regions) | Parse one immutable registered capture into model-neutral text and icon regions. | macOS, Linux, Windows |
+| <span id="get_window_state"></span>[`get_window_state`](/cua-driver/reference/mcp-tools/apps-windows-and-screen#get_window_state) | Snapshot a window: the accessibility tree plus a screenshot. | macOS, Linux, Windows |
+| <span id="get_accessibility_tree"></span>[`get_accessibility_tree`](/cua-driver/reference/mcp-tools/apps-windows-and-screen#get_accessibility_tree) | Return a lightweight snapshot of the desktop: running regular apps and on-screen visible windows with their bounds, z-order, and owner pid. | macOS, Linux, Windows |
+| <span id="verify_state"></span>[`verify_state`](/cua-driver/reference/mcp-tools/apps-windows-and-screen#verify_state) | Deterministically verify bounded predicates against one exact window. | macOS, Linux, Windows |
+| <span id="parse_visual_regions"></span>[`parse_visual_regions`](/cua-driver/reference/mcp-tools/apps-windows-and-screen#parse_visual_regions) | Parse one immutable registered capture into model-neutral text and icon regions. | macOS, Linux, Windows |
## Screen tools
-The desktop, screen size, cursor position and zoomed crops. [Reference](/cua-driver/reference/mcp-tools/screen).
+The desktop, screen size, cursor position and zoomed crops. [Reference](/cua-driver/reference/mcp-tools/apps-windows-and-screen#screen-tools).
| Tool | Description | Platforms |
| --- | --- | --- |
-| <span id="get_desktop_state"></span>[`get_desktop_state`](/cua-driver/reference/mcp-tools/screen#get_desktop_state) | Capture the full display. | macOS, Linux, Windows |
-| <span id="get_screen_size"></span>[`get_screen_size`](/cua-driver/reference/mcp-tools/screen#get_screen_size) | Return the logical size of the main display in points plus its backing scale factor. | macOS, Linux, Windows |
-| <span id="get_cursor_position"></span>[`get_cursor_position`](/cua-driver/reference/mcp-tools/screen#get_cursor_position) | Return the current mouse cursor position in screen points (origin top-left). | macOS, Linux, Windows |
-| <span id="zoom"></span>[`zoom`](/cua-driver/reference/mcp-tools/screen#zoom) | Capture a cropped JPEG of a window region (x1,y1)–(x2,y2) in screenshot pixel coordinates, with 20% padding added on each side. | macOS, Linux, Windows |
+| <span id="get_desktop_state"></span>[`get_desktop_state`](/cua-driver/reference/mcp-tools/apps-windows-and-screen#get_desktop_state) | Capture the full display. | macOS, Linux, Windows |
+| <span id="get_screen_size"></span>[`get_screen_size`](/cua-driver/reference/mcp-tools/apps-windows-and-screen#get_screen_size) | Return the logical size of the main display in points plus its backing scale factor. | macOS, Linux, Windows |
+| <span id="get_cursor_position"></span>[`get_cursor_position`](/cua-driver/reference/mcp-tools/apps-windows-and-screen#get_cursor_position) | Return the current mouse cursor position in screen points (origin top-left). | macOS, Linux, Windows |
+| <span id="zoom"></span>[`zoom`](/cua-driver/reference/mcp-tools/apps-windows-and-screen#zoom) | Capture a cropped JPEG of a window region (x1,y1)–(x2,y2) in screenshot pixel coordinates, with 20% padding added on each side. | macOS, Linux, Windows |
## Click tool
-Click by element or pixel. [Reference](/cua-driver/reference/mcp-tools/click).
+Click by element or pixel. [Reference](/cua-driver/reference/mcp-tools/click-and-type#click-tool).
| Tool | Description | Platforms |
| --- | --- | --- |
-| <span id="click"></span>[`click`](/cua-driver/reference/mcp-tools/click#click) | Click a target pid. | macOS, Linux, Windows |
+| <span id="click"></span>[`click`](/cua-driver/reference/mcp-tools/click-and-type#click) | Click a target pid. | macOS, Linux, Windows |
## Double-click and right-click tools
-Double-click and right-click by element or pixel. [Reference](/cua-driver/reference/mcp-tools/double-and-right-click).
+Double-click and right-click by element or pixel. [Reference](/cua-driver/reference/mcp-tools/click-and-type#double-click-and-right-click-tools).
| Tool | Description | Platforms |
| --- | --- | --- |
-| <span id="double_click"></span>[`double_click`](/cua-driver/reference/mcp-tools/double-and-right-click#double_click) | Double-click at (x, y) or on an AX element identified by element_token. | macOS, Linux, Windows |
-| <span id="right_click"></span>[`right_click`](/cua-driver/reference/mcp-tools/double-and-right-click#right_click) | Right-click against a target pid. | macOS, Linux, Windows |
+| <span id="double_click"></span>[`double_click`](/cua-driver/reference/mcp-tools/click-and-type#double_click) | Double-click at (x, y) or on an AX element identified by element_token. | macOS, Linux, Windows |
+| <span id="right_click"></span>[`right_click`](/cua-driver/reference/mcp-tools/click-and-type#right_click) | Right-click against a target pid. | macOS, Linux, Windows |
## Pointer tools
-Drag, scroll, move the pointer, and press or release buttons. [Reference](/cua-driver/reference/mcp-tools/pointer).
+Drag, scroll, move the pointer, and press or release buttons. [Reference](/cua-driver/reference/mcp-tools/pointer-cursor-and-browser#pointer-tools).
| Tool | Description | Platforms |
| --- | --- | --- |
-| <span id="drag"></span>[`drag`](/cua-driver/reference/mcp-tools/pointer#drag) | Press-drag-release gesture from (from_x, from_y) to (to_x, to_y) in window-local screenshot pixels: the same space get_window_state returns. | macOS, Linux, Windows |
-| <span id="scroll"></span>[`scroll`](/cua-driver/reference/mcp-tools/pointer#scroll) | Scroll the target pid. | macOS, Linux, Windows |
-| <span id="move_cursor"></span>[`move_cursor`](/cua-driver/reference/mcp-tools/pointer#move_cursor) | Move a cursor to (x, y). | macOS, Linux, Windows |
-| <span id="mouse_button_down"></span>[`mouse_button_down`](/cua-driver/reference/mcp-tools/pointer#mouse_button_down) | Press and hold a mouse button at (x,y) via background X11 delivery. | Linux |
-| <span id="mouse_button_up"></span>[`mouse_button_up`](/cua-driver/reference/mcp-tools/pointer#mouse_button_up) | Release a previously-held mouse button via background X11 delivery. | Linux |
-| <span id="mouse_drag"></span>[`mouse_drag`](/cua-driver/reference/mcp-tools/pointer#mouse_drag) | Move a previously-held mouse button to a new point via background X11 delivery. | Linux |
-| <span id="parallel_mouse_drag"></span>[`parallel_mouse_drag`](/cua-driver/reference/mcp-tools/pointer#parallel_mouse_drag) | Run multiple mouse drag gestures concurrently via Linux MPX/XI2 virtual master pointers. | Linux |
+| <span id="drag"></span>[`drag`](/cua-driver/reference/mcp-tools/pointer-cursor-and-browser#drag) | Press-drag-release gesture from (from_x, from_y) to (to_x, to_y) in window-local screenshot pixels: the same space get_window_state returns. | macOS, Linux, Windows |
+| <span id="scroll"></span>[`scroll`](/cua-driver/reference/mcp-tools/pointer-cursor-and-browser#scroll) | Scroll the target pid. | macOS, Linux, Windows |
+| <span id="move_cursor"></span>[`move_cursor`](/cua-driver/reference/mcp-tools/pointer-cursor-and-browser#move_cursor) | Move a cursor to (x, y). | macOS, Linux, Windows |
+| <span id="mouse_button_down"></span>[`mouse_button_down`](/cua-driver/reference/mcp-tools/pointer-cursor-and-browser#mouse_button_down) | Press and hold a mouse button at (x,y) via background X11 delivery. | Linux |
+| <span id="mouse_button_up"></span>[`mouse_button_up`](/cua-driver/reference/mcp-tools/pointer-cursor-and-browser#mouse_button_up) | Release a previously-held mouse button via background X11 delivery. | Linux |
+| <span id="mouse_drag"></span>[`mouse_drag`](/cua-driver/reference/mcp-tools/pointer-cursor-and-browser#mouse_drag) | Move a previously-held mouse button to a new point via background X11 delivery. | Linux |
+| <span id="parallel_mouse_drag"></span>[`parallel_mouse_drag`](/cua-driver/reference/mcp-tools/pointer-cursor-and-browser#parallel_mouse_drag) | Run multiple mouse drag gestures concurrently via Linux MPX/XI2 virtual master pointers. | Linux |
## Typing tools
-Type text into a field or window. [Reference](/cua-driver/reference/mcp-tools/keyboard).
+Type text into a field or window. [Reference](/cua-driver/reference/mcp-tools/click-and-type#typing-tools).
| Tool | Description | Platforms |
| --- | --- | --- |
-| <span id="type_text"></span>[`type_text`](/cua-driver/reference/mcp-tools/keyboard#type_text) | Insert text via `AXSetAttribute(kAXSelectedText)` into the element given by `element_token`, or the pid's focused element. | macOS, Linux, Windows |
+| <span id="type_text"></span>[`type_text`](/cua-driver/reference/mcp-tools/click-and-type#type_text) | Insert text via `AXSetAttribute(kAXSelectedText)` into the element given by `element_token`, or the pid's focused element. | macOS, Linux, Windows |
## Key and shortcut tools
-Press keys and keyboard shortcuts. [Reference](/cua-driver/reference/mcp-tools/keys-and-shortcuts).
+Press keys and keyboard shortcuts. [Reference](/cua-driver/reference/mcp-tools/click-and-type#key-and-shortcut-tools).
| Tool | Description | Platforms |
| --- | --- | --- |
-| <span id="press_key"></span>[`press_key`](/cua-driver/reference/mcp-tools/keys-and-shortcuts#press_key) | Press and release one key. | macOS, Linux, Windows |
-| <span id="hotkey"></span>[`hotkey`](/cua-driver/reference/mcp-tools/keys-and-shortcuts#hotkey) | Press a key combination: e.g. | macOS, Linux, Windows |
+| <span id="press_key"></span>[`press_key`](/cua-driver/reference/mcp-tools/click-and-type#press_key) | Press and release one key. | macOS, Linux, Windows |
+| <span id="hotkey"></span>[`hotkey`](/cua-driver/reference/mcp-tools/click-and-type#hotkey) | Press a key combination: e.g. | macOS, Linux, Windows |
## Value and clipboard tools
-Set element values and read or write the clipboard. [Reference](/cua-driver/reference/mcp-tools/values-and-clipboard).
+Set element values and read or write the clipboard. [Reference](/cua-driver/reference/mcp-tools/click-and-type#value-and-clipboard-tools).
| Tool | Description | Platforms |
| --- | --- | --- |
-| <span id="set_value"></span>[`set_value`](/cua-driver/reference/mcp-tools/values-and-clipboard#set_value) | Set an element's value by `element_token`. | macOS, Linux, Windows |
-| <span id="clipboard_read"></span>[`clipboard_read`](/cua-driver/reference/mcp-tools/values-and-clipboard#clipboard_read) | List available system clipboard types and optionally return privacy-sensitive plain text. | macOS, Linux, Windows |
-| <span id="clipboard_write"></span>[`clipboard_write`](/cua-driver/reference/mcp-tools/values-and-clipboard#clipboard_write) | Replace the system clipboard with exactly one value: plain text, an image from an absolute local path, or a file URL from an absolute local path. | macOS, Linux, Windows |
+| <span id="set_value"></span>[`set_value`](/cua-driver/reference/mcp-tools/click-and-type#set_value) | Set an element's value by `element_token`. | macOS, Linux, Windows |
+| <span id="clipboard_read"></span>[`clipboard_read`](/cua-driver/reference/mcp-tools/click-and-type#clipboard_read) | List available system clipboard types and optionally return privacy-sensitive plain text. | macOS, Linux, Windows |
+| <span id="clipboard_write"></span>[`clipboard_write`](/cua-driver/reference/mcp-tools/click-and-type#clipboard_write) | Replace the system clipboard with exactly one value: plain text, an image from an absolute local path, or a file URL from an absolute local path. | macOS, Linux, Windows |
## Batch and script tools
-Run several action tools, or a script that drives them, in one call. [Reference](/cua-driver/reference/mcp-tools/batch).
+Run several action tools, or a script that drives them, in one call. [Reference](/cua-driver/reference/mcp-tools/batch-recording-and-settings#batch-and-script-tools).
| Tool | Description | Platforms |
| --- | --- | --- |
-| <span id="run_steps"></span>[`run_steps`](/cua-driver/reference/mcp-tools/batch#run_steps) | The default way to act: run one or more action tools in ONE call, in order, stop at the first failure, and (with `observe`) get what changed in the same response. | macOS, Linux, Windows |
-| <span id="run_script"></span>[`run_script`](/cua-driver/reference/mcp-tools/batch#run_script) | Run a JavaScript program that drives apps through Cua Driver, in ONE call: loops, conditions, reads and checks between actions, and only the result comes back. | macOS, Linux, Windows |
+| <span id="run_steps"></span>[`run_steps`](/cua-driver/reference/mcp-tools/batch-recording-and-settings#run_steps) | The default way to act: run one or more action tools in ONE call, in order, stop at the first failure, and (with `observe`) get what changed in the same response. | macOS, Linux, Windows |
+| <span id="run_script"></span>[`run_script`](/cua-driver/reference/mcp-tools/batch-recording-and-settings#run_script) | Run a JavaScript program that drives apps through Cua Driver, in ONE call: loops, conditions, reads and checks between actions, and only the result comes back. | macOS, Linux, Windows |
## Page tools
-Read and act on web pages, and prepare and navigate browsers. [Reference](/cua-driver/reference/mcp-tools/page).
+Read and act on web pages, and prepare and navigate browsers. [Reference](/cua-driver/reference/mcp-tools/pointer-cursor-and-browser#page-tools).
| Tool | Description | Platforms |
| --- | --- | --- |
-| <span id="page"></span>[`page`](/cua-driver/reference/mcp-tools/page#page) | Legacy browser compatibility tool. | macOS, Linux, Windows |
-| <span id="get_browser_state"></span>[`get_browser_state`](/cua-driver/reference/mcp-tools/page#get_browser_state) | Read-only browser inspection. | macOS, Linux, Windows |
-| <span id="browser_prepare"></span>[`browser_prepare`](/cua-driver/reference/mcp-tools/page#browser_prepare) | Attach the browser tools to a browser. | macOS, Linux, Windows |
-| <span id="browser_navigate"></span>[`browser_navigate`](/cua-driver/reference/mcp-tools/page#browser_navigate) | Navigate one tab of an exactly-bound browser target to a new URL (http/https/about only). | macOS, Linux, Windows |
+| <span id="page"></span>[`page`](/cua-driver/reference/mcp-tools/pointer-cursor-and-browser#page) | Legacy browser compatibility tool. | macOS, Linux, Windows |
+| <span id="get_browser_state"></span>[`get_browser_state`](/cua-driver/reference/mcp-tools/pointer-cursor-and-browser#get_browser_state) | Read-only browser inspection. | macOS, Linux, Windows |
+| <span id="browser_prepare"></span>[`browser_prepare`](/cua-driver/reference/mcp-tools/pointer-cursor-and-browser#browser_prepare) | Attach the browser tools to a browser. | macOS, Linux, Windows |
+| <span id="browser_navigate"></span>[`browser_navigate`](/cua-driver/reference/mcp-tools/pointer-cursor-and-browser#browser_navigate) | Navigate one tab of an exactly-bound browser target to a new URL (http/https/about only). | macOS, Linux, Windows |
## Browser input tools
-Exact browser input over CDP: clicks, typing, pointer, dialogs, files and downloads. [Reference](/cua-driver/reference/mcp-tools/browser-input).
+Exact browser input over CDP: clicks, typing, pointer, dialogs, files and downloads. [Reference](/cua-driver/reference/mcp-tools/pointer-cursor-and-browser#browser-input-tools).
| Tool | Description | Platforms |
| --- | --- | --- |
-| <span id="browser_click"></span>[`browser_click`](/cua-driver/reference/mcp-tools/browser-input#browser_click) | Click a page element (by ref) or viewport coordinates in an exactly-bound tab. | macOS, Linux, Windows |
-| <span id="browser_type"></span>[`browser_type`](/cua-driver/reference/mcp-tools/browser-input#browser_type) | Type text into an exactly-bound tab via the Input domain. | macOS, Linux, Windows |
-| <span id="browser_select"></span>[`browser_select`](/cua-driver/reference/mcp-tools/browser-input#browser_select) | Select one option of a native HTML &lt;select&gt; ref on an exactly-bound tab without opening its popup. | macOS, Linux, Windows |
-| <span id="browser_pointer"></span>[`browser_pointer`](/cua-driver/reference/mcp-tools/browser-input#browser_pointer) | Perform hover, right-click, double-click, scroll, or drag in an exactly-bound browser tab. | macOS, Linux, Windows |
-| <span id="browser_dialog"></span>[`browser_dialog`](/cua-driver/reference/mcp-tools/browser-input#browser_dialog) | Inspect or resolve a page-owned JavaScript alert, confirm, prompt, or beforeunload dialog on one exactly-bound tab. | macOS, Linux, Windows |
-| <span id="browser_set_input_files"></span>[`browser_set_input_files`](/cua-driver/reference/mcp-tools/browser-input#browser_set_input_files) | Assign one or more explicit absolute local files to an exact live &lt;input type=file&gt; ref through CDP. | macOS, Linux, Windows |
-| <span id="browser_download"></span>[`browser_download`](/cua-driver/reference/mcp-tools/browser-input#browser_download) | Trigger one download through an exact live browser ref and save it inside an explicitly approved directory. | macOS, Linux, Windows |
+| <span id="browser_click"></span>[`browser_click`](/cua-driver/reference/mcp-tools/pointer-cursor-and-browser#browser_click) | Click a page element (by ref) or viewport coordinates in an exactly-bound tab. | macOS, Linux, Windows |
+| <span id="browser_type"></span>[`browser_type`](/cua-driver/reference/mcp-tools/pointer-cursor-and-browser#browser_type) | Type text into an exactly-bound tab via the Input domain. | macOS, Linux, Windows |
+| <span id="browser_select"></span>[`browser_select`](/cua-driver/reference/mcp-tools/pointer-cursor-and-browser#browser_select) | Select one option of a native HTML &lt;select&gt; ref on an exactly-bound tab without opening its popup. | macOS, Linux, Windows |
+| <span id="browser_pointer"></span>[`browser_pointer`](/cua-driver/reference/mcp-tools/pointer-cursor-and-browser#browser_pointer) | Perform hover, right-click, double-click, scroll, or drag in an exactly-bound browser tab. | macOS, Linux, Windows |
+| <span id="browser_dialog"></span>[`browser_dialog`](/cua-driver/reference/mcp-tools/pointer-cursor-and-browser#browser_dialog) | Inspect or resolve a page-owned JavaScript alert, confirm, prompt, or beforeunload dialog on one exactly-bound tab. | macOS, Linux, Windows |
+| <span id="browser_set_input_files"></span>[`browser_set_input_files`](/cua-driver/reference/mcp-tools/pointer-cursor-and-browser#browser_set_input_files) | Assign one or more explicit absolute local files to an exact live &lt;input type=file&gt; ref through CDP. | macOS, Linux, Windows |
+| <span id="browser_download"></span>[`browser_download`](/cua-driver/reference/mcp-tools/pointer-cursor-and-browser#browser_download) | Trigger one download through an exact live browser ref and save it inside an explicitly approved directory. | macOS, Linux, Windows |
## Session tools
-Start, escalate, inspect and end lifecycle sessions. [Reference](/cua-driver/reference/mcp-tools/sessions).
+Start, escalate, inspect and end lifecycle sessions. [Reference](/cua-driver/reference/mcp-tools/apps-windows-and-screen#session-tools).
| Tool | Description | Platforms |
| --- | --- | --- |
-| <span id="start_session"></span>[`start_session`](/cua-driver/reference/mcp-tools/sessions#start_session) | Optionally create or return a lifecycle session before acting. | macOS, Linux, Windows |
-| <span id="escalate_session"></span>[`escalate_session`](/cua-driver/reference/mcp-tools/sessions#escalate_session) | Deprecated compatibility tool for legacy capture-scope sessions. | macOS, Linux, Windows |
-| <span id="get_session"></span>[`get_session`](/cua-driver/reference/mcp-tools/sessions#get_session) | Read content-free lifecycle, cursor, recording, and idle status for one session visible to this authenticated transport. | macOS, Linux, Windows |
-| <span id="list_sessions"></span>[`list_sessions`](/cua-driver/reference/mcp-tools/sessions#list_sessions) | List content-free lifecycle summaries attached to this authenticated transport lease. | macOS, Linux, Windows |
-| <span id="get_session_state"></span>[`get_session_state`](/cua-driver/reference/mcp-tools/sessions#get_session_state) | Deprecated compatibility alias that reads a live legacy session's capture policy. | macOS, Linux, Windows |
-| <span id="end_session"></span>[`end_session`](/cua-driver/reference/mcp-tools/sessions#end_session) | End one visible lifecycle session and run its cursor, recording, configuration, and other cleanup hooks exactly once. | macOS, Linux, Windows |
+| <span id="start_session"></span>[`start_session`](/cua-driver/reference/mcp-tools/apps-windows-and-screen#start_session) | Optionally create or return a lifecycle session before acting. | macOS, Linux, Windows |
+| <span id="escalate_session"></span>[`escalate_session`](/cua-driver/reference/mcp-tools/apps-windows-and-screen#escalate_session) | Deprecated compatibility tool for legacy capture-scope sessions. | macOS, Linux, Windows |
+| <span id="get_session"></span>[`get_session`](/cua-driver/reference/mcp-tools/apps-windows-and-screen#get_session) | Read content-free lifecycle, cursor, recording, and idle status for one session visible to this authenticated transport. | macOS, Linux, Windows |
+| <span id="list_sessions"></span>[`list_sessions`](/cua-driver/reference/mcp-tools/apps-windows-and-screen#list_sessions) | List content-free lifecycle summaries attached to this authenticated transport lease. | macOS, Linux, Windows |
+| <span id="get_session_state"></span>[`get_session_state`](/cua-driver/reference/mcp-tools/apps-windows-and-screen#get_session_state) | Deprecated compatibility alias that reads a live legacy session's capture policy. | macOS, Linux, Windows |
+| <span id="end_session"></span>[`end_session`](/cua-driver/reference/mcp-tools/apps-windows-and-screen#end_session) | End one visible lifecycle session and run its cursor, recording, configuration, and other cleanup hooks exactly once. | macOS, Linux, Windows |
## Agent cursor tools
-Show, animate and style the agent cursor. [Reference](/cua-driver/reference/mcp-tools/agent-cursor).
+Show, animate and style the agent cursor. [Reference](/cua-driver/reference/mcp-tools/pointer-cursor-and-browser#agent-cursor-tools).
| Tool | Description | Platforms |
| --- | --- | --- |
-| <span id="set_agent_cursor_enabled"></span>[`set_agent_cursor_enabled`](/cua-driver/reference/mcp-tools/agent-cursor#set_agent_cursor_enabled) | Show or hide the agent cursor owned by a session. | macOS, Linux, Windows |
-| <span id="set_agent_cursor_motion"></span>[`set_agent_cursor_motion`](/cua-driver/reference/mcp-tools/agent-cursor#set_agent_cursor_motion) | Configure the movement style, timing, effects and visibility timing for a session cursor. | macOS, Linux, Windows |
-| <span id="set_agent_cursor_theme"></span>[`set_agent_cursor_theme`](/cua-driver/reference/mcp-tools/agent-cursor#set_agent_cursor_theme) | Select an already-installed cursor theme for a session. | macOS, Linux, Windows |
-| <span id="get_agent_cursor_state"></span>[`get_agent_cursor_state`](/cua-driver/reference/mcp-tools/agent-cursor#get_agent_cursor_state) | Return the session cursor's theme, semantic playback, position, visibility, and motion. | macOS, Linux, Windows |
+| <span id="set_agent_cursor_enabled"></span>[`set_agent_cursor_enabled`](/cua-driver/reference/mcp-tools/pointer-cursor-and-browser#set_agent_cursor_enabled) | Show or hide the agent cursor owned by a session. | macOS, Linux, Windows |
+| <span id="set_agent_cursor_motion"></span>[`set_agent_cursor_motion`](/cua-driver/reference/mcp-tools/pointer-cursor-and-browser#set_agent_cursor_motion) | Configure the movement style, timing, effects and visibility timing for a session cursor. | macOS, Linux, Windows |
+| <span id="set_agent_cursor_theme"></span>[`set_agent_cursor_theme`](/cua-driver/reference/mcp-tools/pointer-cursor-and-browser#set_agent_cursor_theme) | Select an already-installed cursor theme for a session. | macOS, Linux, Windows |
+| <span id="get_agent_cursor_state"></span>[`get_agent_cursor_state`](/cua-driver/reference/mcp-tools/pointer-cursor-and-browser#get_agent_cursor_state) | Return the session cursor's theme, semantic playback, position, visibility, and motion. | macOS, Linux, Windows |
## Recording tools
-Record and replay trajectories. [Reference](/cua-driver/reference/mcp-tools/recording).
+Record and replay trajectories. [Reference](/cua-driver/reference/mcp-tools/batch-recording-and-settings#recording-tools).
| Tool | Description | Platforms |
| --- | --- | --- |
-| <span id="start_recording"></span>[`start_recording`](/cua-driver/reference/mcp-tools/recording#start_recording) | Start trajectory recording for the calling session. | macOS, Linux, Windows |
-| <span id="stop_recording"></span>[`stop_recording`](/cua-driver/reference/mcp-tools/recording#stop_recording) | Stop trajectory recording. | macOS, Linux, Windows |
-| <span id="get_recording_state"></span>[`get_recording_state`](/cua-driver/reference/mcp-tools/recording#get_recording_state) | Report the current trajectory recorder state: whether recording is enabled, the output directory (when enabled), and the 1-based counter for the next turn folder that will be written. | macOS, Linux, Windows |
-| <span id="replay_trajectory"></span>[`replay_trajectory`](/cua-driver/reference/mcp-tools/recording#replay_trajectory) | Replay a recorded trajectory by re-invoking every turn's tool call in lexical order. | macOS, Linux, Windows |
-| <span id="install_ffmpeg"></span>[`install_ffmpeg`](/cua-driver/reference/mcp-tools/recording#install_ffmpeg) | Install the ffmpeg binary used by start_recording's video capture (Linux/Windows; macOS records natively and needs no ffmpeg). | macOS, Linux, Windows |
+| <span id="start_recording"></span>[`start_recording`](/cua-driver/reference/mcp-tools/batch-recording-and-settings#start_recording) | Start trajectory recording for the calling session. | macOS, Linux, Windows |
+| <span id="stop_recording"></span>[`stop_recording`](/cua-driver/reference/mcp-tools/batch-recording-and-settings#stop_recording) | Stop trajectory recording. | macOS, Linux, Windows |
+| <span id="get_recording_state"></span>[`get_recording_state`](/cua-driver/reference/mcp-tools/batch-recording-and-settings#get_recording_state) | Report the current trajectory recorder state: whether recording is enabled, the output directory (when enabled), and the 1-based counter for the next turn folder that will be written. | macOS, Linux, Windows |
+| <span id="replay_trajectory"></span>[`replay_trajectory`](/cua-driver/reference/mcp-tools/batch-recording-and-settings#replay_trajectory) | Replay a recorded trajectory by re-invoking every turn's tool call in lexical order. | macOS, Linux, Windows |
+| <span id="install_ffmpeg"></span>[`install_ffmpeg`](/cua-driver/reference/mcp-tools/batch-recording-and-settings#install_ffmpeg) | Install the ffmpeg binary used by start_recording's video capture (Linux/Windows; macOS records natively and needs no ffmpeg). | macOS, Linux, Windows |
## Configuration and maintenance tools
-Configuration, permissions, health, updates, extensions and on-demand guides. [Reference](/cua-driver/reference/mcp-tools/maintenance).
+Configuration, permissions, health, updates, extensions and on-demand guides. [Reference](/cua-driver/reference/mcp-tools/batch-recording-and-settings#configuration-and-maintenance-tools).
| Tool | Description | Platforms |
| --- | --- | --- |
-| <span id="get_config"></span>[`get_config`](/cua-driver/reference/mcp-tools/maintenance#get_config) | Return the current cua-driver-rs configuration. | macOS, Linux, Windows |
-| <span id="set_config"></span>[`set_config`](/cua-driver/reference/mcp-tools/maintenance#set_config) | Update cua-driver-rs configuration. | macOS, Linux, Windows |
-| <span id="check_permissions"></span>[`check_permissions`](/cua-driver/reference/mcp-tools/maintenance#check_permissions) | Report TCC permission status for Accessibility and Screen Recording. | macOS, Linux, Windows |
-| <span id="health_report"></span>[`health_report`](/cua-driver/reference/mcp-tools/maintenance#health_report) | Single-call end-to-end driver diagnostics. | macOS, Linux, Windows |
-| <span id="check_for_update"></span>[`check_for_update`](/cua-driver/reference/mcp-tools/maintenance#check_for_update) | Check the saved stable/nightly Cua Driver channel for a release on GitHub. | macOS, Linux, Windows |
-| <span id="install_extension"></span>[`install_extension`](/cua-driver/reference/mcp-tools/maintenance#install_extension) | Preview or install one Driver-managed optional extension. | macOS, Linux, Windows |
-| <span id="get_guide"></span>[`get_guide`](/cua-driver/reference/mcp-tools/maintenance#get_guide) | Read Cua Driver guidance on demand, taken from the guide bundled with this driver (no skill install needed). | macOS, Linux, Windows |
+| <span id="get_config"></span>[`get_config`](/cua-driver/reference/mcp-tools/batch-recording-and-settings#get_config) | Return the current cua-driver-rs configuration. | macOS, Linux, Windows |
+| <span id="set_config"></span>[`set_config`](/cua-driver/reference/mcp-tools/batch-recording-and-settings#set_config) | Update cua-driver-rs configuration. | macOS, Linux, Windows |
+| <span id="check_permissions"></span>[`check_permissions`](/cua-driver/reference/mcp-tools/batch-recording-and-settings#check_permissions) | Report TCC permission status for Accessibility and Screen Recording. | macOS, Linux, Windows |
+| <span id="health_report"></span>[`health_report`](/cua-driver/reference/mcp-tools/batch-recording-and-settings#health_report) | Single-call end-to-end driver diagnostics. | macOS, Linux, Windows |
+| <span id="check_for_update"></span>[`check_for_update`](/cua-driver/reference/mcp-tools/batch-recording-and-settings#check_for_update) | Check the saved stable/nightly Cua Driver channel for a release on GitHub. | macOS, Linux, Windows |
+| <span id="install_extension"></span>[`install_extension`](/cua-driver/reference/mcp-tools/batch-recording-and-settings#install_extension) | Preview or install one Driver-managed optional extension. | macOS, Linux, Windows |
+| <span id="get_guide"></span>[`get_guide`](/cua-driver/reference/mcp-tools/batch-recording-and-settings#get_guide) | Read Cua Driver guidance on demand, taken from the guide bundled with this driver (no skill install needed). | macOS, Linux, Windows |
diff --git a/docs/content/docs/cua-driver/reference/mcp-tools/keyboard.mdx b/docs/content/docs/cua-driver/reference/mcp-tools/keyboard.mdx
deleted file mode 100644
index 0e6cc692db..0000000000
--- a/docs/content/docs/cua-driver/reference/mcp-tools/keyboard.mdx
+++ /dev/null
@@ -1,106 +0,0 @@
----
-title: "Typing tools"
-description: "Type text into a field or window."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-driver
- Source: cua-driver dump-docs --type mcp (macOS, Linux and Windows registries)
- Version: 0.36.0
-*/}
-
-import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
-
-Served by `cua-driver mcp`; see [MCP tools](/cua-driver/reference/mcp-tools) for every tool.
-
-## `type_text`
-
-Effect: destructive. Platforms: macOS, Linux, Windows.
-
-<Tabs items={['macOS', 'Linux', 'Windows']} groupId="platform" persist>
-<Tab value="macOS">
-
-Insert text via `AXSetAttribute(kAXSelectedText)` into the element given by `element_token`, or the pid's focused element. Does not press keys: use `press_key` / `hotkey` for Return, Escape, arrows. If AX insertion is unsupported (Chromium/Electron), it falls back to CGEvent typing when the route fits the transport budget; longer routes are refused with a safe chunk size.
-
-Web content (browser tabs, Slack, VS Code): AXValue is not proof the DOM saw the text, so the result is `effect:"unverifiable"` and Electron web content refuses background delivery. For a browser tab use the `page` tool. For an embedded web view pass `x, y` (no element_token) to pixel-click the field then type in one call; a pixel click will not reliably open a closed control, so AX-press it open first. Confirm from the screenshot, and use `delivery_mode:"foreground"` only if background still drops the text.
-
-**macOS parameters**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="type_text--macos--delay_ms"></span>`delay_ms` | `integer` | | Ms between characters in the CGEvent fallback. Default 30. Range: 0 to 200. |
-| <span id="type_text--macos--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | | Default "background": AX insert, then CGEvent keys, no focus steal. "foreground": front the window, type, restore; last resort for surfaces (WhatsApp/Catalyst) where background keys do not land. |
-| <span id="type_text--macos--element_token"></span>`element_token` | `string` | | Element handle `<snapshot_id>:<row>` from get_window_state: row `[11]` of a read whose snapshot_id is s0000002a is "s0000002a:11" (also in `structuredContent.elements[].element_token`). Returns an explicit stale error naming the current snapshots once a newer read supersedes it. |
-| <span id="type_text--macos--pid"></span>`pid` | `integer` | | Target process ID. |
-| <span id="type_text--macos--scope"></span>`scope` | `"window" \| "desktop"` | `"window"` | "desktop" with no pid/window_id types into the frontmost app. |
-| <span id="type_text--macos--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. |
-| <span id="type_text--macos--text"></span>`text` | `string` | required | Text to insert. |
-| <span id="type_text--macos--window_id"></span>`window_id` | `integer` | | Window ID. Omit with element_token. |
-| <span id="type_text--macos--x"></span>`x` | `number` | | Screenshot-pixel X of the field (get_window_state PNG, as in click). With y and no element_token, pixel-clicks to focus, then types. |
-| <span id="type_text--macos--y"></span>`y` | `number` | | Screenshot-pixel Y (see x). |
-
-</Tab>
-<Tab value="Linux">
-
-Type text to a window via XSendEvent (KeyPress/KeyRelease). No focus steal.
-
-**Linux parameters**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="type_text--linux--coordinate_frame"></span>`coordinate_frame` | `"window" \| "desktop"` | | Frame of x/y (and from_x/from_y/to_x/to_y). Default "window": window-local screenshot pixels as returned by get_window_state. "desktop": full-screen pixels as returned by get_desktop_state, translated to the target window. Passing scope:"desktop" together with pid/window_id means the same thing. |
-| <span id="type_text--linux--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | `"background"` | Input delivery mode. 'background' (default) never activates or raises the target window. On X11 it injects via XTEST / the XInput2 master pointer (no focus steal). On Wayland it goes through libei + xdg-desktop-portal, which injects to the compositor's input focus: Wayland's security model has no per-window background targeting, so a specific non-focused window cannot be aimed at; when no libei backend is available the tool returns a structured background_unavailable error. 'foreground' is the explicit escalation: activate the target (X11 _NET_ACTIVE_WINDOW; Wayland compositor activate), inject, then restore the prior active window; a brief focus swap unless the target was already active. Matches the macOS / Windows delivery_mode surface. |
-| <span id="type_text--linux--element_token"></span>`element_token` | `string` | | Element handle `<snapshot_id>:<row>` from get_window_state: row `[11]` of a read whose snapshot_id is s0000002a is "s0000002a:11" (also in `structuredContent.elements[].element_token`). Returns an explicit stale error naming the current snapshots once a newer read supersedes it. |
-| <span id="type_text--linux--pid"></span>`pid` | `integer` | | Target process ID. Omit with scope "desktop" to type into the focused application. |
-| <span id="type_text--linux--scope"></span>`scope` | `"window" \| "desktop"` | `"window"` | Use "desktop" with no pid to type into the focused application. Default "window". |
-| <span id="type_text--linux--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
-| <span id="type_text--linux--text"></span>`text` | `string` | required | Text to type. |
-| <span id="type_text--linux--window_id"></span>`window_id` | `integer` | | Window id from list_windows. Required with x/y; optional with element_token (the token carries it). |
-| <span id="type_text--linux--x"></span>`x` | `number` | | Pixel X of the field to type into: the element px action form. Pass x,y (no element_token) and the tool pixel-clicks there to establish real renderer focus, then types. Use for Chromium/Electron inputs the AX path can't reach. Window-local pixels of the target window's own get_window_state screenshot by default (same convention as click); for get_desktop_state pixels pass scope:"desktop" (or coordinate_frame:"desktop"): a bare pid+x/y is otherwise misinterpreted as window-local and can focus the wrong widget. |
-| <span id="type_text--linux--y"></span>`y` | `number` | | Pixel Y of the field (see x). |
-
-</Tab>
-<Tab value="Windows">
-
-Insert text into the target pid via character-by-character PostMessage(WM_CHAR) to the focused window. No focus steal.
-
-Special keys (Return, Escape, arrows, Tab) go through `press_key` / `hotkey`: they are not text.
-
-**Routing on Windows.** When the target's owning EXE or top-level window class identifies it as a XAML / WinUI3 / UWP host (modern Notepad, Calculator, Photos, Settings, etc.), the tool requires `element_token` and routes through UI Automation's `ValuePattern.SetValue`: same backend as the `set_value` tool. PostMessage WM_CHAR doesn't reach those hosts (their CoreInput dispatcher only consumes events from the system input queue), so the fallback path silently dropped chars. If you call `type_text(pid, text)` on a XAML host without `element_token`, the tool returns an actionable error pointing you at `get_window_state` first. Native ConsoleHost on Windows ARM64 is hard-refused because it can accept synthesized Unicode events without delivering them; use a process or PTY setup channel instead. Legacy Win32 apps still use the PostMessage path, preserving the no-focus-steal property.
-
-`delay_ms` (0–200, default 30) spaces successive characters on the PostMessage path so autocomplete and IME can keep up. Ignored on the UIA path (SetValue is atomic).
-
-**Windows parameters**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="type_text--windows--delay_ms"></span>`delay_ms` | `integer` | | Milliseconds between characters. Default 30. Range: 0 to 200. |
-| <span id="type_text--windows--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | | Input delivery mode. 'background' (default) never swaps foreground: it routes through UIA Invoke / PostMessage and the window is never raised. For targets whose input stack silently drops posted events (Chromium/Electron content, GTK buttons, VCL/LibreOffice accelerators) the tool returns a structured background_unavailable error rather than fronting. 'foreground' is the explicit escalation: a brief SetForegroundWindow swap + SendInput, restoring the prior foreground afterward. IMPORTANT: 'background' is not a hint to weigh; it is the mandatory first attempt. Do NOT pass 'foreground' preemptively because a target 'looks like' GTK/Chromium/Electron; the DRIVER decides when background is impossible and tells you so via a background_unavailable error (or a verified no-op). Only THEN re-issue the same action with 'foreground'. The lists above are the driver's detectors, not a checklist for you to front on a guess: fronting up-front needlessly steals the user's focus and is a bug, not a shortcut. Matches the macOS delivery_mode surface. |
-| <span id="type_text--windows--element_token"></span>`element_token` | `string` | | Opaque element handle from get_window_state. When supplied, type_text writes through UIA ValuePattern and reads that exact element back by handle. The shared ActionResult is confirmed only when the complete expected value is synchronously visible. If SetValue succeeds but read-back is stale or unavailable, the result is unverifiable with no escalation; take a fresh snapshot before retrying because deferred providers may publish only after this call returns. |
-| <span id="type_text--windows--pid"></span>`pid` | `integer` | | Target process ID. |
-| <span id="type_text--windows--scope"></span>`scope` | `"window" \| "desktop"` | | Use desktop with no pid/window_id to type into the current foreground application. |
-| <span id="type_text--windows--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
-| <span id="type_text--windows--text"></span>`text` | `string` | required | Text to insert at the focused element's cursor. |
-| <span id="type_text--windows--window_id"></span>`window_id` | `integer` | | HWND of the target window. Omit when element_token is supplied (the token carries it). |
-| <span id="type_text--windows--x"></span>`x` | `number` | | Window-local screenshot-pixel X of the field to type into: the element px action form. Pass x,y (no element_token) and the tool pixel-clicks there to establish real renderer focus, then types. Use for Chromium/Electron inputs the UIA/WM_CHAR path can't reach. Read straight off the get_window_state PNG, same convention as click. |
-| <span id="type_text--windows--y"></span>`y` | `number` | | Window-local screenshot-pixel Y of the field (see x). |
-
-</Tab>
-</Tabs>
-
-**Parameters on every platform**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="type_text--target"></span>`target` | `object` | | Preferred per-call target: an exact window (`kind="window"`, `pid`, `window_id`) or the primary desktop (`kind="desktop"`, `display_id="primary"`). |
-| <span id="type_text--target-display_id"></span>`target.display_id` | `string` | | Display id. Required when kind is desktop; use "primary". |
-| <span id="type_text--target-kind"></span>`target.kind` | `"window" \| "desktop"` | | window requires pid and window_id; desktop requires display_id. |
-| <span id="type_text--target-pid"></span>`target.pid` | `integer` | | Process id. Required when kind is window. Minimum: 0. |
-| <span id="type_text--target-window_id"></span>`target.window_id` | `integer` | | Window id from list_windows. Required when kind is window. Minimum: 0. |
-
-**Example arguments**
-
-```json
-{"text":"<text>"}
-```
diff --git a/docs/content/docs/cua-driver/reference/mcp-tools/keys-and-shortcuts.mdx b/docs/content/docs/cua-driver/reference/mcp-tools/keys-and-shortcuts.mdx
deleted file mode 100644
index b80a2a99a7..0000000000
--- a/docs/content/docs/cua-driver/reference/mcp-tools/keys-and-shortcuts.mdx
+++ /dev/null
@@ -1,207 +0,0 @@
----
-title: "Key and shortcut tools"
-description: "Press keys and keyboard shortcuts."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-driver
- Source: cua-driver dump-docs --type mcp (macOS, Linux and Windows registries)
- Version: 0.36.0
-*/}
-
-import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
-
-| Tool | Description | Platforms |
-| --- | --- | --- |
-| [`press_key`](#press_key) | Press and release one key. | macOS, Linux, Windows |
-| [`hotkey`](#hotkey) | Press a key combination: e.g. | macOS, Linux, Windows |
-
-Served by `cua-driver mcp`; see [MCP tools](/cua-driver/reference/mcp-tools) for every tool.
-
-## `press_key`
-
-Effect: destructive. Platforms: macOS, Linux, Windows.
-
-<Tabs items={['macOS', 'Linux', 'Windows']} groupId="platform" persist>
-<Tab value="macOS">
-
-Press and release one key. `delivery_mode` as in click/type_text.
-- `background` (default): posts to the pid without raising the window; with `element_token` it focuses that element first.
-- `foreground`: fronts the exact window (needs `window_id`), sends a real HID key transition (Chromium content, inline editors, menu equivalents), then restores the prior app.
-
-An element target whose focus cannot be confirmed is refused with `target_focus_unconfirmed`, effect "refused", and no key dispatched.
-Confirmed only when a native AX value/selection read-back changes; otherwise `effect:"unverifiable"` (not a delivery failure). Keys: return, tab, escape, up/down/left/right, space, delete, home, end, pageup, pagedown, f1-f12, any letter or digit.
-
-**macOS parameters**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="press_key--macos--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | | Default "background": no fronting or focus steal. "foreground": briefly front the window, act, restore the prior app; last resort when background did not land. |
-| <span id="press_key--macos--key"></span>`key` | `string` | required | Key name. |
-| <span id="press_key--macos--modifiers"></span>`modifiers` | `string[]` | | cmd, shift, option/alt, ctrl, fn. |
-| <span id="press_key--macos--pid"></span>`pid` | `integer` | | Target process ID. |
-| <span id="press_key--macos--scope"></span>`scope` | `"window" \| "desktop"` | `"window"` | "desktop" with no pid/window_id sends to the frontmost app. |
-| <span id="press_key--macos--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. |
-| <span id="press_key--macos--window_id"></span>`window_id` | `integer` | | Target window; required for foreground. Does not raise by itself. |
-| <span id="press_key--macos--x"></span>`x` | `number` | | Screenshot-pixel X: pixel-click to focus, then send the key. With y, no element_token. |
-| <span id="press_key--macos--y"></span>`y` | `number` | | Screenshot-pixel Y (see x). |
-
-</Tab>
-<Tab value="Linux">
-
-Press a key via XSendEvent to a window. No focus steal.
-
-**Linux parameters**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="press_key--linux--coordinate_frame"></span>`coordinate_frame` | `"window" \| "desktop"` | | Frame of x/y (and from_x/from_y/to_x/to_y). Default "window": window-local screenshot pixels as returned by get_window_state. "desktop": full-screen pixels as returned by get_desktop_state, translated to the target window. Passing scope:"desktop" together with pid/window_id means the same thing. |
-| <span id="press_key--linux--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | `"background"` | Input delivery mode. 'background' (default) never activates or raises the target window. On X11 it injects via XTEST / the XInput2 master pointer (no focus steal). On Wayland it goes through libei + xdg-desktop-portal, which injects to the compositor's input focus: Wayland's security model has no per-window background targeting, so a specific non-focused window cannot be aimed at; when no libei backend is available the tool returns a structured background_unavailable error. 'foreground' is the explicit escalation: activate the target (X11 _NET_ACTIVE_WINDOW; Wayland compositor activate), inject, then restore the prior active window; a brief focus swap unless the target was already active. Matches the macOS / Windows delivery_mode surface. |
-| <span id="press_key--linux--key"></span>`key` | `string` | required | Key name: enter/return, tab, escape, space, backspace, delete, insert, home, end, pageup, pagedown, up, down, left, right, f1-f12, or any single ASCII character. |
-| <span id="press_key--linux--modifiers"></span>`modifiers` | `string[]` | | Modifier keys held while the key is pressed: ctrl, shift, alt, super. |
-| <span id="press_key--linux--pid"></span>`pid` | `integer` | | Target process ID. Omit with scope "desktop" to send the key to the focused application. |
-| <span id="press_key--linux--scope"></span>`scope` | `"window" \| "desktop"` | `"window"` | Use "desktop" with no pid to send the key to the focused application. Default "window". |
-| <span id="press_key--linux--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
-| <span id="press_key--linux--window_id"></span>`window_id` | `integer` | | Window id from list_windows. Required with x/y or element_index; optional with element_token (the token carries it). |
-| <span id="press_key--linux--x"></span>`x` | `number` | | Pixel X: the element px action form: pixel-click there to focus, then send the key. Use when the key must go to a Chromium/Electron surface the AX path can't focus. Pass with y, no element_token. Window-local pixels by default (same convention as click); for get_desktop_state pixels pass scope:"desktop" (or coordinate_frame:"desktop"). |
-| <span id="press_key--linux--y"></span>`y` | `number` | | Pixel Y (see x). |
-
-</Tab>
-<Tab value="Windows">
-
-Press and release a single key, delivered directly to the target pid's top-level window via PostMessage(WM_KEYDOWN/WM_KEYUP). The target does NOT need to be frontmost: no focus steal.
-
-Optional `window_id` selects a specific HWND when the pid owns more than one; without it the first visible top-level window for the pid is used.
-
-Key vocabulary: return, tab, escape, up/down/left/right, space, delete, home, end, pageup, pagedown, f1-f12, plus any letter or digit. Optional `modifiers` array takes ctrl/shift/alt/win. For true combinations (ctrl+c), `hotkey` is a cleaner surface.
-
-`element_token` focuses the cached UIA element before sending the key; the top-level window remains backgrounded when delivery_mode is background.
-
-**Windows parameters**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="press_key--windows--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | | Input delivery mode. 'background' (default) never swaps foreground: it routes through UIA Invoke / PostMessage and the window is never raised. For targets whose input stack silently drops posted events (Chromium/Electron content, GTK buttons, VCL/LibreOffice accelerators) the tool returns a structured background_unavailable error rather than fronting. 'foreground' is the explicit escalation: a brief SetForegroundWindow swap + SendInput, restoring the prior foreground afterward. IMPORTANT: 'background' is not a hint to weigh; it is the mandatory first attempt. Do NOT pass 'foreground' preemptively because a target 'looks like' GTK/Chromium/Electron; the DRIVER decides when background is impossible and tells you so via a background_unavailable error (or a verified no-op). Only THEN re-issue the same action with 'foreground'. The lists above are the driver's detectors, not a checklist for you to front on a guess: fronting up-front needlessly steals the user's focus and is a bug, not a shortcut. Matches the macOS delivery_mode surface. |
-| <span id="press_key--windows--key"></span>`key` | `string` | required | Key name (return, tab, escape, up, down, left, right, space, delete, home, end, pageup, pagedown, f1-f12, letter, digit). |
-| <span id="press_key--windows--modifiers"></span>`modifiers` | `string[]` | | Optional modifier names held while the key is pressed (ctrl/shift/alt/win). |
-| <span id="press_key--windows--pid"></span>`pid` | `integer` | | Target process ID. |
-| <span id="press_key--windows--scope"></span>`scope` | `"window" \| "desktop"` | | Use desktop with no pid/window_id to send the key to the current foreground application. |
-| <span id="press_key--windows--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
-| <span id="press_key--windows--window_id"></span>`window_id` | `integer` | | HWND for the target window. Omit when element_token is supplied; otherwise auto-resolves the pid's first visible window. |
-| <span id="press_key--windows--x"></span>`x` | `number` | | Window-local screenshot-pixel X: the element px action form: pixel-click there to focus, then send the key. Use when the key must go to a Chromium/Electron surface the UIA path can't focus. Pass with y, no element_token. |
-| <span id="press_key--windows--y"></span>`y` | `number` | | Window-local screenshot-pixel Y (see x). |
-
-</Tab>
-</Tabs>
-
-**Parameters on every platform**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="press_key--element_token"></span>`element_token` | `string` | | Element handle `<snapshot_id>:<row>` from get_window_state: row `[11]` of a read whose snapshot_id is s0000002a is "s0000002a:11" (also in `structuredContent.elements[].element_token`). Returns an explicit stale error naming the current snapshots once a newer read supersedes it. |
-| <span id="press_key--target"></span>`target` | `object` | | Preferred per-call target: an exact window (`kind="window"`, `pid`, `window_id`) or the primary desktop (`kind="desktop"`, `display_id="primary"`). |
-| <span id="press_key--target-display_id"></span>`target.display_id` | `string` | | Display id. Required when kind is desktop; use "primary". |
-| <span id="press_key--target-kind"></span>`target.kind` | `"window" \| "desktop"` | | window requires pid and window_id; desktop requires display_id. |
-| <span id="press_key--target-pid"></span>`target.pid` | `integer` | | Process id. Required when kind is window. Minimum: 0. |
-| <span id="press_key--target-window_id"></span>`target.window_id` | `integer` | | Window id from list_windows. Required when kind is window. Minimum: 0. |
-
-**Example arguments**
-
-```json
-{"key":"<key>"}
-```
-
-## `hotkey`
-
-Effect: destructive. Platforms: macOS, Linux, Windows.
-
-<Tabs items={['macOS', 'Linux', 'Windows']} groupId="platform" persist>
-<Tab value="macOS">
-
-Press a key combination: e.g. `["cmd", "c"]` for Copy, `["cmd", "shift", "4"]` for screenshot selection. Follows the same `delivery_mode` ladder as click/type_text: it does NOT raise the window by default:
-• `background` (default): post the combo to the target pid WITHOUT fronting or raising it; uses the macOS 14+ auth-message envelope so Chromium/Electron accept it as trusted live input. With an AX target, focus that exact element first. No top-level focus steal. `window_id` here only targets the combo; it does not raise. Background key events never reach a native app's menus, so when the combo is a menu item's key equivalent (cmd+s, cmd+w, ...) and the app is not in front, that menu item runs through accessibility instead (a disabled Save is saved through the app's scripting interface and verified on disk); a menu item macOS keeps disabled in the background is refused with `background_unavailable`, and no keys are sent.
-• `foreground`: briefly front the window (NSMenu path, &lt; 1 ms via SLPSSetFrontProcessWithOptions) so native menu key-equivalents (Cmd+Z, Cmd+W) dispatch, then restore the prior frontmost; the explicit escalation for menu-bar shortcuts on non-Chromium apps that ignore a background combo. With an AX target or x,y, the focused field receives the chord through the foreground HID queue (needed by native Chromium fields such as the omnibox). Requires window_id.
-
-A combo is never driver-verifiable (no read-back) → effect:"unverifiable"; confirm via screenshot. NOTE: a keyboard combo does NOT focus a text field; to type into a backgrounded Electron input, establish real renderer focus with a PIXEL click first, then `type_text`. If an app only accepts paste, call `clipboard_write`, then `clipboard_read` and verify its types (and text when applicable) before selecting or replacing editor content; only then send Cmd+V.
-
-Recognized modifiers: cmd/command, shift, option/alt, ctrl/control, fn. Non-modifier keys use the same vocabulary as `press_key`. Order: modifiers first, one non-modifier last.
-
-**macOS parameters**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="hotkey--macos--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | | Best-effort-background ladder rung (default "background"). "background": inject without fronting or raising the target; no focus steal. "foreground": briefly front the target, act, then restore the prior frontmost; the explicit last resort when a background attempt didn't land. Re-call with "foreground" only for the action that needs it. |
-| <span id="hotkey--macos--keys"></span>`keys` | `string[]` | required | Modifier(s) and one non-modifier key, e.g. ["cmd", "c"]. Items: 2 to any. |
-| <span id="hotkey--macos--pid"></span>`pid` | `integer` | | Target process ID. Required with x, y; optional with element_token (the token carries the pid). |
-| <span id="hotkey--macos--scope"></span>`scope` | `"window" \| "desktop"` | `"window"` | Use desktop with no pid/window_id to send the chord to the frontmost application. |
-| <span id="hotkey--macos--window_id"></span>`window_id` | `integer` | | Target window. Required for delivery_mode:"foreground" (the NSMenu activation needs a window). Does NOT itself raise the window: raising is gated on delivery_mode. |
-| <span id="hotkey--macos--x"></span>`x` | `number` | | Screenshot-pixel X: the element px action form: pixel-click there to focus, then send the combo (so e.g. Cmd+V pastes into that field). Pass with y. Use for Chromium/Electron surfaces the background combo can't reach. |
-| <span id="hotkey--macos--y"></span>`y` | `number` | | Screenshot-pixel Y (see x). |
-
-</Tab>
-<Tab value="Linux">
-
-Press a combination of keys simultaneously, e.g. ["ctrl","c"] for Copy. Delivered to the target window without focus steal (real key events from a virtual master keyboard on X11); target does NOT need to be frontmost. Window-manager chords cannot reach the WM that way: alt+F4 on a window target closes that window through the WM (_NET_CLOSE_WINDOW, effect confirmed when it unmaps); super+*, alt+tab, ctrl+alt+* and other WM bindings are refused with code wm_chord_unavailable; use bring_to_front / list_windows / kill_app or delivery_mode:"foreground" instead.
-
-**Linux parameters**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="hotkey--linux--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | `"background"` | Input delivery mode. 'background' (default) never activates or raises the target window. On X11 it injects via XTEST / the XInput2 master pointer (no focus steal). On Wayland it goes through libei + xdg-desktop-portal, which injects to the compositor's input focus: Wayland's security model has no per-window background targeting, so a specific non-focused window cannot be aimed at; when no libei backend is available the tool returns a structured background_unavailable error. 'foreground' is the explicit escalation: activate the target (X11 _NET_ACTIVE_WINDOW; Wayland compositor activate), inject, then restore the prior active window; a brief focus swap unless the target was already active. Matches the macOS / Windows delivery_mode surface. |
-| <span id="hotkey--linux--keys"></span>`keys` | `string[]` | required | Modifier(s) + one non-modifier key, e.g. ["ctrl","c"]. Items: 2 to any. |
-| <span id="hotkey--linux--pid"></span>`pid` | `integer` | | Target process ID. Omit with scope "desktop" to send the chord to the focused application. |
-| <span id="hotkey--linux--scope"></span>`scope` | `"window" \| "desktop"` | `"window"` | Use "desktop" with no pid to send the chord to the focused application. Default "window". |
-| <span id="hotkey--linux--window_id"></span>`window_id` | `integer` | | Window id from list_windows. Required with x/y or element_index; optional with element_token (the token carries it). |
-| <span id="hotkey--linux--x"></span>`x` | `number` | | Screenshot-pixel X: the element px action form: pixel-click there to focus, then send the combo (so e.g. Ctrl+V pastes into that field). Pass with y. Use for Chromium/Electron surfaces the background combo can't reach. |
-| <span id="hotkey--linux--y"></span>`y` | `number` | | Screenshot-pixel Y (see x). |
-
-</Tab>
-<Tab value="Windows">
-
-Press a combination of keys simultaneously: e.g. `["ctrl", "c"]` for Copy, `["ctrl", "shift", "t"]` for reopen-closed-tab. Dispatch is target-aware:
-
-- **Modern XAML / WinUI / UWP targets** route through UI Automation: the driver walks the target's accessibility subtree, finds a descendant whose AcceleratorKey matches the combo, and invokes it. No focus steal, no system-queue input.
-
-- **Legacy Win32 targets with modifiers** (Ctrl+S, Alt+Tab, etc.) route through `SendInput` against the system input queue, with a brief `SetForegroundWindow` swap so the events land on the target. This path is necessary because PostMessage(WM_KEYDOWN, VK_CONTROL) does NOT update the OS-wide modifier state visible to `GetKeyState` / `TranslateAccelerator`, so Win32 apps that bind accelerators via `TranslateAccelerator` (LibreOffice, FAR, classic Notepad, etc.) never see the combo as a real accelerator on the PostMessage-only path. Trade-off: brief foreground swap (mitigated by restoring the previous foreground after the keystrokes flush). Requires the daemon to have UIAccess integrity so `SetForegroundWindow` is permitted: the MCP proxy auto-prefers the `cua-driver-uia.exe` worker pipe when both daemons are running.
-
-- **Legacy Win32 targets without modifiers** (plain `enter`, `tab`, `f5`, etc.) route through `PostMessage(WM_KEYDOWN/UP)`: no focus steal, no need to update modifier state.
-
-The target does NOT need to be frontmost in any branch.
-
-**`window_id`** (optional): explicit HWND when the pid owns more than one window; otherwise the pid's first visible window is used.
-
-Recognized modifiers: ctrl/control, shift, alt, win/windows. Non-modifier keys use the same vocabulary as `press_key` (return, tab, escape, up/down/left/right, space, delete, home, end, pageup, pagedown, f1-f12, letters, digits). Order: modifiers first, one non-modifier last.
-
-**Windows parameters**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="hotkey--windows--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | | Input delivery mode. 'background' (default) never swaps foreground: it routes through UIA Invoke / PostMessage and the window is never raised. For targets whose input stack silently drops posted events (Chromium/Electron content, GTK buttons, VCL/LibreOffice accelerators) the tool returns a structured background_unavailable error rather than fronting. 'foreground' is the explicit escalation: a brief SetForegroundWindow swap + SendInput, restoring the prior foreground afterward. IMPORTANT: 'background' is not a hint to weigh; it is the mandatory first attempt. Do NOT pass 'foreground' preemptively because a target 'looks like' GTK/Chromium/Electron; the DRIVER decides when background is impossible and tells you so via a background_unavailable error (or a verified no-op). Only THEN re-issue the same action with 'foreground'. The lists above are the driver's detectors, not a checklist for you to front on a guess: fronting up-front needlessly steals the user's focus and is a bug, not a shortcut. Matches the macOS delivery_mode surface. |
-| <span id="hotkey--windows--keys"></span>`keys` | `string[]` | required | Modifier(s) and one non-modifier key, e.g. ["ctrl", "c"]. Items: 2 to any. |
-| <span id="hotkey--windows--pid"></span>`pid` | `integer` | | Target process ID. |
-| <span id="hotkey--windows--scope"></span>`scope` | `"window" \| "desktop"` | | Use desktop with no pid/window_id to send the hotkey to the current foreground application. |
-| <span id="hotkey--windows--window_id"></span>`window_id` | `integer` | | Explicit HWND when the pid owns multiple windows. |
-| <span id="hotkey--windows--x"></span>`x` | `number` | | Window-local screenshot-pixel X: the element px action form: pixel-click there to focus, then send the combo (so e.g. Ctrl+V pastes into that field). Pass with y. Use for Chromium/Electron surfaces the background combo can't reach. |
-| <span id="hotkey--windows--y"></span>`y` | `number` | | Window-local screenshot-pixel Y (see x). |
-
-</Tab>
-</Tabs>
-
-**Parameters on every platform**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="hotkey--element_token"></span>`element_token` | `string` | | Element handle `<snapshot_id>:<row>` from get_window_state: row `[11]` of a read whose snapshot_id is s0000002a is "s0000002a:11" (also in `structuredContent.elements[].element_token`). Returns an explicit stale error naming the current snapshots once a newer read supersedes it. |
-| <span id="hotkey--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
-| <span id="hotkey--target"></span>`target` | `object` | | Preferred per-call target: an exact window (`kind="window"`, `pid`, `window_id`) or the primary desktop (`kind="desktop"`, `display_id="primary"`). |
-| <span id="hotkey--target-display_id"></span>`target.display_id` | `string` | | Display id. Required when kind is desktop; use "primary". |
-| <span id="hotkey--target-kind"></span>`target.kind` | `"window" \| "desktop"` | | window requires pid and window_id; desktop requires display_id. |
-| <span id="hotkey--target-pid"></span>`target.pid` | `integer` | | Process id. Required when kind is window. Minimum: 0. |
-| <span id="hotkey--target-window_id"></span>`target.window_id` | `integer` | | Window id from list_windows. Required when kind is window. Minimum: 0. |
-
-**Example arguments**
-
-```json
-{"keys":["<key>","<key>"]}
-```
diff --git a/docs/content/docs/cua-driver/reference/mcp-tools/maintenance.mdx b/docs/content/docs/cua-driver/reference/mcp-tools/maintenance.mdx
deleted file mode 100644
index f6fbfe2f31..0000000000
--- a/docs/content/docs/cua-driver/reference/mcp-tools/maintenance.mdx
+++ /dev/null
@@ -1,295 +0,0 @@
----
-title: "Configuration and maintenance tools"
-description: "Configuration, permissions, health, updates, extensions and on-demand guides."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-driver
- Source: cua-driver dump-docs --type mcp (macOS, Linux and Windows registries)
- Version: 0.36.0
-*/}
-
-import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
-
-| Tool | Description | Platforms |
-| --- | --- | --- |
-| [`get_config`](#get_config) | Return the current cua-driver-rs configuration. | macOS, Linux, Windows |
-| [`set_config`](#set_config) | Update cua-driver-rs configuration. | macOS, Linux, Windows |
-| [`check_permissions`](#check_permissions) | Report TCC permission status for Accessibility and Screen Recording. | macOS, Linux, Windows |
-| [`health_report`](#health_report) | Single-call end-to-end driver diagnostics. | macOS, Linux, Windows |
-| [`check_for_update`](#check_for_update) | Check the saved stable/nightly Cua Driver channel for a release on GitHub. | macOS, Linux, Windows |
-| [`install_extension`](#install_extension) | Preview or install one Driver-managed optional extension. | macOS, Linux, Windows |
-| [`get_guide`](#get_guide) | Read Cua Driver guidance on demand, taken from the guide bundled with this driver (no skill install needed). | macOS, Linux, Windows |
-
-Served by `cua-driver mcp`; see [MCP tools](/cua-driver/reference/mcp-tools) for every tool.
-
-## `get_config`
-
-Effect: read-only, idempotent. Platforms: macOS, Linux, Windows.
-
-<Tabs items={['macOS', 'Linux', 'Windows']} groupId="platform" persist>
-<Tab value="macOS">
-
-Return the current cua-driver-rs configuration.
-
-</Tab>
-<Tab value="Linux">
-
-Return current cua-driver-rs configuration.
-
-</Tab>
-<Tab value="Windows">
-
-Report the current persistent driver config.
-
-Pure read-only. Returns defaults when the underlying state is unset: same fallback the daemon uses at startup. Sibling to `set_config`.
-
-Current schema (Windows):
-
- &#123;
- "schema_version": 1,
- "version": "&lt;crate version&gt;",
- "source_sha": "&lt;maintainer build commit or null&gt;",
- "platform": "windows",
- "capture_mode": "ax" | "vision" (DEPRECATED, ignored),
- "max_image_dimension": 0
- &#125;
-
-`capture_mode` is deprecated and no longer affects behavior: `get_window_state` always returns both the UIA tree and a screenshot.
-
-</Tab>
-</Tabs>
-
-**Parameters on every platform**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="get_config--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
-
-## `set_config`
-
-Effect: mutating, idempotent. Platforms: macOS, Linux, Windows.
-
-<Tabs items={['macOS', 'Linux', 'Windows']} groupId="platform" persist>
-<Tab value="macOS">
-
-Update cua-driver-rs configuration. Changes to max_image_dimension take effect immediately. The experimental_pip keys are persisted to ~/.cua-driver/config.json and take effect on the next daemon restart (the PiP backend is initialised once at startup).
-
-Note: capture_mode is a per-call param (on get_window_state / click), not a stored setting. Capture modality is selected by each action's target; the old capture_scope config key is retired.
-
-Cursor motion defaults: cursor.motion.style, cursor.motion.timing and cursor.motion.effects.&lt;trail|glow|magnet|ripple|squish&gt; are saved to ~/.cua-driver/config.json and seed sessions started afterwards. start_session cursor_motion and set_agent_cursor_motion override them; reduced motion always wins.
-
-Agent cursor badge: cursor.badges is minimal (default), verbose or off, saved to ~/.cua-driver/config.json and applied to every cursor at once.
-
-**macOS parameters**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="set_config--macos--experimental_pip"></span>`experimental_pip` | `boolean` | | Enable the experimental picture-in-picture preview window. Applies on next daemon restart. |
-| <span id="set_config--macos--experimental_pip_geometry"></span>`experimental_pip_geometry` | `string` | | PiP window size + optional position in `WxH` or `WxH+X+Y` form (e.g. `320x200+24+24`). Applies on next daemon restart. |
-
-</Tab>
-<Tab value="Linux">
-
-Update cua-driver-rs configuration. capture_mode / max_image_dimension take effect immediately.
-
-Pass each setting as its own field: `{"capture_mode": "som", "max_image_dimension": 0}`.
-
-The experimental_pip keys persist to ~/.cua-driver/config.json and apply on next daemon restart (the PiP backend is initialised once at startup; Linux ships only the trait stub today: see issue #1729).
-
-`cursor.motion.style`, `cursor.motion.timing` and `cursor.motion.effects.<name>` (`on`, `off`, or `default`) save the default cursor motion for sessions started afterwards. `cursor.motion: "default"` clears every saved cursor motion default.
-
-`cursor.badges` (`minimal` default, `verbose`, or `off`) sets the agent cursor badge for every cursor at once.
-
-**Linux parameters**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="set_config--linux--capture_mode"></span>`capture_mode` | `"ax" \| "vision"` | | Default capture mode for get_window_state. ("som"/"screenshot" still decode as deprecated aliases.). |
-| <span id="set_config--linux--experimental_pip"></span>`experimental_pip` | `boolean` | | Enable the experimental PiP preview window (applies next restart; Linux backend stubbed). |
-| <span id="set_config--linux--experimental_pip_geometry"></span>`experimental_pip_geometry` | `string` | | PiP window size + optional position in `WxH` or `WxH+X+Y` form. |
-
-</Tab>
-<Tab value="Windows">
-
-Write a setting into the persistent driver config. Values take effect immediately. Pass each setting as its own field.
-
-Known keys:
-- `capture_mode` (string: `vision` | `ax` | `som`); DEPRECATED and ignored; `get_window_state` always returns both the UIA tree and a screenshot. Still accepted/persisted for back-compat but has no effect.
-- `max_image_dimension` (integer)
-- `experimental_pip` (boolean; persisted to config.json, applies on next daemon restart: Windows backend stubbed today, see issue #1729)
-- `experimental_pip_geometry` (string `WxH` or `WxH+X+Y`; persisted; applies on next daemon restart)
-
-- `cursor.motion.style`, `cursor.motion.timing`, `cursor.motion.effects.<name>` (`on`, `off`, or `default`): saved default cursor motion for sessions started afterwards. `cursor.motion: "default"` clears every saved cursor motion default.
-- `cursor.badges` (`minimal` default, `verbose`, or `off`): agent cursor badge; applies to every cursor at once.
-
-Returns the full updated config in the same shape as `get_config`.
-
-**Windows parameters**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="set_config--windows--capture_mode"></span>`capture_mode` | `"ax" \| "vision"` | | DEPRECATED and ignored: get_window_state always returns both the UIA tree and a screenshot. Still accepted/persisted for back-compat but has no effect. ("som"/"screenshot" still decode as deprecated aliases.). |
-| <span id="set_config--windows--experimental_pip"></span>`experimental_pip` | `boolean` | | Enables PiP preview (applies next restart). |
-| <span id="set_config--windows--experimental_pip_geometry"></span>`experimental_pip_geometry` | `string` | | PiP window size + optional position. |
-
-</Tab>
-</Tabs>
-
-**Parameters on every platform**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="set_config--cursor-badges"></span>`cursor.badges` | `"minimal" \| "verbose" \| "off" \| "default"` | | Agent cursor badge. minimal (default): no badge at rest; a brief chip for a foreground moment or a key combo, and the session name on hover or when two or more agent cursors are on screen. verbose: the earlier badge with the session name and delivery/target chips on every action. off: no badge. Applies immediately to every cursor. |
-| <span id="set_config--cursor-motion"></span>`cursor.motion` | `"default"` | | Pass `default` to clear every saved cursor motion default. |
-| <span id="set_config--cursor-motion-effects-glow"></span>`cursor.motion.effects.glow` | `"on" \| "off" \| "default"` | | Saved default for the `glow` cursor effect: on, off, or default (the style's own). Omit the key to leave it unchanged. |
-| <span id="set_config--cursor-motion-effects-magnet"></span>`cursor.motion.effects.magnet` | `"on" \| "off" \| "default"` | | Saved default for the `magnet` cursor effect: on, off, or default (the style's own). Omit the key to leave it unchanged. |
-| <span id="set_config--cursor-motion-effects-ripple"></span>`cursor.motion.effects.ripple` | `"on" \| "off" \| "default"` | | Saved default for the `ripple` cursor effect: on, off, or default (the style's own). Omit the key to leave it unchanged. |
-| <span id="set_config--cursor-motion-effects-squish"></span>`cursor.motion.effects.squish` | `"on" \| "off" \| "default"` | | Saved default for the `squish` cursor effect: on, off, or default (the style's own). Omit the key to leave it unchanged. |
-| <span id="set_config--cursor-motion-effects-trail"></span>`cursor.motion.effects.trail` | `"on" \| "off" \| "default"` | | Saved default for the `trail` cursor effect: on, off, or default (the style's own). Omit the key to leave it unchanged. |
-| <span id="set_config--cursor-motion-style"></span>`cursor.motion.style` | `"signature_arc" \| "spring_settle" \| "magnetic" \| "comet_swoop" \| "adaptive" \| "classic"` | | Saved default cursor motion style for new sessions. Overridden by start_session cursor_motion and set_agent_cursor_motion; reduced motion always wins. Built-in default: signature_arc. |
-| <span id="set_config--cursor-motion-timing"></span>`cursor.motion.timing` | `"native" \| "fitts" \| "fixed" \| "relaxed" \| "steady" \| "calm" \| "deliberate"` | | Saved default cursor move timing for new sessions. Built-in default: steady (a 600 ms floor on every move). |
-| <span id="set_config--max_image_dimension"></span>`max_image_dimension` | `integer` | | Max dimension for screenshot resizing (0 = no limit). |
-| <span id="set_config--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
-
-## `check_permissions`
-
-Effect: mutating, idempotent. Platforms: macOS, Linux, Windows.
-
-<Tabs items={['macOS', 'Linux', 'Windows']} groupId="platform" persist>
-<Tab value="macOS">
-
-Report TCC permission status for Accessibility and Screen Recording. By default also raises the system permission dialogs for any missing grants: Apple's request APIs are no-ops when the grant is already active, so this is safe to call repeatedly. Pass &#123;"prompt": false&#125; for a purely read-only status check.
-
-Returns: `accessibility` + `screen_recording` (booleans from the TCC preflight APIs), `screen_recording_capturable` (a live ScreenCaptureKit probe when `prompt` is true; null on read-only calls), `direct_capture_status` (`ready`, `unavailable`, `timed_out`, `probe_failed`, `blocked_by_screen_recording`, or `not_checked`), `direct_capture_error` (a structured timeout/probe failure when applicable), `direct_capture_verification` (validated source, UTC time, and bundle identity from an explicit grant probe), and `source` (which TCC identity the booleans reflect: the CuaDriver daemon vs the launching terminal/IDE). macOS attributes grants to the responsible process, so a standalone call from a terminal reports the terminal's grants, not the driver's. The prompt-capable ScreenCaptureKit probe never runs when `prompt` is false. Pass `probe_direct_capture:false` with `prompt:true` to register/request only the two required TCC grants before separately explaining Tahoe's direct-capture consent. How to get them granted: `get_guide({topic:"permissions"})`.
-
-**macOS parameters**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="check_permissions--macos--probe_direct_capture"></span>`probe_direct_capture` | `boolean` | | When prompting and Screen Recording is granted, also run the live ScreenCaptureKit probe that may raise Tahoe's direct-capture consent. Default true. Set false for a staged Accessibility/Screen Recording request. |
-| <span id="check_permissions--macos--prompt"></span>`prompt` | `boolean` | `false` | Raise the system permission prompts for missing grants. Default false; only a trusted host setup route may set true. |
-
-</Tab>
-<Tab value="Linux">
-
-Check required permissions for cua-driver-rs on Linux. How to get them granted: `get_guide({topic:"permissions"})`.
-
-**Linux parameters**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="check_permissions--linux--prompt"></span>`prompt` | `boolean` | | Ignored: Linux has no permission prompts. |
-
-</Tab>
-<Tab value="Windows">
-
-Check required permissions for cua-driver-rs on Windows. How to get them granted: `get_guide({topic:"permissions"})`.
-
-**Windows parameters**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="check_permissions--windows--prompt"></span>`prompt` | `boolean` | | Ignored: Windows has no permission prompts. |
-
-</Tab>
-</Tabs>
-
-**Parameters on every platform**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="check_permissions--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
-
-## `health_report`
-
-Single-call end-to-end driver diagnostics. Designed to let downstream consumers ship one stable call instead of stitching together check_permissions, doctor, version, bundle attribution, and platform capability status. On macOS, prompt-capable direct capture is deliberately skipped. For standalone CuaDriver, use `cua-driver permissions grant` to verify it explicitly. For an embedded or linked driver, use the host's permission flow for the app or executable macOS attributes this process's permission request to; the standalone command does not verify the host's capture readiness. cua-driver owns the health model; consumers stay thin.
-
-Input: all optional:
- &#123;
- "include": ["&lt;check_name&gt;", ...], // run only these
- "skip": ["&lt;check_name&gt;", ...] // skip these
- &#125;
-If both are given, `include` wins.
-
-Canonical check names:
- macOS : binary_version, platform_supported, session_active,
- bundle_identity, tcc_accessibility, tcc_screen_recording,
- ax_capability, screen_capture_capability, windowserver_connection
- Windows: binary_version, platform_supported, session_active,
- ax_capability (via UIA), screen_capture_capability (via DXGI)
- Linux : binary_version, platform_supported, session_active,
- ax_capability (via AT-SPI), screen_capture_capability (via X11)
-
-Output: stable contract, schema_version="1":
- &#123;
- "schema_version": "1",
- "platform": "darwin" | "win32" | "linux",
- "driver_version": "&lt;semver&gt;",
- "overall": "ok" | "degraded" | "failed",
- "checks": [
- &#123;
- "name": "&lt;one of the canonical names above&gt;",
- "status": "pass" | "fail" | "skip",
- "message": "&lt;one-line summary, always present&gt;",
- "hint": "&lt;remediation step, present when status=fail&gt;",
- "data": &#123; /* check-specific structured fields */ &#125;
- &#125;,
- ...
- ]
- &#125;
-
-`overall` rules:
- - `ok` : every non-skipped check passes
- - `degraded`: at least one non-core check fails (binary is still usable)
- - `failed` : any core check fails (binary_version, platform_supported, session_active)
-
-Stability: schema_version="1" is the contract. Future breaking changes will be `"2"`. Adding new check names under the same schema_version is non-breaking; consumers must tolerate unknown check names.
-
-Effect: read-only, idempotent. Platforms: macOS, Linux, Windows.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="health_report--include"></span>`include` | `string[]` | | Only run these checks (canonical names). Wins over `skip`. |
-| <span id="health_report--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
-| <span id="health_report--skip"></span>`skip` | `string[]` | | Skip these checks (canonical names). Ignored when `include` is set. |
-
-## `check_for_update`
-
-Check the saved stable/nightly Cua Driver channel for a release on GitHub. Returns current and selected channels, current and latest versions, an `update_available` boolean, the install one-liner, and the release notes URL. Read-only: never installs. Pacman-owned Linux executables return package-manager guidance without checking GitHub. Mirror of `cua-driver check-update --json`.
-
-Effect: read-only, idempotent. Platforms: macOS, Linux, Windows.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="check_for_update--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
-
-## `install_extension`
-
-Preview or install one Driver-managed optional extension. The first call without confirm returns the exact signed artifact, destination, license, source, and trust plan without mutation. Re-call with confirm=true to perform that exact verified installation.
-
-Effect: destructive. Platforms: macOS, Linux, Windows.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="install_extension--confirm"></span>`confirm` | `boolean` | | Install the previewed extension. Omit or false for a read-only plan. |
-| <span id="install_extension--name"></span>`name` | `"perception"` | required | Extension to preview or install. Only perception (the local visual-region parser used by parse_visual_regions) is available. |
-| <span id="install_extension--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
-
-**Example arguments**
-
-```json
-{"name":"perception"}
-```
-
-## `get_guide`
-
-Read Cua Driver guidance on demand, taken from the guide bundled with this driver (no skill install needed). Topics: overview, drag, browser, permissions, batching, menus. Call with no topic to list them. Read-only.
-
-Effect: read-only, idempotent. Platforms: macOS, Linux, Windows.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="get_guide--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
-| <span id="get_guide--topic"></span>`topic` | `string` | | One of: overview, drag, browser, permissions, batching, menus. Omit to list the topics. |
diff --git a/docs/content/docs/cua-driver/reference/mcp-tools/meta.json b/docs/content/docs/cua-driver/reference/mcp-tools/meta.json
index 0a8e56fbbf..26d55859e2 100644
--- a/docs/content/docs/cua-driver/reference/mcp-tools/meta.json
+++ b/docs/content/docs/cua-driver/reference/mcp-tools/meta.json
@@ -2,21 +2,9 @@
"title": "MCP tools",
"pages": [
"index",
- "apps-and-windows",
- "window-state",
- "screen",
- "click",
- "double-and-right-click",
- "pointer",
- "keyboard",
- "keys-and-shortcuts",
- "values-and-clipboard",
- "batch",
- "page",
- "browser-input",
- "sessions",
- "agent-cursor",
- "recording",
- "maintenance"
+ "apps-windows-and-screen",
+ "click-and-type",
+ "pointer-cursor-and-browser",
+ "batch-recording-and-settings"
]
}
diff --git a/docs/content/docs/cua-driver/reference/mcp-tools/page.mdx b/docs/content/docs/cua-driver/reference/mcp-tools/page.mdx
deleted file mode 100644
index 9636d0b2b3..0000000000
--- a/docs/content/docs/cua-driver/reference/mcp-tools/page.mdx
+++ /dev/null
@@ -1,114 +0,0 @@
----
-title: "Page tools"
-description: "Read and act on web pages, and prepare and navigate browsers."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-driver
- Source: cua-driver dump-docs --type mcp (macOS, Linux and Windows registries)
- Version: 0.36.0
-*/}
-
-| Tool | Description | Platforms |
-| --- | --- | --- |
-| [`page`](#page) | Legacy browser compatibility tool. | macOS, Linux, Windows |
-| [`get_browser_state`](#get_browser_state) | Read-only browser inspection. | macOS, Linux, Windows |
-| [`browser_prepare`](#browser_prepare) | Attach the browser tools to a browser. | macOS, Linux, Windows |
-| [`browser_navigate`](#browser_navigate) | Navigate one tab of an exactly-bound browser target to a new URL (http/https/about only). | macOS, Linux, Windows |
-
-Served by `cua-driver mcp`; see [MCP tools](/cua-driver/reference/mcp-tools) for every tool.
-
-## `page`
-
-Legacy browser compatibility tool. Prefer get_browser_state and the typed browser_* tools for exact targeting, endpoint ownership, and consent. Read-only get_text and query_dom remain available by default. Mutating actions require the daemon operator to set CUA_DRIVER_ENABLE_LEGACY_PAGE_MUTATIONS=1 before daemon startup (restart the daemon after changing it); this escape hatch does not provide the typed browser surface's exact binding or existing-profile grant guarantees. Supports Chrome, Brave, Edge, Safari (via AppleScript on macOS), Electron apps (via CDP), Chromium/Firefox on Windows (via UIA for read; CDP for execute_javascript when --remote-debugging-port is set), and WKWebView/Tauri/AT-SPI fallbacks.
-
-Actions:
-- execute_javascript: Run JS and return the result.
-- get_text: Extract visible text from the page.
-- query_dom: Find elements matching a CSS selector.
-- click_element: Click a CSS-selected element AND animate the agent cursor to its on-screen center first (so the user sees what the agent is doing). Prefer over `execute_javascript('el.click()')` whenever you want visible cursor feedback.
-- insert_text: Insert `text` at whatever currently holds DOM focus in one native operation (CDP Input.insertText); no synthesized key events, but more durable than a one-shot execute_javascript write since rich-text editors already have to treat it like an IME commit. Try this before type_keystrokes on a contenteditable that discarded an execute_javascript write. Click/focus the target field first.
-- type_keystrokes: Type `text` via real per-character keystroke events into whatever currently holds DOM focus. Slower than insert_text but the most durable rung: use it when insert_text also gets discarded, or the editor's own keydown/keyup handlers need to see real keys. Click/focus the target field first.
-- enable_javascript_apple_events: macOS-only; patch the browser's Preferences to allow JS from Apple Events (Chrome/Brave/Edge, requires user confirmation and a browser restart).
-
-Effect: mutating. Platforms: macOS, Linux, Windows.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="page--action"></span>`action` | `"execute_javascript" \| "get_text" \| "query_dom" \| "click_element" \| "insert_text" \| "type_keystrokes" \| "enable_javascript_apple_events"` | required | Action to perform. |
-| <span id="page--attributes"></span>`attributes` | `string[]` | | Element attributes to include in query_dom results. |
-| <span id="page--bundle_id"></span>`bundle_id` | `string` | | Bundle ID of the browser. Required for enable_javascript_apple_events (macOS only). |
-| <span id="page--cdp_port"></span>`cdp_port` | `integer` | | Optional, for execute_javascript/insert_text/type_keystrokes: use this exact CDP port instead of auto-discovering one from pid. Needed when the port was opened via the browser's own remote-debugging toggle rather than a launch-time flag, since that path may not answer the auto-discovery probe. Range: 1 to 65535. |
-| <span id="page--css_selector"></span>`css_selector` | `string` | | CSS selector for query_dom (e.g. 'a', 'button', 'input', 'h1'-'h6', 'p', 'img', 'select', '*'). |
-| <span id="page--javascript"></span>`javascript` | `string` | | JavaScript to execute. Required for execute_javascript. |
-| <span id="page--pid"></span>`pid` | `integer` | | Target process ID. |
-| <span id="page--selector"></span>`selector` | `string` | | CSS selector for click_element (e.g. 'button.submit', '#login a'). |
-| <span id="page--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
-| <span id="page--target_url_contains"></span>`target_url_contains` | `string` | | Optional, for execute_javascript/insert_text/type_keystrokes: require exactly one browser tab whose URL contains this substring. Use this on a multi-tab browser: there's no built-in link between window_id and which tab a CDP call reaches. |
-| <span id="page--text"></span>`text` | `string` | | Text to insert or type. Required for insert_text and type_keystrokes. The target field must already have DOM focus (click/focus it first). |
-| <span id="page--user_has_confirmed_enabling"></span>`user_has_confirmed_enabling` | `boolean` | | Must be true to proceed with enable_javascript_apple_events. This will quit and relaunch the browser. |
-| <span id="page--window_id"></span>`window_id` | `integer` | | Target window ID from list_windows. |
-
-**Example arguments**
-
-```json
-{"action":"execute_javascript"}
-```
-
-## `get_browser_state`
-
-Read-only browser inspection. Mode 1 (bind): pass pid + window_id of a native browser window to classify it, correlate it to a CDP target (exact-or-refuse), and mint a session-scoped target id plus tab ids. Mode 2 (snapshot): pass target_id + tab_id. The dom_refs_v1 compatibility format returns composed DOM refs. semantic_v2 joins accessibility, DOM, layout, and viewport state; ranks visible content before retained/offscreen state; and returns a semantic outline, typed action refs, content refs, scoped reads, and opaque continuation. Never performs setup: a browser that is not attached yet refuses with browser_consent_required or browser_requires_setup, and detail.next_call names the browser_prepare call that attaches it. Use this route for any web page in Chrome, Edge or Brave; desktop pointer tools move the user's pointer. Setup and recovery: `get_guide({topic:"browser"})`.
-
-Effect: read-only, idempotent. Platforms: macOS, Linux, Windows.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="get_browser_state--continuation"></span>`continuation` | `string` | | Opaque continuation minted by an earlier semantic_v2 response. |
-| <span id="get_browser_state--include_screenshot"></span>`include_screenshot` | `boolean` | `false` | Capture the exact tab viewport as PNG through CDP without selecting the tab or foregrounding its native window. The request refuses if capture cannot be completed. |
-| <span id="get_browser_state--pid"></span>`pid` | `integer` | | Native browser process id (bind mode). |
-| <span id="get_browser_state--query"></span>`query` | `string` | | Read-only semantic match over role, accessible name, and visible text. |
-| <span id="get_browser_state--scope_ref"></span>`scope_ref` | `string` | | Current semantic/content ref whose subtree should be observed. |
-| <span id="get_browser_state--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. Browser targets, tabs, and refs belong to the resolved lifecycle session. |
-| <span id="get_browser_state--snapshot_format"></span>`snapshot_format` | `"dom_refs_v1" \| "semantic_v2"` | | Versioned snapshot contract. dom_refs_v1 remains the compatibility default. |
-| <span id="get_browser_state--tab_id"></span>`tab_id` | `string` | | Opaque tab id from get_browser_state (session-scoped). |
-| <span id="get_browser_state--target_id"></span>`target_id` | `string` | | Opaque browser target id minted by get_browser_state (session-scoped; never a CDP id). |
-| <span id="get_browser_state--window_id"></span>`window_id` | `integer` | | Native window id owned by pid (bind mode). |
-
-## `browser_prepare`
-
-Attach the browser tools to a browser. For a page in the user's running Chrome, Edge or Brave, call it once with pid, window_id, session and strategy &#123;"kind":"existing_profile"&#125; when get_browser_state refuses with browser_consent_required or browser_requires_setup; then call get_browser_state again and act with browser_click, browser_type or browser_pointer. It attaches, or refuses with nothing changed and says why. Explicitly prepare an owned DevTools endpoint for a browser. pid is required for an existing process or existing-profile attachment, and optional only for allow_launch=true with an isolated profile. Existing endpoints are detected without side effects. Acting setup for an isolated profile follows the runtime permission mode and optional capability manifest. It requires allow_launch=true, launches a separate browser, and never copies, modifies, or terminates the requested user profile. Without pid, only a platform-attested system Chrome/Edge installation (or a root-owned package payload on Linux) is eligible; redirects and user-controlled locations fail closed. Existing-profile attachment is explicit and follows the runtime's immutable permission mode: standard requires an explicit --grant existing-profile launch grant or an embedding authorization host, bounded requires a launch-approved exact resource manifest, and unrestricted requires explicit trusted startup risk acceptance. Ordinary MCP transport approval never proves profile authorization. On proven platforms, an authorized request also permits one bounded exact-window setup: open the recognized browser product's fixed remote-debugging page, toggle its uniquely matched per-instance checkbox, prove the PID-owned loopback endpoint, and close the temporary tab. Every visible effect is reported; ambiguity is refused. Where attaching would bring the browser in front of the user's app (macOS Chrome shows its own remote-debugging prompt in front whenever the driver opens a new browser connection; sessions for the same browser share one approved connection, kept for up to 30 minutes idle and 8 hours in total, so later sessions do not prompt again), existing-profile attachment refuses with background_unavailable unless delivery_mode is "foreground" (the app that was in front is brought back afterwards) or the browser window is on another Space than the user's, where it attaches in the background while the driver reverts the browser's own brief activations. A driver-owned isolated launch result carries an advisory lifecycle object: the browser process ends with the calling session after idle_expires_in_seconds without session activity, an isolated_named profile persists after the session and an isolated_new profile does not, and explicit end, disconnect, revocation or shutdown end it earlier. Setup and recovery: `get_guide({topic:"browser"})`.
-
-Effect: destructive. Platforms: macOS, Linux, Windows.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="browser_prepare--allow_launch"></span>`allow_launch` | `boolean` | | Allow a separate driver-owned isolated Chromium process to be launched (default false). |
-| <span id="browser_prepare--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | `"background"` | Existing-profile attachment only. background (default) attaches in the background when the browser window is on another Space than the user's, and otherwise refuses with background_unavailable, before any visible effect, where attaching would bring the browser in front of the user's app. foreground accepts that, for a screen nobody else is using or when the user agreed; the app that was in front is brought back afterwards. |
-| <span id="browser_prepare--pid"></span>`pid` | `integer` | | Browser process id to prepare. Required except for a driver-owned isolated_new/isolated_named launch with allow_launch=true. |
-| <span id="browser_prepare--profile"></span>`profile` | `object` | | Driver-owned isolated Chromium profile to launch with allow_launch=true. mode=isolated_new creates a fresh throwaway profile; mode=isolated_named reuses the named driver-owned profile. Never an existing user profile. |
-| <span id="browser_prepare--profile-mode"></span>`profile.mode` | `"isolated_new" \| "isolated_named"` | | |
-| <span id="browser_prepare--profile-name"></span>`profile.name` | `string` | | Required only for isolated_named; 1-64 path-safe ASCII characters. |
-| <span id="browser_prepare--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. Browser targets, tabs, and refs belong to the resolved lifecycle session. |
-| <span id="browser_prepare--strategy"></span>`strategy` | `object` | | Attach to an already-running browser instead of launching one. Pass an object, &#123;"kind":"existing_profile"&#125;, not a string. kind=existing_profile attaches to the user's running profile at pid/window_id under the runtime's profile authorization. |
-| <span id="browser_prepare--strategy-kind"></span>`strategy.kind` | `"existing_profile"` | | |
-| <span id="browser_prepare--window_id"></span>`window_id` | `integer` | | Exact native window approval anchor; required for strategy.kind=existing_profile. |
-
-## `browser_navigate`
-
-Navigate one tab of an exactly-bound browser target to a new URL (http/https/about only). Refused for heuristic bindings. Navigation invalidates all p&lt;snapshot&gt;:&lt;index&gt; refs for the tab.
-
-Effect: mutating. Platforms: macOS, Linux, Windows.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="browser_navigate--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. Browser targets, tabs, and refs belong to the resolved lifecycle session. |
-| <span id="browser_navigate--tab_id"></span>`tab_id` | `string` | required | Opaque tab id from get_browser_state (session-scoped). |
-| <span id="browser_navigate--target_id"></span>`target_id` | `string` | required | Opaque browser target id minted by get_browser_state (session-scoped; never a CDP id). |
-| <span id="browser_navigate--url"></span>`url` | `string` | required | Destination URL (http:, https:, or about:). |
-
-**Example arguments**
-
-```json
-{"target_id":"<target_id>","tab_id":"<tab_id>","url":"<url>"}
-```
diff --git a/docs/content/docs/cua-driver/reference/mcp-tools/pointer-cursor-and-browser.mdx b/docs/content/docs/cua-driver/reference/mcp-tools/pointer-cursor-and-browser.mdx
new file mode 100644
index 0000000000..e3804b05e0
--- /dev/null
+++ b/docs/content/docs/cua-driver/reference/mcp-tools/pointer-cursor-and-browser.mdx
@@ -0,0 +1,734 @@
+---
+title: "Pointer, cursor and browser"
+description: "Drag, scroll and move the pointer; the agent cursor; web pages and browser input."
+---
+
+{/*
+ AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
+ Generated by: pnpm --dir docs docs:generate:cua-driver
+ Source: cua-driver dump-docs --type mcp (macOS, Linux and Windows registries)
+ Version: 0.36.0
+*/}
+
+import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
+
+| Tool | Description | Platforms |
+| --- | --- | --- |
+| [`drag`](#drag) | Press-drag-release gesture from (from_x, from_y) to (to_x, to_y) in window-local screenshot pixels: the same space get_window_state returns. | macOS, Linux, Windows |
+| [`scroll`](#scroll) | Scroll the target pid. | macOS, Linux, Windows |
+| [`move_cursor`](#move_cursor) | Move a cursor to (x, y). | macOS, Linux, Windows |
+| [`mouse_button_down`](#mouse_button_down) | Press and hold a mouse button at (x,y) via background X11 delivery. | Linux |
+| [`mouse_button_up`](#mouse_button_up) | Release a previously-held mouse button via background X11 delivery. | Linux |
+| [`mouse_drag`](#mouse_drag) | Move a previously-held mouse button to a new point via background X11 delivery. | Linux |
+| [`parallel_mouse_drag`](#parallel_mouse_drag) | Run multiple mouse drag gestures concurrently via Linux MPX/XI2 virtual master pointers. | Linux |
+| [`set_agent_cursor_enabled`](#set_agent_cursor_enabled) | Show or hide the agent cursor owned by a session. | macOS, Linux, Windows |
+| [`set_agent_cursor_motion`](#set_agent_cursor_motion) | Configure the movement style, timing, effects and visibility timing for a session cursor. | macOS, Linux, Windows |
+| [`set_agent_cursor_theme`](#set_agent_cursor_theme) | Select an already-installed cursor theme for a session. | macOS, Linux, Windows |
+| [`get_agent_cursor_state`](#get_agent_cursor_state) | Return the session cursor's theme, semantic playback, position, visibility, and motion. | macOS, Linux, Windows |
+| [`page`](#page) | Legacy browser compatibility tool. | macOS, Linux, Windows |
+| [`get_browser_state`](#get_browser_state) | Read-only browser inspection. | macOS, Linux, Windows |
+| [`browser_prepare`](#browser_prepare) | Attach the browser tools to a browser. | macOS, Linux, Windows |
+| [`browser_navigate`](#browser_navigate) | Navigate one tab of an exactly-bound browser target to a new URL (http/https/about only). | macOS, Linux, Windows |
+| [`browser_click`](#browser_click) | Click a page element (by ref) or viewport coordinates in an exactly-bound tab. | macOS, Linux, Windows |
+| [`browser_type`](#browser_type) | Type text into an exactly-bound tab via the Input domain. | macOS, Linux, Windows |
+| [`browser_select`](#browser_select) | Select one option of a native HTML &lt;select&gt; ref on an exactly-bound tab without opening its popup. | macOS, Linux, Windows |
+| [`browser_pointer`](#browser_pointer) | Perform hover, right-click, double-click, scroll, or drag in an exactly-bound browser tab. | macOS, Linux, Windows |
+| [`browser_dialog`](#browser_dialog) | Inspect or resolve a page-owned JavaScript alert, confirm, prompt, or beforeunload dialog on one exactly-bound tab. | macOS, Linux, Windows |
+| [`browser_set_input_files`](#browser_set_input_files) | Assign one or more explicit absolute local files to an exact live &lt;input type=file&gt; ref through CDP. | macOS, Linux, Windows |
+| [`browser_download`](#browser_download) | Trigger one download through an exact live browser ref and save it inside an explicitly approved directory. | macOS, Linux, Windows |
+
+Served by `cua-driver mcp`; see [MCP tools](/cua-driver/reference/mcp-tools) for every tool.
+
+## Pointer tools
+
+Drag, scroll, move the pointer, and press or release buttons.
+
+### `drag`
+
+Effect: destructive. Platforms: macOS, Linux, Windows.
+
+<Tabs items={['macOS', 'Linux', 'Windows']} groupId="platform" persist>
+<Tab value="macOS">
+
+Press-drag-release gesture from (from_x, from_y) to (to_x, to_y) in window-local screenshot pixels: the same space get_window_state returns. Top-left origin of the target's window.
+
+Use for: marquee/lasso selection, drag-and-drop, resizing via a handle, scrubbing a slider, repositioning a panel.
+
+`duration_ms` (default 500) is the wall-clock budget for the path between mouse-down and mouse-up; `steps` (default 20) is the number of intermediate mouseDragged events linearly interpolated along the path. Increase both for slower, more human drags; decrease for snap gestures.
+
+`modifier` keys (cmd/shift/option/ctrl) are held across the entire gesture.
+
+When `from_zoom` is true, coordinates are in the last zoom image for this pid; the driver maps them back to window coordinates before dispatching.
+
+A window-scoped drag (pid + window_id) runs in the background by default: the gesture is posted to that window, the real pointer does not move, and the user's frontmost window keeps focus. It works for controls that follow the drag events: sliders, canvases, and pointer-event widgets on web pages in Chrome. In an Electron window the driver sends the gesture from the app's main process, so pointer-capture widgets and HTML5 drag and drop also drop there. Elsewhere, a drag that starts a macOS drag-and-drop session (reordering a list by drag and drop, moving a file, HTML5 draggable content) cannot drop in the background, because macOS tracks those with the real pointer; the driver detects it, releases at once and returns background_unavailable with reason drag_and_drop_session. For a page in a browser tab already bound with get_browser_state, browser_pointer action:"drag" drives the same gesture through CDP with page refs. The result is not driver-verified: confirm with a screenshot or the accessibility tree, and only if nothing changed retry with delivery_mode:"foreground", which briefly fronts the window and moves the physical pointer. Limits and fallbacks: `get_guide({topic:"drag"})`.
+
+**macOS parameters**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="drag--macos--button"></span>`button` | `"left" \| "right" \| "middle"` | | Mouse button used for the drag. Default: left. |
+| <span id="drag--macos--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | | Window-scoped drag on macOS: "background" (default) posts the press, drag and release to the exact window (window_id required) without moving the pointer, raising the window or taking the user's focus. "foreground" briefly fronts the window, drives the physical pointer through the gesture, then restores the prior frontmost app; use it only when a background drag had no effect. Desktop scope ignores this field. |
+| <span id="drag--macos--duration_ms"></span>`duration_ms` | `integer` | | Wall-clock duration of the drag path between mouseDown and mouseUp. Default: 500. Range: 0 to 10000. |
+| <span id="drag--macos--from_x"></span>`from_x` | `number` | required | Drag-start X in window-local screenshot pixels. Top-left origin. |
+| <span id="drag--macos--from_y"></span>`from_y` | `number` | required | Drag-start Y in window-local screenshot pixels. Top-left origin. |
+| <span id="drag--macos--from_zoom"></span>`from_zoom` | `boolean` | | When true, coordinates are in the last zoom image for this pid; driver maps back to window coordinates. |
+| <span id="drag--macos--modifier"></span>`modifier` | `string[]` | | Modifier keys held across the entire gesture: cmd/shift/option/ctrl. |
+| <span id="drag--macos--pid"></span>`pid` | `integer` | | Target process ID. |
+| <span id="drag--macos--scope"></span>`scope` | `"window" \| "desktop"` | `"window"` | Use desktop with no pid/window_id for native get_desktop_state screenshot coordinates. |
+| <span id="drag--macos--steps"></span>`steps` | `integer` | | Number of intermediate mouseDragged events linearly interpolated along the path. Default: 20. Range: 1 to 200. |
+| <span id="drag--macos--to_x"></span>`to_x` | `number` | required | Drag-end X in window-local screenshot pixels. |
+| <span id="drag--macos--to_y"></span>`to_y` | `number` | required | Drag-end Y in window-local screenshot pixels. |
+| <span id="drag--macos--window_id"></span>`window_id` | `integer` | | CGWindowID for the window the pixel coordinates were measured against. Optional only when pid owns exactly one eligible top-level window; otherwise the action refuses with ambiguous_window_target. |
+
+</Tab>
+<Tab value="Linux">
+
+Press-drag-release gesture from (from_x, from_y) to (to_x, to_y) in window-local screenshot pixels. Background delivery on X11 is one real held gesture on the session's virtual master pointer (path mpx_pointer: press, interpolated motion, release); it lands on GTK/VCL/Qt/Chromium; a point covered by another application's window is refused (target_occluded), one covered by this app's own dialog is retargeted to it. Headless servers fall back to XSendEvent. duration_ms (default 500), steps (default 20). No focus steal. Limits and fallbacks: `get_guide({topic:"drag"})`.
+
+**Linux parameters**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="drag--linux--button"></span>`button` | `"left" \| "right" \| "middle"` | | Mouse button. Default "left". |
+| <span id="drag--linux--coordinate_frame"></span>`coordinate_frame` | `"window" \| "desktop"` | | Frame of x/y (and from_x/from_y/to_x/to_y). Default "window": window-local screenshot pixels as returned by get_window_state. "desktop": full-screen pixels as returned by get_desktop_state, translated to the target window. Passing scope:"desktop" together with pid/window_id means the same thing. |
+| <span id="drag--linux--cursor_id"></span>`cursor_id` | `string` | | Optional multi-cursor instance id. Default: 'default'. |
+| <span id="drag--linux--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | `"background"` | Input delivery mode. 'background' (default) never activates or raises the target window. On X11 it injects via XTEST / the XInput2 master pointer (no focus steal). On Wayland it goes through libei + xdg-desktop-portal, which injects to the compositor's input focus: Wayland's security model has no per-window background targeting, so a specific non-focused window cannot be aimed at; when no libei backend is available the tool returns a structured background_unavailable error. 'foreground' is the explicit escalation: activate the target (X11 _NET_ACTIVE_WINDOW; Wayland compositor activate), inject, then restore the prior active window; a brief focus swap unless the target was already active. Matches the macOS / Windows delivery_mode surface. |
+| <span id="drag--linux--duration_ms"></span>`duration_ms` | `integer` | | Total drag duration. Default: 500. Range: 0 to 10000. |
+| <span id="drag--linux--from_x"></span>`from_x` | `number` | required | Drag start X: window-local pixels of the target window's own get_window_state screenshot; pass scope:"desktop" for get_desktop_state pixels. |
+| <span id="drag--linux--from_y"></span>`from_y` | `number` | required | Drag start Y (same frame as from_x). |
+| <span id="drag--linux--from_zoom"></span>`from_zoom` | `boolean` | | Set true after a zoom call to auto-translate zoom-image pixel coordinates back to full-window space. |
+| <span id="drag--linux--modifier"></span>`modifier` | `string[]` | | Modifier keys held during the action: cmd, shift, option/alt, ctrl. |
+| <span id="drag--linux--pid"></span>`pid` | `integer` | | Target process ID. Required unless scope is "desktop". |
+| <span id="drag--linux--scope"></span>`scope` | `"window" \| "desktop"` | `"window"` | Use "desktop" with no pid/window_id for get_desktop_state screen coordinates. Default "window". |
+| <span id="drag--linux--steps"></span>`steps` | `integer` | | Intermediate MotionNotify events. Default: 20. Range: 1 to 200. |
+| <span id="drag--linux--to_x"></span>`to_x` | `number` | required | Drag end X (same frame as from_x). |
+| <span id="drag--linux--to_y"></span>`to_y` | `number` | required | Drag end Y (same frame as from_x). |
+| <span id="drag--linux--window_id"></span>`window_id` | `integer` | | Target window XID. Required. |
+
+</Tab>
+<Tab value="Windows">
+
+Press-drag-release gesture from (from_x, from_y) to (to_x, to_y) in window-local screenshot pixels. duration_ms (default 500) is the wall-clock budget; steps (default 20) interpolates intermediate WM_MOUSEMOVE events along the path. No focus steal. After a zoom call, pass from_zoom=true. Drags that start on a window caption / title bar or resize border (i.e. moving or resizing the window itself) cannot be delivered in the background, the OS move/resize loop needs real pointer input, so they return background_unavailable; re-issue those with delivery_mode:"foreground". Limits and fallbacks: `get_guide({topic:"drag"})`.
+
+**Windows parameters**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="drag--windows--button"></span>`button` | `"left" \| "right" \| "middle"` | | Mouse button. Default "left". |
+| <span id="drag--windows--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | | Input delivery mode. 'background' (default) never swaps foreground: it routes through UIA Invoke / PostMessage and the window is never raised. For targets whose input stack silently drops posted events (Chromium/Electron content, GTK buttons, VCL/LibreOffice accelerators) the tool returns a structured background_unavailable error rather than fronting. 'foreground' is the explicit escalation: a brief SetForegroundWindow swap + SendInput, restoring the prior foreground afterward. IMPORTANT: 'background' is not a hint to weigh; it is the mandatory first attempt. Do NOT pass 'foreground' preemptively because a target 'looks like' GTK/Chromium/Electron; the DRIVER decides when background is impossible and tells you so via a background_unavailable error (or a verified no-op). Only THEN re-issue the same action with 'foreground'. The lists above are the driver's detectors, not a checklist for you to front on a guess: fronting up-front needlessly steals the user's focus and is a bug, not a shortcut. Matches the macOS delivery_mode surface. |
+| <span id="drag--windows--duration_ms"></span>`duration_ms` | `integer` | | Wall-clock duration of drag path. Default: 500. Range: 0 to 10000. |
+| <span id="drag--windows--from_x"></span>`from_x` | `number` | required | Drag-start X in window-local screenshot pixels. |
+| <span id="drag--windows--from_y"></span>`from_y` | `number` | required | Drag-start Y in window-local screenshot pixels. |
+| <span id="drag--windows--from_zoom"></span>`from_zoom` | `boolean` | | When true, coordinates are in the last zoom image for this pid. |
+| <span id="drag--windows--modifier"></span>`modifier` | `string[]` | | Modifier keys held during the action: cmd, shift, option/alt, ctrl. |
+| <span id="drag--windows--pid"></span>`pid` | `integer` | | Target process ID. |
+| <span id="drag--windows--scope"></span>`scope` | `"window" \| "desktop"` | | Use desktop with no pid/window_id for screen-absolute coordinates. |
+| <span id="drag--windows--steps"></span>`steps` | `integer` | | Number of intermediate WM_MOUSEMOVE events. Default: 20. Range: 1 to 200. |
+| <span id="drag--windows--to_x"></span>`to_x` | `number` | required | Drag-end X in window-local screenshot pixels. |
+| <span id="drag--windows--to_y"></span>`to_y` | `number` | required | Drag-end Y in window-local screenshot pixels. |
+| <span id="drag--windows--window_id"></span>`window_id` | `integer` | | Target window handle (HWND). Optional: driver picks frontmost window of pid when omitted. |
+
+</Tab>
+</Tabs>
+
+**Parameters on every platform**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="drag--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
+| <span id="drag--target"></span>`target` | `object` | | Preferred per-call target: an exact window (`kind="window"`, `pid`, `window_id`) or the primary desktop (`kind="desktop"`, `display_id="primary"`). |
+| <span id="drag--target-display_id"></span>`target.display_id` | `string` | | Display id. Required when kind is desktop; use "primary". |
+| <span id="drag--target-kind"></span>`target.kind` | `"window" \| "desktop"` | | window requires pid and window_id; desktop requires display_id. |
+| <span id="drag--target-pid"></span>`target.pid` | `integer` | | Process id. Required when kind is window. Minimum: 0. |
+| <span id="drag--target-window_id"></span>`target.window_id` | `integer` | | Window id from list_windows. Required when kind is window. Minimum: 0. |
+
+**Example arguments**
+
+```json
+{"from_x":100,"from_y":200,"to_x":100,"to_y":200}
+```
+
+### `scroll`
+
+Effect: mutating. Platforms: macOS, Linux, Windows.
+
+<Tabs items={['macOS', 'Linux', 'Windows']} groupId="platform" persist>
+<Tab value="macOS">
+
+Scroll the target pid.
+- Targeted wheel: pass `element_token` (preferred) or window-local `x, y`. Sends a real wheel event at that point, so it scrolls whatever is under it. The only way to scroll nested `overflow:auto` regions in web views.
+- Keystroke: no target, just pid + direction. PageDown/PageUp (by='page') or arrows (by='line') on the focused scroller.
+
+Electron/Chromium windows drop background wheel events: there a background scroll reveals the content just past the edge of the scroll container under the target through accessibility (about `amount` notches); `delivery_mode:"foreground"` is the fallback.
+`amount` is wheel notches (targeted) or key repetitions (keystroke).
+
+**macOS parameters**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="scroll--macos--amount"></span>`amount` | `integer` | | Wheel notches or key repetitions, clamped to the maximum. Default 3. Range: 1 to 50. |
+| <span id="scroll--macos--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | | Default "background": no fronting or focus steal. "foreground": briefly front the window, act, restore the prior app; last resort when background did not land. |
+| <span id="scroll--macos--pid"></span>`pid` | `integer` | | Target process ID. Required unless scope is "desktop" or element_token is supplied. |
+| <span id="scroll--macos--scope"></span>`scope` | `"window" \| "desktop"` | `"window"` | "desktop" with x,y and no pid/window_id uses get_desktop_state coordinates. |
+| <span id="scroll--macos--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. |
+| <span id="scroll--macos--window_id"></span>`window_id` | `integer` | | Window ID. Required with x/y; optional with element_token. |
+| <span id="scroll--macos--x"></span>`x` | `number` | | Window-local screenshot X (get_window_state PNG). With y, wheel-scrolls at that point; needs window_id. |
+| <span id="scroll--macos--y"></span>`y` | `number` | | Window-local screenshot Y. |
+
+</Tab>
+<Tab value="Linux">
+
+Scroll the target pid's focused region via XSendEvent Button4/5. direction required; by defaults to line, amount defaults to 3.
+
+**Linux parameters**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="scroll--linux--amount"></span>`amount` | `integer` | | Number of scroll steps. Default: 3. Range: 1 to 50. |
+| <span id="scroll--linux--coordinate_frame"></span>`coordinate_frame` | `"window" \| "desktop"` | | Frame of x/y (and from_x/from_y/to_x/to_y). Default "window": window-local screenshot pixels as returned by get_window_state. "desktop": full-screen pixels as returned by get_desktop_state, translated to the target window. Passing scope:"desktop" together with pid/window_id means the same thing. |
+| <span id="scroll--linux--cursor_id"></span>`cursor_id` | `string` | | Optional multi-cursor instance id. Default: 'default'. |
+| <span id="scroll--linux--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | `"background"` | Input delivery mode. 'background' (default) never activates or raises the target window. On X11 it injects via XTEST / the XInput2 master pointer (no focus steal). On Wayland it goes through libei + xdg-desktop-portal, which injects to the compositor's input focus: Wayland's security model has no per-window background targeting, so a specific non-focused window cannot be aimed at; when no libei backend is available the tool returns a structured background_unavailable error. 'foreground' is the explicit escalation: activate the target (X11 _NET_ACTIVE_WINDOW; Wayland compositor activate), inject, then restore the prior active window; a brief focus swap unless the target was already active. Matches the macOS / Windows delivery_mode surface. |
+| <span id="scroll--linux--pid"></span>`pid` | `integer` | | Target process ID. Required unless scope is "desktop" or element_token is supplied (the token carries the pid). |
+| <span id="scroll--linux--scope"></span>`scope` | `"window" \| "desktop"` | `"window"` | Use "desktop" with x,y and no pid/window_id for get_desktop_state screen coordinates. Default "window". |
+| <span id="scroll--linux--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
+| <span id="scroll--linux--window_id"></span>`window_id` | `integer` | | Window id from list_windows. Required with x/y; optional with element_token (the token carries it). |
+| <span id="scroll--linux--x"></span>`x` | `number` | | Window-local screenshot-pixel X of the scroll target. Pass with y and without element_token. |
+| <span id="scroll--linux--y"></span>`y` | `number` | | Window-local screenshot-pixel Y of the scroll target. Pass with x and without element_token. |
+
+</Tab>
+<Tab value="Windows">
+
+Scroll the target pid's focused region.
+
+Windows transport: WM_VSCROLL / WM_HSCROLL posted to the window; the same events the OS sends when scrollbars or trackpads scroll, so any window that handles scrollbars correctly responds to this. Swift uses synthesized keystrokes (PageDown / arrow keys) via auth-signed SLEventPostToPid; both approaches reach backgrounded windows.
+
+Mapping: `by: "page"` → SB_PAGEDOWN/UP/LEFT/RIGHT × amount; `by: "line"` → SB_LINEDOWN/UP/LEFT/RIGHT × amount.
+
+Note: `element_token` is accepted for cross-platform parity but currently no-op on Windows (UIA SetFocus not wired up yet; same caveat as `press_key`).
+
+**Windows parameters**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="scroll--windows--amount"></span>`amount` | `integer` | | Number of scroll ticks. Default 3. Range: 1 to 50. |
+| <span id="scroll--windows--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | | Input delivery mode. 'background' (default) never swaps foreground: it routes through UIA Invoke / PostMessage and the window is never raised. For targets whose input stack silently drops posted events (Chromium/Electron content, GTK buttons, VCL/LibreOffice accelerators) the tool returns a structured background_unavailable error rather than fronting. 'foreground' is the explicit escalation: a brief SetForegroundWindow swap + SendInput, restoring the prior foreground afterward. IMPORTANT: 'background' is not a hint to weigh; it is the mandatory first attempt. Do NOT pass 'foreground' preemptively because a target 'looks like' GTK/Chromium/Electron; the DRIVER decides when background is impossible and tells you so via a background_unavailable error (or a verified no-op). Only THEN re-issue the same action with 'foreground'. The lists above are the driver's detectors, not a checklist for you to front on a guess: fronting up-front needlessly steals the user's focus and is a bug, not a shortcut. Matches the macOS delivery_mode surface. |
+| <span id="scroll--windows--pid"></span>`pid` | `integer` | | Target process ID for window scope. Optional with element_token (the token carries the pid). Omit with scope=desktop for screen-absolute coordinates from get_desktop_state. |
+| <span id="scroll--windows--scope"></span>`scope` | `"window" \| "desktop"` | `"window"` | Use "desktop" with x,y and no pid/window_id for screen-absolute coordinates from get_desktop_state. Default "window". |
+| <span id="scroll--windows--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
+| <span id="scroll--windows--window_id"></span>`window_id` | `integer` | | HWND of the target window. Omit when element_token is supplied; otherwise auto-resolves the pid's first visible window. |
+| <span id="scroll--windows--x"></span>`x` | `number` | | With pid/window_id: window-local screenshot X used to target a nested scroll surface in foreground mode. Without pid/window_id: screen-absolute X for desktop scope. Must be paired with y. |
+| <span id="scroll--windows--y"></span>`y` | `number` | | With pid/window_id: window-local screenshot Y used to target a nested scroll surface in foreground mode. Without pid/window_id: screen-absolute Y for desktop scope. Must be paired with x. |
+
+</Tab>
+</Tabs>
+
+**Parameters on every platform**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="scroll--by"></span>`by` | `"line" \| "page"` | | Scroll granularity. Default: line. |
+| <span id="scroll--direction"></span>`direction` | `"up" \| "down" \| "left" \| "right"` | required | Scroll direction. |
+| <span id="scroll--element_token"></span>`element_token` | `string` | | Element handle `<snapshot_id>:<row>` from get_window_state: row `[11]` of a read whose snapshot_id is s0000002a is "s0000002a:11" (also in `structuredContent.elements[].element_token`). Returns an explicit stale error naming the current snapshots once a newer read supersedes it. |
+| <span id="scroll--target"></span>`target` | `object` | | Preferred per-call target: an exact window (`kind="window"`, `pid`, `window_id`) or the primary desktop (`kind="desktop"`, `display_id="primary"`). |
+| <span id="scroll--target-display_id"></span>`target.display_id` | `string` | | Display id. Required when kind is desktop; use "primary". |
+| <span id="scroll--target-kind"></span>`target.kind` | `"window" \| "desktop"` | | window requires pid and window_id; desktop requires display_id. |
+| <span id="scroll--target-pid"></span>`target.pid` | `integer` | | Process id. Required when kind is window. Minimum: 0. |
+| <span id="scroll--target-window_id"></span>`target.window_id` | `integer` | | Window id from list_windows. Required when kind is window. Minimum: 0. |
+
+**Example arguments**
+
+```json
+{"direction":"up"}
+```
+
+### `move_cursor`
+
+Effect: mutating, idempotent. Platforms: macOS, Linux, Windows.
+
+<Tabs items={['macOS', 'Linux', 'Windows']} groupId="platform" persist>
+<Tab value="macOS">
+
+Move a cursor to (x, y). With target &#123;kind: "window", pid, window_id&#125;, x/y are window screenshot pixels (as for click) and only the agent cursor moves there; in a background app it also hovers through a route that leaves the real pointer alone where one exists (AXShowAlternateUI on the element under the point, or an Electron page) and says so. Without a target, moves only the agent cursor overlay, in screen points. Other macOS hover and tooltips follow the real pointer, so most background apps see no hover; for a web page in Chrome, Edge or Brave use browser_pointer hover instead. With scope=desktop, moves the user's real OS pointer in native get_desktop_state screenshot coordinates; over a window of an app that is not in front it refuses unless delivery_mode is "foreground".
+
+**macOS parameters**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="move_cursor--macos--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | | Desktop scope only. Default "background": refuses, before moving anything, when the point is over a window of an app that is not in front, since that would move the user's pointer. "foreground": move the real pointer anyway; only when nobody is using this screen or the user agreed. |
+| <span id="move_cursor--macos--scope"></span>`scope` | `"window" \| "desktop"` | `"window"` | "window" (default) moves only the agent cursor overlay; "desktop" moves the real OS pointer. |
+| <span id="move_cursor--macos--x"></span>`x` | `number` | required | Destination X. Window target: window screenshot pixels. No target: screen points for the agent cursor overlay. Desktop scope: native get_desktop_state screenshot pixels. |
+
+</Tab>
+<Tab value="Linux">
+
+Move the synthetic agent cursor without changing the user's pointer. Only an explicit scope=desktop request moves the real OS pointer in get_desktop_state coordinates.
+
+**Linux parameters**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="move_cursor--linux--scope"></span>`scope` | `"window" \| "desktop"` | `"window"` | "window" (default) moves only the agent cursor overlay; "desktop" moves the real OS pointer. |
+| <span id="move_cursor--linux--x"></span>`x` | `number` | required | Destination X. Window scope: screen coordinates of the agent cursor overlay. Desktop scope: get_desktop_state screenshot pixels. |
+
+</Tab>
+<Tab value="Windows">
+
+Move the agent cursor overlay to (x, y). Does NOT move the real mouse cursor.
+
+**Windows parameters**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="move_cursor--windows--scope"></span>`scope` | `"window" \| "desktop"` | | desktop moves the real OS pointer; window moves only the agent overlay. |
+| <span id="move_cursor--windows--x"></span>`x` | `number` | required | Destination X. Window scope: screen coordinates of the agent cursor overlay. Desktop scope: get_desktop_state screenshot pixels. |
+
+</Tab>
+</Tabs>
+
+**Parameters on every platform**
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="move_cursor--cursor_id"></span>`cursor_id` | `string` | | Cursor instance to move. Default: 'default'. |
+| <span id="move_cursor--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
+| <span id="move_cursor--target"></span>`target` | `object` | | Preferred per-call target: an exact window (`kind="window"`, `pid`, `window_id`) or the primary desktop (`kind="desktop"`, `display_id="primary"`). |
+| <span id="move_cursor--target-display_id"></span>`target.display_id` | `string` | | Display id. Required when kind is desktop; use "primary". |
+| <span id="move_cursor--target-kind"></span>`target.kind` | `"window" \| "desktop"` | | window requires pid and window_id; desktop requires display_id. |
+| <span id="move_cursor--target-pid"></span>`target.pid` | `integer` | | Process id. Required when kind is window. Minimum: 0. |
+| <span id="move_cursor--target-window_id"></span>`target.window_id` | `integer` | | Window id from list_windows. Required when kind is window. Minimum: 0. |
+| <span id="move_cursor--y"></span>`y` | `number` | required | Destination Y, in the same space as x. |
+
+**Example arguments**
+
+```json
+{"x":100,"y":200}
+```
+
+### `mouse_button_down`
+
+Press and hold a mouse button at (x,y) via background X11 delivery. Does not release the button; pair with mouse_drag / mouse_button_up. Returns the current held-button state.
+
+Effect: destructive. Platforms: Linux.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="mouse_button_down--button"></span>`button` | `"left" \| "right" \| "middle"` | | Mouse button. Default "left". |
+| <span id="mouse_button_down--coordinate_frame"></span>`coordinate_frame` | `"window" \| "desktop"` | | Frame of x/y (and from_x/from_y/to_x/to_y). Default "window": window-local screenshot pixels as returned by get_window_state. "desktop": full-screen pixels as returned by get_desktop_state, translated to the target window. Passing scope:"desktop" together with pid/window_id means the same thing. |
+| <span id="mouse_button_down--cursor_id"></span>`cursor_id` | `string` | | Optional multi-cursor instance id. Default: 'default'. |
+| <span id="mouse_button_down--from_zoom"></span>`from_zoom` | `boolean` | | Set true after a zoom call to auto-translate zoom-image pixel coordinates back to full-window space. |
+| <span id="mouse_button_down--pid"></span>`pid` | `integer` | required | Target process ID. |
+| <span id="mouse_button_down--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. When both are present, session takes precedence over cursor_id. |
+| <span id="mouse_button_down--window_id"></span>`window_id` | `integer` | required | Window id from list_windows. |
+| <span id="mouse_button_down--x"></span>`x` | `number` | required | Window-local pixel X of the target window's own get_window_state screenshot (0..screenshot_width). For get_desktop_state pixels pass scope:"desktop" (or coordinate_frame:"desktop"). |
+| <span id="mouse_button_down--y"></span>`y` | `number` | required | Window-local pixel Y of the target window's own get_window_state screenshot (0..screenshot_height); see x. |
+
+**Example arguments**
+
+```json
+{"pid":1,"window_id":1,"x":100,"y":200}
+```
+
+### `mouse_button_up`
+
+Release a previously-held mouse button via background X11 delivery. If x/y are omitted, releases at the last held position. Returns the current held-button state.
+
+Effect: destructive. Platforms: Linux.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="mouse_button_up--coordinate_frame"></span>`coordinate_frame` | `"window" \| "desktop"` | | Frame of x/y (and from_x/from_y/to_x/to_y). Default "window": window-local screenshot pixels as returned by get_window_state. "desktop": full-screen pixels as returned by get_desktop_state, translated to the target window. Passing scope:"desktop" together with pid/window_id means the same thing. |
+| <span id="mouse_button_up--cursor_id"></span>`cursor_id` | `string` | | Optional multi-cursor instance id. Default: 'default'. |
+| <span id="mouse_button_up--from_zoom"></span>`from_zoom` | `boolean` | | Set true after a zoom call to auto-translate zoom-image pixel coordinates back to full-window space. |
+| <span id="mouse_button_up--pid"></span>`pid` | `integer` | | Optional process ID; must match the held button's target. |
+| <span id="mouse_button_up--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. When both are present, session takes precedence over cursor_id. |
+| <span id="mouse_button_up--window_id"></span>`window_id` | `integer` | | Optional window id; must match the held button's target. |
+| <span id="mouse_button_up--x"></span>`x` | `number` | | Window-local pixel X of the target window's own get_window_state screenshot (0..screenshot_width). For get_desktop_state pixels pass scope:"desktop" (or coordinate_frame:"desktop"). |
+| <span id="mouse_button_up--y"></span>`y` | `number` | | Window-local pixel Y of the target window's own get_window_state screenshot (0..screenshot_height); see x. |
+
+### `mouse_drag`
+
+Move a previously-held mouse button to a new point via background X11 delivery. Requires an active mouse_button_down state; does not release the button. Returns the updated held-button state.
+
+Effect: destructive. Platforms: Linux.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="mouse_drag--cursor_id"></span>`cursor_id` | `string` | | Optional multi-cursor instance id. Default: 'default'. |
+| <span id="mouse_drag--duration_ms"></span>`duration_ms` | `integer` | | Total drag duration. Default: 500. Range: 0 to 10000. |
+| <span id="mouse_drag--from_zoom"></span>`from_zoom` | `boolean` | | Set true after a zoom call to auto-translate zoom-image pixel coordinates back to full-window space. |
+| <span id="mouse_drag--pid"></span>`pid` | `integer` | | Optional process ID; must match the held button's target. |
+| <span id="mouse_drag--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. When both are present, session takes precedence over cursor_id. |
+| <span id="mouse_drag--steps"></span>`steps` | `integer` | | Intermediate MotionNotify events. Default: 20. Range: 1 to 200. |
+| <span id="mouse_drag--window_id"></span>`window_id` | `integer` | | Optional window id; must match the held button's target. |
+| <span id="mouse_drag--x"></span>`x` | `number` | required | Window-local pixel X of the target window's own get_window_state screenshot (0..screenshot_width). For get_desktop_state pixels pass scope:"desktop" (or coordinate_frame:"desktop"). |
+| <span id="mouse_drag--y"></span>`y` | `number` | required | Window-local pixel Y of the target window's own get_window_state screenshot (0..screenshot_height); see x. |
+
+**Example arguments**
+
+```json
+{"x":100,"y":200}
+```
+
+### `parallel_mouse_drag`
+
+Run multiple mouse drag gestures concurrently via Linux MPX/XI2 virtual master pointers. Each drag item runs on its own session-scoped master pointer (true same-window concurrent draws on X11). Each item presses once, glides continuously through its whole path, and releases once: one smooth held drag, not a chain of clicks. A path is given either as a straight segment (from_x/from_y → to_x/to_y) or as a function `fn` = y(x) sampled over [x_from, x_to] in window-local pixels (e.g. fn:"x" is a diagonal, fn:"300+120*sin(x/40)" a sine wave). Functions support + - * / ^, sin/cos/tan, sqrt, abs, exp, ln, pi, e.
+
+Effect: destructive. Platforms: Linux.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="parallel_mouse_drag--drags"></span>`drags` | `object[]` | required | Two or more drag gestures to run concurrently, each on its own virtual master pointer. Items: 2 to any. |
+| <span id="parallel_mouse_drag--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
+
+**Example arguments**
+
+```json
+{"drags":[{"session":"<session>","window_id":1},{"session":"<session>","window_id":1}]}
+```
+
+## Agent cursor tools
+
+Show, animate and style the agent cursor.
+
+### `set_agent_cursor_enabled`
+
+Show or hide the agent cursor owned by a session.
+
+Effect: mutating, idempotent. Platforms: macOS, Linux, Windows.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="set_agent_cursor_enabled--enabled"></span>`enabled` | `boolean` | required | `true` shows the session's agent cursor overlay; `false` hides it. |
+| <span id="set_agent_cursor_enabled--session"></span>`session` | `string` | required | Public label of the session that owns the cursor. |
+
+**Example arguments**
+
+```json
+{"session":"<session>","enabled":false}
+```
+
+### `set_agent_cursor_motion`
+
+Configure the movement style, timing, effects and visibility timing for a session cursor.
+
+Effect: mutating, idempotent. Platforms: macOS, Linux, Windows.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="set_agent_cursor_motion--arc_flow"></span>`arc_flow` | `number` | | Added to the arc asymmetry of `signature_arc`, `spring_settle` and `comet_swoop`: positive moves the apex toward the destination. Clamped to -1..1 (default 0). |
+| <span id="set_agent_cursor_motion--arc_size"></span>`arc_size` | `number` | | Scales the arc of `signature_arc`, `spring_settle` and `comet_swoop`: 0.25 (default) keeps the style's arc, 0 is a straight line, 0.5 doubles it. Clamped to 0..1. |
+| <span id="set_agent_cursor_motion--dwell_after_click_ms"></span>`dwell_after_click_ms` | `number` | | Pause after a click animation, in milliseconds. Clamped to 0..5000 (default 80). |
+| <span id="set_agent_cursor_motion--effects"></span>`effects` | `object` | | Turn effects on or off. Omit a field to keep it; `"default"` restores the style default. |
+| <span id="set_agent_cursor_motion--effects-glow"></span>`effects.glow` | `"on" \| "off" \| "default"` | | Soft glow around the cursor that grows with speed. |
+| <span id="set_agent_cursor_motion--effects-magnet"></span>`effects.magnet` | `"on" \| "off" \| "default"` | | Target glow when the `magnetic` style locks on. |
+| <span id="set_agent_cursor_motion--effects-ripple"></span>`effects.ripple` | `"on" \| "off" \| "default"` | | Ring that expands from the hotspot on click. |
+| <span id="set_agent_cursor_motion--effects-squish"></span>`effects.squish` | `"on" \| "off" \| "default"` | | Brief scale-down of the cursor on click. |
+| <span id="set_agent_cursor_motion--effects-trail"></span>`effects.trail` | `"on" \| "off" \| "default"` | | Short fading trail behind the cursor. |
+| <span id="set_agent_cursor_motion--end_handle"></span>`end_handle` | `number` | | Arc control-point offset from the end, as a fraction of the distance, for `signature_arc`, `spring_settle` and `comet_swoop`. Clamped to 0..1 (default 0.3). |
+| <span id="set_agent_cursor_motion--glide_duration_ms"></span>`glide_duration_ms` | `number` | | Move duration in milliseconds for `fixed` timing (1430 ms when 0, the default). A nonzero value with `native` or the default `steady` timing also fixes the duration. Clamped to 0..5000. |
+| <span id="set_agent_cursor_motion--idle_hide_ms"></span>`idle_hide_ms` | `number` | | Hide the cursor after this many idle milliseconds; 0 never hides it. Clamped to 0..60000 (default 15000). |
+| <span id="set_agent_cursor_motion--session"></span>`session` | `string` | required | Public label of the session that owns the cursor. Omitted or null motion fields keep their current value. |
+| <span id="set_agent_cursor_motion--spring"></span>`spring` | `number` | | Arrival spring damping for `classic`: 1 is critically damped, 0.3 is bouncy. Clamped to 0.3..1 (default 0.72). |
+| <span id="set_agent_cursor_motion--start_handle"></span>`start_handle` | `number` | | Arc control-point offset from the start, as a fraction of the distance, for `signature_arc`, `spring_settle` and `comet_swoop`. Clamped to 0..1 (default 0.3). |
+| <span id="set_agent_cursor_motion--style"></span>`style` | `"signature_arc" \| "spring_settle" \| "magnetic" \| "comet_swoop" \| "adaptive" \| "classic"` | | Trajectory style. `signature_arc` (default) is one arc with a small follow-through; `spring_settle` lands with one soft bounce; `magnetic` is pulled into the target; `comet_swoop` is a wide arc with a short trail; `adaptive` picks a careful approach for small targets and a swoop for long moves; `classic` is the previous Dubins glide. When the theme's reduced motion is on, every move is a short straight glide with no effects. |
+| <span id="set_agent_cursor_motion--timing"></span>`timing` | `"native" \| "fitts" \| "fixed" \| "relaxed" \| "steady" \| "calm" \| "deliberate"` | | `steady` (default) keeps the style's timing but makes every move take at least 600 ms, with a gentler ease; `relaxed` and `calm` do the same with a 450 or 750 ms floor. `native` uses the style's own timing; `fitts` scales the move time with distance and target size; `deliberate` is a slower Fitts curve (450..1300 ms); `fixed` uses glide_duration_ms (1430 ms when 0). |
+| <span id="set_agent_cursor_motion--turn_radius"></span>`turn_radius` | `number` | | Minimum turning radius of the `classic` glide path, in points; smaller turns tighter. Clamped to 1..1000 (default 80). |
+
+**Example arguments**
+
+```json
+{"session":"<session>"}
+```
+
+### `set_agent_cursor_theme`
+
+Select an already-installed cursor theme for a session.
+
+Effect: mutating, idempotent. Platforms: macOS, Linux, Windows.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="set_agent_cursor_theme--reduced_motion"></span>`reduced_motion` | `"auto" \| "on" \| "off"` | `"auto"` | Theme animation policy: `on` uses the theme's reduced-motion frames, `off` always animates, `auto` (default) leaves the choice to the host. |
+| <span id="set_agent_cursor_theme--session"></span>`session` | `string` | required | Public label of the session that owns the cursor. |
+| <span id="set_agent_cursor_theme--theme_id"></span>`theme_id` | `string` | required | Id of an installed cursor theme (see `cua-driver cursor-theme list`). |
+
+**Example arguments**
+
+```json
+{"session":"<session>","theme_id":"<theme_id>"}
+```
+
+### `get_agent_cursor_state`
+
+Return the session cursor's theme, semantic playback, position, visibility, and motion.
+
+Effect: read-only, idempotent. Platforms: macOS, Linux, Windows.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="get_agent_cursor_state--session"></span>`session` | `string` | required | Public label of the session whose cursor to inspect. |
+
+**Example arguments**
+
+```json
+{"session":"<session>"}
+```
+
+## Page tools
+
+Read and act on web pages, and prepare and navigate browsers.
+
+### `page`
+
+Legacy browser compatibility tool. Prefer get_browser_state and the typed browser_* tools for exact targeting, endpoint ownership, and consent. Read-only get_text and query_dom remain available by default. Mutating actions require the daemon operator to set CUA_DRIVER_ENABLE_LEGACY_PAGE_MUTATIONS=1 before daemon startup (restart the daemon after changing it); this escape hatch does not provide the typed browser surface's exact binding or existing-profile grant guarantees. Supports Chrome, Brave, Edge, Safari (via AppleScript on macOS), Electron apps (via CDP), Chromium/Firefox on Windows (via UIA for read; CDP for execute_javascript when --remote-debugging-port is set), and WKWebView/Tauri/AT-SPI fallbacks.
+
+Actions:
+- execute_javascript: Run JS and return the result.
+- get_text: Extract visible text from the page.
+- query_dom: Find elements matching a CSS selector.
+- click_element: Click a CSS-selected element AND animate the agent cursor to its on-screen center first (so the user sees what the agent is doing). Prefer over `execute_javascript('el.click()')` whenever you want visible cursor feedback.
+- insert_text: Insert `text` at whatever currently holds DOM focus in one native operation (CDP Input.insertText); no synthesized key events, but more durable than a one-shot execute_javascript write since rich-text editors already have to treat it like an IME commit. Try this before type_keystrokes on a contenteditable that discarded an execute_javascript write. Click/focus the target field first.
+- type_keystrokes: Type `text` via real per-character keystroke events into whatever currently holds DOM focus. Slower than insert_text but the most durable rung: use it when insert_text also gets discarded, or the editor's own keydown/keyup handlers need to see real keys. Click/focus the target field first.
+- enable_javascript_apple_events: macOS-only; patch the browser's Preferences to allow JS from Apple Events (Chrome/Brave/Edge, requires user confirmation and a browser restart).
+
+Effect: mutating. Platforms: macOS, Linux, Windows.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="page--action"></span>`action` | `"execute_javascript" \| "get_text" \| "query_dom" \| "click_element" \| "insert_text" \| "type_keystrokes" \| "enable_javascript_apple_events"` | required | Action to perform. |
+| <span id="page--attributes"></span>`attributes` | `string[]` | | Element attributes to include in query_dom results. |
+| <span id="page--bundle_id"></span>`bundle_id` | `string` | | Bundle ID of the browser. Required for enable_javascript_apple_events (macOS only). |
+| <span id="page--cdp_port"></span>`cdp_port` | `integer` | | Optional, for execute_javascript/insert_text/type_keystrokes: use this exact CDP port instead of auto-discovering one from pid. Needed when the port was opened via the browser's own remote-debugging toggle rather than a launch-time flag, since that path may not answer the auto-discovery probe. Range: 1 to 65535. |
+| <span id="page--css_selector"></span>`css_selector` | `string` | | CSS selector for query_dom (e.g. 'a', 'button', 'input', 'h1'-'h6', 'p', 'img', 'select', '*'). |
+| <span id="page--javascript"></span>`javascript` | `string` | | JavaScript to execute. Required for execute_javascript. |
+| <span id="page--pid"></span>`pid` | `integer` | | Target process ID. |
+| <span id="page--selector"></span>`selector` | `string` | | CSS selector for click_element (e.g. 'button.submit', '#login a'). |
+| <span id="page--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
+| <span id="page--target_url_contains"></span>`target_url_contains` | `string` | | Optional, for execute_javascript/insert_text/type_keystrokes: require exactly one browser tab whose URL contains this substring. Use this on a multi-tab browser: there's no built-in link between window_id and which tab a CDP call reaches. |
+| <span id="page--text"></span>`text` | `string` | | Text to insert or type. Required for insert_text and type_keystrokes. The target field must already have DOM focus (click/focus it first). |
+| <span id="page--user_has_confirmed_enabling"></span>`user_has_confirmed_enabling` | `boolean` | | Must be true to proceed with enable_javascript_apple_events. This will quit and relaunch the browser. |
+| <span id="page--window_id"></span>`window_id` | `integer` | | Target window ID from list_windows. |
+
+**Example arguments**
+
+```json
+{"action":"execute_javascript"}
+```
+
+### `get_browser_state`
+
+Read-only browser inspection. Mode 1 (bind): pass pid + window_id of a native browser window to classify it, correlate it to a CDP target (exact-or-refuse), and mint a session-scoped target id plus tab ids. Mode 2 (snapshot): pass target_id + tab_id. The dom_refs_v1 compatibility format returns composed DOM refs. semantic_v2 joins accessibility, DOM, layout, and viewport state; ranks visible content before retained/offscreen state; and returns a semantic outline, typed action refs, content refs, scoped reads, and opaque continuation. Never performs setup: a browser that is not attached yet refuses with browser_consent_required or browser_requires_setup, and detail.next_call names the browser_prepare call that attaches it. Use this route for any web page in Chrome, Edge or Brave; desktop pointer tools move the user's pointer. Setup and recovery: `get_guide({topic:"browser"})`.
+
+Effect: read-only, idempotent. Platforms: macOS, Linux, Windows.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="get_browser_state--continuation"></span>`continuation` | `string` | | Opaque continuation minted by an earlier semantic_v2 response. |
+| <span id="get_browser_state--include_screenshot"></span>`include_screenshot` | `boolean` | `false` | Capture the exact tab viewport as PNG through CDP without selecting the tab or foregrounding its native window. The request refuses if capture cannot be completed. |
+| <span id="get_browser_state--pid"></span>`pid` | `integer` | | Native browser process id (bind mode). |
+| <span id="get_browser_state--query"></span>`query` | `string` | | Read-only semantic match over role, accessible name, and visible text. |
+| <span id="get_browser_state--scope_ref"></span>`scope_ref` | `string` | | Current semantic/content ref whose subtree should be observed. |
+| <span id="get_browser_state--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. Browser targets, tabs, and refs belong to the resolved lifecycle session. |
+| <span id="get_browser_state--snapshot_format"></span>`snapshot_format` | `"dom_refs_v1" \| "semantic_v2"` | | Versioned snapshot contract. dom_refs_v1 remains the compatibility default. |
+| <span id="get_browser_state--tab_id"></span>`tab_id` | `string` | | Opaque tab id from get_browser_state (session-scoped). |
+| <span id="get_browser_state--target_id"></span>`target_id` | `string` | | Opaque browser target id minted by get_browser_state (session-scoped; never a CDP id). |
+| <span id="get_browser_state--window_id"></span>`window_id` | `integer` | | Native window id owned by pid (bind mode). |
+
+### `browser_prepare`
+
+Attach the browser tools to a browser. For a page in the user's running Chrome, Edge or Brave, call it once with pid, window_id, session and strategy &#123;"kind":"existing_profile"&#125; when get_browser_state refuses with browser_consent_required or browser_requires_setup; then call get_browser_state again and act with browser_click, browser_type or browser_pointer. It attaches, or refuses with nothing changed and says why. Explicitly prepare an owned DevTools endpoint for a browser. pid is required for an existing process or existing-profile attachment, and optional only for allow_launch=true with an isolated profile. Existing endpoints are detected without side effects. Acting setup for an isolated profile follows the runtime permission mode and optional capability manifest. It requires allow_launch=true, launches a separate browser, and never copies, modifies, or terminates the requested user profile. Without pid, only a platform-attested system Chrome/Edge installation (or a root-owned package payload on Linux) is eligible; redirects and user-controlled locations fail closed. Existing-profile attachment is explicit and follows the runtime's immutable permission mode: standard requires an explicit --grant existing-profile launch grant or an embedding authorization host, bounded requires a launch-approved exact resource manifest, and unrestricted requires explicit trusted startup risk acceptance. Ordinary MCP transport approval never proves profile authorization. On proven platforms, an authorized request also permits one bounded exact-window setup: open the recognized browser product's fixed remote-debugging page, toggle its uniquely matched per-instance checkbox, prove the PID-owned loopback endpoint, and close the temporary tab. Every visible effect is reported; ambiguity is refused. Where attaching would bring the browser in front of the user's app (macOS Chrome shows its own remote-debugging prompt in front whenever the driver opens a new browser connection; sessions for the same browser share one approved connection, kept for up to 30 minutes idle and 8 hours in total, so later sessions do not prompt again), existing-profile attachment refuses with background_unavailable unless delivery_mode is "foreground" (the app that was in front is brought back afterwards) or the browser window is on another Space than the user's, where it attaches in the background while the driver reverts the browser's own brief activations. A driver-owned isolated launch result carries an advisory lifecycle object: the browser process ends with the calling session after idle_expires_in_seconds without session activity, an isolated_named profile persists after the session and an isolated_new profile does not, and explicit end, disconnect, revocation or shutdown end it earlier. Setup and recovery: `get_guide({topic:"browser"})`.
+
+Effect: destructive. Platforms: macOS, Linux, Windows.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="browser_prepare--allow_launch"></span>`allow_launch` | `boolean` | | Allow a separate driver-owned isolated Chromium process to be launched (default false). |
+| <span id="browser_prepare--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | `"background"` | Existing-profile attachment only. background (default) attaches in the background when the browser window is on another Space than the user's, and otherwise refuses with background_unavailable, before any visible effect, where attaching would bring the browser in front of the user's app. foreground accepts that, for a screen nobody else is using or when the user agreed; the app that was in front is brought back afterwards. |
+| <span id="browser_prepare--pid"></span>`pid` | `integer` | | Browser process id to prepare. Required except for a driver-owned isolated_new/isolated_named launch with allow_launch=true. |
+| <span id="browser_prepare--profile"></span>`profile` | `object` | | Driver-owned isolated Chromium profile to launch with allow_launch=true. mode=isolated_new creates a fresh throwaway profile; mode=isolated_named reuses the named driver-owned profile. Never an existing user profile. |
+| <span id="browser_prepare--profile-mode"></span>`profile.mode` | `"isolated_new" \| "isolated_named"` | | |
+| <span id="browser_prepare--profile-name"></span>`profile.name` | `string` | | Required only for isolated_named; 1-64 path-safe ASCII characters. |
+| <span id="browser_prepare--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. Browser targets, tabs, and refs belong to the resolved lifecycle session. |
+| <span id="browser_prepare--strategy"></span>`strategy` | `object` | | Attach to an already-running browser instead of launching one. Pass an object, &#123;"kind":"existing_profile"&#125;, not a string. kind=existing_profile attaches to the user's running profile at pid/window_id under the runtime's profile authorization. |
+| <span id="browser_prepare--strategy-kind"></span>`strategy.kind` | `"existing_profile"` | | |
+| <span id="browser_prepare--window_id"></span>`window_id` | `integer` | | Exact native window approval anchor; required for strategy.kind=existing_profile. |
+
+### `browser_navigate`
+
+Navigate one tab of an exactly-bound browser target to a new URL (http/https/about only). Refused for heuristic bindings. Navigation invalidates all p&lt;snapshot&gt;:&lt;index&gt; refs for the tab.
+
+Effect: mutating. Platforms: macOS, Linux, Windows.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="browser_navigate--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. Browser targets, tabs, and refs belong to the resolved lifecycle session. |
+| <span id="browser_navigate--tab_id"></span>`tab_id` | `string` | required | Opaque tab id from get_browser_state (session-scoped). |
+| <span id="browser_navigate--target_id"></span>`target_id` | `string` | required | Opaque browser target id minted by get_browser_state (session-scoped; never a CDP id). |
+| <span id="browser_navigate--url"></span>`url` | `string` | required | Destination URL (http:, https:, or about:). |
+
+**Example arguments**
+
+```json
+{"target_id":"<target_id>","tab_id":"<tab_id>","url":"<url>"}
+```
+
+## Browser input tools
+
+Exact browser input over CDP: clicks, typing, pointer, dialogs, files and downloads.
+
+### `browser_click`
+
+Click a page element (by ref) or viewport coordinates in an exactly-bound tab. Default route is trusted hardware-like input (Input.dispatchMouseEvent), and refuses where that route cannot preserve standalone-browser background posture unless delivery_mode="foreground" accepts that the browser window may activate (including Linux Chromium configurations whose trusted route cannot stay in the background; for example a browser inside a sandbox). input_route="dom_event" (synthetic pointer and mouse down/up/click sequence at the element's center, ref required) is used only when explicitly requested; it proves dispatch, not control activation, because trust-gated controls may ignore synthetic events. Refused for heuristic bindings.
+
+Effect: mutating. Platforms: macOS, Linux, Windows.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="browser_click--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | `"background"` | background (default) refuses trusted input where it would activate the browser window, including Linux Chromium and macOS Chromium configurations whose trusted route cannot stay in the background. foreground accepts that activation, for a browser whose window nobody else is using (for example inside a sandbox). |
+| <span id="browser_click--input_route"></span>`input_route` | `"trusted" \| "dom_event"` | | "trusted" (default): Input.dispatchMouseEvent. It refuses rather than foregrounding a standalone browser. "dom_event": synthetic full-background DOM click, only when explicitly requested. Dispatch does not prove the control activated; refresh page state and verify the expected postcondition. |
+| <span id="browser_click--ref"></span>`ref` | `string` | | Page element ref in the p&lt;snapshot&gt;:&lt;index&gt; namespace from get_browser_state. Refs are invalidated by navigation and by newer snapshots of the same tab. |
+| <span id="browser_click--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. Browser targets, tabs, and refs belong to the resolved lifecycle session. |
+| <span id="browser_click--tab_id"></span>`tab_id` | `string` | required | Opaque tab id from get_browser_state (session-scoped). |
+| <span id="browser_click--target_id"></span>`target_id` | `string` | required | Opaque browser target id minted by get_browser_state (session-scoped; never a CDP id). |
+| <span id="browser_click--x"></span>`x` | `number` | | Viewport x (CSS px): alternative to ref. |
+| <span id="browser_click--y"></span>`y` | `number` | | Viewport y (CSS px): alternative to ref. |
+
+**Example arguments**
+
+```json
+{"target_id":"<target_id>","tab_id":"<tab_id>"}
+```
+
+### `browser_type`
+
+Type text into an exactly-bound tab via the Input domain. mode="insert_text" (default) uses Input.insertText; mode="keystrokes" dispatches per-character key events. Both insert at the caret, so typing into a field that already holds text appends to it; pass replace=true to set the field instead, or to clear it by typing an empty string. Pass a ref to an editable element from the latest snapshot. A ref is required; heuristic bindings are refused.
+
+Effect: mutating. Platforms: macOS, Linux, Windows.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="browser_type--mode"></span>`mode` | `"insert_text" \| "keystrokes"` | | insert_text (default): bulk Input.insertText. keystrokes: per-character Input.dispatchKeyEvent. |
+| <span id="browser_type--ref"></span>`ref` | `string` | required | Page element ref in the p&lt;snapshot&gt;:&lt;index&gt; namespace from get_browser_state. Refs are invalidated by navigation and by newer snapshots of the same tab. |
+| <span id="browser_type--replace"></span>`replace` | `boolean` | | false (default): insert at the caret, appending to whatever the field already holds. true: select the element's whole content first so the text replaces it; with an empty text this clears the field. Replacement goes through the selection, so beforeinput/input still fire and framework state stays consistent. |
+| <span id="browser_type--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. Browser targets, tabs, and refs belong to the resolved lifecycle session. |
+| <span id="browser_type--tab_id"></span>`tab_id` | `string` | required | Opaque tab id from get_browser_state (session-scoped). |
+| <span id="browser_type--target_id"></span>`target_id` | `string` | required | Opaque browser target id minted by get_browser_state (session-scoped; never a CDP id). |
+| <span id="browser_type--text"></span>`text` | `string` | required | Text to type. |
+
+**Example arguments**
+
+```json
+{"target_id":"<target_id>","tab_id":"<tab_id>","ref":"<ref>","text":"<text>"}
+```
+
+### `browser_select`
+
+Select one option of a native HTML &lt;select&gt; ref on an exactly-bound tab without opening its popup. Pass exactly one of label or value; exactly one option must equal it. Refuses non-native, multiple-selection, and disabled selects, disabled options, and zero or ambiguous matches before changing anything. A change dispatches bubbling input and change events; they are synthetic, so verify the page accepted the selection. Selecting the option that is already selected dispatches no events.
+
+Effect: mutating. Platforms: macOS, Linux, Windows.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="browser_select--label"></span>`label` | `string` | | Exact visible label of the option to select. |
+| <span id="browser_select--ref"></span>`ref` | `string` | required | Page element ref in the p&lt;snapshot&gt;:&lt;index&gt; namespace from get_browser_state. Refs are invalidated by navigation and by newer snapshots of the same tab. |
+| <span id="browser_select--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. Browser targets, tabs, and refs belong to the resolved lifecycle session. |
+| <span id="browser_select--tab_id"></span>`tab_id` | `string` | required | Opaque tab id from get_browser_state (session-scoped). |
+| <span id="browser_select--target_id"></span>`target_id` | `string` | required | Opaque browser target id minted by get_browser_state (session-scoped; never a CDP id). |
+| <span id="browser_select--value"></span>`value` | `string` | | Exact value attribute of the option to select. |
+
+**Example arguments**
+
+```json
+{"target_id":"<target_id>","tab_id":"<tab_id>","ref":"<ref>"}
+```
+
+### `browser_pointer`
+
+Perform hover, right-click, double-click, scroll, or drag in an exactly-bound browser tab. Semantic refs must declare pointer for hover, right-click, double-click, and drag; scroll accepts a scroll or pointer capability. The trusted route uses CDP Input events and refuses if standalone background posture cannot be preserved. The explicit dom_event route requires a page ref and synthesizes full-background DOM events. Never activates or brings a tab to the foreground.
+
+Effect: mutating. Platforms: macOS, Linux, Windows.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="browser_pointer--action"></span>`action` | `"hover" \| "right_click" \| "double_click" \| "scroll" \| "drag"` | required | Pointer gesture. scroll needs delta_x or delta_y; drag needs destination_ref or to_x/to_y. |
+| <span id="browser_pointer--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | `"background"` | background (default) refuses trusted input where it would activate the browser window, including Linux Chromium and macOS Chromium configurations whose trusted route cannot stay in the background. foreground accepts that activation, for a browser whose window nobody else is using (for example inside a sandbox). |
+| <span id="browser_pointer--delta_x"></span>`delta_x` | `number` | | Horizontal scroll delta in CSS pixels. |
+| <span id="browser_pointer--delta_y"></span>`delta_y` | `number` | | Vertical scroll delta in CSS pixels. |
+| <span id="browser_pointer--destination_ref"></span>`destination_ref` | `string` | | Drag destination page ref in the exact same frame. |
+| <span id="browser_pointer--input_route"></span>`input_route` | `"trusted" \| "dom_event"` | `"trusted"` | trusted sends CDP Input events; dom_event synthesizes DOM events in the page and requires ref. |
+| <span id="browser_pointer--ref"></span>`ref` | `string` | | Origin page ref. Alternative to x/y. |
+| <span id="browser_pointer--session"></span>`session` | `string` | required | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. This tool requires the label that owns its browser target, tab, and refs. |
+| <span id="browser_pointer--tab_id"></span>`tab_id` | `string` | required | Opaque tab id minted by get_browser_state. |
+| <span id="browser_pointer--target_id"></span>`target_id` | `string` | required | Opaque target id minted by get_browser_state. |
+| <span id="browser_pointer--to_x"></span>`to_x` | `number` | | Drag destination viewport x in CSS pixels. |
+| <span id="browser_pointer--to_y"></span>`to_y` | `number` | | Drag destination viewport y in CSS pixels. |
+| <span id="browser_pointer--x"></span>`x` | `number` | | Origin viewport x in CSS pixels. |
+| <span id="browser_pointer--y"></span>`y` | `number` | | Origin viewport y in CSS pixels. |
+
+**Example arguments**
+
+```json
+{"target_id":"<target_id>","tab_id":"<tab_id>","session":"<session>","action":"hover"}
+```
+
+### `browser_dialog`
+
+Inspect or resolve a page-owned JavaScript alert, confirm, prompt, or beforeunload dialog on one exactly-bound tab. This never handles browser permission UI, extension UI, native dialogs, or file pickers. Inspect returns an opaque dialog_id; accept/dismiss require that exact current id. Resolution defaults to background delivery; Linux callers must explicitly request foreground delivery because Chromium's native modal cannot be resolved there without changing foreground posture.
+
+Effect: mutating. Platforms: macOS, Linux, Windows.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="browser_dialog--action"></span>`action` | `"inspect" \| "accept" \| "dismiss"` | required | inspect returns the current dialog and its dialog_id; accept or dismiss resolves that exact dialog. |
+| <span id="browser_dialog--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | `"background"` | Requested foreground posture for accept/dismiss. Linux Chromium requires foreground; inspect is read-only. |
+| <span id="browser_dialog--dialog_id"></span>`dialog_id` | `string` | | Opaque current dialog generation returned by action=inspect. |
+| <span id="browser_dialog--prompt_text"></span>`prompt_text` | `string` | | Sensitive response text, valid only when accepting a prompt dialog. |
+| <span id="browser_dialog--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. Browser targets, tabs, and refs belong to the resolved lifecycle session. |
+| <span id="browser_dialog--tab_id"></span>`tab_id` | `string` | required | Opaque tab id from get_browser_state (session-scoped). |
+| <span id="browser_dialog--target_id"></span>`target_id` | `string` | required | Opaque browser target id minted by get_browser_state (session-scoped; never a CDP id). |
+
+**Example arguments**
+
+```json
+{"target_id":"<target_id>","tab_id":"<tab_id>","action":"inspect"}
+```
+
+### `browser_set_input_files`
+
+Assign one or more explicit absolute local files to an exact live &lt;input type=file&gt; ref through CDP. This bypasses native file pickers, rejects symlinks and non-regular files, and never returns local paths.
+
+Effect: mutating. Platforms: macOS, Linux, Windows.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="browser_set_input_files--files"></span>`files` | `string[]` | required | Absolute paths of 1 to 32 local regular files to assign to the input. Items: 1 to 32. |
+| <span id="browser_set_input_files--ref"></span>`ref` | `string` | required | Page element ref in the p&lt;snapshot&gt;:&lt;index&gt; namespace from get_browser_state. Refs are invalidated by navigation and by newer snapshots of the same tab. |
+| <span id="browser_set_input_files--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. Browser targets, tabs, and refs belong to the resolved lifecycle session. |
+| <span id="browser_set_input_files--tab_id"></span>`tab_id` | `string` | required | Opaque tab id from get_browser_state (session-scoped). |
+| <span id="browser_set_input_files--target_id"></span>`target_id` | `string` | required | Opaque browser target id minted by get_browser_state (session-scoped; never a CDP id). |
+
+**Example arguments**
+
+```json
+{"target_id":"<target_id>","tab_id":"<tab_id>","ref":"<ref>","files":["<file>"]}
+```
+
+### `browser_download`
+
+Trigger one download through an exact live browser ref and save it inside an explicitly approved directory. Requires MCP-host destructive-tool approval, refuses ambiguous or stale capabilities, and never returns the source URL, filename, or destination path.
+
+Effect: destructive. Platforms: macOS, Linux, Windows.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="browser_download--destination_root"></span>`destination_root` | `string` | required | Absolute, existing, canonical directory approved to receive the download. |
+| <span id="browser_download--ref"></span>`ref` | `string` | required | Live page ref whose activation initiates the download. |
+| <span id="browser_download--session"></span>`session` | `string` | required | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. This tool requires the label that owns its browser target, tab, and refs. |
+| <span id="browser_download--tab_id"></span>`tab_id` | `string` | required | Opaque exact tab id from get_browser_state. |
+| <span id="browser_download--target_id"></span>`target_id` | `string` | required | Opaque exact browser target id from get_browser_state. |
+
+**Example arguments**
+
+```json
+{"session":"<session>","target_id":"<target_id>","tab_id":"<tab_id>","ref":"<ref>","destination_root":"<destination_root>"}
+```
diff --git a/docs/content/docs/cua-driver/reference/mcp-tools/pointer.mdx b/docs/content/docs/cua-driver/reference/mcp-tools/pointer.mdx
deleted file mode 100644
index b187935d11..0000000000
--- a/docs/content/docs/cua-driver/reference/mcp-tools/pointer.mdx
+++ /dev/null
@@ -1,368 +0,0 @@
----
-title: "Pointer tools"
-description: "Drag, scroll, move the pointer, and press or release buttons."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-driver
- Source: cua-driver dump-docs --type mcp (macOS, Linux and Windows registries)
- Version: 0.36.0
-*/}
-
-import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
-
-| Tool | Description | Platforms |
-| --- | --- | --- |
-| [`drag`](#drag) | Press-drag-release gesture from (from_x, from_y) to (to_x, to_y) in window-local screenshot pixels: the same space get_window_state returns. | macOS, Linux, Windows |
-| [`scroll`](#scroll) | Scroll the target pid. | macOS, Linux, Windows |
-| [`move_cursor`](#move_cursor) | Move a cursor to (x, y). | macOS, Linux, Windows |
-| [`mouse_button_down`](#mouse_button_down) | Press and hold a mouse button at (x,y) via background X11 delivery. | Linux |
-| [`mouse_button_up`](#mouse_button_up) | Release a previously-held mouse button via background X11 delivery. | Linux |
-| [`mouse_drag`](#mouse_drag) | Move a previously-held mouse button to a new point via background X11 delivery. | Linux |
-| [`parallel_mouse_drag`](#parallel_mouse_drag) | Run multiple mouse drag gestures concurrently via Linux MPX/XI2 virtual master pointers. | Linux |
-
-Served by `cua-driver mcp`; see [MCP tools](/cua-driver/reference/mcp-tools) for every tool.
-
-## `drag`
-
-Effect: destructive. Platforms: macOS, Linux, Windows.
-
-<Tabs items={['macOS', 'Linux', 'Windows']} groupId="platform" persist>
-<Tab value="macOS">
-
-Press-drag-release gesture from (from_x, from_y) to (to_x, to_y) in window-local screenshot pixels: the same space get_window_state returns. Top-left origin of the target's window.
-
-Use for: marquee/lasso selection, drag-and-drop, resizing via a handle, scrubbing a slider, repositioning a panel.
-
-`duration_ms` (default 500) is the wall-clock budget for the path between mouse-down and mouse-up; `steps` (default 20) is the number of intermediate mouseDragged events linearly interpolated along the path. Increase both for slower, more human drags; decrease for snap gestures.
-
-`modifier` keys (cmd/shift/option/ctrl) are held across the entire gesture.
-
-When `from_zoom` is true, coordinates are in the last zoom image for this pid; the driver maps them back to window coordinates before dispatching.
-
-A window-scoped drag (pid + window_id) runs in the background by default: the gesture is posted to that window, the real pointer does not move, and the user's frontmost window keeps focus. It works for controls that follow the drag events: sliders, canvases, and pointer-event widgets on web pages in Chrome. In an Electron window the driver sends the gesture from the app's main process, so pointer-capture widgets and HTML5 drag and drop also drop there. Elsewhere, a drag that starts a macOS drag-and-drop session (reordering a list by drag and drop, moving a file, HTML5 draggable content) cannot drop in the background, because macOS tracks those with the real pointer; the driver detects it, releases at once and returns background_unavailable with reason drag_and_drop_session. For a page in a browser tab already bound with get_browser_state, browser_pointer action:"drag" drives the same gesture through CDP with page refs. The result is not driver-verified: confirm with a screenshot or the accessibility tree, and only if nothing changed retry with delivery_mode:"foreground", which briefly fronts the window and moves the physical pointer. Limits and fallbacks: `get_guide({topic:"drag"})`.
-
-**macOS parameters**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="drag--macos--button"></span>`button` | `"left" \| "right" \| "middle"` | | Mouse button used for the drag. Default: left. |
-| <span id="drag--macos--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | | Window-scoped drag on macOS: "background" (default) posts the press, drag and release to the exact window (window_id required) without moving the pointer, raising the window or taking the user's focus. "foreground" briefly fronts the window, drives the physical pointer through the gesture, then restores the prior frontmost app; use it only when a background drag had no effect. Desktop scope ignores this field. |
-| <span id="drag--macos--duration_ms"></span>`duration_ms` | `integer` | | Wall-clock duration of the drag path between mouseDown and mouseUp. Default: 500. Range: 0 to 10000. |
-| <span id="drag--macos--from_x"></span>`from_x` | `number` | required | Drag-start X in window-local screenshot pixels. Top-left origin. |
-| <span id="drag--macos--from_y"></span>`from_y` | `number` | required | Drag-start Y in window-local screenshot pixels. Top-left origin. |
-| <span id="drag--macos--from_zoom"></span>`from_zoom` | `boolean` | | When true, coordinates are in the last zoom image for this pid; driver maps back to window coordinates. |
-| <span id="drag--macos--modifier"></span>`modifier` | `string[]` | | Modifier keys held across the entire gesture: cmd/shift/option/ctrl. |
-| <span id="drag--macos--pid"></span>`pid` | `integer` | | Target process ID. |
-| <span id="drag--macos--scope"></span>`scope` | `"window" \| "desktop"` | `"window"` | Use desktop with no pid/window_id for native get_desktop_state screenshot coordinates. |
-| <span id="drag--macos--steps"></span>`steps` | `integer` | | Number of intermediate mouseDragged events linearly interpolated along the path. Default: 20. Range: 1 to 200. |
-| <span id="drag--macos--to_x"></span>`to_x` | `number` | required | Drag-end X in window-local screenshot pixels. |
-| <span id="drag--macos--to_y"></span>`to_y` | `number` | required | Drag-end Y in window-local screenshot pixels. |
-| <span id="drag--macos--window_id"></span>`window_id` | `integer` | | CGWindowID for the window the pixel coordinates were measured against. Optional only when pid owns exactly one eligible top-level window; otherwise the action refuses with ambiguous_window_target. |
-
-</Tab>
-<Tab value="Linux">
-
-Press-drag-release gesture from (from_x, from_y) to (to_x, to_y) in window-local screenshot pixels. Background delivery on X11 is one real held gesture on the session's virtual master pointer (path mpx_pointer: press, interpolated motion, release); it lands on GTK/VCL/Qt/Chromium; a point covered by another application's window is refused (target_occluded), one covered by this app's own dialog is retargeted to it. Headless servers fall back to XSendEvent. duration_ms (default 500), steps (default 20). No focus steal. Limits and fallbacks: `get_guide({topic:"drag"})`.
-
-**Linux parameters**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="drag--linux--button"></span>`button` | `"left" \| "right" \| "middle"` | | Mouse button. Default "left". |
-| <span id="drag--linux--coordinate_frame"></span>`coordinate_frame` | `"window" \| "desktop"` | | Frame of x/y (and from_x/from_y/to_x/to_y). Default "window": window-local screenshot pixels as returned by get_window_state. "desktop": full-screen pixels as returned by get_desktop_state, translated to the target window. Passing scope:"desktop" together with pid/window_id means the same thing. |
-| <span id="drag--linux--cursor_id"></span>`cursor_id` | `string` | | Optional multi-cursor instance id. Default: 'default'. |
-| <span id="drag--linux--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | `"background"` | Input delivery mode. 'background' (default) never activates or raises the target window. On X11 it injects via XTEST / the XInput2 master pointer (no focus steal). On Wayland it goes through libei + xdg-desktop-portal, which injects to the compositor's input focus: Wayland's security model has no per-window background targeting, so a specific non-focused window cannot be aimed at; when no libei backend is available the tool returns a structured background_unavailable error. 'foreground' is the explicit escalation: activate the target (X11 _NET_ACTIVE_WINDOW; Wayland compositor activate), inject, then restore the prior active window; a brief focus swap unless the target was already active. Matches the macOS / Windows delivery_mode surface. |
-| <span id="drag--linux--duration_ms"></span>`duration_ms` | `integer` | | Total drag duration. Default: 500. Range: 0 to 10000. |
-| <span id="drag--linux--from_x"></span>`from_x` | `number` | required | Drag start X: window-local pixels of the target window's own get_window_state screenshot; pass scope:"desktop" for get_desktop_state pixels. |
-| <span id="drag--linux--from_y"></span>`from_y` | `number` | required | Drag start Y (same frame as from_x). |
-| <span id="drag--linux--from_zoom"></span>`from_zoom` | `boolean` | | Set true after a zoom call to auto-translate zoom-image pixel coordinates back to full-window space. |
-| <span id="drag--linux--modifier"></span>`modifier` | `string[]` | | Modifier keys held during the action: cmd, shift, option/alt, ctrl. |
-| <span id="drag--linux--pid"></span>`pid` | `integer` | | Target process ID. Required unless scope is "desktop". |
-| <span id="drag--linux--scope"></span>`scope` | `"window" \| "desktop"` | `"window"` | Use "desktop" with no pid/window_id for get_desktop_state screen coordinates. Default "window". |
-| <span id="drag--linux--steps"></span>`steps` | `integer` | | Intermediate MotionNotify events. Default: 20. Range: 1 to 200. |
-| <span id="drag--linux--to_x"></span>`to_x` | `number` | required | Drag end X (same frame as from_x). |
-| <span id="drag--linux--to_y"></span>`to_y` | `number` | required | Drag end Y (same frame as from_x). |
-| <span id="drag--linux--window_id"></span>`window_id` | `integer` | | Target window XID. Required. |
-
-</Tab>
-<Tab value="Windows">
-
-Press-drag-release gesture from (from_x, from_y) to (to_x, to_y) in window-local screenshot pixels. duration_ms (default 500) is the wall-clock budget; steps (default 20) interpolates intermediate WM_MOUSEMOVE events along the path. No focus steal. After a zoom call, pass from_zoom=true. Drags that start on a window caption / title bar or resize border (i.e. moving or resizing the window itself) cannot be delivered in the background, the OS move/resize loop needs real pointer input, so they return background_unavailable; re-issue those with delivery_mode:"foreground". Limits and fallbacks: `get_guide({topic:"drag"})`.
-
-**Windows parameters**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="drag--windows--button"></span>`button` | `"left" \| "right" \| "middle"` | | Mouse button. Default "left". |
-| <span id="drag--windows--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | | Input delivery mode. 'background' (default) never swaps foreground: it routes through UIA Invoke / PostMessage and the window is never raised. For targets whose input stack silently drops posted events (Chromium/Electron content, GTK buttons, VCL/LibreOffice accelerators) the tool returns a structured background_unavailable error rather than fronting. 'foreground' is the explicit escalation: a brief SetForegroundWindow swap + SendInput, restoring the prior foreground afterward. IMPORTANT: 'background' is not a hint to weigh; it is the mandatory first attempt. Do NOT pass 'foreground' preemptively because a target 'looks like' GTK/Chromium/Electron; the DRIVER decides when background is impossible and tells you so via a background_unavailable error (or a verified no-op). Only THEN re-issue the same action with 'foreground'. The lists above are the driver's detectors, not a checklist for you to front on a guess: fronting up-front needlessly steals the user's focus and is a bug, not a shortcut. Matches the macOS delivery_mode surface. |
-| <span id="drag--windows--duration_ms"></span>`duration_ms` | `integer` | | Wall-clock duration of drag path. Default: 500. Range: 0 to 10000. |
-| <span id="drag--windows--from_x"></span>`from_x` | `number` | required | Drag-start X in window-local screenshot pixels. |
-| <span id="drag--windows--from_y"></span>`from_y` | `number` | required | Drag-start Y in window-local screenshot pixels. |
-| <span id="drag--windows--from_zoom"></span>`from_zoom` | `boolean` | | When true, coordinates are in the last zoom image for this pid. |
-| <span id="drag--windows--modifier"></span>`modifier` | `string[]` | | Modifier keys held during the action: cmd, shift, option/alt, ctrl. |
-| <span id="drag--windows--pid"></span>`pid` | `integer` | | Target process ID. |
-| <span id="drag--windows--scope"></span>`scope` | `"window" \| "desktop"` | | Use desktop with no pid/window_id for screen-absolute coordinates. |
-| <span id="drag--windows--steps"></span>`steps` | `integer` | | Number of intermediate WM_MOUSEMOVE events. Default: 20. Range: 1 to 200. |
-| <span id="drag--windows--to_x"></span>`to_x` | `number` | required | Drag-end X in window-local screenshot pixels. |
-| <span id="drag--windows--to_y"></span>`to_y` | `number` | required | Drag-end Y in window-local screenshot pixels. |
-| <span id="drag--windows--window_id"></span>`window_id` | `integer` | | Target window handle (HWND). Optional: driver picks frontmost window of pid when omitted. |
-
-</Tab>
-</Tabs>
-
-**Parameters on every platform**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="drag--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
-| <span id="drag--target"></span>`target` | `object` | | Preferred per-call target: an exact window (`kind="window"`, `pid`, `window_id`) or the primary desktop (`kind="desktop"`, `display_id="primary"`). |
-| <span id="drag--target-display_id"></span>`target.display_id` | `string` | | Display id. Required when kind is desktop; use "primary". |
-| <span id="drag--target-kind"></span>`target.kind` | `"window" \| "desktop"` | | window requires pid and window_id; desktop requires display_id. |
-| <span id="drag--target-pid"></span>`target.pid` | `integer` | | Process id. Required when kind is window. Minimum: 0. |
-| <span id="drag--target-window_id"></span>`target.window_id` | `integer` | | Window id from list_windows. Required when kind is window. Minimum: 0. |
-
-**Example arguments**
-
-```json
-{"from_x":100,"from_y":200,"to_x":100,"to_y":200}
-```
-
-## `scroll`
-
-Effect: mutating. Platforms: macOS, Linux, Windows.
-
-<Tabs items={['macOS', 'Linux', 'Windows']} groupId="platform" persist>
-<Tab value="macOS">
-
-Scroll the target pid.
-- Targeted wheel: pass `element_token` (preferred) or window-local `x, y`. Sends a real wheel event at that point, so it scrolls whatever is under it. The only way to scroll nested `overflow:auto` regions in web views.
-- Keystroke: no target, just pid + direction. PageDown/PageUp (by='page') or arrows (by='line') on the focused scroller.
-
-Electron/Chromium windows drop background wheel events: there a background scroll reveals the content just past the edge of the scroll container under the target through accessibility (about `amount` notches); `delivery_mode:"foreground"` is the fallback.
-`amount` is wheel notches (targeted) or key repetitions (keystroke).
-
-**macOS parameters**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="scroll--macos--amount"></span>`amount` | `integer` | | Wheel notches or key repetitions, clamped to the maximum. Default 3. Range: 1 to 50. |
-| <span id="scroll--macos--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | | Default "background": no fronting or focus steal. "foreground": briefly front the window, act, restore the prior app; last resort when background did not land. |
-| <span id="scroll--macos--pid"></span>`pid` | `integer` | | Target process ID. Required unless scope is "desktop" or element_token is supplied. |
-| <span id="scroll--macos--scope"></span>`scope` | `"window" \| "desktop"` | `"window"` | "desktop" with x,y and no pid/window_id uses get_desktop_state coordinates. |
-| <span id="scroll--macos--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. |
-| <span id="scroll--macos--window_id"></span>`window_id` | `integer` | | Window ID. Required with x/y; optional with element_token. |
-| <span id="scroll--macos--x"></span>`x` | `number` | | Window-local screenshot X (get_window_state PNG). With y, wheel-scrolls at that point; needs window_id. |
-| <span id="scroll--macos--y"></span>`y` | `number` | | Window-local screenshot Y. |
-
-</Tab>
-<Tab value="Linux">
-
-Scroll the target pid's focused region via XSendEvent Button4/5. direction required; by defaults to line, amount defaults to 3.
-
-**Linux parameters**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="scroll--linux--amount"></span>`amount` | `integer` | | Number of scroll steps. Default: 3. Range: 1 to 50. |
-| <span id="scroll--linux--coordinate_frame"></span>`coordinate_frame` | `"window" \| "desktop"` | | Frame of x/y (and from_x/from_y/to_x/to_y). Default "window": window-local screenshot pixels as returned by get_window_state. "desktop": full-screen pixels as returned by get_desktop_state, translated to the target window. Passing scope:"desktop" together with pid/window_id means the same thing. |
-| <span id="scroll--linux--cursor_id"></span>`cursor_id` | `string` | | Optional multi-cursor instance id. Default: 'default'. |
-| <span id="scroll--linux--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | `"background"` | Input delivery mode. 'background' (default) never activates or raises the target window. On X11 it injects via XTEST / the XInput2 master pointer (no focus steal). On Wayland it goes through libei + xdg-desktop-portal, which injects to the compositor's input focus: Wayland's security model has no per-window background targeting, so a specific non-focused window cannot be aimed at; when no libei backend is available the tool returns a structured background_unavailable error. 'foreground' is the explicit escalation: activate the target (X11 _NET_ACTIVE_WINDOW; Wayland compositor activate), inject, then restore the prior active window; a brief focus swap unless the target was already active. Matches the macOS / Windows delivery_mode surface. |
-| <span id="scroll--linux--pid"></span>`pid` | `integer` | | Target process ID. Required unless scope is "desktop" or element_token is supplied (the token carries the pid). |
-| <span id="scroll--linux--scope"></span>`scope` | `"window" \| "desktop"` | `"window"` | Use "desktop" with x,y and no pid/window_id for get_desktop_state screen coordinates. Default "window". |
-| <span id="scroll--linux--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
-| <span id="scroll--linux--window_id"></span>`window_id` | `integer` | | Window id from list_windows. Required with x/y; optional with element_token (the token carries it). |
-| <span id="scroll--linux--x"></span>`x` | `number` | | Window-local screenshot-pixel X of the scroll target. Pass with y and without element_token. |
-| <span id="scroll--linux--y"></span>`y` | `number` | | Window-local screenshot-pixel Y of the scroll target. Pass with x and without element_token. |
-
-</Tab>
-<Tab value="Windows">
-
-Scroll the target pid's focused region.
-
-Windows transport: WM_VSCROLL / WM_HSCROLL posted to the window; the same events the OS sends when scrollbars or trackpads scroll, so any window that handles scrollbars correctly responds to this. Swift uses synthesized keystrokes (PageDown / arrow keys) via auth-signed SLEventPostToPid; both approaches reach backgrounded windows.
-
-Mapping: `by: "page"` → SB_PAGEDOWN/UP/LEFT/RIGHT × amount; `by: "line"` → SB_LINEDOWN/UP/LEFT/RIGHT × amount.
-
-Note: `element_token` is accepted for cross-platform parity but currently no-op on Windows (UIA SetFocus not wired up yet; same caveat as `press_key`).
-
-**Windows parameters**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="scroll--windows--amount"></span>`amount` | `integer` | | Number of scroll ticks. Default 3. Range: 1 to 50. |
-| <span id="scroll--windows--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | | Input delivery mode. 'background' (default) never swaps foreground: it routes through UIA Invoke / PostMessage and the window is never raised. For targets whose input stack silently drops posted events (Chromium/Electron content, GTK buttons, VCL/LibreOffice accelerators) the tool returns a structured background_unavailable error rather than fronting. 'foreground' is the explicit escalation: a brief SetForegroundWindow swap + SendInput, restoring the prior foreground afterward. IMPORTANT: 'background' is not a hint to weigh; it is the mandatory first attempt. Do NOT pass 'foreground' preemptively because a target 'looks like' GTK/Chromium/Electron; the DRIVER decides when background is impossible and tells you so via a background_unavailable error (or a verified no-op). Only THEN re-issue the same action with 'foreground'. The lists above are the driver's detectors, not a checklist for you to front on a guess: fronting up-front needlessly steals the user's focus and is a bug, not a shortcut. Matches the macOS delivery_mode surface. |
-| <span id="scroll--windows--pid"></span>`pid` | `integer` | | Target process ID for window scope. Optional with element_token (the token carries the pid). Omit with scope=desktop for screen-absolute coordinates from get_desktop_state. |
-| <span id="scroll--windows--scope"></span>`scope` | `"window" \| "desktop"` | `"window"` | Use "desktop" with x,y and no pid/window_id for screen-absolute coordinates from get_desktop_state. Default "window". |
-| <span id="scroll--windows--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
-| <span id="scroll--windows--window_id"></span>`window_id` | `integer` | | HWND of the target window. Omit when element_token is supplied; otherwise auto-resolves the pid's first visible window. |
-| <span id="scroll--windows--x"></span>`x` | `number` | | With pid/window_id: window-local screenshot X used to target a nested scroll surface in foreground mode. Without pid/window_id: screen-absolute X for desktop scope. Must be paired with y. |
-| <span id="scroll--windows--y"></span>`y` | `number` | | With pid/window_id: window-local screenshot Y used to target a nested scroll surface in foreground mode. Without pid/window_id: screen-absolute Y for desktop scope. Must be paired with x. |
-
-</Tab>
-</Tabs>
-
-**Parameters on every platform**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="scroll--by"></span>`by` | `"line" \| "page"` | | Scroll granularity. Default: line. |
-| <span id="scroll--direction"></span>`direction` | `"up" \| "down" \| "left" \| "right"` | required | Scroll direction. |
-| <span id="scroll--element_token"></span>`element_token` | `string` | | Element handle `<snapshot_id>:<row>` from get_window_state: row `[11]` of a read whose snapshot_id is s0000002a is "s0000002a:11" (also in `structuredContent.elements[].element_token`). Returns an explicit stale error naming the current snapshots once a newer read supersedes it. |
-| <span id="scroll--target"></span>`target` | `object` | | Preferred per-call target: an exact window (`kind="window"`, `pid`, `window_id`) or the primary desktop (`kind="desktop"`, `display_id="primary"`). |
-| <span id="scroll--target-display_id"></span>`target.display_id` | `string` | | Display id. Required when kind is desktop; use "primary". |
-| <span id="scroll--target-kind"></span>`target.kind` | `"window" \| "desktop"` | | window requires pid and window_id; desktop requires display_id. |
-| <span id="scroll--target-pid"></span>`target.pid` | `integer` | | Process id. Required when kind is window. Minimum: 0. |
-| <span id="scroll--target-window_id"></span>`target.window_id` | `integer` | | Window id from list_windows. Required when kind is window. Minimum: 0. |
-
-**Example arguments**
-
-```json
-{"direction":"up"}
-```
-
-## `move_cursor`
-
-Effect: mutating, idempotent. Platforms: macOS, Linux, Windows.
-
-<Tabs items={['macOS', 'Linux', 'Windows']} groupId="platform" persist>
-<Tab value="macOS">
-
-Move a cursor to (x, y). With target &#123;kind: "window", pid, window_id&#125;, x/y are window screenshot pixels (as for click) and only the agent cursor moves there; in a background app it also hovers through a route that leaves the real pointer alone where one exists (AXShowAlternateUI on the element under the point, or an Electron page) and says so. Without a target, moves only the agent cursor overlay, in screen points. Other macOS hover and tooltips follow the real pointer, so most background apps see no hover; for a web page in Chrome, Edge or Brave use browser_pointer hover instead. With scope=desktop, moves the user's real OS pointer in native get_desktop_state screenshot coordinates; over a window of an app that is not in front it refuses unless delivery_mode is "foreground".
-
-**macOS parameters**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="move_cursor--macos--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | | Desktop scope only. Default "background": refuses, before moving anything, when the point is over a window of an app that is not in front, since that would move the user's pointer. "foreground": move the real pointer anyway; only when nobody is using this screen or the user agreed. |
-| <span id="move_cursor--macos--scope"></span>`scope` | `"window" \| "desktop"` | `"window"` | "window" (default) moves only the agent cursor overlay; "desktop" moves the real OS pointer. |
-| <span id="move_cursor--macos--x"></span>`x` | `number` | required | Destination X. Window target: window screenshot pixels. No target: screen points for the agent cursor overlay. Desktop scope: native get_desktop_state screenshot pixels. |
-
-</Tab>
-<Tab value="Linux">
-
-Move the synthetic agent cursor without changing the user's pointer. Only an explicit scope=desktop request moves the real OS pointer in get_desktop_state coordinates.
-
-**Linux parameters**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="move_cursor--linux--scope"></span>`scope` | `"window" \| "desktop"` | `"window"` | "window" (default) moves only the agent cursor overlay; "desktop" moves the real OS pointer. |
-| <span id="move_cursor--linux--x"></span>`x` | `number` | required | Destination X. Window scope: screen coordinates of the agent cursor overlay. Desktop scope: get_desktop_state screenshot pixels. |
-
-</Tab>
-<Tab value="Windows">
-
-Move the agent cursor overlay to (x, y). Does NOT move the real mouse cursor.
-
-**Windows parameters**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="move_cursor--windows--scope"></span>`scope` | `"window" \| "desktop"` | | desktop moves the real OS pointer; window moves only the agent overlay. |
-| <span id="move_cursor--windows--x"></span>`x` | `number` | required | Destination X. Window scope: screen coordinates of the agent cursor overlay. Desktop scope: get_desktop_state screenshot pixels. |
-
-</Tab>
-</Tabs>
-
-**Parameters on every platform**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="move_cursor--cursor_id"></span>`cursor_id` | `string` | | Cursor instance to move. Default: 'default'. |
-| <span id="move_cursor--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
-| <span id="move_cursor--target"></span>`target` | `object` | | Preferred per-call target: an exact window (`kind="window"`, `pid`, `window_id`) or the primary desktop (`kind="desktop"`, `display_id="primary"`). |
-| <span id="move_cursor--target-display_id"></span>`target.display_id` | `string` | | Display id. Required when kind is desktop; use "primary". |
-| <span id="move_cursor--target-kind"></span>`target.kind` | `"window" \| "desktop"` | | window requires pid and window_id; desktop requires display_id. |
-| <span id="move_cursor--target-pid"></span>`target.pid` | `integer` | | Process id. Required when kind is window. Minimum: 0. |
-| <span id="move_cursor--target-window_id"></span>`target.window_id` | `integer` | | Window id from list_windows. Required when kind is window. Minimum: 0. |
-| <span id="move_cursor--y"></span>`y` | `number` | required | Destination Y, in the same space as x. |
-
-**Example arguments**
-
-```json
-{"x":100,"y":200}
-```
-
-## `mouse_button_down`
-
-Press and hold a mouse button at (x,y) via background X11 delivery. Does not release the button; pair with mouse_drag / mouse_button_up. Returns the current held-button state.
-
-Effect: destructive. Platforms: Linux.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="mouse_button_down--button"></span>`button` | `"left" \| "right" \| "middle"` | | Mouse button. Default "left". |
-| <span id="mouse_button_down--coordinate_frame"></span>`coordinate_frame` | `"window" \| "desktop"` | | Frame of x/y (and from_x/from_y/to_x/to_y). Default "window": window-local screenshot pixels as returned by get_window_state. "desktop": full-screen pixels as returned by get_desktop_state, translated to the target window. Passing scope:"desktop" together with pid/window_id means the same thing. |
-| <span id="mouse_button_down--cursor_id"></span>`cursor_id` | `string` | | Optional multi-cursor instance id. Default: 'default'. |
-| <span id="mouse_button_down--from_zoom"></span>`from_zoom` | `boolean` | | Set true after a zoom call to auto-translate zoom-image pixel coordinates back to full-window space. |
-| <span id="mouse_button_down--pid"></span>`pid` | `integer` | required | Target process ID. |
-| <span id="mouse_button_down--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. When both are present, session takes precedence over cursor_id. |
-| <span id="mouse_button_down--window_id"></span>`window_id` | `integer` | required | Window id from list_windows. |
-| <span id="mouse_button_down--x"></span>`x` | `number` | required | Window-local pixel X of the target window's own get_window_state screenshot (0..screenshot_width). For get_desktop_state pixels pass scope:"desktop" (or coordinate_frame:"desktop"). |
-| <span id="mouse_button_down--y"></span>`y` | `number` | required | Window-local pixel Y of the target window's own get_window_state screenshot (0..screenshot_height); see x. |
-
-**Example arguments**
-
-```json
-{"pid":1,"window_id":1,"x":100,"y":200}
-```
-
-## `mouse_button_up`
-
-Release a previously-held mouse button via background X11 delivery. If x/y are omitted, releases at the last held position. Returns the current held-button state.
-
-Effect: destructive. Platforms: Linux.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="mouse_button_up--coordinate_frame"></span>`coordinate_frame` | `"window" \| "desktop"` | | Frame of x/y (and from_x/from_y/to_x/to_y). Default "window": window-local screenshot pixels as returned by get_window_state. "desktop": full-screen pixels as returned by get_desktop_state, translated to the target window. Passing scope:"desktop" together with pid/window_id means the same thing. |
-| <span id="mouse_button_up--cursor_id"></span>`cursor_id` | `string` | | Optional multi-cursor instance id. Default: 'default'. |
-| <span id="mouse_button_up--from_zoom"></span>`from_zoom` | `boolean` | | Set true after a zoom call to auto-translate zoom-image pixel coordinates back to full-window space. |
-| <span id="mouse_button_up--pid"></span>`pid` | `integer` | | Optional process ID; must match the held button's target. |
-| <span id="mouse_button_up--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. When both are present, session takes precedence over cursor_id. |
-| <span id="mouse_button_up--window_id"></span>`window_id` | `integer` | | Optional window id; must match the held button's target. |
-| <span id="mouse_button_up--x"></span>`x` | `number` | | Window-local pixel X of the target window's own get_window_state screenshot (0..screenshot_width). For get_desktop_state pixels pass scope:"desktop" (or coordinate_frame:"desktop"). |
-| <span id="mouse_button_up--y"></span>`y` | `number` | | Window-local pixel Y of the target window's own get_window_state screenshot (0..screenshot_height); see x. |
-
-## `mouse_drag`
-
-Move a previously-held mouse button to a new point via background X11 delivery. Requires an active mouse_button_down state; does not release the button. Returns the updated held-button state.
-
-Effect: destructive. Platforms: Linux.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="mouse_drag--cursor_id"></span>`cursor_id` | `string` | | Optional multi-cursor instance id. Default: 'default'. |
-| <span id="mouse_drag--duration_ms"></span>`duration_ms` | `integer` | | Total drag duration. Default: 500. Range: 0 to 10000. |
-| <span id="mouse_drag--from_zoom"></span>`from_zoom` | `boolean` | | Set true after a zoom call to auto-translate zoom-image pixel coordinates back to full-window space. |
-| <span id="mouse_drag--pid"></span>`pid` | `integer` | | Optional process ID; must match the held button's target. |
-| <span id="mouse_drag--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. When both are present, session takes precedence over cursor_id. |
-| <span id="mouse_drag--steps"></span>`steps` | `integer` | | Intermediate MotionNotify events. Default: 20. Range: 1 to 200. |
-| <span id="mouse_drag--window_id"></span>`window_id` | `integer` | | Optional window id; must match the held button's target. |
-| <span id="mouse_drag--x"></span>`x` | `number` | required | Window-local pixel X of the target window's own get_window_state screenshot (0..screenshot_width). For get_desktop_state pixels pass scope:"desktop" (or coordinate_frame:"desktop"). |
-| <span id="mouse_drag--y"></span>`y` | `number` | required | Window-local pixel Y of the target window's own get_window_state screenshot (0..screenshot_height); see x. |
-
-**Example arguments**
-
-```json
-{"x":100,"y":200}
-```
-
-## `parallel_mouse_drag`
-
-Run multiple mouse drag gestures concurrently via Linux MPX/XI2 virtual master pointers. Each drag item runs on its own session-scoped master pointer (true same-window concurrent draws on X11). Each item presses once, glides continuously through its whole path, and releases once: one smooth held drag, not a chain of clicks. A path is given either as a straight segment (from_x/from_y → to_x/to_y) or as a function `fn` = y(x) sampled over [x_from, x_to] in window-local pixels (e.g. fn:"x" is a diagonal, fn:"300+120*sin(x/40)" a sine wave). Functions support + - * / ^, sin/cos/tan, sqrt, abs, exp, ln, pi, e.
-
-Effect: destructive. Platforms: Linux.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="parallel_mouse_drag--drags"></span>`drags` | `object[]` | required | Two or more drag gestures to run concurrently, each on its own virtual master pointer. Items: 2 to any. |
-| <span id="parallel_mouse_drag--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
-
-**Example arguments**
-
-```json
-{"drags":[{"session":"<session>","window_id":1},{"session":"<session>","window_id":1}]}
-```
diff --git a/docs/content/docs/cua-driver/reference/mcp-tools/recording.mdx b/docs/content/docs/cua-driver/reference/mcp-tools/recording.mdx
deleted file mode 100644
index 8d53ea9be1..0000000000
--- a/docs/content/docs/cua-driver/reference/mcp-tools/recording.mdx
+++ /dev/null
@@ -1,122 +0,0 @@
----
-title: "Recording tools"
-description: "Record and replay trajectories."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-driver
- Source: cua-driver dump-docs --type mcp (macOS, Linux and Windows registries)
- Version: 0.36.0
-*/}
-
-| Tool | Description | Platforms |
-| --- | --- | --- |
-| [`start_recording`](#start_recording) | Start trajectory recording for the calling session. | macOS, Linux, Windows |
-| [`stop_recording`](#stop_recording) | Stop trajectory recording. | macOS, Linux, Windows |
-| [`get_recording_state`](#get_recording_state) | Report the current trajectory recorder state: whether recording is enabled, the output directory (when enabled), and the 1-based counter for the next turn folder that will be written. | macOS, Linux, Windows |
-| [`replay_trajectory`](#replay_trajectory) | Replay a recorded trajectory by re-invoking every turn's tool call in lexical order. | macOS, Linux, Windows |
-| [`install_ffmpeg`](#install_ffmpeg) | Install the ffmpeg binary used by start_recording's video capture (Linux/Windows; macOS records natively and needs no ffmpeg). | macOS, Linux, Windows |
-
-Served by `cua-driver mcp`; see [MCP tools](/cua-driver/reference/mcp-tools) for every tool.
-
-## `start_recording`
-
-Start trajectory recording for the calling session. Each action-tool invocation (click, right_click, scroll, type_text, press_key, hotkey, set_value) from that session writes a turn folder under `output_dir`. Without `session`, every call on the same connection is recorded, including named-session calls. Other connections and session lifecycle calls (`start_session` / `end_session`) are not recorded. CLI recordings started with `cua-driver recording start` are daemon-wide.
-
-Each turn folder holds:
-
-- `before_state.json` / `after_state.json`: application AX/UIA/AT-SPI state immediately before and after the action.
-- `before.png` / `after.png`: target-window screenshots immediately before and after the action.
-- `evidence.json`: capture status and a stable classification when an expected artifact could not be captured.
-- `app_state.json`: post-action AX/UIA snapshot for the target pid.
-- `screenshot.png`: compatibility alias of `after.png`.
-- `action.json`: tool name, full input arguments, result summary, result-error flag, pid, click point (when applicable), ISO-8601 timestamp.
-- `click.png`: for dispatched click-family actions only, `before.png` with a red marker at the click point. A call refused before target resolution is explicitly not applicable instead.
-
-The per-turn accessibility walk is bounded like `get_window_state`: `state_timeout_ms` (default 1000) caps each before/after walk, a walk that runs out of budget records the PARTIAL tree, and `evidence.json` carries `truncated`, `truncation_reason`, `nodes_visited`, `nodes_pending` and `timeout_ms` for that phase. A provider that stops answering is abandoned after the budget plus a short grace and the phase is classified `state_capture_timeout`. Actions refused before dispatch (for example an unknown or expired `capture_id`) skip the state walk; their state is classified `not_applicable` / `action_refused_before_dispatch`. Pass `include_accessibility_tree: false` to record screenshots and actions without state.
-
-Turn folders are named `turn-00001/`, `turn-00002/`, etc. Turn numbering restarts at 1 each time recording is (re-)started.
-
-**Video is off by default.** Pass `record_video: true` to also capture the main display to `<output_dir>/recording.mp4` (H.264 / 30 fps) for the lifetime of the session. The recording is torn down automatically when the MCP client disconnects.
-
-**macOS uses native ScreenCaptureKit** (daemon-owned SCStream + SCRecordingOutput) under the daemon's Screen Recording grant, with no ffmpeg subprocess. Requires macOS 15.0+. On macOS 26 (Tahoe), the first direct capture can also show a one-time consent asking to let Cua Driver bypass the system private window picker and directly access your screen and audio; choose Allow, or run `cua-driver permissions grant` beforehand to answer it up front. The recorder captures screen video only and does not enable system-audio capture.
-
-**Windows + Linux use an ffmpeg subprocess** (`gdigrab` / `x11grab` + libx264). Requires ffmpeg on PATH (winget install Gyan.FFmpeg / apt install ffmpeg); when ffmpeg is missing or fails on startup the per-turn capture (screenshots + action.json) still runs and the session's `last_error` field carries the diagnostic.
-
-State persists for the life of the daemon; a restart resets to disabled with no on-disk state. Call `stop_recording` to disable + finalize the mp4.
-
-Effect: mutating, idempotent. Platforms: macOS, Linux, Windows.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="start_recording--include_accessibility_tree"></span>`include_accessibility_tree` | `boolean` | `true` | Default true. Set false to skip the per-turn before/after accessibility walks entirely; screenshots, click markers and action.json are still recorded and state is classified `state_capture_disabled`. |
-| <span id="start_recording--output_dir"></span>`output_dir` | `string` | required | Absolute or ~-rooted directory where turn folders and (when enabled) the video file are written. |
-| <span id="start_recording--record_video"></span>`record_video` | `boolean` | | Capture the main display to &lt;output_dir&gt;/recording.mp4. Default: false. Set to true to also capture the main display to recording.mp4 (otherwise only the per-turn screenshots + JSON are recorded). On macOS this uses native ScreenCaptureKit (macOS 15.0+); macOS 26 can show a one-time direct screen-capture consent on first use (see `cua-driver permissions grant`). On Windows + Linux it requires ffmpeg on PATH. |
-| <span id="start_recording--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
-| <span id="start_recording--state_timeout_ms"></span>`state_timeout_ms` | `integer` | `1000` | Wall-clock budget in milliseconds for EACH per-turn before/after accessibility walk (same default and bounds as get_window_state's timeout_ms). A walk that runs out records the partial tree and marks it truncated in evidence.json. Range: 100 to 120000. |
-
-**Example arguments**
-
-```json
-{"output_dir":"<output_dir>"}
-```
-
-## `stop_recording`
-
-Stop trajectory recording. Disables further per-turn capture and, when video was enabled, gracefully terminates the ffmpeg subprocess so the mp4's moov atom is finalized (the file is playable). Calling stop on an already-stopped session is a no-op. The response carries `last_video_path` pointing at the finalized mp4 (when video was on).
-
-A manual `stop_recording` is **unconditional**: it stops whatever recording is active regardless of which session started it. Ownership-scoped teardown (so one client disconnecting can't stop a recording a later client started) is handled by the registry's `session_end` lifecycle hook, not by this tool.
-
-Effect: mutating, idempotent. Platforms: macOS, Linux, Windows.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="stop_recording--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
-
-## `get_recording_state`
-
-Report the current trajectory recorder state: whether recording is enabled, the output directory (when enabled), and the 1-based counter for the next turn folder that will be written. Counter increments on every recorded action tool call and resets to 1 each time recording is (re-)enabled.
-
-Pure read-only.
-
-Effect: read-only, idempotent. Platforms: macOS, Linux, Windows.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="get_recording_state--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
-
-## `replay_trajectory`
-
-Replay a recorded trajectory by re-invoking every turn's tool call in lexical order. `dir` must point at a directory previously written by `start_recording`. Each `turn-NNNNN/` is parsed for `action.json`, and the recorded tool is called with its recorded `arguments` via the same dispatch path an MCP / CLI call uses.
-
-Caveats:
-- Element-token actions (`click({pid, element_token})` etc.) will fail because element tokens are per-snapshot and don't survive across sessions. Pixel clicks (`click({pid, x, y})`) and all keyboard tools replay cleanly. Failures are reported but don't stop replay unless `stop_on_error` is true.
-- `get_window_state` and other read-only tools are NOT currently recorded, so replays do not re-populate the per-(pid, window_id) element cache.
-- If recording is ENABLED while replay runs, the replay itself is recorded into the currently configured output directory. That's deliberate: recording a replay against a new build and diffing the two trajectories is the regression-test workflow.
-
-Effect: destructive. Platforms: macOS, Linux, Windows.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="replay_trajectory--delay_ms"></span>`delay_ms` | `integer` | | Milliseconds to sleep between turns, for human-observable pacing. Default 500. Range: 0 to 10000. |
-| <span id="replay_trajectory--dir"></span>`dir` | `string` | required | Trajectory directory previously written by `start_recording`. Absolute or ~-rooted. |
-| <span id="replay_trajectory--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
-| <span id="replay_trajectory--stop_on_error"></span>`stop_on_error` | `boolean` | | Stop replay on the first tool-call error. Default true: set false to best-effort through the full trajectory. |
-
-**Example arguments**
-
-```json
-{"dir":"<dir>"}
-```
-
-## `install_ffmpeg`
-
-Install the ffmpeg binary used by start_recording's video capture (Linux/Windows; macOS records natively and needs no ffmpeg). Two-step and confirmed: called without `confirm` it only REPORTS the exact install command for this platform's package manager; pass `confirm: true` to actually run it. No-op if ffmpeg is already on PATH. ffmpeg is run as a separate process, never linked into the driver.
-
-Effect: destructive. Platforms: macOS, Linux, Windows.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="install_ffmpeg--confirm"></span>`confirm` | `boolean` | | Run the install command. Without it, only the planned command is reported. |
-| <span id="install_ffmpeg--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
diff --git a/docs/content/docs/cua-driver/reference/mcp-tools/screen.mdx b/docs/content/docs/cua-driver/reference/mcp-tools/screen.mdx
deleted file mode 100644
index f6fe14595d..0000000000
--- a/docs/content/docs/cua-driver/reference/mcp-tools/screen.mdx
+++ /dev/null
@@ -1,169 +0,0 @@
----
-title: "Screen tools"
-description: "The desktop, screen size, cursor position and zoomed crops."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-driver
- Source: cua-driver dump-docs --type mcp (macOS, Linux and Windows registries)
- Version: 0.36.0
-*/}
-
-import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
-
-| Tool | Description | Platforms |
-| --- | --- | --- |
-| [`get_desktop_state`](#get_desktop_state) | Capture the full display. | macOS, Linux, Windows |
-| [`get_screen_size`](#get_screen_size) | Return the logical size of the main display in points plus its backing scale factor. | macOS, Linux, Windows |
-| [`get_cursor_position`](#get_cursor_position) | Return the current mouse cursor position in screen points (origin top-left). | macOS, Linux, Windows |
-| [`zoom`](#zoom) | Capture a cropped JPEG of a window region (x1,y1)–(x2,y2) in screenshot pixel coordinates, with 20% padding added on each side. | macOS, Linux, Windows |
-
-Served by `cua-driver mcp`; see [MCP tools](/cua-driver/reference/mcp-tools) for every tool.
-
-## `get_desktop_state`
-
-Effect: read-only. Platforms: macOS, Linux, Windows.
-
-<Tabs items={['macOS', 'Linux', 'Windows']} groupId="platform" persist>
-<Tab value="macOS">
-
-Capture the full display. The long edge is capped at `max_image_dimension` (the configured default unless given); pixels of the returned image map back to the screen through its capture. Use its PNG as the coordinate source for actions whose target is &#123;kind:"desktop",display_id:"primary"&#125;. Returns the true screen size and backing scale factor. Vision-only: no AX tree walk.
-
-</Tab>
-<Tab value="Linux">
-
-Capture the full display in the desktop action coordinate frame. Use the returned PNG directly as the coordinate source for actions whose target is &#123;kind:"desktop",display_id:"primary"&#125;. No AT-SPI walk.
-
-</Tab>
-<Tab value="Windows">
-
-Capture the full display in true screen pixels, full size unless `max_image_dimension` caps it. Use its PNG as the coordinate source for actions whose target is &#123;kind:"desktop",display_id:"primary"&#125;. Returns the true screen size. Vision-only: no UIA tree walk.
-
-</Tab>
-</Tabs>
-
-**Parameters on every platform**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="get_desktop_state--max_image_dimension"></span>`max_image_dimension` | `integer` | | Optional long-edge cap for the returned PNG, in pixels (aspect ratio preserved). Omitted or 0 returns the full-size capture. When the cap downsizes the image, the response reports `screenshot_original_width/height`, and x/y read off it for this session's later scope:"desktop" actions (or passed with its `capture_id`) are mapped back to the full-size frame automatically. Minimum: 0. |
-| <span id="get_desktop_state--screenshot_out_file"></span>`screenshot_out_file` | `string` | | Write PNG here instead of base64. |
-| <span id="get_desktop_state--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
-
-## `get_screen_size`
-
-Effect: read-only, idempotent. Platforms: macOS, Linux, Windows.
-
-<Tabs items={['macOS', 'Linux', 'Windows']} groupId="platform" persist>
-<Tab value="macOS">
-
-Return the logical size of the main display in points plus its backing scale factor. Agents click in points; Retina displays have scale_factor 2.0. Requires no TCC permissions.
-
-</Tab>
-<Tab value="Linux">
-
-Return the logical size of the main display in points plus its backing scale factor. Agents click in points; Retina displays have scale_factor 2.0. Requires no TCC permissions.
-
-</Tab>
-<Tab value="Windows">
-
-Return the size of the main display in physical pixels plus its display scale factor. On Windows, screenshots and pixel clicks use this same physical-pixel coordinate space. Requires no special permissions.
-
-</Tab>
-</Tabs>
-
-**Parameters on every platform**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="get_screen_size--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
-
-## `get_cursor_position`
-
-Return the current mouse cursor position in screen points (origin top-left).
-
-Effect: read-only, idempotent. Platforms: macOS, Linux, Windows.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="get_cursor_position--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
-
-## `zoom`
-
-Effect: read-only, idempotent. Platforms: macOS, Linux, Windows.
-
-<Tabs items={['macOS', 'Linux', 'Windows']} groupId="platform" persist>
-<Tab value="macOS">
-
-Capture a cropped JPEG of a window region (x1,y1)–(x2,y2) in screenshot pixel coordinates, with 20% padding added on each side. The output image is at most 500 px wide. Corners, not a size: x1,y1 is the top-left and x2,y2 the bottom-right (x,y,width,height is also accepted and converted).
-
-After a zoom, pass `from_zoom=true` to click/type_text to auto-translate coordinates back to full-window space. Coordinate actions return `screenshot_context_missing` when no current snapshot contains a screenshot owned by this session. `from_zoom` actions return `zoom_context_missing` when the zoom was never created or was replaced; call `get_window_state`, then `zoom`, again on the same connection.
-
-**macOS parameters**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="zoom--macos--pid"></span>`pid` | `integer` | | Optional target pid. When omitted, the driver resolves the unique current snapshot for this session and window. |
-| <span id="zoom--macos--window_id"></span>`window_id` | `integer` | required | CGWindowID from list_windows. |
-| <span id="zoom--macos--x1"></span>`x1` | `number` | required | Left edge of region in screenshot pixels. |
-| <span id="zoom--macos--x2"></span>`x2` | `number` | required | Right edge of region in screenshot pixels. |
-| <span id="zoom--macos--y1"></span>`y1` | `number` | required | Top edge of region in screenshot pixels. |
-| <span id="zoom--macos--y2"></span>`y2` | `number` | required | Bottom edge of region in screenshot pixels. |
-
-</Tab>
-<Tab value="Linux">
-
-Capture a cropped JPEG of a window region (x1,y1)–(x2,y2) in screenshot pixels, with 20% padding. Output is at most 500 px wide. Corners, not a size: x1,y1 is the top-left and x2,y2 the bottom-right (x,y,width,height is also accepted and converted).
-
-After a zoom, pass from_zoom=true to click/type_text to auto-translate coordinates back to full-window space. Coordinate actions return `screenshot_context_missing` when no current snapshot contains a screenshot owned by this session. `from_zoom` actions return `zoom_context_missing` when the zoom was never created or was replaced; call `get_window_state`, then `zoom`, again on the same connection.
-
-**Linux parameters**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="zoom--linux--pid"></span>`pid` | `integer` | | Optional target pid. When omitted, the driver resolves the unique current snapshot for this session and window. |
-| <span id="zoom--linux--window_id"></span>`window_id` | `integer` | required | Window id of the window captured by get_window_state. |
-| <span id="zoom--linux--x1"></span>`x1` | `number` | required | Left edge of the region in window-local screenshot pixels. |
-| <span id="zoom--linux--x2"></span>`x2` | `number` | required | Right edge of the region in window-local screenshot pixels. |
-| <span id="zoom--linux--y1"></span>`y1` | `number` | required | Top edge of the region in window-local screenshot pixels. |
-| <span id="zoom--linux--y2"></span>`y2` | `number` | required | Bottom edge of the region in window-local screenshot pixels. |
-
-</Tab>
-<Tab value="Windows">
-
-Zoom into a rectangular region of a window screenshot at full (native) resolution. Use this when `get_window_state` returned a resized image and you need to read small text, identify icons, or verify UI details.
-
-Corners, not a size: x1,y1 is the top-left and x2,y2 the bottom-right (x,y,width,height is also accepted and converted). Coordinates `x1, y1, x2, y2` are in the same pixel space as the screenshot returned by `get_window_state` (i.e. the resized image if `max_image_dimension` is active). The maximum zoom region width is 500 px in scaled-image coordinates.
-
-A 20% padding is automatically added on every side of the requested region so the target remains visible even if the caller's coordinates are slightly off.
-
-After a zoom, pass `from_zoom=true` to click/type_text to auto-translate coordinates back to full-window space. Coordinate actions return `screenshot_context_missing` when no current snapshot contains a screenshot owned by this session. `from_zoom` actions return `zoom_context_missing` when the zoom was never created or was replaced; call `get_window_state`, then `zoom`, again on the same connection.
-
-Windows-specific: `window_id` is the canonical addressing field (HWND). `pid` is preferred when available; otherwise the driver resolves the unique current snapshot owned by this session and window.
-
-**Windows parameters**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="zoom--windows--pid"></span>`pid` | `integer` | | Optional target process ID. When omitted, the unique current snapshot for this session and HWND is used. |
-| <span id="zoom--windows--window_id"></span>`window_id` | `integer` | required | HWND of the target window. |
-| <span id="zoom--windows--x1"></span>`x1` | `number` | required | Left edge of the region (resized-image pixels). |
-| <span id="zoom--windows--x2"></span>`x2` | `number` | required | Right edge of the region (resized-image pixels). |
-| <span id="zoom--windows--y1"></span>`y1` | `number` | required | Top edge of the region (resized-image pixels). |
-| <span id="zoom--windows--y2"></span>`y2` | `number` | required | Bottom edge of the region (resized-image pixels). |
-
-</Tab>
-</Tabs>
-
-**Parameters on every platform**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="zoom--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
-
-**Example arguments**
-
-```json
-{"window_id":1,"x1":100,"y1":200,"x2":100,"y2":200}
-```
diff --git a/docs/content/docs/cua-driver/reference/mcp-tools/sessions.mdx b/docs/content/docs/cua-driver/reference/mcp-tools/sessions.mdx
deleted file mode 100644
index ed6c04af59..0000000000
--- a/docs/content/docs/cua-driver/reference/mcp-tools/sessions.mdx
+++ /dev/null
@@ -1,108 +0,0 @@
----
-title: "Session tools"
-description: "Start, escalate, inspect and end lifecycle sessions."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-driver
- Source: cua-driver dump-docs --type mcp (macOS, Linux and Windows registries)
- Version: 0.36.0
-*/}
-
-| Tool | Description | Platforms |
-| --- | --- | --- |
-| [`start_session`](#start_session) | Optionally create or return a lifecycle session before acting. | macOS, Linux, Windows |
-| [`escalate_session`](#escalate_session) | Deprecated compatibility tool for legacy capture-scope sessions. | macOS, Linux, Windows |
-| [`get_session`](#get_session) | Read content-free lifecycle, cursor, recording, and idle status for one session visible to this authenticated transport. | macOS, Linux, Windows |
-| [`list_sessions`](#list_sessions) | List content-free lifecycle summaries attached to this authenticated transport lease. | macOS, Linux, Windows |
-| [`get_session_state`](#get_session_state) | Deprecated compatibility alias that reads a live legacy session's capture policy. | macOS, Linux, Windows |
-| [`end_session`](#end_session) | End one visible lifecycle session and run its cursor, recording, configuration, and other cleanup hooks exactly once. | macOS, Linux, Windows |
-
-Served by `cua-driver mcp`; see [MCP tools](/cua-driver/reference/mcp-tools) for every tool.
-
-## `start_session`
-
-Optionally create or return a lifecycle session before acting. For multi-call work, prefer a short public `session` label and repeat it on every call that accepts it; an omitted value uses the authenticated transport lease's implicit session instead. This tool is optional because an ordinary action can create or reuse a named run directly. Use it to set the initial cursor theme before acting or to revive a public name after it has ended; ordinary actions never revive ended names. `capture_scope` is deprecated compatibility input; new callers select window or desktop modality per action. Idempotent.
-
-Effect: mutating, idempotent. Platforms: macOS, Linux, Windows.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="start_session--capture_scope"></span>`capture_scope` | `"auto" \| "window" \| "desktop"` | | Deprecated compatibility policy. New callers select window or desktop modality on each action instead of storing it on the session. |
-| <span id="start_session--cursor_motion"></span>`cursor_motion` | `object` | | Optional initial cursor motion (style, timing, effects and tuning). The host applies it before the cursor is first made visible. A later `set_agent_cursor_motion` call wins; this wins over the saved default (`cursor.motion.*` in the driver config) and the built-in `signature_arc`. Reduced motion always wins. |
-| <span id="start_session--cursor_motion-arc_flow"></span>`cursor_motion.arc_flow` | `number` | | Added to the arc asymmetry of `signature_arc`, `spring_settle` and `comet_swoop`: positive moves the apex toward the destination. Clamped to -1..1 (default 0). |
-| <span id="start_session--cursor_motion-arc_size"></span>`cursor_motion.arc_size` | `number` | | Scales the arc of `signature_arc`, `spring_settle` and `comet_swoop`: 0.25 (default) keeps the style's arc, 0 is a straight line, 0.5 doubles it. Clamped to 0..1. |
-| <span id="start_session--cursor_motion-dwell_after_click_ms"></span>`cursor_motion.dwell_after_click_ms` | `number` | | Pause after a click animation, in milliseconds. Clamped to 0..5000 (default 80). |
-| <span id="start_session--cursor_motion-effects"></span>`cursor_motion.effects` | `object` | | Turn effects on or off. Omit a field to keep it; `"default"` restores the style default. |
-| <span id="start_session--cursor_motion-end_handle"></span>`cursor_motion.end_handle` | `number` | | Arc control-point offset from the end, as a fraction of the distance, for `signature_arc`, `spring_settle` and `comet_swoop`. Clamped to 0..1 (default 0.3). |
-| <span id="start_session--cursor_motion-glide_duration_ms"></span>`cursor_motion.glide_duration_ms` | `number` | | Move duration in milliseconds for `fixed` timing (1430 ms when 0, the default). A nonzero value with `native` or the default `steady` timing also fixes the duration. Clamped to 0..5000. |
-| <span id="start_session--cursor_motion-idle_hide_ms"></span>`cursor_motion.idle_hide_ms` | `number` | | Hide the cursor after this many idle milliseconds; 0 never hides it. Clamped to 0..60000 (default 15000). |
-| <span id="start_session--cursor_motion-spring"></span>`cursor_motion.spring` | `number` | | Arrival spring damping for `classic`: 1 is critically damped, 0.3 is bouncy. Clamped to 0.3..1 (default 0.72). |
-| <span id="start_session--cursor_motion-start_handle"></span>`cursor_motion.start_handle` | `number` | | Arc control-point offset from the start, as a fraction of the distance, for `signature_arc`, `spring_settle` and `comet_swoop`. Clamped to 0..1 (default 0.3). |
-| <span id="start_session--cursor_motion-style"></span>`cursor_motion.style` | `"signature_arc" \| "spring_settle" \| "magnetic" \| "comet_swoop" \| "adaptive" \| "classic"` | | Trajectory style. `signature_arc` (default) is one arc with a small follow-through; `spring_settle` lands with one soft bounce; `magnetic` is pulled into the target; `comet_swoop` is a wide arc with a short trail; `adaptive` picks a careful approach for small targets and a swoop for long moves; `classic` is the previous Dubins glide. When the theme's reduced motion is on, every move is a short straight glide with no effects. |
-| <span id="start_session--cursor_motion-timing"></span>`cursor_motion.timing` | `"native" \| "fitts" \| "fixed" \| "relaxed" \| "steady" \| "calm" \| "deliberate"` | | `steady` (default) keeps the style's timing but makes every move take at least 600 ms, with a gentler ease; `relaxed` and `calm` do the same with a 450 or 750 ms floor. `native` uses the style's own timing; `fitts` scales the move time with distance and target size; `deliberate` is a slower Fitts curve (450..1300 ms); `fixed` uses glide_duration_ms (1430 ms when 0). |
-| <span id="start_session--cursor_motion-turn_radius"></span>`cursor_motion.turn_radius` | `number` | | Minimum turning radius of the `classic` glide path, in points; smaller turns tighter. Clamped to 1..1000 (default 80). |
-| <span id="start_session--cursor_theme"></span>`cursor_theme` | `object` | | Optional initial cursor theme. The host applies it before the cursor is first made visible, avoiding a flash of the default theme. |
-| <span id="start_session--cursor_theme-reduced_motion"></span>`cursor_theme.reduced_motion` | `"auto" \| "on" \| "off"` | `"auto"` | |
-| <span id="start_session--cursor_theme-theme_id"></span>`cursor_theme.theme_id` | `string` | | |
-| <span id="start_session--session"></span>`session` | `string` | | Optional stable public label for this run (e.g. "research-run-1"). When omitted, the authenticated transport lease's implicit session is created or returned. |
-
-## `escalate_session`
-
-Deprecated compatibility tool for legacy capture-scope sessions. New callers select window or desktop modality on each action. No deescalate_session tool exists.
-
-Effect: mutating. Platforms: macOS, Linux, Windows.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="escalate_session--detail"></span>`detail` | `string` | | Optional bounded diagnostic detail. Never use secrets or page content. |
-| <span id="escalate_session--reason"></span>`reason` | `"ax_tree_pixel_mismatch" \| "background_delivery_failed" \| "foreground_ineffective" \| "no_window_target" \| "other"` | required | Why the window-scoped attempt failed and desktop capture is needed. |
-| <span id="escalate_session--session"></span>`session` | `string` | required | Public label of the legacy capture-scope session to escalate. |
-
-**Example arguments**
-
-```json
-{"session":"<session>","reason":"ax_tree_pixel_mismatch"}
-```
-
-## `get_session`
-
-Read content-free lifecycle, cursor, recording, and idle status for one session visible to this authenticated transport. Omit `session` to inspect its implicit session.
-
-Effect: read-only, idempotent. Platforms: macOS, Linux, Windows.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="get_session--session"></span>`session` | `string` | | Optional public label. When omitted, inspect the caller's attached implicit session. |
-
-## `list_sessions`
-
-List content-free lifecycle summaries attached to this authenticated transport lease. It does not enumerate other callers' sessions.
-
-Effect: read-only, idempotent. Platforms: macOS, Linux, Windows.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="list_sessions--cursor"></span>`cursor` | `string` | | Opaque continuation cursor returned by a previous call. |
-| <span id="list_sessions--limit"></span>`limit` | `integer` | | Maximum number of content-free summaries to return (default 50, max 100). Ordinary agent transports are scoped to their own lease. Minimum: 0. |
-
-## `get_session_state`
-
-Deprecated compatibility alias that reads a live legacy session's capture policy. Use get_session for lifecycle state.
-
-Effect: read-only, idempotent. Platforms: macOS, Linux, Windows.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="get_session_state--session"></span>`session` | `string` | | Optional public label. When omitted, inspect the caller's attached implicit session. |
-
-## `end_session`
-
-End one visible lifecycle session and run its cursor, recording, configuration, and other cleanup hooks exactly once. Omit `session` to end the authenticated transport's implicit session. Idempotent.
-
-Effect: destructive, idempotent. Platforms: macOS, Linux, Windows.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="end_session--session"></span>`session` | `string` | | Optional public label to end. When omitted, end the caller's attached implicit session. |
diff --git a/docs/content/docs/cua-driver/reference/mcp-tools/values-and-clipboard.mdx b/docs/content/docs/cua-driver/reference/mcp-tools/values-and-clipboard.mdx
deleted file mode 100644
index 89b4feb877..0000000000
--- a/docs/content/docs/cua-driver/reference/mcp-tools/values-and-clipboard.mdx
+++ /dev/null
@@ -1,114 +0,0 @@
----
-title: "Value and clipboard tools"
-description: "Set element values and read or write the clipboard."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-driver
- Source: cua-driver dump-docs --type mcp (macOS, Linux and Windows registries)
- Version: 0.36.0
-*/}
-
-import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
-
-| Tool | Description | Platforms |
-| --- | --- | --- |
-| [`set_value`](#set_value) | Set an element's value by `element_token`. | macOS, Linux, Windows |
-| [`clipboard_read`](#clipboard_read) | List available system clipboard types and optionally return privacy-sensitive plain text. | macOS, Linux, Windows |
-| [`clipboard_write`](#clipboard_write) | Replace the system clipboard with exactly one value: plain text, an image from an absolute local path, or a file URL from an absolute local path. | macOS, Linux, Windows |
-
-Served by `cua-driver mcp`; see [MCP tools](/cua-driver/reference/mcp-tools) for every tool.
-
-## `set_value`
-
-Effect: destructive, idempotent. Platforms: macOS, Linux, Windows.
-
-<Tabs items={['macOS', 'Linux', 'Windows']} groupId="platform" persist>
-<Tab value="macOS">
-
-Set an element's value by `element_token`. A popup button / select dropdown: selects the menu item whose title or value matches `value` (case-insensitive). Safari `<select>` is set through the DOM; AppKit and Chromium popups list items only while open, so the menu is opened, the item pressed and the menu closed again (in the background the user's front window keeps key focus). An unknown value lists the options. Any other element: writes AXValue (sliders, steppers, date pickers, native text fields).
-
-A Finder file name cell (list or icon view, not being edited) is renamed through Finder's scripting interface with Finder left in the background, and the new name is read back from disk; the value is the full new name with its extension. macOS asks the user once to allow Cua Driver to control Finder. Finder's Get Info `Name` field is refused with `file_name_needs_rename`. For free-form text in web inputs use `type_text_chars`: WebKit ignores AXValue writes.
-
-**macOS parameters**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="set_value--macos--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. |
-| <span id="set_value--macos--value"></span>`value` | `string` | required | New value, coerced to the element's type. |
-| <span id="set_value--macos--window_id"></span>`window_id` | `integer` | | Window ID. Omit with element_token. |
-
-</Tab>
-<Tab value="Linux">
-
-Set value of an AT-SPI element via SetValue action.
-
-**Linux parameters**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="set_value--linux--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | `"background"` | Input delivery mode. 'background' (default) never activates or raises the target window. On X11 it injects via XTEST / the XInput2 master pointer (no focus steal). On Wayland it goes through libei + xdg-desktop-portal, which injects to the compositor's input focus: Wayland's security model has no per-window background targeting, so a specific non-focused window cannot be aimed at; when no libei backend is available the tool returns a structured background_unavailable error. 'foreground' is the explicit escalation: activate the target (X11 _NET_ACTIVE_WINDOW; Wayland compositor activate), inject, then restore the prior active window; a brief focus swap unless the target was already active. Matches the macOS / Windows delivery_mode surface. |
-| <span id="set_value--linux--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
-| <span id="set_value--linux--value"></span>`value` | `string` | required | New value. Written through AT-SPI EditableText/Value when the element exposes them; otherwise (GTK2 spin scales, VCL spin buttons) the field is clicked with the session's real pointer, its text selected and replaced through the virtual keyboard and committed with Tab, then read back. |
-| <span id="set_value--linux--window_id"></span>`window_id` | `integer` | | Omit when element_token is supplied (the token carries it). |
-
-</Tab>
-<Tab value="Windows">
-
-Set a value on a UIA element via the ValuePattern interface.
-
-Two semantic modes (matching Swift's split):
-- **Standard input** (text fields, sliders, combo box edit): writes the value directly through UIA `IUIAutomationValuePattern::SetValue`. This is the canonical Windows write path, equivalent to Swift's `AXValue` write.
-- **ComboBox**: on a native Win32 combo box (WinForms, MFC, dialogs) selects the option whose text matches `value` and sends the app the notifications a user's choice sends (CBN_SELENDOK, CBN_SELCHANGE), without focusing the window; an editable combo gets the text typed into its edit field. A drop-down list without that option is refused with the list of options. Other combo boxes get a UIA value write, which the app may not treat as a selection.
-
-For free-form text entry that the target accepts via keystrokes only, prefer `type_text`: UIA ValuePattern writes are ignored by some web inputs (same caveat as Swift's `AXValue`-vs-WebKit).
-
-**Windows parameters**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="set_value--windows--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | | Input delivery mode. 'background' (default) never swaps foreground: it routes through UIA Invoke / PostMessage and the window is never raised. For targets whose input stack silently drops posted events (Chromium/Electron content, GTK buttons, VCL/LibreOffice accelerators) the tool returns a structured background_unavailable error rather than fronting. 'foreground' is the explicit escalation: a brief SetForegroundWindow swap + SendInput, restoring the prior foreground afterward. IMPORTANT: 'background' is not a hint to weigh; it is the mandatory first attempt. Do NOT pass 'foreground' preemptively because a target 'looks like' GTK/Chromium/Electron; the DRIVER decides when background is impossible and tells you so via a background_unavailable error (or a verified no-op). Only THEN re-issue the same action with 'foreground'. The lists above are the driver's detectors, not a checklist for you to front on a guess: fronting up-front needlessly steals the user's focus and is a bug, not a shortcut. Matches the macOS delivery_mode surface. |
-| <span id="set_value--windows--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
-| <span id="set_value--windows--value"></span>`value` | `string` | required | New value. UIA will coerce to the element's native type. |
-| <span id="set_value--windows--window_id"></span>`window_id` | `integer` | | HWND of the window. Omit when element_token is supplied (the token carries it). |
-
-</Tab>
-</Tabs>
-
-**Parameters on every platform**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="set_value--element_token"></span>`element_token` | `string` | | Element handle `<snapshot_id>:<row>` from get_window_state: row `[11]` of a read whose snapshot_id is s0000002a is "s0000002a:11" (also in `structuredContent.elements[].element_token`). Returns an explicit stale error naming the current snapshots once a newer read supersedes it. |
-| <span id="set_value--pid"></span>`pid` | `integer` | | Target process ID. Optional with element_token (the token carries the pid). |
-
-**Example arguments**
-
-```json
-{"value":"<value>"}
-```
-
-## `clipboard_read`
-
-List available system clipboard types and optionally return privacy-sensitive plain text. Clipboard content is never retained in telemetry.
-
-Effect: read-only. Platforms: macOS, Linux, Windows.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="clipboard_read--include_text"></span>`include_text` | `boolean` | `false` | Return plain-text clipboard content in addition to the available types. Clipboard content is privacy-sensitive and is never retained in telemetry. |
-| <span id="clipboard_read--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
-
-## `clipboard_write`
-
-Replace the system clipboard with exactly one value: plain text, an image from an absolute local path, or a file URL from an absolute local path. Returns the available types for read-back before paste.
-
-Effect: destructive, idempotent. Platforms: macOS, Linux, Windows.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="clipboard_write--file_path"></span>`file_path` | `string` | | Absolute path to a local file to place on the clipboard as a file URL. |
-| <span id="clipboard_write--image_path"></span>`image_path` | `string` | | Absolute path to a local image to place on the clipboard. |
-| <span id="clipboard_write--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
-| <span id="clipboard_write--text"></span>`text` | `string` | | Plain text to place on the clipboard. |
diff --git a/docs/content/docs/cua-driver/reference/mcp-tools/window-state.mdx b/docs/content/docs/cua-driver/reference/mcp-tools/window-state.mdx
deleted file mode 100644
index e1f6251d75..0000000000
--- a/docs/content/docs/cua-driver/reference/mcp-tools/window-state.mdx
+++ /dev/null
@@ -1,235 +0,0 @@
----
-title: "Window state tools"
-description: "Screenshots, accessibility trees, verification and visual regions of a window."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:cua-driver
- Source: cua-driver dump-docs --type mcp (macOS, Linux and Windows registries)
- Version: 0.36.0
-*/}
-
-import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
-
-| Tool | Description | Platforms |
-| --- | --- | --- |
-| [`get_window_state`](#get_window_state) | Snapshot a window: the accessibility tree plus a screenshot. | macOS, Linux, Windows |
-| [`get_accessibility_tree`](#get_accessibility_tree) | Return a lightweight snapshot of the desktop: running regular apps and on-screen visible windows with their bounds, z-order, and owner pid. | macOS, Linux, Windows |
-| [`verify_state`](#verify_state) | Deterministically verify bounded predicates against one exact window. | macOS, Linux, Windows |
-| [`parse_visual_regions`](#parse_visual_regions) | Parse one immutable registered capture into model-neutral text and icon regions. | macOS, Linux, Windows |
-
-Served by `cua-driver mcp`; see [MCP tools](/cua-driver/reference/mcp-tools) for every tool.
-
-## `get_window_state`
-
-Effect: read-only. Platforms: macOS, Linux, Windows.
-
-<Tabs items={['macOS', 'Linux', 'Windows']} groupId="platform" persist>
-<Tab value="macOS">
-
-Snapshot a window: the accessibility tree plus a screenshot. By default the tree is ONE compact Markdown rendering (`tree_format:"markdown"`): a row `[N]` is addressed with `element_token` `<snapshot_id>:N`, where `snapshot_id` is in the response header and in structuredContent. `tree_format:"elements"` returns the structured `elements` array instead (`element_index`, `element_token`, `role`, `label`, `value`, `actions`, `frame`, `parent_index`, `depth`); `"both"` returns both (about twice the size). Pass the token to click, type_text, press_key, etc.
-
-START NARROW: a read walks at most 250 nodes by default and says `Tree truncated at max_elements=…` (`truncated:true`) when it stops; raise `max_elements`, or use `query` (case-insensitive substring; matching rows plus ancestors) and `max_depth`. Indices and tokens stay valid for the whole snapshot. `verbose:true` adds `_note` and the full `background_input` report; `full_output:true` restores the previous full response (both representations, all metadata, ≤2 000 nodes).
-
-DIFF READS (use them for every re-read after acting): `since:"latest"`, or `since:<snapshot_id>` from an earlier read of the same window, returns only what changed: `+` added, `~` changed, `-` removed rows (removed ids are the old snapshot's), a `reindexed:` line if indices shifted, or `no change since …; focused element is …`. The response carries a NEW snapshot_id: use it in tokens. An unknown, expired, other-window or differently-scoped (query/max_elements/max_depth) `since` falls back to a full read; `since_status` says why.
-
-A new snapshot of the same (pid, window_id) replaces the previous one and stales its tokens (`invalidated_snapshot_ids`). `include_screenshot:false` returns the tree only and keeps the last screenshot's pixel frame while the window keeps its size; `include_accessibility_tree:false` returns only the screenshot and keeps the current snapshot's rows and tokens valid (use it, not `max_elements:1`, when you just need to look); adding `display_only:true` (live previews) also leaves the pixel frame alone. The tree can lie on some surfaces (Electron, Catalyst, virtualized rows with `h:1` frames): cross-check the screenshot, and use pixel x,y at action time only for elements missing from the tree.
-
-Refusals: `window_id_not_found`; `window_owner_pid_mismatch` names the real `owner_pid` (sandboxed Open/Save panels belong to a panel service). `degraded_reason` `ax_window_unresolved` or `ax_app_launching` (the latter with `truncation_reason: app_lookup_timeout`) means an empty tree: re-snapshot, or act with `delivery_mode:"foreground"`. `degraded_reason` `screen_locked` means the screen saver, display sleep or a lock hid every window from accessibility: wake and unlock the Mac, then re-snapshot; foreground input would reach the lock screen. `px_frame_mismatch` / `px_capture_unavailable` omit the unprovable screenshot; the AX payload stays valid.
-
-**macOS parameters**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="get_window_state--macos--include_accessibility_tree"></span>`include_accessibility_tree` | `boolean` | | Default true. False skips the AX walk and returns the screenshot plus window metadata. Both this and include_screenshot false is an error. |
-| <span id="get_window_state--macos--include_screenshot"></span>`include_screenshot` | `boolean` | | Default true. False returns the tree only (saves image tokens and latency); screenshot_out_file still forces a capture. |
-| <span id="get_window_state--macos--max_depth"></span>`max_depth` | `integer` | | Cap on walk depth. Default 25. Minimum: 1. |
-| <span id="get_window_state--macos--max_dimension"></span>`max_dimension` | `integer` | | Optional cap on the returned screenshot's long edge, in pixels (aspect ratio preserved): the cheap path for a small preview / thumbnail. Applied on top of the session/global max_image_dimension ceiling; the tighter of the two wins. Omit for the configured default. Minimum: 1. |
-| <span id="get_window_state--macos--max_elements"></span>`max_elements` | `integer` | | Cap on AX nodes walked (depth-first; markdown and elements truncate together). Default 250 (2 000 with full_output:true); the response states when the tree was cut. Minimum: 1. |
-| <span id="get_window_state--macos--max_image_dimension"></span>`max_image_dimension` | `integer` | | Per-call override for the returned screenshot's long edge in pixels. An explicit value wins over the session/global setting; 0 returns native resolution. Omit to preserve configured behavior. Minimum: 0. |
-| <span id="get_window_state--macos--pid"></span>`pid` | `integer` | required | Target process ID. |
-| <span id="get_window_state--macos--query"></span>`query` | `string` | | Case-insensitive substring filter: returns matching rows plus ancestors; element_index values are not renumbered. Try this before a full read. |
-| <span id="get_window_state--macos--screenshot_out_file"></span>`screenshot_out_file` | `string` | | When set, write the PNG to this file path (~ expanded) instead of embedding base64 in the response. The structured output will contain screenshot_file_path instead. |
-| <span id="get_window_state--macos--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. |
-| <span id="get_window_state--macos--window_id"></span>`window_id` | `integer` | required | Target window ID from list_windows. |
-
-</Tab>
-<Tab value="Linux">
-
-Walk a running app's AT-SPI tree and return it ONCE, as compact Markdown by default (`tree_format:"markdown"`). Every actionable element is tagged `[N]` (an element_index); its element_token is `<snapshot_id>:N`, where `snapshot_id` is printed in the response header and returned in structuredContent. Pass `tree_format:"elements"` for the structured `elements` array instead (explicit `element_token`, `role`, `label`, `value`, `enabled`, `selected`, `actions`, `frame: {x,y,w,h}` when AT-SPI reports usable bounds, `parent_index`, `depth`), or `"both"` for both (about twice the size). Set `query` to project the tree to matching rows plus their ancestor chain while preserving original indices; `total_element_count` reports the complete snapshot.
-
-Size: a read is bounded by default (`max_elements` 250 actionable nodes). When the walk stops at that budget the response says `Tree truncated at max_elements=…` and `truncated: true`; pass a larger `max_elements`, or `query` / `max_depth`, to reach the rest. `_note` is omitted unless `verbose:true`. `full_output:true` restores the previous full response: both representations, all metadata, and the walker's own limits (≤5 000 nodes).
-
-DIFF READS: pass `since: <snapshot_id>` from an earlier read of the same window to get only what changed: `+` added rows, `~` changed rows, `-` removed rows (their ids are the old snapshot's), or `no change since …`. Rows not listed keep their previous `[N]` unless a `reindexed:` line says otherwise. The response carries a NEW snapshot_id: use it in element_tokens. An unknown, expired, other-window or differently-scoped (query/max_elements/max_depth) `since` falls back to a full read and `since_status` says why. The focused element is not reported on Linux yet.
-
-Always returns BOTH the element tree AND a screenshot: ground on both and cross-check (the tree lies on some surfaces). Choose the modality at ACTION time: an element ax action (element_token → accessibility rung) or an element px action (x,y → pixel rung off this screenshot). capture_mode is deprecated and ignored. On Wayland, where output capture cannot prove the requested surface's identity, the truthful tree is returned without a screenshot and `screenshot_error.code` is `surface_identity_unproven`.
-
-The mirror image: pass `include_accessibility_tree:false` to SKIP the AT-SPI walk entirely and return just the screenshot plus window metadata (window_bounds, app_name, window_title); the capture-only path for a live window preview / picture-in-picture. Setting BOTH `include_accessibility_tree:false` and `include_screenshot:false` is an error. Optional `max_dimension` caps the returned screenshot's long edge in pixels for a cheap thumbnail.
-
-Optional `max_elements` / `max_depth` bound the AT-SPI walk (Electron / large web apps produce 10k+ element trees). Markdown and structured elements are truncated identically. Default: `max_elements` 250.
-
-TIME BUDGET: `timeout_ms` (default 1000) bounds the whole AT-SPI walk. When omitted, a window's first snapshot gets a 2000 ms cold-start budget so Chromium/Electron can finish publishing its initial tree. Explicit values are always honored. Large apps (LibreOffice, GIMP, file managers) can exceed the budget; the call then returns the PARTIAL tree with `truncated: true`, `truncation_reason`, `nodes_visited`/`nodes_pending` and `elements_complete: false`. Every element listed is real and clickable; elements after the cut are simply missing. Retry with a larger `timeout_ms` (e.g. 5000) or narrow with `query`/`max_depth` when the element you need is absent.
-
-SCREENSHOT SCALE: the screenshot is delivered at or below 1.15 megapixels (long edge &lt;= max_image_dimension, 1568 by default), because larger images are downsized before a model reads them and its pixel coordinates would then be uniformly short. Element `screenshot_frame`s and x/y for the pointer tools are pixels of the delivered screenshot (`frame` stays in screen coordinates, as on every platform); `frame_scale` &lt; 1 reports the downsizing. An explicit per-call `max_image_dimension` (0 = native) replaces this cap.
-
-POPUP MENUS: a context menu / popover / combo list is an override-redirect window that list_windows never shows. A click or right_click that opened one names it in its result (`popup: {window_id, bounds, title}`); pass that window_id here to walk the popup's own AT-SPI toplevel so its menu items get element indices (then click them by element_token). Omitting window_id while a popup of this pid is open walks that popup.
-
-**Linux parameters**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="get_window_state--linux--include_accessibility_tree"></span>`include_accessibility_tree` | `boolean` | | Default true: walk the AT-SPI tree and return it (per `tree_format`) alongside the screenshot. Set false to SKIP the AT-SPI walk entirely and return just the screenshot plus window metadata (window_bounds, app_name, window_title): the capture-only path for a live window preview / picture-in-picture. Mirrors include_screenshot. Setting BOTH include_accessibility_tree:false AND include_screenshot:false is an error (nothing to return). |
-| <span id="get_window_state--linux--include_screenshot"></span>`include_screenshot` | `boolean` | | Default true: returns a grounding screenshot alongside the tree. Set false to skip the grab and return tree only (the cheap path for re-indexing before an element ax action). |
-| <span id="get_window_state--linux--max_depth"></span>`max_depth` | `integer` | | Cap on the AT-SPI tree walk depth. Omit for the default (uncapped). Lower for deeply nested apps. Minimum: 1. |
-| <span id="get_window_state--linux--max_dimension"></span>`max_dimension` | `integer` | | Legacy optional cap on the returned screenshot's long edge. Applied on top of the configured max_image_dimension ceiling when max_image_dimension is omitted. Minimum: 1. |
-| <span id="get_window_state--linux--max_elements"></span>`max_elements` | `integer` | | Cap on total AT-SPI nodes walked. Default 250 (5 000 with full_output:true); the response states when the tree was cut. Raise it to read further into a large window. Minimum: 1. |
-| <span id="get_window_state--linux--max_image_dimension"></span>`max_image_dimension` | `integer` | | Per-call long-edge override. This value wins over configured and legacy limits; 0 returns native-resolution PNG bytes. Omit to preserve configured behavior. Minimum: 0. |
-| <span id="get_window_state--linux--pid"></span>`pid` | `integer` | required | Process ID that owns the window. |
-| <span id="get_window_state--linux--query"></span>`query` | `string` | | Optional case-insensitive substring. Projects both tree_markdown and structured elements to matches plus ancestors while preserving original indices. Compare total_element_count with returned_element_count. |
-| <span id="get_window_state--linux--screenshot_out_file"></span>`screenshot_out_file` | `string` | | When set, write the PNG to this file path (~ expanded) instead of embedding base64 in the response. The structured output carries screenshot_file_path instead. |
-| <span id="get_window_state--linux--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
-| <span id="get_window_state--linux--window_id"></span>`window_id` | `integer` | | Native window identifier from list_windows, or the `popup.window_id` a click / right_click result named (an open context menu / popover; its menu items then get element indices). Omitted: the pid's open popup menu when one is mapped, else its focused / active / largest window. |
-
-</Tab>
-<Tab value="Windows">
-
-Walk a running app's UIA tree and return it ONCE, as compact Markdown by default (`tree_format:"markdown"`). Every actionable element is tagged `[N]` (an element_index); its element_token is `<snapshot_id>:N`, where `snapshot_id` is printed in the response header and returned in structuredContent. Pass `tree_format:"elements"` for the structured `elements` array instead (explicit `element_token`, `frame`, `parent_index`, `value`, `actions` per row), or `"both"` for both (about twice the size).
-
-Size: a read is bounded by default (`max_elements` 250). When the walk stops at that budget the response says `Tree truncated at max_elements=…` and `truncated: true`; pass a larger `max_elements`, or `query` / `max_depth`, to reach the rest. `_note` is omitted unless `verbose:true`. `full_output:true` restores the previous full response: both representations, all metadata, and the platform's walk limits (≤5 000 elements, depth ≤25).
-
-DIFF READS: pass `since: <snapshot_id>` from an earlier read of the same window to get only what changed: `+` added rows, `~` changed rows, `-` removed rows (their ids are the old snapshot's), or `no change since …`. Rows not listed keep their previous `[N]` unless a `reindexed:` line says otherwise. The response carries a NEW snapshot_id: use it in element_tokens. An unknown, expired, other-window or differently-scoped (query/max_elements/max_depth) `since` falls back to a full read and `since_status` says why. The focused element is not reported on Windows yet.
-
-INVARIANT: call `get_window_state` once per turn per (pid, window_id) before any element action against that window. The next snapshot of the same (pid, window_id) replaces this one, stales its element tokens, and lists the replaced ids in `invalidated_snapshot_ids`. A screenshot-only read (`include_accessibility_tree:false`) keeps the current snapshot's rows and tokens valid, and `display_only:true` also leaves its pixel frame alone.
-
-The UIA tree walked is the window's tree (HWND-scoped); the screenshot and window bounds reported come from the same `window_id`. This is the source of truth for which window the caller intends to reason about: the driver never picks a window implicitly.
-
-`window_id` MUST belong to `pid`; the call returns `isError: true` otherwise. The driver does not auto-fall-back to a different window.
-
-Set `query` to a case-insensitive substring to project the tree to matching rows plus their ancestor chain. Original element indices are preserved. `total_element_count` reports the complete snapshot; `returned_element_count` reports the projection.
-
-Always returns BOTH the element tree AND a screenshot: ground on both and cross-check (the tree lies on some surfaces). Choose the modality at ACTION time: an element ax action (element_token → accessibility rung) or an element px action (x,y → pixel rung off this screenshot). capture_mode is deprecated and ignored.
-
-The mirror image: pass `include_accessibility_tree:false` to SKIP the UIA walk entirely and return just the screenshot plus window metadata (window_bounds, app_name, window_title); the capture-only path for a live window preview / picture-in-picture. Setting BOTH `include_accessibility_tree:false` and `include_screenshot:false` is an error. Optional `max_image_dimension` overrides the configured screenshot long-edge limit for this call; pass 0 for native resolution. Legacy `max_dimension` remains a cap on the configured limit.
-
-Uses `IUIAutomationCacheRequest` to batch-fetch all element properties in a single COM call (Chrome's ~5000-element tree returns in ~2-3s instead of timing out at 4s with per-property RPCs).
-
-Optional `max_elements` / `max_depth` bound the UIA walk (Electron / large web apps produce 10k+ element trees). Markdown and structured elements are truncated identically. Default: `max_elements` 250, depth ≤25.
-
-CHROMIUM COVERAGE: a browser-owned permission bubble can be composited outside the requested native window. Chromium-family snapshots therefore describe this limit in structuredContent.capture_coverage. After a verified ineffective window action, call escalate_session, take a fresh get_desktop_state snapshot, act explicitly in desktop scope if needed, then verify with another fresh desktop snapshot. This is separate from page JavaScript dialogs, which remain on browser_dialog.
-
-Windows requires no special permissions.
-
-**Windows parameters**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="get_window_state--windows--include_accessibility_tree"></span>`include_accessibility_tree` | `boolean` | | Default true: walk the UIA tree and return it (per `tree_format`) alongside the screenshot. Set false to SKIP the UIA walk entirely and return just the screenshot plus window metadata (window_bounds, app_name, window_title): the capture-only path for a live window preview / picture-in-picture. Mirrors include_screenshot. Setting BOTH include_accessibility_tree:false AND include_screenshot:false is an error (nothing to return). |
-| <span id="get_window_state--windows--include_screenshot"></span>`include_screenshot` | `boolean` | | Default true: returns a grounding screenshot alongside the tree. Set false to skip the grab and return tree only (the cheap path for re-indexing before an element ax action). |
-| <span id="get_window_state--windows--max_depth"></span>`max_depth` | `integer` | | Cap on the UIA-tree walk depth. Nodes whose rendered indent would exceed this are omitted. Omit for the default (25). Lower for deep menu / Electron trees. Minimum: 1. |
-| <span id="get_window_state--windows--max_dimension"></span>`max_dimension` | `integer` | | Legacy optional cap on the returned screenshot's long edge, in pixels (aspect ratio preserved). Applied on top of the configured max_image_dimension ceiling when max_image_dimension is omitted; the tighter wins. Minimum: 1. |
-| <span id="get_window_state--windows--max_elements"></span>`max_elements` | `integer` | | Cap on the total number of UIA nodes walked. Truncates depth-first; markdown and structured elements truncate together. Default 250 (5 000 with full_output:true); the response states when the tree was cut. Raise it to read further into a large window. Minimum: 1. |
-| <span id="get_window_state--windows--max_image_dimension"></span>`max_image_dimension` | `integer` | | Per-call long-edge limit for the returned screenshot, in pixels (aspect ratio preserved). Explicit values override configured behavior; 0 returns native resolution. Omit to preserve the configured default. Minimum: 0. |
-| <span id="get_window_state--windows--pid"></span>`pid` | `integer` | required | Process ID from `list_apps`. |
-| <span id="get_window_state--windows--query"></span>`query` | `string` | | Optional case-insensitive substring. Projects both tree_markdown and structured elements to matches plus ancestors while preserving original indices. Compare total_element_count with returned_element_count. |
-| <span id="get_window_state--windows--screenshot_out_file"></span>`screenshot_out_file` | `string` | | When set, write the PNG to this file path instead of embedding base64 in the response. The structured output will contain `screenshot_file_path` instead. |
-| <span id="get_window_state--windows--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
-| <span id="get_window_state--windows--window_id"></span>`window_id` | `integer` | required | HWND of the target window. Must belong to `pid`. Enumerate via `list_windows` or read from `launch_app`'s `windows` array. |
-
-</Tab>
-</Tabs>
-
-**Parameters on every platform**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="get_window_state--capture_mode"></span>`capture_mode` | `"ax" \| "vision"` | | DEPRECATED and ignored. get_window_state always returns BOTH the element tree and a screenshot: ground on both. The modality is chosen at action time by how you address the target: an element ax action (element_token) or an element px action (x,y). Any value (including the old "som"/"screenshot" aliases) is accepted but has no effect. |
-| <span id="get_window_state--display_only"></span>`display_only` | `boolean` | | Default false. With include_accessibility_tree:false, returns pixels for display without registering an action capture or replacing the agent snapshot. The image cannot ground input actions. |
-| <span id="get_window_state--full_output"></span>`full_output` | `boolean` | | Default false. Set true to restore the previous full response: both `elements` and `tree_markdown`, all metadata, and the platform's own walk limits unless max_elements / max_depth are passed. Does not combine with `since`. |
-| <span id="get_window_state--since"></span>`since` | `string` | | A `snapshot_id` from an earlier get_window_state of the same window, or "latest" for this window's most recent read with the same query/max_elements/max_depth. Use it on every re-read after acting. Returns only what changed against that snapshot: `+` added rows, `~` changed rows, `-` removed rows (removed ids are the old snapshot's), or `no change`. Falls back to a full read when the snapshot is unknown, expired, belongs to another window, or was read with a different query/max_elements/max_depth; `since_status` says which. The response still carries a NEW snapshot_id and its element_tokens; rows not listed keep their previous [N] unless a `reindexed:` line says otherwise. |
-| <span id="get_window_state--timeout_ms"></span>`timeout_ms` | `integer` | `1000` | Wall-clock budget in milliseconds for the accessibility-tree walk (default 1000, min 100, max 120000). Bounds the WHOLE walk. When the budget runs out the tool returns the PARTIAL tree it has, flagged with `truncated: true`, `truncation_reason`, `nodes_visited`, `nodes_pending` and `elements_complete: false`; retry with a larger value (e.g. 5000) or narrow with `query` / `max_depth`. Range: 100 to 120000. |
-| <span id="get_window_state--tree_format"></span>`tree_format` | `"markdown" \| "elements" \| "both"` | | Which tree representation to return. Default "markdown": the compact `tree_markdown` only, where a row `[N]` is addressed with element_token `<snapshot_id>:N`. "elements": the structured `elements` array only (per-element element_token, frame, parent_index, value). "both": the two together, as before; roughly doubles the size. |
-| <span id="get_window_state--verbose"></span>`verbose` | `boolean` | | Default false. Set true to include the `_note` string and the full `background_input` capability report (macOS), which are omitted by default to save context. |
-
-**Example arguments**
-
-```json
-{"pid":1,"window_id":1}
-```
-
-## `get_accessibility_tree`
-
-Effect: read-only, idempotent. Platforms: macOS, Linux, Windows.
-
-<Tabs items={['macOS', 'Linux', 'Windows']} groupId="platform" persist>
-<Tab value="macOS">
-
-Return a lightweight snapshot of the desktop: running regular apps and on-screen visible windows with their bounds, z-order, and owner pid.
-
-For the full AX subtree of a single window (with interactive element indices you can click by), use `get_window_state` instead: that's the heavy per-window tool. This one is a fast discovery read that needs no TCC grants.
-
-</Tab>
-<Tab value="Linux">
-
-Return a lightweight snapshot of the desktop: running processes and on-screen visible X11 windows with their bounds and owner pid.
-
-For the full AT-SPI subtree of a single window (with interactive element indices you can click by), use get_window_state instead: this is a fast discovery read.
-
-</Tab>
-<Tab value="Windows">
-
-Return a lightweight snapshot of the desktop: running processes and on-screen visible windows with their bounds and owner pid.
-
-For the full UIA subtree of a single window (with interactive element indices you can click by), use get_window_state instead: this is a fast discovery read.
-
-</Tab>
-</Tabs>
-
-**Parameters on every platform**
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="get_accessibility_tree--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
-
-## `verify_state`
-
-Deterministically verify bounded predicates against one exact window. The driver evaluates structured window/accessibility state and may return the final screenshot as uninterpreted visual evidence for a multimodal caller. Predicate results are satisfied, unsatisfied, or unknown; unknown never implies success. Accessibility projections are conservative: absence remains unknown unless the observed search domain is proven exhaustive.
-
-Effect: read-only. Platforms: macOS, Linux, Windows.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="verify_state--expect"></span>`expect` | `object[]` | required | One to eight predicates, combined with logical AND. Items: 1 to 8. |
-| <span id="verify_state--include_screenshot"></span>`include_screenshot` | `boolean` | | Return the final window screenshot as image content for a multimodal caller. The driver does not interpret that image. |
-| <span id="verify_state--pid"></span>`pid` | `integer` | required | Exact process whose window may be observed. Minimum: 1. |
-| <span id="verify_state--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. This field never selects capture modality or authorization. |
-| <span id="verify_state--stable_samples"></span>`stable_samples` | `integer` | `2` | Consecutive satisfied samples required before returning success. Range: 1 to 5. |
-| <span id="verify_state--timeout_ms"></span>`timeout_ms` | `integer` | `5000` | Bounded wait. Zero performs one sample. Range: 0 to 10000. |
-| <span id="verify_state--window_id"></span>`window_id` | `integer` | required | Exact native window identifier. |
-
-**Example arguments**
-
-```json
-{"pid":1,"window_id":1,"expect":[{}]}
-```
-
-## `parse_visual_regions`
-
-Parse one immutable registered capture into model-neutral text and icon regions.
-
-Effect: read-only, idempotent. Platforms: macOS, Linux, Windows.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="parse_visual_regions--capture_id"></span>`capture_id` | `string` | required | `capture_id` of a screenshot returned by get_window_state or get_desktop_state. |
-| <span id="parse_visual_regions--options"></span>`options` | `object` | `{}` | Optional, model-neutral controls for one bounded parse. |
-| <span id="parse_visual_regions--options-kinds"></span>`options.kinds` | `"text" \| "icon"[]` | | Region kinds to return (`text`, `icon`). Omit for all kinds. Items: 1 to 2. |
-| <span id="parse_visual_regions--options-max_regions"></span>`options.max_regions` | `integer` | | Return at most this many regions. Minimum: 1. |
-| <span id="parse_visual_regions--options-min_confidence"></span>`options.min_confidence` | `number` | | Drop regions below this confidence (0 to 1). Range: 0 to 1. |
-| <span id="parse_visual_regions--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |
-
-**Example arguments**
-
-```json
-{"capture_id":"<capture_id>"}
-```
diff --git a/docs/content/docs/cua-sdk/guides/images.mdx b/docs/content/docs/cua-sdk/guides/images.mdx
index eb98147808..ed152c00fc 100644
--- a/docs/content/docs/cua-sdk/guides/images.mdx
+++ b/docs/content/docs/cua-sdk/guides/images.mdx
@@ -101,7 +101,7 @@ cua sb create python:3.12-slim --name app -- python -m http.server 8000
Each builder method returns a new, immutable `Image`. Steps build into your
container engine before boot (VM images apply them after boot through
cua-spacesd). To build once and reuse an image, use
-[`cua image build` and `cua image push`](/cua-cli/reference/cli/image).
+[`cua image build` and `cua image push`](/cua-cli/reference/cli/sandboxes#cua-image).
```python test="docs" id="install-packages" session="build"
from cua_sandbox import Image
diff --git a/docs/content/docs/lume/guides/manage-vms.mdx b/docs/content/docs/lume/guides/manage-vms.mdx
index 3ea6f3fd04..21dc49bb04 100644
--- a/docs/content/docs/lume/guides/manage-vms.mdx
+++ b/docs/content/docs/lume/guides/manage-vms.mdx
@@ -174,7 +174,7 @@ path that `which lume` prints:
Restart the client. It can then list, create, run, stop, clone and resize VMs,
and run SSH commands in unattended guests (see the
-[MCP tools](/lume/reference/mcp-tools)). To test the server on its own:
+[MCP tools](/lume/reference/http-api#mcp-tools)). To test the server on its own:
```bash skip="third-party-cli"
npx @modelcontextprotocol/inspector lume serve --mcp
diff --git a/docs/content/docs/lume/reference/cli.mdx b/docs/content/docs/lume/reference/cli.mdx
new file mode 100644
index 0000000000..e8192690fa
--- /dev/null
+++ b/docs/content/docs/lume/reference/cli.mdx
@@ -0,0 +1,1283 @@
+---
+title: "lume CLI"
+description: "A lightweight CLI and local API server to build, run and manage macOS VMs."
+---
+
+{/*
+ AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
+ Generated by: pnpm --dir docs docs:generate:lume
+ Source: lume dump-docs --type cli
+ Version: 0.6.1
+*/}
+
+```text output
+lume [OPTIONS] <COMMAND>
+```
+
+Run `lume <command> --help` for the build you have.
+
+## Commands
+
+| Command | Description |
+| --- | --- |
+| [`lume create`](#lume-create) | Create a new virtual machine. |
+| [`lume run`](#lume-run) | Run a virtual machine. |
+| [`lume attach`](#lume-attach) | Open a viewer for a running virtual machine. |
+| [`lume stop`](#lume-stop) | Stop a virtual machine. |
+| [`lume shutdown`](#lume-shutdown) | Gracefully shut down a virtual machine. |
+| [`lume restart`](#lume-restart) | Gracefully restart a virtual machine. |
+| [`lume ls`](#lume-ls) | List virtual machines. |
+| [`lume get`](#lume-get) | Get detailed information about a virtual machine. |
+| [`lume set`](#lume-set) | Set new values for CPU, memory, and disk size of a virtual machine. |
+| [`lume clone`](#lume-clone) | Clone an existing virtual machine. |
+| [`lume delete`](#lume-delete) | Delete a virtual machine. |
+| [`lume images`](#lume-images) | List available macOS images from local cache. |
+| [`lume pull`](#lume-pull) | Pull a prebuilt or custom macOS image from an OCI-compatible registry. |
+| [`lume push`](#lume-push) | Push a macOS VM to an OCI-compatible registry. |
+| [`lume convert`](#lume-convert) | Convert a legacy Lume image to OCI-compliant format. |
+| [`lume ipsw`](#lume-ipsw) | Get macOS restore image IPSW URL. |
+| [`lume prune`](#lume-prune) | Remove cached images. |
+| [`lume setup`](#lume-setup) | Prepare unattended macOS setup. |
+| [`lume ssh`](#lume-ssh) | Connect to a VM via SSH or execute commands remotely. |
+| [`lume cp`](#lume-cp) | Copy files between the host and a VM. |
+| [`lume sip`](#lume-sip) | Enable or disable System Integrity Protection on a macOS VM. |
+| [`lume serve`](#lume-serve) | Start the VM management server. |
+| [`lume logs`](#lume-logs) | View lume serve logs. |
+| [`lume logs info`](#lume-logs-info) | View info logs from the daemon. |
+| [`lume logs error`](#lume-logs-error) | View error logs from the daemon. |
+| [`lume logs all`](#lume-logs-all) | View both info and error logs from the daemon. |
+| [`lume dump-docs`](#lume-dump-docs) | Output CLI and API documentation as JSON for tooling and integrations. |
+| [`lume config`](#lume-config) | Get or set lume configuration. |
+| [`lume config get`](#lume-config-get) | Get current configuration. |
+| [`lume config storage`](#lume-config-storage) | Manage VM storage locations. |
+| [`lume config storage add`](#lume-config-storage-add) | Add a new VM storage location. |
+| [`lume config storage remove`](#lume-config-storage-remove) | Remove a VM storage location. |
+| [`lume config storage list`](#lume-config-storage-list) | List all VM storage locations. |
+| [`lume config storage default`](#lume-config-storage-default) | Set the default VM storage location. |
+| [`lume config cache`](#lume-config-cache) | Manage image cache settings. |
+| [`lume config cache dir`](#lume-config-cache-dir) | Get or set cache directory. |
+| [`lume config cache enable`](#lume-config-cache-enable) | Enable image caching. |
+| [`lume config cache disable`](#lume-config-cache-disable) | Disable image caching. |
+| [`lume config cache status`](#lume-config-cache-status) | Show cache status and directory. |
+| [`lume config telemetry`](#lume-config-telemetry) | Manage pseudonymous telemetry settings. |
+| [`lume config telemetry status`](#lume-config-telemetry-status) | Show current telemetry status. |
+| [`lume config telemetry enable`](#lume-config-telemetry-enable) | Enable pseudonymous telemetry. |
+| [`lume config telemetry disable`](#lume-config-telemetry-disable) | Disable pseudonymous telemetry. |
+| [`lume config telemetry reset-id`](#lume-config-telemetry-reset-id) | Delete the pseudonymous installation ID and registration markers. |
+| [`lume config registry`](#lume-config-registry) | Manage container registry settings. |
+| [`lume config registry status`](#lume-config-registry-status) | Show current registry configuration. |
+| [`lume config registry type`](#lume-config-registry-type) | Get or set registry type. |
+| [`lume config registry ghcr`](#lume-config-registry-ghcr) | Configure GitHub Container Registry settings. |
+| [`lume config registry gcs`](#lume-config-registry-gcs) | Configure GCS registry settings. |
+| [`lume config network`](#lume-config-network) | Manage network settings. |
+| [`lume config network interfaces`](#lume-config-network-interfaces) | List available network interfaces for bridged networking. |
+| [`lume check-update`](#lume-check-update) | Check whether a newer Lume release is available. |
+| [`lume update`](#lume-update) | Check for a Lume update and optionally apply it. |
+| [`lume channel`](#lume-channel) | Inspect or change the stable/nightly update channel; selection does not install. |
+| [`lume channel status`](#lume-channel-status) | Show selected and current release channels. |
+| [`lume channel set`](#lume-channel-set) | Save stable or nightly as the update channel. |
+
+## VMs
+
+Create, run, inspect, change, clone and delete virtual machines.
+
+### `lume create`
+
+Create a new virtual machine.
+
+```text output
+lume create [OPTIONS] <name>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<name>` | string | required | Name for the virtual machine. |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="lume-create--os"></span>`--os` | string | `macOS` | Operating system to install: macOS or linux. |
+| <span id="lume-create--cpu"></span>`--cpu` | integer | `4` | Number of CPU cores. |
+| <span id="lume-create--memory"></span>`--memory` | string | `8GB` | Memory size (8, 8GB or 8192MB; a bare number is GB). |
+| <span id="lume-create--disk-size"></span>`--disk-size` | string | | Disk size (100, 100GB or 102400MB; a bare number is GB). Defaults to 100GB for macOS and 50GB for Linux. |
+| <span id="lume-create--display"></span>`--display` | string | `1024x768` | Display resolution as WIDTHxHEIGHT. |
+| <span id="lume-create--ipsw"></span>`--ipsw` | string | | Path to a macOS restore image (IPSW), or 'latest' to download the latest supported version. Required for macOS VMs. |
+| <span id="lume-create--storage"></span>`--storage` | string | | VM storage location name, or a direct path to the VM location. |
+| <span id="lume-create--unattended"></span>`--unattended` | string | | Prepare macOS unattended setup offline after install. Built-in presets: sequoia, tahoe; a YAML path is accepted for compatibility. macOS VMs only. |
+| <span id="lume-create--debug-dir"></span>`--debug-dir` | string | | Compatibility option; ignored by offline setup. |
+| <span id="lume-create--vnc-port"></span>`--vnc-port` | integer | `0` | Port for the temporary verification VNC server (0 picks a free port). |
+| <span id="lume-create--network"></span>`--network` | string | `nat` | Network mode: nat, bridged (picks an interface), or bridged:&lt;interface&gt; (for example bridged:en0). |
+| <span id="lume-create--debug"></span>`--debug` | boolean | `false` | Compatibility flag; ignored by offline setup. |
+| <span id="lume-create--no-display"></span>`--no-display` | boolean | `false` | Compatibility flag; offline setup verifies headlessly. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-lume-create"
+# A macOS VM from the latest IPSW, set up unattended (SSH user lume/lume)
+lume create macos-tahoe --ipsw latest --unattended tahoe
+
+# A Linux VM
+lume create dev --os linux --cpu 4 --memory 8GB --disk-size 50GB
+
+# Bridge the VM onto the host's en0 network
+lume create macos-tahoe --ipsw latest --network bridged:en0
+```
+
+### `lume run`
+
+Run a virtual machine.
+
+```text output
+lume run [OPTIONS] <name>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<name>` | string | required | Name of the VM, or an image to pull and run (format: name or name:tag). |
+
+| Flag | Short | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| <span id="lume-run--display"></span>`--display` | | `vnc` \| `native` \| `none` | `native` | Local viewer to open. The VNC server stays available in every mode. |
+| <span id="lume-run--log-file"></span>`--log-file` | | string | | Log path for --detach (default: ~/Library/Logs/lume/&#123;vm&#125;.log). |
+| <span id="lume-run--shared-dir"></span>`--shared-dir` | | string | | Directory to share with the VM: a path (read-write) or path:ro / path:rw. Repeatable. |
+| <span id="lume-run--mount"></span>`--mount` | | string | | For Linux VMs only, a read-only disk image to attach. |
+| <span id="lume-run--usb-storage"></span>`--usb-storage` | | string | | Disk image to attach as a USB mass storage device. Repeatable. |
+| <span id="lume-run--disk"></span>`--disk` | | string | | Disk image to attach as a read-write virtio-blk device. Repeatable. |
+| <span id="lume-run--registry"></span>`--registry` | | string | `ghcr.io` | Container registry to pull images from. |
+| <span id="lume-run--organization"></span>`--organization` | | string | `trycua` | Organization to pull images from. |
+| <span id="lume-run--vnc"></span>`--vnc` | | `enabled` \| `disabled` | `enabled` | VNC server policy. disabled starts the VM with no VNC listener and reports a null vncUrl. |
+| <span id="lume-run--vnc-port"></span>`--vnc-port` | | integer | `0` | Port for the VNC server (0 picks a free port). |
+| <span id="lume-run--vnc-password"></span>`--vnc-password` | | string | | Password for the VNC server (default: a random passphrase). |
+| <span id="lume-run--recovery-mode"></span>`--recovery-mode` | | boolean | `false` | For macOS VMs only, boot into recovery mode. |
+| <span id="lume-run--storage"></span>`--storage` | | string | | VM storage location name, or a direct path to the VM location. |
+| <span id="lume-run--disk-path"></span>`--disk-path` | | string | | Use this disk image instead of disk.img in the VM directory. |
+| <span id="lume-run--nvram-path"></span>`--nvram-path` | | string | | Use this NVRAM file instead of nvram.bin in the VM directory. |
+| <span id="lume-run--network"></span>`--network` | | string | | Network override for this run: nat, bridged, or bridged:&lt;interface&gt; (default: the VM's configured mode). |
+| <span id="lume-run--no-display"></span>`--no-display` | `-d` | boolean | `false` | Compatibility alias for --display none. |
+| <span id="lume-run--detach"></span>`--detach` | | boolean | `false` | Run the VM in the background and return immediately. |
+| <span id="lume-run--clipboard"></span>`--clipboard` | | boolean | `false` | Sync the clipboard both ways over SSH. Automatic with the native macOS display. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-lume-run"
+lume run my-vm
+
+# Headless, with a read-only shared folder
+lume run my-vm --shared-dir ~/src:ro --display none
+
+# In the background with no VNC listener
+lume run my-vm --detach --display none --vnc disabled
+```
+
+### `lume attach`
+
+Open a viewer for a running virtual machine.
+
+The native display is used when the `lume run` process that owns the VM supports live attachment; VNC is the fallback.
+
+```text output
+lume attach [OPTIONS] <name>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<name>` | string | required | Name of the virtual machine. |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="lume-attach--display"></span>`--display` | `native` \| `vnc` | | Viewer to open (default: native, falling back to VNC). |
+| <span id="lume-attach--storage"></span>`--storage` | string | | VM storage location to use. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-lume-attach"
+lume attach my-vm
+
+# Open Screen Sharing over VNC
+lume attach my-vm --display vnc
+```
+
+### `lume stop`
+
+Stop a virtual machine.
+
+```text output
+lume stop [OPTIONS] <name>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<name>` | string | required | Name of the VM to stop. |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="lume-stop--storage"></span>`--storage` | string | | VM storage location name, or a direct path to the VM location. |
+| <span id="lume-stop--timeout"></span>`--timeout` | integer | `10` | Seconds to wait for a graceful shutdown before forcing power off. |
+| <span id="lume-stop--force"></span>`--force` | boolean | `false` | Power off the VM immediately instead of attempting a graceful shutdown first. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-lume-stop"
+lume stop my-vm
+lume stop my-vm --force
+```
+
+### `lume shutdown`
+
+Gracefully shut down a virtual machine.
+
+Requests the operation inside the guest over SSH. VMs created with --unattended use lume/lume credentials by default.
+
+```text output
+lume shutdown [OPTIONS] <name>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<name>` | string | required | Name of the virtual machine. |
+
+| Flag | Short | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| <span id="lume-shutdown--user"></span>`--user` | `-u` | string | `lume` | SSH username. |
+| <span id="lume-shutdown--password"></span>`--password` | `-p` | string | `lume` | SSH and sudo password. |
+| <span id="lume-shutdown--storage"></span>`--storage` | | string | | VM storage location to use. |
+| <span id="lume-shutdown--timeout"></span>`--timeout` | `-t` | integer | `30` | SSH command timeout in seconds. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-lume-shutdown"
+lume shutdown my-vm
+
+# With another SSH user and a longer timeout
+lume shutdown my-vm --user admin --timeout 60
+```
+
+### `lume restart`
+
+Gracefully restart a virtual machine.
+
+Requests the operation inside the guest over SSH. VMs created with --unattended use lume/lume credentials by default.
+
+```text output
+lume restart [OPTIONS] <name>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<name>` | string | required | Name of the virtual machine. |
+
+| Flag | Short | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| <span id="lume-restart--user"></span>`--user` | `-u` | string | `lume` | SSH username. |
+| <span id="lume-restart--password"></span>`--password` | `-p` | string | `lume` | SSH and sudo password. |
+| <span id="lume-restart--storage"></span>`--storage` | | string | | VM storage location to use. |
+| <span id="lume-restart--timeout"></span>`--timeout` | `-t` | integer | `30` | SSH command timeout in seconds. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-lume-restart"
+lume restart my-vm
+
+# With another SSH user and a longer timeout
+lume restart my-vm --user admin --timeout 60
+```
+
+### `lume ls`
+
+List virtual machines.
+
+```text output
+lume ls [OPTIONS]
+```
+
+| Flag | Short | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| <span id="lume-ls--format"></span>`--format` | `-f` | `json` \| `text` | `text` | Output format. |
+| <span id="lume-ls--storage"></span>`--storage` | | string | | Show only VMs in this storage location. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-lume-ls"
+lume ls
+lume ls --format json
+```
+
+### `lume get`
+
+Get detailed information about a virtual machine.
+
+```text output
+lume get [OPTIONS] <name>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<name>` | string | required | Name of the VM. |
+
+| Flag | Short | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| <span id="lume-get--format"></span>`--format` | `-f` | `json` \| `text` | `text` | Output format. |
+| <span id="lume-get--storage"></span>`--storage` | | string | | VM storage location name, or a direct path to the VM location. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-lume-get"
+lume get my-vm
+
+# Machine-readable, including the IP address and VNC URL
+lume get my-vm --format json
+```
+
+### `lume set`
+
+Set new values for CPU, memory, and disk size of a virtual machine.
+
+```text output
+lume set [OPTIONS] <name>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<name>` | string | required | Name of the VM. |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="lume-set--cpu"></span>`--cpu` | integer | | New number of CPU cores. |
+| <span id="lume-set--memory"></span>`--memory` | string | | New memory size (8, 8GB or 8192MB; a bare number is GB). |
+| <span id="lume-set--disk-size"></span>`--disk-size` | string | | New total disk size, increase only. For macOS VMs this relocates the recovery partition and grows the main APFS container; the VM must be stopped and it may take several minutes. |
+| <span id="lume-set--display"></span>`--display` | string | | New display resolution as WIDTHxHEIGHT. |
+| <span id="lume-set--machine-identifier"></span>`--machine-identifier` | string | | New machine identifier: 'random', or a base64 identifier from `lume get --format json` to give this VM an existing machine identity (per-machine licenses then see one machine). macOS VMs only; the VM must be stopped. |
+| <span id="lume-set--mac-address"></span>`--mac-address` | string | | New MAC address: 'random' (locally administered) or aa:bb:cc:dd:ee:ff. The VM must be stopped. The DHCP lease follows the MAC, so two running VMs with one MAC claim the same IP. |
+| <span id="lume-set--storage"></span>`--storage` | string | | VM storage location name, or a direct path to the VM location. |
+| <span id="lume-set--no-backup"></span>`--no-backup` | boolean | `false` | Skip the pre-resize disk backup (macOS resize only). Faster, but a failure cannot be rolled back. |
+| <span id="lume-set--keep-backup"></span>`--keep-backup` | boolean | `false` | Keep the pre-resize backup after a successful macOS resize. |
+| <span id="lume-set--dry-run"></span>`--dry-run` | boolean | `false` | Validate the disk-resize plan and print it without changing anything (macOS resize only). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-lume-set"
+lume set my-vm --cpu 8 --memory 16GB
+
+# Check a disk resize plan, then run it without --dry-run
+lume set my-vm --disk-size 120GB --dry-run
+lume set my-vm --mac-address random
+```
+
+### `lume clone`
+
+Clone an existing virtual machine.
+
+```text output
+lume clone [OPTIONS] <name> <new-name>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<name>` | string | required | Name of the source VM. |
+| `<new-name>` | string | required | Name for the cloned VM. |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="lume-clone--source-storage"></span>`--source-storage` | string | | Source VM storage location. |
+| <span id="lume-clone--dest-storage"></span>`--dest-storage` | string | | Destination VM storage location. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-lume-clone"
+# Keep a golden copy before changing a VM
+lume clone macos-tahoe macos-tahoe-backup
+
+# Copy a VM to another storage location
+lume clone macos-tahoe macos-tahoe --source-storage default --dest-storage external
+```
+
+### `lume delete`
+
+Delete a virtual machine.
+
+```text output
+lume delete [OPTIONS] <name>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<name>` | string | required | Name of the VM to delete. |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="lume-delete--storage"></span>`--storage` | string | | VM storage location name, or a direct path to the VM location. |
+| <span id="lume-delete--force"></span>`--force` | boolean | `false` | Delete without asking for confirmation. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-lume-delete"
+lume delete my-vm
+
+# Without the confirmation prompt
+lume delete my-vm --force
+```
+
+## Images
+
+Pull, push and convert VM images, find restore images, and prune the cache.
+
+### `lume images`
+
+List available macOS images from local cache.
+
+```text output
+lume images [OPTIONS]
+```
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="lume-images--organization"></span>`--organization` | string | `trycua` | Organization to list images for. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-lume-images"
+lume images
+```
+
+### `lume pull`
+
+Pull a prebuilt or custom macOS image from an OCI-compatible registry.
+
+```text output
+lume pull [OPTIONS] <image> [<name>]
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<image>` | string | required | Image to pull (format: name:tag). |
+| `<name>` | string | optional | Name for the resulting VM (defaults to the image name without its tag). |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="lume-pull--registry"></span>`--registry` | string | `ghcr.io` | Container registry to pull from. |
+| <span id="lume-pull--organization"></span>`--organization` | string | `trycua` | Organization to pull from. |
+| <span id="lume-pull--storage"></span>`--storage` | string | | VM storage location name, or a direct path to the VM location. |
+| <span id="lume-pull--username"></span>`--username` | string | | Registry username for authentication. |
+| <span id="lume-pull--password"></span>`--password` | string | | Registry password for authentication. |
+| <span id="lume-pull--force"></span>`--force` | boolean | `false` | Download again even if the image is cached. |
+| <span id="lume-pull--verbose"></span>`--verbose` | boolean | `false` | Enable verbose logging. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-lume-pull"
+# Pull an image from ghcr.io/trycua as a VM named macos-tahoe-vanilla
+lume pull macos-tahoe-vanilla:latest
+
+# Pull it as my-vm into another storage location
+lume pull macos-tahoe-vanilla:latest my-vm --storage external
+```
+
+### `lume push`
+
+Push a macOS VM to an OCI-compatible registry.
+
+```text output
+lume push [OPTIONS] <name> <image>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<name>` | string | required | Name of the VM to push. |
+| `<image>` | string | required | Image tag to push (format: name:tag). |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="lume-push--additional-tags"></span>`--additional-tags` | string | | Additional tags to push the same image to. Takes one or more values. |
+| <span id="lume-push--registry"></span>`--registry` | string | `ghcr.io` | Container registry to push to. |
+| <span id="lume-push--organization"></span>`--organization` | string | `trycua` | Organization to push to. |
+| <span id="lume-push--storage"></span>`--storage` | string | | VM storage location to use. |
+| <span id="lume-push--chunk-size-mb"></span>`--chunk-size-mb` | integer | `512` | Chunk size for large files, in MB. |
+| <span id="lume-push--verbose"></span>`--verbose` | boolean | `false` | Enable verbose logging. |
+| <span id="lume-push--dry-run"></span>`--dry-run` | boolean | `false` | Prepare files without uploading to the registry. |
+| <span id="lume-push--reassemble"></span>`--reassemble` | boolean | `false` | With --dry-run, also reassemble the chunks to verify integrity. |
+| <span id="lume-push--single-layer"></span>`--single-layer` | boolean | `false` | Push the disk as a single layer (kubelet-compatible, no chunking). |
+| <span id="lume-push--legacy"></span>`--legacy` | boolean | `false` | Use the legacy Lume LZ4-chunked format instead of the OCI-compliant format. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-lume-push"
+# Push my-vm as ghcr.io/my-org/my-image:latest
+lume push my-vm my-image:latest --organization my-org
+
+# Push one image under several tags
+lume push my-vm my-image:1.0 --additional-tags latest stable
+
+# Prepare and verify the chunks without uploading
+lume push my-vm my-image:latest --dry-run --reassemble
+```
+
+### `lume convert`
+
+Convert a legacy Lume image to OCI-compliant format.
+
+Pulls a legacy Lume image from the registry, pushes it again in OCI-compliant format under a new name and tag, then removes the temporary local VM.
+
+```text output
+lume convert [OPTIONS] <source-image> <target-image>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<source-image>` | string | required | Source image to convert (legacy format, for example macos-tahoe:latest). |
+| `<target-image>` | string | required | Target image to push in OCI format (format: name:tag). |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="lume-convert--additional-tags"></span>`--additional-tags` | string | | Additional tags to push the OCI image to. Takes one or more values. |
+| <span id="lume-convert--registry"></span>`--registry` | string | `ghcr.io` | Registry to pull from and push to. |
+| <span id="lume-convert--organization"></span>`--organization` | string | `trycua` | Registry organization. |
+| <span id="lume-convert--verbose"></span>`--verbose` | boolean | `false` | Enable verbose logging. |
+| <span id="lume-convert--dry-run"></span>`--dry-run` | boolean | `false` | Prepare files without uploading to the registry. |
+| <span id="lume-convert--single-layer"></span>`--single-layer` | boolean | `false` | Push the disk as a single layer (kubelet-compatible, no chunking). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-lume-convert"
+lume convert macos-tahoe:latest macos-tahoe:latest-oci
+```
+
+### `lume ipsw`
+
+Get macOS restore image IPSW URL.
+
+Prints the URL of the latest supported restore image. Download it, then pass the file to `lume create --ipsw`.
+
+```text output
+lume ipsw
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-lume-ipsw"
+lume ipsw
+```
+
+### `lume prune`
+
+Remove cached images.
+
+```text output
+lume prune
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-lume-prune"
+lume prune
+```
+
+## Guest access
+
+Prepare unattended setup, open SSH sessions, copy files and change SIP in a guest.
+
+### `lume setup`
+
+Prepare unattended macOS setup.
+
+Lume prepares the macOS disk offline, skips Setup Assistant, enables autologin and SSH, disables screensaver lock, verifies SSH, then stops the VM.
+
+```text output
+lume setup [OPTIONS] <name>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<name>` | string | required | Name of the virtual machine. |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="lume-setup--unattended"></span>`--unattended` | string | | Built-in preset (sequoia, tahoe) or a YAML path, kept for compatibility and optional post-SSH commands (default: tahoe). |
+| <span id="lume-setup--storage"></span>`--storage` | string | | VM storage location name, or a direct path to the VM location. |
+| <span id="lume-setup--vnc-port"></span>`--vnc-port` | integer | `0` | Port for the temporary verification VNC server (0 picks a free port). |
+| <span id="lume-setup--debug-dir"></span>`--debug-dir` | string | | Compatibility option; ignored by offline setup. |
+| <span id="lume-setup--no-display"></span>`--no-display` | boolean | `false` | Compatibility flag; offline setup verifies headlessly. |
+| <span id="lume-setup--debug"></span>`--debug` | boolean | `false` | Compatibility flag; ignored by offline setup. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-lume-setup"
+lume setup my-vm
+lume setup my-vm --unattended sequoia
+```
+
+### `lume ssh`
+
+Connect to a VM via SSH or execute commands remotely.
+
+Opens an interactive shell, or runs one command and exits with its status. Password authentication is handled for you (no sshpass needed). Requires Remote Login in the guest; VMs created with --unattended have it enabled with credentials lume/lume.
+
+```text output
+lume ssh [OPTIONS] <name> [<command>...]
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<name>` | string | required | Name of the virtual machine. |
+| `<command>...` | string | optional | Command to execute (omit for an interactive shell). Repeatable. |
+
+| Flag | Short | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| <span id="lume-ssh--user"></span>`--user` | `-u` | string | `lume` | SSH username. |
+| <span id="lume-ssh--password"></span>`--password` | `-p` | string | `lume` | SSH password. |
+| <span id="lume-ssh--storage"></span>`--storage` | | string | | Storage location name or path. |
+| <span id="lume-ssh--timeout"></span>`--timeout` | `-t` | integer | `60` | Command timeout in seconds (0 for no timeout). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-lume-ssh"
+# Interactive shell
+lume ssh my-vm
+
+# Run one command
+lume ssh my-vm "ls -la"
+
+# A long-running command with no timeout
+lume ssh my-vm --timeout 0 "cd /app && npm test"
+```
+
+### `lume cp`
+
+Copy files between the host and a VM.
+
+Copies a file or directory between the host and a running VM over SSH, using the same credentials as `lume ssh`. Exactly one of the source or destination is a VM path, written as VM:PATH. Host directories are copied recursively automatically; pass --recursive for a recursive guest-to-host copy.
+
+```text output
+lume cp [OPTIONS] <source> <destination>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<source>` | string | required | Source path. Use VM:PATH for a path inside a VM. |
+| `<destination>` | string | required | Destination path. Use VM:PATH for a path inside a VM. |
+
+| Flag | Short | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| <span id="lume-cp--user"></span>`--user` | `-u` | string | `lume` | SSH username. |
+| <span id="lume-cp--password"></span>`--password` | `-p` | string | `lume` | SSH password. |
+| <span id="lume-cp--storage"></span>`--storage` | | string | | Storage location name or path. |
+| <span id="lume-cp--timeout"></span>`--timeout` | `-t` | integer | `600` | Transfer timeout in seconds (0 for no timeout). |
+| <span id="lume-cp--recursive"></span>`--recursive` | `-r` | boolean | `false` | Copy directories recursively. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-lume-cp"
+# Copy a host file into the VM
+lume cp ./build.zip my-vm:/tmp/build.zip
+
+# Copy a file out of the VM
+lume cp my-vm:/tmp/out.log ./out.log
+
+# Copy a directory into the VM
+lume cp -r ./assets my-vm:/tmp/assets
+```
+
+### `lume sip`
+
+Enable or disable System Integrity Protection on a macOS VM.
+
+Boots the stopped VM normally to validate the admin credentials, runs `csrutil disable` (or `enable`) in paired recoveryOS over VNC, then boots normally once more to verify the result. The VM needs an admin account and Remote Login; VMs from unattended setup use lume/lume. Prefer --admin-password-stdin: --admin-password is visible to other processes. Requires vncdotool (pip3 install vncdotool).
+
+```text output
+lume sip [OPTIONS] <state> <name>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<state>` | `on` \| `off` | required | Desired SIP state. |
+| `<name>` | string | required | Name of the virtual machine. |
+
+| Flag | Short | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| <span id="lume-sip--admin-user"></span>`--admin-user` | | string | `lume` | Administrator username in the guest. |
+| <span id="lume-sip--admin-password"></span>`--admin-password` | | string | | Administrator password in the guest (default: lume); prefer --admin-password-stdin. |
+| <span id="lume-sip--screenshot-dir"></span>`--screenshot-dir` | | string | | Save step-by-step framebuffer PNGs here for debugging. |
+| <span id="lume-sip--vnc-port"></span>`--vnc-port` | | integer | `5999` | TCP port for the temporary recovery VNC server. |
+| <span id="lume-sip--storage"></span>`--storage` | | string | | VM storage location. |
+| <span id="lume-sip--timeout"></span>`--timeout` | | integer | `900` | Overall timeout in seconds. |
+| <span id="lume-sip--yes"></span>`--yes` | `-y` | boolean | `false` | Skip the interactive confirmation prompt. |
+| <span id="lume-sip--admin-password-stdin"></span>`--admin-password-stdin` | | boolean | `false` | Read one administrator-password line from standard input without echo. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-lume-sip"
+lume sip off my-vm --yes
+
+# With another admin account, password read from stdin
+lume sip on my-vm --yes --admin-user alice --admin-password-stdin
+```
+
+## Server
+
+Run the HTTP API and MCP server, read its logs, and dump the CLI and API definitions.
+
+### `lume serve`
+
+Start the VM management server.
+
+Serves the HTTP API on localhost, or with --mcp an MCP server over stdio for AI agents.
+
+```text output
+lume serve [OPTIONS]
+```
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="lume-serve--port"></span>`--port` | integer | `7777` | Port to listen on (HTTP mode only). |
+| <span id="lume-serve--mcp"></span>`--mcp` | boolean | `false` | Run as an MCP server (stdio transport) for AI agents. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-lume-serve"
+# HTTP API on http://localhost:7777
+lume serve
+lume serve --port 7778
+
+# MCP server over stdio (what MCP clients launch)
+lume serve --mcp
+```
+
+### `lume logs`
+
+View lume serve logs.
+
+```text output
+lume logs <COMMAND>
+```
+
+#### `lume logs info`
+
+View info logs from the daemon.
+
+```text output
+lume logs info [OPTIONS]
+```
+
+| Flag | Short | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| <span id="lume-logs-info--lines"></span>`--lines` | `-l` | integer | | Number of lines to display from the end of the file. |
+| <span id="lume-logs-info--follow"></span>`--follow` | `-f` | boolean | `false` | Follow the log continuously (like tail -f). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-lume-logs-info"
+lume logs info --lines 100
+lume logs info --follow
+```
+
+#### `lume logs error`
+
+View error logs from the daemon.
+
+```text output
+lume logs error [OPTIONS]
+```
+
+| Flag | Short | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| <span id="lume-logs-error--lines"></span>`--lines` | `-l` | integer | | Number of lines to display from the end of the file. |
+| <span id="lume-logs-error--follow"></span>`--follow` | `-f` | boolean | `false` | Follow the log continuously (like tail -f). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-lume-logs-error"
+lume logs error --lines 100
+lume logs error --follow
+```
+
+#### `lume logs all`
+
+View both info and error logs from the daemon.
+
+```text output
+lume logs all [OPTIONS]
+```
+
+| Flag | Short | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| <span id="lume-logs-all--lines"></span>`--lines` | `-l` | integer | | Number of lines to display from the end of each file. |
+| <span id="lume-logs-all--follow"></span>`--follow` | `-f` | boolean | `false` | Follow the log continuously (like tail -f). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-lume-logs-all"
+lume logs all --lines 100
+lume logs all --follow
+```
+
+### `lume dump-docs`
+
+Output CLI and API documentation as JSON for tooling and integrations.
+
+Emits the CLI, HTTP API or MCP tool metadata (arguments, options, flags, endpoints, tool schemas, help text, defaults and types) that the generated reference is built from.
+
+```text output
+lume dump-docs [OPTIONS]
+```
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="lume-dump-docs--type"></span>`--type` | `cli` \| `api` \| `mcp` \| `all` | `cli` | Documentation type to output. |
+| <span id="lume-dump-docs--pretty"></span>`--pretty` | boolean | `false` | Pretty-print the JSON output with sorted keys. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-lume-dump-docs"
+lume dump-docs --type cli --pretty
+
+# The MCP server's tool list
+lume dump-docs --type mcp
+```
+
+## Configuration
+
+Storage locations, the image cache and telemetry settings.
+
+### `lume config`
+
+Get or set lume configuration.
+
+Without a subcommand, prints the current configuration (`lume config get`).
+
+```text output
+lume config <COMMAND>
+```
+
+#### `lume config get`
+
+Get current configuration.
+
+```text output
+lume config get
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-lume-config-get"
+lume config get
+```
+
+#### `lume config storage`
+
+Manage VM storage locations.
+
+```text output
+lume config storage <COMMAND>
+```
+
+##### `lume config storage add`
+
+Add a new VM storage location.
+
+```text output
+lume config storage add <name> <path>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<name>` | string | required | Storage name (letters, digits, dashes and underscores). |
+| `<path>` | string | required | Path to the VM storage directory. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-lume-config-storage-add"
+lume config storage add external /Volumes/External/lume
+```
+
+##### `lume config storage remove`
+
+Remove a VM storage location.
+
+```text output
+lume config storage remove <name>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<name>` | string | required | Storage name to remove. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-lume-config-storage-remove"
+lume config storage remove external
+```
+
+##### `lume config storage list`
+
+List all VM storage locations.
+
+```text output
+lume config storage list
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-lume-config-storage-list"
+lume config storage list
+```
+
+##### `lume config storage default`
+
+Set the default VM storage location.
+
+```text output
+lume config storage default <name>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<name>` | string | required | Storage name to set as default. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-lume-config-storage-default"
+lume config storage default external
+```
+
+#### `lume config cache`
+
+Manage image cache settings.
+
+```text output
+lume config cache <COMMAND>
+```
+
+##### `lume config cache dir`
+
+Get or set cache directory.
+
+```text output
+lume config cache dir [<path>]
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<path>` | string | optional | Path to the cache directory (omit to show the current one). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-lume-config-cache-dir"
+lume config cache dir
+lume config cache dir /Volumes/External/lume-cache
+```
+
+##### `lume config cache enable`
+
+Enable image caching.
+
+```text output
+lume config cache enable
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-lume-config-cache-enable"
+lume config cache enable
+```
+
+##### `lume config cache disable`
+
+Disable image caching.
+
+```text output
+lume config cache disable
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-lume-config-cache-disable"
+lume config cache disable
+```
+
+##### `lume config cache status`
+
+Show cache status and directory.
+
+```text output
+lume config cache status
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-lume-config-cache-status"
+lume config cache status
+```
+
+#### `lume config telemetry`
+
+Manage pseudonymous telemetry settings.
+
+```text output
+lume config telemetry <COMMAND>
+```
+
+##### `lume config telemetry status`
+
+Show current telemetry status.
+
+```text output
+lume config telemetry status
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-lume-config-telemetry-status"
+lume config telemetry status
+```
+
+##### `lume config telemetry enable`
+
+Enable pseudonymous telemetry.
+
+```text output
+lume config telemetry enable
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-lume-config-telemetry-enable"
+lume config telemetry enable
+```
+
+##### `lume config telemetry disable`
+
+Disable pseudonymous telemetry.
+
+```text output
+lume config telemetry disable
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-lume-config-telemetry-disable"
+lume config telemetry disable
+```
+
+##### `lume config telemetry reset-id`
+
+Delete the pseudonymous installation ID and registration markers.
+
+```text output
+lume config telemetry reset-id
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-lume-config-telemetry-reset-id"
+lume config telemetry reset-id
+```
+
+#### `lume config registry`
+
+Manage container registry settings.
+
+```text output
+lume config registry <COMMAND>
+```
+
+##### `lume config registry status`
+
+Show current registry configuration.
+
+```text output
+lume config registry status
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-lume-config-registry-status"
+lume config registry status
+```
+
+##### `lume config registry type`
+
+Get or set registry type.
+
+```text output
+lume config registry type [<type>]
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<type>` | string | optional | Registry type to use: ghcr or gcs (omit to show the current one). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-lume-config-registry-type"
+lume config registry type
+lume config registry type ghcr
+```
+
+##### `lume config registry ghcr`
+
+Configure GitHub Container Registry settings.
+
+```text output
+lume config registry ghcr [OPTIONS]
+```
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="lume-config-registry-ghcr--registry"></span>`--registry` | string | | Registry URL (default: ghcr.io). |
+| <span id="lume-config-registry-ghcr--organization"></span>`--organization` | string | | Organization or namespace (default: trycua). |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-lume-config-registry-ghcr"
+lume config registry ghcr --organization my-org
+```
+
+##### `lume config registry gcs`
+
+Configure GCS registry settings.
+
+```text output
+lume config registry gcs [OPTIONS]
+```
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="lume-config-registry-gcs--api-url"></span>`--api-url` | string | | API URL for signed URL generation. |
+| <span id="lume-config-registry-gcs--api-key"></span>`--api-key` | string | | API key for authentication. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-lume-config-registry-gcs"
+lume config registry gcs --api-url https://images.example.com --api-key <key>
+```
+
+#### `lume config network`
+
+Manage network settings.
+
+```text output
+lume config network <COMMAND>
+```
+
+##### `lume config network interfaces`
+
+List available network interfaces for bridged networking.
+
+```text output
+lume config network interfaces
+```
+
+**Examples**
+
+```bash test="cli-shape" id="ref-lume-config-network-interfaces"
+lume config network interfaces
+```
+
+## Updates
+
+Check for, apply and choose the channel of Lume updates.
+
+### `lume check-update`
+
+Check whether a newer Lume release is available.
+
+Read-only update check. Uses GitHub Releases, caches the result briefly, and never installs anything.
+
+```text output
+lume check-update [OPTIONS]
+```
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="lume-check-update--json"></span>`--json` | boolean | `false` | Emit the structured update-state payload as JSON. |
+| <span id="lume-check-update--no-cache"></span>`--no-cache` | boolean | `false` | Bypass the local update-check cache. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-lume-check-update"
+lume check-update
+lume check-update --json --no-cache
+```
+
+### `lume update`
+
+Check for a Lume update and optionally apply it.
+
+Without --apply, this command only checks for a newer release and prints the command to install it. With --apply, it runs the official Lume installer pinned to the discovered version and exits with the installer's status.
+
+```text output
+lume update [OPTIONS]
+```
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="lume-update--apply"></span>`--apply` | boolean | `false` | Apply the update while preserving the current background-service choice. |
+| <span id="lume-update--json"></span>`--json` | boolean | `false` | Emit the structured update-state payload as JSON. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-lume-update"
+lume update
+lume update --apply
+```
+
+### `lume channel`
+
+Inspect or change the stable/nightly update channel; selection does not install.
+
+The selection persists but never installs by itself; run `lume update --apply` after changing it. Without a subcommand, prints the status.
+
+```text output
+lume channel <COMMAND>
+```
+
+#### `lume channel status`
+
+Show selected and current release channels.
+
+```text output
+lume channel status [OPTIONS]
+```
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="lume-channel-status--json"></span>`--json` | boolean | `false` | Emit machine-readable channel state as JSON. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-lume-channel-status"
+lume channel status --json
+```
+
+#### `lume channel set`
+
+Save stable or nightly as the update channel.
+
+```text output
+lume channel set [OPTIONS] <channel>
+```
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<channel>` | string | required | Release channel: stable or nightly. |
+
+| Flag | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="lume-channel-set--json"></span>`--json` | boolean | `false` | Emit machine-readable channel state as JSON. |
+
+**Examples**
+
+```bash test="cli-shape" id="ref-lume-channel-set"
+lume channel set nightly
+lume channel set stable
+```
+
+## Global options
+
+`--help` prints help for any command; `--version` prints the version.
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| `0` | Success. |
+| `1` | The command failed (for example the VM does not exist or the operation errored). |
+| `64` | Usage error: an unknown command or option, a missing argument, or an invalid value. |
diff --git a/docs/content/docs/lume/reference/cli/config.mdx b/docs/content/docs/lume/reference/cli/config.mdx
deleted file mode 100644
index e7624b8563..0000000000
--- a/docs/content/docs/lume/reference/cli/config.mdx
+++ /dev/null
@@ -1,382 +0,0 @@
----
-title: "Configuration"
-description: "Storage locations, the image cache and telemetry settings."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:lume
- Source: lume dump-docs --type cli
- Version: 0.6.1
-*/}
-
-| Command | Description |
-| --- | --- |
-| [`lume config get`](#lume-config-get) | Get current configuration. |
-| [`lume config storage`](#lume-config-storage) | Manage VM storage locations. |
-| [`lume config storage add`](#lume-config-storage-add) | Add a new VM storage location. |
-| [`lume config storage remove`](#lume-config-storage-remove) | Remove a VM storage location. |
-| [`lume config storage list`](#lume-config-storage-list) | List all VM storage locations. |
-| [`lume config storage default`](#lume-config-storage-default) | Set the default VM storage location. |
-| [`lume config cache`](#lume-config-cache) | Manage image cache settings. |
-| [`lume config cache dir`](#lume-config-cache-dir) | Get or set cache directory. |
-| [`lume config cache enable`](#lume-config-cache-enable) | Enable image caching. |
-| [`lume config cache disable`](#lume-config-cache-disable) | Disable image caching. |
-| [`lume config cache status`](#lume-config-cache-status) | Show cache status and directory. |
-| [`lume config telemetry`](#lume-config-telemetry) | Manage pseudonymous telemetry settings. |
-| [`lume config telemetry status`](#lume-config-telemetry-status) | Show current telemetry status. |
-| [`lume config telemetry enable`](#lume-config-telemetry-enable) | Enable pseudonymous telemetry. |
-| [`lume config telemetry disable`](#lume-config-telemetry-disable) | Disable pseudonymous telemetry. |
-| [`lume config telemetry reset-id`](#lume-config-telemetry-reset-id) | Delete the pseudonymous installation ID and registration markers. |
-| [`lume config registry`](#lume-config-registry) | Manage container registry settings. |
-| [`lume config registry status`](#lume-config-registry-status) | Show current registry configuration. |
-| [`lume config registry type`](#lume-config-registry-type) | Get or set registry type. |
-| [`lume config registry ghcr`](#lume-config-registry-ghcr) | Configure GitHub Container Registry settings. |
-| [`lume config registry gcs`](#lume-config-registry-gcs) | Configure GCS registry settings. |
-| [`lume config network`](#lume-config-network) | Manage network settings. |
-| [`lume config network interfaces`](#lume-config-network-interfaces) | List available network interfaces for bridged networking. |
-
-Every command also accepts the [global options](/lume/reference/cli#global-options).
-
-<span id="lume-config"></span>
-
-Get or set lume configuration.
-
-Without a subcommand, prints the current configuration (`lume config get`).
-
-```text output
-lume config <COMMAND>
-```
-
-## `lume config get`
-
-Get current configuration.
-
-```text output
-lume config get
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-lume-config-get"
-lume config get
-```
-
-## `lume config storage`
-
-Manage VM storage locations.
-
-```text output
-lume config storage <COMMAND>
-```
-
-### `lume config storage add`
-
-Add a new VM storage location.
-
-```text output
-lume config storage add <name> <path>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<name>` | string | required | Storage name (letters, digits, dashes and underscores). |
-| `<path>` | string | required | Path to the VM storage directory. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-lume-config-storage-add"
-lume config storage add external /Volumes/External/lume
-```
-
-### `lume config storage remove`
-
-Remove a VM storage location.
-
-```text output
-lume config storage remove <name>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<name>` | string | required | Storage name to remove. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-lume-config-storage-remove"
-lume config storage remove external
-```
-
-### `lume config storage list`
-
-List all VM storage locations.
-
-```text output
-lume config storage list
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-lume-config-storage-list"
-lume config storage list
-```
-
-### `lume config storage default`
-
-Set the default VM storage location.
-
-```text output
-lume config storage default <name>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<name>` | string | required | Storage name to set as default. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-lume-config-storage-default"
-lume config storage default external
-```
-
-## `lume config cache`
-
-Manage image cache settings.
-
-```text output
-lume config cache <COMMAND>
-```
-
-### `lume config cache dir`
-
-Get or set cache directory.
-
-```text output
-lume config cache dir [<path>]
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<path>` | string | optional | Path to the cache directory (omit to show the current one). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-lume-config-cache-dir"
-lume config cache dir
-lume config cache dir /Volumes/External/lume-cache
-```
-
-### `lume config cache enable`
-
-Enable image caching.
-
-```text output
-lume config cache enable
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-lume-config-cache-enable"
-lume config cache enable
-```
-
-### `lume config cache disable`
-
-Disable image caching.
-
-```text output
-lume config cache disable
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-lume-config-cache-disable"
-lume config cache disable
-```
-
-### `lume config cache status`
-
-Show cache status and directory.
-
-```text output
-lume config cache status
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-lume-config-cache-status"
-lume config cache status
-```
-
-## `lume config telemetry`
-
-Manage pseudonymous telemetry settings.
-
-```text output
-lume config telemetry <COMMAND>
-```
-
-### `lume config telemetry status`
-
-Show current telemetry status.
-
-```text output
-lume config telemetry status
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-lume-config-telemetry-status"
-lume config telemetry status
-```
-
-### `lume config telemetry enable`
-
-Enable pseudonymous telemetry.
-
-```text output
-lume config telemetry enable
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-lume-config-telemetry-enable"
-lume config telemetry enable
-```
-
-### `lume config telemetry disable`
-
-Disable pseudonymous telemetry.
-
-```text output
-lume config telemetry disable
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-lume-config-telemetry-disable"
-lume config telemetry disable
-```
-
-### `lume config telemetry reset-id`
-
-Delete the pseudonymous installation ID and registration markers.
-
-```text output
-lume config telemetry reset-id
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-lume-config-telemetry-reset-id"
-lume config telemetry reset-id
-```
-
-## `lume config registry`
-
-Manage container registry settings.
-
-```text output
-lume config registry <COMMAND>
-```
-
-### `lume config registry status`
-
-Show current registry configuration.
-
-```text output
-lume config registry status
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-lume-config-registry-status"
-lume config registry status
-```
-
-### `lume config registry type`
-
-Get or set registry type.
-
-```text output
-lume config registry type [<type>]
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<type>` | string | optional | Registry type to use: ghcr or gcs (omit to show the current one). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-lume-config-registry-type"
-lume config registry type
-lume config registry type ghcr
-```
-
-### `lume config registry ghcr`
-
-Configure GitHub Container Registry settings.
-
-```text output
-lume config registry ghcr [OPTIONS]
-```
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="lume-config-registry-ghcr--registry"></span>`--registry` | string | | Registry URL (default: ghcr.io). |
-| <span id="lume-config-registry-ghcr--organization"></span>`--organization` | string | | Organization or namespace (default: trycua). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-lume-config-registry-ghcr"
-lume config registry ghcr --organization my-org
-```
-
-### `lume config registry gcs`
-
-Configure GCS registry settings.
-
-```text output
-lume config registry gcs [OPTIONS]
-```
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="lume-config-registry-gcs--api-url"></span>`--api-url` | string | | API URL for signed URL generation. |
-| <span id="lume-config-registry-gcs--api-key"></span>`--api-key` | string | | API key for authentication. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-lume-config-registry-gcs"
-lume config registry gcs --api-url https://images.example.com --api-key <key>
-```
-
-## `lume config network`
-
-Manage network settings.
-
-```text output
-lume config network <COMMAND>
-```
-
-### `lume config network interfaces`
-
-List available network interfaces for bridged networking.
-
-```text output
-lume config network interfaces
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-lume-config-network-interfaces"
-lume config network interfaces
-```
-
-## Exit codes
-
-| Code | Meaning |
-| --- | --- |
-| `0` | Success. |
-| `1` | The command failed (for example the VM does not exist or the operation errored). |
-| `64` | Usage error: an unknown command or option, a missing argument, or an invalid value. |
diff --git a/docs/content/docs/lume/reference/cli/guest.mdx b/docs/content/docs/lume/reference/cli/guest.mdx
deleted file mode 100644
index 9316b3b5db..0000000000
--- a/docs/content/docs/lume/reference/cli/guest.mdx
+++ /dev/null
@@ -1,164 +0,0 @@
----
-title: "Guest access"
-description: "Prepare unattended setup, open SSH sessions, copy files and change SIP in a guest."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:lume
- Source: lume dump-docs --type cli
- Version: 0.6.1
-*/}
-
-| Command | Description |
-| --- | --- |
-| [`lume setup`](#lume-setup) | Prepare unattended macOS setup. |
-| [`lume ssh`](#lume-ssh) | Connect to a VM via SSH or execute commands remotely. |
-| [`lume cp`](#lume-cp) | Copy files between the host and a VM. |
-| [`lume sip`](#lume-sip) | Enable or disable System Integrity Protection on a macOS VM. |
-
-Every command also accepts the [global options](/lume/reference/cli#global-options).
-
-## `lume setup`
-
-Prepare unattended macOS setup.
-
-Lume prepares the macOS disk offline, skips Setup Assistant, enables autologin and SSH, disables screensaver lock, verifies SSH, then stops the VM.
-
-```text output
-lume setup [OPTIONS] <name>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<name>` | string | required | Name of the virtual machine. |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="lume-setup--unattended"></span>`--unattended` | string | | Built-in preset (sequoia, tahoe) or a YAML path, kept for compatibility and optional post-SSH commands (default: tahoe). |
-| <span id="lume-setup--storage"></span>`--storage` | string | | VM storage location name, or a direct path to the VM location. |
-| <span id="lume-setup--vnc-port"></span>`--vnc-port` | integer | `0` | Port for the temporary verification VNC server (0 picks a free port). |
-| <span id="lume-setup--debug-dir"></span>`--debug-dir` | string | | Compatibility option; ignored by offline setup. |
-| <span id="lume-setup--no-display"></span>`--no-display` | boolean | `false` | Compatibility flag; offline setup verifies headlessly. |
-| <span id="lume-setup--debug"></span>`--debug` | boolean | `false` | Compatibility flag; ignored by offline setup. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-lume-setup"
-lume setup my-vm
-lume setup my-vm --unattended sequoia
-```
-
-## `lume ssh`
-
-Connect to a VM via SSH or execute commands remotely.
-
-Opens an interactive shell, or runs one command and exits with its status. Password authentication is handled for you (no sshpass needed). Requires Remote Login in the guest; VMs created with --unattended have it enabled with credentials lume/lume.
-
-```text output
-lume ssh [OPTIONS] <name> [<command>...]
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<name>` | string | required | Name of the virtual machine. |
-| `<command>...` | string | optional | Command to execute (omit for an interactive shell). Repeatable. |
-
-| Flag | Short | Type | Default | Description |
-| --- | --- | --- | --- | --- |
-| <span id="lume-ssh--user"></span>`--user` | `-u` | string | `lume` | SSH username. |
-| <span id="lume-ssh--password"></span>`--password` | `-p` | string | `lume` | SSH password. |
-| <span id="lume-ssh--storage"></span>`--storage` | | string | | Storage location name or path. |
-| <span id="lume-ssh--timeout"></span>`--timeout` | `-t` | integer | `60` | Command timeout in seconds (0 for no timeout). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-lume-ssh"
-# Interactive shell
-lume ssh my-vm
-
-# Run one command
-lume ssh my-vm "ls -la"
-
-# A long-running command with no timeout
-lume ssh my-vm --timeout 0 "cd /app && npm test"
-```
-
-## `lume cp`
-
-Copy files between the host and a VM.
-
-Copies a file or directory between the host and a running VM over SSH, using the same credentials as `lume ssh`. Exactly one of the source or destination is a VM path, written as VM:PATH. Host directories are copied recursively automatically; pass --recursive for a recursive guest-to-host copy.
-
-```text output
-lume cp [OPTIONS] <source> <destination>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<source>` | string | required | Source path. Use VM:PATH for a path inside a VM. |
-| `<destination>` | string | required | Destination path. Use VM:PATH for a path inside a VM. |
-
-| Flag | Short | Type | Default | Description |
-| --- | --- | --- | --- | --- |
-| <span id="lume-cp--user"></span>`--user` | `-u` | string | `lume` | SSH username. |
-| <span id="lume-cp--password"></span>`--password` | `-p` | string | `lume` | SSH password. |
-| <span id="lume-cp--storage"></span>`--storage` | | string | | Storage location name or path. |
-| <span id="lume-cp--timeout"></span>`--timeout` | `-t` | integer | `600` | Transfer timeout in seconds (0 for no timeout). |
-| <span id="lume-cp--recursive"></span>`--recursive` | `-r` | boolean | `false` | Copy directories recursively. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-lume-cp"
-# Copy a host file into the VM
-lume cp ./build.zip my-vm:/tmp/build.zip
-
-# Copy a file out of the VM
-lume cp my-vm:/tmp/out.log ./out.log
-
-# Copy a directory into the VM
-lume cp -r ./assets my-vm:/tmp/assets
-```
-
-## `lume sip`
-
-Enable or disable System Integrity Protection on a macOS VM.
-
-Boots the stopped VM normally to validate the admin credentials, runs `csrutil disable` (or `enable`) in paired recoveryOS over VNC, then boots normally once more to verify the result. The VM needs an admin account and Remote Login; VMs from unattended setup use lume/lume. Prefer --admin-password-stdin: --admin-password is visible to other processes. Requires vncdotool (pip3 install vncdotool).
-
-```text output
-lume sip [OPTIONS] <state> <name>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<state>` | `on` \| `off` | required | Desired SIP state. |
-| `<name>` | string | required | Name of the virtual machine. |
-
-| Flag | Short | Type | Default | Description |
-| --- | --- | --- | --- | --- |
-| <span id="lume-sip--admin-user"></span>`--admin-user` | | string | `lume` | Administrator username in the guest. |
-| <span id="lume-sip--admin-password"></span>`--admin-password` | | string | | Administrator password in the guest (default: lume); prefer --admin-password-stdin. |
-| <span id="lume-sip--screenshot-dir"></span>`--screenshot-dir` | | string | | Save step-by-step framebuffer PNGs here for debugging. |
-| <span id="lume-sip--vnc-port"></span>`--vnc-port` | | integer | `5999` | TCP port for the temporary recovery VNC server. |
-| <span id="lume-sip--storage"></span>`--storage` | | string | | VM storage location. |
-| <span id="lume-sip--timeout"></span>`--timeout` | | integer | `900` | Overall timeout in seconds. |
-| <span id="lume-sip--yes"></span>`--yes` | `-y` | boolean | `false` | Skip the interactive confirmation prompt. |
-| <span id="lume-sip--admin-password-stdin"></span>`--admin-password-stdin` | | boolean | `false` | Read one administrator-password line from standard input without echo. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-lume-sip"
-lume sip off my-vm --yes
-
-# With another admin account, password read from stdin
-lume sip on my-vm --yes --admin-user alice --admin-password-stdin
-```
-
-## Exit codes
-
-| Code | Meaning |
-| --- | --- |
-| `0` | Success. |
-| `1` | The command failed (for example the VM does not exist or the operation errored). |
-| `64` | Usage error: an unknown command or option, a missing argument, or an invalid value. |
diff --git a/docs/content/docs/lume/reference/cli/images.mdx b/docs/content/docs/lume/reference/cli/images.mdx
deleted file mode 100644
index 554dbf9ab3..0000000000
--- a/docs/content/docs/lume/reference/cli/images.mdx
+++ /dev/null
@@ -1,180 +0,0 @@
----
-title: "Images"
-description: "Pull, push and convert VM images, find restore images, and prune the cache."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:lume
- Source: lume dump-docs --type cli
- Version: 0.6.1
-*/}
-
-| Command | Description |
-| --- | --- |
-| [`lume images`](#lume-images) | List available macOS images from local cache. |
-| [`lume pull`](#lume-pull) | Pull a prebuilt or custom macOS image from an OCI-compatible registry. |
-| [`lume push`](#lume-push) | Push a macOS VM to an OCI-compatible registry. |
-| [`lume convert`](#lume-convert) | Convert a legacy Lume image to OCI-compliant format. |
-| [`lume ipsw`](#lume-ipsw) | Get macOS restore image IPSW URL. |
-| [`lume prune`](#lume-prune) | Remove cached images. |
-
-Every command also accepts the [global options](/lume/reference/cli#global-options).
-
-## `lume images`
-
-List available macOS images from local cache.
-
-```text output
-lume images [OPTIONS]
-```
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="lume-images--organization"></span>`--organization` | string | `trycua` | Organization to list images for. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-lume-images"
-lume images
-```
-
-## `lume pull`
-
-Pull a prebuilt or custom macOS image from an OCI-compatible registry.
-
-```text output
-lume pull [OPTIONS] <image> [<name>]
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<image>` | string | required | Image to pull (format: name:tag). |
-| `<name>` | string | optional | Name for the resulting VM (defaults to the image name without its tag). |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="lume-pull--registry"></span>`--registry` | string | `ghcr.io` | Container registry to pull from. |
-| <span id="lume-pull--organization"></span>`--organization` | string | `trycua` | Organization to pull from. |
-| <span id="lume-pull--storage"></span>`--storage` | string | | VM storage location name, or a direct path to the VM location. |
-| <span id="lume-pull--username"></span>`--username` | string | | Registry username for authentication. |
-| <span id="lume-pull--password"></span>`--password` | string | | Registry password for authentication. |
-| <span id="lume-pull--force"></span>`--force` | boolean | `false` | Download again even if the image is cached. |
-| <span id="lume-pull--verbose"></span>`--verbose` | boolean | `false` | Enable verbose logging. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-lume-pull"
-# Pull an image from ghcr.io/trycua as a VM named macos-tahoe-vanilla
-lume pull macos-tahoe-vanilla:latest
-
-# Pull it as my-vm into another storage location
-lume pull macos-tahoe-vanilla:latest my-vm --storage external
-```
-
-## `lume push`
-
-Push a macOS VM to an OCI-compatible registry.
-
-```text output
-lume push [OPTIONS] <name> <image>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<name>` | string | required | Name of the VM to push. |
-| `<image>` | string | required | Image tag to push (format: name:tag). |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="lume-push--additional-tags"></span>`--additional-tags` | string | | Additional tags to push the same image to. Takes one or more values. |
-| <span id="lume-push--registry"></span>`--registry` | string | `ghcr.io` | Container registry to push to. |
-| <span id="lume-push--organization"></span>`--organization` | string | `trycua` | Organization to push to. |
-| <span id="lume-push--storage"></span>`--storage` | string | | VM storage location to use. |
-| <span id="lume-push--chunk-size-mb"></span>`--chunk-size-mb` | integer | `512` | Chunk size for large files, in MB. |
-| <span id="lume-push--verbose"></span>`--verbose` | boolean | `false` | Enable verbose logging. |
-| <span id="lume-push--dry-run"></span>`--dry-run` | boolean | `false` | Prepare files without uploading to the registry. |
-| <span id="lume-push--reassemble"></span>`--reassemble` | boolean | `false` | With --dry-run, also reassemble the chunks to verify integrity. |
-| <span id="lume-push--single-layer"></span>`--single-layer` | boolean | `false` | Push the disk as a single layer (kubelet-compatible, no chunking). |
-| <span id="lume-push--legacy"></span>`--legacy` | boolean | `false` | Use the legacy Lume LZ4-chunked format instead of the OCI-compliant format. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-lume-push"
-# Push my-vm as ghcr.io/my-org/my-image:latest
-lume push my-vm my-image:latest --organization my-org
-
-# Push one image under several tags
-lume push my-vm my-image:1.0 --additional-tags latest stable
-
-# Prepare and verify the chunks without uploading
-lume push my-vm my-image:latest --dry-run --reassemble
-```
-
-## `lume convert`
-
-Convert a legacy Lume image to OCI-compliant format.
-
-Pulls a legacy Lume image from the registry, pushes it again in OCI-compliant format under a new name and tag, then removes the temporary local VM.
-
-```text output
-lume convert [OPTIONS] <source-image> <target-image>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<source-image>` | string | required | Source image to convert (legacy format, for example macos-tahoe:latest). |
-| `<target-image>` | string | required | Target image to push in OCI format (format: name:tag). |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="lume-convert--additional-tags"></span>`--additional-tags` | string | | Additional tags to push the OCI image to. Takes one or more values. |
-| <span id="lume-convert--registry"></span>`--registry` | string | `ghcr.io` | Registry to pull from and push to. |
-| <span id="lume-convert--organization"></span>`--organization` | string | `trycua` | Registry organization. |
-| <span id="lume-convert--verbose"></span>`--verbose` | boolean | `false` | Enable verbose logging. |
-| <span id="lume-convert--dry-run"></span>`--dry-run` | boolean | `false` | Prepare files without uploading to the registry. |
-| <span id="lume-convert--single-layer"></span>`--single-layer` | boolean | `false` | Push the disk as a single layer (kubelet-compatible, no chunking). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-lume-convert"
-lume convert macos-tahoe:latest macos-tahoe:latest-oci
-```
-
-## `lume ipsw`
-
-Get macOS restore image IPSW URL.
-
-Prints the URL of the latest supported restore image. Download it, then pass the file to `lume create --ipsw`.
-
-```text output
-lume ipsw
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-lume-ipsw"
-lume ipsw
-```
-
-## `lume prune`
-
-Remove cached images.
-
-```text output
-lume prune
-```
-
-**Examples**
-
-```bash test="cli-shape" id="ref-lume-prune"
-lume prune
-```
-
-## Exit codes
-
-| Code | Meaning |
-| --- | --- |
-| `0` | Success. |
-| `1` | The command failed (for example the VM does not exist or the operation errored). |
-| `64` | Usage error: an unknown command or option, a missing argument, or an invalid value. |
diff --git a/docs/content/docs/lume/reference/cli/index.mdx b/docs/content/docs/lume/reference/cli/index.mdx
deleted file mode 100644
index 68de920800..0000000000
--- a/docs/content/docs/lume/reference/cli/index.mdx
+++ /dev/null
@@ -1,129 +0,0 @@
----
-title: "lume"
-description: "A lightweight CLI and local API server to build, run and manage macOS VMs."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:lume
- Source: lume dump-docs --type cli
- Version: 0.6.1
-*/}
-
-```text output
-lume [OPTIONS] <COMMAND>
-```
-
-Run `lume <command> --help` for the build you have.
-
-## Commands
-
-### VMs
-
-Create, run, inspect, change, clone and delete virtual machines. [Reference](/lume/reference/cli/vms).
-
-| Command | Description |
-| --- | --- |
-| <span id="lume-create"></span>[`lume create`](/lume/reference/cli/vms#lume-create) | Create a new virtual machine. |
-| <span id="lume-run"></span>[`lume run`](/lume/reference/cli/vms#lume-run) | Run a virtual machine. |
-| <span id="lume-attach"></span>[`lume attach`](/lume/reference/cli/vms#lume-attach) | Open a viewer for a running virtual machine. |
-| <span id="lume-stop"></span>[`lume stop`](/lume/reference/cli/vms#lume-stop) | Stop a virtual machine. |
-| <span id="lume-shutdown"></span>[`lume shutdown`](/lume/reference/cli/vms#lume-shutdown) | Gracefully shut down a virtual machine. |
-| <span id="lume-restart"></span>[`lume restart`](/lume/reference/cli/vms#lume-restart) | Gracefully restart a virtual machine. |
-| <span id="lume-ls"></span>[`lume ls`](/lume/reference/cli/vms#lume-ls) | List virtual machines. |
-| <span id="lume-get"></span>[`lume get`](/lume/reference/cli/vms#lume-get) | Get detailed information about a virtual machine. |
-| <span id="lume-set"></span>[`lume set`](/lume/reference/cli/vms#lume-set) | Set new values for CPU, memory, and disk size of a virtual machine. |
-| <span id="lume-clone"></span>[`lume clone`](/lume/reference/cli/vms#lume-clone) | Clone an existing virtual machine. |
-| <span id="lume-delete"></span>[`lume delete`](/lume/reference/cli/vms#lume-delete) | Delete a virtual machine. |
-
-### Images
-
-Pull, push and convert VM images, find restore images, and prune the cache. [Reference](/lume/reference/cli/images).
-
-| Command | Description |
-| --- | --- |
-| <span id="lume-images"></span>[`lume images`](/lume/reference/cli/images#lume-images) | List available macOS images from local cache. |
-| <span id="lume-pull"></span>[`lume pull`](/lume/reference/cli/images#lume-pull) | Pull a prebuilt or custom macOS image from an OCI-compatible registry. |
-| <span id="lume-push"></span>[`lume push`](/lume/reference/cli/images#lume-push) | Push a macOS VM to an OCI-compatible registry. |
-| <span id="lume-convert"></span>[`lume convert`](/lume/reference/cli/images#lume-convert) | Convert a legacy Lume image to OCI-compliant format. |
-| <span id="lume-ipsw"></span>[`lume ipsw`](/lume/reference/cli/images#lume-ipsw) | Get macOS restore image IPSW URL. |
-| <span id="lume-prune"></span>[`lume prune`](/lume/reference/cli/images#lume-prune) | Remove cached images. |
-
-### Guest access
-
-Prepare unattended setup, open SSH sessions, copy files and change SIP in a guest. [Reference](/lume/reference/cli/guest).
-
-| Command | Description |
-| --- | --- |
-| <span id="lume-setup"></span>[`lume setup`](/lume/reference/cli/guest#lume-setup) | Prepare unattended macOS setup. |
-| <span id="lume-ssh"></span>[`lume ssh`](/lume/reference/cli/guest#lume-ssh) | Connect to a VM via SSH or execute commands remotely. |
-| <span id="lume-cp"></span>[`lume cp`](/lume/reference/cli/guest#lume-cp) | Copy files between the host and a VM. |
-| <span id="lume-sip"></span>[`lume sip`](/lume/reference/cli/guest#lume-sip) | Enable or disable System Integrity Protection on a macOS VM. |
-
-### Server
-
-Run the HTTP API and MCP server, read its logs, and dump the CLI and API definitions. [Reference](/lume/reference/cli/server).
-
-| Command | Description |
-| --- | --- |
-| <span id="lume-serve"></span>[`lume serve`](/lume/reference/cli/server#lume-serve) | Start the VM management server. |
-| <span id="lume-logs"></span>[`lume logs`](/lume/reference/cli/server#lume-logs) | View lume serve logs. |
-| <span id="lume-logs-info"></span>[`lume logs info`](/lume/reference/cli/server#lume-logs-info) | View info logs from the daemon. |
-| <span id="lume-logs-error"></span>[`lume logs error`](/lume/reference/cli/server#lume-logs-error) | View error logs from the daemon. |
-| <span id="lume-logs-all"></span>[`lume logs all`](/lume/reference/cli/server#lume-logs-all) | View both info and error logs from the daemon. |
-| <span id="lume-dump-docs"></span>[`lume dump-docs`](/lume/reference/cli/server#lume-dump-docs) | Output CLI and API documentation as JSON for tooling and integrations. |
-
-### Configuration
-
-Storage locations, the image cache and telemetry settings. [Reference](/lume/reference/cli/config).
-
-| Command | Description |
-| --- | --- |
-| <span id="lume-config"></span>[`lume config`](/lume/reference/cli/config#lume-config) | Get or set lume configuration. |
-| <span id="lume-config-get"></span>[`lume config get`](/lume/reference/cli/config#lume-config-get) | Get current configuration. |
-| <span id="lume-config-storage"></span>[`lume config storage`](/lume/reference/cli/config#lume-config-storage) | Manage VM storage locations. |
-| <span id="lume-config-storage-add"></span>[`lume config storage add`](/lume/reference/cli/config#lume-config-storage-add) | Add a new VM storage location. |
-| <span id="lume-config-storage-remove"></span>[`lume config storage remove`](/lume/reference/cli/config#lume-config-storage-remove) | Remove a VM storage location. |
-| <span id="lume-config-storage-list"></span>[`lume config storage list`](/lume/reference/cli/config#lume-config-storage-list) | List all VM storage locations. |
-| <span id="lume-config-storage-default"></span>[`lume config storage default`](/lume/reference/cli/config#lume-config-storage-default) | Set the default VM storage location. |
-| <span id="lume-config-cache"></span>[`lume config cache`](/lume/reference/cli/config#lume-config-cache) | Manage image cache settings. |
-| <span id="lume-config-cache-dir"></span>[`lume config cache dir`](/lume/reference/cli/config#lume-config-cache-dir) | Get or set cache directory. |
-| <span id="lume-config-cache-enable"></span>[`lume config cache enable`](/lume/reference/cli/config#lume-config-cache-enable) | Enable image caching. |
-| <span id="lume-config-cache-disable"></span>[`lume config cache disable`](/lume/reference/cli/config#lume-config-cache-disable) | Disable image caching. |
-| <span id="lume-config-cache-status"></span>[`lume config cache status`](/lume/reference/cli/config#lume-config-cache-status) | Show cache status and directory. |
-| <span id="lume-config-telemetry"></span>[`lume config telemetry`](/lume/reference/cli/config#lume-config-telemetry) | Manage pseudonymous telemetry settings. |
-| <span id="lume-config-telemetry-status"></span>[`lume config telemetry status`](/lume/reference/cli/config#lume-config-telemetry-status) | Show current telemetry status. |
-| <span id="lume-config-telemetry-enable"></span>[`lume config telemetry enable`](/lume/reference/cli/config#lume-config-telemetry-enable) | Enable pseudonymous telemetry. |
-| <span id="lume-config-telemetry-disable"></span>[`lume config telemetry disable`](/lume/reference/cli/config#lume-config-telemetry-disable) | Disable pseudonymous telemetry. |
-| <span id="lume-config-telemetry-reset-id"></span>[`lume config telemetry reset-id`](/lume/reference/cli/config#lume-config-telemetry-reset-id) | Delete the pseudonymous installation ID and registration markers. |
-| <span id="lume-config-registry"></span>[`lume config registry`](/lume/reference/cli/config#lume-config-registry) | Manage container registry settings. |
-| <span id="lume-config-registry-status"></span>[`lume config registry status`](/lume/reference/cli/config#lume-config-registry-status) | Show current registry configuration. |
-| <span id="lume-config-registry-type"></span>[`lume config registry type`](/lume/reference/cli/config#lume-config-registry-type) | Get or set registry type. |
-| <span id="lume-config-registry-ghcr"></span>[`lume config registry ghcr`](/lume/reference/cli/config#lume-config-registry-ghcr) | Configure GitHub Container Registry settings. |
-| <span id="lume-config-registry-gcs"></span>[`lume config registry gcs`](/lume/reference/cli/config#lume-config-registry-gcs) | Configure GCS registry settings. |
-| <span id="lume-config-network"></span>[`lume config network`](/lume/reference/cli/config#lume-config-network) | Manage network settings. |
-| <span id="lume-config-network-interfaces"></span>[`lume config network interfaces`](/lume/reference/cli/config#lume-config-network-interfaces) | List available network interfaces for bridged networking. |
-
-### Updates
-
-Check for, apply and choose the channel of Lume updates. [Reference](/lume/reference/cli/updates).
-
-| Command | Description |
-| --- | --- |
-| <span id="lume-check-update"></span>[`lume check-update`](/lume/reference/cli/updates#lume-check-update) | Check whether a newer Lume release is available. |
-| <span id="lume-update"></span>[`lume update`](/lume/reference/cli/updates#lume-update) | Check for a Lume update and optionally apply it. |
-| <span id="lume-channel"></span>[`lume channel`](/lume/reference/cli/updates#lume-channel) | Inspect or change the stable/nightly update channel; selection does not install. |
-| <span id="lume-channel-status"></span>[`lume channel status`](/lume/reference/cli/updates#lume-channel-status) | Show selected and current release channels. |
-| <span id="lume-channel-set"></span>[`lume channel set`](/lume/reference/cli/updates#lume-channel-set) | Save stable or nightly as the update channel. |
-
-## Global options
-
-`--help` prints help for any command; `--version` prints the version.
-
-## Exit codes
-
-| Code | Meaning |
-| --- | --- |
-| `0` | Success. |
-| `1` | The command failed (for example the VM does not exist or the operation errored). |
-| `64` | Usage error: an unknown command or option, a missing argument, or an invalid value. |
diff --git a/docs/content/docs/lume/reference/cli/meta.json b/docs/content/docs/lume/reference/cli/meta.json
deleted file mode 100644
index 2743bde8e4..0000000000
--- a/docs/content/docs/lume/reference/cli/meta.json
+++ /dev/null
@@ -1,12 +0,0 @@
-{
- "title": "CLI",
- "pages": [
- "index",
- "vms",
- "images",
- "guest",
- "server",
- "config",
- "updates"
- ]
-}
diff --git a/docs/content/docs/lume/reference/cli/server.mdx b/docs/content/docs/lume/reference/cli/server.mdx
deleted file mode 100644
index 051b6059d5..0000000000
--- a/docs/content/docs/lume/reference/cli/server.mdx
+++ /dev/null
@@ -1,148 +0,0 @@
----
-title: "Server"
-description: "Run the HTTP API and MCP server, read its logs, and dump the CLI and API definitions."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:lume
- Source: lume dump-docs --type cli
- Version: 0.6.1
-*/}
-
-| Command | Description |
-| --- | --- |
-| [`lume serve`](#lume-serve) | Start the VM management server. |
-| [`lume logs`](#lume-logs) | View lume serve logs. |
-| [`lume logs info`](#lume-logs-info) | View info logs from the daemon. |
-| [`lume logs error`](#lume-logs-error) | View error logs from the daemon. |
-| [`lume logs all`](#lume-logs-all) | View both info and error logs from the daemon. |
-| [`lume dump-docs`](#lume-dump-docs) | Output CLI and API documentation as JSON for tooling and integrations. |
-
-Every command also accepts the [global options](/lume/reference/cli#global-options).
-
-## `lume serve`
-
-Start the VM management server.
-
-Serves the HTTP API on localhost, or with --mcp an MCP server over stdio for AI agents.
-
-```text output
-lume serve [OPTIONS]
-```
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="lume-serve--port"></span>`--port` | integer | `7777` | Port to listen on (HTTP mode only). |
-| <span id="lume-serve--mcp"></span>`--mcp` | boolean | `false` | Run as an MCP server (stdio transport) for AI agents. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-lume-serve"
-# HTTP API on http://localhost:7777
-lume serve
-lume serve --port 7778
-
-# MCP server over stdio (what MCP clients launch)
-lume serve --mcp
-```
-
-## `lume logs`
-
-View lume serve logs.
-
-```text output
-lume logs <COMMAND>
-```
-
-### `lume logs info`
-
-View info logs from the daemon.
-
-```text output
-lume logs info [OPTIONS]
-```
-
-| Flag | Short | Type | Default | Description |
-| --- | --- | --- | --- | --- |
-| <span id="lume-logs-info--lines"></span>`--lines` | `-l` | integer | | Number of lines to display from the end of the file. |
-| <span id="lume-logs-info--follow"></span>`--follow` | `-f` | boolean | `false` | Follow the log continuously (like tail -f). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-lume-logs-info"
-lume logs info --lines 100
-lume logs info --follow
-```
-
-### `lume logs error`
-
-View error logs from the daemon.
-
-```text output
-lume logs error [OPTIONS]
-```
-
-| Flag | Short | Type | Default | Description |
-| --- | --- | --- | --- | --- |
-| <span id="lume-logs-error--lines"></span>`--lines` | `-l` | integer | | Number of lines to display from the end of the file. |
-| <span id="lume-logs-error--follow"></span>`--follow` | `-f` | boolean | `false` | Follow the log continuously (like tail -f). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-lume-logs-error"
-lume logs error --lines 100
-lume logs error --follow
-```
-
-### `lume logs all`
-
-View both info and error logs from the daemon.
-
-```text output
-lume logs all [OPTIONS]
-```
-
-| Flag | Short | Type | Default | Description |
-| --- | --- | --- | --- | --- |
-| <span id="lume-logs-all--lines"></span>`--lines` | `-l` | integer | | Number of lines to display from the end of each file. |
-| <span id="lume-logs-all--follow"></span>`--follow` | `-f` | boolean | `false` | Follow the log continuously (like tail -f). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-lume-logs-all"
-lume logs all --lines 100
-lume logs all --follow
-```
-
-## `lume dump-docs`
-
-Output CLI and API documentation as JSON for tooling and integrations.
-
-Emits the CLI, HTTP API or MCP tool metadata (arguments, options, flags, endpoints, tool schemas, help text, defaults and types) that the generated reference is built from.
-
-```text output
-lume dump-docs [OPTIONS]
-```
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="lume-dump-docs--type"></span>`--type` | `cli` \| `api` \| `mcp` \| `all` | `cli` | Documentation type to output. |
-| <span id="lume-dump-docs--pretty"></span>`--pretty` | boolean | `false` | Pretty-print the JSON output with sorted keys. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-lume-dump-docs"
-lume dump-docs --type cli --pretty
-
-# The MCP server's tool list
-lume dump-docs --type mcp
-```
-
-## Exit codes
-
-| Code | Meaning |
-| --- | --- |
-| `0` | Success. |
-| `1` | The command failed (for example the VM does not exist or the operation errored). |
-| `64` | Usage error: an unknown command or option, a missing argument, or an invalid value. |
diff --git a/docs/content/docs/lume/reference/cli/updates.mdx b/docs/content/docs/lume/reference/cli/updates.mdx
deleted file mode 100644
index d5259a7102..0000000000
--- a/docs/content/docs/lume/reference/cli/updates.mdx
+++ /dev/null
@@ -1,124 +0,0 @@
----
-title: "Updates"
-description: "Check for, apply and choose the channel of Lume updates."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:lume
- Source: lume dump-docs --type cli
- Version: 0.6.1
-*/}
-
-| Command | Description |
-| --- | --- |
-| [`lume check-update`](#lume-check-update) | Check whether a newer Lume release is available. |
-| [`lume update`](#lume-update) | Check for a Lume update and optionally apply it. |
-| [`lume channel`](#lume-channel) | Inspect or change the stable/nightly update channel; selection does not install. |
-| [`lume channel status`](#lume-channel-status) | Show selected and current release channels. |
-| [`lume channel set`](#lume-channel-set) | Save stable or nightly as the update channel. |
-
-Every command also accepts the [global options](/lume/reference/cli#global-options).
-
-## `lume check-update`
-
-Check whether a newer Lume release is available.
-
-Read-only update check. Uses GitHub Releases, caches the result briefly, and never installs anything.
-
-```text output
-lume check-update [OPTIONS]
-```
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="lume-check-update--json"></span>`--json` | boolean | `false` | Emit the structured update-state payload as JSON. |
-| <span id="lume-check-update--no-cache"></span>`--no-cache` | boolean | `false` | Bypass the local update-check cache. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-lume-check-update"
-lume check-update
-lume check-update --json --no-cache
-```
-
-## `lume update`
-
-Check for a Lume update and optionally apply it.
-
-Without --apply, this command only checks for a newer release and prints the command to install it. With --apply, it runs the official Lume installer pinned to the discovered version and exits with the installer's status.
-
-```text output
-lume update [OPTIONS]
-```
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="lume-update--apply"></span>`--apply` | boolean | `false` | Apply the update while preserving the current background-service choice. |
-| <span id="lume-update--json"></span>`--json` | boolean | `false` | Emit the structured update-state payload as JSON. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-lume-update"
-lume update
-lume update --apply
-```
-
-## `lume channel`
-
-Inspect or change the stable/nightly update channel; selection does not install.
-
-The selection persists but never installs by itself; run `lume update --apply` after changing it. Without a subcommand, prints the status.
-
-```text output
-lume channel <COMMAND>
-```
-
-### `lume channel status`
-
-Show selected and current release channels.
-
-```text output
-lume channel status [OPTIONS]
-```
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="lume-channel-status--json"></span>`--json` | boolean | `false` | Emit machine-readable channel state as JSON. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-lume-channel-status"
-lume channel status --json
-```
-
-### `lume channel set`
-
-Save stable or nightly as the update channel.
-
-```text output
-lume channel set [OPTIONS] <channel>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<channel>` | string | required | Release channel: stable or nightly. |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="lume-channel-set--json"></span>`--json` | boolean | `false` | Emit machine-readable channel state as JSON. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-lume-channel-set"
-lume channel set nightly
-lume channel set stable
-```
-
-## Exit codes
-
-| Code | Meaning |
-| --- | --- |
-| `0` | Success. |
-| `1` | The command failed (for example the VM does not exist or the operation errored). |
-| `64` | Usage error: an unknown command or option, a missing argument, or an invalid value. |
diff --git a/docs/content/docs/lume/reference/cli/vms.mdx b/docs/content/docs/lume/reference/cli/vms.mdx
deleted file mode 100644
index a91a8c7d31..0000000000
--- a/docs/content/docs/lume/reference/cli/vms.mdx
+++ /dev/null
@@ -1,370 +0,0 @@
----
-title: "VMs"
-description: "Create, run, inspect, change, clone and delete virtual machines."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:lume
- Source: lume dump-docs --type cli
- Version: 0.6.1
-*/}
-
-| Command | Description |
-| --- | --- |
-| [`lume create`](#lume-create) | Create a new virtual machine. |
-| [`lume run`](#lume-run) | Run a virtual machine. |
-| [`lume attach`](#lume-attach) | Open a viewer for a running virtual machine. |
-| [`lume stop`](#lume-stop) | Stop a virtual machine. |
-| [`lume shutdown`](#lume-shutdown) | Gracefully shut down a virtual machine. |
-| [`lume restart`](#lume-restart) | Gracefully restart a virtual machine. |
-| [`lume ls`](#lume-ls) | List virtual machines. |
-| [`lume get`](#lume-get) | Get detailed information about a virtual machine. |
-| [`lume set`](#lume-set) | Set new values for CPU, memory, and disk size of a virtual machine. |
-| [`lume clone`](#lume-clone) | Clone an existing virtual machine. |
-| [`lume delete`](#lume-delete) | Delete a virtual machine. |
-
-Every command also accepts the [global options](/lume/reference/cli#global-options).
-
-## `lume create`
-
-Create a new virtual machine.
-
-```text output
-lume create [OPTIONS] <name>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<name>` | string | required | Name for the virtual machine. |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="lume-create--os"></span>`--os` | string | `macOS` | Operating system to install: macOS or linux. |
-| <span id="lume-create--cpu"></span>`--cpu` | integer | `4` | Number of CPU cores. |
-| <span id="lume-create--memory"></span>`--memory` | string | `8GB` | Memory size (8, 8GB or 8192MB; a bare number is GB). |
-| <span id="lume-create--disk-size"></span>`--disk-size` | string | | Disk size (100, 100GB or 102400MB; a bare number is GB). Defaults to 100GB for macOS and 50GB for Linux. |
-| <span id="lume-create--display"></span>`--display` | string | `1024x768` | Display resolution as WIDTHxHEIGHT. |
-| <span id="lume-create--ipsw"></span>`--ipsw` | string | | Path to a macOS restore image (IPSW), or 'latest' to download the latest supported version. Required for macOS VMs. |
-| <span id="lume-create--storage"></span>`--storage` | string | | VM storage location name, or a direct path to the VM location. |
-| <span id="lume-create--unattended"></span>`--unattended` | string | | Prepare macOS unattended setup offline after install. Built-in presets: sequoia, tahoe; a YAML path is accepted for compatibility. macOS VMs only. |
-| <span id="lume-create--debug-dir"></span>`--debug-dir` | string | | Compatibility option; ignored by offline setup. |
-| <span id="lume-create--vnc-port"></span>`--vnc-port` | integer | `0` | Port for the temporary verification VNC server (0 picks a free port). |
-| <span id="lume-create--network"></span>`--network` | string | `nat` | Network mode: nat, bridged (picks an interface), or bridged:&lt;interface&gt; (for example bridged:en0). |
-| <span id="lume-create--debug"></span>`--debug` | boolean | `false` | Compatibility flag; ignored by offline setup. |
-| <span id="lume-create--no-display"></span>`--no-display` | boolean | `false` | Compatibility flag; offline setup verifies headlessly. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-lume-create"
-# A macOS VM from the latest IPSW, set up unattended (SSH user lume/lume)
-lume create macos-tahoe --ipsw latest --unattended tahoe
-
-# A Linux VM
-lume create dev --os linux --cpu 4 --memory 8GB --disk-size 50GB
-
-# Bridge the VM onto the host's en0 network
-lume create macos-tahoe --ipsw latest --network bridged:en0
-```
-
-## `lume run`
-
-Run a virtual machine.
-
-```text output
-lume run [OPTIONS] <name>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<name>` | string | required | Name of the VM, or an image to pull and run (format: name or name:tag). |
-
-| Flag | Short | Type | Default | Description |
-| --- | --- | --- | --- | --- |
-| <span id="lume-run--display"></span>`--display` | | `vnc` \| `native` \| `none` | `native` | Local viewer to open. The VNC server stays available in every mode. |
-| <span id="lume-run--log-file"></span>`--log-file` | | string | | Log path for --detach (default: ~/Library/Logs/lume/&#123;vm&#125;.log). |
-| <span id="lume-run--shared-dir"></span>`--shared-dir` | | string | | Directory to share with the VM: a path (read-write) or path:ro / path:rw. Repeatable. |
-| <span id="lume-run--mount"></span>`--mount` | | string | | For Linux VMs only, a read-only disk image to attach. |
-| <span id="lume-run--usb-storage"></span>`--usb-storage` | | string | | Disk image to attach as a USB mass storage device. Repeatable. |
-| <span id="lume-run--disk"></span>`--disk` | | string | | Disk image to attach as a read-write virtio-blk device. Repeatable. |
-| <span id="lume-run--registry"></span>`--registry` | | string | `ghcr.io` | Container registry to pull images from. |
-| <span id="lume-run--organization"></span>`--organization` | | string | `trycua` | Organization to pull images from. |
-| <span id="lume-run--vnc"></span>`--vnc` | | `enabled` \| `disabled` | `enabled` | VNC server policy. disabled starts the VM with no VNC listener and reports a null vncUrl. |
-| <span id="lume-run--vnc-port"></span>`--vnc-port` | | integer | `0` | Port for the VNC server (0 picks a free port). |
-| <span id="lume-run--vnc-password"></span>`--vnc-password` | | string | | Password for the VNC server (default: a random passphrase). |
-| <span id="lume-run--recovery-mode"></span>`--recovery-mode` | | boolean | `false` | For macOS VMs only, boot into recovery mode. |
-| <span id="lume-run--storage"></span>`--storage` | | string | | VM storage location name, or a direct path to the VM location. |
-| <span id="lume-run--disk-path"></span>`--disk-path` | | string | | Use this disk image instead of disk.img in the VM directory. |
-| <span id="lume-run--nvram-path"></span>`--nvram-path` | | string | | Use this NVRAM file instead of nvram.bin in the VM directory. |
-| <span id="lume-run--network"></span>`--network` | | string | | Network override for this run: nat, bridged, or bridged:&lt;interface&gt; (default: the VM's configured mode). |
-| <span id="lume-run--no-display"></span>`--no-display` | `-d` | boolean | `false` | Compatibility alias for --display none. |
-| <span id="lume-run--detach"></span>`--detach` | | boolean | `false` | Run the VM in the background and return immediately. |
-| <span id="lume-run--clipboard"></span>`--clipboard` | | boolean | `false` | Sync the clipboard both ways over SSH. Automatic with the native macOS display. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-lume-run"
-lume run my-vm
-
-# Headless, with a read-only shared folder
-lume run my-vm --shared-dir ~/src:ro --display none
-
-# In the background with no VNC listener
-lume run my-vm --detach --display none --vnc disabled
-```
-
-## `lume attach`
-
-Open a viewer for a running virtual machine.
-
-The native display is used when the `lume run` process that owns the VM supports live attachment; VNC is the fallback.
-
-```text output
-lume attach [OPTIONS] <name>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<name>` | string | required | Name of the virtual machine. |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="lume-attach--display"></span>`--display` | `native` \| `vnc` | | Viewer to open (default: native, falling back to VNC). |
-| <span id="lume-attach--storage"></span>`--storage` | string | | VM storage location to use. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-lume-attach"
-lume attach my-vm
-
-# Open Screen Sharing over VNC
-lume attach my-vm --display vnc
-```
-
-## `lume stop`
-
-Stop a virtual machine.
-
-```text output
-lume stop [OPTIONS] <name>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<name>` | string | required | Name of the VM to stop. |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="lume-stop--storage"></span>`--storage` | string | | VM storage location name, or a direct path to the VM location. |
-| <span id="lume-stop--timeout"></span>`--timeout` | integer | `10` | Seconds to wait for a graceful shutdown before forcing power off. |
-| <span id="lume-stop--force"></span>`--force` | boolean | `false` | Power off the VM immediately instead of attempting a graceful shutdown first. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-lume-stop"
-lume stop my-vm
-lume stop my-vm --force
-```
-
-## `lume shutdown`
-
-Gracefully shut down a virtual machine.
-
-Requests the operation inside the guest over SSH. VMs created with --unattended use lume/lume credentials by default.
-
-```text output
-lume shutdown [OPTIONS] <name>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<name>` | string | required | Name of the virtual machine. |
-
-| Flag | Short | Type | Default | Description |
-| --- | --- | --- | --- | --- |
-| <span id="lume-shutdown--user"></span>`--user` | `-u` | string | `lume` | SSH username. |
-| <span id="lume-shutdown--password"></span>`--password` | `-p` | string | `lume` | SSH and sudo password. |
-| <span id="lume-shutdown--storage"></span>`--storage` | | string | | VM storage location to use. |
-| <span id="lume-shutdown--timeout"></span>`--timeout` | `-t` | integer | `30` | SSH command timeout in seconds. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-lume-shutdown"
-lume shutdown my-vm
-
-# With another SSH user and a longer timeout
-lume shutdown my-vm --user admin --timeout 60
-```
-
-## `lume restart`
-
-Gracefully restart a virtual machine.
-
-Requests the operation inside the guest over SSH. VMs created with --unattended use lume/lume credentials by default.
-
-```text output
-lume restart [OPTIONS] <name>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<name>` | string | required | Name of the virtual machine. |
-
-| Flag | Short | Type | Default | Description |
-| --- | --- | --- | --- | --- |
-| <span id="lume-restart--user"></span>`--user` | `-u` | string | `lume` | SSH username. |
-| <span id="lume-restart--password"></span>`--password` | `-p` | string | `lume` | SSH and sudo password. |
-| <span id="lume-restart--storage"></span>`--storage` | | string | | VM storage location to use. |
-| <span id="lume-restart--timeout"></span>`--timeout` | `-t` | integer | `30` | SSH command timeout in seconds. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-lume-restart"
-lume restart my-vm
-
-# With another SSH user and a longer timeout
-lume restart my-vm --user admin --timeout 60
-```
-
-## `lume ls`
-
-List virtual machines.
-
-```text output
-lume ls [OPTIONS]
-```
-
-| Flag | Short | Type | Default | Description |
-| --- | --- | --- | --- | --- |
-| <span id="lume-ls--format"></span>`--format` | `-f` | `json` \| `text` | `text` | Output format. |
-| <span id="lume-ls--storage"></span>`--storage` | | string | | Show only VMs in this storage location. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-lume-ls"
-lume ls
-lume ls --format json
-```
-
-## `lume get`
-
-Get detailed information about a virtual machine.
-
-```text output
-lume get [OPTIONS] <name>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<name>` | string | required | Name of the VM. |
-
-| Flag | Short | Type | Default | Description |
-| --- | --- | --- | --- | --- |
-| <span id="lume-get--format"></span>`--format` | `-f` | `json` \| `text` | `text` | Output format. |
-| <span id="lume-get--storage"></span>`--storage` | | string | | VM storage location name, or a direct path to the VM location. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-lume-get"
-lume get my-vm
-
-# Machine-readable, including the IP address and VNC URL
-lume get my-vm --format json
-```
-
-## `lume set`
-
-Set new values for CPU, memory, and disk size of a virtual machine.
-
-```text output
-lume set [OPTIONS] <name>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<name>` | string | required | Name of the VM. |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="lume-set--cpu"></span>`--cpu` | integer | | New number of CPU cores. |
-| <span id="lume-set--memory"></span>`--memory` | string | | New memory size (8, 8GB or 8192MB; a bare number is GB). |
-| <span id="lume-set--disk-size"></span>`--disk-size` | string | | New total disk size, increase only. For macOS VMs this relocates the recovery partition and grows the main APFS container; the VM must be stopped and it may take several minutes. |
-| <span id="lume-set--display"></span>`--display` | string | | New display resolution as WIDTHxHEIGHT. |
-| <span id="lume-set--machine-identifier"></span>`--machine-identifier` | string | | New machine identifier: 'random', or a base64 identifier from `lume get --format json` to give this VM an existing machine identity (per-machine licenses then see one machine). macOS VMs only; the VM must be stopped. |
-| <span id="lume-set--mac-address"></span>`--mac-address` | string | | New MAC address: 'random' (locally administered) or aa:bb:cc:dd:ee:ff. The VM must be stopped. The DHCP lease follows the MAC, so two running VMs with one MAC claim the same IP. |
-| <span id="lume-set--storage"></span>`--storage` | string | | VM storage location name, or a direct path to the VM location. |
-| <span id="lume-set--no-backup"></span>`--no-backup` | boolean | `false` | Skip the pre-resize disk backup (macOS resize only). Faster, but a failure cannot be rolled back. |
-| <span id="lume-set--keep-backup"></span>`--keep-backup` | boolean | `false` | Keep the pre-resize backup after a successful macOS resize. |
-| <span id="lume-set--dry-run"></span>`--dry-run` | boolean | `false` | Validate the disk-resize plan and print it without changing anything (macOS resize only). |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-lume-set"
-lume set my-vm --cpu 8 --memory 16GB
-
-# Check a disk resize plan, then run it without --dry-run
-lume set my-vm --disk-size 120GB --dry-run
-lume set my-vm --mac-address random
-```
-
-## `lume clone`
-
-Clone an existing virtual machine.
-
-```text output
-lume clone [OPTIONS] <name> <new-name>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<name>` | string | required | Name of the source VM. |
-| `<new-name>` | string | required | Name for the cloned VM. |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="lume-clone--source-storage"></span>`--source-storage` | string | | Source VM storage location. |
-| <span id="lume-clone--dest-storage"></span>`--dest-storage` | string | | Destination VM storage location. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-lume-clone"
-# Keep a golden copy before changing a VM
-lume clone macos-tahoe macos-tahoe-backup
-
-# Copy a VM to another storage location
-lume clone macos-tahoe macos-tahoe --source-storage default --dest-storage external
-```
-
-## `lume delete`
-
-Delete a virtual machine.
-
-```text output
-lume delete [OPTIONS] <name>
-```
-
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-| `<name>` | string | required | Name of the VM to delete. |
-
-| Flag | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="lume-delete--storage"></span>`--storage` | string | | VM storage location name, or a direct path to the VM location. |
-| <span id="lume-delete--force"></span>`--force` | boolean | `false` | Delete without asking for confirmation. |
-
-**Examples**
-
-```bash test="cli-shape" id="ref-lume-delete"
-lume delete my-vm
-
-# Without the confirmation prompt
-lume delete my-vm --force
-```
-
-## Exit codes
-
-| Code | Meaning |
-| --- | --- |
-| `0` | Success. |
-| `1` | The command failed (for example the VM does not exist or the operation errored). |
-| `64` | Usage error: an unknown command or option, a missing argument, or an invalid value. |
diff --git a/docs/content/docs/lume/reference/http-api.mdx b/docs/content/docs/lume/reference/http-api.mdx
index 97adc5a9bb..584a779ded 100644
--- a/docs/content/docs/lume/reference/http-api.mdx
+++ b/docs/content/docs/lume/reference/http-api.mdx
@@ -1,6 +1,6 @@
---
-title: "HTTP API"
-description: "Every endpoint of the Lume HTTP API server (lume serve)."
+title: "HTTP API and MCP tools"
+description: "Every endpoint of the Lume HTTP API server and every tool of its MCP server (lume serve)."
---
{/*
@@ -1143,3 +1143,182 @@ const data = await response.json();
- `200`: Success.
- `400`: Failed to read logs.
+
+## MCP tools
+
+`lume serve --mcp` serves these tools over stdio. See [Connect an MCP client](/lume/guides/manage-vms#connect-an-mcp-client) for client setup.
+
+### VM tools
+
+#### `lume_list_vms`
+
+List all virtual machines with their status, IP addresses, and resource allocation.
+
+Effect: read-only, idempotent.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="lume_list_vms--storage"></span>`storage` | `string` | | Optional storage location name or path to filter VMs. |
+
+#### `lume_get_vm`
+
+Get detailed information about a specific VM including IP address, VNC URL, and SSH availability.
+
+Effect: read-only, idempotent.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="lume_get_vm--name"></span>`name` | `string` | required | Name of the VM. |
+| <span id="lume_get_vm--storage"></span>`storage` | `string` | | Optional storage location name or path. |
+
+**Example arguments**
+
+```json
+{"name":"<name>"}
+```
+
+#### `lume_run_vm`
+
+Start a VM with optional shared directory for file access. The shared directory will be available at /Volumes/My Shared Files inside the VM.
+
+Effect: mutating.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="lume_run_vm--name"></span>`name` | `string` | required | Name of the VM to start. |
+| <span id="lume_run_vm--no_display"></span>`no_display` | `boolean` | | Run headless without VNC window (default: true). |
+| <span id="lume_run_vm--shared_dir"></span>`shared_dir` | `string` | | Host directory path to share with the VM (appears at /Volumes/My Shared Files). |
+| <span id="lume_run_vm--storage"></span>`storage` | `string` | | Optional storage location name or path. |
+| <span id="lume_run_vm--vnc"></span>`vnc` | `"enabled" \| "disabled"` | | VNC server policy. 'disabled' starts no VNC listener and reports a null vncUrl (default: enabled). |
+
+**Example arguments**
+
+```json
+{"name":"<name>"}
+```
+
+#### `lume_stop_vm`
+
+Stop a running VM gracefully.
+
+Effect: mutating.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="lume_stop_vm--name"></span>`name` | `string` | required | Name of the VM to stop. |
+| <span id="lume_stop_vm--storage"></span>`storage` | `string` | | Optional storage location name or path. |
+
+**Example arguments**
+
+```json
+{"name":"<name>"}
+```
+
+#### `lume_clone_vm`
+
+Clone a VM to create a copy. Useful for creating golden images for instant reset.
+
+Effect: mutating.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="lume_clone_vm--name"></span>`name` | `string` | required | Name of the source VM to clone. |
+| <span id="lume_clone_vm--new_name"></span>`new_name` | `string` | required | Name for the cloned VM. |
+
+**Example arguments**
+
+```json
+{"name":"<name>","new_name":"<new_name>"}
+```
+
+#### `lume_delete_vm`
+
+Delete a VM and all its associated files.
+
+Effect: destructive.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="lume_delete_vm--name"></span>`name` | `string` | required | Name of the VM to delete. |
+| <span id="lume_delete_vm--storage"></span>`storage` | `string` | | Optional storage location name or path. |
+
+**Example arguments**
+
+```json
+{"name":"<name>"}
+```
+
+#### `lume_create_vm`
+
+Create a new macOS VM asynchronously. Returns immediately while the VM is being provisioned. Poll lume_list_vms or lume_get_vm to check progress (status will be 'provisioning' until complete).
+
+Effect: mutating.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="lume_create_vm--cpu"></span>`cpu` | `integer` | | Number of CPU cores (default: 4). |
+| <span id="lume_create_vm--disk_size"></span>`disk_size` | `string` | | Disk size, e.g., '100GB' (default: 100GB). |
+| <span id="lume_create_vm--ipsw"></span>`ipsw` | `string` | | Path to IPSW file or 'latest' to download (default: latest). |
+| <span id="lume_create_vm--memory"></span>`memory` | `string` | | Memory size, e.g., '8GB' (default: 8GB). |
+| <span id="lume_create_vm--name"></span>`name` | `string` | required | Name for the new VM. |
+| <span id="lume_create_vm--storage"></span>`storage` | `string` | | Optional storage location name or path. |
+| <span id="lume_create_vm--unattended"></span>`unattended` | `string` | | Unattended setup preset (e.g., 'tahoe', 'sequoia') for automatic macOS configuration. |
+
+**Example arguments**
+
+```json
+{"name":"<name>"}
+```
+
+#### `lume_resize_disk`
+
+Grow a stopped VM's disk. For macOS VMs this preserves the paired RecoveryOS partition (relocating it to the new end of disk) and expands the main APFS container so future macOS updates keep working. Grow-only; the VM must be stopped; may take several minutes.
+
+Effect: destructive.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="lume_resize_disk--disk_size"></span>`disk_size` | `string` | required | New disk size, e.g., '100GB'. Must be larger than the current size. |
+| <span id="lume_resize_disk--dry_run"></span>`dry_run` | `boolean` | | Validate and print the resize plan without modifying the disk. Default false. |
+| <span id="lume_resize_disk--keep_backup"></span>`keep_backup` | `boolean` | | Keep the rollback backup after a successful resize; cannot be combined with no_backup. Default false. |
+| <span id="lume_resize_disk--name"></span>`name` | `string` | required | Name of the VM to resize. |
+| <span id="lume_resize_disk--no_backup"></span>`no_backup` | `boolean` | | Skip the pre-resize backup (faster, but no automatic rollback on failure). Default false. |
+| <span id="lume_resize_disk--storage"></span>`storage` | `string` | | Optional storage location name or path. |
+
+**Example arguments**
+
+```json
+{"name":"<name>","disk_size":"<disk_size>"}
+```
+
+### Guest tools
+
+#### `lume_exec`
+
+Execute a command inside a running VM via SSH. Requires SSH to be enabled in the VM (default for VMs created with --unattended tahoe).
+
+Effect: destructive.
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| <span id="lume_exec--command"></span>`command` | `string` | required | Shell command to execute inside the VM. |
+| <span id="lume_exec--name"></span>`name` | `string` | required | Name of the VM. |
+| <span id="lume_exec--password"></span>`password` | `string` | | SSH password (default: lume). |
+| <span id="lume_exec--storage"></span>`storage` | `string` | | Optional storage location name or path. |
+| <span id="lume_exec--user"></span>`user` | `string` | | SSH username (default: lume). |
+
+**Example arguments**
+
+```json
+{"name":"<name>","command":"<command>"}
+```
+
+### Maintenance tools
+
+#### `check_for_update`
+
+Check the saved stable/nightly Lume channel for a release on GitHub. Returns current and selected channels. Read-only; never installs. Mirrors `lume check-update --json`.
+
+Effect: read-only, idempotent.
+
+No parameters.
diff --git a/docs/content/docs/lume/reference/index.mdx b/docs/content/docs/lume/reference/index.mdx
index 2ba88c6a62..7265193cf6 100644
--- a/docs/content/docs/lume/reference/index.mdx
+++ b/docs/content/docs/lume/reference/index.mdx
@@ -15,21 +15,16 @@ description: "Every lume command, HTTP endpoint and MCP tool, generated from the
| Command group | Description |
| --- | --- |
| [`lume`](/lume/reference/cli) | Synopsis, global options, exit codes and every command. |
-| [VMs](/lume/reference/cli/vms) | Create, run, inspect, change, clone and delete virtual machines. |
-| [Images](/lume/reference/cli/images) | Pull, push and convert VM images, find restore images, and prune the cache. |
-| [Guest access](/lume/reference/cli/guest) | Prepare unattended setup, open SSH sessions, copy files and change SIP in a guest. |
-| [Server](/lume/reference/cli/server) | Run the HTTP API and MCP server, read its logs, and dump the CLI and API definitions. |
-| [Configuration](/lume/reference/cli/config) | Storage locations, the image cache and telemetry settings. |
-| [Updates](/lume/reference/cli/updates) | Check for, apply and choose the channel of Lume updates. |
+| [VMs](/lume/reference/cli#vms) | Create, run, inspect, change, clone and delete virtual machines. |
+| [Images](/lume/reference/cli#images) | Pull, push and convert VM images, find restore images, and prune the cache. |
+| [Guest access](/lume/reference/cli#guest-access) | Prepare unattended setup, open SSH sessions, copy files and change SIP in a guest. |
+| [Server](/lume/reference/cli#server) | Run the HTTP API and MCP server, read its logs, and dump the CLI and API definitions. |
+| [Configuration](/lume/reference/cli#configuration) | Storage locations, the image cache and telemetry settings. |
+| [Updates](/lume/reference/cli#updates) | Check for, apply and choose the channel of Lume updates. |
-## HTTP API
+## HTTP API and MCP tools
| API | Description |
| --- | --- |
| [HTTP API](/lume/reference/http-api) | Every endpoint `lume serve` exposes, with parameters and examples. |
-
-## MCP tools
-
-| Tools | Description |
-| --- | --- |
-| [MCP tools](/lume/reference/mcp-tools) | Every tool Lume's MCP server exposes, with its parameters. |
+| [MCP tools](/lume/reference/http-api#mcp-tools) | Every tool Lume's MCP server exposes, with its parameters. |
diff --git a/docs/content/docs/lume/reference/mcp-tools.mdx b/docs/content/docs/lume/reference/mcp-tools.mdx
deleted file mode 100644
index 375f7d0106..0000000000
--- a/docs/content/docs/lume/reference/mcp-tools.mdx
+++ /dev/null
@@ -1,188 +0,0 @@
----
-title: "MCP tools"
-description: "Every tool Lume's MCP server exposes, with its parameters."
----
-
-{/*
- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
- Generated by: pnpm --dir docs docs:generate:lume
- Source: lume dump-docs --type mcp
- Version: 0.6.1
-*/}
-
-`lume serve --mcp` serves these tools over stdio. See [Connect an MCP client](/lume/guides/manage-vms#connect-an-mcp-client) for client setup.
-
-## VM tools
-
-### `lume_list_vms`
-
-List all virtual machines with their status, IP addresses, and resource allocation.
-
-Effect: read-only, idempotent.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="lume_list_vms--storage"></span>`storage` | `string` | | Optional storage location name or path to filter VMs. |
-
-### `lume_get_vm`
-
-Get detailed information about a specific VM including IP address, VNC URL, and SSH availability.
-
-Effect: read-only, idempotent.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="lume_get_vm--name"></span>`name` | `string` | required | Name of the VM. |
-| <span id="lume_get_vm--storage"></span>`storage` | `string` | | Optional storage location name or path. |
-
-**Example arguments**
-
-```json
-{"name":"<name>"}
-```
-
-### `lume_run_vm`
-
-Start a VM with optional shared directory for file access. The shared directory will be available at /Volumes/My Shared Files inside the VM.
-
-Effect: mutating.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="lume_run_vm--name"></span>`name` | `string` | required | Name of the VM to start. |
-| <span id="lume_run_vm--no_display"></span>`no_display` | `boolean` | | Run headless without VNC window (default: true). |
-| <span id="lume_run_vm--shared_dir"></span>`shared_dir` | `string` | | Host directory path to share with the VM (appears at /Volumes/My Shared Files). |
-| <span id="lume_run_vm--storage"></span>`storage` | `string` | | Optional storage location name or path. |
-| <span id="lume_run_vm--vnc"></span>`vnc` | `"enabled" \| "disabled"` | | VNC server policy. 'disabled' starts no VNC listener and reports a null vncUrl (default: enabled). |
-
-**Example arguments**
-
-```json
-{"name":"<name>"}
-```
-
-### `lume_stop_vm`
-
-Stop a running VM gracefully.
-
-Effect: mutating.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="lume_stop_vm--name"></span>`name` | `string` | required | Name of the VM to stop. |
-| <span id="lume_stop_vm--storage"></span>`storage` | `string` | | Optional storage location name or path. |
-
-**Example arguments**
-
-```json
-{"name":"<name>"}
-```
-
-### `lume_clone_vm`
-
-Clone a VM to create a copy. Useful for creating golden images for instant reset.
-
-Effect: mutating.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="lume_clone_vm--name"></span>`name` | `string` | required | Name of the source VM to clone. |
-| <span id="lume_clone_vm--new_name"></span>`new_name` | `string` | required | Name for the cloned VM. |
-
-**Example arguments**
-
-```json
-{"name":"<name>","new_name":"<new_name>"}
-```
-
-### `lume_delete_vm`
-
-Delete a VM and all its associated files.
-
-Effect: destructive.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="lume_delete_vm--name"></span>`name` | `string` | required | Name of the VM to delete. |
-| <span id="lume_delete_vm--storage"></span>`storage` | `string` | | Optional storage location name or path. |
-
-**Example arguments**
-
-```json
-{"name":"<name>"}
-```
-
-### `lume_create_vm`
-
-Create a new macOS VM asynchronously. Returns immediately while the VM is being provisioned. Poll lume_list_vms or lume_get_vm to check progress (status will be 'provisioning' until complete).
-
-Effect: mutating.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="lume_create_vm--cpu"></span>`cpu` | `integer` | | Number of CPU cores (default: 4). |
-| <span id="lume_create_vm--disk_size"></span>`disk_size` | `string` | | Disk size, e.g., '100GB' (default: 100GB). |
-| <span id="lume_create_vm--ipsw"></span>`ipsw` | `string` | | Path to IPSW file or 'latest' to download (default: latest). |
-| <span id="lume_create_vm--memory"></span>`memory` | `string` | | Memory size, e.g., '8GB' (default: 8GB). |
-| <span id="lume_create_vm--name"></span>`name` | `string` | required | Name for the new VM. |
-| <span id="lume_create_vm--storage"></span>`storage` | `string` | | Optional storage location name or path. |
-| <span id="lume_create_vm--unattended"></span>`unattended` | `string` | | Unattended setup preset (e.g., 'tahoe', 'sequoia') for automatic macOS configuration. |
-
-**Example arguments**
-
-```json
-{"name":"<name>"}
-```
-
-### `lume_resize_disk`
-
-Grow a stopped VM's disk. For macOS VMs this preserves the paired RecoveryOS partition (relocating it to the new end of disk) and expands the main APFS container so future macOS updates keep working. Grow-only; the VM must be stopped; may take several minutes.
-
-Effect: destructive.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="lume_resize_disk--disk_size"></span>`disk_size` | `string` | required | New disk size, e.g., '100GB'. Must be larger than the current size. |
-| <span id="lume_resize_disk--dry_run"></span>`dry_run` | `boolean` | | Validate and print the resize plan without modifying the disk. Default false. |
-| <span id="lume_resize_disk--keep_backup"></span>`keep_backup` | `boolean` | | Keep the rollback backup after a successful resize; cannot be combined with no_backup. Default false. |
-| <span id="lume_resize_disk--name"></span>`name` | `string` | required | Name of the VM to resize. |
-| <span id="lume_resize_disk--no_backup"></span>`no_backup` | `boolean` | | Skip the pre-resize backup (faster, but no automatic rollback on failure). Default false. |
-| <span id="lume_resize_disk--storage"></span>`storage` | `string` | | Optional storage location name or path. |
-
-**Example arguments**
-
-```json
-{"name":"<name>","disk_size":"<disk_size>"}
-```
-
-## Guest tools
-
-### `lume_exec`
-
-Execute a command inside a running VM via SSH. Requires SSH to be enabled in the VM (default for VMs created with --unattended tahoe).
-
-Effect: destructive.
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| <span id="lume_exec--command"></span>`command` | `string` | required | Shell command to execute inside the VM. |
-| <span id="lume_exec--name"></span>`name` | `string` | required | Name of the VM. |
-| <span id="lume_exec--password"></span>`password` | `string` | | SSH password (default: lume). |
-| <span id="lume_exec--storage"></span>`storage` | `string` | | Optional storage location name or path. |
-| <span id="lume_exec--user"></span>`user` | `string` | | SSH username (default: lume). |
-
-**Example arguments**
-
-```json
-{"name":"<name>","command":"<command>"}
-```
-
-## Maintenance tools
-
-### `check_for_update`
-
-Check the saved stable/nightly Lume channel for a release on GitHub. Returns current and selected channels. Read-only; never installs. Mirrors `lume check-update --json`.
-
-Effect: read-only, idempotent.
-
-No parameters.
diff --git a/docs/content/docs/lume/reference/meta.json b/docs/content/docs/lume/reference/meta.json
index 9d845f01b0..4f11d30879 100644
--- a/docs/content/docs/lume/reference/meta.json
+++ b/docs/content/docs/lume/reference/meta.json
@@ -3,7 +3,6 @@
"pages": [
"index",
"cli",
- "http-api",
- "mcp-tools"
+ "http-api"
]
}
diff --git a/docs/content/docs/redirects.json b/docs/content/docs/redirects.json
index 587a4cd6d1..9487b0fc56 100644
--- a/docs/content/docs/redirects.json
+++ b/docs/content/docs/redirects.json
@@ -40,8 +40,8 @@
"cua-bench/concepts/what-is-cua-bench": "cua-bench",
"cua-bench/guides/osworld": "cua-bench/guides/benchmarks",
"cua-bench/guides/run-a-task": "cua-bench/quickstart",
- "cua-cli/reference/mcp-tools/space-agents": "cua-cli/reference/mcp-tools/spaces",
- "cua-cli/reference/mcp-tools/space-io": "cua-cli/reference/mcp-tools/spaces",
+ "cua-cli/reference/mcp-tools/space-agents": "cua-cli/reference/mcp-tools#spaces-tools",
+ "cua-cli/reference/mcp-tools/space-io": "cua-cli/reference/mcp-tools#spaces-tools",
"cua-driver/concepts/action-selection-policy": "cua-driver/concepts/how-cua-driver-works",
"cua-driver/concepts/browser-profile-attachment": "cua-driver/guides/browsers",
"cua-driver/concepts/browser-semantic-snapshots": "cua-driver/guides/browsers",
@@ -114,7 +114,7 @@
"cua-driver/guides/verify-a-desktop-action": "cua-driver/guides/use-the-sdk",
"cua-driver/guides/windows-ssh": "cua-driver/guides/vms-and-remote",
"cua-driver/guides/write-a-bounded-manifest": "cua-driver/guides/permissions",
- "cua-driver/reference/macos-permissions": "cua-driver/reference/cli/permissions",
+ "cua-driver/reference/macos-permissions": "cua-driver/reference/cli/serve-and-configure#cua-driver-permissions",
"cua-driver/reference/mcp-tool-notes": "cua-driver/reference/mcp-tools",
"cua-driver/reference/mcp-tools-linux": "cua-driver/reference/mcp-tools",
"cua-driver/reference/mcp-tools-windows": "cua-driver/reference/mcp-tools",
@@ -323,7 +323,7 @@
"reference/cua-driver/development": "cua-driver",
"reference/cua-driver/embedding": "cua-driver/guides/use-the-sdk",
"reference/cua-driver/limits": "cua-driver/guides/troubleshoot",
- "reference/cua-driver/macos-permissions": "cua-driver/reference/cli/permissions",
+ "reference/cua-driver/macos-permissions": "cua-driver/reference/cli/serve-and-configure#cua-driver-permissions",
"reference/cua-driver/mcp-tool-notes": "cua-driver/reference/mcp-tools",
"reference/cua-driver/mcp-tools": "cua-driver/reference/mcp-tools",
"reference/cua-driver/mcp-tools-linux": "cua-driver/reference/mcp-tools",
@@ -382,7 +382,7 @@
"reference/lume/cli-reference": "lume/reference/cli",
"reference/lume/http-api": "lume/reference/http-api",
"reference/lume/limits": "lume/concepts/how-lume-works",
- "reference/lume/mcp-tools": "lume/reference/mcp-tools",
+ "reference/lume/mcp-tools": "lume/reference/http-api#mcp-tools",
"reference/lume/telemetry": "lume/concepts/how-lume-works",
"reference/sandbox-sdk": "cua-sdk/reference/sandbox",
"reference/sandbox-sdk/api/configuration": "cua-sdk/reference/python/configuration",
@@ -437,7 +437,7 @@
"cua-bench/guides/third-party-benchmarks": "cua-bench/guides/adapter-benchmarks",
"spaces/guides/cua-drive": "spaces/guides/cua-volume",
"spaces/reference/drive": "spaces/reference/volume",
- "cua-cli/reference/cli/drive": "cua-cli/reference/cli/volume",
+ "cua-cli/reference/cli/drive": "cua-cli/reference/cli/files-teleport-and-keys#cua-volume",
"cua-sdk/reference/spaces/drive": "cua-sdk/reference/spaces/volume",
"cua-sdk/reference/spaces/drive-sync": "cua-sdk/reference/spaces/volume-sync",
"cua-sdk/reference/spaces/drive-app-core": "cua-sdk/reference/spaces/volume-app-core",
@@ -482,6 +482,77 @@
"spaces/guides/site-login": "spaces/guides/keyvault#let-an-agent-sign-in-to-a-site",
"spaces/guides/troubleshoot-create": "spaces/guides/troubleshoot",
"spaces/guides/mesh": "spaces/guides/relay-security#end-to-end-encrypted-connections-beta",
- "spaces/examples/other-languages": "spaces/guides/create-a-space-with-the-sdk#examples-in-other-languages"
+ "spaces/examples/other-languages": "spaces/guides/create-a-space-with-the-sdk#examples-in-other-languages",
+ "cua-cli/reference/cli/spaces": "cua-cli/reference/cli/spaces-and-computers#cua-spaces",
+ "cua-cli/reference/cli/host": "cua-cli/reference/cli/spaces-and-computers#cua-host",
+ "cua-cli/reference/cli/devices": "cua-cli/reference/cli/spaces-and-computers#cua-devices",
+ "cua-cli/reference/cli/team": "cua-cli/reference/cli/spaces-and-computers#cua-team",
+ "cua-cli/reference/cli/usage": "cua-cli/reference/cli/spaces-and-computers#cua-usage",
+ "cua-cli/reference/cli/spacesd": "cua-cli/reference/cli/spaces-and-computers#cua-spacesd",
+ "cua-cli/reference/cli/volume": "cua-cli/reference/cli/files-teleport-and-keys#cua-volume",
+ "cua-cli/reference/cli/teleport": "cua-cli/reference/cli/files-teleport-and-keys#cua-teleport",
+ "cua-cli/reference/cli/keyvault": "cua-cli/reference/cli/files-teleport-and-keys#cua-keyvault",
+ "cua-cli/reference/cli/sandbox": "cua-cli/reference/cli/sandboxes#cua-sandbox",
+ "cua-cli/reference/cli/image": "cua-cli/reference/cli/sandboxes#cua-image",
+ "cua-cli/reference/cli/runtime": "cua-cli/reference/cli/sandboxes#cua-runtime",
+ "cua-cli/reference/cli/cache": "cua-cli/reference/cli/sandboxes#cua-cache",
+ "cua-cli/reference/cli/cloud": "cua-cli/reference/cli/sandboxes#cua-cloud",
+ "cua-cli/reference/cli/viewer": "cua-cli/reference/cli/sandboxes#cua-viewer",
+ "cua-cli/reference/cli/do": "cua-cli/reference/cli/computer-actions#cua-do",
+ "cua-cli/reference/cli/trajectory": "cua-cli/reference/cli/computer-actions#cua-trajectory",
+ "cua-cli/reference/cli/agent": "cua-cli/reference/cli/agents#cua-agent",
+ "cua-cli/reference/cli/mcp": "cua-cli/reference/cli/agents#cua-mcp",
+ "cua-cli/reference/cli/skills": "cua-cli/reference/cli/agents#cua-skills",
+ "cua-cli/reference/cli/auth": "cua-cli/reference/cli/account-and-setup#cua-auth",
+ "cua-cli/reference/cli/config": "cua-cli/reference/cli/account-and-setup#cua-config",
+ "cua-cli/reference/cli/daemon": "cua-cli/reference/cli/account-and-setup#cua-daemon",
+ "cua-cli/reference/cli/doctor": "cua-cli/reference/cli/account-and-setup#cua-doctor",
+ "cua-cli/reference/cli/telemetry": "cua-cli/reference/cli/account-and-setup#cua-telemetry",
+ "cua-cli/reference/cli/sandbox-access": "cua-cli/reference/cli/sandboxes#cua-sandbox-exec",
+ "cua-cli/reference/mcp-tools/computer": "cua-cli/reference/mcp-tools#computer-tools",
+ "cua-cli/reference/mcp-tools/images": "cua-cli/reference/mcp-tools#image-tools",
+ "cua-cli/reference/mcp-tools/sandbox": "cua-cli/reference/mcp-tools#sandbox-tools",
+ "cua-cli/reference/mcp-tools/skills": "cua-cli/reference/mcp-tools#skills-tools",
+ "cua-cli/reference/mcp-tools/spaces": "cua-cli/reference/mcp-tools#spaces-tools",
+ "cua-cli/reference/mcp-tools/teleport": "cua-cli/reference/mcp-tools#teleport-tools",
+ "cua-driver/reference/cli/mcp": "cua-driver/reference/cli/serve-and-configure#cua-driver-mcp",
+ "cua-driver/reference/cli/daemon": "cua-driver/reference/cli/serve-and-configure#cua-driver-serve",
+ "cua-driver/reference/cli/permissions": "cua-driver/reference/cli/serve-and-configure#cua-driver-permissions",
+ "cua-driver/reference/cli/config": "cua-driver/reference/cli/serve-and-configure#cua-driver-config",
+ "cua-driver/reference/cli/updates": "cua-driver/reference/cli/serve-and-configure#cua-driver-check-update",
+ "cua-driver/reference/cli/extensions": "cua-driver/reference/cli/skills-recording-and-history#cua-driver-skills",
+ "cua-driver/reference/cli/recording": "cua-driver/reference/cli/skills-recording-and-history#cua-driver-recording",
+ "cua-driver/reference/cli/history": "cua-driver/reference/cli/skills-recording-and-history#cua-driver-history",
+ "cua-driver/reference/mcp-tools/apps-and-windows": "cua-driver/reference/mcp-tools/apps-windows-and-screen#app-and-window-tools",
+ "cua-driver/reference/mcp-tools/window-state": "cua-driver/reference/mcp-tools/apps-windows-and-screen#window-state-tools",
+ "cua-driver/reference/mcp-tools/screen": "cua-driver/reference/mcp-tools/apps-windows-and-screen#screen-tools",
+ "cua-driver/reference/mcp-tools/sessions": "cua-driver/reference/mcp-tools/apps-windows-and-screen#session-tools",
+ "cua-driver/reference/mcp-tools/click": "cua-driver/reference/mcp-tools/click-and-type#click-tool",
+ "cua-driver/reference/mcp-tools/double-and-right-click": "cua-driver/reference/mcp-tools/click-and-type#double-click-and-right-click-tools",
+ "cua-driver/reference/mcp-tools/keyboard": "cua-driver/reference/mcp-tools/click-and-type#typing-tools",
+ "cua-driver/reference/mcp-tools/keys-and-shortcuts": "cua-driver/reference/mcp-tools/click-and-type#key-and-shortcut-tools",
+ "cua-driver/reference/mcp-tools/values-and-clipboard": "cua-driver/reference/mcp-tools/click-and-type#value-and-clipboard-tools",
+ "cua-driver/reference/mcp-tools/pointer": "cua-driver/reference/mcp-tools/pointer-cursor-and-browser#pointer-tools",
+ "cua-driver/reference/mcp-tools/agent-cursor": "cua-driver/reference/mcp-tools/pointer-cursor-and-browser#agent-cursor-tools",
+ "cua-driver/reference/mcp-tools/page": "cua-driver/reference/mcp-tools/pointer-cursor-and-browser#page-tools",
+ "cua-driver/reference/mcp-tools/browser-input": "cua-driver/reference/mcp-tools/pointer-cursor-and-browser#browser-input-tools",
+ "cua-driver/reference/mcp-tools/batch": "cua-driver/reference/mcp-tools/batch-recording-and-settings#batch-and-script-tools",
+ "cua-driver/reference/mcp-tools/recording": "cua-driver/reference/mcp-tools/batch-recording-and-settings#recording-tools",
+ "cua-driver/reference/mcp-tools/maintenance": "cua-driver/reference/mcp-tools/batch-recording-and-settings#configuration-and-maintenance-tools",
+ "lume/reference/cli/vms": "lume/reference/cli#vms",
+ "lume/reference/cli/images": "lume/reference/cli#images",
+ "lume/reference/cli/guest": "lume/reference/cli#guest-access",
+ "lume/reference/cli/server": "lume/reference/cli#server",
+ "lume/reference/cli/config": "lume/reference/cli#configuration",
+ "lume/reference/cli/updates": "lume/reference/cli#updates",
+ "lume/reference/mcp-tools": "lume/reference/http-api#mcp-tools",
+ "cua-bench/reference/cli/run": "cua-bench/reference/cli#cb-run",
+ "cua-bench/reference/cli/task": "cua-bench/reference/cli#cb-task",
+ "cua-bench/reference/cli/dataset": "cua-bench/reference/cli#cb-dataset",
+ "cua-bench/reference/cli/trace": "cua-bench/reference/cli#cb-trace",
+ "cua-bench/reference/cli/env": "cua-bench/reference/cli#sandboxes-and-account",
+ "cua-bench/reference/cli/agent": "cua-bench/reference/cli#cb-agent",
+ "cua-bench/reference/cli/images": "cua-bench/reference/cli#images-and-platforms",
+ "cua-bench/reference/results": "cua-bench/reference/task-definition#result-files"
}
}
diff --git a/docs/content/docs/spaces/guides/cua-volume.mdx b/docs/content/docs/spaces/guides/cua-volume.mdx
index 922a8a54ac..7b07d510ee 100644
--- a/docs/content/docs/spaces/guides/cua-volume.mdx
+++ b/docs/content/docs/spaces/guides/cua-volume.mdx
@@ -61,7 +61,7 @@ cua volume revoke 5f2c9a0b1d3e4f67
cua volume audit
```
-See the [`cua volume` reference](/cua-cli/reference/cli/volume).
+See the [`cua volume` reference](/cua-cli/reference/cli/files-teleport-and-keys#cua-volume).
## From the SDK
diff --git a/docs/content/docs/spaces/guides/keyvault.mdx b/docs/content/docs/spaces/guides/keyvault.mdx
index 47a286ae0f..09f14d3a89 100644
--- a/docs/content/docs/spaces/guides/keyvault.mdx
+++ b/docs/content/docs/spaces/guides/keyvault.mdx
@@ -277,7 +277,7 @@ cua keyvault lock
```
Scripts can pass the passphrase on stdin with `--passphrase-stdin`. See the
-[`cua keyvault` reference](/cua-cli/reference/cli/keyvault).
+[`cua keyvault` reference](/cua-cli/reference/cli/files-teleport-and-keys#cua-keyvault).
See [Teleport an app](/spaces/guides/teleport-an-app) for what moves, and the
[teleport reference](/spaces/reference/teleport) for the `teleport_app` consent
diff --git a/scripts/docs-generators/config.json b/scripts/docs-generators/config.json
index 5503e65262..4080e9659d 100644
--- a/scripts/docs-generators/config.json
+++ b/scripts/docs-generators/config.json
@@ -45,7 +45,7 @@
}
],
"enabled": true,
- "notes": "Renders reference/index.mdx, reference/cli/ (one page per command group) and reference/mcp-tools/ (one page per tool category) with the shared renderers in lib/. The CLI comes from the hand-maintained cli_docs_json() in crates/cua-driver/src/cli.rs (host independent). The MCP registry differs per OS: each host refreshes (or, with --check, verifies) its own snapshot cli-specs/cua-driver-mcp-<macos|linux|windows>.json and every page renders from the three committed snapshots, so the pages are identical on every host. Curated headers: scripts/docs-generators/headers/cua-driver/."
+ "notes": "Renders reference/index.mdx, reference/cli/ (one page per command group, several commands each) and reference/mcp-tools/ (an index and a few pages of tool categories) with the shared renderers in lib/. The CLI comes from the hand-maintained cli_docs_json() in crates/cua-driver/src/cli.rs (host independent). The MCP registry differs per OS: each host refreshes (or, with --check, verifies) its own snapshot cli-specs/cua-driver-mcp-<macos|linux|windows>.json and every page renders from the three committed snapshots, so the pages are identical on every host. Curated headers: scripts/docs-generators/headers/cua-driver/."
},
"lume": {
"name": "Lume VM Manager",
@@ -74,18 +74,13 @@
},
{
"type": "cli",
- "outputFile": "cli/index.mdx",
+ "outputFile": "cli.mdx",
"extractCommand": ".build/release/lume dump-docs --type cli"
},
{
"type": "api",
"outputFile": "http-api.mdx",
- "extractCommand": ".build/release/lume dump-docs --type api"
- },
- {
- "type": "mcp",
- "outputFile": "mcp-tools.mdx",
- "extractCommand": ".build/release/lume dump-docs --type mcp"
+ "extractCommand": ".build/release/lume dump-docs --type api (and --type mcp)"
},
{
"type": "nav",
@@ -94,7 +89,7 @@
}
],
"enabled": true,
- "notes": "Renders reference/index.mdx, reference/cli/ (one page per command group), http-api.mdx and mcp-tools.mdx from `lume dump-docs --type all` with the shared renderers in lib/."
+ "notes": "Renders reference/index.mdx, reference/cli.mdx (the whole CLI on one page, a section per command group) and http-api.mdx (the HTTP API, then the MCP tools) from `lume dump-docs --type all` with the shared renderers in lib/."
},
"cua-bench": {
"name": "Cua Bench (cb CLI, task and result schemas)",
@@ -132,7 +127,7 @@
},
{
"type": "cli",
- "outputFile": "cli/index.mdx",
+ "outputFile": "cli.mdx",
"extractCommand": null
},
{
@@ -140,11 +135,6 @@
"outputFile": "task-definition.mdx",
"extractCommand": null
},
- {
- "type": "reference",
- "outputFile": "results.mdx",
- "extractCommand": null
- },
{
"type": "nav",
"outputFile": "meta.json",
@@ -233,7 +223,7 @@
},
{
"type": "mcp",
- "outputFile": "mcp-tools/index.mdx",
+ "outputFile": "mcp-tools.mdx",
"extractCommand": "${CARGO_TARGET_DIR:-target}/debug/cua dump-docs --type mcp"
},
{
@@ -243,7 +233,7 @@
}
],
"enabled": true,
- "notes": "Renders reference/index.mdx, reference/cli/ (one page per command group) and reference/mcp-tools/ (one page per tool group) from the hidden `cua dump-docs` (the clap definition and the MCP tool list) with the shared renderers in lib/, plus scripts/docs-generators/cli-specs/cua.json, the docs CLI-shape lane's oracle. Examples come from each command's clap `after_help` (a cua-cli test parses every one)."
+ "notes": "Renders reference/index.mdx, reference/cli/ (one page per command group, several commands each) and reference/mcp-tools.mdx (every tool on one page) from the hidden `cua dump-docs` (the clap definition and the MCP tool list) with the shared renderers in lib/, plus scripts/docs-generators/cli-specs/cua.json, the docs CLI-shape lane's oracle. Examples come from each command's clap `after_help` (a cua-cli test parses every one)."
},
"cua-sdk": {
"name": "Cua SDK object reference (UniFFI)",
diff --git a/scripts/docs-generators/cua-bench.ts b/scripts/docs-generators/cua-bench.ts
index 77c2acb44f..9ed211fe46 100644
--- a/scripts/docs-generators/cua-bench.ts
+++ b/scripts/docs-generators/cua-bench.ts
@@ -9,9 +9,8 @@
* (`#:` field comments). Writes, through the shared renderers in lib/:
*
* - docs/content/docs/cua-bench/reference/index.mdx (the Reference index)
- * - docs/content/docs/cua-bench/reference/cli/ (one page per command group)
- * - docs/content/docs/cua-bench/reference/task-definition.mdx
- * - docs/content/docs/cua-bench/reference/results.mdx
+ * - docs/content/docs/cua-bench/reference/cli.mdx (every command on one page)
+ * - docs/content/docs/cua-bench/reference/task-definition.mdx (with the result files)
* - scripts/docs-generators/cli-specs/cb.json (the CLI-shape lane's oracle)
*
* Usage:
@@ -128,6 +127,7 @@ export function cliReference(cli: CLIDocumentation): CliReference {
product: 'cua-bench',
cli,
groups: CLI_GROUPS,
+ singlePage: true,
generator: REGENERATE,
source: SOURCE,
intro: readHeader('cua-bench', 'cli'),
@@ -214,9 +214,12 @@ export function taskDefinitionPage(docs: CbDocs, example: string, version: strin
body.push(`{/* Source: ${EXAMPLE_TASK} (run by libs/cua-bench/cua_bench/tests/test_cli_golden.py) */}`, '');
body.push(codeFence('python', example.trim()), '');
+ // What a run writes back: the same page, so a task's contract and its results read together.
+ body.push('## Result files', '', ...resultsBody(docs, 3));
+
return renderPage({
- title: 'Task definition',
- description: 'The task module contract: cb.Task, setup_config, the lifecycle decorators, the session API and actions.',
+ title: 'Tasks and results',
+ description: 'The task module contract (cb.Task, setup_config, the lifecycle decorators, the session API and actions) and the result.json and summary.json a run writes.',
generator: REGENERATE,
source: SOURCE,
version,
@@ -226,7 +229,9 @@ export function taskDefinitionPage(docs: CbDocs, example: string, version: strin
// ---------------------------------------------------------------- results
-export function resultsPage(docs: CbDocs, version: string): string {
+/** The result files, `level` being the heading level of `result.json` and `summary.json`. */
+export function resultsBody(docs: CbDocs, level = 2): string[] {
+ const h = (n: number) => '#'.repeat(level + n);
const r = docs.results;
const jobDocs = new Map(r.job_result.fields.map((f) => [f.name, f.description]));
const summaryDocs = new Map(r.summary.fields.map((f) => [f.name, f.description]));
@@ -250,27 +255,32 @@ export function resultsPage(docs: CbDocs, version: string): string {
const body: string[] = [];
const header = readHeader('cua-bench', 'results');
if (header) body.push(header, '');
- body.push('## `result.json`', '', escapeMdxText(sentence(rst(r.job_result.doc))), '');
+ body.push(`${h(0)} \`result.json\``, '', escapeMdxText(sentence(rst(r.job_result.doc))), '');
body.push(...fieldsTable(resultFields, { fallback: jobDocs }));
body.push(
`Phase spans (\`environment_setup\`, \`agent_execution\`, \`verifier\`) are ${r.span.fields.map((f) => codeCell(f.name)).join(' and ')} timestamps (ISO 8601, UTC).`,
''
);
- body.push('## `summary.json`', '', escapeMdxText(sentence(rst(r.summary.doc))), '');
+ body.push(`${h(0)} \`summary.json\``, '', escapeMdxText(sentence(rst(r.summary.doc))), '');
body.push(...fieldsTable(r.summary.fields));
- body.push('### `results[]`', '', escapeMdxText(sentence(rst(r.summary_result.doc))), '');
+ body.push(`${h(1)} \`results[]\``, '', escapeMdxText(sentence(rst(r.summary_result.doc))), '');
body.push(...fieldsTable(r.summary_result.fields, { prefix: 'results[].', fallback: jobDocs }));
- body.push('### `stats`', '');
+ body.push(`${h(1)} \`stats\``, '');
body.push(...fieldsTable(r.summary_stats.fields, { prefix: 'stats.' }));
- body.push('### `targets[]`', '', escapeMdxText(sentence(rst(r.summary_target.doc))), '');
+ body.push(`${h(1)} \`targets[]\``, '', escapeMdxText(sentence(rst(r.summary_target.doc))), '');
body.push(...fieldsTable(r.summary_target.fields, { prefix: 'targets[].', fallback: jobDocs }));
+ return body;
+}
+
+/** The result files on a page of their own. */
+export function resultsPage(docs: CbDocs, version: string): string {
return renderPage({
title: 'Results',
description: 'The result.json and summary.json a run writes: every key, its type and meaning.',
generator: REGENERATE,
source: SOURCE,
version,
- body: body.join('\n'),
+ body: resultsBody(docs).join('\n'),
});
}
@@ -281,7 +291,6 @@ export function renderAll(docs: CbDocs, example: string): Map<string, string> {
const version = docs.cli.version;
const rel = new Map<string, string>(renderCliReference(cli));
rel.set('task-definition.mdx', taskDefinitionPage(docs, example, version));
- rel.set('results.mdx', resultsPage(docs, version));
rel.set(
'index.mdx',
renderReferenceIndex({
@@ -297,13 +306,13 @@ export function renderAll(docs: CbDocs, example: string): Map<string, string> {
column: 'Schema',
rows: [
{ name: 'Task definition', href: '/cua-bench/reference/task-definition', description: 'cb.Task, setup_config, the lifecycle decorators, the session API and actions.' },
- { name: 'Results', href: '/cua-bench/reference/results', description: 'Every key of result.json and summary.json.' },
+ { name: 'Results', href: '/cua-bench/reference/task-definition#result-files', description: 'Every key of result.json and summary.json.' },
],
},
],
})
);
- rel.set('meta.json', metaJson('Reference', ['index', 'cli', 'task-definition', 'results']));
+ rel.set('meta.json', metaJson('Reference', ['index', 'cli', 'task-definition']));
const files = new Map<string, string>();
for (const [p, content] of rel) files.set(path.join(OUT_DIR, p), content);
files.set(CB_CLI_SPEC, stableJson(docs.cli));
diff --git a/scripts/docs-generators/cua-cli.test.ts b/scripts/docs-generators/cua-cli.test.ts
index 7f18c6f2f4..201f187f60 100644
--- a/scripts/docs-generators/cua-cli.test.ts
+++ b/scripts/docs-generators/cua-cli.test.ts
@@ -40,8 +40,10 @@ const mcp: McpDocumentation = {
test('every cua command is on exactly one group page', () => {
// Throws when a visible top-level command is ungrouped or grouped twice.
const files = renderCliReference(cliReference(spec));
- assert.ok(files.has('cli/sandbox.mdx'));
- assert.ok(files.get('cli/sandbox.mdx')!.includes('## `cua sandbox create`'));
+ assert.ok(files.has('cli/sandboxes.mdx'));
+ // Several commands share a page: each is a section, its subcommands one level below.
+ assert.ok(files.get('cli/sandboxes.mdx')!.includes('## `cua sandbox`'));
+ assert.ok(files.get('cli/sandboxes.mdx')!.includes('### `cua sandbox create`'));
assert.ok(files.get('cli/index.mdx')!.includes('## Exit codes'));
});
@@ -68,18 +70,16 @@ test('Spaces tools link to their one entry in the Spaces reference instead of re
]);
const files = renderAll({ cli: spec, mcp }, spaces);
const page = (rel: string) => [...files].find(([p]) => p.endsWith(join('reference', ...rel.split('/'))))?.[1];
- const spacesPage = page('mcp-tools/spaces.mdx')!;
- assert.ok(spacesPage.includes('| <span id="add_space"></span>[`add_space`](/spaces/reference/lifecycle#add_space) | Register a Space. |'));
- assert.ok(spacesPage.includes('[`space_bash`](/spaces/reference/commands-and-files#space_bash)'));
- assert.ok(!spacesPage.includes('| Parameter |'), 'no repeated parameter tables');
- assert.ok(spacesPage.includes('## Space lifecycle\n\nFull entries: [Space lifecycle](/spaces/reference/lifecycle).'));
- assert.equal(page('mcp-tools/space-io.mdx'), undefined);
- assert.equal(page('mcp-tools/space-agents.mdx'), undefined);
- const index = page('mcp-tools/index.mdx')!;
- assert.ok(index.includes('[`agent_start`](/spaces/reference/agents#agent_start)'));
- assert.ok(index.includes('## Permissions') && index.includes('`sandbox:all`'));
- const sandbox = page('mcp-tools/sandbox.mdx')!;
- assert.ok(sandbox.includes('## `sandbox_list`'));
+ // Every tool is on one page; the Spaces tools are tables linking to their entries.
+ const tools = page('mcp-tools.mdx')!;
+ assert.ok(tools.includes('| <span id="add_space"></span>[`add_space`](/spaces/reference/lifecycle#add_space) | Register a Space. |'));
+ assert.ok(tools.includes('[`space_bash`](/spaces/reference/commands-and-files#space_bash)'));
+ assert.ok(tools.includes('[`agent_start`](/spaces/reference/agents#agent_start)'));
+ assert.ok(tools.includes('### Space lifecycle\n\nFull entries: [Space lifecycle](/spaces/reference/lifecycle).'));
+ assert.ok(!tools.includes('### `add_space`'), 'no repeated Spaces entries');
+ assert.ok(tools.includes('## Permissions') && tools.includes('`sandbox:all`'));
+ assert.ok(tools.includes('### `sandbox_list`'));
+ assert.equal(page('mcp-tools/index.mdx'), undefined);
assert.throws(() => renderAll({ cli: spec, mcp }, { anchors: new Map(), sections: new Map() }), /Spaces contract manifest lacks/);
});
diff --git a/scripts/docs-generators/cua-cli.ts b/scripts/docs-generators/cua-cli.ts
index 4188f72ff2..5ade3f7f1a 100644
--- a/scripts/docs-generators/cua-cli.ts
+++ b/scripts/docs-generators/cua-cli.ts
@@ -9,7 +9,7 @@
*
* - docs/content/docs/cua-cli/reference/index.mdx (the Reference index)
* - docs/content/docs/cua-cli/reference/cli/ (one page per command group)
- * - docs/content/docs/cua-cli/reference/mcp-tools/ (one page per tool group)
+ * - docs/content/docs/cua-cli/reference/mcp-tools.mdx (every tool on one page)
* - scripts/docs-generators/cli-specs/cua.json (the CLI-shape lane's oracle)
*
* Usage:
@@ -90,47 +90,46 @@ export interface CuaDumpDocs {
// ---------------------------------------------------------------- CLI
-/** Command groups: one page each, in the order readers meet them. */
+/** Command groups: one page each (several commands per page), in the order readers meet them. */
export const CLI_GROUPS: CliGroup[] = [
- { slug: 'auth', title: 'cua auth', summary: 'Sign in and out, see who is signed in, and store sandbox provider keys', commands: ['auth'] },
{
- slug: 'sandbox',
- title: 'cua sandbox',
- summary: 'Create, list, connect to, suspend and delete sandboxes, local or on your own machines',
- commands: ['sandbox'],
- subcommands: ['create', 'launch', 'connect', 'ls', 'info', 'suspend', 'resume', 'restart', 'rm'],
+ slug: 'spaces-and-computers',
+ title: 'Spaces, computers and teams',
+ summary:
+ 'Your Spaces and machines, unattended access on this machine, devices, teams, your remote use this month, and a cua-spacesd by URL',
+ commands: ['spaces', 'host', 'devices', 'team', 'usage', 'spacesd'],
},
{
- slug: 'sandbox-access',
- title: 'Sandbox access',
- summary: 'Run commands, copy files, forward ports, take screenshots, reach the MCP and view a sandbox (`cua sandbox exec`, `cp`, `view`, ...)',
- commands: ['sandbox'],
- subcommands: ['exec', 'shell', 'cp', 'overlay', 'logs', 'port-forward', 'url', 'screenshot', 'mcp', 'view'],
+ slug: 'files-teleport-and-keys',
+ title: 'Files, teleport and keys',
+ summary: 'Cua Volume files and sharing, moving an app session into a sandbox, and the Cua Keyvault',
+ commands: ['volume', 'teleport', 'keyvault'],
+ },
+ {
+ slug: 'sandboxes',
+ title: 'Sandboxes and images',
+ summary:
+ 'Create, reach and delete sandboxes; pull, build and push images; local runtimes, disk cleanup, your own cloud account and the sandbox viewer',
+ commands: ['sandbox', 'image', 'images', 'runtime', 'cache', 'cloud', 'viewer'],
+ },
+ {
+ slug: 'computer-actions',
+ title: 'Computer actions',
+ summary: 'One-shot computer actions (screenshot, click, type, windows) against a selected target, and their recorded trajectories',
+ commands: ['do', 'do-host-consent', 'trajectory'],
+ },
+ {
+ slug: 'agents',
+ title: 'Agents, MCP and skills',
+ summary: 'Run coding agents in a sandbox, set up your AI agents, the stdio MCP server, and recorded skills',
+ commands: ['agent', 'agents', 'mcp', 'skills'],
+ },
+ {
+ slug: 'account-and-setup',
+ title: 'Account and setup',
+ summary: 'Sign in and out, user defaults, the cua daemon, health checks and usage telemetry',
+ commands: ['auth', 'config', 'daemon', 'doctor', 'telemetry'],
},
- { slug: 'config', title: 'cua config', summary: 'User defaults: where sandboxes run (`default.on`), the default kind and runtime', commands: ['config'] },
- { slug: 'viewer', title: 'cua viewer', summary: 'One local browser page that lists every sandbox and opens its viewer', commands: ['viewer'] },
- { slug: 'do', title: 'cua do', summary: 'One-shot computer actions (screenshot, click, type, windows) against a selected target', commands: ['do', 'do-host-consent'] },
- { slug: 'image', title: 'cua image', summary: 'Pull, build and push OCI images; list the image catalog', commands: ['image', 'images'] },
- { slug: 'mcp', title: 'cua mcp', summary: 'The stdio MCP server for AI assistants', commands: ['mcp'] },
- { slug: 'agent', title: 'cua agent', summary: 'Run coding agents (Claude Code, Codex, Gemini CLI, ...) inside a sandbox and follow, continue or stop them', commands: ['agent'] },
- { slug: 'agents', title: 'cua agents', summary: 'Install cua skills and the cua MCP server into AI coding agents', commands: ['agents'] },
- { slug: 'skills', title: 'cua skills', summary: 'Record, list and replay demonstrations (skills)', commands: ['skills'] },
- { slug: 'trajectory', title: 'cua trajectory', summary: 'Recorded `cua do` trajectories', commands: ['trajectory'] },
- { slug: 'spaces', title: 'cua spaces', summary: 'Registered Spaces and your machines on the relay', commands: ['spaces'] },
- { slug: 'cloud', title: 'cua cloud', summary: 'Your own AWS, Google Cloud or Modal account as a place for sandboxes and Spaces: connect, test, status, sweep', commands: ['cloud'] },
- { slug: 'host', title: 'cua host', summary: 'Set this machine up for unattended access', commands: ['host'] },
- { slug: 'devices', title: 'cua devices', summary: 'Enroll this device on the relay, approve, rename and revoke devices, and read the access log', commands: ['devices'] },
- { slug: 'team', title: 'cua team', summary: 'Teams (organizations), their members, machines and device approvals', commands: ['team'] },
- { slug: 'usage', title: 'cua usage', summary: 'Your hosted relay allowance this month: live sessions and relay hours', commands: ['usage'] },
- { slug: 'teleport', title: 'cua teleport', summary: 'Move a desktop app session into a sandbox', commands: ['teleport'] },
- { slug: 'volume', title: 'cua volume', summary: 'Cua Volume: files, versions, grants, access requests and audit of the volume every Space and agent shares', commands: ['volume'] },
- { slug: 'keyvault', title: 'cua keyvault', summary: 'Set up, unlock and lock the Cua Keyvault, with the OS key store or a passphrase', commands: ['keyvault'] },
- { slug: 'spacesd', title: 'cua spacesd', summary: 'Talk to a cua-spacesd directly by URL', commands: ['spacesd'] },
- { slug: 'daemon', title: 'cua daemon', summary: 'Start, stop and inspect the cua daemon', commands: ['daemon'] },
- { slug: 'cache', title: 'cua cache', summary: 'See and reclaim the disk used by images, sandboxes, builds and logs', commands: ['cache'] },
- { slug: 'runtime', title: 'cua runtime', summary: 'Inspect and provision local runtimes', commands: ['runtime'] },
- { slug: 'doctor', title: 'cua doctor', summary: 'Check the host, an image and a sandbox guest, or eval parity between image variants', commands: ['doctor'] },
- { slug: 'telemetry', title: 'cua telemetry', summary: 'Anonymous usage telemetry (status, off, show-last)', commands: ['telemetry'] },
];
export function cliReference(cli: CLIDocumentation): CliReference {
@@ -254,6 +253,7 @@ export function mcpReference(mcp: McpDocumentation, spaces: SpacesLinks): McpRef
tools,
header,
footer: permissionsSection(mcp),
+ singlePage: true,
};
}
diff --git a/scripts/docs-generators/cua-driver-platform.test.ts b/scripts/docs-generators/cua-driver-platform.test.ts
index 39f570948a..cf33f9a5b7 100644
--- a/scripts/docs-generators/cua-driver-platform.test.ts
+++ b/scripts/docs-generators/cua-driver-platform.test.ts
@@ -94,7 +94,7 @@ test('each host refreshes only its own registry snapshot; pages merge all three'
const files = referenceFiles(docs('Fresh Linux tree.'), linux, out, specs);
const snapshots = [...files.keys()].filter((f) => f.startsWith(specs)).map((f) => basename(f)).sort();
assert.deepEqual(snapshots, ['cua-driver-mcp-linux.json', 'cua-driver.json']);
- const page = files.get(join(out, 'mcp-tools', 'window-state.mdx'))!;
+ const page = files.get(join(out, 'mcp-tools', 'apps-windows-and-screen.mdx'))!;
assert.ok(page.includes("<Tabs items={['macOS', 'Linux', 'Windows']}"));
assert.ok(page.includes('Fresh Linux tree.') && page.includes('macOS tree.') && page.includes('Windows tree.'));
// The shared parameter is listed once, outside the tabs.
diff --git a/scripts/docs-generators/cua-driver.ts b/scripts/docs-generators/cua-driver.ts
index afa29f41d6..cdd4ee0121 100644
--- a/scripts/docs-generators/cua-driver.ts
+++ b/scripts/docs-generators/cua-driver.ts
@@ -8,9 +8,9 @@
*
* - docs/content/docs/cua-driver/reference/index.mdx (the Reference index)
* - docs/content/docs/cua-driver/reference/cli/ (one page per command group)
- * - docs/content/docs/cua-driver/reference/mcp-tools/ (one page per tool
- * category, every platform on one page: tabs where macOS, Linux and
- * Windows differ)
+ * - docs/content/docs/cua-driver/reference/mcp-tools/ (an index and a few
+ * pages of tool categories, MCP_PAGES; every platform on one page: tabs
+ * where macOS, Linux and Windows differ)
* - scripts/docs-generators/cli-specs/cua-driver.json (the CLI, host
* independent: the CLI-shape lane's oracle)
* - scripts/docs-generators/cli-specs/cua-driver-mcp-<platform>.json (the
@@ -48,6 +48,7 @@ import { readHeader } from './lib/headers';
import {
type JsonSchema,
type McpCategory,
+ type McpPage,
type McpReference,
type McpToolEntry,
mcpIndexRows,
@@ -186,52 +187,23 @@ export function getLatestReleasedVersion(git: GitRunner = runGit): string {
export const CLI_GROUPS: CliGroup[] = [
{
- slug: 'mcp',
- title: 'Tools and MCP',
- summary: 'Serve MCP, print client config, and list, describe or call tools from the shell',
- commands: ['mcp', 'mcp-config', 'list-tools', 'describe', 'call', 'manifest', 'dump-docs'],
+ slug: 'serve-and-configure',
+ title: 'Serve, configure and update',
+ summary:
+ 'Serve MCP and call tools from the shell; run the daemon; grant permissions and diagnose; configure the driver, telemetry and cursor; update and pick a release channel',
+ commands: [
+ 'mcp', 'mcp-config', 'list-tools', 'describe', 'call', 'manifest', 'dump-docs',
+ 'serve', 'stop', 'status', 'sessions', 'revoke', 'autostart',
+ 'permissions', 'doctor', 'diagnose',
+ 'config', 'telemetry', 'cursor-theme', 'cursor',
+ 'check-update', 'update', 'channel',
+ ],
},
{
- slug: 'daemon',
- title: 'Daemon',
- summary: 'Run, stop and inspect the daemon, its sessions and autostart',
- commands: ['serve', 'stop', 'status', 'sessions', 'revoke', 'autostart'],
- },
- {
- slug: 'permissions',
- title: 'Permissions and diagnostics',
- summary: 'macOS permission grants, diagnostic probes and install reports',
- commands: ['permissions', 'doctor', 'diagnose'],
- },
- {
- slug: 'recording',
- title: 'Trajectory recording',
- summary: 'Record, inspect and render action trajectories',
- commands: ['recording'],
- },
- {
- slug: 'history',
- title: 'Computer History',
- summary: 'The encrypted, metadata-only Computer History preview',
- commands: ['history'],
- },
- {
- slug: 'config',
- title: 'Configuration',
- summary: 'Driver configuration, telemetry, cursor themes and cursor motion',
- commands: ['config', 'telemetry', 'cursor-theme', 'cursor'],
- },
- {
- slug: 'extensions',
- title: 'Skills and extensions',
- summary: 'The agent skill pack, signed extensions and the perception parser',
- commands: ['skills', 'extension', 'perception'],
- },
- {
- slug: 'updates',
- title: 'Updates',
- summary: 'Check for and apply updates, and choose the release channel',
- commands: ['check-update', 'update', 'channel'],
+ slug: 'skills-recording-and-history',
+ title: 'Skills, recording and history',
+ summary: 'The agent skill pack, signed extensions and the perception parser; trajectory recording; the Computer History preview',
+ commands: ['skills', 'extension', 'perception', 'recording', 'history'],
},
];
@@ -353,6 +325,34 @@ export const MCP_CATEGORIES: Array<McpCategory & { tools: string[] }> = [
},
];
+/** The MCP tool pages: several categories each. */
+export const MCP_PAGES: McpPage[] = [
+ {
+ slug: 'apps-windows-and-screen',
+ title: 'Apps, windows and screen',
+ summary: 'Apps and windows, window state and screenshots, the screen, and lifecycle sessions',
+ categories: ['apps-and-windows', 'window-state', 'screen', 'sessions'],
+ },
+ {
+ slug: 'click-and-type',
+ title: 'Click and type',
+ summary: 'Clicks, typing, keys and shortcuts, element values and the clipboard',
+ categories: ['click', 'double-and-right-click', 'keyboard', 'keys-and-shortcuts', 'values-and-clipboard'],
+ },
+ {
+ slug: 'pointer-cursor-and-browser',
+ title: 'Pointer, cursor and browser',
+ summary: 'Drag, scroll and move the pointer; the agent cursor; web pages and browser input',
+ categories: ['pointer', 'agent-cursor', 'page', 'browser-input'],
+ },
+ {
+ slug: 'batch-recording-and-settings',
+ title: 'Batch, recording and settings',
+ summary: 'Run several actions in one call, record and replay trajectories, and configuration and maintenance',
+ categories: ['batch', 'recording', 'maintenance'],
+ },
+];
+
/** The registry fields the pages use (the per-host version is left out: it drifts every release). */
export function mcpSnapshot(mcp: MCPDocumentation): McpSnapshot {
return {
@@ -414,6 +414,7 @@ export function mcpReference(snapshots: Map<ReferencePlatform, McpSnapshot>, ver
tools: mergeTools(snapshots),
header: readHeader('cua-driver', 'mcp-tools'),
platforms: referencePlatforms.map((p) => p.name),
+ pages: MCP_PAGES,
};
}
diff --git a/scripts/docs-generators/lib/cli-mdx.ts b/scripts/docs-generators/lib/cli-mdx.ts
index 94980c4266..71d51d953f 100644
--- a/scripts/docs-generators/lib/cli-mdx.ts
+++ b/scripts/docs-generators/lib/cli-mdx.ts
@@ -8,7 +8,8 @@
* exit codes) and an index of every command, grouped. Old per-command
* anchors of the single-page reference resolve here (hidden anchors that
* link on to the command's section).
- * - `reference/cli/<group>.mdx`: one page per command group. Each command has
+ * - `reference/cli/<group>.mdx`: one page per command group (a group may hold
+ * several top-level commands, each a section). Each command has
* a heading anchored by its full path (`#cua-sandbox-create`), a synopsis,
* an arguments table and a flags table (`Flag | Short | Type | Default |
* Env var | Description`, one anchor per flag: `#cua-sandbox-create--name`),
@@ -16,6 +17,9 @@
* `test="cli-shape"`, so the docs CLI-shape lane parses each one against the
* same JSON. Exit codes close the page.
*
+ * Small CLIs (`singlePage`) render everything to `reference/cli.mdx` instead:
+ * a table of every command, then one section per group.
+ *
* cua-driver and lume emit the base fields; `cua dump-docs` (clap) adds usage,
* aliases, hidden commands, global options, env vars and repeatability; `cb`
* (argparse) adds usage and choices. The docs CLI-shape lane reads the same
@@ -159,6 +163,11 @@ export interface CliReference {
intro?: string;
/** Curated Markdown per group slug, shown under the page's command table. */
headers?: Record<string, string>;
+ /**
+ * One page for the whole CLI (`reference/cli.mdx`) instead of a folder: the
+ * groups become sections of that page. For small CLIs.
+ */
+ singlePage?: boolean;
}
/** clap strips the final period from doc comments; put it back for prose. */
@@ -545,6 +554,22 @@ function cliUrl(ref: CliReference, page?: string): string {
return `/${ref.product}/reference/cli${page ? `/${page}` : ''}`;
}
+/**
+ * On a single-page CLI reference, a group titled by its command (`cb task`)
+ * is that command's section (with any companion commands beside it); any
+ * other group gets a section heading of its own.
+ */
+function isCommandSection(group: CliGroup, root: string): boolean {
+ return !group.subcommands && isCommandTitle(group, root);
+}
+
+/** Where a group's reference starts: its page, or its section of the single page. */
+function groupHref(ref: CliReference, group: CliGroup): string {
+ if (!ref.singlePage) return cliUrl(ref, group.slug);
+ const root = ref.cli.name;
+ return `${cliUrl(ref)}#${isCommandSection(group, root) ? commandAnchor([root, group.commands[0]]) : slug(group.title)}`;
+}
+
function commandRows(
entries: Array<{ cmd: CommandDoc; path: string[] }>,
href: (anchor: string) => string,
@@ -674,7 +699,18 @@ function renderGroup(ref: CliReference, group: CliGroup, commands: PageCommand[]
body.push(`<span id="${commandAnchor([...parents, cmd.name])}"></span>`, '');
body.push(...renderCommand(cmd, parents, 0));
}
- else for (const { cmd, parents } of commands) body.push(...renderCommand(cmd, parents, 2));
+ else {
+ for (const { cmd, parents } of commands) {
+ // A command's curated notes (`headers/<product>/cli-<command>.md`) sit
+ // under its heading when the page holds several commands.
+ const [heading, blank, ...rest] = renderCommand(cmd, parents, 2);
+ if (heading === undefined) continue;
+ body.push(heading, blank);
+ const own = cmd.name !== group.slug && parents.length === 1 ? readHeader(ref.product, `cli-${cmd.name}`) : undefined;
+ if (own) body.push(own.trim(), '');
+ body.push(...rest);
+ }
+ }
if (cli.exit_codes?.length) {
body.push('## Exit codes', '');
body.push(...exitCodesTable(cli.exit_codes));
@@ -689,6 +725,60 @@ function renderGroup(ref: CliReference, group: CliGroup, commands: PageCommand[]
});
}
+/**
+ * The whole CLI on one page: synopsis, a table of every command, one section
+ * per group (a one-command group is that command's own section), global
+ * options and exit codes.
+ */
+function renderSinglePage(ref: CliReference, pages: Map<string, PageCommand[]>): string {
+ const { cli } = ref;
+ const root = cli.name;
+ const body: string[] = [];
+ const intro = ref.intro ?? readHeader(ref.product, 'cli');
+ if (intro) body.push(intro.trim(), '');
+ body.push(codeFence('text', cli.usage ?? `${root} [OPTIONS] <COMMAND>`, 'output'), '');
+ body.push(`Run \`${root} <command> --help\` for the build you have.`, '');
+ body.push('## Commands', '');
+ const all = ref.groups.flatMap((g) => (pages.get(g.slug) ?? []).flatMap((c) => flatten(c.cmd, c.parents)));
+ body.push(...commandRows(all, (a) => `#${a}`));
+ for (const group of ref.groups) {
+ const commands = pages.get(group.slug) ?? [];
+ const header = ref.headers?.[group.slug] ?? readHeader(ref.product, `cli-${group.slug}`);
+ if (isCommandSection(group, root)) {
+ commands.forEach(({ cmd, parents }, i) => {
+ const [heading, blank, ...rest] = renderCommand(cmd, parents, 2);
+ if (heading === undefined) return;
+ body.push(heading, blank);
+ if (header && i === 0) body.push(header.trim(), '');
+ body.push(...rest);
+ });
+ continue;
+ }
+ body.push(`## ${group.title}`, '', escapeMdxText(sentence(group.summary)), '');
+ if (header) body.push(header.trim(), '');
+ for (const { cmd, parents } of commands) body.push(...renderCommand(cmd, parents, 3));
+ }
+ body.push('## Global options', '');
+ const globals = (cli.global_options ?? []).filter((o) => !o.hidden);
+ if (globals.length) {
+ body.push('Accepted by every command, before or after the subcommand.', '');
+ body.push(...flagsTable(globals));
+ }
+ body.push(`\`--help\` prints help for any command; \`--version\` prints the version.`, '');
+ if (cli.exit_codes?.length) {
+ body.push('## Exit codes', '');
+ body.push(...exitCodesTable(cli.exit_codes));
+ }
+ return renderPage({
+ title: `${root} CLI`,
+ description: sentence(cli.abstract),
+ generator: ref.generator,
+ source: ref.source,
+ version: cli.version,
+ body: body.join('\n'),
+ });
+}
+
/**
* Renders `reference/cli/`: index, one page per group and `meta.json`, keyed
* by path relative to the product's `reference/` folder.
@@ -696,6 +786,10 @@ function renderGroup(ref: CliReference, group: CliGroup, commands: PageCommand[]
export function renderCliReference(ref: CliReference): Map<string, string> {
const pages = groupCommands(ref);
const out = new Map<string, string>();
+ if (ref.singlePage) {
+ out.set('cli.mdx', renderSinglePage(ref, pages));
+ return out;
+ }
out.set('cli/index.mdx', renderIndex(ref, pages));
for (const group of ref.groups) {
out.set(`cli/${group.slug}.mdx`, renderGroup(ref, group, pages.get(group.slug)!));
@@ -710,7 +804,7 @@ export function cliIndexRows(ref: CliReference): IndexRow[] {
{ name: `\`${ref.cli.name}\``, href: cliUrl(ref), description: 'Synopsis, global options, exit codes and every command.' },
...ref.groups.map((g) => ({
name: groupTitle(g, ref.cli.name),
- href: cliUrl(ref, g.slug),
+ href: groupHref(ref, g),
description: sentence(g.summary),
})),
];
diff --git a/scripts/docs-generators/lib/mcp-mdx.ts b/scripts/docs-generators/lib/mcp-mdx.ts
index 33a534cfad..31eba3320d 100644
--- a/scripts/docs-generators/lib/mcp-mdx.ts
+++ b/scripts/docs-generators/lib/mcp-mdx.ts
@@ -106,10 +106,24 @@ export interface McpReference {
footer?: string;
/** One page for every tool instead of a folder of category pages. */
singlePage?: boolean;
+ /**
+ * Folder mode: group categories onto fewer pages (each category a section
+ * of its page). Without it, every category gets its own page.
+ */
+ pages?: McpPage[];
/** Every platform the server runs on, in tab order (for per-platform variants). */
platforms?: string[];
}
+/** A page of the folder-mode reference holding several categories. */
+export interface McpPage {
+ slug: string;
+ title: string;
+ summary: string;
+ /** Category slugs on this page, in order. */
+ categories: string[];
+}
+
// ---------------------------------------------------------------- schema
/** A reader-facing type label for a JSON Schema. */
@@ -430,62 +444,113 @@ export function renderMcpReference(ref: McpReference): Map<string, string> {
const all = ref.platforms ?? [];
if (ref.singlePage) {
- const body: string[] = [];
- if (ref.header) body.push(ref.header.trim(), '');
- for (const cat of ref.categories) {
- const tools = groups.get(cat.slug) ?? [];
- if (!tools.length) continue;
- body.push(`## ${cat.title}`, '');
- if (cat.intro) body.push(cat.intro.trim(), '');
- for (const tool of tools) body.push(...toolSection(tool, 3, all));
- }
- if (ref.footer) body.push(ref.footer.trim(), '');
- out.set('mcp-tools.mdx', page('MCP tools', ref.description, body));
+ out.set('mcp-tools.mdx', page('MCP tools', ref.description, mcpBody(ref, 2)));
return out;
}
+ const pages = mcpPages(ref);
+ const pageOf = new Map(pages.flatMap((p) => p.categories.map((c) => [c, p.slug] as const)));
const index: string[] = [];
if (ref.header) index.push(ref.header.trim(), '');
for (const cat of ref.categories) {
const tools = groups.get(cat.slug) ?? [];
if (!tools.length) continue;
- index.push(`## ${cat.title}`, '', `${escapeMdxText(sentence(cat.summary))} [Reference](${mcpUrl(ref, cat.slug)}).`, '');
- index.push(...indexTable(tools, cat.canonical ?? ((t) => `${mcpUrl(ref, cat.slug)}#${t}`), withPlatforms));
+ const at = pageOf.get(cat.slug)!;
+ const catHref = ref.pages ? `${mcpUrl(ref, at)}#${slug(cat.title)}` : mcpUrl(ref, at);
+ index.push(`## ${cat.title}`, '', `${escapeMdxText(sentence(cat.summary))} [Reference](${catHref}).`, '');
+ index.push(...indexTable(tools, cat.canonical ?? ((t) => `${mcpUrl(ref, at)}#${t}`), withPlatforms));
}
if (ref.footer) index.push(ref.footer.trim(), '');
out.set('mcp-tools/index.mdx', page('All tools', ref.description, index));
const slugs: string[] = [];
+ for (const p of pages) {
+ const cats = p.categories
+ .map((c) => ref.categories.find((x) => x.slug === c)!)
+ .filter((cat) => (groups.get(cat.slug) ?? []).length);
+ if (!cats.length) continue;
+ slugs.push(p.slug);
+ const body: string[] = [];
+ // One category per page: its tools are the page's sections. Several: each
+ // category is a section and its tools sit one level below.
+ const level = ref.pages ? 3 : 2;
+ if (ref.pages) {
+ const listed = cats.flatMap((cat) => (cat.canonical ? [] : groups.get(cat.slug)!));
+ if (listed.length > 1) body.push(...indexTable(listed, (t) => `#${t}`, withPlatforms).map((l) => l.replace(/<span id="[^"]*"><\/span>/, '')));
+ }
+ body.push(`Served by \`${ref.server}\`; see [MCP tools](${mcpUrl(ref)}) for every tool.`, '');
+ for (const cat of cats) {
+ const tools = groups.get(cat.slug)!;
+ if (ref.pages) body.push(`## ${cat.title}`, '', escapeMdxText(sentence(cat.summary)), '');
+ if (cat.canonical) {
+ body.push(...canonicalTables(cat, tools, withPlatforms, ref.pages ? 3 : 2));
+ continue;
+ }
+ if (!ref.pages && tools.length > 1) body.push(...indexTable(tools, (t) => `#${t}`, withPlatforms).map((l) => l.replace(/<span id="[^"]*"><\/span>/, '')));
+ if (cat.intro) body.push(cat.intro.trim(), '');
+ for (const tool of tools) body.push(...toolSection(tool, level, all));
+ }
+ out.set(`mcp-tools/${p.slug}.mdx`, page(p.title, sentence(p.summary), body));
+ }
+ out.set('mcp-tools/meta.json', metaJson('MCP tools', ['index', ...slugs]));
+ return out;
+}
+
+/** The folder-mode pages: the configured groups, or one page per category. */
+function mcpPages(ref: McpReference): McpPage[] {
+ if (!ref.pages) return ref.categories.map((c) => ({ slug: c.slug, title: c.title, summary: c.summary, categories: [c.slug] }));
+ const placed = ref.pages.flatMap((p) => p.categories);
+ const known = ref.categories.map((c) => c.slug);
+ const left = known.filter((c) => !placed.includes(c));
+ const stray = placed.filter((c, i) => !known.includes(c) || placed.indexOf(c) !== i);
+ if (left.length || stray.length) {
+ throw new Error(`MCP pages of ${ref.server} do not cover the categories once. Unplaced: ${left.join(', ') || 'none'}; unknown or repeated: ${stray.join(', ') || 'none'}`);
+ }
+ return ref.pages;
+}
+
+/** A canonical category: tables linking to where each tool is documented, tool anchors kept. */
+function canonicalTables(cat: McpCategory, tools: McpToolEntry[], withPlatforms: boolean, level: number): string[] {
+ const body: string[] = [];
+ if (cat.intro) body.push(cat.intro.trim(), '');
+ const sections = new Map<string, { href: string; tools: McpToolEntry[] }>();
+ for (const tool of tools) {
+ const sec = cat.canonicalSection?.(tool.name) ?? { title: '', href: '' };
+ const entry = sections.get(sec.title) ?? { href: sec.href, tools: [] };
+ entry.tools.push(tool);
+ sections.set(sec.title, entry);
+ }
+ for (const [title, sec] of sections) {
+ if (title) body.push(`${'#'.repeat(level)} ${title}`, '', `Full entries: [${title}](${sec.href}).`, '');
+ body.push(...indexTable(sec.tools, cat.canonical!, withPlatforms));
+ }
+ return body;
+}
+
+/**
+ * The whole tool reference as one body: header, one section per category
+ * (canonical categories as linking tables), tools a level below, footer.
+ * `level` is the category heading level.
+ */
+export function mcpBody(ref: McpReference, level: number): string[] {
+ const groups = byCategory(ref);
+ const withPlatforms = ref.tools.some((t) => t.platforms?.length);
+ const body: string[] = [];
+ if (ref.header) body.push(ref.header.trim(), '');
for (const cat of ref.categories) {
const tools = groups.get(cat.slug) ?? [];
if (!tools.length) continue;
- slugs.push(cat.slug);
- const body: string[] = [];
+ body.push(`${'#'.repeat(level)} ${cat.title}`, '');
if (cat.canonical) {
- if (cat.intro) body.push(cat.intro.trim(), '');
- const sections = new Map<string, { href: string; tools: McpToolEntry[] }>();
- for (const tool of tools) {
- const sec = cat.canonicalSection?.(tool.name) ?? { title: '', href: '' };
- const entry = sections.get(sec.title) ?? { href: sec.href, tools: [] };
- entry.tools.push(tool);
- sections.set(sec.title, entry);
- }
- for (const [title, sec] of sections) {
- if (title) body.push(`## ${title}`, '', `Full entries: [${title}](${sec.href}).`, '');
- body.push(...indexTable(sec.tools, cat.canonical, withPlatforms));
- }
- body.push(`Served by \`${ref.server}\`; see [MCP tools](${mcpUrl(ref)}) for every tool.`, '');
- out.set(`mcp-tools/${cat.slug}.mdx`, page(cat.title, sentence(cat.summary), body));
+ body.push(escapeMdxText(sentence(cat.summary)), '');
+ body.push(...canonicalTables(cat, tools, withPlatforms, level + 1));
continue;
}
- if (tools.length > 1) body.push(...indexTable(tools, (t) => `#${t}`, withPlatforms).map((l) => l.replace(/<span id="[^"]*"><\/span>/, '')));
if (cat.intro) body.push(cat.intro.trim(), '');
- body.push(`Served by \`${ref.server}\`; see [MCP tools](${mcpUrl(ref)}) for every tool.`, '');
- for (const tool of tools) body.push(...toolSection(tool, 2, all));
- out.set(`mcp-tools/${cat.slug}.mdx`, page(cat.title, sentence(cat.summary), body));
+ for (const tool of tools) body.push(...toolSection(tool, level + 1, ref.platforms ?? []));
}
- out.set('mcp-tools/meta.json', metaJson('MCP tools', ['index', ...slugs]));
- return out;
+ if (ref.footer) body.push(ref.footer.trim(), '');
+ return body;
}
/** Rows for a product Reference index: one per MCP category. */
@@ -496,12 +561,13 @@ export function mcpIndexRows(ref: McpReference): Array<{ name: string; href: str
}
return [
{ name: 'All tools', href: mcpUrl(ref), description: `Every \`${ref.server}\` tool with a one-line summary.` },
- ...ref.categories
- .filter((c) => (groups.get(c.slug) ?? []).length)
- .map((c) => ({
- name: c.title,
- href: mcpUrl(ref, c.slug),
- description: `${sentence(c.summary)} ${(groups.get(c.slug) ?? []).length} tools.`,
+ ...mcpPages(ref)
+ .map((p) => ({ p, count: p.categories.reduce((n, c) => n + (groups.get(c)?.length ?? 0), 0) }))
+ .filter(({ count }) => count)
+ .map(({ p, count }) => ({
+ name: p.title,
+ href: mcpUrl(ref, p.slug),
+ description: `${sentence(p.summary)} ${count} tools.`,
})),
];
}
diff --git a/scripts/docs-generators/lume.test.ts b/scripts/docs-generators/lume.test.ts
index c8912e44c8..00ca2f2bac 100644
--- a/scripts/docs-generators/lume.test.ts
+++ b/scripts/docs-generators/lume.test.ts
@@ -1,6 +1,6 @@
import assert from 'node:assert/strict';
import { readFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { join, sep } from 'node:path';
import test from 'node:test';
import { renderAll, type CLIDocumentation } from './lume';
@@ -35,11 +35,15 @@ test('lume: CLI groups, HTTP API and MCP render from one dump', () => {
},
});
const byName = (end: string) => [...files].find(([p]) => p.endsWith(end))![1];
- assert.ok(byName(join('cli', 'vms.mdx')).includes('## `lume create`'));
- const http = byName('http-api.mdx');
+ // The whole CLI is one page, a section per group.
+ const cliPage = byName(join('reference', 'cli.mdx'));
+ assert.ok(cliPage.includes('## VMs') && cliPage.includes('### `lume create`'));
+ assert.ok(![...files.keys()].some((p) => p.includes(join('reference', 'cli') + sep)), 'no CLI folder');
+ // The HTTP API, then the MCP tools, on one page.
+ const page = byName('http-api.mdx');
+ const [http, mcp] = page.split('\n## MCP tools\n');
assert.ok(http.includes('Get VM &#123;name&#125;') && http.includes('VM \\| name'));
assert.ok(!/^#### /m.test(http), 'endpoint sub-sections must not repeat headings');
- const mcp = byName('mcp-tools.mdx');
- assert.ok(mcp.includes('## VM tools') && mcp.includes('### `lume_list_vms`') && mcp.includes('## Maintenance tools'));
- assert.deepEqual(JSON.parse(byName(join('reference', 'meta.json'))).pages, ['index', 'cli', 'http-api', 'mcp-tools']);
+ assert.ok(mcp.includes('### VM tools') && mcp.includes('#### `lume_list_vms`') && mcp.includes('### Maintenance tools'));
+ assert.deepEqual(JSON.parse(byName(join('reference', 'meta.json'))).pages, ['index', 'cli', 'http-api']);
});
diff --git a/scripts/docs-generators/lume.ts b/scripts/docs-generators/lume.ts
index 8dba1064e5..b3f8d5bb67 100644
--- a/scripts/docs-generators/lume.ts
+++ b/scripts/docs-generators/lume.ts
@@ -8,9 +8,8 @@
* definitions) and writes, through the shared renderers in lib/:
*
* - docs/content/docs/lume/reference/index.mdx (the Reference index)
- * - docs/content/docs/lume/reference/cli/ (one page per command group)
- * - docs/content/docs/lume/reference/http-api.mdx
- * - docs/content/docs/lume/reference/mcp-tools.mdx
+ * - docs/content/docs/lume/reference/cli.mdx (every command on one page)
+ * - docs/content/docs/lume/reference/http-api.mdx (the HTTP API, then the MCP tools)
* - scripts/docs-generators/cli-specs/lume.json (the CLI-shape lane's oracle)
*
* Usage:
@@ -36,8 +35,7 @@ import {
type JsonSchema,
type McpCategory,
type McpReference,
- mcpIndexRows,
- renderMcpReference,
+ mcpBody,
} from './lib/mcp-mdx';
import { DOCS_CONTENT, REPO_ROOT, codeCell, codeFence, escapeMdxText, escapeTableCell, finish, isCheckMode, metaJson, stableJson, syncFiles } from './lib/mdx';
import { normalizeEmDashes } from './prose-style';
@@ -111,6 +109,7 @@ export function cliReference(cli: CLIDocumentation): CliReference {
generator: REGENERATE,
source: 'lume dump-docs --type cli',
intro: readHeader('lume', 'cli'),
+ singlePage: true,
};
}
@@ -154,22 +153,23 @@ export function mcpReference(mcp: NonNullable<LumeDumpDocs['mcp']>, version: str
export function renderAll(docs: LumeDumpDocs): Map<string, string> {
const cli = cliReference(docs.cli);
const rel = new Map<string, string>(renderCliReference(cli));
- rel.set('http-api.mdx', normalizeEmDashes(generateHTTPAPIMDX(docs.api)));
+ // The HTTP API and the MCP tools share one page: both are what `lume serve` exposes.
+ const mcp = docs.mcp ? mcpReference(docs.mcp, docs.cli.version) : undefined;
+ rel.set('http-api.mdx', normalizeEmDashes(generateHTTPAPIMDX(docs.api, mcp ? mcpBody(mcp, 3) : undefined)));
const sections = [
{ title: 'Commands', column: 'Command group', rows: cliIndexRows(cli) },
{
- title: 'HTTP API',
+ title: 'HTTP API and MCP tools',
column: 'API',
- rows: [{ name: 'HTTP API', href: '/lume/reference/http-api', description: 'Every endpoint `lume serve` exposes, with parameters and examples.' }],
+ rows: [
+ { name: 'HTTP API', href: '/lume/reference/http-api', description: 'Every endpoint `lume serve` exposes, with parameters and examples.' },
+ ...(mcp
+ ? [{ name: 'MCP tools', href: '/lume/reference/http-api#mcp-tools', description: mcp.description }]
+ : []),
+ ],
},
];
const pages = ['index', 'cli', 'http-api'];
- if (docs.mcp) {
- const mcp = mcpReference(docs.mcp, docs.cli.version);
- for (const [p, content] of renderMcpReference(mcp)) rel.set(p, content);
- sections.push({ title: 'MCP tools', column: 'Tools', rows: mcpIndexRows(mcp) });
- pages.push('mcp-tools');
- }
rel.set(
'index.mdx',
renderReferenceIndex({
@@ -272,15 +272,19 @@ export interface APIStatusCodeDoc {
// HTTP API Reference Generator
// ============================================================================
-export function generateHTTPAPIMDX(docs: HTTPAPIDocumentation): string {
+export function generateHTTPAPIMDX(docs: HTTPAPIDocumentation, mcpTools?: string[]): string {
const lines: string[] = [];
const documentedVersion = docs.version;
// Header - frontmatter MUST be at the very beginning of the file
lines.push('---');
- lines.push('title: "HTTP API"');
- lines.push('description: "Every endpoint of the Lume HTTP API server (lume serve)."');
+ lines.push(mcpTools ? 'title: "HTTP API and MCP tools"' : 'title: "HTTP API"');
+ lines.push(
+ mcpTools
+ ? 'description: "Every endpoint of the Lume HTTP API server and every tool of its MCP server (lume serve)."'
+ : 'description: "Every endpoint of the Lume HTTP API server (lume serve)."'
+ );
lines.push('---');
lines.push('');
lines.push(`{/*
@@ -325,6 +329,8 @@ export function generateHTTPAPIMDX(docs: HTTPAPIDocumentation): string {
}
}
+ if (mcpTools) lines.push('## MCP tools', '', ...mcpTools);
+
return lines.join('\n');
}
diff --git a/scripts/docs-generators/reference-quality.test.ts b/scripts/docs-generators/reference-quality.test.ts
index d198ccd662..d06ff0bde2 100644
--- a/scripts/docs-generators/reference-quality.test.ts
+++ b/scripts/docs-generators/reference-quality.test.ts
@@ -3,7 +3,9 @@
* lume and cb (the pages the shared renderers write):
*
* - every page carries the generator marker and has unique anchors;
- * - no page exceeds 5,000 words (docs.cua.ai eager-imports every page);
+ * - no page exceeds 12,000 words: pages hold several command groups or tool
+ * categories, and docs/scripts/page-budget.test.ts (bytes, code blocks,
+ * tabs) is what keeps each one renderable;
* - no placeholder leaks (`undefined`, `[object Object]`) or em dashes;
* - every visible command in the CLI spec has a section on its group page and
* at least one example (tagged for the cli-shape lane) somewhere on that page.
@@ -33,6 +35,8 @@ function walk(dir: string): string[] {
});
}
+const MAX_WORDS = 12_000;
+
function words(page: string): number {
return page.replace(/<span id="[^"]*"><\/span>/g, '').split(/\s+/).filter(Boolean).length;
}
@@ -47,7 +51,7 @@ for (const [product, spec] of PRODUCTS) {
const page = readFileSync(file, 'utf-8');
const rel = file.slice(DOCS_CONTENT.length + 1);
assert.ok(page.slice(0, 600).includes(GENERATED_MARKER), `${rel} lacks the marker`);
- assert.ok(words(page) <= 5000, `${rel} has ${words(page)} words (limit 5000)`);
+ assert.ok(words(page) <= MAX_WORDS, `${rel} has ${words(page)} words (limit ${MAX_WORDS})`);
assert.ok(!/\bundefined\b|\[object Object\]|—/.test(page), `${rel} leaks a placeholder or an em dash`);
assertUniqueAnchors(rel, page);
}
diff --git a/scripts/docs-generators/runner.ts b/scripts/docs-generators/runner.ts
index 37e8dcaaa0..c252ad98df 100644
--- a/scripts/docs-generators/runner.ts
+++ b/scripts/docs-generators/runner.ts
@@ -333,7 +333,7 @@ function testGeneratorRouting(config: Config): void {
config,
[
'libs/cua-driver/rust/crates/cua-driver/src/main.rs',
- 'docs/content/docs/cua-driver/reference/cli/daemon.mdx',
+ 'docs/content/docs/cua-driver/reference/cli/serve-and-configure.mdx',
'scripts/docs-generators/cua-driver.ts',
],
['cua-driver']
@@ -342,7 +342,7 @@ function testGeneratorRouting(config: Config): void {
for (const file of [
'scripts/docs-generators/cli-specs/cua-driver-mcp-windows.json',
'scripts/docs-generators/headers/cua-driver/mcp-tools.md',
- 'docs/content/docs/cua-driver/reference/mcp-tools/click.mdx',
+ 'docs/content/docs/cua-driver/reference/mcp-tools/click-and-type.mdx',
'docs/content/docs/cua-driver/reference/index.mdx',
]) {
assertSelection(config, [file], ['cua-driver']);
@@ -352,7 +352,7 @@ function testGeneratorRouting(config: Config): void {
[
'libs/cua-bench/cua_bench/cli/commands/run.py',
'libs/cua-bench/cua_bench/results.py',
- 'docs/content/docs/cua-bench/reference/cli/run.mdx',
+ 'docs/content/docs/cua-bench/reference/cli.mdx',
'scripts/docs-generators/extract_cb_docs.py',
],
['cua-bench']
@@ -380,7 +380,7 @@ function testGeneratorRouting(config: Config): void {
config,
[
'libs/cua/crates/cua-cli/src/main.rs',
- 'docs/content/docs/cua-cli/reference/mcp-tools/computer.mdx',
+ 'docs/content/docs/cua-cli/reference/mcp-tools.mdx',
'scripts/docs-generators/cua-cli.ts',
],
['cua-cli']
@@ -393,7 +393,7 @@ function testGeneratorRouting(config: Config): void {
);
assertSelection(config, ['libs/cua/crates/cua-fleet/src/lib.rs'], ['cua-rust']);
assertSelection(config, ['docs/content/docs/cua-cli/guides/mcp-server.mdx'], []);
- assertSelection(config, ['docs/content/docs/lume/reference/cli/vms.mdx'], ['lume']);
+ assertSelection(config, ['docs/content/docs/lume/reference/cli.mdx'], ['lume']);
assertSelection(
config,
[