Documentation Governance

How architectural knowledge is maintained and kept true. It defines the source of truth for every architectural artefact and who owns keeping it current. Builds on the existing update-conventions, documentation model, and CLAUDE.md. Evidence-first.

Source of truth per artefact

Artefact	Source of truth	Owner	Update frequency	Derives from
CLAUDE.md (repo-level)	Each repo’s own `CLAUDE.md`	that repo	with the code	the repo itself
Repository digest	`portal/repos/<slug>.md`	`portfolio-portal`	when the repo changes materially	the repo’s docs (README/CLAUDE/ADRs)
Capability page	`portal/capabilities/cap-<slug>.md`	Capability Registry	when the capability’s contract/maturity changes	repo digests + evidence
Architecture diagrams	the embedded Mermaid in `portal/architecture/*`	`portfolio-portal`	per topology change	digests + dependency evidence
ADRs	`portal/decisions/NNNN-*.md`	founder (accepts)	append-only; immutable once accepted	the decision itself
Operating Model	`portal/operating-model/*`	`portfolio-portal`	per operating change	synthesis of digests/capabilities
Glossary (authoritative)	`portal/operating-model/glossary.md`	`portfolio-portal`	when a term is added/standardised	the ecosystem’s vocabulary
Registries (repo, capability)	`portal/registry/` + `portal/capabilities/README.md`	`portfolio-portal`	when repos/capabilities added	digests + capability pages
Current state (dashboard/changelog/roadmap)	`portal/current-state/*`	`portfolio-portal`	every change	all of the above
Machine index	`llms.txt`	`portfolio-portal`	with structural changes	the registries

The synchronisation contract

The portal is a derived view of many repos. Keeping it true is governed by explicit rules (Principle 2 — definition vs derivation):

graph LR
    REPO[Repo docs<br/>CLAUDE.md · README · ADRs] -->|digest| DIG[Repo digest]
    DIG -->|roll up| CAP[Capability page]
    DIG --> REG[Registry row]
    CAP --> RUSE[Reuse map]
    DIG & CAP --> ARCH[Architecture diagrams]
    ALL[all pages] --> CS[Current-state + changelog]
    ALL --> LLMS[llms.txt]

Invariants (must always hold — from update-conventions):

Registry ⇄ digests are 1:1 (no orphans, no duplicates).
Every diagram node resolves to a real digest/capability.
Every venture and its repos link both ways.
No dead internal links; no silent blanks (explicit placeholders only).
last_reviewed on any touched page is current.

Generated vs human-authored regions

Pages mark ownership so future automation is safe (documentation model):

… — human-owned prose; automation must preserve it.
… — automation-owned; the orchestrator may overwrite.

Portal synchronisation — implemented vs future

Aspect	Today	Future
Digest/diagram/registry updates	🔶 Manual, per update-conventions	⏳ `portfolio-portal-orchestrator` generates them from source
Consistency checks (links/orphans)	🔶 Manual + link-check script	⏳ Automated in the orchestrator run + CI
`llms.txt` freshness	🔶 Manual	⏳ Regenerated from the registry
Pin-freshness (pack versions)	❌ Not tracked	⏳ Registry-tracked + CI check (Risk R5)

Responsibilities

Repos own their CLAUDE.md, README, and ADRs (their truth).
The portal owns the derived views (digests, capabilities, diagrams, registries) and must not contradict a repo’s own docs — if it does, the repo wins and the digest is corrected.
The founder owns accepting ADRs and resolving ambiguous ownership.
AI assistants may draft/generate any derived artefact but a human reviews structural changes (AI Governance).