Struktur, Doku und S0-Toolchain fuer das abdulive-Toolkit

Monorepo-Geruest fuer neun Streamer-Tools plus den Ingest-Daemon, der
unter sechs davon liegt. Enthaelt:

- docs/: Ueberblick, Architektur, Twitch-Integration, Datenmodell,
  Roadmap, Setup, Hebel-Analyse und den MVP-Plan "Clip-Knopf"
- docs/projects/: je eine Spezifikation pro Tool
- docs/decisions/: vier ADRs (TS-Monorepo, SQLite, EventSub/IRC, Docker)
- docker/: Image mit ffmpeg und whisper.cpp, abhaengigkeitsfreier
  Entrypoint mit check-env, fetch-model und calibrate
- config/layout.yaml: aus einem VOD-Screenshot eingemessener
  Facecam-Ausschnitt (440x330 oben links, Chat-Overlay ab x=1270)

Noch kein Anwendungscode - Scheibe S0 aus docs/07-mvp-plan.md.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013VTGjd92LsDDWF3frd9FTB

docs/projects/chat-control.md

@@ -0,0 +1,95 @@
+# 7 — Chat steuert Dinge (`apps/overlay-server` + `apps/overlay-web`)
+
+**Wirkrichtung:** Bindung. Aus Zuschauen wird Mitmachen.
+
+## Aufbau
+
+```
+Chat-Command ──► overlay-server (4791) ──► WS ──► Browser-Source in OBS
+                        │
+                        ├──► obs-websocket   (Szenen, Filter, Quellen, Hotkeys)
+                        ├──► Home Assistant / WLED  (Licht)
+                        └──► Helix            (Umfragen, Titel)
+```
+
+`overlay-server` ist ein Fastify-Server, der drei Dinge tut: Overlay-Seiten
+ausliefern, den WS-Kanal zu den Browser-Sources halten, und Commands vom
+Event-Bus in Aktionen übersetzen.
+
+## Overlay-Seiten (Browser-Sources in OBS)
+
+| Pfad | Zweck | Größe |
+|---|---|---|
+| `/overlay/alerts` | Follow/Sub/Raid-Einblendungen | 1920x1080 |
+| `/overlay/effects` | Emote-Regen, Soundboard-Feedback, Konfetti | 1920x1080 |
+| `/overlay/community` | Chatter-Hinweis (nur für Abdu) | 480x220 |
+| `/overlay/poll` | laufende Umfrage | 480x600 |
+| `/overlay/game` | Minigame-Anzeige | 1920x1080 |
+| `/overlay/raid-panel` | Raid-Ziele am Streamende | 900x600 |
+
+Alle Seiten teilen sich einen WS-Client (`packages/shared/overlay-client.ts`)
+mit automatischem Reconnect — eine Browser-Source, die nach einem Serverneustart
+tot bleibt, ist der häufigste Fehler bei solchen Overlays.
+
+## Command-Registry
+
+Commands liegen deklarativ in `config/commands.yaml`:
+
+```yaml
+- trigger: "!sound"
+  args: [name]
+  cooldown: { global: 20, user: 120 }
+  permission: everyone
+  cost: 50            # Punkte, optional
+  action: { type: sound, file: "sounds/{name}.mp3" }
+
+- trigger: "!licht"
+  args: [farbe]
+  cooldown: { global: 60 }
+  permission: subscriber
+  action: { type: wled, preset: "{farbe}" }
+```
+
+Aktionstypen: `sound`, `overlay-effect`, `obs-hotkey`, `obs-source-toggle`,
+`obs-filter`, `wled`, `helix-poll`, `set-title`, `script`.
+
+**Cooldowns und Rechte sind nicht optional.** Ein Soundboard ohne Cooldown ist
+nach zwei Streams abgeschaltet. Default: 20 s global, 120 s pro User,
+Sounds nur für Follower.
+
+## Minispiele
+
+Ausbaustufe 2. Kandidaten, die bei kleinem Chat funktionieren (wichtig: sie
+dürfen mit 3 Mitspielern genauso gut sein wie mit 30):
+
+- **Tipprunde** — `!tipp <zahl>`, Abdu löst auf, Punkte für die Nächsten
+- **Kollektive Entscheidung** — Helix-Umfrage mit echter Konsequenz im Spiel
+- **Boss-Bingo** — Karte im Overlay, Chat ruft Felder aus
+
+## Umfragen mit Konsequenz
+
+`!umfrage` startet eine Helix-Poll (`POST /helix/polls`). Bei `poll.end` führt
+der Server die hinterlegte Aktion zur Gewinneroption aus — Szenenwechsel,
+Schwierigkeitsgrad, nächstes Spiel. Der Unterschied zu einer normalen Umfrage
+ist, dass das Ergebnis automatisch etwas tut, statt nur angezeigt zu werden.
+
+## Sicherheit
+
+Alles, was den Stream sichtbar verändert oder Geräte im Haus schaltet, ist
+missbrauchbar. Deshalb:
+
+- `overlay-server` bindet nur auf `127.0.0.1`.
+- Der Panik-Command `!aus` (Mods) schaltet alle Effekte für 10 min ab.
+- Aktionen mit `requires_approval: true` erscheinen erst in einer Warteschlange
+  im Overlay-Panel und laufen nach Abdus Klick.
+- Kein Command darf beliebigen Text auf dem Bildschirm anzeigen. TTS und freie
+  Textanzeigen sind bewusst nicht Teil von Ausbaustufe 1.
+
+## Abnahmekriterien
+
+- `!sound huch` spielt innerhalb von 300 ms den Sound ab.
+- Cooldown greift und wird im Chat sichtbar quittiert (einmal, nicht bei jedem
+  Versuch).
+- OBS-Neustart oder Server-Neustart: Browser-Source verbindet sich innerhalb von
+  5 s automatisch neu.
+- `!aus` stoppt sofort alle laufenden Effekte.