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