diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f41e843
--- /dev/null
+++ b/README.md
@@ -0,0 +1,66 @@
+# BEAMGRID
+
+A JUCE-based VST3 / AU spectrum analyzer with a fully black UI, teal accents,
+and a configurable display.
+
+![build](https://img.shields.io/badge/build-rolling-blue)
+
+## Features
+
+- **Three display modes** (top-right `MODE` knob):
+  - **BARS** — classic log-spaced spectrum bars with peak-hold caps.
+  - **SPECTRUM** — a smooth (quadratic-spline) waveform trace of the spectrum,
+    with a matching smooth peak-hold wave. Use the `SMOOTH` knob to go from
+    raw/edgy to heavily smoothed.
+  - **LED** — an LED-meter style view (`LEDS` knob sets LEDs per bar).
+- **Frequency range** fixed to **20 Hz – 20 kHz**.
+- **HUE** knob rotates the hue of every UI accent (knob arcs, peaks, title)
+  without altering the underlying data.
+- **UI scaling** dropdown (75% – 300%) in the top-right.
+- Per-project **size & scale persistence** (stored in the plugin state).
+
+## Parameters
+
+| Knob        | Range            | Description                                   |
+|-------------|------------------|-----------------------------------------------|
+| PEAK GRACE  | 0 – 2000 ms      | Grace period before a peak-hold marker decays |
+| PEAK FALLOFF| 0 – 1            | Peak-hold decay rate                          |
+| BAR FALLOFF| 0 – 1            | Spectrum bar release speed                    |
+| BARS        | 8 / 16 / 32 / 64 / 128 | Number of spectrum bands (snaps)          |
+| HUE         | 0 – 1            | Rotates the UI accent hue (0.5 = no change)   |
+| MODE        | 1 / 2 / 3        | BARS / SPECTRUM / LED                         |
+| LEDS        | 4 – 48           | LEDs per bar in LED mode                      |
+| SMOOTH      | 0 – 1            | Waveform smoothing amount in SPECTRUM mode    |
+
+## Building
+
+Requires [CMake](https://cmake.org/) (>= 3.22) and a JUCE-supported
+toolchain (Xcode / clang on macOS, MSVC / GCC on Windows, etc.). JUCE is
+fetched automatically by CMake.
+
+```sh
+cmake -B build -G Ninja
+cmake --build build --config Release
+```
+
+The built plugins are installed to your system plugin folders:
+
+- `build/BEAMGRID_artefacts/Release/VST3/BEAMGRID.vst3`
+- `build/BEAMGRID_artefacts/Release/AU/BEAMGRID.component`
+
+Then rescan in your DAW (FL Studio, REAPER, Logic, etc.).
+
+## Project layout
+
+```
+Source/
+  PluginProcessor.cpp/.h   Audio processor + parameter layout
+  PluginEditor.cpp/.h      Editor UI, knobs, layout
+  Analyser.h/.cpp          FFT analysis, banding, peak-hold
+  AnalyserComponent.h      Drawing (BARS / SPECTRUM / LED)
+  BeamgridLookAndFeel.h    Black/teal styling, hue rotation, rotary drawing
+```
+
+## License
+
+See the repository license file.