[claude-code-user-docs-review] 🔍 Claude Code User Documentation Review - 2026-10-29

[github-actions[bot]]

Executive Summary

A Claude Code user (no Copilot account) can fully install, configure, and run gh-aw without ever touching Copilot — Claude has its own setup page, a complete auth story, and a full worked example. No critical blockers were found this run — a first since tracking began (prior runs consistently found 1–2). The remaining friction is subtler: a dangling cross-reference, undisclosed default agent behavior, and persistent Copilot-centric framing in reference pages that makes Claude feel like a secondary path even though it fully works.

Severity Findings

Critical Blockers / Major Obstacles / Minor Confusion

Critical Blockers: none found this run. (Historical note: a CLAUDE_CODE_OAUTH_TOKEN wording contradiction between auth.mdx:221 and cli.md:287 was flagged in prior daily reviews back to 2026-08-22; it did not reproduce this run — all citations now consistently describe subscription OAuth tokens as unsupported.)

Major Obstacles

1. Dangling cross-reference — reference/auth.mdx:223 promises "additional configuration needed when using Claude with GitHub MCP" on the engines page, but reference/engines.md:12-27 contains no such content (just the engine comparison table). Fix: add the missing section or remove the pointer.
2. Model alias confusion — reference/engines/claude.md:51 remaps sonnet/opus/haiku to gh-aw's own alias table rather than Claude Code's native model meaning, and this isn't mentioned on the beginner-facing engines/claude.md setup page at all.
3. Undisclosed default agent behavior — Claude's default permission mode is dontAsk, and bare mode restricts native tools to Bash/Edit/Read (reference/engines/claude.md:35-37, :63-71). The main getting-started page (engines/claude.md:41-52) never mentions either, so a user following only the quick path won't know what the agent is allowed to do.
4. Add-wizard secret gap — setup/cli.md:207 documents ANTHROPIC_API_KEY setup only for the pull-request installation path; direct-push installs are left unexplained (a gap still unfixed from the prior run).
5. Unspecified MCP token — the Claude example workflow uses tools.github.toolsets (engines/claude.md:18-39), implying GitHub MCP access, but no page states what token/permission that needs beyond the Anthropic key.

Minor Confusion

• Copilot-billed path (model: copilot/auto) is presented as an equal alternative to an Anthropic key (engines/claude.md:6,12) without flagging that it still requires an org Copilot subscription.
• engine.max-turns is deprecated in favor of top-level max-turns, but both appear side-by-side in the shared feature matrix (reference/engines.md:33,47).
• Quick-start prerequisites list Copilot first and say it "requires no extra account setup" (setup/quick-start.mdx:70), subtly steering readers toward Copilot before Claude appears as an equal option at :125.
• Claude web search is opt-in only, unlike other engines' defaults (reference/tools.md:128).
• --settings auto-insertion is documented only for the Copilot-routed path (reference/engines/claude.md:27), leaving native-Anthropic users unsure if it applies.
• auto model resolution differs depending on Copilot-billed vs. native route (reference/engines/claude.md:29,51).

Engine & Tool Matrix

Engine	Setup Clarity	Examples	Auth Instructions	Score
Copilot	Clear — default engine, 2 auth paths	81 frontmatter refs / 38 files; 1 full tutorial + many snippets	Full: copilot-requests permission or PAT	5/5
Claude	Clear auth; partial config (dangling MCP link)	17 frontmatter refs / 11 files; 1 full tutorial	Full: ANTHROPIC_API_KEY, WIF, Copilot-billed alt; OAuth explicitly unsupported	4/5
Codex	Clear	8 frontmatter refs / 7 files; 1 full tutorial	CODEX_API_KEY/OPENAI_API_KEY, Copilot-billed alt, Azure OIDC	4/5
Custom	Partial — import-based; sample defs explicitly "not supported"	0 frontmatter form (uses engine.id object); no end-to-end tutorial	Defers to each definition; threat detection silently falls back to Copilot	2/5

Parity observations (from engine-example-counter):

• Copilot is the explicit default — reference/engines.md:16 labels it "(default)"; omitting engine: selects it.
• Docs-wide example ratio copilot:claude ≈ 4.8:1 (81:17) this run — narrower than some prior runs (~7:1) but still lopsided.
• Per-engine getting-started pages (engines/copilot.md, engines/claude.md, engines/codex.md) are near-parity in depth (~50 lines each, one worked "daily report" example) — the imbalance is concentrated in reference/pattern pages (e.g. reference/imports.md:16 uses engine: copilot as the default illustration), not the core tutorials.
• No dedicated custom-engine tutorial exists; reference/third-party-agent.md:37 explicitly calls its sample definitions "not supported gh-aw engines."
• Custom-engine and Gemini/Pi threat detection silently default to Copilot credentials (reference/threat-detection.md:321-325; reference/engines/gemini.md:12; reference/engines/pi.md:19) even when the main workflow engine is non-Copilot.

Auth Gaps

• Claude: ANTHROPIC_API_KEY via gh aw secrets set (reference/auth.mdx:211-212), or Anthropic WIF (:227-269), or Copilot-billed model: copilot/auto with copilot-requests: write (engines/claude.md:12). CLAUDE_CODE_OAUTH_TOKEN / subscription login is explicitly unsupported (reference/auth.mdx:219-221; setup/cli.md:287) — consistent across all citations this run.
• Dangling promise: reference/auth.mdx:223 references "additional configuration ... for Claude with GitHub MCP" on the engines page, which doesn't exist (reference/engines.md:12-27).
• gh aw init still scaffolds Copilot-only artifacts (custom agent file, .github/mcp.json, copilot-setup-steps.yml) by default; setup/cli.md:153,159,172-181 says Claude users must pass --engine claude to avoid this.
• Add-wizard Claude secret instructions exist only on the PR install path (setup/cli.md:207), not direct-push.

Recommended Actions

Priority 1

• Fix the dangling reference/auth.mdx:223 → reference/engines.md cross-reference (add the missing GitHub MCP + Claude content, or remove the claim).
• Document the direct-push ANTHROPIC_API_KEY setup path in setup/cli.md alongside the existing PR-path instructions.

Priority 2

• Surface Claude's default permission mode (dontAsk) and bare-mode tool restrictions on engines/claude.md itself, not only the deeper reference page.
• Add a one-line note on engines/claude.md that sonnet/opus/haiku are gh-aw aliases, not Claude Code's native model names.

Priority 3

• Rebalance reference/pattern-page examples (imports.md, model-routing, cost-management) to show Claude alongside Copilot rather than defaulting illustrations to Copilot.
• Explicitly flag the Copilot-subscription requirement wherever the Copilot-billed model: copilot/auto path is offered as a Claude alternative.

---

Automated daily documentation review from a Claude-Code-only user's perspective. Findings tracked in cache-memory/review-history.jsonl for trend analysis.

Generated by 📝 Claude Code User Documentation Review · claude · agent · ~52 AIC · ⌖ ~1 AIC · ⊞ 1.6K · ◷

• expires on Oct 30, 2026, 4:39 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 #73040.