trycua · f-trycua · Jun 21, 2026 · Jun 21, 2026 · Jun 21, 2026 · Jun 21, 2026
diff --git a/docs/content/docs/how-to-guides/driver/meta.json b/docs/content/docs/how-to-guides/driver/meta.json
@@ -1 +1 @@
-{ "title": "Driver", "pages": ["install", "connect-your-agent", "keep-running", "update", "windows-ssh"] }
+{ "title": "Driver", "pages": ["install", "connect-your-agent", "keep-running", "personalize-cursor", "update", "windows-ssh"] }
diff --git a/docs/content/docs/how-to-guides/driver/personalize-cursor.mdx b/docs/content/docs/how-to-guides/driver/personalize-cursor.mdx
@@ -0,0 +1,87 @@
+---
+title: Personalize the Cua cursor
+description: Swap the agent cursor shape and palette — pick a built-in silhouette, override at runtime, or bring your own SVG/PNG/ICO.
+---
+
+import { Tabs, Tab } from 'fumadocs-ui/components/tabs';
+import { Callout } from 'fumadocs-ui/components/callout';
+
+The cua agent cursor ships with two built-in silhouettes:
+
+- **`arrow`** (the default) — a procedural gradient diamond drawn from vector primitives each frame. Sharp at any backing scale.
+- **`teardrop`** — an embedded `cursor-up` SVG (upward teardrop with notched bottom, gradient body, white outline) rasterised once into a 52 px buffer.
+
+`arrow` is the default while we finish sorting the teardrop's retina rasterisation. Opt into the teardrop with `--cursor-shape teardrop`. You can also replace the silhouette entirely with your own SVG / PNG / JPEG / ICO file via `--cursor-icon <path>`, swap the body palette at runtime, or scale the bloom halo independently.
+
+## Pick a built-in silhouette
+
+```bash
+cua-driver serve --cursor-shape teardrop   # opt into the SVG teardrop
+cua-driver serve --cursor-shape arrow      # explicit; same as the default
+```
+
+`--cursor-shape` is parsed on `serve` and `mcp`. It's a no-op on one-shot CLI calls like `cua-driver call` — those don't keep the long-lived UI runloop the overlay needs.
+
+`--cursor-icon <path>` always wins over `--cursor-shape`: if you pass both, the custom file is what renders.
+
+## Change the cursor look at runtime
+
+Every per-instance cursor accepts a runtime style override via the `set_agent_cursor_style` MCP tool. An agent or harness can call it mid-session; the next paint frame picks up the new style.
+
+```json
+{
+  "gradient_colors": ["#FF6B6B", "#FFD93D"],
+  "bloom_color":     "#FF6B6B"
+}
+```
+
+- `gradient_colors`: array of CSS hex strings used as the cursor body's tip-to-tail gradient. An empty array reverts to the palette default (`#F0FBFF` → `#66D9FF` → `#35C6D8` on the teardrop; the palette's `cursor_start/mid/end` on the arrow).
+- `bloom_color`: hex string for the radial halo behind the cursor. Empty string reverts.
+- `image_path`: path to a PNG / JPEG / SVG / ICO file. When set, replaces the built-in silhouette with your asset. Empty string reverts.
+
+Switching between `arrow` and `teardrop` at runtime is not exposed via `set_agent_cursor_style` yet — for now it's CLI-only.
+
+## Use your own cursor asset
+
+Pass `--cursor-icon <path>` to `cua-driver serve` (or set `image_path` on `set_agent_cursor_style` at runtime). Supported formats: `.svg`, `.png`, `.jpeg`, `.ico`. The asset is rasterised once at startup into a 52×52 RGBA buffer and used in place of the built-in silhouette.
+
+```bash
+cua-driver serve --cursor-icon ~/my-cursor.svg
+```
+
+<Callout type="info" title="Tip orientation">
+Custom cursor assets are rendered with no rotation compensation — the driver assumes your asset's tip points to the **right** at rest. If your SVG has a tip pointing up, up-left, or anywhere else, the cursor will appear rotated off-axis during motion. Two options:
+
+1. **Re-author your SVG** so the tip points right at the unrotated default. The driver's rotation logic then aligns the tip with motion direction automatically.
+2. **Stick with PNG / static art** if you don't care about motion-aligned rotation — the cursor will render at a fixed orientation regardless of motion direction. This is what most OS cursor packs do.
+</Callout>
+
+## How the built-ins render
+
+### `arrow` (default)
+
+- **Path**: procedural gradient diamond. 4-vertex polygon `(14, 0) → (−8, −9) → (−3, 0) → (−8, 9)` rebuilt each frame.
+- **Body**: linear gradient from the palette's `cursor_start` to `cursor_end` (runtime `gradient_colors` overrides).
+- **Rotation**: tip at +x at rest; `heading + π` aligns the tip with motion direction.
+- **Resolution**: drawn from vector primitives every frame, so it stays sharp at any backing scale without rasterisation artifacts.
+
+### `teardrop`
+
+- **Path**: classic upward teardrop with a notched bottom (Streamline Iconoir `cursor-up`).
+- **Body**: linear gradient from `#F0FBFF` at the tip to `#35C6D8` at the tail.
+- **Outline**: white 1.5 px stroke, rounded caps and joins.
+- **Bloom**: soft radial halo behind the cursor, tinted from the palette's bloom color.
+- **Rotation**: the SVG points up at rest; a `+90°` paint-time offset aligns the tip with motion direction so the cursor faces where it's heading.
+- **Resolution**: source rasterised at 2× the display target (52 px) and rendered at backing-aware physical resolution on retina. We're still tightening retina crispness on this path — that's why the default is `arrow` for now.
+
+## Things that aren't currently personalizable
+
+- **Multiple agent cursors with distinct palettes.** Only one built-in palette today. If you want per-agent distinct cursors, file an issue with the use case.
+- **Cursor display size.** Fixed at 26 logical pixels (52 physical on retina). The runtime `cursor_size` field controls the **dot-style** cursor's radius and doesn't apply to the shape-based render path.
+- **Motion-path curve shape.** Glide duration, post-click dwell, idle-hide delay, and spring damping are tunable via `set_agent_cursor_motion`, but the underlying bezier shape of the path is hardcoded.
+- **Switching `arrow` ↔ `teardrop` at runtime.** Today it's CLI-only — restart the daemon with a different `--cursor-shape` to swap.
+
+## See also
+
+- [Connect your agent](./connect-your-agent.mdx) — register cua-driver with Claude Code, Codex, Hermes, and others.
+- [`set_agent_cursor_style` MCP tool reference](../../reference/cua-driver/mcp-tools.mdx) — full parameter list and return shape.
diff --git a/docs/content/docs/how-to-guides/recipes/build-a-report-in-a-native-app.mdx b/docs/content/docs/how-to-guides/recipes/build-a-report-in-a-native-app.mdx
@@ -74,7 +74,7 @@ Numbers is a **macOS-only** app with **no clean automation API** for building a
     Give the agent the task in plain language:
 
     ```text
-    Fetch the last 30 days of AAPL daily closing prices. Open Numbers, create a new spreadsheet, enter Date and Close columns, add a 2D line chart, then export the document as a PDF to ~/reports/aapl-analysis.pdf.
+    Using cua-driver, fetch the last 30 days of AAPL daily closing prices. Open Numbers, create a new spreadsheet, enter Date and Close columns, add a 2D line chart, then export the document as a PDF to ~/reports/aapl-analysis.pdf.
     ```
 
     The agent drives Numbers with `launch_app`, `list_windows`, `click`, `type_text`, `set_value`, and `get_window_state`.

