update .md

CONFIG_PARAMS.md

@@ -1,108 +1,178 @@
-## **1\. `config/retriex/agent.yaml`**
+# CONFIG_PARAMS.md
 
-| YAML-Parameter | Bewirkt |
-| ----- | ----- |
-| `retriex.agent.config.commerce_history_budget_chars` | Begrenzt, wie viel Chatverlauf für Commerce-/Shop-Kontext in die Query-Auflösung einfließt. |
-| `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“. |
-| `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. |
-| `input_normalization.enabled` | Schaltet die Vor-Normalisierung der Nutzereingabe ein/aus. |
-| `input_normalization.max_input_chars` | Maximale Eingabelänge, die zur Normalisierung geschickt wird. |
-| `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. |
-| `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“. |
-| `input_normalization.skip_patterns` | Überspringt Normalisierung bei URLs, Codeblöcken usw. |
-| `input_normalization.prompt.*` | Steuert den Prompt für die LLM-basierte Eingabenormalisierung. |
-| `input_normalization.fuzzy_routing.*` | Steuert Typo-Toleranz für Routingbegriffe wie Shop, Preis, Zubehör, Messgerät. |
-| `follow_up_context.strong_reference_patterns` | Erkennt referenzielle Folgefragen wie „mit welchem Indikator“, „dieser Wert“, „womit“. |
-| `follow_up_context.explicit_commercial_signal_terms` | Erkennt kommerzielle Folgefragen wie Preis, Shop, kaufen, Artikelnummer. |
-| `follow_up_context.commercial_table_follow_up.*` | Erkennt Folgefragen nach Preis-/Shop-Tabellen und baut daraus Shop-Kontextqueries. |
+# RetrieX v1.6.0 – Konfigurationsparameter und Tuning-Leitfaden
+
+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.
+
+## Grundregel
+
+- `config/retriex/*.yaml` ist die zentrale Source of Truth für fachlich konfigurierbares Verhalten.
+- `config/packages/security.yaml` ist die zentrale Source of Truth für Firewalls, Rollen und Access-Control.
+- PHP-Code soll Konfiguration lesen, validieren und ausführen, aber keine neuen fachlichen Tokenlisten oder Business-Regeln verstecken.
+
+---
+
+# 1. YAML-Dateien im Überblick
+
+| Datei | Zweck |
+| --- | --- |
+| `config/retriex/agent.yaml` | AgentRunner-Orchestrierung, Follow-up-Kontext, Shopruntime, Guards, No-LLM-Fallback, UI-Produktionsdaten |
+| `config/retriex/chat-messages.yaml` | User-sichtbare Chat-, SSE-, Frontend-, Agent-, Status-, Follow-up- und Fehlermeldungen |
+| `config/retriex/commerce.yaml` | Shopware-Anbindung, Commerce-Query-Parsing, Reference Resolver, Shop-Matching und Produkt-Ranking |
+| `config/retriex/genre.yaml` | Genre-native Source of Truth für fachliche Adaption, Product Roles, Query Runtime, Context Resolution, Search Repair |
+| `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 oder Härtewert aus vorherigen Antworten. |
-| `messages.*` | User-/Stream-Statusmeldungen und Fehlertexte im AgentRunner. |
-| `rag_evidence_guard.cleanup_profile` | Wählt das Sprachbereinigungsprofil für RAG-Evidence-Prüfung. |
-| `rag_evidence_guard.stop_terms` | Entfernt irrelevante Wörter aus Evidence-Vergleichen. |
-| `rag_evidence_guard.aggregate_query_patterns` | Erkennt aggregierende Fragen wie „wie viele Geräte“. |
-| `rag_evidence_guard.aggregate_evidence_terms` | Tokens, die bei Aggregatfragen als belastbare Zählinformation gelten. |
-| `rag_evidence_guard.aggregate_answer_evidence_patterns` | Prüft, ob die Antwort wirklich eine belegte Aggregat-/Zählaussage enthält. |
-| `rag_evidence_guard.synonyms` | Fachliche Synonyme für Evidence-Abgleich, z. B. Redox/ORP, Salinität/Salzgehalt. |
-| `no_llm_fallback.max_shop_results` | Begrenzt Shop-Produkte in Fallback-Antworten ohne LLM. |
-| `no_llm_fallback.messages.*` | Vorgefertigte Sicherheits-/Fallbackantworten, wenn LLM, RAG oder Shopdaten fehlen. |
-| `no_llm_fallback.product_fields.*` | Textformatierung für Produktzeilen ohne LLM. |
-| `no_llm_fallback.product_roles.*` | Unterscheidet in Fallbacks Hauptgerät vs. Zubehör. |
-| `production_ui.stage_labels.*` | Statusphasen im Frontend, z. B. „Shop wird durchsucht“. |
-| `production_ui.confidence_labels.*` | Labels für Beleglage/Confidence im UI. |
-| `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. |
+| `follow_up_context.reference_anchor.*` | Extrahiert technische Anker wie Testomat-Modell, Messwert oder Produktbezug. |
+| `final_answer_guard.*` | Begrenzt wiederholte oder zu lange finale Antworten. |
+| `shop_runtime.query_cleanup.current_input_preservation.*` | Erhält wichtige Tokens aus der aktuellen Nutzereingabe in der Shopquery. |
+| `shop_runtime.query_cleanup.stopword_cleanup.*` | Entfernt Sprach-, Bedien- und Relationsrauschen aus Shopqueries. |
+| `shop_runtime.query_cleanup.positive_token_filter.*` | Erlaubt positives Filtern auf produktnahe Tokens, Code-Patterns und Varianten-Tokens. |
+| `shop_runtime.attribute_cleanup.*` | Bereinigt direkte Attribut-/Zubehörsuchen, z. B. Kabel-/Puffer-/Sensorfragen. |
+| `shop_runtime.context_resolution.history_anchor_enrichment.*` | Reichert kurze referenzielle Shopqueries mit Verlaufankern an. |
+| `shop_runtime.context_resolution.meta_query_guard.*` | Verhindert Meta-Queries wie „suche im Shop“ ohne konkreten Produktanker. |
+| `shop_runtime.context_resolution.rag_anchor_enrichment.*` | Ergänzt Shopqueries aus RAG-Ankern, z. B. bei exakten Messwerten. |
+| `shop_runtime.result_identity.*` | Prüft primäre Produktidentität und verhindert zu breite Direct-Product-Ergebnisse. |
+| `shop_runtime.answer_constraints.*` | Steuert direkte Antwortfilter, z. B. nach Längenangaben. |
+| `rag_evidence_guard.*` | Prüft, ob RAG-Treffer und Antwort ausreichende fachliche Evidenz liefern. |
+| `no_llm_fallback.*` | Fallback-Verhalten, wenn kein LLM verfügbar ist oder keine sichere Synthese möglich ist. |
+| `production_ui.shop_results.max_cards` | Anzahl sichtbarer Shopkarten. |
+| `shop_prompt.*` | LLM-Regeln zur Erzeugung kurzer Shopware-Suchqueries. |
 
-## **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. |
-| `phrases_to_remove` | Entfernt Bedienphrasen aus Shop-Suchqueries. |
-| `filter_search_tokens` | Entfernt irrelevante Suchtokens. |
+| `known_brands` | Markenbegriffe, die beim Query Parsing erhalten bleiben. |
+| `phrases_to_remove` | Entfernt Bedienphrasen aus Shopqueries. |
+| `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_canonical_map` | Vereinheitlicht Varianten, z. B. Plural/Singular oder Englisch/Deutsch. |
-| `semantic_shop_search_tokens` | Erlaubt semantische Shop-Suche auch bei indirekter Produktsprache. |
+| `search_token_corrections` | Korrigiert bekannte Tippfehler, z. B. Pool-/Schwimmbad-Kontext. |
+| `search_token_canonical_map` | Vereinheitlicht Varianten, Plural/Singular oder Sprachvarianten. |
+| `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, Modellkontextfenster, maximale Shop-Suchtoken. |
-| `patterns.*` | Regex-Logik für Preise, Modellnummern, Zubehörmuster, History-Kontext, Tokenisierung. |
+| `limits.*` | Tokenlängen, Kontextfenster und maximale Shop-Suchtoken. |
+| `patterns.*` | Regex-Logik für Preise, Modelle, Zubehör, History-Kontext, Messwerte. |
 | `commerce_reference_resolver.conversation_product_patterns` | Findet Produkte/Modelle im Chatverlauf. |
-| `commerce_reference_resolver.focus_term_patterns` | Erkennt Fokusbegriffe wie Indikator, Reagenz, Zubehör. |
-| `shop_matching.top_product_log_limit` | Begrenzt Logging/Debug-Ausgabe für Top-Shopprodukte. |
-| `shop_matching.vocabulary_views` | Bindet zentrale `vocabulary.yaml`\-Views an Shop-Matching. |
-| `shop_matching.role_guard.*` | Steuert Gerät/Zubehör-Filterung bei Device-Queries. |
-| `shop_matching.scores.*` | Gewichtung für Shop-Ranking: Produktnummer, Name, Hersteller, Token-Overlap, Rollenbonus/-penalty. |
-| `shop_matching.patterns.*` | Normalisierung/Tokenisierung für Matching. |
+| `commerce_reference_resolver.focus_term_patterns` | Erkennt Fokusbegriffe wie Indikator, Reagenz, Zubehör, Filter. |
+| `shop_matching.vocabulary_views.*` | Bindet Geräte-/Zubehörrollen aus `vocabulary.yaml` an Shop-Matching. |
+| `shop_matching.role_guard.*` | Steuert Geräte-/Zubehörfilterung bei Device- und Accessory-Queries. |
+| `shop_matching.scores.*` | Gewichtung für Produktnummer, Name, Hersteller, Token-Overlap, Verfügbarkeit und Rollenbonus/-Penalty. |
+| `shop_matching.patterns.*` | Normalisierung und Tokenisierung für Shop-Matching. |
 | `shop_matching.price.*` | Preisformatierung und Preisnormalisierung. |
-| `shop_matching.custom_fields.*` | Mapped Shopware-Custom-Fields auf Metadaten. |
-| `shop_matching.text.*` | Textformatierung für Custom-Field-Ausgabe. |
+| `shop_matching.custom_fields.*` | Mapped Shopware-Custom-Fields auf Produktmetadaten. |
 | `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 |
