docs: the docs were only readable one page at a time on github.com

[skyoo2003]

Summary

Publishes docs/ as a searchable Hugo site at https://skyoo2003.github.io/devcloud/, built from the same twenty markdown files github.com renders rather than a copy of them.

Related Issue

N/A — no tracking issue.

Changes

The constraint that shaped everything: docs/*.md are read two ways now, so they gain no front matter and keep their plain relative links. Hugo mounts the directory instead of copying it, and docs/README.md becomes the home page rather than a duplicated _index.md.

• hugo.toml — mounts, and the sidebar order as [menu.before]. Every entry needs its own identifier; entries carrying only pageRef share the empty identifier and collapse into one surviving link.
• layouts/_markup/render-link.html — resolves the 83 links inside docs/ to site URLs and rewrites the 46 that escape it (../internal/gateway/router.go, ../CONTRIBUTING.md) to GitHub blob/tree URLs instead of 404s.
• layouts/_partials/docs/title.html — titles from each page's H1. The theme's filename fallback produces "Crud Engine", "Faq" and "Iam Sts"; the fix it expects is a title key on all twenty documents, which github.com renders as a metadata table above every page.
• layouts/_partials/docs/menu-filetree.html — empty, so the sidebar comes from config. Hugo sorts pages alphabetically without weight, which buries Getting Started at position ten.
• scripts/check-site-links.py — the render hook cannot fail loudly, because an unresolvable link is indistinguishable from a legitimate one leaving docs/. A renamed page would quietly become a GitHub URL that goes nowhere. This checks the built output instead.
• .github/workflows/pages.yml — builds on pull requests too (the link check is the gate), deploys only from main. Hugo pinned to 0.165.0; actions pinned by SHA, matching lint.yml.
• themes/hugo-book as a submodule rather than a Hugo module, so hugo mod init never touches the root go.mod that belongs to the Go program.
• Makefile — docs-serve, docs-build; clean now also removes public/ and resources/.
• docs/contributing.md — a Documentation section stating the no-front-matter rule and that a new page needs a [menu.before] entry to appear in the sidebar.

Known wart: hugo.toml keeps the deprecated module.mounts.excludeFiles. Its replacement files does not filter mounts as of Hugo v0.165.0 — six patterns and a mount reorder were all silently ignored — and without it README.md is built twice, as the home page and again as /readme/. The reasoning is recorded at the call site; it costs one deprecation warning per build.

Test Plan

• make docs-build — 29 pages, 887 internal links all resolve, no errors.
• Link checker verified in both directions: passes on a clean build, and exits 1 naming all 28 inbound links when a page is removed from public/.
• Sidebar verified as 19 entries in the intended order, services nested, every title taken from its H1.
• Escaped links spot-checked in the output: ../internal/auth/auth.go → blob/main/…, ../internal/auth/ → tree/main/…, ../TRADEMARKS.md → repository root.
• BookEditLink corrected — it was emitting edit/main/docs/docs/… because .Path already arrives prefixed.
• Served locally (hugo server): / and /getting-started/ both 200; search index (99 KB), mobile nav and colour-scheme toggle present in the output.
• pre-commit run --all-files passes.

Not yet exercised: the deploy job. GitHub Pages is already set to build_type: workflow with no build history, so the first real deployment happens when this merges.

Checklist

• Self-reviewed the code
• Added/updated tests — scripts/check-site-links.py, which CI runs on every pull request; verified it fails when a page goes missing
• Lint/format passes — no Go files changed, so golangci-lint has nothing to say; pre-commit (ruff, ruff-format, yaml, whitespace) passes
• Updated documentation (if applicable)
• Added a Changie changelog fragment for user-facing changes