refactor(source): move every implementation into its module directory

- 36 files move into the module whose AGENTS.md already claimed them:
  Engine/, Synth/, Modulation/, Params/, Plugin/, GUI/, EffectUnits/, Resources/
- Source/engine, modulation, params, plugin and synth become Engine,
  Modulation, Params, Plugin and Synth, matching the directories that already
  hold code
- ExactCompare.h stays at the Source/ root as the one shared header
- SERUMALT_INCLUDE_DIRS adds one include directory per module, so the 31
  parent-relative includes become plain names with no path prefix
- the module AGENTS.md files list owned files instead of describing a move
  that had not happened, and README.md and AGENTS.md describe the real tree

Verified: the harness passes CTest, the Linux VST3 and Standalone link, the
Windows cross-build passes its module checks, each configure exposes only its
own targets, no first-party warning line appears, and the generated Windows
manifest is unchanged.

AGENTS.md

@@ -83,23 +83,31 @@ extra files. Never edit generated CMakeCache.txt files. The checked-in
 
 ## Current source layout
 
-`CMakeLists.txt` owns the explicit `SERUMALT_SOURCES` list and shared target setup.
-`cmake/Plugin.cmake` owns production formats and MinGW link flags;
-`cmake/Harness.cmake` owns the console harness and CTest registration.
-The harness compiles the same processor/editor sources independently of the plugin.
+`CMakeLists.txt` owns the explicit `SERUMALT_SOURCES` list, the module include
+directories and shared target setup. `cmake/Plugin.cmake` owns production formats
+and MinGW link flags; `cmake/Harness.cmake` owns the console harness and CTest
+registration. The harness compiles the same processor/editor sources independently
+of the plugin.
 
-Most C++ files still live directly under `Source/`. Existing implementation
-subdirectories are `EffectUnits/`, `GUI/`, `Presets/`, `Resources/`, and `Tests/`.
-`FXProcessor`, `PluginEditor`, `Resources`, and `RAVEButton` remain at the source root.
-`RAVEButton.{h,cpp}` defines `RaveController`.
+Every implementation lives in a module directory under `Source/`, and the
+`AGENTS.md` in that directory owns its rules:
 
-The lowercase `Source/engine`, `modulation`, `params`, `plugin`, and `synth`
-directories currently hold guidance, not relocated implementations. Consult their
-`AGENTS.md` files when editing the related root-level sources. Consult the matching
-`AGENTS.md` when editing an existing implementation subdirectory.
-`docs/AUDIT_REPORT.md` is a historical audit and proposed refactor, not a pending
-instruction to move files. Update the explicit source list and includes only when
-an actual source move is part of the requested task.
+- `Engine/` the voice pool, LFOs, wavetable library, FX rack, matrix and macros.
+- `Synth/` wavetables, oscillators, filters, envelopes, LFOs and the voice.
+- `Modulation/` the modulation matrix, macros, and `RAVEButton`, which defines
+  `RaveController`.
+- `Params/` parameter IDs, indexed groups, enums and unit mappings.
+- `Plugin/` the JUCE `AudioProcessor` boundary.
+- `GUI/` the editor with its controls and previews.
+- `EffectUnits/` the effect rack and the effect units.
+- `Presets/`, `Resources/` and `Tests/`, as their names suggest.
+
+`Source/ExactCompare.h` is the one shared header, and several modules include it.
+`SERUMALT_INCLUDE_DIRS` lists one include directory per module, so a source names a
+header without a path prefix. No two headers share a basename; check that before
+adding one. `docs/AUDIT_REPORT.md` is a historical audit and proposed refactor, not
+a pending instruction. Update `SERUMALT_SOURCES` and `SERUMALT_INCLUDE_DIRS` when
+files move.
 
 ## Style and ownership
 

CMakeLists.txt

