Document complete recovery requirements and reference state

README.md

@@ -46,6 +46,9 @@ llama.cpp :8080 + profilabhängige MCP-Server
 
 - [Architektur](docs/ARCHITECTURE.md)
 - [Komponentenverzeichnis](docs/COMPONENTS.md)
+- [Aktueller produktiver Referenzstand](docs/CURRENT_REFERENCE.md)
+- [Noch benötigte Wiederherstellungsartefakte](docs/RECOVERY_REQUIREMENTS.md)
+- [Disaster Recovery und Abnahme](docs/DISASTER_RECOVERY.md)
 - [Saubere Installation](docs/INSTALLATION.md)
 - [Betrieb und Profilwechsel](docs/OPERATIONS.md)
 - [Sicherheitsmodell](docs/SECURITY.md)

docs/CURRENT_REFERENCE.md

@@ -0,0 +1,163 @@
+# Aktueller produktiver Referenzstand
+
+Stand: 20. August 2026. Dieses Dokument beschreibt die funktionierende
+Referenz vor dem geplanten Neuaufbau. Es ist keine Empfehlung, jede Altlast des
+Hosts zu übernehmen.
+
+## Hardware und Betriebssystem
+
+| Bereich | Referenz |
+|---|---|
+| Betriebssystem | Debian 13 `trixie` |
+| Kernel | 6.12.101+deb13-amd64 |
+| CPU | AMD Ryzen 5 5600, 6 Kerne/12 Threads |
+| RAM | 48 GiB DDR4-2666 |
+| GPU | NVIDIA GeForce RTX 5080, 16 GiB VRAM |
+| NVIDIA-Treiber | 610.57.04 |
+| System-SSD | Samsung 980 PRO 1 TB |
+| Daten-SSD | Samsung 980 PRO 2 TB |
+
+Die früher verwendete Radeon RX 470 ist ausgebaut und gehört nicht zur
+Zielplattform.
+
+## Produktiver Text-Stack
+
+| Eigenschaft | Aktueller Wert |
+|---|---|
+| Runtime | llama.cpp |
+| Repository | `https://github.com/ggml-org/llama.cpp.git` |
+| Commit | `4df29be4f4c3673f428170fda944a5b19f743bb8` |
+| Compiler | GCC 14.2 |
+| Hauptdienst | `mike-ai-llama-ui.service` |
+| llama.cpp-Port | 8080, auf dem alten Host noch im LAN gebunden |
+| Client-Port | 8081 über den Router |
+| MCP-Konfiguration | `/etc/mike-ai/mcp-servers.json` |
+
+### Aktives Fast-Profil
+
+- Qwen3.8-27B IQ4-MIX
+- Kontext 73.728
+- vollständig auf CUDA0
+- Flash Attention
+- KV-Cache Q4_0 für K und V
+- MTP Draft, maximal zwei Tokens
+- sechs Threads und sechs Batch-Threads
+- Batch 64, Micro-Batch 32
+- ein paralleler Slot
+- Jinja und automatisches Reasoning
+- Temperatur 0,2, Top-p 0,8, Top-k 20
+
+### Profile
+
+| Profil | Virtuelles Modell | Kontext | Besonderheit |
+|---|---|---:|---|
+| Fast | `qwen-fast` | 73.728 | IQ4-MIX, MTP2, vollständig GPU |
+| Medium | `qwen-medium` | 94.208 | IQ4_XS Pure, ohne MTP |
+| Long | `qwen-long` | 131.072 | IQ4-MIX, MTP2, FFN-Blöcke 0–11 auf CPU |
+
+## Router
+
+- Dienst: `mike-ai-profile-router.service`
+- Port: 8081
+- Upstream: `127.0.0.1:8080`
+- Commit des Plattform-Repositories: siehe jeweils aktuelles `main`
+- Umschaltskript: `/usr/local/bin/llama-profile`
+- Timeout für Profilwechsel und Requests: 600 Sekunden
+
+Der Router übernimmt:
+
+- OpenAI-kompatibles Chat-Proxying und Streaming
+- virtuelle Modelle und automatische Profilumschaltung
+- Tool Calls
+- Vision-Hotswap mit Cache für Folgefragen
+- FLUX-Hotswap zur Bildgenerierung
+- Whisper Speech-to-Text
+- XTTS Text-to-Speech
+- Zustands- und Modellendpunkte
+
+## Vision
+
+| Bereich | Referenz |
+|---|---|
+| Text-/Visionmodell | Qwen3.8-27B Q3_K_M |
+| Projektor | BF16-mmproj |
+| Kontext | 32.768 |
+| temporärer Port | 8086 |
+| maximale Ausgabe | 4.096 Tokens |
+
+Vision wird nicht dauerhaft parallel geladen. Der Router entlädt das
+Textprofil, analysiert das Bild und stellt danach das ursprüngliche Profil
+wieder her.
+
+## Bildgenerierung
+
+- Modell: FLUX.2 klein Base 4B
+- Runtime: PyTorch/Diffusers
+- CPU-Offload aktiviert
+- Standard: 30 Schritte
+- High: 50 Schritte
+- Worker wird nach jedem Job vollständig beendet
+- Qwen wird anschließend mit dem vorherigen Profil wiederhergestellt
+
+## Sprache
+
+### Whisper
+
+- Modell: large-v3-turbo
+- lokale Standardsprache: Deutsch
+- CPU-Ausführung
+- acht Threads im produktiven Worker
+- Port 8084, nur localhost
+- ffmpeg für Eingabeumwandlung
+
+### XTTS
+
+- Modell: Coqui XTTS-v2
+- CPU-only
+- Stimme: `claribel`
+- Deutsch und Englisch
+- Port 8085, auf dem alten Host noch im LAN gebunden
+- eigenes Python-3.11-Venv
+
+## Websuche
+
+- Docker Compose
+- SearXNG, per Digest gepinnt
+- TinySearch 0.5.1, per Digest gepinnt
+- TinySearch nur auf `127.0.0.1:8000`
+- lokale ONNX-Embeddings
+- kompakte Web-MCP-Fassade mit vier Werkzeugen
+- strukturierte API-Pfade für GitHub und Hugging Face
+
+## MCP-Referenz
+
+Aktuell existieren funktionale Adapter für:
+
+- Websuche
+- Home Assistant
+- Sonarr/Radarr
+- Unraid read-only
+- eigener Unraid-Administrationsserver
+
+Der frühere allgemeine Shell-MCP und doppelte, schreibende Werkzeuge gehören
+nicht zum Sicherheitsziel und werden nicht ungeprüft wiederhergestellt.
+
+## Bekannte Probleme des alten Hosts
+
+- Systempartition vollständig gefüllt
+- Datenpartition nahezu vollständig gefüllt
+- etwa 1,27 TB Modelle, darunter Duplikate
+- mehrere alte llama.cpp-Builds
+- RX-Dienste trotz ausgebauter Karte
+- aktivierte Benchmark-/Race-Dienste
+- alte systemd-Overrides und Sicherungskopien
+- unvollständiger großer Modelldownload
+- zu viele MCP-Werkzeuge gleichzeitig im Kontext
+
+Diese Punkte erklären den Neuaufbau, sind aber keine Bestandteile der neuen
+Plattform.
+
+Zusätzliche bekannte Sicherheitsabweichung: llama.cpp auf Port 8080 und XTTS
+auf Port 8085 sind im alten Zustand breiter gebunden als im Zielsystem. Beim
+Neuaufbau werden beide auf localhost begrenzt; Clients verwenden ausschließlich
+den Router auf Port 8081.