-| ----- | ----- |
-| `regression_baseline.*` | Definiert geschützte Regressionstokens und Pflichtmarker für bekannte stabile Fälle. |
+# 5. `config/retriex/genre.yaml`
+
+| 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. |
-| `core_pattern_audit.*` | Steuert Audit auf verdächtige hardcodierte Listen/Patterns im PHP-Core. |
+| `language.required_profile_term_defaults` | Default-Pflichtbegriffe je Profil. |
+| `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. |
-| `patterns.*` | Regex für SKU, Preis, Größe, Farbe, Modellprodukte. |
+| `technical_factual_knowledge.*` | Erkennt technische Wissensfragen, die nicht als reine Shopfrage laufen sollen. |
+| `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.strong_patterns` | Starke Listen-/Mengenmuster. |
-| `intent.sales.*` | Erkennt Sales-, Vergleichs-, Einwand-, Implementierungs- und ROI-Fragen. |
+| `intent.light.*` | Leichte Listen-/Mengenfrage-Erkennung. |
+| `intent.sales.*` | 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.word_separator_chars` | Zeichen, die als Worttrenner normalisiert werden. |
+| `normalization.ascii_transliteration` | Umlaut-/ASCII-Normalisierung. |
+| `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. |
-| `meta_term_groups.retrieval_reference` | Meta-Wörter für Retrieval-Referenzen. |
+| `stopword_group_sets.*` | Wiederverwendbare Gruppen-Sets. |
+| `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. |
-| `technical_product_keywords` | Technische Produktbegriffe für Promptlogik. |
-| `accessory_request_keywords` | Erkennt Zubehöranfragen. |
+| `vocabulary_views.*` | Bindet technische Produkt-, Geräte- und Zubehörbegriffe aus `vocabulary.yaml`. |
 | `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.trim_characters` | Trimmt Parameterwerte. |
+| `parameter_parsing.*` | Trennt mehrere Parameter wie „pH und Redox“. |
 | `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. |
-| `keyword_topk_multiplier` | Multiplikator für Keyword-Retrieval-Kandidaten. |
-| `keyword_score_threshold` | Mindestscore Keyword-Treffer. |
-| `keyword_rrf_weight` | Gewichtung Keyword-RRF. |
-| `scoped_vector_rrf_weight` | Gewichtung fokussierter Vector-Treffer. |
-| `scoped_keyword_rrf_weight` | Gewichtung fokussierter Keyword-Treffer. |
-| `empty_rrf_fallback_topn` | Fallback, wenn Fusion leer läuft. |
-| `max_chunks_per_doc` | Maximalzahl Chunks pro Dokument. |
-| `min_chunk_distance` | Mindestabstand zwischen Chunks. |
-| `dominant_doc_*` | Logik zur Dominanz eines Dokuments in den Treffern. |
+| `rrf_k` | Konstante für Reciprocal Rank Fusion. |
+| `keyword_topk_multiplier` | Multiplikator für Keyword-Kandidaten. |
+| `keyword_score_threshold` | Mindestscore für Keyword-Treffer. |
+| `keyword_rrf_weight` | Gewichtung von Keyword-Treffern in der Fusion. |
+| `scoped_vector_rrf_weight` | Gewichtung gescopter Vektortreffer. |
+| `scoped_keyword_rrf_weight` | Gewichtung gescopter Keywordtreffer. |
+| `empty_rrf_fallback_topn` | Fallback-Anzahl, wenn Fusion leer bleibt. |
+| `max_chunks_per_doc` | Maximalchunks pro Dokument. |
+| `min_chunk_distance` | Mindestabstand zwischen ausgewählten Chunks. |
+| `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. |
-| `catalog_list_shortcut_patterns` | Erkennt Katalog-/Listenfragen. |
-| `exact_selection_*` | Präzisionslogik für Tabellen/Indikatoren/Grenzwerte. |
+| `focused_product_*` | Fokussierte Produktauswahl im Retrieval. |
+| `catalog_list_shortcut_patterns` | Direkte Katalog-/Listenrouten. |
+| `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. |
-| `important_short_model_tokens` | Geschützte kurze Modell-/Fachtokens wie pH/RX/TC. |
-| `family_descriptor_tokens` | Produktfamilien-/Gerätebeschreibungen. |
-| `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. |
+| `generic_exact_selection_tokens` | Tokens für generische exakte Auswahlfragen. |
+| `vocabulary_views.*` | Bindet zentrale Retrieval-Vocabulary-Views an. |
+| `retriex.retrieval.inventory` | Inventar-/Katalogdaten für Retrieval-Logik. |
 
-## **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.ndjson` | Haupt-Wissensindex. |
-| `retriex.knowledge.index_meta` | Metadaten des Wissensindex. |
-| `retriex.knowledge.vector_index` | FAISS-Vectorindex für Chunks. |
-| `retriex.knowledge.vector_index_meta` | Metadaten zum Chunk-Vectorindex. |
-| `retriex.knowledge.runtime_meta` | Runtime-/Indexstatus-Datei. |
+| `retriex.knowledge.root` | Knowledge-Verzeichnis. |
+| `retriex.knowledge.ndjson` | Pfad zu `index.ndjson`. |
+| `retriex.knowledge.index_meta` | Pfad zu `index_meta.json`. |
+| `retriex.knowledge.vector_index` | Pfad zu `vector.index`. |
+| `retriex.knowledge.vector_index_meta` | Pfad zu `vector.index.meta.json`. |
+| `retriex.knowledge.runtime_meta` | Pfad zu `index_runtime.json`. |
 | `retriex.knowledge.upload` | Upload-Verzeichnis. |
-| `retriex.knowledge.tags_ndjson` | Tag-Indexdaten. |
-| `retriex.knowledge.vector_tags_index` | FAISS-Vectorindex für Tags. |
-| `retriex.knowledge.vector_tags_index_meta` | Metadaten zum Tag-Vectorindex. |
+| `retriex.knowledge.tags_ndjson` | Pfad zu `tags.ndjson`. |
+| `retriex.knowledge.vector_tags_index` | Pfad zu `vector_tags.index`. |
+| `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.context.config.max_visible_regular_lines` | Sichtbare Kontextzeilen im Admin-/Debug-Kontext. |
-| `retriex.context.config.max_full_lines` | Maximale vollständige Kontextzeilen. |
+| `retriex.tags.rebuild_lock` | Lock für Tag-Rebuild. |
+| `retriex.context.config.max_visible_regular_lines` | Reguläre sichtbare History-Lines, aktuell 25. |
+| `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. |
-| `model_candidate_exclude_terms` | Ausschlussbegriffe für falsche Modellkandidaten. |
-| `limits.top_product_log_limit` | Debug-/Loglimit für Topprodukte. |
-| `sanitize_trim_character_codes` | Zeichen-Codes für Query-Sanitizing. |
-| `product_key_separator` | Separator für Produkt-Dedupe-/Keybildung. |
-| `scores.*` | Scoring für Repair-Kandidaten, Prompt-Match, Query-Overlap, Spezifität. |
-| `patterns.*` | Regex-Templates für Modell-, Zubehör-, Bundle- und Token-Erkennung. |
+| `specific_model_candidate_patterns` | Modellkandidaten-Erkennung. |
+| `limits.top_product_log_limit` | Logging-/Debug-Begrenzung für Topprodukte. |
+| `sanitize_trim_character_codes` | Zeichen, die aus Repair-Queries getrimmt werden. |
+| `product_key_separator` | Separator für Produktkeys. |
+| `scores.*` | Gewichtung der Repair-Rankinglogik. |
+| `patterns.*` | Regex-Erkennung für Modelle, Zubehörcodes, Zubehör-/Bundle-Begriffe. |
 
-## **13\. `config/retriex/vector.yaml`**
+---
 
-| YAML-Parameter | Bewirkt |
-| ----- | ----- |
-| `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. |
+# 16. `config/retriex/vector.yaml`
 
