docs(cua-driver): wire reference auto-generation to the real docs dir + release - #2088
Merged
Conversation
…rst-app tutorial The tutorial told users to start the daemon by hand (`cua-driver serve`, or on macOS `open -n -g -a CuaDriver --args serve`) in each install tab. That's not needed: the CLI (`doctor`/`call`) and the agent's MCP connection start the daemon automatically. Removed the daemon-start blocks from the macOS/Windows/Linux tabs; macOS keeps `permissions grant` (which launches CuaDriver itself for the TCC prompts). Section 2's verify step is unchanged. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011BJPGdRQxiBPTQhjwZsQ8G
… + release
The cua-driver reference generator was disabled and pointed at a docs
directory that does not exist, so CI silently skipped it and the committed
reference drifted (v0.5.7, 36 tools) from the shipping binary (v0.7.0, 38
tools). This repoints and re-enables it, splits the hand-authored content
out of the generator-owned files, and wires a release-time regen.
- Repoint output to the real dir: cua-driver.ts DOCS_OUTPUT_DIR and
config.json docsOutputPath now target docs/content/docs/reference/cua-driver.
No duplicate docs/content/docs/cua-driver/reference tree is created.
- Fix the generator for the current Diataxis docs: drop the dead
<VersionHeader>/@/components/version-selector import (the component no
longer exists) and the /cua-driver/reference + /cua-driver/guide links;
emit the repo's install-snippet + "Documented against X" intro and
/reference/cua-driver + /explanation links instead.
- Preserve curated content the generator does not own by extracting it into
two non-generated siblings:
mcp-tool-notes.mdx <- Common/Required/Platform-specific parameters and
the action response shape, plus get_window_state
degraded + page platform per-tool notes.
macos-permissions.mdx <- the macOS-only `cua-driver permissions` command.
meta.json links both; the generated files link back to them.
- Categorize the five newer tools (get_desktop_state, health_report,
install_ffmpeg, start_session, end_session) instead of dumping them in
"Other tools".
- Enable the generator in config.json; fix ci-check-docs.yml path filter
(docs/content/docs/cua-driver/reference -> docs/content/docs/reference/
cua-driver) so it stops falsely passing; add docs:generate:cua-driver.
- Add cd-cua-driver-docs.yml: on a cua-driver-rs-v* tag, rebuild, regenerate,
and open a PR with the refreshed MDX.
- Regenerate to v0.7.0 / 38 tools.
CLI docs still come from the hand-maintained cli_docs_json() literal in
crates/cua-driver/src/cli.rs (the CLI is hand-parsed, not clap); introspecting
it is a tracked follow-up, intentionally out of scope here.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Th8TxivbUjS6NUT2cKVo6s
Contributor
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
|
Important Review skippedAuto incremental reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
📝 WalkthroughWalkthroughAdds a CD workflow that regenerates auto-generated cua-driver reference docs on version-tag pushes, updates CI path filters, enables and repoints the cua-driver docs generator's output path, adjusts generator logic (removing version-header generation, adding code-formatted headings), and regenerates CLI/MCP reference MDX plus two new hand-maintained pages and minor tutorial edits. ChangesCua Driver docs generation pipeline and reference docs
Estimated code review effort: 3 (Moderate) | ~25 minutes Possibly related issues
Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 3
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (3)
docs/content/docs/tutorials/drive-your-first-app.mdx (2)
67-67: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winRephrase "only CLI you run by hand" for macOS readers.
macOS users have already run
cua-driver permissions grantby hand in the install step, so the claim thatdoctorandlist_appsare "the only CLI you run by hand" is inaccurate for them. Consider qualifying the statement, e.g., "That is the last CLI you need to run by hand" or "From here the agent does the driving."🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/content/docs/tutorials/drive-your-first-app.mdx` at line 67, The wording in the tutorial is too absolute for macOS users, since they already ran the permissions grant command by hand during setup. Update the sentence in the introductory flow around the app-check/doctor guidance to avoid saying it is the only CLI run manually; use phrasing like “the last CLI you need to run by hand” or simply “from here the agent does the driving,” so the copy stays accurate for the `doctor` and `list_apps` section.
25-29: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winUpdate downstream claim about "only CLI you run by hand."
Adding
cua-driver permissions grantto the macOS install step means macOS users have now run a CLI command by hand before reaching the verification section. The unchanged line 67 ("That is the only CLI you run by hand") becomes inaccurate for macOS readers. Consider rephrasing that claim to account for the permissions command, e.g., "That is the last CLI you need to run by hand."🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/content/docs/tutorials/drive-your-first-app.mdx` around lines 25 - 29, The install walkthrough now includes the cua-driver permissions grant command, so the later claim in drive-your-first-app.mdx that it is “the only CLI you run by hand” is no longer accurate for macOS readers. Update that downstream sentence to reflect that the permissions command is also run manually, and rephrase it in a way that matches the tutorial flow; use the surrounding verification section text and the cua-driver permissions grant step to locate the affected wording..github/workflows/ci-check-docs.yml (1)
61-116: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
config.jsonchanges can still bypass the drift check.This PR proves
scripts/docs-generators/config.jsonis not metadata-only: it now changes both the cua-driver output path and whether that generator runs at all. But this step still ignores config-only edits unless a generator script also changed, so future wiring changes can merge without ever exercising the relevant generator.Suggested fix
- # Only runner.ts changes trigger all generators (it's the orchestration layer) - # config.json changes only affect whichever generator scripts were also changed - if echo "$CHANGED_FILES" | grep -qE "^scripts/docs-generators/runner\.ts$"; then + # runner.ts and config.json both affect generator selection/output wiring + if echo "$CHANGED_FILES" | grep -qE "^scripts/docs-generators/(runner\.ts|config\.json)$"; then GENERATORS="all" fi🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.github/workflows/ci-check-docs.yml around lines 61 - 116, The changed-generator detection in the “Determine changed generators” step still ignores scripts/docs-generators/config.json when no generator script changed, which can let generator wiring changes skip validation. Update the CHANGED_FILES matching logic so config.json edits are treated as triggering the affected generator(s) in the same way as source changes, using the existing GENERATORS aggregation and dedup flow. Make sure the detection rules in this step stay aligned with the config-driven behavior used by scripts/docs-generators/runner.ts and the per-generator scripts like cua-driver.ts.
🧹 Nitpick comments (1)
.github/workflows/cd-cua-driver-docs.yml (1)
55-63: 🔒 Security & Privacy | 🔵 Trivial | ⚡ Quick winScope the GitHub App token to the permissions this job actually uses.
This token currently inherits whatever repo permissions the App installation has. The rest of the job only needs
contents: writeandpull-requests: write, so minting a narrower token would reduce blast radius ifGH_TOKENever leaks.Suggested fix
- name: Generate GitHub App token id: app-token uses: actions/create-github-app-token@v1 with: app-id: ${{ secrets.RELEASE_APP_ID }} private-key: ${{ secrets.RELEASE_APP_PRIVATE_KEY }} owner: ${{ github.repository_owner }} repositories: ${{ github.event.repository.name }} + permission-contents: write + permission-pull-requests: write🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.github/workflows/cd-cua-driver-docs.yml around lines 55 - 63, The GitHub App token created in the app-token step is broader than this job needs, so narrow it to only the permissions used by the workflow. Update the token minting in the actions/create-github-app-token@v1 step so the resulting GH_TOKEN is scoped to contents: write and pull-requests: write only, using the existing app-token/app-id/private-key setup. Keep the rest of the job unchanged and ensure the new scope still works with the doc publishing and PR update steps.Source: Linters/SAST tools
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.github/workflows/cd-cua-driver-docs.yml:
- Around line 28-31: The Checkout repository step in the workflow leaves the
default token persisted in git config, which can expose write-capable
credentials to later commands like pnpm install and cargo build. Update the
actions/checkout@v4 configuration in the checkout step to disable persisted
credentials, using the existing Checkout repository action block as the
reference, and keep the later App token re-authentication flow for pushes
unchanged.
In `@docs/content/docs/reference/cua-driver/mcp-tools.mdx`:
- Around line 538-556: The `replay_trajectory` docs contain an incorrect
parameter description for `dir` that references a non-existent tool name. Update
the source string in the Rust `replay_trajectory` tool definition, specifically
the `dir` argument description, so it uses `start_recording` and matches the
surrounding documentation text. Ensure the generated MDX picks up the corrected
wording on the next regen.
In `@scripts/docs-generators/cua-driver.ts`:
- Around line 278-295: Exclude the macOS-only permissions command from the
generated CLI reference so it no longer appears under “Other commands.” Update
the CLI docs generation flow in scripts/docs-generators/cua-driver.ts,
specifically around generateCLIReferenceMDX() and the dump-docs input, to filter
out `permissions` before rendering. Keep the separate macOS permissions page as
the only source for that command.
---
Outside diff comments:
In @.github/workflows/ci-check-docs.yml:
- Around line 61-116: The changed-generator detection in the “Determine changed
generators” step still ignores scripts/docs-generators/config.json when no
generator script changed, which can let generator wiring changes skip
validation. Update the CHANGED_FILES matching logic so config.json edits are
treated as triggering the affected generator(s) in the same way as source
changes, using the existing GENERATORS aggregation and dedup flow. Make sure the
detection rules in this step stay aligned with the config-driven behavior used
by scripts/docs-generators/runner.ts and the per-generator scripts like
cua-driver.ts.
In `@docs/content/docs/tutorials/drive-your-first-app.mdx`:
- Line 67: The wording in the tutorial is too absolute for macOS users, since
they already ran the permissions grant command by hand during setup. Update the
sentence in the introductory flow around the app-check/doctor guidance to avoid
saying it is the only CLI run manually; use phrasing like “the last CLI you need
to run by hand” or simply “from here the agent does the driving,” so the copy
stays accurate for the `doctor` and `list_apps` section.
- Around line 25-29: The install walkthrough now includes the cua-driver
permissions grant command, so the later claim in drive-your-first-app.mdx that
it is “the only CLI you run by hand” is no longer accurate for macOS readers.
Update that downstream sentence to reflect that the permissions command is also
run manually, and rephrase it in a way that matches the tutorial flow; use the
surrounding verification section text and the cua-driver permissions grant step
to locate the affected wording.
---
Nitpick comments:
In @.github/workflows/cd-cua-driver-docs.yml:
- Around line 55-63: The GitHub App token created in the app-token step is
broader than this job needs, so narrow it to only the permissions used by the
workflow. Update the token minting in the actions/create-github-app-token@v1
step so the resulting GH_TOKEN is scoped to contents: write and pull-requests:
write only, using the existing app-token/app-id/private-key setup. Keep the rest
of the job unchanged and ensure the new scope still works with the doc
publishing and PR update steps.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: a0c5b2c3-b886-4d03-9a44-f1b6466cc47c
📒 Files selected for processing (11)
.github/workflows/cd-cua-driver-docs.yml.github/workflows/ci-check-docs.ymldocs/content/docs/reference/cua-driver/cli-reference.mdxdocs/content/docs/reference/cua-driver/macos-permissions.mdxdocs/content/docs/reference/cua-driver/mcp-tool-notes.mdxdocs/content/docs/reference/cua-driver/mcp-tools.mdxdocs/content/docs/reference/cua-driver/meta.jsondocs/content/docs/tutorials/drive-your-first-app.mdxdocs/package.jsonscripts/docs-generators/config.jsonscripts/docs-generators/cua-driver.ts
Comment on lines
+28
to
+31
| - name: Checkout repository | ||
| uses: actions/checkout@v4 | ||
| with: | ||
| fetch-depth: 0 # full history for git-tag version discovery |
Contributor
There was a problem hiding this comment.
🔒 Security & Privacy | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
sed -n '1,180p' .github/workflows/cd-cua-driver-docs.yml | cat -nRepository: trycua/cua
Length of output: 4408
🏁 Script executed:
python3 - <<'PY'
from pathlib import Path
p = Path('.github/workflows/cd-cua-driver-docs.yml')
text = p.read_text()
for i, line in enumerate(text.splitlines(), 1):
if 'checkout' in line.lower() or 'credentials' in line.lower() or 'github app' in line.lower() or 'git remote set-url' in line.lower() or 'pnpm install' in line.lower() or 'cargo build' in line.lower():
print(f"{i}: {line}")
PYRepository: trycua/cua
Length of output: 566
🏁 Script executed:
sed -n '1,140p' .github/workflows/cd-cua-driver-docs.yml | nl -ba | sed -n '1,140p'Repository: trycua/cua
Length of output: 184
Disable persisted checkout credentials. actions/checkout leaves the repo token in git config until it is cleared later, so pnpm install and cargo build can read a write-capable credential. Set persist-credentials: false here; the workflow re-authenticates with the App token before pushing.
🧰 Tools
🪛 zizmor (1.26.1)
[warning] 28-31: credential persistence through GitHub Actions artifacts (artipacked): does not set persist-credentials: false
(artipacked)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.github/workflows/cd-cua-driver-docs.yml around lines 28 - 31, The Checkout
repository step in the workflow leaves the default token persisted in git
config, which can expose write-capable credentials to later commands like pnpm
install and cargo build. Update the actions/checkout@v4 configuration in the
checkout step to disable persisted credentials, using the existing Checkout
repository action block as the reference, and keep the later App token
re-authentication flow for pushes unchanged.
Source: Linters/SAST tools
Comment on lines
538
to
556
| ### `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`. | ||
| 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-indexed actions fail because element indices are per-snapshot. Pixel clicks and keyboard tools replay cleanly. | ||
| - `get_window_state` and other read-only tools are not recorded, so replays do not re-populate the element cache. | ||
| - When recording is enabled while replay runs, the replay itself is recorded into the currently configured output directory. | ||
| - Element-indexed actions (`click({pid, element_index})` etc.) will fail because element indices 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. | ||
|
|
||
| | Argument | Type | Required | Description | | ||
| | -------- | ---- | -------- | ----------- | | ||
| | `dir` | string | Yes | Trajectory directory previously written by `start_recording`. Absolute or `~`-rooted. | | ||
| | `delay_ms` | integer | No | Milliseconds to sleep between turns. Default 500. | | ||
| | `stop_on_error` | boolean | No | Stop replay on the first tool-call error. Default true. | | ||
| **Arguments:** | ||
|
|
||
| - `delay_ms` (integer, optional): Milliseconds to sleep between turns, for human-observable pacing. Default 500. | ||
| - `dir` (string, required): Trajectory directory previously written by `set_recording`. Absolute or ~-rooted. | ||
| - `stop_on_error` (boolean, optional): Stop replay on the first tool-call error. Default true — set false to best-effort through the full trajectory. | ||
|
|
||
| ```json | ||
| {"dir": "~/cua-trajectories/demo1"} | ||
| {"dir":"~/cua-trajectories/demo1"} | ||
| ``` | ||
|
|
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Fix non-existent tool name in replay_trajectory parameter description.
The dir parameter description references set_recording, which is not a valid tool. It should read start_recording to match the actual tool name and the description text two lines above.
Since this MDX is auto-generated, fix the source string in the Rust replay_trajectory tool definition (likely in the dir parameter's description field) so the next regeneration picks it up.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/content/docs/reference/cua-driver/mcp-tools.mdx` around lines 538 - 556,
The `replay_trajectory` docs contain an incorrect parameter description for
`dir` that references a non-existent tool name. Update the source string in the
Rust `replay_trajectory` tool definition, specifically the `dir` argument
description, so it uses `start_recording` and matches the surrounding
documentation text. Ensure the generated MDX picks up the corrected wording on
the next regen.
Comment on lines
+278
to
+295
| // Introduction | ||
| lines.push(escapeMdxText(docs.abstract) + ' Install via the official script:'); | ||
| lines.push(''); | ||
| lines.push('```sh'); | ||
| lines.push( | ||
| ` installCommand="curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/cua-driver/scripts/install.sh | bash"` | ||
| 'curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/cua-driver/scripts/install.sh | bash' | ||
| ); | ||
| lines.push('/>'); | ||
| lines.push('```'); | ||
| lines.push(''); | ||
|
|
||
| // Introduction | ||
| lines.push(escapeMdxText(docs.abstract)); | ||
| lines.push( | ||
| `Documented against Cua Driver **${releasedVersion}**. Run \`cua-driver --version\` for your installed version.` | ||
| ); | ||
| lines.push(''); | ||
| lines.push( | ||
| 'The macOS-only `cua-driver permissions` command is documented separately in [macOS permissions](/reference/cua-driver/macos-permissions).' | ||
| ); | ||
| lines.push(''); | ||
| lines.push('---'); |
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "Checking whether the permissions command is still present in generator inputs/outputs..."
rg -n -C2 '\bpermissions\b' \
docs/content/docs/reference/cua-driver/cli-reference.mdx \
libs/cua-driver/rust/crates/cua-driver/src/cli.rsRepository: trycua/cua
Length of output: 14044
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "Map the docs generator and inspect the CLI reference generation path."
ast-grep outline scripts/docs-generators/cua-driver.ts --view expanded
echo
echo "Relevant generator slices:"
sed -n '1,220p' scripts/docs-generators/cua-driver.ts
echo
sed -n '220,380p' scripts/docs-generators/cua-driver.ts
echo
sed -n '380,520p' scripts/docs-generators/cua-driver.tsRepository: trycua/cua
Length of output: 18947
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "Inspect how dump-docs populates the CLI command list and whether permissions is filtered anywhere."
ast-grep outline libs/cua-driver/rust/crates/cua-driver/src/cli.rs --view expanded
echo
echo "Search for command serialization / filtering around dump-docs:"
rg -n -C3 'permissions|dump-docs|commands|subcommands|mcp' libs/cua-driver/rust/crates/cua-driver/src/cli.rsRepository: trycua/cua
Length of output: 50366
Exclude permissions from the generated CLI reference. dump-docs still includes permissions, and generateCLIReferenceMDX() will render it under “Other commands, so cli-reference.mdxstill owns the macOS-only command even though the intro points to the separate page.scripts/docs-generators/cua-driver.ts`
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@scripts/docs-generators/cua-driver.ts` around lines 278 - 295, Exclude the
macOS-only permissions command from the generated CLI reference so it no longer
appears under “Other commands.” Update the CLI docs generation flow in
scripts/docs-generators/cua-driver.ts, specifically around
generateCLIReferenceMDX() and the dump-docs input, to filter out `permissions`
before rendering. Keep the separate macOS permissions page as the only source
for that command.
f-trycua
added a commit
that referenced
this pull request
Jul 1, 2026
…grant recipe - capture-and-dispatch-modalities: mcp-tool-notes doesn't exist on main (it's introduced by #2088), so point action-response-shape back to mcp-tools - fill-a-form recipe: 'permissions status' is read-only and won't trigger the prompts the step tells you to approve — use 'permissions grant' first Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Th8TxivbUjS6NUT2cKVo6s
…desc, exclude permissions - cd-cua-driver-docs.yml: persist-credentials: false on checkout (the workflow re-auths with the App token before pushing) - recording_tools.rs: replay_trajectory 'dir' description referenced the removed 'set_recording' tool -> 'start_recording' (regenerated mcp-tools.mdx) - cua-driver.ts: exclude 'permissions' from the generated CLI reference; it's documented on its own macos-permissions page Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Th8TxivbUjS6NUT2cKVo6s
Contributor
Linux visual regression artifactsMatrix jobs now run independently. Download visual artifacts from this workflow run.
|
f-trycua
added a commit
that referenced
this pull request
Jul 1, 2026
Now that #2088 has merged, the 'Action response shape' section lives in mcp-tool-notes.mdx (moved out of the auto-generated mcp-tools.mdx). Point the capture-and-dispatch-modalities link at its new home. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Th8TxivbUjS6NUT2cKVo6s
f-trycua
added a commit
that referenced
this pull request
Jul 1, 2026
* docs(cua-driver): fix macOS audit findings — 42 not 391, 0.7.0, permissions status Iteration 1 live-audit fixes (verified against cua-driver 0.7.0): - tutorial: result was reported as 391, contradicting its own step 4 (42) - install: --version/doctor showed 0.5.x; live is 0.7.0 - install: pretty ✅ TCC output belongs to 'permissions status', not 'check_permissions' (which returns JSON) Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Th8TxivbUjS6NUT2cKVo6s * docs(cua-driver): fix consistency findings — phantom tools, anchors, axes, mcp-config Iteration 1 cross-doc consistency fixes (verified vs live cua-driver 0.7.0): - remove phantom 'screenshot' tool refs (no such tool among the 38) - fix action-response-shape anchor to mcp-tool-notes - explanation index: three axes -> four (adds the action-rung axis) - demonstrations: video is not recorded 'by default' - connect-your-agent: Pi examples need 'call'; mcp-config claude example matches live output (--scope user, no compat flag) Source/generator-level findings (type_text_chars, manifest, flag docs) recorded in DOCS_AUDIT.md for a coordinated fix with cua#2088. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Th8TxivbUjS6NUT2cKVo6s * docs(cua-driver): fix how-to + recipe findings — permissions status, versions, autostart, cursor-palette Iteration 2 (macOS how-to guides + recipes, verified vs 0.7.0): - recipes: 'call check_permissions' (JSON) -> 'permissions status' (matches shown output); stale 0.5.x placeholder -> 0.7.0 - keep-running: macOS autostart helper is repo-relative and breaks for curl-installed users; reframed around the plist - personalize-cursor: document the live --cursor-palette launch flag Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Th8TxivbUjS6NUT2cKVo6s * docs: note Azure resource-group for audit VM cleanup Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Th8TxivbUjS6NUT2cKVo6s * docs(cua-driver): fix Linux findings — libXi prereq, headless gap, ffmpeg, systemd target Iteration 3 (Linux, live-verified on fresh Azure Ubuntu 22.04): - install (Linux): [blocker] binary won't launch without libXi.so.6; add 'sudo apt install libxi6 at-spi2-core' prereq + sudo caveat + headless-desktop note; drop the phantom ffmpeg claim from the doctor sentence - keep-running (Linux): headless boxes need WantedBy=default.target Recorded (generator fix, cua#2088): mcp-tools tool count is platform-specific — Linux exposes 43 (5 Linux-only tools incl type_text_chars), macOS 38. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Th8TxivbUjS6NUT2cKVo6s * docs(cua-driver): refresh update.mdx sample versions 0.3.x -> 0.7.0 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Th8TxivbUjS6NUT2cKVo6s * docs(cua-driver): fix Windows findings + finalize audit summary Iteration 4 (Windows, live on Azure Server 2022 via run-command/Session 0): - install (Windows): note the installer registers the cua-driver-serve autostart task + its interactive requirement - keep-running (Windows): autostart from a non-interactive/SSH context fails with a cryptic SID error — use RDP/local console Windows list-tools = 39 (macOS 38 / Linux 43) — reinforces the platform-specific tool-surface finding for cua#2088. Full audit summary in DOCS_AUDIT.md. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Th8TxivbUjS6NUT2cKVo6s * chore: drop working audit log (kept out of the docs PR) * docs(cua-driver): unify inbound link text to the choose-a-modality title The page title is 'Choose an Action Rung and Dispatch Mode' but several docs linked it as 'Choose a capture and dispatch mode'. Unify to match. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Th8TxivbUjS6NUT2cKVo6s * docs(cua-driver): address CodeRabbit — revert anchor, fix permission-grant recipe - capture-and-dispatch-modalities: mcp-tool-notes doesn't exist on main (it's introduced by #2088), so point action-response-shape back to mcp-tools - fill-a-form recipe: 'permissions status' is read-only and won't trigger the prompts the step tells you to approve — use 'permissions grant' first Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Th8TxivbUjS6NUT2cKVo6s * docs(cua-driver): point action-response-shape anchor to mcp-tool-notes Now that #2088 has merged, the 'Action response shape' section lives in mcp-tool-notes.mdx (moved out of the auto-generated mcp-tools.mdx). Point the capture-and-dispatch-modalities link at its new home. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Th8TxivbUjS6NUT2cKVo6s --------- Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The cua-driver reference generator was
enabled: falseand pointed atdocs/content/docs/cua-driver/reference(which does not exist), while the committed docs live atdocs/content/docs/reference/cua-driver. So the runner/CI silently skipped it and falsely reported "up to date", and the reference drifted from the binary: committed said v0.5.7 / 36 tools, the shipping binary is v0.7.0 / 38 tools (missingget_desktop_stateandhealth_report). This PR makes the generator the real, working owner ofcli-reference.mdx+mcp-tools.mdx, preserves the hand-authored content, and wires release-time regeneration.What was repointed
cua-driver.tsDOCS_OUTPUT_DIRandconfig.jsondocsOutputPath→docs/content/docs/reference/cua-driver(the one canonical location). No duplicatedocs/content/docs/cua-driver/referencetree is created.Generator fixes for the current (Diátaxis) docs
Running the generator as-is would have broken the docs build: it emitted
import { VersionHeader } from '@/components/version-selector'(that component no longer exists — no doc uses it) and/cua-driver/reference/…+/cua-driver/guide/…links that don't resolve.VersionHeaderblock +discoverVersions/VersionInfomachinery./reference/cua-driver/…and/explanation/process-model//explanation/the-no-foreground-contract.Curated content split out (nothing lost)
The per-tool bodies come from the binary's own
dump-docsdescriptions (rich and current). The genuinely cross-cutting hand-authored content — not derivable from any single tool schema — was extracted into two non-generated siblings:mcp-tool-notes.mdx← "Common parameters", "Required parameters", "Platform-specific parameters", "Action response shape", plus theget_window_statedegraded-result note and thepageplatform-support note (trycua/cua#2084).macos-permissions.mdx← the macOS-onlycua-driver permissionscommand (absent fromdump-docs, so the generator can't emit it).meta.jsonlinks both; the generated files link back to them.contracts.mdx,limits.mdx,modality-test-suite.mdxare untouched. Verified every curated phrase still resolves in the docs dir.Config / CI / script / workflow
config.json:enabled: false → true; refreshed the stale note.ci-check-docs.yml: fixed the path filter and changed-generator grep (docs/content/docs/cua-driver/reference→docs/content/docs/reference/cua-driver) so the drift check actually runs for cua-driver instead of no-op passing.docs/package.json: addeddocs:generate:cua-driver(mirrorsdocs:generate:lume).cd-cua-driver-docs.yml: on acua-driver-rs-v*tag (or manual dispatch), rebuild + regenerate + open a PR with the refreshed MDX. No release workflow (lume included) previously regenerated docs, so this is a minimal tag-triggered workflow scoped to cua-driver, using the same App-token identity as the existing release automation.Regen result
get_desktop_state,health_report,install_ffmpeg,start_session,end_session) instead of dumping them in "Other tools".get_desktop_stateandhealth_reportnow present.npx tsx scripts/docs-generators/runner.ts --library cua-driver --checknow actually checks (builds, 38 tools) and reports up-to-date — no longer "Skipped (disabled)".Known follow-up (intentionally out of scope)
CLI docs still come from the hand-maintained
cli_docs_json()literal inlibs/cua-driver/rust/crates/cua-driver/src/cli.rs. The CLI is hand-parsed (notclap), so there's nothing to introspect yet; adoptingclapor reflecting the parser to make CLI docs source-derived (like the MCP side already is) is a separate change.🤖 Generated with Claude Code
https://claude.ai/code/session_01Th8TxivbUjS6NUT2cKVo6s
Summary by CodeRabbit
New Features
Documentation
Bug Fixes