# Agent Instructions

## Documentation Maintenance

When changing behavior, architecture, or user-facing workflows, update documentation in the same task. Do not defer documentation updates for implemented work.

Use `docs/README.md` as the documentation map and keep each fact in one home:

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

Create an ADR in `docs/adr/NNNN-short-title.md` when a decision is hard to reverse or affects multiple crates, such as rendering path, scene format, PIE semantics, settings schema, or netcode choice. Use this format: Status, Context, Decision, Consequences. Number ADRs sequentially and link new ADRs from `docs/README.md` and the root README when relevant.

Coherence rules:

- One home per fact. Link across docs; do not copy paragraphs between README, mission, and ADRs.
- Intent vs implementation: mission/ADRs explain why, README explains how to use, crate module docs explain 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`.

End-of-task checklist for relevant implementation work:

1. Did behavior or UX change? Update README controls or checklist.
2. Did architecture or policy change? Update or create an ADR or mission note.
3. Did an editor workflow change? Update `docs/editor/`.
4. Added a new doc file? Index it in `docs/README.md`.
5. Left a deliberate gap? Record it as future work in README or an ADR Consequences section.
