diff --git a/COMMAND_REF.md b/COMMAND_REF.md
index 2744d29..d2f9722 100644
--- a/COMMAND_REF.md
+++ b/COMMAND_REF.md
@@ -1,449 +1,646 @@
-# RetrieX – CLI Command Reference
+# RetrieX v1.6.0 – CLI Command Reference
 
-**Basis:** `rag.zip` (aktueller Code-Stand vom 2026-04-15)  
-**Scope:** ausschließlich projektspezifische Symfony-Commands unter `src/Command`  
-**Namespace-Konvention:** `mto:agent:*`
+Basis: aktueller `rag-inprogress.zip`-Stand der Version **1.6.0**.  
+Scope: projektspezifische Symfony-Commands unter `src/Command`.  
+Namespace-Konvention: `mto:agent:*`.
 
-Diese Referenz ist gegen den realen Codebestand abgeglichen und ersetzt die veraltete Fassung der bisherigen `COMMAND_REF.md`.
+Diese Referenz ist gegen die real vorhandenen Command-Klassen im Paket abgeglichen.
 
 ---
 
 ## 1. Überblick
 
 | Command | Bereich | Kurzbeschreibung |
-|---|---|---|
-| `mto:agent:chat` | Agent / CLI | Interaktiver Terminal-Chat gegen den AgentRunner |
-| `mto:agent:ingest:version` | Ingest | Startet einen Ingest für eine konkrete Dokumentversion |
+| --- | --- | --- |
+| `mto:agent:chat` | Agent / CLI | Interaktiver Terminal-Chat gegen den `AgentRunner` |
+| `mto:agent:eval:run` | Evaluation | Führt versionierte Eval-Cases aus |
+| `mto:agent:ingest:version` | Ingest | Startet den Ingest für eine konkrete Dokumentversion |
 | `mto:agent:ingest:run` | Ingest Jobs | Führt einen vorhandenen `IngestJob` aus |
-| `mto:agent:system:rebuild` | System | Globaler Hard-Rebuild von Chunks, Vektorindex, Tags und optional Service-Reload |
+| `mto:agent:system:rebuild` | System | Globaler Hard-Rebuild von Knowledge-, Vector- und optional Tag-Artefakten |
+| `mto:agent:vector:rebuild` | Vector | Baut den Chunk-Vektorindex aus `index.ndjson` neu |
+| `mto:agent:vector:control` | Vector Service | Install, Start, Stop, Reload und Status des Python-Vector-Service |
+| `mto:agent:vector:health` | Vector | Konsistenzcheck für Chunk-NDJSON und Vektorindex |
+| `mto:agent:test-vector` | Debug | Testet Tag- und Chunk-Vector-Clients direkt |
+| `mto:agent:retrieval:test` | Retrieval Debug | Testet den realen hybriden Retrieval-Pfad mit Debugausgabe |
+| `mto:agent:tags:export` | Tags | Exportiert Tags nach `tags.ndjson` |
+| `mto:agent:tags:rebuild` | Tags | Exportiert Tags und baut `vector_tags.index` neu |
+| `mto:agent:tags:job:run` | Tag Jobs | Führt einen vorhandenen Tag-Rebuild-Job aus oder erstellt direkt einen neuen |
+| `mto:agent:tag:health` | Tags | Konsistenzcheck für Tag-NDJSON und Tag-Vektorindex |
+| `mto:agent:test:shop-search` | Commerce / Debug | Testkommando für Shopware-Suche und optional Search Repair |
+| `mto:agent:user:create` | User | Interaktive Anlage eines Users |
 | `mto:agent:config:validate` | Config / Governance | Validiert die effektive RetrieX-Konfiguration |
 | `mto:agent:config:audit-source` | Config / Governance | Auditiert YAML-Mappings gegen PHP-Fallbacks und Defaults |
 | `mto:agent:config:audit-patterns` | Config / Governance | Auditiert fachliche Pattern-, Token- und Signalreste im PHP-Core |
 | `mto:agent:config:dump-effective` | Config / Governance | Gibt die effektive Konfigurationsinventur aus |
-| `mto:agent:regression:test` | Config / Governance | Fuehrt Offline-Regression-Guards fuer stabile Pfade aus |
-| `mto:agent:vector:rebuild` | Vector | Baut den Chunk-Vektorindex aus `index.ndjson` neu |
-| `mto:agent:vector:control` | Vector Service | Install, Start, Stop, Reload und Status des Python-Vector-Service |
-| `mto:agent:vector:health` | Vector | Konsistenzcheck für Chunk-NDJSON und Vektorindex |
-| `mto:agent:test-vector` | Debug | Führt Tag-Routing und Chunk-Retrieval für einen Testprompt aus |
-| `mto:agent:tags:export` | Tags | Exportiert Tags nach `tags.ndjson` |
-| `mto:agent:tags:rebuild` | Tags | Exportiert Tags und baut `vector_tags.index` neu |
-| `mto:agent:tags:job:run` | Tag Jobs | Führt einen vorhandenen Tag-Rebuild-Job aus oder erstellt direkt einen neuen |
-| `mto:agent:tag:health` | Tags | Konsistenzcheck für `tags.ndjson` und Tag-Vektorindex |
-| `mto:agent:test:shop-search` | Commerce / Debug | Testkommando für die Shopware-Suche |
-| `mto:agent:user:create` | User | Interaktive Anlage eines Users |
+| `mto:agent:regression:test` | Config / Governance | Führt Offline-Regression-Guards für stabile Pfade aus |
 
 ---
 
 ## 2. Agent / Chat
 
 ### `mto:agent:chat`
+
 Interaktiver CLI-Chat mit dem Agenten.
 
 **Signatur**
+
 ```bash
-bin/console mto:agent:chat [user-id]
+php bin/console mto:agent:chat [user-id]
 ```
 
 **Argumente**
-- `user-id` optional, Default: `cli`
 
-**Reales Verhalten im Code**
+- `user-id` optional, Default `cli`
+
+**Reales Verhalten**
+
 - startet eine Terminal-Schleife mit `Question` → `Answer`
 - ruft pro Eingabe `AgentRunner->run($prompt, $userId)` auf
 - streamt Tokens direkt ins Terminal
 - beendet sich bei EOF, leerer Eingabe oder `exit`
 
-**Beispiel**
+**Beispiele**
+
 ```bash
-bin/console mto:agent:chat
-bin/console mto:agent:chat admin-debug
+php bin/console mto:agent:chat
+php bin/console mto:agent:chat cli-debug
 ```
 
 ---
 
-## 3. Ingest / Jobs
+## 3. Evaluation
+
+### `mto:agent:eval:run`
+
+Führt versionierte Eval-Cases aus.
+
+**Signatur**
+
+```bash
+php bin/console mto:agent:eval:run [type] [--case=CASE_ID] [--json] [--no-write]
+```
+
+**Argumente / Optionen**
+
+- `type` optional, Default `retrieval`
+- `--case=CASE_ID` führt nur einen einzelnen Case aus
+- `--json` gibt den vollständigen Report als JSON aus
+- `--no-write` verhindert das Schreiben des Report-Files
+
+**Reales Verhalten**
+
+- lädt Cases über `EvalCaseLoader`
+- filtert optional auf eine Case-ID
+- führt Cases über `AgentEvalRunner` aus
+- schreibt standardmäßig einen Report über `EvalReportWriter`
+- Exit-Code ist fehlerhaft, wenn mindestens ein Case fehlschlägt
+
+**Beispiele**
+
+```bash
+php bin/console mto:agent:eval:run
+php bin/console mto:agent:eval:run retrieval --case=water-hardness-lowest
+php bin/console mto:agent:eval:run retrieval --json --no-write
+```
+
+---
+
+## 4. Ingest / Jobs
 
 ### `mto:agent:ingest:version`
+
 Startet einen Ingest für eine konkrete `DocumentVersion` mit explizitem Benutzerkontext.
 
 **Signatur**
+
 ```bash
-bin/console mto:agent:ingest:version <versionId> <userId>
+php bin/console mto:agent:ingest:version <versionId> <userId>
 ```
 
 **Argumente**
+
 - `versionId` erforderlich, UUID einer `DocumentVersion`
 - `userId` erforderlich, UUID des auslösenden Users
 
-**Reales Verhalten im Code**
+**Reales Verhalten**
+
 - lädt `DocumentVersion` und `User` aus Doctrine
-- bricht mit Fehler ab, wenn Version oder User nicht existieren
+- bricht ab, wenn Version oder User nicht existieren
 - ruft `IngestOrchestrator->runForVersion($version, $user)` auf
 - gibt nach Abschluss die erzeugte Job-ID aus
 
 **Beispiel**
+
 ```bash
-bin/console mto:agent:ingest:version <documentVersionUuid> <userUuid>
+php bin/console mto:agent:ingest:version <documentVersionUuid> <userUuid>
 ```
 
-**Wichtige Korrektur zur alten Doku**
-Die bisherige Referenz dokumentierte nur einen Parameter. Im aktuellen Code sind **zwei Pflichtargumente** erforderlich.
-
----
-
 ### `mto:agent:ingest:run`
+
 Führt einen bereits existierenden `IngestJob` aus.
 
 **Signatur**
+
 ```bash
-bin/console mto:agent:ingest:run <jobId> [--dry-run]
+php bin/console mto:agent:ingest:run <jobId> [--dry-run]
 ```
 
 **Argumente / Optionen**
-- `jobId` erforderlich, UUID eines `IngestJob`
-- `--dry-run` optional, simuliert schwere Operationen ohne tatsächliche Ausführung
 
-**Reales Verhalten im Code**
+- `jobId` erforderlich, UUID eines `IngestJob`
+- `--dry-run` simuliert schwere Operationen ohne tatsächliche Ausführung
+
+**Reales Verhalten**
+
 - lädt den Job aus der Datenbank
-- bricht mit Fehler ab, wenn der Job nicht gefunden wird
 - beendet sich erfolgreich, wenn der Job bereits terminal ist (`COMPLETED`, `FAILED`, `ABORTED`)
 - ruft sonst `IngestOrchestrator->runExistingJob($job, $dryRun)` auf
 
 **Beispiele**
+
 ```bash
-bin/console mto:agent:ingest:run <jobUuid>
-bin/console mto:agent:ingest:run <jobUuid> --dry-run
+php bin/console mto:agent:ingest:run <jobUuid>
+php bin/console mto:agent:ingest:run <jobUuid> --dry-run
 ```
 
----
-
 ### `mto:agent:system:rebuild`
+
 Globaler Hard-Rebuild des Systems.
 
 **Signatur**
+
 ```bash
-bin/console mto:agent:system:rebuild --hard [--no-tags] [--no-reload] [--no-health] [--dry-run]
+php bin/console mto:agent:system:rebuild --hard [--no-tags] [--no-reload] [--no-health] [--dry-run]
 ```
 
 **Optionen**
-- `--hard` **Pflicht-Sicherheitsschalter**; ohne diese Option bricht das Kommando ab
-- `--no-tags` überspringt den Tag-Rebuild
-- `--no-reload` überspringt Reload/Start des Vector-Service
-- `--no-health` überspringt den abschließenden Health-Check
-- `--dry-run` simuliert den Reindex ohne Schreiboperationen
 
-**Reales Verhalten im Code**
-1. erzeugt einen neuen `IngestJob` vom Typ `GLOBAL_REINDEX`
+- `--hard` Pflicht-Sicherheitsschalter; ohne diese Option bricht das Kommando ab
+- `--no-tags` überspringt Tag-Rebuild
+- `--no-reload` überspringt Reload/Start des Vector-Service
+- `--no-health` überspringt abschließende Health-Checks
+- `--dry-run` simuliert Schritte ohne Schreiboperationen
+
+**Reales Verhalten**
+
+1. erzeugt einen globalen Reindex-Job
 2. führt den globalen Reindex über den Orchestrator aus
-3. exportiert optional `tags.ndjson` und baut `vector_tags.index` neu
-4. startet bzw. reloadet optional den Python-Vector-Service
+3. exportiert optional Tags und baut `vector_tags.index` neu
+4. startet oder reloadet optional den Python-Vector-Service
 5. führt optional Chunk- und Tag-Health-Checks aus
 
 **Beispiele**
-```bash
-bin/console mto:agent:system:rebuild --hard
-bin/console mto:agent:system:rebuild --hard --dry-run
-bin/console mto:agent:system:rebuild --hard --no-tags --no-reload
-```
 
-**Hinweis**
-Dieses Kommando ist aktuell der zentrale Produktions-Entry-Point für einen vollständigen Neuaufbau des Retrieval-Stacks.
+```bash
+php bin/console mto:agent:system:rebuild --hard
+php bin/console mto:agent:system:rebuild --hard --dry-run
+php bin/console mto:agent:system:rebuild --hard --no-tags --no-reload
+```
 
 ---
 
-## 4. Vector / Retrieval
+## 5. Vector / Retrieval
 
 ### `mto:agent:vector:rebuild`
-Baut den Chunk-Vektorindex neu.
+
+Baut den Chunk-Vektorindex aus `index.ndjson` neu.
 
 **Signatur**
+
 ```bash
-bin/console mto:agent:vector:rebuild
+php bin/console mto:agent:vector:rebuild
 ```
 
-**Reales Verhalten im Code**
+**Reales Verhalten**
+
 - schreibt `Rebuilding vector index...`
 - ruft `VectorIndexBuilder->rebuildFromNdjson()` auf
 - schreibt anschließend `Done.`
 
-**Beispiel**
-```bash
-bin/console mto:agent:vector:rebuild
-```
-
----
-
 ### `mto:agent:vector:control`
+
 Steuert den persistenten Python-Vector-Service über `python/vector/vector_control.py`.
 
 **Signatur**
+
 ```bash
-bin/console mto:agent:vector:control [optionen]
+php bin/console mto:agent:vector:control [--install] [--start] [--stop] [--force] [--reload] [--status] [--foreground] [--port=8090] [--host=0.0.0.0]
 ```
 
-**Unterstützte Optionen**
-- `--install` installiert fehlende Python-Dependencies in `.venv`
+**Optionen**
+
+- `--install` installiert fehlende Python-Abhängigkeiten in `.venv`
 - `--start` startet den Service, falls er nicht läuft
 - `--stop` stoppt den Service anhand der PID-Datei
 - `--force` erzwingt einen Hard-Stop
-- `--reload` triggert den `/reload`-Endpoint des Service
+- `--reload` triggert den `/reload`-Endpoint
 - `--status` gibt den aktuellen Status aus
 - `--foreground` startet im Vordergrund
-- `--port=8090` setzt den Port
-- `--host=0.0.0.0` setzt den Host
-
-**Reales Verhalten im Code**
-- baut einen Prozessaufruf gegen `.venv/bin/python python/vector/vector_control.py`
-- reicht gesetzte Optionen durch
-- hängt immer `--port` und `--host` an
-- gibt `stdout` des Python-Skripts direkt aus
+- `--port` setzt den Port, Default `8090`
+- `--host` setzt den Host, Default `0.0.0.0`
 
 **Beispiele**
+
 ```bash
-bin/console mto:agent:vector:control --install
-bin/console mto:agent:vector:control --start
-bin/console mto:agent:vector:control --status
-bin/console mto:agent:vector:control --reload
-bin/console mto:agent:vector:control --stop --force
+php bin/console mto:agent:vector:control --install
+php bin/console mto:agent:vector:control --start
+php bin/console mto:agent:vector:control --status
+php bin/console mto:agent:vector:control --reload
+php bin/console mto:agent:vector:control --stop --force
 ```
 
----
-
 ### `mto:agent:vector:health`
+
 Health-Check für Chunk-NDJSON und Chunk-Vektorindex.
 
 **Signatur**
+
 ```bash
-bin/console mto:agent:vector:health
+php bin/console mto:agent:vector:health
 ```
 
-**Reales Verhalten im Code**
+**Reales Verhalten**
+
 - ruft `VectorIndexHealthService->check()` auf
-- gibt den Report als JSON aus
-- endet mit Exit-Code `0`, wenn `status` mit `OK` beginnt; sonst `1`
-
-**Beispiel**
-```bash
-bin/console mto:agent:vector:health
-```
-
----
+- gibt JSON aus
+- Exit-Code `0`, wenn `status` mit `OK` beginnt; sonst `1`
 
 ### `mto:agent:test-vector`
-Debug-Kommando für einen realistischen Retrieval-Test.
+
+Debug-Kommando für Tag- und Chunk-Vector-Clients.
 
 **Signatur**
+
 ```bash
-bin/console mto:agent:test-vector <prompt>
+php bin/console mto:agent:test-vector <prompt>
 ```
 
 **Argumente**
-- `prompt` erforderlich, Testanfrage für das Retrieval
 
-**Reales Verhalten im Code**
-- führt zuerst Tag-Routing über `TagVectorSearchClient` aus
-- führt danach Chunk-Retrieval über `VectorSearchClient` aus
+- `prompt` erforderlich
+
+**Reales Verhalten**
+
+- führt Tag-Routing über `TagVectorSearchClient` aus
+- führt Chunk-Retrieval über `VectorSearchClient` aus
 - misst Tag-, Chunk- und Gesamtdauer
 - gibt beide Result-Sets als JSON aus
 
 **Beispiel**
