Document Athena 3D mode and agent operations

2026-09-10 18:31:44 +02:00
parent 795101b746
commit 43321b6797
11 changed files with 353 additions and 10 deletions
@@ -13,6 +13,7 @@ Sie betreibt:
 - FLUX.2 Klein 9B FP8 Beta für Textbilder und Referenzbild-Bearbeitung,
 - Qwen3-TTS für Sprache,
 - ACE-Step 1.5 XL-SFT als exklusiven Musikstudio-Modus,
 - TRELLIS.2 4B Q8 als exklusives Bild-zu-3D-Studio,
 - das Athena-Dashboard,
 - Portainer CE als optionale Ansicht auf die laufenden Docker-Container,
 - WireGuard-Gateway und Datenbackup,
@@ -29,6 +30,7 @@ werden keine zweiten Instanzen dieser Dienste angelegt.
 | `/data/models` | Modellgewichte |
 | `/data/llama-dashboard` | historische Dashboard-Messwerte |
 | `/data/docker-backups` | automatische Athena-Backups |
 | `/data/trellis-studio` | trellis.cpp-Runtime und erzeugte 3D-Modelle |
 | `/etc/mike-ai` | lokale Konfiguration und Secrets, niemals Git |
 Portainer läuft als separater, optionaler Verwaltungscontainer
@@ -72,6 +74,10 @@ Qwen-Profil wird vom Profile Controller verwaltet.
 - ACE-Step 1.5 XL-SFT: exklusiver Musikmodus auf der RTX 5080. Dashboard und
  die Routerbefehle `/athena music`, `/athena llm`, `/athena status` bedienen
  dieselbe persistente Zustandsmaschine; siehe `docs/OPERATING_MODES.md`.
 - TRELLIS.2 4B Q8: exklusives Bild-zu-3D-Profil auf der RTX 5080. Die
  browserbasierte Oberfläche läuft unter `http://192.168.1.212:8013`, erzeugt
  GLB und verwendet standardmäßig `1024 · cascade`. Der 1536er Pfad kann die
  16 GiB VRAM überschreiten.
 Die verbindlichen Werte stehen in `config/profile-matrix.json` und
 `docs/STANDARD_PROFILE_MATRIX.md`.
@@ -100,6 +106,9 @@ Bootloader, Partitionen, Mounts, SSH, LAN, WireGuard oder Firewall ändern.
 Secrets dürfen lokal verwendet, aber nie in Git, Logs oder Chatantworten
 veröffentlicht werden.
 Vor Änderungen durch einen Agenten ist [for_ki.md](for_ki.md) vollständig zu
 lesen. Dort stehen insbesondere Modus-, Label-, Netzwerk- und Aufräumregeln.
 ## Fertig bedeutet
 - Änderung ist im kanonischen Git-Checkout,
@@ -1,7 +1,8 @@
 ATHENA – AUFBAU VON UNTEN NACH OBEN
 ====================================
-Stand: 10.09.2026 nach Entfernung von Beta 1 und Piper.
+Stand: 10.09.2026 nach Entfernung von Beta 1 und Piper sowie Integration von
 TRELLIS.2 als 3D-Studio.
 Athena besitzt derzeit 23 Container, fünf auswählbare LLM-Profile und vier
 verwendete Docker-Volumes. Verwaiste Docker-Volumes gibt es nicht.
@@ -95,6 +96,9 @@ Betriebsmodus gestartet. Zum Zeitpunkt der Aufnahme war Applio/RVC aktiv.
 | mike-ai-stem-separator            | gestoppt/bereit   | Trennt Gesang, Begleitung und Instrumente    |
 |                                   |                   | mit BS-RoFormer und Demucs.                   |
 +-----------------------------------+-------------------+----------------------------------------------+
 | mike-ai-trellis-studio            | läuft/bedarfsgest.| TRELLIS.2 4B Q8 erzeugt aus einem Bild ein   |
 |                                   |                   | texturiertes GLB-Modell auf der RTX 5080.     |
 +-----------------------------------+-------------------+----------------------------------------------+
 | mike-ai-voice-studio              | gestoppt/bereit   | Voice Studio für Text-zu-Stimme und          |
 |                                   |                   | referenzbasierte Stimmerzeugung.              |
 +-----------------------------------+-------------------+----------------------------------------------+
