fix: give repeated documentation headings distinct anchors

[steipete]

Summary

Give repeated documentation headings distinct anchors and table-of-contents destinations. The generated Cache, Capsules, and Agent Sandbox pages currently reuse heading IDs, so selecting the later TOC entry jumps to the earlier section.

Reuse the link checker's existing per-document collision allocator in the renderer. First-occurrence URLs remain unchanged; literal suffix collisions remain safe. The Markdown parsers and slug normalization rules stay separate, and no dependency is added.

Verification

• Added regressions first: both the four-heading collision sequence and real generated Cache TOC test fail on the previous renderer.
• After the fix, node --test scripts/check-docs-links.test.js scripts/build-docs-site.test.js: 17 passed, 0 failed, 0 skipped.
• scripts/check-docs.sh passed, including a fresh site build, generated-page tests, links, discovery, and navigation checks.
• git diff --check and managed pre-commit review passed with no actionable findings.

Real Chrome proof

Verified through the actual Chrome extension browser against locally built documentation, not an isolated browser or DOM-only substitute. On the tested main baseline (14ca854eb1f417a46ad621dc3cd22768a898e861), clicking the later cache volumes item in the Cache Controls page's table of contents navigates to #cache-volumes and displays the earlier Cache volumes overview. With the integrated fix (bba8e5e5fdd46de9ea80455b736cb9a6740054e9), that item navigates to #cache-volumes-1 and displays the intended command section and its examples.

The attached captures show the settled rendered destinations after the same real click. They contain only public project documentation; the task-owned tab and all three loopback proof servers were closed afterward. The initial mid-scroll capture was not used.

The updated branch retains only the six-file anchor allocation change against current main. The 17 targeted tests pass with no skips, and the complete docs check passes, including the generated site, links, discovery, and navigation checks. Managed Codex review is P0 scoped-clean. The Unreleased entry is maintainer-added; published 0.50.0 and older release notes are unchanged.

Current head ae7be4cc2aa70a1dd476b9619a54ac181744dcbe integrates the Freestyle landing without changing the renderer, shared allocator, link checker, or Cache Controls source used in this browser proof.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed September 6, 2026, 4:04 AM ET / 08:04 UTC.

ClawSweeper review

What this changes

The PR shares collision handling between the documentation renderer and link checker so repeated headings receive distinct links, with regression coverage and an Unreleased note.

Merge readiness

✅ Ready for maintainer review

This remains a useful, focused fix: current main and v0.50.0 still generate duplicate heading destinations. No blocking correctness findings remain, and the revision-specific browser proof still applies.

Priority: P3
Reviewed head: ae7be4cc2aa70a1dd476b9619a54ac181744dcbe

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	A focused repair with relevant regressions and applicable browser proof; no blocking defects were found.
Proof confidence	🐚 platinum hermit (4/6) ✨ media proof bonus	Sufficient (linked_artifact): The captured Chrome report exercises the generated Cache page through an actual TOC click and records the corrected command-section destination after the fix; the exercised production files are unchanged at HEAD. Attachment access failed here, so the assessment preserves the revision-specific report without claiming independent image inspection.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Verified	Sufficient (linked_artifact): The captured Chrome report exercises the generated Cache page through an actual TOC click and records the corrected command-section destination after the fix; the exercised production files are unchanged at HEAD. Attachment access failed here, so the assessment preserves the revision-specific report without claiming independent image inspection.
Evidence reviewed	8 items	Repository policy: Read the complete root policy; no ancestor-scoped policy exists under the changed scripts paths, and no maintainer-notes directory was present. Applied documentation testing and maintainer-owned changelog guidance. Current main still has the defect: The main renderer assigns slug(text) directly to each heading without recording prior IDs. Cache documentation contains both 'Cache volumes' and 'cache volumes', which normalize identically; the table-of-contents builder copies rendered IDs. Latest release also lacks allocation: Inspected the v0.50.0 renderer: it likewise assigns the raw slug directly. The release tag resolves to the supplied release commit.
Findings	None	None.
Security	None	None.

How this fits together