+
 ```bash
-bin/console mto:agent:test-vector "welche dokumente behandeln den ingest-flow?"
+php bin/console mto:agent:test-vector "welche dokumente behandeln den ingest-flow?"
+```
+
+### `mto:agent:retrieval:test`
+
+Testet den realen hybriden Retrieval-Pfad mit Debugausgabe.
+
+**Signatur**
+
+```bash
+php bin/console mto:agent:retrieval:test <prompt> [--json] [--show-text]
+```
+
+**Argumente / Optionen**
+
+- `prompt` erforderlich
+- `--json` gibt das rohe Debugresultat als JSON aus
+- `--show-text` zeigt vollständige Chunktexte statt gekürzter Vorschau
+
+**Reales Verhalten**
+
+- ruft `NdjsonHybridRetriever->retrieveDebug($prompt)` auf
+- zeigt Pipeline Summary, Scope Candidates, Hit Counts, Boosts und ausgewählte Chunks
+- bricht bei leerem Prompt oder Retrieval-Exception mit Fehler ab
+
+**Beispiele**
+
+```bash
+php bin/console mto:agent:retrieval:test "niedrigster Grenzwert Wasserhärte"
+php bin/console mto:agent:retrieval:test "Testomat 808 SIO2" --json
+php bin/console mto:agent:retrieval:test "Indikatortyp 300" --show-text
 ```
 
 ---
 
-## 5. Tag-System
+## 6. Tag-System
 
 ### `mto:agent:tags:export`
+
 Exportiert die Tag-Datenbasis nach `tags.ndjson`.
 
 **Signatur**
+
 ```bash
-bin/console mto:agent:tags:export
+php bin/console mto:agent:tags:export
 ```
 
-**Reales Verhalten im Code**
+**Reales Verhalten**
+
 - ruft `TagNdjsonExporter->export()` auf
 - gibt Pfad, Tag-Anzahl, Zeilen und Bytes aus
 
-**Beispiel**
-```bash
-bin/console mto:agent:tags:export
-```
-
----
-
 ### `mto:agent:tags:rebuild`
+
 Kompletter Neuaufbau des Tag-Retrievals.
 
 **Signatur**
+
 ```bash
-bin/console mto:agent:tags:rebuild
+php bin/console mto:agent:tags:rebuild
 ```
 
-**Reales Verhalten im Code**
+**Reales Verhalten**
+
 1. exportiert `tags.ndjson`
 2. baut `vector_tags.index`
 3. setzt einen Runtime-Marker über `IndexMetaManager->touchRuntime()`
 
-**Beispiel**
-```bash
-bin/console mto:agent:tags:rebuild
-```
-
----
-
 ### `mto:agent:tags:job:run`
+
 Führt einen Tag-Rebuild-Job mit File-Lock aus.
 
 **Signatur**
+
 ```bash
-bin/console mto:agent:tags:job:run [jobId] [--create]
+php bin/console mto:agent:tags:job:run [jobId] [--create]
 ```
 
 **Argumente / Optionen**
-- `jobId` optional, UUID eines bestehenden `TagRebuildJob`
-- `--create` optional, erstellt und startet sofort einen neuen `TagRebuildJob`
 
-**Regeln im Code**
-- entweder `jobId` **oder** `--create`
+- `jobId` optional, UUID eines bestehenden `TagRebuildJob`
+- `--create` erstellt und startet sofort einen neuen `TagRebuildJob`
+
+**Regeln**
+
+- entweder `jobId` oder `--create`
 - beides zusammen ist ungültig
 - keines von beiden ist ebenfalls ungültig
 
-**Reales Verhalten im Code**
-- markiert den Job auf `RUNNING`
-- sperrt parallel laufende Tag-Rebuilds per File-Lock
-- exportiert `tags.ndjson`
-- baut `vector_tags.index`
-- markiert den Job bei Erfolg als `COMPLETED`, sonst als `FAILED`
-
 **Beispiele**
+
 ```bash
-bin/console mto:agent:tags:job:run --create
-bin/console mto:agent:tags:job:run <jobUuid>
+php bin/console mto:agent:tags:job:run --create
+php bin/console mto:agent:tags:job:run <jobUuid>
 ```
 
----
-
 ### `mto:agent:tag:health`
+
 Health-Check für das Tag-Retrieval.
 
 **Signatur**
+
 ```bash
-bin/console mto:agent:tag:health
+php bin/console mto:agent:tag:health [--summary]
 ```
 
-**Reales Verhalten im Code**
+**Optionen**
+
+- `--summary` gibt eine lesbare Zusammenfassung statt JSON aus
+
+**Reales Verhalten**
+
 - ruft `TagVectorIndexHealthService->check()` auf
-- gibt den Report als JSON aus
-- endet mit Exit-Code `0`, wenn `status` mit `OK` beginnt; sonst `1`
+- gibt JSON oder Summary aus
+- Exit-Code `0`, wenn der Status als gesund gilt; sonst `1`
+
+**Beispiele**
 
-**Beispiel**
 ```bash
-bin/console mto:agent:tag:health
+php bin/console mto:agent:tag:health
+php bin/console mto:agent:tag:health --summary
 ```
 
-**Wichtige Korrektur zur alten Doku**
-Der reale Command-Name ist **`tag:health` (Singular)**, nicht `tags:health`.
+Wichtig: Der reale Command-Name ist `tag:health` im Singular.
 
 ---
 
-## 6. Commerce / Shopware Debug
+## 7. Commerce / Shopware Debug
 
 ### `mto:agent:test:shop-search`
-Testkommando für die Shopware-Suche.
+
+Testkommando für Shopware-Suche und optionalen Search-Repair-Test.
 
 **Signatur**
+
 ```bash
-bin/console mto:agent:test:shop-search [query]
+php bin/console mto:agent:test:shop-search [query] [--intent=INTENT] [--history=TEXT] [--repair]
 ```
 
-**Argumente**
-- `query` optional
-- Default im Code: `zeige mir testomat modelle wasserhärte unter 5000 euro`
+**Argumente / Optionen**
 
-**Beabsichtigtes Verhalten**
-- ruft die Shop-Suche auf
-- gibt pro Treffer Produktdaten wie ID, Produktnummer, Hersteller, Preis, Verfügbarkeit, URL und Description aus
+- `query` optional, Default `zeige mir testomat modelle wasserhärte unter 5000 euro`
+- `--intent` optional, Default `CommerceIntentLite::ADVISORY_PRODUCT_SEARCH`
+- `--history` optionaler Commerce-History-Kontext
+- `--repair` aktiviert zusätzlich die Search-Repair-Auswertung
 
-**Wichtiger Code-Hinweis**
-Im aktuellen Stand von `rag.zip` ruft das Command `ShopSearchService->search($query)` mit **einem** Argument auf, die Service-Signatur erwartet aber **zwei** Argumente (`string $originalPrompt, string $commerceIntent`). Das Kommando ist daher im aktuellen Codebestand sehr wahrscheinlich **nicht lauffähig**, solange diese Signaturabweichung nicht behoben wird.
+**Reales Verhalten**
+
+- ruft `ShopSearchService->search($query, $intent, $history)` auf
+- gibt Treffer mit ID, Produktnummer, Hersteller, Preis, Verfügbarkeit, URL, Description und Highlights aus
+- bei `--repair` werden Knowledge-Chunks geholt und `SearchRepairService->repair(...)` ausgeführt
+- zeigt dann verwendete Repair-Queries und finale gemergte Ergebnisse
+
+**Beispiele**
+
+```bash
+php bin/console mto:agent:test:shop-search "testomat 808 300 indikator"
+php bin/console mto:agent:test:shop-search "testomat 808 300 indikator" --repair
+php bin/console mto:agent:test:shop-search "testomat lab cl" --intent=advisory_product_search
+php bin/console mto:agent:test:shop-search "was kostet der indikator" --history="Testomat 808 Indikatortyp 300"
+```
 
 ---
 
-## 7. User-Management
+## 8. User-Management
 
 ### `mto:agent:user:create`
+
 Interaktive Anlage eines Users.
 
 **Signatur**
+
 ```bash
-bin/console mto:agent:user:create
+php bin/console mto:agent:user:create
 ```
 
 **Interaktiver Ablauf**
+
 1. E-Mail eingeben
 2. Passwort eingeben
-3. Rolle wählen
+3. Passwort wiederholen
+4. eine oder mehrere Rollen wählen
+5. Aktivstatus bestätigen
+
+**Validierungen**
 
-**Validierungen im Code**
 - E-Mail muss valide sein
-- User mit gleicher E-Mail darf nicht bereits existieren
+- E-Mail darf noch nicht existieren
 - Passwort muss mindestens 8 Zeichen lang sein
+- Passwortwiederholung muss übereinstimmen
+- mindestens eine Rolle muss gewählt werden
+
+**Zuweisbare Rollen**
 
-**Im Code auswählbare Rollen**
 - `ROLE_SUPER_ADMIN`
 - `ROLE_KNOWLEDGE_ADMIN`
 - `ROLE_EDITOR`
-- `ROLE_USER`
+- `ROLE_ADMIN_AREA`
+- `ROLE_CHAT_USER`
 
-**Beispiel**
-```bash
-bin/console mto:agent:user:create
-```
+`ROLE_USER` wird als technische Basisrolle über die Hierarchie genutzt, ist aber nicht als fachliche Zielrolle in der Auswahl vorgesehen.
 
 ---
 
-## 8. Typische Betriebsabläufe
+## 9. Config / Governance
+
+### `mto:agent:config:validate`
+
+Validiert die effektive RetrieX-Konfiguration.
+
+**Signatur**
+
+```bash
+php bin/console mto:agent:config:validate [--json]
+```
+
+**Erwartung vor Merge/Deployment**
+
+- Status `OK`
+- keine Errors
+
+### `mto:agent:config:audit-source`
+
+Auditiert YAML-backed Configuration gegen PHP-Defaults, Fallback-Accessors und Constructor-Defaults.
+
+**Signatur**
+
+```bash
+php bin/console mto:agent:config:audit-source [--details] [--json]
+```
+
+**Optionen**
+
+- `--details` zeigt reviewbare Detailzeilen
+- `--json` gibt maschinenlesbares JSON aus
+
+### `mto:agent:config:audit-patterns`
+
+Auditiert verbleibende Pattern-, Token- und Signalnutzung im PHP-Core.
+
+**Signatur**
+
+```bash
+php bin/console mto:agent:config:audit-patterns [--details] [--json] [--all]
+```
+
+**Zweck**
+
+- findet konfigurierte Calls wie `preg_match`, `str_contains`, `in_array` usw.
+- markiert WARN-Funde bei Domain-Marker-Terms
+- bleibt revieworientiert und nicht selbst runtime-verändernd
+
+**Beispiel**
+
+```bash
+php bin/console mto:agent:config:audit-patterns --details
+```
+
+### `mto:agent:config:dump-effective`
+
+Gibt die effektive RetrieX-Konfigurationsinventur aus.
+
+**Signatur**
+
+```bash
+php bin/console mto:agent:config:dump-effective [--summary]
+```
+
+**Beispiele**
+
+```bash
+php bin/console mto:agent:config:dump-effective
+php bin/console mto:agent:config:dump-effective --summary
+```
+
+### `mto:agent:regression:test`
+
+Führt Offline-Regression-Guards für stabile Pfade aus.
+
+**Signatur**
+
+```bash
+php bin/console mto:agent:regression:test [--json]
+```
+
+**Zweck**
+
+- schützt regressionsempfindliche 1.4.x/1.5.x/1.6.0-Flows
+- prüft Konfigurationspfade, Tokens und Guardrail-Erwartungen
+- ist Pflichtcheck für Änderungen an YAML-, Prompt-, Retrieval-, Commerce- oder Agent-Logik
+
+---
+
+## 10. Typische Betriebsabläufe
 
 ### Manueller Ingest einer Version
+
 ```bash
-bin/console mto:agent:ingest:version <documentVersionUuid> <userUuid>
+php bin/console mto:agent:ingest:version <documentVersionUuid> <userUuid>
 ```
 
 ### Vorhandenen Ingest-Job ausführen
+
 ```bash
-bin/console mto:agent:ingest:run <jobUuid>
+php bin/console mto:agent:ingest:run <jobUuid>
 ```
 
 ### Nur Chunk-Vektorindex neu bauen
+
 ```bash
-bin/console mto:agent:vector:rebuild
+php bin/console mto:agent:vector:rebuild
 ```
 
 ### Gesamtsystem hart neu aufbauen
+
 ```bash
-bin/console mto:agent:system:rebuild --hard
+php bin/console mto:agent:system:rebuild --hard
 ```
 
 ### Vector-Service prüfen und reloaden
+
 ```bash
-bin/console mto:agent:vector:health
-bin/console mto:agent:vector:control --reload
+php bin/console mto:agent:vector:health
+php bin/console mto:agent:vector:control --status
+php bin/console mto:agent:vector:control --reload
 ```
 
 ### Tag-Retrieval neu aufbauen
+
 ```bash
-bin/console mto:agent:tags:rebuild
-bin/console mto:agent:tag:health
+php bin/console mto:agent:tags:rebuild
+php bin/console mto:agent:tag:health --summary
+```
+
+### Shopquery mit Repair testen
+
+```bash
+php bin/console mto:agent:test:shop-search "testomat 808 300 indikator" --repair
+```
+
+### Config-Änderung prüfen
+
+```bash
+php bin/console mto:agent:config:validate
+php bin/console mto:agent:config:audit-source --details
+php bin/console mto:agent:config:audit-patterns --details
+php bin/console mto:agent:regression:test
 ```
 
 ---
 
-## 9. Wichtige Runtime-Dateien und Pfade
-
-Die bisherige Doku nannte teilweise veraltete Pfade unter `var/`. Im aktuellen Code liegen die Knowledge-Artefakte primär unter `var/knowledge/`.
+## 11. Wichtige Runtime-Dateien und Pfade
 
 ```text
 var/
@@ -458,128 +655,52 @@ var/
 │   ├── vector_tags.index.meta.json
 │   ├── uploads/
 │   └── locks/
-│       └── tag_rebuild.lock
 ├── run/
 │   └── vector_service.pid
 └── locks/
     └── ingest.lock
 ```
 
-**Herkunft im Code**
-- `config/services.yaml` definiert `mto.knowledge.root = %mto.root%/var/knowledge`
-- `python/vector/vector_control.py` verwendet `var/run/vector_service.pid`
-- `App\Service\LockService` verwendet aktuell `var/locks/ingest.lock`
+Herkunft im Code:
+
+- `config/services.yaml` bindet `mto.knowledge.*` an `retriex.knowledge.*`.
+- `python/vector/vector_control.py` verwendet `var/run/vector_service.pid`.
+- `App\Service\LockService` verwendet `var/locks/ingest.lock`.
 
 ---
 
-## 10. Wichtige Abweichungen zur alten `COMMAND_REF.md`
+## 12. Wichtige Korrekturen gegenüber älteren Referenzen
 
-Die bisherige Datei war in mehreren Punkten nicht mehr codekonform. Wesentliche Korrekturen:
-
-1. `mto:agent:system:rebuild` fehlte vollständig
-2. `mto:agent:test:shop-search` fehlte vollständig
-3. `mto:agent:tag:health` fehlte und war zudem leicht falsch benannt
-4. `mto:agent:ingest:version` braucht aktuell **`<versionId> <userId>`**
-5. Runtime-Dateien liegen nicht nur unter `var/`, sondern überwiegend unter `var/knowledge/`
-6. der globale Rebuild läuft heute über `mto:agent:system:rebuild --hard`, nicht über ein dokumentiertes `ingest:global`
+1. Der aktuelle Stand enthält **21** projektspezifische Commands, nicht nur die älteren 18.
+2. `mto:agent:eval:run` ist Teil des aktuellen Command-Sets.
+3. `mto:agent:retrieval:test` testet den realen hybriden Retrieval-Pfad und ergänzt `mto:agent:test-vector`.
+4. `mto:agent:test:shop-search` ist im aktuellen Stand mit `query`, `--intent`, `--history` und `--repair` codekonform dokumentiert.
+5. `mto:agent:tag:health` unterstützt `--summary`.
+6. `mto:agent:user:create` kann mehrere Rollen auswählen und fragt Aktivstatus ab.
+7. Zuweisbare Rollen umfassen `ROLE_ADMIN_AREA` und `ROLE_CHAT_USER`.
+8. `mto:agent:ingest:version` braucht weiterhin zwei Pflichtargumente: `<versionId> <userId>`.
+9. Der globale Rebuild läuft über `mto:agent:system:rebuild --hard`.
+10. Runtime-Artefakte liegen überwiegend unter `var/knowledge/`.
 
 ---
 
+## 13. Fazit
 
-## 11. Config-Governance / YAML-only Guardrails
+Für den operativen Betrieb sind besonders relevant:
 