@@ -133,6 +137,7 @@ aber gemeinsam als Athena-Docker-Stack betrachtet:
 - Spurentrennung: /opt/mike-ai/stem-separator
 - Voice Studio: /opt/mike-ai/omnivoice-studio
 - X-VC: /opt/mike-ai/xvc-studio
 - 3D Studio: /opt/mike-ai/trellis-studio
 LLM-PROFILE
@@ -188,11 +193,18 @@ benötigten Modelle.
 +---------------+------------------------------------------------------------+
 | Applio / RVC  | RVC-Inferenz, Modellverwaltung und Stimmtraining.           |
 +---------------+------------------------------------------------------------+
 | 3D Studio     | TRELLIS.2 4B Q8 über trellis.cpp auf der RTX 5080.          |
 +---------------+------------------------------------------------------------+
 Qwen3-TTS läuft nur im LLM-Modus. In einem exklusiven Spezialmodus bleibt das
 leichte TTS-Gateway als API-Dienst gesund, meldet aber "ready: false", weil das
 eigentliche Qwen3-TTS-Modell absichtlich entladen ist.
 Das 3D-Studio ist im privaten WireGuard-Netz unter
 http://192.168.1.212:8013 erreichbar. Es erzeugt GLB-Dateien; empfohlen ist
 1024 · cascade. Runtime und Ausgaben liegen unter /data/trellis-studio, die
 Q8-Gewichte unter /data/models/trellis2-q8.
 TTS-AUFBAU
 ===========
@@ -252,6 +264,7 @@ Die wichtigsten davon sind:
 - /data/voice/applio           Applio-Datensätze, Logs und Stimmenmodelle
 - /data/music                  Musikprojekte und generierte Titel
 - /data/audio/separation       Ergebnisse der Audio- und Spurentrennung
 - /data/trellis-studio         trellis.cpp-Runtime und erzeugte GLB-Dateien
 - /data/llama-dashboard        Verlauf und Zustandsdaten des Dashboards
 - /etc/mike-ai                 betriebliche Konfiguration und Geheimnisse
 - /data/docker-backups         erzeugte Sicherungsarchive
@@ -16,7 +16,9 @@ Bild- und Sprachausgabe. **Hermes und die Fach-MCPs laufen auf Unraid.**
 - Whisper.cpp `ggml-small` auf der CPU für lokale deutsche Spracherkennung
 - Live-Dashboard mit 21 Tagen Detailhistorie auf Port 8099
 - Dashboard-Umschaltung zwischen LLM-Betrieb, ACE-Step-Musikstudio,
-  BS-RoFormer-Stimmtrennung, OmniVoice, X-VC und Applio/RVC
+  BS-RoFormer-Stimmtrennung, OmniVoice, X-VC, Applio/RVC und TRELLIS.2
 - TRELLIS.2 4B Q8 über trellis.cpp 0.6.0 für lokale Bild-zu-3D-Erzeugung
  auf der RTX 5080
 - Portainer CE als optionale Container-Ansicht auf Port 9443
 - WireGuard-Gateway, Datenbackup und Athena-Operator
 - keine produktive Hermes-, OpenWebUI- oder portable Fach-MCP-Instanz
@@ -129,10 +131,12 @@ Details, Installation, Prüfung und Rollback stehen in
 - Voice Changer (X-VC, Audio zu Audio; native 16 kHz plus optional restaurierte 44,1 kHz): `http://192.168.1.212:8009`
 - Applio (RVC-Inferenz, Modelle und Training): `http://192.168.1.212:8011`
 - Mikes Applio UI (geführte RVC-Oberfläche): `http://192.168.1.212:8012`
 - 3D Studio (TRELLIS.2 Q8, GLB-Ausgabe): `http://192.168.1.212:8013`
 Der Betriebsmodus lässt sich dort direkt umschalten. In Hermes funktionieren
 außerdem `/athena music`, `/athena stems`, `/athena voice`,
