Skip to content

Canonical Docs Consolidation Note (2026-04-11)

Scope

This note records the documentation wrap/bootstrap slice that establishes docs/ as canonical.

Canonical Rule

  • docs/ is now the canonical publication root.
  • doc/ is legacy and archived under docs/archive/doc-legacy/.
  • spec/ is transitional compatibility while code/tests still reference specific spec files.

What Moved

  • Entire legacy doc/ content moved to:
  • docs/archive/doc-legacy/

What Was Added

  • MkDocs Material site config (mkdocs.yml) with protocol-first nav
  • Canonical docs sections:
  • docs/protocol/
  • docs/specs/
  • docs/runtime/
  • docs/wallet/
  • docs/security/
  • docs/reference/
  • docs/roadmap/
  • Full-detail spec publication mirror:
  • docs/specs/source/
  • docs/specs/spec-coverage-matrix.md
  • docs/specs/full-detail-catalog.md
  • Generated reference pipeline under:
  • tools/docs/generate-reference-docs.mjs
  • docs/reference/generated/
  • CI docs checks workflow:
  • .github/workflows/docs-site.yml

What Remains Transitional

spec/ still contains compatibility references used by current code/tests/fixtures, including:

  • terminology/spec anchors
  • protocol/planning specs referenced by tooling and tests
  • full-detail source files mirrored into docs/specs/source/ for publication

Plan:

  1. keep spec/ readable and explicitly marked transitional
  2. migrate authoritative publication content into docs/
  3. avoid breaking compatibility references until consumers are updated

Current Truth Boundary Preserved

  • first-hop and follow-on direct-spend live validation evidence exists
  • bounded two-input proof alignment is the publishable bounded milestone
  • repeated no-top-up continuation remains reserve-limited
  • transparent supplemental economics support remains interim path when reserve is insufficient
  • graph/shell observability reduction remains future aggregation work

Validation Checklist For This Slice

  • canonical docs root established
  • strict MkDocs site scaffolded with protocol-first navigation
  • generated docs path and generation script added
  • CI docs-freshness and strict build checks added
  • claim boundary language kept precise and non-inflated