One document whose spec says where it starts
Six of seven served Markdown surfaces should carry frontmatter.
/auth.md is the seventh, and the reason is its own specification,
not the two points it happens to recover.
What the spec actually prescribes
A well-formed auth.md is organized as a numbered walkthrough an agent follows top to bottom. Here is what each section should cover:
Title and intro - A one-line title (# auth.md) followed by a short preamble addressed to the agent.
The walkthrough's first section is the title. A header block above it puts non-walkthrough content ahead of the document's own first step.
Keep the file conservative in length and high in signal. Anything an agent doesn't need to register or operate against your API belongs in your main documentation, not in auth.md.
The spec enumerates what a consumer extracts: headings, the Discovery section, fenced code blocks, and the PRM as authoritative. No metadata key is in that list.
Which surfaces keep it
| Surface | Frontmatter | Why |
|---|---|---|
/index.md, /docs/*.md | keep | no spec constrains their opening |
/pricing.md, /api-policy.md | keep | same |
/developers.md, /yonyon.md | keep | same |
/auth.md | remove | its spec prescribes the opening |
How we got here, including the part we got wrong
The guard
it("auth.md must NOT carry frontmatter, and opens with its own H1")
Verified to bite by
re-adding the block and watching it fail by name, then restoring from a file
copy rather than git checkout so the control could not revert unrelated
work. A guard that has never been seen to fail is not a guard.
Closes #3691. Reached with a peer session that hit the identical regression in another repo and corrected its own published justification when the spec did not support it.