Validate and finalize the archival documentation site

[acgetchell]

Current v1.0.0 plan (2026-07-24)

Starts after: #98 and #104; #115 has established the public API boundary. Blocks: #95.

Finalize a correct archival documentation site after the viewer and comparison-harness documentation surfaces are present. Select and pin the Doxygen version that renders the repository correctly, fix repository-owned defects, and add a lightweight generated-site validator.

The goal is a dependable archival site, not adoption of every Doxygen feature or an upstream documentation-tool research project.

Native GitHub dependency metadata is the source of truth for ordering.

---

Summary

Validate and finalize a correct, self-contained, reproducible Doxygen site for the v1.0.0 archive.

This issue owns generated-site correctness and documentation-specific validation. #96 remains the authority for final release prose, metadata, citations, and archival handoff.

Audit baseline

The existing audit found repository-owned broken links and literal Markdown, stale external links, an unused Mermaid CDN, strict warnings outside the intended public boundary, and Doxygen-version-dependent duplicate-label and alphabetical-index defects.

Use that evidence to choose a stable archival configuration; do not bind the release to Doxygen 1.17 if another supported pin renders the site more correctly.

Scope

• Choose and pin a Doxygen version that produces a correct archival site with the existing supported wrapper.
• Fix repository-owned broken internal links, literal Markdown, stale hard-failing external links, and uncopied local targets.
• Remove the unused Mermaid CDN dependency.
• Add a lightweight generated-site check for local pages, targets, fragments, duplicate IDs, required images, scripts, stylesheets, and the known duplicate-label regression.
• Preserve useful current behavior such as search, responsive/dark HTML, code folding, copy controls, SVG graphs, and GitHub-style Markdown IDs where supported.
• Document the public API boundary established by Define and normalize the public C++ namespace and API boundary #115 and enable warning settings that sustainably enforce that boundary.
• Document any bounded Doxygen-version workaround or known generated-site limitation needed for archival reproducibility.

Non-goals

• No requirement to adopt Doxygen 1.17 specifically.
• No review of every newly introduced Doxyfile option.
• No MathJax, navigation, sitemap, icon, appearance, or input-threading modernization unless required to fix a release-blocking defect.
• No exhaustive documentation of private or incidental symbols.
• No requirement to eliminate all warnings produced by an intentionally broader private/internal extraction mode.
• No upstream minimal reproducer or bug report unless it is necessary to unblock the archival site.
• No aesthetic redesign.

Acceptance criteria

• The canonical documentation build completes with repository-pinned Doxygen and Graphviz versions and no release-blocking warnings.
• The generated-site validator passes for local pages, targets, fragments, IDs, images, scripts, stylesheets, and other required assets.
• No repository-owned Markdown link is emitted literally or points to an unreachable local target.
• No known hard-failing repository-owned external link remains.
• The observed duplicate-label and alphabetical-index defects are avoided by the pinned version or a bounded documented workaround.
• Unused Mermaid CDN loading is removed.
• The public API documentation boundary is explicit and enforced without requiring exhaustive private-symbol documentation.
• README, bibliography, scientific design notes, viewer instructions, comparison-harness instructions, and public API pages render correctly.
• Audit and enforce the v1.0.0 build and CI release gates #95 and Prepare v1.0.0 documentation, metadata, and archival handoff #96 can rely on the documented generated-site command and validator.

Boundaries

• Prepare v1.0.0 documentation, metadata, and archival handoff #96 owns final v1.0.0 prose, citation metadata, release notes, maintenance status, and archival handoff.
• Audit and enforce the v1.0.0 build and CI release gates #95 owns the broader release-gate and CI audit.
• Audit and independently validate all 3D CDT ergodic moves #106 owns the scientific correctness audit for the 3D ergodic moves.