# Athena – Betriebsanleitung

Diese Datei ist der kurze, verbindliche Einstieg für Menschen und Agenten.
Für normale Arbeiten reicht sie aus. Detaildokumente unter `docs/` werden nur
gelesen, wenn diese Datei ausdrücklich darauf verweist oder eine konkrete
Fehlersuche sie benötigt.

## Aufbau

- Host: Debian, ohne lokalen Notfallzugriff oder KVM.
- Arbeitsbaum und laufender Stack: `/opt/mike-ai/stack`.
- Persistente Daten, Modelle und Backups: `/data`.
- Lokale Konfiguration und Secrets: `/etc/mike-ai` (niemals in Git).
- Benutzerzugriff auf KI-Dienste: über WireGuard, nicht über das Uni-LAN.
- OpenAI-kompatible Modell-API: Profile Router auf Port 8081.
- Oberfläche auf Athena: OpenWebUI. Der offizielle Hermes Agent läuft auf
  Unraid unter `/mnt/nvme-storage/appdata/Hermes-Agent` und verwendet Athenas
  Router als Modell-Backend.
- Inferenz: genau ein aktives llama.cpp-Textprofil; der Router wechselt bei
  Bedarf zwischen Fast, Medium, Large, Ultra und Uncensored.

## Verzeichnisse

| Pfad | Zweck |
|---|---|
| `/opt/mike-ai/stack` | Einziger Git-Checkout und einzige Quelle für Deployments |
| `/data/models` | GGUF-Modelle, Projektoren und weitere große Modelldateien |
| `/data` | Persistente Anwendungsdaten und Docker-Backups |
| `/etc/mike-ai` | Lokale Env-Dateien, API-Schlüssel und SSH-Schlüssel |
| `/tmp` | Einmalige Hilfsprogramme und temporäre Arbeitsdateien |

Die früheren Checkouts `/data/mike-ai-operator/repository` und
`/root/AI-Profile-Router` sind keine Arbeitsquellen. Sie dürfen nach der
Migration höchstens als gekennzeichnetes Archiv existieren.

## Container-Prinzip

Ein eigener Container ist sinnvoll, wenn ein Dienst eigene Abhängigkeiten,
Zugangsdaten oder eine eigene Fehlergrenze hat. Deshalb bleiben die fachlichen
MCPs getrennt, beispielsweise Home Assistant, Unraid, ARR, Navidrome, Deemix,
Web und SSH. Es gibt jedoch keine zusätzlichen MCPs für einzelne
Zwischenschritte einer Installation.

Hermes auf Unraid ist die primäre Oberfläche für längere administrative und
agentische Aufgaben. OpenWebUI auf Athena erhält weiterhin die Werkzeuge, die
für kurze Abfragen sinnvoll sind. Ein neuer MCP muss nicht automatisch in jede
Oberfläche eingebunden werden; das richtet sich nach dem Auftrag.

## Standardablauf für Änderungen

1. `athena_operator_inspect` einmal für den betroffenen Bereich aufrufen.
2. Mit `athena_operator_search_source` die konkrete Datei finden.
3. Mit `athena_operator_read_source` nur den benötigten Ausschnitt lesen.
4. Änderung über `athena_operator_change` ausführen.
5. Syntax, Compose, Dienstzustand und eine kleine Funktionsprobe prüfen.
6. Geänderte Dateien committen und pushen.
7. Ein manuelles Datenbackup nur nach speicherrelevanten Änderungen auslösen.

Nicht bei jedem Zwischenschritt die gesamte Plattform neu untersuchen. Keine
vollständigen Compose-, Installations- oder Dokumentationsdateien in den Chat
laden, wenn ein kleiner Ausschnitt genügt. Derselbe fehlgeschlagene Pfad oder
Werkzeugaufruf wird höchstens einmal wiederholt.

## Neuer MCP

Für einen neuen MCP sind gewöhnlich nur diese Teile nötig:

1. Servercode und Dockerfile unter `platform/mcp/`.
2. Ein Service im eingebundenen `platform/mcp/compose.yaml`.
3. Eine Env-Beispieldatei unter `config/`; echte Werte nach `/etc/mike-ai`.
4. Genau ein Eintrag in `config/mcp-registry.json`; daraus werden Hermes und
   OpenWebUI automatisch erzeugt.
5. Ein kleiner Test sowie ein kurzer Eintrag in dieser Datei oder in der
   Komponentenübersicht, falls wirklich zusätzliche Erklärung nötig ist.

Dann wird nur der neue MCP gebaut und gestartet. Router, Qwen, WireGuard,
Hermes und der komplette Stack werden nicht pauschal neu gestartet.

## Temporär oder dauerhaft

- „Nutze Programm X“: wenn es fehlt, nur temporär unter `/tmp` oder in einem
  kurzlebigen Container verwenden und anschließend entfernen.
- „Installiere Programm X dauerhaft“: versioniert in den Stack aufnehmen.
- Bestehende Dienste auf Unraid oder im Heimnetz werden weiterverwendet; auf
  Athena wird nicht ohne Grund eine zweite Instanz aufgebaut.

## Sicherheitsgrenze

Athena darf ohne ausdrücklichen, aktuellen Auftrag niemals heruntergefahren
oder neu gestartet werden. Ebenfalls tabu sind Änderungen an SSH, LAN,
WireGuard, Firewall, Bootloader, Kernel, Partitionen und Mounts. Diese Grenze
schützt die Erreichbarkeit des entfernten Hosts.

Innerhalb des vertrauenswürdigen WireGuard-Netzes dürfen die vorgesehenen
Container normal miteinander, mit dem Heimnetz und mit dem Internet
kommunizieren. Keine zusätzlichen Netzwerkbarrieren ohne konkreten Bedarf.

Secrets dürfen lokal von Athena und dem lokalen Modell verwendet werden. Sie
werden aber weder in Git noch in normalen Werkzeugausgaben oder Chatantworten
veröffentlicht.

## Fertig bedeutet

Eine Änderung ist erst fertig, wenn:

- der versionierte Arbeitsbaum die Änderung enthält,
- der betroffene Dienst den neuen Stand verwendet,
- ein fokussierter Test erfolgreich war,
- Git-Status und Commit bekannt sind,
- das automatische Backup läuft und bei Datenänderungen ein Archiv geprüft wurde.

Bei Unsicherheit wird der konkrete offene Punkt genannt. Es werden keine
Ergebnisse, Werkzeugaufrufe oder erfolgreichen Deployments erfunden.

## Referenzen

- Installation und Überblick: `README.md`
- Wiederherstellung: `docs/RECOVERY.md`
- Modellprofile: `docs/STANDARD_PROFILE_MATRIX.md`