Feat: documentation

docs/getting-started/engine.md

@@ -0,0 +1,52 @@
+# The Audio Engine
+
+The Engine page (`F6`) is where you configure audio hardware, adjust performance settings, and manage your sample library. The right side of the page shows a real-time oscilloscope and spectrum analyzer. The page is divided into three sections. Press `Tab` to move between them, `Shift+Tab` to go back.
+
+## Devices
+
+Two columns show available output and input devices. Press `Left` or `Right` to switch between them. Browse with `Up`/`Down` and press `Enter` to select a device. Use `PageUp`/`PageDown` to scroll long device lists. Press `D` to refresh the device list if you plugged something in after launching Cagire.
+
+## Settings
+
+Four audio parameters are adjustable with `Left`/`Right`:
+
+| Setting | Range | Description |
+|---------|-------|-------------|
+| Channels | 1–64 | Number of output channels |
+| Buffer | 64–4096 | Audio buffer size in bytes |
+| Voices | 1–128 | Maximum polyphony (simultaneous sounds) |
+| Nudge | -100 to +100 ms | Timing offset to compensate for latency |
+
+The last two rows — sample rate and audio host — are read-only values reported by your system. After changing the buffer size or channel count, press `Shift+r` to restart the audio engine for changes to take effect.
+
+## Samples
+
+This section shows how many sample directories are registered and how many files have been indexed. Press `A` to open a file browser and add a new sample directory. Press `D` to remove the last one. Cagire indexes audio files (wav, mp3, ogg, flac, aac, m4a) from all registered paths.
+
+Sample directories must be added here before you can use the sample browser or reference samples in your scripts.
+
+## Audio Controls
+
+A few keys work from anywhere on the Engine page:
+
+- `h` — Hush. Silence all audio immediately.
+- `p` — Panic. Hard stop, clears all active voices.
+- `t` — Test tone. Plays a brief sine wave to verify audio output.
+- `r` — Reset the peak voice counter.
+
+## Keybindings
+
+| Key | Action |
+|-----|--------|
+| `Tab` / `Shift+Tab` | Next / previous section |
+| `Up` / `Down` | Navigate within section |
+| `Left` / `Right` | Switch device column / adjust setting |
+| `PageUp` / `PageDown` | Scroll device list |
+| `Enter` | Select device |
+| `D` | Refresh devices / remove last sample path |
+| `A` | Add sample directory |
+| `Shift+r` | Restart audio engine |
+| `h` | Hush |
+| `p` | Panic |
+| `t` | Test tone |
+| `r` | Reset peak voices |