update .md

RAG_SYSTEM_OVERVIEW.md

@@ -1,27 +1,31 @@
 # RAG_SYSTEM_OVERVIEW.md
 
-# RetrieX – Systemüberblick
+# RetrieX v1.6.0 – Systemüberblick
 
 > Hinweis: Die Datei heißt weiterhin `RAG_SYSTEM_OVERVIEW.md`, das System selbst wird fachlich jedoch als **RetrieX** bezeichnet.
 
 ## Grundidee
 
-RetrieX ist ein dokumentenbasiertes Assistenzsystem mit **Retrieval-Augmented Generation**.
+RetrieX ist ein dokumentenbasiertes Assistenzsystem mit Retrieval-Augmented Generation. Version 1.6.0 beschreibt den aktuellen Stand aus RAG-Kern, Commerce-Erweiterung, Chat-/Admin-Trennung, Rollenmodell und Governance-Guardrails.
 
 Das bedeutet:
 
-- Antworten sollen nicht frei erfunden werden
-- Wissen stammt primär aus den aktivierten Dokumenten im System
-- die KI formuliert auf Basis von abgerufenem Kontext
-- bei Produktanfragen können zusätzlich Live-Shopdaten einbezogen werden
+- Antworten sollen nicht frei erfunden werden.
+- Wissen stammt primär aus aktivierten Dokumentversionen.
+- Die KI formuliert auf Basis von abgerufenem Kontext.
+- Bei Produktanfragen können Live-Shopdaten einbezogen werden.
+- Chat- und Adminzugang sind rollenbasiert getrennt.
+- Konfigurierbare Fachlogik liegt überwiegend in YAML statt im PHP-Core.
 
-RetrieX ist damit **kein frei antwortender Chatbot**, sondern ein kontrolliertes System aus:
+RetrieX ist damit kein frei antwortender Chatbot, sondern ein kontrolliertes System aus:
 
 - versionierten Wissensdokumenten
 - deterministischem Ingest
 - hybridem Retrieval
 - optionaler Commerce-Erweiterung
-- LLM-basierter Formulierung der Antwort
+- LLM-basierter Antwortformulierung
+- SSE-basierter Browserausgabe
+- rollenbasierter Betriebs- und Administrationslogik
 
 ---
 
@@ -29,23 +33,22 @@ RetrieX ist damit **kein frei antwortender Chatbot**, sondern ein kontrolliertes
 
 ## 1. Dokumente als Wissensbasis
 
-Die Wissensbasis besteht aus hochgeladenen Dokumenten, zum Beispiel:
+Die Wissensbasis besteht aus hochgeladenen Dokumenten, aktuell verifiziert für:
 
 - PDF
-- DOCX
-- Markdown
 - TXT
+- Markdown
 
-Diese Dokumente werden nicht direkt „gelesen“, sondern in einen verarbeitbaren Wissensindex überführt.
+Diese Dokumente werden nicht direkt zur Laufzeit vollständig gelesen, sondern in einen verarbeitbaren Wissensindex überführt.
 
 Wichtige Eigenschaften:
 
-- Dokumente sind versioniert
-- pro Dokument gibt es fachlich genau eine aktive Version
-- nur aktive Inhalte fließen in den Wissensindex ein
-- Chunks sind abgeleitete Artefakte, keine manuell gepflegte Primärquelle
+- Dokumente sind versioniert.
+- Pro Dokument gibt es fachlich genau eine aktive Version.
+- Nur aktive Inhalte fließen in den Wissensindex ein.
+- Chunks sind abgeleitete Artefakte, keine manuell gepflegte Primärquelle.
 
-Die eigentliche Wissensquelle sind also die **aktiven Dokumentversionen**, nicht frei bearbeitete Textfragmente.
+Die eigentliche Wissensquelle sind also die aktiven Dokumentversionen, nicht frei bearbeitete Textfragmente.
 
 ---
 
@@ -55,30 +58,35 @@ Sobald eine Dokumentversion ingestiert oder aktiviert wird, läuft ein technisch
 
 Dabei passiert im Kern:
 
-1. Dokumentinhalt wird extrahiert
-2. Inhalt wird in Chunks zerlegt
-3. Chunk-Datensätze werden in `index.ndjson` geschrieben
-4. der Vektorindex wird vollständig neu aufgebaut
-5. Laufzeit-Metadaten werden aktualisiert
+1. Dokumentinhalt wird extrahiert.
+2. Inhalt wird in Chunks zerlegt.
+3. Chunk-Datensätze werden in `index.ndjson` geschrieben.
+4. Der Vektorindex wird vollständig neu aufgebaut.
+5. Runtime-Metadaten werden aktualisiert.
+6. Der Status der Version wird auf `INDEXED` gesetzt.
 
-Der Ingest ist bewusst **deterministisch** aufgebaut.  
-Das heißt: derselbe Datenstand soll immer wieder denselben Indexzustand erzeugen.
+Der Ingest ist bewusst deterministisch aufgebaut. Derselbe Datenstand soll denselben Indexzustand erzeugen.
 
 ---
 
 ## 3. Retrieval zur Laufzeit
 