-## **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. |
-| `views.shop.device_query` | Gerätebegriffe für Shop-Queries. |
-| `views.shop.accessory_query` | Zubehörbegriffe für Shop-Queries. |
-| `views.shop.accessory_product` | Zubehörerkennung in Shop-Produkten. |
-| `views.shop.device_product` | Geräteerkennung in Shop-Produkten. |
-| `views.shop.device_focus` | Fokusbegriffe für Geräteanfragen. |
-| `views.shop.accessory_focus` | Fokusbegriffe für Zubehöranfragen. |
-| `views.retrieval.*` | Vocabulary-Projektionen für Retrieval-Listen wie Reagenz, Safety, Device, Dokument. |
-| `views.search_repair.*` | Vocabulary-Projektionen für Repair-Kandidaten und Spezifitätsboost. |
-| `views.prompt.*` | Vocabulary-Projektionen für PromptBuilder-Keywords. |
-| `maps.shop.accessory_focus_variants` | Variantenmapping für Zubehörfokus, z. B. unterschiedliche Schreibweisen. |
+| `classes.accessory` | Zentrale Zubehörbegriffe. |
+| `classes.requested_accessory_code_terms` | Begriffe für angefragte Zubehör-/Indikatorcodes. |
+| `classes.shop_meta_terms` | Meta-Terme für Shop-Follow-ups. |
+| `classes.direct_product_attribute_stop_terms` | Stop-Terme für direkte Attributsuchen. |
+| `classes.input_normalization_fuzzy_routing_terms` | Fuzzy-Routing-Terme für Eingabenormalisierung. |
+| `classes.agent_*` | Agent-nahe Vokabulare für Follow-ups, Fallbacks und Query Preservation. |
+| `views.shop.*` | Shop-Views für Geräte-, Zubehör-, Fokus- und Produktrollen. |
+| `views.retrieval.*` | Retrieval-Views für Produkt-, Modell-, Reagenz-, Dokument- und Geräteterme. |
+| `views.search_repair.*` | Search-Repair-Views für direkte Produktsuchen und Zubehörcodes. |
+| `views.prompt.*` | Prompt-Views für technische Produkt- und Zubehörbegriffe. |
+| `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 |
-| ----- | ----- | ----- |
-| `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. |
+# 18. `config/packages/security.yaml`
 
-## **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 |
-| ----- | ----- | ----- |
-| `config/retriex/retrieval.yaml` | `retriex.retrieval.config.hard_max_chunks` | Maximale Chunks in der finalen Auswahl. Einer der wichtigsten Antwort-/Kontexthebel. |
-| `retrieval.yaml` | `hard_max_vectork` | Maximale Vektor-Kandidaten. |
-| `retrieval.yaml` | `hard_max_keywordk` | Maximale Keyword-Kandidaten. |
-| `retrieval.yaml` | `vector_score_threshold` | Mindestscore für Vektortreffer. |
-| `retrieval.yaml` | `threshold_floor` / `threshold_ceil` | Dynamischer Score-Korridor. |
-| `retrieval.yaml` | `list_bonus` | Bonus für Listen-/Tabellenähnliche Treffer. Wichtig für Produktlisten/Grenzwerte. |
-| `retrieval.yaml` | `rrf_k` | Stärke des Reciprocal-Rank-Fusion-Verhaltens. |
-| `retrieval.yaml` | `keyword_topk_multiplier` | Erweitert Keyword-Kandidatenset. |
-| `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. |
+| Bereich | Bewirkt |
+| --- | --- |
+| `providers.app_user_provider` | Gemeinsamer User-Provider über `App\Entity\User`. |
+| `firewalls.admin` | Admin-Firewall für `^/admin`, inklusive Login, Logout, Remember-Me, User-Checker und Access-Denied-Handler. |
+| `firewalls.chat` | Chat-Firewall für `/`, `/chat`, `/ask-jobs`, `/ask-sse`, `/history`, `/chat-messages/frontend`. |
+| `firewalls.main` | Öffentliche/statische Restfläche. |
+| `role_hierarchy` | Rollenvererbung für Super Admin, Knowledge Admin, Editor, Admin Area und Chat User. |
+| `access_control` | Konkrete serverseitige Route-zu-Rolle-Matrix. |
+| `access_denied_handler` | Einheitliche 403-Seite für falsche Bereichs-/Rollenwechsel. |
+| `user_checker` | Sperrt deaktivierte Benutzer beim Login. |
 
-## **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 |
-| ----- | ----- | ----- |
-| `config/retriex/intent.yaml` | `retriex.intent.commerce.config.strong_signals` | Starke Shop-/Commerce-Signale. |
-| `intent.yaml` | `non_product_commerce_signals` | Commerce-Signale ohne Produktsuche. |
-| `intent.yaml` | `advisory_signals` | Beratungssignale. |
-| `intent.yaml` | `advisory_product_selection_patterns` | Muster für Produktauswahlfragen. |
-| `intent.yaml` | `price_terms`, `color_terms`, `size_*` | Preis-/Farb-/Größenfilter-Erkennung. |
-| `intent.yaml` | `support_diagnostic_patterns` | Support-/Diagnosefragen abgrenzen. |
-| `intent.yaml` | `explicit_commerce_intent_patterns` | Explizite Shopabsicht. |
-| `intent.yaml` | `technical_factual_knowledge.*` | Erkennung technischer Wissensfragen, damit nicht alles in Shoplogik läuft. |
-| `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. |
+| Datei | Bereich | Wirkung |
+| --- | --- | --- |
+| `prompt.yaml` | `fact_grounding.*` | Verhindert unbelegte Behauptungen. |
+| `prompt.yaml` | `measurement_evidence_guard.*` | Schützt Messparameter-/Eignungsaussagen. |
+| `prompt.yaml` | `output_priority.*` | Priorisiert Antwortaufbau. |
+| `prompt.yaml` | `numeric_value_focus.*` | Hält Grenzwerte und exakte Zahlen im Fokus. |
+| `model.yaml` | `default_num_ctx`, `num_predict` | Kontext- und Antwortbudget. |
+| `retrieval.yaml` | `hard_max_chunks`, `threshold_*`, `focused_product_*` | Menge und Qualität des RAG-Kontexts. |
+| `language.yaml` | `cleanup_profiles.*` | Qualität der Query- und Evidence-Bereinigung. |
+| `vocabulary.yaml` | `views.prompt.*`, `views.retrieval.*` | Fachbegriffe und sichere Matching-Begriffe. |
 
-## **5\. Sprachbereinigung und Vocabulary**
+---
 
-| Datei | Parameter / Bereich | Wirkung |
-| ----- | ----- | ----- |
-| `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. |
+# 20. Wichtigste Stellschrauben für RAG-Suchergebnisse
 
-## **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 Antwortqualität. |
-| `config/retriex/vector.yaml` | Host, Port, Script-Pfade, Timeouts | Betrieb/Performance, nicht fachliche Qualität. |
-| `config/retriex/commerce.yaml` | `shop_timeout`, API-URL, Access-Key | Verfügbarkeit/Performance der Shopdaten, nicht Rankingqualität. |
-| `config/retriex/agent.yaml` | `messages`, `production_ui`, `source_labels`, `html` | UX-/Anzeige-Texte, nicht fachliche Antwortoptimierung. |
+| `runtime.yaml` | Pfade zu Knowledge/Index/Locks | Infrastruktur, nicht fachliche Qualität. |
+| `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. |
+| `chat-messages.yaml` | reine UI-Texte | UX-relevant, fachlich nur indirekt. |
 
-## **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.  
-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.
+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:
+
+- 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**  
-   Aktive Dokumentversionen, System-Prompts und Ingest-Regeln sind klar steuerbar.
+3. **Präzisere Commerce-Unterstützung**  
+   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**  
-   Bei Produktanfragen können zusätzlich Live-Shopdaten eingebunden werden, sodass nicht nur erklärt, sondern auch konkret beraten werden kann.
+4. **Mehr Governance und Betriebssicherheit**  
+   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
-- **Index und Suche**: aufbereitete Chunks, Metadaten, Vektorindizes, Routing
-- **Orchestrierung**: Anfrageverarbeitung, Retrieval, Prompt-Aufbau, Streaming
-- **Ausgabe**: nutzbare Antwort im Frontend
+- **Wissensquellen**: Dokumente, aktive Versionen, Systemregeln, Konfigurationen
+- **Index und Suche**: Chunks, Metadaten, FAISS-Indizes, Tag-Routing, Retrieval-Regeln
+- **Orchestrierung**: Anfrageverarbeitung, Kontextauflösung, Retrieval, Commerce, Prompt-Aufbau, Streaming
+- **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
-- nur aktive Inhalte zählen
-- der Wissensindex wird deterministisch erzeugt
-- strukturelle Änderungen sind durch Guardrails abgesichert
-- Retrieval und Prompt-Aufbau folgen festen Regeln
-- Produktdaten können als autoritative Live-Quelle eingebunden werden
+- Dokumente sind versioniert.
+- Nur aktive Versionen fließen in den Index ein.
+- Ingest und Vector-Rebuild folgen festen Regeln.
+- Strukturänderungen werden über Guardrails abgesichert.
+- Retrieval und Prompt-Aufbau sind konfiguriert und auditierbar.
+- 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:  
-RetrieX ist keine Spielerei und kein Frontend-Gimmick, sondern ein System zur kontrollierten Operationalisierung von Wissen.
+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.
 
