docs-write

# Documentation Standards

Structure and templates for project documentation — the human-facing docs that help developers understand and use your project.

This skill covers *what* to include and *where* it goes. For *how* to write it:
- `styleguide` — Sentence rhythm, metaphors, structural moves
- `voice` — Philosophical foundation (apply as review pass)

For agent-specific documentation (CLAUDE.md, AGENTS.md), see `agent-docs`.

## Documentation Hierarchy

Documentation is prioritized in this order:

1. **Types** — Self-documenting code through TypeScript types
2. **Inline comments** — TSDoc/JSDoc for non-obvious decisions
3. **`docs/`** — Broader architectural and reference material

All three levels matter. Types express intent through code, comments explain why, and docs provide context.

## Project Directory Structure

Standardized directory layout for documentation across repositories.

### Root-Level Files

| File | Purpose |
|------|---------|
| `README.md` | Entry point for humans — quick start, links to docs |
| `CONTRIBUTING.md` | Contribution guidelines (if applicable) |
| `CHANGELOG.md` | Version history (auto-generated preferred) |

### Standard Directories

```
project/
└── docs/
    ├── architecture/        # System design, ADRs
    ├── api/                 # API reference (if applicable)
    ├── cli/                 # CLI command reference
    ├── guides/              # How-to guides, tutorials
    └── development/         # Dev setup, workflows
```

### Directory Purpose

| Directory | Content |
|-----------|---------|
| `architecture/` | System design docs, Architecture Decision Records (ADRs), diagrams |
| `api/` | API reference, endpoint documentation, type definitions |
| `cli/` | Command reference, flags, usage examples, exit codes |
| `guides/` | How-to tutorials, walkthroughs, use-case guides |
| `development/` | Contributing setup, local dev, testing, release process |

### Source of Truth Principle

Each type of documentation should have