update .md

CONFIG_PARAMS.md

@@ -1,108 +1,178 @@
-## **1\. `config/retriex/agent.yaml`**
+# CONFIG_PARAMS.md
 
-| YAML-Parameter | Bewirkt |
+# RetrieX v1.6.0 – Konfigurationsparameter und Tuning-Leitfaden
-| ----- | ----- |
+
-| `retriex.agent.config.commerce_history_budget_chars` | Begrenzt, wie viel Chatverlauf für Commerce-/Shop-Kontext in die Query-Auflösung einfließt. |
+Diese Datei beschreibt die wichtigsten Konfigurationsflächen des aktuellen Systems. Fachliche Listen, Promptregeln, Intent-Signale, Sprachbereinigung, Shopquery-Logik und UI-Texte sollen weiterhin bevorzugt in YAML gepflegt werden, nicht als neue Domain-Sonderlogik im PHP-Core.
-| `product_search_knowledge_chunk_limit` | Begrenzt RAG-Chunks bei normalen produktnahen Shop-/Wissensfragen. |
+
-| `advisory_product_search_knowledge_chunk_limit` | Begrenzt RAG-Chunks bei beratenden Produktauswahlfragen, z. B. „welches Gerät ist geeignet“. |
+## Grundregel
-| `optimized_shop_query_prefix_pattern` | Entfernt LLM-Ausgabepräfixe wie `query:` oder `keywords:` aus optimierten Shop-Suchqueries. |
+
-| `optimized_shop_query_trim_characters` | Trimmt unerwünschte Zeichen am Rand optimierter Shop-Queries. |
+- `config/retriex/*.yaml` ist die zentrale Source of Truth für fachlich konfigurierbares Verhalten.
-| `input_normalization.enabled` | Schaltet die Vor-Normalisierung der Nutzereingabe ein/aus. |
+- `config/packages/security.yaml` ist die zentrale Source of Truth für Firewalls, Rollen und Access-Control.
-| `input_normalization.max_input_chars` | Maximale Eingabelänge, die zur Normalisierung geschickt wird. |
+- PHP-Code soll Konfiguration lesen, validieren und ausführen, aber keine neuen fachlichen Tokenlisten oder Business-Regeln verstecken.
-| `input_normalization.max_output_chars` | Maximale akzeptierte Länge der Normalisierungsantwort. |
+
-| `input_normalization.max_added_tokens` | Verhindert, dass die Normalisierung zu viele neue Wörter hinzufügt. |
+---
-| `input_normalization.max_length_ratio_percent` | Guardrail gegen aufgeblasene Normalisierungsantworten. |
+
-| `input_normalization.heartbeat_message` | Statusmeldung während der Eingabeoptimierung. |
+# 1. YAML-Dateien im Überblick
-| `input_normalization.output_prefix_pattern` | Entfernt Präfixe wie `normalisiert:` aus der Normalisierungsantwort. |
+
-| `input_normalization.placeholder_outputs` | Erkennt ungültige Platzhalterantworten wie „normalized user input“. |
+| Datei | Zweck |
-| `input_normalization.skip_patterns` | Überspringt Normalisierung bei URLs, Codeblöcken usw. |
+| --- | --- |
-| `input_normalization.prompt.*` | Steuert den Prompt für die LLM-basierte Eingabenormalisierung. |
+| `config/retriex/agent.yaml` | AgentRunner-Orchestrierung, Follow-up-Kontext, Shopruntime, Guards, No-LLM-Fallback, UI-Produktionsdaten |
-| `input_normalization.fuzzy_routing.*` | Steuert Typo-Toleranz für Routingbegriffe wie Shop, Preis, Zubehör, Messgerät. |
+| `config/retriex/chat-messages.yaml` | User-sichtbare Chat-, SSE-, Frontend-, Agent-, Status-, Follow-up- und Fehlermeldungen |
-| `follow_up_context.strong_reference_patterns` | Erkennt referenzielle Folgefragen wie „mit welchem Indikator“, „dieser Wert“, „womit“. |
+| `config/retriex/commerce.yaml` | Shopware-Anbindung, Commerce-Query-Parsing, Reference Resolver, Shop-Matching und Produkt-Ranking |
-| `follow_up_context.explicit_commercial_signal_terms` | Erkennt kommerzielle Folgefragen wie Preis, Shop, kaufen, Artikelnummer. |
+| `config/retriex/genre.yaml` | Genre-native Source of Truth für fachliche Adaption, Product Roles, Query Runtime, Context Resolution, Search Repair |
-| `follow_up_context.commercial_table_follow_up.*` | Erkennt Folgefragen nach Preis-/Shop-Tabellen und baut daraus Shop-Kontextqueries. |
+| `config/retriex/governance.yaml` | Regression-Baselines, Source-of-Truth-Guards, Pflichtprofile, Core-Pattern-Audit |
+| `config/retriex/index.yaml` | Chunking-, Embedding-, Indexformat- und Vector-Backend-Metadaten |
+| `config/retriex/intent.yaml` | Commerce-, Katalog-, Light-, Sales- und technische Intent-Erkennung |
+| `config/retriex/language.yaml` | Stopwords, Protected Terms, Normalisierung, Cleanup-Profile und Sprachrauschen |
+| `config/retriex/model.yaml` | Default-Modellparameter, Kontextfenster, Retrieval-Limits und LLM-Timeouts |
+| `config/retriex/prompt.yaml` | Promptbudget, Promptsektionen, Shop-Ergebnisformat, Fact-Grounding, Output-Regeln |
+| `config/retriex/query_enrichment.yaml` | Query-Erweiterungen und Synonymregeln für Retrieval |
+| `config/retriex/retrieval.yaml` | Retrieval-Schwellen, RRF, Dokumentbegrenzung, exakte Auswahlpfade, Inventar |
+| `config/retriex/runtime.yaml` | Pfade, Knowledge-Dateien, Locks und Gesprächskontext-Limits |
+| `config/retriex/search_repair.yaml` | Repair-Queries, exakte Zubehörcodes, direkte Attributsuchen, Repair-Ranking |
+| `config/retriex/vector.yaml` | Python-/Vector-Service-Pfade, Host/Port, HTTP-Timeouts, Tag-Routing-Limits |
+| `config/retriex/vocabulary.yaml` | Zentrales Vocabulary für Geräte, Zubehör, Agent, Prompt, Search Repair, Retrieval und Shop |
+
+---
+
+# 2. `config/retriex/agent.yaml`
+
+| Parameter / Bereich | Bewirkt |
+| --- | --- |
+| `commerce_history_budget_chars` | Begrenzt, wie viel Chatverlauf für Commerce-/Shop-Kontext genutzt wird. |
+| `product_search_knowledge_chunk_limit` | Begrenzt RAG-Chunks bei normalen Produkt-/Shopfragen. |
+| `advisory_product_search_knowledge_chunk_limit` | Begrenzt RAG-Chunks bei beratenden Produktauswahlfragen. |
+| `optimized_shop_query_prefix_pattern` | Entfernt LLM-Präfixe wie `query:` aus optimierten Shopqueries. |
+| `optimized_shop_query_trim_characters` | Trimmt unerwünschte Randzeichen optimierter Shopqueries. |
+| `input_normalization.*` | LLM-basierte Vor-Normalisierung, Länge, Skip-Patterns, Prompt und Fuzzy-Routing. |
+| `follow_up_context.strong_reference_patterns` | Erkennt referenzielle Folgefragen wie „mit welchem Indikator“, „dieser Wert“. |
+| `follow_up_context.explicit_commercial_signal_terms` | Erkennt Preis-, Shop-, Kauf- und Artikelnummer-Folgefragen. |
+| `follow_up_context.commercial_table_follow_up.*` | Erkennt Folgefragen nach Preis-/Shop-Tabellen und baut Kontextqueries. |
 | `follow_up_context.history_*_pattern` | Extrahiert relevante Vorfragen aus dem Chatverlauf. |
-| `follow_up_context.context_labels.*` | Textbausteine für den intern erzeugten Follow-up-Kontext. |
+| `follow_up_context.reference_anchor.*` | Extrahiert technische Anker wie Testomat-Modell, Messwert oder Produktbezug. |
-| `follow_up_context.reference_anchor.*` | Extrahiert technische Anker wie Testomat-Modell oder Härtewert aus vorherigen Antworten. |
+| `final_answer_guard.*` | Begrenzt wiederholte oder zu lange finale Antworten. |
-| `messages.*` | User-/Stream-Statusmeldungen und Fehlertexte im AgentRunner. |
+| `shop_runtime.query_cleanup.current_input_preservation.*` | Erhält wichtige Tokens aus der aktuellen Nutzereingabe in der Shopquery. |
-| `rag_evidence_guard.cleanup_profile` | Wählt das Sprachbereinigungsprofil für RAG-Evidence-Prüfung. |
+| `shop_runtime.query_cleanup.stopword_cleanup.*` | Entfernt Sprach-, Bedien- und Relationsrauschen aus Shopqueries. |
-| `rag_evidence_guard.stop_terms` | Entfernt irrelevante Wörter aus Evidence-Vergleichen. |
+| `shop_runtime.query_cleanup.positive_token_filter.*` | Erlaubt positives Filtern auf produktnahe Tokens, Code-Patterns und Varianten-Tokens. |
-| `rag_evidence_guard.aggregate_query_patterns` | Erkennt aggregierende Fragen wie „wie viele Geräte“. |
+| `shop_runtime.attribute_cleanup.*` | Bereinigt direkte Attribut-/Zubehörsuchen, z. B. Kabel-/Puffer-/Sensorfragen. |
-| `rag_evidence_guard.aggregate_evidence_terms` | Tokens, die bei Aggregatfragen als belastbare Zählinformation gelten. |
+| `shop_runtime.context_resolution.history_anchor_enrichment.*` | Reichert kurze referenzielle Shopqueries mit Verlaufankern an. |
-| `rag_evidence_guard.aggregate_answer_evidence_patterns` | Prüft, ob die Antwort wirklich eine belegte Aggregat-/Zählaussage enthält. |
+| `shop_runtime.context_resolution.meta_query_guard.*` | Verhindert Meta-Queries wie „suche im Shop“ ohne konkreten Produktanker. |
-| `rag_evidence_guard.synonyms` | Fachliche Synonyme für Evidence-Abgleich, z. B. Redox/ORP, Salinität/Salzgehalt. |
+| `shop_runtime.context_resolution.rag_anchor_enrichment.*` | Ergänzt Shopqueries aus RAG-Ankern, z. B. bei exakten Messwerten. |
-| `no_llm_fallback.max_shop_results` | Begrenzt Shop-Produkte in Fallback-Antworten ohne LLM. |
+| `shop_runtime.result_identity.*` | Prüft primäre Produktidentität und verhindert zu breite Direct-Product-Ergebnisse. |
-| `no_llm_fallback.messages.*` | Vorgefertigte Sicherheits-/Fallbackantworten, wenn LLM, RAG oder Shopdaten fehlen. |
+| `shop_runtime.answer_constraints.*` | Steuert direkte Antwortfilter, z. B. nach Längenangaben. |
-| `no_llm_fallback.product_fields.*` | Textformatierung für Produktzeilen ohne LLM. |
+| `rag_evidence_guard.*` | Prüft, ob RAG-Treffer und Antwort ausreichende fachliche Evidenz liefern. |
-| `no_llm_fallback.product_roles.*` | Unterscheidet in Fallbacks Hauptgerät vs. Zubehör. |
+| `no_llm_fallback.*` | Fallback-Verhalten, wenn kein LLM verfügbar ist oder keine sichere Synthese möglich ist. |
-| `production_ui.stage_labels.*` | Statusphasen im Frontend, z. B. „Shop wird durchsucht“. |
+| `production_ui.shop_results.max_cards` | Anzahl sichtbarer Shopkarten. |
-| `production_ui.confidence_labels.*` | Labels für Beleglage/Confidence im UI. |
+| `shop_prompt.*` | LLM-Regeln zur Erzeugung kurzer Shopware-Suchqueries. |
-| `production_ui.text.*` | UI-Texte für Statuskarten, Shop-Ergebnisse, Metadaten, Hinweise. |
-| `production_ui.templates.*` | Formatvorlagen für Zähler, Hinweise, Relevanztexte. |
-| `production_ui.shop_results.max_cards` | Maximale Anzahl sichtbarer Shopkarten im UI. |
-| `production_ui.follow_up_actions.*` | Folgeaktions-Chips wie „Im Shop suchen“, „Preis anzeigen“. |
-| `source_labels.*` | Quellenlabels wie RAG-Wissen, Chatverlauf, Shopsystem. |
-| `html.*` | HTML-Templates für Badges, Fehler, Think-/Info-Ausgaben. |
-| `shop_prompt.*` | Prompt, Regeln und Kontextlogik für die Shopware-Suchquery-Optimierung. |
-| `shop_prompt.current_input_preservation.*` | Schützt wichtige Begriffe aus der aktuellen Nutzereingabe vor Verlust, z. B. pH/Redox/ORP. |
-| `shop_prompt.context_usage.referential_terms` | Erkennt „suche im Shop“, „dazu“, „davon“ als Kontext-Follow-up. |
-| `shop_prompt.context_anchor_enrichment.*` | Reichert kurze Shop-Folgefragen mit Verlaufankern an. |
-| `shop_prompt.meta_query_guard.*` | Verhindert Meta-Queries wie „suche im Shop“ ohne konkreten Produkt-/Themenanker. |
-| `shop_prompt.language_preservation.*` | Bewahrt Sprache und korrigiert unerwünschte Übersetzungen in Shopqueries. |
 
-## **2\. `config/retriex/commerce.yaml`**
+---
 
-| YAML-Parameter | Bewirkt |
+# 3. `config/retriex/chat-messages.yaml`
-| ----- | ----- |
+
+| Parameter / Bereich | Bewirkt |
+| --- | --- |
+| `sse.empty_prompt` | Meldung bei leerem Prompt. |
+| `sse.job_*` | Meldungen für Job-Anlage, fehlende Jobs, stale Jobs und Jobfehler. |
+| `sse.claim.*` | Meldungen für abgelaufene, gesperrte, laufende oder abgeschlossene Stream-Jobs. |
+| `sse.storage.*` | Fehlermeldungen für Stream-Job-Dateispeicher. |
+| `frontend.document.title` | Browser-/Dokumenttitel. |
+| `frontend.ui.*` | Header, Footer, Buttons, Optionen und Eingabeplatzhalter im Chat. |
+| `frontend.assistant.*` | Loader-, Abbruch- und History-Meldungen im Frontend. |
+| `frontend.source_chips.*` | Labels für sichtbare Quellenchips. |
+| `frontend.run_meta.*` | Status-/Meta-Texte für abgeschlossene oder unterbrochene Antworten. |
+| `frontend.stream.*` | Frontend-Meldungen bei Streamunterbrechung oder Retry-Fällen. |
+| `frontend.guards.*` | Frontend-Guards gegen unkonkrete Shopantworten. |
+| `agent.messages.*` | Statusmeldungen während Analyse, Retrieval, Shop-Suche und Antwortgenerierung. |
+| `agent.final_answer_guard.*` | Nutzerhinweise bei gekürzten Antworten. |
+| `agent.no_llm_fallback.messages.*` | Vorgefertigte No-LLM-/No-Data-/Shop-Unavailable-Antworten. |
+| `agent.production_ui.stage_labels.*` | Statusphasen wie „Shop wird durchsucht“ oder „Antwort wird generiert“. |
+| `agent.production_ui.confidence_labels.*` | Beleglage-/Confidence-Labels im UI. |
+| `agent.production_ui.text.*` | UI-Texte für Statuskarten, Shop-Meta, Shop-Ergebnisse und Hinweise. |
+| `agent.production_ui.templates.*` | Templates für Trefferzahlen, Relevanz und History-Hinweise. |
+| `agent.production_ui.follow_up_actions.*` | Folgeaktionen wie „Im Shop suchen“, „Preis anzeigen“, „Nur Zubehör anzeigen“. |
+| `agent.source_labels.*` | Labels für RAG, Chatverlauf, Shop, externe URL und erweiterte Shopsuche. |
+| `agent.html.*` | HTML-Templates für Badges, Fehler, Think- und Info-Ausgaben. |
+
+Wichtig für v1.6.0: Follow-up-Actions können über Felder wie `material_query_template`, `hide_when_material_query_matches_current`, `hide_when_answer_matches_any`, `target_role` oder `requires_answer_anchor` kontextsensitiv versteckt werden.
+
+---
+
+# 4. `config/retriex/commerce.yaml`
+
+| Parameter / Bereich | Bewirkt |
+| --- | --- |
 | `retriex.commerce.enabled` | Schaltet Shop-/Commerce-Anbindung grundsätzlich ein/aus. |
 | `retriex.commerce.max_shop_results` | Maximale Shopware-Trefferzahl. |
 | `retriex.commerce.shop_timeout` | Timeout für Shopware-Anfragen. |
 | `store_api_base_url` | Store-API-Basis-URL. |
 | `sales_channel_access_key` | Store-API-Zugriffsschlüssel. |