-Wenn ein Nutzer eine Anfrage stellt, durchsucht RetrieX nicht „das ganze Dokument direkt“, sondern den vorbereiteten Wissensbestand.
+Wenn ein Nutzer eine Anfrage stellt, durchsucht RetrieX nicht das ganze Dokument direkt, sondern den vorbereiteten Wissensbestand.
 
-Das Retrieval ist im aktuellen Stand **hybrid und routingfähig**:
+Das Retrieval ist im aktuellen Stand hybrid und routingfähig:
 
-- Vektor-Retrieval über FAISS
-- zusätzliches Tag-Routing zur Vorselektion möglicher Dokumente
-- Score-basierte Auswahl relevanter Chunks
+- Query Cleaning
+- Query Enrichment
+- Intent-Erkennung
+- Tag-Routing zur Kandidatendokument-Vorselektion
+- FAISS-Vektor-Retrieval
+- optionale gescopte Suche auf Kandidatendokumente
+- Score- und RRF-basierte Fusion
 - Sonderroute für Katalog-/Listenanfragen
+- Präzisionsrouten für exakte Tabellen-/Grenzwert-/Indikatorfragen
 - optionale Ergänzung durch Live-Shopdaten bei Commerce-Intent
 
-Das System liefert also nicht einfach „irgendwelche Treffer“, sondern baut einen gezielten Kontextblock für das Modell.
+Das System liefert also nicht einfach irgendwelche Treffer, sondern baut einen gezielten Kontextblock für das Modell.
 
 ---
 
@@ -95,13 +103,23 @@ Dieser Prompt kann aus mehreren Blöcken bestehen:
 - optional extrahierter Inhalt einer URL aus der Nutzeranfrage
 - aktuelle Nutzerfrage
 
-Erst danach erzeugt das Sprachmodell die eigentliche Antwort.
-
-Die KI ist damit die **Formulierungsinstanz**, nicht die eigentliche Wissensquelle.
+Die KI ist damit die Formulierungsinstanz, nicht die eigentliche Wissensquelle.
 
 ---
 
-# Architektur in vier Ebenen
+## 5. Chat, Admin und Betrieb
+
+Version 1.6.0 trennt den öffentlichen Chat-Einstieg architektonisch vom Adminbereich:
+
+- Chat: `/`, `/chat`, `/chat/login`, `/chat/logout`
+- Chat-APIs: `/ask-jobs`, `/ask-sse`, `/ask-sse/{jobId}`, `/history`, `/chat-messages/frontend`
+- Admin: `/admin...`
+
+Beide Bereiche nutzen denselben User-Provider, aber getrennte Firewalls und Rollenregeln. Dadurch kann ein Benutzer z. B. nur Chatrechte, nur Adminbasisrechte oder erweiterte Adminrechte besitzen.
+
+---
+
+# Architektur in fünf Ebenen
 
 ## 1. Primärquellen
 
@@ -111,9 +129,10 @@ Primärquellen sind die fachlichen Eingaben des Systems:
 - Dokumentversionen
 - aktive System-Prompts
 - Modellkonfiguration
+- YAML-Konfigurationen
 - optional externe Shopdaten
 
-Diese Ebene bestimmt, **welches Wissen und welche Regeln** überhaupt verwendet werden dürfen.
+Diese Ebene bestimmt, welches Wissen und welche Regeln verwendet werden dürfen.
 
 ---
 
@@ -136,31 +155,60 @@ Diese Ebene ist für Suche, Relevanz und Reproduzierbarkeit zuständig.
 Diese Ebene verbindet alle Teile des Systems:
 
 - Anfrageannahme
+- Client-ID-Auflösung
+- Gesprächskontext
 - URL-Auswertung
 - Retrieval
 - Intent-Erkennung
 - Shop-Suche
+- Query-Reparatur
 - Prompt-Aufbau
 - Streaming der Modellantwort
 - Historienpersistenz
 
-Zentrale Klasse für die Laufzeit ist hier insbesondere der `AgentRunner`.
+Zentrale Laufzeitklasse ist `AgentRunner`.
 
 ---
 
 ## 4. Ausgabe- und UI-Ebene
 
-Die Antwort wird per **Server-Sent Events (SSE)** gestreamt.
+Die Antwort wird per Server-Sent Events gestreamt.
 
-Dadurch erhält das Frontend die Ausgabe schrittweise, statt auf eine vollständige Blockantwort zu warten.
+Die UI kann anzeigen:
 
-Der aktuelle Projektstand setzt für Browser-Streaming bevorzugt auf SSE.
+- laufende Statusphasen
+- Datenbasis und Confidence-Hinweise
+- RAG-/Shop-Quellen
+- Shopkarten
+- gesendete Shopquery oder Einzelqueries
+- Follow-up-Actions wie Preis anzeigen, nur Zubehör anzeigen oder technische Details anzeigen
+
+Seit den neueren v1.6.0-Patches sind Follow-up-Actions kontextsensitiver und vermeiden Selbstloops, wenn dieselbe Shopquery bereits ausgeführt wurde.
+
+---
+
+## 5. Betriebs- und Governance-Ebene
+
+Diese Ebene umfasst:
+
+- Chat-/Admin-Firewalls
+- Rollenmatrix
+- Admin-Userverwaltung
+- Aktiv-/Inaktiv-Loginprüfung
+- Access-Denied-Handler
+- 403/404/500-Fehlerseiten
+- Konfigurationsvalidierung
+- Source-Audit
+- Core-Pattern-Audit
+- Regressionstests
+
+Damit wird RetrieX nicht nur fachlich, sondern auch organisatorisch betreibbar.
 
 ---
 
 # Wissensspeicher und Indexdateien
 
