From bf518d78b395df26d922c7c95f778ab1a027f4bf Mon Sep 17 00:00:00 2001
From: Shawn <shawn@ourpad.casa>
Date: Mon, 25 May 2026 20:19:00 -0400
Subject: [PATCH] Add AGENTS.md for AI agent context

---
 AGENTS.md | 106 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 106 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..198f2ce
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,106 @@
+# Raspberry Pi Mixer — Agent Guide
+
+Professional 16-channel real-time audio mixer on Raspberry Pi 4B. Sub-10ms latency with USB audio, MIDI controllers, touchscreen UI, multi-track recording, live streaming, and web control surface.
+
+## Stack
+
+- **Python** 3.11+, **JACK2** (PREEMPT_RT kernel)
+- **Carla** — LV2/VST/NAM plugin host
+- **FastAPI** + **uvicorn** — REST API + WebSocket
+- **Kivy** — touchscreen UI
+- **GStreamer** — live streaming
+- **numpy**, **python-jack-client**
+- **pytest** — 735 tests
+
+## Project Structure
+
+```
+src/
+  mixer/          # DSP engine, channel strips, bus manager, routing matrix
+  midi/           # MIDI engine, learn mode, clock sync, device discovery
+  session/        # Session manager, setlists, snapshots
+  recording/      # Multi-track WAV recorder, bounce, disk monitor
+  backing/        # Backing track player, metronome, transport
+  streaming/      # GStreamer pipeline, platform presets, camera
+  network/        # FastAPI REST API + WebSocket + OSC server
+  plugin/         # Plugin manager, LV2/VST/NAM support, scanner
+  ui/             # Kivy touchscreen UI
+
+main_touch.py     # Touchscreen UI entry point
+
+config/
+  99-audio.conf           # ALSA USB audio config
+  99-midi.rules           # udev rules for MIDI
+  jackdrc                 # JACK2 configuration
+  carla-8ch-default.carxp # Carla patchbay preset
+  usb-audio-quirks.conf   # USB audio quirks
+
+build/
+  build.sh                # SD card image builder
+  configure-system.sh     # System configuration
+  first-boot/             # First-boot setup wizard
+
+docs/
+  build-guide.md          # Hardware assembly + OS setup
+  user-manual.md          # End-user documentation
+  developer-guide.md      # Architecture + extending
+  troubleshooting.md      # Common issues
+  hardware-compatibility.md
+  midi-controller-support.md
+  audio-stack-config.md
+  carla-integration.md
+  touchscreen-ui-evaluation.md
+  decisions/              # Architecture Decision Records
+  research/               # Research reports
+
+tests/                    # pytest suite (735 tests)
+```
+
+## How to Run
+
+```bash
+# On the Pi itself:
+
+# Audio API server
+python -m src.network.run
+
+# Touchscreen UI
+python main_touch.py
+
+# Or via systemd (production):
+sudo systemctl start mixer-api
+sudo systemctl start mixer-ui
+```
+
+## Systemd Services
+
+| Service | Purpose | Port | User |
+|---------|---------|------|------|
+| `cpu-performance.service` | CPU governor → performance | — | root |
+| `jackd.service` | JACK2 audio server (SCHED_FIFO prio 70) | — | root |
+| `mixer-api.service` | FastAPI REST/WebSocket API | 8080 | pi:audio |
+| `mixer-ui.service` | Kivy touchscreen UI | — | pi:audio |
+| `mixer-firstboot.service` | First-boot setup | — | root |
+
+## Production
+
+- **URL:** `http://pi-mixer.local:8080`
+- **Audio:** JACK2 at 48kHz/128 frames, ALSA hw:USB interface
+- **OS:** PREEMPT_RT kernel 6.12.y on Raspberry Pi 4B
+- **Plugins:** Carla hosts LV2, VST3, and NAM (Neural Amp Modeler)
+- **License:** MIT
+
+## Environment & Config
+
+Key config files under `/opt/rpi-mixer/config/`:
+- `jackdrc` — JACK2 server parameters (sample rate, buffer size, ALSA device)
+- `99-midi.rules` — USB MIDI device permissions
+- `99-audio.conf` — ALSA audio limits for `pi` user
+
+## Pitfalls
+
+- **Real-time audio** — all DSP code must avoid blocking calls, file I/O in audio thread
+- **PREEMPT_RT kernel** required for sub-10ms latency — building from source via `build/build.sh`
+- JACK2 config varies by USB audio interface — `config/jackdrc` may need per-device tuning
+- Plugin blacklist in `src/plugin/` prevents known-crash plugins at scan time
+- SD card image builder in `build/` — modifications to base image need careful tracking