# Documentation Template

How documentation must be updated after every phase.

## Principle

Code and documentation ship together. A phase that changes behavior without docs is incomplete ([project-principles.md](../development/project-principles.md)).

## Update Checklist

### Always

- [ ] Phase document created/updated (from [phase-template.md](phase-template.md))
- [ ] [phase-handover.md](phase-handover.md) sections filled (or equivalent in phase doc)
- [ ] [progress.md](../progress.md) — completed work only
- [ ] [next-steps.md](../next-steps.md) — immediate next milestone only
- [ ] [module-registry.md](../module-registry.md) — version, phase, events, permissions, migration
- [ ] [phase-manifest.yaml](phase-manifest.yaml) — status / dependencies
- [ ] [service-manifest.yaml](service-manifest.yaml) — version / phase / APIs / events if service changed

### When Applicable

- [ ] [roadmap.md](../roadmap.md) — only if future sequencing changed
- [ ] [provider-registry.md](../provider-registry.md) — new/changed providers
- [ ] [glossary.md](../glossary.md) — new canonical terms
- [ ] ADR created/updated under [architecture/adr/](../architecture/adr/)
- [ ] Architecture docs if boundaries/topology changed (never silently)
- [ ] [reference/api-reference.md](../reference/api-reference.md)
- [ ] [reference/services-contracts.md](../reference/services-contracts.md)
- [ ] [reference/event-catalog.md](../reference/event-catalog.md)
- [ ] [reference/database-schema.md](../reference/database-schema.md)
- [ ] Service README under `backend/services/<name>/`
- [ ] Phase area README under [phases/](../phases/)
- [ ] Frontend docs under [frontend/](../frontend/) if UI shipped

### Never

- Do not put future work into `progress.md`
- Do not overwrite accepted ADRs
- Do not duplicate [master-prompt.md](master-prompt.md) rules into phase prompts
- Do not leave broken links or undocumented public surfaces for the phase

## Cross-Link Requirements

Every new phase doc must link at least:

- Architecture overview or relevant architecture leaf
- Related ADR(s)
- Module registry entry
- Development standards (principles / testing) as needed
- AI framework loop/gates when the phase is AI-implemented
- Progress / next-steps

## Validation

Before completion, run Documentation + Cross Reference + Broken Link validation from [quality-gates.md](quality-gates.md).

## Related Documents

- [docs/README.md](../README.md)
- [Phase Template](phase-template.md)
- [Phase Handover](phase-handover.md)
- [templates/](../templates/) (registry-oriented short templates)