-| `retriex.commerce.search_repair.*` | Globale Steuerung, wann und wie viele Repair-Suchqueries nachgeschoben werden. |
+| `retriex.commerce.search_repair.*` | Globale Steuerung, wann Repair-Suchqueries nachgeschoben werden. |
 | `retriex.commerce_query.config.cleanup_profile` | Sprachbereinigung für Commerce-Queries. |
-| `known_brands` | Markenbegriffe, die beim Query Parsing als Produkt-/Modellkontext erhalten bleiben. |
+| `known_brands` | Markenbegriffe, die beim Query Parsing erhalten bleiben. |
-| `phrases_to_remove` | Entfernt Bedienphrasen aus Shop-Suchqueries. |
+| `phrases_to_remove` | Entfernt Bedienphrasen aus Shopqueries. |
-| `filter_search_tokens` | Entfernt irrelevante Suchtokens. |
+| `filter_search_tokens` | Entfernt irrelevante Tokens aus Shopqueries. |
 | `search_control_tokens` | Tokens zur Steuerung von Suchabsicht, nicht als Produktinhalt. |
-| `search_token_corrections` | Korrigiert bekannte Tippfehler. |
+| `search_token_corrections` | Korrigiert bekannte Tippfehler, z. B. Pool-/Schwimmbad-Kontext. |
-| `search_token_canonical_map` | Vereinheitlicht Varianten, z. B. Plural/Singular oder Englisch/Deutsch. |
+| `search_token_canonical_map` | Vereinheitlicht Varianten, Plural/Singular oder Sprachvarianten. |
-| `semantic_shop_search_tokens` | Erlaubt semantische Shop-Suche auch bei indirekter Produktsprache. |
+| `vocabulary_views.semantic_shop_search_tokens` | Bindet semantische Shop-Suchbegriffe aus `vocabulary.yaml` an. |
 | `normalization.*` | Regex-Normalisierung für Commerce-Query-Text. |
-| `text.trim_characters` | Zeichen, die aus Suchtexten am Rand entfernt werden. |
+| `limits.*` | Tokenlängen, Kontextfenster und maximale Shop-Suchtoken. |
-| `limits.*` | Tokenlängen, Modellkontextfenster, maximale Shop-Suchtoken. |
+| `patterns.*` | Regex-Logik für Preise, Modelle, Zubehör, History-Kontext, Messwerte. |
-| `patterns.*` | Regex-Logik für Preise, Modellnummern, Zubehörmuster, History-Kontext, Tokenisierung. |
 | `commerce_reference_resolver.conversation_product_patterns` | Findet Produkte/Modelle im Chatverlauf. |
-| `commerce_reference_resolver.focus_term_patterns` | Erkennt Fokusbegriffe wie Indikator, Reagenz, Zubehör. |
+| `commerce_reference_resolver.focus_term_patterns` | Erkennt Fokusbegriffe wie Indikator, Reagenz, Zubehör, Filter. |
-| `shop_matching.top_product_log_limit` | Begrenzt Logging/Debug-Ausgabe für Top-Shopprodukte. |
+| `shop_matching.vocabulary_views.*` | Bindet Geräte-/Zubehörrollen aus `vocabulary.yaml` an Shop-Matching. |
-| `shop_matching.vocabulary_views` | Bindet zentrale `vocabulary.yaml`\-Views an Shop-Matching. |
+| `shop_matching.role_guard.*` | Steuert Geräte-/Zubehörfilterung bei Device- und Accessory-Queries. |
-| `shop_matching.role_guard.*` | Steuert Gerät/Zubehör-Filterung bei Device-Queries. |
+| `shop_matching.scores.*` | Gewichtung für Produktnummer, Name, Hersteller, Token-Overlap, Verfügbarkeit und Rollenbonus/-Penalty. |
-| `shop_matching.scores.*` | Gewichtung für Shop-Ranking: Produktnummer, Name, Hersteller, Token-Overlap, Rollenbonus/-penalty. |
+| `shop_matching.patterns.*` | Normalisierung und Tokenisierung für Shop-Matching. |
-| `shop_matching.patterns.*` | Normalisierung/Tokenisierung für Matching. |
 | `shop_matching.price.*` | Preisformatierung und Preisnormalisierung. |
-| `shop_matching.custom_fields.*` | Mapped Shopware-Custom-Fields auf Metadaten. |
+| `shop_matching.custom_fields.*` | Mapped Shopware-Custom-Fields auf Produktmetadaten. |
-| `shop_matching.text.*` | Textformatierung für Custom-Field-Ausgabe. |
 | `shop_matching.description.*` | Beschreibungscleanup und Längenlimit. |
-| `shop_matching.seo.relative_prefix` | URL-/SEO-Pfadbehandlung. |
 | `shop_matching.highlight.*` | Highlighttexte für Verfügbarkeit und Produktnummer. |
-| `shop_matching.image.missing_placeholder` | Placeholder für fehlende Produktbilder. |
 | `shop_matching.deduplication.separator` | Key-Separator für Shop-Deduplizierung. |
 
-## **3\. `config/retriex/governance.yaml`**
+---
 
-| YAML-Parameter | Bewirkt |
+# 5. `config/retriex/genre.yaml`
-| ----- | ----- |
+
-| `regression_baseline.*` | Definiert geschützte Regressionstokens und Pflichtmarker für bekannte stabile Fälle. |
+| Parameter / Bereich | Bewirkt |
+| --- | --- |
+| `id`, `label`, `mode`, `description` | Beschreiben das aktive Fachgenre bzw. die Domänenadaption. |
+| `adaptation_surface.*` | Dokumentiert und strukturiert die fachlichen Anpassungsflächen. |
+| `configuration_values.product_roles.*` | Geräte-/Zubehörrollen und Rollenvokabular. |
+| `configuration_values.product_attributes.*` | Produktattribute, Messparameter und relevante fachliche Terme. |
+| `configuration_values.brands_and_canonical_terms.*` | Marken, Kanonisierung und produktnahe Standardterme. |
+| `configuration_values.intent_and_routing.*` | Intent-/Routing-nahe Genrewerte. |
+| `configuration_values.context_resolution.*` | History-, Referenz- und Produktlistenanker. |
+| `configuration_values.shop_query_runtime.*` | Query-Preservation, Stopword-Cleanup, Positive Filter, Generic Device Anchors. |
+| `configuration_values.result_identity_and_answer_policy.*` | Produktidentität und Antwortpolicy. |
+| `configuration_values.search_repair.*` | Repair-Begriffe, Zubehörcode-Terme und direkte Produktsuchen. |
+| `configuration_values.retrieval_and_language.*` | Retrieval- und Language-Anbindung. |
+| `configuration_values.shop_data_mapping.*` | Shopdaten-Mapping. |
+| `configuration_values.governance_and_regression.*` | Regression- und Governance-Anker. |
+
+Wichtig: `genre.yaml` ist in v1.6.0 eine zentrale Entlastung des PHP-Cores. Domainnahe Logik wie Produktfamilienstarts, Geräteanker oder erhaltenswerte Tokens soll hier bzw. über angebundene Vocabulary-Views gepflegt werden.
+
+---
+
+# 6. `config/retriex/governance.yaml`
+
+| Parameter / Bereich | Bewirkt |
+| --- | --- |
+| `regression_baseline.*` | Definiert geschützte Regressionstokens und Pflichtmarker für stabile Flows. |
 | `vocabulary.protected_short_model_tokens` | Schützt kurze Modell-/Fachtokens vor falscher Cleanup-Entfernung. |
+| `genre_source_of_truth.*` | Steuert Genre-Source-of-Truth, Legacy-Hash-Guards und Runtime-Resolved-Paths. |
 | `language.protected_stopword_terms` | Begriffe, die trotz Stopword-Logik nicht entfernt werden dürfen. |
 | `language.required_cleanup_profiles` | Pflichtprofile, die in `language.yaml` existieren müssen. |
-| `language.required_profile_terms` | Pflichtbegriffe je Cleanup-Profil, z. B. für Regression Guardrails. |
+| `language.required_profile_term_defaults` | Default-Pflichtbegriffe je Profil. |
-| `core_pattern_audit.*` | Steuert Audit auf verdächtige hardcodierte Listen/Patterns im PHP-Core. |
+| `language.required_profile_terms` | Effektive Pflichtbegriffe für Regression Guardrails. |
+| `core_pattern_audit.*` | Audit auf verdächtige hardcodierte Listen/Patterns im PHP-Core. |
 
-## **4\. `config/retriex/index.yaml`**
+---
 
-| YAML-Parameter | Bewirkt |
+# 7. `config/retriex/index.yaml`
-| ----- | ----- |
+
+| Parameter | Bewirkt |
+| --- | --- |
 | `chunk_size` | Standardgröße für Wissenschunks beim Indexing. |
 | `chunk_overlap` | Überlappung zwischen Chunks. |
 | `embedding_model` | Fallback-/Metadatenmodell für Embeddings. |
@@ -111,55 +181,62 @@
 | `index_format` | Indexformat, aktuell NDJSON. |
 | `vector_backend` | Vector-Backend, aktuell FAISS. |
 
-## **5\. `config/retriex/intent.yaml`**
+---
 
-| YAML-Parameter | Bewirkt |
+# 8. `config/retriex/intent.yaml`
-| ----- | ----- |
+
+| Parameter / Bereich | Bewirkt |
+| --- | --- |
 | `intent.commerce.strong_signals` | Starke Shop-/Produktabsicht. |
 | `non_product_commerce_signals` | Kommerzsignale, die nicht automatisch Produktsuche bedeuten. |
-| `advisory_signals` | Beratungssignale wie Empfehlung/Eignung. |
+| `advisory_signals` | Beratungssignale wie Empfehlung oder Eignung. |
 | `advisory_product_selection_patterns` | Muster für Produktauswahlfragen. |
 | `price_terms`, `color_terms`, `size_*` | Preis-, Farb- und Größenintents. |
 | `support_diagnostic_patterns` | Trennt Support-/Diagnosefragen von Shopfragen. |
 | `explicit_commerce_intent_patterns` | Explizite Commerce-Absichten. |
-| `technical_factual_knowledge.*` | Erkennt technische Wissensfragen, die nicht als reine Shopfrage behandelt werden sollen. |
+| `technical_factual_knowledge.*` | Erkennt technische Wissensfragen, die nicht als reine Shopfrage laufen sollen. |
-| `patterns.*` | Regex für SKU, Preis, Größe, Farbe, Modellprodukte. |
+| `patterns.*` | Regex für SKU, Preis, Größe, Farbe und Modellprodukte. |
 | `labels.*` | Interne Intent-Signallabels. |
 | `scores.*` | Gewichtung der Intent-Signale. |
 | `intent.catalog.*` | Schwellenwerte für Katalog-/Listenintents. |
-| `intent.light.quantity_words` | Mengen-/Listenwörter für leichte Intent-Erkennung. |
+| `intent.light.*` | Leichte Listen-/Mengenfrage-Erkennung. |
-| `intent.light.strong_patterns` | Starke Listen-/Mengenmuster. |
+| `intent.sales.*` | Sales-, Vergleichs-, Einwand-, Implementierungs- und ROI-Fragen. |
-| `intent.sales.*` | Erkennt Sales-, Vergleichs-, Einwand-, Implementierungs- und ROI-Fragen. |
 
-## **6\. `config/retriex/language.yaml`**
+---
 
-| YAML-Parameter | Bewirkt |
+# 9. `config/retriex/language.yaml`
-| ----- | ----- |
+
+| Parameter / Bereich | Bewirkt |
+| --- | --- |
 | `words` | Legacy-/Basis-Stopwords. |
 | `protected_terms` | Begriffe, die nie generisch entfernt werden sollen. |
-| `normalization.ascii_transliteration` | Zentrale Umlaut-/ASCII-Normalisierung. |
+| `normalization.ascii_transliteration` | Umlaut-/ASCII-Normalisierung. |
-| `normalization.word_separator_chars` | Zeichen, die als Worttrenner normalisiert werden. |
+| `normalization.word_separator_chars` | Worttrenner-Normalisierung. |
 | `normalization.dash_equivalents` | Unicode-Dash-/Bindestrich-Normalisierung. |
 | `stopword_groups.de_core` | Allgemeine deutsche Stopwords. |
-| `stopword_groups.conversation` | Dialog-/Bedienwörter wie „bitte“, „mal“. |
+| `stopword_groups.conversation` | Dialog-/Bedienwörter. |
 | `stopword_groups.pronouns` | Pronomen für Referenz-/Cleanup-Logik. |
-| `stopword_groups.user_instruction_terms` | Bedienphrasen-Tokens wie „zeige“, „suche“. |
+| `stopword_groups.user_instruction_terms` | Bedienphrasen-Tokens wie „zeige“ oder „suche“. |
 | `stopword_groups.response_style` | Präsentations-/Antwortstilwörter. |
 | `stopword_groups.question_terms` | Fragewörter für Cleanup. |
 | `stopword_groups.usage_terms` | generische Nutzungs-/Anwendungswörter. |
+| `stopword_groups.shop_relation_noise` | Shopquery-Rauschen wie Relations-/Mess-/Satzwörter. |
 | `stopword_groups.reference_fillers` | Füllwörter bei Folgefragen. |
 | `phrase_groups.user_instruction` | Ganze Bedienphrasen, die aus Queries entfernt werden können. |
-| `meta_term_groups.presentation` | Präsentationswörter wie Tabelle, Liste, Übersicht. |
+| `stopword_group_sets.*` | Wiederverwendbare Gruppen-Sets. |
-| `meta_term_groups.retrieval_reference` | Meta-Wörter für Retrieval-Referenzen. |
+| `phrase_group_sets.*` | Wiederverwendbare Phrasen-Sets. |
+| `meta_term_groups.*` | Präsentations- und Retrieval-Referenzwörter. |
 | `cleanup_profiles.commerce_query` | Cleanup-Profil für Shop-/Commerce-Queries. |
 | `cleanup_profiles.rag_evidence` | Cleanup-Profil für RAG-Evidence-Prüfung. |
 | `cleanup_profiles.retrieval_reference_cleanup` | Cleanup-Profil für Retrieval-Referenzauflösung. |
 | `cleanup_profiles.shop_context_fallback` | Cleanup-Profil für Shop-Follow-up-Kontextfallback. |
 
-## **7\. `config/retriex/model.yaml`**
+---
 
-| YAML-Parameter | Bewirkt |
+# 10. `config/retriex/model.yaml`
-| ----- | ----- |
+
+| Parameter | Bewirkt |
+| --- | --- |
 | `default_name` | Standard-LLM-Modellname. |
 | `default_stream` | Standard-Streamingverhalten. |
 | `default_temperature` | Kreativität/Varianz der Modellantwort. |
@@ -173,336 +250,352 @@
 | `guardrail_max_retrieval_chunks` | Obergrenze für Chunk-Anzahl. |
 | `guardrail_max_vector_top_k` | Obergrenze für Vector-Kandidaten. |
 | `retriex.llm.timeout_seconds` | Timeout für LLM-Aufrufe. |
+| `retriex.llm.num_predict` | Vorhersage-/Output-Limit für LLM-Aufrufe. |
 
-## **8\. `config/retriex/prompt.yaml`**
+---
 
-| YAML-Parameter | Bewirkt |
+# 11. `config/retriex/prompt.yaml`
-| ----- | ----- |
+
+| Parameter / Bereich | Bewirkt |
+| --- | --- |
 | `budget.*` | Promptbudget, Outputreserve und Sicherheitsreserve. |
 | `shop_results.*` | Wie Shopprodukte in den LLM-Prompt geschrieben werden. |
 | `shop_results.fields.*` | Feldlabels für Produktnummer, Preis, Hersteller, Rollenkompatibilität usw. |
-| `technical_product_keyword_match_threshold` | Schwelle, ab wann technische Produktfrage erkannt wird. |
+| `vocabulary_views.*` | Bindet technische Produkt-, Geräte- und Zubehörbegriffe aus `vocabulary.yaml`. |
-| `technical_product_keywords` | Technische Produktbegriffe für Promptlogik. |
-| `accessory_request_keywords` | Erkennt Zubehöranfragen. |
 | `sections.*` | Überschriften der Promptsektionen. |
 | `conversation_context.intro_lines` | Regeln für Chatverlauf im Prompt. |
 | `shop_search.source_line` | Quellenzeile für Shop-Suchquery. |
 | `role_guard.*` | Gerät/Zubehör-Rollenprüfung im Prompt. |
 | `measurement_evidence_guard.*` | Schutz gegen falsche Eignungsaussagen bei Messparametern. |
-| `measurement_evidence_guard.rule_templates.*` | konkrete Regeltexte für Evidence-Prüfung. |
+| `measurement_evidence_guard.rule_templates.*` | Konkrete Regeltexte für Evidence-Prüfung. |
 | `output_priority.*` | Prioritätsregeln für Antwortaufbau. |
+| `numeric_value_focus.*` | Fokussiert numerische Werte wie Grenzwerte. |
 | `fallback_escalation.*` | Regeln je Confidence-/Evidence-State. |