-`/athena voicechange`, `/athena applio`, `/athena llm` und `/athena status`; Details stehen in
+`/athena voicechange`, `/athena applio`, `/athena 3d`, `/athena llm` und
 `/athena status`; Details stehen in
 [docs/OPERATING_MODES.md](docs/OPERATING_MODES.md).
 Der Router stellt Sprache OpenAI-kompatibel bereit: Sprachausgabe über
@@ -189,6 +193,7 @@ Szenarien stehen in [docs/RECOVERY.md](docs/RECOVERY.md).
 ## Verbindliche Dokumentation
 - [ATHENA.md](ATHENA.md) – kurze Betriebsanleitung
 - [for_ki.md](for_ki.md) – verbindlicher System- und Änderungsleitfaden für KI-Agenten
 - [docs/STANDARD_PROFILE_MATRIX.md](docs/STANDARD_PROFILE_MATRIX.md) – Profile
 - [docs/CONTAINER_INVENTORY.md](docs/CONTAINER_INVENTORY.md) – alle Container, Modelle und Aufgaben
 - [docs/TESTED_MODELS.md](docs/TESTED_MODELS.md) – zentrale Testhistorie und Sperrliste gegen Doppeltests
@@ -10,6 +10,8 @@ flowchart LR
    I --> E[Qwen3-8B NF4 Textencoder<br/>RTX 3060 während Bildauftrag]
    R --> T[Qwen3-TTS RTX 3060<br/>Normalisierungs- und Streaming-Gateway]
    R --> STT[Whisper.cpp ggml-small<br/>CPU, lokale Spracherkennung]
    P --> SP[Exklusive Spezialworker<br/>Musik / Trennung / Voice / RVC / 3D]
    SP --> TR[TRELLIS.2 4B Q8<br/>trellis.cpp, RTX 5080]
    H --> U[MUA / Unraid MCP]
    H --> A[ARR-MCP]
@@ -17,11 +19,12 @@ flowchart LR
    H --> N[Navidrome-MCP]
    H --> S[STRATO-MCP]
    H --> X[Nginx-Proxy-Manager-MCP]
