# Documentation System

## Structure

The docs set uses:

- [Diataxis](https://diataxis.fr/) categories for tutorials, how-to guides, reference, and explanation.
- [C4](https://c4model.com/introduction) and [arc42](https://arc42.org/) inspired architecture pages.
- [ADRs](https://adr.github.io/) for durable decisions.
- [TypeDoc Markdown](https://typedoc-plugin-markdown.org/docs) for public API reference.
- A custom inventory generator for line-addressable source reference.

## Research Basis

This corpus follows the current public documentation patterns reviewed during the documentation build:

- Diataxis separates learning-oriented tutorials, task-oriented how-to guides, factual reference, and explanatory architecture/background docs.
- C4 provides layered architecture views from system context down toward code-level detail.
- arc42 provides pragmatic architecture documentation sections for context, building blocks, runtime views, quality concerns, and decisions.
- ADR guidance treats each decision as a short record of context, decision, consequences, and supersession links.
- Runbook guidance treats operational docs as executable procedures with prerequisites, steps, rollback, and verification.
- TypeDoc plus `typedoc-plugin-markdown` generates API reference from TypeScript declarations and TSDoc comments.

## Scripts

```bash
npm run docs:inventory
npm run docs:api
npm run docs:check
npm run docs:build
```

Direct equivalents:

```bash
node scripts/generate-docs-inventory.mjs
npx typedoc
node scripts/check-docs.mjs
```

## Generated Docs

- `docs/reference/generated/inventory.md`
- `docs/reference/generated/source/`
- `docs/reference/generated/api/`

Generated source pages list each file, detected symbols, and links for every source line. They are intentionally generated so line coverage does not create noisy source comments.

## Source Comments

Use source comments for public contracts and complex behavior:

- exported interfaces, classes, functions, and hooks that define a subsystem boundary
- compatibility transforms
- runtime lifecycle and stream fanout
- Cline SDK boundaries
- PTY/session state machines
- git/worktree safety rules
- security checks

Avoid comments that restate assignments, JSX markup, or obvious type names.

## Link Policy

Use relative Markdown links for repo docs and generated references. Use external links only for durable upstream documentation, such as official Cline docs, Diataxis, TypeDoc, C4, and arc42.