-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
-- Produktinformationen gezielt in KI-Antworten einfließen
-- Governance, Nachvollziehbarkeit und Wartbarkeit erhalten bleiben
+- Beratungs- und Supportprozesse skalierbarer werden
+- Produktinformationen und Preise gezielt einfließen
+- 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
-- Wissen stammt primär aus den aktivierten Dokumenten im System
-- die KI formuliert auf Basis von abgerufenem Kontext
-- bei Produktanfragen können zusätzlich Live-Shopdaten einbezogen werden
+- Antworten sollen nicht frei erfunden werden.
+- Wissen stammt primär aus aktivierten Dokumentversionen.
+- Die KI formuliert auf Basis von abgerufenem Kontext.
+- Bei Produktanfragen können Live-Shopdaten einbezogen werden.
+- Chat- und Adminzugang sind rollenbasiert getrennt.
+- Konfigurierbare Fachlogik liegt überwiegend in YAML statt im PHP-Core.
 
-RetrieX ist damit **kein frei antwortender Chatbot**, sondern ein kontrolliertes System aus:
+RetrieX ist damit kein frei antwortender Chatbot, sondern ein kontrolliertes System aus:
 
 - versionierten Wissensdokumenten
 - deterministischem Ingest
 - hybridem Retrieval
 - optionaler Commerce-Erweiterung
-- LLM-basierter Formulierung der Antwort
+- LLM-basierter Antwortformulierung
+- SSE-basierter Browserausgabe
+- rollenbasierter Betriebs- und Administrationslogik
 
 ---
 
@@ -29,23 +33,22 @@ RetrieX ist damit **kein frei antwortender Chatbot**, sondern ein kontrolliertes
 
 ## 1. Dokumente als Wissensbasis
 
-Die Wissensbasis besteht aus hochgeladenen Dokumenten, zum Beispiel:
+Die Wissensbasis besteht aus hochgeladenen Dokumenten, aktuell verifiziert für:
 
 - PDF
-- DOCX
-- Markdown
 - TXT
+- Markdown
 
-Diese Dokumente werden nicht direkt „gelesen“, sondern in einen verarbeitbaren Wissensindex überführt.
+Diese Dokumente werden nicht direkt zur Laufzeit vollständig gelesen, sondern in einen verarbeitbaren Wissensindex überführt.
 
 Wichtige Eigenschaften:
 
-- Dokumente sind versioniert
-- pro Dokument gibt es fachlich genau eine aktive Version
-- nur aktive Inhalte fließen in den Wissensindex ein
-- Chunks sind abgeleitete Artefakte, keine manuell gepflegte Primärquelle
+- Dokumente sind versioniert.
+- Pro Dokument gibt es fachlich genau eine aktive Version.
+- Nur aktive Inhalte fließen in den Wissensindex ein.
+- Chunks sind abgeleitete Artefakte, keine manuell gepflegte Primärquelle.
 
-Die eigentliche Wissensquelle sind also die **aktiven Dokumentversionen**, nicht frei bearbeitete Textfragmente.
+Die eigentliche Wissensquelle sind also die aktiven Dokumentversionen, nicht frei bearbeitete Textfragmente.
 
 ---
 
@@ -55,30 +58,35 @@ Sobald eine Dokumentversion ingestiert oder aktiviert wird, läuft ein technisch
 
 Dabei passiert im Kern:
 
-1. Dokumentinhalt wird extrahiert
-2. Inhalt wird in Chunks zerlegt
-3. Chunk-Datensätze werden in `index.ndjson` geschrieben
-4. der Vektorindex wird vollständig neu aufgebaut
-5. Laufzeit-Metadaten werden aktualisiert
+1. Dokumentinhalt wird extrahiert.
+2. Inhalt wird in Chunks zerlegt.
+3. Chunk-Datensätze werden in `index.ndjson` geschrieben.
+4. Der Vektorindex wird vollständig neu aufgebaut.
+5. Runtime-Metadaten werden aktualisiert.
+6. Der Status der Version wird auf `INDEXED` gesetzt.
 
-Der Ingest ist bewusst **deterministisch** aufgebaut.  
-Das heißt: derselbe Datenstand soll immer wieder denselben Indexzustand erzeugen.
+Der Ingest ist bewusst deterministisch aufgebaut. Derselbe Datenstand soll denselben Indexzustand erzeugen.
 
 ---
 
 ## 3. Retrieval zur Laufzeit
 
-Wenn ein Nutzer eine Anfrage stellt, durchsucht RetrieX nicht „das ganze Dokument direkt“, sondern den vorbereiteten Wissensbestand.
+Wenn ein Nutzer eine Anfrage stellt, durchsucht RetrieX nicht das ganze Dokument direkt, sondern den vorbereiteten Wissensbestand.
 
-Das Retrieval ist im aktuellen Stand **hybrid und routingfähig**:
+Das Retrieval ist im aktuellen Stand hybrid und routingfähig:
 
-- Vektor-Retrieval über FAISS
-- zusätzliches Tag-Routing zur Vorselektion möglicher Dokumente
-- Score-basierte Auswahl relevanter Chunks
+- Query Cleaning
+- Query Enrichment
+- Intent-Erkennung
+- Tag-Routing zur Kandidatendokument-Vorselektion
+- FAISS-Vektor-Retrieval
+- optionale gescopte Suche auf Kandidatendokumente
+- Score- und RRF-basierte Fusion
 - Sonderroute für Katalog-/Listenanfragen
+- Präzisionsrouten für exakte Tabellen-/Grenzwert-/Indikatorfragen
 - optionale Ergänzung durch Live-Shopdaten bei Commerce-Intent
 
-Das System liefert also nicht einfach „irgendwelche Treffer“, sondern baut einen gezielten Kontextblock für das Modell.
+Das System liefert also nicht einfach irgendwelche Treffer, sondern baut einen gezielten Kontextblock für das Modell.
 
 ---
 
@@ -95,13 +103,23 @@ Dieser Prompt kann aus mehreren Blöcken bestehen:
 - optional extrahierter Inhalt einer URL aus der Nutzeranfrage
 - aktuelle Nutzerfrage
 
-Erst danach erzeugt das Sprachmodell die eigentliche Antwort.
-
-Die KI ist damit die **Formulierungsinstanz**, nicht die eigentliche Wissensquelle.
+Die KI ist damit die Formulierungsinstanz, nicht die eigentliche Wissensquelle.
 
 ---
 
-# Architektur in vier Ebenen
+## 5. Chat, Admin und Betrieb
+
+Version 1.6.0 trennt den öffentlichen Chat-Einstieg architektonisch vom Adminbereich:
+
+- Chat: `/`, `/chat`, `/chat/login`, `/chat/logout`
+- Chat-APIs: `/ask-jobs`, `/ask-sse`, `/ask-sse/{jobId}`, `/history`, `/chat-messages/frontend`
+- Admin: `/admin...`
+
+Beide Bereiche nutzen denselben User-Provider, aber getrennte Firewalls und Rollenregeln. Dadurch kann ein Benutzer z. B. nur Chatrechte, nur Adminbasisrechte oder erweiterte Adminrechte besitzen.
+
+---
+
+# Architektur in fünf Ebenen
 
 ## 1. Primärquellen
 
@@ -111,9 +129,10 @@ Primärquellen sind die fachlichen Eingaben des Systems:
 - Dokumentversionen
 - aktive System-Prompts
 - Modellkonfiguration
+- YAML-Konfigurationen
 - optional externe Shopdaten
 
-Diese Ebene bestimmt, **welches Wissen und welche Regeln** überhaupt verwendet werden dürfen.
+Diese Ebene bestimmt, welches Wissen und welche Regeln verwendet werden dürfen.
 
 ---
 
@@ -136,31 +155,60 @@ Diese Ebene ist für Suche, Relevanz und Reproduzierbarkeit zuständig.
 Diese Ebene verbindet alle Teile des Systems:
 
 - Anfrageannahme
+- Client-ID-Auflösung
+- Gesprächskontext
 - URL-Auswertung
 - Retrieval
 - Intent-Erkennung
 - Shop-Suche
+- Query-Reparatur
 - Prompt-Aufbau
 - Streaming der Modellantwort
 - Historienpersistenz
 
-Zentrale Klasse für die Laufzeit ist hier insbesondere der `AgentRunner`.
+Zentrale Laufzeitklasse ist `AgentRunner`.
 
 ---
 
 ## 4. Ausgabe- und UI-Ebene
 
