Uebergabe: Stand, offene Punkte, Einstieg fuer den naechsten

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

README.md

@@ -39,6 +39,9 @@ Dazu der Dienst, der unter allen anderen liegt:
 - [`docs/05-setup.md`](docs/05-setup.md) — Lokal einrichten
 - [`docs/06-hebel-analyse.md`](docs/06-hebel-analyse.md) — **Womit anfangen und warum**
 - [`docs/07-mvp-plan.md`](docs/07-mvp-plan.md) — **MVP „Clip-Knopf": Umfang, Scheiben, Zeitplan**
+- [`docs/handoff.md`](docs/handoff.md) — **Übergabe: Stand, Fallstricke, wo weitermachen**
+- [`docs/offene-punkte.md`](docs/offene-punkte.md) — was noch fehlt
+- [`docs/obs-layout.md`](docs/obs-layout.md) — die Layout-Vorgabe für OBS
 - [`docs/projects/`](docs/projects/) — je ein Spec-Dokument pro Tool
 - [`docs/decisions/`](docs/decisions/) — Architekturentscheidungen (ADRs)
 
@@ -62,10 +65,14 @@ Datei im Projekt ([ADR-0005](docs/decisions/ADR-0005-zugangsdaten.md)).
 
 ## Aktueller Stand
 
-Scheiben **S0 und S1** des MVP „Clip-Knopf" sind fertig: Container-Toolchain,
+Vier von sieben Scheiben des MVP „Clip-Knopf" sind gebaut: Container-Toolchain,
-Einrichtung im Browser, Twitch-Auth, Datenbank und Chat-Aufnahme. Als Nächstes
+Einrichtung im Browser, Twitch-Auth, Datenbank, Chat-Aufnahme, OBS-Anbindung mit
-S2 — OBS-Anbindung und der `!clip`-Trigger. Fahrplan:
+`!clip`, 9:16-Render und Untertitel. 53 Tests grün.
-[`docs/07-mvp-plan.md`](docs/07-mvp-plan.md).
+
+Offen: die Abnahme der OBS-Anbindung an einem laufenden OBS, dann S5 —
+Onboarding-Assistent und Sichtungsseite.
+
+Details: [`docs/handoff.md`](docs/handoff.md)
 
 ## Tests
 

docs/handoff.md