Crabbox’s documentation builder turns Markdown into static pages and derives each page’s table of contents from its rendered headings. Heading IDs determine where section links and browser navigation land.

flowchart LR
  A[Markdown headings] --> B[Documentation renderer]
  B --> C[Per-page anchor allocation]
  C --> D[HTML section IDs]
  D --> E[Table of contents]
  E --> F[Browser section navigation]
  G[Markdown link checker] --> C

Loading

Before merge

None.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Production and test growth	production +8 net lines; tests +23 net lines	The small production increase shares an existing allocator and is supported by collision and generated-page regressions.

Technical review

Best possible solution:

Use the shared per-document allocator to keep section destinations unique while retaining existing first-occurrence links and slug normalization.

Do we have a high-confidence way to reproduce the issue?

Yes: current main renders the two Cache volumes headings with the same ID and copies that ID into both table-of-contents links; the supplied browser report demonstrates the corresponding wrong destination.

Is this the best way to solve the issue?

Yes: extracting and reusing the checker’s collision allocator repairs the renderer without introducing competing normalization rules or dependencies.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning medium; reviewed against bcd8ffc9bb5f.

Labels

Label justifications:

• P3: This repairs documentation navigation with a small, isolated change and no core runtime impact.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (linked_artifact): The captured Chrome report exercises the generated Cache page through an actual TOC click and records the corrected command-section destination after the fix; the exercised production files are unchanged at HEAD. Attachment access failed here, so the assessment preserves the revision-specific report without claiming independent image inspection.
• proof: sufficient: Contributor real behavior proof is sufficient. The captured Chrome report exercises the generated Cache page through an actual TOC click and records the corrected command-section destination after the fix; the exercised production files are unchanged at HEAD. Attachment access failed here, so the assessment preserves the revision-specific report without claiming independent image inspection.

Evidence

What I checked:

• Repository policy: Read the complete root policy; no ancestor-scoped policy exists under the changed scripts paths, and no maintainer-notes directory was present. Applied documentation testing and maintainer-owned changelog guidance. (AGENTS.md:1, ae7be4cc2aa7)
• Current main still has the defect: The main renderer assigns slug(text) directly to each heading without recording prior IDs. Cache documentation contains both 'Cache volumes' and 'cache volumes', which normalize identically; the table-of-contents builder copies rendered IDs. (scripts/build-docs-site.mjs:365, bcd8ffc9bb5f)
• Latest release also lacks allocation: Inspected the v0.50.0 renderer: it likewise assigns the raw slug directly. The release tag resolves to the supplied release commit. (scripts/build-docs-site.mjs:365, 215115a45086)
• Focused repair and regressions: The renderer creates one anchor set per document and uses the checker’s existing collision algorithm. Tests cover repeated headings, literal suffix collisions, document isolation, and both generated Cache table-of-contents destinations. (scripts/build-docs-site.test.js:383, ae7be4cc2aa7)
• Browser proof remains applicable: The captured PR body reports an actual Chrome click on the later Cache entry: baseline 14ca854 reached the earlier overview, while bba8e5e reached the intended command section at #cache-volumes-1. Comparing that proof revision with HEAD found no changes to the renderer, allocator, checker, or Cache source. Source snapshot identity: e79a3b8f2ae37ba68cb7a5d2e13a2802549885ac5fb8b0e546bc71ba0d738726. (scripts/build-docs-site.mjs:368, ae7be4cc2aa7)
• Proof inspection limitation and review continuity: Both supplied GitHub attachment fetches returned cache misses, so independent visual inspection remains unavailable. This does not invalidate the captured revision-specific browser report or require contributor follow-up. The previous completed review had no findings; the current body explicitly identifies the Unreleased note as maintainer-added.

Likely related people:

• kiranmagic7: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)
• Yossi Eliaz: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

History

Review history (2 earlier review cycles)

• reviewed 2026-09-04T04:37:37.953Z sha e9dcf4f :: needs real behavior proof before merge. :: [P3] Leave the changelog entry to a maintainer
• reviewed 2026-09-06T07:53:07.322Z sha bba8e5e :: blocked before merge. :: none