diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..c41a4b4
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,61 @@
+# AGENTS.md
+
+Guidance for working in this repository.
+
+## Project
+
+Horizont is a stereo algorithmic reverb audio plugin (VST3 / AU) for macOS.
+It pairs a Schroeder/Moorer reverb core (diffusion allpass + parallel damped
+combs, gains derived from RT60) with a granular feedback pitch-shifter loop.
+Built with JUCE and C++17. See `README.md` for the full DSP description.
+
+## Build & test
+
+From the repo root:
+
+```
+make            # fetches JUCE 8.0.15 into ./JUCE if missing, configures + builds (Release)
+make install    # installs into ~/Library/Audio/Plug-Ins/VST3 and .../Components
+make clean      # delete the build directory
+```
+
+- Build artefacts land in `build/Horizont_artefacts/Release/`.
+- JUCE must be a **8.0.x release tag** — JUCE 9/master refactored the
+  LookAndFeel API and is not supported.
+- Configure manually with `cmake -B build -DCMAKE_BUILD_TYPE=Release -DJUCE_ROOT="$(pwd)/JUCE"`.
+- There are **no unit tests** in this project. Verify by building, then
+  loading the plugin in a host (or `auval` for the AU).
+- C++17 only; avoid pre-C++17 and post-C++17 features.
+
+## Layout
+
+```
+CMakeLists.txt          build config; new source files must be added here
+Makefile                one-command macOS build/install
+Source/
+  PluginProcessor.*     processor, APVTS, state save/load, host program (presets)
+  PluginEditor.*        layout, panels, preset combo box
+  HorizontEngine.*      reverb DSP core (allpass diffusers + comb bank + feedback loop)
+  PitchShifter.*        granular crossfade pitch shifter
+  HorizontLookAndFeel.* dark teal theme, skeuomorphic rotary knobs
+  Knob.*                knob component (slider + caption + value readout)
+  SpectrumDisplay.*     animated wet/dry spectrum analyser (FFT, timer-driven paint)
+  Presets.h             factory presets
+```
+
+## Conventions
+
+- Follow JUCE style: `lowerCamelCase` methods/variables, `UpperCamelCase`
+  classes, leading-underscore members in some files (match the file you edit).
+- Match existing brace/paren style exactly (`juce::` type usage, trailing
+  space, tabs for indentation).
+- No dynamic allocation in audio callbacks — the processor uses pre-sized
+  buffers and `juce::SmoothedValue` for per-sample parameter smoothing.
+- All DSP is sample-rate independent: delay lengths, filters, and grain
+  windows scale with the sample rate.
+- Only add source files after updating `target_sources(...)` in `CMakeLists.txt`.
+- Do not add comments unless they explain a non-obvious DSP decision; the
+  existing code is mostly self-documenting.
+- The UI is a dark teal hardware-rack style; new UI code should match the
+  existing palette in `HorizontLookAndFeel.h` / `SpectrumDisplay.cpp` rather
+  than introducing new themes.