-    U --> M[Media-Tools<br/>ffmpeg / ffprobe / yt-dlp]
+    U --> MT[Media-Tools<br/>ffmpeg / ffprobe / yt-dlp]
    W[WireGuard-Gateway<br/>Athena] -->|DNS-Proxy| R
    W -->|DNS-Proxy :8099| B[Athena Dashboard<br/>internes Frontend-Netz]
    W -->|DNS-Proxy :9443| PRT[Portainer<br/>internes Frontend-Netz]
    W -->|DNS-Proxy :8013| TRUI[Trellis Studio<br/>Bild zu GLB]
    W -->|DNS-Proxy| O[Athena Operator]
    K[Backup alle 5 Stunden] --> DATA[/data und /etc/mike-ai]
 ```
@@ -34,6 +37,9 @@ flowchart LR
 - **MUA** verwaltet Unraid. **Athena Operator** bleibt auf den Athena-Host
  begrenzt.
 - Der Router ist die einzige Modelladresse, die Hermes kennen muss.
 - GPU-intensive Spezialdienste sind gegenseitig exklusiv. Der Router speichert
  Modus und Rückkehrprofil; der Profile Controller startet nur eindeutig
  gelabelte Worker.
 - Dashboard und Portainer besitzen eigene Netzwerk-Namespaces. Das
  WireGuard-Gateway löst ihre stabilen Compose-Dienstnamen bei jeder
  Verbindung neu auf; seine konkrete Container-ID ist damit irrelevant.
@@ -75,3 +81,16 @@ Eine zweite Detailkarte, `athena-gpu-allocation-map.png`, zeigt die
 profilabhängige Layer-Verteilung auf RTX 5080 und RTX 3060. Die PNG-Karten
 zeigen noch den Stand vor dem 9B-Bildpfad; die aktuelle textuelle Beschreibung
 in diesem Dokument ist verbindlich.
 ## TRELLIS.2 3D-Modus
 Der Modus `trellis` stoppt die anderen GPU-Worker und startet genau den mit
 `com.mike-ai.trellis-worker=trellis2-q8` markierten Container. trellis.cpp
 0.6.0 sieht ausschließlich die Host-GPU 1, die RTX 5080. Q8-Gewichte liegen
 unter `/data/models/trellis2-q8`, Runtime und Ausgaben unter
 `/data/trellis-studio`. Die UI ist intern `trellis-studio:8080` und wird vom
 WireGuard-Gateway auf `192.168.1.212:8013` weitergeleitet. Sie erzeugt GLB;
 regulärer Qualitätsmodus ist 1024 Pixel.
 Die vollständigen Regeln für Erweiterungen, Rückbau und Fehlersuche stehen in
 [`../for_ki.md`](../for_ki.md).
@@ -27,6 +27,7 @@ nicht automatisch ein ungenutzter Rest.
 | `mike-ai-qwen3-tts` | `Qwen/Qwen3-TTS-12Hz-1.7B-Base`, Stimme Serena | Hochwertige deutsche Sprachausgabe auf der RTX 3060 im LLM-Betrieb. |
 | `mike-ai-router` | kein eigenes Modell | Einzige OpenAI-kompatible Modelladresse; koordiniert Profile, Bildaufträge, Sprache und Betriebsarten. |
 | `mike-ai-stem-separator` | BS-RoFormer Viperx 1297, `htdemucs_ft`, `htdemucs_6s`, `MossFormer2_SE_48K` | Trennt Gesang, Instrumente oder Sprache/Hintergrundgeräusche im exklusiven Separationsmodus. |
 | `mike-ai-trellis-studio` | TRELLIS.2 4B Q8 über trellis.cpp 0.6.0 | Erzeugt im exklusiven 3D-Modus aus einem Bild ein texturiertes, geschlossen aufbereitetes GLB-Mesh. Nutzt ausschließlich die RTX 5080 und wird über Port 8013 bedient. |
 | `mike-ai-tts-gateway` | kein eigenes Modell | Normalisiert Text, konvertiert Ausgabeformate und stellt Qwen3-TTS sowie natives PCM-Streaming über eine stabile interne API bereit. |
 | `mike-ai-voice-studio` | `k2-fsa/OmniVoice` 0.2.1 mit Whisper-ASR | Erzeugt Text-to-Speech mit einer Referenzstimme; kein Audio-to-Audio-Voice-Changer. |
 | `mike-ai-whisper` | Whisper.cpp `ggml-small` | Lokale deutsche Spracherkennung auf der CPU über `/v1/audio/transcriptions`. |
@@ -1,6 +1,15 @@
 # Aktueller produktiver Laufzustand
-Stand: 8. September 2026
+Stand: 10. September 2026
 ## TRELLIS.2 3D-Studio
 TRELLIS.2 4B läuft über trellis.cpp 0.6.0 als exklusiver Q8-Worker auf der
 RTX 5080. Runtime und Q8-Gewichte liegen getrennt unter
 `/data/trellis-studio` und `/data/models/trellis2-q8`; die Browseroberfläche
 ist im WireGuard-Netz unter `http://192.168.1.212:8013` erreichbar. Ein realer
 512er Ende-zu-Ende-Test erzeugte in 54,2 Sekunden ein gültiges 4,4-MB-GLB.
 Für reguläre Qualitätsläufe ist `1024 · cascade` vorgesehen.
 ## Fotorestaurierung verworfen
@@ -1,6 +1,6 @@
 # Athena-Betriebsmodi
-Athena besitzt sechs gegenseitig exklusive Betriebsmodi:
+Athena besitzt sieben gegenseitig exklusive Betriebsmodi:
 - `llm`: ein llama.cpp-Profil und Qwen3-TTS laufen; Spezialdienste sind gestoppt.
 - `music`: ACE-Step 1.5 XL-SFT läuft; alle LLM-, Bild-, TTS- und Separator-Worker sind gestoppt.
@@ -13,6 +13,9 @@ Athena besitzt sechs gegenseitig exklusive Betriebsmodi:
  GPU-Dienste sind gestoppt.
 - `applio`: Applio stellt RVC-Inferenz, Modellverwaltung und Training bereit.
  Alle anderen GPU-Dienste sind gestoppt.
 - `trellis`: TRELLIS.2 4B Q8 erzeugt über trellis.cpp aus einem Eingabebild ein
  texturiertes GLB. Der Worker läuft ausschließlich auf der RTX 5080; alle
  anderen GPU-Dienste sind gestoppt.
 Die Zustandsmaschine lebt im Athena-Router. Das Dashboard und Chat-Clients wie
 Hermes sind nur Bedienoberflächen derselben API. Der zuletzt aktive LLM-Modus