-## index.ndjson
+## `index.ndjson`
 
 `index.ndjson` ist die zentrale Chunk-Datei des Systems.
 
@@ -170,13 +218,13 @@ Eigenschaften:
 - streamingfähig
 - append-/rewrite-fähig
 - geeignet für größere Bestände
-- dient als operative Grundlage für den Vector-Rebuild
+- operative Grundlage für den Vector-Rebuild
 
 Jede Zeile repräsentiert einen Chunk-Datensatz.
 
 ---
 
-## index_meta.json
+## `index_meta.json`
 
 `index_meta.json` beschreibt den strukturellen Zustand des Index.
 
@@ -191,20 +239,19 @@ Beispielhafte Inhalte:
 - `index_format`
 - `vector_backend`
 
-Diese Datei ist wichtig für Guardrails.  
-Wenn sich die Strukturparameter ändern, darf lokaler Ingest nicht einfach weiterlaufen.
+Diese Datei ist wichtig für Guardrails. Wenn sich Strukturparameter ändern, darf lokaler Ingest nicht einfach weiterlaufen.
 
 ---
 
-## index_runtime.json
+## `index_runtime.json`
 
-`index_runtime.json` enthält laufzeitbezogene Informationen zum aktuellen Indexzustand, zum Beispiel aktualisierte Chunk-Zählungen.
+`index_runtime.json` enthält laufzeitbezogene Informationen zum aktuellen Indexzustand, z. B. Chunk-Zählungen und Rebuild-Zeitpunkte.
 
 Diese Datei dient nicht als Primärquelle, sondern als technische Betriebsmetadatei.
 
 ---
 
-## vector.index
+## `vector.index`
 
 `vector.index` ist der FAISS-Vektorindex des Systems.
 
@@ -212,16 +259,15 @@ Er wird nicht manuell gepflegt, sondern aus `index.ndjson` neu erzeugt.
 
 ---
 
-## tags.ndjson und vector_tags.index
+## `tags.ndjson` und `vector_tags.index`
 
 Neben dem Hauptindex existiert eine Tag-Ebene:
 
 - `tags.ndjson`
 - `vector_tags.index`
+- `vector_tags.index.meta.json`
 
-Diese wird für Tag-Routing bzw. thematische Vorselektion verwendet.
-
-Sie ist eine ergänzende Routing-Schicht, kein Ersatz für das Hauptretrieval.
+Diese Ebene unterstützt Tag-Routing und Kandidatendokument-Vorselektion.
 
 ---
 
@@ -229,20 +275,19 @@ Sie ist eine ergänzende Routing-Schicht, kein Ersatz für das Hauptretrieval.
 
 ## 1. Dokument anlegen
 
-Ein Dokument wird als fachliche Einheit gespeichert.
+Ein Dokument wird als fachliches Objekt im Adminbereich gepflegt.
 
 ## 2. Versionen verwalten
 
-Dokumente besitzen Versionen.  
-Diese Versionen sind der eigentliche inhaltliche Träger.
+Dokumente besitzen Versionen. Diese Versionen sind der eigentliche inhaltliche Träger.
 
 ## 3. Aktivierung
 
-Wird eine Version aktiviert, wird nicht einfach nur „ein Text ausgetauscht“, sondern ein definierter Prozess ausgelöst.
+Wird eine Version aktiviert, wird ein definierter Prozess ausgelöst. Die aktive Version bestimmt den Wissensstand des Dokuments.
 
 ## 4. IngestJob
 
-Die Aktivierung führt in die Ingest-Orchestrierung.
+Ingest-Jobs führen den Verarbeitungsprozess nachvollziehbar aus.
 
 ## 5. Chunk-Erzeugung
 
@@ -250,64 +295,39 @@ Aus der aktiven Version werden Chunk-Records erzeugt.
 
 ## 6. NDJSON-Update
 
-Bestehende Chunks des betroffenen Dokuments werden entfernt und durch neue ersetzt.
+Der Chunk-Bestand wird dokumentbezogen aktualisiert.
 
 ## 7. Vollständiger Vector-Rebuild
 
-Anschließend wird der gesamte FAISS-Index aus dem aktuellen NDJSON-Bestand neu gebaut.
+Nach relevanten Ingest-Schritten wird der FAISS-Index vollständig neu aufgebaut.
 
 ---
 
-# Ingest-Logik im aktuellen Stand
+# Ingest-Logik
 
-Der Ingest ist in mehrere spezialisierte Services getrennt.
+## `GuardrailValidator`
 
