[deep-report] Docs: bundle 3 first-time-user friction points from Quickstart + CLI Commands page

[github-actions]

Description

Today's Documentation Noob Tester run (discussion #58711) surfaced 3 first-time-user friction points, none of them yet tracked by open issues (#58182 is about a doc-generator rendering bug, #58183 is about the Playwright/Chromium tooling gap — both distinct from these content/structure findings):

1. "Frontmatter" jargon reused without a back-reference. The Quickstart defines "frontmatter" inline on first use, but later references ("If you changed the frontmatter...") don't link back to that definition or a glossary entry, forcing a true beginner to recall a one-line parenthetical from paragraphs earlier.
2. No default guidance across 5 parallel authentication paths. The Quickstart's "Configuring authentication" step presents Copilot/Claude/Codex/Gemini/Pi as equal tabs with no inline steer on which to pick; the one hint ("If you already have GitHub Copilot, start there") lives in the earlier Prerequisites section and is easy to skim past.
3. CLI Commands reference page has no beginner/advanced visual separation. The page opens with a 100+ link sidebar/TOC before any content, and the one helpful callout ("New to gh aw? You can stop here...") is a single easy-to-miss Tip box in a long scroll that also interleaves GHES/Enterprise-only setup among basic commands.

Expected Impact

Reduces onboarding friction for first-time users on the exact path (quick-start → cli) that the project's own Quickstart promises takes 10 minutes — directly improves new-user conversion.

Suggested Fix

• Add an inline anchor link on "frontmatter" back to its Quickstart definition (or a short glossary entry) wherever it's reused.
• Promote the "start with Copilot if you already have it" guidance from Prerequisites into the authentication tabs section itself (e.g. a default-selected tab or a one-line callout directly above the tabs).
• Add a clear "Day-one commands" vs "Advanced/Enterprise" visual split on the CLI Commands page, and move GHES-specific setup out of the basic command flow.

Suggested Agent

Docs-focused agent (Copilot SWE Agent) with access to docs/setup/quick-start and docs/setup/cli sources.

Estimated Effort

Quick (< 1 hour) for the frontmatter anchor + auth callout; Medium (1-4 hours) for the CLI page restructure.

Data Source

DeepReport analysis 2026-09-05, sourced from Documentation Noob Tester discussion #58711.
Related to #56849

Warning

Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• api.anthropic.com

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "api.anthropic.com"

See Network Configuration for more information.

Generated by 🔬 Deep Report · claude · agent · 149.1 AIC · ⌖ 11.4 AIC · ⊞ 12.8K · ◷

• expires on Sep 6, 2026, 10:44 PM UTC-08:00