# INSIGHTS.md — non-obvious codebase facts (+ the why)

> Append when you discover something that would save the next session an investigation. Read before working an unfamiliar area. Worker agents return insights in their report; the orchestrator records them here. When an insight proves stable and broadly useful, graduate it into a hard rule in CLAUDE.md.

<!-- Format: a fact + why it matters + where it bites. -->
- `<area>`: `<non-obvious fact>` — `<why / where it matters>`