OVERVIEW: Agentic Documentation Workflow (Diátaxis)

Welcome to the /docs/ directory.

The Framework

We strictly follow the Diátaxis framework, adapted for AI Agents. All documentation MUST fall into one of four quadrants. Do not mix them.

1. /tutorials/ - Learning-oriented. Step-by-step for beginners. (e.g., "Build your first tLOS node").
2. /how-to-guides/ - Task-oriented. Recipes for specific problems. (e.g., "How to parse new data sources in Harkly").
3. /reference/ - Information-oriented. Dry facts, APIs, ABIs, CLI flags. Machine-readable formats preferred.
4. /explanation/ - Understanding-oriented. Architectural philosophy, "Why we did it this way" (Yellow Papers).

Ecosystem Level Docs

The /ecosystem-noadmin/ folder contains documentation about the agent system itself, not the products (tLOS/Harkly). Crucially, it contains the /adr/ (Architecture Decision Records) directory.

ADR Policy (Architects ONLY)

If the CTO or Senior Architect makes a structural change (e.g., "Switching to Pull-based GitOps"), they MUST write an ADR. This prevents future agents from endlessly debating or reverting settled decisions due to context wiping.

Docs-as-Code Workflow

1. Generated Reference: Content in /reference/ should ideally NOT be written by AI directly in Markdown. It should be generated by documenting the source code (Rustdoc/TypeDoc) and having the DevOps Lead run an extraction script post-release.
2. Post-Mortem Guides: When a major bug is fixed, the Tech Lead should instruct a Technical Writer agent to add a concise /how-to-guides/ entry on how to prevent/fix it next time.