serumalt/AGENTS.md

<!-- graft:start -->
## Graft — repo context graph

This repo is indexed in `graft/`: small linked markdown nodes that explain each
system and carry exact file:line spans, kept in sync with the code through git.

For ANY task here — understanding how something works, finding where code lives,
or scoping a change — get context from the graph before grepping or opening
source files. Re-ask freely (it's cheap) and reuse literal identifiers you
already have (symbol, error string, file name) as the query. New to this repo?
Run `graft map` first — a token-budgeted orientation (dir clusters, hubs,
hotspots), no LLM, no key.

- Run `graft ask "<your question>" --source` → ranked nodes with the relevant
  code spans inlined (each hit's ≤8-line crux by default; `--full` for whole
  definitions when the crux isn't enough). Match the tool to the task shape:
  for understanding or editing, the top node IS the answer — cite its
  `covers:` file:line spans and edit straight from `--source`. For
  exhaustive tasks ("every occurrence / every caller of this pattern"), ranked
  results are top-N, not complete — run `graft grep "<literal>"` instead
  (exhaustive over indexed files, grouped by enclosing symbol), falling back
  to raw `grep -rn` only for unindexed files.
- `graft skeleton <file>` → every definition's signature + span, ~10× cheaper
  than reading the file; use it to skim an API surface.
- `graft callers <symbol>` gives precomputed, exact edges — who calls this.
  Add `--direction out` for what it calls, or `--depth N` to walk
  transitively for the full blast radius. For structural questions, skip
  ranking and use this directly.
- Or browse: `graft/INDEX.md` lists every node; follow the links.
- Monorepos and folders of multiple repos rank fairly across sub-projects —
  hits carry `[scope/]` labels naming which one they're from. Narrow with
  `graft ask "<task>" --in <scope>/` once you know where you're working.

If a returned span is truncated ("+N more lines"), open the file at that exact
range before finalizing. Only open source files when a node genuinely lacks a
needed detail, and then at the exact file:line the node points to — never
re-read whole files.

After big code changes, refresh the graph with `graft build` (deterministic,
no API key, $0).
<!-- graft:end -->

# 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.

## Development scope

This is a fun proof of concept. Prefer small working changes, clear names, and
successful compilation over release engineering or broad rewrites. Use the existing
smoke harness for DSP changes; add test infrastructure only when requested. The user
will judge sound and interaction by using the synth. Keep ownership and audio-thread
safety fixes practical, without adding a generic framework.

## 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: `./scripts/build_linux.sh`.
- macOS production, on a Mac: `./scripts/build_macos.sh`.
- Windows x64 VST3, cross-compiled on Linux: `./scripts/build_windows.sh`.
- Native QA build and execution: `./scripts/build_harness.sh --run`.
- Shell syntax: `for script in scripts/*.sh; do bash -n "$script"; done`.
- Build output removal: `./scripts/clean.sh --dry-run`, then the flags you need.

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. Each script defaults to a
directory under `build/`; 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
`cmake/mingw64-toolchain.cmake` is the single source of cross-compiler configuration.

## Current source layout

`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.

Every implementation lives in a module directory under `Source/`, and the
`AGENTS.md` in that directory owns its rules:

- `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

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.

The engine prebuilds wavetables and renders through bounded buffer views. GUI and
state edits hold `Engine::getControlLock()`; audio uses a try-lock to capture into
reserved storage and keeps its last snapshot when busy. Keep those two copies
separate. RAVE changes render settings, not the underlying knob values. The
historical audit describes the older implementation, not current behavior.

## 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.