docs: initialize project

.planning/PROJECT.md

@@ -0,0 +1,85 @@
+# LED Sync Studio
+
+## What This Is
+
+Eine Cyberpunk-Terminal-App (Python/Textual) zur Steuerung von LED-Streifen, die auf einem Raspberry Pi 4B laeuft und per SSH bedient wird. Die App ermoeglicht sowohl Song-Choreografie (Animationen manuell auf Zeitpunkte im Song mappen) als auch Live-Reaktiv-Modus (Beat-Detection aus System-Audio). Die Animationen laufen lokal auf einem ESP32-C3, der per JSON-Kommandos ueber WiFi gesteuert wird.
+
+## Core Value
+
+Songs mit LED-Animationen choreografieren und abspielen — der Nutzer baut Timeline-basierte Lichtshows zu seiner Musik.
+
+## Requirements
+
+### Validated
+
+(None yet — ship to validate)
+
+### Active
+
+- [ ] Song abspielen und an beliebiger Stelle stoppen/fortsetzen
+- [ ] Animationen auf Zeitpunkte im Song zuweisen (Choreografie-Editor)
+- [ ] Timeline-Ansicht (horizontal, Song laeuft links-rechts, Animationen als Bloecke)
+- [ ] Event-Liste-Ansicht (tabellarisch, Zeitpunkte mit Animationen)
+- [ ] Loop-Funktion fuer Animationen (Wiederholungen definieren)
+- [ ] Vielzahl an LED-Animationen (Farbwechsel, Lauflichter, Pulsieren, Spektrum, etc.)
+- [ ] Animationen mit Parametern konfigurierbar (Farbe, Speed, Intensitaet, etc.)
+- [ ] 2 LED-Zonen unabhaengig steuerbar (WS2801 Schrank + SK6812 Wand)
+- [ ] Choreografien als Dateien speichern und laden (JSON/YAML)
+- [ ] Live-Reaktiv-Modus mit Beat-Detection aus System-Audio (PipeWire/PulseAudio)
+- [ ] Lokale Songdateien abspielen (MP3/FLAC/WAV)
+- [ ] Streaming-Dienst-Integration (Spotify o.ae.) als Audio-Quelle
+- [ ] ESP32-C3 Firmware: Animationen lokal ausfuehren, JSON-Kommandos empfangen
+- [ ] Pi-zu-ESP Kommunikation ueber WiFi (JSON-Protokoll)
+- [ ] Cyberpunk/Neon Terminal-UI mit Textual
+
+### Out of Scope
+
+- Frame-Streaming vom Pi zum ESP — ESP fuehrt Animationen lokal aus, Pi sendet nur Kommandos
+- Web-UI oder GUI — reines Terminal mit Textual
+- Mehr als ein ESP32 — beide Strips laufen an einem ESP32-C3
+
+## Context
+
+- **Hardware:** ESP32-C3 SuperMini mit 2 LED-Strips: WS2801 5m/160 LEDs (U-Turn um Schrank) und SK6812 5m/300 LEDs (Wand entlang)
+- **Host:** Raspberry Pi 4B, Zugriff per SSH vom Laptop
+- **Kommunikation:** Pi sendet JSON-Kommandos an ESP ueber WiFi — keine Frame-Daten, nur Animation-Name + Parameter
+- **Audio:** System-Audio-Stream (PipeWire/PulseAudio) fuer Beat-Detection und Song-Playback
+- **Firmware:** ESP32-C3 Firmware muss komplett neu gebaut werden (Arduino/ESP-IDF)
+- **UI-Style:** Cyberpunk/Neon — leuchtende Neonfarben, dunkler Hintergrund, Glitch-Aesthetic
+
+## Constraints
+
+- **Platform**: Raspberry Pi 4B (ARM, Linux) — App muss performant auf Pi laufen
+- **Terminal**: Textual TUI Framework (Python) — muss ueber SSH funktionieren
+- **ESP**: ESP32-C3 SuperMini — begrenzter Speicher, ein Core, WiFi only
+- **LED-Protokoll**: WS2801 (SPI/Clock+Data) und SK6812 (single-wire like NeoPixel) — unterschiedliche Ansteuerung
+- **Latenz**: JSON-Kommandos muessen schnell genug sein fuer musikalische Synchronisation
+
+## Key Decisions
+
+| Decision | Rationale | Outcome |
+|----------|-----------|---------|
+| Animationen laufen auf ESP, nicht gestreamt | Reduziert WiFi-Last und Latenz, ESP ist autonom | -- Pending |
+| Ein ESP fuer beide Strips | Einfacheres Setup, ESP32-C3 hat genug GPIOs | -- Pending |
+| Textual als UI-Framework | Terminal-basiert, laeuft ueber SSH, Python-Oekosystem | -- Pending |
+| JSON ueber WiFi (Pi->ESP) | Einfach, flexibel, kein Kabel noetig | -- Pending |
+
+## Evolution
+
+This document evolves at phase transitions and milestone boundaries.
+
+**After each phase transition** (via `/gsd:transition`):
+1. Requirements invalidated? -> Move to Out of Scope with reason
+2. Requirements validated? -> Move to Validated with phase reference
+3. New requirements emerged? -> Add to Active
+4. Decisions to log? -> Add to Key Decisions
+5. "What This Is" still accurate? -> Update if drifted
+
+**After each milestone** (via `/gsd:complete-milestone`):
+1. Full review of all sections
+2. Core Value check — still the right priority?
+3. Audit Out of Scope — reasons still valid?
+4. Update Context with current state
+
+---
+*Last updated: 2026-04-03 after initialization*