docs/DISASTER_RECOVERY.md

@@ -0,0 +1,107 @@
+# Disaster Recovery und Abnahme
+
+## Definition „vollständig wiederhergestellt“
+
+Eine Installation gilt erst dann als wiederhergestellt, wenn nicht nur Prozesse
+laufen, sondern alle fachlichen Funktionen geprüft wurden.
+
+## Phase A – Basissystem
+
+- [ ] Betriebssystem und Kernel dokumentierter Stand
+- [ ] Uhrzeit, Zeitzone und NTP korrekt
+- [ ] Netzwerk nach Neustart automatisch verfügbar
+- [ ] NVIDIA-Treiber geladen
+- [ ] RTX und kompletter VRAM sichtbar
+- [ ] System- und Modelllaufwerk korrekt gemountet
+- [ ] mindestens 15 Prozent frei auf dem Systemlaufwerk
+- [ ] Docker und Compose funktionieren
+- [ ] keine RX- oder Benchmark-Altlast aktiviert
+
+## Phase B – Textmodell
+
+- [ ] llama.cpp entspricht dem festgelegten Commit
+- [ ] Modelldateien stimmen mit SHA256 überein
+- [ ] Fast startet mit 73.728 Kontext
+- [ ] Medium startet mit 94.208 Kontext
+- [ ] Long startet mit 131.072 Kontext
+- [ ] GPU-/CPU-Verteilung entspricht den Profilen
+- [ ] Fast erreicht den festgelegten Geschwindigkeitstoleranzbereich
+- [ ] MTP funktioniert und verursacht keine Qualitätsregression
+- [ ] Rolling-/Kontextverhalten ist bewusst definiert und getestet
+
+## Phase C – Router
+
+- [ ] `/status` meldet den richtigen Upstream
+- [ ] `/v1/models` liefert drei virtuelle Modelle
+- [ ] `/fast`, `/medium` und `/long` wechseln zuverlässig
+- [ ] automatischer Wechsel über virtuellen Modellnamen funktioniert
+- [ ] paralleler Wechsel wird sauber gesperrt
+- [ ] Streaming funktioniert
+- [ ] Tool Calls funktionieren
+- [ ] Fehler sind OpenAI-kompatibel
+- [ ] ein abgebrochener Client hinterlässt keinen blockierten Job
+
+## Phase D – Web und MCP
+
+- [ ] SearXNG und TinySearch gesund
+- [ ] Websuche liefert kompakte, quellengebundene Ergebnisse
+- [ ] GitHub- und Hugging-Face-Routing geprüft
+- [ ] Home Assistant read-only Diagnose geprüft
+- [ ] ARR read-only Suche geprüft
+- [ ] Unraid read-only Diagnose geprüft
+- [ ] schreibende Werkzeuge standardmäßig nicht geladen
+- [ ] Tool-Schemas bleiben innerhalb des festgelegten Kontextbudgets
+- [ ] kein Secret erscheint in Toolantworten oder Logs
+
+## Phase E – Vision, Bild und Sprache
+
+- [ ] neues Bild löst genau einen Vision-Hotswap aus
+- [ ] Folgefrage verwendet Cache und keinen zweiten Hotswap
+- [ ] Bilddaten werden vor dem Textmodell sanitisiert
+- [ ] Qwen-Profil wird nach Vision wiederhergestellt
+- [ ] FLUX erzeugt Standard- und High-Bild
+- [ ] Qwen-Profil wird nach FLUX wiederhergestellt
+- [ ] Whisper transkribiert deutsche und englische Testdatei
+- [ ] XTTS erzeugt deutsche WAV- und MP3-Ausgabe
+- [ ] STT/TTS blockieren das Textmodell nicht unzulässig
+
+## Phase F – Sicherheitsprüfung
+
+- [ ] Port 8080 von normalen Clients nicht erreichbar
+- [ ] Hilfsports nur localhost
+- [ ] Router nur aus erlaubtem Netz erreichbar
+- [ ] Dienste laufen mit minimalen Rechten
+- [ ] Environment-Dateien Modus 0600
+- [ ] kein allgemeiner Shell-MCP im Standardprofil
+- [ ] Schreibaktionen verlangen Vorschau und Approval Ticket
+- [ ] Secret-Restore wurde ohne Klartextausgabe durchgeführt
+
+## Phase G – Fachlicher Benchmark
+
+Der gespeicherte Standardbenchmark wird mindestens mit Fast und Long ausgeführt:
+
+- Home-Assistant-Automatisierung analysieren
+- Logs lesen und Fehlerursache begründen
+- sichere Korrektur vorschlagen
+- Webrecherche mit Quellen durchführen
+- Docker-/Unraid-Diagnose simulieren
+- Tool-Limits, Halluzinationen und unnötige Aufrufe bewerten
+
+Die neue Installation muss innerhalb einer vorher festgelegten Toleranz zur
+Referenz liegen. Nur „Dienst läuft“ genügt nicht.
+
+## Recovery-Protokoll
+
+Für jeden Wiederaufbau werden festgehalten:
+
+- Datum
+- verwendeter Repository-Commit
+- Modellmanifest-Version
+- Hardware
+- Dauer je Phase
+- Abweichungen
+- Testergebnis
+- verantwortliche Freigabe
+
+Erst nach Abschluss aller Pflichtpunkte darf der alte Host gelöscht oder als
+Fallback außer Betrieb genommen werden.