-These commands are mandatory for changes that touch YAML-backed configuration, prompt/retrieval behavior, intent detection, commerce/shop logic or regression-sensitive answer paths.
-
-### `mto:agent:config:validate`
-
-Validates the effective RetrieX configuration.
-
-**Signature**
-```bash
-bin/console mto:agent:config:validate [--json]
-```
-
-**Expected result before merge**
-- status `OK`
-- no errors
-
-### `mto:agent:config:audit-source`
-
-Audits YAML-backed configuration against remaining PHP defaults, fallback accessors and constructor defaults.
-
-**Signature**
-```bash
-bin/console mto:agent:config:audit-source [--details] [--json]
-```
-
-**Expected result before merge**
-- no missing YAML mappings
-- no new undocumented PHP-only semantic constants
-- no constructor defaults without YAML/service-parameter mapping
-
-Use `--details` for reviewable console output and `--json` for machine-readable CI output.
-
-### `mto:agent:config:dump-effective`
-
-Dumps the effective RetrieX configuration inventory.
-
-**Signature**
-```bash
-bin/console mto:agent:config:dump-effective [--summary]
-```
-
-Use `--summary` for a compact review view.
-
-### `mto:agent:regression:test`
-
-Runs offline regression guards for stable configuration paths.
-
-**Signature**
-```bash
-bin/console mto:agent:regression:test [--json]
-```
-
-**Expected result before merge**
-- status `OK`
-- all checks pass
-
-This command protects the regression-sensitive 1.4.2/1.5.0 baseline, especially the Testomat 808 / 0,02 deg dH / indicator type 300 flow and related configuration paths.
-
----
-
-## 12. Fazit
-
-Der aktuelle Custom-CLI-Umfang des Systems besteht aus mindestens **18 projektspezifischen Commands**. Für den operativen Betrieb sind besonders relevant:
-
-- `mto:agent:ingest:run`
-- `mto:agent:system:rebuild`
-- `mto:agent:vector:control`
+- `mto:agent:system:rebuild --hard`
+- `mto:agent:vector:control --status|--reload|--start`
 - `mto:agent:vector:health`
-- `mto:agent:tags:rebuild`
-- `mto:agent:tag:health`
+- `mto:agent:tag:health --summary`
+- `mto:agent:ingest:run`
+- `mto:agent:config:validate`
+- `mto:agent:regression:test`
 
-### `mto:agent:config:audit-patterns`
+Für Entwicklung und Fehlersuche sind besonders hilfreich:
 
-Audits remaining pattern-, token- and signal-sensitive calls in PHP core files for developer-policy review.
-
-**Signature**
-```bash
-bin/console mto:agent:config:audit-patterns [--details] [--json] [--all]
-```
-
-**Purpose**
-- finds configured calls such as `preg_match`, `str_contains`, `in_array` and related pattern/token helpers in configured source roots
-- raises WARN findings when configured domain marker terms are involved
-- keeps the command non-blocking and review-oriented; it does not change runtime behavior and does not activate strict validation
-
-**Options**
-- `--details` renders reviewable warning rows
-- `--json` renders machine-readable audit output
-- `--all` includes lower-priority REVIEW findings in addition to WARN findings
-
-**Expected use before merge**
-```bash
-bin/console mto:agent:config:audit-patterns --details
-```
-
-Review WARN findings and move new semantic terms, product names, intent words, commerce signals or retrieval/follow-up patterns to YAML-backed configuration when they are not purely technical.
+- `mto:agent:chat`
+- `mto:agent:retrieval:test`
+- `mto:agent:test-vector`
+- `mto:agent:test:shop-search --repair`
+- `mto:agent:config:dump-effective --summary`
+- `mto:agent:config:audit-patterns --details`
diff --git a/INSTALL.md b/INSTALL.md
index fc19a91..610d560 100644
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -1,315 +1,242 @@
-# RetrieX – Installationsanleitung
+# RetrieX v1.6.0 – Installationsanleitung
 
-Stand: 15.04.2026  
-Quelle: aktuelle `rag.zip` (Single Source of Truth)
+Stand: Version **1.6.0** auf Basis des aktuellen `rag-inprogress.zip`.
 
-Diese Anleitung beschreibt die **codebasierte Neuinstallation** des aktuellen Systems. Sie ersetzt ältere Installationsstände. Alle Angaben unten wurden an den tatsächlich vorhandenen Dateien, Services, Commands und Pfaden aus dem ZIP ausgerichtet.
+Diese Anleitung beschreibt eine codebasierte Neuinstallation des aktuellen Systems. Sie ersetzt ältere Installationshinweise, die noch von `rag.zip`, einem Stand vom 15.04.2026 oder einer rein statischen Chat-Startseite ausgehen.
 
 ---
 
 ## 1. Architektur des aktuellen Stands
 
-RetrieX besteht aktuell aus diesen Hauptbausteinen:
+RetrieX v1.6.0 besteht aus diesen Hauptbausteinen:
 
-- **Symfony 7.4** auf **PHP 8.2+**
-- **Doctrine ORM + Doctrine Migrations**
-- **MariaDB/MySQL** als operative Datenbank
-- **Python-Vektorlayer** mit `faiss-cpu`, `sentence-transformers`, `fastapi`, `uvicorn`
-- **Ollama-kompatibler LLM-Endpunkt** über `AI_LLM_API_URL`
-- **NDJSON + FAISS** im Dateisystem unter `var/knowledge`
-- **Adminoberfläche** für Dokumente, Ingest-Profile, System Prompt, Modellkonfiguration und Jobs
-- **SSE-Streaming** für den Browser-Chat
+- Symfony 7.4 auf PHP 8.2+
+- Doctrine ORM und Doctrine Migrations
+- MariaDB/MySQL-orientierte Migrationen mit binären UUIDs
+- dateibasierte Knowledge-Artefakte unter `var/knowledge`
+- Python-Vektorlayer mit FastAPI, uvicorn, FAISS und SentenceTransformers
+- Ollama-kompatibler LLM-Generate-Endpunkt über `AI_LLM_API_URL`
+- hybrides Retrieval über NDJSON, FAISS, Keyword-/Lexical-Komponenten und Tag-Routing
+- optionaler Shopware-Store-API-Commercepfad
+- Twig-basierte Chat- und Adminoberflächen
+- Job-basierter SSE-Flow für Browserantworten
+- getrennte Admin- und Chat-Firewalls mit Rollenmodell
+- Admin-Benutzerverwaltung, Fehlerseiten und Access-Denied-UX
+- Config-/Governance-/Regression-Commands für sichere Änderungen
 
-Wichtige Betriebsordner im aktuellen Code:
+Wichtige Ordner:
 
-- `var/knowledge/` → NDJSON, FAISS-Indizes, Uploads
-- `var/log/` → System-, Agent- und Ingest-Logs
-- `var/run/` → PID-Dateien des Python-Services
-- `var/locks/` → Ingest-Lock
-- `python/vector/` → Python-Control-, Search- und Service-Skripte
+```text
+var/knowledge/        NDJSON, FAISS-Indizes, Tags, Uploads
+var/log/              Symfony-, Agent-, Ingest- und Vector-Logs
+var/run/              PID-Dateien, z. B. vector_service.pid
+var/locks/            globale Locks, z. B. ingest.lock
+python/vector/        Python-Control-, Search- und Ingest-Skripte
+config/retriex/       Runtime-, Retrieval-, Commerce-, Prompt- und Genre-Konfiguration
+```
 
 ---
 
-## 2. Wichtige Korrekturen gegenüber älteren Installationsständen
+## 2. Wichtige Änderungen gegenüber älteren Ständen
 
-Die frühere `INSTALL.md` passt nicht mehr zum aktuellen Code. Für den aktuellen Stand gelten insbesondere diese Punkte:
-
-- Der Wissensspeicher liegt unter **`var/knowledge/`**, nicht unter `var/vector/`.
-- Der Python-Code liegt unter **`python/vector/`**, nicht unter `vector/`.
-- Die Python-Abhängigkeiten kommen aus der Datei **`requirements.txt` im Projektroot**.
-- Der korrekte Rebuild-Befehl ist **`mto:agent:system:rebuild --hard`**, nicht `mto:agent:ingest:global`.
-- Das LLM-Modell kommt **nicht** mehr aus einer `AI_LLM_MODEL`-Umgebungsvariable, sondern aus der **aktiven ModelGenerationConfig** in der Adminoberfläche.
-- Für den Chat sind **zwingend** nötig:
-    - ein **aktiver System Prompt**
-    - eine **aktive ModelGenerationConfig**
-    - mindestens ein erfolgreich indexiertes Dokument für wissensbasiertes Retrieval
-- Die Upload-UI erwähnt mehrere Dateitypen, der aktuelle Extractor-Code unterstützt jedoch **faktisch nur PDF**.
+- Das Chat-Frontend läuft nicht mehr über eine statische `public/index.html`, sondern über `App\Controller\Chat\ChatController` mit `/` und `/chat`.
+- Chat- und Adminbereiche sind architektonisch und sicherheitsseitig getrennt.
+- Admin-Routen liegen unter `/admin...`; Chat-/Ask-/SSE-/History-Routen liegen in der Chat-Firewall.
+- `ROLE_USER` allein reicht nicht mehr für Chat oder Admin.
+- `ROLE_CHAT_USER` schaltet Chat-Zugriff frei.
+- `ROLE_ADMIN_AREA`, `ROLE_EDITOR`, `ROLE_KNOWLEDGE_ADMIN` und `ROLE_SUPER_ADMIN` schalten Adminbereiche gestuft frei.
+- Die CLI umfasst inzwischen 21 projektspezifische Commands unter `mto:agent:*`.
+- `mto:agent:test:shop-search` unterstützt jetzt `--intent`, `--history` und optional `--repair`; die ältere Warnung über eine falsche Service-Signatur ist nicht mehr zutreffend.
+- Der produktive Loader unterstützt PDF, TXT und Markdown (`.md`).
+- `genre.yaml` ist die zentrale fachliche Source-of-Truth für Produktrollen, Query-Guards, Follow-up-Auflösung und Regression-Anker.
 
 ---
 
 ## 3. Systemvoraussetzungen
 
-## 3.1 Betriebssystem
+### 3.1 Betriebssystem
 
 Empfohlen:
 
-- Ubuntu 22.04 LTS oder neuer
-- Debian 12 ist ebenfalls passend
+- Linux Server oder VM
+- Ubuntu 22.04/24.04 oder Debian 12
 
-Für lokale Entwicklung sind auch macOS oder Linux-Container-Setups möglich.
+Lokal ist Entwicklung auch auf macOS oder WSL möglich, produktiv sollte ein regulärer Webserver mit PHP-FPM verwendet werden.
 
----
-
-## 3.2 PHP
+### 3.2 PHP
 
 Erforderlich:
 
-- **PHP 8.2 oder höher**
+- PHP 8.2 oder neuer
+- Composer
 
-Benötigte bzw. praktisch notwendige Extensions aus dem aktuellen Projektstand:
+Relevante PHP-Erweiterungen aus `composer.json` und Runtime:
 
 - `ctype`
 - `curl`
 - `dom`
 - `iconv`
 - `libxml`
-- `pdo`
 - `pdo_mysql`
 - `mbstring`
 - `zip`
+- `sqlite3`
 
 Prüfen:
 
 ```bash
 php -v
 php -m
-```
-
----
-
-## 3.3 Composer
-
-Prüfen:
-
-```bash
 composer --version
 ```
 
-Falls Composer nicht global vorhanden ist, kann lokal installiert werden. Für den regulären Betrieb ist ein globaler Composer aber sinnvoll.
+### 3.3 Datenbank
 
----
-
-## 3.4 Datenbank
-
-Der aktuelle Projektstand ist praktisch auf **MariaDB/MySQL** ausgerichtet.
+Die mitgelieferten Migrationen sind praktisch auf MariaDB/MySQL ausgelegt, z. B. durch `BINARY(16)`, `TINYINT`, `LONGTEXT`, `JSON` und MariaDB-kompatible UUID-Strukturen.
 
 Empfohlen:
 
-- **MariaDB 10.11.x**
+- MariaDB 10.11.x oder kompatibles MySQL 8.x
 
-Beispielinstallation:
-
-```bash
-sudo apt install mariadb-server
-```
-
-Beispiel für Datenbank und Benutzer:
+Beispiel:
 
 ```sql
-CREATE DATABASE db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
-CREATE USER 'db'@'%' IDENTIFIED BY 'db';
-GRANT ALL PRIVILEGES ON db.* TO 'db'@'%';
+CREATE DATABASE retriex CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+CREATE USER 'retriex'@'%' IDENTIFIED BY 'change-me';
+GRANT ALL PRIVILEGES ON retriex.* TO 'retriex'@'%';
 FLUSH PRIVILEGES;
 ```
 
-Hinweis:
-Die mitgelieferte `.env` enthält derzeit noch eine PostgreSQL-Placeholder-URL. Für den realen Betrieb muss `DATABASE_URL` auf **MariaDB/MySQL** gesetzt werden.
+Die mitgelieferte `.env` kann noch Platzhalter enthalten. Für Betrieb eine eigene `.env.local` verwenden.
 
----
-
-## 3.5 Python
+### 3.4 Python
 
 Erforderlich:
 
-- **Python 3.10 oder höher**
+- Python 3.10 oder neuer
 - `python3-venv`
 - `python3-pip`
 
-Installation:
+Python-Abhängigkeiten aus `requirements.txt`:
 
-```bash
-sudo apt install python3 python3-venv python3-pip
-```
+- `fastapi`
+- `uvicorn`
+- `faiss-cpu`
+- `sentence-transformers`
+- `numpy`
 
-Prüfen:
+### 3.5 LLM-Endpunkt
 
-```bash
-python3 --version
-```
+RetrieX spricht den LLM über `AI_LLM_API_URL` an. Erwartet wird ein Ollama-kompatibler `/api/generate`-Endpoint.
 
----
-
-## 3.6 Ollama oder kompatibler Generate-Endpunkt
-
-RetrieX spricht den LLM-Endpunkt über `AI_LLM_API_URL` an. Erwartet wird ein **Ollama-kompatibler `/api/generate`-Endpoint**.
-
-Beispiel mit Ollama:
-
-```bash
-curl -fsSL https://ollama.com/install.sh | sh
-```
-
-Ein Modell muss lokal vorhanden sein, zum Beispiel:
-
-```bash
-ollama pull qwen3
-```
-
-oder ein projektspezifisches Modell, falls vorhanden.
-
-Verfügbarkeit prüfen:
+Beispiel:
 
 ```bash
 curl http://127.0.0.1:11434/api/tags
 ```
 
-Wichtig:
-Welches Modell tatsächlich benutzt wird, bestimmt später die **aktive ModelGenerationConfig im Admin**, nicht eine `.env`-Variable.
+Das konkret verwendete Modell wird über die aktive `ModelGenerationConfig` im Admin gesteuert, nicht allein über `.env`.
 
----
+### 3.6 Optional: Shopware Store API
 
-## 3.7 Optional: Shopware Store API
+Für Commerce-/Shopfragen kann die Shopware Store API angebunden werden.
 
-Der Commerce-Pfad ist im aktuellen Code **standardmäßig aktiviert**. Für produktbezogene Anfragen nutzt das System optional die Shopware Store API.
-
-Dafür werden diese Variablen verwendet:
+Relevante Variablen:
 
 - `SHOPWARE_STORE_API_BASE_URL`
 - `SHOPWARE_SALES_CHANNEL_ACCESS_KEY`
 - `SHOPWARE_STORE_API_MAX_RESULT`
 
-Wenn keine Shopware-Suche gewünscht ist, sollte der Commerce-Pfad vor produktivem Einsatz bewusst deaktiviert oder sauber konfiguriert werden.
+Wenn keine Shopware-Suche gewünscht ist, Commerce bewusst deaktivieren oder sauber mit leeren/ungefährlichen Testwerten konfigurieren.
 
 ---
 
 ## 4. Projekt bereitstellen
 
-ZIP entpacken und ins Projekt wechseln:
+Beispiel mit ZIP:
 
 ```bash
-unzip rag.zip -d retriex
+unzip rag-inprogress.zip -d retriex
 cd retriex
 ```
 
-Alternativ über Repository-Checkout, falls das Projekt aus Git bereitgestellt wird.
+Oder über Repository-Checkout, falls der Stand in Git verwaltet wird.
 
 ---
 
 ## 5. PHP-Abhängigkeiten installieren
 
+Entwicklung:
+
 ```bash
 composer install --no-interaction
 ```
 
-Für Produktion:
+Produktion:
 
 ```bash
 composer install --no-dev --optimize-autoloader --no-interaction
 ```
 
-Erst nach diesem Schritt funktionieren `bin/console` und die Symfony-Commands.
+Danach sollte `bin/console` ausführbar sein:
+
+```bash
+php bin/console list mto:agent
+```
 
 ---
 
 ## 6. Umgebung konfigurieren
 
-## 6.1 Grundregel
+Eine lokale `.env.local` anlegen und mindestens Datenbank und LLM-Endpunkt setzen.
 
-Lokale oder serverbezogene Overrides sollten in **`.env.local`** gepflegt werden, nicht direkt in der committeten `.env`.
+Beispiel:
 