-## GuardrailValidator
+Prüft, ob der bestehende Index strukturell zur aktiven Konfiguration passt.
 
-Prüft, ob der aktuelle Indexzustand mit der erwarteten Struktur kompatibel ist.
+## `ChunkWriteService`
 
-Wenn nicht, wird lokaler Ingest blockiert.
+Kapselt Schreiboperationen auf `index.ndjson`.
 
----
+## `VectorRebuildService`
 
-## ChunkWriteService
+Baut den Vektorindex neu und aktualisiert Runtime-Metadaten.
 
-Kapselt die Schreibvorgänge auf der Chunk-Ebene, insbesondere:
+## `IngestFlow`
 
-- Chunks zählen
-- Chunks für ein Dokument entfernen
-- neue Chunks anhängen
-- gesamten NDJSON-Bestand neu schreiben
-
----
-
-## VectorRebuildService
-
-Verantwortet den vollständigen Rebuild des Vektorindex und die Aktualisierung der Runtime-Metadaten.
-
----
-
-## IngestFlow
-
-Der `IngestFlow` orchestriert den Gesamtprozess.
-
-Für Dokument-Ingest bedeutet das insbesondere:
-
-- Guardrail prüfen
-- Status auf laufend setzen
-- alte Dokument-Chunks entfernen
-- neue Chunks streamingfähig anhängen
-- Chunk-Limits überwachen
-- Vector-Rebuild auslösen
-- finalen Status setzen
+Orchestriert Einzel-Ingest, Global Reindex und Lösch-/Reset-Flows.
 
 ---
 
 # Guardrails und Reproduzierbarkeit
 
-RetrieX schützt sich bewusst gegen strukturellen Drift.
+RetrieX schützt sich gegen strukturellen Drift.
 
-Wenn sich zentrale Indexparameter ändern, etwa:
+Lokaler Ingest darf nicht weiterlaufen, wenn sich z. B. diese Strukturparameter geändert haben:
 
 - Embedding-Modell
 - Embedding-Dimension
@@ -315,27 +335,24 @@ Wenn sich zentrale Indexparameter ändern, etwa:
 - Chunk-Overlap
 - Scoring-Version
 - Indexformat
+- Vector-Backend
 
-dann darf ein lokaler Ingest nicht stillschweigend in einen inkompatiblen Index hineinschreiben.
-
-Stattdessen wird ein **Global Reindex** erforderlich.
-
-Das verhindert inkonsistente Mischzustände.
+Dann ist ein Global Reindex erforderlich.
 
 ---
 
 # Global Reindex
 
-Ein Global Reindex unterscheidet sich bewusst vom lokalen Dokument-Ingest.
+Der Global Reindex baut den operativen Wissensbestand aus den aktiven Dokumentversionen neu auf.
 
-Dabei passiert:
+Ziel:
 
-- alle aktiven Dokumente werden neu verarbeitet
-- `index.ndjson` wird vollständig neu geschrieben
-- der Vektorindex wird komplett neu gebaut
-- die `index_version` wird erhöht
+- konsistenter Chunk-Bestand
+- konsistenter Vektorindex
+- aktualisierte Runtime-Metadaten
+- reproduzierbarer Systemzustand
 
-Der Global Reindex ist damit der kontrollierte Weg, strukturelle Änderungen sauber auf den gesamten Wissensbestand anzuwenden.
+In v1.6.0 ist der Global-Reindex-Zugriff serverseitig und im Admin-UI auf `ROLE_SUPER_ADMIN` eingeschränkt.
 
 ---
 
@@ -343,344 +360,337 @@ Der Global Reindex ist damit der kontrollierte Weg, strukturelle Änderungen sau
 
 ## Hybrid-Retrieval
 
-Das aktuelle System verwendet kein rein lineares Suchmodell, sondern kombiniert mehrere Schritte:
+Der aktive Retriever kombiniert mehrere Signale:
 
-- Query-Cleaning
-- Query-Enrichment
-- Intent-Erkennung
+- bereinigte Nutzerfrage
+- Query-Enrichment-Regeln
+- Intent-Routing
+- Vektortreffer
 - Tag-Routing
-- globale Vektorsuche
-- optional gescopte Vektorsuche auf Kandidatendokumente
-- Fusion und Auswahl relevanter Chunks
-
-Das Ziel ist nicht einfach „mehr Treffer“, sondern **passendere, stabilere Kontexterzeugung**.
-
----
+- gescopte Suche
+- RRF-/Score-Fusion
+- dokumentbezogene Begrenzung
 
 ## Tag-Routing
 
-Vor der eigentlichen Chunk-Auswahl kann das System thematisch passende Dokumente über Tags eingrenzen.
-
-Das reduziert die Suchfläche und erhöht die Wahrscheinlichkeit, dass relevante Dokumente bevorzugt werden.
-
----
+Tags können Kandidatendokumente vorselektieren. Dadurch kann die spätere Vektorsuche fokussierter laufen.
 
 ## Katalog-/Listenroute
 
