[claude-code-user-docs-review] 🔍 Claude Code User Documentation Review - 2026-08-24

[github-actions[bot]]

Executive Summary

A Claude Code user (no Copilot) can complete the quick-start today using --engine claude, but hits one unresolved critical blocker that has now persisted across 3 consecutive daily reviews: a silently-ignored CLAUDE_CODE_OAUTH_TOKEN that produces a misleading auth error. Docs still frame Copilot as the implicit default (how-they-work.mdx:26, quick-start.mdx:118), and one CLI feature (custom agent + MCP wiring) remains Copilot-only.

Severity Findings (Critical → Major → Minor)

Critical Blockers

1. CLAUDE_CODE_OAUTH_TOKEN from claude login is silently ignored; the run instead fails with an API-key auth error that never mentions the token. Warning is buried inside a tabbed Claude section a user could skip. — quick-start.mdx:210-211, cli.md:282. Unresolved from the 2026-08-22 and 2026-08-23 reviews.

Major Obstacles

1. gh aw init --engine copilot creates a custom agent (.github/agents/agentic-workflows.md) and MCP wiring; no equivalent artifact is generated for Claude — cli.md:159, 177-184.
2. If the engine: field is manually removed from workflow frontmatter, the runtime silently falls back to Copilot rather than erroring or preserving the last engine — quick-start.mdx:118.
3. No inline walkthrough for creating ANTHROPIC_API_KEY; only a bare link to the Anthropic Console — quick-start.mdx:214.
4. Anthropic Workload Identity Federation (WIF) is named as a Claude auth alternative but never explained inline, with setup fully delegated to an external reference page — quick-start.mdx:211.

Minor Confusion

1. No guidance on when to prefer ANTHROPIC_API_KEY vs. WIF (single-repo vs. org use) — quick-start.mdx:209-215.
2. drive-memory and qmd tool entries don't state per-engine support, unlike other tools in the same table — tools.md:92-99, tools.md:112.
3. Pi engine auth isn't inlined in quick-start; fully deferred to /gh-aw/engines/pi/ — quick-start.mdx:232-234.

Engine & Tool Matrix

Engine	Setup clarity	Example coverage	Auth	Score
Copilot	Clear, default path, no extra account (quick-start.mdx:71)	115 workflows	copilot-requests: write or COPILOT_GITHUB_TOKEN	✅ Best
Claude	Partial — critical OAuth-token gotcha, no inline API-key walkthrough (quick-start.mdx:209-215)	63 workflows	ANTHROPIC_API_KEY or Anthropic WIF	⚠️ Usable, rough edges
Codex	Clear; notable caveat that web-search is disabled by default unless declared (tools.md:67-68)	47 workflows	CODEX_API_KEY (precedence) or OPENAI_API_KEY	✅ Good
Custom	Minimal documentation	1 workflow	N/A	⚠️ Sparse

Tool support (tools.md) is largely uniform across engines — 11 of 14 documented tools show full cross-engine support. Exceptions: web-search is off by default for Codex only; drive-memory (private preview) and qmd (experimental) don't state per-engine support at all.

Parity note: the Copilot:Claude example ratio narrowed from 2.3x (prior run) to 1.8x today, and Codex examples nearly tripled — directional improvement, but raw counts have swung widely across the three runs to date (39/39/11/1 → 60/138/15/47 → 63/115/47/1), which looks like counting-methodology drift between runs rather than confirmed doc churn. Treat trend direction as indicative, not precise.

Auth Gaps

• Critical: Claude's CLAUDE_CODE_OAUTH_TOKEN incompatibility warning is tab-hidden and the resulting CLI error gives no hint about the token — quick-start.mdx:209-211, cli.md:282.
• High: No step-by-step for creating ANTHROPIC_API_KEY (link-only) — quick-start.mdx:214.
• Medium: WIF mentioned without explanation for both Claude and Gemini paths — quick-start.mdx:211, 224-229.
• Medium: Codex key precedence (CODEX_API_KEY over OPENAI_API_KEY) stated without rationale or migration guidance — quick-start.mdx:222.
• Medium: Copilot fine-grained PAT flow says the browser page "must be completed manually" with no next-step detail — quick-start.mdx:203-207.

Recommended Actions

Priority 1 (blocks Claude users today)

• Move the CLAUDE_CODE_OAUTH_TOKEN warning out of the tabbed UI into a top-level callout before the engine picker, and make the resulting CLI error explicitly say "token type not supported, use ANTHROPIC_API_KEY" (quick-start.mdx:209-211, cli.md:282).

Priority 2 (friction, workable but rough)

• Add an inline 3-step ANTHROPIC_API_KEY creation walkthrough matching the Copilot PAT section's level of detail (quick-start.mdx:214).
• Document what gh aw init --engine claude produces vs. --engine copilot, or extend the custom-agent/MCP artifacts to Claude (cli.md:159-184).
• Change the silent Copilot fallback on missing engine: to a warning/error instead (quick-start.mdx:118).

Priority 3 (polish)

• Add a one-line recommendation (API key for solo/single-repo, WIF for org-wide) to the Claude/Gemini auth tabs.
• Fill in per-engine support for drive-memory and qmd in the tools table.

Generated by 📝 Claude Code User Documentation Review · claude · agent · 101.5 AIC · ⌖ 7.19 AIC · ⊞ 6.3K · ◷

• expires on Aug 25, 2026, 4:40 AM UTC-08:00