First-pass review only. These are mechanical findings from Netero; the full review panel has not yet reviewed this PR. The panel will review after these findings are addressed. These are defects worth resolving before the panel spends parallel review time.

The change is small and well-scoped: the generator sources are the only real diff (40 effective additions), the front-matter approach is clean, the extractSectionName rewrite keeps a sensible legacy # fallback, and the idempotency and chat.md-orphan reasoning check out (os.RemoveAll on reference/api/ does wipe and rewrite the directory each run, and no manifest or doc references to chat.md remain).

Severity count: 2 P2, 1 P3.

The two P2s are the same class and they contradict the PR body's central claim that "rendered output is unchanged." It holds for every section and command page (their front-matter title equals the manifest child title by construction), but not for the two index landing pages. The coder.com renderer precedence is frontmatter.title -> manifest route.title, and both renderers hide the body H1 and inject a single heading from the resolved title. So pre-PR these two pages took their rendered title (and Algolia lvl1) from the manifest, not from the removed H1. Post-PR the front-matter title wins and demotes them: REST API -> API and Command Line -> coder. That reaches production on merge, since docs markdown is fetched from mainline at request time.

The P3 is a latent gap, not a live break: the current output is correct, but the rewritten parser now derives every API page's filename, section title, and manifest route title with zero test coverage. As Netero put it, a future regression there produces "wrong-but-idempotent output, so the committed-golden make gen diff check in CI would not catch it."

Note that CI currently shows the title check failing; worth confirming that is unrelated (PR-title lint) before merge.

🤖 This review was automatically generated with Coder Agents.

Round 2. The three round-1 findings are all genuinely fixed, verified at the code by the panel, not just claimed: the API index emits title: REST API and the CLI index emits title: Command Line via the new atRoot branch (both matching their manifest routes), and extractSectionName now has a real table test that reaches 100% of the rewritten parser. swagger.json and manifest.json are byte-identical to main, so route topology and API annotations are untouched. Nice, tight diff with no scope creep.

One thing to fix before this is done, and two claims in the PR body to correct.

Severity count (new this round): 1 P2, 3 P3, 1 Nit, 2 Note.