@@ -21,7 +24,7 @@ wird persistent gespeichert und beim Verlassen eines Spezialmodus wieder geladen
 ## Bedienung
 Im Athena-Dashboard stehen **LLM-Betrieb**, **Musikstudio**, **Audio trennen**,
-**Voice Studio**, **X-VC** und **Applio / RVC** bereit. Im Musikmodus werden zwei Oberflächen angeboten:
+**Voice Studio**, **X-VC**, **Applio / RVC** und **3D Studio** bereit. Im Musikmodus werden zwei Oberflächen angeboten:
 - **Original UI · stabil** öffnet die zum laufenden ACE-Step-Image gehörende
  Gradio-Oberfläche. Sie ist für Cover, Remix und erweiterte Workflows der
@@ -80,6 +83,13 @@ benötigt zwingend ein zuvor importiertes oder trainiertes RVC-Stimmenmodell
 nicht. Der Code ist auf Commit
 `7fa68ec2166ab1331c539704159fa14901e94e5a` fixiert.
 Das TRELLIS.2-3D-Studio ist unter `http://192.168.1.212:8013` erreichbar. Es
 verwendet trellis.cpp 0.6.0 und die Q8-Variante von TRELLIS.2 4B. Das Modell
 läuft ausschließlich auf der RTX 5080; `1024 · cascade`, automatische
 Hintergrundentfernung und `xatlas` sind die empfohlenen Standardwerte. Die UI
 exportiert GLB. Ein nachgelagerter STL-/3MF-Export ist noch nicht Bestandteil
 der Oberfläche.
 Hermes benötigt dafür kein Plugin. Exakt eingegebene Steuerbefehle werden vom
 Router lokal beantwortet, auch wenn gerade kein LLM geladen ist:
@@ -89,6 +99,8 @@ Router lokal beantwortet, auch wenn gerade kein LLM geladen ist:
 /athena voice
 /athena voicechange
 /athena applio
 /athena 3d
 /athena trellis
 /athena llm
 /athena status
 ```
@@ -102,6 +114,7 @@ POST /mode  {"mode":"separation"}
 POST /mode  {"mode":"voice"}
 POST /mode  {"mode":"voicechange"}
 POST /mode  {"mode":"applio"}
 POST /mode  {"mode":"trellis"}
 POST /mode  {"mode":"llm"}
 ```
@@ -111,7 +124,8 @@ Der Wechsel läuft asynchron. Fortschritt und Fehler stehen unter `mode` in
 `com.mike-ai.stem-separator=bs-roformer` oder
 `com.mike-ai.voice-worker=vevo2` beziehungsweise
 `com.mike-ai.voice-change-worker=xvc` oder
-`com.mike-ai.applio-worker=applio` markierten Container; freie
+`com.mike-ai.applio-worker=applio` oder
 `com.mike-ai.trellis-worker=trellis2-q8` markierten Container. Freie
 Container- oder Docker-Befehle werden nicht entgegengenommen.
 ## Wiederanlauf
@@ -41,6 +41,16 @@ werden außerdem:
 - Audio-Trennungen unter `/data/audio`,
 - Dashboard-, Operator-, Benchmark- und Projektdaten.
 ### Aktuelle TRELLIS-Lücke
 Das am 10.09.2026 ergänzte 3D-Studio speichert seine Ausgaben unter
 `/data/trellis-studio/output`. Dieser Pfad ist im derzeit ausgerollten
 Export- und Disaster-Backup **noch nicht enthalten**. Wichtige GLB-Dateien
 müssen bis zur Erweiterung der Backup-Skripte zusätzlich extern gesichert
 werden. Runtime und Q8-Gewichte sind erneut ladbar; die vom Benutzer erzeugten
 GLB-Dateien sind es nicht. Der Live-Code unter `/opt/mike-ai/trellis-studio`
 wird vom lokalen Schnellbackup über `/opt/mike-ai` erfasst.
 Die rund 100 GB reproduzierbaren Modellgewichte unter `/data/models` werden
 nicht extern dupliziert. Kerngewichte lädt `install.sh` anhand URL und SHA256
 neu. Spezialmodelle laden ihre gepinnten Container beim ersten Start erneut.
