[claude-code-user-docs-review] 🔍 Claude Code User Documentation Review - 2026-07-09

[github-actions[bot]]

Executive Summary

A Claude Code user can onboard gh-aw without any Copilot product: Claude is a first-class engine with quick-start auth coverage, 59 example workflows, and it is the sole engine in the core smoke-test suite. No critical blockers. Key finding: the docs still have no PAT-free/OAuth path for Claude, default silently to Copilot when engine: is omitted, and lead with a Copilot-first framing — the same three friction points logged for 22 consecutive daily runs (score stable at 7.5/10).

Severity Findings (Critical → Major → Minor)

Critical Blockers: none. A Claude Code user can complete quick-start end-to-end with ANTHROPIC_API_KEY alone.

Major Obstacles

1. No PAT-free / OAuth path for Claude. Copilot offers an org-billing shortcut (permissions.copilot-requests: write, no PAT) — quick-start.mdx:92-95. Claude's only documented path is an ANTHROPIC_API_KEY console key (quick-start.mdx:98-100, cli.md:171). Claude Pro/Max/Teams subscription (OAuth) tokens are not surfaced as usable; prior runs confirmed CLAUDE_CODE_OAUTH_TOKEN is explicitly ignored (auth.mdx:206-208). This hits the exact persona.
2. Silent Copilot default. Omit engine: and the runtime defaults to Copilot (how-they-work.mdx:26, quick-start.mdx:75); gh aw init emits Copilot artifacts unless --engine claude (cli.md:143,148). The --engine claude flag is documented in cli.md but never surfaced in the quick-start add flow.
3. Uneven secret callouts. Quick-start gives detailed setup blocks for Copilot + Anthropic + Codex, but Gemini is prereq-only with no auth block (quick-start.mdx:81,109-112), and WIF keyless auth (auth.mdx:207-271) is never mentioned in quick-start.

Minor Confusion

• Copilot-first nudge in prerequisites ("start there — no extra account setup", quick-start.mdx:30); no why-Claude-vs-Copilot guidance.
• custom engine has 0 standalone example workflows (only shared/genaiscript.md fragment); crush appears in the secrets-bootstrap --engine list (cli.md:258) but has no documented secret; no default Claude model version is documented (architecture.mdx:279).

Engine & Tool Matrix

Engine	Setup in quick-start	Example workflows	Auth	Score
Copilot (default)	✅ detailed + org-billing shortcut	125 explicit (~161 w/ implicit default)	PAT or PAT-free org billing	9/10
Claude	✅ detailed	59 (2nd; sole engine in smoke suite)	ANTHROPIC_API_KEY only; no OAuth/PAT-free path	7.5/10
Codex	✅ detailed	14 (under-represented)	OPENAI_API_KEY/CODEX_API_KEY; web-search off by default	7/10
Custom	❌ none	0 standalone (fragment only)	generic note only	4/10

Tools: all ~14 tools (edit, github, bash, web-fetch, playwright, cache-memory, repo-memory, safeoutputs, etc.) are engine-agnostic — 0 Copilot-only and 0 Claude-only tools (tools.md:20-210). Strong parity positive. Only ambiguous entry: web-search, which is engine-dependent (Codex disabled by default, tools.md:65-67).

Parity observation (engine-example-counter): Claude leads the inline-string engine: claude form (44 vs Copilot 32) but Copilot dominates the object id: form (93 vs 15), so effective Copilot exposure is ~2.6× Claude. Codex and Custom have materially weaker example parity.

Auth Gaps

• Quick-start does not state that Anthropic/OpenAI/Gemini accounts may require billing/credits (quick-start.mdx:30).
• No manual (non-wizard) secret-setup path beyond the tabbed gh secret set commands; relies on the wizard prompt (quick-start.mdx:77-114).
• Full auth detail (WIF keyless, OAuth-token caveat) lives at /reference/auth/, linked but not part of the quick-start flow (quick-start.mdx:81).
• GH_AW_PROJECT_GITHUB_TOKEN PAT scope documented only in the cli.md project section, not in the main prereq/auth list (cli.md:876-882).

Recommended Actions

Priority 1 — Add a Claude auth subsection to quick-start that (a) states OAuth subscription tokens are not supported and points to ANTHROPIC_API_KEY or WIF keyless, and (b) links the copilot-requests-style PAT-free guidance. Closes the single most persona-relevant gap (open 22 runs).

Priority 2 — Surface --engine claude in the quick-start add step and add a callout that omitting engine: silently defaults to Copilot. Give Gemini a secret block matching Codex.

Priority 3 — Add one why-Claude-vs-Copilot sentence, one standalone engine: custom example, and document the default Claude model + crush secret.

References: §28944070081 · §28868508537 · §29021096731

Generated by 📝 Claude Code User Documentation Review · 434 AIC · ⌖ 37.4 AIC · ⊞ 5.2K · ◷

• expires on Jul 10, 2026, 5:40 AM UTC-08:00

[github-actions[bot]]

This discussion has been marked as outdated by Claude Code User Documentation Review.

A newer discussion is available at Discussion #44727.