Document complete recovery requirements and reference state

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.