@@ -19,24 +19,24 @@ endif()
 add_subdirectory("${JUCE_ROOT}" "${CMAKE_CURRENT_BINARY_DIR}/third_party/JUCE")
 
 set(SERUMALT_SOURCES
-    Source/PluginProcessor.cpp
-    Source/PluginEditor.cpp
-    Source/Params.cpp
-    Source/Wavetable.cpp
-    Source/Oscillator.cpp
-    Source/SubOscillator.cpp
-    Source/NoiseOscillator.cpp
-    Source/Filter.cpp
-    Source/FilterBank.cpp
-    Source/Envelope.cpp
-    Source/LFO.cpp
-    Source/ModulationMatrix.cpp
-    Source/FXProcessor.cpp
-    Source/MacroControls.cpp
-    Source/RAVEButton.cpp
-    Source/SynthVoice.cpp
-    Source/Engine.cpp
-    Source/Resources.cpp
+    Source/Plugin/PluginProcessor.cpp
+    Source/GUI/PluginEditor.cpp
+    Source/Params/Params.cpp
+    Source/Synth/Wavetable.cpp
+    Source/Synth/Oscillator.cpp
+    Source/Synth/SubOscillator.cpp
+    Source/Synth/NoiseOscillator.cpp
+    Source/Synth/Filter.cpp
+    Source/Synth/FilterBank.cpp
+    Source/Synth/Envelope.cpp
+    Source/Synth/LFO.cpp
+    Source/Modulation/ModulationMatrix.cpp
+    Source/EffectUnits/FXProcessor.cpp
+    Source/Modulation/MacroControls.cpp
+    Source/Modulation/RAVEButton.cpp
+    Source/Synth/SynthVoice.cpp
+    Source/Engine/Engine.cpp
+    Source/Resources/Resources.cpp
     Source/EffectUnits/Hyper.cpp
     Source/EffectUnits/Chorus.cpp
     Source/EffectUnits/Flanger.cpp
@@ -57,9 +57,25 @@ set(SERUMALT_SOURCES
     Source/GUI/Panel.cpp
     Source/Presets/FactoryPresets.cpp)
 
+# One include directory per module, so a source names a header without a path
+# prefix. No two headers in this tree share a basename.
+set(SERUMALT_INCLUDE_DIRS
+    Source
+    Source/EffectUnits
+    Source/Engine
+    Source/GUI
+    Source/Modulation
+    Source/Params
+    Source/Plugin
+    Source/Presets
+    Source/Resources
+    Source/Synth
+    Source/Tests)
+
 function(serumalt_configure_target target)
     juce_generate_juce_header(${target})
     target_sources(${target} PRIVATE ${SERUMALT_SOURCES})
+    target_include_directories(${target} PRIVATE ${SERUMALT_INCLUDE_DIRS})
     target_compile_definitions(${target}
         PUBLIC
             JUCE_WEB_BROWSER=0

README.md

@@ -27,28 +27,17 @@ working builds and hands-on listening over elaborate test infrastructure.
 
 ```
 Source/
-  PluginProcessor.{h,cpp}     APVTS, presets, state, RAVE/UI-scale glue
-  PluginEditor.{h,cpp}        Tabbed GUI, owned controls, scaling, previews
-  Params.{h,cpp}              Parameter IDs, indexed groups, enums, mappings
-  Wavetable.{h,cpp}           256×2048 tables, prebuilt by the engine
-  Oscillator.{h,cpp}          Morph/warp/unison oscillator
-  SubOscillator.{h,cpp}       Sine/triangle sub
-  NoiseOscillator.{h,cpp}     White/pink noise
-  Filter.{h,cpp}              Seven filter models and cached coefficients
-  FilterBank.{h,cpp}          Two slots and routing
-  Envelope.{h,cpp}            ADSR with curve
-  LFO.{h,cpp}                 Continuous phase, sync and shape editing
-  ModulationMatrix.{h,cpp}    Connections
-  FXProcessor.{h,cpp}         Independent effect state per rack slot
-  EffectUnits/                Hyper, Chorus, Flanger, Phaser, Distortion, EQ,
-                              Compressor, Delay, Reverb
-  MacroControls.{h,cpp}       Four assignable macros
-  RAVEButton.{h,cpp}          Render-time boost, without rewriting parameters
-  SynthVoice.{h,cpp}          Per-voice oscillators, filters and envelopes
-  Engine.{h,cpp}              32 voices, MIDI timing, control snapshots, FX
-  GUI/                        Controls and previews
-  Presets/FactoryPresets.cpp  Factory preset definitions
-  Resources/                  SVG assets
+  Engine/         Voice pool, MIDI timing, control snapshots, FX rack
+  Synth/          Wavetables, oscillators, filters, envelopes, LFOs, voice
+  Modulation/     Matrix, macros, RAVE
+  Params/         Parameter IDs, indexed groups, enums, mappings
+  Plugin/         AudioProcessor: APVTS, presets, state, RAVE/UI-scale glue
+  GUI/            Editor, controls and previews
+  EffectUnits/    FX rack and the nine effect units
+  Presets/        Factory preset definitions
+  Resources/      Theme, formatters and SVG assets
+  Tests/          Headless QA harness
+  ExactCompare.h  Shared exact float comparison helpers
 ```
 
 The engine splits rendering at MIDI event positions and into segments of at most

Source/EffectUnits/AGENTS.md

@@ -2,7 +2,7 @@
 
 ## Owned files
 
-- Related rack implementation: `../FXProcessor.h`, `../FXProcessor.cpp`
+- FXProcessor.h, FXProcessor.cpp
 - Biquad.h
 - Hyper.h, Hyper.cpp
 - Chorus.h, Chorus.cpp
@@ -27,7 +27,7 @@
 ## IF-THEN
 
 - IF a unit needs a delay line THEN allocate it in `prepare()` at the full required length and only read and write it in `process`.
-- Include the existing rack interface via `../FXProcessor.h`; no source relocation is implied by this guidance.
+- Include the rack interface via `FXProcessor.h`.
 
 ## Examples
 

Source/EffectUnits/Chorus.h

@@ -1,6 +1,6 @@
 #pragma once
 
-#include "../FXProcessor.h"
+#include "FXProcessor.h"
 
 namespace serum
 {

Source/EffectUnits/Compressor.h

@@ -1,6 +1,6 @@
 #pragma once
 
-#include "../FXProcessor.h"
+#include "FXProcessor.h"
 
 namespace serum
 {

Source/EffectUnits/Delay.h

@@ -1,6 +1,6 @@
 #pragma once
 
-#include "../FXProcessor.h"
+#include "FXProcessor.h"
 
 namespace serum
 {

Source/EffectUnits/Distortion.h

@@ -1,6 +1,6 @@
 #pragma once
 
-#include "../FXProcessor.h"
+#include "FXProcessor.h"
 #include "Biquad.h"
 
 namespace serum

Source/EffectUnits/EQ.h

@@ -1,6 +1,6 @@
 #pragma once
 
-#include "../FXProcessor.h"
+#include "FXProcessor.h"
 #include "Biquad.h"
 
 namespace serum

Source/EffectUnits/Flanger.h

@@ -1,6 +1,6 @@
 #pragma once
 
-#include "../FXProcessor.h"
+#include "FXProcessor.h"
 
 namespace serum
 {

Source/EffectUnits/Hyper.h

@@ -1,6 +1,6 @@
 #pragma once
 
-#include "../FXProcessor.h"
+#include "FXProcessor.h"
 #include "Biquad.h"
 
 namespace serum

Source/EffectUnits/Phaser.h

@@ -1,6 +1,6 @@
 #pragma once
 
-#include "../FXProcessor.h"
+#include "FXProcessor.h"
 
 namespace serum
 {

Source/EffectUnits/Reverb.h

@@ -1,6 +1,6 @@
 #pragma once
 
-#include "../FXProcessor.h"
+#include "FXProcessor.h"
 
 namespace serum
 {

Source/Engine/AGENTS.md

@@ -1,9 +1,8 @@
 # engine module
 
-## Related source files
+## Owned files
 
-This directory contains guidance; the implementation remains in `../Engine.h`
-and `../Engine.cpp`.
+- Engine.h, Engine.cpp
 
 ## Rules
 

Source/GUI/AGENTS.md

@@ -2,7 +2,7 @@
 
 ## Owned files
 
-- Related editor implementation: `../PluginEditor.h`, `../PluginEditor.cpp`
+- PluginEditor.h, PluginEditor.cpp
 - Knob.h, Knob.cpp
 - KnobLookAndFeel.h, KnobLookAndFeel.cpp
 - ToggleButton.h, ToggleButton.cpp

Source/GUI/Display.h

@@ -1,7 +1,7 @@
 #pragma once
 
 #include <JuceHeader.h>
-#include "../Resources.h"
+#include "Resources.h"
 
 namespace serum
 {

Source/GUI/EnvelopeDisplay.cpp

@@ -1,6 +1,6 @@
 #include "EnvelopeDisplay.h"
-#include "../Envelope.h"
-#include "../ExactCompare.h"
+#include "Envelope.h"
+#include "ExactCompare.h"
 
 namespace serum
 {

Source/GUI/EnvelopeDisplay.h

@@ -1,8 +1,8 @@
 #pragma once
 
 #include <JuceHeader.h>
-#include "../Resources.h"
-#include "../Params.h"
+#include "Resources.h"
+#include "Params.h"
 
 namespace serum
 {

Source/GUI/FilterDisplay.cpp

@@ -1,5 +1,5 @@
 #include "FilterDisplay.h"
-#include "../ExactCompare.h"
+#include "ExactCompare.h"
 
 namespace serum
 {

Source/GUI/FilterDisplay.h

@@ -1,8 +1,8 @@
 #pragma once
 
 #include <JuceHeader.h>
-#include "../Resources.h"
-#include "../Params.h"
+#include "Resources.h"
+#include "Params.h"
 
 namespace serum
 {

Source/GUI/Knob.h

@@ -2,7 +2,7 @@
 
 #include <JuceHeader.h>
 #include <memory>
-#include "../Resources.h"
+#include "Resources.h"
 #include "KnobLookAndFeel.h"
 
 namespace serum

Source/GUI/KnobLookAndFeel.h

@@ -1,7 +1,7 @@
 #pragma once
 
 #include <JuceHeader.h>
-#include "../Resources.h"
+#include "Resources.h"
 
 namespace serum
 {

Source/GUI/LFODisplay.cpp

@@ -1,5 +1,5 @@
 #include "LFODisplay.h"
-#include "../ExactCompare.h"
+#include "ExactCompare.h"
 
 namespace serum
 {

Source/GUI/LFODisplay.h

@@ -1,9 +1,9 @@
 #pragma once
 
 #include <JuceHeader.h>
-#include "../Resources.h"
-#include "../Params.h"
-#include "../LFO.h"
+#include "Resources.h"
+#include "Params.h"
+#include "LFO.h"
 
 namespace serum
 {

Source/GUI/Panel.h

@@ -1,7 +1,7 @@
 #pragma once
 
 #include <JuceHeader.h>
-#include "../Resources.h"
+#include "Resources.h"
 
 namespace serum
 {

Source/GUI/ToggleButton.h

@@ -1,7 +1,7 @@
 #pragma once
 
 #include <JuceHeader.h>
-#include "../Resources.h"
+#include "Resources.h"
 
 namespace serum
 {

Source/GUI/WaveformDisplay.h

@@ -1,9 +1,9 @@
 #pragma once
 
 #include <JuceHeader.h>
-#include "../ExactCompare.h"
-#include "../Resources.h"
-#include "../Wavetable.h"
+#include "ExactCompare.h"
+#include "Resources.h"
+#include "Wavetable.h"
 
 namespace serum
 {

Source/Modulation/AGENTS.md

@@ -1,13 +1,10 @@
 # modulation module
 
-## Related source files
+## Owned 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`
+- ModulationMatrix.h, ModulationMatrix.cpp
+- MacroControls.h, MacroControls.cpp
+- RAVEButton.h, RAVEButton.cpp, which define `RaveController`
 
 ## Rules
 

Source/Params/AGENTS.md

@@ -1,15 +1,14 @@
 # params module
 
-## Related source files
+## Owned files
 
-This directory contains guidance; the implementation remains in `../Params.h`
-and `../Params.cpp`.
+- Params.h, Params.cpp
 
 ## Rules
 
 - Use the `ids::` namespace for every APVTS parameter ID string.
 - Require one `ids::` entry per audio parameter, and one entry only.
-- Reach indexed parameters through the `paramIds::` arrays in `../Params.h`, which pair each
+- Reach indexed parameters through the `paramIds::` arrays in `Params.h`, which pair each
   ID with its slot: `paramIds::oscillators`, `paramIds::envAttack`, `paramIds::lfoRate`,
   `paramIds::fxType`, `paramIds::macros` and their siblings. Use a single `ids::` entry only
   when the parameter has no index.

Source/Plugin/AGENTS.md

@@ -1,9 +1,8 @@
 # plugin module
 
-## Related source files
+## Owned files
 
-This directory contains guidance; the implementation remains in
-`../PluginProcessor.h` and `../PluginProcessor.cpp`.
+- PluginProcessor.h, PluginProcessor.cpp
 
 ## Rules
 

Source/Presets/FactoryPresets.h

@@ -1,8 +1,8 @@
 #pragma once
 
 #include <JuceHeader.h>
-#include "../Params.h"
-#include "../ModulationMatrix.h"
+#include "Params.h"
+#include "ModulationMatrix.h"
 
 namespace serum
 {

Source/Resources/AGENTS.md

@@ -2,7 +2,7 @@
 
 ## Owned files
 
-- Related embedded assets and helpers: `../Resources.h`, `../Resources.cpp`
+- Resources.h, Resources.cpp
 - logo.svg
 - background.svg
 

Source/Synth/AGENTS.md

@@ -1,9 +1,6 @@
 # synth module
 
-## Related source files
-
-This directory contains guidance. All files listed below remain in the parent
-`Source/` directory.
+## Owned files
 
 - Wavetable.h, Wavetable.cpp
 - Oscillator.h, Oscillator.cpp

Source/Tests/TestMain.cpp

@@ -1,7 +1,7 @@
 #include <JuceHeader.h>
 #include <cmath>
 #include <iostream>
-#include "../PluginProcessor.h"
+#include "PluginProcessor.h"
 
 // ===========================================================================
 // Headless QA harness: instantiates the processor, plays notes through every