# 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. Deployment NUR über `./deploy.sh`.** Idempotent, EIN fester Compose-Projektname
(`rippy`), EIN Pfad (`~/projects/rippy`). Nie freihändig per SSH auf der VM bauen.
(Vorgefallen: Doppel-Anlage `Rippy` + `rippy` auf der arcane-VM.)

**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 (21.07.2026)

- ✅ **Etappe 8 abgeschlossen:** Dark Mode mit Theme-Toggle, React-UI mit TailwindCSS
- ✅ **Git Sync:** Arcane VM (192.168.178.162) mit Git Repository konfiguriert
- ✅ **Savepoint v1.8:** Separation of Concerns geplant, Dark Mode implementiert
- 📝 **Nächste Etappe:** SoC-Refactoring (Theme-Context auslagern)