-Für bestimmte Anfragen erkennt das System, dass keine klassische Chunk-Antwort, sondern eher eine Listen- oder Katalogausgabe sinnvoll ist.
-
-Dann kann statt normaler Chunk-Selektion ein Katalogblock erzeugt werden.
-
----
+Katalog- oder Listenfragen können direkt in einen Katalogblock führen, statt nur einzelne Textchunks zu liefern.
 
 ## Ergebnisbegrenzung
 
-Die Zahl der zurückgegebenen Wissens-Chunks ist konfigurationsgetrieben.
-
-Wichtige Steuergrößen sind:
-
-- `retrievalMaxChunks`
-- `retrievalVectorTopK`
-
-Diese Werte stammen aus der aktiven Modell-/Generierungskonfiguration.
+Parameter aus `retrieval.yaml`, `model.yaml` und `prompt.yaml` begrenzen Kandidaten, Chunks und Promptbudget.
 
 ---
 
 # Commerce-Erweiterung und Shop-Suche
 
-Ein zentrales Merkmal des aktuellen Systemstands ist die **optionale Shopware-Store-API-Anbindung**.
+## `CommerceIntentLite`
 
-Diese wird nicht immer verwendet, sondern nur dann, wenn die Anfrage nach Commerce-Logik aussieht.
+Erkennt, ob eine Anfrage Commerce-Relevanz hat.
 
-## CommerceIntentLite
-
-Die Anfrage wird heuristisch auf Commerce-Signale geprüft, zum Beispiel:
+Mögliche Zustände:
 
+- keine Commerce-Suche
 - Produktsuche
-- Preisbezug
-- Größen-/Farbhinweise
-- SKU-ähnliche Nummern
-- typische Produkt- oder Empfehlungsfragen
+- beratende Produktsuche
 
-Das Ergebnis ist einer von drei Zuständen:
+## `CommerceQueryParser`
 
-- `none`
-- `product_search`
-- `advisory_product_search`
+Bereinigt und normalisiert Shopqueries:
 
----
+- bekannte Marken behalten
+- Bedienphrasen entfernen
+- Tippfehler korrigieren
+- Token kanonisieren
+- Kontext-/Preservation-Tokens erhalten
+- Preis-/Farb-/Größenmuster erkennen
 
-## CommerceQueryParser
+## `ShopSearchService`
 
-Wenn Commerce erkannt wird, wird die Nutzeranfrage deterministisch aufbereitet.
-
-Dabei werden strukturierte Suchinformationen abgeleitet, etwa:
-
-- Suchkern
-- Preis
-- Größe
-- Farbe
-- weitere Suchsignale
-
----
-
-## ShopSearchService
-
-Der `ShopSearchService` baut daraus eine Shopware-Store-API-Anfrage und mappt die Ergebnisse in ein internes, schlankes Produktformat.
-
-Typische Produktinformationen sind dann:
-
-- Name
-- Produktnummer
-- Hersteller
-- Preis
-- Verfügbarkeit
-- URL
-- Beschreibung
-- Bild
-- ausgewählte Zusatzinformationen
-
----
+Führt die Shopware-Suche aus und kann Repair-Queries nachschieben, wenn primäre Treffer fehlen oder zu ungenau sind.
 
 ## Rolle der Shopdaten
 
-Shopdaten werden im Prompt ausdrücklich als **authoritative for products** behandelt.
+Shopdaten sind für Produktinformationen autoritativ, insbesondere für:
 
-Das bedeutet:
-
-- für reale Produktdaten sind Live-Shopdaten führend
-- Wissens-Chunks bleiben unterstützend
-- das System trennt damit Produktwahrheit und Dokumentwissen bewusst voneinander
-
----
+- Produktname
+- Artikelnummer
+- Preis
+- Verfügbarkeit
+- Hersteller
+- Shop-URL
+- Shop-Beschreibung und Custom Fields
 
 ## Balance zwischen Shop und Wissen
 
-Wenn Commerce aktiv ist, wird die Zahl der Wissens-Chunks reduziert:
+Shopdaten ersetzen nicht automatisch fachliche Eignungsbelege. Bei technischen Eignungsfragen müssen RAG-Kontext, Shopdaten und Prompt-Guardrails zusammenpassen.
 
-- bei `product_search` stärker
-- bei `advisory_product_search` moderat
+---
 
-So soll verhindert werden, dass Shopdaten im finalen Prompt von allgemeinen Wissens-Chunks verdrängt werden.
+# v1.6.0 Commerce- und Follow-up-Guards
+
+Version 1.6.0 enthält mehrere Präzisionsmechanismen:
+
+- Direkte Produktnamen werden in Shopqueries erhalten.
+- Noise-Tokens wie reine Bedien-, Relations- oder Denkmarker werden entfernt.
+- Tippfehler wie `schwinnbad` können zu `schwimmbad` korrigiert und erhalten werden.
+- Modellkürzel wie `LAB CL` bleiben erhalten, wenn sie im konfigurierten Kontext auftreten.
+- generische Geräteanfragen können auf exakte fachliche Produktanker aufgelöst werden, z. B. bei SiO2/Silikat.
+- Produktlisten-Follow-ups werden in einzelne Produktqueries aufgeteilt.
+- Produktanker-Kanonisierung ist YAML-gestützt statt im PHP-Core hartcodiert.
+- Exakte Zubehörcodes werden als exakte Codes behandelt.
+- Preis-Folgeaktionen verwenden sichtbare Produktidentitäten mit Produktnummern.
+- Schwache referenzielle Shopqueries können auf History-Modellanker zurückfallen.
 
 ---
 
 # URL-Auswertung
 
