Context

Two independent docs audits on 2026-06-03 surfaced the same onboarding friction:

1. Claude Code User Docs Review (#36654, M1, persona-critical): CLAUDE_CODE_OAUTH_TOKEN is not supported — only a pay-as-you-go ANTHROPIC_API_KEY works, and OAuth tokens (Claude Pro/Max/Teams) are silently ignored. This is documented only in reference/auth.mdx:121-123 and reference/faq.md:337-339, never in onboarding. A Claude Code user assumes their subscription auth carries over and hits a wall.
2. Docs Noob Test (#36577): the term "frontmatter" is used in the Quick Start with no definition — opaque to anyone who hasn't used Jekyll/Hugo/Astro.

Task

In the quick-start docs (docs/.../setup/quick-start):

• Add a callout near the ANTHROPIC_API_KEY step: "Claude Code / Max / Pro subscription OAuth tokens are not supported — gh-aw needs a separate Anthropic API key (billed per use)."
• Add a one-line parenthetical defining frontmatter on first use (e.g. "the configuration block between the --- markers at the top of the file").

Acceptance criteria

• Both clarifications appear in the onboarding/quick-start flow (not only in reference pages).
• Links/anchors render correctly in the docs site build.

Effort

~1h, mechanical docs edit. Suggested agent: a docs agent.

Source: #36654 (M1), #36577. Identified by DeepReport 2026-06-03.

Generated by 🔬 DeepReport - Intelligence Gathering Agent · opus48 18.3M · ◷

• expires on Jun 5, 2026, 4:17 PM UTC