[schmitch]

Fixes #521

What

#623 (for #622, which duplicated this issue) built the site at https://forgepkg.github.io/forge/ with mdBook, cargo xtask docs and the Pages workflow. That covers most of #521. Two items are still open: the READMEs under deploy/ should be pages of the site, and the repository's About section should link it. This PR does the first. A pull request can't make the second change (see below).

• docs/SUMMARY.md lists the Helm chart's (deploy/helm/forge/README.md), the Kubernetes manifests' (deploy/kubernetes/README.md) and the monitoring examples' (deploy/monitoring/README.md) READMEs under Running Forge, after the deployment guide. The issue names the first two. The monitoring README is the same kind of operator guide (the deployment guide's Telemetry section links it), so it's included as well.
• xtask/src/docs.rs: a README other than the repository's is now named after its directory on the site: deploy-helm-forge.html, deploy-kubernetes.html, deploy-monitoring.html. Before, all three would have become readme.md. The site stays flat because the rewritten links name pages from its root. The READMEs' own links resolve from their directories, like any page's. A link to another page goes to that page (the deployment guide now links the chart and manifests pages instead of GitHub). A link to a file such as values.yaml, ci/ or alerts.yaml goes to GitHub. A new test covers this.
• docs/README.md, the index GitHub shows for docs/, links the three pages, as the staging requires.
• CI: ci-changes.sh adds deploy to the group that runs fmt, so a change to deploy/ runs cargo xtask docs --check. The READMEs link files there, so renaming e.g. values.yaml can break a link. fmt builds only xtask. Pages also deploys on a push that changes deploy/**/README.md.
• Docs: DEVELOPMENT.md's Documentation site section, book.toml's comment and the module docs name the new pages.

Repository settings (admin)

The About section's website field is still empty. The issue asks for it to point at the site. Setting it needs a repository administrator: on the repository's main page, the gear next to About → Website: https://forgepkg.github.io/forge/.

How it was checked

• cargo xtask docs --check: 15 pages (12 + 3), every link resolves. cargo xtask changelog --check, cargo fmt --all --check, cargo clippy -p xtask --all-targets -- -D warnings and cargo test -p xtask (33 + 1) pass.
• Built with mdBook 0.5.4. The new pages add no warnings; the two left come from CHANGELOG.md's raw <user>/<name> tags, as before. In the HTML, all 422 links between pages reach a page and an id, no .md link is left, and all 32 links into the source tree name a path that exists. A search for honor_labels finds the monitoring page, and the sidebar shows the three pages under Running Forge.
• ci-changes.sh on a probe commit that touches only deploy/monitoring/README.md: changelog=true (so fmt runs) and kubernetes=true, every other group false.

Changelog

docs/changes/2.2.0/521.docs.md, the issue's milestone.

---

Generated by Claude Code