Document production image prompt enhancement

docs/CONTAINER_INVENTORY.md

@@ -2,7 +2,7 @@
 
 Stand: 21. September 2026
 
-Athena hat 31 reguläre Docker-Container. Nicht jeder Container enthält
+Athena hat 33 reguläre Docker-Container. Nicht jeder Container enthält
 ein KI-Modell: Router, Oberflächen, Netzwerk, Steuerung und Sicherung sind
 gewöhnliche Dienste. Die rechenintensiven GPU-Worker werden absichtlich nur bei
 Bedarf gestartet. Ein Container im Zustand `Created` oder `Exited (0)` ist daher
@@ -15,6 +15,8 @@ nicht automatisch ein ungenutzter Rest.
 | `mike-ai-bonsai2-ab` | Bonsai-2-Vergleichsmodell | Gestoppter, reproduzierbar dokumentierter A/B-Testcontainer; kein Produktivprofil. |
 | `mike-ai-applio-studio` | Applio/RVC; Stimmenmodelle werden nutzerseitig ergänzt | Vollständige RVC-Oberfläche für Inferenz, Modellverwaltung und Training auf der RTX 5080. Für eine Konvertierung ist ein importiertes oder trainiertes `.pth`-Modell nötig; eine Referenzaufnahme allein reicht nicht. |
 | `mike-ai-image-worker` | Qwen-Image-2.1 INT8, Qwen3-VL-8B INT8 und VAE | Produktiver Bildworker; erzeugt und bearbeitet Bilder transaktional auf der RTX 5080. |
+| `mike-ai-image-prompt-enhancer-t2i` | Qwen-Image-2.1 PE-T2I Q5_K_M | Kurzlebiger offizieller Prompt-Aufbereiter für reine Textaufträge auf der RTX 3060; außerhalb eines Bildauftrags gestoppt. |
+| `mike-ai-image-prompt-enhancer-i2i` | Qwen-Image-2.1 PE-I2I Q5_K_M mit BF16-MMProj | Kurzlebiger offizieller Prompt-Aufbereiter für bis zu vier Referenzbilder auf der RTX 3060; außerhalb eines Bildauftrags gestoppt. |
 | `mike-ai-flux-image-worker` | FLUX.2 Klein 9B FP8, Qwen3-8B NF4 Textencoder und VAE | Gestoppter Rückfallworker; wird vom normalen Router-Bildpfad nicht gestartet. |
 | `mike-ai-llama-dashboard` | kein Modell | Zeigt Telemetrie, Profile, GPU-Nutzung, Slot-Kontextbelegung mit Verlauf und Betriebsarten an und bietet die Modusumschaltung. |
 | `mike-ai-llama-fast` | Qwen3.8-27B `IQ4-MIX`, Qwen-MMProj BF16 | Schnelles Q4-Text-/Vision-Profil mit 76.800 Token Kontext. |
@@ -45,7 +47,8 @@ nicht automatisch ein ungenutzter Rest.
 
 Alle fünf llama-Container verwenden llama.cpp 0.4.1 (`b29c606`). Medium lief
 beim Abgleich gesund mit zwei Slots; die anderen vier Textprofile waren
-planmäßig nicht aktiv. Der Image-Worker war ebenfalls gestoppt. Die
+planmäßig nicht aktiv. Der Image-Worker und beide Prompt-Enhancer waren
+ebenfalls gestoppt. Die
 Infrastruktur und die Musik-/Applio-Oberflächen liefen. Diese Zustände ändern
 sich mit der Nutzung.
 Die Detailbeschreibungen der Spezialmodelle stammen aus der bestehenden

docs/LIVE_STATE.md

@@ -3,7 +3,8 @@
 Stand: **21. September 2026**. Quelle: lesender SSH-Abgleich von Docker,
 Compose-Dateien, Git-Inhalten, Images, Health-Endpunkten und Backup-Timern.
 Containerzustände sind Momentaufnahmen; der Controller darf Profile danach
