Rebuild profile router as secure recoverable v2

docs/ROUTER_V2_MIGRATION.md

@@ -0,0 +1,58 @@
+# Router V2 – Migration und Kompatibilität
+
+## Ergebnis
+
+V2 behält die OpenAI-kompatible Basis-URL und die virtuellen Modelle
+`qwen-fast`, `qwen-medium` und `qwen-long`. Bestehende Chat-, Tool-, Audio-,
+Vision- und Bildpfade bleiben erhalten. Die Änderungen betreffen absichtlich
+die Stellen, an denen der alte Router unsicher oder nicht deterministisch war.
+
+## Bewusste Änderungen
+
+| Alt | V2 |
+|---|---|
+| alle LAN-Clients ohne Authentifizierung | API-Key für alle fachlichen Endpunkte |
+| `GET /fast` schaltet ein Modell | nur noch `POST /fast` (analog medium/long) |
+| `/health` hängt am Modellzustand | `/health` = Prozess, `/ready` = Textmodell |
+| Profil durch Textvergleich erkannt | Kontext + Alias aus Profilregister geprüft |
+| Profilwechsel und Request konnten sich überholen | atomare Modell-Lease |
+| Drain-Timeout beendete trotzdem das Modell | Wechsel wird sicher abgebrochen |
+| Workerzustand nur im RAM | atomare Zustandsdatei und Startup-Recovery |
+| beliebige Bild-URL | Data-URL, Größenlimit; Remote standardmäßig aus |
+| unbegrenzte Parallelität und Bildablage | Request- und Retention-Limits |
+| Auth-Header potenziell am Upstream | Router-Credentials werden entfernt |
+
+## Client-Migration
+
+1. Router-Key aus `/etc/mike-ai/router-api-key` ohne Anzeige in einen lokalen
+   Secret-Store des Clients übernehmen.
+2. Basis-URL unverändert auf `http://HOST:8081/v1` lassen.
+3. Den Key als OpenAI-API-Key/Bearer-Token konfigurieren.
+4. `GET /v1/models` testen und anschließend einen kurzen Chat über
+   `qwen-fast` senden.
+5. Automationen, die Profile per GET schalten, auf POST umstellen.
+6. Überwachung auf `/health` (Liveness) und `/ready` (Readiness) aufteilen.
+
+## Sicheres Rollout
+
+V2 wird nicht blind über einen laufenden Router kopiert:
+
+1. Repository-Commit und aktuelle produktive Konfiguration sichern.
+2. Profilregister gegen alle drei systemd-Overrides prüfen.
+3. API-Key erzeugen und Clients vorbereiten.
+4. Router installieren und zuerst lokal mit Key prüfen.
+5. Fast, Medium und Long jeweils einmal schalten und Alias/Kontext prüfen.
+6. Streaming und einen Tool Call testen.
+7. Erst danach normale Clients auf V2 freigeben.
+
+Ein Rollback stellt Routerdateien und Unit aus dem Installationsbackup wieder
+her. Der neu erzeugte API-Key und die Zustandsdatei enthalten keine
+Modelldateien oder Chatdaten.
+
+## Verbleibender Architekturpunkt
+
+Der Routerprozess läuft derzeit als root, weil er den systemweiten llama.cpp-
+Dienst und temporäre GPU-Worker steuert. Die Unit ist stark gehärtet, dennoch
+ist das nicht das langfristige Ideal. V3 soll HTTP/API und privilegierte
+Orchestrierung trennen: unprivilegierter Proxy plus kleiner Root-Helper mit
+festen, nicht frei parametrisierbaren Aktionen.