You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
[deep-report] Docs: define "frontmatter" and explain .lock.yml in the Quick Start #32421
A fresh-user docs review (2026-05-15) found three critical onboarding traps in the Quick Start:
"Frontmatter" jargon used before defined — Step 4 of Quick Start references frontmatter with only a parenthetical aside. A first-time user has to re-read twice.
No explanation of .lock.yml — Step 4 mentions "the .md file you edit and a generated .lock.yml file that GitHub Actions runs" without explaining why there are two files or whether the user should ever touch the lockfile. Beginners interpret this as needing to hand-edit both.
Token-secret setup is fragmented — Setting up COPILOT_GITHUB_TOKEN spans multiple collapsible notes; new users miss the Account permissions → Copilot Requests → Read step.
Source: Documentation Noob Test Report — 2026-05-15.
Suggested Fix
Add a glossary callout (or one-sentence inline definition) for frontmatter the first time it appears in Quick Start.
Add a 2-sentence callout under Step 4 explaining: "You edit the .md source; gh aw compile regenerates the .lock.yml — never edit the lockfile by hand."
Convert the COPILOT_GITHUB_TOKEN setup into a single numbered checklist (PAT scope, account-vs-repo permission distinction, repo-secret command).
Activity
github-actions commentedon May 15, 2026
🍪 Issue Monster selected this for Copilot
I've identified this issue as a good candidate for automated resolution and requested assignment to the Copilot coding agent.
If assignment succeeds, the Copilot coding agent will analyze the issue and create a pull request with the fix.
Om nom nom! 🍪