-| `parameter_parsing.split_pattern` | Trennt mehrere Parameter wie „pH und Redox“. |
+| `parameter_parsing.*` | Trennt mehrere Parameter wie „pH und Redox“. |
-| `parameter_parsing.trim_characters` | Trimmt Parameterwerte. |
 | `response_format.*` | Antwortformat-Regeln mit/ohne Shopdaten. |
 | `language.rules` | Sprachregeln für die Modellantwort. |
-| `fact_grounding.*` | Fact-Grounding-Regeln, besonders gegen Halluzinationen. |
+| `fact_grounding.*` | Fact-Grounding-Regeln gegen Halluzinationen. |
 | `retrieved_knowledge.source_line` | Quellenzeile für Dokumentwissen. |
 | `url_content.source_line` | Quellenzeile für URL-Inhalte. |
 | `technical_product_model_pattern` | Regex zur Erkennung technischer Produktmodelle. |
 
-## **9\. `config/retriex/query_enrichment.yaml`**
+---
 
-| YAML-Parameter | Bewirkt |
+# 12. `config/retriex/query_enrichment.yaml`
-| ----- | ----- |
+
+| Parameter | Bewirkt |
+| --- | --- |
 | `max_expansions` | Maximale Anzahl Query-Erweiterungen. |
 | `rules.*` | Synonym-/Erweiterungsregeln für Retrieval, z. B. Wasserhärte → Resthärte. |
 
-## **10\. `config/retriex/retrieval.yaml`**
+---
 
-| YAML-Parameter | Bewirkt |
+# 13. `config/retriex/retrieval.yaml`
-| ----- | ----- |
+
+| Parameter / Bereich | Bewirkt |
+| --- | --- |
 | `hard_max_chunks` | Harte Obergrenze zurückgegebener Chunks. |
 | `hard_max_vectork` | Harte Obergrenze Vector-Kandidaten. |
 | `hard_max_keywordk` | Harte Obergrenze Keyword-Kandidaten. |
 | `vector_score_threshold` | Mindestscore für Vector-Treffer. |
 | `threshold_floor`, `threshold_ceil` | Dynamischer Score-Korridor. |
 | `list_bonus` | Bonus für Listen-/Tabellenrelevanz. |
-| `rrf_k` | RRF-Fusionsparameter. |
+| `rrf_k` | Konstante für Reciprocal Rank Fusion. |
-| `keyword_topk_multiplier` | Multiplikator für Keyword-Retrieval-Kandidaten. |
+| `keyword_topk_multiplier` | Multiplikator für Keyword-Kandidaten. |
-| `keyword_score_threshold` | Mindestscore Keyword-Treffer. |
+| `keyword_score_threshold` | Mindestscore für Keyword-Treffer. |
-| `keyword_rrf_weight` | Gewichtung Keyword-RRF. |
+| `keyword_rrf_weight` | Gewichtung von Keyword-Treffern in der Fusion. |
-| `scoped_vector_rrf_weight` | Gewichtung fokussierter Vector-Treffer. |
+| `scoped_vector_rrf_weight` | Gewichtung gescopter Vektortreffer. |
-| `scoped_keyword_rrf_weight` | Gewichtung fokussierter Keyword-Treffer. |
+| `scoped_keyword_rrf_weight` | Gewichtung gescopter Keywordtreffer. |
-| `empty_rrf_fallback_topn` | Fallback, wenn Fusion leer läuft. |
+| `empty_rrf_fallback_topn` | Fallback-Anzahl, wenn Fusion leer bleibt. |
-| `max_chunks_per_doc` | Maximalzahl Chunks pro Dokument. |
+| `max_chunks_per_doc` | Maximalchunks pro Dokument. |
-| `min_chunk_distance` | Mindestabstand zwischen Chunks. |
+| `min_chunk_distance` | Mindestabstand zwischen ausgewählten Chunks. |
-| `dominant_doc_*` | Logik zur Dominanz eines Dokuments in den Treffern. |
+| `dominant_doc_*` | Bevorzugung dominanter Dokumente bei klarer Trefferlage. |
 | `exact_document_max_chunks` | Maximalchunks bei exaktem Dokumentfokus. |
-| `focused_product_*` | Fokuslogik für ein klar erkanntes Produkt/Gerät. |
+| `focused_product_*` | Fokussierte Produktauswahl im Retrieval. |
-| `catalog_list_shortcut_patterns` | Erkennt Katalog-/Listenfragen. |
+| `catalog_list_shortcut_patterns` | Direkte Katalog-/Listenrouten. |
-| `exact_selection_*` | Präzisionslogik für Tabellen/Indikatoren/Grenzwerte. |
+| `exact_selection_*` | Präzisionslogik für Tabellen, Indikatoren, Grenzwerte und Messbereiche. |
 | `exact_detail_tokens` | Detailfrage-Tokens für gezielte Retrievalauswahl. |
 | `generic_exact_selection_cleanup_profile` | Cleanup-Profil für generische exakte Auswahl. |
-| `generic_product_tokens` | Allgemeine Produkttokens fürs Retrieval. |
+| `generic_exact_selection_tokens` | Tokens für generische exakte Auswahlfragen. |
-| `important_short_model_tokens` | Geschützte kurze Modell-/Fachtokens wie pH/RX/TC. |
+| `vocabulary_views.*` | Bindet zentrale Retrieval-Vocabulary-Views an. |
-| `family_descriptor_tokens` | Produktfamilien-/Gerätebeschreibungen. |
+| `retriex.retrieval.inventory` | Inventar-/Katalogdaten für Retrieval-Logik. |
-| `looks_like_reagent_*` | Erkennung von Reagenz-/Indikator-Dokumenten. |
-| `looks_like_safety_*` | Erkennung von Sicherheitsdatenblättern. |
-| `looks_like_document_words` | Dokumenttyp-Erkennung. |
-| `looks_like_device_words` | Geräte-/Device-Erkennung. |
-| `retriex.retrieval.inventory` | Alias auf die effektive Retrieval-Konfiguration. |
 
-## **11\. `config/retriex/runtime.yaml`**
+---
 
-| YAML-Parameter | Bewirkt |
+# 14. `config/retriex/runtime.yaml`
-| ----- | ----- |
+
+| Parameter / Bereich | Bewirkt |
+| --- | --- |
 | `retriex.root` | Projektwurzel. |
-| `retriex.knowledge.root` | Basisverzeichnis der Wissensdaten. |
+| `retriex.knowledge.root` | Knowledge-Verzeichnis. |
-| `retriex.knowledge.ndjson` | Haupt-Wissensindex. |
+| `retriex.knowledge.ndjson` | Pfad zu `index.ndjson`. |
-| `retriex.knowledge.index_meta` | Metadaten des Wissensindex. |
+| `retriex.knowledge.index_meta` | Pfad zu `index_meta.json`. |
-| `retriex.knowledge.vector_index` | FAISS-Vectorindex für Chunks. |
+| `retriex.knowledge.vector_index` | Pfad zu `vector.index`. |
-| `retriex.knowledge.vector_index_meta` | Metadaten zum Chunk-Vectorindex. |
+| `retriex.knowledge.vector_index_meta` | Pfad zu `vector.index.meta.json`. |
-| `retriex.knowledge.runtime_meta` | Runtime-/Indexstatus-Datei. |
+| `retriex.knowledge.runtime_meta` | Pfad zu `index_runtime.json`. |
 | `retriex.knowledge.upload` | Upload-Verzeichnis. |
-| `retriex.knowledge.tags_ndjson` | Tag-Indexdaten. |
+| `retriex.knowledge.tags_ndjson` | Pfad zu `tags.ndjson`. |
-| `retriex.knowledge.vector_tags_index` | FAISS-Vectorindex für Tags. |
+| `retriex.knowledge.vector_tags_index` | Pfad zu `vector_tags.index`. |
-| `retriex.knowledge.vector_tags_index_meta` | Metadaten zum Tag-Vectorindex. |
+| `retriex.knowledge.vector_tags_index_meta` | Pfad zu `vector_tags.index.meta.json`. |
 | `retriex.locks.dir` | Lock-Verzeichnis. |
-| `retriex.tags.rebuild_lock` | Lock-Datei für Tag-Rebuild. |
+| `retriex.tags.rebuild_lock` | Lock für Tag-Rebuild. |
-| `retriex.context.config.max_visible_regular_lines` | Sichtbare Kontextzeilen im Admin-/Debug-Kontext. |
+| `retriex.context.config.max_visible_regular_lines` | Reguläre sichtbare History-Lines, aktuell 25. |
-| `retriex.context.config.max_full_lines` | Maximale vollständige Kontextzeilen. |
+| `retriex.context.config.max_full_lines` | Full-Context-History-Lines, aktuell 500. |
 
-## **12\. `config/retriex/search_repair.yaml`**
+---
 
-| YAML-Parameter | Bewirkt |
+# 15. `config/retriex/search_repair.yaml`
-| ----- | ----- |
+
+| Parameter / Bereich | Bewirkt |
+| --- | --- |
 | `strict_requested_accessory_code_repair` | Erzwingt präzisere Repair-Logik bei angefragtem Zubehörcode. |
 | `prefer_prompt_anchored_model_for_requested_accessory_code` | Bevorzugt Modellanker aus Prompt/Verlauf bei Zubehörcode-Repair. |
+| `direct_product_attribute_lookup.*` | Direkte Attributsuchen wie „Anschlusskabel pH/Redox länger 20m“. |
 | `requested_accessory_code_fallback_query_templates` | Fallback-Query-Templates für Zubehörcodes. |
-| `requested_accessory_code_fallback_terms` | Begriffe für Zubehörcode-Erkennung. |
-| `requested_accessory_code_context_prefix_terms` | Kontextpräfixe für Zubehörcode-Suche. |
 | `requested_accessory_code_proximity_window` | Zeichenfenster für Nähe zwischen Modell und Zubehörcode. |
-| `specific_model_candidate_patterns` | Regex für Modellkandidaten. |
+| `specific_model_candidate_patterns` | Modellkandidaten-Erkennung. |
-| `model_candidate_exclude_terms` | Ausschlussbegriffe für falsche Modellkandidaten. |
+| `limits.top_product_log_limit` | Logging-/Debug-Begrenzung für Topprodukte. |
-| `limits.top_product_log_limit` | Debug-/Loglimit für Topprodukte. |
+| `sanitize_trim_character_codes` | Zeichen, die aus Repair-Queries getrimmt werden. |
-| `sanitize_trim_character_codes` | Zeichen-Codes für Query-Sanitizing. |
+| `product_key_separator` | Separator für Produktkeys. |
-| `product_key_separator` | Separator für Produkt-Dedupe-/Keybildung. |
+| `scores.*` | Gewichtung der Repair-Rankinglogik. |
-| `scores.*` | Scoring für Repair-Kandidaten, Prompt-Match, Query-Overlap, Spezifität. |
+| `patterns.*` | Regex-Erkennung für Modelle, Zubehörcodes, Zubehör-/Bundle-Begriffe. |
-| `patterns.*` | Regex-Templates für Modell-, Zubehör-, Bundle- und Token-Erkennung. |
 
-## **13\. `config/retriex/vector.yaml`**
+---
 
-| YAML-Parameter | Bewirkt |
+# 16. `config/retriex/vector.yaml`
-| ----- | ----- |
-| `vector.script_dir` | Verzeichnis der Python-Vector-Skripte. |
-| `python_bin` | Python-Binary für Vector-Tools. |
-| `control_script` | Vector-Service-Control-Skript. |
-| `ingest_script` | Chunk-Vector-Ingest-Skript. |
-| `search_script` | Chunk-Vector-Search-Skript. |
-| `ingest_tags_script` | Tag-Vector-Ingest-Skript. |
-| `search_tags_script` | Tag-Vector-Search-Skript. |
-| `host`, `port`, `service_url` | Vector-Service-Erreichbarkeit. |
-| `timeout` | Timeout für Vector-Prozesse. |
-| `vector.search.*` | Score-/Limit-/HTTP-Timeout für Chunk-Vector-Suche. |
-| `vector.tags.*` | Score-/Limit-/HTTP-Timeout für Tag-Vector-Suche. |
-| `vector.tag_routing.*` | Tag-basierte Dokumentvorauswahl: TopK, Mindestscore, Score-Drop, Kandidatenlimit, Multi-Tag-Bonus. |
 
-## **14\. `config/retriex/vocabulary.yaml`**
+| Parameter / Bereich | Bewirkt |
+| --- | --- |
+| `script_dir` | Verzeichnis der Python-Vector-Skripte. |
+| `python_bin` | Python-Binary. |
+| `control_script` | Script zur Service-Steuerung. |
+| `ingest_script` | Script für Hauptindex-Ingest. |
+| `search_script` | Script für Hauptindex-Suche. |
+| `ingest_tags_script` | Script für Tag-Index-Ingest. |
+| `search_tags_script` | Script für Tag-Suche. |
+| `host`, `port`, `service_url` | Vector-Service-Adresse. |
+| `timeout` | Prozess-/Service-Timeout. |
+| `search.min_score` | Mindestscore für Vector-Suche. |
+| `search.max_limit` | Maximales Suchlimit. |
+| `search.http_timeout` | HTTP-Timeout für Vector-Suche. |
+| `tags.*` | Score-, Limit- und Timeoutwerte für Tag-Suche. |
+| `tag_routing.*` | Top-K, Mindestscore, Score-Drop, Candidate-Docs und Multi-Tag-Bonus. |
 
-| YAML-Parameter | Bewirkt |
+---
-| ----- | ----- |
+
+# 17. `config/retriex/vocabulary.yaml`
+
+| Parameter / Bereich | Bewirkt |
+| --- | --- |
 | `classes.device` | Zentrale Gerätebegriffe. |
-| `classes.accessory` | Zentrale Zubehör-/Verbrauchsmaterialbegriffe. |
+| `classes.accessory` | Zentrale Zubehörbegriffe. |
-| `views.shop.device_query` | Gerätebegriffe für Shop-Queries. |
+| `classes.requested_accessory_code_terms` | Begriffe für angefragte Zubehör-/Indikatorcodes. |
-| `views.shop.accessory_query` | Zubehörbegriffe für Shop-Queries. |
+| `classes.shop_meta_terms` | Meta-Terme für Shop-Follow-ups. |
-| `views.shop.accessory_product` | Zubehörerkennung in Shop-Produkten. |
+| `classes.direct_product_attribute_stop_terms` | Stop-Terme für direkte Attributsuchen. |
-| `views.shop.device_product` | Geräteerkennung in Shop-Produkten. |
+| `classes.input_normalization_fuzzy_routing_terms` | Fuzzy-Routing-Terme für Eingabenormalisierung. |
-| `views.shop.device_focus` | Fokusbegriffe für Geräteanfragen. |
+| `classes.agent_*` | Agent-nahe Vokabulare für Follow-ups, Fallbacks und Query Preservation. |
-| `views.shop.accessory_focus` | Fokusbegriffe für Zubehöranfragen. |
+| `views.shop.*` | Shop-Views für Geräte-, Zubehör-, Fokus- und Produktrollen. |
-| `views.retrieval.*` | Vocabulary-Projektionen für Retrieval-Listen wie Reagenz, Safety, Device, Dokument. |
+| `views.retrieval.*` | Retrieval-Views für Produkt-, Modell-, Reagenz-, Dokument- und Geräteterme. |
-| `views.search_repair.*` | Vocabulary-Projektionen für Repair-Kandidaten und Spezifitätsboost. |
+| `views.search_repair.*` | Search-Repair-Views für direkte Produktsuchen und Zubehörcodes. |
-| `views.prompt.*` | Vocabulary-Projektionen für PromptBuilder-Keywords. |
+| `views.prompt.*` | Prompt-Views für technische Produkt- und Zubehörbegriffe. |
-| `maps.shop.accessory_focus_variants` | Variantenmapping für Zubehörfokus, z. B. unterschiedliche Schreibweisen. |
+| `views.agent.*` | Agent-Views für Runtime-, Follow-up- und Fallbacklogik. |
+| `maps.prompt.*` | Mapping für Prompt-Evidence-Regeln. |
+| `maps.agent.*` | Mapping für Agent-Evidence- und Query-Logik. |
+| `maps.shop.*` | Mapping für Shop-Fokusvarianten und Rollen. |
 
-## **1\. Wichtigste Stellschrauben für Antwortqualität**
+---
 
