Clean up Cua docs IA and references

[f-trycua]

Summary

• Reorganize the public docs around the current Diataxis map: Tutorials, Concepts, How-to Guides, and Reference.
• Rename the old Explanation section to Concepts, keep compatibility redirects, and trim Concepts to the core model pages.
• Move advanced or agent-facing material into Cua Driver Reference, including Process model and Agent action policy.
• Remove or redirect duplicate and overly internal public pages, including the Linux/Wayland explainer, sandbox duplicate tutorial, demonstration skills page, public modality test-suite page, and the short-lived ecosystem concept page.
• Refresh Cua Driver and Lume generated references, remove internal issue/partner references from generated doc sources, and add a public-docs hygiene check for CI.

Validation

• pnpm --dir docs docs:check-hygiene
• pnpm --dir docs docs:check-links
• pnpm --dir docs docs:check
• pnpm --dir docs build
• git diff --check
• local route checks on localhost:8090 for new pages and redirects
• additions-only leak scans for local paths and secret-shaped values before commits

Summary by CodeRabbit

• New Features

  • Added a new Concepts section and several user-facing guides covering background operation, capture/delivery behavior, action selection, and getting started paths.
  • Expanded setup instructions for connecting agents, using cloud sandboxes, and customizing the cursor.

• Bug Fixes

  • Updated site redirects so older documentation links still reach the correct pages.
  • Added checks to help catch outdated or inconsistent docs content during CI.

• Documentation

  • Simplified the docs homepage and navigation, and refreshed reference pages to better match the current product terminology.

[coderabbitai]

Caution

Review failed

An error occurred during the review process. Please try again later.

📝 Walkthrough

Walkthrough

This PR restructures the public docs site: adds a new Concepts section replacing Explanation, rewrites driver/reference guides around delivery_mode/effect/escalation terminology, simplifies recipes and tutorials, adds a docs hygiene check script wired into CI, migrates pnpm overrides to a workspace file, adds URL redirects, and removes issue-number/attribution references from Rust tool description strings while adding a Linux bring_to_front tool.

Changes

Documentation content and navigation restructuring