-Die Antwort wird per **Server-Sent Events (SSE)** gestreamt.
+Die Antwort wird per Server-Sent Events gestreamt.
 
-Dadurch erhält das Frontend die Ausgabe schrittweise, statt auf eine vollständige Blockantwort zu warten.
+Die UI kann anzeigen:
 
-Der aktuelle Projektstand setzt für Browser-Streaming bevorzugt auf SSE.
+- laufende Statusphasen
+- Datenbasis und Confidence-Hinweise
+- RAG-/Shop-Quellen
+- Shopkarten
+- gesendete Shopquery oder Einzelqueries
+- Follow-up-Actions wie Preis anzeigen, nur Zubehör anzeigen oder technische Details anzeigen
+
+Seit den neueren v1.6.0-Patches sind Follow-up-Actions kontextsensitiver und vermeiden Selbstloops, wenn dieselbe Shopquery bereits ausgeführt wurde.
+
+---
+
+## 5. Betriebs- und Governance-Ebene
+
+Diese Ebene umfasst:
+
+- Chat-/Admin-Firewalls
+- Rollenmatrix
+- Admin-Userverwaltung
+- Aktiv-/Inaktiv-Loginprüfung
+- Access-Denied-Handler
+- 403/404/500-Fehlerseiten
+- Konfigurationsvalidierung
+- Source-Audit
+- Core-Pattern-Audit
+- Regressionstests
+
+Damit wird RetrieX nicht nur fachlich, sondern auch organisatorisch betreibbar.
 
 ---
 
 # Wissensspeicher und Indexdateien
 
-## index.ndjson
+## `index.ndjson`
 
 `index.ndjson` ist die zentrale Chunk-Datei des Systems.
 
@@ -170,13 +218,13 @@ Eigenschaften:
 - streamingfähig
 - append-/rewrite-fähig
 - geeignet für größere Bestände
-- dient als operative Grundlage für den Vector-Rebuild
+- operative Grundlage für den Vector-Rebuild
 
 Jede Zeile repräsentiert einen Chunk-Datensatz.
 
 ---
 
-## index_meta.json
+## `index_meta.json`
 
 `index_meta.json` beschreibt den strukturellen Zustand des Index.
 
@@ -191,20 +239,19 @@ Beispielhafte Inhalte:
 - `index_format`
 - `vector_backend`
 
-Diese Datei ist wichtig für Guardrails.  
-Wenn sich die Strukturparameter ändern, darf lokaler Ingest nicht einfach weiterlaufen.
+Diese Datei ist wichtig für Guardrails. Wenn sich Strukturparameter ändern, darf lokaler Ingest nicht einfach weiterlaufen.
 
 ---
 
-## index_runtime.json
+## `index_runtime.json`
 
-`index_runtime.json` enthält laufzeitbezogene Informationen zum aktuellen Indexzustand, zum Beispiel aktualisierte Chunk-Zählungen.
+`index_runtime.json` enthält laufzeitbezogene Informationen zum aktuellen Indexzustand, z. B. Chunk-Zählungen und Rebuild-Zeitpunkte.
 
 Diese Datei dient nicht als Primärquelle, sondern als technische Betriebsmetadatei.
 
 ---
 
-## vector.index
+## `vector.index`
 
 `vector.index` ist der FAISS-Vektorindex des Systems.
 
@@ -212,16 +259,15 @@ Er wird nicht manuell gepflegt, sondern aus `index.ndjson` neu erzeugt.
 
 ---
 
-## tags.ndjson und vector_tags.index
+## `tags.ndjson` und `vector_tags.index`
 
 Neben dem Hauptindex existiert eine Tag-Ebene:
 
 - `tags.ndjson`
 - `vector_tags.index`
+- `vector_tags.index.meta.json`
 
-Diese wird für Tag-Routing bzw. thematische Vorselektion verwendet.
-
-Sie ist eine ergänzende Routing-Schicht, kein Ersatz für das Hauptretrieval.
+Diese Ebene unterstützt Tag-Routing und Kandidatendokument-Vorselektion.
 
 ---
 
@@ -229,20 +275,19 @@ Sie ist eine ergänzende Routing-Schicht, kein Ersatz für das Hauptretrieval.
 
 ## 1. Dokument anlegen
 
-Ein Dokument wird als fachliche Einheit gespeichert.
+Ein Dokument wird als fachliches Objekt im Adminbereich gepflegt.
 
 ## 2. Versionen verwalten
 
-Dokumente besitzen Versionen.  
-Diese Versionen sind der eigentliche inhaltliche Träger.
+Dokumente besitzen Versionen. Diese Versionen sind der eigentliche inhaltliche Träger.
 
 ## 3. Aktivierung
 
-Wird eine Version aktiviert, wird nicht einfach nur „ein Text ausgetauscht“, sondern ein definierter Prozess ausgelöst.
+Wird eine Version aktiviert, wird ein definierter Prozess ausgelöst. Die aktive Version bestimmt den Wissensstand des Dokuments.
 
 ## 4. IngestJob
 
-Die Aktivierung führt in die Ingest-Orchestrierung.
+Ingest-Jobs führen den Verarbeitungsprozess nachvollziehbar aus.
 
 ## 5. Chunk-Erzeugung
 
@@ -250,64 +295,39 @@ Aus der aktiven Version werden Chunk-Records erzeugt.
 
 ## 6. NDJSON-Update
 
-Bestehende Chunks des betroffenen Dokuments werden entfernt und durch neue ersetzt.
+Der Chunk-Bestand wird dokumentbezogen aktualisiert.
 
 ## 7. Vollständiger Vector-Rebuild
 
-Anschließend wird der gesamte FAISS-Index aus dem aktuellen NDJSON-Bestand neu gebaut.
+Nach relevanten Ingest-Schritten wird der FAISS-Index vollständig neu aufgebaut.
 
 ---
 
-# Ingest-Logik im aktuellen Stand
+# Ingest-Logik
 
-Der Ingest ist in mehrere spezialisierte Services getrennt.
+## `GuardrailValidator`
 
-## GuardrailValidator
+Prüft, ob der bestehende Index strukturell zur aktiven Konfiguration passt.
 
-Prüft, ob der aktuelle Indexzustand mit der erwarteten Struktur kompatibel ist.
+## `ChunkWriteService`
 
-Wenn nicht, wird lokaler Ingest blockiert.
+Kapselt Schreiboperationen auf `index.ndjson`.
 
----
+## `VectorRebuildService`
 
-## ChunkWriteService
+Baut den Vektorindex neu und aktualisiert Runtime-Metadaten.
 
-Kapselt die Schreibvorgänge auf der Chunk-Ebene, insbesondere:
+## `IngestFlow`
 
-- Chunks zählen
-- Chunks für ein Dokument entfernen
-- neue Chunks anhängen
-- gesamten NDJSON-Bestand neu schreiben
-
----
-
-## VectorRebuildService
-
-Verantwortet den vollständigen Rebuild des Vektorindex und die Aktualisierung der Runtime-Metadaten.
-
----
-
-## IngestFlow
-
-Der `IngestFlow` orchestriert den Gesamtprozess.
-
-Für Dokument-Ingest bedeutet das insbesondere:
-
-- Guardrail prüfen
-- Status auf laufend setzen
-- alte Dokument-Chunks entfernen
-- neue Chunks streamingfähig anhängen
-- Chunk-Limits überwachen
-- Vector-Rebuild auslösen
-- finalen Status setzen
+Orchestriert Einzel-Ingest, Global Reindex und Lösch-/Reset-Flows.
 
 ---
 
 # Guardrails und Reproduzierbarkeit
 
-RetrieX schützt sich bewusst gegen strukturellen Drift.
+RetrieX schützt sich gegen strukturellen Drift.
 
-Wenn sich zentrale Indexparameter ändern, etwa:
+Lokaler Ingest darf nicht weiterlaufen, wenn sich z. B. diese Strukturparameter geändert haben:
 
 - Embedding-Modell
 - Embedding-Dimension
@@ -315,27 +335,24 @@ Wenn sich zentrale Indexparameter ändern, etwa:
 - Chunk-Overlap
 - Scoring-Version
 - Indexformat
+- Vector-Backend
 
-dann darf ein lokaler Ingest nicht stillschweigend in einen inkompatiblen Index hineinschreiben.
-
-Stattdessen wird ein **Global Reindex** erforderlich.
-
-Das verhindert inkonsistente Mischzustände.
+Dann ist ein Global Reindex erforderlich.
 
 ---
 
 # Global Reindex
 
-Ein Global Reindex unterscheidet sich bewusst vom lokalen Dokument-Ingest.
+Der Global Reindex baut den operativen Wissensbestand aus den aktiven Dokumentversionen neu auf.
 
-Dabei passiert:
+Ziel:
 
-- alle aktiven Dokumente werden neu verarbeitet
-- `index.ndjson` wird vollständig neu geschrieben
-- der Vektorindex wird komplett neu gebaut
-- die `index_version` wird erhöht
+- konsistenter Chunk-Bestand
+- konsistenter Vektorindex
+- aktualisierte Runtime-Metadaten
+- reproduzierbarer Systemzustand
 