-Wenn die Nutzeranfrage eine URL enthält, kann RetrieX den Inhalt dieser URL zusätzlich extrahieren.
+`UrlAnalyzer` extrahiert Inhalt aus der ersten URL in einer Nutzerfrage.
 
-Dazu wird:
-
-- die erste URL im Prompt erkannt
-- der Inhalt geladen
-- über Readability verarbeitet
-- HTML entfernt
-- Text normalisiert
-- auf eine maximale Länge begrenzt
-
-Der extrahierte Inhalt wird anschließend als zusätzlicher unterstützender Wissensblock in den Prompt aufgenommen.
-
-Das ist hilfreich, wenn ein Nutzer auf eine konkrete externe Quelle verweist.
+Der Inhalt wird als unterstützende Quelle in den Prompt aufgenommen, nicht als Primärindex gespeichert.
 
 ---
 
 # Prompt-Aufbau
 
-Der finale Prompt wird systematisch zusammengesetzt.
+Der final zusammengesetzte Prompt kann enthalten:
 
 ## 1. Systemblock
 
-Der aktive System-Prompt wird aus der Datenbank geladen.
-
-Er ist die führende Regel- und Verhaltensbasis des Modells.
-
----
+Aktiver System-Prompt.
 
 ## 2. Gesprächskontext
 
-Frühere Nachrichten des Nutzers werden als autoritativer Konversationskontext eingebunden.
-
-So bleibt der Dialog über mehrere Turns konsistent.
-
----
+Historie des Nutzers, regulär oder explizit als Full-Context.
 
 ## 3. Live-Shop-Block
 
-Wenn Shop-Ergebnisse vorliegen, werden diese als eigener Block eingebaut.
-
-Sie sind für Produktfragen führend.
-
----
+Shopware-Produkte mit Produktnummer, Preis, Verfügbarkeit, Hersteller, URL und weiteren Feldern.
 
 ## 4. Retrieved Knowledge
 
-Die ausgewählten Wissens-Chunks werden als unterstützender Wissensblock eingefügt.
-
----
+RAG-Chunks aus `index.ndjson`.
 
 ## 5. URL-Content
 
-Optional kommt zusätzlich extrahierter Webinhalt hinzu.
-
----
+Optional extrahierter Inhalt einer URL.
 
 ## 6. Nutzerfrage
 
-Am Ende steht die aktuelle Benutzerfrage.
+Aktuelle Frage.
 
 ---
 
 # Antwort-Streaming
 
-Die Antwort wird nicht gesammelt und dann komplett ausgeliefert, sondern als Stream übertragen.
+## `AskSseController`
 
-## AskSseController
+Der Controller stellt zwei Streaming-Wege bereit:
 
-Der `AskSseController` stellt den SSE-Endpunkt bereit.
+- Job-basierter Flow: `POST /ask-jobs` plus `GET /ask-sse/{jobId}`
+- direkter Flow: `POST /ask-sse`
 
-Dabei werden:
-
-- Buffer geleert
-- Cookies weitergereicht
-- SSE-Header gesetzt
-- Daten als `data:`-Zeilen gesendet
-- am Ende ein `done`-Event ausgeliefert
+Der Job-basierte Flow unterstützt Statusabfrage, Event-IDs, Replay/Tailing und Stale-Erkennung.
 
 ## Vorteil
 
-Das Frontend kann Antworten live darstellen und laufend erweitern.
-
-Das verbessert die Benutzererfahrung deutlich, besonders bei längeren Antworten.
+Der Browser erhält schrittweise Ausgabe und kann Statusinformationen, Shopkarten und Folgeaktionen während bzw. nach der Antwort anzeigen.
 
 ---
 
 # Conversation Context und Historie
 
-RetrieX verwaltet Nutzerkontext über eine eigene Context-Schicht.
+`ContextService` speichert abgeschlossene Turns pro Client-ID.
 
-Dazu gehören insbesondere:
+Aktuelle Standardwerte:
 
-- Aufbau eines nutzerspezifischen Gesprächskontexts
-- Einbindung früherer Turns in den Prompt
-- Persistierung der finalen Antworthistorie
+- regulär: 25 Zeilen
+- Full-Context: 500 Zeilen
 