----
-
-## 6.2 Minimale `.env.local`
-
-Beispiel für einen lokalen oder servernahen MariaDB-Betrieb:
-
-```env
+```dotenv
 APP_ENV=prod
 APP_SECRET=change-me
-
-DATABASE_URL="mysql://db:db@127.0.0.1:3306/db?serverVersion=10.11.0-mariadb&charset=utf8mb4"
-MESSENGER_TRANSPORT_DSN=doctrine://default?auto_setup=0
-
-AI_LLM_API_URL=http://127.0.0.1:11434/api/generate
-AI_LLM_TIMEOUT=600
-AI_HISTORY_DIR=var/agent-history
-AI_DEBUG=false
-AI_LOG_PROMPT=false
-AI_LOG_CONTEXT=false
-
-SHOPWARE_STORE_API_BASE_URL="https://example.invalid"
-SHOPWARE_SALES_CHANNEL_ACCESS_KEY="replace-me"
-SHOPWARE_STORE_API_MAX_RESULT=25
+DATABASE_URL="mysql://retriex:change-me@127.0.0.1:3306/retriex?serverVersion=10.11.2-MariaDB&charset=utf8mb4"
+AI_LLM_API_URL="http://127.0.0.1:11434/api/generate"
 ```
 
-Hinweise:
+Optional für Shopware:
 
-- `APP_ENV=prod` ist im aktuellen `.env` bereits voreingestellt.
-- `DATABASE_URL` muss auf MariaDB/MySQL zeigen.
-- `AI_LLM_API_URL` muss auf einen funktionierenden `/api/generate`-Endpoint zeigen.
-- `AI_LLM_TIMEOUT=600` ist mit dem aktuellen Code konsistent.
-- `AI_LLM_MODEL` wird **nicht** verwendet.
+```dotenv
+SHOPWARE_STORE_API_BASE_URL="https://example.invalid/store-api"
+SHOPWARE_SALES_CHANNEL_ACCESS_KEY="change-me"
+SHOPWARE_STORE_API_MAX_RESULT=10
+```
 
----
-
-## 6.3 Shopware deaktivieren, wenn nicht benötigt
-
-Im aktuellen Code ist `mto.commerce.enabled` in `config/services.yaml` auf `true` gesetzt. Wer die Shopware-Suche nicht einsetzen will, sollte vor produktivem Einsatz bewusst einen dieser Wege wählen:
-
-1. gültige Shopware-Zugangsdaten hinterlegen, oder
-2. `config/services.yaml` gezielt anpassen und Commerce deaktivieren.
-
-Für reine Wissens- und Dokumentinstallation ist die Shopware-Anbindung nicht zwingend, sollte aber nicht unklar halbkonfiguriert bleiben.
+Wichtig: keine produktiven Secrets in die versionierte `.env` schreiben.
 
 ---
 
 ## 7. Datenbank initialisieren
 
-Migrationen ausführen:
-
 ```bash
+php bin/console doctrine:database:create --if-not-exists
 php bin/console doctrine:migrations:migrate --no-interaction
 ```
 
-Damit werden unter anderem diese zentralen Tabellen angelegt:
+Bei Produktionsbetrieb danach Cache aufbauen:
 
-- `user`
-- `document`
-- `document_version`
-- `ingest_job`
-- `system_prompt`
-- `ingest_profile`
-- `model_generation_config`
-- `knowledge_tag`
-- `document_tag`
-- `tag_rebuild_job`
+```bash
+php bin/console cache:clear --env=prod
+php bin/console cache:warmup --env=prod
+```
 
 ---
 
 ## 8. Python-Umgebung aufbauen
 
-## 8.1 Virtuelle Umgebung anlegen
+Virtuelle Umgebung anlegen:
 
 ```bash
 python3 -m venv .venv
 source .venv/bin/activate
 ```
 
----
-
-## 8.2 Python-Abhängigkeiten installieren
-
-Manuell:
+Abhängigkeiten installieren:
 
 ```bash
 pip install --upgrade pip
@@ -322,12 +249,11 @@ Alternativ nach angelegter `.venv` über den Symfony-Wrapper:
 php bin/console mto:agent:vector:control --install
 ```
 
-Wichtig:
-Der Wrapper erwartet bereits eine existierende `.venv`. Er erzeugt sie **nicht** selbst.
+Der Wrapper erwartet eine vorhandene `.venv`; er legt sie nicht selbst an.
 
 ---
 
-## 9. Vector Service starten
+## 9. Vector-Service starten
 
 Start:
 
@@ -335,335 +261,297 @@ Start:
 php bin/console mto:agent:vector:control --start
 ```
 
-Status prüfen:
+Status:
 
 ```bash
 php bin/console mto:agent:vector:control --status
 ```
 
-Optionaler Reload:
+Reload:
 
 ```bash
 php bin/console mto:agent:vector:control --reload
 ```
 
-Der Service startet aktuell standardmäßig auf:
+Standardwerte aus dem aktuellen Command/Service-Setup:
 
 - Host: `0.0.0.0`
 - Port: `8090`
-
-Der PHP-Code spricht standardmäßig gegen:
-
-- `http://127.0.0.1:8090`
+- PHP-Service-URL: typischerweise `http://127.0.0.1:8090`
+- PID-Datei: `var/run/vector_service.pid`
 
 ---
 
-## 10. Admin-Benutzer anlegen
+## 10. Ersten Benutzer anlegen
 
-Ohne Admin-Benutzer lässt sich das System nicht fertig konfigurieren.
-
-CLI-Befehl:
+Ohne Benutzer ist weder Chat noch Admin sinnvoll nutzbar.
 
 ```bash
 php bin/console mto:agent:user:create
 ```
 
-Der Command fragt interaktiv ab:
+Der Command fragt ab:
 
 - E-Mail
-- Passwort
-- Rolle
+- Passwort mit Wiederholung
+- eine oder mehrere Rollen
+- Aktivstatus
 
-Für die Erstinstallation ist typischerweise sinnvoll:
-
-- `ROLE_SUPER_ADMIN`
+Für die Erstinstallation ist typischerweise `ROLE_SUPER_ADMIN` sinnvoll. Diese Rolle enthält über die Hierarchie auch Admin-, Editor-, Knowledge-Admin- und Chat-Rechte.
 
 ---
 
 ## 11. Anwendung starten
 
-Für einen einfachen lokalen Test:
+Lokaler Test:
 
 ```bash
 php -S 127.0.0.1:8000 -t public
 ```
 
-Danach sind typischerweise relevant:
+Relevante Einstiegspunkte:
 
-- Chat-Frontend: `http://127.0.0.1:8000/`
+- Chat: `http://127.0.0.1:8000/`
+- Chat-Login: `http://127.0.0.1:8000/chat/login`
 - Admin-Login: `http://127.0.0.1:8000/admin/login`
 
-Für Produktion sollte stattdessen ein regulärer Webserver genutzt werden, zum Beispiel Nginx + PHP-FPM.
+Für Produktion Nginx/Apache + PHP-FPM verwenden und `public/` als Document Root setzen.
 
 ---
 
 ## 12. Pflicht-Initialisierung im Admin
 
-Nach der technischen Grundinstallation ist das System **noch nicht vollständig betriebsbereit**. Es müssen im Admin zwingend Inhalte angelegt werden.
+### 12.1 System Prompt anlegen
 
-## 12.1 System Prompt anlegen und aktivieren
+Pfad:
 
-Pfad im Admin:
-
-- `/admin/system/prompt`
-
-Ohne aktiven System Prompt wirft der PromptBuilder zur Laufzeit einen Fehler.
-
----
-
-## 12.2 ModelGenerationConfig anlegen und aktivieren
-
-Pfad im Admin:
-
-- `/admin/model-config/`
-
-Ohne aktive ModelGenerationConfig schlägt das Retrieval fehl, weil `NdjsonHybridRetriever` explizit eine aktive Konfiguration verlangt.
-
-Sinnvolle Minimalwerte für einen stabilen Start:
-
-- Modellname: exakt wie im Ollama-Endpunkt verfügbar, z. B. `qwen3:latest`
-- Streaming: aktiv
-- Temperature: `0.2` bis `0.4`
-- Top K: `40`
-- Top P: `0.9`
-- Repeat Penalty: `1.1`
-- num_ctx: `8192`
-- Retrieval Max Chunks: `25`
-- Retrieval Vector Top K: `25`
-
----
-
-## 12.3 Optional: Ingest-Profil anlegen
-
-Pfad im Admin:
-
-- `/admin/ingest-profiles/`
-
-Wenn kein Profil aktiv ist, fällt das System auf die Parameter aus `config/services.yaml` zurück:
-
-- Chunk Size: `800`
-- Chunk Overlap: `100`
-- Embedding Model: `intfloat/multilingual-e5-base`
-- Embedding Dimension: `768`
-- Scoring Version: `1`
-
-Das ist für einen ersten Start ausreichend. Ein eigenes Ingest-Profil ist also **optional**, solange man die Fallback-Werte bewusst akzeptiert.
-
----
-
-## 13. Erste Dokumente ingestieren
-
-## 13.1 Wichtiger Format-Hinweis
-
-Die Upload-Maske nennt mehrere Formate, aber der aktuelle Extractor-Code enthält nur einen **`PdfExtractor`**. Für einen sicheren Erstbetrieb sollten daher aktuell **nur PDF-Dateien** hochgeladen werden.
-
----
-
-## 13.2 Erstes Dokument hochladen
-
-Pfad im Admin:
-
-- `/admin/documents/new`
-
-Beim Upload passiert im aktuellen Code folgendes:
-
-1. Datei wird nach `var/knowledge/uploads` verschoben.
-2. Dokument und Version 1 werden in der DB angelegt.
-3. Die neue Version wird aktiv gesetzt.
-4. Ein Ingest-Job vom Typ `DOCUMENT_VERSION_ACTIVATE` wird erstellt.
-5. Der Job wird **asynchron per `exec()`** gestartet.
-
----
-
-## 13.3 Wenn `exec()` deaktiviert ist
-
-Der Admin-Flow für Upload, Aktivierung und Löschen setzt im aktuellen Code Hintergrundstarts über `exec()` voraus.
-
-Ist `exec()` serverseitig deaktiviert, werden Jobs zwar angelegt, aber nicht automatisch ausgeführt. In diesem Fall muss der Job manuell gestartet werden:
-
-```bash
-php bin/console mto:agent:ingest:run <jobId>
+```text
+/admin/system/prompt
 ```
 
-Die `jobId` ist in der Job-Ansicht im Admin nachvollziehbar.
+Ohne aktiven System Prompt kann der finale PromptBuilder keine saubere Antwortgrundlage erzeugen.
+
+### 12.2 ModelGenerationConfig anlegen
+
+Pfad:
+
+```text
+/admin/model-config/
+```
+
+Sinnvolle Startwerte:
+
+| Feld | Beispiel |
+| --- | --- |
+| Modellname | `qwen3:latest` oder der lokal verfügbare Ollama-Name |
+| Streaming | aktiv |
+| Temperature | `0.2` bis `0.4` |
+| Top K | `40` |
+| Top P | `0.9` |
+| Repeat Penalty | `1.1` |
+| num_ctx | `8192` oder höher, passend zum Modell |
+| Retrieval Max Chunks | `25` |
+| Retrieval Vector Top K | `25` |
+
+### 12.3 Optional: Ingest-Profil prüfen
+
+Pfad:
+
+```text
+/admin/ingest-profiles/
+```
+
+Wenn kein Profil aktiv ist, gelten die Fallbackwerte aus der technischen Konfiguration. Für produktive Systeme sollte ein bewusstes Profil gepflegt werden.
+
+---
+
+## 13. Dokumente ingestieren
+
+Unterstützte Formate im aktuellen Ingest-Loader:
+
+- `.pdf`
+- `.txt`
+- `.md`
+
+Ablauf im Admin:
+
+1. Als Benutzer mit `ROLE_EDITOR` oder höher einloggen.
+2. Dokument anlegen oder öffnen.
+3. Version hochladen.
+4. Version ingestieren bzw. aktivieren.
+5. Ingest-Job prüfen.
+6. Danach Vector-/Tag-Health prüfen.
+
+CLI-Ingest einer konkreten Version:
+
+```bash
+php bin/console mto:agent:ingest:version <documentVersionUuid> <userUuid>
+```
+
+Vorhandenen Job ausführen:
+
+```bash
+php bin/console mto:agent:ingest:run <jobUuid>
+```
 
 ---
 
 ## 14. Rebuild und Konsistenzprüfung
 
-## 14.1 Vollständiger System-Rebuild
-
-Sobald aktive Dokumente vorhanden sind, kann ein vollständiger Rebuild ausgeführt werden:
+Vollständiger Hard-Rebuild:
 
 ```bash
 php bin/console mto:agent:system:rebuild --hard
 ```
 
-Dieser Ablauf umfasst aktuell:
+Optionen:
 
-1. globalen Reindex der aktiven Dokumente
-2. Tag-Export und Tag-Index-Rebuild
-3. Reload des Vector Service
-4. Health-Checks
+```bash
+php bin/console mto:agent:system:rebuild --hard --dry-run
+php bin/console mto:agent:system:rebuild --hard --no-tags
+php bin/console mto:agent:system:rebuild --hard --no-reload
+php bin/console mto:agent:system:rebuild --hard --no-health
+```
 
-Wichtig:
-Der Befehl bricht absichtlich ab, wenn **keine aktiven Dokumente** vorhanden sind.
-
----
-
-## 14.2 Vector Health prüfen
+Health-Checks:
 
 ```bash
 php bin/console mto:agent:vector:health
+php bin/console mto:agent:tag:health --summary
 ```
 
-Mögliche gesunde Zustände:
-
-- `OK_EMPTY` → noch keine Wissensdaten vorhanden
-- `OK` → NDJSON und FAISS konsistent
-
----
-
-## 14.3 Tag Health prüfen
+Tag-Retrieval neu aufbauen:
 
 ```bash
-php bin/console mto:agent:tag:health
-```
-
----
-
-## 15. Wichtige Commands im aktuellen Stand
-
-```bash
-php bin/console mto:agent:user:create
-php bin/console mto:agent:vector:control --install
-php bin/console mto:agent:vector:control --start
-php bin/console mto:agent:vector:control --status
-php bin/console mto:agent:vector:control --reload
-php bin/console mto:agent:vector:rebuild
-php bin/console mto:agent:vector:health
-php bin/console mto:agent:ingest:run <jobId>
-php bin/console mto:agent:ingest:version <versionId> <userId>
-php bin/console mto:agent:system:rebuild --hard
-php bin/console mto:agent:tags:export
 php bin/console mto:agent:tags:rebuild
-php bin/console mto:agent:tag:health
-php bin/console mto:agent:chat
-php bin/console mto:agent:test:shop-search "deine Anfrage"
 ```
 
 ---
 
-## 16. Minimaler Go-Live-Check
+## 15. Governance-Checks nach Installation oder Änderungen
 
-Eine Installation ist im aktuellen Stand erst dann wirklich lauffähig, wenn alle folgenden Punkte erfüllt sind:
+Für Konfigurations- und Prompt-/Retrieval-/Commerce-Änderungen:
 
-- Composer-Abhängigkeiten installiert
-- Datenbankmigrationen erfolgreich durchgelaufen
-- `.env.local` korrekt gesetzt
-- `.venv` vorhanden und Python-Abhängigkeiten installiert
-- Vector Service läuft auf Port `8090`
-- Admin-Benutzer existiert
-- aktiver System Prompt vorhanden
-- aktive ModelGenerationConfig vorhanden
-- mindestens ein PDF erfolgreich ingestiert
-- `mto:agent:vector:health` liefert `OK` oder `OK_EMPTY`
-- Chat-Frontend und Admin-Login sind erreichbar
+```bash
+php bin/console mto:agent:config:validate
+php bin/console mto:agent:config:audit-source --details
+php bin/console mto:agent:config:audit-patterns --details
+php bin/console mto:agent:regression:test
+```
+
+Zur Übersicht:
+
+```bash
+php bin/console mto:agent:config:dump-effective --summary
+```
+
+Für reale Pfadtests:
+
+```bash
+php bin/console mto:agent:retrieval:test "niedrigster Grenzwert Wasserhärte"
+php bin/console mto:agent:test:shop-search "testomat 808 300 indikator" --repair
+php bin/console mto:agent:chat cli-debug
+```
 
 ---
 
-## 17. Häufige Fehlerbilder
+## 16. Rollenmodell für den Betrieb
 
-## 17.1 `No active system prompt configured.`
+| Rolle | Zweck |
+| --- | --- |
+| `ROLE_CHAT_USER` | Zugriff auf Chat, Ask/SSE, History und Frontend-Messages |
+| `ROLE_ADMIN_AREA` | Adminbasis, Dashboard, Guides und Jobübersicht |
+| `ROLE_EDITOR` | Dokumente, Versionen, Tags und Dokument-Ingest |
+| `ROLE_KNOWLEDGE_ADMIN` | Modell-/Retrieval-Konfiguration und Ingest-Profile |
+| `ROLE_SUPER_ADMIN` | Userverwaltung, Logs, System Prompt/Agent, kritische Aktionen, Global Reindex |
 
-Ursache:
-Es existiert kein aktiver System Prompt.
-
-Lösung:
-Im Admin unter `/admin/system/prompt` eine Version speichern und aktivieren.
+`ROLE_SUPER_ADMIN` enthält alle darunterliegenden Rollen. `ROLE_USER` ist nur technische Basisrolle.
 
 ---
 
-## 17.2 `No active ModelGenerationConfig found.`
+## 17. Minimaler Go-Live-Check
 
-Ursache:
-Es existiert keine aktive Modellkonfiguration.
+Vor produktiver Nutzung prüfen:
 
-Lösung:
-Im Admin unter `/admin/model-config/` eine Konfiguration anlegen und aktivieren.
+- `.env.local` enthält produktive DB-, LLM- und ggf. Shopware-Werte.
+- Datenbankmigrationen sind durchgelaufen.
+- Mindestens ein aktiver `ROLE_SUPER_ADMIN` existiert.
+- Mindestens ein aktiver Chat-User existiert.
+- Aktiver System Prompt ist vorhanden.
+- Aktive ModelGenerationConfig ist vorhanden.
+- Vector-Service läuft.
+- Mindestens ein aktives Dokument ist ingestiert.
+- `mto:agent:vector:health` ist grün.
+- `mto:agent:tag:health --summary` ist grün oder bewusst initial leer.
+- `mto:agent:config:validate` ist grün.
+- `mto:agent:regression:test` ist grün.
+- Chat-Login und Admin-Login sind getrennt erreichbar.
+- 403/404/500-Seiten funktionieren im gewünschten Layout.
 
 ---
 
-## 17.3 Vector Service startet nicht
+## 18. Häufige Fehlerbilder
 
-Typische Ursachen:
+### `No active system prompt configured.`
 
-- `.venv` fehlt
-- Python-Pakete fehlen
-- Port `8090` ist schon belegt
-- `uvicorn` ist nicht in der virtuellen Umgebung installiert
+Im Admin einen System Prompt anlegen und aktivieren.
+
+### `No active ModelGenerationConfig found.`
+
+Im Admin unter `/admin/model-config/` eine Modellkonfiguration anlegen und aktivieren.
+
+### Vector-Service startet nicht
 
 Prüfen:
 
 ```bash
