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`.