Simplify Athena operator architecture

ATHENA.md

@@ -0,0 +1,120 @@
+# 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 Recovery: `/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ächen: Hermes Agent und OpenWebUI.
+- 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 Recovery-Koffer |
+| `/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 ist die primäre Oberfläche für längere administrative und agentische
+Aufgaben. OpenWebUI 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. Recovery nur nach abgeschlossenen, funktionierenden Änderungen erneuern.
+
+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 in `platform/mcp/compose.yaml`.
+3. Eine Env-Beispieldatei unter `config/`; echte Werte nach `/etc/mike-ai`.
+4. Registrierung in Hermes und optional OpenWebUI.
+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,
+- bei einer wesentlichen Änderung der Recovery-Koffer aktualisiert wurde.
+
+Bei Unsicherheit wird der konkrete offene Punkt genannt. Es werden keine
+Ergebnisse, Werkzeugaufrufe oder erfolgreichen Deployments erfunden.
+
+## Detailreferenzen
+
+- Installation und Wiederherstellung: `docs/INSTALLATION.md`,
+  `docs/DISASTER_RECOVERY.md`
+- Aktuelle Modellprofile: `docs/STANDARD_PROFILE_MATRIX.md`
+- Netzwerk und externer Standort: `docs/WIREGUARD_HOME_PEER.md`,
+  `docs/VPN_SERVICE_PORTS.md`
+- Historische Entscheidungen und Benchmarks: übrige Dateien unter `docs/`
+