-| Datei | Parameter / Bereich | Wirkung |
+# 18. `config/packages/security.yaml`
-| ----- | ----- | ----- |
-| `config/retriex/prompt.yaml` | `retriex.prompt.config.budget.*` | Steuert Prompt-Budget, Historie, Output-Reserve und Sicherheitsreserve. Wichtig, wenn Antworten Quellen verlieren oder zu wenig Kontext bekommen. |
-| `prompt.yaml` | `retriex.prompt.config.shop_results.max_results_in_prompt` | Anzahl der Shop-Treffer, die überhaupt ins LLM-Prompt gelangen. Sehr wichtiger Hebel für Shop-Antworten. |
-| `prompt.yaml` | `retriex.prompt.config.shop_results.detailed_max_count` | Wie viele Shop-Treffer detailliert in den Prompt geschrieben werden. |
-| `prompt.yaml` | `retriex.prompt.config.shop_results.header_lines` | Regeln, wie das LLM Shopdaten behandeln darf. Wichtig gegen Vermischung von Gerät/Zubehör/Preis/URL. |
-| `prompt.yaml` | `retriex.prompt.config.technical_product_keyword_match_threshold` | Schwelle, ab wann eine Anfrage als technische Produktfrage behandelt wird. |
-| `prompt.yaml` | `retriex.prompt.config.technical_product_keywords` | Begriffe für technische Antwortlogik. |
-| `prompt.yaml` | `retriex.prompt.config.accessory_request_keywords` | Begriffe für Zubehör-/Indikator-/Reagenzfragen. |
-| `prompt.yaml` | `retriex.prompt.config.role_guard.*` | Gerät-vs-Zubehör-Abgrenzung im Prompt. Sehr wichtig gegen falsche Produkttypen. |
-| `prompt.yaml` | `retriex.prompt.config.measurement_evidence_guard.*` | Messparameter-Beweislogik, z. B. pH, Redox, freies Chlor. Wichtig gegen erfundene Eignungen. |
-| `prompt.yaml` | `retriex.prompt.config.measurement_evidence_guard.parameters[]` | Konkrete Messparameter mit `request_terms`, `positive_terms`, `negative_context_terms`, `non_equivalent_terms`. Sehr direkter Qualitätshebel. |
-| `prompt.yaml` | `retriex.prompt.config.output_priority.*` | Priorität der Antwort: fachliche Fakten, Shopdaten, technische Regeln. |
-| `prompt.yaml` | `retriex.prompt.config.numeric_value_focus.*` | Verhalten bei niedrigstem/höchstem Grenzwert, exakten Zahlenwerten, Messbereichen. |
-| `prompt.yaml` | `retriex.prompt.config.fallback_escalation.*` | Was bei unsicherer Evidenz, fehlenden Daten oder nur semantischen Treffern gesagt werden darf. |
-| `prompt.yaml` | `retriex.prompt.config.response_format.*` | Struktur der Antwort, Shop-/Nicht-Shop-Regeln, Zubehörregeln. |
-| `prompt.yaml` | `retriex.prompt.config.fact_grounding.*` | Regeln gegen Halluzination, falsche Kombination von Quellen und falsche Shop-/RAG-Vermischung. |
-| `prompt.yaml` | `retriex.prompt.config.language.rules` | Sprachverhalten der Antwort. |
-| `prompt.yaml` | `retriex.prompt.config.parameter_parsing.*` | Zerlegung von Messparametern wie pH/Redox/Chlor. |
-| `config/retriex/model.yaml` | `retriex.model.default_temperature` | Kreativität. Für technische Antworten eher niedrig halten. |
-| `model.yaml` | `retriex.model.default_top_k` | Sampling-Breite des LLM. |
-| `model.yaml` | `retriex.model.default_top_p` | Nucleus-Sampling. |
-| `model.yaml` | `retriex.model.default_repeat_penalty` | Wiederholungsverhalten. |
-| `model.yaml` | `retriex.model.default_num_ctx` | Kontextfenster. Wichtig bei langen RAG-/Shop-Prompts. |
-| `model.yaml` | `retriex.model.default_retrieval_max_chunks` | Default-Anzahl genutzter Chunks. |
-| `model.yaml` | `retriex.model.default_retrieval_vector_top_k` | Default-Vektor-Kandidatenzahl. |
 
-## **2\. Wichtigste Stellschrauben für RAG-Suchergebnisse**
+Diese Datei liegt nicht unter `config/retriex`, ist aber für v1.6.0 zentral.
 
-| Datei | Parameter / Bereich | Wirkung |
+| Bereich | Bewirkt |
-| ----- | ----- | ----- |
+| --- | --- |
-| `config/retriex/retrieval.yaml` | `retriex.retrieval.config.hard_max_chunks` | Maximale Chunks in der finalen Auswahl. Einer der wichtigsten Antwort-/Kontexthebel. |
+| `providers.app_user_provider` | Gemeinsamer User-Provider über `App\Entity\User`. |
-| `retrieval.yaml` | `hard_max_vectork` | Maximale Vektor-Kandidaten. |
+| `firewalls.admin` | Admin-Firewall für `^/admin`, inklusive Login, Logout, Remember-Me, User-Checker und Access-Denied-Handler. |
-| `retrieval.yaml` | `hard_max_keywordk` | Maximale Keyword-Kandidaten. |
+| `firewalls.chat` | Chat-Firewall für `/`, `/chat`, `/ask-jobs`, `/ask-sse`, `/history`, `/chat-messages/frontend`. |
-| `retrieval.yaml` | `vector_score_threshold` | Mindestscore für Vektortreffer. |
+| `firewalls.main` | Öffentliche/statische Restfläche. |
-| `retrieval.yaml` | `threshold_floor` / `threshold_ceil` | Dynamischer Score-Korridor. |
+| `role_hierarchy` | Rollenvererbung für Super Admin, Knowledge Admin, Editor, Admin Area und Chat User. |
-| `retrieval.yaml` | `list_bonus` | Bonus für Listen-/Tabellenähnliche Treffer. Wichtig für Produktlisten/Grenzwerte. |
+| `access_control` | Konkrete serverseitige Route-zu-Rolle-Matrix. |
-| `retrieval.yaml` | `rrf_k` | Stärke des Reciprocal-Rank-Fusion-Verhaltens. |
+| `access_denied_handler` | Einheitliche 403-Seite für falsche Bereichs-/Rollenwechsel. |
-| `retrieval.yaml` | `keyword_topk_multiplier` | Erweitert Keyword-Kandidatenset. |
+| `user_checker` | Sperrt deaktivierte Benutzer beim Login. |
-| `retrieval.yaml` | `keyword_score_threshold` | Mindestscore für Keyword-Treffer. |
-| `retrieval.yaml` | `keyword_rrf_weight` | Gewichtung Keyword-Treffer gegen Vektortreffer. |
-| `retrieval.yaml` | `scoped_vector_rrf_weight` | Gewichtung scoped Vector Retrieval. |
-| `retrieval.yaml` | `scoped_keyword_rrf_weight` | Gewichtung scoped Keyword Retrieval. |
-| `retrieval.yaml` | `empty_rrf_fallback_topn` | Fallback, wenn RRF leer bleibt. |
-| `retrieval.yaml` | `max_chunks_per_doc` | Verhindert, dass ein Dokument zu stark dominiert. |
-| `retrieval.yaml` | `min_chunk_distance` | Abstand zwischen Chunks desselben Dokuments. |
-| `retrieval.yaml` | `dominant_doc_window`, `dominant_doc_min_hits`, `dominant_doc_max_chunks` | Dominantes Dokument erkennen und begrenzen/gewichten. |
-| `retrieval.yaml` | `exact_document_max_chunks` | Maximalzahl bei exakter Dokumentfokussierung. |
-| `retrieval.yaml` | `focused_product_window`, `focused_product_min_score`, `focused_product_min_gap`, `focused_product_max_chunks` | Produktfokus-Logik. Kritisch für Testomat-/Indikator-Fälle. |
-| `retrieval.yaml` | `catalog_list_shortcut_patterns` | Erkennung von Listen-/Katalogfragen. |
-| `retrieval.yaml` | `exact_selection_*` | Exakte Auswahlfragen, z. B. Indikator/Grenzwert/Messbereich/Testomat. |
-| `retrieval.yaml` | `exact_detail_tokens` | Detailfrage-Erkennung. |
-| `retrieval.yaml` | `generic_exact_selection_cleanup_profile` | Cleanup-Profil für exakte Auswahl. |
-| `retrieval.yaml` | `generic_product_tokens` | Generische Produktbegriffe, die beim Retrieval anders behandelt werden. |
-| `retrieval.yaml` | `important_short_model_tokens` | Geschützte Kurzmodell-/Parameter-Tokens wie `pH`, `TH`, `RX`. Sehr wichtig. |
-| `retrieval.yaml` | `family_descriptor_tokens` | Produktfamilien-Zusätze wie EVO/ECO/PLUS usw. |
-| `retrieval.yaml` | `looks_like_reagent_*`, `looks_like_safety_*`, `looks_like_document_*`, `looks_like_device_*` | Dokument-/Produktrollen-Erkennung im Retrieval. |
-| `config/retriex/vector.yaml` | `retriex.vector.search.min_score` | Mindestscore der Vektorsuche. |
-| `vector.yaml` | `retriex.vector.search.max_limit` | Maximal abrufbare Vektortreffer. |
-| `vector.yaml` | `retriex.vector.tags.min_score` | Mindestscore Tag-Suche. |
-| `vector.yaml` | `retriex.vector.tags.default_limit` / `max_limit` | Anzahl Tag-Treffer. |
-| `vector.yaml` | `retriex.vector.tag_routing.default_topk` | Top-K für Tag-Routing. |
-| `vector.yaml` | `retriex.vector.tag_routing.min_best_score` | Mindestscore für beste Tag-Zuordnung. |
-| `vector.yaml` | `retriex.vector.tag_routing.max_score_drop_from_best` | Wie stark schlechtere Tags noch mitgenommen werden. |
-| `vector.yaml` | `retriex.vector.tag_routing.max_routing_tags` | Maximal verwendete Routing-Tags. |
-| `vector.yaml` | `retriex.vector.tag_routing.max_candidate_docs` | Maximal aus Tags abgeleitete Kandidatendokumente. |
-| `vector.yaml` | `multi_tag_bonus_per_extra_tag`, `max_multi_tag_bonus` | Bonus für mehrere passende Tags. |
-| `config/retriex/index.yaml` | `retriex.index.chunk_size` | Chunk-Größe beim Ingest. Nur nach Reindex wirksam. |
-| `index.yaml` | `retriex.index.chunk_overlap` | Chunk-Überlappung. Nur nach Reindex wirksam. |
-| `index.yaml` | `retriex.index.embedding_model` | Embedding-Modell. Sehr großer Hebel, aber nur mit Reindex. |
-| `index.yaml` | `retriex.index.embedding_dimension` | Passend zum Embedding-Modell. |
-| `config/retriex/query_enrichment.yaml` | `retriex.query_enrichment.config.max_expansions` | Maximale Query-Erweiterungen. |
-| `query_enrichment.yaml` | `retriex.query_enrichment.config.rules.*` | Synonym-/Erweiterungsregeln, z. B. Wasserhärte → Resthärte. |
 
-## **3\. Shop-Suche und Shop-Ranking**
+Wichtig: `ROLE_USER` ist nur technische Basisrolle. Sie darf nicht als Bereichsberechtigung für Chat oder Admin verwendet werden.
 
-| Datei | Parameter / Bereich | Wirkung |
+---
-| ----- | ----- | ----- |
-| `config/retriex/commerce.yaml` | `retriex.commerce.max_shop_results` | Maximale Shop-Treffer aus Shopware. |
-| `commerce.yaml` | `retriex.commerce.search_repair.enabled` | Erweiterte Shop-Suche aktivieren/deaktivieren. |
-| `commerce.yaml` | `retriex.commerce.search_repair.max_queries` | Anzahl Repair-Suchqueries. |
-| `commerce.yaml` | `retriex.commerce.search_repair.min_primary_results_without_repair` | Ab wann keine Repair-Suche nötig ist. |
-| `commerce.yaml` | `retriex.commerce_query.config.cleanup_profile` | Language-Cleanup-Profil für Shopqueries. |
-| `commerce.yaml` | `retriex.commerce_query.config.known_brands` | Markenerkennung. |
-| `commerce.yaml` | `phrases_to_remove` | Entfernt unnötige Phrasen aus Shopqueries. |
-| `commerce.yaml` | `filter_search_tokens` | Entfernt irrelevante Tokens aus Shopqueries. |
-| `commerce.yaml` | `search_control_tokens` | Tokens, die Shop-/Suchabsicht anzeigen. |
-| `commerce.yaml` | `search_token_corrections` | Tippfehlerkorrekturen für Shopquery. |
-| `commerce.yaml` | `search_token_canonical_map` | Vereinheitlichung von Tokens, z. B. indicators → indikator. |
-| `commerce.yaml` | `semantic_shop_search_tokens` | Produkt-/Zubehörbegriffe für semantische Shop-Suche. |
-| `commerce.yaml` | `limits.max_shop_search_tokens` | Maximale Tokenzahl der Shopquery. |
-| `commerce.yaml` | `limits.direct_product_max_tokens` | Begrenzung direkter Produktsuchen. |
-| `commerce.yaml` | `patterns.*` | Regex-Erkennung für Preis, Modell, Zubehör, Historienbezug, Messwerte. |
-| `commerce.yaml` | `retriex.commerce_reference_resolver.config.conversation_product_patterns` | Produktanker aus dem Chatverlauf. |
-| `commerce.yaml` | `retriex.commerce_reference_resolver.config.focus_term_patterns` | Fokusbegriffe wie Indikator, Reagenz, Zubehör, Filter. |
-| `commerce.yaml` | `retriex.shop_matching.config.vocabulary_views.*` | Verknüpfung zu Vocabulary-Listen für Geräte-/Zubehörrollen. |
-| `commerce.yaml` | `retriex.shop_matching.config.role_guard.*` | Zubehör bei Gerätefragen filtern oder ambigue Treffer behalten. |
-| `commerce.yaml` | `retriex.shop_matching.config.scores.*` | Direktes Shop-Ranking: Produktnummer, Name, Hersteller, Token-Overlap, Größenmatch, Verfügbarkeit, Geräte-/Zubehörbonus/-Penalty. |
-| `commerce.yaml` | `retriex.shop_matching.config.description.max_length` | Länge der Shopbeschreibung im Such-/Promptkontext. |
-| `commerce.yaml` | `retriex.shop_matching.config.deduplication.separator` | Dedupe-Key-Aufbau. |
-| `config/retriex/search_repair.yaml` | `strict_requested_accessory_code_repair` | Strenge Repair-Logik für angefragte Zubehörcodes. |
-| `search_repair.yaml` | `prefer_prompt_anchored_model_for_requested_accessory_code` | Modellanker aus Prompt bevorzugen. |
-| `search_repair.yaml` | `direct_product_attribute_lookup.*` | Direkte Attributsuchen wie „Anschlusskabel pH/Redox länger 20m“. |
-| `search_repair.yaml` | `requested_accessory_code_*` | Fallback-Queries und Kontextfenster für Indikator-/Reagenz-Codes. |
-| `search_repair.yaml` | `specific_model_candidate_patterns` | Modellkandidaten-Erkennung. |
-| `search_repair.yaml` | `model_candidate_exclude_terms` | Ausschlussbegriffe für falsche Modellanker. |
-| `search_repair.yaml` | `scores.*` | Gewichtung der Repair-Rankinglogik. |
-| `search_repair.yaml` | `patterns.*` | Regex-Erkennung für Modelle, Zubehörcodes, Zubehör-/Bundle-Begriffe. |
-| `config/retriex/agent.yaml` | `retriex.agent.config.product_search_knowledge_chunk_limit` | Anzahl Knowledge-Chunks bei Produktsuche. |
-| `agent.yaml` | `advisory_product_search_knowledge_chunk_limit` | Knowledge-Chunks bei beratender Produktsuche. |
-| `agent.yaml` | `commerce_history_budget_chars` | Wie viel Verlauf für Commerce-Kontext genutzt wird. |
-| `agent.yaml` | `shop_prompt.*` | LLM-Regeln zur Erzeugung der Shop-Suchquery. Sehr wichtiger Hebel. |
-| `agent.yaml` | `shop_prompt.current_input_preservation.*` | Bewahrt aktuelle Eingabetokens wie pH/Redox/ORP. |
-| `agent.yaml` | `shop_prompt.product_attribute_query_cleanup.*` | Cleanup für direkte Attribut-/Zubehörsuchen. |
-| `agent.yaml` | `shop_prompt.context_anchor_enrichment.*` | Ergänzt Shopquery aus Verlaufskontext. |
-| `agent.yaml` | `shop_prompt.meta_query_guard.*` | Löst „suche im shop“ über Verlauf auf. |
-| `agent.yaml` | `shop_prompt.rag_anchor_enrichment.*` | Reichert Shopquery mit RAG-Produktankern an, z. B. bei exakten Messwerten. |
-| `agent.yaml` | `shop_prompt.language_preservation.*` | Verhindert unerwünschte Übersetzung in Shopqueries. |
 
-## **4\. Intent- und Routing-Optimierung**
+# 19. Wichtigste Stellschrauben für Antwortqualität
 
