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.

AGENT.md

@@ -0,0 +1,83 @@
+# SerumAlt agent guidance
+
+## Project
+
+SerumAlt is a JUCE 7 wavetable synthesiser using C++17. Project metadata is in
+`CMakeLists.txt`. Production formats are VST3 and Standalone on Linux, VST3/AU/Standalone
+on macOS, and VST3 on Windows. First-party classes use `namespace serum`; executable
+entry points and JUCE's `createPluginFilter` are outside that namespace.
+
+## Build and verification
+
+Read README.md's Building section before changing scripts, dependencies, or CMake.
+It is the maintained source for prerequisites, options and artifact paths.
+
+- Linux production: `./build_linux.sh`.
+- macOS production, on a Mac: `./build_macos.sh`.
+- Windows x64 VST3, cross-compiled on Linux: `./build_windows.sh`.
+- Native QA build and execution: `./build_harness.sh --run`.
+- Shell syntax: `for script in build_*.sh; do bash -n "$script"; done`.
+
+Production scripts explicitly enable `SERUMALT_BUILD_PLUGIN` and disable
+`SERUMALT_BUILD_TESTS`. The harness script does the reverse in a separate directory.
+Building `SerumAltTest` alone does not execute it; `--run` invokes CTest.
+When changing CMake, verify production has no `SerumAltTest` target and the
+harness-only build has no `SerumAlt`, VST3, AU, or Standalone target.
+
+Keep existing build trees and local changes intact. Use a new `BUILD_DIR` for
+clean-build verification. Use a fresh Windows `OUTPUT_DIR` for distribution checks,
+since staging does not remove extra files. Never edit generated CMakeCache.txt files.
+The checked-in MinGW toolchain is the single source of cross-compiler configuration.
+
+## 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.
+
+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`.
+
+The lowercase `Source/engine`, `modulation`, `params`, `plugin`, and `synth`
+directories currently hold guidance, not relocated implementations. Consult their
+AGENT.md files when editing the related root-level sources. Consult the matching
+AGENT.md when editing an existing implementation subdirectory.
+`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.
+
+## Style and ownership
+
+Follow the surrounding file. Existing C++ generally uses four-space indentation,
+`#pragma once`, PascalCase types, camelCase members without prefixes, `k`-prefixed
+constants, scoped enums, and `noexcept` on cheap getters and DSP paths. Use `Count`
+only for enums that need a size or iteration sentinel. Headers include JuceHeader;
+implementation files normally include their own header first.
+
+Prefer value members or `std::unique_ptr` for owned objects and attachments.
+`addAndMakeVisible` does not transfer ownership or delete children. Raw allocations
+returned by `createEditor` and `createPluginFilter` transfer ownership to JUCE callers.
+Guard parameter lookups and invalid state data. Use `jassert` sparingly for programmer
+errors and return `bool` from bounded inserts to report failure.
+
+## Real-time and concurrency requirements
+
+For new or changed audio paths, allocate buffers during preparation and avoid heap
+allocation, blocking locks and I/O in `processBlock` or per-sample DSP. Account for
+variable host block sizes without allocating in the callback. Keep GUI updates on
+the JUCE message thread. Exchange GUI/audio state through a safe snapshot or bounded
+handoff; a timer or a writer-only mutex does not make concurrent access safe.
+
+These are requirements, not claims that the current code already satisfies them.
+The historical audit records lazy wavetable allocation, per-block buffer resizing,
+and unsynchronised modulation/LFO edits. When changing those paths, inspect the
+current implementation and verify the fix separately. The QA smoke test does not
+prove real-time safety or absence of data races.
+
+## Scope of guidance
+
+Module guidance refines this file for its related sources. Preserve the root
+real-time and ownership requirements if an example conflicts with them.