Documentation layers

Holon's documentation is organized into four layers with clear boundaries. This prevents drift between what users see, what the runtime actually does, and what maintainers are designing next.

Layer 1: Product website (docs/website/)

Audience: New users, evaluators, integrators, and contributors learning Holon.

Goal: Explain why Holon exists, guide first success, and expose stable-enough concepts without overwhelming readers with RFC detail.

Structure:

Rule: Website pages should explain what and how, not why the design works that way. Link to RFCs for design rationale.

Layer 2: Runtime specs (docs/website/spec/)

Audience: Maintainers and contributors who need the current runtime contract.

Goal: Describe the current implementation-facing contract — what Holon actually does today, verified against implementation and tests.

Rule: Spec pages are not user tutorials. They are authoritative contracts. Each spec page links to the source RFCs that motivated the design and tracks known implementation/RFC/test gaps. When runtime behavior changes, the spec page and the RFC should be updated together.

Layer 3: Current public contract

Audience: Users running, configuring, integrating, or troubleshooting Holon.

Goal: Describe current behavior. Mark experimental or unstable behavior clearly.

Includes:

• docs/website/reference/ — CLI, configuration, and HTTP control-plane pages
• README.md — high-level repository entry and contributor orientation
• docs/website/spec/ — current implementation-facing contracts
• docs/runtime-spec.md — aggregate index mapping original v0 spec to focused spec pages (not a user tutorial)

Rule: Reference pages should be verified against the compiled runtime (holon --help, holon config schema). Mark the version each page was last checked against. If behavior is experimental, say so.

Layer 4: Maintainer design (docs/, docs/rfcs/, docs/implementation-decisions/)

Audience: Maintainers and contributors changing runtime semantics.

Goal: Preserve architecture contracts, design rationale, and historical decisions. These are the canonical source of truth for runtime behavior.

Structure:

Rule: When a runtime concept changes, update the RFC first. Implementation decisions capture why a choice was made. Archives preserve history without cluttering the active surface.

Cross-layer links

• Website pages link to RFCs as "deeper design background" — not as required reading.
• The repository README.md links to the website as the product entry point.

When to update which layer