-| Datei | Parameter / Bereich | Wirkung |
+| Datei | Bereich | Wirkung |
-| ----- | ----- | ----- |
+| --- | --- | --- |
-| `config/retriex/intent.yaml` | `retriex.intent.commerce.config.strong_signals` | Starke Shop-/Commerce-Signale. |
+| `prompt.yaml` | `fact_grounding.*` | Verhindert unbelegte Behauptungen. |
-| `intent.yaml` | `non_product_commerce_signals` | Commerce-Signale ohne Produktsuche. |
+| `prompt.yaml` | `measurement_evidence_guard.*` | Schützt Messparameter-/Eignungsaussagen. |
-| `intent.yaml` | `advisory_signals` | Beratungssignale. |
+| `prompt.yaml` | `output_priority.*` | Priorisiert Antwortaufbau. |
-| `intent.yaml` | `advisory_product_selection_patterns` | Muster für Produktauswahlfragen. |
+| `prompt.yaml` | `numeric_value_focus.*` | Hält Grenzwerte und exakte Zahlen im Fokus. |
-| `intent.yaml` | `price_terms`, `color_terms`, `size_*` | Preis-/Farb-/Größenfilter-Erkennung. |
+| `model.yaml` | `default_num_ctx`, `num_predict` | Kontext- und Antwortbudget. |
-| `intent.yaml` | `support_diagnostic_patterns` | Support-/Diagnosefragen abgrenzen. |
+| `retrieval.yaml` | `hard_max_chunks`, `threshold_*`, `focused_product_*` | Menge und Qualität des RAG-Kontexts. |
-| `intent.yaml` | `explicit_commerce_intent_patterns` | Explizite Shopabsicht. |
+| `language.yaml` | `cleanup_profiles.*` | Qualität der Query- und Evidence-Bereinigung. |
-| `intent.yaml` | `technical_factual_knowledge.*` | Erkennung technischer Wissensfragen, damit nicht alles in Shoplogik läuft. |
+| `vocabulary.yaml` | `views.prompt.*`, `views.retrieval.*` | Fachbegriffe und sichere Matching-Begriffe. |
-| `intent.yaml` | `scores.*` | Gewichtung von Commerce-/Advisory-/SKU-/Preis-/Modell-Signalen. |
-| `intent.yaml` | `retriex.intent.catalog.config.*` | Tag-/Katalogintent-Schwellen: `min_score`, `ambiguity_delta`, Limits. |
-| `intent.yaml` | `retriex.intent.light.config.*` | Leichte Listen-/Mengenfrage-Erkennung. |
-| `intent.yaml` | `retriex.intent.sales.config.*` | Sales-/ROI-/Vergleichs-/Einwand-Intent. |
-| `agent.yaml` | `input_normalization.*` | Vor-Normalisierung der Nutzereingabe. |
-| `agent.yaml` | `input_normalization.fuzzy_routing.*` | Tippfehlerrobustes Routing für Shop-/Produkt-/Messbegriffe. |
-| `agent.yaml` | `follow_up_context.strong_reference_patterns` | Folgefrage-Erkennung. |
-| `agent.yaml` | `follow_up_context.explicit_commercial_signal_terms` | Folgefrage wird zu Shop-/Preis-/Commerce-Kontext. |
-| `agent.yaml` | `follow_up_context.commercial_table_follow_up.*` | Tabellen-/Preisfolgefragen. |
-| `agent.yaml` | `follow_up_context.reference_anchor.*` | Verlaufanker wie Testomat-Modell oder Härtewert. |
 
-## **5\. Sprachbereinigung und Vocabulary**
+---
 
-| Datei | Parameter / Bereich | Wirkung |
+# 20. Wichtigste Stellschrauben für RAG-Suchergebnisse
-| ----- | ----- | ----- |
-| `config/retriex/language.yaml` | `retriex.stopwords.config.words` | Allgemeine Stopwords. |
-| `language.yaml` | `protected_terms` | Begriffe, die niemals generisch entfernt werden dürfen. Sehr wichtig für `pH`, `RX`, `TH`, `0,02`, Testomat usw. |
-| `language.yaml` | `normalization.*` | Umlaut-/ASCII-/Separator-/Dash-Normalisierung. |
-| `language.yaml` | `stopword_groups.*` | Sprach-, Dialog-, Pronomen-, Frage- und Bedienwörter. |
-| `language.yaml` | `phrase_groups.user_instruction` | Entfernt Phrasen wie „ich suche“, „zeige mir“. |
-| `language.yaml` | `meta_term_groups.*` | Präsentations-/Meta-Begriffe wie Tabelle, Liste, Übersicht. |
-| `language.yaml` | `cleanup_profiles.commerce_query` | Cleanup für Shopqueries. |
-| `language.yaml` | `cleanup_profiles.rag_evidence` | Cleanup für RAG-Evidenzprüfung. |
-| `language.yaml` | `cleanup_profiles.retrieval_reference_cleanup` | Cleanup für Retrieval-Referenzen. |
-| `language.yaml` | `cleanup_profiles.shop_context_fallback` | Cleanup für Verlauf-Fallback bei Shop-Folgefragen. |
-| `config/retriex/vocabulary.yaml` | `classes.device` | Zentrale Gerätebegriffe. |
-| `vocabulary.yaml` | `classes.accessory` | Zentrale Zubehörbegriffe. |
-| `vocabulary.yaml` | `views.shop.device_query` | Begriffe für Geräte-Shopqueries. |
-| `vocabulary.yaml` | `views.shop.accessory_query` | Begriffe für Zubehör-Shopqueries. |
-| `vocabulary.yaml` | `views.shop.accessory_product` | Erkennung von Zubehörprodukten. |
-| `vocabulary.yaml` | `views.shop.device_product` | Erkennung von Geräteprodukten. |
-| `vocabulary.yaml` | `views.shop.device_focus` | Fokus auf Geräte. |
-| `vocabulary.yaml` | `views.shop.accessory_focus` | Fokus auf Zubehör. |
-| `vocabulary.yaml` | `views.retrieval.*` | Retrieval-Vokabular: generische Produkttokens, Kurzmodell-Tokens, Reagenz-/Safety-/Device-Erkennung. |
-| `vocabulary.yaml` | `views.search_repair.*` | Vocabulary für Search-Repair und direkte Produktsuchen. |
-| `vocabulary.yaml` | `views.prompt.technical_product_keywords` | Prompt-Vocabulary für technische Fragen. |
-| `vocabulary.yaml` | `views.prompt.accessory_request_keywords` | Prompt-Vocabulary für Zubehörfragen. |
-| `vocabulary.yaml` | `maps.shop.accessory_focus_variants` | Varianten/Normalisierung von Zubehörfokusbegriffen. |
 
-## **6\. Sekundär relevant, aber nicht primär zum Tuning**
+| Datei | Bereich | Wirkung |
+| --- | --- | --- |
+| `retrieval.yaml` | `vector_score_threshold`, `threshold_floor`, `threshold_ceil` | Relevanzschwelle für Treffer. |
+| `retrieval.yaml` | `rrf_k`, `keyword_rrf_weight`, `scoped_*_weight` | Fusion von Keyword-, globaler und gescopter Suche. |
+| `retrieval.yaml` | `max_chunks_per_doc`, `min_chunk_distance` | Diversität und Redundanz der Chunks. |
+| `retrieval.yaml` | `exact_selection_*` | Präzision bei Tabellen-/Indikator-/Grenzwertfragen. |
+| `query_enrichment.yaml` | `rules.*` | Synonyme und Query-Erweiterungen. |
+| `vector.yaml` | `search.min_score`, `tag_routing.*` | Vector- und Tagrouting-Schwellen. |
+| `index.yaml` | `chunk_size`, `chunk_overlap` | Granularität des Index. |
+| `language.yaml` | `cleanup_profiles.retrieval_reference_cleanup` | Referenzbereinigung bei Folgefragen. |
 
-| Datei | Parameter / Bereich | Einschätzung |
+---
-| ----- | ----- | ----- |
+
-| `config/retriex/governance.yaml` | `retriex.governance.config.regression_baseline.*` | Nicht direkt zur Antwortoptimierung, sondern Schutz gegen Regressionen. Nur ändern, wenn Tests/Guardrails bewusst angepasst werden. |
+# 21. Shop-Suche und Shop-Ranking
+
+| Datei | Bereich | Wirkung |
+| --- | --- | --- |
+| `agent.yaml` | `shop_prompt.*` | Erzeugt kurze Shop-Suchqueries. |
+| `agent.yaml` | `shop_runtime.query_cleanup.*` | Entfernt Noise und erhält wichtige aktuelle Tokens. |
+| `agent.yaml` | `shop_runtime.context_resolution.*` | Löst referenzielle Shop-Folgefragen über Verlauf/RAG. |
+| `agent.yaml` | `shop_runtime.result_identity.*` | Filtert auf primäre Produktidentität. |
+| `commerce.yaml` | `search_token_corrections` | Tippfehlerkorrekturen für Shopqueries. |
+| `commerce.yaml` | `search_token_canonical_map` | Token-Kanonisierung. |
+| `commerce.yaml` | `shop_matching.scores.*` | Ranking für Shopprodukte. |
+| `commerce.yaml` | `shop_matching.role_guard.*` | Hauptgerät-/Zubehör-Abgrenzung. |
+| `search_repair.yaml` | `requested_accessory_code_*` | Exakte Indikator-/Reagenz-/Zubehörcode-Reparatur. |
+| `genre.yaml` | `shop_query_runtime.*` | Domänenspezifische Shopquery-Preservation und Generic Device Anchors. |
+| `vocabulary.yaml` | `views.shop.*`, `views.search_repair.*` | Geräte-/Zubehör-/Repair-Vokabular. |
+
+---
+
+# 22. Intent- und Routing-Optimierung
+
+| Datei | Bereich | Wirkung |
+| --- | --- | --- |
+| `intent.yaml` | `intent.commerce.*` | Commerce-Erkennung. |
+| `intent.yaml` | `intent.catalog.*` | Katalog-/Listenrouten. |
+| `intent.yaml` | `intent.light.*` | leichte Listen-/Mengenfrage-Erkennung. |
+| `intent.yaml` | `intent.sales.*` | Sales-, ROI-, Vergleichs- und Einwandfragen. |
+| `agent.yaml` | `input_normalization.*` | Tippfehler- und Routing-Normalisierung. |
+| `agent.yaml` | `follow_up_context.*` | Folgefrage-Erkennung und Kontextmaterialisierung. |
+| `genre.yaml` | `intent_and_routing.*` | Genre-nahe Routingkonfiguration. |
+
+---
+
+# 23. Sprachbereinigung und Vocabulary
+
+| Datei | Bereich | Wirkung |
+| --- | --- | --- |
+| `language.yaml` | `protected_terms` | Schützt kritische Kurztokens wie Modell-/Mess-/Code-Terme. |
+| `language.yaml` | `stopword_groups.shop_relation_noise` | Entfernt Relationstokens wie Mess-/Satzrauschen aus Shopqueries. |
+| `language.yaml` | `cleanup_profiles.commerce_query` | Hauptprofil für Shopquery-Cleanup. |
+| `language.yaml` | `cleanup_profiles.rag_evidence` | Hauptprofil für Evidence-Cleanup. |
+| `vocabulary.yaml` | `classes.*` | Wiederverwendbare Fachwortklassen. |
+| `vocabulary.yaml` | `views.*` | Kontextbezogene Views auf Fachwortklassen. |
+| `vocabulary.yaml` | `maps.*` | Mapping-Tabellen für Varianten, Synonyme und Fokusbegriffe. |
+| `genre.yaml` | `configuration_values.*.vocabulary_views` | Bindet Genre-Konfiguration an zentrale Vocabulary-Views. |
+
+---
+
+# 24. UI-, Chat- und Follow-up-Tuning
+
+| Datei | Bereich | Wirkung |
+| --- | --- | --- |
+| `chat-messages.yaml` | `frontend.ui.*` | Texte für Chatoberfläche. |
+| `chat-messages.yaml` | `frontend.stream.*` | Retry-/Stream-Hinweise. |
+| `chat-messages.yaml` | `agent.production_ui.stage_labels.*` | Statuskarten-Phasen. |
+| `chat-messages.yaml` | `agent.production_ui.confidence_labels.*` | Beleglage-Labels. |
+| `chat-messages.yaml` | `agent.production_ui.follow_up_actions.*` | Folgeaktions-Chips und Sichtbarkeitsregeln. |
+| `agent.yaml` | `production_ui.shop_results.max_cards` | Maximal sichtbare Shopkarten. |
+| `templates/chat/index.html.twig` | Struktur | Icons und Text-Spans für Chatbuttons. |
+| `public/assets/js/base.js` | Verhalten | Frontend-Streaming, UI-Karten und Message-Mapping. |
+
+---
+
+# 25. Security-, Rollen- und Admin-Tuning
+
+| Datei | Bereich | Wirkung |
+| --- | --- | --- |
+| `config/packages/security.yaml` | `role_hierarchy` | Rollenvererbung. |
+| `config/packages/security.yaml` | `access_control` | Serverzugriff je Route. |
+| `src/Security/ApplicationRoles.php` | `assignableChoices()` | Rollen, die UI/Console zuweisen dürfen. |
+| `src/Security/ActiveUserChecker.php` | Loginprüfung | Blockiert deaktivierte Benutzer. |
+| `src/Security/ActiveUserSessionSubscriber.php` | Sessionprüfung | Meldet deaktivierte eingeloggte Benutzer ab. |
+| `src/Security/AccessDeniedHandler.php` | 403 Handling | Rendert Bereichs-/Rollenfehler. |
+| `templates/admin/base.html.twig` | Navigation | Blendet Adminbereiche rollengerecht aus. |
+| `templates/admin/user/*` | Userverwaltung | Benutzerliste, Anlage, Bearbeitung. |
+
+---
+
+# 26. Sekundär relevant, aber nicht primär zum fachlichen Tuning
+
+| Datei | Bereich | Einschätzung |
+| --- | --- | --- |
+| `governance.yaml` | `regression_baseline.*` | Schutz gegen Regressionen; nur bewusst ändern. |
 | `governance.yaml` | `core_pattern_audit.*` | Developer-/Audit-Regeln, keine direkte Suchqualität. |
-| `config/retriex/runtime.yaml` | `retriex.context.config.max_visible_regular_lines`, `max_full_lines` | Kann beeinflussen, wie viel Kontext sichtbar/ausgegeben wird, aber kein primärer Rankinghebel. |
+| `runtime.yaml` | Pfade zu Knowledge/Index/Locks | Infrastruktur, nicht fachliche Qualität. |
-| `runtime.yaml` | Pfade zu Knowledge/Index/Locks | Infrastruktur, nicht Antwortqualität. |
+| `vector.yaml` | Host, Port, Script-Pfade, Timeouts | Betrieb/Performance, nicht fachliche Qualität. |
-| `config/retriex/vector.yaml` | Host, Port, Script-Pfade, Timeouts | Betrieb/Performance, nicht fachliche Qualität. |
+| `commerce.yaml` | API-URL, Access-Key, Timeout | Verfügbarkeit/Performance der Shopdaten. |
-| `config/retriex/commerce.yaml` | `shop_timeout`, API-URL, Access-Key | Verfügbarkeit/Performance der Shopdaten, nicht Rankingqualität. |
+| `chat-messages.yaml` | reine UI-Texte | UX-relevant, fachlich nur indirekt. |
-| `config/retriex/agent.yaml` | `messages`, `production_ui`, `source_labels`, `html` | UX-/Anzeige-Texte, nicht fachliche Antwortoptimierung. |
 
-## **Empfohlene Tuning-Reihenfolge**
+---
 
-Für bessere Suchergebnisse zuerst `retrieval.yaml`, `vector.yaml`, `query_enrichment.yaml`, `language.yaml` und `vocabulary.yaml` anfassen.
+# 27. Empfohlene Tuning-Reihenfolge
 
-Für bessere Shop-Suche zuerst `agent.yaml` → `shop_prompt.*`, dann `commerce.yaml` → `commerce_query.*` / `shop_matching.*`, danach `search_repair.yaml`.
+Für bessere RAG-Suchergebnisse zuerst:
 
-Für bessere Antwortqualität zuerst `prompt.yaml` → `fact_grounding`, `measurement_evidence_guard`, `output_priority`, `numeric_value_focus`, `response_format`, danach `model.yaml`.
+1. `retrieval.yaml`
+2. `query_enrichment.yaml`
+3. `vector.yaml`
+4. `language.yaml`
+5. `vocabulary.yaml`
+
+Für bessere Shop-Suche zuerst:
+
+1. `agent.yaml` → `shop_prompt.*`, `shop_runtime.*`
+2. `commerce.yaml` → `commerce_query.*`, `shop_matching.*`
+3. `search_repair.yaml`
+4. `genre.yaml`
+5. `vocabulary.yaml`
+
+Für bessere Antwortqualität zuerst:
+
+1. `prompt.yaml` → `fact_grounding`, `measurement_evidence_guard`, `output_priority`, `numeric_value_focus`, `response_format`
+2. `model.yaml`
+3. `agent.yaml` → `rag_evidence_guard`, `no_llm_fallback`
+4. `chat-messages.yaml` für sichtbare Hinweise und Folgeaktionen
+
+Für Rollen, Login und Adminzugriff zuerst:
+
+1. `config/packages/security.yaml`
+2. `src/Security/ApplicationRoles.php`
+3. Controller-Guards unter `src/Controller/Admin/`
+4. Admin-Templates unter `templates/admin/`
+
+---
+
+# 28. Pflichtchecks nach Konfigurationsänderungen
+
+```bash
+php bin/console cache:clear
+php bin/console lint:yaml config/packages/security.yaml config/retriex
+php bin/console lint:twig templates
+php bin/console mto:agent:config:validate
+php bin/console mto:agent:regression:test
+php bin/console mto:agent:config:audit-source --details
+php bin/console mto:agent:config:audit-patterns --details
+```
+
+Bei Änderungen an Shopquery-, Follow-up- oder Vocabulary-Regeln zusätzlich manuell prüfen:
+
+- exakte Indikator-/Zubehörcodes, z. B. `300` ohne `300 S`
+- Mehrprodukt-Follow-ups mit Einzelqueries
+- Preis-Folgeaktionen nach mehreren sichtbaren Produkten
+- schwache referenzielle Shopfragen mit History-Anker
+- direkte Produktnamen wie `chlor select sensor`
+- Modellkürzel wie `testomat lab cl`
+- Tippfehlerkorrektur mit erhaltenem Anwendungskontext