-umschalten. Es wurde für diesen Abgleich kein Dienst neu gestartet.
+umschalten. Für die Prompt-Enhancer-Integration wurden Router und Controller
+gezielt neu gebaut und beide Bildpfade transaktional geprüft.
 
 Aktueller Abschluss: [Test- und Änderungsübersicht](ATHENA_SESSION_20260920.md).
 Die folgenden MTP-/Microbatch-Werte enthalten die abschließenden Übernahmen.
@@ -41,7 +42,11 @@ nicht mehr den aktuellen Containerzustand.
 
 - Qwen-Image-2.1 INT8 läuft produktiv über gepinntes ComfyUI mit Low-VRAM auf
   der RTX 5080. Der Router verwendet 25 Schritte, Guidance 1 und bis zu vier
-  Referenzbilder. FLUX.2 Klein 9B FP8 bleibt mit seinen Gewichten als
+  Referenzbilder. Vor jedem Bild startet er automatisch den passenden
+  offiziellen Q5-Prompt-Enhancer: PE-T2I für reine Textaufträge oder PE-I2I
+  für Referenzbilder. Der Enhancer läuft kurzzeitig auf der RTX 3060, wird vor
+  dem Rendern wieder gestoppt und speichert Rohprompt sowie Rewrite im
+  Bild-Sidecar. FLUX.2 Klein 9B FP8 bleibt mit seinen Gewichten als
   gestoppter, explizit allowlist-beschränkter Rückfallcontainer erhalten.
 - Qwen3-TTS 1.7B auf 3060 hinter dem TTS-Gateway; kein Piper-Fallback.
 - Whisper.cpp `ggml-small` auf CPU über `/v1/audio/transcriptions`.
@@ -68,7 +73,7 @@ nicht mehr den aktuellen Containerzustand.
   trotzdem Status, Modelle und vorbereitende Aufgaben anzeigen; eine echte
   Konvertierung verlangt den Applio-Modus.
 
-Der vollständige Bestand der **31** angelegten Docker-Container steht im
+Der vollständige Bestand der **33** angelegten Docker-Container steht im
 [Container-Inventar](CONTAINER_INVENTORY.md). `Created` oder `Exited` bei
 Spezialworkern bedeutet nicht automatisch einen zu entfernenden Testrest.
 
@@ -104,7 +109,7 @@ externe Restic-Timer zwar ebenfalls aktiviert, aber ohne seine erforderliche
 `/etc/mike-ai/disaster-backup.env` **nicht** als funktionierende externe
 Sicherung zu werten. Details und Restore-Grenzen: [Backup](RECOVERY.md).
 
-Geprüft wurden aktuelle Container- und Quellenstände sowie ausgewählte
-Health-Endpunkte. Keine erneuten Bild-, Langkontext-, Trainings- oder
-Restore-Tests; ältere Ergebnisse sind im [Update-Audit](UPDATE_AUDIT_20260915.md)
+Geprüft wurden aktuelle Container- und Quellenstände, Health-Endpunkte sowie
+Text-zu-Bild und Referenzbildbearbeitung mit den beiden Prompt-Enhancern. Keine
+erneuten Langkontext-, Trainings- oder Restore-Tests; ältere Ergebnisse sind im [Update-Audit](UPDATE_AUDIT_20260915.md)
 und [FLUX-Auflösungstest](FLUX_RESOLUTION_TEST_20260912.md) dokumentiert.

docs/QWEN_IMAGE_21.md

@@ -31,10 +31,14 @@ Ein Bildauftrag läuft transaktional:
 
 1. Der Router merkt sich das aktive Textprofil.
 2. Der Profile Controller stoppt LLM, TTS und andere GPU-Spezialworker.
-3. `mike-ai-image-worker` startet Qwen Image auf der RTX 5080.
-4. Der Adapter erzeugt das Bild oder bearbeitet bis zu vier Referenzbilder.
-5. Der Qwen-Worker wird vollständig gestoppt.
-6. Das vorherige Textprofil und Qwen3-TTS werden wiederhergestellt.
+3. Bei einem Textauftrag startet `mike-ai-image-prompt-enhancer-t2i`, bei
+   Referenzbildern `mike-ai-image-prompt-enhancer-i2i` auf der RTX 3060.
+4. Der offizielle Qwen-Enhancer schreibt den knappen Benutzertext um und wird
+   anschließend vollständig gestoppt.
+5. `mike-ai-image-worker` startet Qwen Image auf der RTX 5080 und erzeugt das
+   Bild oder bearbeitet bis zu vier Referenzbilder.
+6. Der Qwen-Worker wird vollständig gestoppt.
+7. Das vorherige Textprofil und Qwen3-TTS werden wiederhergestellt.
 
 Der Container ist außerhalb eines Auftrags gestoppt. Das ist der Sollzustand.
 