@@ -0,0 +1,113 @@
+# Übergabe
+
+Stand **2026-09-09**. Wer hier weitermacht, sollte diese Seite zuerst lesen und
+danach [`07-mvp-plan.md`](07-mvp-plan.md).
+
+## Wo das Projekt steht
+
+Vier von sieben Scheiben des MVP „Clip-Knopf" sind gebaut. Die Kette vom
+Auslöser bis zum fertigen Short steht **im Code vollständig** — geprüft ist sie
+überall dort, wo es ohne Abdus Stream-PC ging.
+
+| Scheibe | Stand | Nachweis |
+|---|---|---|
+| S0 Container + Toolchain | fertig | `check-env` ohne harte Fehler |
+| S1 Einrichtung, Auth, DB, Chat | fertig | Daemon läuft, Chat verbunden, Secrets verschlüsselt |
+| S2 OBS + `!clip` | Code fertig, **nicht abgenommen** | braucht laufendes OBS |
+| S3 9:16-Render | fertig | Durchlauf mit künstlicher Aufnahme |
+| S4 Untertitel | fertig | Durchlauf mit echtem deutschen Clip |
+| S5 Onboarding + Sichtung | offen | — |
+| S6 Erstchatter-Begrüßung | offen | — |
+
+53 Tests, alle grün. Vollständige Liste dessen, was noch fehlt:
+[`offene-punkte.md`](offene-punkte.md).
+
+## Was jemand wissen muss, bevor er etwas anfasst
+
+**Es gibt keine Abhängigkeiten und keinen Build.** Node 24 bringt SQLite,
+WebSocket, `fetch` und die Ausführung von TypeScript mit. `node docker/entrypoint.ts`
+läuft direkt. Deshalb gilt: nur *löschbare* TypeScript-Syntax — keine `enum`,
+keine Parameter-Properties im Konstruktor, keine `namespace`. `erasableSyntaxOnly`
+in der `tsconfig.json` erzwingt das und hat schon einen echten Fehler gefangen.
+
+**Alles läuft unter einem Dach**, einem Prozess in einem Container. Schwere
+Arbeit (ffmpeg, whisper) läuft als Kindprozess und darf abstürzen. Der Ingest
+darf nie sterben — was er nicht mitschreibt, ist für immer weg.
+
+**Zugangsdaten kommen aus der Weboberfläche**, nicht aus einer Datei. Sie liegen
+verschlüsselt in einem Docker-Volume, bewusst außerhalb der Datenbank, weil die
+gesichert und dabei auf die Windows-Seite kopiert wird.
+
+**Rohdateien gehören ins Arbeits-Volume**, nicht in den Windows-Bind-Mount. Über
+die WSL2-Brücke zu encodieren kostet ein Vielfaches. Dagegen habe ich einmal
+selbst verstoßen — der Fehler fiel erst in S3 auf.
+
+Die Begründungen stehen in [`decisions/`](decisions/), sechs ADRs. Wer eine
+davon umwerfen will, sollte sie vorher lesen; jede hat einen Grund, der beim
+Bauen aufgetaucht ist.
+
+## Loslegen
+
+```powershell
+git clone https://git.zeasy.dev/ZeasyAlex/abdulive.git
+cd abdulive
+Copy-Item config\config.example.yaml config\config.yaml
+
+docker compose build
+docker compose run --rm toolkit check-env
+docker compose run --rm toolkit fetch-model     # ca. 465 MB
+docker compose up -d
+```
+
+Dann `http://localhost:4792/setup` öffnen. Ausführlich in
+[`05-setup.md`](05-setup.md).
+
+Tests:
+
+```powershell
+docker run --rm -v "${PWD}:/app" -w /app node:24-bookworm-slim `
+  node --test "packages/**/*.test.ts" "apps/**/*.test.ts"
+```
+
+Typprüfung (das Einzige, wofür npm gebraucht wird):
+
+```powershell
+docker run --rm -v "${PWD}:/app" -w /tmp node:24-bookworm-slim sh -c `
+  "npm i -s typescript@5.9 @types/node && cd /app && /tmp/node_modules/.bin/tsc --noEmit --typeRoots /tmp/node_modules/@types"
+```
+
+## Die drei Dinge, die Abdu tun muss
+
+1. **Zwei Twitch-Apps anlegen** (dev.twitch.tv/console/apps), Redirect-URI
+   `http://localhost:4792/callback`. Client-ID und Secret danach auf der
+   Einrichtungsseite eintragen — nicht in eine Datei.
+2. **OBS einrichten**: obs-websocket an (Port 4455), Wiedergabepuffer 90 s,
+   Hotkey auf „Wiedergabepuffer speichern", getrennte Audiospuren.
+3. **Layout umstellen** nach [`obs-layout.md`](obs-layout.md). Die
+   Ausrichtungsvorlage in OBS über die Szene legen, Quellen einpassen, wieder
+   ausblenden. Danach `calibrate` zur Kontrolle.
+
+Ohne Punkt 1 liest das Toolkit den Chat anonym mit und kann nichts senden.
+Ohne Punkt 2 gibt es keine Clips. Ohne Punkt 3 sitzt der Ausschnitt schief.
+
+## Wo ich weitermachen würde
+
+**S5.** Nicht wegen des Codes, sondern weil das Werkzeug ohne Einrichtungs-
+Assistenten und Sichtungsseite für Abdu nicht bedienbar ist. Die Kette
+funktioniert, aber sie hat noch keine Oberfläche, die jemand ohne Erklärung
+benutzt. Abnahmekriterium steht im Plan: *Ein Fremder kommt von „nichts
+eingerichtet" bis zum ersten eigenen Clip, ohne die Dokumentation zu lesen.*
+
+Davor, wenn Gelegenheit ist: **S2 an einem laufenden OBS abnehmen**. Das ist
+die einzige ungeprüfte Stelle in der ganzen Kette, und alles Weitere hängt
+daran.
+
+## Womit ich nicht zufrieden bin
+
+Die Untertitel sind brauchbar, nicht gut. `ggml-small` verhört sich hörbar
+(„Danke" wurde „Dank es"), die Schrift ist unauffällig, und das fortlaufende
+Einfärben ist nicht der Stil, der auf Shorts trägt. Sechs konkrete
+Verbesserungen stehen in [`offene-punkte.md`](offene-punkte.md).
+
+Und: Das Aufräumen im Arbeits-Volume fehlt komplett. Rohdateien sammeln sich
+unbegrenzt an. Das ist die Lücke, die als Erstes weh tun wird.

docs/offene-punkte.md