DELETE_PUBLIC_INDEX_HTML.txt

@@ -1,7 +0,0 @@
-Important when applying this patch manually:
-
-Delete public/index.html from the target installation.
-
-The chat root route is now handled by Symfony via App\Controller\Chat\ChatController.
-If public/index.html remains on disk, the web server may still serve the static file
-before Symfony handles /, which would bypass the chat firewall and ROLE_CHAT_USER check.

MANAGEMENT_SUMMARY.md

@@ -1,82 +1,125 @@
-# Management Summary
+# Management Summary – RetrieX v1.6.0
 
 ## RetrieX in einem Satz
 
-RetrieX ist ein kontrolliertes, dokumentenbasiertes KI-System, das Unternehmenswissen, Suchlogik und optional Live-Produktdaten so verbindet, dass belastbare, nachvollziehbare und fachlich nutzbare Antworten entstehen.
+RetrieX v1.6.0 ist ein kontrolliertes, dokumentenbasiertes KI-System, das Unternehmenswissen, Retrieval-Logik, Rollen-/Berechtigungssteuerung und optional Live-Produktdaten so verbindet, dass belastbare, nachvollziehbare und fachlich nutzbare Antworten entstehen.
+
+## Was sich mit Version 1.6.0 verändert hat
+
+Version 1.6.0 ist nicht nur ein fachlicher RAG-/Shop-Stand, sondern ein deutlich produktionsnäherer Systemstand. Neben den stabilisierten Antwort-, Retrieval- und Commerce-Flows enthält der Stand nun eine sauber getrennte Chat- und Admin-Oberfläche, eine Rollenmatrix, eine Admin-Benutzerverwaltung, bessere Fehlerseiten sowie weitere Guardrails gegen unscharfe Shop- und Folgefragen.
+
+Der aktuelle Fokus liegt damit auf drei Ebenen:
+
+1. **Antwortqualität und Präzision**  
+   Exakte Produkt-, Zubehör-, Indikator- und Preis-Folgefragen bleiben stärker auf den tatsächlichen Kontext fokussiert.
+
+2. **Betrieb und Governance**  
+   Chat, Admin, Userverwaltung, Rollen, Login/Logout und Fehlerfälle sind klarer strukturiert.
+
+3. **Konfigurierbarkeit statt Core-Sonderlogik**  
+   Fachliche Listen, Vokabulare, Guardrails, UI-Texte und Query-Regeln bleiben überwiegend YAML-gestützt und damit wartbar.
 
 ## Worum es bei RetrieX wirklich geht
 
-RetrieX ist nicht einfach ein Chatbot.  
+RetrieX ist kein frei antwortender Chatbot. Das System ist darauf ausgelegt, Antworten nicht zu erfinden, sondern sie auf kontrollierte Daten- und Regelquellen zu stützen:
-Das System ist darauf ausgelegt, Antworten nicht frei zu erfinden, sondern sie auf eine klar gesteuerte Wissensbasis zu stützen. Grundlage sind versionierte Dokumente, definierte Systemregeln, reproduzierbare Indexierungsprozesse und eine kontrollierte Anfrageverarbeitung.
+
+- aktive, versionierte Wissensdokumente
+- deterministische Ingest- und Indexprozesse
+- hybrides Retrieval mit Routing und Tag-Vorselektion
+- optional autoritative Live-Shopdaten aus Shopware
+- zentral gepflegte Prompt-, Intent-, Vocabulary-, Language- und Commerce-Regeln
+- abgesicherte Chat- und Adminbereiche mit Rollenmodell
 
 Damit wird aus generativer KI ein betrieblich einsetzbares Assistenzsystem.
 
 ## Geschäftlicher Nutzen
 
-RetrieX schafft einen strukturierten Zugang zu Unternehmenswissen und reduziert die typische Schwäche klassischer KI-Systeme: unzuverlässige, nicht belegbare Antworten.
+RetrieX schafft einen strukturierten Zugang zu Unternehmenswissen und reduziert typische Risiken generischer KI-Systeme: unklare Quellen, instabile Antworten, schwer nachvollziehbare Produktberatung und fehlende Governance.
 
-Der Nutzen liegt insbesondere in vier Punkten:
+Der Nutzen liegt insbesondere in fünf Punkten:
 
 1. **Bessere Wissensnutzung**  
    Vorhandene Dokumente werden in eine aktiv nutzbare Wissensbasis überführt.
 
 2. **Höhere Antwortqualität**  
-   Antworten entstehen auf Basis realer Inhalte statt rein statistischer Modellvermutung.
+   Antworten entstehen aus realen Dokument- und Shopdaten statt aus reiner Modellvermutung.
 
-3. **Mehr Governance und Kontrolle**  
+3. **Präzisere Commerce-Unterstützung**  
-   Aktive Dokumentversionen, System-Prompts und Ingest-Regeln sind klar steuerbar.
+   Preis-, Zubehör-, Geräte- und Produktlink-Folgefragen bleiben enger am sichtbaren Antwortkontext und an konkreten Produktidentitäten.
 
-4. **Erweiterbarkeit für Commerce und Beratung**  
+4. **Mehr Governance und Betriebssicherheit**  
-   Bei Produktanfragen können zusätzlich Live-Shopdaten eingebunden werden, sodass nicht nur erklärt, sondern auch konkret beraten werden kann.
+   Rollen, Benutzerverwaltung, aktive Versionen, System-Prompts, Ingest-Regeln und Konfigurationsaudits sind steuerbar.
+
+5. **Skalierbarkeit für Beratung und Support**  
+   Fachliche Antworten, Shopdaten, Follow-up-Actions und UI-Statusinformationen bilden zusammen eine nutzbare Beratungsoberfläche.
 
 ## Strategische Einordnung
 
-RetrieX ist als Brücke zwischen Wissensmanagement, Assistenzsystem und digitaler Beratung zu verstehen.
+RetrieX ist als Brücke zwischen Wissensmanagement, Assistenzsystem, Produktberatung und kontrollierter KI-Operationalisierung zu verstehen.
 
 Das System verbindet:
 
 - dokumentiertes Unternehmenswissen
 - technische Such- und Routinglogik
 - KI-gestützte Formulierung
-- optional produktbezogene Echtzeitdaten
+- optionale Shopware-Live-Daten
+- rollenbasierte Bedien- und Administrationsbereiche
 
-Dadurch entsteht kein isoliertes KI-Feature, sondern eine skalierbare Wissens- und Antwortinfrastruktur.
+Dadurch entsteht keine isolierte Chat-Funktion, sondern eine ausbaufähige Wissens- und Antwortinfrastruktur.
 
 ## Zentrale Architekturidee
 
-Das System trennt klar zwischen vier Ebenen:
+Das System trennt klar zwischen fünf Ebenen:
 
-- **Wissensquellen**: Dokumente, Versionen, Systemregeln, Konfigurationen
+- **Wissensquellen**: Dokumente, aktive Versionen, Systemregeln, Konfigurationen
-- **Index und Suche**: aufbereitete Chunks, Metadaten, Vektorindizes, Routing
+- **Index und Suche**: Chunks, Metadaten, FAISS-Indizes, Tag-Routing, Retrieval-Regeln
-- **Orchestrierung**: Anfrageverarbeitung, Retrieval, Prompt-Aufbau, Streaming
+- **Orchestrierung**: Anfrageverarbeitung, Kontextauflösung, Retrieval, Commerce, Prompt-Aufbau, Streaming
-- **Ausgabe**: nutzbare Antwort im Frontend
+- **Ausgabe**: Chat-Frontend, SSE-Stream, Statuskarten, Quellen- und Follow-up-Actions
+- **Betrieb/Governance**: Adminbereich, Rollenmatrix, Userverwaltung, Fehlerseiten, Audits und Regressionstests
 
 Diese Trennung ist wesentlich, weil sie Transparenz, Wartbarkeit und kontrollierte Weiterentwicklung ermöglicht.
 
 ## Warum der aktuelle Ansatz belastbar ist
 
-RetrieX setzt nicht auf einen unkontrollierten „KI fragt einfach ein Modell“-Ansatz, sondern auf einen technisch disziplinierten Ablauf:
+RetrieX v1.6.0 setzt nicht auf einen unkontrollierten „KI fragt einfach ein Modell“-Ablauf, sondern auf einen disziplinierten Prozess:
 
-- Dokumente sind versioniert
+- Dokumente sind versioniert.
-- nur aktive Inhalte zählen
+- Nur aktive Versionen fließen in den Index ein.
-- der Wissensindex wird deterministisch erzeugt
+- Ingest und Vector-Rebuild folgen festen Regeln.
-- strukturelle Änderungen sind durch Guardrails abgesichert
+- Strukturänderungen werden über Guardrails abgesichert.
-- Retrieval und Prompt-Aufbau folgen festen Regeln
+- Retrieval und Prompt-Aufbau sind konfiguriert und auditierbar.
-- Produktdaten können als autoritative Live-Quelle eingebunden werden
+- Shopdaten können als führende Produktquelle eingebunden werden.
+- Chat- und Adminbereich sind sicherheitlich getrennt.
+- Rollen steuern sichtbar und serverseitig, wer welche Bereiche nutzen darf.
+- Folgefragen werden mit Verlauf, sichtbaren Produkten und konkreten Artikelnummern abgeglichen.
 
-Damit ist RetrieX deutlich besser für produktive, unternehmensrelevante Nutzung geeignet als ein generischer Chatbot.
+Damit ist RetrieX deutlich näher an einem produktiv betreibbaren Unternehmenssystem als an einem Prototyp-Chatbot.
 
 ## Bedeutung für das Management
 
-Für das Management ist entscheidend:  
+Für das Management ist entscheidend: RetrieX operationalisiert Wissen kontrolliert. Das System ermöglicht nicht nur Antworten, sondern steuerbare Prozesse für Wissenspflege, Produktberatung, Nutzerzugang und Systembetrieb.
-RetrieX ist keine Spielerei und kein Frontend-Gimmick, sondern ein System zur kontrollierten Operationalisierung von Wissen.
 
-Es schafft die Voraussetzung dafür, dass:
+Version 1.6.0 schafft die Voraussetzung dafür, dass:
 
 - Wissen konsistenter nutzbar wird
-- Beratungs- und Supportprozesse skaliert werden können
+- Beratungs- und Supportprozesse skalierbarer werden
-- Produktinformationen gezielt in KI-Antworten einfließen
+- Produktinformationen und Preise gezielt einfließen
-- Governance, Nachvollziehbarkeit und Wartbarkeit erhalten bleiben
+- Benutzer und Rollen zentral verwaltet werden können
+- falsche Bereichszugriffe verständlich behandelt werden
+- fachliche Regeln ohne Core-Code-Änderungen weiterentwickelt werden können
+
+## Aktuelle Stärken von v1.6.0
+
+- Eigenständiger Symfony-Chatcontroller für `/` und `/chat`
+- Getrennte Chat- und Admin-Firewalls mit gemeinsamen User-Provider
+- Rollenmodell mit `ROLE_CHAT_USER`, `ROLE_ADMIN_AREA`, `ROLE_EDITOR`, `ROLE_KNOWLEDGE_ADMIN` und `ROLE_SUPER_ADMIN`
+- Admin-Userverwaltung inklusive Aktiv-/Deaktiv-Logik und Self-Protection
+- Freundliche 403/404/500-Fehlerseiten und Access-Denied-Behandlung
+- Präzisere Shopquery-Bereinigung für Noise-, Relations- und Tippfehlerfälle
+- Exakte Zubehör-/Indikatorcode-Guards, z. B. Indikatortyp `300` ohne `300 S`-Vermischung
+- Mehrprodukt-Follow-ups mit Einzelqueries statt unscharfer Kombi-Suche
+- Preis-Folgeaktionen mit sichtbaren Produktidentitäten und Produktnummern
+- YAML-gestützte Vocabulary-, Genre-, Prompt-, Language- und Commerce-Regeln
 
 ## Zielbild
 
@@ -86,16 +129,18 @@ Nicht das Modell steht im Mittelpunkt, sondern die Kombination aus:
 
 - kuratiertem Wissen
 - kontrollierter Suchlogik
+- belastbaren Produktdaten
+- rollenbasierter Bedienung
 - klarer Systemsteuerung
 - nutzbarer Ausgabe für reale Anwendungsfälle
 
 ## Fazit
 
-RetrieX verwandelt statische Dokumente und Konfigurationslogik in ein steuerbares Assistenzsystem für Wissen, Beratung und Produktkontext.
+RetrieX v1.6.0 verwandelt statische Dokumente, Konfigurationslogik und optionale Shopdaten in ein steuerbares Assistenzsystem für Wissen, Beratung und Produktkontext.
 
 Die strategische Stärke liegt darin, dass das System zwei Welten sauber verbindet:
 
-- **Verlässlichkeit und Governance**
+- **Verlässlichkeit, Governance und Betriebssicherheit**
 - **Flexibilität und Nutzerfreundlichkeit durch KI**
 
-Damit ist RetrieX eine belastbare Grundlage für den produktiven Einsatz generativer KI im Unternehmen.
+Damit ist RetrieX v1.6.0 eine belastbare Grundlage für den produktiven Einsatz generativer KI im Unternehmen.

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
+- Antworten sollen nicht frei erfunden werden.
-- Wissen stammt primär aus den aktivierten Dokumenten im System
+- Wissen stammt primär aus aktivierten Dokumentversionen.
-- die KI formuliert auf Basis von abgerufenem Kontext
+- Die KI formuliert auf Basis von abgerufenem Kontext.
-- bei Produktanfragen können zusätzlich Live-Shopdaten einbezogen werden
+- 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
+- Dokumente sind versioniert.
-- pro Dokument gibt es fachlich genau eine aktive Version
+- Pro Dokument gibt es fachlich genau eine aktive Version.
-- nur aktive Inhalte fließen in den Wissensindex ein
+- Nur aktive Inhalte fließen in den Wissensindex ein.
-- Chunks sind abgeleitete Artefakte, keine manuell gepflegte Primärquelle
+- 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
+1. Dokumentinhalt wird extrahiert.
-2. Inhalt wird in Chunks zerlegt
+2. Inhalt wird in Chunks zerlegt.
-3. Chunk-Datensätze werden in `index.ndjson` geschrieben
+3. Chunk-Datensätze werden in `index.ndjson` geschrieben.
-4. der Vektorindex wird vollständig neu aufgebaut
+4. Der Vektorindex wird vollständig neu aufgebaut.
-5. Laufzeit-Metadaten werden aktualisiert
+5. Runtime-Metadaten werden aktualisiert.
+6. Der Status der Version wird auf `INDEXED` gesetzt.
 
-Der Ingest ist bewusst **deterministisch** aufgebaut.  
+Der Ingest ist bewusst deterministisch aufgebaut. Derselbe Datenstand soll denselben Indexzustand erzeugen.
-Das heißt: derselbe Datenstand soll immer wieder 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
+- Query Cleaning
-- zusätzliches Tag-Routing zur Vorselektion möglicher Dokumente
+- Query Enrichment
-- Score-basierte Auswahl relevanter Chunks
+- 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.  
+Diese Datei ist wichtig für Guardrails. Wenn sich Strukturparameter ändern, darf lokaler Ingest nicht einfach weiterlaufen.
-Wenn sich die 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.
+Diese Ebene unterstützt Tag-Routing und Kandidatendokument-Vorselektion.
-
-Sie ist eine ergänzende Routing-Schicht, kein Ersatz für das Hauptretrieval.
 
 ---
 
@@ -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.  
+Dokumente besitzen Versionen. Diese Versionen sind der eigentliche inhaltliche Träger.
-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
+Orchestriert Einzel-Ingest, Global Reindex und Lösch-/Reset-Flows.
-- 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
 
 ---
 
 # 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.
+Dann ist ein Global Reindex erforderlich.
-
-Stattdessen wird ein **Global Reindex** erforderlich.
-
-Das verhindert inkonsistente Mischzustände.
 
 ---
 
 # 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
