rippy/AGENTS.md

# AGENTS.md — Arbeits-Konventionen für Rippy

## Grundregeln

**1. Plan vor Code.** Vor jeder Etappe: Klare Akzeptanzkriterien schreiben, dann bauen.
**2. Kleine Schritte.** Max. eine Feature pro Commit. Commit-Nachrichten beschreiben WAS und WARUM.
**3. Beweisen statt behaupten.** Testen, was gebaut wurde. Keine "es sollte funktionieren"-Commits.
**4. Deutsch-Nicht-Entwickler.** Der Commander liest alles — Variablennamen auf Englisch, aber Kommentare und Docs auf Deutsch.

## ⛔ HARTE Regeln (mechanisch geprüft — seit 22.07.2026)

**A. Die CI-Ampel muss GRÜN sein, bevor irgendetwas „fertig" heißt.**
`.gitea/workflows/ci.yml` läuft bei jedem Push auf dem Gitea-Runner (NICHT löschen, NICHT
abschwächen). Keine Tests = rot = nicht fertig. Der Commander liest die Ampel, nicht den Code.

**B. Abweichung vom KONZEPT = STOPP + fragen.** Anderes Werkzeug, andere Bibliothek,
gestrichenes Muss-Feature → erst den Commander fragen, NIE still ersetzen.
(Vorgefallen: Muss-Feature „MakeMKV lossless" wurde still durch lossy HandBrake ersetzt.)

**C. Single Source of Truth ist `main` — es gibt nur diesen einen Branch**
(seit 24.07.2026; der `stable`-Zwischenbranch ist abgeschafft). Die CI-Ampel
läuft bei jedem Push und PRÜFT nur (Ruff/pytest/Vite-Build) — sie befördert
nichts mehr. Deployt wird direkt aus `main`: auf der VM `git pull` bzw.
`./deploy.sh` (verifiziere vorher, dass die Ampel für den Commit GRÜN ist —
rot heißt: nicht deployen). Nie freihändig per SSH auf der VM bauen.
(Vorgefallen: Doppel-Anlage `Rippy` + `rippy` auf der VM durch Freihand-Deploys.)

**D. Externe Schnittstellen NIE aus dem Kopf.** Vor Nutzung fremder CLI-Flags oder
Bibliotheks-APIs: `--help`/Doku prüfen und die Fundstelle im Commit nennen.
(Vorgefallen: erfundene Celery-Methode `self.send_task`, erfundene abcde-Flags.)

## Workflow

1. **Read:** KONZEPT.md + ROADMAP.md lesen. Verstehen, welche Etappe dran ist.
2. **Plan:** Was genau soll diese Sitzung bauen? Eine Zeile.
3. **Build:** Code schreiben, testen, committen.
4. **Verify:** `docker compose up` — funktioniert das Ganze?
5. **Savepoint:** SAVEPOINT.md aktualisieren. Nächster Chat beginnt nicht von Null.

## Modelle je Aufgabe

- **Planung:** Heavy-Modell (Reasoning) für Architektur-Entscheidungen.
- **Bauen:** schnelles Coding-Modell.
- **Review:** Heavy nochmal für Code-Review vor Merge.

## Docker-Praxis

- Alles läuft in Containern: `docker compose up -d`
- Keine System-Pakete auf dem Host — alles im Container.
- Dockerfile immer multi-stage, kleinste Images.

## Was NICHT gebaut wird

- Kein Code direkt im Host-OS.
- Kein Proxmox-LXC-Nesting-Workaround — das Projekt lebt bewusst in normalem Docker.
- Kein ARM-Fork — Rippy ist ein Eigenbau von Grund auf.

## Aktueller Stand (26.07.2026)

- ✅ **E2E bewiesen (v3.1):** BD-50 komplett durch die Kette (43 GB → 4,8 GB)
- ✅ **Etappe 13 (v3.2):** Universal-Komfort-Runde — Media-Server-Integration,
  echte Benachrichtigungen, SMB-Klartext-Fehler, UHD-Arbeitsverzeichnis,
  MakeMKV-Key via UI, Job-Detail-Popup, Toast-Feedback, Ampel-Blocker behoben
- ✅ **Etappe 17 (v3.10):** 4K-UHD-Disc-Schlüssel — persistentes
  MakeMKV-Datenverzeichnis + `KEYDB.cfg` im UI
- ✅ **Etappe 18 (v3.11):** 4K-UHD gelöst — `makemkvcon` holt Schlüssel
  unter Linux nie, unter Windows schon; Schlüsselspeicher übernehmbar.
  Akira-UHD geht auf der VM auf (`TCOUNT:5`, bewiesen)
- ✅ **Etappe 19 (v3.14):** Durchsicht Frontend/Backend — vier Placebos weg
  (Fortschritt log, Auswurf tat nichts, „Alle Tracks" konnte nichts, Encoder
  wurden behauptet statt gemessen), Zombie-Erkennung gebaut, Pfad-Prüfung
  gehärtet, und der Platten-Schutz aus `c065967` als **unwirksam** entlarvt
- ✅ **Etappe 20 (v3.15):** Aufräum-Runde — `/capabilities` 1,010 s → 0,003 s
  (Ping im Hintergrund), Kompression je Disc-Typ abwählbar (4K verlustfrei),
  Wizard empfiehlt nach gemessener CPU, vier tote Routen entfernt
- ✅ **Etappe 21 (v3.17):** Der Blocker externes Encoden ist zu —
  `RIPPY_PATH_MAP` leitet Rippy aus seinen eigenen Mounts ab, der Installer holt
  es selbst; Presets kommen vom Worker statt aus dem Quelltext; Dashboard ohne
  Placebos, mit Restzeit. Dazu vier Bestandsfehler, alle live gemessen (u. a.
  „Neu komprimieren" ging nie, und `os.path.isdir` hing im Kernel)
- ✅ **Etappe 22 (v3.18):** Auswurf wirkt endlich (MakeMKV verriegelt die Tür —
  erst entriegeln, dann prüfen statt glauben), externer Worker meldet sein Log
  nach Rippy, zeigt den laufenden Job und nimmt mehrere Aufträge an. Dazu **die
  Mount-Ursache**: Die CIFS-Verbindung lebt in der Netz-Namespace des
  api-Containers und stirbt mit ihm — eine Wache heilt das jetzt selbst
- ✅ **Etappe 23 (v3.19):** Sprachwahl vor dem Rip (Ton + Untertitel, Automatik
  einstellbar), Auswurf wirkt wirklich (MakeMKV verriegelt die Tür), externer
  Worker mit Verwaltungsfenster/Deinstaller/Slots, Schlüssel-Automatik für 4K,
  Mount-Wiederanbindung 202 s → 8 s, Weitergabe an einem frischen Klon geprüft
- 📝 **Details immer in SAVEPOINT.md** — diese Sektion nennt nur die Etappe

## Was diese Sitzungen wiederholt gekostet hat

**Nicht aus einem Zustandswert auf einen Mechanismus schließen.** Vorgefallen:
aus „kein Schlüssel da" → „Server abgeschaltet" (falsch), aus Status
`transcoding` → „Celery hat neu zugestellt" (falsch), aus `progress=99` →
„Altwert aus dem Absturz" (falsch — ein Bug), aus gleichem `st_dev` →
„`os.rename` funktioniert" (falsch — der Kernel vergleicht den Mount).
Jedes Mal hätte eine Messung von unter einer Minute gereicht.

**Und die Umkehrung gilt genauso:** gleiches `st_dev` heißt NICHT gleicher
Mount. Wo eine Eigenschaft ausprobierbar ist, probiere sie aus, statt sie
vorherzusagen.

**Ein Hintergrund-Prozess, der still scheitert, ist schlimmer als einer, der
laut scheitert** (26.07.2026). Ein `except Exception: pass` in einer
Vorrats-Schleife hat eine Stunde gekostet: Der Vorrat blieb leer, die Funktion
lief direkt aufgerufen einwandfrei, und der Grund stand nirgends. Gefunden erst
über die Thread-Zustände (`/proc/<pid>/task/*/stat`, Zustand `D` = im Kernel
blockiert). Jede Hintergrund-Schleife MELDET ihren Fehler, und wer einen Vorrat
anlegt, macht sein Alter abfragbar (`GET /health/vorraete`) — sonst ist am
Endpunkt selbst nichts zu sehen.

**Ein Rückgabewert ist kein Beweis, wo die Wirkung prüfbar ist** (26.07.2026,
zweimal am selben Abend). `CDROMEJECT` quittiert Erfolg auf einem verriegelten
Laufwerk und wirft nichts aus; `mount` quittiert Erfolg auf einer Verbindung, die
Sekunden später stirbt. Beide Fehler waren monatelang unsichtbar, weil der Code
dem Rückgabewert glaubte. Nach einer Aktion den ZUSTAND fragen — und wenn er
flattert, zweimal mit Abstand.

**Bei „zu langsam" die DAUER je Schritt messbar machen, nicht die plausibelste
Ursache beheben** (26.07.2026). Eine Mount-Wiederanbindung brauchte 150 s; die
erste, sehr plausible Erklärung war falsch, und die Änderung machte es langsamer
(202 s). Erst Zeitstempel im Log zeigten die Stelle: ein `os.makedirs` in Zeile
eins, das drei Minuten im Kernel hing. Danach 8 s. Wer eine Dauer nicht
aufschlüsselt, optimiert die falsche Stelle.

**Netz-Pfade nie ungebremst anfassen.** `os.path.isdir`/`open` auf einem toten
CIFS-Mount blockieren im Kernel und lassen sich aus Python NICHT abbrechen. Ein
Kind-Prozess lässt sich abbrechen: `timeout N ls -d <pfad>` (Muster in
`mounts.ist_erreichbar` und `rohdaten.verzeichnis_da`). Und „konnte nicht
nachsehen" ist etwas anderes als „ist nicht da" — beides zu vermischen erzeugt
falsche Aussagen im UI.