+source .venv/bin/activate
+pip install -r requirements.txt
 php bin/console mto:agent:vector:control --status
 ```
 
----
+Außerdem prüfen, ob Port `8090` frei ist und `python/vector/vector_control.py` existiert.
 
-## 17.4 Rebuild bricht mit „no active documents found“ ab
+### Rebuild bricht mit `no active documents found` ab
 
-Ursache:
-Es wurde noch kein aktives Dokument erfolgreich angelegt.
+Mindestens ein Dokument und eine aktive, ingestierte Version anlegen.
 
-Lösung:
-Zuerst ein PDF hochladen und ingestieren, danach den Rebuild erneut starten.
+### Chat zeigt Access Denied
+
+Der Benutzer braucht `ROLE_CHAT_USER` oder eine übergeordnete Rolle.
+
+### Admin zeigt Access Denied
+
+Der Benutzer braucht mindestens `ROLE_ADMIN_AREA`; für Dokumente `ROLE_EDITOR`, für Modell-/Ingest-Konfiguration `ROLE_KNOWLEDGE_ADMIN`, für Userverwaltung und kritische Systemaktionen `ROLE_SUPER_ADMIN`.
+
+### Nicht-PDF-Ingest
+
+TXT und Markdown werden im aktuellen `DocumentLoader` unterstützt. Für andere Formate wie DOCX gibt es im aktuellen produktiven Ingest-Pfad keinen verifizierten Loader.
 
 ---
 
-## 17.5 Upload klappt, Ingest startet aber nicht
+## 19. Produktionshinweise
 
-Ursache:
-`exec()` ist auf dem Server deaktiviert.
-
-Lösung:
-Job manuell mit `mto:agent:ingest:run <jobId>` starten oder Serverkonfiguration anpassen.
+- Webserver auf `public/` zeigen lassen.
+- Schreibrechte für `var/` sicherstellen.
+- `APP_ENV=prod` und `APP_DEBUG=0` setzen.
+- Secrets nur in `.env.local` oder Secret-Management pflegen.
+- Vector-Service über systemd, Supervisor oder Container-Prozessmanagement betreiben.
+- Logs rotieren.
+- Rebuilds nicht parallel ausführen.
+- Vor Änderungen an `genre.yaml`, `commerce.yaml`, `prompt.yaml` oder Retrieval-Konfiguration immer Governance-Checks ausführen.
+- Regelmäßig ein Backup von Datenbank und `var/knowledge` erstellen.
 
 ---
 
-## 17.6 Dokument-Ingest schlägt bei Nicht-PDF fehl
+## 20. Ergebnis
 
-Ursache:
-Der aktuelle Code enthält nur einen `PdfExtractor`.
+Nach Abschluss der Installation stehen zur Verfügung:
 
-Lösung:
-Für den aktuellen Stand ausschließlich PDFs ingestieren oder Extractor-Layer erweitern.
-
----
-
-## 18. Empfohlene Produktionshinweise
-
-Für stabilen produktiven Betrieb sind sinnvoll:
-
-- Nginx oder Apache vor Symfony/PHP-FPM
-- eigener Service-Start für den Python-Vector-Service
-- eigener Service für Ollama
-- Backup von Datenbank und `var/knowledge/`
-- Monitoring der Logs unter `var/log/`
-- bewusstes Governance-Handling für Ingest-Profile, System Prompts und Model-Konfigurationen
-
----
-
-## 19. Ergebnis
-
-Nach erfolgreicher Installation bietet der aktuelle Stand von RetrieX:
-
-- dokumentenbasierte Wissensverwaltung
-- versionierte Dokumente
-- asynchronen Ingest über Jobs
-- NDJSON als Wissensspeicher
-- FAISS-basiertes Retrieval
-- optionales Tag-Routing
-- optionalen Shopware-Commerce-Pfad
-- browserbasierten SSE-Chat
-- Symfony-Adminoberfläche für Betrieb und Governance
+- rollenbasierter Chat unter `/` und `/chat`
+- rollenbasierter Adminbereich unter `/admin`
+- dokumentenbasierter RAG-Ingest
+- hybrides Retrieval mit Vector- und Tag-Komponenten
+- optionaler Shopware-Commercepfad
+- SSE-Streaming für Browserantworten
+- CLI-Werkzeuge für Ingest, Rebuild, Health, Governance und Debugging
diff --git a/genre_yaml_konfigurationsanleitung.md b/genre_yaml_konfigurationsanleitung.md
index b207fae..88fec7d 100644
--- a/genre_yaml_konfigurationsanleitung.md
+++ b/genre_yaml_konfigurationsanleitung.md
@@ -1,16 +1,10 @@
-# Konfigurationsanleitung `config/retriex/genre.yaml`
+# RetrieX v1.6.0 – Konfigurationsanleitung `config/retriex/genre.yaml`
 
-Stand: aktueller Arbeitsstand aus `rag-inprogress.zip`.
+Stand: Version **1.6.0** auf Basis des aktuellen `rag-inprogress.zip`.
 
-Diese Anleitung beschreibt, welche Bereiche in `genre.yaml` gepflegt werden, welche Auswirkungen Änderungen haben und wie eine Anpassung sicher durchgeführt wird.
+Diese Anleitung beschreibt, welche fachlichen Werte in `config/retriex/genre.yaml` gepflegt werden, wie sie in der Runtime wirken und welche Prüfungen nach Änderungen ausgeführt werden müssen.
 
----
-
-## 1. Zweck der Datei
-
-`config/retriex/genre.yaml` ist die zentrale fachliche Konfigurationsfläche für eine RetrieX-Installation mit genau einem aktiven Genre.
-
-Aktuell ist das Genre:
+`genre.yaml` ist in RetrieX v1.6.0 die zentrale Fachkonfiguration für die aktive Domäne. Im aktuellen Paket ist genau ein Genre aktiv:
 
 ```yaml
 id: water_analysis
@@ -18,13 +12,38 @@ label: Water analysis / measurement devices
 mode: single_installation_single_genre
 ```
 
-Wichtig:
+Wichtig: RetrieX v1.6.0 ist keine Multi-Tenant- oder Multi-Genre-Plattform. Eine Installation steht für ein fachliches Genre. Domainnahe Begriffe, Produktrollen, Query-Guards, Promptregeln, Shop-Matching-Wörter und Regression-Guardrails gehören deshalb hierher, nicht zurück in hart codierte PHP-Listen.
 
-- Eine Installation steht für ein Genre.
-- Es gibt keine Multi-Tenant-, Multi-Shop-, Host-, API-Key- oder Request-basierte Genre-Umschaltung.
-- Fachliche Listen, Begriffe, Muster, Produktrollen, Antwortregeln und genreabhängige Guardrails gehören in `genre.yaml`.
-- Technische Einstellungen wie Modell, Vector-Index, Chunking, Cache, LLM-Parameter, Store-API-Credentials oder allgemeine Infrastruktur bleiben außerhalb von `genre.yaml`.
-- Die alten YAML-Dateien bleiben als technische Verarbeitungsschicht, leere Fallbacks oder eingefrorene Legacy-Pfade erhalten. Neue fachliche Werte sollen dort nicht wieder eingeführt werden.
+---
+
+## 1. Rolle von `genre.yaml` im System
+
+`genre.yaml` ergänzt die technischen YAML-Dateien unter `config/retriex` um eine fachliche Source-of-Truth-Schicht.
+
+In `genre.yaml` gehören insbesondere:
+
+- Hauptprodukt-, Zubehör- und Verbrauchsmaterialrollen
+- Produktattribute, Messparameter, Größen-, Farb- oder Längenbegriffe
+- Marken, Kanonisierungen, Schreibvarianten und Synonyme
+- Commerce-/Shop-Suchbegriffe und positive Tokenfilter
+- Referenzauflösung für Follow-ups aus dem Chatverlauf
+- Produktlisten- und Produktlink-Follow-ups
+- exakte Zubehör-/Indikatorcode-Guards
+- technische Prompt- und Antwortprioritäten
+- Measurement-Evidence-Guards
+- Search-Repair-Kandidaten und Direct-Attribute-Lookups
+- Governance-, Source-of-Truth- und Regression-Anker
+
+Nicht in `genre.yaml` gehören:
+
+- Datenbankzugangsdaten
+- Shopware-Zugangsdaten
+- LLM-Endpunkt
+- Python-/Vector-Service-Pfade
+- Cache-, Lock-, Log- oder Infrastrukturparameter
+- konkrete Modell-Samplingwerte wie Temperature oder Top-P
+
+Diese Werte bleiben in `.env`, `services.yaml`, `model.yaml`, `vector.yaml`, `runtime.yaml` oder in der Datenbankkonfiguration.
 
 ---
 
@@ -43,121 +62,104 @@ parameters:
     configuration_values: ...
 ```
 
-### 2.1 `id`, `label`, `mode`, `description`
+### 2.1 Metadaten
 
-| Feld | Bedeutung | Auswirkung | Anpassung |
-|---|---|---|---|
-| `id` | Technischer Genre-Identifier | Metadaten, Diagnose, zukünftige Dokumentation | Bei Umwidmung ändern, z. B. `fashion`, `spare_parts`, `electronics` |
-| `label` | Lesbarer Name | Audit-/Debug-/Dokumentationswert | Frei sprechend halten |
-| `mode` | Betriebsmodell | Beschreibt bewusst `single_installation_single_genre` | Nicht auf Multi-Genre ändern, solange keine Architektur dafür existiert |
-| `description` | Kurzbeschreibung | Dokumentation | An neues Genre anpassen |
+| Feld | Bedeutung | Anpassung |
+| --- | --- | --- |
+| `id` | technischer Genre-Identifier | Nur ändern, wenn die Installation fachlich umgewidmet wird. |
+| `label` | lesbarer Name | Frei sprechend halten. |
+| `mode` | Betriebsmodell | In v1.6.0 bei `single_installation_single_genre` belassen. |
+| `description` | Kurzbeschreibung | Bei Umwidmung aktualisieren. |
 
 ### 2.2 `adaptation_surface`
 
-`adaptation_surface` ist die Landkarte. Sie gruppiert alle Konfigurationsbereiche, die bei einer Umwidmung des Systems überprüft werden müssen.
-
-Sie enthält Beschreibungen und `paths` auf alte/effective Runtime-Konfigurationspfade.
+`adaptation_surface` ist die Landkarte der fachlichen Anpassungsflächen. Sie dokumentiert, welche Runtime-Pfade durch `genre.yaml` fachlich überlagert oder gespeist werden.
 
 Auswirkung:
 
-- Ändert normalerweise nicht direkt das Antwort- oder Suchverhalten.
-- Wird für Validierung, Audit und Nachvollziehbarkeit genutzt.
-- Muss synchron zu `configuration_values` bleiben.
-- Jede Gruppe in `adaptation_surface` braucht eine entsprechende Gruppe in `configuration_values`.
+- dient Audit, Review und Migration
+- ändert normalerweise nicht direkt das Antwortverhalten
+- muss zu `configuration_values` passen
+- soll keine fachliche Payload enthalten
 
-Anpassen:
-
-- Nur ändern, wenn ein neuer genreabhängiger Runtime-Pfad hinzukommt, wegfällt oder umbenannt wird.
-- Keine fachlichen Werte dort pflegen.
-- `paths` müssen gültige Pfade sein; falsche Pfade werden durch Validate/Audit sichtbar.
+Ändern nur dann, wenn neue genreabhängige Runtime-Pfade hinzukommen, wegfallen oder umbenannt werden.
 
 ### 2.3 `configuration_values`
 
-`configuration_values` ist die eigentliche zentrale Wertefläche.
+`configuration_values` enthält die eigentlichen fachlichen Werte. Änderungen hier können Retrieval, Shop-Suche, Commerce-Routing, Promptbau, Search Repair, Follow-up-Auflösung und Regression-Guards unmittelbar beeinflussen.
 
-Auswirkung:
+Grundregel:
 
-- Die Runtime-Konfigurationsklassen lesen diese Werte bevorzugt über `GenreConfig`.
-- Änderungen hier beeinflussen Retrieval, Shop-Suche, Commerce-Routing, Search Repair, Antwortregeln, Follow-up-Auflösung, Produktrollentrennung und Regression-Guardrails.
-- Die alten Pfade sollen leer oder eingefroren bleiben.
-
-Anpassen:
-
-- Fachliche Änderungen immer hier vornehmen.
-- Die bestehende Gruppenstruktur beibehalten.
+- Fachwerte immer hier pflegen.
+- Bestehende Gruppenstruktur beibehalten.
 - `source_paths` nicht entfernen.
-- Nach Änderungen immer Validate, Regression und Audits ausführen.
+- Nach Änderungen immer Validate, Source-Audit, Pattern-Audit und Regression ausführen.
 
 ### 2.4 `source_paths`
 
-`source_paths` verknüpft einen Wertknoten in `configuration_values` mit seinen alten/effective Config-Pfaden.
+`source_paths` verknüpfen Genre-Werte mit den alten oder effektiven technischen Config-Pfaden.
 
-Auswirkung:
+Sie sind wichtig für:
 
-- Dient Audit, Source-of-Truth-Guard und Migrationsnachvollziehbarkeit.
-- Liefert nicht selbst den Runtime-Wert.
-- Falsche oder unbekannte Pfade erzeugen Validate-/Audit-Probleme.
+- Nachvollziehbarkeit
+- Source-of-Truth-Guardrails
+- Migrationssicherheit
+- Audit-Ausgaben
 
-Anpassen:
-
-- Bei reinen Wertänderungen normalerweise unverändert lassen.
-- Nur ändern, wenn die technische Verdrahtung oder ein Legacy-Pfad wirklich geändert wurde.
-- Wenn ein Wertknoten direkte Payload enthält, muss er selbst oder ein Parent-Knoten `source_paths` deklarieren.
-- Doppelte oder leere `source_paths` sind nicht zulässig.
+Sie liefern nicht selbst den Runtime-Wert. Bei reinen Fachwertänderungen bleiben sie normalerweise unverändert.
 
 ---
 
-## 3. Runtime-Lesemodell
+## 3. Runtime-Lesemodell in v1.6.0
 
-Die wichtigsten Klassen erhalten `GenreConfig` per Dependency Injection und lesen fachliche Werte bevorzugt aus `genre.yaml`:
+Die folgenden Runtime-Klassen lesen fachliche Werte bevorzugt über `GenreConfig` bzw. genregebundene Konfigurationsviews:
 
