Document Athena 3D mode and agent operations

for_ki.md

@@ -0,0 +1,256 @@
+# Athena: verbindlicher Kontext für KI-Agenten
+
+Stand: 10. September 2026, nach Integration von TRELLIS.2 als 3D-Studio.
+
+Diese Datei ist die erste Lektüre für jede KI, die Athena prüfen oder ändern
+soll. Sie beschreibt den realen Aufbau, die Zuständigkeiten und die Regeln für
+sichere Erweiterungen. Bei Abweichungen zwischen Annahmen und Live-System gilt:
+erst lesend prüfen, dann die Dokumentation und den Code gemeinsam korrigieren.
+
+## Unverhandelbare Sicherheitsregeln
+
+1. **Athena niemals herunterfahren oder neu starten.** Der Rechner steht in
+   einer anderen Stadt und ist nicht kurzfristig physisch erreichbar.
+2. Ohne ausdrücklichen aktuellen Auftrag weder Kernel, Bootloader, BIOS,
+   Partitionen, Mounts, SSH, LAN, WireGuard noch Firewall verändern.
+3. Secrets dürfen lokal benutzt, aber niemals ausgegeben, geloggt oder in Git
+   aufgenommen werden. Das betrifft besonders `/etc/mike-ai`.
+4. Keine laufende Modellarbeit abbrechen. Vor Änderungen Betriebsmodus,
+   Containerzustand und GPU-Prozesse prüfen.
+5. Keine pauschalen Docker-Bereinigungen ausführen. Ein gestoppter Worker ist
+   meistens gewollt und kein Müll.
+6. Keine Container anhand zufälliger IDs verdrahten. Stabile Dienstnamen,
+   Compose-Netze und eindeutige `com.mike-ai.*`-Labels verwenden.
+7. Änderungen klein und reversibel halten. Nie den gesamten Stack neu erstellen,
+   wenn ein einzelner Dienst aktualisiert werden kann.
+
+## Physischer und logischer Aufbau
+
+```text
+Athena: ASUS PRIME B550-PLUS
+├── Debian 13 (trixie), Kernel 6.12
+├── AMD Ryzen 5 5600, 6 Kerne / 12 Threads
+├── 46 GiB nutzbarer RAM + 47 GiB Swap
+├── System: Samsung 980 PRO 1 TB, ext4 auf /
+├── Daten:  WD Blue SN580 1 TB, ext4 auf /data
+├── GPU 0: RTX 3060, 12.288 MiB
+├── GPU 1: RTX 5080, 16.303 MiB
+└── Docker
+    ├── Kernprojekt /opt/mike-ai/stack
+    │   ├── Router, Profile Controller und Dashboard
+    │   ├── fünf llama.cpp-Profile
+    │   ├── Bild, Qwen3-TTS, TTS-Gateway und Whisper
+    │   ├── WireGuard-Gateway, Portainer, Backup
+    │   └── Athena-Operator
+    ├── /opt/mike-ai/acestep-test              Musik
+    ├── /opt/mike-ai/stem-separator            Audio-Trennung
+    ├── /opt/mike-ai/omnivoice-studio          Voice Studio
+    ├── /opt/mike-ai/xvc-studio                Voice Changer
+    ├── /opt/mike-ai/stack/experiments/applio-rvc
+    │                                             Applio/RVC
+    ├── /opt/mike-ai/Mikes-Applio-UI           geführte Applio-UI
+    └── /opt/mike-ai/trellis-studio            3D Studio
+```
+
+Die beiden GPUs bilden **keinen gemeinsamen VRAM-Pool**. Ein Backend muss
+Mehrkartenbetrieb ausdrücklich unterstützen. Die Nummern oben sind Hostnummern;
+wenn ein Container nur `NVIDIA_VISIBLE_DEVICES=1` erhält, sieht er die RTX 5080
+innerhalb des Containers üblicherweise als GPU 0.
+
+## Rollen der dauerhaften Kerndienste
+
+| Dienst | Rolle |
+|---|---|
+| `mike-ai-router` | Einzige OpenAI-kompatible Modelladresse; besitzt die Zustandsmaschine für Profile und Betriebsmodi. |
+| `mike-ai-profile-controller` | Darf ausschließlich freigegebene, eindeutig markierte Worker starten und stoppen. |
+| `mike-ai-llama-dashboard` | Telemetrie, Modusumschaltung und Download der portablen Backups. |
+| `mike-ai-wireguard-gateway` | Veröffentlicht interne Dienste an der privaten Adresse `192.168.1.212`; keine öffentliche/LAN-Bindung. |
+| `mike-ai-tts-gateway` | Stabile TTS-API, Textnormalisierung, Formatumwandlung und PCM-Streaming; enthält kein Ersatzmodell. |
+| `mike-ai-whisper` | Dauerhafte CPU-Spracherkennung mit Whisper.cpp `ggml-small`. |
+| `mike-ai-mcp-athena-operator` | Begrenzte Verwaltungsfunktionen für Agenten; kein allgemeiner Root-Ersatz. |
+| `mike-ai-backup` | Lokales Schnellbackup; externe Disaster-Sicherung läuft zusätzlich über systemd-Timer. |
+
+## LLM-Profile
+
+Es läuft höchstens ein llama.cpp-Profil. Die Standardprofile nutzen
+Qwen3.8-27B in Q4-Quantisierung.
+
+| Profil | API-Name | Kontext | Vision |
+|---|---|---:|---|
+| Fast | `qwen-fast` | 76.800 | ja |
+| Medium | `qwen-medium` | 160.000 | ja |
+| Large | `qwen-large` | 192.000 | ja |
+| Ultra | `qwen-ultra` | 262.144 | nein |
+| Uncensored | `qwen-uncensored` | 80.000 | ja, eigener Projektor |
+
+Die verbindlichen Parameter stehen in `config/profile-matrix.json`,
+`router/router_profiles.json`, `platform/profiles/` und
+`docs/STANDARD_PROFILE_MATRIX.md`. Diese Quellen dürfen sich nicht
+widersprechen.
+
+## Exklusive Betriebsmodi
+
+Große GPU-Worker sind gegenseitig exklusiv. Der Router speichert
+`mode`, `last_profile` und `return_profile` persistent. Beim Wechsel in einen
+Spezialmodus werden LLM, Bildworker und Qwen3-TTS soweit nötig gestoppt; beim
+Wechsel zu `llm` wird das zuvor gemerkte Profil wiederhergestellt.
+
+| Modus | Worker / Modell | GPU-Nutzung | Oberfläche |
+|---|---|---|---|
+| `llm` | ein Qwen-Profil + Qwen3-TTS | profilabhängig beide GPUs; TTS RTX 3060 | Router `:8081` |
+| Bildauftrag | FLUX.2 Klein 9B FP8 + Qwen3-8B NF4 | RTX 5080 + RTX 3060, transaktional | über Router |
+| `music` | ACE-Step 1.5 XL-SFT | RTX 5080 | `:7862` original, `:7861` Community |
+| `separation` | BS-RoFormer, Demucs, MossFormer2 | RTX 5080 | `:8007` |
+| `voice` | OmniVoice | RTX 5080 | `:8008` |
+| `voicechange` | X-VC + optional Resemble Enhance | RTX 5080 | `:8009` |
+| `applio` | Applio/RVC | RTX 5080 | `:8011`, eigene UI `:8012` |
+| `trellis` | TRELLIS.2 4B Q8 über trellis.cpp 0.6.0 | ausschließlich RTX 5080 | `:8013` |
+
+TRELLIS liegt unter `/opt/mike-ai/trellis-studio`. Seine Q8-Gewichte liegen
+unter `/data/models/trellis2-q8`, die Runtime und Ausgaben unter
+`/data/trellis-studio`. Die Oberfläche liefert GLB. `1024 · cascade` ist der
+Qualitätsstandard für die 16-GiB-RTX-5080; 1536 kann den VRAM überschreiten.
+Ein 512er Ende-zu-Ende-Test erzeugte am 10.09.2026 in 54,2 Sekunden ein
+gültiges 4,4-MB-GLB.
+
+## Steuerbefehle und Status
+
+Im Dashboard wird über die Modus-API geschaltet. Hermes kann dieselbe
+Zustandsmaschine mit exakten Befehlen bedienen:
+
+```text
+/athena music
+/athena stems
+/athena voice
+/athena voicechange
+/athena applio
+/athena 3d
+/athena trellis
+/athena llm
+/athena status
+```
+
+Ein Moduswechsel ist asynchron. Eine angenommene Anfrage bedeutet noch nicht,
+dass der Worker bereit ist. Immer warten, bis `GET /status` beziehungsweise das
+Dashboard `phase: ready`, den richtigen `active`-Modus und einen gesunden
+Worker meldet. Bei Fehlern nicht blind erneut starten, sondern `last_error`,
+Containerstatus und Logs lesen.
+
+## Netzwerkmodell
+
+Anwendungscontainer veröffentlichen ihre Host-Ports nur auf `127.0.0.1` oder
+gar nicht. Das WireGuard-Gateway sitzt im externen Docker-Netz
+`mike-ai_frontend`, bindet die private WireGuard-Adresse `192.168.1.212` und
+leitet mit `socat` auf Compose-Dienstnamen weiter.
+
+Wichtige Regeln:
+
+- Gateway und Anwendung **nicht** über `network_mode: container:...` koppeln.
+- Ziel ist zum Beispiel `trellis-studio:8080`, niemals eine Container-IP.
+- Der Zielcontainer muss im selben externen Frontend-Netz liegen.
+- Beim Hinzufügen eines Ports den Proxy-Eintrag im Gateway, das Dashboard und
+  die Endpunkt-Dokumentation gemeinsam ergänzen.
+- Ein Gateway-Recreate kann eine bestehende SSH-Verbindung unterbrechen. Nur
+  kontrolliert und mit automatisch verzögertem Wiederanlauf durchführen.
+- Nach einem Recreate DNS-Auflösung, Listener, Ziel-Healthcheck und Zugriff
+  über den WireGuard-Pfad prüfen.
+
+## Daten und Sicherung
+
+| Pfad | Inhalt |
+|---|---|
+| `/opt/mike-ai` | Deployments, Compose-Projekte und lokale Quellstände |
+| `/etc/mike-ai` | Konfiguration, Schlüssel und Tokens; geheim |
+| `/data/models` | erneut ladbare Modellgewichte und Caches |
+| `/data/voice` | Trainingsdaten, Checkpoints und trainierte Stimmen |
+| `/data/music` | Musikprojekte und Ausgaben |
+| `/data/audio` | Audio-Trennungen |
+| `/data/trellis-studio` | trellis.cpp-Runtime und 3D-Ausgaben |
+| `/data/llama-dashboard` | Telemetriehistorie |
+| `/data/docker-backups` | lokale Schnellbackups |
+
+Docker-Volumes: `mike-ai_router-state`, `mike-ai_router-images`,
+`mike-ai_whisper-data`, `portainer_data`.
+
+Das lokale Exportbackup läuft etwa alle fünf Stunden, das verschlüsselte
+Disaster-Backup nachts. Ein Backup auf `/data` schützt nicht vor dem Ausfall
+der Datenplatte. Details und alle drei Ausfallszenarien stehen in
+`docs/RECOVERY.md`. **Aktuelle Lücke:** `/data/trellis-studio/output` ist im
+ausgerollten Export- und Disaster-Backup noch nicht enthalten. Wichtige GLB-
+Ausgaben daher zusätzlich extern sichern, bis die Backup-Skripte erweitert und
+getestet wurden.
+
+## Neuen GPU-Dienst korrekt hinzufügen
+
+1. `docs/TESTED_MODELS.md` vollständig prüfen, damit kein verworfener Kandidat
+   erneut geladen wird.
+2. Lizenz, Modellrevision, Runtime-Revision, VRAM, RAM, Ausgabeformat und
+   Hardwareunterstützung dokumentieren.
+3. Eigenes Compose-Projekt oder klar abgegrenzten Kernservice anlegen. Image
+   und Upstream-Commit pinnen; nicht dauerhaft `latest` als einzige
+   Wiederherstellungsinformation verwenden.
+4. Gewichte unter einem eindeutigen Verzeichnis in `/data/models` speichern,
+   veränderliche Ergebnisse separat unter `/data`.
+5. `restart: "no"` für exklusive GPU-Worker verwenden. Dauerhafte UIs dürfen
+   laufen, dürfen aber im Leerlauf kein großes Modell laden.
+6. Genau ein eindeutiges Label vergeben, zum Beispiel
+   `com.mike-ai.trellis-worker=trellis2-q8`. Der Controller muss bei null oder
+   mehreren Treffern absichtlich abbrechen.
+7. Worker in **Controller, Router, Dashboard, Compose-Umgebung,
+   WireGuard-Proxy, Tests und Dokumentation** ergänzen.
+8. Alle anderen exklusiven Worker sowohl beim Eintritt als auch beim Verlassen
+   des neuen Modus behandeln. Den Rückweg zum gespeicherten LLM-Profil testen.
+9. Healthcheck-Werkzeuge tatsächlich im Image installieren. Ein Backendprozess
+   kann laufen, während ein fehlerhafter Healthcheck den Modus blockiert.
+10. Bei Web-UIs korrekte MIME-Typen ausliefern. ES-Module benötigen
+    `application/javascript`, CSS `text/css`; Browsermodus muss denselben
+    Ursprung oder eine sauber konfigurierte API-Adresse verwenden.
+11. Compose validieren, Syntax prüfen, nur den betroffenen Dienst bauen und
+    einen echten Ende-zu-Ende-Auftrag ausführen. Danach Rückschaltung testen.
+12. Quellcode, Installer, Wiederaufbau und Dokumentation im selben Git-Stand
+    versionieren. Erst dann ist die Erweiterung wiederherstellbar.
+
+## Dienst vollständig entfernen
+
+1. Belegen, dass der Dienst nicht aktiv ist und keine laufende Arbeit besitzt.
+2. Testergebnis und Ablehnungsgrund zuerst in `docs/TESTED_MODELS.md` sichern.
+3. Routerbefehle, Zustandsfelder, Controller-Labelsuche, Dashboard-Schalter,
+   Proxy-Port, Compose-Projekt, Tests und Dokumentation entfernen.
+4. Container und Image gezielt anhand exakter Namen entfernen.
+5. Gewichte, Cache, Ausgaben und Volumes einzeln klassifizieren: reproduzierbar,
+   ersetzbar oder unersetzlich. Unersetzliche Daten sichern; keine Globs oder
+   pauschalen Prune-Befehle benutzen.
+6. Prüfen, dass kein Labelduplikat, verwaister Proxy, unbenutztes Netz oder
+   verwaistes Volume übrig ist.
+7. LLM-Modus wiederherstellen und einen Smoke-Test ausführen.
+
+## Häufige Fehlerbilder
+
+- **Controller meldet zwei Worker:** Während `docker compose up
+  --force-recreate` können alter und neuer Container kurz dasselbe Label
+  tragen. Recreate beenden lassen, danach exakt gelabelte Container prüfen und
+  erst dann den Modus erneut anfordern.
+- **Webseite ist unformatiert und bleibt auf „connecting“:** MIME-Typen oder
+  Asset-Cache prüfen; nicht automatisch das KI-Backend beschuldigen.
+- **Dashboard oder Port fehlt nach Recreate:** Listener im Gateway,
+  DNS-Auflösung des Dienstnamens und gemeinsames Frontend-Netz prüfen.
+- **Worker gesund, Modus trotzdem fehlerhaft:** Routerzustand und
+  `last_error` können noch den vorherigen fehlgeschlagenen Übergang zeigen;
+  nach Beseitigung der Ursache Modus kontrolliert erneut anfordern.
+- **VRAM scheinbar leer:** Manche Runtime lädt Gewichte erst beim ersten
+  Auftrag und gibt Speicher anschließend wieder frei. Ein Healthcheck allein
+  ist daher kein vollständiger GPU-Test.
+- **Compose verwendet falsche Werte:** Der Kernstack benötigt
+  `--env-file /etc/mike-ai/stack.env`.
+
+## Definition von „fertig“
+
+Eine Änderung ist erst fertig, wenn sie im kanonischen Git-Stand liegt,
+reproduzierbar gebaut werden kann, Compose/Syntax valide sind, der Dienst gesund
+ist, ein echter kleiner Funktionsauftrag erfolgreich war, die Rückschaltung
+funktioniert, Backup und WireGuard-Zugriff gesund geblieben sind und Commit
+sowie Push erfolgt sind.
+
+Weiterführend: `ATHENA.md`, `docs/ARCHITECTURE.md`,
+`docs/OPERATING_MODES.md`, `docs/CONTAINER_INVENTORY.md`,
+`docs/TESTED_MODELS.md` und `docs/RECOVERY.md`.