docs: add agent guidance and historical audit report

Add root AGENT.md with project conventions, build verification steps,
source layout, style rules, and real-time/concurrency requirements.
Add per-module AGENT.md files for each existing and proposed source
subdirectory. Add AUDIT_REPORT.md as a historical Phase 1 snapshot
documenting memory management, error handling, concurrency model,
naming conventions, and anti-pattern catalog.

Source/modulation/AGENT.md

@@ -0,0 +1,34 @@
+# modulation module
+
+## Related source files
+
+This directory contains guidance; implementations remain in the parent `Source/`
+directory:
+
+- `../ModulationMatrix.h`, `../ModulationMatrix.cpp`
+- `../MacroControls.h`, `../MacroControls.cpp`
+- `../RAVEButton.h`, `../RAVEButton.cpp`, which define `RaveController`
+
+## Rules
+
+- Use `bool` return codes for bounded inserts (`addConnection`, `addAssignment`).
+- Require a cap on connection and assignment counts (`kMaxConnections`, `kMaxAssignments`).
+- Serialise and restore state through `juce::ValueTree` so presets survive save and load.
+- Never accept a `ModTarget::None` connection; reject it and return false.
+- Use `ids::` for every APVTS parameter reference in RaveController.
+- Keep the existing RAVEButton filenames unless a rename is explicitly in scope.
+
+## GUI/audio state
+
+The current public connection and assignment vectors are shared mutable state.
+GUI writes can race with audio-thread iteration. A mutex taken only by the writer
+does not protect an unlocked reader, and taking a blocking mutex in the audio
+callback conflicts with the real-time requirements.
+
+When fixing this path, publish a stable snapshot or use a bounded thread-safe
+handoff. Keep allocation and snapshot reclamation off the audio thread. Validate
+reader and writer lifetimes together, including preset and state restore.
+
+If `addConnection` or `addAssignment` returns false, handle the failed insert.
+
+This file refines the repository-root AGENT.md for the related sources.