-| Klasse | Liest aus `genre.yaml` | Typische Wirkung |
-|---|---|---|
-| `DomainVocabularyConfig` | Produktrollen, Vocabulary-Views, Prompt-/Shop-/Retrieval-Views, Maps | Grundvokabular, Shop-/Prompt-Rollen, Evidence-Begriffe |
-| `CommerceQueryParserConfig` | Marken, Canonical-Terms | Query-Normalisierung für Shop-Suche |
-| `QueryEnricherConfig` | Query-Enrichment-Regeln | Erweiterung/Umformung von Suchanfragen |
-| `CommerceIntentConfig` | Commerce-Signale, Größen-/Farb-/Produktmuster | Erkennung von Kauf-, Preis-, Shop- und Beratungsabsicht |
-| `SalesIntentConfig` | Sales-/Vergleichs-/ROI-Signale | Sales-orientierte Intent-Erkennung |
-| `AgentRunnerConfig` | Follow-ups, Shop-Query-Cleanup, Direct Answer, Längenfilter, RAG-Anker | Gesprächskontext, Shop-Fallbacks, direkte Shopantworten |
-| `PromptBuilderConfig` | Antwortpriorität, Formatregeln, Fact-Grounding, Evidence Guards | Qualität und Grenzen der finalen Antwort |
-| `SearchRepairConfig` | Direct-Attribute-Lookup, Kandidatenmuster, Repair-Tokens | Reparatur schwacher Shop-Suchen |
-| `NdjsonHybridRetrieverConfig` | Exact Selection, Indicator-/Tabellenmuster | Präzision bei RAG-Fakten und Tabellenextraktion |
-| `LanguageCleanupConfig` | Protected Terms | Schutz wichtiger Tokens vor Cleanup |
-| `GovernanceConfig` | Regression-/Audit-Guardrails | Schutz vor Regressions- und Core-Listen-Rückfällen |
+| Klasse / Bereich | Typische Genre-Werte | Wirkung |
+| --- | --- | --- |
+| `DomainVocabularyConfig` | Produktrollen, Views, Rollenbegriffe | Geräte-/Zubehörtrennung, Prompt- und Shop-Begriffe |
+| `CommerceQueryParserConfig` | Marken, Canonical Terms, Korrekturen | Shopquery-Normalisierung und Token-Erhalt |
+| `QueryEnricherConfig` | Query-Enrichment-Regeln | Erweiterung oder Fokussierung von Suchanfragen |
+| `CommerceIntentConfig` | Commerce-Signale, Produkt-/Preis-/Shopmuster | Erkennung von Kauf-, Preis- und Shop-Intents |
+| `SalesIntentConfig` | Sales-, Vergleichs-, ROI-Signale | Vertriebsnahe Intent-Erkennung |
+| `AgentRunnerConfig` | Follow-ups, Shopquery-Cleanup, Direct Answer, RAG-Anker | Chatverlauf, Shop-Fallbacks und Antwortsteuerung |
+| `PromptBuilderConfig` | Antwortpriorität, Fact-Grounding, Output-Regeln | Finale Antwortqualität und Grenzen |
+| `SearchRepairConfig` | Repair-Kandidaten, Attribut-Lookup, Zubehörcodes | Reparatur schwacher oder referenzieller Shopanfragen |
+| `NdjsonHybridRetrieverConfig` | Exact Selection, Tabellen-/Indikatormuster | Präzision bei RAG-Fakten und Tabellenextraktion |
+| `LanguageCleanupConfig` | Protected Terms und Cleanup-Profile | Schutz fachlicher Tokens vor Sprachbereinigung |
+| `GovernanceConfig` | Regression- und Audit-Guardrails | Schutz vor Rückfällen in hardcodierte Fachlogik |
 
-Die Legacy-YAMLs sind weiterhin wichtig, aber nicht mehr der primäre Pflegeort für genreabhängige Fachwerte.
+Legacy-YAMLs bleiben als technische Verarbeitungsschicht relevant, sind aber nicht mehr der bevorzugte Pflegeort für neue fachliche Domänenwerte.
 
 ---
 
-## 4. Gruppenübersicht mit Auswirkungen
+## 4. Gruppen in `configuration_values`
 
 ### 4.1 `product_roles`
 
-Zweck: Definiert, welche Begriffe als Hauptprodukt, Zubehör, Verbrauchsmaterial oder produktrollenbezogene Prompt-/Shop-Begriffe gelten.
+Zweck: definiert, welche Begriffe als Hauptprodukt, Zubehör, Verbrauchsmaterial oder rollenbezogene Prompt-/Shop-Begriffe gelten.
 
-Wichtige Werte:
+Wichtige Knoten:
 
-- `primary_product_terms.terms`
-- `accessory_product_terms.terms`
-- `requested_accessory_code_terms.terms`
-- `shop_views.*`
-- `prompt_views.*`
-- `no_llm_fallback_terms.*`
+- `primary_product_terms`
+- `accessory_product_terms`
+- `requested_accessory_code_terms`
+- `shop_views`
+- `prompt_views`
+- `no_llm_fallback_terms`
 
 Auswirkung:
 
-- Entscheidet, ob eine Anfrage eher Gerät/Hauptprodukt oder Zubehör meint.
-- Beeinflusst Shop-Query-Aufbau, Produktrollentrennung und Antwortformat.
-- Verhindert z. B., dass Zubehör als Gerät oder Geräte als Zubehör beantwortet werden.
-- Steuert No-LLM-Fallbacks bei einfachen oder schwach belegten Anfragen.
+- trennt Geräte/Hauptprodukte von Zubehör und Verbrauchsmaterialien
+- beeinflusst Shop-Matching, Promptregeln und No-LLM-Fallbacks
+- verhindert, dass Zubehörfragen als Gerätefragen beantwortet werden
+- schützt Flows wie Indikator/Reagenz/Zubehör gegen falsche Produktrollen
 
 Anpassung:
 
-- Für ein neues Genre zuerst diese Gruppe anpassen.
-- Hauptproduktbegriffe vollständig ersetzen, nicht nur ergänzen.
-- Zubehör- und Verbrauchsmaterialbegriffe getrennt halten.
-- Synonyme, Umlaute und ASCII-Varianten aufnehmen, wenn Nutzer sie realistisch verwenden.
-- Keine zu allgemeinen Wörter wie `produkt`, `artikel`, `teil` allein als starke Rollenbegriffe verwenden, sonst steigt Fehlrouting.
+- Für ein neues Genre zuerst diese Gruppe überarbeiten.
+- Hauptprodukt- und Zubehörbegriffe getrennt halten.
+- Realistische Nutzerbegriffe, Umlaute und ASCII-Varianten aufnehmen.
+- Keine zu generischen Wörter wie `produkt`, `artikel` oder `teil` als starke Rollenbegriffe verwenden.
 
 Beispiel Wasseranalyse:
 