-Der Global Reindex ist damit der kontrollierte Weg, strukturelle Änderungen sauber auf den gesamten Wissensbestand anzuwenden.
+In v1.6.0 ist der Global-Reindex-Zugriff serverseitig und im Admin-UI auf `ROLE_SUPER_ADMIN` eingeschränkt.
 
 ---
 
@@ -343,267 +360,267 @@ Der Global Reindex ist damit der kontrollierte Weg, strukturelle Änderungen sau
 
 ## Hybrid-Retrieval
 
-Das aktuelle System verwendet kein rein lineares Suchmodell, sondern kombiniert mehrere Schritte:
+Der aktive Retriever kombiniert mehrere Signale:
 
-- Query-Cleaning
-- Query-Enrichment
-- Intent-Erkennung
+- bereinigte Nutzerfrage
+- Query-Enrichment-Regeln
+- Intent-Routing
+- Vektortreffer
 - Tag-Routing
-- globale Vektorsuche
-- optional gescopte Vektorsuche auf Kandidatendokumente
-- Fusion und Auswahl relevanter Chunks
-
-Das Ziel ist nicht einfach „mehr Treffer“, sondern **passendere, stabilere Kontexterzeugung**.
-
----
+- gescopte Suche
+- RRF-/Score-Fusion
+- dokumentbezogene Begrenzung
 
 ## Tag-Routing
 
-Vor der eigentlichen Chunk-Auswahl kann das System thematisch passende Dokumente über Tags eingrenzen.
-
-Das reduziert die Suchfläche und erhöht die Wahrscheinlichkeit, dass relevante Dokumente bevorzugt werden.
-
----
+Tags können Kandidatendokumente vorselektieren. Dadurch kann die spätere Vektorsuche fokussierter laufen.
 
 ## Katalog-/Listenroute
 
-Für bestimmte Anfragen erkennt das System, dass keine klassische Chunk-Antwort, sondern eher eine Listen- oder Katalogausgabe sinnvoll ist.
-
-Dann kann statt normaler Chunk-Selektion ein Katalogblock erzeugt werden.
-
----
+Katalog- oder Listenfragen können direkt in einen Katalogblock führen, statt nur einzelne Textchunks zu liefern.
 
 ## Ergebnisbegrenzung
 
-Die Zahl der zurückgegebenen Wissens-Chunks ist konfigurationsgetrieben.
-
-Wichtige Steuergrößen sind:
-
-- `retrievalMaxChunks`
-- `retrievalVectorTopK`
-
-Diese Werte stammen aus der aktiven Modell-/Generierungskonfiguration.
+Parameter aus `retrieval.yaml`, `model.yaml` und `prompt.yaml` begrenzen Kandidaten, Chunks und Promptbudget.
 
 ---
 
 # Commerce-Erweiterung und Shop-Suche
 
-Ein zentrales Merkmal des aktuellen Systemstands ist die **optionale Shopware-Store-API-Anbindung**.
+## `CommerceIntentLite`
 
-Diese wird nicht immer verwendet, sondern nur dann, wenn die Anfrage nach Commerce-Logik aussieht.
+Erkennt, ob eine Anfrage Commerce-Relevanz hat.
 
-## CommerceIntentLite
-
-Die Anfrage wird heuristisch auf Commerce-Signale geprüft, zum Beispiel:
+Mögliche Zustände:
 
+- keine Commerce-Suche
 - Produktsuche
-- Preisbezug
-- Größen-/Farbhinweise
-- SKU-ähnliche Nummern
-- typische Produkt- oder Empfehlungsfragen
+- beratende Produktsuche
 
-Das Ergebnis ist einer von drei Zuständen:
+## `CommerceQueryParser`
 
-- `none`
-- `product_search`
-- `advisory_product_search`
+Bereinigt und normalisiert Shopqueries:
 
----
+- bekannte Marken behalten
+- Bedienphrasen entfernen
+- Tippfehler korrigieren
+- Token kanonisieren
+- Kontext-/Preservation-Tokens erhalten
+- Preis-/Farb-/Größenmuster erkennen
 
-## CommerceQueryParser
+## `ShopSearchService`
 
-Wenn Commerce erkannt wird, wird die Nutzeranfrage deterministisch aufbereitet.
-
-Dabei werden strukturierte Suchinformationen abgeleitet, etwa:
-
-- Suchkern
-- Preis
-- Größe
-- Farbe
-- weitere Suchsignale
-
----
-
-## ShopSearchService
-
-Der `ShopSearchService` baut daraus eine Shopware-Store-API-Anfrage und mappt die Ergebnisse in ein internes, schlankes Produktformat.
-
-Typische Produktinformationen sind dann:
-
-- Name
-- Produktnummer
-- Hersteller
-- Preis
-- Verfügbarkeit
-- URL
-- Beschreibung
-- Bild
-- ausgewählte Zusatzinformationen
-
----
+Führt die Shopware-Suche aus und kann Repair-Queries nachschieben, wenn primäre Treffer fehlen oder zu ungenau sind.
 
 ## Rolle der Shopdaten
 
-Shopdaten werden im Prompt ausdrücklich als **authoritative for products** behandelt.
+Shopdaten sind für Produktinformationen autoritativ, insbesondere für:
 
-Das bedeutet:
-
-- für reale Produktdaten sind Live-Shopdaten führend
-- Wissens-Chunks bleiben unterstützend
-- das System trennt damit Produktwahrheit und Dokumentwissen bewusst voneinander
-
----
+- Produktname
+- Artikelnummer
+- Preis
+- Verfügbarkeit
+- Hersteller
+- Shop-URL
+- Shop-Beschreibung und Custom Fields
 
 ## Balance zwischen Shop und Wissen
 
-Wenn Commerce aktiv ist, wird die Zahl der Wissens-Chunks reduziert:
+Shopdaten ersetzen nicht automatisch fachliche Eignungsbelege. Bei technischen Eignungsfragen müssen RAG-Kontext, Shopdaten und Prompt-Guardrails zusammenpassen.
 
-- bei `product_search` stärker
-- bei `advisory_product_search` moderat
+---
 
-So soll verhindert werden, dass Shopdaten im finalen Prompt von allgemeinen Wissens-Chunks verdrängt werden.
+# v1.6.0 Commerce- und Follow-up-Guards
+
+Version 1.6.0 enthält mehrere Präzisionsmechanismen:
+
+- Direkte Produktnamen werden in Shopqueries erhalten.
+- Noise-Tokens wie reine Bedien-, Relations- oder Denkmarker werden entfernt.
+- Tippfehler wie `schwinnbad` können zu `schwimmbad` korrigiert und erhalten werden.
+- Modellkürzel wie `LAB CL` bleiben erhalten, wenn sie im konfigurierten Kontext auftreten.
+- generische Geräteanfragen können auf exakte fachliche Produktanker aufgelöst werden, z. B. bei SiO2/Silikat.
+- Produktlisten-Follow-ups werden in einzelne Produktqueries aufgeteilt.
+- Produktanker-Kanonisierung ist YAML-gestützt statt im PHP-Core hartcodiert.
+- Exakte Zubehörcodes werden als exakte Codes behandelt.
+- Preis-Folgeaktionen verwenden sichtbare Produktidentitäten mit Produktnummern.
+- Schwache referenzielle Shopqueries können auf History-Modellanker zurückfallen.
 
 ---
 
 # URL-Auswertung
 
-Wenn die Nutzeranfrage eine URL enthält, kann RetrieX den Inhalt dieser URL zusätzlich extrahieren.
+`UrlAnalyzer` extrahiert Inhalt aus der ersten URL in einer Nutzerfrage.
 
-Dazu wird:
-
-- die erste URL im Prompt erkannt
-- der Inhalt geladen
-- über Readability verarbeitet
-- HTML entfernt
-- Text normalisiert
-- auf eine maximale Länge begrenzt
-
-Der extrahierte Inhalt wird anschließend als zusätzlicher unterstützender Wissensblock in den Prompt aufgenommen.
-
-Das ist hilfreich, wenn ein Nutzer auf eine konkrete externe Quelle verweist.
+Der Inhalt wird als unterstützende Quelle in den Prompt aufgenommen, nicht als Primärindex gespeichert.
 
 ---
 
 # Prompt-Aufbau
 
-Der finale Prompt wird systematisch zusammengesetzt.
+Der final zusammengesetzte Prompt kann enthalten:
 
 ## 1. Systemblock
 
-Der aktive System-Prompt wird aus der Datenbank geladen.
-
-Er ist die führende Regel- und Verhaltensbasis des Modells.
-
----
+Aktiver System-Prompt.
 
 ## 2. Gesprächskontext
 
-Frühere Nachrichten des Nutzers werden als autoritativer Konversationskontext eingebunden.
-
-So bleibt der Dialog über mehrere Turns konsistent.
-
----
+Historie des Nutzers, regulär oder explizit als Full-Context.
 
 ## 3. Live-Shop-Block
 
