Plan 005: Document minimal web support

Executor instructions: Follow this plan step by step. Run every verification command and confirm the expected result before moving to the next step. If anything in the "STOP conditions" section occurs, stop and report. When done, update the status row for this plan in plans/README.md.

Drift check (run first): git diff --stat f9a9662f0..HEAD -- src/utils/cli-help.ts src/utils/cli-flags.ts src/utils/cli-command-overrides.ts src/utils/__tests__/args.test.ts README.md website/docs skills
If any in-scope file changed since this plan was written, compare the current state below against the live code before proceeding; on mismatch, stop and report.

Status

• Priority: P2
• Effort: S
• Risk: LOW
• Depends on: plans/003-agent-browser-local-adapter.md, plans/004-web-provider-scenarios.md
• Category: docs
• Planned at: commit f9a9662f0, 2026-06-19
• Parent PRD: feat: support web automation through agent-browser #817
• Issue: docs: document minimal web support #822

Why this matters

Web support is intentionally narrow and optional. Users need to know that agent-device reuses agent-browser, which commands work, how to install/check the browser adapter, and which browser features remain direct agent-browser workflows.

Current state

• CLI help and workflow guidance are source of truth for agents.
• The repo says not to duplicate full manuals in skills; skills should route to versioned CLI help.
• CLI help/guidance changes require targeted args tests.

Commands you will need

Scope

In scope

• CLI help for --platform web and a concise web workflow topic if needed.
• README or website docs for install/check/scope.
• Tests asserting important help copy.
• SkillGym case only if command-planning guidance changes.

Out of scope

• Updating skills/**/SKILL.md with detailed behavior.
• Documenting advanced agent-browser features as agent-device features.
• Marketing copy.

Steps

Step 1: Add concise CLI guidance

Document the minimal command loop:
open <url> --platform web, snapshot -i, click @ref, fill @ref, wait text, screenshot, close.
State that agent-browser must be installed and healthy.

Verify: pnpm exec vitest run src/utils/__tests__/args.test.ts exits 0 after adding assertions.

Step 2: Document adapter ownership boundaries

Explain that agent-device owns command/session/replay integration while agent-browser owns browser mechanics. Point users to agent-browser doctor --offline --quick for local browser health checks.

Verify: help tests still pass.

Step 3: Update website/README where user-facing

Add a compact support section that lists first-slice supported and unsupported commands. Avoid copying the agent-browser manual.

Verify: pnpm format exits 0.

Step 4: Add SkillGym coverage only if needed

If CLI guidance teaches agents to plan web commands, add or update one SkillGym case to assert the expected command family and forbid unsupported native commands.

Verify: run the focused SkillGym case if created.

Test plan

• Help copy assertions for install guidance and first-slice command loop.
• Optional SkillGym case if agent-facing planning guidance changes.

Done criteria

• CLI help documents minimal web support and agent-browser dependency.
• User-facing docs list supported and out-of-scope commands.
• Skills remain thin routers.
• Help tests pass.
• pnpm typecheck exits 0.
• pnpm format exits 0.

STOP conditions

• Docs imply web support owns advanced browser features not implemented.
• Skill docs start duplicating CLI help.
• Help copy conflicts with actual provider scenario coverage.

Maintenance notes

Keep docs in lockstep with provider scenario coverage. Do not describe a command as supported until the broad web scenario or a focused test proves it.