Layer / File(s)	Summary
New Concepts section and navigation docs/content/docs/concepts/*, docs/content/docs/meta.json, docs/content/docs/index.mdx	Adds Concepts index, capture-and-delivery-modalities and the-no-foreground-contract pages, updates what-is-computer-use wording, and wires "concepts" into site navigation.
Cua Driver action policy and contracts reference docs/content/docs/reference/cua-driver/action-selection-policy.mdx, .../contracts.mdx, .../mcp-tool-notes.mdx, .../mcp-tools.mdx, .../limits.mdx, .../meta.json	Adds the agent action policy page and rewrites contracts/notes/tools/limits docs to use delivery_mode, effect, and escalation terminology instead of dispatch/no-foreground-contract phrasing.
Driver how-to guides update docs/content/docs/how-to-guides/driver/*	Rewrites connect-your-agent, drive-a-web-page, personalize-cursor, windows-ssh pages and updates driver navigation metadata.
Recipe and other how-to guide simplification docs/content/docs/how-to-guides/recipes/*, .../lume/install-lume.mdx, .../sandbox/*, .../skills/record-a-demonstration.mdx, .../meta.json	Consolidates recipe prerequisite steps into upfront callouts, reorders navigation, and streamlines lume/sandbox/skills reference sections.
Tutorials update and cloud sandbox clipboard example docs/content/docs/tutorials/*	Updates drive-your-first-app terminology/links, adjusts tutorial index/meta, and adds clipboard set/read code to your-first-cloud-sandbox.
Version bumps and misc reference index updates docs/content/docs/reference/cua-driver/cli-reference.mdx, .../lume/cli-reference.mdx, .../lume/http-api.mdx, .../index.mdx, .../docs-code-mcp/index.mdx	Bumps documented cua-driver/Lume versions and revises reference index descriptions.

Docs tooling and build infrastructure

Layer / File(s)	Summary
Docs hygiene script and CI/package wiring docs/scripts/check-hygiene.ts, .github/workflows/ci-check-docs-links.yml, docs/package.json	Adds a script scanning mdx files against banned regex patterns, wires it into CI, and adds the corresponding npm script.
pnpm workspace and redirects config docs/pnpm-workspace.yaml, docs/next.config.mjs, docs/README.md	Moves pnpm overrides to a workspace file, adds turbopack root and legacy route redirects, and updates README instructions.

Rust tool doc-string cleanup and bring_to_front

Layer / File(s)	Summary
Remove issue references from get_window_state descriptions platform-linux/.../impl_.rs, platform-macos/.../get_window_state.rs, platform-windows/.../impl_.rs	Removes embedded issue-number references from max_elements/max_depth schema text and structured notes.
Linux bring_to_front tool implementation platform-linux/.../impl_.rs	Adds BringToFrontTool with Wayland rejection and X11 activation logic, registered in build_registry.
health_report and schema contract wording cleanup cua-driver-core/src/health_report.rs, platform-macos/.../mod.rs, platform-windows/.../impl_.rs, test-harness/*, scripts/docs-generators/*	Removes Hermes Agent/issue references from descriptions and comments and aligns test-harness docs and generator link/config with updated terminology.

Estimated code review effort: 3 (Moderate) | ~30 minutes

Possibly related PRs

• trycua/cua#2053: Overlaps directly with the capture-and-delivery modality documentation rewrite and axis semantics.
• trycua/cua#2095: Both remove the legacy "auto" delivery_mode value and specify fallback behavior in the same reference docs.
• trycua/cua#2107: Both update Codex onboarding instructions in connect-your-agent.mdx.

Suggested reviewers: ddupont808

Poem

A rabbit hopped through docs so deep,
Swept "explanation" off to sleep,
New Concepts bloom where old ones lay,
Delivery modes now light the way. 🐇✨
Hygiene scripts stand watch at the gate—
Clean docs, clean code, review time's great!

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/docs-diataxis-cleanup

Warning

Tools execution failed with the following error:

Failed to run tools: 13 INTERNAL: Received RST_STREAM with code 2 (Internal server error)

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

📦 Publishable packages changed

• cua-driver-rs

Add release:<service> labels to auto-release on merge (+ optional bump:minor or bump:major, default is patch).
Or add no-release to skip.

[github-actions]

Linux visual regression artifacts

Matrix jobs now run independently. Download visual artifacts from this workflow run.
Each background-GUI job uploads a .gif of the interaction plus two annotated PNGs (<app>.png raw, <app>-atspi.png with AT-SPI element boxes); the cua-driver-linux-som-overlays artifact adds <app>-som.png cua Set-of-Marks overlays:

• cua-driver-linux-cursor-click-gif
• cua-driver-linux-background-terminal-gif
• cua-driver-linux-parallel-drag-xserver
• cua-driver-linux-background-gui-chromium
• cua-driver-linux-background-gui-tk
• cua-driver-linux-background-gui-gtk3-gedit
• cua-driver-linux-background-gui-gtk3-mousepad
• cua-driver-linux-background-gui-gtk3-scite
• cua-driver-linux-background-gui-gtk4-characters
• cua-driver-linux-background-gui-qt5-manuskript
• cua-driver-linux-background-gui-qt5-klog
• cua-driver-linux-background-gui-qt5-openambit
• cua-driver-linux-background-gui-qt6-kate
• cua-driver-linux-background-gui-qt6-kcalc
• cua-driver-linux-background-gui-qt6-okular
• cua-driver-linux-background-gui-qt6-qownnotes
• cua-driver-linux-background-gui-electron-zettlr
• cua-driver-linux-background-gui-electron-joplin
• cua-driver-linux-background-gui-electron-logseq
• cua-driver-linux-som-overlays

Open workflow run and download artifacts

[github-actions]

📦 Publishable packages changed

• cua-driver-rs

Add release:<service> labels to auto-release on merge (+ optional bump:minor or bump:major, default is patch).
Or add no-release to skip.

[github-actions]

📦 Publishable packages changed

• cua-driver-rs

Add release:<service> labels to auto-release on merge (+ optional bump:minor or bump:major, default is patch).
Or add no-release to skip.

[github-actions]

📦 Publishable packages changed

• cua-driver-rs

Add release:<service> labels to auto-release on merge (+ optional bump:minor or bump:major, default is patch).
Or add no-release to skip.

[github-actions]

📦 Publishable packages changed

• cua-driver-rs

Add release:<service> labels to auto-release on merge (+ optional bump:minor or bump:major, default is patch).
Or add no-release to skip.

[github-actions]

📦 Publishable packages changed

• cua-driver-rs

Add release:<service> labels to auto-release on merge (+ optional bump:minor or bump:major, default is patch).
Or add no-release to skip.

[github-actions]

📦 Publishable packages changed

• cua-driver-rs

Add release:<service> labels to auto-release on merge (+ optional bump:minor or bump:major, default is patch).
Or add no-release to skip.

[github-actions]

📦 Publishable packages changed

• cua-driver-rs

Add release:<service> labels to auto-release on merge (+ optional bump:minor or bump:major, default is patch).
Or add no-release to skip.