-So kann das System nicht nur auf Einzelfragen, sondern auf fortlaufende Dialoge reagieren.
+Full-Context ist nicht mehr implizit der Browserstandard, sondern muss ausdrücklich angefordert werden.
+
+---
+
+# Security und Rollenmodell
+
+## Firewalls
+
+`config/packages/security.yaml` definiert getrennte Firewalls:
+
+- `admin` für `^/admin`
+- `chat` für Chat-, Ask-, SSE-, History- und Frontend-Message-Routen
+- `main` für sonstige öffentliche/statische Ressourcen
+
+## Rollenmatrix
+
+| Bereich | Effektive Rolle |
+| --- | --- |
+| Chat, Ask/SSE, History, Frontend-Messages | `ROLE_CHAT_USER` |
+| Admin-Dashboard, Guides, Jobs | `ROLE_ADMIN_AREA` |
+| Dokumente, Versionen, Tags, Dokument-Ingest | `ROLE_EDITOR` |
+| Modell-/Retrieval-Konfiguration, Ingest-Profile ansehen | `ROLE_KNOWLEDGE_ADMIN` |
+| Userverwaltung, Logs, System Prompt/Agent, Global Reindex, Reset/Delete | `ROLE_SUPER_ADMIN` |
+
+`ROLE_USER` alleine reicht für keinen Bereich.
+
+---
+
+# Admin-Bereich
+
+Admins können je nach Rolle steuern:
+
+- Dokumente und Versionen
+- Tags und Tag-Zuweisungen
+- Ingest-Jobs
+- Global Reindex
+- Modell-/Retrieval-Konfiguration
+- Ingest-Profile
+- System Prompt
+- System Agent
+- Logs
+- Benutzerverwaltung
+
+Die Admin-Navigation blendet Aktionen passend zur Rolle aus. Serverzugriffe sind zusätzlich über `access_control` und Controller-Checks geschützt.
+
+---
+
+# Userverwaltung
+
+Die Userverwaltung in v1.6.0 umfasst:
+
+- Liste, Anlage und Bearbeitung von Benutzern
+- Rollenzuweisung
+- Passwortsetzen
+- Aktiv-/Inaktiv-Schaltung
+- Self-Protection
+- Schutz des letzten aktiven Super-Admins
+- Loginblock für deaktivierte Benutzer
+- Session-Abmeldung für nachträglich deaktivierte Benutzer
+
+---
+
+# Fehlerseiten und Access Denied
+
+RetrieX rendert konsistente Fehlerseiten für:
+
+- 403
+- 404
+- 500
+- generische Fehler
+
+Der Access-Denied-Handler unterscheidet Chat- und Adminbereich und zeigt die benötigte Rolle sowie sinnvolle Rücksprung- und Logout-Optionen.
 
 ---
 
 # Modell- und Antwortsteuerung
 
-Ein Teil des Systemverhaltens wird über Modellkonfigurationen gesteuert.
+Die Antwortqualität wird gesteuert durch:
 
-Dazu gehören fachlich und technisch insbesondere:
+- aktiven System-Prompt
+- `prompt.yaml`
+- `model.yaml`
+- `retrieval.yaml`
+- `language.yaml`
+- `vocabulary.yaml`
+- `commerce.yaml`
+- `search_repair.yaml`
+- `agent.yaml`
+- `genre.yaml`
+- `chat-messages.yaml`
 
-- welches Modell verwendet wird
-- wie Retrieval parametriert ist
-- wie viele Chunks eingebunden werden
-- wie breit die Vektorsuche sucht
-- wie stark die Antwort durch System-Prompt und Kontext geprägt wird
-
-Diese Konfiguration ist bewusst nicht „wild überschreibbar“, sondern an die aktiven Systemobjekte gebunden.
+Viele fachliche Listen liegen bewusst in YAML und nicht hartcodiert im PHP-Core.
 
 ---
 
 # Was Admins fachlich steuern
 
-Aus Admin-Sicht wird nicht nur „die KI“ gesteuert, sondern ein ganzes Wissens- und Antwortsystem.
+Admins und Knowledge-Admins steuern je nach Rolle:
 
-Steuerbar sind unter anderem:
-
-- welche Dokumente im System existieren
-- welche Version aktiv ist
-- welche Ingest-Profile gelten
-- wann Reindexing ausgelöst wird
-- welcher System-Prompt aktiv ist
-- welche Modellkonfiguration aktiv ist
-- ob und wie Commerce integriert ist
+- welche Dokumentversion aktiv ist
+- wann ingestiert oder reindiziert wird
+- welche System-Prompts aktiv sind
+- welche Modellkonfiguration genutzt wird
+- welche Ingest-Profile sichtbar bzw. aktiv sind
+- welche Benutzer Zugriff auf Chat oder Admin haben
 
 ---
 
 # Was die Antwortqualität tatsächlich beeinflusst
 
-Die Qualität der Antworten hängt direkt von mehreren Ebenen ab:
-
 ## 1. Dokumentqualität
 
 Schlecht strukturierte oder inhaltlich schwache Dokumente führen zu schwachen Antworten.
 
 ## 2. Aktivierungslogik
 
-Nur aktive Versionen zählen.  
-Falsche Aktivierung bedeutet falscher Wissensstand.
+Nur aktive Versionen zählen.
 
 ## 3. Chunking
 
-Chunk-Größe und Overlap beeinflussen, wie gut relevante Informationen später gefunden werden.
+Chunkgröße und Overlap beeinflussen, wie viel Kontext pro Treffer verfügbar ist.
 
 ## 4. Retrieval-Konfiguration
 
