# Athena – Betriebsanleitung

Diese Datei ist der kurze, verbindliche Einstieg für Menschen und Agenten.

## Rolle

Athena ist eine Inferenzmaschine, kein allgemeiner Anwendungsserver.

Sie betreibt:

- llama.cpp mit genau einem aktiven Qwen-Profil,
- den OpenAI-kompatiblen Profile Router,
- 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,
- YuE2-3B mit Ladypoly-WebUI als zweiten, getrennten 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,
- den hostgebundenen Athena-Operator.

Hermes, Benutzeroberfläche und portable Fach-MCPs laufen auf Unraid. Auf Athena
werden keine zweiten Instanzen dieser Dienste angelegt.

## Pfade

| Pfad | Zweck |
|---|---|
| `/opt/mike-ai/stack` | kanonischer Checkout und Compose-Stack |
| `/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 |
| `/data/models/yue2`, `/data/music/yue2` | YuE2-Gewichte und dauerhafte Ergebnisse |
| `/etc/mike-ai` | lokale Konfiguration und Secrets, niemals Git |

Portainer läuft als separater, optionaler Verwaltungscontainer
`mike-ai-portainer` im internen Frontend-Netz und ist ausschließlich über den
namensbasierten Proxy des WireGuard-Gateways unter
`https://192.168.1.212:9443` erreichbar. Das Dashboard verwendet denselben
stabilen Aufbau auf Port 8099. Beide teilen ausdrücklich nicht den
Netzwerk-Namespace des Gateway-Containers: Ein Recreate des Gateways kann sie
dadurch nicht mehr in einem veralteten Namespace zurücklassen. Portainers
Einstellungen liegen im Docker-Volume `portainer_data`, das vom Athena-Backup
mitgesichert wird. Portainer beobachtet beziehungsweise
verwaltet Docker, ist aber keine Abhängigkeit des Inferenz-Stacks.

## Standardbefehle

```bash
cd /opt/mike-ai/stack
./manage.sh validate
./manage.sh deploy SERVICE
./manage.sh deploy core
sudo ./smoke-test.sh
```

`deploy SERVICE` verwendet `--no-deps` und fasst keine anderen Container an.
`deploy core` aktualisiert den vollständigen Athena-Kern. Das aktuell aktive
Qwen-Profil wird vom Profile Controller verwaltet.

## Modelle

- Fast: kurze, interaktive Aufgaben
- Medium/Large/Ultra: steigende Kontextgrößen desselben lokalen Qwen-Modells
- Uncensored: separates lokales Profil
- FLUX.2 Klein 9B FP8 Beta: Der Transformer läuft auf der RTX 5080, der
  Qwen3-8B-NF4-Textencoder vorübergehend auf der RTX 3060. Das aktive
  llama.cpp-Profil und Qwen3-TTS werden dafür gestoppt und danach automatisch
  wiederhergestellt. Die Beta arbeitet mit 1024 × 1024 Pixeln, vier Schritten
  und Guidance 1,0.
- Qwen3-TTS 1.7B: RTX 3060. Der Router reicht
  zusätzlich natives 24-kHz-PCM für den optionalen Hermes-Streaming-Adapter
  unter `integrations/hermes-qwen3-stream` durch.
- 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`.
- YuE2-3B: eigener exklusiver Musikmodus mit Score- und Remix-Funktionen unter
  `http://192.168.1.212:8014`. Der Routerbefehl lautet `/athena yue2`.
- 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`.

## Globale Modellrichtlinie

`config/global-system-policy.txt` wird vom Profile Router allen Textanfragen
über `/v1/chat/completions` und `/v1/responses` vorangestellt. Sie gilt damit
für alle Hermes-Profile und andere Clients, die den Athena-Router verwenden.
Der Router liest die Datei bei jeder Anfrage neu; spätere Textänderungen
benötigen nach der erstmaligen Bereitstellung keinen Container-Neustart.
Clients außerhalb des Routers und Werkzeuge, die ein Frontend nicht anbietet,
werden dadurch nicht erfasst.

## Werkzeuge

Portable Werkzeuge gehören auf Unraid in eigene, per DockerMan verwaltete
Container. Der einzige MCP auf Athena ist der Athena-Operator, weil nur er den
Athena-Host verwalten muss. Neue Fach-MCPs werden nicht in diesen Stack
eingebaut.

## Sicherheitsgrenze

Ohne ausdrücklichen aktuellen Auftrag niemals Shutdown, Reboot, Kernel,
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,
- Compose und Syntax sind gültig,
- betroffener Dienst ist gesund,
- eine kleine Funktionsprobe war erfolgreich,
- Commit und Push sind erfolgt,
- das automatische Backup bleibt gesund.