@@ -174,537 +176,424 @@ accessory_product_terms:
     - zubehör
 ```
 
-Beispiel Umwidmung Fashion:
-
-```yaml
-primary_product_terms:
-  terms:
-    - shirt
-    - hose
-    - jacke
-    - schuh
-accessory_product_terms:
-  terms:
-    - gürtel
-    - tasche
-    - pflegeset
-```
-
----
-
 ### 4.2 `product_attributes`
 
-Zweck: Definiert genreabhängige Attribute und Constraints, z. B. Kabellänge, Messgröße, Größe, Farbe oder Material.
+Zweck: definiert fachliche Attribute, Constraints und Vergleichsmuster.
 
-Wichtige Werte:
+Wichtige Knoten:
 
 - `direct_attribute_cleanup.product_type_terms`
 - `direct_attribute_cleanup.stop_terms`
 - `direct_attribute_cleanup.comparative_constraint_patterns`
-- `size_and_color_terms.*`
-- `numeric_length_constraints.length_sort.*`
-- `numeric_length_constraints.length_filter.*`
+- `size_and_color_terms`
+- `numeric_length_constraints`
 
 Auswirkung:
 
-- Beeinflusst direkte Produktattribut-Suchen wie „Anschlusskabel länger 20m“.
-- Steuert, welche Wörter nach Cleanup übrig bleiben müssen, damit Search Repair greift.
-- Aktiviert Sortierung oder Filterung nach numerischen Längen-/Größenwerten.
-- Commerce-Intent erkennt Größe/Farbe/Varianten besser oder schlechter abhängig von diesen Listen.
+- ermöglicht direkte Attributfragen wie „Anschlusskabel länger 20 m“
+- steuert Cleanup vor Search Repair
+- unterstützt Sortier-/Filterlogik für numerische Längen oder Größen
+- kann für andere Genres auf Größe, Farbe, Material, Spannung, Gewinde, Kompatibilität usw. umgewidmet werden
 
 Anpassung:
 
-- Produktartbegriffe an das Genre anpassen, z. B. `anschlusskabel` durch `sneaker`, `sofa`, `akku`, `ersatzfilter` ersetzen.
-- Stop-Terme nur für Bedienwörter verwenden, nicht für fachliche Kernbegriffe.
-- Regex-Patterns vorsichtig ändern und mit realen Anfragen testen.
-- Für Fashion Größen/Farben ausbauen; für Ersatzteile eher Maße, Kompatibilität, Seriennummern, Gewinde, Spannung usw. pflegen.
-
-Achtung:
-
-- `nicht`, `kein`, Modellkürzel und fachliche Kurzbegriffe dürfen nicht versehentlich als Stopword entfernt werden.
-- Numerische Patterns müssen Einheiten passend zum Genre abbilden. Bei Fashion wäre `cm`, `inch`, `EU`, `UK`; bei Kabeln `m`, `meter`.
-
----
+- Fachliche Produktartbegriffe austauschen, nicht nur ergänzen.
+- Stop-Terme nur für Bedienwörter verwenden.
+- Regex-Muster vorsichtig ändern und mit echten Prompts testen.
 
 ### 4.3 `brands_and_canonical_terms`
 
-Zweck: Pflegt Marken, Token-Normalisierung, Synonyme und Query-Enrichment.
+Zweck: pflegt Marken, Kanonisierungen, Schreibweisen und semantische Synonyme.
 
-Wichtige Werte:
+Wichtige Knoten:
 
-- `known_brands.terms`
-- `canonical_terms.map`
-- `query_enrichment_rules.rules`
-- `accessory_focus_variants.map`
-- `rag_evidence_synonyms.map`
+- `known_brands`
+- `canonical_terms`
+- `query_enrichment_rules`
+- `accessory_focus_variants`
+- `rag_evidence_synonyms`
 
 Auswirkung:
 
-- Marken werden in Shop-Queries und Query-Parsing besser erkannt.
-- Plural-/Sprachvarianten werden auf kanonische Suchbegriffe zurückgeführt.
-- Query-Enrichment ergänzt fachlich sinnvolle verwandte Suchbegriffe.
-- Evidence-Guards verstehen Synonyme besser.
+- schützt Markennamen und Modellfamilien in Shopqueries
+- normalisiert Tippfehler oder Schreibvarianten
+- hält direkte Produktnamen wie `chlor select sensor` oder Modellkürzel wie `testomat lab cl` stabil
+- unterstützt RAG-Evidence-Abgleich über Synonyme
 
 Anpassung:
 
-- Markenliste shop- und genrebezogen pflegen.
-- Canonical Map nur für eindeutige Äquivalenzen verwenden.
-- Query-Enrichment nicht als Ranking-Hack missbrauchen; nur semantisch nahe Begriffe ergänzen.
-- Synonyme nicht mit Nicht-Äquivalenten mischen.
-
-Beispiel:
-
-```yaml
-canonical_terms:
-  map:
-    reagenzien: reagenz
-    indicators: indikator
-```
-
-Für Fashion:
-
-```yaml
-canonical_terms:
-  map:
-    sneakers: sneaker
-    shirts: shirt
-    t-shirts: tshirt
-```
-
----
+- Nur etablierte Synonyme und klare Korrekturen eintragen.
+- Keine aggressiven Kanonisierungen, die Varianten zusammenwerfen.
+- Kürzel wie `CL`, `TH`, `SIO2`, `LAB CL` immer gegen Regression testen.
 
 ### 4.4 `intent_and_routing`
 
-Zweck: Steuert, ob eine Anfrage als Shop-, Preis-, Beratungs-, Produktwahl-, Vergleichs- oder Sales-Anfrage erkannt wird.
+Zweck: enthält fachliche Werte für Commerce-, Sales- und Routing-Erkennung.
 
-Wichtige Werte:
+Wichtige Knoten:
 
-- `fuzzy_routing_terms.terms`
-- `commerce_intent.strong_signals`
-- `commerce_intent.advisory_signals`
-- `commerce_intent.advisory_product_selection_patterns`
-- `commerce_intent.explicit_commerce_intent_patterns`
-- `commerce_intent.model_like_product_pattern`
-- `sales_intent.*`
+- `fuzzy_routing_terms`
+- `commerce_intent`
+- `sales_intent`
 
 Auswirkung:
 
-- Entscheidet, ob Shop-Suche gestartet wird.
-- Erkennt Follow-ups wie „suche im shop“ oder „was kostet das“.
-- Unterscheidet Beratung von reiner Wissensfrage.
-- Beeinflusst, wann Produktlisten, Preise oder Produktempfehlungen erzeugt werden.
+- erkennt Preis-, Shop-, Produkt-, Beratungs- und Vergleichsfragen
+- trennt technische Wissensfragen von Produkt-/Kaufintents
+- verhindert, dass reine Fachfragen unnötig zu Shop-Suchen werden
 
 Anpassung:
 
-- Shop-/Preis-/Kaufbegriffe meist generisch belassen.
-- Produktwahlmuster genrebezogen anpassen, z. B. `mit welchem testomat` durch `welche jacke`, `welcher akku`, `welches ersatzteil` ersetzen.
-- `model_like_product_pattern` nur ändern, wenn Modell-/SKU-Struktur im neuen Genre anders ist.
-- Sales-Signale nur anpassen, wenn die Installation tatsächlich Sales-/B2B-Beratung leisten soll.
-
-Risiko:
-
-- Zu breite starke Commerce-Signale führen dazu, dass Wissensfragen fälschlich als Shop-Anfragen behandelt werden.
-- Zu enge Muster verhindern gewünschte Shop-Follow-ups.
-
----
+- Starke Shopbegriffe und Beratungssignale sauber trennen.
+- Branchen- oder Anwendungskontexte nicht automatisch als Produktbeweis behandeln.
+- Für neue Genres typische Kauf-/Vergleichs-/Beratungswörter ergänzen.
 
 ### 4.5 `context_resolution`
 
-Zweck: Löst referenzielle Folgefragen und baut aus dem Verlauf sinnvolle Shop-Queries.
+Zweck: löst referenzielle Folgefragen aus Chatverlauf und sichtbaren Antworten auf.
 
-Wichtige Werte:
+Wichtige Knoten:
 
-- `commercial_table_follow_up.*`
-- `referential_terms.terms`
-- `history_anchor_enrichment.*`
-- `meta_query_guard.*`
-- `rag_anchor_enrichment.*`
+- `commercial_table_follow_up`
+- `referential_terms`
+- `history_anchor_enrichment`
+- `product_list_followup`
+- `meta_query_guard`
+- `rag_anchor_enrichment`
 
-Auswirkung:
+Auswirkung in v1.6.0:
 
-- „Was kostet der Indikator?“ kann aus vorherigem Kontext `Indikatortyp 300` ableiten.
-- „Suche im Shop“ kann aus einer vorherigen Produktempfehlung eine konkrete Shop-Suche erzeugen.
-- Meta-only-Anfragen wie `shop`, `preis`, `kosten` werden nicht verworfen, wenn brauchbarer Verlaufskontext existiert.
-- Numerische RAG-Anker wie `0,02 °dH` können mit Produktankern kombiniert werden.
+- Folgefragen wie „was kostet der indikator“ können den letzten Geräte-/Indikatoranker nutzen.
+- Produktlisten-Follow-ups wie „gib mir Links zu den Produkten“ können sichtbare Produktnamen extrahieren.
+- Mehrprodukt-Follow-ups werden auf einzelne Produktanker vorbereitet.
+- Schwache Shopfragen wie „suche im Shop nach der Information“ können auf konkrete History-Anker zurückfallen.
+- RAG-Anker wie Messwerte und Produkttitel helfen, Folgefragen fachlich zu fokussieren.
 
 Anpassung:
 
-- `history_anchor_patterns` und `anchor_patterns` an typische Modell-, Zubehör- oder Variantenanker des Genres anpassen.
-- `query_template_with_model` und `query_template_without_model` nur ändern, wenn Referenzauflösung anders formuliert werden soll.
-- `meta_only_terms` generisch halten, aber `context_fallback_filter_terms` genrebezogen prüfen.
-- `rag_anchor_enrichment.subject_terms` an fachliche Kernthemen des Genres anpassen.
-
-Beispiel Wasseranalyse:
-
-```yaml
-query_template_with_model: '{model} indikator'
-query_template_without_model: 'indikator'
-```
-
-Für Ersatzteile könnte es z. B. werden:
-
-```yaml
-query_template_with_model: '{model} ersatzteil'
-query_template_without_model: 'ersatzteil'
-```
-
----
+- `referential_terms` sind Pronomen/Füllwörter, keine Produktbegriffe.
+- `product_list_followup.anchor_patterns` müssen konkrete Produktidentitäten erfassen.
+- `meta_query_guard` sollte Bedien-/Meta-Wörter enthalten, die nicht als Suchinhalt dominieren dürfen.
+- Bei neuen Produktfamilien entsprechende `canonical_family_terms` und Startmuster ergänzen.
 
 ### 4.6 `shop_query_runtime`
 
-Zweck: Steuert Shop-Query-Cleanup, direkte Shopantworten, semantische Suchbegriffe und Ergebnisidentität.
+Zweck: steuert, welche Tokens in Shopqueries erhalten, entfernt, positiv gefiltert oder zu konkreten Produktankern repariert werden.
 
-Wichtige Werte:
+Wichtige Knoten:
 
-- `current_input_preservation_terms.terms`
-- `semantic_shop_search_tokens.terms`
-- `stopword_cleanup.terms`
-- `compound_prefix_match.terms`
-- `primary_identity_repair.stop_terms`
-- `direct_answer.*`
+- `current_input_preservation_terms`
+- `stopword_cleanup`
+- `positive_token_filter`
+- `generic_device_anchor`
+- `compound_prefix_match`
+- `primary_identity_repair`
+- `semantic_shop_search_tokens`
+- `direct_answer`
 
-Auswirkung:
+Auswirkung in v1.6.0:
 
-- Bestimmte kurze Begriffe wie `pH`, `rx`, `orp` bleiben in Shop-Queries erhalten.
-- Semantische Shop-Suchbegriffe verbessern Query-Erweiterung.
-- Stopword-Cleanup entfernt Bedienwörter aus Shop-Queries.
-- Direct Answer bestimmt, wie Shop-Ergebnisse direkt textlich ausgegeben werden.
+- Relationsrauschen wie „erreicht“, „gemessen“, „beim“ oder reine Bedienwörter wird entfernt.
+- Korrigierte Tokens aus der Commerce-Konfiguration bleiben in der finalen Query erhalten.
+- Modellkürzel wie `LAB CL`, `THCL`, `CLT`, `SIO2` werden über positive Filter und Nachbarschaftsregeln geschützt.
+- Generische Gerätefragen können auf konkrete YAML-konfigurierte Geräteanker wie `testomat 808 sio2` geführt werden.
+- Self-Loops bei identischen Folgeaktionsqueries können unterdrückt werden.
 
 Anpassung:
 
-- Für jedes neue Genre kurze geschützte Produkt-/Attributtokens eintragen, z. B. `xl`, `usb-c`, `m8`, `a4`, sofern relevant.
-- Stopwords nicht mit Produktkürzeln vermischen.
-- Direct-Answer-Texte an Tonalität und Produktdomäne anpassen.
-- `max_results` so wählen, dass Antworten nicht überladen werden.
-
-Achtung:
-
-- Wenn ein wichtiger kurzer Begriff nicht geschützt ist, kann er beim Cleanup verschwinden.
-- Wenn zu viele allgemeine Begriffe geschützt sind, werden Shop-Queries unscharf.
-
----
+- `allowed_terms` und `blocked_terms` immer zusammen prüfen.
+- `adjacent_variant_terms` nur für echte Modell-/Variantentokens verwenden.
+- `generic_device_anchor.anchor_rules` ist der richtige Ort für domainnahe Gerät-Parameter-Anker, nicht PHP-Core.
+- Stopwords niemals so breit wählen, dass Produktnamen oder Messparameter verloren gehen.
 
 ### 4.7 `result_identity_and_answer_policy`
 
-Zweck: Definiert Prompt-Regeln, Antwortpriorität, Produktrollen-Trennung und Evidence-Guards.
+Zweck: definiert Antwortregeln, Prompt-Prioritäten, Evidence Guards und Ergebnisidentität.
 
-Wichtige Werte:
+Wichtige Knoten:
 
 - `prompt_rules.output_priority_technical`
 - `prompt_rules.response_format_technical`
 - `prompt_rules.response_format_accessory`
 - `prompt_rules.fact_grounding_technical`
 - `prompt_rules.fact_grounding_with_shop`
-- `prompt_keyword_views.technical_product_keywords`
-- `measurement_evidence_guard_terms.*`
-- `measurement_evidence_maps.*`
+- `prompt_keyword_views`
+- `measurement_evidence_guard_terms`
+- `measurement_evidence_maps`
 
 Auswirkung:
 
-- Bestimmt, welche Fakten in technischen Antworten priorisiert werden.
-- Verhindert, dass Eigenschaften eines Produkts einem anderen Produkt zugeschrieben werden.
-- Steuert die Trennung zwischen Gerät/Hauptprodukt und Zubehör/Verbrauchsmaterial.
-- Sichert, dass Messfähigkeit, Zubehörbezug oder Attributbelege nur beantwortet werden, wenn sie belegt sind.
+- technische Fakten werden exakt und quellennahe beantwortet
+- niedrigste/höchste Grenzwerte bleiben auf den Primärfakt fokussiert
+- Indikator-/Reagenzfragen werden nicht mit anderen Varianten vermischt
+- Produktselektion mit Shopdaten bleibt an Produktidentität, Produktnummer und explizite Evidence gebunden
+- nicht belegte Informationen sollen als „Nicht bekannt.“ formuliert werden
 
 Anpassung:
 
-- Antwortregeln domänenspezifisch, aber knapp und testbar formulieren.
-- Evidence-Maps für echte fachliche Mess-/Attributdimensionen pflegen.
-- Nicht-Äquivalenzen explizit halten, z. B. `freies Chlor` ist nicht automatisch `Gesamtchlor`.
-- Für ein anderes Genre positive und negative Kontextbegriffe neu definieren.
-
-Beispiel:
-
-```yaml
-measurement_evidence_maps:
-  request_terms:
-    redox:
-      - redox
-      - orp
-  non_equivalent_terms:
-    free_chlorine:
-      - Gesamtchlor
-```
-
-Für Fashion könnte eine analoge Struktur z. B. Größen-/Material-/Passform-Evidence absichern.
-
----
+- Promptregeln kurz, eindeutig und testbar halten.
+- Keine Vertriebsversprechen aufnehmen, die aus Quellen nicht belegbar sind.
+- Bei neuen Messparametern `measurement_evidence_maps` erweitern.
+- Exakte Code- und Variantenregeln immer mit Zubehör-/Preisflows testen.
 
 ### 4.8 `search_repair`
 
-Zweck: Repariert schwache oder zu kurze Shop-Suchen und extrahiert Modell-/Zubehör-/Spezifitätskandidaten.
+Zweck: repariert schwache Shopqueries und direkte Attributsuchen.
 
-Wichtige Werte:
+Wichtige Knoten:
 
-- `direct_product_attribute_lookup.*`
-- `candidate_patterns.specific_model_candidate_patterns`
-- `candidate_patterns.patterns.*`
-- `candidate_terms.*`
+- `direct_product_attribute_lookup`
+- `requested_accessory_code_terms`
+- `candidate_patterns`
+- `candidate_terms`
 
 Auswirkung:
 
-- Verbessert Suche, wenn die primäre Shop-Suche zu wenig oder falsche Ergebnisse liefert.
-- Erkennt Modellkandidaten, Zubehörcodes, Bundle-/Accessory-Begriffe und Spezifitätsanker.
-- Hilft bei Fällen wie direkten Produktattributfragen oder unvollständigen Shop-Follow-ups.
+- erkennt spezifische Modell-/Zubehörkandidaten
+- hält exakte Zubehörcodes wie `300` getrennt von Varianten wie `300 S`
+- unterstützt reparierte Queries bei fehlenden oder schwachen Primärtreffern
+- hilft bei Follow-ups, die nur „Preis“, „Shop“ oder „Information“ enthalten
 
 Anpassung:
 
-- Candidate-Terms an das Genre anpassen.
-- Regex nur ändern, wenn Modell-/SKU-/Zubehörcode-Struktur wirklich anders ist.
-- `min_query_tokens_after_cleanup` nicht zu niedrig setzen, sonst repariert das System sehr unspezifische Anfragen.
-- Accessory-Code-Muster für neue Domänen neu modellieren, z. B. Ersatzteilnummern, DIN-/Normteile, SKU-Formate.
-
-Regex-Hinweis:
-
-- Patterns sind Strings wie `'/.../iu'`.
-- YAML-Quoting beibehalten.
-- Nach Änderung immer Syntax und Regression testen.
-
----
+- Regexe nicht auf einzelne Produkte hart verdrahten.
+- Code-Muster so definieren, dass Varianten nur bei expliziter Nutzereingabe gematcht werden.
+- Generische Kandidatentokens knapp halten, sonst entstehen breite Shoptreffer.
 
 ### 4.9 `retrieval_and_language`
 
-Zweck: Schützt wichtige Sprache-/Fachbegriffe und steuert genreabhängige Retrieval-Hilfen.
+Zweck: verbindet Genre-Werte mit Retrieval- und Sprachbereinigung.
 
-Wichtige Werte:
+Wichtige Knoten:
 
-- `protected_terms.terms`
-- `cleanup_profiles.*`
-- `retrieval_vocabulary_views.*`
-- `exact_selection.*`
+- `protected_terms`
+- `cleanup_profiles`
+- `retrieval_vocabulary_views`
+- `exact_selection`
 
 Auswirkung:
 
-- Protected Terms verhindern, dass wichtige Wörter beim Cleanup entfernt werden.
-- Retrieval-Vocabulary hilft, Dokumenttypen, Geräte, Reagenzien/Zubehör oder Produkttexte zu erkennen.
-- Exact Selection verbessert gezielte Tabellen-/Faktauswahl, z. B. Indikatortabellen.
-- Falsche Werte hier können RAG-Fakten, Follow-up-Präzision und Tabellenextraktion deutlich verschlechtern.
+- schützt kurze technische Tokens vor Stopword-Cleanup
+- sichert RAG-Evidence- und Retrieval-Referenz-Cleanup
+- unterstützt exakte Auswahl bei Tabellen, Grenzwerten und Indikatormappings
 
 Anpassung:
 
-- Protected Terms mit kurzen, wichtigen Tokens des Genres füllen.
-- Cleanup-Profile nur vorsichtig ändern; allgemeine Sprachbereinigung gehört weiter in `language.yaml`, fachlicher Schutz in `genre.yaml`.
-- `looks_like_*`-Listen an Dokument- und Produkttypen des neuen Genres anpassen.
-- Exact-Selection-Bereiche nur verwenden, wenn das Genre ähnliche strukturierte Tabellen-/Faktmuster hat.
-
-Achtung:
-
-- Negationen wie `nicht`, `kein`, `keine` schützen.
-- Kurze Modell- oder Fachkürzel schützen, z. B. `pH`, `rx`, `th`; in anderen Genres z. B. `XL`, `USB`, `M8`.
-
----
+- Kurze Modell-/Messparameter-Tokens in Protected-Term-Listen absichern.
+- Cleanup-Profile nicht durch alte Legacy-Stopword-Listen ersetzen.
+- Exact-Selection-Regeln bei Tabellenfragen mit Regression testen.
 
 ### 4.10 `shop_data_mapping`
 
-Zweck: Beschreibt, wie Shopware-Felder und Produkttexte für diese Installation interpretiert werden.
+Zweck: beschreibt fachliche Shopdaten-Zuordnung und Shop-Matching-Rollen.
 
-Wichtige Werte:
+Wichtige Knoten:
 
-- `custom_fields.primary`
-- `custom_fields.secondary`
-- `custom_fields.use_cases`
-- `custom_fields.languages`
-- `text.*`
-- `role_guard.*`
-- `commerce_connection.*`
+- `custom_fields`
+- `text`
+- `role_guard`
+- `commerce_connection`
 
 Auswirkung:
 
-- Bestimmt, welche Shopware-Custom-Fields für Produktbeschreibung, Attribute, Einsatzgebiete oder Sprache genutzt werden.
-- Textlabels beeinflussen die Darstellung/Interpretation von Shopdaten.
-- Role Guard filtert Zubehör bei Geräteanfragen bzw. hält ambige Produkte bei Geräteanfragen.
-- Store-API-URL und max results sind runtime-/env-aufgelöste Pfade und im Guard explizit erlaubt.
+- mappt Shopware-Custom-Fields auf Antwortfelder
+- steuert Geräte-/Zubehörfilterung im Shop-Matching
+- entscheidet, wann Shopdaten als kommerzielle Felder priorisiert werden
 
 Anpassung:
 
-- Bei anderem Shopdatenmodell zuerst `custom_fields` prüfen.
-- Labels an Shopdaten anpassen, aber nicht mit Prompt-Regeln verwechseln.
-- Role Guard nur ändern, wenn die Produktdaten sauber zwischen Hauptprodukt und Zubehör unterscheiden.
-- Credentials und technische Verbindungswerte nicht hart in `genre.yaml` eintragen; ENV-Referenzen beibehalten.
-
----
+- Feldnamen an den realen Shopware-Datenbestand anpassen.
+- Rollenfilter nicht so hart setzen, dass Zubehör-/Bundle-Treffer verschwinden.
+- Shopdaten dürfen technische Eignung nur belegen, wenn der Produktdatensatz sie explizit nennt.
 
 ### 4.11 `governance_and_regression`
 
-Zweck: Schützt das aktive Genre durch Regression-Baselines und Audit-Regeln.
+Zweck: hält Regression- und Audit-Anker für stabile Flows.
 
-Wichtige Werte:
+Wichtige Knoten:
 
-- `regression_baseline.*`
+- `regression_baseline`
 - `vocabulary_guardrails`
-- `core_pattern_audit.*`
+- `core_pattern_audit`
 
 Auswirkung:
 
-- Regressionstests wissen, welche Kurzmodelle, Messwerte, fachlichen Keywords und Shop-Query-Fälle geschützt sind.
-- Pattern-Audit erkennt, wenn wieder harte Fachlisten in PHP-Code oder falsche Config-Pfade wandern.
-- Verhindert Rückfälle in Core-Keywordlisten.
+- schützt zentrale 1.4.x/1.5.x/1.6.0-Flows
+- bewahrt kurze Modell-/Parameter-Tokens
+- verhindert Rückfälle in neue fachliche PHP-Hardcodings
+- macht verdächtige Pattern-/Token-Nutzung im Core reviewbar
 
 Anpassung:
 
-- Bei Genre-Umwidmung Regression-Baseline konsequent austauschen.
-- Keine alten Wasseranalyse-Werte stehen lassen, wenn sie für das neue Genre nicht gelten.
-- `core_pattern_audit.domain_marker_terms` mit neuen Fachmarkern füllen, damit Audit Rückfälle erkennt.
-- Technische Audit-Ausnahmen nur erweitern, wenn wirklich nötig und mit Begründung.
+- Neue stabile Kunden-/Testflows als Regression-Anker ergänzen.
+- Domain Marker Terms aktuell halten.
+- Audit-Ausnahmen nur für technische Parserlogik zulassen, nicht für fachliche Sonderfälle.
 
 ---
 
-## 5. Source-of-Truth-Guard
+## 5. Wichtige v1.6.0-Guardrails
 
-Der Guard wird über `config/retriex/governance.yaml` gesteuert:
+### 5.1 Exakte Zubehör- und Indikatorcodes
 
-```yaml
-genre_source_of_truth:
-  enabled: true
-  source: genre.yaml
-  legacy_mode: frozen_or_empty_fallback
-```
+Ein konkreter Code wie `300` darf nicht automatisch Varianten wie `300 S`, `301` oder `302` einschließen. Varianten sind nur erlaubt, wenn die Nutzerfrage sie explizit nennt oder die Quelle denselben Produktdatensatz eindeutig damit verbindet.
 
-Er prüft:
+Relevant sind insbesondere:
 
-1. `genre.configuration_values` ist vorhanden und nicht leer.
-2. Jede `adaptation_surface`-Gruppe hat eine passende `configuration_values`-Gruppe.
-3. Jeder relevante Wertknoten ist durch `source_paths` abgedeckt.
-4. Alle `source_paths` zeigen auf bekannte Config-Pfade.
-5. Alte Legacy-Pfade sind entweder leer, runtime-aufgelöst erlaubt oder per SHA-256-Hash eingefroren.
-6. Wenn ein eingefrorener Legacy-Wert geändert wird, schlägt Validate/Audit fehl.
+- `product_roles.requested_accessory_code_terms`
+- `search_repair.requested_accessory_code_terms`
+- `search_repair.candidate_patterns`
+- `result_identity_and_answer_policy.prompt_rules`
 
-Bedeutung für die Pflege:
+### 5.2 Geräteanker bei referenziellen Shopfragen
 
-- Fachliche Werte in `genre.yaml` ändern.
-- Legacy-Werte nicht parallel ändern.
-- Wenn ein Legacy-Pfad absichtlich nicht leer bleiben muss, braucht er einen bewussten Hash-Eintrag in `governance.yaml`.
-- Wenn ein neuer Runtime-Pfad genreabhängig wird, muss er in `adaptation_surface`, `configuration_values.source_paths` und ggf. in die Guard-Logik aufgenommen werden.
+Bei Follow-ups wie „was kostet der indikator“ muss der konkrete Verlaufskontext erhalten bleiben, z. B. Gerät + Indikatortyp. `indikatortyp` ist Kontextsignal, darf aber nicht allein die Shopquery dominieren.
+
+Relevant sind:
+
+- `context_resolution.history_anchor_enrichment`
+- `context_resolution.commercial_table_follow_up`
+- `shop_query_runtime.positive_token_filter`
+- `shop_query_runtime.stopword_cleanup`
+
+### 5.3 Produktlisten- und Link-Follow-ups
+
+Bei Fragen wie „gib mir Links zu den Produkten“ soll RetrieX sichtbare Produktanker aus der vorherigen Antwort verwenden und Mehrproduktlisten in Einzelqueries aufteilen.
+
+Relevant sind:
+
+- `context_resolution.product_list_followup.enabled`
+- `context_resolution.product_list_followup.anchor_patterns`
+- `context_resolution.product_list_followup.max_anchors`
+- `context_resolution.product_list_followup.template`
+
+### 5.4 Schwache History-/Meta-Fragen
+
+Meta-Fragen wie „suche im Shop nach der Information“ enthalten kaum Produktsubstanz. v1.6.0 darf dann auf den letzten konkreten Produktanker aus der History zurückfallen, statt `information` als Shopquery zu senden.
+
+Relevant sind:
+
+- `context_resolution.meta_query_guard`
+- `context_resolution.product_list_followup.noise_terms`
+- `shop_query_runtime.stopword_cleanup`
+
+### 5.5 Generische Device-Parameter-Anker
+
+Fragen wie „Gerät für Silikatüberwachung“ können auf konkrete konfigurierbare Anker wie `testomat 808 sio2` geführt werden. Diese Abbildung gehört in YAML, nicht als Sonderlogik in PHP.
+
+Relevant ist:
+
+- `shop_query_runtime.generic_device_anchor.anchor_rules`
 
 ---
 
 ## 6. Sichere Änderungsreihenfolge
 
-### Kleine Wertänderung innerhalb des aktuellen Genres
+### Kleine Wertänderung
 
-1. Passende Gruppe in `configuration_values` finden.
-2. Nur dort Werte ändern.
+1. Passenden Knoten in `configuration_values` suchen.
+2. Wert ändern oder ergänzen.
 3. `source_paths` unverändert lassen.
-4. YAML-Syntax prüfen.
-5. Pflichtchecks ausführen.
-6. Relevante manuelle Regression mit realen Beispielanfragen testen.
+4. Config und Regression prüfen.
 
 ### Neues Synonym oder neue Marke
 
-1. Prüfen, ob es ein Rollenbegriff, Attribut, Canonical Term oder Query-Enrichment ist.
-2. In der passenden Gruppe ergänzen:
-   - Marke: `brands_and_canonical_terms.known_brands.terms`
-   - Synonym mit echter Gleichwertigkeit: `canonical_terms.map`
-   - Query-Erweiterung: `query_enrichment_rules.rules`
-   - Evidence-Synonym: `rag_evidence_synonyms.map`
-3. Keine Duplikate in Legacy-YAMLs eintragen.
-4. Shop- und RAG-Testfälle ausführen.
+1. `brands_and_canonical_terms` prüfen.
+2. Falls Shopquery-relevant: `shop_query_runtime.positive_token_filter.allowed_terms` prüfen.
+3. Falls Retrieval-/Prompt-relevant: `retrieval_and_language.protected_terms` oder passende Vocabulary-Views prüfen.
+4. Gegen echte Prompts testen.
 
-### Neues Attribut oder Constraint
+### Neues Zubehör oder Verbrauchsmaterial
 
-1. Produkt-/Attributbegriff in `product_attributes.direct_attribute_cleanup.product_type_terms` aufnehmen.
-2. Wenn nötig Cleanup-Stopterms prüfen.
-3. Vergleichs-/Filterpattern nur ergänzen, wenn echte Nutzerformulierungen vorliegen.
-4. Wenn das Attribut in Antworten belegt werden muss, zusätzlich `result_identity_and_answer_policy` prüfen.
-5. Tests mit positiver und negativer Anfrage ausführen.
+1. `product_roles.accessory_product_terms` ergänzen.
+2. `product_roles.requested_accessory_code_terms` prüfen.
+3. `result_identity_and_answer_policy.response_format_accessory` prüfen.
+4. Shopquery- und Preis-Follow-up testen.
 
-### Umwidmung auf ein neues Genre
+### Neues Geräte-/Parameter-Mapping
 
-Empfohlene Reihenfolge:
+1. `shop_query_runtime.generic_device_anchor.anchor_rules` ergänzen.
+2. `brands_and_canonical_terms.canonical_terms` prüfen.
+3. `result_identity_and_answer_policy.measurement_evidence_maps` ergänzen, falls technische Evidence betroffen ist.
+4. `mto:agent:test:shop-search` und `mto:agent:retrieval:test` ausführen.
+
+### Umwidmung auf neues Genre
 
 1. `id`, `label`, `description` ändern.
-2. `product_roles` vollständig neu definieren.
-3. `product_attributes` neu definieren.
-4. `brands_and_canonical_terms` austauschen.
-5. `intent_and_routing` auf neue Produktsprache anpassen.
-6. `context_resolution` auf neue Verlaufanker umstellen.
-7. `shop_query_runtime` und geschützte Kurzbegriffe anpassen.
-8. `result_identity_and_answer_policy` neu formulieren.
-9. `search_repair` für neue Modell-/SKU-/Zubehörmuster anpassen.
-10. `retrieval_and_language` auf neue Dokument-/Produktbegriffe umstellen.
-11. `shop_data_mapping` an Shopware-Felder prüfen.
-12. `governance_and_regression` komplett neu setzen.
-13. Tests und Audits ausführen.
-
-Wichtig: Nicht nur neue Werte ergänzen, sondern alte Wasseranalyse-spezifische Werte entfernen, wenn sie im neuen Genre keine Bedeutung haben. Sonst bleiben falsche Anker aktiv.
+2. `product_roles` vollständig ersetzen.
+3. Attribute, Marken, Synonyme und Intents ersetzen.
+4. Shopquery-Runtime und Search Repair neu fachlich definieren.
+5. Promptregeln neutralisieren und danach genrebezogen ergänzen.
+6. Regression-Baseline für das neue Genre aufbauen.
+7. Alte Wasseranalyse-Tokens aus Guardrails entfernen, sofern nicht mehr gültig.
 
 ---
 
 ## 7. Pflichtchecks nach Änderungen
 
-Im Projekt mit installiertem `vendor/` ausführen:
+Nach jeder fachlichen Änderung an `genre.yaml` mindestens ausführen:
 
 ```bash