diff --git a/docs/content/docs/how-to-guides/recipes/export-contacts-overnight.mdx b/docs/content/docs/how-to-guides/recipes/export-contacts-overnight.mdx
@@ -75,7 +75,7 @@ For other MCP clients, see [Connect Cua Driver to an MCP client](/how-to-guides/
 Ask the agent for the exact extraction you want. For LinkedIn, start from the connections page and cap the run with a clear `N` while you test:
 
 ```text
-Open the browser to https://www.linkedin.com/mynetwork/invite-connect/connections/ .
+Using cua-driver, open the browser to https://www.linkedin.com/mynetwork/invite-connect/connections/ .
 
 For each of the first 50 connections:
 1. Open the profile.

diff --git a/docs/content/docs/tutorials/drive-your-first-app.mdx b/docs/content/docs/tutorials/drive-your-first-app.mdx
@@ -94,11 +94,17 @@ Register Cua Driver with your agent harness once.
     cua-driver skills install
     ```
 
-    Prefer plain MCP instead of the skill? Generate the registration command:
+    Prefer plain MCP instead of the skill? Print the Claude Code registration command:
 
     ```bash
     cua-driver mcp-config --client claude
     ```
+
+    It prints a command you run to register the server (paths will be specific to your install):
+
+    ```bash
+    claude mcp add-json cua-computer-use '{"args":["mcp","--claude-code-computer-use-compat"],"command":"/Users/you/.local/bin/cua-driver"}'
+    ```
   </Tab>
   <Tab value="Codex">
     Print the Codex registration command:
@@ -144,7 +150,7 @@ Using Cursor, Gemini/Antigravity, OpenCode, OpenClaw, or Pi instead? See [Connec
 Now ask your agent in plain English. Type this prompt to Claude Code, Codex, or Hermes:
 
 ```text
-Open the calculator and compute 17 x 23, then tell me the answer.
+Using cua-driver, open the calculator and compute 17 x 23, then tell me the answer.
 ```
 
 The agent uses Cua Driver to launch the calculator (Calculator on macOS and Windows, the system calculator on Linux), read the window's accessibility tree, click the number and operator keys, and read the result back from the display. All of it runs in the background. The agent picks the right calculator app for your OS, so the same prompt works on all three platforms.
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		{ "title": "Driver", "pages": ["install", "connect-your-agent", "keep-running", "update", "windows-ssh"] }
		{ "title": "Driver", "pages": ["install", "connect-your-agent", "keep-running", "personalize-cursor", "update", "windows-ssh"] }