Docs: close the gaps an audit turned up

Audited README, BEDIENUNGSANLEITUNG and CLAUDE.md against what the repo and the
running stack actually do. Findings, all fixed:

- CLAUDE.md claimed the repo holds "only deployment config (docker-compose.yml,
  .env, .gitignore)". It has not been that for a while: services/ is our own
  source (TTS/STT servers + systemd units), scripts/ is tooling, and
  prompts/podcast/ + config/content_core.yaml are overlays bind-mounted over the
  image. Those overlays are the fragile part, so the section now says so and
  points at smoke_test.sh.
- CLAUDE.md still described the image as a moving tag and argued against patching
  app code "because it would rot against pull_policy: always" — both obsolete
  since the digest pin.
- README listed neither yt-dlp (needed by add_video_source.py) nor smoke_test.sh
  in the verification step, and section 2.3 still told you to `docker compose pull`
  as if the tag moved.
- BEDIENUNGSANLEITUNG had nothing at all about updates — the very thing a user has
  to do periodically. New section 8 covers check_updates / update_stack / smoke_test
  and, importantly, why updating is not automatic (DB migration is one-way without
  a backup; the local adaptations can break silently without crashing).
- Renumbered the ad-hoc "3a. Updates" in README into a real section 4, and the
  BEDIENUNGSANLEITUNG sections after the new 8 accordingly.

Verified mechanically: every scripts//services//config//prompts/ path named in the
docs exists, and all internal and cross-document anchors resolve (0 dead links —
one was already broken before this change: README pointed at
BEDIENUNGSANLEITUNG.md#stimmklonung instead of #5-stimmklonung).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Dieter Schlüter 2026-07-11 14:17:06 +02:00
commit 09c6d910a7
3 changed files with 82 additions and 16 deletions

View file

@ -15,9 +15,10 @@ 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. [Suche über Chunks (Search/Ask)](#8-suche-über-chunks-searchask)
9. [Die API in eigenen Programmen nutzen](#9-die-api-in-eigenen-programmen-nutzen)
10. [Troubleshooting](#10-troubleshooting)
8. [Updates einspielen](#8-updates-einspielen)
9. [Suche über Chunks (Search/Ask)](#9-suche-über-chunks-searchask)
10. [Die API in eigenen Programmen nutzen](#10-die-api-in-eigenen-programmen-nutzen)
11. [Troubleshooting](#11-troubleshooting)
---
@ -256,7 +257,54 @@ ollama ps # aktuell geladene Modelle + GPU/CPU-Verteilung
---
## 8. Suche über Chunks (Search/Ask)
## 8. Updates einspielen
Open Notebook läuft hier auf einer **festgenagelten Version** (Digest-Pin in
`docker-compose.yml`). Weder ein Start noch ein Reboot tauscht die Anwendung unbemerkt aus — Sie
bekommen immer genau den Stand, der zuletzt geprüft wurde.
**Beim Sitzungsstart** (ändert nichts, dauert Sekunden):
```bash
./scripts/check_updates.sh
```
Ausgabe entweder „Du laeufst auf dem aktuellen Release. Nichts zu tun." oder ein Hinweis auf ein
neues Image.
**Update einspielen:**
```bash
./scripts/update_stack.sh
```
Das Skript sichert zuerst Datenbank und Notebook-Daten nach `backups/<Zeitstempel>/`, stellt dann
auf das neue Image um, startet den Stack und fährt einen **Rauchtest** (API, Sprachausgabe,
Spracherkennung, YouTube-Import, alle lokalen Anpassungen). Schlägt der fehl, wird **automatisch
zurückgerollt** — Daten und Konfiguration landen wieder auf dem alten Stand.
Läuft alles, committen Sie den neuen Stand:
```bash
git add docker-compose.yml && git commit -m "Update auf <Version>"
```
**Warum nicht einfach immer die neueste Version?** Ein Update verändert das Datenbankschema, und
eine ältere Version kann eine bereits migrierte Datenbank in der Regel nicht mehr lesen — ohne
Sicherung wäre ein misslungenes Update also eine Einbahnstraße. Außerdem hängen die Anpassungen
dieser Installation (Podcast-Vorlagen, YouTube-Sprachen, TTS-Einstellungen) an Interna der
Anwendung und können durch ein Update **still** kaputtgehen, ohne dass etwas abstürzt. Genau
deshalb der Rauchtest.
Ihn können Sie auch jederzeit einzeln laufen lassen, etwa wenn sich etwas seltsam verhält:
```bash
./scripts/smoke_test.sh
```
---
## 9. 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
@ -300,7 +348,7 @@ weil nur die relevanten Chunks statt des ganzen Dokuments verarbeitet werden.
---
## 9. Die API in eigenen Programmen nutzen
## 10. Die API in eigenen Programmen nutzen
Die REST-API ist eine ganz normale JSON-über-HTTP-API **ohne Authentifizierung** — kein API-Key
nötig, da nur `127.0.0.1` gebunden (jeder lokale Prozess auf diesem Rechner hat Zugriff, aber
@ -361,7 +409,7 @@ Spezifisches nötig, kein SDK erforderlich.
---
## 10. Troubleshooting
## 11. Troubleshooting
### „Chat gibt keine Antwort" (leere Antwort, kein Fehler)