-Wenn Shop-Ergebnisse vorliegen, werden diese als eigener Block eingebaut.
-
-Sie sind für Produktfragen führend.
-
----
+Shopware-Produkte mit Produktnummer, Preis, Verfügbarkeit, Hersteller, URL und weiteren Feldern.
 
 ## 4. Retrieved Knowledge
 
-Die ausgewählten Wissens-Chunks werden als unterstützender Wissensblock eingefügt.
-
----
+RAG-Chunks aus `index.ndjson`.
 
 ## 5. URL-Content
 
-Optional kommt zusätzlich extrahierter Webinhalt hinzu.
-
----
+Optional extrahierter Inhalt einer URL.
 
 ## 6. Nutzerfrage
 
-Am Ende steht die aktuelle Benutzerfrage.
+Aktuelle Frage.
 
 ---
 
 # Antwort-Streaming
 
-Die Antwort wird nicht gesammelt und dann komplett ausgeliefert, sondern als Stream übertragen.
+## `AskSseController`
 
-## AskSseController
+Der Controller stellt zwei Streaming-Wege bereit:
 
-Der `AskSseController` stellt den SSE-Endpunkt bereit.
+- Job-basierter Flow: `POST /ask-jobs` plus `GET /ask-sse/{jobId}`
+- direkter Flow: `POST /ask-sse`
 
-Dabei werden:
-
-- Buffer geleert
-- Cookies weitergereicht
-- SSE-Header gesetzt
-- Daten als `data:`-Zeilen gesendet
-- am Ende ein `done`-Event ausgeliefert
+Der Job-basierte Flow unterstützt Statusabfrage, Event-IDs, Replay/Tailing und Stale-Erkennung.
 
 ## Vorteil
 
-Das Frontend kann Antworten live darstellen und laufend erweitern.
-
-Das verbessert die Benutzererfahrung deutlich, besonders bei längeren Antworten.
+Der Browser erhält schrittweise Ausgabe und kann Statusinformationen, Shopkarten und Folgeaktionen während bzw. nach der Antwort anzeigen.
 
 ---
 
 # Conversation Context und Historie
 
-RetrieX verwaltet Nutzerkontext über eine eigene Context-Schicht.
+`ContextService` speichert abgeschlossene Turns pro Client-ID.
 
-Dazu gehören insbesondere:
+Aktuelle Standardwerte:
 
-- Aufbau eines nutzerspezifischen Gesprächskontexts
-- Einbindung früherer Turns in den Prompt
-- Persistierung der finalen Antworthistorie
+- regulär: 25 Zeilen
+- Full-Context: 500 Zeilen
 
-So kann das System nicht nur auf Einzelfragen, sondern auf fortlaufende Dialoge reagieren.
+Full-Context ist nicht mehr implizit der Browserstandard, sondern muss ausdrücklich angefordert werden.
+
+---
+
+# Security und Rollenmodell
+
+## Firewalls
+
+`config/packages/security.yaml` definiert getrennte Firewalls:
+
+- `admin` für `^/admin`
+- `chat` für Chat-, Ask-, SSE-, History- und Frontend-Message-Routen
+- `main` für sonstige öffentliche/statische Ressourcen
+
+## Rollenmatrix
+
+| Bereich | Effektive Rolle |
+| --- | --- |
+| Chat, Ask/SSE, History, Frontend-Messages | `ROLE_CHAT_USER` |
+| Admin-Dashboard, Guides, Jobs | `ROLE_ADMIN_AREA` |
+| Dokumente, Versionen, Tags, Dokument-Ingest | `ROLE_EDITOR` |
+| Modell-/Retrieval-Konfiguration, Ingest-Profile ansehen | `ROLE_KNOWLEDGE_ADMIN` |
+| Userverwaltung, Logs, System Prompt/Agent, Global Reindex, Reset/Delete | `ROLE_SUPER_ADMIN` |
+
+`ROLE_USER` alleine reicht für keinen Bereich.
+
+---
+
+# Admin-Bereich
+
+Admins können je nach Rolle steuern:
+
+- Dokumente und Versionen
+- Tags und Tag-Zuweisungen
+- Ingest-Jobs
+- Global Reindex
+- Modell-/Retrieval-Konfiguration
+- Ingest-Profile
+- System Prompt
+- System Agent
+- Logs
+- Benutzerverwaltung
+
+Die Admin-Navigation blendet Aktionen passend zur Rolle aus. Serverzugriffe sind zusätzlich über `access_control` und Controller-Checks geschützt.
+
+---
+
+# Userverwaltung
+
+Die Userverwaltung in v1.6.0 umfasst:
+
+- Liste, Anlage und Bearbeitung von Benutzern
+- Rollenzuweisung
+- Passwortsetzen
+- Aktiv-/Inaktiv-Schaltung
+- Self-Protection
+- Schutz des letzten aktiven Super-Admins
+- Loginblock für deaktivierte Benutzer
+- Session-Abmeldung für nachträglich deaktivierte Benutzer
+
+---
+
+# Fehlerseiten und Access Denied
+
+RetrieX rendert konsistente Fehlerseiten für:
+
+- 403
+- 404
+- 500
+- generische Fehler
+
+Der Access-Denied-Handler unterscheidet Chat- und Adminbereich und zeigt die benötigte Rolle sowie sinnvolle Rücksprung- und Logout-Optionen.
 
 ---
 
 # Modell- und Antwortsteuerung
 
-Ein Teil des Systemverhaltens wird über Modellkonfigurationen gesteuert.
+Die Antwortqualität wird gesteuert durch:
 
-Dazu gehören fachlich und technisch insbesondere:
+- aktiven System-Prompt
+- `prompt.yaml`
+- `model.yaml`
+- `retrieval.yaml`
+- `language.yaml`
+- `vocabulary.yaml`
+- `commerce.yaml`
+- `search_repair.yaml`
+- `agent.yaml`
+- `genre.yaml`
+- `chat-messages.yaml`
 
-- welches Modell verwendet wird
-- wie Retrieval parametriert ist
-- wie viele Chunks eingebunden werden
-- wie breit die Vektorsuche sucht
-- wie stark die Antwort durch System-Prompt und Kontext geprägt wird
-
-Diese Konfiguration ist bewusst nicht „wild überschreibbar“, sondern an die aktiven Systemobjekte gebunden.
+Viele fachliche Listen liegen bewusst in YAML und nicht hartcodiert im PHP-Core.
 
 ---
 
 # Was Admins fachlich steuern
 
-Aus Admin-Sicht wird nicht nur „die KI“ gesteuert, sondern ein ganzes Wissens- und Antwortsystem.
+Admins und Knowledge-Admins steuern je nach Rolle:
 
-Steuerbar sind unter anderem:
-
-- welche Dokumente im System existieren
-- welche Version aktiv ist
-- welche Ingest-Profile gelten
-- wann Reindexing ausgelöst wird
-- welcher System-Prompt aktiv ist
-- welche Modellkonfiguration aktiv ist
-- ob und wie Commerce integriert ist
+- welche Dokumentversion aktiv ist
+- wann ingestiert oder reindiziert wird
+- welche System-Prompts aktiv sind
+- welche Modellkonfiguration genutzt wird
+- welche Ingest-Profile sichtbar bzw. aktiv sind
+- welche Benutzer Zugriff auf Chat oder Admin haben
 
 ---
 
 # Was die Antwortqualität tatsächlich beeinflusst
 
-Die Qualität der Antworten hängt direkt von mehreren Ebenen ab:
-
 ## 1. Dokumentqualität
 
 Schlecht strukturierte oder inhaltlich schwache Dokumente führen zu schwachen Antworten.
@@ -611,76 +628,69 @@ Schlecht strukturierte oder inhaltlich schwache Dokumente führen zu schwachen A
 ## 2. Aktivierungslogik
 
 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:
-
-- dokumentenzentriert statt modellzentriert
-- deterministisch statt zufällig orchestriert
-- reproduzierbar statt implizit
-- governance-fähig statt unkontrolliert
-- hybrid im Retrieval
-- erweiterbar durch Shopdaten
-- streamingfähig in der Ausgabe
+- Keine freie Wissensbehauptung ohne Datenbasis.
+- Aktive Dokumentversionen sind fachliche Primärquelle.
+- Shopdaten sind autoritativ für Produkt-/Preis-/Verfügbarkeitsdaten.
+- Technische Eignung darf nicht aus Shopdaten allein überinterpretiert werden.
+- YAML ist Source of Truth für konfigurierbare Fachlogik.
+- PHP-Core soll Orchestrierung leisten, nicht Domainlisten verstecken.
+- Rollen müssen UI-seitig und serverseitig konsistent sein.
+- Regressionstests schützen bekannte stabile Flows.
 
 ---
 
 # Was RetrieX ausdrücklich nicht ist
 
-RetrieX ist im aktuellen Design:
+RetrieX ist nicht:
 
