# Documentation Policy

## Three trees + agent

| Tree | Audience | Freshness rule |
|------|----------|----------------|
| `living_docs/` | Everyone — **current truth** | Update every significant session |
| `developer_docs/` | Contributors | Update with technical changes |
| `user_docs/` | End users | Update with user-visible changes |
| `agent/` | Humans + AI process | Update when process/rules change |

## living_docs/

| File | When to update |
|------|----------------|
| `ROADMAP.md` | Phase status, acceptance, owners |
| `PROGRESS.md` | Append-only each session with real work |
| `CURRENT_STATUS.md` | After any “what works” change |
| `ARCHITECTURE_OVERVIEW.md` | Design changes |
| `OPEN_QUESTIONS.md` | New/resolved questions |
| `CHANGELOG.md` | User-visible or notable internal changes |

## developer_docs/

Update the matching file when you touch that domain (setup, architecture, modules, protocol, build, testing).

## user_docs/

- Ship accurate instructions only for **implemented** features.
- Label incomplete features **Planned** with phase.
- Never claim multiplayer works until Phase 2 acceptance is met.

## ADRs

- Required before architecture/protocol/security merges.
- Status lifecycle: Proposed → Accepted → (Deprecated|Superseded).
- Linking: ROADMAP and ARCHITECTURE should cite ADR numbers.

## Same-change rule

Documentation updates belong in the **same PR/commit** as the code they describe. “Docs follow-up later” is not complete work.

## End of session checklist

1. `PROGRESS.md` entry
2. `CURRENT_STATUS.md` if reality changed
3. `CHANGELOG.md` if notable
4. Specialist docs for the area touched
5. ADR if decision changed