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/GUI/AGENT.md

@@ -0,0 +1,47 @@
+# gui module
+
+## Owned files
+
+- Related editor implementation: `../PluginEditor.h`, `../PluginEditor.cpp`
+- SerumLookAndFeel.h
+- Knob.h, Knob.cpp
+- Slider.h, Slider.cpp
+- ToggleButton.h, ToggleButton.cpp
+- Display.h, Display.cpp
+- Panel.h, Panel.cpp
+- WaveformDisplay.h, WaveformDisplay.cpp
+- FilterDisplay.h, FilterDisplay.cpp
+- EnvelopeDisplay.h, EnvelopeDisplay.cpp
+- LFODisplay.h, LFODisplay.cpp
+
+## Rules
+
+- Draw all controls through `SerumLookAndFeel`.
+- Use `theme::` colours from Resources.h instead of hardcoded colour values.
+- Own GUI attachments with `std::unique_ptr`.
+- Own component children by value or with `std::unique_ptr`; `addAndMakeVisible` only attaches and shows them, and does not manage their lifetime.
+- Refresh visuals from a `juce::Timer` callback on the message thread, not from the audio thread.
+- Keep layout constants in the `layout` namespace and derive every position from them.
+- Use `std::function` formatters for value readouts.
+- Reference `ids::` for APVTS parameter IDs.
+
+## IF-THEN
+
+- IF a control reads a DSP value THEN refresh it on the message thread from a thread-safe snapshot or atomic value. A `timerCallback` alone does not make a shared DSP read safe.
+- IF a raw parameter pointer is dereferenced THEN null-guard it first.
+
+## Examples
+
+```cpp
+// BAD: unchecked raw parameter dereference
+const float v = processor.parameters.getRawParameterValue (ids::f1Cutoff)->load();
+```
+
+```cpp
+// GOOD: null guard with fallback
+const float v = processor.parameters.getRawParameterValue (ids::f1Cutoff)
+                    ? processor.parameters.getRawParameterValue (ids::f1Cutoff)->load()
+                    : 0.0f;
+```
+
+This file overrides /AGENT.md where they conflict.