update .md

COMMAND_REF.md

@@ -1,10 +1,10 @@
-# 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.
 
 ---
 
@@ -12,438 +12,635 @@ Diese Referenz ist gegen den realen Codebestand abgeglichen und ersetzt die vera
 
 | 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`

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