---
description: Keep project documentation current—ADRs, mission, editor docs, README checklist
alwaysApply: true
---

# Documentation Maintenance

When changing behavior, architecture, or user-facing workflows, **update docs in the same task**—do not defer.

## Doc map (single source of truth: [docs/README.md](../../docs/README.md))

| Change type | Update |
|-------------|--------|
| Architecture / crate boundary / sim-network split | New or updated ADR in `docs/adr/` |
| Editor framework intent, principles, non-goals | `docs/mission.md` |
| Editor feature design or phase status | `docs/editor/` (see its README) |
| User controls, run commands, troubleshooting | Root `README.md` |
| Shipped feature completion | Root `README.md` Implementation Checklist |
| Bevy upgrade policy | ADR 0002 + migration notes in `docs/adr/` |
| Milestone scope (pre-implementation) | `.cursor/plans/` plan file |

## ADRs

Create `docs/adr/NNNN-short-title.md` when a decision is **hard to reverse** or affects multiple crates (rendering path, scene format, PIE semantics, settings schema, netcode choice).

Format: Status, Context, Decision, Consequences. Number sequentially. Link from `docs/README.md` and root README.

## Coherence rules

- **One home per fact.** Link across docs; do not copy paragraphs between README, mission, and ADRs.
- **Intent vs implementation:** mission/ADRs = *why*; README = *how to use*; crate module docs = *local API*.
- **Plans vs permanent docs:** `.cursor/plans/` holds working roadmaps; promote stable decisions into `docs/` when implemented.
- **Stale docs are bugs.** If code contradicts docs, fix both or fix docs in the same PR/task.
- **New subsystems** get a short entry in `docs/README.md` and, if editor-facing, `docs/editor/README.md`.

## Agent checklist (end of relevant tasks)

1. Did behavior or UX change? → README controls / checklist
2. Did architecture or policy change? → ADR or mission
3. Did editor workflow change? → `docs/editor/`
4. Added a new doc file? → index in `docs/README.md`
5. Left a deliberate gap? → "Future work" in README or an ADR Consequences section—not silent omission