-Top-K, Auswahlgrenzen und Routing beeinflussen, welche Informationen überhaupt im Prompt landen.
+Schwellenwerte, Routing, Tag-Suche, Query-Enrichment und Ergebnisbegrenzung bestimmen den Kontext.
 
-## 5. System-Prompt
+## 5. System-Prompt und Prompt-Regeln
 
-Der System-Prompt bestimmt Stil, Regelverhalten und Prioritäten der Ausgabe.
+Diese Regeln bestimmen, wie das Modell mit Wissen, Shopdaten, Unsicherheit und Quellen umgeht.
 
 ## 6. Commerce-Daten
 
-Bei Produktfragen entscheidet die Qualität der Live-Shopdaten über die Produktwahrheit der Antwort.
+Shopware-Daten beeinflussen Produkt-, Preis-, Verfügbarkeits- und Linkantworten.
+
+## 7. Rollen und UI-Flows
+
+Rollen, Loginstatus und Access-Denied-Verhalten bestimmen, welche Nutzer welche Funktionen erreichen.
 
 ---
 
 # Grundprinzipien des Systems
 
-RetrieX folgt im aktuellen Stand diesen Grundprinzipien:
-
-- dokumentenzentriert statt modellzentriert
-- deterministisch statt zufällig orchestriert
-- reproduzierbar statt implizit
-- governance-fähig statt unkontrolliert
-- hybrid im Retrieval
-- erweiterbar durch Shopdaten
-- streamingfähig in der Ausgabe
+- Keine freie Wissensbehauptung ohne Datenbasis.
+- Aktive Dokumentversionen sind fachliche Primärquelle.
+- Shopdaten sind autoritativ für Produkt-/Preis-/Verfügbarkeitsdaten.
+- Technische Eignung darf nicht aus Shopdaten allein überinterpretiert werden.
+- YAML ist Source of Truth für konfigurierbare Fachlogik.
+- PHP-Core soll Orchestrierung leisten, nicht Domainlisten verstecken.
+- Rollen müssen UI-seitig und serverseitig konsistent sein.
+- Regressionstests schützen bekannte stabile Flows.
 
 ---
 
 # Was RetrieX ausdrücklich nicht ist
 
-RetrieX ist im aktuellen Design:
+RetrieX ist nicht:
 
-- kein rein freier LLM-Chat
-- kein ausschließlich kreatives Generierungssystem
-- kein manuell gepflegter Chunk-Editor
-- kein Produktkatalog ohne Wissenslogik
-- kein rein vektorbasierter Blackbox-Sucher
-
-Es ist ein **kontrolliertes Antwortsystem**, das Wissen, Routing, Produktdaten und Modellformulierung zusammenführt.
+- ein frei improvisierender Chatbot
+- ein Ersatz für Datenpflege
+- ein Ersatz für validierte technische Beratung in Grenzfällen
+- ein manuell gepflegter Chunk-Editor
+- ein Shop-Scraper
+- ein unkontrollierter Prompt-Wrapper um ein LLM
 
 ---
 
 # Kurz zusammengefasst
 
-RetrieX arbeitet im Kern so:
-
-1. Dokumente und Versionen definieren den Wissensstand
-2. Ingest erzeugt daraus NDJSON-Chunks
-3. daraus wird der FAISS-Index vollständig neu aufgebaut
-4. bei einer Anfrage laufen Retrieval, Routing und optional Commerce-Suche
-5. PromptBuilder kombiniert Systemregeln, Kontext, Wissenschunks, URL-Inhalte und Shopdaten
-6. das Modell formuliert daraus die Antwort
-7. die Ausgabe wird per SSE ins Frontend gestreamt
-
-Kurzform:
-
-**Dokumente → Ingest → NDJSON → Vector Index → Retrieval → Prompt-Aufbau → LLM-Antwort → SSE-Streaming**
+1. Dokumente und Versionen definieren den Wissensstand.
+2. Ingest erzeugt Chunks und FAISS-Indizes.
+3. Retrieval sucht gezielt Kontext.
+4. Commerce kann Shopware-Daten ergänzen.
+5. PromptBuilder setzt Systemregeln, Kontext, Shopdaten und Frage zusammen.
+6. Das LLM formuliert die Antwort.
+7. SSE streamt die Antwort ins Frontend.
+8. Rollen und Adminlogik steuern Zugriff und Betrieb.
+9. YAML- und Audit-Guardrails schützen die Wartbarkeit.
 
 ---
 
 # Merksatz
 
-> Sie steuern in RetrieX nicht einfach nur ein Modell.  
-> Sie steuern die zugelassene Wissensbasis, die Suchlogik, die Antwortregeln und – bei Produktfragen – die produktbezogene Live-Datenquelle.
-
-Die KI formuliert.  
-RetrieX bestimmt, worauf sie sich dabei stützen darf.
+RetrieX v1.6.0 ist kein Chatbot mit Dokumentanhang, sondern eine kontrollierte Antwortinfrastruktur aus Wissen, Suche, Shopdaten, Rollenmodell und Governance.