docs/RECOVERY_REQUIREMENTS.md

@@ -0,0 +1,188 @@
+# Noch benötigte Wiederherstellungsartefakte
+
+Diese Liste definiert, was vor einer Löschung oder grundlegenden Änderung des
+alten Hosts noch gesichert beziehungsweise präzisiert werden muss.
+
+Statuswerte:
+
+- **gesichert**: vollständig im Git oder anderweitig reproduzierbar
+- **offen**: muss vor dem Neuaufbau erledigt werden
+- **lokal geheim**: darf nicht unverschlüsselt ins Git
+
+## 1. Modelle und Prüfsummen – offen, höchste Priorität
+
+Für jedes tatsächlich benötigte Modell werden erfasst:
+
+- exakte Downloadquelle und Repository-ID
+- Revision oder Commit
+- Dateiname und Splitreihenfolge
+- Dateigröße
+- SHA256 jeder Datei
+- Lizenz
+- Zielpfad
+- zugehöriger mmproj/MTP-Tensor
+- getestete Runtime und Profilzuordnung
+
+Das Ergebnis wird als `platform/models/manifest.local.yaml` erzeugt. Die Datei
+enthält keine Geheimnisse, kann aber wegen möglicher privater Quellen zunächst
+lokal bleiben. Eine bereinigte Fassung gehört anschließend ins Git.
+
+Pflichtrollen:
+
+- Qwen Fast/Long IQ4-MIX
+- Qwen Medium IQ4_XS Pure
+- Qwen Q3 Vision
+- BF16 Vision-Projektor
+- Whisper large-v3-turbo
+- FLUX.2 klein
+- XTTS-v2 und verwendete Stimme
+
+## 2. Externe Komponenten und Commits – offen
+
+Für jedes separate Projekt benötigen wir Repository und Commit:
+
+- Home-Assistant-MCP
+- ARR-MCP
+- Unraid read-only MCP
+- gegebenenfalls eigener Unraid-Administrations-MCP
+- LLama-GUI, falls sie erhalten bleibt
+
+Jede Komponente bekommt zusätzlich:
+
+- Installationsbefehl
+- Systembenutzer
+- systemd-/Docker-Datei
+- Health-Check
+- benötigte Environment-Namen ohne Werte
+- Liste read-only und schreibender Werkzeuge
+
+## 3. Basissystem-Bootstrap – offen
+
+Ein idempotentes Bootstrap-Skript muss noch erstellen:
+
+- Paketquellen und benötigte Debian-Pakete
+- NVIDIA-Treiber und exakte Version
+- CUDA Toolkit und Buildabhängigkeiten
+- Docker und Compose
+- Python 3.13 und Python 3.11/uv
+- Dienstbenutzer und Gruppen
+- Verzeichnisse, Eigentümer und Dateirechte
+- Firewallregeln
+- Journalgrößenlimit
+- automatische Sicherheitsupdates nach bewusstem Freigabemodell
+
+Das Skript darf weder formatieren noch Modelle löschen. Destruktive
+Speicheroperationen bleiben ein separater, ausdrücklich bestätigter Schritt.
+
+## 4. Secret-Verfahren – lokal geheim
+
+Benötigt wird ein festes Verfahren für:
+
+- Home-Assistant-Token
+- Sonarr-/Radarr-API-Schlüssel
+- Unraid-Zugang
+- optionale GitHub-, Hugging-Face- und Brave-Schlüssel
+- SSH-Hostschlüssel und bekannte Hosts
+
+Noch festzulegen:
+
+- verschlüsseltes Backupformat, beispielsweise age oder ein Passwortmanager
+- Besitzer und Rechte je Environment-Datei
+- Rotation und Widerruf
+- Restore ohne Ausgabe der Werte in Terminal- oder Modellkontext
+- Funktionstest mit ausschließlich Statuscode, niemals Tokenanzeige
+
+## 5. Netzwerk und DNS – offen
+
+Dokumentiert werden müssen:
+
+- endgültiger Hostname
+- statische Adresse oder DHCP-Reservierung
+- DNS-Name
+- erlaubte Client-Netze
+- Firewallmatrix pro Port
+- TLS/Reverse Proxy, sofern verwendet
+- Verhalten bei Neustart und fehlendem Netzwerk
+
+Zielmatrix:
+
+| Port | Zugriff |
+|---:|---|
+| 22 | nur Administration |
+| 8080 | localhost |
+| 8081 | vertrauenswürdiges LAN/VPN |
+| 8084 | localhost |
+| 8085 | localhost |
+| 8000 | localhost |
+| 5240 | optional nur Administration |
+
+## 6. Speicherlayout – offen
+
+Vor dem Neuaufbau festlegen:
+
+- System, Modelle, Caches und Ergebnisse auf getrennten Mounts
+- Dateisystem des Modelllaufwerks
+- Mindestreserve und Warnschwellen
+- Docker-Datenpfad
+- Hugging-Face- und Python-Cachepfade
+- Backupziel
+- Aufbewahrungsregeln für Bilder, Audio und Logs
+
+Empfehlung: System unter 85 Prozent, Modelllaufwerk unter 90 Prozent halten.
+
+## 7. Runtime-Locks – teilweise gesichert
+
+Bereits gesichert:
+
+- llama.cpp-Commit
+- zentrale Python-Versionen für FLUX und XTTS
+- TinySearch-/SearXNG-Image-Digests
+
+Noch offen:
+
+- vollständiges `pip freeze` je produktivem Venv
+- CUDA-kompatible Wheel-Quelle
+- FLUX-Revision
+- XTTS-Modellrevision
+- Whisper-Commit und Buildoptionen
+- Docker-Engine-/Compose-Version
+
+## 8. Betriebsdaten und Aufbewahrung – offen
+
+Festlegen, welche Daten persistent sein sollen:
+
+- generierte Bilder: standardmäßig zeitlich begrenzt
+- Audiodateien: standardmäßig nicht dauerhaft
+- Vision-Cache: flüchtig
+- Chatverläufe: nicht Bestandteil dieser Plattform
+- Benchmarkresultate: eigenes Repository
+- Logs: ohne Prompt- und Tool-Antwortinhalte
+
+## 9. Ende-zu-Ende-Installer – offen
+
+Der gewünschte Endzustand ist:
+
+```text
+bootstrap-host
+install-runtime
+verify-model-manifest
+install-platform
+restore-secrets
+enable-selected-mcp-profiles
+run-acceptance-tests
+```
+
+Jeder Schritt muss wiederholbar, einzeln prüfbar und bei Fehlern abbrechbar
+sein. Ein fehlgeschlagener Schritt darf keinen halb aktivierten Dienst
+hinterlassen.
+
+## 10. Dokumentations-Abnahmekriterium
+
+Der alte Host darf erst verworfen werden, wenn eine fachkundige Person mit:
+
+1. diesem Repository,
+2. den dokumentierten Modellquellen,
+3. dem verschlüsselten Secret-Backup
+
+einen leeren Host ohne Wissen aus früheren Chats vollständig in Betrieb nehmen
+kann.