docs(api): publish Doxygen API reference to GitHub Pages + ADR-0027 (M7.1)

[danielPoloWork]

Summary

Closes ROADMAP item 7.1 — Doxygen-generated API documentation published as a static site — the first step toward v1.0.0. The public-header Doxygen contract is now built into a dependency-free static HTML site, gated warn-as-error on every PR and published to GitHub Pages on push to master.

Motivation

ADR-0013 settled the documentation format (Doxygen for the API contract, Markdown for the narrative) but explicitly deferred the rendering pipeline to M7.1 (§4: "the final pick is M7.1's choice"; §5 sketched a warn-as-error Doxyfile "added in M7.1"). This PR makes that decision and implements it.

Changes

• ADR-0027 records the pipeline decision: Doxygen HTML → GitHub Pages via the official Pages Actions, no external doc toolchain (the MkDocs/Sphinx-Breathe unified narrative site is deferred post-v1.0), PROJECT_NUMBER single-sourced from version.hpp, and a gate that validates documentation correctness (malformed commands, unresolved cross-references, stale @param names) rather than ceremonial exhaustiveness — refining ADR-0013 §5.
• docs/doxygen/Doxyfile — checked-in partial config: public headers only (EXTRACT_PRIVATE = NO), WARN_AS_ERROR = FAIL_ON_WARNINGS, dependency-free HTML (built-in theme + treeview, HAVE_DOT = NO), PBR_MEMORY_POOL_DIAGNOSTICS=1 predefined so the ADR-0019 iterator surface renders.
• docs/doxygen/mainpage.md — hand-written landing page linking out to the GitHub-rendered narrative.
• .github/workflows/docs-site.yml — builds the reference as a warn-as-error gate on PRs (no deploy, so PRs are never blocked by Pages config) and builds + deploys to Pages on master via upload-pages-artifact / deploy-pages.
• Three public-header comments gain the Doxygen % auto-link escape (::%operator new / ::%operator delete) to silence spurious unresolved-link warnings on the global operators. Comment-only — no API or behavior change.
• Doc sync: ROADMAP 7.1 flipped, ADR index row, README docs-site badge + API-reference pointer, CHANGELOG Unreleased.

Design Patterns

• None — straightforward tooling / documentation-infrastructure work. (The patterns catalogued by the project are unaffected; the M7.5 catalogue audit is a later item.)

Verification

• Builds cleanly on the full toolchain matrix — header changes are comment-only %-escapes inside existing Doxygen blocks; no code change.
• Unit tests pass — N/A to behavior; no source logic touched.
• clang-tidy clean on the diff — comment-only header edits.
• ASan + UBSan clean (TSan when threading is involved) — N/A, no runtime change.
• Valgrind: ERROR SUMMARY: 0 errors from 0 contexts — N/A, no runtime change.
• Benchmark numbers attached (when perf-relevant) — N/A.
• Doxygen build verified locally (1.10.0): zero warnings under WARN_AS_ERROR = FAIL_ON_WARNINGS; build/doxygen/html/index.html generated.
• markdownlint clean on changed Markdown (CI-enforced rule set).

Documentation Impact

• README.md updated — docs-site badge + published API-reference pointer.
• ROADMAP.md checkbox flipped — 7.1, with an implementation note.
• ADR added/updated — ADR-0027 (Accepted) + index row.
• docs/patterns/README.md updated — N/A, no pattern introduced.
• Spec updated — N/A, no behavior divergence.
• CHANGELOG.md updated — Unreleased Added (M7.1) + Changed (M7.1).

⚠️ One-time maintainer action

Before the first master deploy, enable GitHub Pages: Settings → Pages → Source: GitHub Actions. The PR build gate works without it; only the deploy job on master requires it (ADR-0027 Consequences).