2026-05-14: Doc site consistency fixes
Problem
Section titled “Problem”Several inconsistencies discovered in the doc site after v1.2.1 was shipped:
- Sidebar not reversed: Individual release note files had
sidebar: order: Xfrontmatter overridingreversed: truein astro.config.mjs. Same issue in two plan files. - Release note title inconsistency: Older files used
"Release Notes — v1.X.X"prefix; v1.2.1 used plain"v1.2.1". - Badly named plan file:
2025-01-beta-feedback-plan.md(missing day DD) was a duplicate of the correctly named2026-05-01-beta-feedback-plan.md. - Plans index.md had no table: Unlike
releases/index.mdwhich lists all releases,plans/index.mdhad only a brief description. - dev-setup.md still mentioned Node 22: Tip header (
Node >=22 LTS — Node 24 recommended) and line 103 (Node ≥ 22 — already required) were still pointing to Node 22.
- F1 Remove
sidebar: order:fromv1-0-0,v1-1-0,v1-1-1,v1-1-2,v1-2-0+2026-05-01-beta-feedback-plan.md - F2 Standardize all release titles to
"v1.X.X"(5 files) - F3 Delete
2025-01-beta-feedback-plan.md(badly named duplicate) - F4 Rebuild
plans/index.mdwith full table of all plans, newest first - F5
dev-setup.md: update tip header + line 103 to say Node 24
AGENTS.md Checklist
Section titled “AGENTS.md Checklist”| # | Convention | Status |
|---|---|---|
| 1 | Doc site IS the deliverable | ✅ |
| 2 | All 4 test gates | ⏭ No code change |
| 3 | Self-review complete | ✅ |
| 4 | Endpoint coverage | ⏭ N/A |
| 5 | Bug-to-Test | ⏭ N/A |
| 6 | Seed isolation | ⏭ N/A |
| 7 | Transaction invariants | ⏭ N/A |
| 8 | Plan history | ✅ This file |
| 9 | cd docs && npm run build before + after | ✅ |
| 10 | Local Node 24, no Docker | ✅ |
| 11 | Baseline before changes | ✅ Passed (73 pages) |
| 12 | Execution summary | ✅ Below |
| 13 | Doc Grep Rule | ⏭ Changes ARE the docs |
| 14 | Patch release v1.2.2 | ✅ |
Execution Summary
Section titled “Execution Summary”Commit: TBD
Actual changes
Section titled “Actual changes”releases/v1-0-0.md,v1-1-0.md,v1-1-1.md,v1-1-2.md,v1-2-0.md— removedsidebar: order:block + updated title to"v1.X.X"formatplans/2026-05-01-beta-feedback-plan.md— removedsidebar: order:blockplans/2025-01-beta-feedback-plan.md— deleted (badly named duplicate)plans/index.md— rebuilt with full table listing all 36 plans newest-firstdev-setup.md— tip header + line 103 updated to Node 24
Deviations from plan
Section titled “Deviations from plan”None.
Test results
Section titled “Test results”| Gate | Result |
|---|---|
| Docs build (baseline) | ✅ 73 pages |
| Docs build (after) | ✅ 73 pages (1 deleted + 1 created = net 0) |
| Backend unit | ⏭ Not affected |
| Backend e2e | ⏭ Not affected |
| Frontend unit | ⏭ Not affected |
| Frontend e2e | ⏭ Not affected |
Key discoveries
Section titled “Key discoveries”sidebar: order:in individual files silently overridesreversed: truein astro.config.mjs — this was the root cause of sidebar ordering not working.