Documentation layers

Holon's documentation is organized into five distinct layers with explicit boundaries, audience definitions, and content contracts. This prevents drift between user-facing mental models, authoritative reference contracts, and internal runtime specifications.

The five documentation layers

Layer guidelines & content contracts

1. Getting started — First success

• Purpose: Take a new user from zero to a verified running agent in under 15 minutes.
• Format: Minimal commands, clear prerequisites, explicit expected output, and pointers to next paths.
• Rule: Never dump complete option lists or internal repository layouts into getting started pages. Keep the path uninterrupted.

2. Concepts — User-facing mental models

• Purpose: Explain Holon's core building blocks and observable semantics so users can predict runtime behavior.
• Audience: Regular users and integrators, not runtime engine developers.
• Content principles:
  • Audience-first: Write for the person operating or building on top of Holon.
  • Stable semantics only: Focus on durable concepts (e.g. why agents persist, how work items track objectives, what trust boundaries isolate).
  • Do not disguise implementation details as concepts: Never burden users with internal Rust module names, struct layouts, database tables, or private queue mechanics just because they exist in code.
  • Behavioral durability check: A concept page must remain accurate even if internal queue or storage implementations are refactored.
  • Link rather than duplicate: Link to Reference for exact parameters and to Spec or RFCs for maintainer contracts.

3. Guides — Task-oriented how-to

• Purpose: Solve a concrete user problem ("How do I integrate via HTTP?", "How do I monitor with Prometheus?").
• Standard guide structure:
  1. Goal & context: What will be achieved and when to use this approach.
  2. Prerequisites: Tools, keys, or permissions needed before starting.
  3. Step-by-step instructions: Minimal reproducible commands with explanations.
  4. Verification: How to confirm the task succeeded.
  5. Troubleshooting: Common failure modes and immediate remedies.
  6. Related reference & concepts: Direct links to authoritative reference and background concepts.
• Rule: Guides provide minimal inline examples. Complete endpoint tables or configuration schemas belong in Reference.

4. Reference — Current authoritative contract

• Purpose: The single source of truth for syntax, options, endpoints, and schema definitions.
• Structure: Standardized tables and sections: Scope, Syntax / Endpoint, Parameters / Payload, Return values, Limits, and Stability.
• Rule: Reference pages are authoritative snapshots verified against the compiled binary (holon --help, holon config schema, route inventory). If an option or endpoint changes, update Reference first.

5. Spec — Maintainer runtime contracts

• Purpose: Document internal contracts, lifecycle state transitions, and invariants that engine contributors must adhere to.
• Audience: Contributors and maintainers working on Holon's codebase.
• Rule: Spec pages are normative specifications, not user documentation. User-facing navigation de-emphasizes spec pages so beginners are not confused by internal mechanics.

Supporting maintainer layers

• docs/rfcs/ (Design RFCs): Canonical design rationale and architectural debates behind major capabilities.
• docs/implementation-decisions/ (ADRs): Lightweight records explaining why a specific technical choice was made when multiple viable options existed.
• docs/archive/: Preserved historical notes that are no longer active specifications.
• docs/website/maintainers/ (Maintainer workflows): Build, test, and documentation workflows for people changing Holon itself.

Cross-layer links

A well-structured document links across layers rather than copying content:

Getting started ──> Guides (for specific tasks)
      │                │
      ▼                ▼
  Concepts ──────> Reference (for exact parameters/endpoints)
      │
      ▼ (maintainers only)
    Spec ─────────> RFCs / ADRs (for design rationale)

When to update which layer