@@ -1,6 +1,6 @@
 # Roadmap fuer spezialisierte lokale KI-Dienste
-Stand: 8. September 2026
+Stand: 10. September 2026
 Diese Liste sammelt Nischenmodelle, die wir auf Athena nacheinander testen.
 Ein Eintrag ist erst produktiv, wenn er auf der realen Hardware abgenommen und
@@ -14,6 +14,7 @@ im zentralen Register `TESTED_MODELS.md` dokumentiert wurde.
 | 4 | Objekte lokalisieren und zaehlen | Grounding DINO oder RF-DETR | optionaler Vision-Worker; normales Erkennen bleibt beim vorhandenen Qwen-Vision-Projektor | offen |
 | 5 | Bildort schaetzen | GeoAgent 8B | exklusives Vision-Profil; Ergebnis nur als Wahrscheinlichkeitsrangliste | offen |
 | 6 | Eigene Orte/Bilder wiederfinden | AnyLoc oder GME-Qwen2-VL-7B | Embedding-Index mit eigener Referenzdatenbank | offen |
 | 7 | Bild zu texturiertem 3D-Modell | TRELLIS.2 4B Q8 über trellis.cpp 0.6.0 | exklusiver Worker auf RTX 5080; GLB; Standard 1024 | **integriert; technischer Ende-zu-Ende-Test bestanden** |
 ## Grundsaetze
@@ -1,6 +1,6 @@
 # Register getesteter Modelle
-Stand: 9. September 2026
+Stand: 10. September 2026
 Dieses Dokument ist die zentrale Sperrliste gegen doppelte Modelltests. Vor
 jedem Download müssen Repository, Dateiname, Basismodell, Fine-Tune und
@@ -64,6 +64,12 @@ Titelgenerierung und Kontextkompression in Hermes.
 | 09.09.2026 | `Plachtaa/seed-vc` V1, Code `51383efd921027683c89e5348211d93ff12ac2a8` | Technisch vollständig lauffähig: gepinntes CUDA-Image, persistente Gewichte und reale WAV-Konvertierung mit etwa 3,6 GiB VRAM. Im deutschen Hörtest erhielt die Ausgabe jedoch einen deutlich chinesischen Akzent | **qualitativ verworfen und vollständig entfernt**; nicht erneut für deutsche Sprachwandlung einplanen |
 | 09.09.2026 | `IAHispano/Applio`, Code `7fa68ec2166ab1331c539704159fa14901e94e5a` | Gepinntes CUDA-12.8-fähiges Image auf RTX 5080 gestartet; vollständige Applio/RVC-Oberfläche antwortet und CUDA ist verfügbar. Rund 1,8 GiB Basisgewichte und die Konfiguration wurden persistent ausgelagert. Es ist kein Zielstimmenmodell installiert; Applio kann aus einer Referenzaufnahme allein kein Modell ableiten | **technischer Start- und Persistenztest bestanden**; Konvertierung erst nach Import oder Training einer `.pth`-Stimme möglich |
 ## 3D-Erzeugung
 | Datum | Modell | Test | Ergebnis | Status / Entscheidung | Beleg |
 |---|---|---|---|---|---|
 | 10.09.2026 | TRELLIS.2 4B Q8, zehn GGUF-Komponenten, trellis.cpp 0.6.0 | Bild-zu-3D bei 512, ausschließlich RTX 5080, Hintergrundentfernung `auto`, UV `xatlas` | HTTP 200 nach 54,2 s; gültiges GLB 2 mit 4,4 MB; Container und Browseroberfläche gesund | **technisch integriert**; 1024 ist der vorgesehene Qualitätsstandard, Druck- und subjektive Geometrieabnahme noch offen | Athena: `/opt/mike-ai/trellis-studio`, Gewichte: `/data/models/trellis2-q8` |
 ## Musikgenerierung
 | Datum | Modell | Test | Ergebnis | Status / Entscheidung | Beleg |
@@ -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`.