The P2 is the one that matters: the migration missed a sibling. Three reviewers independently traced it. security.def (pulled into main.dot via {{#def.security}}) still emits a bare # Authentication, so authentication.md is the single generated API page with no front-matter title. It renders fine today because the manifest title matches and the legacy # fallback still parses it, but that means the fallback is load-bearing for a shipped page, and this PR's own goal ("once docs migrate to front-matter titles, make gen will no longer revert them") fails for exactly this page: any future title: added to authentication.md is overwritten on the next make gen. The fix is a two-line template change plus a regenerate.

Two PR-body claims are inaccurate (both harmless to the outcome, worth correcting):

• "a YAML front-matter title: block at byte 0 of every generated file" is false while authentication.md keeps its H1 (see the P2).
• The chat.md deletion rationale ("the postprocessor wipes and rewrites reference/api/ each run") is false: make gen runs the generator against a _gen tmpdir and then moves files back per-file (Makefile:1361-1367), so os.RemoveAll hits the tmpdir, not docs/. Stale files are not auto-removed; the explicit deletion in this PR is what removes chat.md. (I got this wrong myself in round 1; Mafuuu caught it.)

The P3s are a real-but-modest dead doc anchor, an unquoted-YAML-title foot-gun the migration introduces, and a parse error with no locator. Leorio on that last one: "That is a doctor saying 'one of your organs is failing' and walking out."

Process is honest: the PR discloses that make gen/make fmt was not run end-to-end and stays a draft until CI is green; markdownlint and the table formatter pass locally on the changed pages.

scripts/apidocgen/markdown-template/security.def:2

P2 [CRF-4] The Authentication section producer still emits a bare # Authentication, so authentication.md is the one generated API page this migration leaves behind. (Melody P2, Razor P2, Zoro P2)

two of three producers were rewritten, security.def was not ... authentication.md alone keeps a legacy # Authentication. The blanket "every generated file" claim is therefore false.

Verified: security.def is included by main.dot:92 via {{? ...securitySchemes }}{{#def.security}}. swagger.json is OpenAPI 2.0 (securityDefinitions), which widdershins converts to components.securitySchemes, so the guard is true and the section is emitted every run. Empirically, authentication.md is the only docs/reference/api/*.md whose first line is not ---, and its content equals security.def.

Consequences: (1) rendered output is unchanged today (manifest title Authentication matches, both renderers hide the body H1), so nothing regresses now; (2) the extractSectionName legacy # fallback is load-bearing for this page, not defensive; (3) this defeats the PR's stated purpose for authentication.md specifically: a future front-matter title: added there is reverted on the next make gen. Fix: replace # Authentication with ---/title: Authentication/---, matching the two main.dot producers, then regenerate.

🤖

docs/support/support-bundle.md:73

P3 [CRF-5] Removing the page-title H1 from every generated CLI/API page deletes the page-slug heading anchor, and one live in-repo link now points at a fragment that no longer exists. (Hisoka P3, Pariston P3)

login.md used to open with # login (anchor #login); it now opens with front matter and its first heading is ## Usage, so #login is gone ... docs/support/support-bundle.md links to exactly that fragment.

Verified: grep '^#' docs/reference/cli/login.md no longer yields a login heading (first is ## Usage); support-bundle.md:73 links to ../reference/cli/login.md#login. This is a one-instance class in-repo (Hisoka checked all 68 fragment links into reference/cli|api; every other one targets a surviving ##/### heading). Consequence is modest (the dead #login targeted the top of the page, so the reader lands at the top anyway), but it is a broken fragment on the raw/GitHub surface, and pnpm check-docs does not validate cross-file fragments so CI stays green. Fix: repoint the link to a live section or drop the fragment.

🤖

docs/manifest.json:1688

Note [CRF-10] reference/cli/index.md is targeted by two manifest routes with different titles: the parent group route Command Line (line 1688) and a self-referential child coder (line 1704). (Pariston, Ryosuke)

Not re-raising CRF-2 (fixed). resolveDocTitle(attributes, routeTitle) takes a single already-selected routeTitle, so the renderer binds index.md to one of these routes before front matter is consulted. The CRF-2 fix (title: Command Line) is correct if the nav binds to the parent route; if it binds to the coder child, the pre-PR title was coder and the fix changes it to Command Line. Benign either way (Command Line is the better label), and the manifest is byte-identical to main so this PR did not introduce it. Worth a one-line confirmation from whoever owns the coder.com renderer.

🤖

🤖 This review was automatically generated with Coder Agents.

Round 3, fix verification. Every round-2 finding is genuinely fixed at the root, verified by the panel and not just taken from the inventory:

• CRF-4 (P2): all three API section producers now emit front matter (main.dot resource loop, main.dot Schemas, and security.def), authentication.md is migrated, and every file under docs/reference/{api,cli}/ now leads with ---. The class is closed, not the instance.
• CRF-5 (P3): the support-bundle.md link dropped the dead #login fragment, and the page-slug-anchor class was swept clean (no remaining <page>.md#<page> self-title links anywhere in docs/).
• CRF-7 (P3) / CRF-8 (Nit): both errors name the failure mode and the legacy branch echoes the offending line; both prefix strips use CutPrefix.
• CRF-9 (Note): the PR body's chat.md rationale is corrected to the verified tmpdir/per-file-move behavior.

swagger.json and docs/manifest.json remain byte-identical to main, so there is no route or API-annotation drift.

CRF-10 (the dual cli/index.md manifest route) is closed as benign: five reviewers concurred that under front-matter precedence the page resolves to Command Line regardless of which route the nav binds, so the CRF-2 fix is robust to it. The only residual is the manifest-sourced sidebar label (coder), which is unchanged from main. One small consistency note: the PR body's universal claim "each page's front-matter title matches its manifest route" is not literally true for this one dual-route page, so consider qualifying it.

Severity count (new this round): 1 P3, 1 Note, 1 Nit.

The one P3 is the other half of CRF-7: the locator was added to the legacy branch, but the front-matter-with-no-title branch, which is now the primary path since every producer emits front matter, still names no section, and its two tests assert only the locator-less message. It is latent today (all producers emit a titled block), so it does not block, but it is exactly the diagnosability CRF-7 set out to provide, on the branch that matters most.

Nit (not inline, no diff line): the commit subject fix(docs): address round-2 review states the ritual, not the change. Leorio: "a reader bisecting to 'why does security.def emit front matter?' lands here and learns only that a review happened." Near-zero impact if this is squash-merged under the (good) PR title.

This PR is essentially ready: the only open code item is the latent P3 above, plus the already-ticketed CRF-6 (DOCS-596).

🤖 This review was automatically generated with Coder Agents.

Round 4. CRF-12 is genuinely fixed and the PR has converged. The front-matter-no-title parse error now appends a compact section preview via the new sectionPreview helper, so the now-primary parse branch is locatable in make gen output (not just the legacy # path), and the error-path tests assert the section content actually reaches the message rather than just asserting an error occurred. extractSectionName is 100% covered. The commit is squashed under a descriptive subject (CRF-13), and the PR body now qualifies the dual-route cli/index.md claim.

Everything substantive across four rounds is resolved: CRF-1..CRF-9 and CRF-12 fixed, CRF-10 closed benign, CRF-11 accepted (defensive fallback kept), CRF-13 fixed, CRF-6 deferred with a real ticket (DOCS-596). swagger.json and docs/manifest.json remain byte-identical to main, so there is no route or API-annotation drift.

Approving. The three items below are all non-blocking (2 Notes + 1 Nit) and do not need to hold the merge.

Severity count (new this round): 1 Nit, 2 Note.

One process note on severity: a reviewer rated the comment-verbosity items P2; I downgraded them to a single Nit. Comment narration where the code works is a style/convention issue with no runtime or correctness consequence, and the same reviewer's own note conceded it is "not per-line severity." Bisky on the test suite: "not one of them is the same outfit on the same body."

One thing to confirm before merge that is outside this PR's diff: CI. The PR is a draft pending the gen/fmt check; the front-matter output is idempotent and lint-clean locally, but let the make gen/make fmt CI check go green before merging.

🤖 This review was automatically generated with Coder Agents.