@@ -0,0 +1,82 @@
+# Offene Punkte
+
+Stand 2026-09-09. Sortiert nach Dringlichkeit, nicht nach Aufwand.
+Erledigtes wandert raus, nicht ins Archiv — die Historie steht in Git.
+
+## Blockiert, bis jemand am Stream-PC sitzt
+
+- [ ] **S2 abnehmen.** Der obs-websocket-Client ist gebaut und getestet, soweit
+      es ohne OBS geht: Anmeldeverfahren, Pfadübersetzung, Warten auf die
+      fertige Datei. Ungeprüft ist das tatsächliche Gespräch mit einem
+      laufenden OBS. Bis dahin ist `!clip` nicht bewiesen.
+- [ ] **Strecke IRC → Datenbank im Livebetrieb.** Die Teile sind einzeln
+      getestet, die Verdrahtung wird erst beim ersten echten Stream sichtbar.
+- [ ] **Layout umstellen** nach [`obs-layout.md`](obs-layout.md) und danach
+      `calibrate` laufen lassen.
+
+## Bekannte Lücke im Betrieb
+
+- [ ] **Aufräumen im Arbeits-Volume.** Jede Rohdatei landet unter `/work/<clipId>/`
+      und bleibt dort liegen. Bei fünf Clips pro Stream und mehreren hundert MB
+      je Datei läuft das Volume in wenigen Wochen voll. Gebraucht wird eine
+      Aufbewahrungsregel — Vorschlag: Rohdateien der letzten 30 Clips behalten,
+      ältere löschen, sobald `status = 'rendered'`. **Das ist der Punkt, der als
+      Erstes weh tun wird.**
+- [ ] Was passiert, wenn der Rechner mitten im Rendern ausgeht? Clips bleiben
+      auf `status = 'raw'` stehen und werden nach Neustart nicht wieder
+      eingereiht.
+
+## Untertitel verbessern
+
+Der Durchlauf am echten Clip war brauchbar, aber nicht gut. Was auffiel:
+
+- [ ] **Größeres Modell testen.** `ggml-small` machte aus „Danke" ein „Dank es"
+      und aus „Sabrina" ein „Savina". `medium` ist etwa dreimal so langsam —
+      bei 30-Sekunden-Clips nach dem Stream ist das egal. Vergleich an
+      demselben Clip fahren und entscheiden.
+- [ ] **Wörter mit niedriger Wahrscheinlichkeit prüfen.** Whisper liefert je
+      Token ein `p`. Bei den Fehlgriffen lag es unter 0,15, bei korrekten
+      Wörtern über 0,9. Entweder weglassen oder gedimmt anzeigen.
+- [ ] **Schrift.** DejaVu Sans ist im Image vorhanden, aber unauffällig. Auf
+      Shorts trägt eine fettere, rundere Schrift (Montserrat ExtraBold,
+      Inter Black). Braucht eine Schriftdatei im Image und eine Lizenzprüfung.
+- [ ] **Nur das aktuelle Wort hervorheben** statt fortlaufend einzufärben. Der
+      heutige Karaoke-Effekt lässt gesprochene Wörter gefärbt stehen; der Stil,
+      der auf TikTok funktioniert, hebt genau ein Wort hervor. Braucht mehrere
+      Dialogzeilen je Zeile statt einer.
+- [ ] **Position prüfen.** 340 px Abstand nach unten ist geschätzt, nicht
+      gemessen. An einem echten Handy gegen die TikTok-, Reels- und
+      Shorts-Oberfläche halten.
+- [ ] **Nur transkribieren, wenn Abdu spricht.** Bei getrennten Tonspuren
+      reicht ein Pegelfilter auf der Mikrofonspur, damit aus Stille kein
+      erfundener Text wird.
+
+## Streamsetup
+
+- [ ] **Live-Captions verschieben.** Sie liegen im Gameplay-Band und sind fest
+      eingebrannt. Zwei Vorschläge stehen in [`obs-layout.md`](obs-layout.md).
+- [ ] **Spieluntertitel abschalten.**
+- [ ] **Bessere Bildquelle für die Facecam** — Plugin `Source Record` oder
+      `Aitum Vertical`. Damit entfällt die 2,25-fache Vergrößerung. Lohnt sich
+      erst, wenn regelmäßig Shorts entstehen.
+
+## Nach dem MVP
+
+- [ ] **Spitzen-Erkennung scharf schalten.** Sie läuft mit und schreibt jeden
+      Kandidaten samt Punktzahl in `events`. Sobald ein paar Streams
+      protokolliert sind: an echten Daten kalibrieren, dann `armed: true`.
+- [ ] Automatischer Upload zu TikTok und YouTube.
+- [ ] EventSub für Follows, Subs, Raids — bisher reicht IRC plus Polling.
+- [ ] Follower-Prüfung bei `!clip`, falls die Abklingzeiten nicht reichen.
+- [ ] Die übrigen acht Werkzeuge, siehe [`04-roadmap.md`](04-roadmap.md).
+
+## Kleinigkeiten
+
+- [ ] `docker compose run` reicht ein TTY durch, dadurch schreibt die
+      Fortschrittsanzeige `\r`-Zeilen ins Protokoll. Mit `-T` sauber, aber
+      unschön als Standard.
+- [ ] `ldconfig` meldet beim Bauen `libwhisper.so.1 is not a symbolic link`.
+      Funktioniert, ist aber unsauber.
+- [ ] `docs/05-setup.md` nennt ffmpeg 6+; im Image steckt 5.1.9 aus Debian
+      bookworm. Für unseren Filtergraph irrelevant, die Angabe stimmt trotzdem
+      nicht.