From 83fd13fb982e5017489a234b492f6fabd7798587 Mon Sep 17 00:00:00 2001
From: dschlueter <dschlueter@kitux.de>
Date: Sat, 11 Jul 2026 00:59:06 +0200
Subject: [PATCH] Close two documentation gaps found during an accuracy audit

- README's "Bekannte Stolpersteine" quick-reference list was missing the
  podcast-language pitfall (already documented in CLAUDE.md/BEDIENUNGSANLEITUNG.md).
- The search/ask feature was only mentioned in passing; added a full section
  with the working curl examples and the SSE response shape, since it's the
  fastest/most accurate way to query long documents.

Everything else cross-checked against live state (credential num_ctx,
default models, running services, episode profile languages) and matched.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 BEDIENUNGSANLEITUNG.md | 49 ++++++++++++++++++++++++++++++++++++++++--
 README.md              |  3 +++
 2 files changed, 50 insertions(+), 2 deletions(-)

diff --git a/BEDIENUNGSANLEITUNG.md b/BEDIENUNGSANLEITUNG.md
index 29ee4c4..156db98 100644
--- a/BEDIENUNGSANLEITUNG.md
+++ b/BEDIENUNGSANLEITUNG.md
@@ -15,7 +15,8 @@ siehe [`CLAUDE.md`](CLAUDE.md).
 5. [Stimmklonung](#5-stimmklonung)
 6. [Modelle und Provider verwalten](#6-modelle-und-provider-verwalten)
 7. [Dienste starten/stoppen](#7-dienste-startenstoppen)
-8. [Troubleshooting](#8-troubleshooting)
+8. [Suche über Chunks (Search/Ask)](#8-suche-über-chunks-searchask)
+9. [Troubleshooting](#9-troubleshooting)
 
 ---
 
@@ -220,7 +221,51 @@ ollama ps        # aktuell geladene Modelle + GPU/CPU-Verteilung
 
 ---
 
-## 8. Troubleshooting
+## 8. Suche über Chunks (Search/Ask)
+
+Jedes Dokument wird beim Hochladen automatisch in feste, überlappende Textabschnitte
+("Chunks", ~400 Tokens) zerlegt und eingebettet — **nicht** kapitelweise, sondern rein
+größenbasiert (siehe Abschnitt 2). Um gezielt in diesen Chunks zu suchen, gibt es zwei
+API-Endpunkte (in der UI vermutlich unter einem eigenen Menüpunkt wie „Search"/„Ask" mit
+Lupen-Symbol, getrennt von „Mit Notebook chatten" — die genaue Beschriftung war ohne
+Browser-Zugriff nicht zu verifizieren):
+
+### Einfache Suche — schnell, liefert Roh-Textstellen
+
+```bash
+curl -s -X POST http://127.0.0.1:5055/api/search \
+  -H "Content-Type: application/json" \
+  -d '{"query": "Suchbegriff", "type": "vector", "limit": 5}'
+```
+
+Liefert die ähnlichsten Chunks per Embedding-Vergleich samt Ähnlichkeits-Score (0–1), ohne
+KI-Interpretation — am schnellsten, aber du musst die Antwort selbst zusammensetzen.
+
+### „Ask" — durchsuchen und direkt beantworten lassen
+
+Die smartere Variante: Die KI zerlegt die Frage selbst in mehrere gezielte Suchanfragen,
+durchsucht die Chunks für jede getrennt und fasst alles zu einer einzigen, mit
+Quellenverweisen (`[source:...]`) belegten Antwort zusammen. Getestet mit „Wie kam Wallenstein
+ums Leben?" — Ergebnis war eine vollständige, korrekt zitierte Antwort in ca. 3 Minuten
+(mehrere LLM-Aufrufe hintereinander: Suchstrategie → Einzelantworten → Zusammenfassung).
+
+```bash
+MODEL_ID=$(curl -s http://127.0.0.1:5055/api/models/defaults | python3 -c "import json,sys; print(json.load(sys.stdin)['default_chat_model'])")
+curl -N -X POST http://127.0.0.1:5055/api/search/ask \
+  -H "Content-Type: application/json" \
+  -d "{\"question\": \"Deine Frage\", \"strategy_model\": \"$MODEL_ID\", \"answer_model\": \"$MODEL_ID\", \"final_answer_model\": \"$MODEL_ID\"}"
+```
+
+Antwort kommt als Server-Sent-Events-Stream (`data: {...}`-Zeilen, kein einzelnes JSON-Objekt);
+das letzte `"type": "complete"`-Event enthält die finale Antwort im Feld `final_answer`.
+
+**Wann was nutzen:** Für gezielte Detailfragen über lange/viele Quellen ist „Ask" meist
+treffsicherer und dabei noch schneller als der „vollständiger Inhalt"-Chat-Modus (Abschnitt 3),
+weil nur die relevanten Chunks statt des ganzen Dokuments verarbeitet werden.
+
+---
+
+## 9. Troubleshooting
 
 ### „Chat gibt keine Antwort" (leere Antwort, kein Fehler)
 
diff --git a/README.md b/README.md
index fc3eb86..789f885 100644
--- a/README.md
+++ b/README.md
@@ -204,3 +204,6 @@ Kurzreferenz — Details jeweils in [`CLAUDE.md`](CLAUDE.md):
   leere Chat-Antworten bei größerem Kontext, ohne sichtbaren Fehler.
 - **Neue Host-Ports brauchen eine `ufw`-Regel**, sonst kann der Container sie nicht erreichen
   (Timeout, keine Fehlermeldung in Open Notebook selbst).
+- **Podcasts werden ohne explizites `language`-Feld auf Englisch erzeugt**, unabhängig von der
+  Sprache der Quelle. Die drei mitgelieferten Episode-Profile sind bereits auf `"de"` gesetzt;
+  bei selbst angelegten Profilen selbst daran denken.