docs: align development docs with current code behavior

docs/agent-handoffs/README.md

@@ -0,0 +1,18 @@
+# Agent Handoffs
+
+This directory stores reusable notes for future agent runs.
+
+## Purpose
+
+- `learnings/`: repeatable implementation patterns and successful fixes.
+- `incidents/`: reproducible failures, root causes, and mitigations.
+
+## Note format
+
+Use `YYYY-MM-DD-short-topic.md` and include:
+
+1. Context
+2. Observation
+3. Action taken
+4. Validation performed
+5. Recommendation for next agents

docs/agent-handoffs/incidents/.gitkeep

@@ -0,0 +1 @@
+

docs/agent-handoffs/learnings/.gitkeep

@@ -0,0 +1 @@
+