-- kein rein freier LLM-Chat
-- kein ausschließlich kreatives Generierungssystem
-- kein manuell gepflegter Chunk-Editor
-- kein Produktkatalog ohne Wissenslogik
-- kein rein vektorbasierter Blackbox-Sucher
-
-Es ist ein **kontrolliertes Antwortsystem**, das Wissen, Routing, Produktdaten und Modellformulierung zusammenführt.
+- ein frei improvisierender Chatbot
+- ein Ersatz für Datenpflege
+- ein Ersatz für validierte technische Beratung in Grenzfällen
+- ein manuell gepflegter Chunk-Editor
+- ein Shop-Scraper
+- ein unkontrollierter Prompt-Wrapper um ein LLM
 
 ---
 
 # Kurz zusammengefasst
 
-RetrieX arbeitet im Kern so:
-
-1. Dokumente und Versionen definieren den Wissensstand
-2. Ingest erzeugt daraus NDJSON-Chunks
-3. daraus wird der FAISS-Index vollständig neu aufgebaut
-4. bei einer Anfrage laufen Retrieval, Routing und optional Commerce-Suche
-5. PromptBuilder kombiniert Systemregeln, Kontext, Wissenschunks, URL-Inhalte und Shopdaten
-6. das Modell formuliert daraus die Antwort
-7. die Ausgabe wird per SSE ins Frontend gestreamt
-
-Kurzform:
-
-**Dokumente → Ingest → NDJSON → Vector Index → Retrieval → Prompt-Aufbau → LLM-Antwort → SSE-Streaming**
+1. Dokumente und Versionen definieren den Wissensstand.
+2. Ingest erzeugt Chunks und FAISS-Indizes.
+3. Retrieval sucht gezielt Kontext.
+4. Commerce kann Shopware-Daten ergänzen.
+5. PromptBuilder setzt Systemregeln, Kontext, Shopdaten und Frage zusammen.
+6. Das LLM formuliert die Antwort.
+7. SSE streamt die Antwort ins Frontend.
+8. Rollen und Adminlogik steuern Zugriff und Betrieb.
+9. YAML- und Audit-Guardrails schützen die Wartbarkeit.
 
 ---
 
 # Merksatz
 
-> Sie steuern in RetrieX nicht einfach nur ein Modell.  
-> Sie steuern die zugelassene Wissensbasis, die Suchlogik, die Antwortregeln und – bei Produktfragen – die produktbezogene Live-Datenquelle.
-
-Die KI formuliert.  
-RetrieX bestimmt, worauf sie sich dabei stützen darf.
+RetrieX v1.6.0 ist kein Chatbot mit Dokumentanhang, sondern eine kontrollierte Antwortinfrastruktur aus Wissen, Suche, Shopdaten, Rollenmodell und Governance.

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:  
-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.
+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.
 
 ---
 
-## 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:
-
-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
+Zusätzlich existiert weiterhin `POST /ask-sse` als direkter Streaming-Endpunkt.
 
 ---
 
@@ -107,21 +177,22 @@ Die Anfrage läuft im aktuellen Stand vereinfacht so:
 
 Eigenschaften:
 
-- Nutzerhistorie wird pro Client-ID in einer Textdatei gespeichert
-- abgeschlossene Turns werden append-only geschrieben
-- regulärer Kontext und Full-Context sind getrennt vorgesehen
-- der aktuelle SSE-Flow ruft `AgentRunner->run(..., true)` auf und nutzt damit **vollen Kontext**
+- Historie wird pro stabiler Client-ID gespeichert.
+- abgeschlossene Turns werden append-only geschrieben.
+- regulärer Kontext und Full-Context sind getrennt vorgesehen.
+- 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
-- voller Kontext: letzte 500 Zeilen
+- regulärer sichtbarer Kontext: letzte 25 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
-2. Guardrails prüfen die Strukturverträglichkeit
-3. alte Chunks des Dokuments werden entfernt
-4. neue Chunks werden streamingfähig geschrieben
-5. der komplette Vektorindex wird neu gebaut
-6. Runtime-Stats werden atomar aktualisiert
-7. Status der Version wird auf `INDEXED` gesetzt
+1. Dokumentversion wird aktiviert oder ingestiert.
+2. Guardrails prüfen die Strukturverträglichkeit.
+3. Alte Chunks des Dokuments werden entfernt.
+4. Neue Chunks werden streamingfähig geschrieben.
+5. Der komplette Vektorindex wird neu gebaut.
+6. Runtime-Stats werden atomar aktualisiert.
+7. Status der Version wird auf `INDEXED` gesetzt.
 
 Wichtige Eigenschaft:
 
-- Pro Dokument gibt es fachlich eine aktive Version
-- Chunks sind abgeleitete Artefakte, keine Primärdaten
+- Pro Dokument gibt es fachlich eine aktive Version.
+- 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.
-
-Wenn sich relevante Strukturparameter geändert haben, wird lokaler Ingest blockiert.
+Prüft über `IndexMetaManager`, ob der aktuelle Index strukturell zur aktiven Konfiguration passt. Wenn relevante Strukturparameter geändert wurden, wird lokaler Ingest blockiert.
 
 ### `ChunkWriteService`
 
@@ -236,31 +303,13 @@ Orchestriert:
 
 ---
 
-## Guardrails
-
-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
+## Retrieval
 
 Der aktive Retriever ist:
 
 - `App\Knowledge\Retrieval\NdjsonHybridRetriever`
 
-Wichtig:  
-„Hybrid“ bedeutet hier im verifizierten Code nicht einfach „Keyword + Vektor“, sondern eine orchestrierte Kombination aus mehreren Retrieval-Schritten.
+„Hybrid“ bedeutet im aktuellen Code eine orchestrierte Kombination aus mehreren Retrieval-Schritten.
 
 ### Aktuelle Retrieval-Pipeline
 
@@ -289,10 +338,11 @@ Wichtig:
 
 ### Besondere Logiken
 
-- Listenfragen werden gesondert erkannt
-- Kataloganfragen können direkt einen Katalogblock statt regulärer Chunks liefern
-- globale und gescopte Treffer werden gefused
-- Chunk-Selektion ist dokument- und abstandsbegrenzt
+- Listenfragen werden gesondert erkannt.
+- Kataloganfragen können direkt einen Katalogblock statt regulärer Chunks liefern.
+- globale und gescopte Treffer werden gefused.
+- 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 Quelle**.
+Für Produktfragen behandelt das System Shopdaten explizit als führende Produktquelle. Fachliche Eignungsaussagen bleiben dennoch an RAG-/Kontextbelege und Prompt-Guardrails gebunden.
 
 ---
 
 ## 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
-2. LLM erzeugt zunächst eine kurze Shop-Suchphrase
-3. `ShopSearchService` ruft `CommerceQueryParser` auf
-4. `ShopwareCriteriaBuilder` baut Suchkriterien
-5. `StoreApiClient` ruft `/store-api/search` auf
-6. Ergebnisse werden zu `ShopProductResult` gemappt
-7. Ergebnisse fließen in den Prompt ein
+1. Commerce-Intent erkennen.
+2. LLM erzeugt zunächst eine kurze Shop-Suchphrase.
+3. `CommerceQueryParser` normalisiert und bereinigt die Query.
+4. Follow-up-/History-/RAG-Anker können die Query ergänzen.
+5. `SearchRepairService` kann fehlende oder zu enge Shopqueries reparieren.
+6. `ShopwareCriteriaBuilder` baut Suchkriterien.
+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:
-
-- **heuristische Intent-Erkennung**
-- **LLM-unterstützte Kurzsuchphrase**
-- **deterministische Nachverarbeitung im Parser**
-- **Store-API-Suche**
-
-### 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`
+- Exakte Artikelnummern und Produktnummern werden bevorzugt.
+- Exakte Zubehörcodes bleiben exakt.
+- Produktlisten-Follow-ups werden in Einzelqueries aufgeteilt.
+- Produktidentität wird über Name, URL, Artikelnummer und sichtbare Antwortprodukte abgesichert.
+- Schwache Shop-Meta-Fragen dürfen auf konkrete History-Anker zurückfallen.
+- Shop-only Antworten bleiben vorsichtig, wenn keine belastbare technische Eignung belegt ist.
 
 ---
 
 ## 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.
-- No new PHP-only semantic defaults, token lists, prompt texts, matching rules or business fallbacks.
-- New configurable behavior must be added through YAML and wired explicitly.
-- Regression-sensitive flows from the 1.4.2/1.5.0 baseline must remain protected.
-- Strict YAML validation is deferred and must remain disabled by default when introduced later.
+- YAML unter `config/retriex/` ist die Source of Truth für konfigurierbares Verhalten.
+- Keine neuen PHP-only-semantischen Defaults, Tokenlisten, Prompttexte, Matching-Regeln oder Business-Fallbacks.
+- Neues konfigurierbares Verhalten muss über YAML ergänzt und explizit verdrahtet werden.
+- Regression-sensitive Flows aus den stabilen 1.4.x/1.5.x/1.6.0-Baselines müssen geschützt bleiben.
+- Core-Pattern- und Source-Audits sollen Domainlisten im PHP-Core verhindern.