@@ -46,13 +50,14 @@ sudo ./scripts/prepare-qwen-image-21.sh
 ```
 
 Das Skript lädt fehlende Dateien mit festen SHA-256-Prüfsummen, baut den
-produktiven Qwen-Worker und legt Qwen sowie FLUX gestoppt an. Es lädt dabei
-kein Modell in den VRAM.
+produktiven Qwen-Worker und legt Qwen, beide Prompt-Enhancer sowie FLUX
+gestoppt an. Es lädt dabei kein Modell in den VRAM.
 
 ## Funktionsprobe über den echten Routerweg
 
 ```bash
 curl -sS http://127.0.0.1:8081/v1/images/generations \
+  -H "Authorization: Bearer $ROUTER_API_KEY" \
   -H 'Content-Type: application/json' \
   -d '{
     "model":"Qwen-Image-2.1-int8",
@@ -64,7 +69,7 @@ curl -sS http://127.0.0.1:8081/v1/images/generations \
   }'
 ```
 
-Nach dem Lauf müssen `mike-ai-image-worker` und
+Nach dem Lauf müssen `mike-ai-image-worker`, beide Prompt-Enhancer und
 `mike-ai-flux-image-worker` gestoppt sein und das vorherige LLM-Profil wieder
 gesund laufen.
 
@@ -151,68 +156,76 @@ Historische FLUX-Messwerte und Grenzen stehen in
 [FLUX_9B_BETA.md](FLUX_9B_BETA.md) und
 [FLUX_RESOLUTION_TEST_20260912.md](FLUX_RESOLUTION_TEST_20260912.md).
 
-## Offizieller Prompt Enhancer: Vorabtest vom 21. September 2026
+## Offizielle Prompt-Enhancer im produktiven Router
 
-Qwen veröffentlicht für Referenzbild-Aufträge einen separaten, auf
-Qwen3.5-VL 9B nachtrainierten Prompt Enhancer. Er ist kein Bestandteil der
-Qwen-Image-Gewichte und wird vom ComfyUI-Workflow nicht automatisch geladen.
-Der produktive Router verwendet ihn derzeit noch nicht; der folgende Test
-prüfte zunächst Speicherbedarf, Laufzeit und Wirkung.
+Qwen veröffentlicht zwei getrennte, auf Qwen3.5-VL 9B nachtrainierte
+Prompt-Enhancer. Sie sind kein Bestandteil der Qwen-Image-Gewichte. Athena
+startet automatisch die zum Auftrag passende Variante; OpenClaw ruft weiterhin
+nur sein normales Werkzeug `image_generate` mit dem unveränderten Modellnamen
+`openai/Qwen-Image-2.1-int8` auf.
 
-Geprüft wurde `Qwen/Qwen-Image-2.1-PE-I2I`, Revision
-`72927bc08afc99b7888ceb7d7d51a12db3700bbd`. Der offizielle Systemprompt
-verlangt bei mehreren Eingabebildern eine strukturierte Zuordnung und liefert
-zusätzlich `wh_ratio` beziehungsweise `ratio_follow`.
+- `mike-ai-image-prompt-enhancer-t2i` bereitet reine Textaufträge auf.
+- `mike-ai-image-prompt-enhancer-i2i` wertet ein bis vier Referenzbilder
+  gemeinsam aus und trennt Identität, gewünschte Änderungen und neue Szene.
+- Beide verwenden getrennte offizielle Systemprompts, `Q5_K_M`, llama.cpp
+  Build 10930, 16.384 Token Kontext und höchstens 2.048 Denktokens.
+- Sie laufen ausschließlich und nacheinander auf der RTX 3060. Nach dem Rewrite
+  werden sie gestoppt; Qwen-Image rendert anschließend auf der RTX 5080.
+- Falls der Client keine Größe vorgibt, übernimmt der Router das vom Enhancer
+  vorgeschlagene Seitenverhältnis und bildet es auf eine erlaubte Auflösung ab.
+  Eine ausdrücklich angegebene gültige Größe bleibt unverändert.
+- Das Sidecar jedes PNG enthält `original_prompt`, den tatsächlich verwendeten
+  `prompt` und Modell, Quantisierung, Laufzeit und Verhältnis unter
+  `prompt_enhancer`. Verdeckte Denktokens werden nicht gespeichert.
+- Ein fehlgeschlagener Rewrite bricht den Bildauftrag sichtbar ab. Der Router
+  sendet in diesem Fall keinen unaufbereiteten Ersatzprompt an Qwen-Image.
 
-### FP8 auf der RTX 3060
+### Gepinnte Dateien
 
-Der vorquantisierte Testcheckpoint
-`prithivMLmods/Qwen-Image-2.1-PE-I2I-FP8`, Revision
-`ac9065ce94fdc39b9aecfff7d11f297b77a5c178`, umfasst 13,54 GB und passt
-einschließlich Laufzeit- und Aktivierungsspeicher nicht vollständig in die
-12-GB-RTX-3060:
-
-- mit 11.264 MiB Modellbudget scheiterte das Laden bei nur noch 32 MiB freiem
-  VRAM an einer weiteren 96-MiB-Allokation;
-- mit 9.216 MiB Modellbudget und CPU-Offload scheiterte die Inferenz bei nur
-  noch 78 MiB freiem VRAM an einer 136-MiB-Allokation;
-- mit 7.168 MiB Modellbudget, CPU-Offload und auf 262.144 Pixel verkleinerten
-  Referenzen lief die Inferenz, erzeugte wegen der langsamen Transformers-
-  Referenzkerne aber auch nach mehr als drei Minuten noch keinen Rewrite.
-
-Der FP8-Testcheckpoint wurde anschließend wieder entfernt. FP8 mit CPU-Offload
-ist damit kein sinnvoller Produktionspfad auf dieser 3060.
-
-### Q5 vollständig auf der RTX 3060
-
-Als funktionierender Vergleich wurde dieselbe PE-I2I-Feinabstimmung als
-`Q5_K_M`-GGUF aus
+PE-I2I stammt aus `Qwen/Qwen-Image-2.1-PE-I2I`, Revision
+`72927bc08afc99b7888ceb7d7d51a12db3700bbd`, und dem GGUF-Repository
 `prithivMLmods/Qwen-Image-2.1-PE-I2I-GGUF`, Revision
-`55b9c1a326599e142d59bcad8715d5601ccf8daa`, mit llama.cpp Build 10930
-getestet. Die Dateien liegen vorerst außerhalb von Git unter
-`/data/models/qwen-image-2.1-pe-i2i-q5-test`:
+`55b9c1a326599e142d59bcad8715d5601ccf8daa`. Die Dateien liegen unter
+`/data/models/qwen-image-2.1-pe-i2i-q5`:
 
 | Datei | SHA-256 |
 |---|---|
 | `Qwen-Image-2.1-PE-I2I.Q5_K_M.gguf` | `cb71f71fe5fe5938570d65a7c403fbcb1a9065dff9dd9a021f58aec42785b84e` |
 | `Qwen-Image-2.1-PE-I2I.mmproj-bf16.gguf` | `8dedb71dbc3092dc47de9108ad373d68a12854e2527d59bd9399601738f3bce1` |
+| `system_prompt.txt` | `e378fea686a1431581ba4c654d332ae96adad633f144ae738ec8ce9c4fd66439` |
 
-Mit vier Peter-Maffay-Referenzbildern belegte der Rewriter 7.167 MiB VRAM.
-Der erste Prefill umfasste 10.045 Tokens und lief mit 791,3 Token/s; die
-Ausgabe lief mit 45,9 Token/s. Ohne Denkbudget verbrauchte das Modell mehr als
-4.096 Ausgabetokens. Mit `thinking_budget_tokens: 2048` lieferte es nach 52,0
-Sekunden gültiges JSON mit 2.384 Ausgabetokens. Der Rewrite erkannte die vier
-Bilder als dieselbe Person und formulierte ausdrücklich eine einzelne Person,
-genau eine Gummiente und ein neues 3:4-Motiv.
+PE-T2I stammt aus `Qwen/Qwen-Image-2.1-PE-T2I`, Revision
+`f3ed7985c788ad75b3ab7223e0c4c51e2a43545b`, und dem GGUF-Repository
+`prithivMLmods/Qwen-Image-2.1-PE-T2I-GGUF`, Revision
+`e18d4a3e0830ab157770738b16830e6fcf5f57d4`. Die Dateien liegen unter
+`/data/models/qwen-image-2.1-pe-t2i-q5`:
 
-Der anschließende Ende-zu-Ende-Lauf hielt den Rewriter auf der RTX 3060 und
-Qwen-Image-2.1 auf der RTX 5080. Qwen-Image benötigte 193,18 Sekunden und
-erzeugte ein neues PNG mit 1.312 × 1.824 Pixeln, genau einer Person und genau
-einer gelben Gummiente. Das Ergebnis liegt im Router-Bildvolume als
-`qwen-pe-e2e.png`; SHA-256:
-`931cd3cf46993aee735e95c7c2447c500a498ffb600a26a96f5faab87a0260e9`.
+| Datei | SHA-256 |
+|---|---|
+| `Qwen-Image-2.1-PE-T2I.Q5_K_M.gguf` | `749f5652fd6e8b760ca860091f7a5bffa254a7954203ae5c9bcdf5f93197702f` |
+| `system_prompt.txt` | `a77c9a06c59b120741141d9514b95682bb8761d02bec49ca61def7b2b3d9fb99` |
 
-Nach dem Test wurden beide Testworker gestoppt und Medium sowie Qwen3-TTS
-wieder gesund gestartet. Der Q5-Checkpoint bleibt für die geplante
-Routerintegration liegen, ist aber noch kein automatisch gestarteter
-Produktionsdienst.
+Der zuvor geprüfte PE-I2I-FP8-Checkpoint ist 13,54 GB groß und passt mit
+Aktivierungs- und Laufzeitspeicher nicht in die 12-GB-RTX-3060. CPU-Offload war
+unpraktisch langsam. Er wurde verworfen und entfernt. Der Q5-I2I-Worker belegt
+etwa 7.167 MiB VRAM und ist deshalb der produktive Stand.
+
+### Abnahme vom 21. September 2026
+
+Der vollständige öffentliche Routerweg wurde nach der Integration zweimal
+geprüft:
+
+- Ein kurzer deutscher Textprompt wurde von PE-T2I in 36,6 Sekunden in einen
+  strukturierten englischen Produktionsprompt umgeschrieben. Qwen-Image
+  erzeugte das 1024×1024-PNG anschließend in 49,0 Sekunden.
+- Ein hochgeladenes Referenzbild wurde von PE-I2I in 65,9 Sekunden aufbereitet.
+  Der Rewrite verlangte ausdrücklich eine neue Szene, neue Pose und Kleidung
+  sowie das Entfernen der alten Gegenstände. Qwen-Image erzeugte in 111,3
+  Sekunden ein neues 1024×1536-PNG: genau eine Person in einer Blumenwiese an
+  einer Autobahn, ohne Badewanne, Gitarre oder Gummiente.
+
+Nach beiden Aufträgen waren der Bildworker und beide Enhancer gestoppt. Medium
+und Qwen3-TTS liefen wieder gesund. Der erste I2I-Versuch deckte eine relative
+Pfadauflösung bei temporären Multipart-Uploads auf; der korrigierte Pfad ist mit
+einem eigenen Regressionstest abgedeckt. Insgesamt laufen 96 schnelle
+GPU-freie Release-Tests.

docs/RECOVERY.md

@@ -23,6 +23,10 @@ Backup-Mounts. Ein Backup ausschließlich auf `/data` schützt nicht vor deren A
 Das gilt auch für das reproduzierbare EmbeddingGemma-Gewicht unter
 `/data/models/embeddinggemma`; URL und SHA-256 stehen in
 `config/install.env.example`, sodass der Installer es erneut laden und prüfen kann.
+Auch die Qwen-Image-Gewichte und beide Prompt-Enhancer liegen unter
+`/data/models` und damit außerhalb des regulären Volume-Backups. Das Skript
+`scripts/prepare-qwen-image-21.sh` lädt sämtliche gepinnten Dateien anhand
+fester SHA-256-Prüfsummen erneut und legt Bildworker sowie Enhancer gestoppt an.
 
 Die verschlüsselten Notfallpakete über `athena-export-backup.timer` laufen
 ebenfalls im Fünf-Stunden-Takt; beim Abgleich war der Timer aktiv und der

docs/TESTED_MODELS.md

@@ -1,6 +1,6 @@
 # Register getesteter Modelle
 
-Stand: 20. September 2026
+Stand: 21. September 2026
 
 Dieses Dokument ist die zentrale Sperrliste gegen doppelte Modelltests. Vor
 jedem Download müssen Repository, Dateiname, Basismodell, Fine-Tune und
@@ -55,7 +55,8 @@ Titelgenerierung und Kontextkompression in Hermes.
 | bis 07.09.2026 | FLUX.2 Klein 4B | funktional, aber schwächere räumliche und motivische Konsistenz | **ersetzt** durch 9B FP8 | [FLUX_9B_BETA.md](FLUX_9B_BETA.md) |
 | 07.09.2026 | FLUX.2 Klein 9B FP8 | bessere Prompttreue als 4B; produktiver Zwei-GPU-Pfad, auf 1024 × 1024 begrenzt | **Standby seit 21.09.2026** | [FLUX_9B_BETA.md](FLUX_9B_BETA.md) |
 | 21.09.2026 | Qwen-Image-2.1 INT8 | im direkten Vergleich fotorealistischer, bessere Textdarstellung und Prompttreue; 1024 × 1024 bei 25 Schritten in rund 49 s Pipeline-Lauf | **produktiv** | [QWEN_IMAGE_21.md](QWEN_IMAGE_21.md) |
-| 21.09.2026 | Qwen-Image-2.1 PE-I2I, FP8 und Q5_K_M | FP8 passt nicht vollständig in 12 GB und ist mit CPU-Offload unpraktisch langsam; Q5_K_M samt BF16-MMProj belegt 7.167 MiB auf der RTX 3060 und erzeugt mit 2.048 Denktokens in 52,0 s einen gültigen Mehrbild-Rewrite | **Vorabtest bestanden, noch nicht produktiv verdrahtet** | [QWEN_IMAGE_21.md](QWEN_IMAGE_21.md#offizieller-prompt-enhancer-vorabtest-vom-21-september-2026) |
+| 21.09.2026 | Qwen-Image-2.1 PE-I2I, FP8 und Q5_K_M | FP8 passt nicht vollständig in 12 GB und ist mit CPU-Offload unpraktisch langsam; Q5_K_M samt BF16-MMProj belegt 7.167 MiB auf der RTX 3060. Der produktive Router-Rewrite mit einem Referenzbild dauerte 65,9 s und führte zu einer vollständig neuen Szene | **Q5_K_M produktiv**, FP8 verworfen | [QWEN_IMAGE_21.md](QWEN_IMAGE_21.md#offizielle-prompt-enhancer-im-produktiven-router) |
+| 21.09.2026 | Qwen-Image-2.1 PE-T2I Q5_K_M | automatischer Rewrite eines knappen deutschen Textprompts in 36,6 s; nachfolgende Bildgenerierung erfolgreich | **produktiv** für Text-zu-Bild | [QWEN_IMAGE_21.md](QWEN_IMAGE_21.md#offizielle-prompt-enhancer-im-produktiven-router) |
 | 08.09.2026 | HYPIR-SD2 | glättete oder erfand Details und veränderte kleine Strukturen | **verworfen** | [IMAGE_RESTORATION.md](IMAGE_RESTORATION.md) |
 | 08.09.2026 | SeedVR2 7B FP8 | bewahrte Identität besser als HYPIR, brachte beim realen unscharfen Foto aber kaum nutzbare Details zurück | **verworfen** | [IMAGE_RESTORATION.md](IMAGE_RESTORATION.md) |