Align the README With the Declared Structure

[ptr727]

Step 4, the last of the resync. Follows #89, #90 and #91.

Ten findings, all in the README, none of them visible to a reader who is not comparing it against the fleet model.

The retired section name, and what it broke

Use Cases is a retired name for Overview, which has no accepted aliases. Renaming it orphaned the Table of Contents anchor, caught by markdownlint as MD051 rather than shipping a link into nothing.

That is the whole reason a heading rename is not a one-line change, and it is the same class the hub's deletion sweep exists for: an inbound reference that breaks when its target moves. I swept for other inbound anchors to the old name and there were none.

The link definitions

Two structural problems:

• A Workflow group the model does not declare.
• The Repo group held six references to this repository's own GitHub pages, which the model classifies as distribution rather than local.

Rebuilt into the four declared groups it needs, each sorted by reference name:

Shields 5
Distribution 6 github, commits, discussions, issues, releases, actions
Repo 14 local paths only
External 4

All 29 definitions preserved, verified by count. The classification is not my reading of the URLs: it comes from the audit's own link_kind against the model's declared distribution.urlPrefixes, so it matches what the checker will decide rather than what looks right.

3rd Party Tools

• License column dropped. A license belongs to the dependency and is authoritative at its source, so restating it is a maintenance obligation carrying no information.
• Fleet descriptions adopted for all three rows, since a shared tool carries one description across the fleet rather than a per-repo paraphrase: Static site generator., Hugo theme., Web server.
• Alphabetized, Caddy before Hugo before PaperMod, because the list is scanned rather than read.

Verification

markdownlint-cli2 clean (it failed first on the orphaned anchor, which is the gate doing its job), prose_lint --diff HEAD clean, cspell clean on the gated files, editorconfig-checker clean.

After this

develop carries the whole resync. The two remaining audit findings on this repo are hub-only entries for publish-release.yml and validate-task.yml, both dispositioned investigate in the hub's ledger, which explicitly makes them not this repository's to settle.

The resync then wants promoting to main, since the audit reads main as ground truth and would otherwise still report the pre-resync state.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR completes the resync’s README alignment work by updating section structure and link-definition grouping so the document matches the declared fleet/model structure and passes markdown linting checks.

Changes:

• Renames the retired Use Cases section to Overview and updates the Table of Contents anchor accordingly.
• Simplifies and normalizes the “3rd Party Tools” table by removing the License column and standardizing tool role descriptions.
• Reorganizes link reference definitions into the declared groups (notably replacing the old “Workflow” group with “Distribution”) and reorders definitions for consistency.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.