+- konsistenter Chunk-Bestand
-- `index.ndjson` wird vollständig neu geschrieben
+- konsistenter Vektorindex
-- der Vektorindex wird komplett neu gebaut
+- aktualisierte Runtime-Metadaten
-- die `index_version` wird erhöht
+- 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
+- bereinigte Nutzerfrage
-- Query-Enrichment
+- Query-Enrichment-Regeln
-- Intent-Erkennung
+- Intent-Routing
+- Vektortreffer
 - Tag-Routing
-- globale Vektorsuche
+- gescopte Suche
-- optional gescopte Vektorsuche auf Kandidatendokumente
+- RRF-/Score-Fusion
-- Fusion und Auswahl relevanter Chunks
+- dokumentbezogene Begrenzung
-
-Das Ziel ist nicht einfach „mehr Treffer“, sondern **passendere, stabilere Kontexterzeugung**.
-
----
 
 ## Tag-Routing
 
-Vor der eigentlichen Chunk-Auswahl kann das System thematisch passende Dokumente über Tags eingrenzen.
+Tags können Kandidatendokumente vorselektieren. Dadurch kann die spätere Vektorsuche fokussierter laufen.
-
-Das reduziert die Suchfläche und erhöht die Wahrscheinlichkeit, dass relevante Dokumente bevorzugt werden.
-
----
 
 ## Katalog-/Listenroute
 
-Für bestimmte Anfragen erkennt das System, dass keine klassische Chunk-Antwort, sondern eher eine Listen- oder Katalogausgabe sinnvoll ist.
+Katalog- oder Listenfragen können direkt in einen Katalogblock führen, statt nur einzelne Textchunks zu liefern.
-
-Dann kann statt normaler Chunk-Selektion ein Katalogblock erzeugt werden.
-
----
 
 ## Ergebnisbegrenzung
 
-Die Zahl der zurückgegebenen Wissens-Chunks ist konfigurationsgetrieben.
+Parameter aus `retrieval.yaml`, `model.yaml` und `prompt.yaml` begrenzen Kandidaten, Chunks und Promptbudget.
-
-Wichtige Steuergrößen sind:
-
-- `retrievalMaxChunks`
-- `retrievalVectorTopK`
-
-Diese Werte stammen aus der aktiven Modell-/Generierungskonfiguration.
 
 ---
 
 # 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
+Mögliche Zustände:
-
-Die Anfrage wird heuristisch auf Commerce-Signale geprüft, zum Beispiel:
 
+- keine Commerce-Suche
 - Produktsuche
-- Preisbezug
+- beratende Produktsuche
-- Größen-/Farbhinweise
-- SKU-ähnliche Nummern
-- typische Produkt- oder Empfehlungsfragen
 
-Das Ergebnis ist einer von drei Zuständen:
+## `CommerceQueryParser`
 
-- `none`
+Bereinigt und normalisiert Shopqueries:
-- `product_search`
-- `advisory_product_search`
 
----
+- 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.
+Führt die Shopware-Suche aus und kann Repair-Queries nachschieben, wenn primäre Treffer fehlen oder zu ungenau sind.
-
-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
-
----
 
 ## 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:
+- Produktname
-
+- Artikelnummer
-- für reale Produktdaten sind Live-Shopdaten führend
+- Preis
-- Wissens-Chunks bleiben unterstützend
+- Verfügbarkeit
-- das System trennt damit Produktwahrheit und Dokumentwissen bewusst voneinander
+- 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:
+Der Inhalt wird als unterstützende Quelle in den Prompt aufgenommen, nicht als Primärindex gespeichert.
-
-- 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.
 
 ---
 
 # 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.
+Aktiver System-Prompt.
-
-Er ist die führende Regel- und Verhaltensbasis des Modells.
-
----
 
 ## 2. Gesprächskontext
 
-Frühere Nachrichten des Nutzers werden als autoritativer Konversationskontext eingebunden.
+Historie des Nutzers, regulär oder explizit als Full-Context.
-
-So bleibt der Dialog über mehrere Turns konsistent.
-
----
 
 ## 3. Live-Shop-Block
 
-Wenn Shop-Ergebnisse vorliegen, werden diese als eigener Block eingebaut.
+Shopware-Produkte mit Produktnummer, Preis, Verfügbarkeit, Hersteller, URL und weiteren Feldern.
-
-Sie sind für Produktfragen führend.
-
----
 
 ## 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:
+Der Job-basierte Flow unterstützt Statusabfrage, Event-IDs, Replay/Tailing und Stale-Erkennung.
-
-- Buffer geleert
-- Cookies weitergereicht
-- SSE-Header gesetzt
-- Daten als `data:`-Zeilen gesendet
-- am Ende ein `done`-Event ausgeliefert
 
 ## Vorteil
 
-Das Frontend kann Antworten live darstellen und laufend erweitern.
+Der Browser erhält schrittweise Ausgabe und kann Statusinformationen, Shopkarten und Folgeaktionen während bzw. nach der Antwort anzeigen.
-
-Das verbessert die Benutzererfahrung deutlich, besonders bei längeren Antworten.
 
 ---
 
 # 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
+- regulär: 25 Zeilen
-- Einbindung früherer Turns in den Prompt
+- Full-Context: 500 Zeilen
-- Persistierung der finalen Antworthistorie
 
-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
+Viele fachliche Listen liegen bewusst in YAML und nicht hartcodiert im PHP-Core.
-- 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.
 
 ---
 
 # 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 Dokumentversion aktiv ist
-
+- wann ingestiert oder reindiziert wird
-- welche Dokumente im System existieren
+- welche System-Prompts aktiv sind
-- welche Version aktiv ist
+- welche Modellkonfiguration genutzt wird
-- welche Ingest-Profile gelten
+- welche Ingest-Profile sichtbar bzw. aktiv sind
-- wann Reindexing ausgelöst wird
+- welche Benutzer Zugriff auf Chat oder Admin haben
-- welcher System-Prompt aktiv ist
-- welche Modellkonfiguration aktiv ist
-- ob und wie Commerce integriert ist
 
 ---
 
 # 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.  
+Nur aktive Versionen zählen.
-Falsche Aktivierung bedeutet falscher Wissensstand.
 
 ## 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:
+- Keine freie Wissensbehauptung ohne Datenbasis.
-
+- Aktive Dokumentversionen sind fachliche Primärquelle.
-- dokumentenzentriert statt modellzentriert
+- Shopdaten sind autoritativ für Produkt-/Preis-/Verfügbarkeitsdaten.
-- deterministisch statt zufällig orchestriert
+- Technische Eignung darf nicht aus Shopdaten allein überinterpretiert werden.
-- reproduzierbar statt implizit
+- YAML ist Source of Truth für konfigurierbare Fachlogik.
-- governance-fähig statt unkontrolliert
+- PHP-Core soll Orchestrierung leisten, nicht Domainlisten verstecken.
-- hybrid im Retrieval
+- Rollen müssen UI-seitig und serverseitig konsistent sein.
-- erweiterbar durch Shopdaten
+- Regressionstests schützen bekannte stabile Flows.
-- streamingfähig in der Ausgabe
 
 ---
 
 # Was RetrieX ausdrücklich nicht ist
 
-RetrieX ist im aktuellen Design:
+RetrieX ist nicht:
 
-- kein rein freier LLM-Chat
+- ein frei improvisierender Chatbot
-- kein ausschließlich kreatives Generierungssystem
+- ein Ersatz für Datenpflege
-- kein manuell gepflegter Chunk-Editor
+- ein Ersatz für validierte technische Beratung in Grenzfällen
-- kein Produktkatalog ohne Wissenslogik
+- ein manuell gepflegter Chunk-Editor
-- kein rein vektorbasierter Blackbox-Sucher
+- ein Shop-Scraper
-
+- ein unkontrollierter Prompt-Wrapper um ein LLM
-Es ist ein **kontrolliertes Antwortsystem**, das Wissen, Routing, Produktdaten und Modellformulierung zusammenführt.
 
 ---
 
 # Kurz zusammengefasst
 
-RetrieX arbeitet im Kern so:
+1. Dokumente und Versionen definieren den Wissensstand.
-
+2. Ingest erzeugt Chunks und FAISS-Indizes.
-1. Dokumente und Versionen definieren den Wissensstand
+3. Retrieval sucht gezielt Kontext.
-2. Ingest erzeugt daraus NDJSON-Chunks
+4. Commerce kann Shopware-Daten ergänzen.
-3. daraus wird der FAISS-Index vollständig neu aufgebaut
+5. PromptBuilder setzt Systemregeln, Kontext, Shopdaten und Frage zusammen.
-4. bei einer Anfrage laufen Retrieval, Routing und optional Commerce-Suche
+6. Das LLM formuliert die Antwort.
-5. PromptBuilder kombiniert Systemregeln, Kontext, Wissenschunks, URL-Inhalte und Shopdaten
+7. SSE streamt die Antwort ins Frontend.
-6. das Modell formuliert daraus die Antwort
+8. Rollen und Adminlogik steuern Zugriff und Betrieb.
-7. die Ausgabe wird per SSE ins Frontend gestreamt
+9. YAML- und Audit-Guardrails schützen die Wartbarkeit.
-
-Kurzform:
-
-**Dokumente → Ingest → NDJSON → Vector Index → Retrieval → Prompt-Aufbau → LLM-Antwort → SSE-Streaming**
 
 ---
 
 # Merksatz
 
-> Sie steuern in RetrieX nicht einfach nur ein Modell.  
+RetrieX v1.6.0 ist kein Chatbot mit Dokumentanhang, sondern eine kontrollierte Antwortinfrastruktur aus Wissen, Suche, Shopdaten, Rollenmodell und Governance.
-> 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.

README.md

@@ -1,24 +1,27 @@
 # README.md
 
-# RetrieX
+# RetrieX v1.6.0
 
 > Hinweis: Das System wird fachlich als **RetrieX** bezeichnet.  
 > Im Repository existieren aus historischen Gründen noch einzelne Bezeichner wie `RAG`, `rag.zip` oder `RAG_SYSTEM_OVERVIEW.md`.
 
 ## Überblick
 
-RetrieX ist ein dokumentenbasiertes Assistenzsystem auf Basis von Retrieval-Augmented Generation.
+RetrieX ist ein dokumentenbasiertes Assistenzsystem auf Basis von Retrieval-Augmented Generation. Version 1.6.0 kombiniert den stabilisierten RAG-/Commerce-Kern mit einer produktionsnäheren Chat-/Admin-Architektur.
 
-Das System beantwortet Nutzeranfragen nicht rein frei, sondern kombiniert:
+Das System beantwortet Nutzeranfragen nicht frei, sondern kombiniert:
 
 - versionierte Wissensdokumente
 - deterministische Ingest- und Indexierungslogik
-- hybrides Retrieval mit Routing
+- hybrides Retrieval mit Tag-Routing
 - optionale Shopware-Live-Produktsuche
+- YAML-gestützte Intent-, Language-, Vocabulary-, Prompt- und Commerce-Regeln
 - LLM-basierte Antwortformulierung
 - SSE-Streaming für die Browserausgabe
+- getrennte Chat- und Adminbereiche mit Rollenmodell
+- Admin-Benutzerverwaltung und Access-Denied-/Fehlerseiten
 
-Der aktuelle Stand ist kein generischer Chatbot, sondern eine kontrollierte Wissens- und Antwortpipeline.
+Der aktuelle Stand ist kein generischer Chatbot, sondern eine kontrollierte Wissens-, Antwort- und Betriebs-Pipeline.
 
 ---
 
@@ -53,20 +56,89 @@ Der aktuelle Stand ist kein generischer Chatbot, sondern eine kontrollierte Wiss
 RetrieX trennt klar zwischen:
 
 1. **Primärquellen**  
-   Dokumente, Dokumentversionen, aktive System-Prompts, Modellkonfigurationen, optionale Shopdaten
+   Dokumente, Dokumentversionen, aktive System-Prompts, Modellkonfigurationen, optionale Shopware-Daten
 
 2. **Index- und Retrieval-Ebene**  
    `index.ndjson`, `index_meta.json`, `index_runtime.json`, `vector.index`, `tags.ndjson`, `vector_tags.index`
 
 3. **Orchestrierung**  
-   Anfrageannahme, Kontextaufbau, URL-Analyse, Retrieval, Commerce-Erkennung, Prompt-Aufbau, Streaming
+   Anfrageannahme, Kontextaufbau, URL-Analyse, Retrieval, Commerce-Erkennung, Shopquery-Reparatur, Prompt-Aufbau, Streaming
 
 4. **Ausgabe**  
-   Token-Streaming an das Frontend über Server-Sent Events
+   Chat-Frontend, SSE-Stream, Statuskarten, Shopkarten, Quellenchips und kontextsensitive Folgeaktionen
+
+5. **Betrieb und Governance**  
+   Chat-/Admin-Security, Rollenmatrix, Userverwaltung, Fehlerseiten, Konfigurationsvalidierung, Source-Audits und Regressionstests
 
 ---
 
-## Aktuell unterstützte Dokumentformate
+## Version 1.6.0 – wesentliche Neuerungen gegenüber 1.5.x
+
+### Chat- und Admin-Architektur
+
+- Der Chat läuft über `App\Controller\Chat\ChatController`.
+- `/` und `/chat` rendern `templates/chat/index.html.twig`.
+- Die frühere statische `public/index.html` ist entfernt.
+- Admin-Routen bleiben unter `/admin...` getrennt.
+- Chat-Login und Chat-Logout laufen über `/chat/login` und `/chat/logout`.
+
+### Rollen und Security
+
+RetrieX nutzt weiterhin eine gemeinsame User-Entity, trennt aber die Bereichsrechte:
+
+| Rolle | Zweck |
+| --- | --- |
+| `ROLE_CHAT_USER` | Zugriff auf Chat, Ask/SSE, History und Frontend-Messages |
+| `ROLE_ADMIN_AREA` | Zugriff auf Adminbasis, Dashboard, Guides und Jobübersicht |
+| `ROLE_EDITOR` | Dokumente, Versionen, Tags und Dokument-Ingest |
+| `ROLE_KNOWLEDGE_ADMIN` | Modell-/Retrieval-Konfiguration lesen/testen und Ingest-Profile ansehen |
+| `ROLE_SUPER_ADMIN` | Userverwaltung, Systembereiche, Logs, Reset/Delete, Global Reindex und kritische Umschaltungen |
+
+Die Hierarchie ist in `config/packages/security.yaml` definiert. `ROLE_USER` ist nur technische Basisrolle und schaltet keinen Bereich allein frei.
+
+### Admin-Benutzerverwaltung
+
+`ROLE_SUPER_ADMIN` kann Benutzer im Adminbereich verwalten:
+
+- Benutzerliste
+- Benutzer anlegen
+- Benutzer bearbeiten
+- Rollen zuweisen
+- Passwort setzen/zurücksetzen
+- Benutzer aktivieren/deaktivieren
+- Schutz gegen Selbst-Aussperren
+- Schutz des letzten aktiven Super-Admins
+
+Deaktivierte Benutzer werden beim Login über `ActiveUserChecker` blockiert und bestehende Sessions über `ActiveUserSessionSubscriber` beendet.
+
+### Fehler- und Access-Denied-UX
+
+Version 1.6.0 enthält konsistente Fehlerseiten für:
+
+- 403 / fehlende Rolle
+- 404 / Route nicht gefunden
+- 500 / Serverfehler
+- generische Fehlerfälle
+
+Der `AccessDeniedHandler` zeigt bei falschem Bereich die benötigte Rolle, den aktuellen Benutzer und sinnvolle Rücksprung- bzw. Logout-Optionen.
+
+### Commerce- und Follow-up-Präzision
+
+Die Commerce-Logik wurde weiter gehärtet:
+
+- Shopqueries entfernen stärker Sprach-, Satz- und Relationsrauschen.
+- Tippfehlerkorrekturen aus `commerce.yaml` bleiben in der finalen Query erhalten.
+- Direkte Produktnamen wie `chlor select sensor` bleiben erhalten.
+- Modellkürzel wie `Testomat LAB CL` werden nicht mehr auf `testomat` reduziert.
+- Exakte Zubehör-/Indikatorcodes wie `300` werden nicht mit Varianten wie `300 S` vermischt.
+- Mehrprodukt-Follow-ups werden in Einzelqueries aufgeteilt.
+- Preis-Folgeaktionen nutzen sichtbare Produktidentitäten inklusive Produktnummern.
+- Schwache referenzielle Shopfragen wie „suche im Shop nach der Information“ können auf den letzten konkreten Produktanker aus der History zurückfallen.
+- Wiederholende Folgeaktions-Loops werden unterdrückt, wenn die materialisierte Query identisch mit der aktuellen Query ist.
+
+---
+
+## Unterstützte Dokumentformate
 
 Der verifizierte aktuelle Loader unterstützt:
 
@@ -74,30 +146,28 @@ Der verifizierte aktuelle Loader unterstützt:
 - TXT
 - MD
 
-Wichtig:  
+Wichtig: Im aktuellen Code-Stand ist kein produktiver DOCX-Loader in der eigentlichen Ingest-Pipeline sichtbar. Dokumentation und Tests sollten deshalb bewusst nur die real verifizierten Formate nennen.
-Im aktuellen Code-Stand ist **kein produktiver DOCX-Loader** in der eigentlichen Ingest-Pipeline sichtbar. Die README sollte deshalb bewusst nur die real verifizierten Formate nennen.
 
 ---
 