-bin/console cache:clear
-bin/console mto:agent:config:validate
-bin/console mto:agent:regression:test
-bin/console mto:agent:config:audit-source --details
-bin/console mto:agent:config:audit-patterns --details
+php bin/console mto:agent:config:validate
+php bin/console mto:agent:config:audit-source --details
+php bin/console mto:agent:config:audit-patterns --details
+php bin/console mto:agent:regression:test
 ```
 
-Zusätzlich sinnvoll:
+Für Review/CI zusätzlich möglich:
 
 ```bash
-php -l src/Config/GenreConfig.php
-python3 - <<'PY'
-import yaml
-from pathlib import Path
-for path in Path('config/retriex').glob('*.yaml'):
-    yaml.safe_load(path.read_text())
-print('YAML parse OK')
-PY
+php bin/console mto:agent:config:dump-effective --summary
+php bin/console mto:agent:config:validate --json
+php bin/console mto:agent:regression:test --json
 ```
 
-Hinweis: In der entpackten ZIP liegt kein `vendor/`, deshalb sind die `bin/console`-Checks dort nicht lokal ausführbar. Sie müssen im echten Projektstand mit Dependencies laufen.
+Für praktische Query-Tests:
+
+```bash
+php bin/console mto:agent:retrieval:test "niedrigster Grenzwert Wasserhärte"
+php bin/console mto:agent:test:shop-search "testomat 808 300 indikator" --repair
+php bin/console mto:agent:chat cli-debug
+```
 
 ---
 
-## 8. Typische Fehler und Auswirkungen
+## 8. Typische Fehlerbilder
 
-| Fehler | Auswirkung | Korrektur |
-|---|---|---|
-| Fachliche Werte in Legacy-YAML ergänzt | Source-of-Truth-Guard kann brechen; doppelte Pflege kehrt zurück | Wert nach `genre.yaml` verschieben, Legacy leer/eingefroren lassen |
-| `source_paths` entfernt | Validate/Audit meldet fehlende Abdeckung | `source_paths` am Wertknoten oder Parent wiederherstellen |
-| Allgemeines Wort als starkes Rollenwort | Falsches Routing, unscharfe Shop-Suche | Nur fachlich trennscharfe Begriffe verwenden |
-| Wichtiges Kürzel nicht geschützt | Query-Cleanup entfernt es; Shop/RAG verliert Präzision | In `protected_terms` oder `current_input_preservation_terms` aufnehmen |
-| Regex falsch escaped | Runtime-/Validate-Fehler oder keine Treffer | YAML-Quoting und Regex-Syntax prüfen |
-| Alte Genrebegriffe bei Umwidmung behalten | Antworten/Shopqueries driften ins alte Genre | Alte Listen aktiv bereinigen |
-| Negationen als Stopwords entfernt | Antworten können semantisch falsch werden | `nicht`, `kein`, `keine` schützen |
-| Query-Enrichment zu breit | Shop-Suche findet falsche Produkte | Nur echte fachliche Nähe ergänzen |
-| Evidence-Synonyme zu breit | Eigenschaften werden falsch übertragen | Synonyme und Nicht-Äquivalenzen sauber trennen |
+| Änderung | Möglicher Fehler |
+| --- | --- |
+| Fachbegriff nur in PHP ergänzt | Audit findet neue hardcodierte Semantik oder spätere Updates verlieren den Wert. |
+| `blocked_terms` zu breit | Produkt-/Parameter-Tokens verschwinden aus Shopqueries. |
+| `allowed_terms` zu eng | Modellkürzel wie `LAB CL` oder `SIO2` fallen auf generische Begriffe zurück. |
+| Zubehörbegriff als Hauptprodukt gepflegt | Zubehörfragen werden als Gerätefragen beantwortet. |
+| Exakte Code-Regel zu weich | `300` zieht Varianten wie `300 S` oder andere Codes in die Antwort. |
+| Product-list Patterns zu breit | Follow-ups erzeugen falsche oder kombinierte Produktqueries. |
+| Promptregel zu allgemein | Antworten werden sales-lastig oder enthalten nicht belegte Details. |
+| Regression-Baseline nicht angepasst | stabile Flows können unbemerkt brechen. |
 
 ---
 
-## 9. Entscheidungsregeln: Wohin gehört welcher Wert?
+## 9. Entscheidungsregeln
 
-| Wertart | Gehört nach `genre.yaml`? | Zielgruppe |
-|---|---:|---|
-| Produktrollen, Zubehörrollen, Verbrauchsmaterialrollen | Ja | `product_roles` |
-| Marken und eindeutige Synonyme | Ja | `brands_and_canonical_terms` |
-| Shop-/Kauf-/Preis-Signale mit Genrebezug | Ja | `intent_and_routing` |
-| Nutzer-Stopwords ohne Fachbezug | Eher nein | `language.yaml`, falls allgemeine Sprachschicht |
-| Geschützte Fachkürzel | Ja | `retrieval_and_language.protected_terms` oder `shop_query_runtime.current_input_preservation_terms` |
-| Prompt-Antwortregeln mit Fachbezug | Ja | `result_identity_and_answer_policy` |
-| Technische Prompt-Struktur ohne Fachbezug | Nein | `prompt.yaml` |
-| Modellparameter, Temperatur, Top-K | Nein | Model-/Runtime-Konfiguration |
-| Shopware-Credentials | Nein | ENV / technische Config |
-| Shopware-Custom-Field-Mapping | Ja, wenn installations-/genreabhängig | `shop_data_mapping` |
-| Regression-Fachwerte | Ja | `governance_and_regression` |
-| Audit-Source-Roots und technische Pfadausnahmen | Eher nein bzw. nur Governance | `governance.yaml` / `governance_and_regression.core_pattern_audit` je nach bestehender Struktur |
+| Wertart | Richtiger Ort |
+| --- | --- |
+| Geräte-/Zubehörwort | `product_roles` |
+| Messparameter oder Attribut | `product_attributes` oder `measurement_evidence_maps` |
+| Markenname / Produktfamilie | `brands_and_canonical_terms.known_brands` |
+| Schreibvariante / Tippfehler | `brands_and_canonical_terms.canonical_terms` oder Commerce-Korrektur |
+| Shopquery-Stopword | `shop_query_runtime.stopword_cleanup` |
+| erhaltenswertes Shop-Token | `shop_query_runtime.positive_token_filter.allowed_terms` |
+| verbotener Shop-Noise | `shop_query_runtime.positive_token_filter.blocked_terms` |
+| generische Gerätefrage zu konkretem Produktanker | `shop_query_runtime.generic_device_anchor.anchor_rules` |
+| Follow-up aus Verlauf | `context_resolution` |
+| Antwort-/Promptgrenze | `result_identity_and_answer_policy.prompt_rules` |
+| Search-Repair-Muster | `search_repair` |
+| Regression-Schutz | `governance_and_regression` |
 
 ---
 
-## 10. Minimalbeispiel: neues Zubehör-Synonym ergänzen
+## 10. Minimalbeispiele
 
-Ziel: Nutzer sagen künftig auch „Chemiesatz“ für Reagenz-/Indikator-Zubehör.
-
-Prüfen, ob es Rolle, Canonical Term oder Evidence-Synonym ist:
-
-- Als Zubehörrolle relevant: ja.
-- Als Suchnormalisierung relevant: eventuell.
-- Als Evidence-Synonym relevant: nur wenn fachlich gleichwertig belegt.
-
-Mögliche Änderung:
+### 10.1 Neues Zubehör-Synonym ergänzen
 
 ```yaml
 configuration_values:
@@ -713,62 +602,50 @@ configuration_values:
       terms:
         - indikator
         - reagenz
-        - chemiesatz
-```
-
-Optional zusätzlich:
-
-```yaml
-configuration_values:
-  brands_and_canonical_terms:
-    canonical_terms:
-      map:
-        chemiesatz: reagenz
+        - kalibrierpuffer
 ```
 
 Danach testen:
 
-- „welcher chemiesatz passt zu ...“
-- „suche chemiesatz im shop“
-- Negativtest: Gerät darf dadurch nicht als Zubehör klassifiziert werden.
+```bash
+php bin/console mto:agent:config:validate
+php bin/console mto:agent:regression:test
+```
 
----
-
-## 11. Minimalbeispiel: neues kurzes Attribut schützen
-
-Ziel: Im neuen Genre ist `M8` ein wichtiger Anschluss-/Gewindetyp und darf nicht aus Shop-Queries verschwinden.
-
-Mögliche Änderung:
+### 10.2 Neues Modellkürzel schützen
 
 ```yaml
 configuration_values:
-  retrieval_and_language:
-    protected_terms:
-      terms:
-        - m8
   shop_query_runtime:
-    current_input_preservation_terms:
-      terms:
-        - m8
+    positive_token_filter:
+      adjacent_variant_terms:
+        - lab
+        - cl
+        - sio2
 ```
 
-Danach testen:
+Zusätzlich prüfen, ob das Kürzel auch in `retrieval_and_language.protected_terms` oder Governance-Guardrails geschützt werden muss.
 
-- „zeige mir kabel m8 länger 5m“
-- „suche im shop nach m8“
-- „was kostet das m8 kabel“ nach vorherigem Kontext
+### 10.3 Neue generische Geräteanker-Regel
+
+```yaml
+configuration_values:
+  shop_query_runtime:
+    generic_device_anchor:
+      anchor_rules:
+        - anchor: example device xy
+          template: "{anchor}"
+          match_terms:
+            - beispielparameter
+            - beispielüberwachung
+```
+
+Danach praktische Shop- und Retrievaltests ausführen.
 
 ---
 
-## 12. Kurzfazit
+## 11. Kurzfazit
 
-`genre.yaml` ist die fachliche Source of Truth für eine Single-Genre-RetrieX-Installation.
+`genre.yaml` ist in RetrieX v1.6.0 die zentrale fachliche Steuerdatei. Sie hält die Domänenlogik aus dem PHP-Core heraus und macht Produktrollen, Query-Verhalten, Follow-up-Auflösung, Shop-Matching, Promptgrenzen und Regression-Guards reviewbar.
 
-Bei Anpassungen gilt:
-
-1. Fachwerte in `configuration_values` ändern.
-2. `adaptation_surface` nur als Inventar pflegen.
-3. `source_paths` als Audit-Verknüpfung erhalten.
-4. Legacy-YAMLs nicht wieder mit Fachwerten füllen.
-5. Nach jeder Änderung Validate, Regression und Audits ausführen.
-6. Bei Genre-Umwidmung alte Fachbegriffe bewusst entfernen, nicht nur neue ergänzen.
+Neue fachliche Werte sollen hier oder in den angebundenen YAML-Views gepflegt werden. Nach jeder Änderung müssen Config-Validierung, Source-Audit, Pattern-Audit und Regressionstest grün bleiben.