diff --git a/.gitignore b/.gitignore
index dc84959..caa98ed 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,2 +1,45 @@
+# Build
 build/
+Terion_artefacts/
 
+# Dependencies
+third_party/
+
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+Icon
+Icon?
+._*
+.Spotlight-V100
+.Trashes
+.fseventsd
+.TemporaryItems
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+.AppleDB
+.AppleDesktop
+Network Trash Folder
+Temporary Items
+.apdisk
+
+# VIM
+*.swp
+*.swo
+*~$~
+*~
+Session.vim
+
+# Editors / IDE
+.vscode/
+.idea/
+*.xcworkspace
+*.xcodeproj
+
+# Object files
+*.o
+*.obj
+
+# Xcode user data
+xcuserdata/
\ No newline at end of file
diff --git a/README.md b/README.md
index e69de29..3e941ef 100644
--- a/README.md
+++ b/README.md
@@ -0,0 +1,79 @@
+# Terion
+
+Real-time stereo analyzer and mid-side vector scope audio plugin for macOS.
+
+Terion visualizes the stereo field of any audio signal using a mid/side coordinate system. The X axis represents the Side (difference) signal and the Y axis represents the Mid (sum) signal, plotted as an XY vectorscope with a configurable phosphor-style fading trail. It is an analysis-only plugin — audio passes through unmodified.
+
+## Features
+
+- **Mid/Side vectorscope** — XY plot with phase-mapped color (correlated content in cyan/blue, out-of-phase content shifting toward red)
+- **Phosphor trail** — configurable fade time from 0.1 to 10 seconds for persistent visual history
+- **Real-time stereo metrics** — correlation, stereo width, mid/side levels, balance, phase angle, crest factor, and peak/RMS levels
+- **Freeze** — capture and hold the current display for inspection
+- **Resizable UI** — scales from 420×420 up to 1200×1200, with preset scale factors (100/125/150/200/300%)
+- **Custom arc knobs** — clean rotary controls with teal arc indicators
+- **VST3 and Audio Unit** formats
+
+## Requirements
+
+- macOS
+- CMake 3.22 or later
+- C++17 compiler (Xcode command line tools)
+- JUCE framework (cloned automatically by `make juce`, or use an existing `~/JUCE` install)
+
+## Building
+
+```sh
+make all        # configure + build (Release)
+make install    # build, codesign, un-quarantine, install to ~/Library/Audio/Plug-Ins
+```
+
+### Makefile targets
+
+| Target | Description |
+|---|---|
+| `make all` | Configure and build |
+| `make juce` | Clone JUCE into `third_party/JUCE` (skipped if `~/JUCE` exists) |
+| `make configure` | Run CMake configure only |
+| `make build` | Compile only |
+| `make install` | Build, codesign (ad-hoc), strip quarantine, install to user plug-in dirs |
+| `make sign` | Codesign installed bundles |
+| `make unquarantine` | Strip Gatekeeper quarantine xattrs from installed bundles |
+| `make uninstall` | Remove installed VST3 and AU bundles |
+| `make clean` | Remove `build/` |
+| `make deepclean` | Remove `build/`, `third_party/`, and stray artefacts |
+
+### Variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `BUILD_DIR` | `build` | CMake build directory |
+| `CONFIG` | `Release` | Build configuration |
+| `JOBS` | `$(ncpu)` | Parallel compilation jobs |
+| `CODESIGN_ID` | *(empty = ad-hoc)* | Codesign identity string |
+| `JUCE_DIR` | auto-detected | Override JUCE source location |
+
+## Parameters
+
+| Parameter | Range | Description |
+|---|---|---|
+| Fade | 0.1 – 10 s | Trail persistence time |
+| Sensitivity | -12 – +24 dB | Input gain for M/S decode |
+| Dot size | 0.5 – 3.0 px | Size of each plotted point |
+| Smoothing | 0 – 0.99 | One-pole smoothing on M/S signals |
+| Freeze | on/off | Stop capturing new points |
+
+## Project structure
+
+```
+terion/
+├── CMakeLists.txt          # JUCE plugin build configuration
+├── Makefile                # Build/install/sign wrapper
+├── Source/
+│   ├── PluginProcessor.*   # Audio engine: M/S decode, ring buffer, metrics
+│   ├── PluginEditor.*      # UI layout, knobs, freeze, scale, footer
+│   ├── VectorScope.*       # XY scope rendering, trail, legends, overlay
+│   ├── ArcKnob.*           # Custom rotary arc slider
+│   └── Version.h.in        # Git hash/timestamp template
+└── third_party/JUCE/       # JUCE framework (auto-cloned, gitignored)
+```