-## Laufzeitfluss einer Anfrage
+## Laufzeitfluss einer Browser-Anfrage
 
-Der zentrale Browser-Endpunkt ist:
+Der aktuelle Chat nutzt bevorzugt den Job-basierten SSE-Flow:
 
-- `POST /ask-sse`
+1. Frontend sendet `POST /ask-jobs` mit Prompt und optionalem Kontextflag.
+2. `AskSseController` legt einen Antwort-Job an.
+3. Frontend öffnet `GET /ask-sse/{jobId}`.
+4. `AgentRunner` orchestriert die Anfrage.
+5. Optional wird URL-Inhalt aus der Nutzerfrage extrahiert.
+6. `NdjsonHybridRetriever` holt Wissenskontext.
+7. Optional erkennt `CommerceIntentLite` Commerce-/Shop-Intent.
+8. Shopquery wird optimiert, bereinigt, ggf. repariert und über Shopware gesucht.
+9. `PromptBuilder` baut den finalen LLM-Prompt.
+10. `OllamaClient` streamt die Modellantwort.
+11. Chunks werden als SSE-Events ins Frontend gesendet.
+12. Der Turn wird in der Gesprächshistorie persistiert.
 
-Die Anfrage läuft im aktuellen Stand vereinfacht so:
+Zusätzlich existiert weiterhin `POST /ask-sse` als direkter Streaming-Endpunkt.
-
-1. `AskSseController` nimmt die Anfrage entgegen
-2. `ClientIdResolver` bestimmt eine stabile Client-ID
-3. Antwort wird als **SSE-Stream** geöffnet
-4. `AgentRunner` orchestriert den kompletten Ablauf
-5. Optional wird URL-Inhalt aus dem Prompt extrahiert
-6. `RetrieverInterface` bzw. `NdjsonHybridRetriever` holt Wissenskontext
-7. Optional wird Commerce-Intent erkannt und Shopware durchsucht
-8. `PromptBuilder` baut den finalen LLM-Prompt
-9. `OllamaClient` streamt die Modellantwort
-10. Die Antwort wird chunkweise ins Frontend gesendet
-11. Der Turn wird in der Gesprächshistorie persistiert
 
 ---
 
@@ -107,21 +177,22 @@ Die Anfrage läuft im aktuellen Stand vereinfacht so:
 
 Eigenschaften:
 
-- Nutzerhistorie wird pro Client-ID in einer Textdatei gespeichert
+- Historie wird pro stabiler Client-ID gespeichert.
-- abgeschlossene Turns werden append-only geschrieben
+- abgeschlossene Turns werden append-only geschrieben.
-- regulärer Kontext und Full-Context sind getrennt vorgesehen
+- regulärer Kontext und Full-Context sind getrennt vorgesehen.
-- der aktuelle SSE-Flow ruft `AgentRunner->run(..., true)` auf und nutzt damit **vollen Kontext**
+- Browser-Anfragen nutzen standardmäßig budgetierten bzw. regulären Kontext.
+- Full-Context muss explizit über `fullContext` angefordert werden.
 
-Standardlogik im aktuellen Stand:
+Aktuelle Standardwerte aus `config/retriex/runtime.yaml`:
 
-- normale Historie: letzte 20 Zeilen
+- regulärer sichtbarer Kontext: letzte 25 Zeilen
-- voller Kontext: letzte 500 Zeilen
+- Full-Context: letzte 500 Zeilen
 
 ---
 
 ## URL-Auswertung
 
-Wenn im Prompt eine URL vorkommt, extrahiert `UrlAnalyzer` den Inhalt der **ersten** URL.
+Wenn im Prompt eine URL vorkommt, extrahiert `UrlAnalyzer` den Inhalt der ersten URL.
 
 Aktuelle Eigenschaften:
 
@@ -152,9 +223,7 @@ RetrieX nutzt eine deterministische Ingest-Architektur mit NDJSON als operativer
 - `var/knowledge/vector_tags.index`
 - `var/knowledge/vector_tags.index.meta.json`
 
-### Bedeutung
+### `index.ndjson`
-
-#### `index.ndjson`
 
 Operative Chunk-Basis des Systems:
 
@@ -163,7 +232,7 @@ Operative Chunk-Basis des Systems:
 - geeignet für append und full rewrite
 - Grundlage für den Vector-Rebuild
 
-#### `index_meta.json`
+### `index_meta.json`
 
 Struktur-Metadaten des Index, u. a.:
 
@@ -176,7 +245,7 @@ Struktur-Metadaten des Index, u. a.:
 - `scoring_version`
 - weitere Strukturfelder aus der aktiven Index-Konfiguration
 
-#### `index_runtime.json`
+### `index_runtime.json`
 
 Laufzeitdaten, u. a.:
 
@@ -190,28 +259,26 @@ Laufzeitdaten, u. a.:
 
 Der aktuelle Dokumentfluss ist technisch so aufgebaut:
 
-1. Dokumentversion wird aktiviert oder ingestiert
+1. Dokumentversion wird aktiviert oder ingestiert.
-2. Guardrails prüfen die Strukturverträglichkeit
+2. Guardrails prüfen die Strukturverträglichkeit.
-3. alte Chunks des Dokuments werden entfernt
+3. Alte Chunks des Dokuments werden entfernt.
-4. neue Chunks werden streamingfähig geschrieben
+4. Neue Chunks werden streamingfähig geschrieben.
-5. der komplette Vektorindex wird neu gebaut
+5. Der komplette Vektorindex wird neu gebaut.
-6. Runtime-Stats werden atomar aktualisiert
+6. Runtime-Stats werden atomar aktualisiert.
-7. Status der Version wird auf `INDEXED` gesetzt
+7. Status der Version wird auf `INDEXED` gesetzt.
 
 Wichtige Eigenschaft:
 
-- Pro Dokument gibt es fachlich eine aktive Version
+- Pro Dokument gibt es fachlich eine aktive Version.
-- Chunks sind abgeleitete Artefakte, keine Primärdaten
+- Chunks sind abgeleitete Artefakte, keine Primärdaten.
 
 ---
 
-## Ingest-Services im aktuellen Stand
+## Ingest-Services
 
 ### `GuardrailValidator`
 
-Prüft über `IndexMetaManager`, ob der aktuelle Index strukturell zur aktiven Konfiguration passt.
+Prüft über `IndexMetaManager`, ob der aktuelle Index strukturell zur aktiven Konfiguration passt. Wenn relevante Strukturparameter geändert wurden, wird lokaler Ingest blockiert.
-
-Wenn sich relevante Strukturparameter geändert haben, wird lokaler Ingest blockiert.
 
 ### `ChunkWriteService`
 
@@ -236,31 +303,13 @@ Orchestriert:
 
 ---
 
-## Guardrails
+## Retrieval
-
-RetrieX schützt sich gegen strukturellen Drift.
-
-Lokaler Ingest darf nicht weiterlaufen, wenn sich z. B. diese Strukturparameter geändert haben:
-
-- Embedding-Modell
-- Embedding-Dimension
-- Chunk-Größe
-- Chunk-Overlap
-- Scoring-Version
-- Index-Strukturkonfiguration
-
-Dann ist ein **Global Reindex** erforderlich.
-
----
-
-## Retrieval im aktuellen Stand
 
 Der aktive Retriever ist:
 
 - `App\Knowledge\Retrieval\NdjsonHybridRetriever`
 
-Wichtig:  
+„Hybrid“ bedeutet im aktuellen Code eine orchestrierte Kombination aus mehreren Retrieval-Schritten.
-„Hybrid“ bedeutet hier im verifizierten Code nicht einfach „Keyword + Vektor“, sondern eine orchestrierte Kombination aus mehreren Retrieval-Schritten.
 
 ### Aktuelle Retrieval-Pipeline
 
@@ -289,10 +338,11 @@ Wichtig:
 
 ### Besondere Logiken
 
-- Listenfragen werden gesondert erkannt
+- Listenfragen werden gesondert erkannt.
-- Kataloganfragen können direkt einen Katalogblock statt regulärer Chunks liefern
+- Kataloganfragen können direkt einen Katalogblock statt regulärer Chunks liefern.
-- globale und gescopte Treffer werden gefused
+- globale und gescopte Treffer werden gefused.
-- Chunk-Selektion ist dokument- und abstandsbegrenzt
+- Chunk-Selektion ist dokument- und abstandsbegrenzt.
+- Exakte Auswahlfragen, Tabellen-/Indikatorfragen und Grenzwertfragen haben eigene Präzisionspfade.
 
 ---
 
@@ -321,15 +371,13 @@ Service-URL im aktuellen Default:
 - Suchanfragen für Tags beantworten
 - Reloads auf neue Indexstände ermöglichen
 
-### Wichtige Eigenschaft
-
 Der Python-Service hält Modell und Indizes persistent im RAM, um wiederholte Suchanfragen deutlich schneller zu bedienen.
 
 ---
 
 ## Prompt-Aufbau
 
-`PromptBuilder` setzt den finalen LLM-Prompt im aktuellen Stand aus diesen Blöcken zusammen:
+`PromptBuilder` setzt den finalen LLM-Prompt aus diesen Blöcken zusammen:
 
 1. **SYSTEM**  
    Aktiver System-Prompt aus der Datenbank
@@ -344,19 +392,18 @@ Der Python-Service hält Modell und Indizes persistent im RAM, um wiederholte Su
    Wissens-Chunks aus dem Retriever
 
 5. **CONTENT FROM URL (supporting)**  
-   Optional extrahierter Webinhalt
+   Optional extrahierter URL-Inhalt
 
 6. **USER QUESTION**  
    Aktuelle Nutzerfrage
 
-Wichtig:  
+Für Produktfragen behandelt das System Shopdaten explizit als führende Produktquelle. Fachliche Eignungsaussagen bleiben dennoch an RAG-/Kontextbelege und Prompt-Guardrails gebunden.
-Für Produktfragen behandelt das System Shopdaten explizit als **führende Quelle**.
 
 ---
 
 ## Commerce- und Shopware-Integration
 
-RetrieX besitzt im aktuellen Stand eine optionale Shopware-Store-API-Integration.
+RetrieX besitzt eine optionale Shopware-Store-API-Integration.
 
 ### Aktivierung
 
@@ -368,62 +415,46 @@ Mögliche Zustände:
 - `product_search`
 - `advisory_product_search`
 
-### Signale für Commerce
-
-Der Intent-Detektor reagiert u. a. auf:
-
-- Such- und Produktbegriffe
-- SKU-/Zahlenmuster
-- Preisangaben
-- Größenangaben
-- Farbangaben
-- beratende Formulierungen wie „passt“, „besser“, „empfiehl“
-
 ### Aktueller Shop-Flow
 
-1. Commerce-Intent erkennen
+1. Commerce-Intent erkennen.
-2. LLM erzeugt zunächst eine kurze Shop-Suchphrase
+2. LLM erzeugt zunächst eine kurze Shop-Suchphrase.
-3. `ShopSearchService` ruft `CommerceQueryParser` auf
+3. `CommerceQueryParser` normalisiert und bereinigt die Query.
-4. `ShopwareCriteriaBuilder` baut Suchkriterien
+4. Follow-up-/History-/RAG-Anker können die Query ergänzen.
-5. `StoreApiClient` ruft `/store-api/search` auf
+5. `SearchRepairService` kann fehlende oder zu enge Shopqueries reparieren.
-6. Ergebnisse werden zu `ShopProductResult` gemappt
+6. `ShopwareCriteriaBuilder` baut Suchkriterien.
-7. Ergebnisse fließen in den Prompt ein
+7. `StoreApiClient` ruft `/store-api/search` auf.
+8. Ergebnisse werden zu `ShopProductResult` gemappt.
+9. Ergebnisidentität und Rollenlogik filtern zu breite Treffer.
+10. Ergebnisse fließen in Prompt, Statuskarten und Folgeaktionen ein.
 
-### Wichtige Anmerkung
+### Wichtige Präzisionsregeln in v1.6.0
 
-Der aktuelle Code kombiniert also:
+- Exakte Artikelnummern und Produktnummern werden bevorzugt.
-
+- Exakte Zubehörcodes bleiben exakt.
-- **heuristische Intent-Erkennung**
+- Produktlisten-Follow-ups werden in Einzelqueries aufgeteilt.
-- **LLM-unterstützte Kurzsuchphrase**
+- Produktidentität wird über Name, URL, Artikelnummer und sichtbare Antwortprodukte abgesichert.
-- **deterministische Nachverarbeitung im Parser**
+- Schwache Shop-Meta-Fragen dürfen auf konkrete History-Anker zurückfallen.
-- **Store-API-Suche**
+- Shop-only Antworten bleiben vorsichtig, wenn keine belastbare technische Eignung belegt ist.
-
-### Aktuelle Shop-Parameter
-
-In `services.yaml` sind u. a. konfiguriert:
-
-- `mto.commerce.enabled`
-- `mto.commerce.max_shop_results`
-- `mto.commerce.shop_timeout`
-- `mto.commerce.store_api_base_url`
-- `mto.commerce.sales_channel_access_key`
 
 ---
 
 ## Antwort-Streaming
 
-Die Browserausgabe erfolgt per **Server-Sent Events**.
+Die Browserausgabe erfolgt per Server-Sent Events.
 
 ### Eigenschaften des aktuellen SSE-Flows
 
+- Job-basierter Stream über `/ask-jobs` und `/ask-sse/{jobId}`
+- direkter Legacy-Stream über `POST /ask-sse`
+- Reconnect-/Replay-Unterstützung über Event-IDs
+- Stale-Job-Erkennung
 - Output Buffer werden aktiv geleert
 - Cookies werden vor Streamstart weitergereicht
 - Chunks werden direkt als SSE `data:`-Zeilen übertragen
 - Zeilenumbrüche bleiben erhalten
 - am Ende wird ein `done`-Event gesendet
 
-Das ist im aktuellen System die bevorzugte Streaming-Variante für den Browser.
-
 ---
 
 ## Projektstruktur
@@ -443,13 +474,16 @@ Die zentralen Verzeichnisse im aktuellen Stand sind:
 
 - `Agent/`
 - `Commerce/`
+- `Config/`
 - `Context/`
-- `Controller/`
+- `Controller/Chat/`
+- `Controller/Admin/`
 - `Index/`
 - `Ingest/`
 - `Intent/`
 - `Knowledge/`
 - `Routing/`
+- `Security/`
 - `Shopware/`
 - `Tag/`
 - `Vector/`
@@ -473,41 +507,51 @@ Verifizierte relevante Commands im aktuellen Stand:
 - `mto:agent:system:rebuild`
 - `mto:agent:config:validate`
 - `mto:agent:config:audit-source`
+- `mto:agent:config:audit-patterns`
 - `mto:agent:config:dump-effective`
 - `mto:agent:regression:test`
 - `mto:agent:test:shop-search`
 - `mto:agent:test-vector`
 - `mto:agent:user:create`
 
-### Besonders wichtig
+### Vector-Service steuern
-
-#### Vector-Service steuern
 
 ```bash
 bin/console mto:agent:vector:control --status
 bin/console mto:agent:vector:control --install --start --reload
-
 ```
 
+### Empfohlene Standardchecks nach Patches
+
+```bash
+php bin/console cache:clear
+php bin/console lint:yaml config/packages/security.yaml config/retriex
+php bin/console lint:twig templates
+php bin/console mto:agent:config:validate
+php bin/console mto:agent:regression:test
+php bin/console mto:agent:config:audit-source --details
+php bin/console mto:agent:config:audit-patterns --details
+```
 
 ---
 
 ## Developer Policies / Governance
 
-The YAML-only migration is treated as completed after Patch 11.0a, as long as these checks stay green:
+Die YAML-only-Migration gilt als abgeschlossen, solange diese Checks grün bleiben:
 
 ```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
 ```
 
-From now on, developers must follow `DEVELOPER_POLICIES.md`.
+Entwickler müssen `DEVELOPER_POLICIES.md` beachten.
 
-Core rules:
+Kernregeln:
 
-- YAML under `config/retriex/` is the source of truth for configurable behavior.
+- YAML unter `config/retriex/` ist die Source of Truth für konfigurierbares Verhalten.
-- No new PHP-only semantic defaults, token lists, prompt texts, matching rules or business fallbacks.
+- Keine neuen PHP-only-semantischen Defaults, Tokenlisten, Prompttexte, Matching-Regeln oder Business-Fallbacks.
-- New configurable behavior must be added through YAML and wired explicitly.
+- Neues konfigurierbares Verhalten muss über YAML ergänzt und explizit verdrahtet werden.
-- Regression-sensitive flows from the 1.4.2/1.5.0 baseline must remain protected.
+- Regression-sensitive Flows aus den stabilen 1.4.x/1.5.x/1.6.0-Baselines müssen geschützt bleiben.
-- Strict YAML validation is deferred and must remain disabled by default when introduced later.
+- Core-Pattern- und Source-Audits sollen Domainlisten im PHP-Core verhindern.