update

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

.env.example

@@ -1,3 +1,6 @@
+# Standard-Provider für alle Agenten (Pflicht — es gibt keinen Code-Default)
+DEFAULT_PROVIDER=minimax
+
 # Datei nach .env kopieren (wird nicht committet).
 
 # Claude-Provider: lokal einmal 'claude setup-token' ausführen, Token eintragen.
@@ -5,3 +8,21 @@ CLAUDE_CODE_OAUTH_TOKEN=
 
 # MiniMax-Provider: API-Key aus der MiniMax-Console (Coding-Plan).
 MINIMAX_API_KEY=
+
+# Optional — Rollen-Mixing über Anbieter-Grenzen (Standard: die UI-Auswahl gilt für alles).
+# Wert: Provider-Name ("claude"/"minimax"/"lokal") oder "provider:modell".
+#ROLE_QUICK=
+#ROLE_JUDGE=
+#ROLE_GUIDE=
+#ROLE_FAST=
+
+# Parallelität (Defaults: siehe backend/config.py). Prozess-Tier = opencode-Prozesse
+# (~310 MB RSS pro Agent), API-Tier = direkte MiniMax-Calls für tool-lose Agenten (~0 RAM).
+# Auf 8-GB-Maschinen Prozess-Limit klein halten; das API-Tier darf hoch.
+#MAX_CONCURRENT_AGENTS=8
+#MAX_CONCURRENT_AGENTS_PER_TOPIC=24
+#MAX_CONCURRENT_API_AGENTS=28
+# opencode-Starts warten, wenn weniger als dieser Anteil RAM frei ist (0 = aus).
+#RAM_MIN_FREE_PCT=20
+# Kill-Switch: 0 = Text-Calls wieder über opencode-Prozesse statt direkter API.
+#CREATOR_TEXT_API=0

CLAUDE.md

@@ -0,0 +1,12 @@
+# Ziele
+- Auswahl der Bausteine / Subbausteine optimieren: Also Entfernen würde eine Lücke erzeugen und Hinzufügen würde eine Dopplung erzeugen 
+- Performance maximieren: Der Makespan soll so gering wie möglich sein 
+- Tokenverbrauch minimieren: Gesamtverbraucht der Tokens soll so gering wie möglich sein 
+- Korrektheit: Faschinformationen so gerin wie möglich halten
+
+# Soll folgende Probleme lösen  
+- Perfektionismus: Ich brauche die Info was 100% vom Thema ist
+- Kontrolle: Ich muss wissen wie weit ich bin, um es für mich zu planen und tracken 
+- Optimale Auswahl: Zu große Auswahl verlängert die Bearbeitungszeit und die Motivation bricht weg, wenn ich zu wenig Fortschritt sehe; Zu gerine Auswahl triggert den Perfektionismus
+- Tokenverbrauch: Je weniger Token verbaucht werden, desto stärkere Modelle kann ich nehmen 
+- Performance: Bei zu langer Generierungen erschöpft meine Geduld

Dockerfile

@@ -14,6 +14,9 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
     ca-certificates \
     gnupg \
     poppler-utils \
+    tesseract-ocr \
+    tesseract-ocr-deu \
+    tesseract-ocr-eng \
     && curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
     && apt-get install -y nodejs \
     && npm install -g @anthropic-ai/claude-code opencode-ai \
@@ -23,7 +26,15 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
 RUN useradd -m -u 1000 app
 
 COPY backend/requirements.txt /app/backend/requirements.txt
-RUN pip install --no-cache-dir -r /app/backend/requirements.txt
+# torch als CPU-Build (~190 MB) — eigener Index, sonst zieht pip die CUDA-Variante (~2,5 GB).
+# Fürs Lesbarkeits-Gate (transformers nutzt das vorhandene torch).
+RUN pip install --no-cache-dir torch --index-url https://download.pytorch.org/whl/cpu \
+    && pip install --no-cache-dir -r /app/backend/requirements.txt
+
+# Chromium + OS-Libs für Playwright (als root) in ein gemeinsames, welt-lesbares Verzeichnis.
+ENV PLAYWRIGHT_BROWSERS_PATH=/ms-playwright
+RUN python3 -m playwright install --with-deps chromium \
+    && chmod -R a+rX /ms-playwright
 
 COPY --chown=app:app backend/ /app/backend/
 COPY --chown=app:app templates/ /app/templates/

Makefile

@@ -1,10 +1,10 @@
-.PHONY: install dev prod stop logs remove auth sync searxng ollama
+.PHONY: install dev prod stop logs remove auth sync sync-projects sync-all sync-all-reverse projects searxng ollama qa test test-e2e train train-init train-server
 
 COMPOSE = docker compose
 
 auth:
-	@mkdir -p .claude-data storage projects
-	@chown -R 1000:1000 .claude-data storage projects
+	@mkdir -p .claude-data storage projects uni
+	@chown -R 1000:1000 .claude-data storage projects uni
 	@grep -q "^CLAUDE_CODE_OAUTH_TOKEN=.\+" .env 2>/dev/null \
 		|| echo "WARNUNG: CLAUDE_CODE_OAUTH_TOKEN fehlt in .env (Claude-Provider inaktiv)."
 	@grep -q "^MINIMAX_API_KEY=.\+" .env 2>/dev/null \
@@ -12,8 +12,12 @@ auth:
 	@echo "Verzeichnisse angelegt und auf uid 1000 chowned."
 
 install:
-	pip install --break-system-packages fastapi uvicorn[standard] aiosqlite uv
+	pip install --break-system-packages fastapi uvicorn[standard] aiosqlite uv playwright transformers trafilatura pymupdf4llm
+	pip install --break-system-packages torch --index-url https://download.pytorch.org/whl/cpu
+	python3 -m playwright install chromium
+	@echo "Falls Chromium OS-Libs fehlen: 'sudo python3 -m playwright install-deps chromium' einmalig ausführen."
 	@which pdftotext >/dev/null 2>&1 || sudo apt-get install -y poppler-utils
+	@which tesseract >/dev/null 2>&1 || sudo apt-get install -y tesseract-ocr tesseract-ocr-deu tesseract-ocr-eng
 	cd frontend && npm install
 	npm install -g opencode-ai
 	@mkdir -p $(HOME)/.config/opencode
@@ -58,8 +62,79 @@ ollama:
 	ollama pull qwen3.5:9b
 	@echo "Ollama bereit — Provider 'Lokal' ist aktiv (Modelle anpassen: backend/config.py + dev-ops/opencode.json)."
 
-sync:
-	@mkdir -p storage/themen
+# Remote wird für die DB-Kopie gestoppt (sonst reißt der Snapshot mitten im Schreibvorgang)
+# und danach wieder gestartet.
+sync: stop
+	@mkdir -p storage/topics uni
+	@rm -f storage/creator.db-shm storage/creator.db-wal
+	ssh root@178.104.67.87 'cd /var/www/creator && docker compose down'
 	rsync -avz --progress root@178.104.67.87:/var/www/creator/storage/creator.db storage/
-	rsync -avz --progress --delete root@178.104.67.87:/var/www/creator/storage/themen/ storage/themen/
-	@echo "Sync abgeschlossen."
+	-rsync -avz --progress root@178.104.67.87:/var/www/creator/storage/creator.db-wal storage/
+	rsync -avz --progress --delete root@178.104.67.87:/var/www/creator/storage/topics/ storage/topics/
+	rsync -avz --progress --delete root@178.104.67.87:/var/www/creator/uni/ uni/
+	ssh root@178.104.67.87 'cd /var/www/creator && docker compose up -d'
+	@echo "Sync abgeschlossen — Remote läuft wieder."
+
+# Projekte vom Server holen: `make sync-projects` (auch: `make sync projects`).
+# Mit --delete — exakter Spiegel: lokale Projekte ohne Server-Pendant werden gelöscht.
+sync-projects:
+	@mkdir -p projects
+	rsync -avz --progress --delete root@178.104.67.87:/var/www/creator/projects/ projects/
+	@echo "Projekt-Sync abgeschlossen."
+
+sync-all: sync sync-projects
+	@echo "Voller Sync (Themen + Projekte) abgeschlossen."
+
+# Gegenstück zu sync-all: lokalen Stand auf den Server schieben (Local → Remote).
+# Stoppt den Remote-Server (DB-Sicherheit), pusht DB + Themen + Projekte, startet ihn neu.
+# --delete = exakter Spiegel: Remote-Dateien ohne lokales Pendant werden gelöscht.
+sync-all-reverse: stop
+	@echo "ACHTUNG: überschreibt den Remote-Stand (DB, topics/, uni/, projects/) mit dem lokalen."
+	@[ -f storage/creator.db ] || { echo "Keine lokale DB — abgebrochen."; exit 1; }
+	ssh root@178.104.67.87 'cd /var/www/creator && docker compose down'
+	ssh root@178.104.67.87 'rm -f /var/www/creator/storage/creator.db-shm /var/www/creator/storage/creator.db-wal'
+	rsync -avz --progress storage/creator.db root@178.104.67.87:/var/www/creator/storage/
+	@[ -f storage/creator.db-wal ] && rsync -avz --progress storage/creator.db-wal root@178.104.67.87:/var/www/creator/storage/ || true
+	rsync -avz --progress --delete storage/topics/ root@178.104.67.87:/var/www/creator/storage/topics/
+	rsync -avz --progress --delete uni/ root@178.104.67.87:/var/www/creator/uni/
+	rsync -avz --progress --delete projects/ root@178.104.67.87:/var/www/creator/projects/
+	ssh root@178.104.67.87 'cd /var/www/creator && docker compose up -d --build'
+	@echo "Reverse-Sync abgeschlossen — Remote läuft wieder."
+
+# QA-Report über einen abgeschlossenen Lauf (read-only): make qa TOPIC=aak
+qa:
+	@[ -n "$(TOPIC)" ] || { echo "Nutzung: make qa TOPIC=<thema> [LLM=1]"; exit 1; }
+	@set -a; [ -f .env ] && . ./.env; set +a; \
+		cd backend && python3 qa.py "$(TOPIC)" $(if $(LLM),--llm,)
+
+# Guide-QA über einen gebauten Guide (read-only): make qa-guide TOPIC=Markdown [LLM=1]
+qa-guide:
+	@[ -n "$(TOPIC)" ] || { echo "Nutzung: make qa-guide TOPIC=<thema> [LLM=1]"; exit 1; }
+	@set -a; [ -f .env ] && . ./.env; set +a; \
+		cd backend && python3 guide_qa.py "$(TOPIC)" $(if $(LLM),--llm,)
+
+projects: sync-projects
+
+# Backend-Testsuite (Injektionstests + Fake-E2E, keine echten Agenten)
+test:
+	cd backend && python3 -m pytest tests/ -q
+
+# Nur die Fake-E2E-Läufe (kompletter Generierungspfad in Sekunden)
+test-e2e:
+	cd backend && python3 -m pytest tests/test_e2e_fake.py -q
+
+# Parameter-Training auf Mini-Themen: make train [TRIALS=40] [STUNDEN=12]
+# Achtung: jeder Trial ist ein echter Mini-Lauf (MiniMax-Tokens, Minuten).
+train:
+	@set -a; [ -f .env ] && . ./.env; set +a; \
+		cd backend && python3 train.py --trials $(or $(TRIALS),40) --stunden $(or $(STUNDEN),12) --ameisen $(or $(AMEISEN),3)
+
+# Training im Container starten (auf dem Server ausführen; detached, überlebt ssh-Abbruch).
+# Fortschritt: storage/train/<sitzung>/trials.jsonl
+train-server:
+	docker exec -d creator python3 train.py --trials $(or $(TRIALS),40) --stunden $(or $(STUNDEN),12) --ameisen $(or $(AMEISEN),3)
+
+# Frozen-Inventar-Vorlage für das Training bauen (einmalig, echter Mini-Lauf)
+train-init:
+	@set -a; [ -f .env ] && . ./.env; set +a; \
+		cd backend && python3 train.py --init

README.md

@@ -1,18 +1,171 @@
-Bausteine finden 
-- 1+ Agenten suchen Bausteine zum Thema 
-- Baustein bekommt die Einstufung kern, wichtig und rest 
+# Creator
 
-MiniGuide generieren 
-- 1 Agent erstellt den Guide 
-- Nur Themen (kern) verwenden
-- MiniGuide-Format bestimmt den Stil 
+KI-Lernguide-Generator: Aus einem Thema, Uni-Skript, Projektordner oder Web-Link entsteht
+ein vollständiger, belegter Lernguide mit Übungssystem. FastAPI-Backend (`backend/`),
+Vue-Frontend (`frontend/`), SQLite (`storage/creator.db`). MiniMax generiert über die
+OpenCode-CLI, Judge-Agenten prüfen jede Stufe.
 
-Guide generieren 
-- 1 Agent erstellt den Guide 
-- Nur Themen (kern+wichtig) verwenden
-- Guide-Format bestimmt den Stil 
+**Diese README ist das Onboarding für den nächsten KI-Agenten.** Endnutzer-Features stehen
+unten. Persistente Detail-Notizen liegen im Claude-Memory des Projekts; dieses Dokument
+trägt das Wesentliche.
 
-Flow 
-- Bausteine finden
-- HTML erstellen 
-- Code prüfen 
+## Wofür das Projekt gebaut wird (die Gründe des Betreibers)
+
+- Lernen mit **Entscheidungsautomatik statt Wahlfreiheit**: Das System zerlegt, priorisiert
+  und prüft — der Lernende folgt dem Pfad, statt ihn zu bauen.
+- **100-%-Zerlegung** des Stoffs in Bausteine und Subbausteine, jede Aussage mit Beleg.
+- **MECE-Nordstern** (Kern des Projekts, wörtlich): „Man kann keinen Baustein entfernen,
+  ohne eine Lücke zu erzeugen, und keinen hinzufügen, ohne dass eine Dopplung entsteht."
+- Ideal: „Die Pipeline läuft durch, es ist eine 10/10, die Inhalte sind super —
+  nicht zu viel, nicht zu wenig, korrekt."
+
+## Entwicklungsphase: die vier Optimierungsziele
+
+Alle Arbeit optimiert, themenunabhängig:
+1. **Qualität** — Korrektheit maximieren.
+2. **Auswahl** — Lücken und Dopplungen minimieren (MECE).
+3. **Performance** — Gesamtlaufzeit minimieren.
+4. **Tokenverbrauch** — Generierung günstig halten.
+
+Fixes gehören in die **Pipeline** (Generierung). QA misst nur — Detektor-Konstanten und
+Notengewichte sind nie Teil einer Optimierung (Messinvarianz).
+
+## Architektur in einer Minute
+
+Drei Kanban-Boards (Engine: `kanban.py`, Karten in SQLite, resümierbar):
+1. **Inventar** (`board_inventory.py`): Research-Reader → Titel-Ingest → Cluster →
+   Konsens-Gate (+ Anker-Beleg gegen Kanon-Halluzination) → Naming (darf abstrahieren,
+   Anker-Pflicht) → Fragment-Filter → Dedup → Gruppierung → fertige Blöcke.
+   Danach QA-Gate (Note < 9.5 pausiert vor Board 2).
+2. **Artefakte** (`board_artefacts.py`): Subbausteine finden (Panel-Konsens) → Facts
+   (extract-once, Grounding für alles Spätere) → In-Block-Konsolidierung + Lücken-Nachfass
+   → Levels → Relevanz → Cross-Block-Dedup (Barriere, gechunkt) → Fragen → Flashcards/
+   Beispiele → Finalize (DB-Spiegel, Hygiene) → Outline.
+3. **Guide** (`guide_board.py`): Lernziele → Writer (Marker-Format, Längen-Budget) →
+   Fakten-Gate (CoVe; „falsch" fixt immer, „unbelegt" ab Schwelle) → Coverage → Lesbarkeit.
+
+Agenten-Rollen: `quick`/`fast` generieren, `judge` prüft (native MiniMax-Route — die
+kalt-Route stallte 20 % der Calls), `guide` schreibt. Große JSON-Antworten kommen als
+TEXT zurück (`_sink_or_file`) — Datei-schreibende Agenten verloren 40 Runden in
+JSON-Reparatur-Schleifen.
+
+## Arbeitsregeln (verbindlich, aus Erfahrung destilliert)
+
+- **Nie committen/pushen.** Der Betreiber committet selbst.
+- **Ändern nur auf Auftrag.** Beobachtungen berichten, nicht eigenmächtig fixen.
+  Ergebnisse nie nachträglich schönen.
+- **Kein Backend-Edit bei laufendem Flow**: vorher `curl -s localhost:8000/api/blocks/active`
+  == `[]` prüfen — `backend/*.py`-Edits triggern den uvicorn-Reload und killen Läufe.
+  `templates/` und `Makefile` sind gefahrlos.
+- **Generisch bleiben**: keine Domänen-Sonderregeln in Pipeline/Prompts. Quellen-Spezifika
+  löst der Import.
+- **Ursachen statt Symptome**: erst messen (Events, QA-Reports, OpenCode-Session-DB),
+  dann fixen. Kein Raten.
+- **Fragen zuerst beantworten**, dann handeln. Antworten knapp und auf Deutsch.
+- Keine Bewertungen fremder KI-Modelle/Provider (Geschwindigkeit, Qualität).
+- `.env` enthält echte API-Keys — nie exponieren.
+
+## Werkzeuge für Entwicklung und Diagnose
+
+| Kommando | Zweck |
+|---|---|
+| `make test` | ganze Suite (~240 Tests, ~20 s), inkl. Fake-E2E |
+| `make test-e2e` | nur Fake-E2E: kompletter Generierungspfad in Sekunden, ohne LLM |
+| `make qa TOPIC=… [LLM=1]` | Inventar-/Artefakt-QA read-only, Note 0–10 |
+| `make qa-guide TOPIC=… [LLM=1]` | Guide-QA |
+| `make train-init` | Frozen-Inventar-Vorlage für das Training bauen (einmalig) |
+| `make train [TRIALS] [STUNDEN] [AMEISEN]` | Ameisen-Optimierung der Parameter (anytime) |
+| `CREATOR_FAKE_AGENTS=1 make dev` | Server antwortet aus der Fake-Welt — UI-Smoke in Sekunden |
+| `CREATOR_PARAMS='{"X":1}'` | Parameter-Override pro Prozess (Registry: `backend/train_params.py`) |
+
+Diagnose-Quellen: `events`-Tabelle (Agent-Dauern/Tokens/Status je Lauf),
+`storage/qa/<topic>/*.json` (Report-Historie), `arbeit/lauf-summary.json`,
+OpenCode-Session-DB (`~/.local/share/opencode/opencode.db` — Turns/Tokens je Agent).
+
+## Training (`make train`)
+
+Ameisen-Algorithmus (ACO), anytime: Pheromon-Gewichte je Parameter-Stufe steuern die
+Kandidaten; je länger er läuft, desto gezielter die Tests. Drei Fidelity-Stufen:
+F0 Fake-E2E (0,5 s, Invarianten + Struktur-Proxy), F1 Frozen-Inventar (~5–8 min, Board 2
+auf kopiertem Inventar), F2 Volllauf mit Soll-Abgleich gegen
+`benchmarks/pruefstand/soll.json` (konstruiertes Thema mit bekannter Lösung und
+eingebauten Fallen). Übernahme nur nach Bestätigungslauf. Ergebnis:
+`storage/train/aco/{report.md, beste_params.json}`; Übernahme nach `config.py` ist
+manuell.
+
+## Entwicklungs-Meilensteine (was schon gelernt wurde)
+
+- MECE-Regelkreis: In-Block-Konsolidierung (2-Judge-Panel, Einstimmigkeit), Lücken-Nachfass
+  mit hartem Beleg-Gate, Cross-Block-Dedup mit Stichentscheid — Sub-Zahl 425→~213 bei
+  steigender Note.
+- Drei stabile QA-Noten (Inventar/Artefakte/Guide) mit Bestätiger-Pässen gegen
+  Judge-Rauschen; Repair arbeitet Befunde gezielt ab.
+- Resume-Dateien tragen einen Sub-Satz-Hash — Re-Runs übernehmen nie stale Ergebnisse;
+  Finalize löscht Alt-Reste (Lösch-Hygiene überall).
+- Facts-Nachfass: kein consensus-Sub ohne Grounding (sonst flutet das Fakten-Gate).
+- Judge-Stalls (20 % Timeouts) lagen an einer Provider-Route — Messen vor Raten.
+- Naming darf abstrahieren, aber nur korpus-verankert (Kanon-Halluzinations-Schutz).
+
+## Offene Ideen / nächste Schritte
+
+- Training auf dem Server laufen lassen (siehe unten), wirksame Parameter übernehmen.
+- Facts-Chunks parallelisieren; Live-Aktivität (Token-Zähler) an laufenden Karten zeigen.
+- Bekannte Cross-Dubletten knapp unter dem 0.75-Kandidaten-Floor.
+- Roadmap-Lernarchitektur: ein Guide + Stufen-Ansichten, ELO-Score mit wachsendem Cap.
+
+## Server-Betrieb mit 8 GB RAM
+
+- `.env`: `MAX_CONCURRENT_AGENTS=6`, `MAX_CONCURRENT_AGENTS_PER_TOPIC=6`.
+- Training: `make train AMEISEN=1` (jeder parallele Trial lädt das Embedding-Modell, ~1 GB).
+- Embedding + Readability halten zusammen ~1 GB im Backend-Prozess. 2–4 GB Swap anlegen.
+
+---
+
+# Features (Endnutzer-Sicht)
+
+## Quellen
+- Freies Thema: die KI recherchiert den Stoff selbst im Web.
+- Uni-Skript: lädt ein Skript und liest es abschnittsweise.
+- Projektordner: nutzt eigene Dateien als Quelle.
+- Web-Link: crawlt eine Seite und filtert relevante Inhalte.
+
+## Inhalt erstellen
+- Zerlegt den Stoff in einzelne Lern-Konzepte (Bausteine).
+- Führt doppelt genannte Konzepte automatisch zusammen.
+- Entfernt Bruchstücke, die keine eigenen Themen sind.
+- Gliedert jeden Baustein in Teilpunkte.
+- Belegt jeden Teilpunkt mit Fakten aus der Quelle.
+- Stuft Teilpunkte nach Schwierigkeit ein (Anfänger/Fortgeschritten/Experte).
+- Trennt Randthemen vom Kern.
+- Ordnet Bausteine in Kapitel mit Voraussetzungs-Reihenfolge.
+- Schreibt daraus einen lesbaren Guide.
+- Drei Guide-Varianten: fokussiert, komplett, nur Randthemen.
+- Erzeugt Karteikarten und durchgerechnete Beispiele.
+
+## Guide-Ansicht
+- Zeigt Mathe-Formeln korrekt gerendert.
+- Umschalten zwischen kurzer und ausführlicher Darstellung.
+- Filtert den Guide nach Lernstufe.
+- Prüft schwer lesbare Sätze und vereinfacht sie.
+- Einzelne Abschnitte auf Knopfdruck neu prüfen.
+
+## Lernen & Prüfen
+- Übungsfragen je Baustein generieren.
+- Vier Frageformen: Quiz, Lückentext, Freitext, Erklären.
+- KI bewertet Freitext-Antworten mit Begründung.
+- Punkte-System mit Stufen und Streak je Baustein.
+- Themenweite Gesamt-Prüfung über alle Bausteine.
+- Chat-Nachfrage zu jedem Baustein.
+- Fokus-Modus: Guide und Prüfung nebeneinander.
+
+## Eigene Elemente
+- Eigene Lern-Notizen per Stichwort erstellen lassen.
+- Notizen im Chat anpassen; KI prüft Lücken und Stil.
+
+## Steuerung
+- KI-Anbieter wählen: Claude, MiniMax, lokal.
+- Generierung ab jedem Schritt neu starten.
+- Ab jedem Schritt löschen, ohne neu zu generieren.
+- Laufende Generierung abbrechen oder fortsetzen.
+- Live-Fortschritt sehen.
+- Dark Mode.

backend/agents.py

@@ -1,20 +1,213 @@
-"""Provider-Schicht: führt Agent-Aufrufe über die Claude-CLI oder OpenCode (MiniMax) aus.
+"""Provider layer: runs agent calls via the Claude CLI or OpenCode (MiniMax).
 
-Beide Runner sind unabhängig. Fehlt ein Binary/Key, schlägt nur der
-jeweilige Provider fehl — der andere läuft unverändert weiter.
+Both runners are independent. If a binary/key is missing, only the
+respective provider fails — the other keeps running unchanged.
+
+Role routing: config.resolve_role maps (run_provider, role) → (provider, model)
+ACROSS stacks, so one run can generate on MiniMax and judge on Claude. If the
+routed provider is unavailable, the call falls back to the run's provider.
 """
 
 import asyncio
+import heapq
+import logging
 import os
 import re
 import shutil
+import signal
+import sqlite3
 import tempfile
+import time
 import urllib.request
+from contextlib import asynccontextmanager
 from pathlib import Path
 
-from config import PROVIDERS, DEFAULT_PROVIDER
+import httpx
+
+from config import (PROVIDERS, DEFAULT_PROVIDER, MAX_CONCURRENT_AGENTS,
+                    MAX_CONCURRENT_AGENTS_PER_TOPIC, MAX_CONCURRENT_API_AGENTS,
+                    MAX_CONCURRENT_INTERACTIVE, RAM_MIN_FREE_PCT, resolve_role)
+
+log = logging.getLogger("creator.agents")
 
 _active_processes: dict[str, asyncio.subprocess.Process] = {}
+_active_api: set[str] = set()            # agent_keys of running direct-API calls (no process to kill)
+_active_started: dict[str, float] = {}   # agent_key → wall-clock start (for the live runtime display)
+_active_labels: dict[str, str] = {}      # agent_key → human-readable label (for display + events)
+
+
+def active_agents(scope_prefix: str | None = None) -> list[dict]:
+    """Currently running agents and how long they've been running. Filter by key prefix
+    (e.g. f"blocks-{topic}-") for one topic. → [{key, label, runtime}] sorted longest-first."""
+    now = time.time()
+    out = [{"key": k, "label": _active_labels.get(k, ""), "runtime": round(now - t, 1)}
+           for k, t in list(_active_started.items())
+           if (k in _active_processes or k in _active_api)
+           and (not scope_prefix or k.startswith(scope_prefix))]
+    return sorted(out, key=lambda a: -a["runtime"])
+
+# Cancelled scopes (key prefixes, symmetric to kill_process). An agent whose
+# key starts with one of these prefixes aborts BEFORE the spawn — so agents WAITING
+# in the semaphore queue are also stopped immediately on abort instead of still starting.
+_cancelled_prefixes: set[str] = set()
+
+
+def cancel_scope(prefix: str) -> None:
+    _cancelled_prefixes.add(prefix)
+
+
+def clear_scope(prefix: str) -> None:
+    _cancelled_prefixes.discard(prefix)
+
+
+def _scope_cancelled(agent_key: str) -> bool:
+    return any(agent_key.startswith(p) for p in _cancelled_prefixes)
+
+# Caps the real CLI processes — independent of the pipeline semaphore in
+# generator.py. The acquire happens BEFORE the spawn so that queue wait time
+# does not count against the agent timeout.
+class _PrioritySemaphore:
+    """asyncio.Semaphore variant: when slots are scarce, the LOWEST priority number is served first
+    (FIFO within the same priority). Lets earlier pipeline columns grab agents before later ones."""
+    def __init__(self, value: int):
+        self._value = value
+        self._waiters: list = []  # heap of [priority, seq, future]
+        self._seq = 0
+
+    async def acquire(self, priority: int = 100):
+        if self._value > 0:
+            self._value -= 1
+            return
+        fut = asyncio.get_event_loop().create_future()
+        entry = [priority, self._seq, fut]
+        self._seq += 1
+        heapq.heappush(self._waiters, entry)
+        try:
+            await fut  # release() hands us the slot directly (no value change)
+        except BaseException:
+            entry[2] = None  # tombstone so release() skips this dead waiter
+            if fut.done() and not fut.cancelled():
+                self.release()  # granted just before we were cancelled → pass it on
+            raise
+
+    def release(self):
+        while self._waiters:
+            entry = heapq.heappop(self._waiters)
+            if entry[2] is not None and not entry[2].done():
+                entry[2].set_result(None)  # hand the slot straight to the highest-priority waiter
+                return
+        self._value += 1
+
+
+_batch_sem = _PrioritySemaphore(MAX_CONCURRENT_AGENTS)          # process tier (~310 MB RSS each)
+_batch_sem_api = _PrioritySemaphore(MAX_CONCURRENT_API_AGENTS)  # direct-API tier (~0 RAM)
+_interactive_sem = asyncio.Semaphore(MAX_CONCURRENT_INTERACTIVE)
+
+# Per-topic caps (lazily created): each topic gets its own priority semaphore of size
+# MAX_CONCURRENT_AGENTS_PER_TOPIC, nested INSIDE the global _batch_sem. Priority-based too, so the
+# per-topic queue can't undo the global priority when one topic is the only load.
+_topic_sems: dict[str, _PrioritySemaphore] = {}
+
+# Smaller index = higher priority. Board 1 (inventory) first — it feeds everything.
+# Within board 2 the LATE stages win (outline → artefacts → … → subblocks): finish cards
+# instead of opening new WIP, so the makespan tail block gets slots before fresh work.
+_STAGE_PRIORITY = ("research", "ingest", "cluster", "pair", "clarify", "naming", "filter",
+                   "dedup", "grouping", "gruppierung", "supplement", "outline", "artifact",
+                   "question", "relevance", "level", "facts", "subblock")
+
+
+def _agent_priority(key: str) -> int:
+    for i, tag in enumerate(_STAGE_PRIORITY):
+        if f"-{tag}-" in key or key.endswith(f"-{tag}"):
+            return i
+    return len(_STAGE_PRIORITY)  # unmatched keys (guide board, …) after everything
+
+
+@asynccontextmanager
+async def _batch_gate(scope: str | None, priority: int, api: bool = False):
+    """Per-topic slot FIRST (fair), then the GLOBAL slot by priority (earlier columns win when
+    agents are scarce). Order matters — a waiter holds only its per-topic slot while queueing globally.
+    The per-topic cap is shared across both tiers; only the global cap is tiered (process vs API)."""
+    topic_sem = _topic_sems.setdefault(scope, _PrioritySemaphore(MAX_CONCURRENT_AGENTS_PER_TOPIC)) if scope else None
+    global_sem = _batch_sem_api if api else _batch_sem
+    if topic_sem is not None:
+        await topic_sem.acquire(priority)
+    await global_sem.acquire(priority)
+    try:
+        yield
+    finally:
+        global_sem.release()
+        if topic_sem is not None:
+            topic_sem.release()
+
+# Space OpenCode starts: processes starting simultaneously collide on the internal
+# session DB ("database is locked", exit after <1s). Token bucket instead of a lock
+# held through spawn+sleep: the lock only assigns a start slot, the sleep happens
+# outside — a wave of starts is spaced by OPENCODE_START_DELAY without a global convoy.
+_opencode_start_lock = asyncio.Lock()
+_OPENCODE_START_DELAY = float(os.getenv("OPENCODE_START_DELAY", "0.5"))
+_opencode_next_start = 0.0
+
+
+async def _opencode_slot() -> None:
+    global _opencode_next_start
+    loop = asyncio.get_running_loop()
+    async with _opencode_start_lock:
+        now = loop.time()
+        start_at = max(now, _opencode_next_start)
+        _opencode_next_start = start_at + _OPENCODE_START_DELAY
+    await asyncio.sleep(max(0.0, start_at - now))
+
+# RAM-adaptive admission for opencode spawns (~310 MB RSS each): below RAM_MIN_FREE_PCT
+# free memory new processes wait instead of starting. Gates admission only — running
+# processes are never touched.
+_RAM_GATE_FLOOR = 2                # below this many running: always admit (deadlock guard)
+_RAM_PER_PROC_KB = 350 * 1024      # commit estimate: RSS ramps up slowly after spawn
+_RAM_COMMIT_WINDOW_S = 10.0        # fresh admissions count as already-spent RAM
+_RAM_POLL_S = 2.0
+_opencode_running = 0              # opencode spawns only (stagger path), not claude
+_opencode_recent_starts: list[float] = []  # monotonic timestamps of admissions
+
+
+def _meminfo() -> tuple[int, int] | None:
+    """(MemAvailable_kB, MemTotal_kB) from /proc/meminfo; None → gate fails open (non-Linux)."""
+    try:
+        text = Path("/proc/meminfo").read_text()
+    except OSError:
+        return None
+    m = {k: v for k, v in re.findall(r"^(MemTotal|MemAvailable):\s+(\d+)", text, re.MULTILINE)}
+    if "MemTotal" not in m or "MemAvailable" not in m:
+        return None
+    return int(m["MemAvailable"]), int(m["MemTotal"])
+
+
+async def _ram_gate(agent_key: str) -> bool:
+    """True = start admitted (commit registered), False = scope cancelled while waiting.
+    Check and commit-append happen in the same synchronous block (no await between) —
+    concurrent waiters on the loop cannot double-admit on the same free RAM."""
+    if RAM_MIN_FREE_PCT <= 0:
+        return True
+    waited = False
+    while True:
+        if _scope_cancelled(agent_key):
+            return False
+        mem = _meminfo()
+        if mem is None or _opencode_running < _RAM_GATE_FLOOR:
+            break  # fail open / floor
+        avail_kb, total_kb = mem
+        now = time.monotonic()
+        _opencode_recent_starts[:] = [t for t in _opencode_recent_starts
+                                      if now - t < _RAM_COMMIT_WINDOW_S]
+        if avail_kb - len(_opencode_recent_starts) * _RAM_PER_PROC_KB >= total_kb * RAM_MIN_FREE_PCT / 100:
+            break
+        if not waited:
+            log.info("agent %s: RAM gate waiting (%.0f%% free)", agent_key, avail_kb * 100 / total_kb)
+            waited = True
+        await asyncio.sleep(_RAM_POLL_S)
+    _opencode_recent_starts.append(time.monotonic())
+    return True
+
+_SLIM_CONFIG = Path(__file__).resolve().parent.parent / "dev-ops" / "opencode-slim.json"
 
 # Capability → Claude --allowedTools
 _CLAUDE_TOOLS = {
@@ -24,7 +217,7 @@ _CLAUDE_TOOLS = {
     "none": None,
 }
 
-# Capability → OpenCode-Agent (Tool-Rechte in dev-ops/opencode.json definiert)
+# Capability → OpenCode agent (tool permissions defined in dev-ops/opencode.json)
 _OPENCODE_AGENTS = {
     "full": "full",
     "files": "files",
@@ -33,6 +226,17 @@ _OPENCODE_AGENTS = {
 }
 
 
+def _use_text_api(provider: str, model: str, capabilities: str, on_line) -> bool:
+    """Direct API path only for tool-less, non-streaming MiniMax calls. Model-prefix check
+    instead of cli check: "lokal" (ollama) also runs via opencode. Missing key or
+    CREATOR_TEXT_API=0 (kill switch) falls back to the opencode process path."""
+    return (capabilities == "none" and on_line is None
+            and PROVIDERS[provider]["cli"] == "opencode"
+            and model.split("/", 1)[0] in ("minimax", "minimax-kalt")
+            and bool(os.environ.get("MINIMAX_API_KEY"))
+            and os.getenv("CREATOR_TEXT_API", "1") != "0")
+
+
 def provider_available(provider: str) -> bool:
     cfg = PROVIDERS.get(provider)
     if not cfg:
@@ -51,11 +255,49 @@ def provider_available(provider: str) -> bool:
     return True
 
 
-def kill_process(agent_key_prefix: str) -> None:
-    """Killt alle aktiven Prozesse, deren Key mit dem Prefix beginnt (deckt -plan/-w1… ab)."""
-    for key, process in list(_active_processes.items()):
-        if key.startswith(agent_key_prefix) and process.returncode is None:
+# Availability cache for role routing: the routed target is probed at most once per
+# TTL (check_url providers would otherwise block the loop on every call).
+_avail_cache: dict[str, tuple[float, bool]] = {}
+_AVAIL_TTL = 60.0
+
+
+def _available_cached(provider: str) -> bool:
+    now = time.monotonic()
+    hit = _avail_cache.get(provider)
+    if hit and now - hit[0] < _AVAIL_TTL:
+        return hit[1]
+    ok = provider_available(provider)
+    _avail_cache[provider] = (now, ok)
+    return ok
+
+
+def _kill(process) -> None:
+    """Kill the agent and its child processes via the process group (otherwise the
+    children spawned by the CLI survive, keep the pipes open and block communicate())."""
+    try:
+        os.killpg(os.getpgid(process.pid), signal.SIGKILL)
+    except (ProcessLookupError, PermissionError):
+        try:
             process.kill()
+        except ProcessLookupError:
+            pass
+
+
+def kill_process(agent_key_prefix: str) -> None:
+    """Kill all active processes whose key starts with the prefix (covers -plan/-w1…)."""
+    for key, process in list(_active_processes.items()):
+        if process.returncode is not None:  # clean up dead entries while iterating
+            _active_processes.pop(key, None)
+            _active_started.pop(key, None)
+            continue
+        if key.startswith(agent_key_prefix):
+            log.debug("kill agent %s", key)
+            _kill(process)
+
+
+# Event sink for the pipeline history (injected by main.py lifespan as database.add_event —
+# agents.py stays DB-free). Called fire-and-forget for every finished BATCH agent.
+on_event = None
 
 
 async def run_agent(
@@ -65,80 +307,287 @@ async def run_agent(
     provider: str = DEFAULT_PROVIDER,
     role: str = "fast",
     capabilities: str = "none",
+    lane: str = "batch",
+    scope: str | None = None,
+    on_line=None,
+    label: str = "",
 ) -> tuple[int, str, str]:
+    if os.getenv("CREATOR_FAKE_AGENTS"):  # Sekunden-Smoke: deterministische Antworten statt LLM
+        import fake_agents
+        return await fake_agents.respond(agent_key, prompt, capabilities)
+    if _scope_cancelled(agent_key):  # before queueing: don't even enter the queue
+        return 1, "", "cancelled"
     if provider not in PROVIDERS:
-        return 1, "", f"Unbekannter Provider: {provider}"
-    if shutil.which(PROVIDERS[provider]["cli"]) is None:
-        return 1, "", f"CLI '{PROVIDERS[provider]['cli']}' nicht installiert (Provider: {provider})"
-    if PROVIDERS[provider]["cli"] == "opencode":
-        return await _run_opencode(agent_key, prompt, timeout, provider, role, capabilities)
-    return await _run_claude_cli(agent_key, prompt, timeout, role, capabilities)
+        return 1, "", f"Unknown provider: {provider}"
+    run_provider = provider
+    provider, model = resolve_role(run_provider, role)
+    if provider != run_provider and not _available_cached(provider):
+        provider, model = run_provider, PROVIDERS[run_provider].get(role, "")
+    if not model:
+        return 1, "", f"No model for role '{role}' (provider: {provider})"
+    use_api = _use_text_api(provider, model, capabilities, on_line)
+    if not use_api and shutil.which(PROVIDERS[provider]["cli"]) is None:
+        return 1, "", f"CLI '{PROVIDERS[provider]['cli']}' not installed (provider: {provider})"
+    queued = time.monotonic()
+    gate = _interactive_sem if lane == "interactive" else _batch_gate(scope, _agent_priority(agent_key), api=use_api)
+    async with gate:
+        if _scope_cancelled(agent_key):  # after the acquire: cancelled in the queue → no spawn
+            return 1, "", "cancelled"
+        wait_ms = int((time.monotonic() - queued) * 1000)
+        start = time.monotonic()
+        status = "error"
+        rc = None
+        err_tail = ""
+        api_tokens = None
+        try:
+            log.info("agent %s: %s %s (role %s)", agent_key, provider, model, role)
+            if use_api:
+                rc_, out_, err_, api_tokens = await _run_text_api(agent_key, prompt, timeout, model, label=label)
+                res = (rc_, out_, err_)
+            elif PROVIDERS[provider]["cli"] == "opencode":
+                res = await _run_opencode(agent_key, prompt, timeout, provider, model, capabilities, on_line=on_line, label=label)
+            else:
+                res = await _run_claude_cli(agent_key, prompt, timeout, model, capabilities, label=label)
+            rc = res[0]
+            status = "ok" if rc == 0 else ("killed" if rc is not None and rc < 0 else "error")
+            if rc not in (0, None) and rc >= 0:
+                err_tail = (res[2] or res[1] or "").strip()[-300:]  # diagnosis: rc=1 without stderr is opaque
+            return res
+        except asyncio.TimeoutError:
+            status = "timeout"
+            raise
+        except asyncio.CancelledError:
+            status = "cancelled"
+            raise
+        finally:
+            if on_event is not None and scope is not None:  # batch pipeline only, never fatal
+                try:
+                    meta = {"provider": provider, "model": model, "role": role, "rc": rc}
+                    if err_tail:
+                        meta["stderr"] = err_tail
+                    if api_tokens:  # direct-API path: usage from the response, even on rc!=0
+                        meta["tokens"] = api_tokens
+                    elif PROVIDERS[provider]["cli"] == "opencode":  # token accounting per agent
+                        if (tok := await asyncio.to_thread(_session_tokens, agent_key)):
+                            meta["tokens"] = tok
+                    await on_event(topic=scope, kind="agent", key=agent_key, label=label,
+                                   status=status, dur_ms=int((time.monotonic() - start) * 1000),
+                                   wait_ms=wait_ms, meta=meta)
+                except Exception:
+                    log.debug("on_event failed", exc_info=True)
 
 
-async def _communicate(agent_key: str, cmd: list[str], stdin_data: bytes | None, timeout: int) -> tuple[int, str, str]:
-    process = await asyncio.create_subprocess_exec(
-        *cmd,
-        stdin=asyncio.subprocess.PIPE if stdin_data is not None else asyncio.subprocess.DEVNULL,
-        stdout=asyncio.subprocess.PIPE,
-        stderr=asyncio.subprocess.PIPE,
-    )
-    _active_processes[agent_key] = process
+async def _communicate(agent_key: str, cmd: list[str], stdin_data: bytes | None, timeout: int, stagger: bool = False, on_line=None, label: str = "", env: dict | None = None) -> tuple[int, str, str]:
+    start = time.monotonic()
+
+    async def spawn():
+        return await asyncio.create_subprocess_exec(
+            *cmd,
+            stdin=asyncio.subprocess.PIPE if stdin_data is not None else asyncio.subprocess.DEVNULL,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            start_new_session=True,  # own process group → killpg also kills child processes
+            env=env,
+        )
+
+    global _opencode_running
+    if stagger:
+        if not await _ram_gate(agent_key):
+            return 1, "", "cancelled"     # like the cancelled path in run_agent
+        await _opencode_slot()  # gate BEFORE the start slot: an admission wave still gets spaced
+    process = await spawn()
+    if stagger:
+        _opencode_running += 1
+    # Collision-safe tracking: identical keys (e.g. same chunk label from parallel cards)
+    # get a ~n suffix — prefix-based kill/cancel still matches, nothing becomes an orphan.
+    track_key = agent_key
+    n = 2
+    while track_key in _active_processes:
+        track_key = f"{agent_key}~{n}"
+        n += 1
+    _active_processes[track_key] = process
+    _active_started[track_key] = time.time()
+    _active_labels[track_key] = label
     try:
         try:
-            stdout, stderr = await asyncio.wait_for(
-                process.communicate(input=stdin_data),
-                timeout=timeout,
-            )
+            if on_line is not None:
+                # Streaming path: read stdout line by line, hand each raw line to on_line LIVE.
+                out_chunks: list[str] = []
+
+                async def _pump():
+                    async for raw in process.stdout:
+                        s = raw.decode("utf-8", errors="replace")
+                        out_chunks.append(s)
+                        try:
+                            on_line(s)
+                        except Exception:
+                            log.debug("on_line callback failed", exc_info=True)
+                await asyncio.wait_for(_pump(), timeout=timeout)
+                await process.wait()
+                stderr_b = await process.stderr.read()
+                stdout, stderr = "".join(out_chunks).encode("utf-8"), stderr_b
+            else:
+                stdout, stderr = await asyncio.wait_for(
+                    process.communicate(input=stdin_data),
+                    timeout=timeout,
+                )
         except asyncio.TimeoutError:
-            process.kill()
+            _kill(process)
             try:
                 await asyncio.wait_for(process.wait(), timeout=5)
             except asyncio.TimeoutError:
                 pass
+            log.info("agent %s: timeout after %ds", agent_key, timeout)
             raise
+        log.info(
+            "agent %s: exit %s after %.1fs (%d bytes stdout)",
+            agent_key, process.returncode, time.monotonic() - start, len(stdout),
+        )
         return process.returncode, stdout.decode("utf-8", errors="replace"), stderr.decode("utf-8", errors="replace")
     finally:
-        _active_processes.pop(agent_key, None)
+        if stagger:
+            _opencode_running -= 1
+        # Pop only on identity: a slot restart under the same key must not evict
+        # the NEW process from tracking.
+        if _active_processes.get(track_key) is process:
+            del _active_processes[track_key]
+            _active_started.pop(track_key, None)
+            _active_labels.pop(track_key, None)
 
 
-async def _run_claude_cli(agent_key: str, prompt: str, timeout: int, role: str, capabilities: str) -> tuple[int, str, str]:
+async def _run_claude_cli(agent_key: str, prompt: str, timeout: int, model: str, capabilities: str, label: str = "") -> tuple[int, str, str]:
     cfg = PROVIDERS["claude"]
-    cmd = [cfg["cli"], "-p", "--model", cfg[role]]
+    cmd = [cfg["cli"], "-p", "--model", model]
     tools = _CLAUDE_TOOLS.get(capabilities)
     if tools:
         cmd += ["--allowedTools", tools]
     cmd += ["--dangerously-skip-permissions"]
-    return await _communicate(agent_key, cmd, prompt.encode("utf-8"), timeout)
+    return await _communicate(agent_key, cmd, prompt.encode("utf-8"), timeout, label=label)
 
 
-async def _run_opencode(agent_key: str, prompt: str, timeout: int, provider: str, role: str, capabilities: str) -> tuple[int, str, str]:
+_OPENCODE_DB = Path.home() / ".local" / "share" / "opencode" / "opencode.db"
+
+
+def _session_tokens(agent_key: str) -> dict | None:
+    """Token counters of the newest OpenCode session titled `agent_key` (set via run --title).
+    Best-effort read-only lookup — None when DB/row is missing; never fails the agent.
+    Timeouts count too: their sessions consumed tokens, that waste should be visible."""
+    try:
+        con = sqlite3.connect(f"file:{_OPENCODE_DB}?mode=ro", uri=True, timeout=1)
+        try:
+            row = con.execute(
+                "SELECT tokens_input, tokens_output, tokens_reasoning,"
+                " tokens_cache_read, tokens_cache_write"
+                " FROM session WHERE title=? ORDER BY time_created DESC LIMIT 1",
+                (agent_key,)).fetchone()
+        finally:
+            con.close()
+    except Exception:
+        return None
+    if row is None:
+        return None
+    keys = ("input", "output", "reasoning", "cache_read", "cache_write")
+    return {k: int(v or 0) for k, v in zip(keys, row)}
+
+
+async def _run_opencode(agent_key: str, prompt: str, timeout: int, provider: str, model: str, capabilities: str, on_line=None, label: str = "") -> tuple[int, str, str]:
     cfg = PROVIDERS[provider]
-    # Prompt über Tempdatei statt argv (ARG_MAX-Schutz bei großen Projekt-Prompts)
+    # Prompt via temp file instead of argv (ARG_MAX protection for large project prompts)
     with tempfile.NamedTemporaryFile("w", suffix=".md", delete=False, encoding="utf-8", dir=tempfile.gettempdir()) as f:
         f.write(prompt)
         prompt_path = Path(f.name)
-    # Positional-Message MUSS vor -f stehen: -f ist ein Array-Flag und
-    # frisst sonst den Text als zweiten Dateinamen ("File not found").
+    # The positional message MUST come before -f: -f is an array flag and
+    # would otherwise eat the text as a second file name ("File not found").
     cmd = [
         cfg["cli"], "run",
         "Folge exakt den Anweisungen in der angehängten Datei. Sie sind der vollständige Auftrag.",
-        "-m", cfg[role],
+        "-m", model,
         "--agent", _OPENCODE_AGENTS.get(capabilities, "text"),
         "--dangerously-skip-permissions",
+        "--title", agent_key,  # token accounting: joins the OpenCode session to our event
         "-f", str(prompt_path),
     ]
+    if on_line is not None:
+        cmd += ["--format", "json"]  # raw JSON events → parsed live by on_line
+    env = None
+    if capabilities != "full":
+        # Batch agents (files/readonly/text) never use the web MCPs, but opencode starts
+        # every configured MCP server PER PROCESS (~3 procs / ~300 MB each). Point them
+        # at the mcp-free config copy; only `full` (research/supplement) keeps the servers.
+        env = {**os.environ, "OPENCODE_CONFIG": str(_SLIM_CONFIG)}
     try:
-        rc, stdout, stderr = await _communicate(agent_key, cmd, None, timeout)
-        return rc, _clean_opencode_output(stdout), stderr
+        rc, stdout, stderr = await _communicate(agent_key, cmd, None, timeout, stagger=True, on_line=on_line, label=label, env=env)
+        return rc, (stdout if on_line is not None else _clean_opencode_output(stdout)), stderr
     finally:
         prompt_path.unlink(missing_ok=True)
 
 
+# Direct text-API path (MiniMax, Anthropic Messages format): saves the ~310 MB RSS opencode
+# process for tool-less calls. The native "minimax" and "minimax-kalt" opencode providers both
+# resolve to this base URL — only the per-model options differ. Options source of truth:
+# dev-ops/opencode.json (+ -slim); keep in sync on changes there.
+_API_URL = "https://api.minimax.io/anthropic/v1/messages"
+_API_VERSION = "2023-06-01"
+_API_MAX_TOKENS = 32_000  # required Messages field; generate calls are long
+_API_MODEL_OPTS = {       # prefix "minimax" (native) → endpoint defaults (no entry)
+    "minimax-kalt/MiniMax-M3": {"temperature": 0.2, "thinking": {"type": "disabled"}},
+    "minimax-kalt/MiniMax-M2.7-highspeed": {"temperature": 0.3},
+}
+
+
+async def _run_text_api(agent_key: str, prompt: str, timeout: int, model: str,
+                        label: str = "") -> tuple[int, str, str, dict | None]:
+    """→ (rc, text, err, tokens). Tokens come straight from the response usage (same key set
+    as _session_tokens) and are returned even on rc!=0 — waste stays visible."""
+    body = {
+        "model": model.split("/", 1)[1],  # without the opencode provider prefix
+        "max_tokens": _API_MAX_TOKENS,
+        "messages": [{"role": "user", "content": prompt}],
+        **_API_MODEL_OPTS.get(model, {}),
+    }
+    headers = {"x-api-key": os.environ.get("MINIMAX_API_KEY", ""), "anthropic-version": _API_VERSION}
+    track_key = agent_key
+    n = 2
+    while track_key in _active_api:
+        track_key = f"{agent_key}~{n}"
+        n += 1
+    _active_api.add(track_key)
+    _active_started[track_key] = time.time()
+    _active_labels[track_key] = label
+    start = time.monotonic()
+    try:
+        async with httpx.AsyncClient(timeout=httpx.Timeout(timeout, connect=30)) as client:
+            resp = await asyncio.wait_for(  # belt: hard wall-clock cap like the process path
+                client.post(_API_URL, json=body, headers=headers), timeout=timeout)
+    except httpx.TimeoutException:
+        raise asyncio.TimeoutError  # contract: run_agent/_race handle TimeoutError
+    except httpx.HTTPError as e:
+        return 1, "", f"{type(e).__name__}: {e}", None
+    finally:
+        _active_api.discard(track_key)
+        _active_started.pop(track_key, None)
+        _active_labels.pop(track_key, None)
+        log.info("agent %s: api done after %.1fs", agent_key, time.monotonic() - start)
+    if resp.status_code != 200:
+        return 1, "", f"HTTP {resp.status_code}: {resp.text[:300]}", None
+    data = resp.json()
+    # Only text blocks count — thinking blocks (native route) are skipped.
+    text = "".join(b.get("text", "") for b in data.get("content", []) if b.get("type") == "text")
+    u = data.get("usage") or {}
+    tokens = {"input": int(u.get("input_tokens") or 0), "output": int(u.get("output_tokens") or 0),
+              "reasoning": 0, "cache_read": int(u.get("cache_read_input_tokens") or 0),
+              "cache_write": int(u.get("cache_creation_input_tokens") or 0)}
+    if not text.strip():
+        return 1, "", f"empty response (stop_reason={data.get('stop_reason')})", tokens
+    err = "stop_reason=max_tokens (truncated)" if data.get("stop_reason") == "max_tokens" else ""
+    return 0, text, err, tokens
+
+
 _ANSI_RE = re.compile(r"\x1b\[[0-9;]*m")
 
 
 def _clean_opencode_output(text: str) -> str:
-    """Entfernt ANSI-Codes und den führenden Banner ("> agent · modell")."""
+    """Strip ANSI codes and the leading banner ("> agent · model")."""
     text = _ANSI_RE.sub("", text)
     lines = text.splitlines()
     while lines and (not lines[0].strip() or lines[0].lstrip().startswith(">")):

backend/block_calls.py

@@ -0,0 +1,696 @@
+"""Board 2, verschmolzene Call-Struktur: 3 Bausteine pro Block statt ~20 serieller Segmente.
+
+Die alte Stage-Treppe (Finder-Runden → Facts find/erg/check → Konsolidierung → Lücken →
+Nachfass → Levels → Relevanz → Fragen → Kritik → Flashcards → Beispiele → Check) kostete
+pro Block 35–55 Calls und ~14 min Wandzeit — bei p50 20–50 s pro Call zählt NUR die Zahl
+der seriellen Segmente. Hier: Generate(∥2) → Verify(∥2, + Fix-Tail) → Artefakte(Gen+Check)
+= 4–5 Segmente, 6–9 Calls. Unabhängigkeit bleibt: Generatoren und Prüfer sind getrennte
+Agenten, Konsens (≥2 unabhängige Nennungen) und Einstimmigkeits-Faltung wie zuvor.
+
+Output-Kontrakt unverändert (finalize/QA/Guide/Übungssystem lesen dieselben Strukturen):
+raw {block: [sub]}, facts {block: {sub_norm: 5-Felder}}, sidecar {block: [{title, level,
+relevance, facts}]}, pattern {block: [{subblock, question}]}, artefacts {flashcard/example}."""
+
+import asyncio
+import hashlib
+import json
+import logging
+
+import database as db
+import embedding
+from blocks import (
+    _SOURCE_TEMPLATE, _FACTS_FIELDS, _agreed_cliques, _cited_evidence, _dedup_subblocks,
+    _evidence_pack, _facts_lines, _facts_union, _luecken_schnitt, _neg_set, _pairs_of,
+    _sink_json, _sub_tokens, _subs_hash, _variant_clusters, load_source, material_folder,
+    source_folder,
+)
+from config import (ART_SPLIT_SUBS, EMBEDDING_AKTIV, GEN_PANEL, SEED_COVER_COS,
+                    VERIFY_PANEL)
+from jsonio import read_json_file as _json_file
+from pipeline import FAILED, GenContext, _extra, _log, _prompt, _race, _timeout, run_single_slot
+from textkit import _norm_title, clean_title
+
+log = logging.getLogger("creator.block_calls")
+
+_STUFEN = ("beginner", "advanced", "expert")
+_RELEVANZ = ("relevant", "peripheral")
+
+
+def _h8(*parts: str) -> str:
+    return hashlib.md5("|".join(parts).encode("utf-8")).hexdigest()[:8]
+
+
+# ── Schemas ─────────────────────────────────────────────────────────────────────────
+
+def _gen_schema(data) -> list[dict] | None:
+    """{"subs": [{title, level, relevance, …facts}]} → normalisierte Liste · sonst None.
+    Feld-Normalisierung wie _facts_schema; ungültiges level/relevance fällt auf ""
+    (die Stimme entfällt im Vote, der Sub bleibt)."""
+    if not isinstance(data, dict) or not isinstance(data.get("subs"), list):
+        return None
+    out = []
+    for e in data["subs"]:
+        if not isinstance(e, dict) or not str(e.get("title", "")).strip():
+            continue
+        bf = [{"text": t, "source": str(f.get("source", "")).strip()}
+              for f in (e.get("cited_facts") or []) if isinstance(f, dict) and (t := str(f.get("text", "")).strip())]
+        lv = str(e.get("level", "")).strip().casefold()
+        rv = str(e.get("relevance", "")).strip().casefold()
+        out.append({
+            "title": clean_title(str(e["title"]).strip()),
+            "level": lv if lv in _STUFEN else "",
+            "relevance": rv if rv in _RELEVANZ else "",
+            "key_points": [k for x in (e.get("key_points") or []) if (k := str(x).strip())],
+            "prerequisites": str(e.get("prerequisites", "")).strip(),
+            "hurdles": str(e.get("hurdles", "")).strip(),
+            "cited_facts": bf,
+            "example_idea": str(e.get("example_idea", "")).strip(),
+        })
+    return out or None
+
+
+def _vid(x, n: int) -> int | None:
+    """Prüfer-Nummer → int in 1..n, else None (bools sind keine ids)."""
+    if isinstance(x, bool):
+        return None
+    if isinstance(x, str) and x.isdigit():
+        x = int(x)
+    return x if isinstance(x, int) and 1 <= x <= n else None
+
+
+def _verify_schema(data, n: int) -> dict | None:
+    """Prüfer-Output → normalisiertes Verdikt · None wenn kaputt. Alle Felder optional
+    außer der Grundform (dict) — ein leeres Verdikt {"gruppen": []} heißt „alles ok"."""
+    if not isinstance(data, dict):
+        return None
+    pflicht = ("gruppen", "kataloge", "fremd", "luecken", "uebernehmen", "facts_probleme",
+               "levels", "relevanz")
+    if not any(k in data for k in pflicht):
+        return None
+
+    def _ids(lst):
+        return sorted({i for x in (lst or []) if (i := _vid(x, n)) is not None})
+
+    gruppen = []
+    for g in data.get("gruppen") or []:
+        if not isinstance(g, dict):
+            continue
+        haupt = _vid(g.get("haupt"), n)
+        ids = _ids(([haupt] if haupt else []) + list(g.get("weitere") or []))
+        if len(ids) >= 2:
+            gruppen.append({"haupt": haupt if haupt in ids else None, "ids": ids})
+    kataloge = []
+    for k in data.get("kataloge") or []:
+        if not isinstance(k, dict):
+            continue
+        ids = _ids(k.get("mitglieder"))
+        titel = str(k.get("titel") or "").strip()
+        if len(ids) >= 2 and titel:
+            kataloge.append({"titel": titel, "ids": ids})
+    uebernehmen = {}
+    for k, v in (data.get("uebernehmen") or {}).items() if isinstance(data.get("uebernehmen"), dict) else []:
+        if (i := _vid(k, n)) is not None:
+            uebernehmen[i] = str(v).strip().casefold()
+    probleme = []
+    for p in data.get("facts_probleme") or []:
+        if isinstance(p, dict) and (i := _vid(p.get("nr"), n)) is not None:
+            probleme.append({"nr": i, "discard": bool(p.get("discard")),
+                             "hinweis": str(p.get("hinweis", "")).strip()})
+    def _enum_map(key, allowed):
+        out = {}
+        raw = data.get(key)
+        for k, v in (raw.items() if isinstance(raw, dict) else []):
+            if (i := _vid(k, n)) is not None and str(v).strip().casefold() in allowed:
+                out[i] = str(v).strip().casefold()
+        return out
+    return {"gruppen": gruppen, "kataloge": kataloge, "fremd": set(_ids(data.get("fremd"))),
+            "luecken": [s.strip() for s in data.get("luecken") or [] if isinstance(s, str) and s.strip()],
+            "uebernehmen": uebernehmen, "facts_probleme": probleme,
+            "levels": _enum_map("levels", _STUFEN), "relevanz": _enum_map("relevanz", _RELEVANZ)}
+
+
+def _pattern_liste(lst) -> list[dict]:
+    out = []
+    for e in lst or []:
+        if isinstance(e, dict):
+            blk, sub, q = (str(e.get(k, "")).strip() for k in ("block", "subblock", "question"))
+            if blk and sub and q:
+                out.append({"block": blk, "subblock": sub, "question": q})
+    return out
+
+
+def _art_gen_schema(data) -> dict | None:
+    """{"pattern": […], "cards": […], "examples": […]} → normalisiert · None wenn kaputt.
+    pattern ist Pflicht (Leitner hängt an Fragen), cards/examples best-effort."""
+    if not isinstance(data, dict):
+        return None
+    pattern = _pattern_liste(data.get("pattern"))
+    if not pattern:
+        return None
+    cards = []
+    for e in data.get("cards") or []:
+        if isinstance(e, dict):
+            blk, sub, q, a = (str(e.get(k, "")).strip() for k in ("block", "subblock", "question", "answer"))
+            if blk and sub and q and a:
+                cards.append({"block": blk, "subblock": sub, "question": q, "answer": a})
+    examples = []
+    for e in data.get("examples") or []:
+        if isinstance(e, dict):
+            blk, sub, pr, res = (str(e.get(k, "")).strip() for k in ("block", "subblock", "problem", "result"))
+            steps = [s for x in (e.get("steps") or []) if (s := str(x).strip())]
+            if blk and sub and pr and steps:
+                examples.append({"block": blk, "subblock": sub, "problem": pr, "steps": steps, "result": res})
+    return {"pattern": pattern, "cards": cards, "examples": examples}
+
+
+def _art_check_schema(data) -> dict | None:
+    """{"ok": true} → leeres Verdikt · sonst pattern (bereinigt) + pattern_ergaenzt +
+    examples_probleme (1-basierte Indizes)."""
+    if not isinstance(data, dict):
+        return None
+    if data.get("ok") is True:
+        return {"pattern": [], "pattern_ergaenzt": [], "examples_probleme": set()}
+    if not any(k in data for k in ("pattern", "pattern_ergaenzt", "examples_probleme")):
+        return None
+    probleme = set()
+    for p in data.get("examples_probleme") or []:
+        i = p.get("index") if isinstance(p, dict) else p
+        if isinstance(i, str) and i.isdigit():
+            i = int(i)
+        if isinstance(i, int) and not isinstance(i, bool) and i >= 1:
+            probleme.add(i)
+    return {"pattern": _pattern_liste(data.get("pattern")),
+            "pattern_ergaenzt": _pattern_liste(data.get("pattern_ergaenzt")),
+            "examples_probleme": probleme}
+
+
+# ── Gemeinsames ─────────────────────────────────────────────────────────────────────
+
+def _inline_source(topic: str, sources: list[str] | None, queries: list[str]) -> tuple[str, str]:
+    """→ (source-Slot, capabilities). Korpus-Auszüge inline (uni/projekt/link oder
+    thema-Research-Material); ohne Treffer fail-open auf die alte Selbst-Recherche."""
+    mat = material_folder(topic)
+    ev = _evidence_pack(mat, sources, queries) if mat else ""
+    if ev:
+        return _prompt("Blocks-Source-Inline", excerpts=ev), "none"
+    _type = load_source(topic).get("type", "thema")
+    folder = source_folder(topic)
+    if _type in _SOURCE_TEMPLATE:
+        return _prompt(_SOURCE_TEMPLATE[_type], project=folder), ("files" if folder else "full")
+    return _prompt("Blocks-Source-Thema", topic=topic), "full"
+
+
+async def _sims_of(titles: list[str]):
+    """Ähnlichkeitsmatrix fürs Variant-Clustering; ohne Modell exakte Norm-Gleichheit."""
+    if EMBEDDING_AKTIV and await asyncio.to_thread(embedding.available):
+        sims = await asyncio.to_thread(embedding.embed_sims, titles)
+        if sims is not None:
+            return sims
+    norms = [_norm_title(t) for t in titles]
+    return [[1.0 if norms[i] == norms[j] else 0.0 for j in range(len(titles))]
+            for i in range(len(titles))]
+
+
+def _fk_of(e: dict) -> dict:
+    return {k: e.get(k) for k in _FACTS_FIELDS}
+
+
+# ── Generate ────────────────────────────────────────────────────────────────────────
+
+async def _generate_block(ctx: GenContext, files: dict, title: str, description: str,
+                          instructions: str = "", ns: str = "", lbl: str = "",
+                          sources: list[str] | None = None,
+                          seeds: list[str] | None = None, melde=None) -> dict | None:
+    """GEN_PANEL unabhängige Generatoren liefern je Subs+Facts+Level/Relevanz in EINEM Call;
+    Konsens im Code (Variant-Cluster über beide Ausgaben, ≥2 unabhängige Generatoren =
+    consensus). Einzelnennungen und ungedeckte Seeds werden „unsicher" — der Prüfer
+    entscheidet mit Material (ersetzt Sättigungsrunden + Clarify-Panel). Degraded: liefert
+    nur EIN Generator, wird alles unsicher. → {raw, facts, unsicher, votes} | None."""
+    topic, provider = ctx.topic, ctx.provider
+    work_dir = files["arbeit"]
+    bnorm = _norm_title(title)
+    source, caps = await asyncio.to_thread(
+        _inline_source, topic, sources, [f"{title} {description}"])
+    seeds_txt = ""
+    if seeds:
+        seeds_txt = ("\nAlready identified sub-point CANDIDATES of this block (verify against "
+                     "the material; if backed AND not already covered by another entry, include "
+                     "them — rephrased as a standalone statement):\n"
+                     + "\n".join(f"- {s}" for s in dict.fromkeys(seeds) if s) + "\n")
+    if melde:
+        melde("Generate")
+    h = _h8(title, description, "gen")
+    paths = [work_dir / f"gen-{h}-g{g}.json" for g in range(1, GEN_PANEL + 1)]
+    prompt = _prompt("Subblock-Generate", topic=topic,
+                     block=f"{title} — {description}" if description else title,
+                     source=source, seeds=seeds_txt, extra=_extra(instructions))
+    pending = [(g, p) for g, p in enumerate(paths, 1) if _gen_schema(_json_file(p)) is None]
+    if pending:
+        slots = [{
+            "key": f"blocks-{topic}-{ns}sb-gen-{h}-g{g}",
+            "prompt": prompt, "role": "quick", "capabilities": caps,
+            "payload": (lambda result, p=p: _sink_json(result, p, _gen_schema)),
+        } for g, p in pending]
+        await _race(topic, f"{lbl}Generate", slots, len(slots),
+                    _timeout("generate", 10), provider, cancelled=ctx.is_cancelled)
+    if ctx.is_cancelled():
+        return None
+    outs = [o for p in paths if (o := _gen_schema(_json_file(p))) is not None]
+    if not outs:
+        return None
+    if len(outs) < len(paths):
+        _log(topic, f"Generate {title}: nur {len(outs)}/{len(paths)} Generatoren — alles unsicher, Prüfer entscheidet")
+
+    # Mentions in die DB (QA-Beleg-Signal), Karten-Re-Spawn darf nicht kumulieren
+    await db.delete_subblocks(topic, bnorm)
+    alle: list[tuple[dict, int]] = []  # (sub-Eintrag, Generator-Index)
+    for gi, subs in enumerate(outs):
+        seen: set[str] = set()
+        for e in subs:
+            sn = _norm_title(e["title"])
+            if not sn or sn in seen:
+                continue
+            seen.add(sn)
+            alle.append((e, gi))
+            await db.upsert_subblock(topic, bnorm, sn, title, e["title"])
+    if not alle:
+        return {"raw": {title: []}, "facts": {title: {}}, "unsicher": [], "votes": {}}
+
+    sims = await _sims_of([e["title"] for e, _ in alle])
+    raw: list[str] = []
+    facts: dict[str, dict] = {}
+    votes: dict[str, dict] = {}
+    unsicher: list[dict] = []
+    for c in _variant_clusters([e["title"] for e, _ in alle], [1] * len(alle), sims):
+        rep = alle[c["rep"]][0]
+        sn = _norm_title(rep["title"])
+        fk = _fk_of(rep)
+        for m in c["members"]:
+            if m != c["rep"]:
+                _facts_union(fk, _fk_of(alle[m][0]))
+                await db.set_subblock_fields(topic, bnorm, _norm_title(alle[m][0]["title"]),
+                                             status="variant")
+        votes[sn] = {"level": [v for m in c["members"] if (v := alle[m][0]["level"])],
+                     "relevance": [v for m in c["members"] if (v := alle[m][0]["relevance"])]}
+        gens = {alle[m][1] for m in c["members"]}
+        # degraded (1 Generator): kein Konsens möglich — alles unsicher, Prüfer entscheidet
+        if len(gens) >= 2 and len(outs) >= 2:
+            raw.append(rep["title"])
+            facts[sn] = fk
+            await db.set_subblock_fields(topic, bnorm, sn, status="consensus")
+        else:
+            unsicher.append({**rep, **fk})
+
+    # Seed-Garantie: ungedeckte Seeds gehen als unsicher zum Prüfer (der ist das Beleg-Gate)
+    for seed in dict.fromkeys(s for s in (seeds or []) if s):
+        st = _sub_tokens(seed)
+        gedeckt = [t for t in raw + [u["title"] for u in unsicher]]
+        if not st or any(st <= _sub_tokens(t) for t in gedeckt):
+            continue
+        if gedeckt and EMBEDDING_AKTIV and await asyncio.to_thread(embedding.available):
+            sims = await asyncio.to_thread(embedding.embed_sims, [seed] + gedeckt)
+            if sims is not None and max(float(sims[0][j]) for j in range(1, len(gedeckt) + 1)) >= SEED_COVER_COS:
+                continue
+        unsicher.append({"title": seed, "level": "", "relevance": "", "key_points": [],
+                         "prerequisites": "", "hurdles": "", "cited_facts": [], "example_idea": ""})
+
+    raw_map = {title: raw}
+    await _dedup_subblocks(topic, raw_map)  # deterministischer Near-Dup-Filter
+    facts = {sn: fk for sn, fk in facts.items()
+             if sn in {_norm_title(s) for s in raw_map[title]}}
+    return {"raw": raw_map, "facts": {title: facts}, "unsicher": unsicher, "votes": votes}
+
+
+# ── Verify (+ Fix-Tail) ─────────────────────────────────────────────────────────────
+
+def _default_vote(stimmen: list[str], default: str) -> str:
+    """Mehrheit über die Stimmen (Gen-Vorschläge + implizite/explizite Prüfer-Stimmen);
+    Patt oder leer → default."""
+    counter: dict[str, int] = {}
+    for s in stimmen:
+        if s:
+            counter[s] = counter.get(s, 0) + 1
+    best = max(counter.values(), default=0)
+    winners = [s for s, v in counter.items() if v == best]
+    return winners[0] if len(winners) == 1 and best else default
+
+
+async def _verify_block(ctx: GenContext, files: dict, title: str, gen: dict, q: dict,
+                        instructions: str = "", ns: str = "", lbl: str = "",
+                        sources: list[str] | None = None, melde=None) -> dict | None:
+    """VERIFY_PANEL unabhängige Prüfer auditieren den Block in EINEM Call (MECE-Faltung,
+    Fremd, Lücken, Unsicher-Übernahme, Facts-Korrektheit, Level/Relevanz). Auswertung mit
+    Schnittmengen-Semantik pro Befundklasse (Faltung/Fremd/Übernahme einstimmig, Discard
+    2/2, Korrektur ≥1 Stimme); Fix-Tail ist EIN Call für Korrekturen + belegte Lücken.
+    → {raw, facts, sidecar} | None (nur bei Cancel)."""
+    topic = ctx.topic
+    work_dir = files["arbeit"]
+    bnorm = _norm_title(title)
+    subs = list(gen["raw"].get(title) or [])
+    bfacts: dict[str, dict] = dict(gen["facts"].get(title) or {})
+    unsicher: list[dict] = list(gen.get("unsicher") or [])
+    votes: dict[str, dict] = gen.get("votes") or {}
+    nummern = subs + [u["title"] for u in unsicher]  # 1-basiert: consensus, dann unsicher
+    n = len(nummern)
+
+    def _kp(t: str) -> list:
+        fk = bfacts.get(_norm_title(t)) or next(
+            (u for u in unsicher if u["title"] == t), {})
+        return (fk.get("key_points") or [])[:3]
+
+    if melde:
+        melde("Verify")
+    verdicts: list[dict] = []
+    if n:
+        zeilen = "\n".join(f"{k}. {t}" + "".join(f"\n   - {p}" for p in _kp(t))
+                           for k, t in enumerate(nummern, 1))
+        u_txt = ""
+        if unsicher:
+            erste = len(subs) + 1
+            u_txt = (f"\nUNSICHER — entries {erste}–{n} were named by only ONE generator "
+                     "(or are seed candidates). Judge their adoption under `uebernehmen`.\n")
+        cites = [bf.get("source", "") for fk in bfacts.values() for bf in fk.get("cited_facts", [])]
+        mat = material_folder(topic)
+        ev = _cited_evidence(mat, sources, cites, [title] + nummern) if mat else ""
+        if ev:
+            source = _prompt("Blocks-Source-Inline", excerpts=ev)
+        else:
+            source, _caps = await asyncio.to_thread(_inline_source, topic, sources, [title] + nummern)
+        sh = _subs_hash({title: nummern})
+        pfade = {j: work_dir / f"verify-{sh}-j{j}.json" for j in (*range(1, VERIFY_PANEL + 1), "E")}
+
+        async def _judge(j):
+            if _verify_schema(_json_file(pfade[j]), n) is not None:
+                return  # resume
+            status, _v = await run_single_slot(
+                ctx, f"{lbl}Verify j{j}", key=f"blocks-{topic}-{ns}sb-verify-{sh}-j{j}",
+                prompt=_prompt("Subblock-Verify", topic=topic, block=title, subs=zeilen,
+                               unsicher=u_txt, source=source, extra=_extra(instructions)),
+                role="judge", capabilities="none",
+                payload=lambda result, p=pfade[j]: _sink_json(result, p, lambda d: _verify_schema(d, n)),
+                timeout=_timeout("verify", n))
+            if status == FAILED:
+                _log(topic, f"Verify {title} j{j} ohne Ergebnis — fail-open")
+
+        await asyncio.gather(*[_judge(j) for j in range(1, VERIFY_PANEL + 1)])
+        if ctx.is_cancelled():
+            return None
+        verdicts = [v for j in range(1, VERIFY_PANEL + 1)
+                    if (v := _verify_schema(_json_file(pfade[j]), n)) is not None]
+        if len(verdicts) == 1 and VERIFY_PANEL >= 2:  # Ersatz-Richter statt fail-open
+            await _judge("E")
+            if ctx.is_cancelled():
+                return None
+            verdicts = [v for j in (*range(1, VERIFY_PANEL + 1), "E")
+                        if (v := _verify_schema(_json_file(pfade[j]), n)) is not None][:2]
+
+    einstimmig = len(verdicts) >= 2
+    if n and not einstimmig:
+        _log(topic, f"Verify {title}: nur {len(verdicts)}/2 Prüfer — fail-open, unsicher verworfen")
+    negs = [_neg_set(t) for t in nummern]
+    gone: set[int] = set()
+    keep = list(subs)
+    korrekturen: list[dict] = []   # {titel, hinweis}
+    luecken: list[str] = []
+
+    def _titel(k: int) -> str:
+        return nummern[k - 1]
+
+    async def _fold(k: int, wf: dict | None):
+        t = _titel(k)
+        lf = bfacts.pop(_norm_title(t), None) or {}
+        if wf is not None:
+            _facts_union(wf, lf)
+        await db.set_subblock_fields(topic, bnorm, _norm_title(t), status="variant")
+        if t in keep:
+            keep.remove(t)
+        gone.add(k)
+
+    if einstimmig:
+        v1, v2 = verdicts[0], verdicts[1]
+        # 1. Fremd (einstimmig): fürs THEMA fremde Aussagen → discarded
+        for k in sorted(v1["fremd"] & v2["fremd"]):
+            t = _titel(k)
+            bfacts.pop(_norm_title(t), None)
+            await db.set_subblock_fields(topic, bnorm, _norm_title(t), status="discarded")
+            if t in keep:
+                keep.remove(t)
+            gone.add(k)
+        # 2. Unsicher-Übernahme (2/2 „ja"): wird consensus samt Generator-Facts
+        for k in range(len(subs) + 1, n + 1):
+            if k in gone:
+                continue
+            u = unsicher[k - len(subs) - 1]
+            if v1["uebernehmen"].get(k) == "ja" and v2["uebernehmen"].get(k) == "ja":
+                sn = _norm_title(u["title"])
+                bfacts[sn] = _fk_of(u)
+                keep.append(u["title"])
+                await db.set_subblock_fields(topic, bnorm, sn, status="consensus")
+            else:
+                await db.set_subblock_fields(topic, bnorm, _norm_title(u["title"]), status="discarded")
+                gone.add(k)
+        # 3. Gruppen (einstimmige Paare): haupt-Votum, sonst key_points/Länge
+        haupt_votes: dict[int, int] = {}
+        for v in (v1, v2):
+            for g in v["gruppen"]:
+                if g["haupt"]:
+                    haupt_votes[g["haupt"]] = haupt_votes.get(g["haupt"], 0) + 1
+        for g in _agreed_cliques([_pairs_of([x["ids"] for x in v["gruppen"]]) for v in (v1, v2)], negs, n):
+            g = [k for k in g if k not in gone]
+            if len(g) < 2:
+                continue
+            win = max(g, key=lambda k: (haupt_votes.get(k, 0), len(_kp(_titel(k))), len(_titel(k)), -k))
+            wf = bfacts.setdefault(_norm_title(_titel(win)), {})
+            for k in g:
+                if k != win:
+                    await _fold(k, wf)
+        # 4. Kataloge: Aufzählungszeilen → EIN neuer benannter Sub (Facts-Union)
+        for g in _agreed_cliques([_pairs_of([x["ids"] for x in v["kataloge"]]) for v in (v1, v2)], negs, n):
+            g = [k for k in g if k not in gone]
+            if len(g) < 2:
+                continue
+            titel = next((clean_title(x["titel"]) for x in v1["kataloge"] + v2["kataloge"]
+                          if set(x["ids"]) & set(g) and clean_title(x["titel"])), "")
+            kn = _norm_title(titel)
+            if not kn or kn in {_norm_title(s) for s in keep}:
+                continue
+            kf: dict = {}
+            for k in g:
+                await _fold(k, kf)
+            bfacts[kn] = kf
+            keep.append(titel)
+            await db.put_subblock(topic, bnorm, kn, title, titel, status="consensus")
+        # 5. Facts-Probleme: discard nur 2/2 (irreversibel), Korrektur ab 1 Stimme
+        d1 = {p["nr"] for p in v1["facts_probleme"] if p["discard"]}
+        d2 = {p["nr"] for p in v2["facts_probleme"] if p["discard"]}
+        for k in sorted(d1 & d2):
+            if k in gone:
+                continue
+            t = _titel(k)
+            bfacts.pop(_norm_title(t), None)
+            await db.set_subblock_fields(topic, bnorm, _norm_title(t), status="discarded")
+            if t in keep:
+                keep.remove(t)
+            gone.add(k)
+        for p in v1["facts_probleme"] + v2["facts_probleme"]:
+            k = p["nr"]
+            if k in gone or not p["hinweis"]:
+                continue
+            t = _titel(k)
+            if t in keep and all(x["titel"] != t for x in korrekturen):
+                korrekturen.append({"titel": t, "hinweis": p["hinweis"]})
+        # 6. Lücken (Schnitt beider Prüfer, Cap)
+        luecken = _luecken_schnitt(v1["luecken"], v2["luecken"])
+    else:
+        # fail-open: consensus bleibt, unsicher wird verworfen (wie heutiges Clarify-Aus)
+        for u in unsicher:
+            await db.set_subblock_fields(topic, bnorm, _norm_title(u["title"]), status="discarded")
+
+    # 7. Level/Relevanz: Stimmen = Generatoren + Prüfer (explizite Korrektur schlägt
+    #    die implizite Zustimmung); Patt → advanced/relevant (heutige Defaults)
+    sidecar_subs = []
+    for t in keep:
+        sn = _norm_title(t)
+        try:
+            k = nummern.index(t) + 1
+        except ValueError:
+            k = 0  # Katalog-/Fix-Neuzugänge haben keine Nummer
+        stimmen_l = list((votes.get(sn) or {}).get("level") or [])
+        stimmen_r = list((votes.get(sn) or {}).get("relevance") or [])
+        for v in verdicts[:2]:
+            if k and k in v["levels"]:
+                stimmen_l += [v["levels"][k]] * 2  # explizite Korrektur wiegt doppelt
+            if k and k in v["relevanz"]:
+                stimmen_r += [v["relevanz"][k]] * 2
+        fk = bfacts.get(sn) or {}
+        sidecar_subs.append({"title": t, "level": _default_vote(stimmen_l, "advanced"),
+                             "relevance": _default_vote(stimmen_r, "relevant"), "facts": fk})
+
+    # 8. Fix-Tail (0–1 Call): Korrekturen + belegte Lücken
+    if (korrekturen or luecken) and not ctx.is_cancelled():
+        if melde:
+            melde("Fix")
+        neu = await _fix_befunde(ctx, files, title, korrekturen, luecken,
+                                 [s["title"] for s in sidecar_subs], instructions, ns, lbl, sources)
+        for e in neu or []:
+            sn = _norm_title(e["title"])
+            vorhanden = next((s for s in sidecar_subs if _norm_title(s["title"]) == sn), None)
+            if vorhanden is not None:  # Korrektur: Facts ersetzen, Einstufung bleibt
+                vorhanden["facts"] = _fk_of(e)
+                bfacts[sn] = vorhanden["facts"]
+            else:  # Lücken-Fund: neuer consensus-Sub
+                bfacts[sn] = _fk_of(e)
+                keep.append(e["title"])
+                sidecar_subs.append({"title": e["title"],
+                                     "level": e["level"] or "advanced",
+                                     "relevance": e["relevance"] or "relevant",
+                                     "facts": bfacts[sn]})
+                await db.put_subblock(topic, bnorm, sn, title, e["title"], status="consensus")
+
+    if len(keep) != len(subs):
+        _log(topic, f"Verify {title}: {len(subs)} consensus + {len(unsicher)} unsicher → {len(keep)}")
+    return {"raw": {title: [s["title"] for s in sidecar_subs]},
+            "facts": {title: bfacts},
+            "sidecar": {title: sidecar_subs}}
+
+
+async def _fix_befunde(ctx: GenContext, files: dict, title: str, korrekturen: list[dict],
+                       luecken: list[str], vorhanden: list[str], instructions: str,
+                       ns: str, lbl: str, sources: list[str] | None) -> list[dict]:
+    """EIN Call korrigiert beanstandete Facts und füllt gemeldete Lücken. Hartes Beleg-Gate
+    für Neuzugänge (key_points/cited_facts nicht leer) + Dedup gegen den Bestand — ein
+    unbelegter Lücken-„Fund" flutet sonst das Fakten-Gate des Guides."""
+    topic = ctx.topic
+    work_dir = files["arbeit"]
+    auftraege = [f"- KORRIGIEREN: „{k['titel']}“ — {k['hinweis']}" for k in korrekturen]
+    auftraege += [f"- LÜCKE (neuer Subbaustein, nur wenn belegbar): {l}" for l in luecken]
+    source, caps = await asyncio.to_thread(
+        _inline_source, topic, sources,
+        [title] + [k["titel"] for k in korrekturen] + list(luecken))
+    sh = _h8(title, *sorted(a for a in auftraege))
+    pfad = work_dir / f"fix-{sh}.json"
+    if _gen_schema(_json_file(pfad)) is None:
+        status, _v = await run_single_slot(
+            ctx, f"{lbl}Fix", key=f"blocks-{topic}-{ns}sb-fix-{sh}",
+            prompt=_prompt("Subblock-Fix", topic=topic, block=title, source=source,
+                           auftraege="\n".join(auftraege), extra=_extra(instructions)),
+            role="quick", capabilities=caps,
+            payload=lambda result, p=pfad: _sink_json(result, p, _gen_schema),
+            timeout=_timeout("fix", len(auftraege)))
+        if status == FAILED:
+            _log(topic, f"Fix {title} ohne Ergebnis — Befunde bleiben offen")
+            return []
+    out = _gen_schema(_json_file(pfad)) or []
+    korrektur_norms = {_norm_title(k["titel"]) for k in korrekturen}
+    have_norms = {_norm_title(t) for t in vorhanden}
+    angenommen = []
+    for e in out:
+        sn = _norm_title(e["title"])
+        if sn in korrektur_norms:
+            angenommen.append(e)
+            continue
+        if sn in have_norms or not (e["key_points"] or e["cited_facts"]):
+            continue  # unbelegt oder Dublette → verfällt
+        st = _sub_tokens(e["title"])
+        if any(st <= _sub_tokens(t) or _sub_tokens(t) <= st for t in vorhanden):
+            continue
+        angenommen.append(e)
+        have_norms.add(sn)
+    return angenommen
+
+
+# ── Artefakte ───────────────────────────────────────────────────────────────────────
+
+def _subs_text(title: str, sidecar_subs: list[dict]) -> str:
+    return f"BLOCK: {title}\n" + "\n".join(
+        f"- {s['title']}\n" + "\n".join(f"  {z}" for z in _facts_lines(s.get("facts") or {}).splitlines())
+        for s in sidecar_subs)
+
+
+async def _artefakte_block(ctx: GenContext, files: dict, title: str,
+                           sidecar_subs: list[dict], instructions: str = "",
+                           ns: str = "", lbl: str = "", melde=None) -> dict | None:
+    """EIN Generator-Call liefert Fragen + Flashcards + Beispiele (Split in 2 parallele
+    Calls bei > ART_SPLIT_SUBS Subs), EIN Prüfer-Call verifiziert Beispiele, bereinigt
+    die Fragen und ergänzt fehlende. → {pattern, artefacts} | None (nur Cancel)."""
+    topic = ctx.topic
+    work_dir = files["arbeit"]
+    if not sidecar_subs:
+        return {"pattern": {title: []}, "artefacts": {"flashcard": [], "example": []}}
+    if melde:
+        melde("Artefakte gen")
+    sh = _subs_hash({title: sidecar_subs})
+    haelften = ([sidecar_subs] if len(sidecar_subs) <= ART_SPLIT_SUBS
+                else [sidecar_subs[:len(sidecar_subs) // 2], sidecar_subs[len(sidecar_subs) // 2:]])
+
+    async def _gen(gi: int, teil: list[dict]):
+        pfad = work_dir / f"art-{sh}-t{gi}.json"
+        if _art_gen_schema(_json_file(pfad)) is not None:
+            return
+        status, _v = await run_single_slot(
+            ctx, f"{lbl}Artefakte {gi}", key=f"blocks-{topic}-{ns}art-gen-{sh}-t{gi}",
+            prompt=_prompt("Artefakt-Generate", topic=topic, blocks=_subs_text(title, teil),
+                           extra=_extra(instructions)),
+            role="quick", capabilities="none",
+            payload=lambda result, p=pfad: _sink_json(result, p, _art_gen_schema),
+            timeout=_timeout("artefakt", len(teil)))
+        if status == FAILED:
+            _log(topic, f"Artefakte {title} Teil {gi} ohne Ergebnis")
+
+    await asyncio.gather(*[_gen(gi, teil) for gi, teil in enumerate(haelften, 1)])
+    if ctx.is_cancelled():
+        return None
+    pattern: list[dict] = []
+    cards: list[dict] = []
+    examples: list[dict] = []
+    for gi in range(1, len(haelften) + 1):
+        o = _art_gen_schema(_json_file(work_dir / f"art-{sh}-t{gi}.json"))
+        if o:
+            pattern += o["pattern"]
+            cards += o["cards"]
+            examples += o["examples"]
+
+    # Prüfer: Beispiele verifizieren, Fragen bereinigen + fehlende ergänzen
+    sub_titles = [s["title"] for s in sidecar_subs]
+    fehlend = [t for t in sub_titles
+               if _norm_title(t) not in {_norm_title(p["subblock"]) for p in pattern}]
+    if pattern or examples:
+        if melde:
+            melde("Artefakte check")
+        tabelle = "\n".join(f"({p['subblock']}) {p['question']}" for p in pattern) or "(keine)"
+        beisp = "\n\n".join(
+            f"{k}. PROBLEM: {e['problem']}\n   SCHRITTE: " + " | ".join(e["steps"])
+            + (f"\n   ERGEBNIS: {e['result']}" if e.get("result") else "")
+            for k, e in enumerate(examples, 1)) or "(keine)"
+        fehlend_txt = ("\nSUBBLOCKS STILL MISSING A QUESTION:\n"
+                       + "\n".join(f"- {t}" for t in fehlend) + "\n") if fehlend else "\n"
+        pfad = work_dir / f"artcheck-{sh}.json"
+        if _art_check_schema(_json_file(pfad)) is None:
+            status, _v = await run_single_slot(
+                ctx, f"{lbl}Artefakt-Check", key=f"blocks-{topic}-{ns}art-check-{sh}",
+                prompt=_prompt("Artefakt-Check", topic=topic, facts=_subs_text(title, sidecar_subs),
+                               table=tabelle, fehlend=fehlend_txt, examples=beisp,
+                               extra=_extra(instructions)),
+                role="judge", capabilities="none",
+                payload=lambda result, p=pfad: _sink_json(result, p, _art_check_schema),
+                timeout=_timeout("artefakt_check", len(sidecar_subs)))
+            if status == FAILED:
+                _log(topic, f"Artefakt-Check {title} ohne Ergebnis — Rohfassung übernommen")
+        check = _art_check_schema(_json_file(pfad))
+        if check:
+            if check["examples_probleme"]:
+                examples = [e for k, e in enumerate(examples, 1)
+                            if k not in check["examples_probleme"]]
+                _log(topic, f"Artefakt-Check {title}: {len(check['examples_probleme'])} Beispiel(e) verworfen")
+            if check["pattern"]:  # bereinigte Fassung ersetzt die Rohfassung
+                pattern = check["pattern"]
+            pattern += check["pattern_ergaenzt"]
+
+    pattern_map = {title: [{"subblock": p["subblock"], "question": p["question"]}
+                           for p in pattern]}
+    # block-Feld auf den Karten-Block normieren (Ein-Block-Call — Agent-Echos abfangen)
+    for e in cards + examples:
+        e["block"] = title
+    return {"pattern": pattern_map,
+            "artefacts": {"flashcard": [{k: e[k] for k in ("block", "subblock", "question", "answer")} for e in cards],
+                          "example": [{k: e[k] for k in ("block", "subblock", "problem", "steps", "result")} for e in examples]}}

backend/board_artefacts.py

@@ -0,0 +1,569 @@
+"""Board 2 „Artefakte": per finished block, prepare the learning artefacts the guide presents.
+
+A card is spawned by board 1's `done` column per mirrored block and runs through:
+  generate → verify (inkl. Fix-Tail) → artefakte (Gen + Prüfer) → finalize
+(die verschmolzenen Calls liegen in block_calls.py — 4–5 serielle Segmente statt ~20).
+finalize (SERIAL) merges the block's results into the global sidecar/facts/pattern/artefakte
+files + the DB tables. Danach zwei topic-weite BARRIEREN: `konsolidierung` (cross-block
+sub dedup, faltet per repair.falte_sub) und `outline` (prerequisite graph → chapter order),
+re-run once per generation run — outline läuft parallel zur Dedup-Barriere."""
+
+import asyncio
+import hashlib
+import json
+import logging
+import re
+
+import database as db
+import blocks
+import embedding
+from block_calls import _artefakte_block, _generate_block, _verify_block
+from blocks import ARTEFACT_TYPES, _match_sub, _neg_set, _sink_json, _outline_block
+from config import CROSS_CHUNK_PAARE, EMBEDDING_AKTIV, SUB_DUP_KANDIDAT_COS
+from fsutil import atomic_write_json
+from jsonio import read_json_file as _json_file
+from kanban import Flow, Stage
+from pipeline import FAILED, GenContext, _extra, _log, _prompt, _timeout, run_single_slot
+from textkit import _norm_title, _title
+
+log = logging.getLogger("creator.board_artefacts")
+
+BOARD = "artefacts"
+DONE = "done_artefact"
+
+
+def _nset(msg: str, step: int | None = None) -> None:
+    """Progress no-op — the kanban board itself is the progress display."""
+
+
+def _safe(norm: str) -> str:
+    return re.sub(r"\W+", "-", norm).strip("-")[:24] or "block"
+
+
+def _sub_key(existing: set[str], sn: str) -> str:
+    """Agents echo the short sub title while the sub row is keyed 'kurztitel: beschreibung' —
+    resolve to the stored key: exact, unambiguous prefix, then unambiguous substring
+    containment either way (agents paraphrase/truncate, measured 23 orphans of ~560 rows).
+    Ambiguous or unresolvable echoes stay unchanged (visible as QA orphan)."""
+    if sn in existing:
+        return sn
+    hits = [s for s in existing if s.startswith(sn + ":")]
+    if len(hits) == 1:
+        return hits[0]
+    if not hits:
+        hits = [s for s in sorted(existing) if sn in s or s in sn]
+        if len(hits) == 1:
+            return hits[0]
+    return sn
+
+
+def _card_set_p(flow: Flow, norm: str):
+    """Per-card progress: the inner step messages land in-memory on the flow —
+    board_snapshot shows them as the card's info line + phase stepper while active.
+    The step INDEX is resolved to its NAME at write time (indices shift with the
+    source type, names are stable)."""
+    info = flow.state.setdefault("card_info", {})
+
+    def set_p(msg: str, step: int | None = None) -> None:
+        name = ""
+        if step is not None:
+            steps = flow.state.get("blocks_steps")
+            if steps is None:
+                steps = flow.state["blocks_steps"] = blocks._blocks_steps(flow.topic)
+            if 0 <= step < len(steps):
+                name = steps[step]
+        info[f"{BOARD}:{norm}"] = {"msg": msg, "step": name}
+    return set_p
+
+
+def _pfiles(files: dict, norm: str) -> dict:
+    """Per-block file namespace: own work dir + facts/artefakte paths, global rest."""
+    sub = files["arbeit"] / f"ab-{_norm_title(norm).replace(' ', '_')[:60]}"
+    sub.mkdir(parents=True, exist_ok=True)
+    return {**files, "arbeit": sub, "facts": sub / "facts.json", "artefakte": sub / "artefakte.json"}
+
+
+def _entry_line(p: dict) -> str:
+    d = p.get("description")
+    return f"{p['title']} — {d}" if d else p["title"]
+
+
+def make_spawner(topic: str, files: dict):
+    """Hook for board 1's `done` column: one artefact card per mirrored block."""
+
+    async def spawn(block_card_id: str, payload: dict):
+        norm = payload.get("mirrored_norm")
+        if not norm:
+            return
+        await db.kanban_upsert_card(topic, BOARD, norm, "ablock", "generate", {
+            "title": payload.get("title", ""),
+            "description": payload.get("description", ""),
+            "n_size": payload.get("n_size", 0),  # LPT estimate until subs_n exists
+        })
+    return spawn
+
+
+async def _gather_cards(ctx: GenContext, flow: Flow, cards, one):
+    results = await asyncio.gather(*[one(c) for c in cards], return_exceptions=True)
+    errs = [r for r in results if isinstance(r, Exception)]
+    if errs:
+        raise errs[0]
+    flow.wake.set()
+
+
+def _fail_or_cancel(ctx: GenContext, what: str):
+    # A per-card failure belongs on the card (last_error/dead-letter), never in the
+    # topic banner — the inner block functions may have set it there.
+    blocks._blocks_errors.pop(ctx.topic, None)
+    if ctx.is_cancelled():
+        return None  # leave the card where it is
+    raise RuntimeError(f"{what} ohne Ergebnis")
+
+
+# ── Stage processors (one call per card, all parallel) ─────────────────────────────
+async def _seed_map(topic: str) -> dict[str, list[str]]:
+    """Demoted fragments become seed candidates of their SURVIVING parent block.
+    parent_norm may point at a block that itself got grouped/merged/renamed — follow the
+    redirect chain (grouped → merged_into, rejected → parent_norm, done → mirrored_norm)
+    to the living board-2 card id (= mirrored_norm). A dead end drops the seed (as before)."""
+    alive: set[str] = set()
+    redirect: dict[str, str] = {}
+    rejected: list[dict] = []
+    for r in await db.kanban_cards(topic, board="inventory", kind="block"):
+        p = r["payload"]
+        tn = _norm_title(p.get("title", ""))
+        if not tn:
+            continue
+        if r["stage"] in ("done", "done_block"):
+            mn = p.get("mirrored_norm") or tn
+            alive.add(mn)
+            if tn != mn:
+                redirect.setdefault(tn, mn)
+        elif r["stage"] == "grouped" and p.get("merged_into"):
+            redirect.setdefault(tn, _norm_title(p["merged_into"]))
+            # umbrella members are absorbed WHOLE topics ("Aufgabenlisten" → "Listen") —
+            # without a seed the umbrella's finders may simply miss them (measured).
+            rejected.append({"title": p.get("title", ""), "parent_norm": _norm_title(p["merged_into"])})
+        elif r["stage"] == "rejected":
+            if p.get("parent_norm"):
+                redirect.setdefault(tn, p["parent_norm"])
+            rejected.append(p)
+
+    def _resolve(norm: str) -> str | None:
+        seen: set[str] = set()
+        cur = norm
+        while cur and cur not in seen:
+            if cur in alive:  # alive check BEFORE following (self-edges like „Listen"→„Listen")
+                return cur
+            seen.add(cur)
+            cur = redirect.get(cur, "")
+        return None
+
+    seeds: dict[str, list[str]] = {}
+    for p in rejected:
+        pn = p.get("parent_norm")
+        if pn and (target := _resolve(pn)):
+            seeds.setdefault(target, []).append(p.get("title", ""))
+    return seeds
+
+
+def _melder(flow: Flow, norm: str):
+    """Live-Stepper der Karte: Phasenname → card_info (ging bei der Call-Verschmelzung
+    verloren — Karten liefen ohne Badge/Stepper durch das Board)."""
+    set_p = _card_set_p(flow, norm)
+
+    def melde(schritt: str) -> None:
+        try:
+            set_p(f"{schritt}…", step=blocks._step_idx(flow.topic, schritt))
+        except ValueError:
+            set_p(f"{schritt}…")
+    return melde
+
+
+async def _proc_generate(ctx: GenContext, flow: Flow, files: dict, instructions: str, cards):
+    """Verschmolzener Erzeuger: 2 unabhängige Generatoren liefern Subs+Facts+Einstufung
+    in EINEM Call, Konsens im Code (block_calls._generate_block)."""
+    topic = flow.topic
+    # fragments demoted to a parent become seed candidates of the parent's subblocks
+    seeds = await _seed_map(topic)
+
+    async def one(c):
+        p = c["payload"]
+        norm = c["card_id"]
+        gen = await _generate_block(ctx, _pfiles(files, norm), p.get("title", ""),
+                                    p.get("description", ""), instructions,
+                                    ns=f"{_safe(norm)}-", lbl=f"{p.get('title', norm)} · ",
+                                    sources=p.get("sources"),
+                                    seeds=[s for s in seeds.get(norm, []) if s] or None,
+                                    melde=_melder(flow, norm))
+        if gen is None:
+            return _fail_or_cancel(ctx, f"Generate {p.get('title', norm)}")
+        p["raw"], p["facts"] = gen["raw"], gen["facts"]
+        p["unsicher"], p["votes"] = gen["unsicher"], gen["votes"]
+        p["subs_n"] = sum(len(v) for v in gen["raw"].values()) + len(gen["unsicher"])
+        await db.kanban_set_payload(topic, BOARD, norm, p)
+        await db.kanban_advance(topic, BOARD, norm, "verify")
+
+    await _gather_cards(ctx, flow, cards, one)
+
+
+async def _proc_verify(ctx: GenContext, flow: Flow, files: dict, q: dict, instructions: str, cards):
+    """Verschmolzener Prüfer: MECE + Facts + Einstufung in einem Panel-Call, Fix-Tail
+    inklusive (block_calls._verify_block) — ersetzt facts-check/konsolidierung/levels/
+    relevance als eigene Stages."""
+    topic = flow.topic
+
+    async def one(c):
+        p = c["payload"]
+        norm = c["card_id"]
+        title = p.get("title", "")
+        gen = {"raw": p.get("raw") or {}, "facts": p.get("facts") or {},
+               "unsicher": p.get("unsicher") or [], "votes": p.get("votes") or {}}
+        res = await _verify_block(ctx, _pfiles(files, norm), title, gen, q, instructions,
+                                  ns=f"{_safe(norm)}-", lbl=f"{title or norm} · ",
+                                  sources=p.get("sources"), melde=_melder(flow, norm))
+        if res is None:
+            return None  # nur Cancel — Karte bleibt liegen
+        p["raw"], p["facts"], p["sidecar"] = res["raw"], res["facts"], res["sidecar"]
+        p.pop("unsicher", None)
+        p.pop("votes", None)
+        await db.kanban_set_payload(topic, BOARD, norm, p)
+        await db.kanban_advance(topic, BOARD, norm, "artefakte")
+
+    await _gather_cards(ctx, flow, cards, one)
+
+
+async def _proc_artefakte(ctx: GenContext, flow: Flow, files: dict, instructions: str, cards):
+    """Fragen + Flashcards + Beispiele in einem Generator-Call, ein Prüfer-Call dahinter
+    (block_calls._artefakte_block)."""
+    topic = flow.topic
+
+    async def one(c):
+        p = c["payload"]
+        norm = c["card_id"]
+        title = p.get("title", "")
+        res = await _artefakte_block(ctx, _pfiles(files, norm), title,
+                                     (p.get("sidecar") or {}).get(title) or [],
+                                     instructions, ns=f"{_safe(norm)}-", lbl=f"{title or norm} · ",
+                                     melde=_melder(flow, norm))
+        if res is None:
+            return None  # nur Cancel
+        p["pattern"] = res["pattern"]
+        p["artefacts"] = res["artefacts"]
+        await db.kanban_set_payload(topic, BOARD, norm, p)
+        await db.kanban_advance(topic, BOARD, norm, "finalize")
+
+    await _gather_cards(ctx, flow, cards, one)
+
+
+def _cross_schema(data) -> dict[int, str] | None:
+    """{"pairs": {"1": "a"|"b"|"nein"}} → {pair_nr: verdict} · otherwise None."""
+    if not isinstance(data, dict) or not isinstance(data.get("pairs"), dict):
+        return None
+    out: dict[int, str] = {}
+    for k, v in data["pairs"].items():
+        try:
+            nr = int(k)
+        except (ValueError, TypeError):
+            continue
+        s = str(v).strip().casefold()
+        if s in ("a", "b", "nein"):
+            out[nr] = s
+    return out or None
+
+
+async def _proc_konsolidierung(ctx: GenContext, flow: Flow, files: dict, instructions: str, cards):
+    """BARRIER/drain am RUN-ENDE — cross-block sub dedup: the SAME statement carried by two
+    blocks (measured on Markdown: tab handling in 3 blocks, HTML blocks, backslash escapes —
+    the in-block paths never see these). Embedding candidates (block≠block, cos ≥
+    SUB_DUP_KANDIDAT_COS) go to a two-judge panel; UNANIMITY decides which block keeps the
+    statement. Sitzt seit dem Umbau NACH finalize: als Mittel-Barriere wartete jede fertige
+    Karte auf die langsamste (gemessen: 8:46 min Leerlauf pro Block, kanban-smoke). Der
+    Verlierer wird per repair.falte_sub gefaltet (variant + Fragen/Artefakte umhängen) —
+    die wenigen Cross-Dubletten kosten so ein paar umsonst generierte Artefakte statt
+    Minuten Wandzeit für alle. Fail-open on judge failure/dissent."""
+    from repair import falte_sub
+    topic = flow.topic
+    work_dir = flow.work_dir
+    # Resume-Karten aus der alten Stage-Position (Barriere lag vor den Fragen): erst fertig
+    # generieren — die Barriere feuert erneut, wenn alle wieder hier sind. Direkt dedupen
+    # ginge schief: finalize würde den gefalteten Sub aus dem Karten-Sidecar re-spiegeln.
+    nachzuegler = [(c["card_id"], "artefakte" if "sidecar" in c["payload"] else "generate")
+                   for c in cards if "pattern" not in c["payload"]]
+    if nachzuegler:
+        await db.kanban_advance_many(topic, BOARD, nachzuegler)
+        flow.wake.set()
+        return
+
+    async def _advance_all():
+        await db.kanban_advance_many(topic, BOARD, [(c["card_id"], DONE) for c in cards])
+        flow.wake.set()
+
+    rows = [r for r in await db.list_subblocks(topic) if r["status"] == "consensus"]
+    if len(rows) < 2 or not EMBEDDING_AKTIV or not await asyncio.to_thread(embedding.available):
+        await _advance_all()
+        return
+    sims = await asyncio.to_thread(embedding.embed_sims, [r["sub_title"] for r in rows])
+    if sims is None:
+        await _advance_all()
+        return
+    negs = [_neg_set(r["sub_title"]) for r in rows]
+    pairs = [(i, j) for i in range(len(rows)) for j in range(i + 1, len(rows))
+             if rows[i]["block_norm"] != rows[j]["block_norm"] and negs[i] == negs[j]
+             and float(sims[i][j]) >= SUB_DUP_KANDIDAT_COS]
+    if not pairs:
+        await _advance_all()
+        return
+
+    def _kp(r: dict) -> list:
+        try:
+            return (json.loads(r.get("facts") or "{}")).get("key_points") or []
+        except ValueError:
+            return []
+
+    def _side(tag: str, r: dict) -> str:
+        return f"{tag}: [Block: {r['block']}] {r['sub_title']}" + "".join(f"\n   - {p}" for p in _kp(r))
+
+    # chunked judging: ONE call over all pairs scaled its timeout past 50 min, and a hung
+    # call blocked the barrier for the full window (measured on aak: 196 pairs, 2×54 min)
+    chunks = [pairs[lo:lo + CROSS_CHUNK_PAARE] for lo in range(0, len(pairs), CROSS_CHUNK_PAARE)]
+
+    async def _urteile_chunk(chunk: list[tuple[int, int]]) -> dict[int, str]:
+        """Two judges (+ substitute, + tie-breaker) over one pair chunk → {local_k: verdict};
+        empty dict = fail-open (pairs stay)."""
+        lines = "\n\n".join(
+            f"{k}.\n{_side('A', rows[i])}\n{_side('B', rows[j])}"
+            for k, (i, j) in enumerate(chunk, 1))
+        h = hashlib.md5(lines.encode()).hexdigest()[:8]
+        paths = [work_dir / f"sub-crossblock-{h}-j{j}.json" for j in (1, 2)]
+
+        async def _judge(j, path, plines, n):
+            if _cross_schema(_json_file(path)) is not None:
+                return  # resume
+            status, _v = await run_single_slot(
+                ctx, f"Sub-Crossblock j{j}", key=f"blocks-{topic}-sub-crossblock-{h}-j{j}",
+                prompt=_prompt("Subblock-Crossblock", topic=topic, pairs=plines, extra=_extra(instructions)),
+                role="judge", capabilities="none",
+                payload=lambda result, p=path: _sink_json(result, p, _cross_schema),
+                timeout=_timeout("subblock_check", n))
+            if status == FAILED:
+                _log(topic, f"Sub-Crossblock j{j} ohne Ergebnis — fail-open")
+
+        await asyncio.gather(*[_judge(j, p, lines, len(chunk)) for j, p in zip((1, 2), paths)])
+        if ctx.is_cancelled():
+            return {}
+        outs = [o for p in paths if (o := _cross_schema(_json_file(p))) is not None]
+        if len(outs) == 1:  # Ersatz-Richter statt fail-open bei EINEM Ausfall
+            ersatz = work_dir / f"sub-crossblock-{h}-jE.json"
+            await _judge("E", ersatz, lines, len(chunk))
+            if ctx.is_cancelled():
+                return {}
+            outs = [o for p in [*paths, ersatz] if (o := _cross_schema(_json_file(p))) is not None]
+        if len(outs) != 2:
+            if outs:
+                _log(topic, "Sub-Crossblock: nur 1/2 Richter — fail-open")
+            return {}
+        final = {k: (outs[0].get(k, "nein") if outs[0].get(k, "nein") == outs[1].get(k, "nein")
+                     else "uneinig") for k in range(1, len(chunk) + 1)}
+        disputed = [k for k, v in final.items() if v == "uneinig"]
+        if disputed:  # tie-breaker: a third judge sees ONLY the disputed pairs, majority 2/3
+            d_lines = "\n\n".join(
+                f"{x}.\n{_side('A', rows[chunk[k - 1][0]])}\n{_side('B', rows[chunk[k - 1][1]])}"
+                for x, k in enumerate(disputed, 1))
+            p3 = work_dir / f"sub-crossblock-{h}-j3.json"
+            await _judge(3, p3, d_lines, len(disputed))
+            if ctx.is_cancelled():
+                return {}
+            v3 = _cross_schema(_json_file(p3)) or {}
+            if not v3:
+                _log(topic, "Sub-Crossblock j3 ohne Ergebnis — strittige Paare bleiben")
+            for x, k in enumerate(disputed, 1):
+                t = v3.get(x, "nein")
+                if t in (outs[0].get(k, "nein"), outs[1].get(k, "nein")):
+                    final[k] = t  # majority 2/3; anything else stays disputed → no fold
+        return final
+
+    chunk_finals = await asyncio.gather(*[_urteile_chunk(c) for c in chunks])
+    if ctx.is_cancelled():
+        return
+    final_all: dict[int, str] = {}  # global pair index (1-based over `pairs`) → verdict
+    for cnr, fin in enumerate(chunk_finals):
+        for k, v in fin.items():
+            final_all[cnr * CROSS_CHUNK_PAARE + k] = v
+    journal = {"paare": len(pairs), "chunks": len(chunks), "gefaltet": [], "verdicts": []}
+    gone: set[tuple] = set()
+    for k, (i, j) in enumerate(pairs, 1):
+        verdict = final_all.get(k, "nein")
+        journal["verdicts"].append({"a": f"{rows[i]['block']} · {rows[i]['sub_title']}",
+                                    "b": f"{rows[j]['block']} · {rows[j]['sub_title']}",
+                                    "verdict": verdict})
+        if verdict not in ("a", "b"):
+            continue
+        win, lose = (rows[i], rows[j]) if verdict == "a" else (rows[j], rows[i])
+        wk = (win["block_norm"], win["sub_norm"])
+        lk = (lose["block_norm"], lose["sub_norm"])
+        if lk in gone or wk in gone:  # keeper already folded → don't chain away the content
+            continue
+        await falte_sub(topic, files, win, lose)
+        gone.add(lk)
+        journal["gefaltet"].append({"weg": f"{lose['block']} · {lose['sub_title']}",
+                                    "bleibt": f"{win['block']} · {win['sub_title']}"})
+    if journal["gefaltet"]:
+        _log(topic, f"Sub-Crossblock: {len(journal['gefaltet'])} blockübergreifende Dublette(n) gefaltet")
+    hg = hashlib.md5("\n".join(f"{i}:{j}" for i, j in pairs).encode()).hexdigest()[:8]
+    atomic_write_json(work_dir / f"sub-crossblock-{hg}.json", journal, indent=1)
+    await _advance_all()
+
+
+# ── Finalize (SERIAL): merge into the global files + DB tables ─────────────────────
+def _merge_json(path, block_keys: dict) -> None:
+    data = _json_file(path)
+    if not isinstance(data, dict):
+        data = {}
+    data.update(block_keys)
+    atomic_write_json(path, data, indent=1)
+
+
+async def _proc_finalize(ctx: GenContext, flow: Flow, files: dict, cards):
+    topic = flow.topic
+    for c in cards:
+        p = c["payload"]
+        title = p.get("title", "")
+        sidecar = p.get("sidecar") or {}
+        pattern = p.get("pattern") or {}
+        artefacts = p.get("artefacts") or {}
+        # global sidecar files (the legacy read path of guide/frontend/resume)
+        _merge_json(files["sub_roh"], {t: subs for t, subs in (p.get("raw") or {}).items()})
+        _merge_json(files["facts"], p.get("facts") or {})
+        _merge_json(files["sidecar"], sidecar)
+        _merge_json(files["question_pattern"], pattern)
+        art_global = _json_file(files["artefakte"])
+        if not isinstance(art_global, dict):
+            art_global = {}
+        for typ in ARTEFACT_TYPES:
+            kept = [e for e in art_global.get(typ, [])
+                    if _norm_title(_title(str(e.get("block", "")))) != _norm_title(title)]
+            art_global[typ] = kept + list(artefacts.get(typ, []))
+        atomic_write_json(files["artefakte"], art_global, indent=1)
+        # DB mirrors — per block only (no global deletes)
+        await blocks._mirror_sidecar_db(topic, sidecar)
+        # stale question/artefact rows of a PREVIOUS run keyed to gone subs: finalize only
+        # upserts, so re-runs left orphans (measured: 28).
+        await db.delete_question_pattern(topic, _norm_title(title))
+        await db.delete_sub_artefakte(topic, _norm_title(title))
+        # consensus rows of a PREVIOUS run that this run's sidecar no longer carries would
+        # linger without facts/questions/artefacts (measured: 25) — drop them per block;
+        # variant/discarded stay for QA. Then default-level the mirror's own stragglers.
+        for btitle, subs in sidecar.items():
+            keep = {_norm_title(str(s.get("title", ""))) for s in subs if isinstance(s, dict)}
+            await db.delete_stale_consensus(topic, _norm_title(btitle), keep - {""})
+        await db.default_subblock_levels(topic, _norm_title(title))
+        sub_keys: dict[str, set[str]] = {}
+
+        async def _keys(bnorm: str) -> set[str]:
+            if bnorm not in sub_keys:
+                sub_keys[bnorm] = {r["sub_norm"] for r in await db.list_subblocks(topic, bnorm)}
+            return sub_keys[bnorm]
+
+        for btitle, entries in pattern.items():
+            bnorm = _norm_title(btitle)
+            for e in entries if isinstance(entries, list) else []:
+                sub = str(e.get("subblock", "")).strip()
+                sn = _norm_title(sub)
+                question = str(e.get("question", "")).strip()
+                if bnorm and sn and question:
+                    sn = _sub_key(await _keys(bnorm), sn)
+                    await db.upsert_question_pattern(topic, bnorm, sn, btitle, sub, question)
+        btitles = list(sidecar.keys())
+        for typ in ARTEFACT_TYPES:
+            for e in artefacts.get(typ, []):
+                bt = _match_sub(str(e.get("block", "")), btitles)
+                bnorm, sn = _norm_title(bt), _norm_title(str(e.get("subblock", "")))
+                if not bnorm or not sn:
+                    continue
+                sn = _sub_key(await _keys(bnorm), sn)
+                data = json.dumps({k: v for k, v in e.items() if k not in ("block", "subblock")},
+                                  ensure_ascii=False)
+                await db.put_sub_artifact(topic, bnorm, sn, typ, data, bt, str(e.get("subblock", "")))
+        await db.kanban_advance(topic, BOARD, c["card_id"], "konsolidierung")
+        _log(topic, f"Artefakte fertig: {title}")
+    flow.wake.set()
+
+
+# ── Outline (topic-wide barrier singleton) ─────────────────────────────────────────
+OUTLINE_CARD = "outline"
+
+
+async def ensure_outline_card(topic: str) -> None:
+    """(Re-)queue the outline singleton — run once per generation run, after everything."""
+    await db.kanban_upsert_card(topic, BOARD, OUTLINE_CARD, "outline", "outline",
+                                {"title": "Gliederung"})
+
+
+async def _proc_outline(ctx: GenContext, flow: Flow, files: dict, instructions: str, cards):
+    topic = flow.topic
+    done = await db.kanban_cards(topic, board="inventory", stage="done_block")
+    done.sort(key=lambda c: c["updated_at"])
+    entries = {i: _entry_line(c["payload"]) for i, c in enumerate(done, 1)
+               if c["payload"].get("title")}
+    if entries:
+        # The outline may run BEFORE finalize has merged the global facts.json — feed the
+        # prereq hints of _learning_order from the card payloads instead (complete as soon
+        # as every block passed the facts stage, which the trimmed barrier guarantees).
+        facts_map: dict = {}
+        for bc in await db.kanban_cards(topic, board=BOARD, kind="ablock"):
+            facts_map.update(bc["payload"].get("facts") or {})
+        fp = flow.work_dir / "outline-facts.json"
+        atomic_write_json(fp, facts_map, indent=1)
+        plan = await _outline_block(ctx, _nset, {**files, "facts": fp}, entries, instructions)
+        if ctx.is_cancelled():
+            return
+        if isinstance(plan, dict) and plan.get("chapters"):
+            chapters = [
+                {"title": ch.get("title", "Kapitel"),
+                 "blocks": [_title(entries[n]) for n in ch.get("numbers", []) if n in entries]}
+                for ch in plan["chapters"]
+            ]
+            await db.set_outline(topic, json.dumps({"chapters": chapters}, ensure_ascii=False))
+    await db.kanban_advance_many(topic, BOARD, [(c["card_id"], DONE) for c in cards])
+    flow.wake.set()
+
+
+# ── Stage list (appended after board 1 in chain order) ─────────────────────────────
+_ALT_STAGES = ("subblocks", "facts", "levels", "relevance", "question_pattern", "artefacts")
+
+
+async def migriere_alt_karten(topic: str) -> int:
+    """Harter Schnitt: Karten der alten Stage-Treppe beim Flow-Start auf `generate`
+    zurücksetzen (Payload auf die Spawn-Felder reduziert — Zwischenstände der alten
+    Struktur sind für die verschmolzenen Calls wertlos). → Anzahl migrierter Karten."""
+    moves = []
+    for c in await db.kanban_cards(topic, board=BOARD, kind="ablock"):
+        if c["stage"] in _ALT_STAGES:
+            p = c["payload"]
+            await db.kanban_set_payload(topic, BOARD, c["card_id"], {
+                "title": p.get("title", ""), "description": p.get("description", ""),
+                "n_size": p.get("n_size", 0), "sources": p.get("sources")})
+            moves.append((c["card_id"], "generate"))
+    if moves:
+        await db.kanban_advance_many(topic, BOARD, moves)
+    return len(moves)
+
+
+def artefact_stages(ctx: GenContext, flow: Flow, files: dict, q: dict, folder,
+                    instructions: str) -> list[Stage]:
+    research_done = lambda: flow.research_done  # noqa: E731
+    return [
+        Stage(BOARD, "generate", lambda cs: _proc_generate(ctx, flow, files, instructions, cs)),
+        Stage(BOARD, "verify", lambda cs: _proc_verify(ctx, flow, files, q, instructions, cs)),
+        Stage(BOARD, "artefakte", lambda cs: _proc_artefakte(ctx, flow, files, instructions, cs)),
+        Stage(BOARD, "finalize", lambda cs: _proc_finalize(ctx, flow, files, cs), serial=True),
+        # Cross-Block-Dedup als END-Barriere: als Mittel-Barriere idelte jede fertige Karte
+        # auf die langsamste (8:46 min/Block gemessen); jetzt faltet sie nach finalize
+        # per repair.falte_sub — spät gefundene Dubletten kosten Artefakt-Tokens, keine Wandzeit
+        Stage(BOARD, "konsolidierung",
+              lambda cs: _proc_konsolidierung(ctx, flow, files, instructions, cs),
+              barrier=True, drain=True),
+        Stage(BOARD, "outline", lambda cs: _proc_outline(ctx, flow, files, instructions, cs),
+              barrier=True, drain=True, gate=research_done),
+    ]

backend/config.py

@@ -1,3 +1,4 @@
+import os
 from pathlib import Path
 
 PROJECT_ROOT = Path(__file__).resolve().parent.parent
@@ -6,60 +7,278 @@ STORAGE_DIR = PROJECT_ROOT / "storage"
 FRONTEND_DIST = PROJECT_ROOT / "frontend" / "dist"
 DB_PATH = STORAGE_DIR / "creator.db"
 PROJECTS_DIR = PROJECT_ROOT / "projects"
+UNI_DIR = PROJECT_ROOT / "uni"
+
+
+def _load_env(path: Path) -> None:
+    """Mini .env loader (no dependency): KEY=VALUE lines. The FILE wins over inherited
+    env: a --reload master keeps its startup environment forever, so "existing env wins"
+    silently pinned stale values across .env edits (measured: file said 24, workers
+    inherited 15 for hours). Trade-off: ad-hoc shell overrides lose against the file."""
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError:
+        return
+    for line in text.splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        key, value = key.strip(), value.strip().strip('"').strip("'")
+        if key:
+            os.environ[key] = value
+
+
+_load_env(PROJECT_ROOT / ".env")
 
 MAX_CONCURRENT_GENERATIONS = 10
 
-# Timeouts pro Agenten-Schritt: (Basis-Sekunden, Sekunden pro Baustein/Section).
-# Gilt für alle Provider gleich — wer zu langsam ist, wird neu gestartet bzw. überholt.
+# Readability gate: deterministic checker (small German complexity model,
+# scale 1–7). Sections that are too hard go into the read-exam revision.
+# If transformers/torch or the model are missing → gate silently off.
+READABILITY_ACTIVE = True
+READABILITY_MODEL = "MiriUll/distilbert-german-text-complexity"
+# Anchors on the 1–7 scale (TextComplexityDE): plain language ~1.2; Wikipedia average
+# ~3.22; from MOS > 4 a sentence counts as "truly complex" (the paper's simplification cutoff).
+READABILITY_MAX = 3.5          # section too hard when the sentence average is above this
+READABILITY_HARD = 4.0         # an individual sentence is "hard" from here on
+READABILITY_HARD_SHARE = 0.30  # … OR when this share of sentences is hard
+
+# Kanban clustering: semantic embeddings drive the online title clustering and the
+# candidate pairs of the pair check. If transformers/torch are missing or the model
+# won't load → embedding silently off (all pairs go to the judge, clusters stay singletons).
+EMBEDDING_AKTIV = True
+EMBEDDING_MODELL = "sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2"  # CPU, multilingual, ~470 MB
+# Stronger (larger) CPU alternative if needed: "BAAI/bge-m3".
+# Consolidation = two-stage: (1) the embedding builds COARSE similarity blocks (high recall),
+# (2) an LLM judge groups EACH block into the real blocks (merge paraphrases, split
+# over-merges). Pure threshold blocking creates a giant component (everything chained) →
+# hence "capped blocking": greedily merge by cosine, but cap the block size. This keeps the
+# LLM lists short and stable (evidenced: embedding block + LLM judge ≈ 95% precision).
+EMBEDDING_BLOCK_FLOOR = 0.5   # minimum cosine for two candidates to share ONE block
+EMBEDDING_BLOCK_CAP = 25      # max. titles per block (keep the LLM list short/stable)
+# Subblock dedup: purely deterministic (no LLM). Subblocks are short statements IN THE SAME
+# block context — from this cosine on two are the same statement (checked on aak: ≥0.88 are
+# without exception true duplicates). Conservative 0.90 so different aspects (∈NP ≠ NP-hard) stay separate.
+EMBEDDING_SUB_DUP = 0.90
+# Variant folding BEFORE the subblock consensus count: finders rephrase the same concept each
+# round, so exact-norm counting starves real concepts (measured Markdown run: 623/965 mentions
+# discarded, „Zeichenkodierung" 73/74). 0.90 folds true paraphrases at ~0 false folds (0.85/0.88
+# fold distinct aspects like ** vs ***). Antonym pairs measure 0.91–0.95 → negation guard required.
+SUB_VARIANT_COS = 0.90
+# Seed coverage check is LEXICAL first (token containment) — seeds are short fragment NAMES,
+# subs are statements: true covers measure 0.27–0.38 while a wrong hit measured 0.76. The
+# embedding stage only backs up the lexical one (catches „Line Breaks (Soft)" 0.888).
+SEED_COVER_COS = 0.80
+# Sub duplicate CANDIDATE floor for the judge paths (in-block consolidation band hint,
+# cross-block stage, QA detector): the bulk of real paraphrase duplicates measures 0.75–0.90
+# (Markdown: 50 pairs in the band, 4 above) — below every auto-merge threshold, so an LLM
+# judge decides. Candidates only; a merge still needs judge unanimity.
+SUB_DUP_KANDIDAT_COS = 0.75
+# Cross-block judge pairs per call: ONE call over all pairs scaled its timeout to 54 min
+# and a hung call blocked the barrier that long (aak: 196 pairs) — chunks cap it at ~15 min.
+CROSS_CHUNK_PAARE = 40
+
+# Umbrella grouping (block granularity level 2, step "Blocks-Gruppierung", AFTER the filter):
+# collapse sibling DEFINITIONS that are components of ONE umbrella concept (TM model:
+# Konfiguration/Start-/Folge-/Stopkonfiguration/Berechnung/Alphabet/δ; KNF: Literale/Klauseln/
+# Variablen) into ONE block whose description ENUMERATES the children — so the later subblock step
+# re-derives them from the source under the umbrella scope (demotion is re-derivation, not transfer).
+# If the flag is off or no embedding model → step is silently skipped (like Dedup).
+BLOCKS_GRUPPIERUNG_AKTIV = True
+# Lower floor than consolidation (0.5, paraphrase-tuned) for higher sibling recall; the LLM judge is
+# the precision gate. Smaller cap since a lower floor pulls in more nodes → keep the judge lists short.
+EMBEDDING_SIBLING_FLOOR = 0.35   # heterogeneous facets of one model co-cluster weakly → low floor (recall)
+EMBEDDING_SIBLING_CAP = 18       # a rich model (TM) can have many constituent parts
+# Reconcile pass: two independently-judged clusters can emit the SAME parent concept under different
+# titles (e.g. two „Turingmaschine"-umbrellas). Merge umbrella pairs whose title+description cosine is
+# ≥ this (conservative → only true same-parent duplicates, never two distinct umbrellas).
+GROUP_RECONCILE_FLOOR = 0.75
+# Over-merge backstop ONLY (no-structure floor). Research (meronymy ≠ similarity): parts of ONE model are
+# legitimately DISSIMILAR (TM: Alphabet/Konfiguration/δ ~0.22), while distinct same-type concepts (P/NP/…)
+# are SIMILAR (~0.85) — so member-vs-member cosine is the WRONG instrument for over-merge (empirically
+# inverted: TM 0.218 < the P/NP bundle 0.227). The real precision floor is the ATOMICITY type-guard
+# (_GROUP_STANDALONE: a member that is a named algorithm/problem/theorem/complexity-class dissolves the
+# umbrella). This floor is demoted to a near-zero backstop that only rejects a literally structureless
+# chain (random-pair baseline), set BELOW the legitimate heterogeneous minimum so it never kills a real model.
+GROUP_MIN_COS_FLOOR = 0.15
+# Fragment-demote backstop, same logic as GROUP_MIN_COS_FLOOR: fragment↔parent cosine is a BAD
+# fragment detector (measured, Markdown run: wrong demotes Blockzitate→Codeblöcke 0.353 and
+# Zeichenkodierung→Überschriften 0.640 sit ABOVE any usable floor, while true NP proof-gadget
+# demotes αu-Variablen→Cook/Levin 0.172 sit low). So this only vetoes judge/panel demotes with
+# NO containment match whose pair is literally structureless (Emoji→Tabelle 0.136).
+FRAGMENT_MIN_COS = 0.15
+
+# Caps for concurrent CLI agent processes (env-overridable). Two nested limits, both always active:
+# a per-topic cap and a global cap across all topics. Defaults 10/10 = previous behavior (global
+# dominates). Locally raise the global cap to actually parallelize across topics (per-topic stays 10).
+# Own lane for interactive calls (chat, elements) so they don't hang behind running writers.
+MAX_CONCURRENT_AGENTS = int(os.getenv("MAX_CONCURRENT_AGENTS", "16"))                      # global, all topics
+# Per-topic higher than the process cap: it is SHARED between process and API tier — at 12 a
+# single-topic run (the normal case) would never benefit from the cheap API tier.
+MAX_CONCURRENT_AGENTS_PER_TOPIC = int(os.getenv("MAX_CONCURRENT_AGENTS_PER_TOPIC", "24"))  # per topic
+# Direct-API text calls (agents._run_text_api): ~0 RAM, only network — own, higher global cap.
+MAX_CONCURRENT_API_AGENTS = int(os.getenv("MAX_CONCURRENT_API_AGENTS", "28"))
+MAX_CONCURRENT_INTERACTIVE = 8
+
+# RAM guard for opencode spawns: below this free share (MemAvailable/MemTotal in %) new
+# processes wait instead of starting (agents._ram_gate). 0 = off.
+RAM_MIN_FREE_PCT = int(os.getenv("RAM_MIN_FREE_PCT", "20"))
+
+# Grace window of the consensus races (blocks, guide, OnePager): after the first
+# valid result the remaining agents may still become done for this many seconds
+# (kill only once the minimum is already in).
+CONSENSUS_GRACE = 300
+
+# Cap of the clarification and check loops: maximum rounds until everything must be
+# decided. In the last round the mapping agent MUST decide every entry;
+# check loops leave any remaining objections standing after that.
+CONSENSUS_MAX_ROUNDS = 3
+
+# Crawler triage (content/noise) — deterministic rule filter instead of an LLM.
+# Match: substring (lowercase) against URL AND file name. Order: keep > noise > min_chars > keep.
+# Just add special rules here.
+CRAWL_KEEP_PATTERNS = ["learn-unit", "learn-course"]            # always content
+CRAWL_NOISE_PATTERNS = [                                         # clearly off-topic → out
+    "clubs", "events", "podcasts", "resources", "-u-",
+    "academy", "pricing", "/plans", "career", "newsletter", "impressum", "login",
+]
+CRAWL_MIN_CHARS = 400                                            # too little text → out
+
+# LLM topic relevance gate (after the rule filter): per content page yes/no against the spec.
+# Separates the subject area (e.g. backend vs frontend), which the global CRAWL_* rules can't.
+QUELLE_RELEVANZ_CHUNK = 12       # pages per rater package (small, since a snippet ships per page)
+QUELLE_RELEVANZ_SNIPPET = 800    # body characters per page in the prompt (URL is the primary signal)
+
+# QA gate: after the inventory phase an automatic QA run scores the blocks; below the
+# threshold the flow PAUSES before board 2 burns tokens (frontend offers force-continue).
+QA_GATE_NOTE = 9.5   # 0 = gate off; quota-based, so the tolerated finding count scales with topic size
+QA_GATE_LLM = True   # include the LLM samples (Echtheit/Dubletten) in the gate run
+
+# Inline evidence for judge agents: corpus excerpts go INTO the prompt instead of letting
+# every judge re-search the source folder (measured: ~10 tool turns/judge, 82 % of the
+# run's tokens were cache reads from those loops).
+EVIDENCE_BUDGET_CHARS = 48_000   # max excerpt characters per judge prompt
+EVIDENCE_CTX_LINES = 15          # context lines around a cited source position (facts check)
+
+# ── Pipeline tuning (zentral, tunebar via CREATOR_PARAMS — siehe Override-Hook am Datei-Ende;
+# Registry mit Suchraum: backend/train_params.py). QA-/Detektor-Konstanten bleiben bewusst in
+# qa.py/guide_qa.py — die Messlatte darf nie Teil des Suchraums sein. ─────────────────────────
+SUBBLOCK_CHUNK = 10        # subblock finder: 1 agent per ~10 blocks, capped
+SUBBLOCK_MAX = 40          # chunk cap
+LEVEL_CHUNK = 100          # classifying is cheap → large packages
+RESEARCH_BATCH = 20        # crawl pages per batch
+RESEARCH_READERS = 2       # reader agents per batch/section (consensus ≥2)
+RESEARCH_THEMA_AGENTS = 5  # web mode (source "thema")
+RESEARCH_SECTION_CHARS = 12000  # uni/projekt section size (lost-in-the-middle guard)
+RESEARCH_RUNTIME = 900     # one research agent, one round (tail ingests live)
+CONSOLIDATION_CHUNK = 600  # up to here ONE global judge (fallback path)
+DEDUP_PAIR_FLOOR = 0.6     # min cosine for a candidate pair
+DEDUP_PAIRS_CHUNK = 40     # pairs per judge package
+DEDUP_TITLE_AUTO = 0.95    # near-identical TITLE cosine → merge without judge
+DEDUP_GLOBAL_FLOOR = 0.65  # global post-naming dedup candidate floor
+FILTER_CHUNK = 35          # blocks per judge in the degrade pass
+QUESTION_CHUNK_SUBS = 25   # target relevant subs per question chunk (LPT)
+QUESTION_MAX_ROUNDS = 3    # catch-up rounds for subs without a pattern
+FACTS_CHUNK_SUBS = 10      # facts extraction chunk (chunk count = parallelism)
+ARTEFACT_CHUNK_SUBS = 25   # flashcards/examples bulk chunk
+FACTS_CHECK_PANEL = 3      # judges per facts-check chunk (majority)
+CONSOLIDATION_PANEL = 3    # mapping judges per chunk
+SUBBLOCK_PANEL = 3         # judges in the subblock clarification
+# Board 2, verschmolzene Calls (block_calls.py): Panel-Größen der neuen Struktur.
+# Konsens braucht ≥2 unabhängige Nennungen bzw. Einstimmigkeit — 2 ist das Minimum,
+# 3 kauft Robustheit für +50 % Tokens auf dem jeweiligen Segment.
+GEN_PANEL = 2              # unabhängige Generator-Calls pro Block
+VERIFY_PANEL = 2           # unabhängige Prüfer-Calls pro Block (+ Ersatz bei 1 Ausfall)
+ART_SPLIT_SUBS = 20        # Artefakt-Generator splittet ab so vielen Subs in 2 parallele Calls
+FILTER_RECHECK_PANEL = 3   # judges in the survivor-recheck
+GATE_FIX_MIN = 3           # fact-gate: unbelegt-claims below min(this, relevante Subs) → log only (falsch fixt immer)
+WRITER_SPLIT_SUBS = 30     # guide writer splits sections above this sub count
+KANBAN_BATCH = 5           # cards a worker pulls per micro-batch
+MAX_CARD_RETRIES = 3       # failures per card → dead-letter
+RETRY_BACKOFF = 30.0       # base seconds; backoff = base · 2^(retries-1)
+MAX_RESTARTS = 2           # agent restart cap per race slot
+# Stall-Hedge: läuft ein Race-Slot so lange ohne Ergebnis, startet parallel ein Zwilling
+# (key -h), der erste valide gewinnt. Gemessen (kanban-smoke): 4 Panel-Stalls à 160–230 s
+# verlängerten den kritischen Pfad um ~5 min. UNTERGRENZE: effektiv gilt
+# max(HEDGE_NACH_S, halbes Call-Timeout) — pauschale 90 s hedgten jeden gesunden
+# Fix-/Gate-Call (die laufen normal 110–135 s). 0 = aus.
+HEDGE_NACH_S = 90
+JUDGE_CHUNK = 40           # repair: findings per judge call
+EVIDENCE_PER_BLOCK = 6000  # repair: excerpt chars per fremd candidate
+ABSCHLUSS_QA_LLM = 1       # 0 = Abschluss-QA ohne LLM-Judges (Training misst selbst; spart Minuten)
+
+# Timeouts per agent step: (base seconds, seconds per block/section).
+# Applies equally to all providers — whoever is too slow gets restarted or overtaken.
 TIMEOUTS = {
-    "recherche":     (1800, 0),   # fix 30 min
-    "auswahl":       (600, 10),
-    "auswahl_check": (300, 2),
-    "ergaenzung":    (900, 0),   # Themenfeld-Ergänzung bei Projekten (Web-Recherche)
-    "guide_auswahl": (300, 5),    # pro Baustein im Inventar
-    "guide_check":   (300, 2),    # Auswahl-/Gliederungs-Prüfung (nur Titellisten)
+    "research":     (900, 0),    # p95 measured 125 s (web mode); uni/link sections need headroom
+    "research_mapping": (600, 3),  # n = pre-merged entries
+    "selection_mapping":   (600, 2),  # n = remaining entries (block inventory)
+    "ergaenzung":    (600, 0),   # subject-field extension for projects (web research)
     "plan":          (300, 5),
-    "writer":        (600, 120),  # pro Section im Chunk
-    "lese_check":    (300, 10),   # pro Section im Paket
-    "onepager_recherche": (900, 0),
-    "onepager_bauen":     (300, 0),
-    "onepager_verify":    (300, 0),
+    "plan_judge":    (600, 5),    # judge reads up to 5 outlines, n = sections
+    "content":        (450, 30),   # facts find/erg/fix — p95 measured 241 s (was 600+90n)
+    # Judge caps tightened 2026-07-04: judge p50 is 6–72 s; a stalled call burns the whole
+    # cap and its retry heals in seconds — the old 300 s base tripled the stall cost.
+    "content_check":  (150, 8),   # content exam per block in the package
+    "subblock":       (400, 15),  # finder round — p95 measured 124 s (was 900+45n)
+    "subblock_check": (150, 10),  # judge decides contested subblocks in the chunk
+    "konsolidierung": (300, 20),  # consolidation judge sees ALL subs with key points
+    "level":             (300, 10),  # classify subblocks per chunk
+    "level_check":       (150, 8),  # judge decides contested levels in the chunk
+    "relevance":          (300, 10),  # subblocks relevant/peripheral per chunk
+    "relevance_check":    (150, 8),  # judge decides contested relevance in the chunk
+    "question_pattern":      (300, 15),  # question patterns per block (subblocks × types)
+    "question_pattern_check": (150, 8),  # critic cleans up the pattern table per block
+    # Board 2, verschmolzene Calls: größere Outputs pro Call, dafür wenige Segmente
+    "generate":       (450, 0),   # Subs+Facts+Level in einem (Sub-Zahl vorab unbekannt)
+    "verify":         (300, 10),  # Audit über alle Subs (n = Subs), key points gekappt
+    "fix":            (300, 15),  # Korrekturen + Lücken (n = Aufträge)
+    "artefakt":       (450, 15),  # Fragen+Karten+Beispiele (n = Subs)
+    "artefakt_check": (200, 8),   # Beispiel-Verifikation + Fragen-Kritik (n = Subs)
+    "writer":        (450, 60),   # per section — split keeps sections ≤30 subs
+    "lese_check":    (300, 10),   # per section in the package
+    # guide board (per card = one block)
+    "lernziele":     (300, 5),    # backward-design objectives per block
+    "fakten_gate":   (600, 5),    # CoVe claim check per block
+    "coverage":      (300, 5),    # objective↔section mapping per block
 }
 
-# Auswahl-Auftrag je Format: (Mindest-Anteil, Maximal-Anteil, Mindestanzahl, Zweck).
-FORMAT_ANTEIL = {
-    "MiniGuide": (0.05, 0.10, 8, "einen kompakten Anfänger-Guide — der schnelle Einstieg ins Thema"),
-    "Guide":     (0.25, 0.35, 20, "einen ausführlichen Anfänger-Guide — ein solides Fundament im Thema"),
-    "FullGuide": (0.90, 1.00, 0, "einen Komplett-Guide — das ganze Thema"),
+# Purpose per format — flows into the outline judge (what the guide should achieve).
+# German strings: these are inserted verbatim into the judge prompt → kept German on purpose.
+FORMAT_PURPOSE = {
+    "Guide": "einen fokussierten Guide — alles Relevante ohne Randthemen",
+    "FullGuide": "einen Komplett-Guide — das ganze Thema inkl. Randthemen",
+    "Rest": "einen Ergänzungs-Guide — nur die Randthemen",
 }
 
-# Provider-Stacks: komplett unabhängig, einer kann jederzeit entfernt werden.
-# Rollen: "quick" = Massenarbeit (Recherche, Einordnung),
-#         "fast"  = Urteilsaufgaben mit kleinem Output (Auswahl, Final, OnePager, Chat),
-#         "guide" = große Generierung (Plan, Writer).
-DEFAULT_PROVIDER = "claude"
+# Provider stacks: completely independent, any one can be removed at any time.
+# Roles: "quick" = bulk work (research, classification),
+#        "fast"  = interaction + voting (chat, exam, clarification, elements),
+#        "judge" = mapping/judge/check agents — cold (low temperature,
+#                  no thinking) for stable verdicts; Claude/local map to "fast",
+#        "guide" = large generation (proposals, writer).
+# Kein Provider-Default im Code (Betreiber-Vorgabe): die .env entscheidet.
+DEFAULT_PROVIDER = os.getenv("DEFAULT_PROVIDER", "")
+if not DEFAULT_PROVIDER:
+    raise RuntimeError("DEFAULT_PROVIDER fehlt in der .env (z. B. DEFAULT_PROVIDER=minimax)")
 PROVIDERS = {
     "claude": {
         "cli": "claude",
         "guide": "claude-opus-4-8[1m]",
         "fast": "claude-sonnet-4-6",
+        "judge": "claude-sonnet-4-6",  # the CLI has no temperature setting
         "quick": "claude-sonnet-4-6",
-        "env_key": None,  # Auth via CLAUDE_CODE_OAUTH_TOKEN oder ~/.claude
+        "env_key": None,  # auth via CLAUDE_CODE_OAUTH_TOKEN or ~/.claude
     },
+    # "minimax-kalt/…" is NOT its own stack, just an opencode provider entry
+    # (dev-ops/opencode.json) with low temperature; M3 there without thinking.
     "minimax": {
         "cli": "opencode",
         "guide": "minimax/MiniMax-M3",
-        "fast": "minimax/MiniMax-M2.7-highspeed",
-        "quick": "minimax/MiniMax-M2.7-highspeed",
-        "env_key": "MINIMAX_API_KEY",
-    },
-    # Wie "minimax", aber Chat/Elemente (Rolle "fast") laufen auf M3 OHNE Thinking.
-    # M2.x kann Thinking nicht abschalten — nur M3 respektiert thinking:disabled.
-    # guide/quick bleiben identisch zur Thinking-Variante.
-    "minimax-direkt": {
-        "cli": "opencode",
-        "guide": "minimax/MiniMax-M3",
-        "fast": "minimax-direkt/MiniMax-M3",
+        "fast": "minimax-kalt/MiniMax-M2.7-highspeed",
+        "judge": "minimax/MiniMax-M3",  # native route — the kalt endpoint stalled 20 % of
+                                        # judge calls to the timeout cap (516/2590, 2026-07-04)
         "quick": "minimax/MiniMax-M2.7-highspeed",
         "env_key": "MINIMAX_API_KEY",
     },
@@ -67,8 +286,62 @@ PROVIDERS = {
         "cli": "opencode",
         "guide": "ollama/qwen3.6:27b",
         "fast": "ollama/qwen3.5:9b",
+        "judge": "ollama/qwen3.5:9b",
         "quick": "ollama/qwen3.5:9b",
         "env_key": None,
-        "check_url": "http://localhost:11434/api/tags",  # Ollama erreichbar?
+        "check_url": "http://localhost:11434/api/tags",  # Ollama reachable?
     },
 }
+
+# Role routing: by DEFAULT the run's provider (the UI choice) handles ALL roles —
+# the role only picks the model WITHIN that stack (PROVIDERS[stack][role]).
+# Opt-in cross-provider mixing via env: ROLE_JUDGE=claude routes every judge call
+# to the claude stack regardless of the UI choice ("provider:model" pins a model).
+ROLE_ROUTING = {
+    "quick": os.getenv("ROLE_QUICK", ""),
+    "judge": os.getenv("ROLE_JUDGE", ""),
+    "guide": os.getenv("ROLE_GUIDE", ""),
+    "fast":  os.getenv("ROLE_FAST", ""),
+}
+
+
+def resolve_role(run_provider: str, role: str) -> tuple[str, str]:
+    """→ (provider, model) for one agent call. Pure routing, no availability check —
+    the caller (agents.run_agent) falls back to run_provider if the target is unavailable."""
+    target = ROLE_ROUTING.get(role, "") or run_provider
+    provider, _, model = target.partition(":")
+    if provider not in PROVIDERS:
+        provider, model = run_provider, ""
+    if not model:
+        model = PROVIDERS.get(provider, {}).get(role, "")
+    return provider, model
+
+
+# ── Trainings-Override: CREATOR_PARAMS (JSON-Dict im ENV) überschreibt gleichnamige
+# Tuning-Konstanten oben — pro Prozess-Start (der Trainer startet je Trial einen Subprozess;
+# Module binden die Werte beim Import). TIMEOUTS-Einträge via "TIMEOUT_<step>_base"/"_per".
+def _apply_param_overrides() -> None:
+    raw = os.getenv("CREATOR_PARAMS")
+    if not raw:
+        return
+    import json as _json
+    try:
+        overrides = _json.loads(raw)
+    except ValueError:
+        raise SystemExit(f"CREATOR_PARAMS ist kein gültiges JSON: {raw[:80]}")
+    g = globals()
+    for key, val in overrides.items():
+        if key.startswith("TIMEOUT_"):
+            rest = key[len("TIMEOUT_"):]
+            step, _, part = rest.rpartition("_")
+            if step in TIMEOUTS and part in ("base", "per"):
+                base, per = TIMEOUTS[step]
+                TIMEOUTS[step] = (val, per) if part == "base" else (base, val)
+                continue
+            raise SystemExit(f"CREATOR_PARAMS: unbekannter Timeout-Schlüssel {key}")
+        if key not in g or not isinstance(g[key], (int, float)) or isinstance(g[key], bool):
+            raise SystemExit(f"CREATOR_PARAMS: unbekannter/nicht-numerischer Parameter {key}")
+        g[key] = type(g[key])(val)
+
+
+_apply_param_overrides()

backend/crawl.py

@@ -0,0 +1,148 @@
+"""Bounded domain crawler for link sources — renders JS via Playwright (Chromium).
+
+Loads pages + PDFs starting from a start URL — ONLY the same domain, limited depth
+and page count. HTML pages are rendered in a headless browser (needed for SPAs), then
+links + text are pulled from the finished DOM. PDFs are loaded directly as bytes.
+Deterministic, bounded; runs via asyncio.to_thread (sync API, no event loop).
+"""
+
+import hashlib
+import logging
+import re
+from pathlib import Path
+from urllib.parse import urldefrag, urlparse
+from urllib.request import Request, urlopen
+
+from fsutil import atomic_write_text
+
+log = logging.getLogger("creator.crawl")
+
+MAX_DEPTH = 3
+MAX_PAGES = 500
+PAGE_TIMEOUT = 30         # seconds per page (render or PDF download)
+CRAWL_SETTLE_MS = 3000    # capped settle after domcontentloaded (SPA render); no 30s networkidle hang
+MAX_BYTES = 10_000_000    # 10 MB cap per PDF
+_UA = "Mozilla/5.0 (creator-lernbot)"
+
+
+def _fetch_bytes(url: str) -> bytes | None:
+    """Load PDF bytes via urllib (no rendering needed). None on error/too large."""
+    try:
+        req = Request(url, headers={"User-Agent": _UA})
+        with urlopen(req, timeout=PAGE_TIMEOUT) as resp:
+            data = resp.read(MAX_BYTES + 1)
+        return None if len(data) > MAX_BYTES else data
+    except Exception as e:
+        log.debug("crawl: PDF fetch failed %s: %s", url, e)
+        return None
+
+
+def _name(url: str, ext: str) -> str:
+    h = hashlib.md5(url.encode("utf-8")).hexdigest()[:8]
+    slug = re.sub(r"[^a-zA-Z0-9]+", "-", urlparse(url).path).strip("-")[:60] or "index"
+    return f"{h}-{slug}{ext}"
+
+
+def _is_pdf(url: str) -> bool:
+    return url.lower().split("?")[0].rstrip("/").endswith(".pdf")
+
+
+def _scope_prefix(start_url: str) -> str:
+    """First non-empty path segment of the start URL as the crawl scope, e.g.
+    `/learn/path/x` → `/learn`. No path segment → `""` (whole domain, no narrowing)."""
+    seg = [s for s in urlparse(start_url).path.split("/") if s]
+    return f"/{seg[0]}" if seg else ""
+
+
+def _in_scope(url: str, prefix: str) -> bool:
+    """Segment-exact prefix match (no `/learn` ⊃ `/learning-x`). Empty prefix → everything allowed."""
+    if not prefix:
+        return True
+    p = urlparse(url).path
+    return p == prefix or p.startswith(prefix + "/")
+
+
+def _page_text(page) -> str:
+    """Main text of the rendered page — nav/footer/boilerplate removed via trafilatura.
+    Falls back to the raw body text when extraction is empty/too short (non-article pages)."""
+    try:
+        from trafilatura import extract  # lazy: the backend starts even without the package
+        text = extract(page.content(), include_comments=False, include_tables=True) or ""
+    except Exception:
+        text = ""
+    if len(text.strip()) >= 200:
+        return text.strip()
+    try:
+        return page.inner_text("body").strip()
+    except Exception:
+        return text.strip()
+
+
+def crawl(start_url: str, target: Path, *, max_depth: int = MAX_DEPTH, max_pages: int = MAX_PAGES, cancelled=None) -> int:
+    """Crawl from start_url (same domain only), render JS and store pages/PDFs in `target`.
+
+    BFS up to `max_depth` / `max_pages`. Errors on individual pages are skipped.
+    Writes a `.done` marker at the END; an abort (`cancelled()` → True) omits it,
+    so a restart crawls again. Returns the number of saved sources.
+    """
+    # Lazy: this way the backend starts even without Playwright installed; only crawling then fails.
+    from playwright.sync_api import sync_playwright
+
+    target.mkdir(parents=True, exist_ok=True)
+    domain = urlparse(start_url).netloc
+    prefix = _scope_prefix(start_url)  # only follow links under this path segment
+    seen: set[str] = set()
+    queue: list[tuple[str, int]] = [(urldefrag(start_url)[0], 0)]
+    saved = 0
+
+    with sync_playwright() as pw:
+        browser = pw.chromium.launch(args=["--no-sandbox"])  # non-root (Docker user app)
+        page = browser.new_page(user_agent=_UA)
+        try:
+            while queue and saved < max_pages:
+                if cancelled and cancelled():
+                    return saved  # abort → NO .done marker → restart crawls again
+                url, depth = queue.pop(0)
+                if url in seen:
+                    continue
+                seen.add(url)
+
+                # PDFs need no rendering — load directly.
+                if _is_pdf(url):
+                    data = _fetch_bytes(url)
+                    if data:
+                        p = target / _name(url, ".pdf")
+                        if not p.exists():
+                            p.write_bytes(data)
+                        saved += 1
+                    continue
+
+                try:
+                    page.goto(url, wait_until="domcontentloaded", timeout=PAGE_TIMEOUT * 1000)
+                except Exception as e:
+                    log.debug("crawl: goto incomplete %s: %s", url, e)  # still try to read the content
+                try:
+                    page.wait_for_load_state("networkidle", timeout=CRAWL_SETTLE_MS)
+                except Exception:
+                    pass  # an SPA with constant traffic never reaches idle → continue after settle, no 30s hang
+                text = _page_text(page)  # main text, nav/footer removed (fallback: raw body)
+                if text:
+                    atomic_write_text(target / _name(url, ".txt"), f"QUELLE: {url}\n\n{text}")
+                    saved += 1
+                if depth < max_depth:
+                    try:
+                        hrefs = page.eval_on_selector_all("a[href]", "els => els.map(e => e.href)")
+                    except Exception:
+                        hrefs = []
+                    for href in hrefs:
+                        nxt = urldefrag(href)[0]
+                        if (nxt.startswith(("http://", "https://"))
+                                and urlparse(nxt).netloc == domain and _in_scope(nxt, prefix)
+                                and nxt not in seen):
+                            queue.append((nxt, depth + 1))
+        finally:
+            browser.close()
+
+    (target / ".done").write_text("ok", encoding="utf-8")  # ran through cleanly
+    log.info("crawl %s → %d sources in %s", start_url, saved, target)
+    return saved

backend/embedding.py

@@ -0,0 +1,123 @@
+"""Semantic embedding clustering for block consolidation.
+
+Mean-pool embeddings of a multilingual sentence model build GLOBAL candidate
+clusters via cosine blocking + union-find (no chunk loss). Safe pairs (similarity
+≥ HARD) are merged without an LLM; borderline pairs in the band [BAND_LOW, HARD) are
+handed by the caller to an LLM judge for a yes/no decision. If `transformers`/`torch`
+are missing or the model won't load → `embed_sims()` returns `None`, and the caller
+falls back to the old panel-judge path (silent deactivation, like the readability gate).
+
+CPU is enough; the caller wraps the blocking inference in `asyncio.to_thread`.
+`numpy` comes in transitively via torch (deliberately not in requirements.txt, like torch).
+"""
+
+import logging
+
+import numpy as np
+
+from config import EMBEDDING_AKTIV, EMBEDDING_MODELL, EMBEDDING_BLOCK_FLOOR, EMBEDDING_BLOCK_CAP
+
+log = logging.getLogger("creator.embedding")
+
+_model_cache = None       # (tokenizer, model, torch) — singleton
+_load_attempt = False     # already tried to load?
+
+EMBEDDING_BATCH = 32      # inference batch size (CPU)
+EMBEDDING_MAX_LEN = 128   # title + short description are short → a small truncation cap suffices
+
+
+def _model():
+    """Load the model once. None = clustering off (disabled or load error)."""
+    global _model_cache, _load_attempt
+    if _load_attempt:
+        return _model_cache
+    _load_attempt = True
+    if not EMBEDDING_AKTIV:
+        return None
+    try:
+        import torch
+        from transformers import AutoModel, AutoTokenizer
+        tok = AutoTokenizer.from_pretrained(EMBEDDING_MODELL)
+        model = AutoModel.from_pretrained(EMBEDDING_MODELL)
+        model.eval()
+        _model_cache = (tok, model, torch)
+        log.info("embedding model loaded: %s", EMBEDDING_MODELL)
+    except Exception as e:
+        log.warning("embedding clustering disabled (model not loadable): %s", e)
+        _model_cache = None
+    return _model_cache
+
+
+def available() -> bool:
+    """True if the model could be loaded. Loads on the first call (blocking)."""
+    return _model() is not None
+
+
+def embed(texts: list[str]) -> "np.ndarray | None":
+    """Texts → (n, d) L2-normalized, mean-pooled embeddings. None = model off."""
+    if _model() is None:
+        return None
+    tok, model, torch = _model_cache
+    out = []
+    for i in range(0, len(texts), EMBEDDING_BATCH):
+        batch = texts[i:i + EMBEDDING_BATCH]
+        enc = tok(batch, return_tensors="pt", truncation=True, max_length=EMBEDDING_MAX_LEN, padding=True)
+        with torch.no_grad():
+            hidden = model(**enc).last_hidden_state               # (b, t, d)
+        mask = enc["attention_mask"].unsqueeze(-1).type_as(hidden)
+        vec = (hidden * mask).sum(1) / mask.sum(1).clamp(min=1e-9)  # mean-pool without padding
+        vec = torch.nn.functional.normalize(vec, p=2, dim=1)       # L2 → cosine = dot product
+        out.append(vec.cpu().numpy())
+    return np.vstack(out).astype(np.float32)
+
+
+def _find(parent: list[int], x: int) -> int:
+    while parent[x] != x:
+        parent[x] = parent[parent[x]]      # Pfad-Kompression
+        x = parent[x]
+    return x
+
+
+def _union(parent: list[int], a: int, b: int) -> None:
+    ra, rb = _find(parent, a), _find(parent, b)
+    if ra != rb:
+        parent[max(ra, rb)] = min(ra, rb)  # smallest index = root (deterministic)
+
+
+def embed_sims(texts: list[str]):
+    """Texts → (n, n) cosine matrix · None = model not available (fallback)."""
+    embs = embed(texts)
+    if embs is None:
+        return None
+    return embs @ embs.T                    # (n, n) cosine, float32 (~2 MB at n=700)
+
+
+def capped_blocks(sims, floor: float | None = None, cap: int | None = None) -> list[list[int]]:
+    """Coarse similarity blocks for the LLM — high recall, but size-capped.
+
+    Greedy: all pairs with cosine ≥ `floor` in descending cosine order; two blocks are merged
+    only if the resulting block stays ≤ `cap`. Prevents the giant component (pure threshold
+    blocking would otherwise chain almost everything together) and keeps the LLM lists short.
+    → list of blocks (index lists), each node in exactly one block.
+    """
+    fl = EMBEDDING_BLOCK_FLOOR if floor is None else floor
+    cp = EMBEDDING_BLOCK_CAP if cap is None else cap
+    n = len(sims)
+    parent = list(range(n))
+    size = [1] * n
+    if n >= 2:
+        iu = np.triu_indices(n, k=1)
+        s = sims[iu]
+        kept = np.where(s >= fl)[0]
+        # highest cosine first → the tightest pairs form blocks first
+        for k in kept[np.argsort(-s[kept])]:
+            i, j = int(iu[0][k]), int(iu[1][k])
+            ri, rj = _find(parent, i), _find(parent, j)
+            if ri != rj and size[ri] + size[rj] <= cp:
+                _union(parent, i, j)
+                r = _find(parent, i)
+                size[r] = size[ri] + size[rj]
+    blocks: dict[int, list[int]] = {}
+    for i in range(n):
+        blocks.setdefault(_find(parent, i), []).append(i)
+    return list(blocks.values())

backend/fake_agents.py

@@ -0,0 +1,329 @@
+"""Deterministischer Agenten-Ersatz für E2E-Tests: beantwortet run_agent-Aufrufe ohne LLM.
+
+Eine `Welt` beschreibt das Thema (Blöcke → Subs → Facts …); `respond()` routet per
+agent_key-Muster und liefert (rc, stdout, stderr) wie ein echter Agent — files-Agenten
+schreiben die out_path-Datei aus dem Prompt, none-Agenten antworten als Text (der
+Engine-Sink parst/persistiert). Damit laufen ALLE echten Schichten (_race, Quorum,
+Retry, Panels, Producer, QA-Gate) in Sekunden.
+
+Störungen sind deterministisch: `Welt.stoerungen` matcht agent_keys per Regex und
+liefert n-mal einen Fehler / kaputtes JSON / eine feste Antwort (z. B. Dissens).
+
+Aktivierung: pytest-Fixture `fake_welt` (tests/conftest.py) oder ENV CREATOR_FAKE_AGENTS=1
+(echter Server, Sekunden-Smoke im Frontend).
+"""
+
+import json
+import re
+from pathlib import Path
+
+_PATH_RE = re.compile(r"(/\S+\.(?:json|md))")
+_NUM_RE = re.compile(r"^\s*(\d+)[.)]\s+(.*\S)", re.MULTILINE)
+_SUBLIST_RE = re.compile(r"^- (?:\[(\w+)\] )?(.+\S)\s*$", re.MULTILINE)
+_ZIEL_RE = re.compile(r"\(([a-z]\d+)\)")
+_PAIR_RE = re.compile(r"^(\d+)\.\s*\nA: \[Block: (.*?)\] (.*?)\n", re.MULTILINE)
+
+
+def _norm(s: str) -> str:
+    return " ".join((s or "").casefold().split())
+
+
+class Welt:
+    """Deterministisches Themen-Modell. bloecke: {titel: {"beschreibung": str,
+    "subs": [titel]}}; optionale Regeln steuern Konsolidierung/Cross-Block."""
+
+    def __init__(self, bloecke: dict | None = None, *, gruppen: list | None = None,
+                 kataloge: list | None = None, stoerungen: list | None = None):
+        self.bloecke = bloecke if bloecke is not None else standard_bloecke()
+        self.gruppen = gruppen or []      # [(haupt_titel, [weitere_titel])] → In-Block-Fold
+        self.kataloge = kataloge or []    # [(katalog_titel, [mitglieder_titel])]
+        self.stoerungen = [dict(s, rest=int(s.get("mal", 1))) for s in (stoerungen or [])]
+        self.calls: list[str] = []        # Auditspur: jeder agent_key in Reihenfolge
+
+    # ── Nachschlagen ────────────────────────────────────────────────────────────────
+    def _alle_subs(self) -> dict[str, str]:
+        """sub_norm → sub_titel über alle Blöcke (inkl. Katalog-Titel)."""
+        out = {}
+        for b in self.bloecke.values():
+            for s in b["subs"]:
+                out[_norm(s)] = s
+        for kt, _m in self.kataloge:
+            out[_norm(kt)] = kt
+        return out
+
+    def _bloecke_im_prompt(self, prompt: str) -> list[str]:
+        return [t for t in self.bloecke if t in prompt]
+
+    def _subs_im_prompt(self, prompt: str) -> list[str]:
+        gefunden = [s for s in self._alle_subs().values() if s in prompt]
+        return gefunden
+
+    # ── Störungen ───────────────────────────────────────────────────────────────────
+    def _stoerung(self, agent_key: str):
+        for s in self.stoerungen:
+            if s["rest"] > 0 and re.search(s["muster"], agent_key):
+                s["rest"] -= 1
+                return s
+        return None
+
+    # ── Haupteinstieg ──────────────────────────────────────────────────────────────
+    def respond(self, agent_key: str, prompt: str, capabilities: str) -> tuple[int, str, str]:
+        self.calls.append(agent_key)
+        if (s := self._stoerung(agent_key)):
+            if s["modus"] == "fehler":
+                return 1, "", "fake-stoerung"
+            if s["modus"] == "garbage":
+                return self._liefern(prompt, '{"kaputt": ')
+            if s["modus"] == "antwort":
+                return self._liefern(prompt, s["antwort"])
+        text = self._antwort(agent_key, prompt)
+        if text is None:
+            return 1, "", f"fake: kein Handler für {agent_key}"
+        return self._liefern(prompt, text)
+
+    @staticmethod
+    def _liefern(prompt: str, text: str) -> tuple[int, str, str]:
+        """files-Agenten schreiben die out_path-Datei aus dem Prompt; none-Agenten
+        antworten als Text. Wir tun einfach BEIDES — steht ein Pfad im Prompt, wird
+        er geschrieben (dann liest das payload die Datei), und stdout trägt den Text
+        (dann parst ihn der Sink). Ein Weg von beiden greift immer."""
+        if (m := _PATH_RE.search(prompt)):
+            p = Path(m.group(1))
+            try:
+                p.parent.mkdir(parents=True, exist_ok=True)
+                p.write_text(text, encoding="utf-8")
+            except OSError:
+                pass
+        return 0, text, ""
+
+    # ── Antwort-Generatoren je Key-Muster ──────────────────────────────────────────
+    def _antwort(self, key: str, prompt: str) -> str | None:  # noqa: C901 — bewusst ein Router
+        j = json.dumps
+        # Board 1 / Inventar
+        if "-research-" in key:
+            zeilen = []
+            n = 1
+            for t, b in self.bloecke.items():
+                zeilen.append(f"{n}. {t} — {b['beschreibung']}")
+                n += 1
+            return "\n".join(zeilen)
+        if "-pair-" in key:
+            n = prompt.count("\nA: ") or 1
+            return j({"pairs": {str(i): "ja" for i in range(1, n + 1)}})
+        if "-dedup-" in key:
+            n = prompt.count("\nA: ") or 1
+            return j({"pairs": {str(i): "nein" for i in range(1, n + 1)}})
+        if "-clarify-" in key:
+            keep = [ln[2:] for ln in prompt.splitlines() if ln.startswith("- ")]
+            return j({"keep": keep, "rest": []})
+        if "-naming-" in key:  # deckt auch naming_check (gleicher Key)
+            return j({"best": 1})
+        if "-sanierung-" in key:  # Titel/Beschreibung unverändert zurück (Fake-Welt ist sauber)
+            t = re.search(r"^Title: (.+)$", prompt, re.M)
+            d = re.search(r"^Description: (.+)$", prompt, re.M)
+            beschr = (d.group(1).strip() if d else "")
+            if beschr == "(leer)":
+                beschr = "Beschreibung aus dem Material."
+            return j({"title": t.group(1).strip() if t else "", "description": beschr})
+        if "-filter-" in key:  # auch filter-recheck
+            return j({"fragments": {}, "drop": []})
+        if "-gruppierung-completion-" in key:
+            return j({"additions": []})
+        if "-gruppierung-" in key:
+            return j({"umbrellas": []})
+        if "-supplement-beleg" in key or "-anker-beleg-" in key:
+            nums = {m.group(1) for m in _NUM_RE.finditer(prompt)}
+            return j({"relevant": {k: "ja" for k in sorted(nums, key=int)} or {"1": "ja"}})
+        if "-supplement" in key:
+            return j({"blocks": []})
+        if "-source-relevance-" in key:
+            nums = {m.group(1) for m in _NUM_RE.finditer(prompt)}
+            return j({"relevant": {k: "ja" for k in sorted(nums, key=int)} or {"1": "ja"}})
+
+        # Board 2 / Artefakte (verschmolzene Calls, block_calls.py)
+        if "-sb-gen-" in key:
+            subs = []
+            for t in self._bloecke_im_prompt(prompt):
+                for s in self.bloecke[t]["subs"]:
+                    f = self._fakt(t, s)
+                    subs.append({"title": s, "level": "beginner", "relevance": "relevant",
+                                 **{k: f[k] for k in ("key_points", "prerequisites", "hurdles",
+                                                      "cited_facts", "example_idea")}})
+            return j({"subs": subs})
+        if "-sb-verify-" in key:
+            nummern = {_norm(m.group(2)): m.group(1) for m in _NUM_RE.finditer(prompt)}
+            gruppen = []
+            for haupt, weitere in self.gruppen:
+                h, w = nummern.get(_norm(haupt)), [nummern[_norm(x)] for x in weitere
+                                                   if _norm(x) in nummern]
+                if h and w:
+                    gruppen.append({"haupt": int(h), "weitere": [int(x) for x in w]})
+            kataloge = []
+            for kt, mitglieder in self.kataloge:
+                m = [int(nummern[_norm(x)]) for x in mitglieder if _norm(x) in nummern]
+                if len(m) >= 2:
+                    kataloge.append({"titel": kt, "mitglieder": m})
+            unsicher = {}
+            if (u := prompt.find("UNSICHER")) != -1:  # alle Unsicher-Nummern übernehmen
+                import re as _re
+                for m in _re.finditer(r"entries (\d+)–(\d+)", prompt[u:u + 200]):
+                    unsicher = {str(k): "ja" for k in range(int(m.group(1)), int(m.group(2)) + 1)}
+            return j({"gruppen": gruppen, "kataloge": kataloge, "fremd": [], "luecken": [],
+                      "uebernehmen": unsicher, "facts_probleme": [], "levels": {}, "relevanz": {}})
+        if "-sb-fix-" in key:
+            return j({"subs": []})
+        if "-sub-crossblock-" in key:
+            urteile = {}
+            for m in _PAIR_RE.finditer(prompt):
+                urteile[m.group(1)] = "a"  # identischer Text (nur so wird gepaart) → A behält
+            return j({"pairs": urteile or {"1": "nein"}})
+        if "-art-gen-" in key:
+            subs = self._subs_im_prompt(prompt)
+            t = (self._bloecke_im_prompt(prompt) or ["?"])[0]
+            return j({"pattern": [{"block": t, "subblock": s, "question": f"Was ist {s}?"} for s in subs],
+                      "cards": [{"block": t, "subblock": s, "question": f"F: {s}?", "answer": f"A: {s}"} for s in subs],
+                      "examples": [{"block": t, "subblock": s, "problem": f"Aufgabe zu {s}",
+                                    "steps": ["Schritt 1", "Schritt 2"], "result": "Ergebnis"} for s in subs]})
+        if "-art-check-" in key:
+            return j({"ok": True})
+        if "-outline-prereqs" in key:
+            return j({"prereqs": {}})
+        if "-outline-review" in key:
+            return j({"moves": {}})
+        if "-outline-" in key or key.endswith("-outline-judge"):
+            nums = sorted({int(m.group(1)) for m in _NUM_RE.finditer(prompt)}) or [1]
+            return j({"chapters": [{"title": "Kapitel 1", "numbers": nums}]})
+
+        # Guide-Board
+        if "-ziele-" in key:
+            ziele = [{"id": f"z{i}", "text": f"Verstehen von {s}", "sub": s}
+                     for i, s in enumerate(self._subs_im_prompt(prompt), 1)][:8]
+            return j({"ziele": ziele or [{"id": "z1", "text": "Grundlagen verstehen", "sub": ""}]})
+        if "-gfix-" in key:
+            return self._section_aus_prompt(prompt) or "<!-- section: X -->\nRepariert."
+        if "-pruef-" in key:  # verschmolzener Prüfer: Fakten + Coverage + Lesbarkeit
+            ids = sorted(set(_ZIEL_RE.findall(prompt)))
+            return j({"claims": [], "ziele": {z: True for z in ids}, "luecken": [],
+                      "ballast": [], "lese_probleme": []})
+        if "-w-" in key:
+            return self._writer_md(prompt)
+
+        # QA / Repair / Guide-QA (alle Text, _yesno_schema)
+        if key.startswith(("qa-guide-",)):
+            nums = {m.group(1) for m in _NUM_RE.finditer(prompt)}
+            return j({"relevant": {k: "nein" for k in sorted(nums, key=int)} or {"1": "nein"}})
+        if key.startswith(("qa-", "repair-")):
+            # Semantik je Template: Bausteine „ja" = echt; Dubletten/Lücken „nein" = kein Befund
+            wert = "ja" if ("bausteine" in key or "beleg" in key or "fremd" in key) else "nein"
+            nums = {m.group(1) for m in _NUM_RE.finditer(prompt)}
+            return j({"relevant": {k: wert for k in sorted(nums, key=int)} or {"1": wert}})
+        return None
+
+    # ── Bausteine der Antworten ─────────────────────────────────────────────────────
+    @staticmethod
+    def _fakt(block: str, sub: str) -> dict:
+        return {"block": block, "subblock": sub,
+                "key_points": [f"Kernaussage zu {sub}", f"Zweite Aussage zu {sub}"],
+                "prerequisites": "", "hurdles": "",
+                "cited_facts": [{"text": f"Beleg für {sub}", "source": "Fake-Quelle"}],
+                "example_idea": f"Beispiel zu {sub}"}
+
+    def _writer_md(self, prompt: str) -> str:
+        """Section im Marker-Format; Subs aus der SUBBLOCKS-Liste des Prompts
+        (`- [label] titel`), Länge je Sub im 150–1080-Rahmen."""
+        block = next(iter(self._bloecke_im_prompt(prompt)), None) or "Abschnitt"
+        subs = [(lv or "beginner", t) for lv, t in _SUBLIST_RE.findall(prompt)
+                if _norm(t) in self._alle_subs()]
+        if not subs:
+            subs = [("beginner", s) for s in self.bloecke.get(block, {}).get("subs", ["Inhalt"])]
+        kompakt = "\n".join(f"<!-- sub: {lv} | {t} -->\n- Merksatz zu {t}" for lv, t in subs)
+        prosa = "\n".join(f"<!-- sub: {lv} | {t} -->\n" + (f"Lehrtext über {t}. " * 12)
+                          for lv, t in subs)
+        return (f"<!-- kapitel: Kapitel 1 -->\n<!-- section: {block} -->\n"
+                f"<!-- compact -->\n{kompakt}\n<!-- ausführlich -->\n"
+                f"Einstieg in {block}.\n{prosa}")
+
+    @staticmethod
+    def _section_aus_prompt(prompt: str) -> str | None:
+        """Fix-Agenten geben die Section unverändert zurück (minimal-invasiv)."""
+        m = re.search(r"(<!--\s*(?:kapitel|section):.*)", prompt, re.DOTALL)
+        return m.group(1).strip() if m else None
+
+
+def standard_bloecke() -> dict:
+    """3 Blöcke; „Gemeinsamer Grundbegriff" liegt in Alpha UND Beta (Cross-Block-Fall)."""
+    return {
+        "Alpha-Konzept": {"beschreibung": "Das erste Grundkonzept",
+                          "subs": ["Definition Alpha", "Alpha Eigenschaften",
+                                   "Gemeinsamer Grundbegriff"]},
+        "Beta-Verfahren": {"beschreibung": "Das zentrale Verfahren",
+                           "subs": ["Beta Ablauf", "Beta Grenzen", "Gemeinsamer Grundbegriff"]},
+        "Gamma-Anwendung": {"beschreibung": "Praktische Anwendung",
+                            "subs": ["Gamma Praxisfall", "Gamma Werkzeuge"]},
+    }
+
+
+_WELT: Welt | None = None  # ENV-Modus (CREATOR_FAKE_AGENTS=1): eine Welt pro Prozess
+
+
+async def respond(agent_key: str, prompt: str, capabilities: str) -> tuple[int, str, str]:
+    global _WELT
+    if _WELT is None:
+        _WELT = Welt()
+    return _WELT.respond(agent_key, prompt, capabilities)
+
+
+def aktivieren(welt: Welt, setattr_fn=setattr) -> None:
+    """Alle Patches für einen Fake-E2E-Lauf (run_agent überall, Tempo-Bremsen raus,
+    Text-Identitäts-Embedding). pytest übergibt monkeypatch.setattr (auto-Rollback);
+    train_f0 nutzt den Default — der Prozess stirbt nach dem Lauf sowieso."""
+    import asyncio
+
+    import agents
+    import blocks
+    import board_artefacts as ba
+    import board_inventory as bi
+    import guide
+    import guide_board
+    import kanban
+    import pipeline
+    import qa
+    import repair
+
+    async def fake_run_agent(agent_key, prompt, timeout, provider="", role="fast",
+                             capabilities="none", lane="batch", scope=None, on_line=None, label=""):
+        return welt.respond(agent_key, prompt, capabilities)
+
+    for mod in (agents, pipeline, blocks, guide, repair):
+        setattr_fn(mod, "run_agent", fake_run_agent)
+    setattr_fn(blocks, "CONSENSUS_GRACE", 0)
+    setattr_fn(bi, "_QA_GATE_POLL", 0.05)
+    setattr_fn(kanban, "RETRY_BACKOFF", 0.05)
+    setattr_fn(guide_board, "READABILITY_ACTIVE", False)
+    setattr_fn(bi, "_ingest_lock", asyncio.Lock())
+
+    class _FakeEmb:  # identischer Text → cos 1.0, sonst 0.0 (deterministisch, ohne Modell)
+        @staticmethod
+        def available():
+            return True
+
+        @staticmethod
+        def embed(texts):
+            import numpy as np
+            uniq = {t: k for k, t in enumerate(dict.fromkeys(texts))}
+            arr = np.zeros((len(texts), max(len(uniq), 1)))
+            for r, t in enumerate(texts):
+                arr[r, uniq[t]] = 1.0
+            return arr
+
+        @staticmethod
+        def embed_sims(texts):
+            arr = _FakeEmb.embed(texts)
+            return arr @ arr.T
+
+    for mod in (blocks, ba, qa):
+        setattr_fn(mod, "embedding", _FakeEmb)
+
+    async def emb_ok(flow):  # Board-1-Vektorpfade aus — Judge-Wellen reichen
+        return False
+    setattr_fn(bi, "_emb_ok", emb_ok)

backend/fragen-vorrat-aak.md

@@ -0,0 +1,177 @@
+# Frage-Muster für Lern-Prüfung: aak
+
+---
+
+## BAUSTEIN: CliqueAndIndependentSet-Problem
+
+### Subbaustein: Independent Set: Knotenmenge ohne Kanten zwischen je zwei Knoten
+**Muster:** Was ist die formale Definition eines Independent Set in einem Graphen G = (V, E)?
+
+### Subbaustein: Komplementgraph (V, E) bildet IS und Clique aufeinander ab
+**Muster:** Wie hängt die Existenz einer Clique in G mit der Existenz eines Independent Set in G' (dem Komplementgraphen) zusammen?
+
+### Subbaustein: Existenz von Independent Set der Größe k ist NP-vollständig
+**Muster:** Durch welche Polynomialzeitreduktion lässt sich zeigen, dass Independent Set NP-schwer ist?
+
+### Subbaustein: Existenz von Clique der Größe k ist NP-vollständig
+**Muster:** Wie wird in Satz 6.26 die NP-Schwere von k-Clique bewiesen?
+
+### Subbaustein: Reduktion k-CLIQUE ⪯ k-INDEPENDENT-SET mittels Komplementgraph
+**Muster:** Wie transformiert man eine Instanz (G, k) von CLIQUE in eine Instanz von INDEPENDENT-SET?
+
+### Subbaustein: Clique: Knotenmenge, in der je zwei Knoten durch eine Kante verbunden sind
+**Muster:** Wann ist eine Knotenmenge C ⊆ V eine Clique in einem Graphen G = (V, E)?
+
+### Subbaustein: Complementärgraph: Independent Set in G ist Clique in G̅
+**Muster:** Welche Beziehung besteht zwischen einem Independent Set in G und einer Clique in G̅?
+
+### Subbaustein: Beide Probleme sind NP-vollständig
+**Muster:** Welche fundamentale Konsequenz ergibt sich aus Satz 6.16, wenn ein NP-vollständiges Problem in P liegt?
+
+### Subbaustein: Frage: Existiert Independent Set bzw. Clique der Größe k in G?
+**Muster:** Was ist die Eingabe und was die Ausgabe bei den Entscheidungsproblemen k-Clique und k-Independent-Set?
+
+### Subbaustein: Komplementarität: Independent Set in G = Clique im Komplementgraphen
+**Muster:** Warum sind Clique und Independent Set gegenseitig in Polynomialzeit aufeinander reduzierbar?
+
+### Subbaustein: CLIQUE: Knotenmenge in der je zwei Knoten durch Kante verbunden sind
+**Muster:** Welche Bedingung müssen alle Knotenpaare einer Clique erfüllen?
+
+### Subbaustein: Komplementär: IS in G = CLIQUE in G̅
+**Muster:** Was bleibt bei der Bildung des Komplementgraphen G̅ gleich und was ändert sich?
+
+### Subbaustein: Existenz von IS bzw. CLIQUE der Größe k ist NP-vollständig
+**Muster:** Welche untere Schranke für die Laufzeit von Algorithmen für Independent Set folgt aus der ETH?
+
+### Subbaustein: Formale Sprachen: CLIQUE = {(G,k) | G enthält Clique ≥ k}
+**Muster:** Wie ist die formale Sprache CLIQUE über dem Alphabet Σ = {0, 1} kodiert?
+
+### Subbaustein: Formale Sprachen: INDEPENDENT-SET = {(G,k) | G enthält IS ≥ k}
+**Muster:** Welche Struktur hat die formale Sprache INDEPENDENT-SET?
+
+### Subbaustein: Komplementgraph G̅: Kantenmenge E̅ = {(u,v) | u≠v und {u,v} ∉ E}
+**Muster:** Wie unterscheiden sich die Kantenmengen von G und seinem Komplementgraphen G̅?
+
+### Subbaustein: K-Clique in G entspricht K-Unabhängige-Menge in G̅
+**Muster:** Bleibt die Größe k bei der Reduktion von k-Clique auf k-Independent-Set erhalten?
+
+### Subbaustein: Beide Probleme sind in NP (Verifizierer existiert)
+**Muster:** Welche Eigenschaft müssen Zertifikat und Verifizierer für ein Problem in NP erfüllen?
+
+### Subbaustein: NP-vollständig via gegenseitige Reduktion über Komplementgraph
+**Muster:** Wie folgt aus Korollar 6.18 die NP-Vollständigkeit von Independent Set?
+
+---
+
+## BAUSTEIN: Reduktion CLIQUE → CLIQUE-NOMEMBER
+
+### Subbaustein: Füge isolierten Knoten v zu G hinzu: G' = G ∪ {v}
+**Muster:** Wie wird bei der Reduktion von CLIQUE auf CLIQUE-NOMEMBER der neue Graph G' konstruiert?
+
+### Subbaustein: G hat k-Clique ⟺ G' hat (k+1)-Clique mit v
+**Muster:** Warum kann der hinzugefügte Knoten v in keiner gültigen k-Clique von G' enthalten sein?
+
+### Subbaustein: Reduktion beweist CLIQUE-NOMEMBER ∈ NP-vollständig
+**Muster:** Welche drei Bedingungen müssen erfüllt sein, damit CLIQUE-NOMEMBER als NP-vollständig gilt?
+
+### Subbaustein: CLIQUE: Eingabe Graph G, Frage: existiert K-clique?
+**Muster:** Was ist die Eingabe und was ist die Frage beim Entscheidungsproblem CLIQUE?
+
+### Subbaustein: CLIQUE-NOMEMBER: existiert Knoten der nicht in jeder maximalen Clique liegt?
+**Muster:** Wie ist das Problem CLIQUE-NOMEMBER gemäß Skript 6.50 formal definiert?
+
+### Subbaustein: Reduktion: isolierten Knoten v zu G hinzufügen → G'
+**Muster:** Welche Elemente werden bei der Reduktion von CLIQUE auf CLIQUE-NOMEMBER gegenüber der ursprünglichen Instanz verändert?
+
+### Subbaustein: G' hat Clique der Größe k genau dann wenn G eine hat
+**Muster:** Warum bleibt die Cliquengröße k bei der Reduktion unverändert?
+
+### Subbaustein: v ist in G' in keiner k-Clique (isoliert)
+**Muster:** Welche Eigenschaft hat der Knoten v in der konstruierten Instanz (G', v, k)?
+
+### Subbaustein: G hat Clique der Größe k ⟺ G' hat Clique der Größe k ohne v
+**Muster:** Wie hängt eine k-Clique in G mit einer k-Clique in G' zusammen?
+
+### Subbaustein: Polynomielle Transformation
+**Muster:** Warum ist die beschriebene Reduktion in polynomieller Zeit berechenbar?
+
+---
+
+## BAUSTEIN: Independent Set
+
+### Subbaustein: Für alle u, v ∈ S gilt: {u, v} ∉ E
+**Muster:** Welche Bedingung muss für je zwei Knoten eines Independent Set gelten?
+
+### Subbaustein: Komplementär zur Clique
+**Muster:** Wie hängt ein Independent Set in G mit einer Clique im Komplementgraphen G' zusammen?
+
+### Subbaustein: NP-vollständiges Problem
+**Muster:** Welche Komplexitätsklasse enthält Independent Set und wie wurde dies bewiesen?
+
+### Subbaustein: Knotenmenge ohne Kanten zwischen je zwei Knoten der Menge
+**Muster:** Was bedeutet es, dass die Knoten eines Independent Set paarweise nicht adjazent sind?
+
+### Subbaustein: Komplementär zum Clique-Problem
+**Muster:** In welchem Graphen entspricht ein Independent Set einer Clique?
+
+### Subbaustein: Independent Set S⊆V: keine Kante zwischen je zwei Knoten in S
+**Muster:** Wie unterscheidet sich ein Independent Set von einer beliebigen Teilmenge von V?
+
+### Subbaustein: INDEPENDENT-SET = {(G,k) | G enthält unabhängige Menge der Größe ≥k}
+**Muster:** Welche Sprache formalisiert das Entscheidungsproblem Independent Set?
+
+---
+
+## BAUSTEIN: Tiefensuche (DFS) für Zykluserkennung
+
+### Subbaustein: Weiß: unbesuchter Knoten, Grau: aktuell in Bearbeitung, Schwarz: fertig
+**Muster:** Welche Farbe hat ein Knoten während er von der DFS bearbeitet wird und welche nach Abschluss?
+
+### Subbaustein: DFS-Zykluserkennung in O(V+E) bei adjacency List
+**Muster:** Warum beträgt die Laufzeit der DFS-Zykluserkennung bei Adjazenzliste Θ(|V|+|E|)?
+
+### Subbaustein: Schwarz: vollständig bearbeiteter Knoten
+**Muster:** Wann wird ein Knoten in der DFS schwarz gefärbt?
+
+### Subbaustein: Rückkante (grau → weiß): signalisiert Zyklus
+**Muster:** Zu einem Knoten welcher Farbe muss eine Kante führen, um einen Zyklus anzuzeigen?
+
+### Subbaustein: Tree Edge (weiß): Kante zu unbesuchtem Knoten
+**Muster:** Welche Kante wird als Tree Edge bezeichnet?
+
+### Subbaustein: Grau: aktuell in Bearbeitung (in DFS-Weite)
+**Muster:** Was bedeutet es, wenn ein Knoten während der DFS grau gefärbt ist?
+
+---
+
+## BAUSTEIN: Turingmaschine für 0^n (Zweierpotenz)
+
+### Subbaustein: Eingabe: n Nullen in unärer Codierung
+**Muster:** In welcher Codierung wird die Eingabezahl n der TM für 0^n dargestellt?
+
+### Subbaustein: Akzeptiert nur wenn n = 2^k für ein k ≥ 0
+**Muster:** Nach welchem Kriterium entscheidet die TM, ob eine Eingabe akzeptiert wird?
+
+### Subbaustein: Phase 1: Markiere jede zweite 0 mit x (alternierend)
+**Muster:** Wie markiert die TM die Nullen im ersten Schritt?
+
+---
+
+## BAUSTEIN: 3-SAT zu 3-Färbung Reduktion
+
+### Subbaustein: Knotenzahl linear in Variablen und Klauseln
+**Muster:** Aus welchen Komponenten setzt sich die Knotenmenge V der konstruierten Instanz zusammen?
+
+### Subbaustein: Dreieck erzwingt drei verschiedene Farben für die drei Knoten
+**Muster:** Warum benötigen die drei Knoten xi, x̄i und vi eines jeden Dreiecks drei verschiedene Farben?
+
+---
+
+## BAUSTEIN: MC-Knapsack
+
+### Subbaustein: Ziel: Maximierung des Gesamtwerts
+**Muster:** Was ist die Zielfunktion beim Maximum-Cut Knapsack Problem?
+
+---
+
+**Gesamt: 48 Frage-Muster**

backend/fragen-vorrat-aak.md.cleaned.md

@@ -0,0 +1,126 @@
+# Frage-Muster für Lern-Prüfung: aak
+
+---
+
+## BAUSTEIN: CliqueAndIndependentSet-Problem
+
+### Subbaustein: Clique: Knotenmenge, in der je zwei Knoten durch eine Kante verbunden sind
+**Muster:** Wann ist eine Knotenmenge C ⊆ V eine Clique in einem Graphen G = (V, E) und welche Bedingung müssen alle Knotenpaare einer Clique erfüllen?
+
+### Subbaustein: Independent Set: Knotenmenge ohne Kanten zwischen je zwei Knoten
+**Muster:** Was ist die formale Definition eines Independent Set in einem Graphen G = (V, E) und welche Bedingung muss für je zwei Knoten eines Independent Set gelten?
+
+### Subbaustein: Komplementgraph: Independent Set in G ist Clique in G̅
+**Muster:** Welche Beziehung besteht zwischen einem Independent Set in G und einer Clique in G̅, warum sind die Probleme gegenseitig in Polynomialzeit aufeinander reduzierbar, und was bleibt bei der Bildung des Komplementgraphen gleich bzw. ändert sich?
+
+### Subbaustein: K-CLIQUE ⪯ K-INDEPENDENT-SET mittels Komplementgraph
+**Muster:** Wie transformiert man eine Instanz (G, k) von CLIQUE in eine Instanz von INDEPENDENT-SET, und bleibt die Größe k bei der Reduktion erhalten?
+
+### Subbaustein: NP-vollständig via gegenseitige Reduktion über Komplementgraph
+**Muster:** Wie folgt aus Korollar 6.18 die NP-Vollständigkeit von Independent Set, und welche untere Schranke für die Laufzeit von Algorithmen für Independent Set folgt aus der ETH?
+
+### Subbaustein: Existenz von IS bzw. CLIQUE der Größe k ist NP-vollständig
+**Muster:** Durch welche Polynomialzeitreduktion lässt sich zeigen, dass Independent Set NP-schwer ist, und wie wird in Satz 6.26 die NP-Schwere von k-Clique bewiesen?
+
+### Subbaustein: Beide Probleme sind in NP (Verifizierer existiert)
+**Muster:** Welche Eigenschaft müssen Zertifikat und Verifizierer für die Probleme k-Clique und k-Independent-Set erfüllen?
+
+### Subbaustein: Konsequenz: P = NP falls eines in P
+**Muster:** Welche fundamentale Konsequenz ergibt sich aus Satz 6.16, wenn ein NP-vollständiges Problem in P liegt?
+
+### Subbaustein: Formale Sprachen: CLIQUE und INDEPENDENT-SET
+**Muster:** Wie sind die formalen Sprachen CLIQUE und INDEPENDENT-SET über dem Alphabet Σ = {0, 1} kodiert und welche Struktur haben sie?
+
+### Subbaustein: Eingabe/Ausgabe von k-Clique und k-Independent-Set
+**Muster:** Was ist die Eingabe und was die Ausgabe bei den Entscheidungsproblemen k-Clique und k-Independent-Set?
+
+---
+
+## BAUSTEIN: Reduktion CLIQUE → CLIQUE-NOMEMBER
+
+### Subbaustein: Füge isolierten Knoten v zu G hinzu: G' = G ∪ {v}
+**Muster:** Wie wird bei der Reduktion von CLIQUE auf CLIQUE-NOMEMBER der neue Graph G' konstruiert, und welche Elemente werden gegenüber der ursprünglichen Instanz verändert?
+
+### Subbaustein: v ist in G' in keiner k-Clique (isoliert)
+**Muster:** Warum kann der hinzugefügte Knoten v in keiner gültigen k-Clique von G' enthalten sein, und welche Eigenschaft hat der Knoten v in der konstruierten Instanz (G', v, k)?
+
+### Subbaustein: G hat k-Clique ⟺ G' hat (k+1)-Clique mit v
+**Muster:** Wie hängt eine k-Clique in G mit einer k-Clique in G' zusammen, und warum bleibt die Cliquengröße k bei der Reduktion unverändert?
+
+### Subbaustein: Polynomielle Transformation
+**Muster:** Warum ist die beschriebene Reduktion von CLIQUE auf CLIQUE-NOMEMBER in polynomieller Zeit berechenbar?
+
+### Subbaustein: CLIQUE: Eingabe Graph G, Frage: existiert K-clique?
+**Muster:** Was ist die Eingabe und was ist die Frage beim Entscheidungsproblem CLIQUE?
+
+### Subbaustein: CLIQUE-NOMEMBER formal definiert
+**Muster:** Wie ist das Problem CLIQUE-NOMEMBER gemäß Skript 6.50 formal definiert?
+
+### Subbaustein: Reduktion beweist CLIQUE-NOMEMBER ∈ NP-vollständig
+**Muster:** Welche drei Bedingungen müssen erfüllt sein, damit CLIQUE-NOMEMBER als NP-vollständig gilt?
+
+---
+
+## BAUSTEIN: Independent Set
+
+### Subbaustein: Independent Set S⊆V: keine Kante zwischen je zwei Knoten in S
+**Muster:** Welche Bedingung muss für je zwei Knoten eines Independent Set gelten und was bedeutet es, dass die Knoten eines Independent Set paarweise nicht adjazent sind?
+
+### Subbaustein: Komplementär zur Clique
+**Muster:** In welchem Graphen entspricht ein Independent Set einer Clique und wie hängt ein Independent Set in G mit einer Clique im Komplementgraphen G' zusammen?
+
+### Subbaustein: NP-vollständiges Problem
+**Muster:** Welche Komplexitätsklasse enthält Independent Set und wie wurde dies bewiesen?
+
+### Subbaustein: INDEPENDENT-SET = {(G,k) | G enthält unabhängige Menge der Größe ≥k}
+**Muster:** Welche Sprache formalisiert das Entscheidungsproblem Independent Set?
+
+---
+
+## BAUSTEIN: Tiefensuche (DFS) für Zykluserkennung
+
+### Subbaustein: Weiß/Grau/Schwarz: Farbcodierung der DFS
+**Muster:** Welche Farbe hat ein Knoten während er von der DFS bearbeitet wird, welche nach Abschluss, und wann wird ein Knoten in der DFS schwarz gefärbt?
+
+### Subbaustein: Tree Edge (weiß): Kante zu unbesuchtem Knoten
+**Muster:** Welche Kante wird als Tree Edge bezeichnet?
+
+### Subbaustein: Rückkante (grau → weiß): signalisiert Zyklus
+**Muster:** Zu einem Knoten welcher Farbe muss eine Kante führen, um einen Zyklus anzuzeigen?
+
+### Subbaustein: DFS-Zykluserkennung in O(V+E) bei adjacency List
+**Muster:** Warum beträgt die Laufzeit der DFS-Zykluserkennung bei Adjazenzliste Θ(|V|+|E|)?
+
+---
+
+## BAUSTEIN: Turingmaschine für 0^n (Zweierpotenz)
+
+### Subbaustein: Eingabe: n Nullen in unärer Codierung
+**Muster:** In welcher Codierung wird die Eingabezahl n der TM für 0^n dargestellt?
+
+### Subbaustein: Akzeptiert nur wenn n = 2^k für ein k ≥ 0
+**Muster:** Nach welchem Kriterium entscheidet die TM, ob eine Eingabe akzeptiert wird?
+
+### Subbaustein: Phase 1: Markiere jede zweite 0 mit x (alternierend)
+**Muster:** Wie markiert die TM die Nullen im ersten Schritt?
+
+---
+
+## BAUSTEIN: 3-SAT zu 3-Färbung Reduktion
+
+### Subbaustein: Knotenzahl linear in Variablen und Klauseln
+**Muster:** Aus welchen Komponenten setzt sich die Knotenmenge V der konstruierten Instanz zusammen?
+
+### Subbaustein: Dreieck erzwingt drei verschiedene Farben für die drei Knoten
+**Muster:** Warum benötigen die drei Knoten xi, x̄i und vi eines jeden Dreiecks drei verschiedene Farben?
+
+---
+
+## BAUSTEIN: MC-Knapsack
+
+### Subbaustein: Ziel: Maximierung des Gesamtwerts
+**Muster:** Was ist die Zielfunktion beim Maximum-Cut Knapsack Problem?
+
+---
+
+**Gesamt: 28 Frage-Muster**

backend/fsutil.py

@@ -0,0 +1,22 @@
+"""Atomic file writes: first a .tmp in the same directory, then os.replace.
+
+A crash leaves at most a .tmp file behind — never a half-written target
+file. The .tmp is overwritten on the next successful write.
+"""
+
+import json
+import os
+from pathlib import Path
+
+
+def atomic_write_text(path: Path, text: str) -> None:
+    tmp = path.with_name(path.name + ".tmp")
+    with open(tmp, "w", encoding="utf-8") as f:
+        f.write(text)
+        f.flush()
+        os.fsync(f.fileno())
+    os.replace(tmp, path)
+
+
+def atomic_write_json(path: Path, obj, **dumps_kwargs) -> None:
+    atomic_write_text(path, json.dumps(obj, ensure_ascii=False, **dumps_kwargs))

backend/guide.py

@@ -0,0 +1,432 @@
+"""Guide generation as a consensus pipeline.
+
+Outline: select the blocks (deterministic per format) → 3 proposals
+(Grace) that order the blocks into chapters by NUMBER → a judge merges the
+proposals into one coherent order.
+Writing: one writer per block. Reading exam: Check→Fix (one round),
+follow-up rounds check only replaced sections; remaining complaints then stand.
+Step files are kept → an abort preserves progress, ▶ resumes at the open step.
+"""
+
+import asyncio
+import json
+import logging
+import math
+from datetime import datetime, timezone
+from pathlib import Path
+
+import uuid
+
+from agents import run_agent
+from blocks import _convert_pdfs, source_folder
+from config import (
+    DEFAULT_PROVIDER, FORMAT_PURPOSE, CONSENSUS_GRACE,
+    READABILITY_ACTIVE, TEMPLATES_DIR,
+)
+import readability
+from database import (list_guides, update_guide, list_blocks, list_subblocks, set_guide_content,
+                      get_guide_content, get_outline, guide_stage_counts, delete_guide_board)
+from fsutil import atomic_write_json, atomic_write_text
+from jsonio import read_json_file as _json_file, parse_json_text as _parse_json_text
+from paths import blocks_path, guide_content_path, project_dir, subblocks_path
+from pipeline import (
+    CANCELLED, FAILED, GenContext, _claude_error, _extra,
+    _fail, _gather_error, _gather_progress, _log, _prompt, _race,
+    _semaphore, _set_progress, _set_step, _timeout, clear_guide_cancelled,
+    is_guide_cancelled, run_single_slot,
+)
+from textkit import (
+    _unique_title, _load_blocks, _norm_title, _parse_fragment, _split_chunks,
+    _title, _resolve_title, _title_index,
+)
+
+log = logging.getLogger("creator.guide")
+
+
+# Content/Content-Check/Reading-Exam run in packets of ~GUIDE_CHUNK blocks per agent.
+# Only the writer (Writing) stays at 1 agent per block (variable lengths, no trimming, no
+# length alignment between blocks).
+
+# Check steps as a panel: CHECK_PANEL judges per chunk, section flagged on a majority.
+# A single judge is bias/sampling prone; a small panel is more stable.
+
+# Reading exam: only ONE round (Check + Fix). Follow-up rounds added little value
+# (1 agent per block checks finely anyway) but cost extra agents.
+
+
+# Valid level values: new (learning path) + old (difficulty) backward-compatible.
+_LEVELS_OK = ("beginner", "advanced", "expert", "easy", "medium", "hard")
+
+
+async def _load_subblocks(topic: str) -> dict[str, list[dict]]:
+    """Subblocks per block — DB-first ({title, level, relevance}), fallback sidecar file.
+    Both missing → {} (guide takes everything). A missing/invalid level defaults to
+    'advanced' instead of dropping the row: re-run resume left 25 consensus subs
+    level-less, the writer silently lost them while the guide QA still counted them."""
+    out: dict[str, list[dict]] = {}
+    for r in await list_subblocks(topic):
+        if r["status"] == "consensus" and r["sub_title"]:
+            try:
+                facts = json.loads(r["facts"]) if r.get("facts") else {}
+            except (ValueError, TypeError):
+                facts = {}
+            level = r["level"] if r["level"] in _LEVELS_OK else "advanced"
+            out.setdefault(r["block"], []).append(
+                {"title": r["sub_title"], "level": level, "relevance": r["relevance"], "facts": facts})
+    if out:
+        return out
+    data = _json_file(subblocks_path(topic))
+    if not isinstance(data, dict):
+        return {}
+    for title, subs in data.items():
+        if not isinstance(subs, list):
+            continue
+        good = [s for s in subs if isinstance(s, dict) and str(s.get("title", "")).strip()
+                and s.get("level") in _LEVELS_OK]
+        if good:
+            out[title] = good
+    return out
+
+
+def _level_label(s: dict) -> str:
+    """View level of a subblock: peripheral → 'peripheral' (level 4), otherwise the level (1–3)."""
+    return "peripheral" if s.get("relevance") == "peripheral" else (s.get("level") or "beginner")
+
+
+
+
+
+
+def guide_slot_files(content_path: Path) -> list[Path]:
+    """All step files of a guide (for a fresh start)."""
+    return [p for p in content_path.parent.glob(f"{content_path.stem}.*") if p != content_path]
+
+
+
+
+
+
+
+
+
+
+# Slot-file globs per step (index = GUIDE_STEPS). Stem-anchored, collision-free.
+
+
+
+
+
+
+
+
+
+
+def _fallback_outline(entries: dict[int, str]) -> list[dict]:
+    """Deterministic outline when the agents deliver none: one chapter with
+    all selected blocks in order. Guarantees full coverage."""
+    return [{"title": "Contents", "nums": list(entries)}]
+
+
+def _with_remainder(plan: list[dict], entries: dict[int, str]) -> list[dict]:
+    """Ensures that EVERY selected block is in the plan — missing ones land in
+    an "Additional" chapter (against agents/judges that drop blocks)."""
+    present = {num for ch in plan for num in ch.get("nums", [])}
+    missing = [num for num in entries if num not in present]
+    return [*plan, {"title": "Additional", "nums": missing}] if missing else plan
+
+
+def _facts_grounding(subs_raw: dict[str, list[dict]]) -> str:
+    """Verified sub-facts (extract-once from the blocks phase) as a grounding block for the
+    content agent. Empty if no facts are stored (legacy data → fallback to a source hint)."""
+    blocks = []
+    for title, subs in subs_raw.items():
+        lines = []
+        for s in subs:
+            fk = s.get("facts") if isinstance(s.get("facts"), dict) else None
+            if not fk:
+                continue
+            parts = []
+            if fk.get("key_points"):
+                parts.append("Core: " + " · ".join(fk["key_points"]))
+            for bf in fk.get("cited_facts", []):
+                parts.append(f"FACT[{bf.get('source', '?')}]: {bf.get('text', '')}")
+            if fk.get("prerequisites"):
+                parts.append("Prerequisite: " + fk["prerequisites"])
+            if fk.get("hurdles"):
+                parts.append("Hurdle: " + fk["hurdles"])
+            if fk.get("example_idea"):
+                parts.append("Example: " + fk["example_idea"])
+            if parts:
+                lines.append(f"- {s['title']}: " + " | ".join(parts))
+        if lines:
+            blocks.append(f"BLOCK: {title}\n" + "\n".join(lines))
+    if not blocks:
+        return ""
+    return ("VERIFIED FACTS per subblock — binding basis. Quote cited facts (FACT[Source]) "
+            "VERBATIM, invent nothing extra, do NOT re-research. Use examples as examples, "
+            "never as fact.\n\n" + "\n\n".join(blocks))
+
+
+async def _outline_from_db(topic: str, sel_entries: dict[int, str]) -> list[dict] | None:
+    """Read the outline from the blocks artifact (DB) and map it onto the selected blocks.
+    Title-based (robust against number drift): blocks outside the selection are ignored
+    (format filter), missing ones are added later by _with_remainder. None → no artifact (legacy)."""
+    raw = await get_outline(topic)
+    if not raw:
+        return None
+    try:
+        data = json.loads(raw)
+    except (ValueError, TypeError):
+        return None
+    chapters = data.get("chapters") if isinstance(data, dict) else None
+    if not isinstance(chapters, list):
+        return None
+    norm_to_num = {_norm_title(_title(t)): num for num, t in sel_entries.items()}
+    plan, seen = [], set()
+    for ch in chapters:
+        if not isinstance(ch, dict):
+            continue
+        nums = []
+        for bt in ch.get("blocks", []):
+            num = norm_to_num.get(_norm_title(str(bt)))
+            if num is not None and num not in seen:
+                seen.add(num)
+                nums.append(num)
+        if nums:
+            plan.append({"title": str(ch.get("title", "")).strip() or "Chapter", "nums": nums})
+    return plan or None
+
+
+
+
+_LEVEL_RANK = {"beginner": 1, "advanced": 2, "expert": 3, "peripheral": 4,
+               "easy": 1, "medium": 2, "hard": 3}  # old values backward-compatible
+
+
+def _section_for_level(sec: dict, level: int) -> dict:
+    """Reconstruct md/compact of a section from subblocks up to the level (anchor stays)."""
+    subs = sec.get("subs") or []
+    if not subs:
+        return sec  # no sub tags (legacy) → unchanged, visible
+    visible = [s for s in subs if _LEVEL_RANK.get(s.get("level"), 1) <= level]
+    md = "\n\n".join(t for t in [sec.get("anchor", ""), *(s.get("md", "") for s in visible)] if t).strip()
+    compact = "\n".join(t for t in [sec.get("anker_compact", ""), *(s.get("compact", "") for s in visible)] if t).strip()
+    return {**sec, "md": md, "compact": compact, "leer": not visible}
+
+
+def content_fuer_level(content: dict, level: int) -> dict:
+    """Filter guide content to a view level (1=A · 2=F · 3=E · 4=V). Level 4 = full version.
+    Sections without visible subs are hidden, empty chapters drop out."""
+    if not isinstance(content, dict) or level >= 4:
+        return content
+    chapters = []
+    for ch in content.get("chapters", []):
+        secs = [s for s in (_section_for_level(x, level) for x in ch.get("sections", [])) if not s.get("leer")]
+        if secs:
+            chapters.append({**ch, "sections": secs})
+    return {**content, "chapters": chapters}
+
+
+async def reconcile_guides() -> None:
+    """Reconcile DB↔filesystem: status=done without content file → error.
+
+    Runs at server start (after init_db) — catches crashes between
+    file write and status update.
+    """
+    for g in await list_guides():
+        if g["status"] == "done" and not guide_content_path(g["topic"], g["format"]).exists():
+            log.warning("[%s] Guide %s: done without content file — set to error", g["topic"], g["id"])
+            now = datetime.now(timezone.utc).isoformat()
+            await update_guide(g["id"], status="error", error_msg="Content missing — regenerate", updated_at=now)
+
+
+async def generate_guide(guide_id: str, topic: str, format_name: str, instructions: str = "", provider: str = DEFAULT_PROVIDER, ab_step: int | None = None) -> None:
+    async with _semaphore:
+        now = datetime.now(timezone.utc).isoformat()
+        await update_guide(guide_id, status="generating", progress="Starting…", updated_at=now)
+
+        content_path = guide_content_path(topic, format_name)
+        content_path.parent.mkdir(parents=True, exist_ok=True)
+        project = source_folder(topic)  # folder source (project/uni/link) → path, else None
+
+        try:
+            if is_guide_cancelled(guide_id):
+                return
+
+            if project:
+                await asyncio.to_thread(_convert_pdfs, project)
+
+            import guide_board  # lazy — guide_board imports helpers from this module
+            # Re-run from stage: cards from `ab_step` onward back to that column.
+            # A FINISHED guide without ab_step → complete fresh start (board + slots wiped).
+            # Otherwise cards are leftovers of an abort/error → resume at their stored stage.
+            if ab_step is not None:
+                await guide_board.reset_from_stage(topic, format_name, ab_step)
+            elif content_path.exists():
+                counts = await guide_stage_counts(topic, format_name)
+                if not counts or set(counts) == {"done"}:
+                    await delete_guide_board(topic, format_name)
+                    for p_alt in guide_slot_files(content_path):
+                        p_alt.unlink(missing_ok=True)
+
+            bs = await list_blocks(topic, status="consensus")
+            if bs:
+                alle = {i: (f"{b['title']} — {b['description']}" if b["description"] else b["title"])
+                        for i, b in enumerate(bs, 1)}
+            else:  # fallback: blocks.md (legacy topics)
+                bp = blocks_path(topic)
+                alle = _load_blocks(bp.read_text(encoding="utf-8")) if bp.exists() else {}
+            if not alle:
+                await _fail(guide_id, "No blocks found")
+                return
+            entries = _unique_title(alle)
+            chapters = await guide_board.run_guide_board(
+                guide_id, topic, format_name, entries, instructions, provider, content_path,
+            )
+            if is_guide_cancelled(guide_id):
+                return
+            if chapters is None:
+                await _fail(guide_id, "No finished sections (see board — cards with errors)")
+                return
+            content = {"topic": topic, "format": format_name, "chapters": chapters}
+
+            atomic_write_json(content_path, content, indent=1)  # bridge (resume/fallback)
+            await set_guide_content(topic, format_name, json.dumps(content, ensure_ascii=False))
+
+            now = datetime.now(timezone.utc).isoformat()
+            await update_guide(guide_id, status="done", progress=None, step=None, updated_at=now)
+
+        except asyncio.TimeoutError:
+            await _fail(guide_id, "Timeout during generation")
+        except FileNotFoundError:
+            await _fail(guide_id, "Blocks missing")
+        except Exception as e:
+            log.exception("[%s] Guide generation failed (%s)", topic, guide_id)
+            await _fail(guide_id, str(e)[:2000])
+        finally:
+            clear_guide_cancelled(guide_id)
+
+
+# --- On-demand: check / fix / rewrite one section (focus, interactive) ---
+
+SECTION_CHECK_TIMEOUT = 300
+
+
+def _section_spec() -> str:
+    return (TEMPLATES_DIR / "Format" / "Section.md").read_text(encoding="utf-8")
+
+
+def _section_facts(topic: str) -> str:
+    project = source_folder(topic)
+    return _prompt("Guide-Facts-Projekt", project=project) if project else _prompt("Guide-Facts-Thema")
+
+
+def _hint_block(hint: str) -> str:
+    hint = (hint or "").strip()
+    return f"NOTE FROM THE USER (pay special attention):\n{hint}" if hint else ""
+
+
+async def _subs_text(topic: str, block: str) -> str:
+    """Relevant subblocks of a block with level — as a checklist for the agents."""
+    subs_raw = await _load_subblocks(topic)
+    subs = [s for s in subs_raw.get(_title(block), []) if s.get("relevance") != "peripheral"]
+    if not subs:
+        return "(no subblocks recorded — cover 3–7 concise points)"
+    return "\n".join(f"- [{s['level']}] {s['title']}" for s in subs)
+
+
+async def _load_guide_content(topic: str, format_name: str) -> dict | None:
+    js = await get_guide_content(topic, format_name)
+    if not js:
+        return None
+    try:
+        return json.loads(js)
+    except ValueError:
+        return None
+
+
+def _find_section(content: dict, block: str) -> dict | None:
+    for ch in content.get("chapters", []):
+        for s in ch.get("sections", []):
+            if s.get("title") == block:
+                return s
+    return None
+
+
+async def block_pruefen(topic: str, format_name: str, block: str, spot: str, snippet: str, hint: str = "", provider: str = DEFAULT_PROVIDER) -> str | None:
+    """Check one section (Markdown block) against the guide rules → corrected
+    block version as Markdown. None = error/section missing."""
+    content = await _load_guide_content(topic, format_name)
+    sec = _find_section(content, block) if content else None
+    if sec is None:
+        return None
+    whole = sec.get("compact", "") if str(spot).startswith("compact") else sec.get("md", "")
+    prompt = _prompt(
+        "Block-Pruefen", topic=topic, spec=_section_spec(), facts=_section_facts(topic),
+        subblocks=await _subs_text(topic, block), context=whole, snippet=snippet, hint=_hint_block(hint),
+    )
+    rc, stdout, _ = await run_agent(
+        f"block-pruefen-{uuid.uuid4()}", prompt, SECTION_CHECK_TIMEOUT,
+        provider=provider, role="judge", capabilities="none", lane="interactive",
+    )
+    new = stdout.strip() if rc == 0 else ""
+    return new or None
+
+
+async def block_adopt(topic: str, format_name: str, block: str, spot: str, old: str, new: str) -> dict | None:
+    """Replace one block (old→new) in the compact/detailed field + persist.
+    → {compact, md, found}; None = section missing."""
+    content = await _load_guide_content(topic, format_name)
+    sec = _find_section(content, block) if content else None
+    if sec is None:
+        return None
+    is_compact = str(spot).startswith("compact")
+    field = "compact" if is_compact else "md"
+    current = sec.get(field, "") or ""
+    found = old in current
+    if found:
+        sec[field] = current.replace(old, new, 1)
+        # Also replace in anchor + subs (sources of the filtered E/M/S view), otherwise the
+        # leveled view keeps showing the old block.
+        anchor_field = "anker_compact" if is_compact else "anchor"
+        if old in (sec.get(anchor_field) or ""):
+            sec[anchor_field] = sec[anchor_field].replace(old, new, 1)
+        for sub in sec.get("subs", []):
+            if old in (sub.get(field, "") or ""):
+                sub[field] = sub[field].replace(old, new, 1)
+                break
+        js = json.dumps(content, ensure_ascii=False)
+        await set_guide_content(topic, format_name, js)
+        atomic_write_json(guide_content_path(topic, format_name), content, indent=1)
+    return {"compact": sec.get("compact", ""), "md": sec.get("md", ""), "found": found}
+
+
+# --- Tutor chat (moved from the removed elements module) ---
+
+def _build_guide_chat_prompt(topic: str, format_name: str, section: str, outline: str, messages: list[dict]) -> str:
+    transcript = "\n".join(
+        f"{'User' if m.get('role') == 'user' else 'Assistant'}: {m.get('content', '')}"
+        for m in messages
+    )
+    return _prompt(
+        "Chat",
+        topic=topic, format_name=format_name,
+        outline_block=outline.strip() or "(none)",
+        section_block=section.strip() or "(no section detected)",
+        transcript=transcript,
+    )
+
+
+async def chat_with_guide(topic: str, format_name: str, section: str, outline: str, messages: list[dict], provider: str = DEFAULT_PROVIDER) -> str:
+    try:
+        prompt = _build_guide_chat_prompt(topic, format_name, section, outline, messages)
+        returncode, stdout, stderr = await run_agent(
+            "chat-" + str(uuid.uuid4()), prompt, 240, provider=provider, role="fast", capabilities="none", lane="interactive"
+        )
+        if returncode != 0:
+            return "Sorry, that didn't work. Please try again."
+        reply = stdout.strip()
+        return reply or "Sorry, I didn't get a response."
+    except Exception:
+        log.warning("[%s] Guide chat failed", topic, exc_info=True)
+        return "Sorry, that didn't work. Please try again."

backend/guide_board.py

@@ -0,0 +1,769 @@
+"""Board 3 „Guide": one card per block, linear stages with gates between them.
+
+  lernziele   judge-Rolle   Backward Design — objectives BEFORE writing
+  zuweisung   code          chapter/order from the outline artefact + facts grounding
+  writer      guide-Rolle   ONE coherent per-block text, only from VERIFIED FACTS
+  pruefer     judge-Rolle   EIN Call: CoVe-Fakten + Coverage + Lesbarkeit (lasen vorher
+                            denselben Text in 3 seriellen Calls) + deterministische Gates
+  fix         guide-Rolle   EIN Rewrite unter allen Auflagen; bei falsch/Lücken danach
+                            genau ein Re-Prüfer-Pass (der alte Lese-Fix blieb ungeprüft)
+
+Runner: one asyncio task per card (cards are fixed from the start — no queue engine
+needed); stage transitions are persisted in guide_cards, so the board is live and
+cancel/resume just picks cards up at their stored stage. Assembly keeps the exact
+legacy content format → content_fuer_level / TopicDetail stay untouched.
+"""
+
+import asyncio
+import json
+import logging
+import re
+
+import database as db
+import readability
+from blocks import _sink_json
+from config import (FORMAT_PURPOSE, READABILITY_ACTIVE,
+                    TEMPLATES_DIR, MAX_CONCURRENT_AGENTS_PER_TOPIC)
+from guide_qa import block_budget
+from fsutil import atomic_write_json
+from jsonio import read_json_file as _json_file
+from pipeline import (CANCELLED, FAILED, OK, GenContext, _extra, _log, _prompt,
+                      _timeout, is_guide_cancelled, run_single_slot)
+from textkit import _norm_title, _parse_fragment, _title
+
+log = logging.getLogger("creator.guide_board")
+
+GUIDE_STAGES = ("lernziele", "zuweisung", "writer", "pruefer", "fix")
+STAGE_LABELS = {"lernziele": "Lernziele", "zuweisung": "Zuweisung", "writer": "Writer",
+                "pruefer": "Prüfen", "fix": "Fix", "done": "Fertig"}
+from config import GATE_FIX_MIN, WRITER_SPLIT_SUBS  # zentral tunebar
+# Simultaneous cards = the per-topic agent cap: every card busies exactly ONE agent at a
+# time (its stages run serially), so a lower number just idles slots (was hardcoded 10
+# from the old 10-slot era while the .env already allowed 24).
+CARD_CONCURRENCY = MAX_CONCURRENT_AGENTS_PER_TOPIC
+
+
+def _safe(norm: str) -> str:
+    return re.sub(r"\W+", "_", norm)[:50] or "block"
+
+
+def _ziele_schema(data):
+    """{"ziele":[{id,text,sub}]} → list of dicts · None on invalid structure."""
+    if not isinstance(data, dict) or not isinstance(data.get("ziele"), list) or not data["ziele"]:
+        return None
+    out, seen = [], set()
+    for z in data["ziele"]:
+        if not isinstance(z, dict):
+            return None
+        zid = str(z.get("id", "")).strip()
+        text = str(z.get("text", "")).strip()
+        if not zid or not text or zid in seen or len(out) >= 12:
+            continue
+        seen.add(zid)
+        out.append({"id": zid, "text": text, "sub": str(z.get("sub", "")).strip()})
+    return out or None
+
+
+def _gate_schema(data):
+    """{"ok":true} → [] · {"claims":[{text,grund,urteil}]} → list · None invalid.
+    urteil "falsch" (contradicts the facts/itself) vs "unbelegt" (true but underivable) —
+    default unbelegt. Entries whose grund starts with "belegt" are dropped: one judge
+    returned a 65-entry full inventory including SUPPORTED claims."""
+    if not isinstance(data, dict):
+        return None
+    if data.get("ok") is True:
+        return []
+    claims = data.get("claims")
+    if not isinstance(claims, list) or not claims:
+        return None
+    out = []
+    for c in claims:
+        if isinstance(c, dict) and str(c.get("text", "")).strip():
+            grund = str(c.get("grund", "")).strip()
+            if grund.casefold().startswith("belegt"):
+                continue
+            urteil = str(c.get("urteil", "")).strip().casefold()
+            out.append({"text": str(c["text"]).strip(), "grund": grund,
+                        "urteil": urteil if urteil == "falsch" else "unbelegt"})
+    return out
+
+
+def _pruefer_schema(data, ziel_ids: set[str]):
+    """Verschmolzenes Prüfer-Verdikt: Claims (Fakten-Gate-Semantik via _gate_schema) +
+    Coverage (ziele/luecken/ballast) + Lesbarkeit (lese_probleme). {"ok":true} = leeres
+    Verdikt. `ziele` muss alle ids abdecken, wenn Ziele existieren — sonst optional."""
+    if not isinstance(data, dict):
+        return None
+    if data.get("ok") is True:
+        return {"claims": [], "ziele": {}, "luecken": [], "ballast": [], "lese_probleme": []}
+    if not any(k in data for k in ("claims", "ziele", "luecken", "ballast", "lese_probleme")):
+        return None
+    claims = _gate_schema({"claims": data["claims"]}) if data.get("claims") else []
+    if claims is None:
+        return None
+    ziele = {}
+    for k, v in (data.get("ziele") or {}).items() if isinstance(data.get("ziele"), dict) else []:
+        ziele[str(k)] = str(v).strip().casefold() in ("true", "ja", "yes", "1")
+    if ziel_ids and not ziel_ids <= set(ziele):
+        return None
+    luecken = [{"ziel": str(l.get("ziel", "")), "fehlt": str(l.get("fehlt", ""))}
+               for l in data.get("luecken", []) if isinstance(l, dict) and str(l.get("fehlt", "")).strip()]
+    ballast = [str(b).strip() for b in data.get("ballast", []) if str(b).strip()]
+    lese = [str(p.get("problem", "")).strip() for p in data.get("lese_probleme", [])
+            if isinstance(p, dict) and str(p.get("problem", "")).strip()]
+    return {"claims": claims, "ziele": ziele, "luecken": luecken, "ballast": ballast,
+            "lese_probleme": lese}
+
+
+def _first_section(md: str) -> dict | None:
+    secs = _parse_fragment(md) if md else []
+    return secs[0] if secs else None
+
+
+class _Env:
+    """Shared per-run context for the card tasks."""
+
+    def __init__(self, ctx, guide_id, topic, format_name, instructions, content_path,
+                 subs_by_title, chapter_map, fallback_facts, spec):
+        self.ctx = ctx
+        self.guide_id = guide_id
+        self.topic = topic
+        self.format = format_name
+        self.instructions = instructions
+        self.content_path = content_path
+        self.subs_by_title = subs_by_title    # block title → [sub dicts]
+        self.chapter_map = chapter_map        # block_norm → (chapter title, ord)
+        self.fallback_facts = fallback_facts  # generic source hint (legacy topics without facts)
+        self.spec = spec
+
+    def slot(self, name: str):
+        return self.content_path.parent / f"{self.content_path.stem}.{name}"
+
+
+def _card_facts(env: _Env, block_title: str) -> str:
+    from guide import _facts_grounding  # lazy: guide imports this module
+    grounding = _facts_grounding({block_title: env.subs_by_title.get(block_title, [])})
+    return grounding or env.fallback_facts
+
+
+async def _card_examples(env: _Env, block_norm: str, subs: list[dict],
+                         include_unmatched: bool = True) -> str:
+    """Verified worked examples of the block as writer input, matched to `subs` via
+    sub_norm (a split half gets only its own). Rows whose sub does not match (generation
+    mismatch) go to the full writer / split part 1 so they never vanish silently."""
+    rows = await db.get_sub_artefakte(env.topic, type="example", block_norm=block_norm)
+    if not rows:
+        return ""
+    wanted = {_norm_title(s["title"]) for s in subs}
+    out = []
+    for r in rows:
+        matched = r["sub_norm"] in wanted
+        if not matched and not include_unmatched:
+            continue
+        data = json.loads(r["data"]) if isinstance(r["data"], str) else (r["data"] or {})
+        steps = " ".join(f"{i}) {s}" for i, s in enumerate(data.get("steps") or [], 1))
+        where = (f"Subbaustein „{r['sub_title']}“" if matched
+                 else "Subbaustein unklar — dort einweben, wo es fachlich passt")
+        out.append(f"- {where}:\n  Problem: {data.get('problem', '')}\n"
+                   f"  Schritte: {steps}\n  Ergebnis: {data.get('result', '')}")
+    if not out:
+        return ""
+    return ("VERIFIED WORKED EXAMPLES (already fact-checked; each belongs to ONE subblock):\n"
+            + "\n".join(out) + "\n"
+            "Weave each example into the ausführlich text of EXACTLY its subblock, right "
+            "after the concept it applies has been explained — as a short worked-through "
+            "passage (problem → steps → result recognizable, flowing prose or a compact "
+            "numbered list). Take all values and results over VERBATIM, never recompute "
+            "or alter them. NEVER put examples into the compact layer. Subblocks without "
+            "an example get none.")
+
+
+def _card_assignment(env: _Env, card: dict) -> str:
+    from guide import _level_label
+    lines = [f"- {card['block']}"]
+    for s in env.subs_by_title.get(card["block"], []):
+        lines.append(f"    [{_level_label(s)}] {s['title']}")
+    return "\n".join(lines)
+
+
+# Live info per active card (in-memory): what the card is doing RIGHT NOW —
+# board_snapshot shows it as the info line while status == active.
+_live_info: dict[tuple[str, str, str], str] = {}
+
+
+def _live(env: _Env, card: dict, msg: str) -> None:
+    _live_info[(env.topic, env.format, card["block_norm"])] = msg
+
+
+async def _set(env: _Env, card: dict, **fields):
+    card.update(fields)
+    await db.set_guide_card(env.topic, env.format, card["block_norm"], **fields)
+
+
+# ── Stages ─────────────────────────────────────────────────────────────────────────
+async def _stage_lernziele(env: _Env, card: dict) -> bool:
+    norm = card["block_norm"]
+    if not await db.list_lernziele(env.topic, norm):
+        subs = "\n".join(f"- [{s.get('level', 'beginner')}] {s['title']}"
+                         for s in env.subs_by_title.get(card["block"], [])) or "(keine)"
+
+        async def _versuch(suffix: str):
+            path = env.slot(f"ziele-{_safe(norm)}{suffix}.json")
+            return await run_single_slot(
+                env.ctx, f"Lernziele {card['block']}", key=f"{env.guide_id}-ziele-{_safe(norm)}{suffix}",
+                prompt=_prompt("Guide-Lernziele", topic=env.topic, block=card["block"],
+                               subs=subs, facts=_card_facts(env, card["block"]),
+                               out_path=path, extra=_extra(env.instructions)),
+                role="judge", capabilities="files",
+                payload=lambda result, p=path: _ziele_schema(_json_file(p)),
+                timeout=_timeout("lernziele", len(env.subs_by_title.get(card["block"], []))))
+
+        status, ziele = await _versuch("")
+        if status == CANCELLED:
+            return False
+        if status == FAILED:
+            await _set(env, card, status="error", gate_info="Lernziele ohne Ergebnis")
+            return False
+        if not ziele:  # ein Ersatz-Versuch — leere Liste heißt: das Coverage-Gate läuft leer
+            status, ziele = await _versuch("-2")
+            if status == CANCELLED:
+                return False
+            if not isinstance(ziele, list):
+                ziele = []
+            if not ziele:
+                _log(env.topic, f"Lernziele {card['block']}: zweimal leer — Block ohne Coverage-Gate")
+        for z in ziele:
+            await db.put_lernziel(env.topic, norm, z["id"], z["text"], _norm_title(z["sub"]))
+    await _set(env, card, stage="zuweisung", status="open")
+    return True
+
+
+async def _stage_zuweisung(env: _Env, card: dict) -> bool:
+    chapter, ord_ = env.chapter_map.get(card["block_norm"], ("Weitere Inhalte", 10_000))
+    await _set(env, card, chapter=chapter, ord=ord_, stage="writer")
+    return True
+
+
+# A single section over ~45 subs measurably breaks the writer/coverage (Front Matter:
+# 4/6 objectives open after 2 rounds). First drafts of oversized cards are written in two
+# halves and merged back into ONE canonical section (all gates/assembly read one section).
+# WRITER_SPLIT_SUBS: siehe config.py
+
+
+def _merge_split_sections(sec_a: dict, sec_b: dict) -> str:
+    """Rebuild ONE canonical fragment from two half-sections: header + anchor from part A,
+    sub blocks of both parts in order, both layers. Part B's framing is dropped — its
+    prompt forbids an intro; keeping it would inject a second lead-in mid-section."""
+    lines = []
+    if sec_a.get("chapters"):
+        lines.append(f"<!-- kapitel: {sec_a['chapters']} -->")
+    lines.append(f"<!-- section: {sec_a['title']} -->")
+    lines.append("<!-- compact -->")
+    if sec_a.get("anker_compact"):
+        lines.append(sec_a["anker_compact"])
+    for sub in [*sec_a["subs"], *sec_b["subs"]]:
+        if sub.get("compact"):
+            lines.append(f"<!-- sub: {sub['level']} | {sub['title']} -->")
+            lines.append(sub["compact"])
+    lines.append("<!-- ausführlich -->")
+    if sec_a.get("anchor"):
+        lines.append(sec_a["anchor"])
+    for sub in [*sec_a["subs"], *sec_b["subs"]]:
+        if sub.get("md"):
+            lines.append(f"<!-- sub: {sub['level']} | {sub['title']} -->")
+            lines.append(sub["md"])
+    return "\n\n".join(lines)
+
+
+async def _write_split(env: _Env, card: dict, ziele_text: str):
+    """First draft in two halves (parallel), merged into one section.
+    → merged text | None (failed) | False (cancelled)."""
+    from guide import _level_label
+    norm = card["block_norm"]
+    subs = env.subs_by_title.get(card["block"], [])
+    half = (len(subs) + 1) // 2
+    parts = (subs[:half], subs[half:])
+    hints = (
+        "TEIL 1/2: Schreibe den Abschnitts-EINSTIEG und die folgenden Unterpunkte. "
+        "Weitere Unterpunkte folgen in Teil 2 — KEIN Fazit, KEIN Ausblick am Ende.",
+        "TEIL 2/2: FORTSETZUNG desselben Abschnitts. KEIN neuer Einstieg, KEINE "
+        "Wiederholung von Teil 1 — direkt mit den Unterpunkten weitermachen.",
+    )
+
+    async def _one(i):
+        assignment = "\n".join([f"- {card['block']}"]
+                               + [f"    [{_level_label(s)}] {s['title']}" for s in parts[i]])
+        path = env.slot(f"card-{_safe(norm)}-r0-{'ab'[i]}.md")
+        path.unlink(missing_ok=True)
+
+        def _payload(result, p=path):
+            t = p.read_text(encoding="utf-8") if p.exists() else ""
+            sec = _first_section(t)
+            return t if sec and sec.get("md", "").strip() else None
+
+        return await run_single_slot(
+            env.ctx, f"Writer {card['block']} ({i + 1}/2)",
+            key=f"{env.guide_id}-w-{_safe(norm)}-r0-{'ab'[i]}",
+            prompt=_prompt("Guide-Writer-Board", topic=env.topic, format_name=env.format,
+                           chapter=card.get("chapter") or "Inhalte",
+                           assignment=assignment, ziele=ziele_text,
+                           facts=_card_facts(env, card["block"]),
+                           examples=await _card_examples(env, norm, parts[i],
+                                                         include_unmatched=(i == 0)),
+                           gaps="\n" + hints[i] + "\n",
+                           budget=block_budget(parts[i]),
+                           spec=env.spec, out_path=path, extra=_extra(env.instructions)),
+            role="guide", capabilities="files", payload=_payload,
+            timeout=_timeout("writer", 1))
+
+    results = await asyncio.gather(_one(0), _one(1))
+    if any(s == CANCELLED for s, _ in results):
+        return False
+    if any(s == FAILED for s, _ in results):
+        return None
+    return _merge_split_sections(_first_section(results[0][1]), _first_section(results[1][1]))
+
+
+async def _stage_writer(env: _Env, card: dict) -> bool:
+    norm = card["block_norm"]
+    ziele = await db.list_lernziele(env.topic, norm)
+    ziele_text = "\n".join(f"- ({z['ziel_id']}) {z['text']}" for z in ziele) or "(keine definiert)"
+    # oversized first drafts: two halves, merged into one canonical section
+    if card["writer_rounds"] == 0 and len(env.subs_by_title.get(card["block"], [])) > WRITER_SPLIT_SUBS:
+        text = await _write_split(env, card, ziele_text)
+        if text is False:
+            return False
+        if text is None:
+            await _set(env, card, status="error", gate_info="Writer (Split) ohne Ergebnis")
+            return False
+        await _set(env, card, md=text, stage="pruefer", status="open")
+        return True
+
+    path = env.slot(f"card-{_safe(norm)}-r{card['writer_rounds']}.md")
+    path.unlink(missing_ok=True)
+
+    def _payload(result):
+        text = path.read_text(encoding="utf-8") if path.exists() else ""
+        sec = _first_section(text)
+        return text if sec and sec.get("md", "").strip() else None
+
+    status, text = await run_single_slot(
+        env.ctx, f"Writer {card['block']}", key=f"{env.guide_id}-w-{_safe(norm)}-r{card['writer_rounds']}",
+        prompt=_prompt("Guide-Writer-Board", topic=env.topic, format_name=env.format,
+                       chapter=card.get("chapter") or "Inhalte",
+                       assignment=_card_assignment(env, card), ziele=ziele_text,
+                       facts=_card_facts(env, card["block"]),
+                       examples=await _card_examples(env, norm, env.subs_by_title.get(card["block"], [])),
+                       gaps="", spec=env.spec,
+                       budget=block_budget(env.subs_by_title.get(card["block"], [])),
+                       out_path=path, extra=_extra(env.instructions)),
+        role="guide", capabilities="files", payload=_payload,
+        timeout=_timeout("writer", 1))
+    if status == CANCELLED:
+        return False
+    if status == FAILED:
+        await _set(env, card, status="error", gate_info="Writer ohne Ergebnis")
+        return False
+    await _set(env, card, md=text, stage="pruefer", status="open")
+    return True
+
+
+def _n_rel(env: _Env, card: dict) -> int:
+    return sum(1 for s in env.subs_by_title.get(card["block"], [])
+               if s.get("relevance") != "peripheral")
+
+
+def _det_hinweise(env: _Env, card: dict, sec: dict) -> list[str]:
+    """Deterministische Befunde (extern geerdet, kein LLM): Readability-Modell +
+    Längenbudget — dieselbe Formel wie der QA-Detektor (guide_qa.block_budget), nur mit
+    engerem Band, damit der Fix VOR der QA-Grenze greift. Gehen direkt in den Fix
+    und als „nicht wiederholen"-Notiz in den Prüfer-Prompt."""
+    out: list[str] = []
+    subs_all = env.subs_by_title.get(card["block"], [])
+    if not any(s.get("relevance") != "peripheral" for s in subs_all):
+        return out  # kein Inventar als Budget-Basis → kein Längen-Urteil (wie der QA-Detektor)
+    budget = block_budget(subs_all)
+    aus = re.split(r"<!--\s*ausführlich\s*-->", sec["md"], maxsplit=1)
+    zeichen = len(aus[1] if len(aus) == 2 else sec["md"])
+    if not (0.5 * budget <= zeichen <= 1.2 * budget):
+        out.append(
+            f"Länge {zeichen} Zeichen (Budget {budget}, erlaubt {round(0.5 * budget)}–{round(1.2 * budget)}): "
+            f"schreibe den ausführlich-Teil auf etwa {budget} Zeichen GESAMT um — Sockel-Prosa und "
+            f"Wiederholungen streichen, alle Sub-Marker und Beispiele behalten")
+    return out
+
+
+async def _det_readability(sec: dict) -> list[str]:
+    if not READABILITY_ACTIVE:
+        return []
+    hints = await asyncio.to_thread(readability.rate_sections, {1: sec["md"]})
+    return [hints[1]] if hints.get(1) else []
+
+
+def _auftraege(verdict: dict, det: list[str], n_rel: int = 0) -> tuple[list[str], bool]:
+    """Prüfer-Verdikt → Fix-Auftragszeilen. kritisch = falsch-Claims oder Lücken
+    (nur die rechtfertigen den Re-Prüfer-Pass — Fakten/Coverage sind der Qualitätskern).
+    Claims-Schwelle: wenige nur-„unbelegt" lohnen keinen Fix-Pass — bei kleinen Sektionen
+    sinkt sie auf die Sub-Zahl (2 unbelegte Claims in 2 Subs sind viel, nicht wenig)."""
+    claims = verdict["claims"]
+    falsch = [c for c in claims if c["urteil"] == "falsch"]
+    schwelle = min(GATE_FIX_MIN, n_rel) if n_rel else GATE_FIX_MIN
+    if claims and not falsch and len(claims) < schwelle:
+        claims = []
+    zeilen = [f"- CLAIM ({c['urteil']}): {c['text']}" + (f" — {c['grund']}" if c['grund'] else "")
+              for c in claims]
+    zeilen += [f"- LÜCKE ({l['ziel']}): {l['fehlt']}" for l in verdict["luecken"]]
+    zeilen += [f"- BALLAST (kürzen): {b}" for b in verdict["ballast"]]
+    zeilen += [f"- LESBARKEIT: {p}" for p in verdict["lese_probleme"]]
+    zeilen += [f"- LESBARKEIT: {p}" for p in det]
+    return zeilen, bool(falsch or verdict["luecken"])
+
+
+async def _pruefer_call(env: _Env, card: dict, sec: dict, tag: str, det: list[str]) -> dict | None:
+    """EIN Judge-Call prüft Fakten + Coverage + Lesbarkeit (die drei lasen vorher denselben
+    Section-Text in drei seriellen Calls). Text-Antwort + Engine-Sink (Datei-schreibende
+    Judges lieferten invalides JSON). → Verdikt | None (FAILED/CANCELLED)."""
+    norm = card["block_norm"]
+    ziele = await db.list_lernziele(env.topic, norm)
+    ziele_text = "\n".join(f"- ({z['ziel_id']}) {z['text']}" for z in ziele) or "(keine definiert)"
+    ids = {z["ziel_id"] for z in ziele}
+    facts = _card_facts(env, card["block"])
+    ex = await _card_examples(env, norm, env.subs_by_title.get(card["block"], []))
+    if ex:  # der Fix sieht dieselben Facts — Beispiele überleben den Fix-Pass
+        facts += "\n\nVERIFIED WORKED EXAMPLES (count as verified facts for this check):\n" + ex
+    hinweise = ("\nALREADY NOTED deterministically (do NOT repeat, they go to the fix anyway):\n"
+                + "\n".join(f"- {d}" for d in det) + "\n") if det else "\n"
+    path = env.slot(f"pruefer-{_safe(norm)}-{tag}.json")
+    status, verdict = await run_single_slot(
+        env.ctx, f"Prüfer {card['block']}", key=f"{env.guide_id}-pruef-{_safe(norm)}-{tag}",
+        prompt=_prompt("Guide-Pruefer", topic=env.topic, block=card["block"],
+                       section=sec["md"], facts=facts, ziele=ziele_text, spec=env.spec,
+                       hinweise=hinweise, extra=_extra(env.instructions)),
+        role="judge", capabilities="none",
+        payload=lambda result: _sink_json(result, path, lambda d: _pruefer_schema(d, ids)),
+        timeout=_timeout("fakten_gate", 1))
+    if status != OK or verdict is None:
+        return None
+    for zid, ok in verdict["ziele"].items():
+        if zid in ids:
+            await db.set_ziel_covered(env.topic, norm, zid, ok)
+    return verdict
+
+
+async def _stage_pruefer(env: _Env, card: dict) -> bool:
+    """Verschmolzener Qualitäts-Pass: Fakten-Gate + Coverage + Lese-Check in EINEM Call
+    (vorher 3 serielle Judges + bis zu 3 Edit-Pässe, die einander überschrieben und deren
+    letzter ungeprüft blieb). Befunde → Fix-Stage; ohne Befund → done."""
+    sec = _first_section(card["md"])
+    if sec is None:
+        await _set(env, card, status="error", gate_info="Writer-Fragment unlesbar")
+        return False
+    det = (await _det_readability(sec)) + _det_hinweise(env, card, sec)
+    verdict = await _pruefer_call(env, card, sec, f"r{card['writer_rounds']}", det)
+    if verdict is None:
+        if is_guide_cancelled(env.guide_id):
+            return False
+        # fail-open wie das alte Gate: Karte nie blockieren — deterministische Befunde
+        # gehen trotzdem in den Fix
+        _log(env.topic, f"Prüfer {card['block']}: kein Ergebnis — nur deterministische Checks")
+        verdict = {"claims": [], "ziele": {}, "luecken": [], "ballast": [], "lese_probleme": []}
+    zeilen, kritisch = _auftraege(verdict, det, _n_rel(env, card))
+    if not zeilen:
+        await _set(env, card, md=card["md"], stage="done", status="ok", gate_info="")
+        return True
+    _log(env.topic, f"Prüfer {card['block']}: {len(zeilen)} Befund(e){' (kritisch)' if kritisch else ''} → Fix")
+    await _set(env, card, gate_info=("KRITISCH\n" if kritisch else "") + "\n".join(zeilen),
+               stage="fix", status="open")
+    return True
+
+
+async def _stage_fix(env: _Env, card: dict) -> bool:
+    """EIN kompletter Section-Rewrite unter allen Auflagen (ersetzt Fakten-Fix +
+    Writer-Revision + Lese-Fix). Danach GENAU EIN Re-Prüfer-Pass, wenn der Fix wegen
+    falsch-Claims/Lücken lief — der alte Lese-Fix blieb ungeprüft. Rest-Befunde bleiben
+    sichtbar (gate_info), keine weitere Fix-Runde."""
+    from guide import _level_label
+    norm = card["block_norm"]
+    sec = _first_section(card["md"])
+    if sec is None:
+        await _set(env, card, status="error", gate_info="Fragment unlesbar")
+        return False
+    info = card.get("gate_info") or ""
+    kritisch = info.startswith("KRITISCH\n")
+    auftraege = info.removeprefix("KRITISCH\n")
+    subs = env.subs_by_title.get(card["block"], [])
+    sub_list = "\n".join(f"- [{_level_label(s)}] {s['title']}" for s in subs) or "(none)"
+    fixp = env.slot(f"fix-{_safe(norm)}-r{card['writer_rounds']}.md")
+    fixp.unlink(missing_ok=True)
+
+    def _fixload(result):
+        text = fixp.read_text(encoding="utf-8") if fixp.exists() else ""
+        return text if _first_section(text) else None
+
+    fstatus, fixed = await run_single_slot(
+        env.ctx, f"Fix {card['block']}", key=f"{env.guide_id}-gfix-{_safe(norm)}-r{card['writer_rounds']}",
+        prompt=_prompt("Guide-Fix", topic=env.topic, format_name=env.format, block=card["block"],
+                       section=card["md"], facts=_card_facts(env, card["block"]), spec=env.spec,
+                       auftraege=auftraege, sub_list=sub_list, out_path=fixp,
+                       extra=_extra(env.instructions)),
+        role="guide", capabilities="files", payload=_fixload,
+        timeout=_timeout("writer", 1))
+    if fstatus == CANCELLED:
+        return False
+    angewandt = False
+    if fstatus == OK and fixed:
+        new_sec = _first_section(fixed)
+        # marker invariant: a fix that loses the sub markers kills the level filter → discard
+        if sec.get("subs") and not (new_sec and new_sec.get("subs")):
+            _log(env.topic, f"Fix {card['block']} ohne Sub-Marker — verworfen")
+        else:
+            card["md"] = fixed
+            angewandt = True
+    rest = ""
+    if kritisch and angewandt:
+        sec2 = _first_section(card["md"])
+        verdict = await _pruefer_call(env, card, sec2, "re", [])
+        if verdict is None and is_guide_cancelled(env.guide_id):
+            return False
+        if verdict:
+            zeilen, _k = _auftraege(verdict, [], _n_rel(env, card))
+            if zeilen:
+                rest = "Rest-Befunde nach Fix:\n" + "\n".join(zeilen)
+                _log(env.topic, f"Re-Prüfer {card['block']}: {len(zeilen)} Rest-Befund(e) bleiben")
+    await _set(env, card, md=card["md"], stage="done", status="ok", gate_info=rest)
+    return True
+
+
+_STAGE_FN = {"lernziele": _stage_lernziele, "zuweisung": _stage_zuweisung,
+             "writer": _stage_writer, "pruefer": _stage_pruefer, "fix": _stage_fix}
+
+
+async def _run_card(env: _Env, card: dict, sem: asyncio.Semaphore) -> None:
+    async with sem:
+        try:
+            await _run_card_inner(env, card)
+        finally:
+            _live_info.pop((env.topic, env.format, card["block_norm"]), None)
+
+
+async def _run_card_inner(env: _Env, card: dict) -> None:
+    while card["stage"] != "done":
+        if is_guide_cancelled(env.guide_id):
+            await _set(env, card, status="open")  # no longer being worked
+            return
+        fn = _STAGE_FN.get(card["stage"])
+        if fn is None:  # unknown stage → park as error
+            await _set(env, card, status="error", gate_info=f"Unbekannte Stage {card['stage']}")
+            return
+        if card["status"] != "active":
+            await _set(env, card, status="active")  # live board: this card is being worked
+        _live(env, card, STAGE_LABELS.get(card["stage"], card["stage"]) + "…")
+        try:
+            if not await fn(env, card):
+                return
+        except Exception as e:
+            log.exception("[%s] guide card %s failed", env.topic, card["block"])
+            await _set(env, card, status="error", gate_info=f"{type(e).__name__}: {e}"[:300])
+            return
+
+
+# ── Orchestration ──────────────────────────────────────────────────────────────────
+async def _chapter_map(topic: str, entries: dict[int, str]) -> dict[str, tuple[str, int]]:
+    """block_norm → (chapter title, global order) from the outline artefact."""
+    from guide import _outline_from_db, _fallback_outline, _with_remainder
+    plan = await _outline_from_db(topic, entries) or _fallback_outline(entries)
+    plan = _with_remainder(plan, entries)
+    out: dict[str, tuple[str, int]] = {}
+    i = 0
+    for ch in plan:
+        for num in ch.get("nums", []):
+            if num in entries:
+                out[_norm_title(_title(entries[num]))] = (ch.get("title") or "Kapitel", i)
+                i += 1
+    return out
+
+
+async def run_guide_board(guide_id: str, topic: str, format_name: str, entries: dict[int, str],
+                          instructions: str, provider: str, content_path) -> list[dict] | None:
+    """Seed one card per block (existing cards keep their stage — resume), run all cards,
+    assemble the chapters in the legacy content format. → chapters | None (cancel/empty)."""
+    from blocks import source_folder
+    from guide import _load_subblocks
+    ctx = GenContext(topic=topic, provider=provider,
+                     is_cancelled=lambda: is_guide_cancelled(guide_id), guide_id=guide_id)
+    import uuid
+    from datetime import datetime, timezone
+    db.set_current_run(topic, f"{datetime.now(timezone.utc).strftime('%Y%m%d-%H%M')}-g{uuid.uuid4().hex[:4]}")
+    try:
+        spec = (TEMPLATES_DIR / "Format" / "Section.md").read_text(encoding="utf-8")
+        subs_raw = await _load_subblocks(topic)
+        project = source_folder(topic)
+        fallback = (_prompt("Guide-Facts-Projekt", project=project) if project
+                    else _prompt("Guide-Facts-Thema"))
+        env = _Env(ctx, guide_id, topic, format_name, instructions, content_path,
+                   subs_raw, await _chapter_map(topic, entries), fallback, spec)
+        for num, line in entries.items():
+            title = _title(line)
+            await db.upsert_guide_card(topic, format_name, _norm_title(title), title)
+        cards = await db.list_guide_cards(topic, format_name)
+        open_cards = [c for c in cards if c["stage"] != "done"]
+        if open_cards:
+            sem = asyncio.Semaphore(CARD_CONCURRENCY)
+
+            async def _progress():
+                while True:
+                    counts = await db.guide_stage_counts(topic, format_name)
+                    done = counts.get("done", 0)
+                    total = sum(counts.values())
+                    await db.update_guide(guide_id, progress=f"Board: {done}/{total} Karten fertig")
+                    await asyncio.sleep(2.0)
+
+            reporter = asyncio.create_task(_progress())
+            try:
+                await asyncio.gather(*[_run_card(env, c, sem) for c in open_cards])
+            finally:
+                reporter.cancel()
+        if is_guide_cancelled(guide_id):
+            return None
+        # assembly — identical shape to the legacy pipeline
+        cards = await db.list_guide_cards(topic, format_name)
+        chapters: list[dict] = []
+        by_chapter: dict[str, list[dict]] = {}
+        order: list[str] = []
+        for c in sorted(cards, key=lambda c: (c["ord"], c["block_norm"])):
+            if c["stage"] != "done":
+                _log(topic, f"Guide: Karte '{c['block']}' nicht fertig ({c['stage']}) — Abschnitt fehlt")
+                continue
+            sec = _first_section(c["md"])
+            if sec is None:
+                continue
+            ch = c["chapter"] or "Inhalte"
+            if ch not in by_chapter:
+                by_chapter[ch] = []
+                order.append(ch)
+            by_chapter[ch].append({
+                "num": c["ord"], "title": c["block"], "md": sec["md"],
+                "compact": sec.get("compact", ""), "anchor": sec.get("anchor", ""),
+                "anker_compact": sec.get("anker_compact", ""), "subs": sec.get("subs", []),
+                "checkable": format_name == "Guide" or bool(
+                    any(s.get("relevance") == "relevant" for s in subs_raw.get(c["block"], []))),
+            })
+        for ch in order:
+            chapters.append({"title": ch, "sections": by_chapter[ch]})
+        if chapters:
+            try:  # Abschluss-Guide-QA (best-effort): speist das Badge mit einer frischen Note
+                import guide_qa
+                rep = await guide_qa.guide_qa_report(topic, llm=True)
+                if rep:
+                    await asyncio.to_thread(guide_qa._write_report, rep)
+            except Exception:
+                log.exception("[%s] Abschluss-Guide-QA fehlgeschlagen", topic)
+        return chapters or None
+    finally:
+        # erst NACH der Abschluss-Guide-QA leeren: deren Judge-Events gehören zum
+        # Lauf — vorher fielen sie ohne run_id aus jeder Run-Aggregation
+        db.set_current_run(topic, None)
+
+
+async def done_step(topic: str, format_name: str) -> int:
+    """Sidebar dots: highest fully completed stage index. -1 = nothing, len(stages) at done."""
+    counts = await db.guide_stage_counts(topic, format_name)
+    if not counts:
+        return -1
+    if set(counts) == {"done"}:
+        return len(GUIDE_STAGES)
+    lowest = min(GUIDE_STAGES.index(s) for s in counts if s in GUIDE_STAGES)
+    return lowest - 1 if lowest > 0 else -1
+
+
+async def board_snapshot(topic: str, format_name: str, limit: int = 20) -> dict:
+    """Live guide board: columns with counts + cards (title, rounds, covered objectives)."""
+    cards = await db.list_guide_cards(topic, format_name)
+    ziele = {}
+    for z in await db.list_lernziele(topic):
+        d = ziele.setdefault(z["block_norm"], [0, 0])
+        d[1] += 1
+        d[0] += 1 if z["covered"] else 0
+    columns = []
+    for stage in (*GUIDE_STAGES, "done"):
+        in_stage = [c for c in cards if c["stage"] == stage]
+        views = []
+        for c in in_stage[:limit]:
+            zc = ziele.get(c["block_norm"])
+            info = c["gate_info"][:200] if c["status"] == "error" else ""
+            if c["status"] == "active":
+                info = _live_info.get((topic, format_name, c["block_norm"]), "") or info
+            views.append({"title": c["block"], "card_id": c["block_norm"],
+                          "status": c["status"] if c["status"] in ("error", "active") else "open",
+                          "rounds": c["writer_rounds"],
+                          "info": info,
+                          "ziele": f"{zc[0]}/{zc[1]}" if zc else ""})
+        columns.append({"key": stage, "label": STAGE_LABELS[stage],
+                        "total": len(in_stage), "cards": views})
+    import qa as qa_mod  # lazy wie in board_inventory
+    tdir = qa_mod.QA_DIR / topic
+    greports = sorted(tdir.glob("guide-*.json"), key=lambda p: p.stat().st_mtime) if tdir.is_dir() else []
+    note_guide = (_json_file(greports[-1]) or {}).get("note_guide") if greports else None
+    return {"columns": columns, "qa_guide": note_guide}
+
+
+async def repair_karten(topic: str, format_name: str) -> list[str]:
+    """QA-Befund-getriebenes Guide-Repair: Karten, die im jüngsten Guide-QA-Report
+    Befunde tragen, gehen zurück auf `pruefer` (md bleibt) — Prüfer+Fix beheben gezielt,
+    generate_guide resumt die offenen Karten und misst am Ende neu. Pendant zum
+    Blocks-Repair („Score unter 10 muss einen Fix-Pfad haben"). → betroffene Blocktitel."""
+    import qa as qa_mod
+    tdir = qa_mod.QA_DIR / topic
+    reports = sorted(tdir.glob("guide-*.json"), key=lambda p: p.stat().st_mtime) if tdir.is_dir() else []
+    rep = _json_file(reports[-1]) if reports else None
+    if not rep:
+        return []
+    cards = {c["block_norm"]: c for c in await db.list_guide_cards(topic, format_name)}
+    norms: set[str] = set()
+    for e in rep.get("marker_fehlend", []):        # "Block · sub"
+        norms.add(_norm_title(str(e).split(" · ")[0]))
+    for e in rep.get("ziel_ohne_anker", []):       # "block_norm · (id) text"
+        norms.add(str(e).split(" · ")[0])
+    for e in rep.get("laengen_ausreisser", []):    # {"block": titel}
+        norms.add(_norm_title(e.get("block", "") if isinstance(e, dict) else str(e)))
+    for e in rep.get("lesbarkeit", []):            # "Block: hinweis"
+        norms.add(_norm_title(str(e).split(":")[0]))
+    for t in rep.get("fachlich_falsch", []) or []:
+        norms.add(_norm_title(str(t)))
+    for e in rep.get("redundanz", []):             # {"a": "Block: absatz", "b": …}
+        for seite in ("a", "b"):
+            norms.add(_norm_title(str(e.get(seite, "")).split(":")[0]))
+    betroffen = []
+    for n in sorted(norms & set(cards)):
+        await db.set_guide_card(topic, format_name, n, stage="pruefer", status="open", gate_info="")
+        betroffen.append(cards[n]["block"])
+    return betroffen
+
+
+async def reset_card(topic: str, format_name: str, block_norm: str, ab_stage: int) -> bool:
+    """Reset ONE guide card to a stage (single-card variant of reset_from_stage):
+    fields re-zeroed, md only wiped for writer(2) and earlier, lernziele only for 0."""
+    ab_stage = max(0, min(ab_stage, len(GUIDE_STAGES) - 1))
+    cards = {c["block_norm"]: c for c in await db.list_guide_cards(topic, format_name)}
+    if block_norm not in cards:
+        return False
+    fields = dict(stage=GUIDE_STAGES[ab_stage], status="open", writer_rounds=0, gate_info="")
+    if ab_stage <= 2:
+        fields["md"] = ""
+    if ab_stage == 0:
+        await db.delete_lernziele(topic, block_norm)
+    await db.set_guide_card(topic, format_name, block_norm, **fields)
+    return True
+
+
+async def reset_from_stage(topic: str, format_name: str, ab_stage: int) -> int:
+    """Cards in stages ≥ ab_stage (incl. done) back to GUIDE_STAGES[ab_stage]."""
+    ab_stage = max(0, min(ab_stage, len(GUIDE_STAGES) - 1))
+    target = GUIDE_STAGES[ab_stage]
+    stages = list(GUIDE_STAGES[ab_stage:]) + ["done"]
+    if ab_stage == 0:
+        for c in await db.list_guide_cards(topic, format_name):
+            await db.delete_lernziele(topic, c["block_norm"])
+    moved = await db.reset_guide_cards_from_stage(topic, format_name, stages, target,
+                                                  clear_md=ab_stage <= 2)
+    return moved

backend/guide_qa.py

@@ -0,0 +1,258 @@
+"""Unabhängiges Guide-Audit über einen FERTIGEN Guide — read-only.
+
+Misst den gebauten Guide (guide_cards) gegen Lernziele und Sub-Satz mit Detektoren,
+die bewusst NICHT die Pipeline-Gates wiederverwenden (covered-Flag, Fakten-Gate) —
+geteilte blinde Flecken machen das Audit wertlos. Geteilt nur Infra: DB, readability,
+Agent-Runner (--llm), Note-Formel aus qa.py.
+
+CLI:  python3 guide_qa.py <topic> [--llm]     (oder: make qa-guide TOPIC=<topic> [LLM=1])
+Report: storage/qa/<topic>/guide-<ts>.json + Konsolen-Digest.
+"""
+
+import asyncio
+import json
+import re
+import sys
+from datetime import datetime, timezone
+
+import database as db
+import qa
+import readability
+from fsutil import atomic_write_json
+from textkit import _norm_title
+
+JACCARD_ABSATZ = 0.6      # Wort-Jaccard, ab dem zwei Absätze als Doppel gelten
+ABSATZ_MIN_CHARS = 200    # kürzere Absätze sind Übergänge — kein Dubletten-Signal
+LLM_SECTION_CHARS = 2500  # Section-Auszug je Judge-Item
+# fachliche Fehler wiegen am schwersten; Anker-lose Ziele = Coverage-Behauptung ohne Text.
+NOTE_GEWICHTE_GUIDE = {"fachlich_falsch": 3.0, "ziel_ohne_anker": 2.0, "marker_fehlend": 1.5,
+                       "redundanz": 1.0, "laengen_ausreisser": 0.5, "lesbarkeit": 0.5}
+
+_MARKER = re.compile(r"<!--\s*sub:\s*\w+\s*\|\s*(.*?)\s*-->")
+
+
+def _mnorm(s: str) -> str:
+    """Marker-/Sub-Norm ohne Backslashes — escapte Titel (`h\\~2\\~o`) erzeugten
+    falsch-positive „Marker fehlt"-Befunde, weil Writer und DB verschieden escapen."""
+    return _norm_title(s.replace("\\", ""))
+
+
+def _ausfuehrlich(md: str) -> str:
+    """Der Lern-Fließtext einer Karte (hinter dem ausführlich-Marker, sonst alles)."""
+    teile = re.split(r"<!--\s*ausführlich\s*-->", md or "", maxsplit=1)
+    return teile[1] if len(teile) == 2 else (md or "")
+
+
+def marker_fehlend(cards: list[dict], subs_rel: dict[str, set]) -> list[str]:
+    """Relevante Subs ohne Sub-Marker in der Section — der Level-Filter verliert sie."""
+    out = []
+    for c in cards:
+        marker = {_mnorm(m) for m in _MARKER.findall(c["md"] or "")}
+        for sn in sorted(subs_rel.get(c["block_norm"], set())):
+            mn = _mnorm(sn)
+            if mn not in marker and not any(m.startswith(mn) or mn.startswith(m) for m in marker):
+                out.append(f"{c['block']} · {sn}")
+    return out
+
+
+def ziel_ohne_anker(cards: list[dict], ziele: list[dict]) -> list[str]:
+    """Lernziele, deren distinktive Tokens im Section-Text fehlen — eigener Anker-Check,
+    NICHT das covered-Flag der Pipeline (das hat der Coverage-Judge selbst gesetzt)."""
+    text_by_norm = {c["block_norm"]: qa._tokens(_ausfuehrlich(c["md"])) for c in cards}
+    out = []
+    for z in ziele:
+        toks = qa._distinctive(z["text"])
+        st = text_by_norm.get(z["block_norm"])
+        if st is None or not toks:
+            continue
+        if len(toks & st) < min(2, len(toks)):
+            out.append(f"{z['block_norm']} · ({z['ziel_id']}) {z['text'][:60]}")
+    return out
+
+
+# Längenbudget je Sub aus der Inventar-Substanz — ersetzt den festen Rahmen 150–1200/Sub:
+# ein dichter Sub (viele key_points, Fakten, Beispiel) trägt mehr Text als ein Einzeiler.
+# Die Pipeline (Writer-Vorgabe, Prüfer-Trigger, Fix-Ziel) nutzt DIESELBE Formel mit engerem
+# Band — Messlatte und Fix-Auftrag müssen übereinstimmen, sonst sind Befunde unfixbar.
+BUDGET_BASIS = 200        # Einstieg/Übergang je Sub
+BUDGET_KEY_POINT = 160    # ~1–2 Sätze Erklärung je key_point
+BUDGET_FAKT = 60          # zitierter Fakt, in den Text eingewoben
+BUDGET_BEISPIEL = 250     # ausgearbeitetes Beispiel
+LAENGE_BAND = (0.35, 1.5) # QA-Toleranz um das Blockbudget
+
+
+def sub_budget(facts: dict) -> int:
+    """Zeichenbudget für den ausführlich-Teil EINES Subs (facts = Inventar-JSON des Subs)."""
+    kp = len(facts.get("key_points") or [])
+    cf = len(facts.get("cited_facts") or [])
+    ex = 1 if str(facts.get("example_idea") or "").strip() else 0
+    return BUDGET_BASIS + BUDGET_KEY_POINT * kp + BUDGET_FAKT * cf + BUDGET_BEISPIEL * ex
+
+
+def block_budget(subs: list[dict]) -> int:
+    """Budget einer Section: Summe über die relevanten Subs ({relevance, facts}-Dicts)."""
+    return max(BUDGET_BASIS, sum(sub_budget(s.get("facts") or {}) for s in subs
+                                 if s.get("relevance") != "peripheral"))
+
+
+def laengen_ausreisser(cards: list[dict], budget_by_norm: dict[str, int]) -> list[dict]:
+    out = []
+    for c in cards:
+        budget = budget_by_norm.get(c["block_norm"])
+        if not budget:
+            continue
+        zeichen = len(_ausfuehrlich(c["md"]))
+        if not (LAENGE_BAND[0] * budget <= zeichen <= LAENGE_BAND[1] * budget):
+            out.append({"block": c["block"], "zeichen": zeichen, "budget": budget})
+    return out
+
+
+def redundanz(cards: list[dict]) -> list[dict]:
+    """Absatz-Paare topic-weit mit hoher Token-Überlappung — derselbe Stoff doppelt erklärt."""
+    absaetze = []
+    for c in cards:
+        for a in _ausfuehrlich(c["md"]).split("\n\n"):
+            a = a.strip()
+            if len(a) >= ABSATZ_MIN_CHARS:
+                absaetze.append((c["block"], a, qa._tokens(a)))
+    out = []
+    for i in range(len(absaetze)):
+        for j in range(i + 1, len(absaetze)):
+            if qa._jaccard(absaetze[i][2], absaetze[j][2]) >= JACCARD_ABSATZ:
+                out.append({"a": f"{absaetze[i][0]}: {absaetze[i][1][:60]}",
+                            "b": f"{absaetze[j][0]}: {absaetze[j][1][:60]}"})
+    return out
+
+
+def lesbarkeit(cards: list[dict]) -> list[str]:
+    """Deterministisches externes Rating; Modell nicht ladbar → nicht gemessen (zählt nicht)."""
+    try:
+        hints = readability.rate_sections({i: _ausfuehrlich(c["md"]) for i, c in enumerate(cards, 1)})
+    except Exception:
+        return []
+    return [f"{cards[i - 1]['block']}: {h}" for i, h in sorted(hints.items()) if h]
+
+
+async def _fachlich_falsch(topic: str, cards: list[dict]) -> list[str]:
+    """LLM-Stichprobe: Section enthält eine fachlich falsche Aussage? Zwei unabhängige
+    Durchgänge, nur DOPPELT bestätigte zählen — ein Einzel-Judge schwankte zwischen
+    0 und 5 Befunden am selben Guide und kippte die Note (Gewicht 3.0) auf 0."""
+    from agents import run_agent
+    from jsonio import parse_json_text
+    from pipeline import _yesno_schema
+
+    async def _pass(kandidaten: list[dict], tag: str) -> list[str]:
+        out = []
+        for lo in range(0, len(kandidaten), 5):
+            chunk = kandidaten[lo:lo + 5]
+            listing = "\n\n".join(f"{k}. SECTION {c['block']}:\n{_ausfuehrlich(c['md'])[:LLM_SECTION_CHARS]}"
+                                  for k, c in enumerate(chunk, 1))
+            rc, txt, _err = await run_agent(
+                f"qa-guide-{topic}-fakten{tag}-{lo}", qa._qa_prompt("QA-Guide-Fakten", topic=topic, extra="", sections=listing),
+                600, role="judge", capabilities="none", scope=topic, label=f"Guide-QA Fakten{tag} {lo}")
+            v = (_yesno_schema(parse_json_text(txt)) or {}) if rc == 0 else {}
+            out += [c["block"] for k, c in enumerate(chunk, 1) if v.get(k) == "ja"]
+        return out
+
+    verdacht = await _pass(cards, "")
+    if not verdacht:
+        return []
+    # ZWEI unabhängige Bestätiger, beide müssen zustimmen — mit nur einem sprang die
+    # Note desselben Guides weiter zwischen 2.0 und 6.6 (ein Zufalls-ja kostet 1.5 Punkte)
+    kandidaten = [c for c in cards if c["block"] in set(verdacht)]
+    b1 = set(await _pass(kandidaten, "-2"))
+    if not b1:
+        return []
+    b2 = set(await _pass([c for c in kandidaten if c["block"] in b1], "-3"))
+    return [b for b in verdacht if b in b1 and b in b2]
+
+
+async def guide_qa_report(topic: str, llm: bool = False) -> dict | None:
+    cards = [dict(r) for r in await db.list_guide_cards(topic)]
+    cards = [c for c in cards if (c.get("md") or "").strip()]
+    if not cards:
+        print(f"Keine Guide-Karten für '{topic}' — Guide noch nicht gebaut?")
+        return None
+    subs_rel: dict[str, set] = {}
+    subs_by_norm: dict[str, list[dict]] = {}
+    for r in await db.list_subblocks(topic):
+        if r["status"] != "consensus":
+            continue
+        try:
+            facts = json.loads(r["facts"]) if r["facts"] else {}
+        except (ValueError, TypeError):
+            facts = {}
+        subs_by_norm.setdefault(r["block_norm"], []).append(
+            {"relevance": r["relevance"], "facts": facts if isinstance(facts, dict) else {}})
+        if r["relevance"] != "peripheral":
+            subs_rel.setdefault(r["block_norm"], set()).add(r["sub_norm"])
+    ziele = [dict(r) for r in await db.list_lernziele(topic)]
+
+    mf = marker_fehlend(cards, subs_rel)
+    za = ziel_ohne_anker(cards, ziele)
+    la = laengen_ausreisser(cards, {n: block_budget(s) for n, s in subs_by_norm.items()})
+    rd = redundanz(cards)
+    lb = lesbarkeit(cards)
+    falsch = await _fachlich_falsch(topic, cards) if llm else None
+
+    n_subs = max(sum(len(s) for s in subs_rel.values()), 1)
+    n_abs = max(sum(len([a for a in _ausfuehrlich(c["md"]).split("\n\n") if len(a.strip()) >= ABSATZ_MIN_CHARS])
+                    for c in cards), 1)
+    quoten = {
+        "marker_fehlend": round(len(mf) / n_subs, 3),
+        "ziel_ohne_anker": round(len(za) / max(len(ziele), 1), 3),
+        "laengen_ausreisser": round(len(la) / len(cards), 3),
+        "redundanz": round(len(rd) / n_abs, 3),
+        "lesbarkeit": round(len(lb) / len(cards), 3),
+        **({"fachlich_falsch": round(len(falsch) / len(cards), 3)} if falsch is not None else {}),
+    }
+    report = {
+        "topic": topic, "erstellt": datetime.now(timezone.utc).isoformat(), "art": "guide",
+        "bloecke": len(cards), "ziele": len(ziele),
+        "quoten": quoten, "note_guide": qa.note(quoten, NOTE_GEWICHTE_GUIDE),
+        "marker_fehlend": mf, "ziel_ohne_anker": za, "laengen_ausreisser": la,
+        "redundanz": rd[:20], "lesbarkeit": lb,
+        **({"fachlich_falsch": falsch} if falsch is not None else {}),
+        "note_gewichte": NOTE_GEWICHTE_GUIDE,
+    }
+    return report
+
+
+def _write_report(report: dict):
+    tdir = qa.QA_DIR / report["topic"]
+    tdir.mkdir(parents=True, exist_ok=True)
+    path = tdir / f"guide-{datetime.now(timezone.utc).strftime('%Y%m%d-%H%M%S')}.json"
+    atomic_write_json(path, report, indent=1)
+    return path
+
+
+def _digest(report: dict, path):
+    print(f"Guide-QA {report['topic']} — {report['bloecke']} Sections, {report['ziele']} Ziele"
+          f" — Note {report['note_guide']}/10")
+    for k, v in report["quoten"].items():
+        print(f"  {k:20} {v:6.1%}")
+    for k in ("marker_fehlend", "ziel_ohne_anker", "lesbarkeit", "fachlich_falsch"):
+        for x in report.get(k, [])[:5]:
+            print(f"  {k.upper():16} {str(x)[:90]}")
+    for p in report.get("redundanz", [])[:5]:
+        print(f"  DOPPELT?  {p['a'][:55]} <-> {p['b'][:55]}")
+    print(f"Report: {path}")
+
+
+async def main(topic: str, llm: bool):
+    await db.init_db()
+    try:
+        report = await guide_qa_report(topic, llm=llm)
+        if report is None:
+            sys.exit(1)
+        _digest(report, _write_report(report))
+    finally:
+        await db.close_db()
+
+
+if __name__ == "__main__":
+    args = [a for a in sys.argv[1:] if not a.startswith("--")]
+    if not args:
+        print("Nutzung: python3 guide_qa.py <topic> [--llm]")
+        sys.exit(1)
+    asyncio.run(main(args[0], "--llm" in sys.argv))

backend/jsonio.py

@@ -0,0 +1,49 @@
+"""Tolerant JSON parser for AI output — from text or from files.
+
+Copes with code fences, surrounding prose and unescaped quotes inside
+strings (e.g. MiniMax: "Title „p" changed"): the last `"` before the
+error position is escaped and parsing is retried.
+"""
+
+import json
+import logging
+import re
+from pathlib import Path
+
+log = logging.getLogger("creator.jsonio")
+
+
+def parse_json_text(text: str):
+    """Parse JSON from AI output; None for input that can't be repaired."""
+    text = re.sub(r"^```(?:json)?\s*|\s*```$", "", (text or "").strip())
+    start, end = text.find("{"), text.rfind("}")
+    if start == -1 or end <= start:
+        return None
+    candidate = text[start:end + 1]
+    for _ in range(20):
+        try:
+            return json.loads(candidate)
+        except json.JSONDecodeError as e:
+            if not e.msg.startswith(("Expecting ',' delimiter", "Expecting ':' delimiter")):
+                return None
+            q = candidate.rfind('"', 0, e.pos)
+            if q <= 0:
+                return None
+            candidate = candidate[:q] + '\\"' + candidate[q + 1:]
+        except Exception:
+            return None
+    return None
+
+
+def read_json_file(path: Path):
+    """Read a JSON file with the same tolerance; None if missing/invalid."""
+    if not path.exists():
+        return None
+    try:
+        data = parse_json_text(path.read_text(encoding="utf-8"))
+    except Exception as e:
+        log.debug("JSON file not readable: %s (%s)", path, e)
+        return None
+    if data is None:
+        log.debug("JSON file invalid: %s", path)
+    return data

backend/kanban.py

@@ -0,0 +1,262 @@
+"""Generic streaming kanban engine (no concrete stages — boards define those).
+
+Each column is a worker that pulls cards from its input `stage` (the queue = kanban_cards rows
+WHERE stage = <input>), processes up to KANBAN_BATCH at a time, and advances them. Streaming
+columns run continuously; BARRIER columns start only at QUIESCENCE of every stage before them
+(no active worker + no queued card). SERIAL columns process one package at a time (their
+processor mutates shared cross-card state).
+
+Failure handling: a processor exception (including parse-fails it raises) sends the package's
+unadvanced cards into exponential backoff (retries++, not_before); after MAX_CARD_RETRIES the
+card goes to stage 'dead' (dead-letter — visible on the board, requeue-able via API). No card
+is ever deleted by the engine.
+
+Board definitions live in board_inventory.py / board_artefacts.py; run via run_flow().
+"""
+
+import asyncio
+import logging
+
+import database as db
+from config import KANBAN_BATCH, MAX_CARD_RETRIES, MAX_CONCURRENT_AGENTS_PER_TOPIC, RETRY_BACKOFF
+
+log = logging.getLogger("creator.kanban")
+
+# How many packages ONE worker keeps in flight at once. A worker no longer blocks on a single
+# package — it keeps pulling and dispatching until this many run concurrently, so a busy column
+# fills the agent slots (the per-topic semaphore is the real cap; over-dispatch just queues cheaply).
+WORKER_INFLIGHT = MAX_CONCURRENT_AGENTS_PER_TOPIC
+_POLL = 0.3               # seconds between empty-queue polls
+
+# Live registry of running flows (topic → Flow), so routes can attach research agents,
+# report `generating`, and cancel.
+active_flows: dict[str, "Flow"] = {}
+
+
+class Flow:
+    """Shared runtime state of one topic run: active-task counters per stage + a wakeup event.
+    `producers` counts running research agents (initial + any added live); research counts as done
+    only when ALL producers have finished, so the flow stays awake while extras still search."""
+
+    def __init__(self, topic: str, work_dir=None):
+        self.topic = topic
+        self.work_dir = work_dir
+        self.active: dict[str, int] = {}
+        self.producers = 0
+        self.producer_tag = 0
+        self.stop = False
+        self.wake = asyncio.Event()
+        self.spawn_research = None  # set by the board: () → coroutine adding one more research agent
+        self.state: dict = {}       # board-private shared state (embedding caches, one-shot flags …)
+        self.active_cards: set[str] = set()  # "board:card_id" currently inside a processor (live display)
+
+    @property
+    def research_done(self) -> bool:
+        return self.producers <= 0
+
+    def add_producer(self):
+        """MUST be called synchronously BEFORE create_task of the producer — otherwise workers
+        can pass their exit check in the gap and never see the new producer (quiescence race)."""
+        self.producers += 1
+        self.wake.set()
+
+    def done_producer(self):
+        self.producers -= 1
+        self.wake.set()
+
+    def next_tag(self) -> int:
+        self.producer_tag += 1
+        return self.producer_tag
+
+    def enter(self, stage: str):
+        self.active[stage] = self.active.get(stage, 0) + 1
+
+    def leave(self, stage: str):
+        self.active[stage] = max(0, self.active.get(stage, 0) - 1)
+        self.wake.set()
+
+    def active_in(self, stages) -> bool:
+        return any(self.active.get(s, 0) > 0 for s in stages)
+
+
+class Stage:
+    """One column: board + stage name + processor. `upstream` (all stages before it, across
+    boards) is filled by chain_stages(). process(cards) gets the pulled package (list of card
+    dicts with decoded payload).
+
+    barrier: pull only when every upstream stage is quiescent (relational judgements need the
+    full set). gate: extra callable that must be truthy before the stage pulls (works without
+    barrier too — e.g. the consensus gate holds cards until research is done so late reader
+    votes still count). drain: pull the WHOLE queue as one package (global passes like the
+    fragment filter); implies serial."""
+
+    def __init__(self, board: str, stage: str, process, *, barrier: bool = False,
+                 serial: bool = False, gate=None, drain: bool = False):
+        self.board = board
+        self.stage = stage
+        self.process = process
+        self.barrier = barrier
+        self.serial = serial or drain
+        self.gate = gate
+        self.drain = drain
+        self.upstream: list[str] = []
+
+
+def chain_stages(stages: list[Stage]) -> list[Stage]:
+    """Fill each stage's upstream = every stage listed before it (list order = flow order).
+    Producers are upstream of everything implicitly via flow.research_done."""
+    seen: list[str] = []
+    for s in stages:
+        s.upstream = list(seen)
+        seen.append(s.stage)
+    return stages
+
+
+async def quiescent(flow: Flow, stages) -> bool:
+    """True iff no worker is active in `stages` AND no card is queued in any of them.
+    The barrier/exit condition — must include QUEUED cards, not just active workers, or a worker
+    could exit in a momentary lull while an upstream worker still has work to push down."""
+    if not stages:
+        return True
+    if flow.active_in(stages):
+        return False
+    return await db.kanban_count(flow.topic, list(stages)) == 0
+
+
+async def _sleep_wake(flow: Flow):
+    try:
+        await asyncio.wait_for(flow.wake.wait(), timeout=_POLL)
+    except asyncio.TimeoutError:
+        pass
+    flow.wake.clear()
+
+
+async def _fail_package(flow: Flow, spec: Stage, cards: list[dict], error: str):
+    """Backoff/dead-letter for the cards the processor did NOT advance (their stage is unchanged —
+    advanced cards must not be punished for a failure after their move)."""
+    for c in cards:
+        cur = await db.kanban_get_card(flow.topic, spec.board, c["card_id"])
+        if cur is None or cur["stage"] != spec.stage:
+            continue
+        dead = await db.kanban_fail_card(flow.topic, spec.board, c["card_id"], error,
+                                         MAX_CARD_RETRIES, RETRY_BACKOFF)
+        if dead:
+            log.warning("kanban %s/%s: card %s → dead (%s)", flow.topic, spec.stage, c["card_id"], error)
+
+
+async def _worker(flow: Flow, spec: Stage, inflight: int, all_stages: list[str]):
+    """Pull cards from spec.stage, run spec.process — keeping up to `inflight` packages running
+    CONCURRENTLY so a busy column fills the agent slots. A barrier worker only pulls when upstream
+    is fully quiescent (and its gate, if any, is open). ANY worker exits only when research is
+    done and the WHOLE flow is quiescent — global instead of per-stage, so a downstream stage
+    that feeds cards back upstream (gap-check → ingest) never strands work. Double-checked over
+    one grace sleep (a producer attached in the lull keeps the flow alive).
+
+    Double-pull safety: each stage has exactly ONE worker, so an in-memory `claimed` set of
+    card-ids (held while a package runs) keeps concurrent pulls from grabbing the same cards."""
+    topic = flow.topic
+    claimed: set[str] = set()
+    tasks: set[asyncio.Task] = set()
+    batch = 100_000 if spec.drain else KANBAN_BATCH
+
+    async def _run(cards):
+        ids = [c["card_id"] for c in cards]
+        flow.enter(spec.stage)
+        flow.active_cards.update(f"{spec.board}:{i}" for i in ids)
+        try:
+            await spec.process(cards)
+        except Exception as e:  # one bad package must not kill the worker → backoff/dead-letter
+            log.info("kanban %s/%s: %s: %s", topic, spec.stage, type(e).__name__, e)
+            try:
+                await _fail_package(flow, spec, cards, f"{type(e).__name__}: {e}")
+            except Exception:
+                log.exception("kanban %s/%s: fail-handling broke", topic, spec.stage)
+        finally:
+            flow.leave(spec.stage)
+            for i in ids:
+                claimed.discard(i)
+                flow.active_cards.discard(f"{spec.board}:{i}")
+            flow.wake.set()
+
+    async def _idle_exit() -> bool:
+        return (flow.research_done and not flow.active_in(all_stages)
+                and await db.kanban_count(topic, all_stages) == 0)
+
+    async def _may_pull() -> bool:
+        if spec.gate is not None and not spec.gate():
+            return False
+        if not spec.barrier:
+            return True
+        return await quiescent(flow, spec.upstream)
+
+    try:
+        while not flow.stop:
+            tasks = {t for t in tasks if not t.done()}
+            # Fill the pipeline: pull fresh cards and dispatch until `inflight` packages run.
+            if await _may_pull():
+                while len(tasks) < inflight:
+                    rows = await db.kanban_pull(topic, spec.board, spec.stage, batch + len(claimed))
+                    fresh = [r for r in rows if r["card_id"] not in claimed][:batch]
+                    if not fresh:
+                        break
+                    for r in fresh:
+                        claimed.add(r["card_id"])
+                    tasks.add(asyncio.create_task(_run(list(fresh))))
+            if tasks:  # busy → wait for a package to finish, then refill
+                await asyncio.wait(tasks, timeout=_POLL, return_when=asyncio.FIRST_COMPLETED)
+                continue
+            # idle: nothing in flight and nothing pulled
+            if await _idle_exit():
+                # Real grace sleep (NOT _sleep_wake — the wake event is usually already set
+                # by the last package and would collapse the window to 0ms). A producer
+                # attached during the lull flips research_done and keeps us alive.
+                await asyncio.sleep(_POLL)
+                if await _idle_exit():
+                    return  # nothing left and nothing upstream can produce
+                continue
+            await _sleep_wake(flow)
+    finally:
+        for t in tasks:
+            t.cancel()
+        if tasks:
+            await asyncio.gather(*tasks, return_exceptions=True)
+
+
+async def run_flow(flow: Flow, stages: list[Stage], producers=(), set_p=None) -> None:
+    """Run producers + one worker per stage until global quiescence. `producers` are coroutines
+    already counted via flow.add_producer() BEFORE this call (quiescence race). Registers the
+    flow in active_flows for live attach/cancel."""
+    active_flows[flow.topic] = flow
+    names = [s.stage for s in stages]
+
+    def _spawn_workers():
+        return [asyncio.ensure_future(_worker(flow, s, 1 if s.serial else WORKER_INFLIGHT, names))
+                for s in stages]
+
+    workers = [asyncio.ensure_future(p) for p in producers] + _spawn_workers()
+    progress = asyncio.create_task(_progress(flow, set_p)) if set_p else None
+    try:
+        while True:
+            await asyncio.gather(*workers, return_exceptions=True)
+            # Restart round: a producer attached exactly as the workers exited (missed even the
+            # grace sleep) leaves live producers or queued cards behind → run the workers again.
+            if flow.stop or (flow.research_done and await quiescent(flow, names)):
+                break
+            workers = _spawn_workers()
+    finally:
+        flow.stop = True
+        if progress:
+            progress.cancel()
+        if active_flows.get(flow.topic) is flow:
+            active_flows.pop(flow.topic, None)
+
+
+async def _progress(flow: Flow, set_p):
+    while not flow.stop:
+        try:
+            counts = await db.kanban_stage_counts(flow.topic)
+            total = sum(n for stages in counts.values() for n in stages.values())
+            set_p(f"Kanban: {total} Karten im Fluss")
+        except Exception:
+            pass
+        await asyncio.sleep(1.0)

backend/learning.py

@@ -0,0 +1,657 @@
+"""Block learning: deep-dive, block chat and exam for individual guide sections.
+
+All calls are interactive (stdout response, lane "interactive") and stateless —
+the chat/exam history comes from the frontend; only the exam counter (DB) and
+the deep-dive (DB) are persisted.
+"""
+
+import logging
+import random
+import re
+import uuid
+from datetime import datetime, timezone
+
+from agents import run_agent
+from config import DEFAULT_PROVIDER
+from database import get_block_hurdles
+from jsonio import parse_json_text as _parse_json_text
+from pipeline import _prompt, _problems_schema
+from textkit import _norm_title
+
+log = logging.getLogger("creator.learning")
+
+# Learning levels per block — relative to the cap (floor as % of the max score):
+# green=beginner 20% · blue=advanced 40% · purple=expert 60% · gold=master 100%.
+# Exam form is always random (5 forms); the cap scales with the amount of material.
+LEVELS = (("beginner", 0.2), ("advanced", 0.4), ("expert", 0.6), ("master", 1.0))
+
+
+POINTS_BASE = 25  # Points per subblock. Master cap = (all subs) × 25.
+
+# Leitner boxes for the flashcard practice deck: roughly doubling intervals cover
+# session → day → week → month. Box 1 with interval 0 = a failed card stays due in
+# the running session. Absolute UTC times, no day-boundary semantics (timezone-free).
+LEITNER_INTERVALS = {1: 0, 2: 1, 3: 3, 4: 7, 5: 21}  # days per box
+LEITNER_MAX_BOX = 5
+PRACTICE_NEW_PER_SESSION = 10  # new cards offered per deck fetch
+
+
+def leitner_step(box: int | None, correct: bool) -> tuple[int, int]:
+    """(new box, interval in days). New card + correct → box 2; wrong → box 1 (due now);
+    correct → one box up, capped at LEITNER_MAX_BOX."""
+    if not correct:
+        new = 1
+    elif box is None:
+        new = 2
+    else:
+        new = min(box + 1, LEITNER_MAX_BOX)
+    return new, LEITNER_INTERVALS[new]
+
+
+def _levels(n_je_level: dict[int, int]) -> list[int]:
+    return [n_je_level.get(k, 0) for k in (1, 2, 3, 4)]
+
+
+def thresholds(n_je_level: dict[int, int]) -> list[int]:
+    """Cumulative sub-level thresholds [S_1, S_2, S_3, S_4] = (n_1+…+n_k) × 25.
+    S_k is the score at which sub-level k+1 unlocks; S_4 = cap_final."""
+    out, acc = [], 0
+    for n in _levels(n_je_level):
+        acc += n
+        out.append(acc * POINTS_BASE)
+    return out
+
+
+def cap_final(n_je_level: dict[int, int]) -> int:
+    """Max score (master) = all subblocks × 25."""
+    return thresholds(n_je_level)[-1]
+
+
+def freie_level(score: int, n_je_level: dict[int, int]) -> int:
+    """Highest unlocked sub-level 1–4. Level k+1 unlocks once score ≥ S_k.
+    Empty levels (n_k=0) are skipped automatically (S_k == S_{k-1})."""
+    s = thresholds(n_je_level)
+    e = 1
+    for k in range(3):  # S_1..S_3 unlock levels 2..4
+        if score >= s[k]:
+            e = k + 2
+    return e
+
+
+def cap_aktuell(score: int, n_je_level: dict[int, int]) -> int:
+    """Reachable cap of the currently unlocked level = unlocked subs × 25."""
+    return thresholds(n_je_level)[freie_level(score, n_je_level) - 1]
+
+
+def _threshold(p: float, cap: int) -> int:
+    return round(p * cap)
+
+
+def level_from_score(score: int, cap_final_value: int) -> str | None:
+    """Highest reached learning level (None below 20%), relative to cap_final."""
+    reached = None
+    for key, p in LEVELS:
+        if score >= _threshold(p, cap_final_value):
+            reached = key
+    return reached
+
+
+def progressive_malus(basis: int, cap_akt: int) -> int:
+    """Error penalty by progress within the current level (against cap_aktuell):
+    ≤25%→−5 · ≤50%→−10 · ≤75%→−15 · >75%→−20."""
+    pct = (basis / cap_akt) if cap_akt else 0.0
+    if pct <= 0.25:
+        return -5
+    if pct <= 0.5:
+        return -10
+    if pct <= 0.75:
+        return -15
+    return -20
+CHAT_TIMEOUT = 240
+EXAM_TIMEOUT = 120  # short JSON turns; caps the serial latency per exam step
+THOROUGH_TIMEOUT = 600  # "thorough check": strong model (role guide) takes longer
+CRITIC_MAX_ROUNDS = 2   # Generator → Critic → maybe Regenerate, at most this many times
+
+# Question types for active recall — one per question, chosen at random. Creates variety.
+QUESTION_TYPES = {
+    "abruf": "Free Recall: have the learner explain the core idea freely from memory (open comprehension question).",
+    "punkt": "Cued Recall: ask for ONE specific detail or distinction.",
+    "warum": "Why-question: ask for the reason/mechanism — why does this work or hold?",
+    "anwendung": "Application: have the concept applied to ONE short, new example/scenario.",
+    "pruefen": "For code/tool topics: show a small snippet — predict the output OR find the bug. No code topic → an application question instead.",
+}
+
+
+# Answer tier → base points (new 25-scale). "barely" = −1 is only the signal for the
+# progressive malus (the real value comes from progressive_malus). Positive values are
+# modulated up on a streak and clamped to [10, 40].
+TIERS = {
+    "unanswerable": 0,  # question itself broken → no change
+    "barely": -1,           # < 25% correct → malus
+    "partial": 0,       # 25–49% → neutral
+    "solid": 16,         # 50–74%
+    "strong": 24,          # 75–99% (quiz/gap hit)
+    "complete": 30,       # 100% (only reachable by free explanation)
+}
+
+# Order weak→strong (for the follow-up cap).
+_TIER_RANK = ("barely", "partial", "solid", "strong", "complete")
+
+
+def cap_followup(tier: str, asked_again: bool) -> str:
+    """With a follow-up (hint received) at most "solid" — no full score by cheating."""
+    if asked_again and tier in ("strong", "complete"):
+        return "solid"
+    return tier
+
+
+def streak_points(basis_delta: int, streak_basis: int) -> int:
+    """Modulate a positive base delta up by streak, clamped to [10, 40]."""
+    factor = min(1.33, 1 + 0.066 * min(streak_basis, 5))
+    return max(10, min(40, round(basis_delta * factor)))
+
+
+def points_delta(tier: str, streak_basis: int, basis: int, cap_akt: int) -> tuple[int, int]:
+    """Answer tier → (points delta, new streak). Positive: streak-modulated, streak +1.
+    Neutral (0): no change, streak stays. Negative: progressive malus, streak reset to 0."""
+    basis_delta = TIERS.get(tier, 0)
+    if basis_delta > 0:
+        return streak_points(basis_delta, streak_basis), streak_basis + 1
+    if basis_delta == 0:
+        return 0, streak_basis
+    return progressive_malus(basis, cap_akt), 0
+
+
+def compute_score(basis: int, delta: int, floor: int, cap_akt: int, cap_fin: int) -> int:
+    """New score · drift-free from the base. Clamps up against `cap_akt` (cap of the
+    currently unlocked level) and down against `floor`. Frozen ONLY at the absolute
+    maximum (`basis ≥ cap_fin`) — otherwise it would block at every level threshold."""
+    if basis >= cap_fin:
+        return basis
+    return max(floor, min(cap_akt, basis + delta))
+
+
+def floor_from_score(basis: int, cap_fin: int, s_thresholds: list[int]) -> int:
+    """Lower bound (no fallback): highest reached learning-level threshold (over cap_final)
+    AND highest reached level-unlock threshold S_k. max of both axes."""
+    floor = 0
+    for _, p in LEVELS:
+        s = _threshold(p, cap_fin)
+        if basis >= s:
+            floor = max(floor, s)
+    for s in s_thresholds:
+        if basis >= s:
+            floor = max(floor, s)
+    return floor
+
+
+def _transcript(messages: list[dict]) -> str:
+    return "\n".join(
+        f"{'User' if m.get('role') == 'user' else 'Assistant'}: {m.get('content', '')}"
+        for m in messages
+    ) or "(empty)"
+
+
+async def block_chat(topic: str, block: str, section: str, compact: str | None, messages: list[dict], provider: str = DEFAULT_PROVIDER) -> str:
+    try:
+        prompt = _prompt(
+            "Block-Chat",
+            topic=topic, block=block,
+            section_block=section.strip() or "(no guide version provided)",
+            compact_block=(compact or "").strip() or "(none)",
+            transcript=_transcript(messages),
+        )
+        returncode, stdout, _ = await run_agent(
+            "blockchat-" + str(uuid.uuid4()), prompt, CHAT_TIMEOUT,
+            provider=provider, role="fast", capabilities="none", lane="interactive",
+        )
+        if returncode != 0:
+            return "Sorry, that didn't work. Please try again."
+        reply = stdout.strip()
+        return reply or "Sorry, I didn't get a response."
+    except Exception:
+        log.warning("[%s] Block chat failed (%s)", topic, block, exc_info=True)
+        return "Sorry, that didn't work. Please try again."
+
+
+def _question_schema(data) -> dict | None:
+    """{"question": str} · else None."""
+    if not isinstance(data, dict):
+        return None
+    question = str(data.get("question", "")).strip()
+    return {"question": question} if question else None
+
+
+def _rating_schema(data) -> dict | None:
+    """{"feedback": str, "tier": ∈ TIERS} · else None."""
+    if not isinstance(data, dict):
+        return None
+    feedback = str(data.get("feedback", "")).strip()
+    tier = data.get("tier")
+    if not feedback or tier not in TIERS:
+        return None
+    return {"feedback": feedback, "tier": tier}
+
+
+async def _gen_call(name: str, role: str, schema, provider: str, timeout: int = EXAM_TIMEOUT, lane: str = "interactive", **kwargs) -> dict | None:
+    """Generator agent: fill the template, run it, parse via schema · None on error.
+    lane="batch" for background (preloading, thorough rating) → its own slot queue."""
+    returncode, stdout, _ = await run_agent(
+        name.lower() + "-" + str(uuid.uuid4()), _prompt(name, **kwargs), timeout,
+        provider=provider, role=role, capabilities="none", lane=lane,
+    )
+    return schema(_parse_json_text(stdout)) if returncode == 0 else None
+
+
+async def _critique_call(name: str, provider: str, role: str = "judge", timeout: int = EXAM_TIMEOUT, lane: str = "interactive", **kwargs) -> list[str]:
+    """Critic agent (default role judge): empty list = fine. Fail-open: a critic failure
+    must not block the turn, so it returns an empty list then as well."""
+    returncode, stdout, _ = await run_agent(
+        name.lower() + "-" + str(uuid.uuid4()), _prompt(name, **kwargs), timeout,
+        provider=provider, role=role, capabilities="none", lane=lane,
+    )
+    if returncode != 0:
+        return []
+    return _problems_schema(_parse_json_text(stdout)) or []
+
+
+def _critique_block(prev_version: str, problems: list[str]) -> str:
+    points = "\n".join(f"- {p}" for p in problems)
+    return (
+        f"Your previous version was:\n«{prev_version}»\n\n"
+        f"The examiner objects:\n{points}\n\nFix these points."
+    )
+
+
+def _rating_text(rating: dict) -> str:
+    return f"Tier: {rating['tier']}\nFeedback: {rating['feedback']}"
+
+
+# Deterministic guard against double questions — the AI critic misses "…, and which…".
+_QUESTION_WORD = r"(was|welche[rsnm]?|wie|wieso|warum|wofür|wozu|wann|wo|wer|wem|wen|nenne)"
+_DOUBLE_RE = re.compile(r"[,;]?\s+(und|sowie|außerdem|bzw\.?)\s+" + _QUESTION_WORD + r"\b", re.IGNORECASE)
+
+
+def _double_question_flaw(question: str) -> str | None:
+    """Detects two chained questions. None = ok. Flags ONLY 'und/sowie' + question word."""
+    if question.count("?") > 1:
+        return "More than one question mark — ask EXACTLY ONE question."
+    if _DOUBLE_RE.search(question):
+        return "Two questions chained with 'und'/'sowie' — ask EXACTLY ONE question, one thing."
+    return None
+
+
+async def _question_with_critique(
+    topic: str, block: str, section_block: str, compact_block: str,
+    transcript: str, avoid_block: str, type_block: str, fokus_block: str,
+    tier_block: str, provider: str,
+) -> str | None:
+    """Generate a question, have the critic check it, regenerate on flaws (max CRITIC_MAX_ROUNDS)."""
+    kritik_block = "(none)"
+    question = None
+    for _ in range(CRITIC_MAX_ROUNDS):
+        data = await _gen_call(
+            "Block-Question", "guide", _question_schema, provider, lane="batch",
+            topic=topic, block=block, section_block=section_block,
+            compact_block=compact_block, transcript=transcript, avoid_block=avoid_block,
+            type_block=type_block, fokus_block=fokus_block, tier_block=tier_block, kritik_block=kritik_block,
+        )
+        if data is None:
+            return None
+        question = data["question"]
+        problems = await _critique_call(
+            "Block-Question-Critique", provider, role="guide", lane="batch",  # strong AI checks the rules
+            topic=topic, block=block, section_block=section_block,
+            compact_block=compact_block, transcript=transcript, avoid_block=avoid_block,
+            type_block=type_block, fokus_block=fokus_block, question=question,
+        )
+        hard = _double_question_flaw(question)  # forces regeneration even if the AI critic missed it
+        if hard:
+            problems = [hard, *(problems or [])]
+        if not problems:
+            return question
+        kritik_block = _critique_block(question, problems)
+    return question  # best-effort after the last round
+
+
+async def _rating_with_critique(
+    topic: str, block: str, section_block: str, compact_block: str,
+    question: str, transcript: str, reason_block: str, provider: str, role: str = "judge",
+) -> dict | None:
+    """Rate an answer (tier), have the critic check it, redo on misjudgment.
+
+    `question` anchors the checked question; the dialog (transcript) provides answer + discussion.
+    `reason_block` = optional learner dissatisfaction (only for "thorough check").
+    `role` = "judge" (fast) or "guide" (thorough, strong model with thinking).
+    """
+    timeout = THOROUGH_TIMEOUT if role == "guide" else EXAM_TIMEOUT
+    # Thorough (role guide) = user is waiting → interactive. Background-thorough (judge) → batch.
+    lane = "interactive" if role == "guide" else "batch"
+    kritik_block = "(none)"
+    rating = None
+    for _ in range(CRITIC_MAX_ROUNDS):
+        rating = await _gen_call(
+            "Block-Rating", role, _rating_schema, provider, timeout, lane=lane,
+            topic=topic, block=block, section_block=section_block,
+            compact_block=compact_block, question=question, transcript=transcript,
+            reason_block=reason_block, kritik_block=kritik_block,
+        )
+        if rating is None:
+            return None
+        problems = await _critique_call(
+            "Block-Rating-Critique", provider, role=role, timeout=timeout, lane=lane,
+            topic=topic, block=block, section_block=section_block,
+            compact_block=compact_block, question=question, transcript=transcript,
+            rating_block=_rating_text(rating),
+        )
+        if not problems:
+            return rating
+        kritik_block = _critique_block(_rating_text(rating), problems)
+    return rating  # best-effort after the last round
+
+
+def _section_blocks(section: str, compact: str | None) -> tuple[str, str]:
+    return (
+        section.strip() or "(no guide version provided)",
+        (compact or "").strip() or "(none)",
+    )
+
+
+def _avoid_block(avoid: list[str] | None) -> str:
+    entries = [f.strip() for f in (avoid or []) if f and f.strip()]
+    return "\n".join(f"- {f}" for f in entries) or "(none)"
+
+
+# Learner tier (derived from the score) → addressee role for the question. This is how the
+# difficulty arises: not "make it extra hard", but "ask questions for a beginner/expert".
+# Per level: addressee role + cognitive demand (Bloom) + "ask like this" cue. Without explicit levels
+# the model takes the easy path (mere recall) — the cues lift higher tiers to apply/analyze/transfer.
+TIER_ROLE = {
+    "beginner": "The learner is a BEGINNER. Cognitive: REMEMBER/UNDERSTAND. Ask about the basic understanding — the core concept, simple and direct.",
+    "advanced": "The learner is ADVANCED. Cognitive: APPLY. Pose a small concrete situation and have the concept applied to it — don't just ask for the definition.",
+    "expert": "The learner is an EXPERT. Cognitive: ANALYZE. Have them distinguish/compare, classify a special case or uncover a typical pitfall (hurdle) — don't quiz textbook knowledge.",
+    "master": "The learner is at MASTER level. Cognitive: EVALUATE/TRANSFER. Have the concept transferred to a NEW problem, justify a decision or weigh a trade-off.",
+}
+
+
+def _tier_block(tier: str | None) -> str:
+    return TIER_ROLE.get(tier or "", TIER_ROLE["beginner"])
+
+
+async def exam_question(
+    topic: str, block: str, section: str, compact: str | None,
+    messages: list[dict], subblocks: list[str] | None = None,
+    avoid: list[str] | None = None, tier: str = "beginner", provider: str = DEFAULT_PROVIDER,
+) -> str | None:
+    """Action 'question': generate a question — random type for a random subblock,
+    in the addressee role of the tier, then critic (sequential) · None on error."""
+    try:
+        section_block, compact_block = _section_blocks(section, compact)
+        transcript = _transcript(messages) if messages else "(empty)"
+        type_block = QUESTION_TYPES[random.choice(list(QUESTION_TYPES))]
+        subs = [s for s in (subblocks or []) if s and s.strip()]
+        focus = random.choice(subs) if subs else ""
+        fokus_block = (
+            f"Focus the question on this subblock: „{focus}\"" if focus
+            else "(whole block — no specific subblock)"
+        )
+        return await _question_with_critique(
+            topic, block, section_block, compact_block, transcript,
+            _avoid_block(avoid), type_block, fokus_block, _tier_block(tier), provider,
+        )
+    except Exception:
+        log.warning("[%s] Question failed (%s)", topic, block, exc_info=True)
+        return None
+
+
+async def exam_question_variant(
+    topic: str, block: str, section: str, compact: str | None,
+    pattern: str, tier: str = "beginner", provider: str = DEFAULT_PROVIDER,
+) -> str | None:
+    """Action 'question' with a pattern: from a predefined pattern, phrase a concrete question in
+    the addressee role of the tier. No critic (the pattern is build-checked).
+    The style guard stays as a cheap protection against double questions · None on error."""
+    try:
+        section_block, compact_block = _section_blocks(section, compact)
+        data = await _gen_call(
+            "Block-Question-Variante", "guide", _question_schema, provider, lane="batch",
+            topic=topic, block=block, section_block=section_block,
+            compact_block=compact_block, pattern=pattern, tier_block=_tier_block(tier),
+        )
+        if data is None:
+            return None
+        return data["question"]
+    except Exception:
+        log.warning("[%s] Question variant failed (%s)", topic, block, exc_info=True)
+        return None
+
+
+def _options_schema(opts) -> list[dict] | None:
+    """[{text, correct}]×4 → validated list · else None."""
+    if not isinstance(opts, list) or len(opts) != 4:
+        return None
+    out = []
+    for o in opts:
+        if not isinstance(o, dict):
+            return None
+        text = str(o.get("text", "")).strip()
+        correct = o.get("correct")
+        if not text or not isinstance(correct, bool):
+            return None
+        out.append({"text": text, "correct": correct})
+    return out
+
+
+def _quiz_schema(data) -> dict | None:
+    """{"question": str, "options": [{text, correct}]×4} → validated · else None.
+    Single choice: exactly 1 correct. The difficulty is in the tier, not in the count."""
+    if not isinstance(data, dict):
+        return None
+    question = str(data.get("question", "")).strip()
+    out = _options_schema(data.get("options"))
+    if not question or out is None:
+        return None
+    if sum(o["correct"] for o in out) != 1:
+        return None
+    return {"question": question, "options": out}
+
+
+def _gapchoice_schema(data) -> dict | None:
+    """{"sentence": str (with ___), "options": [{text, correct}]×4} → exactly 1 correct · else None."""
+    if not isinstance(data, dict):
+        return None
+    sentence = str(data.get("sentence", "")).strip()
+    out = _options_schema(data.get("options"))
+    if not sentence or "___" not in sentence or out is None or sum(o["correct"] for o in out) != 1:
+        return None
+    return {"sentence": sentence, "options": out}
+
+
+async def hurdles_distractor_block(topic: str, block: str) -> str:
+    """Typical misconceptions (facts hurdles) of the block as a distractor source for quiz/gap choice.
+    Empty if none exist (legacy) → the prompt placeholder disappears without a trace."""
+    try:
+        hurdles = await get_block_hurdles(topic, _norm_title(block))
+    except Exception:
+        return ""
+    if not hurdles:
+        return ""
+    lines = "\n".join(f"- {h}" for h in hurdles[:8])
+    return ("TYPICAL MISCONCEPTIONS for this block (use them as distractors when they fit the question):\n"
+            + lines + "\n")
+
+
+async def generate_quiz(
+    topic: str, block: str, section: str, compact: str | None,
+    pattern: str, tier: str = "beginner", provider: str = DEFAULT_PROVIDER,
+    distractor_block: str = "",
+) -> dict | None:
+    """From a pattern, a single-choice question (exactly 1 correct), at the tier's level.
+    Strong model (role guide) for correct flags. → {question, options} · None on error.
+    distractor_block: optional typical misconceptions (from the facts hurdles) as a distractor source."""
+    try:
+        section_block, compact_block = _section_blocks(section, compact)
+        return await _gen_call(
+            "Block-Quiz", "guide", _quiz_schema, provider, lane="batch",
+            topic=topic, block=block, section_block=section_block,
+            compact_block=compact_block, pattern=pattern, tier_block=_tier_block(tier),
+            distractor_block=distractor_block,
+        )
+    except Exception:
+        log.warning("[%s] Quiz question failed (%s)", topic, block, exc_info=True)
+        return None
+
+
+async def generate_gapchoice(
+    topic: str, block: str, section: str, compact: str | None,
+    pattern: str, tier: str = "beginner", provider: str = DEFAULT_PROVIDER,
+    distractor_block: str = "",
+) -> dict | None:
+    """Gap text with choices: sentence with ___ + 4 terms, exactly 1 correct — at the tier's level.
+    → {sentence, options:[{text,correct}]} · None on error.
+    distractor_block: optional typical misconceptions (from the facts hurdles) as a distractor source."""
+    try:
+        section_block, compact_block = _section_blocks(section, compact)
+        return await _gen_call(
+            "Block-Gapchoice", "guide", _gapchoice_schema, provider, lane="batch",
+            topic=topic, block=block, section_block=section_block,
+            compact_block=compact_block, pattern=pattern, tier_block=_tier_block(tier),
+            distractor_block=distractor_block,
+        )
+    except Exception:
+        log.warning("[%s] Gap-text choice failed (%s)", topic, block, exc_info=True)
+        return None
+
+
+def _gap_schema(data) -> dict | None:
+    """{"sentence": str (with ___), "solution": str, "alternatives": [str]} → validated · else None."""
+    if not isinstance(data, dict):
+        return None
+    sentence = str(data.get("sentence", "")).strip()
+    solution = str(data.get("solution", "")).strip()
+    alt = data.get("alternatives", [])
+    if not sentence or "___" not in sentence or not solution:
+        return None
+    alternatives = [str(a).strip() for a in alt if isinstance(a, str) and str(a).strip()] if isinstance(alt, list) else []
+    return {"sentence": sentence, "solution": solution, "alternatives": alternatives}
+
+
+async def generate_gaptext(
+    topic: str, block: str, section: str, compact: str | None,
+    pattern: str, tier: str = "beginner", provider: str = DEFAULT_PROVIDER,
+) -> dict | None:
+    """From a pattern, a gap-text task (sentence with ___, solution, synonyms), at the
+    tier's level. → {sentence, solution, alternatives} · None on error."""
+    try:
+        section_block, compact_block = _section_blocks(section, compact)
+        return await _gen_call(
+            "Block-Gaptext", "guide", _gap_schema, provider, lane="batch",
+            topic=topic, block=block, section_block=section_block,
+            compact_block=compact_block, pattern=pattern, tier_block=_tier_block(tier),
+        )
+    except Exception:
+        log.warning("[%s] Gap-text question failed (%s)", topic, block, exc_info=True)
+        return None
+
+
+def _norm_term(t: str) -> str:
+    return re.sub(r"[^\wäöüß]", "", str(t or "").lower())
+
+
+def _correct_schema(data) -> dict | None:
+    if not isinstance(data, dict) or not isinstance(data.get("correct"), bool):
+        return None
+    return {"correct": data["correct"]}
+
+
+async def check_gaptext(
+    topic: str, block: str, sentence: str, solution: str, alternatives: list[str],
+    input: str, provider: str = DEFAULT_PROVIDER,
+) -> bool:
+    """Check a gap-text answer: first a normalized comparison (solution + synonyms),
+    otherwise 1 AI call for synonym tolerance. Fail-open to CORRECT only on an exact match."""
+    if not input.strip():
+        return False
+    norm = _norm_term(input)
+    if norm and norm in {_norm_term(solution), *(_norm_term(a) for a in alternatives)}:
+        return True
+    data = await _gen_call(
+        "Block-Gaptext-Exam", "fast", _correct_schema, provider,
+        topic=topic, block=block, sentence=sentence, solution=solution,
+        alternatives=", ".join(alternatives) or "(none)", input=input,
+    )
+    return bool(data and data["correct"])
+
+
+async def exam_rating_fast(
+    topic: str, block: str, section: str, compact: str | None,
+    question: str, messages: list[dict], provider: str = DEFAULT_PROVIDER,
+) -> dict | None:
+    """Action 'answer' (Agent 1, fast): evaluator only, no critic. → {feedback, tier}."""
+    try:
+        section_block, compact_block = _section_blocks(section, compact)
+        transcript = _transcript(messages) if messages else "(empty)"
+        return await _gen_call(
+            "Block-Rating", "judge", _rating_schema, provider,
+            topic=topic, block=block, section_block=section_block, compact_block=compact_block,
+            question=question.strip() or "(no question provided)", transcript=transcript,
+            reason_block="(none)", kritik_block="(none)",
+        )
+    except Exception:
+        log.warning("[%s] Fast rating failed (%s)", topic, block, exc_info=True)
+        return None
+
+
+async def exam_rating(
+    topic: str, block: str, section: str, compact: str | None,
+    question: str, messages: list[dict], provider: str = DEFAULT_PROVIDER,
+    role: str = "judge", reason: str = "",
+) -> dict | None:
+    """Action 'answer_check' (Agent 2, thorough): evaluator + critic. → {feedback, tier}.
+
+    `role` = "guide" for "thorough check" (strong model). `reason` = optional
+    learner dissatisfaction with an earlier rating.
+    """
+    try:
+        section_block, compact_block = _section_blocks(section, compact)
+        transcript = _transcript(messages) if messages else "(empty)"
+        reason_block = reason.strip() or "(none)"
+        return await _rating_with_critique(
+            topic, block, section_block, compact_block,
+            question.strip() or "(no question provided)", transcript, reason_block, provider, role,
+        )
+    except Exception:
+        log.warning("[%s] Rating failed (%s)", topic, block, exc_info=True)
+        return None
+
+
+async def block_discussion(
+    topic: str, block: str, section: str, compact: str | None,
+    question: str, last_rating: str | None, messages: list[dict], provider: str = DEFAULT_PROVIDER,
+) -> str | None:
+    """Action 'discussion': tutor explains/discusses the question or a rating.
+
+    No rating, no critic — here the human is the examiner. None on error.
+    """
+    try:
+        section_block, compact_block = _section_blocks(section, compact)
+        prompt = _prompt(
+            "Block-Exam-Discussion",
+            topic=topic, block=block,
+            section_block=section_block, compact_block=compact_block,
+            question=question.strip() or "(no question provided)",
+            last_rating_block=(last_rating or "").strip() or "(none yet)",
+            transcript=_transcript(messages) if messages else "(empty)",
+        )
+        returncode, stdout, _ = await run_agent(
+            "examdiscussion-" + str(uuid.uuid4()), prompt, CHAT_TIMEOUT,
+            provider=provider, role="fast", capabilities="none", lane="interactive",
+        )
+        if returncode != 0:
+            return None
+        return stdout.strip() or None
+    except Exception:
+        log.warning("[%s] Exam discussion failed (%s)", topic, block, exc_info=True)
+        return None
+
+

backend/logsetup.py

@@ -0,0 +1,11 @@
+"""Central logging setup — call once in main.py before the app is created."""
+
+import logging
+import os
+
+
+def setup_logging() -> None:
+    logging.basicConfig(
+        level=os.environ.get("LOG_LEVEL", "INFO").upper(),
+        format="%(asctime)s %(levelname)s %(name)s %(message)s",
+    )

backend/main.py

@@ -2,23 +2,48 @@ from contextlib import asynccontextmanager
 
 from fastapi import FastAPI
 from fastapi.staticfiles import StaticFiles
+from starlette.middleware.gzip import GZipMiddleware
+
+from logsetup import setup_logging
+
+setup_logging()
 
 from config import FRONTEND_DIST, STORAGE_DIR
+import agents
+import database
 from database import init_db, close_db
+from guide import reconcile_guides
 from routes import router
 
 
 @asynccontextmanager
 async def lifespan(app: FastAPI):
-    (STORAGE_DIR / "themen").mkdir(parents=True, exist_ok=True)
+    (STORAGE_DIR / "topics").mkdir(parents=True, exist_ok=True)
     await init_db()
+    agents.on_event = database.add_event  # pipeline history sink (agents.py stays DB-free)
+    await reconcile_guides()
     yield
     await close_db()
 
 
+class CachedStatic(StaticFiles):
+    """StaticFiles with Cache-Control: hashed assets forever (immutable),
+    index.html never cached (it always points at the current asset hashes)."""
+    async def get_response(self, path, scope):
+        resp = await super().get_response(path, scope)
+        if path.startswith("assets/"):
+            resp.headers["Cache-Control"] = "public, max-age=31536000, immutable"
+        else:
+            resp.headers["Cache-Control"] = "no-cache"
+        return resp
+
+
 app = FastAPI(title="Creator", lifespan=lifespan)
 
+# gzip for the JS/CSS bundle + large JSON responses (~1.39 MB JS → ~400 KB).
+app.add_middleware(GZipMiddleware, minimum_size=500)
+
 app.include_router(router)
 
 if FRONTEND_DIST.exists():
-    app.mount("/", StaticFiles(directory=FRONTEND_DIST, html=True), name="frontend")
+    app.mount("/", CachedStatic(directory=FRONTEND_DIST, html=True), name="frontend")

backend/models.py

@@ -2,48 +2,135 @@ from pydantic import BaseModel, Field
 from typing import Literal
 
 FormatType = Literal[
-    "OnePager",
-    "MiniGuide",
     "Guide",
     "FullGuide",
+    "Rest",
 ]
 
-ProviderType = Literal["claude", "minimax", "minimax-direkt", "lokal"]
+from config import DEFAULT_PROVIDER
+
+ProviderType = Literal["claude", "minimax", "lokal"]
+
+SourceType = Literal["thema", "projekt", "uni", "link"]
 
 
 class GuideCreateRequest(BaseModel):
     topic: str = Field(min_length=1, max_length=100)
     format: FormatType
     instructions: str = Field(default="", max_length=2000)
-    provider: ProviderType = "claude"
+    provider: ProviderType = DEFAULT_PROVIDER
+    ab_step: int | None = Field(default=None, ge=0, le=5)  # re-run from board stage (0 lernziele … 5 lesbarkeit); None = full/resume
+
+
+class GuideBoardResetRequest(BaseModel):
+    topic: str = Field(min_length=1, max_length=100)
+    format: FormatType = "Guide"
+    ab_stage: int = Field(ge=0, le=5)  # reset cards back to this board stage (no generation)
 
 
 class TopicCreateRequest(BaseModel):
     name: str = Field(min_length=1, max_length=100)
 
 
-class BausteineCreateRequest(BaseModel):
+class QaRunRequest(BaseModel):
+    topic: str = Field(min_length=1, max_length=100)
+    llm: bool = True  # wie das Gate: Echtheits-/Dubletten-Stichprobe inklusive
+
+
+class RepairRequest(BaseModel):
+    topic: str = Field(min_length=1, max_length=100)
+
+
+class BlocksCreateRequest(BaseModel):
     topic: str = Field(min_length=1, max_length=100)
     instructions: str = Field(default="", max_length=2000)
-    provider: ProviderType = "claude"
+    provider: ProviderType = DEFAULT_PROVIDER
+    source_type: SourceType = "thema"
+    source_location: str = Field(default="", max_length=2000)
+    research: bool = True  # False = Continue: drain the existing kanban queue, no new search
+    qa_force: bool = False  # True = übersteuert ein pausierendes QA-Gate („Trotzdem fortsetzen")
 
 
-class BausteineStep(BaseModel):
+class BlocksCardRestartRequest(BaseModel):
+    topic: str = Field(min_length=1)
+    card_id: str = Field(min_length=1, max_length=200)
+
+
+class GuideFormatRequest(BaseModel):
+    topic: str = Field(min_length=1)
+    format: str = Field(min_length=1)
+
+
+class PracticeAnswerRequest(BaseModel):
+    topic: str = Field(min_length=1)
+    block_norm: str = Field(min_length=1, max_length=300)
+    sub_norm: str = Field(max_length=300)
+    correct: bool
+
+
+class GuideCardResetRequest(BaseModel):
+    topic: str = Field(min_length=1)
+    format: str = Field(min_length=1)
+    block_norm: str = Field(min_length=1, max_length=200)
+    ab_stage: int = Field(ge=0, le=5)
+
+
+class BlocksResetStageRequest(BaseModel):
+    topic: str = Field(min_length=1, max_length=100)
+    board: Literal["inventory", "artefacts"]
+    stage: str = Field(min_length=1, max_length=40)  # kanban column to reset back to
+
+
+class BlocksStep(BaseModel):
     label: str
     state: Literal["done", "active", "pending"]
 
 
-class BausteineStatusResponse(BaseModel):
+class BlocksFineStep(BaseModel):
+    label: str
+    phase: str = ""
+    state: Literal["done", "active", "pending"]
+
+
+class BlocksStatusResponse(BaseModel):
     ready: bool
     generating: bool
     progress: str | None = None
     error: str | None = None
     partial: bool = False
-    steps: list[BausteineStep] = []
+    steps: list[BlocksStep] = []
+    feine_steps: list[BlocksFineStep] = []
 
 
-class ProjectResponse(BaseModel):
+class FolderResponse(BaseModel):
     name: str
+    location: str  # path relative to the repo root (e.g. "projects/foo")
+
+
+class BlocksSourceUpdate(BaseModel):
+    topic: str = Field(min_length=1, max_length=100)
+    type: SourceType = "thema"
+    location: str = Field(default="", max_length=2000)
+    spec: str = Field(default="", max_length=2000)
+
+
+class BlocksSourceResponse(BaseModel):
+    type: SourceType
+    location: str
+    spec: str
+
+
+class SubblockInfo(BaseModel):
+    title: str
+    level: Literal["beginner", "advanced", "expert", "easy", "medium", "hard"]
+    relevance: Literal["relevant", "peripheral"] | None = None
+
+
+class BlockOverview(BaseModel):
+    num: int
+    title: str
+    description: str = ""
+    subblocks: list[SubblockInfo] = []
 
 
 class ProviderInfo(BaseModel):
@@ -72,91 +159,111 @@ class GuideChatRequest(BaseModel):
     section: str = Field(default="", max_length=20000)
     outline: str = Field(default="", max_length=8000)
     messages: list[ChatMessage] = Field(min_length=1)
-    provider: ProviderType = "claude"
+    provider: ProviderType = DEFAULT_PROVIDER
 
 
 class GuideChatResponse(BaseModel):
     reply: str
 
 
-class ElementResponse(BaseModel):
-    id: str
-    topic: str
-    title: str
-    description: str = ""
-    examples: list[str] = []
-    hints: list[str] = []
-    aufgabe: str = ""
-    loesung: str = ""
-    created_at: str
-    updated_at: str
+# --- Block learning ---
 
-
-class ElementCreateRequest(BaseModel):
+class BlockChatRequest(BaseModel):
     topic: str = Field(min_length=1, max_length=100)
-    hint: str = Field(default="", max_length=500)
-    provider: ProviderType = "claude"
-
-
-class ElementUpdateRequest(BaseModel):
-    title: str | None = Field(default=None, max_length=200)
-    description: str | None = None
-    examples: list[str] | None = None
-    hints: list[str] | None = None
-    aufgabe: str | None = None
-    loesung: str | None = None
-
-
-class ElementCheckRequest(BaseModel):
-    provider: ProviderType = "claude"
-
-
-class ElementSuggestion(BaseModel):
-    text: str
-    target: Literal["description", "examples", "hints", "aufgabe", "loesung"]
-    content: str
-
-
-class ElementCheckResponse(BaseModel):
-    suggestions: list[ElementSuggestion]
-
-
-class ElementStyleChange(BaseModel):
-    text: str
-    action: Literal["entfernen", "anpassen", "hinzufuegen"]
-    target: Literal["title", "description", "examples", "hints", "aufgabe", "loesung"]
-    index: int | None = None
-    content: str = ""
-
-
-class ElementStyleResponse(BaseModel):
-    changes: list[ElementStyleChange]
-
-
-class ElementChatRequest(BaseModel):
+    block: str = Field(min_length=1, max_length=200)
+    section: str = Field(default="", max_length=20000)         # detailed version
+    section_compact: str = Field(default="", max_length=20000)  # compact version (mnemonics)
     messages: list[ChatMessage] = Field(min_length=1)
-    provider: ProviderType = "claude"
+    provider: ProviderType = DEFAULT_PROVIDER
 
 
-class ElementChatResponse(BaseModel):
+class BlockChatResponse(BaseModel):
     reply: str
-    changes: list[ElementStyleChange] = []
 
 
-class ElementRefineRequest(BaseModel):
-    suggestion: ElementStyleChange
-    instruction: str = Field(min_length=1, max_length=2000)
-    provider: ProviderType = "claude"
+class BlockExamRequest(BaseModel):
+    topic: str = Field(min_length=1, max_length=100)
+    block: str = Field(min_length=1, max_length=200)
+    section: str = Field(default="", max_length=20000)         # detailed version
+    section_compact: str = Field(default="", max_length=20000)  # compact version (mnemonics)
+    action: Literal[
+        "question", "discussion", "answer", "answer_check",
+        "quiz_question", "quiz_answer", "gap_question", "gap_answer",
+    ] = "question"
+    question: str = Field(default="", max_length=2000)  # currently checked question (for discussion/answer); base anchor
+    selection: list[int] = []  # quiz/gap-text choice: option indices picked by the learner
+    correct: list[int] = []  # quiz/gap-text choice: correct indices (the client keeps them from generation)
+    solution: str = Field(default="", max_length=500)  # gap text free: expected term
+    alternatives: list[str] = []  # gap text free: accepted synonyms
+    input: str = Field(default="", max_length=500)  # gap text free: typed term
+    schwer: bool = False  # variant: easy (+1/−1) vs hard (+3/−1)
+    last_rating: str = Field(default="", max_length=2000)  # feedback of the last rating (context for discussion)
+    avoid: list[str] = []  # already-asked + earmarked questions — don't repeat them in substance
+    asked_again: bool = False  # asked_again was used for this question → gain capped at +1
+    reason: str = Field(default="", max_length=2000)  # "thorough check": why dissatisfied with the rating
+    pattern: str = Field(default="", max_length=2000)  # drawn question pattern (seed); empty → live generation (fallback)
+    # Base + cap are kept server-side (anchor / subs×25) — the client cap is only a hint.
+    cap: int = Field(default=10, ge=1, le=10000)  # score cap = unlocked subblocks × 25
+    messages: list[ChatMessage] = []  # dialog so far; empty = first question
+    provider: ProviderType = DEFAULT_PROVIDER
+    thorough: bool = False  # "thorough check": rating with a strong model (role guide)
 
 
-class ElementRefineResponse(BaseModel):
-    change: ElementStyleChange
+class QuizOption(BaseModel):
+    text: str
+    correct: bool
 
 
-class ProgressUpdate(BaseModel):
-    chapter: str = Field(min_length=1, max_length=100)
-    done: bool
+class BlockExamResponse(BaseModel):
+    question: str | None = None
+    reply: str | None = None
+    feedback: str | None = None
+    points: int | None = None  # points delta of this answer (−2 … +3); fast = expected
+    rating: Literal["gut", "neutral", "schlecht"] | None = None  # from the sign, for coloring
+    options: list[QuizOption] | None = None  # quiz: 4 options + correct flags
+    sentence: str | None = None  # gap text: sentence with a gap (___)
+    solution: str | None = None  # gap text: expected term
+    alternatives: list[str] | None = None  # gap text: accepted synonyms
+    good_answers: int
+    streak: int = 0  # current run of correct answers (per block)
+    cap: int = 10  # cap_final = all subs × 25 — the frontend derives the learning level
 
 
-class ProgressResponse(BaseModel):
-    chapters: list[str]
+class BlockLearnState(BaseModel):
+    good_answers: int
+    streak: int = 0
+    cap: int = 0          # cap_final = all subblocks × 25
+    cap_aktuell: int = 0  # reachable cap of the currently unlocked level
+    freie_level: int = 1  # 1=A · 2=F · 3=E · 4=V
+
+
+class BlockLearnStateResponse(BaseModel):
+    blocks: dict[str, BlockLearnState]
+
+
+# --- Block content: check + apply one section on demand (focus, right-click) ---
+
+class BlockPruefenRequest(BaseModel):
+    block: str = Field(min_length=1, max_length=200)
+    spot: str = "ausführlich"      # "compact" | "ausführlich" (displayed field)
+    snippet: str = Field(min_length=1, max_length=20000)  # raw markdown block
+    hint: str = Field(default="", max_length=2000)   # optional addition (✏️)
+    provider: ProviderType = DEFAULT_PROVIDER
+
+
+class BlockPruefenResponse(BaseModel):
+    revised: str   # corrected block as markdown
+
+
+class BlockUebernehmenRequest(BaseModel):
+    block: str = Field(min_length=1, max_length=200)
+    spot: str = "ausführlich"
+    alt: str = Field(min_length=1, max_length=20000)
+    revised: str = Field(default="", max_length=20000)
+    provider: ProviderType = DEFAULT_PROVIDER
+
+
+class BlockUebernehmenResponse(BaseModel):
+    compact: str
+    md: str
+    found: bool

backend/paths.py

@@ -1,8 +1,8 @@
 from pathlib import Path
 
-from config import STORAGE_DIR, PROJECTS_DIR
+from config import STORAGE_DIR, PROJECTS_DIR, PROJECT_ROOT
 
-THEMEN_DIR = STORAGE_DIR / "themen"
+TOPICS_DIR = STORAGE_DIR / "topics"
 
 
 def _safe(name: str) -> str:
@@ -10,26 +10,58 @@ def _safe(name: str) -> str:
 
 
 def topic_dir(topic: str) -> Path:
-    return THEMEN_DIR / _safe(topic)
+    return TOPICS_DIR / _safe(topic)
 
 
 def arbeit_dir(topic: str) -> Path:
     return topic_dir(topic) / "arbeit"
 
 
-def bausteine_path(topic: str) -> Path:
-    return topic_dir(topic) / "bausteine.md"
+def blocks_path(topic: str) -> Path:
+    return topic_dir(topic) / "blocks.md"
+
+
+def subblocks_path(topic: str) -> Path:
+    """Sidecar: the subblocks with level per block (shared by all guides)."""
+    return topic_dir(topic) / "subblocks.json"
+
+
+def question_pattern_path(topic: str) -> Path:
+    """Sidecar: predefined question patterns per block (subblock × type → example question)."""
+    return topic_dir(topic) / "question_pattern.json"
+
+
+def source_path(topic: str) -> Path:
+    """Persisted source choice per topic: {type, location, spec}."""
+    return topic_dir(topic) / "source.json"
+
+
+def source_crawl_dir(topic: str) -> Path:
+    """Target folder for crawled link sources (pages + PDF .txt)."""
+    return topic_dir(topic) / "source"
+
+
+def safe_folder(location: str) -> Path | None:
+    """Folder path relative to the repo root, sandboxed. None if empty/escaping (../, absolute outside)."""
+    if not location or not location.strip():
+        return None
+    p = (PROJECT_ROOT / location.strip()).resolve()
+    try:
+        p.relative_to(PROJECT_ROOT)
+    except ValueError:
+        return None
+    return p
 
 
 def guide_content_path(topic: str, format_name: str) -> Path:
     return topic_dir(topic) / "guides" / f"{format_name}.json"
 
 
-def bausteine_topics() -> list[str]:
-    """Themen, für die ein Themen-Ordner existiert."""
-    if not THEMEN_DIR.is_dir():
+def blocks_topics() -> list[str]:
+    """Topics for which a topic folder exists."""
+    if not TOPICS_DIR.is_dir():
         return []
-    return [d.name for d in THEMEN_DIR.iterdir() if d.is_dir()]
+    return [d.name for d in TOPICS_DIR.iterdir() if d.is_dir()]
 
 
 def project_dir(name: str) -> Path:

backend/pipeline.py

@@ -0,0 +1,399 @@
+"""Pipeline building blocks: agent races (with grace), single-slot, schemas, prompts, guide status.
+
+Holds the mutable pipeline state (generation semaphore, cancel set).
+Access the cancel set ONLY through the functions here — copied references
+in other modules would diverge on a re-assign.
+"""
+
+import asyncio
+import logging
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Callable
+
+from agents import run_agent, kill_process, cancel_scope, clear_scope
+from config import MAX_CONCURRENT_GENERATIONS, TEMPLATES_DIR, TIMEOUTS
+from database import update_guide
+from jsonio import read_json_file as _json_file
+from textkit import _STUFEN
+
+log = logging.getLogger("creator.pipeline")
+
+_semaphore = asyncio.Semaphore(MAX_CONCURRENT_GENERATIONS)
+_cancelled: set[str] = set()
+
+
+async def cancel_guide(guide_id: str) -> bool:
+    _cancelled.add(guide_id)
+    cancel_scope(f"{guide_id}-")  # waiting agents bail before spawn
+    kill_process(guide_id)        # kill running subprocesses
+    now = datetime.now(timezone.utc).isoformat()
+    await update_guide(guide_id, status="error", progress=None, error_msg="Cancelled — progress is preserved", updated_at=now)
+    return True
+
+
+def is_guide_cancelled(guide_id: str) -> bool:
+    return guide_id in _cancelled
+
+
+def clear_guide_cancelled(guide_id: str) -> None:
+    _cancelled.discard(guide_id)
+    clear_scope(f"{guide_id}-")  # clear scope → restart not blocked
+
+
+async def _set_progress(guide_id: str, progress: str) -> None:
+    now = datetime.now(timezone.utc).isoformat()
+    await update_guide(guide_id, progress=progress, updated_at=now)
+
+
+async def _set_step(guide_id: str, step: int, progress: str) -> None:
+    now = datetime.now(timezone.utc).isoformat()
+    await update_guide(guide_id, step=step, progress=progress, updated_at=now)
+
+
+async def _fail(guide_id: str, msg: str) -> None:
+    now = datetime.now(timezone.utc).isoformat()
+    await update_guide(guide_id, status="error", progress=None, error_msg=msg, updated_at=now)
+
+
+def _prompt(name: str, **kwargs) -> str:
+    template = (TEMPLATES_DIR / "Prompt" / f"{name}.md").read_text(encoding="utf-8")
+    return template.format(**kwargs)
+
+
+def _extra(instructions: str) -> str:
+    return f"\n\nADDITIONAL INSTRUCTIONS FROM THE USER:\n{instructions}\n" if instructions else ""
+
+
+def _log(topic: str, msg: str) -> None:
+    log.info("[%s] %s", topic, msg)
+
+
+def _claude_error(label: str, returncode: int, stdout: str, stderr: str) -> str:
+    stderr = (stderr or "").strip()
+    if stderr:
+        return f"{label}: {stderr[:1000]}"
+    tail = (stdout or "").strip()[-500:]
+    if tail:
+        return f"{label} (exit {returncode}, stderr empty): …{tail}"
+    return f"{label} (exit {returncode}, no output)"
+
+
+def _gather_error(label: str, results: list) -> str:
+    for r in results:
+        if isinstance(r, BaseException):
+            return f"{label}: {type(r).__name__}: {r}"
+        returncode, stdout, stderr = r
+        if returncode != 0:
+            return _claude_error(label, returncode, stdout, stderr)
+    return f"{label}: no usable result"
+
+
+def _timeout(step: str, n: int = 0) -> int:
+    base, per = TIMEOUTS[step]
+    return base + per * n
+
+
+def _problems_schema(data):
+    """{"ok": true} → [] · {"problems": [str]} → list · else None."""
+    if not isinstance(data, dict):
+        return None
+    if data.get("ok") is True:
+        return []
+    p = data.get("problems")
+    if not isinstance(p, list) or not p:
+        return None
+    out = [str(x).strip() for x in p if str(x).strip()]
+    return out or None
+
+
+def _str_list(val) -> list[str] | None:
+    """List of non-empty strings → stripped list (empty allowed) · else None."""
+    if not isinstance(val, list) or not all(isinstance(x, str) for x in val):
+        return None
+    out = [x.strip() for x in val]
+    return None if any(not x for x in out) else out
+
+
+
+
+def _runde_schema(data, final: bool = False):
+    """{"keep": [str], "rest": [str]} → (include, rest) · else None.
+
+    final=True: last clarification round — a non-empty rest is invalid.
+    """
+    if not isinstance(data, dict):
+        return None
+    include = _str_list(data.get("keep"))
+    rest = _str_list(data.get("rest"))
+    if include is None or rest is None or (final and rest):
+        return None
+    return include, rest
+
+
+_RELEVANCE = ("relevant", "peripheral")
+_YESNO = ("ja", "nein")
+
+
+def _enum_map_schema(key: str, allowed):
+    """Factory for `{"<key>": {"1": value, …}}` → `{id: value}` parsers; value ∈ `allowed`
+    (casefolded). If `ids` are given, at least these must be covered (extras allowed). None
+    on any invalid id/value or wrong shape. The caller filters the result to `ids`."""
+    def parse(data, ids: set[int] | None = None):
+        if not isinstance(data, dict) or not isinstance(data.get(key), dict) or not data[key]:
+            return None
+        out: dict[int, str] = {}
+        for k, v in data[key].items():
+            try:
+                num = int(k)
+            except (ValueError, TypeError):
+                return None
+            value = str(v).strip().casefold()
+            if value not in allowed:
+                return None
+            out[num] = value
+        if ids is not None and not ids <= set(out):
+            return None
+        return out
+    return parse
+
+
+_levels_schema = _enum_map_schema("levels", _STUFEN)            # level ∈ beginner/advanced/expert
+_relevance_schema = _enum_map_schema("relevance", _RELEVANCE)   # relevance ∈ relevant/peripheral
+_yesno_schema = _enum_map_schema("relevant", _YESNO)            # triage gate ∈ ja/nein
+
+
+from config import MAX_RESTARTS as _MAX_RESTARTS, HEDGE_NACH_S as _HEDGE_NACH_S  # noqa: E402 — zentral tunebar
+
+# Detached Nachzügler-Tasks (late-Fold): Referenz gegen GC, Aufräumen via done-callback.
+_NACHZUEGLER: set[asyncio.Task] = set()
+
+
+def _detached(task: asyncio.Task) -> None:
+    _NACHZUEGLER.add(task)
+    task.add_done_callback(_NACHZUEGLER.discard)
+
+
+async def _race(topic: str, label: str, slots: list[dict], quorum: int, timeout: int, provider: str, on_update=None, cancelled=None, *, grace: int | None = None, min_runtime: int | None = None, max_runtime: int | None = None, late=None) -> list | None:
+    """Starts all slots in parallel and collects `quorum` valid results.
+
+    Slot spec: {key, prompt, role, capabilities, payload}. `payload(result)`
+    checks validity and returns the slot result or None.
+    Error/timeout/invalid → slot restart (max. _MAX_RESTARTS). As soon as the
+    quorum stands, the remaining agents are killed. None = quorum missed.
+    `cancelled()` → True aborts (no restarts, returns None).
+
+    With `grace`, `quorum` becomes the minimum: the first valid result starts
+    a timer of `grace` seconds. After it expires, running agents are only
+    killed if the minimum stands — otherwise the race, including restarts,
+    keeps running until it stands. Returns: `quorum` to `len(slots)` results.
+
+    `min_runtime` (wall-clock from start): the race does not return before it
+    elapses while agents are still running — gives them time to search thoroughly.
+    `max_runtime` (wall-clock from start): hard cap — returns whatever is collected
+    (or None if nothing), killing the rest. Both default off; only Research sets them.
+
+    `late(value)` (async): Nachzügler werden beim Quorum-Return NICHT gekillt, sondern
+    laufen detached weiter; jedes noch eintreffende valide Ergebnis geht an `late`.
+    Ersetzt den grace-Timer der Finder-Runden — der hielt die Runde bis 300 s offen,
+    nur damit die dritte Stimme zählt (gemessen: 73 s Warten pro Runde).
+    """
+    attempts = {i: 0 for i in range(len(slots))}
+    tasks: dict[asyncio.Task, int] = {}
+    keys: dict[asyncio.Task, str] = {}
+    born: dict[asyncio.Task, float] = {}
+    hedged: set[int] = set()   # slot got its one twin — no hedge cascades
+    fertig: set[int] = set()   # slot delivered a valid result (late twins are ignored)
+    # Hedge-Schwelle relativ zum Call-Timeout (HEDGE_NACH_S = Untergrenze): pauschale 90 s
+    # hedgten jeden gesunden langen Call — z. B. Guide-Fixes, die normal 110–135 s laufen.
+    hedge_s = max(_HEDGE_NACH_S, timeout / 2) if _HEDGE_NACH_S else 0
+    loop = asyncio.get_running_loop()
+    start = loop.time()
+    min_deadline = start + min_runtime if min_runtime else None
+    max_deadline = start + max_runtime if max_runtime else None
+    deadline: float | None = None
+
+    def spawn(i: int, suffix: str = "") -> None:
+        slot = slots[i]
+        lbl = slot.get("label") or (label if len(slots) == 1 else f"{label} {i + 1}")
+        key = slot["key"] + suffix
+        task = asyncio.create_task(run_agent(
+            key, slot["prompt"], timeout,
+            provider=provider, role=slot["role"], capabilities=slot["capabilities"],
+            scope=topic, on_line=slot.get("on_line"), label=lbl,
+        ))
+        tasks[task] = i
+        keys[task] = key
+        born[task] = loop.time()
+
+    spaet: set[int] = set()  # je Slot zählt nur EIN spätes Ergebnis (Hedge-Zwilling = Echo)
+
+    def _detach_rest() -> None:
+        """Quorum steht: Nachzügler an `late` übergeben statt killen (nur Erfolgs-Return)."""
+        if late is None:
+            return
+        for t, i in list(tasks.items()):
+            tasks.pop(t)
+            keys.pop(t, None)
+            born.pop(t, None)
+
+            async def _warte(t=t, i=i):
+                try:
+                    r = await t
+                    if i in spaet:
+                        return
+                    if r and r[0] == 0 and (val := slots[i]["payload"](r)) is not None:
+                        spaet.add(i)
+                        await late(val)
+                except (asyncio.CancelledError, Exception):  # noqa: BLE001 — Nachzügler sind best-effort
+                    pass
+            _detached(asyncio.create_task(_warte()))
+
+    for i in range(len(slots)):
+        spawn(i)
+
+    results: list = []
+    try:
+        while tasks:
+            if cancelled and cancelled():
+                return None
+            # Hard wall-clock cap: return whatever we have (None if empty), kill the rest.
+            if max_deadline is not None and loop.time() >= max_deadline:
+                _log(topic, f"{label}: max runtime {max_runtime}s reached ({len(results)} valid)")
+                return results or None
+            min_ok = min_deadline is None or loop.time() >= min_deadline
+            if deadline is not None and len(results) >= quorum and loop.time() >= deadline and min_ok:
+                _detach_rest()
+                return results
+            # Hedge: a slot running HEDGE_NACH_S without result gets ONE parallel twin
+            # (key -h) — first valid result wins. Stalled provider calls burned the full
+            # timeout cap before the restart even began (measured: 160–230 s per stall).
+            if hedge_s:
+                now = loop.time()
+                for t in [t for t in list(tasks) if tasks[t] not in hedged | fertig
+                          and now - born[t] >= hedge_s]:
+                    i = tasks[t]
+                    hedged.add(i)
+                    spawn(i, suffix="-h")
+                    _log(topic, f"{label} {i + 1}: {round(hedge_s)}s ohne Ergebnis — Hedge-Zwilling gestartet")
+            # Wake up for the earliest relevant deadline (grace, min, max, or next hedge).
+            waits = []
+            if deadline is not None and len(results) >= quorum:
+                waits.append(deadline - loop.time())
+                if min_deadline is not None:
+                    waits.append(min_deadline - loop.time())
+            if max_deadline is not None:
+                waits.append(max_deadline - loop.time())
+            if hedge_s:
+                naechste = [born[t] + hedge_s - loop.time() for t in tasks
+                            if tasks[t] not in hedged | fertig]
+                if naechste:
+                    waits.append(max(0.0, min(naechste)))
+            wait_timeout = max(0.0, min(waits)) if waits else None
+            done, _ = await asyncio.wait(tasks.keys(), return_when=asyncio.FIRST_COMPLETED, timeout=wait_timeout)
+            if not done:
+                continue
+            for task in done:
+                i = tasks.pop(task)
+                keys.pop(task, None)
+                born.pop(task, None)
+                if i in fertig:
+                    continue  # späte Zwillinge eines bereits gewerteten Slots
+                payload, err = None, None
+                try:
+                    result = task.result()
+                    if result[0] != 0:
+                        err = _claude_error("Error", *result)
+                    else:
+                        payload = slots[i]["payload"](result)
+                        if payload is None:
+                            err = "result invalid/not parseable"
+                except asyncio.TimeoutError:
+                    err = f"Timeout after {timeout}s"
+                except Exception as e:
+                    err = f"{type(e).__name__}: {e}"
+
+                if payload is not None:
+                    results.append(payload)
+                    fertig.add(i)
+                    for t2 in [t2 for t2, i2 in tasks.items() if i2 == i]:  # Zwilling killen
+                        kill_process(keys.get(t2, slots[i]["key"]))
+                        t2.cancel()
+                    if grace is not None and deadline is None:
+                        deadline = loop.time() + grace
+                        _log(topic, f"{label}: first result — grace {grace}s running")
+                    if on_update:
+                        on_update(len(results))
+                    if (len(results) >= quorum and (grace is None or loop.time() >= deadline)
+                            and (min_deadline is None or loop.time() >= min_deadline)):
+                        _detach_rest()
+                        return results
+                    continue
+
+                _log(topic, f"{label} {i + 1} (attempt {attempts[i] + 1}): {err}")
+                attempts[i] += 1
+                # If the minimum already stands, restarts are pointless — the restart
+                # would be killed at the grace end anyway. A still-running twin IS the retry.
+                enough = grace is not None and len(results) >= quorum
+                zwilling = any(i2 == i for i2 in tasks.values())
+                if attempts[i] <= _MAX_RESTARTS and not enough and not zwilling and not (cancelled and cancelled()):
+                    spawn(i)
+        if len(results) >= quorum:  # all slots done, minimum stands (only reachable with grace)
+            _detach_rest()
+            return results
+        _log(topic, f"{label}: quorum {quorum} not reached ({len(results)} valid)")
+        return None
+    finally:
+        for task, i in tasks.items():
+            kill_process(keys.get(task, slots[i]["key"]))
+            task.cancel()
+        if tasks:
+            await asyncio.gather(*tasks.keys(), return_exceptions=True)
+
+
+@dataclass
+class GenContext:
+    """Pipeline parameters passed through — saves long argument signatures."""
+    topic: str
+    provider: str
+    is_cancelled: Callable[[], bool]
+    guide_id: str | None = None
+
+
+# Result status of run_single_slot
+OK, CANCELLED, FAILED = "ok", "cancelled", "failed"
+
+
+async def run_single_slot(
+    ctx: GenContext, label: str, *,
+    key: str, prompt: str, role: str, capabilities: str, payload, timeout: int, on_line=None,
+) -> tuple[str, object]:
+    """One agent, one valid result (race with quorum 1).
+
+    → (OK, value) | (CANCELLED, None) | (FAILED, None)
+    """
+    slots = [{"key": key, "prompt": prompt, "role": role, "capabilities": capabilities, "payload": payload, "on_line": on_line}]
+    res = await _race(ctx.topic, label, slots, 1, timeout, ctx.provider, cancelled=ctx.is_cancelled)
+    if ctx.is_cancelled():
+        return CANCELLED, None
+    if res is None:
+        return FAILED, None
+    return OK, res[0]
+
+
+async def _gather_progress(coros, total, report, start=0):
+    """Runs `coros` concurrently and reports live progress: `await report(done, total)`
+    after each completion (and once initially). Results in order, return_exceptions=True."""
+    done = start
+
+    async def wrap(c):
+        nonlocal done
+        try:
+            return await c
+        finally:
+            done += 1
+            await report(done, total)
+
+    await report(done, total)
+    return await asyncio.gather(*[wrap(c) for c in coros], return_exceptions=True)

backend/pytest.ini

@@ -0,0 +1,3 @@
+[pytest]
+asyncio_mode = auto
+testpaths = tests

backend/qa.py

@@ -0,0 +1,503 @@
+"""Independent quality audit over a FINISHED generation run — read-only.
+
+Measures the MECE goal ("no duplicates, no gaps") with detectors that deliberately
+do NOT reuse the pipeline's heuristics (_canonical_key/_relation_conflict/_evidence_pack)
+— shared blind spots would make the audit worthless. Shared infra only: DB access,
+embedding.py, the agent runner (--llm sampling), atomic_write_json.
+
+CLI:  python3 qa.py <topic> [--llm]     (or: make qa TOPIC=<topic> [LLM=1])
+Report: storage/qa/<topic>/<run_id|timestamp>.json + console digest + diff to the
+previous report of the same topic.
+"""
+
+import asyncio
+import json
+import re
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+import database as db
+import embedding
+from config import STORAGE_DIR, SUB_DUP_KANDIDAT_COS
+from fsutil import atomic_write_json
+from jsonio import read_json_file as _json_file
+from paths import arbeit_dir
+from textkit import _norm_title
+
+QA_DIR = STORAGE_DIR / "qa"
+JACCARD_FLOOR = 0.5      # title token overlap that makes a pair suspicious
+EMB_FLOOR = 0.82         # casefolded title cosine (own threshold, NOT the pipeline's 0.65)
+SECTION_CHARS = 4000     # own paragraph splitter — independent of _text_sections
+COVER_MIN_TOKENS = 2     # distinctive block tokens a section must share to count as covered
+FREMD_MIN_TOKENS = 1     # distinctive title tokens that must appear in the corpus
+LLM_SAMPLE = 12          # pairs/sections per judge call with --llm
+# Note 0-10, deterministisch aus den Quoten (transparent, diffbar — keine LLM-"Gefühlsnote").
+# Lücken/Fremd wiegen am schwersten (fehlender/falscher Stoff); Dubletten-VERDACHT enthält
+# bewusst Rauschen und wiegt daher wenig.
+NOTE_GEWICHTE = {"luecken": 3.0, "fremd": 2.5, "unechte_bloecke": 2.5, "hygiene": 0.5}
+# subs/artefacts only exist after board 2 — at gate time these quotas would always be 0
+# and water down the inventory score, hence a separate score.
+# sub_dubletten counts only with --llm (confirmed pairs); the bare candidate list is
+# suspicion (sub_dubletten_verdacht, weightless — like dubletten_verdacht).
+NOTE_GEWICHTE_ARTEFAKTE = {"subs_ohne_beleg": 2.0, "verwaiste": 1.0, "sub_dubletten": 1.0}
+
+_WORD = re.compile(r"\w{3,}")
+_PAREN = re.compile(r"^\s*(.*?)\s*\(([^()]{2,60})\)\s*$")
+_STOP = {"der", "die", "das", "und", "oder", "für", "mit", "von", "des", "den", "dem",
+         "ein", "eine", "the", "and", "for", "with", "als", "auf", "bei", "aus",
+         "problem", "algorithmus", "algorithm", "definition", "satz", "lemma"}
+
+
+def _tokens(s: str) -> set[str]:
+    return {t for t in _WORD.findall((s or "").casefold()) if t not in _STOP}
+
+
+def _distinctive(s: str) -> set[str]:
+    """Tokens that can anchor a title in a corpus (stopword-free, ≥3 chars)."""
+    return _tokens(s)
+
+
+def _ascii(t: str) -> str:
+    return "".join(c for c in t if c.isascii())
+
+
+def _jaccard(a: set[str], b: set[str]) -> float:
+    return len(a & b) / len(a | b) if a | b else 0.0
+
+
+def _sections(text: str, goal: int | None = None) -> list[str]:
+    """Own paragraph-boundary splitter (NOT blocks._text_sections — independence)."""
+    goal = goal or SECTION_CHARS
+    out, buf = [], ""
+    for para in re.split(r"\n\s*\n", text.strip()):
+        para = para.strip()
+        if not para:
+            continue
+        if buf and len(buf) + len(para) > goal:
+            out.append(buf)
+            buf = para
+        else:
+            buf = f"{buf}\n\n{para}" if buf else para
+    if buf.strip():
+        out.append(buf)
+    return out
+
+
+def _corpus_texts(topic: str) -> dict[str, str]:
+    from blocks import source_folder  # lazy: blocks pulls heavy deps
+    folder = source_folder(topic)
+    if not folder or not folder.is_dir():
+        return {}
+    out = {}
+    for f in sorted(folder.glob("*.txt")):
+        try:
+            out[f.name] = f.read_text(encoding="utf-8")
+        except OSError:
+            continue
+    return out
+
+
+# ── Detectors ───────────────────────────────────────────────────────────────────────
+
+def dubletten(blocks: list[dict], emb_on: bool = True) -> list[dict]:
+    """Suspicious pairs via signal UNION: token jaccard, casefolded-title embedding
+    cosine, paren acronym == other title. Every signal is independent of the pipeline."""
+    titles = [b["title"] for b in blocks]
+    toks = [_tokens(t) for t in titles]
+    sims = None
+    if emb_on and titles and embedding.available():
+        arr = embedding.embed([t.casefold() for t in titles])
+        if arr is not None:
+            sims = arr @ arr.T
+    ops = [bool(re.search(r"[≤⪯≥⊆⊊→⇒⟹⇔←]", t)) for t in titles]
+    out = []
+    for i in range(len(titles)):
+        for j in range(i + 1, len(titles)):
+            # relation vs. its operand ("Subset Sum" ⊂ "3-SAT ≤ Subset Sum"): by design
+            # separate entities — token containment there is expected, not suspicious
+            if ops[i] != ops[j] and (toks[i] <= toks[j] or toks[j] <= toks[i]):
+                continue
+            signals = {}
+            jac = _jaccard(toks[i], toks[j])
+            if jac >= JACCARD_FLOOR:
+                signals["jaccard"] = round(jac, 2)
+            if sims is not None and float(sims[i][j]) >= EMB_FLOOR:
+                signals["emb_cos"] = round(float(sims[i][j]), 2)
+            for a, b in ((i, j), (j, i)):
+                m = _PAREN.match(titles[a])
+                if m and _norm_title(titles[b]) in (_norm_title(m.group(1)), _norm_title(m.group(2))):
+                    signals["akronym"] = True
+            if signals:
+                out.append({"a": titles[i], "b": titles[j], "signale": signals})
+    return out
+
+
+def sub_dubletten(sub_rows: list[dict], emb_on: bool = True) -> list[dict]:
+    """Suspicious SUB pairs, in-block AND cross-block: casefolded title cosine ≥
+    SUB_DUP_KANDIDAT_COS. The pipeline's own merge paths act from 0.90 upward — the
+    measured bulk of real paraphrase duplicates sits in the band below, so everything
+    above the floor is a candidate. The verdict falls with --llm; without it this is
+    a suspicion list only (weightless)."""
+    cons = [r for r in sub_rows if r["status"] == "consensus"]
+    if len(cons) < 2 or not emb_on or not embedding.available():
+        return []
+    arr = embedding.embed([r["sub_title"].casefold() for r in cons])
+    if arr is None:
+        return []
+    sims = arr @ arr.T
+    out = []
+    for i in range(len(cons)):
+        for j in range(i + 1, len(cons)):
+            v = float(sims[i][j])
+            if v >= SUB_DUP_KANDIDAT_COS:
+                out.append({"a": f"[{cons[i]['block']}] {cons[i]['sub_title']}",
+                            "b": f"[{cons[j]['block']}] {cons[j]['sub_title']}",
+                            "cos": round(v, 2),
+                            "cross": cons[i]["block_norm"] != cons[j]["block_norm"]})
+    return sorted(out, key=lambda p: -p["cos"])
+
+
+def luecken(blocks: list[dict], subs_by_norm: dict[str, list[str]], corpus: dict[str, str]) -> list[dict]:
+    """Corpus sections no block (title+description+subs tokens) sufficiently anchors.
+    Description tokens matter at the QA GATE: board 2 has not run yet, so titles alone
+    under-cover and inflate the quota."""
+    anchors: list[set[str]] = []
+    for b in blocks:
+        t = _distinctive(b["title"]) | _distinctive(b.get("description") or "")
+        for s in subs_by_norm.get(_norm_title(b["title"]), []):
+            t |= _distinctive(s)
+        anchors.append(t)
+    out = []
+    for fname, text in corpus.items():
+        for k, sec in enumerate(_sections(text), 1):
+            sec_toks = _tokens(sec)
+            covered = any(len(a & sec_toks) >= COVER_MIN_TOKENS for a in anchors)
+            if not covered:
+                preview = " ".join(sec.split())[:120]
+                out.append({"datei": fname, "abschnitt": k, "vorschau": preview})
+    return out
+
+
+def fremd(blocks: list[dict], corpus: dict[str, str]) -> list[str]:
+    """Blocks whose distinctive title tokens never appear in the corpus (scope creep).
+    Token/stem match, NOT raw substring — 'bergang' ⊂ 'Übergang' had whitewashed the
+    garbage title 'αÜbergang'. The ASCII form only bridges symbol variants (Δ/∆)."""
+    ctoks = set(_WORD.findall("\n".join(corpus.values()).casefold()))
+
+    def _hit(t: str) -> bool:
+        forms = {t} | ({a} if len(a := _ascii(t)) >= 3 else set())
+        # digit-suffix fallback: '∆TSP1' → 'tsp1' misses the corpus token 'tsp' ('∆' is no \w)
+        forms |= {f2 for f in list(forms) if len(f2 := f.rstrip("0123456789")) >= 3}
+        return any(ct == f or ct.startswith(f) for f in forms for ct in ctoks)
+
+    out = []
+    for b in blocks:
+        dist = _distinctive(b["title"])
+        if dist and sum(1 for t in dist if _hit(t)) < FREMD_MIN_TOKENS:
+            out.append(b["title"])
+    return out
+
+
+def beleg(blocks: list[dict], sub_rows: list[dict]) -> dict:
+    ohne_quelle = [b["title"] for b in blocks if not b.get("sources")]
+    ohne_mention = [f"{r['block']} · {r['sub_title']}" for r in sub_rows
+                    if r["status"] != "variant" and not r["mentions"]]
+    return {"bloecke_ohne_quelle": ohne_quelle, "subs_ohne_beleg": ohne_mention}
+
+
+def hygiene(blocks: list[dict]) -> list[dict]:
+    out = []
+    for b in blocks:
+        t = b["title"]
+        probleme = []
+        if "**" in t or "`" in t:
+            probleme.append("markdown")
+        if re.search(r"\(\d+\)\s*$", t):
+            probleme.append("kollisions-suffix")
+        if not (b.get("description") or "").strip():
+            probleme.append("leere-beschreibung")
+        if probleme:
+            out.append({"titel": t, "probleme": probleme})
+    return out
+
+
+def _zaehlbare_luecken(lk: list[dict], llm: bool) -> list[dict]:
+    """With --llm only non-refuted gaps count ('?' = unjudged stays, conservative) — refuted
+    ones dragged the note although the judge cleared them (aak: 5 of 8, weight 3.0)."""
+    return [x for x in lk if x.get("llm") != "nein"] if llm else lk
+
+
+def note(quoten: dict, gewichte: dict = NOTE_GEWICHTE) -> float:
+    """10 = alle gewichteten Quoten 0. Gewicht = Punktabzug bei 100 % Quote (keine Normierung,
+    sonst staucht die Gewichtssumme die Skala nach oben). Ungemessene Quoten zählen nicht —
+    unechte_bloecke existiert nur mit --llm; dubletten_verdacht ist Verdachtsliste, kein Urteil."""
+    da = {k: w for k, w in gewichte.items() if k in quoten}
+    schaden = sum(w * min(float(quoten[k]), 1.0) for k, w in da.items())
+    return round(max(0.0, 10.0 * (1 - schaden)), 1)
+
+
+def artefakte(sub_rows: list[dict], art_rows: list[dict], fragen: list[dict]) -> dict:
+    """Coverage + orphans of the learning artefacts. Nenner = consensus-Subs (verworfene
+    zählen nicht als abzudeckendes Material). Waise = Ziel weder lebend (consensus/variant)
+    noch eindeutig als Kurztitel-Präfix von „kurztitel: beschreibung" auflösbar."""
+    if not art_rows and not fragen:
+        return {"status": "nicht generiert"}
+    cons = {(r["block_norm"], r["sub_norm"]) for r in sub_rows if r["status"] == "consensus"}
+    lebt = {(r["block_norm"], r["sub_norm"]) for r in sub_rows if r["status"] != "discarded"}
+
+    def _ziel(bn: str, sn: str):
+        if (bn, sn) in lebt:
+            return (bn, sn)
+        treffer = [k for k in lebt if k[0] == bn and k[1].startswith(sn + ":")]
+        if len(treffer) == 1:
+            return treffer[0]
+        # mehrere Treffer = meist ein consensus-Sub plus seine gefalteten Varianten
+        haupt = [k for k in treffer if k in cons]
+        return haupt[0] if len(haupt) == 1 else None
+
+    deck: dict[str, set] = {}
+    verwaist = []
+    for typ, bn, sn in ([(r["type"], r["block_norm"], r["sub_norm"]) for r in art_rows]
+                        + [("frage", r["block_norm"], r["sub_norm"]) for r in fragen]):
+        z = _ziel(bn, sn)
+        if z is None:
+            verwaist.append(f"{typ}: {bn} · {sn}")
+        else:
+            deck.setdefault(typ, set()).add(z)
+    n = max(len(cons), 1)
+    return {"status": "ok",
+            "frage_abdeckung": round(len(deck.get("frage", set()) & cons) / n, 3),
+            "flashcard_abdeckung": round(len(deck.get("flashcard", set()) & cons) / n, 3),
+            "beispiel_abdeckung": round(len(deck.get("example", set()) & cons) / n, 3),
+            "verwaiste": sorted(verwaist)}
+
+
+# ── LLM sampling (optional, own prompts under templates/QA/) ────────────────────────
+
+def _qa_prompt(name: str, **kwargs) -> str:
+    """Own template dir (templates/QA/) — deliberately separate from the pipeline prompts."""
+    from config import TEMPLATES_DIR
+    return (TEMPLATES_DIR / "QA" / f"{name}.md").read_text(encoding="utf-8").format(**kwargs)
+
+
+async def _llm_verdicts(template: str, topic: str, key: str, items: list[str]) -> dict[int, str]:
+    from agents import run_agent
+    from pipeline import _yesno_schema
+    from jsonio import parse_json_text
+    listing = "\n\n".join(f"{k}. {it}" for k, it in enumerate(items, 1))
+    slot = {"Dubletten": "pairs", "Luecken": "sections", "Bausteine": "blocks", "Sub": "pairs"}[template.split("-")[1]]
+    rc, out, _err = await run_agent(f"qa-{topic}-{key}", _qa_prompt(template, topic=topic, extra="", **{slot: listing}),
+                                    600, role="judge", capabilities="none", scope=topic, label=f"QA {key}")
+    return (_yesno_schema(parse_json_text(out)) or {}) if rc == 0 else {}
+
+
+# ── Report ──────────────────────────────────────────────────────────────────────────
+
+def freispruch_pfad(topic: str) -> Path:
+    return QA_DIR / topic / "freispruch.json"
+
+
+def _paar_key(a: str, b: str) -> str:
+    return "||".join(sorted((_norm_title(a), _norm_title(b))))
+
+
+def lade_freispruch(topic: str) -> dict[str, list[str]]:
+    """Persistierte 2:1-Freisprüche des Repair-Stichentscheids (repair._mit_stichentscheid):
+    mehrheitlich als „behalten" geurteilte Befunde zählen nicht mehr in die Note — sonst
+    pendelte sie dauerhaft unter 10 ohne Fix-Pfad (gemessen: kanban-smoke 9.4, aak 9.2).
+    Die Detektoren bleiben unverändert; ein Freispruch ist ein persistiertes Urteil,
+    kein Detektor-Tuning. Freigesprochene bleiben im Report sichtbar."""
+    d = _json_file(freispruch_pfad(topic))
+    return d if isinstance(d, dict) else {}
+
+
+async def qa_report(topic: str, llm: bool = False) -> dict | None:
+    cards = await db.kanban_cards(topic, board="inventory", stage="done_block")
+    if not cards:
+        print(f"Keine fertigen Blöcke für '{topic}' — Tippfehler im Namen oder Lauf nicht durch?")
+        return None
+    blocks = [{"title": c["payload"].get("title", ""), "description": c["payload"].get("description", ""),
+               "sources": c["payload"].get("sources") or []} for c in cards]
+    sub_rows = [dict(r) for bn in {_norm_title(b["title"]) for b in blocks}
+                for r in await db.list_subblocks(topic, bn)]
+    subs_by_norm: dict[str, list[str]] = {}
+    for r in sub_rows:
+        if r["status"] != "variant":
+            subs_by_norm.setdefault(r["block_norm"], []).append(r["sub_title"])
+    corpus = _corpus_texts(topic)
+
+    d = dubletten(blocks)
+    sd = sub_dubletten(sub_rows)
+    lk = luecken(blocks, subs_by_norm, corpus) if corpus else []
+    fr = fremd(blocks, corpus) if corpus else []
+    bl = beleg(blocks, sub_rows)
+    hy = hygiene(blocks)
+    n_sections = sum(len(_sections(t)) for t in corpus.values()) or 1
+
+    frei = lade_freispruch(topic)
+    frei_fremd = set(frei.get("fremd") or [])
+    fremd_frei = [t for t in fr if _norm_title(t) in frei_fremd]
+    fr = [t for t in fr if _norm_title(t) not in frei_fremd]
+
+    if llm and d:
+        v = await _llm_verdicts("QA-Dubletten", topic, "dubletten",
+                                [f"A: {p['a']}\nB: {p['b']}" for p in d[:LLM_SAMPLE]])
+        for k, p in enumerate(d[:LLM_SAMPLE], 1):
+            p["llm"] = v.get(k, "?")
+    if llm and lk:
+        v = await _llm_verdicts("QA-Luecken", topic, "luecken",
+                                [f"[{x['datei']} #{x['abschnitt']}] {x['vorschau']}" for x in lk[:LLM_SAMPLE]])
+        for k, x in enumerate(lk[:LLM_SAMPLE], 1):
+            x["llm"] = v.get(k, "?")
+    if llm and sd:  # full coverage in chunks — a sampled quota would mislead the note
+        for lo in range(0, len(sd), 40):
+            chunk = sd[lo:lo + 40]
+            v = await _llm_verdicts("QA-Sub-Dubletten", topic, f"sub-dubletten-{lo}",
+                                    [f"A: {p['a']}\nB: {p['b']}" for p in chunk])
+            for k, p in enumerate(chunk, 1):
+                p["llm"] = v.get(k, "?")
+        frei_sub = set(frei.get("sub_dubletten") or [])
+        for p in sd:
+            if p.get("llm") == "ja" and _paar_key(p["a"], p["b"]) in frei_sub:
+                p["freispruch"] = True  # 2:1-Urteil „behalten" — sichtbar, aber notenfrei
+    unecht: list[str] | None = None
+    if llm and blocks:
+        verdacht = []
+        for lo in range(0, len(blocks), 80):  # ein Call je 80 Titel
+            chunk = blocks[lo:lo + 80]
+            v = await _llm_verdicts("QA-Bausteine", topic, f"bausteine-{lo}",
+                                    [f"{b['title']} — {b['description'] or '(ohne Beschreibung)'}" for b in chunk])
+            verdacht += [b for k, b in enumerate(chunk, 1) if v.get(k) == "nein"]
+        # Bestätiger-Pass nur über die Geflaggten: der Einzel-Judge flaggte pro Lauf ANDERE
+        # Blöcke (gemessen aak: Note pendelte 9.3↔10.0 bei identischem Bestand) — nur
+        # doppelt-„nein" zählt; Repair hat als dritte Sicherung die eigene Zweitmeinung
+        unecht = []
+        if verdacht:
+            v2 = await _llm_verdicts("QA-Bausteine", topic, "bausteine-b2",
+                                     [f"{b['title']} — {b['description'] or '(ohne Beschreibung)'}" for b in verdacht])
+            unecht = [b["title"] for k, b in enumerate(verdacht, 1) if v2.get(k) == "nein"]
+        frei_unecht = set(frei.get("unecht") or [])
+        unecht = [t for t in unecht if _norm_title(t) not in frei_unecht]
+
+    art_rows = [dict(r) for r in await db.get_sub_artefakte(topic)]
+    fragen = [dict(r) for r in await db.list_question_pattern(topic)]
+    art = artefakte(sub_rows, art_rows, fragen)
+    quoten_art: dict[str, float] = {}
+    if sub_rows:
+        quoten_art["subs_ohne_beleg"] = round(len(bl["subs_ohne_beleg"]) / len(sub_rows), 3)
+    if art.get("status") == "ok":
+        quoten_art["verwaiste"] = round(len(art["verwaiste"]) / max(len(art_rows) + len(fragen), 1), 3)
+    n_cons = sum(1 for r in sub_rows if r["status"] == "consensus")
+    if n_cons:
+        quoten_art["sub_dubletten_verdacht"] = round(len(sd) / n_cons, 3)
+        if llm:  # confirmed pairs only — the bare candidate list is suspicion, not damage;
+            # freigesprochene (2:1 „behalten") zählen nicht mehr
+            quoten_art["sub_dubletten"] = round(
+                sum(1 for p in sd if p.get("llm") == "ja" and not p.get("freispruch")) / n_cons, 3)
+    summary = _json_file(arbeit_dir(topic) / "lauf-summary.json") or {}
+    report = {
+        "topic": topic, "erstellt": datetime.now(timezone.utc).isoformat(),
+        "run_id": summary.get("run_id", ""), "bloecke": len(blocks),
+        "quoten": {
+            "dubletten_verdacht": round(len(d) / max(len(blocks), 1), 3),
+            "luecken": round(len(_zaehlbare_luecken(lk, llm)) / n_sections, 3),
+            "fremd": round(len(fr) / max(len(blocks), 1), 3),
+            "hygiene": round(len(hy) / max(len(blocks), 1), 3),
+            **({"unechte_bloecke": round(len(unecht) / max(len(blocks), 1), 3)} if unecht is not None else {}),
+        },
+        "quoten_artefakte": quoten_art,
+        **({"unecht": unecht} if unecht is not None else {}),
+        **({"fremd_freigesprochen": fremd_frei} if fremd_frei else {}),
+        "dubletten": d, "sub_dubletten": sd, "luecken": lk, "fremd": fr, "beleg": bl, "hygiene": hy,
+        "artefakte": art,
+        "lauf": summary,
+    }
+    report["note"] = note(report["quoten"])
+    # None statt 10.0, solange Board 2 nichts geliefert hat — nichts gemessen ist keine Bestnote
+    report["note_artefakte"] = note(quoten_art, NOTE_GEWICHTE_ARTEFAKTE) if quoten_art else None
+    report["note_gewichte"] = {"inventar": NOTE_GEWICHTE, "artefakte": NOTE_GEWICHTE_ARTEFAKTE}
+    return report
+
+
+def _diff(prev: dict | None, cur: dict) -> dict:
+    if not prev:
+        return {}
+    # ältere Reports führten die Artefakt-Quoten noch unter "quoten"
+    alt = {**prev.get("quoten", {}), **prev.get("quoten_artefakte", {})}
+    neu = {**cur["quoten"], **cur.get("quoten_artefakte", {})}
+    return {k: round(v - alt.get(k, 0), 3) for k, v in neu.items()}
+
+
+def _write_report(report: dict) -> Path:
+    tdir = QA_DIR / report["topic"]
+    tdir.mkdir(parents=True, exist_ok=True)
+    # by mtime: run-id names (…-1311-5e5c) and timestamp names don't sort lexicographically.
+    # guide-* reports share the directory but are a SEPARATE series (guide_qa.py).
+    older = sorted((p for p in tdir.glob("*.json") if not p.name.startswith("guide-")),
+                   key=lambda p: p.stat().st_mtime)
+    prev = _json_file(older[-1]) if older else None
+    report["diff_zum_vorlauf"] = _diff(prev, report)
+    name = report["run_id"] or datetime.now(timezone.utc).strftime("%Y%m%d-%H%M%S")
+    path = tdir / f"{name}.json"
+    atomic_write_json(path, report, indent=1)
+    return path
+
+
+async def write_report(report: dict) -> Path:
+    """_write_report + kompaktes kind='qa'-Event. Die Report-JSONs liegen nur auf der
+    Lauf-Maschine (storage/qa/) — ein DB-Pull reichte nicht, um Note/Quoten eines Runs
+    zu rekonstruieren (Analyse 20260704-1452-b223). Nur die Kennzahlen, kein Volltext;
+    run_id stempelt add_event aus der Registry (gesetzt im Lauf, leer bei manueller QA)."""
+    path = await asyncio.to_thread(_write_report, report)
+    try:  # Event ist Komfort — ein DB-Fehler darf den Report nicht kosten (fail-open)
+        await db.add_event(report["topic"], "qa", key=path.stem, meta={
+            "note": report["note"], "note_artefakte": report.get("note_artefakte"),
+            "quoten": report["quoten"], "quoten_artefakte": report.get("quoten_artefakte", {})})
+    except Exception:
+        pass
+    return path
+
+
+def _digest(report: dict, path: Path):
+    na = report.get("note_artefakte")
+    print(f"QA {report['topic']} — {report['bloecke']} Blöcke (run {report['run_id'] or '—'})"
+          f" — Inventar {report['note']}/10 · Artefakte {f'{na}/10' if na is not None else '—'}")
+    for k, v in {**report["quoten"], **report.get("quoten_artefakte", {})}.items():
+        delta = report.get("diff_zum_vorlauf", {}).get(k)
+        d = f"  ({'+' if delta > 0 else ''}{delta})" if delta else ""
+        print(f"  {k:20} {v:6.1%}{d}")
+    for p in report["dubletten"][:8]:
+        print(f"  DUBLETTE? {p['a']}  <->  {p['b']}  {p['signale']}{'  LLM:' + p['llm'] if 'llm' in p else ''}")
+    for p in report.get("sub_dubletten", [])[:8]:
+        print(f"  SUB-DUP?  {p['a']}  <->  {p['b']}  cos={p['cos']}{'  LLM:' + p['llm'] if 'llm' in p else ''}")
+    for t in report["fremd"][:8]:
+        print(f"  FREMD?    {t}")
+    for t in report.get("unecht", [])[:8]:
+        print(f"  UNECHT    {t}")
+    art = report["artefakte"]
+    if art.get("status") == "ok":
+        print(f"  Artefakte: Frage {art['frage_abdeckung']:.0%} · Flashcard {art['flashcard_abdeckung']:.0%}"
+              f" · Beispiel {art['beispiel_abdeckung']:.0%} · verwaist {len(art['verwaiste'])}")
+    else:
+        print("  Artefakte: nicht generiert (Board 2 nicht gelaufen)")
+    print(f"Report: {path}")
+
+
+async def main(topic: str, llm: bool):
+    await db.init_db()
+    try:
+        report = await qa_report(topic, llm=llm)
+        if report is None:
+            sys.exit(1)
+        _digest(report, await write_report(report))
+    finally:
+        await db.close_db()
+
+
+if __name__ == "__main__":
+    args = [a for a in sys.argv[1:] if not a.startswith("--")]
+    if not args:
+        print("Nutzung: python3 qa.py <topic> [--llm]")
+        sys.exit(1)
+    asyncio.run(main(args[0], "--llm" in sys.argv))

backend/readability.py

@@ -0,0 +1,115 @@
+"""Deterministic readability gate for guide sections.
+
+A small German complexity model (DistilBERT, GermEval 2022, scale 1–7) rates the
+readability of the prose. guide.py feeds sections that are too hard into the existing
+read-exam/revision loop — no prompt, no guessing.
+
+Optional: if `transformers`/`torch` are missing or the model won't load, the gate is
+silently disabled (the backend keeps running unchanged). CPU is enough; the caller
+wraps the scoring in `asyncio.to_thread` (blocking model inference).
+"""
+
+import logging
+import re
+
+from config import (
+    READABILITY_ACTIVE, READABILITY_HARD, READABILITY_HARD_SHARE, READABILITY_MAX, READABILITY_MODEL,
+)
+
+log = logging.getLogger("creator.readability")
+
+_model_cache = None       # (tokenizer, model, torch) — singleton
+_load_attempt = False     # already tried to load?
+
+# Strip markup → plain prose (code does not count toward readability).
+_CODE_FENCE = re.compile(r"```.*?```", re.DOTALL)
+_COMMENT = re.compile(r"<!--.*?-->", re.DOTALL)
+_INLINE_CODE = re.compile(r"`[^`]*`")
+_LINK = re.compile(r"\[([^\]]*)\]\([^)]*\)")
+_MD_MARK = re.compile(r"^[ \t]*([#>]+|[-*+]\s)|[*_~|]", re.MULTILINE)
+_WS = re.compile(r"\s+")
+_SENTENCE = re.compile(r"(?<=[.!?])\s+")
+
+
+def _model():
+    """Load the model once. None = gate off (disabled or load error)."""
+    global _model_cache, _load_attempt
+    if _load_attempt:
+        return _model_cache
+    _load_attempt = True
+    if not READABILITY_ACTIVE:
+        return None
+    try:
+        import torch
+        from transformers import AutoModelForSequenceClassification, AutoTokenizer
+        tok = AutoTokenizer.from_pretrained(READABILITY_MODEL)
+        model = AutoModelForSequenceClassification.from_pretrained(READABILITY_MODEL)
+        model.eval()
+        _model_cache = (tok, model, torch)
+        log.info("readability model loaded: %s (num_labels=%d)", READABILITY_MODEL, model.config.num_labels)
+    except Exception as e:
+        log.warning("readability gate disabled (model not loadable): %s", e)
+        _model_cache = None
+    return _model_cache
+
+
+def _prose(md: str) -> str:
+    """Strip markdown/code → plain prose for scoring."""
+    t = _CODE_FENCE.sub(" ", md)
+    t = _COMMENT.sub(" ", t)
+    t = _INLINE_CODE.sub(" ", t)
+    t = _LINK.sub(r"\1", t)
+    t = _MD_MARK.sub(" ", t)
+    return _WS.sub(" ", t).strip()
+
+
+def _sentences(text: str) -> list[str]:
+    """Split prose into sentences; discard very short fragments."""
+    return [s.strip() for s in _SENTENCE.split(text) if len(s.strip()) >= 15]
+
+
+def _scores(sentences: list[str]) -> list[float]:
+    """Complexity per sentence (1–7). Regression (num_labels=1) or expectation over classes."""
+    tok, model, torch = _model_cache
+    values: list[float] = []
+    n = model.config.num_labels
+    for i in range(0, len(sentences), 16):
+        batch = sentences[i:i + 16]
+        enc = tok(batch, return_tensors="pt", truncation=True, max_length=256, padding=True)
+        with torch.no_grad():
+            logits = model(**enc).logits
+        if n == 1:
+            vals = logits.reshape(-1).tolist()
+        else:
+            probs = torch.softmax(logits, dim=-1)
+            levels = torch.arange(1, n + 1, dtype=probs.dtype)
+            vals = (probs * levels).sum(-1).reshape(-1).tolist()
+        values.extend(vals)
+    return values
+
+
+def rate_sections(md_by_num: dict[int, str]) -> dict[int, str]:
+    """{num: section_md} → {num: hint} only for sections that are too hard.
+
+    Empty dict if the gate is off. Blocking (CPU) — call inside to_thread.
+    """
+    if _model() is None:
+        return {}
+    out: dict[int, str] = {}
+    for num, md in md_by_num.items():
+        sentences = _sentences(_prose(md or ""))
+        if len(sentences) < 2:  # almost only code / too short → skip
+            continue
+        values = _scores(sentences)
+        if not values:
+            continue
+        mean = sum(values) / len(values)
+        hard = sum(1 for w in values if w > READABILITY_HARD) / len(values)
+        # Too hard = high mean OR too many hard individual sentences (outlier nests).
+        if mean > READABILITY_MAX or hard >= READABILITY_HARD_SHARE:
+            # German revision hint fed to the (German-writing) writer agent — kept German on purpose.
+            out[num] = (
+                f"Zu schwer lesbar (Ø {mean:.1f}/7, {hard * 100:.0f}% harte Sätze): "
+                "kürzere Sätze, einfachere Wörter, weniger Schachtelsätze, mehr Examples."
+            )
+    return out

backend/repair.py

@@ -0,0 +1,378 @@
+"""Befund-Repair: arbeitet den jüngsten QA-Report gezielt ab — ohne Flow, ohne Board-Rebuild.
+
+Blindes Re-Filtern reproduziert die blinden Flecken der Pipeline (sie hat die Befunde ja
+durchgelassen). Hier fließen die QA-BEFUNDE als Input in gezielte Aktionen: Hygiene
+deterministisch, bestätigte Dubletten mergen (Zweitmeinung), Fremd/Unecht nur nach
+Gegen-Judge entfernen (fail-open: Zweifel/Fehler → behalten). Lücken brauchen Recherche,
+Verwaiste den nächsten Board-2-Lauf — beides wird nur ausgewiesen."""
+
+import json
+import logging
+import re
+
+import database as db
+import qa
+from agents import run_agent
+from blocks import _blocks_files, _evidence_pack, source_folder
+from fsutil import atomic_write_json
+from jsonio import parse_json_text, read_json_file as _json_file
+from pipeline import _yesno_schema
+from textkit import _norm_title, _title, clean_title
+
+log = logging.getLogger("creator.repair")
+
+JUDGE_TIMEOUT = 600
+from config import EVIDENCE_PER_BLOCK, JUDGE_CHUNK  # noqa: E402 — zentral tunebar
+
+
+async def repair_befunde(topic: str) -> dict:
+    tdir = qa.QA_DIR / topic
+    reports = sorted((p for p in tdir.glob("*.json") if not p.name.startswith("guide-")),
+                     key=lambda p: p.stat().st_mtime) if tdir.is_dir() else []
+    report = _json_file(reports[-1]) if reports else None
+    if not report:
+        return {"fehler": "kein QA-Report — erst QA laufen lassen"}
+    files = _blocks_files(topic)
+    cards = await db.kanban_cards(topic, board="inventory", stage="done_block")
+    by_norm = {_norm_title(c["payload"].get("title", "")): c for c in cards}
+
+    hygiene = await _fix_hygiene(topic, report, by_norm, files)
+    merges = await _merge_dubletten(topic, report, by_norm, files)
+    sub_merges, frei_subs = await _merge_sub_dubletten(topic, report, files)
+    entfernt, frei_bloecke = await _entferne_fremd_unecht(topic, report, by_norm, files)
+    aufgeraeumt = await _raeume_waisen(topic)
+
+    # llm=True: gleiche Messlatte wie QA-Button/Abschluss-QA — der llm=False-Report
+    # blendete sub_dubletten aus und ließ die Note zwischen 10.0 und ~9 pendeln
+    neu = await qa.qa_report(topic, llm=True)
+    if neu:
+        await qa.write_report(neu)
+    return {"hygiene": hygiene, "merges": merges, "sub_merges": sub_merges, "entfernt": entfernt,
+            "aufgeraeumt": aufgeraeumt, "freigesprochen": frei_subs + frei_bloecke,
+            "braucht_research": len(report.get("luecken", []))}
+
+
+async def _judge(template: str, topic: str, key: str, slot: str, items: list[str]) -> dict[int, str]:
+    """No-Tool-Judge-Wellen über alle Items (fail-open: Fehler → leeres Verdikt = behalten)."""
+    verdicts: dict[int, str] = {}
+    for lo in range(0, len(items), JUDGE_CHUNK):
+        chunk = items[lo:lo + JUDGE_CHUNK]
+        listing = "\n\n".join(f"{k}. {it}" for k, it in enumerate(chunk, 1))
+        try:
+            rc, out, _err = await run_agent(
+                f"repair-{topic}-{key}-{lo}", qa._qa_prompt(template, topic=topic, extra="", **{slot: listing}),
+                JUDGE_TIMEOUT, role="judge", capabilities="none", scope=topic, label=f"Repair {key}")
+            v = (_yesno_schema(parse_json_text(out)) or {}) if rc == 0 else {}
+        except Exception:
+            log.exception("[%s] Repair-Judge %s fehlgeschlagen — Befunde bleiben", topic, key)
+            v = {}
+        verdicts.update({lo + k: urteil for k, urteil in v.items()})
+    return verdicts
+
+
+def _speichere_freispruch(topic: str, kategorie: str, keys: list[str]) -> None:
+    d = qa.lade_freispruch(topic)
+    alt = set(d.get(kategorie) or [])
+    d[kategorie] = sorted(alt | set(keys))
+    qa.freispruch_pfad(topic).parent.mkdir(parents=True, exist_ok=True)
+    atomic_write_json(qa.freispruch_pfad(topic), d, indent=1)
+
+
+async def _mit_stichentscheid(template: str, topic: str, key: str, slot: str,
+                              lines: list[str], befund: str, kategorie: str = "",
+                              ids: list[str] | None = None) -> tuple[dict[int, str], list[str]]:
+    """Zweitmeinung + Stichentscheid: Der Repair-Judge kann den QA-Befund kippen — bei
+    Dissens (QA sagt Befund, Judge sagt behalten) entscheidet ein DRITTER Judge nur über
+    die strittigen Items, Mehrheit 2/3 (Muster Crossblock-Tiebreaker). Ohne ihn pendelte
+    die Note dauerhaft unter 10 ohne Fix-Pfad (gemessen: aak-fremd 9.2, kanban-smoke-
+    Dublette 9.4 — „keine behebbaren Befunde" trotz Befund).
+    Explizites 2:1-„behalten" wird als FREISPRUCH persistiert (kategorie+ids) — die QA
+    zählt das Item ab dann nicht mehr (qa.lade_freispruch). j3-AUSFALL persistiert nicht
+    (fail-open ist kein Urteil). → (verdicts, freigesprochene Zeilen)."""
+    v = await _judge(template, topic, key, slot, lines)
+    strittig = [i for i in range(1, len(lines) + 1) if v.get(i) != befund]
+    frei: list[str] = []
+    if strittig:
+        v3 = await _judge(template, topic, f"{key}-st", slot, [lines[i - 1] for i in strittig])
+        gegen = "nein" if befund == "ja" else "ja"
+        frei_keys: list[str] = []
+        for pos, i in enumerate(strittig, 1):
+            if v3.get(pos) == befund:
+                v[i] = befund  # 2:1 für den QA-Befund → handeln
+            elif v3.get(pos) == gegen and kategorie and ids:
+                frei_keys.append(ids[i - 1])
+                frei.append(lines[i - 1].splitlines()[0][:80])
+        if frei_keys:
+            _speichere_freispruch(topic, kategorie, frei_keys)
+            log.info("[%s] Repair %s: %d Befund(e) per 2:1 freigesprochen", topic, kategorie, len(frei_keys))
+    return v, frei
+
+
+async def _fix_hygiene(topic: str, report: dict, by_norm: dict, files: dict) -> list[str]:
+    """Nur der norm-invariante Teil (`**`/Backticks); `(n)`-Suffix und leere Beschreibung
+    ändern die Norm bzw. brauchen Inhalt — bleiben Befund."""
+    fixed = []
+    for h in report.get("hygiene", []):
+        alt = h.get("titel", "")
+        neu = clean_title(alt)
+        if neu == alt or _norm_title(neu) != _norm_title(alt):
+            continue
+        norm = _norm_title(alt)
+        card = by_norm.get(norm)
+        if not card:
+            continue
+        p = dict(card["payload"])
+        p["title"] = neu
+        await db.kanban_set_payload(topic, "inventory", card["card_id"], p)
+        await db.set_block_status(topic, norm, "consensus", title=neu)
+        _rename_in_files(files, norm, neu)
+        fixed.append(f"{alt} → {neu}")
+    return fixed
+
+
+async def _merge_dubletten(topic: str, report: dict, by_norm: dict, files: dict) -> list[str]:
+    """Nur QA-bestätigte Paare (llm=ja); eine Zweitmeinung, Merge nur bei erneut ja.
+    Merge spiegelt die dedup-Stage: Union ins Gewinner-Payload, Verlierer → grouped."""
+    paare = [p for p in report.get("dubletten", []) if p.get("llm") == "ja"
+             and _norm_title(p.get("a", "")) in by_norm and _norm_title(p.get("b", "")) in by_norm]
+    if not paare:
+        return []
+    v, _frei = await _mit_stichentscheid("QA-Dubletten", topic, "dubletten", "pairs",
+                                         [f"A: {p['a']}\nB: {p['b']}" for p in paare], "ja")
+    merged = []
+    for i, p in enumerate(paare, 1):
+        a, b = by_norm.get(_norm_title(p["a"])), by_norm.get(_norm_title(p["b"]))
+        if v.get(i) != "ja" or not a or not b or a["card_id"] == b["card_id"]:
+            continue
+        win, lose = sorted((a, b), key=lambda c: (len(c["payload"].get("description") or ""),
+                                                  len(c["payload"].get("title") or "")), reverse=True)
+        wp, lp = dict(win["payload"]), dict(lose["payload"])
+        wp["readers"] = sorted(set(wp.get("readers") or []) | set(lp.get("readers") or []))
+        wp["sources"] = sorted(set(wp.get("sources") or []) | set(lp.get("sources") or []))
+        lp.update(reason="merged", merged_into=wp.get("title", ""))
+        await db.kanban_set_payload(topic, "inventory", win["card_id"], wp)
+        await db.kanban_set_payload(topic, "inventory", lose["card_id"], lp)
+        await db.kanban_advance(topic, "inventory", lose["card_id"], "grouped")
+        await _purge_block(topic, lp.get("title", ""), files)
+        by_norm.pop(_norm_title(lp.get("title", "")), None)
+        merged.append(f"{lp.get('title')} → {wp.get('title')}")
+    return merged
+
+
+_SUB_PAAR = re.compile(r"^\[(.+?)\] (.+)$", re.S)
+
+
+def _sub_gewinner(a: dict, b: dict) -> tuple[dict, dict]:
+    """Gewinner = mehr key_points im facts-Feld, dann längerer Titel (Muster Konsolidierung)."""
+    def score(r):
+        try:
+            kp = len((json.loads(r.get("facts") or "{}")).get("key_points") or [])
+        except ValueError:
+            kp = 0
+        return (kp, len(r.get("sub_title") or ""))
+    return (a, b) if score(a) >= score(b) else (b, a)
+
+
+async def falte_sub(topic: str, files: dict, win: dict, lose: dict) -> None:
+    """Verlierer-Sub falten: Status variant, Fragen/Artefakte zum Gewinner umhängen (oder
+    löschen, wenn der Typ dort existiert), Sidecar-Dateien bereinigen. Gemeinsamer Kern
+    von QA-Repair und Cross-Block-Dedup (Board 2, Run-Ende) — win/lose sind subblocks-Rows."""
+    await db.set_subblock_fields(topic, lose["block_norm"], lose["sub_norm"], status="variant")
+    w_fragen = {r["sub_norm"] for r in await db.list_question_pattern(topic, win["block_norm"])}
+    for r in await db.list_question_pattern(topic, lose["block_norm"]):
+        if r["sub_norm"] != lose["sub_norm"]:
+            continue
+        if win["sub_norm"] not in w_fragen:
+            await db.upsert_question_pattern(topic, win["block_norm"], win["sub_norm"],
+                                             win["block"], win["sub_title"], r["question"])
+        await db.delete_frage_row(topic, lose["block_norm"], lose["sub_norm"])
+    w_typen = {r["type"] for r in await db.get_sub_artefakte(topic, block_norm=win["block_norm"])
+               if r["sub_norm"] == win["sub_norm"]}
+    for r in await db.get_sub_artefakte(topic, block_norm=lose["block_norm"]):
+        if r["sub_norm"] != lose["sub_norm"]:
+            continue
+        if r["type"] not in w_typen:
+            await db.put_sub_artifact(topic, win["block_norm"], win["sub_norm"], r["type"],
+                                      r["data"], win["block"], win["sub_title"])
+        await db.delete_artefakt_row(topic, lose["block_norm"], lose["sub_norm"], r["type"])
+    _entferne_sub_in_files(files, lose["block_norm"], lose["sub_norm"])
+
+
+async def _merge_sub_dubletten(topic: str, report: dict, files: dict) -> tuple[list[str], list[str]]:
+    """QA-bestätigte Sub-Paare (llm=ja) nach Zweitmeinung falten: Verlierer → variant,
+    seine Fragen/Artefakte wandern zum Gewinner (oder fallen weg, wenn er den Typ hat).
+    Repair hatte dafür keinen Handler — die Paare überlebten jeden Repair-Zyklus."""
+    rows = {(r["block_norm"], r["sub_norm"]): r for r in await db.list_subblocks(topic)
+            if r["status"] == "consensus"}
+
+    def _row(eintrag: str):
+        m = _SUB_PAAR.match(eintrag or "")
+        return rows.get((_norm_title(m.group(1)), _norm_title(m.group(2)))) if m else None
+
+    paare = [(a, b) for p in report.get("sub_dubletten", []) if p.get("llm") == "ja"
+             and (a := _row(p.get("a"))) and (b := _row(p.get("b")))
+             and (a["block_norm"], a["sub_norm"]) != (b["block_norm"], b["sub_norm"])]
+    if not paare:
+        return [], []
+    v, frei = await _mit_stichentscheid(
+        "QA-Sub-Dubletten", topic, "sub-dubletten", "pairs",
+        [f"A: [{a['block']}] {a['sub_title']}\nB: [{b['block']}] {b['sub_title']}" for a, b in paare],
+        "ja", kategorie="sub_dubletten",
+        ids=[qa._paar_key(f"[{a['block']}] {a['sub_title']}", f"[{b['block']}] {b['sub_title']}")
+             for a, b in paare])
+    merged: list[str] = []
+    gone: set[tuple] = set()
+    for i, (a, b) in enumerate(paare, 1):
+        win, lose = _sub_gewinner(a, b)
+        wk, lk = (win["block_norm"], win["sub_norm"]), (lose["block_norm"], lose["sub_norm"])
+        if v.get(i) != "ja" or wk in gone or lk in gone:
+            continue
+        await falte_sub(topic, files, win, lose)
+        gone.add(lk)
+        merged.append(f"{lose['sub_title'][:40]} → {win['sub_title'][:40]}")
+    return merged, frei
+
+
+def _entferne_sub_in_files(files: dict, bnorm: str, sub_norm: str) -> None:
+    """Verlierer-Sub aus den Sidecar-JSONs nehmen (Legacy-Lesepfad von Guide/Frontend);
+    die DB trägt die umgehängten Fragen/Artefakte."""
+    for key, feld in (("sidecar", "title"), ("sub_roh", None), ("question_pattern", "subblock")):
+        d = _json_file(files[key])
+        if not isinstance(d, dict):
+            continue
+        changed = False
+        for bt, eintraege in d.items():
+            if _norm_title(bt) != bnorm or not isinstance(eintraege, list):
+                continue
+            neu = [e for e in eintraege
+                   if _norm_title(e if feld is None else str((e or {}).get(feld, ""))) != sub_norm]
+            if len(neu) != len(eintraege):
+                d[bt] = neu
+                changed = True
+        if changed:
+            atomic_write_json(files[key], d, indent=1)
+    art = _json_file(files["artefakte"])
+    if isinstance(art, dict):
+        neu = {t: [e for e in (es if isinstance(es, list) else [])
+                   if not (_norm_title(_title(str(e.get("block", "")))) == bnorm
+                           and _norm_title(str(e.get("subblock", ""))) == sub_norm)]
+               for t, es in art.items()}
+        if neu != art:
+            atomic_write_json(files["artefakte"], neu, indent=1)
+
+
+async def _entferne_fremd_unecht(topic: str, report: dict, by_norm: dict, files: dict) -> tuple[list[str], list[str]]:
+    out = []
+    frei_alle: list[str] = []
+    fremd = [t for t in report.get("fremd", []) if _norm_title(t) in by_norm]
+    if fremd:
+        folder = source_folder(topic)
+        lines = []
+        for t in fremd:
+            srcs = by_norm[_norm_title(t)]["payload"].get("sources") or None
+            ev = _evidence_pack(folder, srcs, [t], budget=EVIDENCE_PER_BLOCK) if folder else ""
+            lines.append(f"{t}\n{ev or '(keine Treffer im Material)'}")
+        v, frei = await _mit_stichentscheid("QA-Repair-Beleg", topic, "fremd", "blocks", lines,
+                                            "nein", kategorie="fremd",
+                                            ids=[_norm_title(t) for t in fremd])
+        frei_alle += frei
+        for i, t in enumerate(fremd, 1):
+            if v.get(i) == "nein":
+                await _reject(topic, t, by_norm, files, "qa-fremd")
+                out.append(t)
+    unecht = [t for t in report.get("unecht", []) if _norm_title(t) in by_norm]
+    if unecht:
+        lines = [f"{t} — {by_norm[_norm_title(t)]['payload'].get('description') or '(ohne Beschreibung)'}"
+                 for t in unecht]
+        v, frei = await _mit_stichentscheid("QA-Bausteine", topic, "unecht", "blocks", lines,
+                                            "nein", kategorie="unecht",
+                                            ids=[_norm_title(t) for t in unecht])
+        frei_alle += frei
+        for i, t in enumerate(unecht, 1):
+            if v.get(i) == "nein":
+                await _reject(topic, t, by_norm, files, "qa-unecht")
+                out.append(t)
+    return out, frei_alle
+
+
+async def _raeume_waisen(topic: str) -> int:
+    """Artefakte/Fragen mit totem Ziel löschen (Sub verworfen oder weg) — inert, der
+    Übungs-Join spielt sie nie aus, aber sie drücken die Artefakt-Note. Mehrdeutige
+    Präfix-Treffer bleiben (könnten lebend sein — Löschen wäre riskanter als behalten)."""
+    lebt = {(r["block_norm"], r["sub_norm"]) for r in await db.list_subblocks(topic)
+            if r["status"] != "discarded"}
+
+    def tot(bn: str, sn: str) -> bool:
+        if (bn, sn) in lebt:
+            return False
+        return not any(b == bn and s.startswith(sn + ":") for b, s in lebt)
+
+    n = 0
+    for r in await db.get_sub_artefakte(topic):
+        if tot(r["block_norm"], r["sub_norm"]):
+            await db.delete_artefakt_row(topic, r["block_norm"], r["sub_norm"], r["type"])
+            n += 1
+    for r in await db.list_question_pattern(topic):
+        if tot(r["block_norm"], r["sub_norm"]):
+            await db.delete_frage_row(topic, r["block_norm"], r["sub_norm"])
+            n += 1
+    return n
+
+
+async def _reject(topic: str, title: str, by_norm: dict, files: dict, grund: str) -> None:
+    norm = _norm_title(title)
+    card = by_norm.pop(norm, None)
+    if not card:
+        return
+    p = dict(card["payload"])
+    p["reason"] = grund
+    await db.kanban_set_payload(topic, "inventory", card["card_id"], p)
+    await db.kanban_advance(topic, "inventory", card["card_id"], "rejected")
+    await _purge_block(topic, title, files)
+
+
+async def _purge_block(topic: str, title: str, files: dict) -> None:
+    """Abgeleitete Daten eines Blocks gezielt entfernen (DB-Spiegel, Board-2-Karte, Sidecars)."""
+    norm = _norm_title(title)
+    await db.set_block_status(topic, norm, "discarded")
+    await db.delete_subblocks(topic, norm)
+    await db.delete_question_pattern(topic, norm)
+    await db.delete_sub_artefakte(topic, norm)
+    await db.kanban_delete_card(topic, "artefacts", norm)
+    for key in ("sidecar", "facts", "question_pattern", "sub_roh"):
+        d = _json_file(files[key])
+        if isinstance(d, dict):
+            hits = [k for k in d if _norm_title(k) == norm]
+            if hits:
+                for k in hits:
+                    d.pop(k)
+                atomic_write_json(files[key], d, indent=1)
+    art = _json_file(files["artefakte"])
+    if isinstance(art, dict):
+        neu = {t: [e for e in (es if isinstance(es, list) else [])
+                   if _norm_title(_title(str(e.get("block", "")))) != norm]
+               for t, es in art.items()}
+        if neu != art:
+            atomic_write_json(files["artefakte"], neu, indent=1)
+
+
+def _rename_in_files(files: dict, norm: str, neu: str) -> None:
+    """Titel-Keys der Sidecar-JSONs + artefakte-`block`-Felder auf den bereinigten Titel."""
+    for key in ("sidecar", "facts", "question_pattern", "sub_roh"):
+        d = _json_file(files[key])
+        if isinstance(d, dict):
+            hits = [k for k in d if _norm_title(k) == norm and k != neu]
+            if hits:
+                for k in hits:
+                    d[neu] = d.pop(k)
+                atomic_write_json(files[key], d, indent=1)
+    art = _json_file(files["artefakte"])
+    if isinstance(art, dict):
+        changed = False
+        for es in art.values():
+            for e in es if isinstance(es, list) else []:
+                if _norm_title(_title(str(e.get("block", "")))) == norm and e.get("block") != neu:
+                    e["block"] = neu
+                    changed = True
+        if changed:
+            atomic_write_json(files["artefakte"], art, indent=1)

backend/requirements.txt

@@ -1,3 +1,10 @@
 fastapi
 uvicorn[standard]
 aiosqlite
+httpx
+playwright
+trafilatura
+pymupdf4llm
+transformers
+# torch NICHT hier listen — sonst zieht pip die CUDA-Variante (~2,5 GB).
+# Es wird separat als CPU-Build installiert (Dockerfile + Makefile-Target `install`).

backend/rules.py

@@ -0,0 +1,141 @@
+"""Learning-debt rules: progression and cap for open guides — the ONLY source.
+
+Rules (new creations only; topics + blocks unlimited):
+- Format "Guide": at most 3 created, not-yet-completed guides
+- No more progression/prerequisite (only a single guide format).
+- Completed: ALL blocks (section titles) of the latest finished guide have
+  a passed exam. The rest is read-only (no progress, no exam).
+All functions work on data loaded once (load_learnstate) — no more
+query loops per guide.
+"""
+
+import json
+
+from database import list_block_scores_all, subs_per_level_all, list_guides
+from guide import guide_slot_files
+from learning import cap_final, LEVELS, _threshold
+from paths import blocks_path, guide_content_path
+from textkit import _norm_title
+
+MAX_OFFENE_GUIDES = 3
+# Only ONE format "Guide" left (all relevant blocks, exam 0–cap). No progression,
+# no prerequisite → the guide is always unlockable. "Rest"/FullGuide are separate.
+PRESTAGE: dict[str, str] = {}
+FREISCHALT_LEVEL: dict[str, str] = {}
+FORMATE = ("Guide",)
+
+# 4 learning levels (floor in % of the cap) — keys from learning.LEVELS.
+_LEVEL_WORT = {
+    "beginner": "to beginner (20%)",
+    "advanced": "to advanced (40%)",
+    "expert": "to expert (60%)",
+    "master": "to mastery (100%)",
+}
+
+
+async def load_learnstate() -> tuple[list[dict], dict[str, dict[str, set[str]]]]:
+    """Guides + blocks per level.
+
+    levels: {"beginner"/"advanced"/"expert"/"master": {topic → normalized title}}.
+    The level per block is derived from score + cap (4×relevant subs).
+    """
+    scores = await list_block_scores_all()
+    subs_by_level = await subs_per_level_all()
+    levels: dict[str, dict[str, set[str]]] = {key: {} for key, _ in LEVELS}
+    for topic, block, score in scores:
+        cf = cap_final(subs_by_level.get((topic, _norm_title(block)), {}))
+        for key, p in LEVELS:
+            if cf and score >= _threshold(p, cf):
+                levels[key].setdefault(topic, set()).add(_norm_title(block))
+    return await list_guides(), levels
+
+
+def _content_json(topic: str, fmt: str) -> dict | None:
+    path = guide_content_path(topic, fmt)
+    if not path.exists():
+        return None
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except ValueError:
+        return None
+
+
+
+
+def _section_title(topic: str, fmt: str) -> set[str] | None:
+    """Normalized block titles (sections) from the guide content."""
+    content = _content_json(topic, fmt)
+    if content is None:
+        return None
+    return {
+        _norm_title(s.get("title", ""))
+        for ch in content.get("chapters", [])
+        for s in ch.get("sections", [])
+    }
+
+
+def _latest_done(guides: list[dict], fmt: str) -> dict[str, dict]:
+    """Per topic, the latest finished guide of this format."""
+    latest: dict[str, dict] = {}
+    for g in guides:
+        if g["format"] == fmt and g["status"] == "done":
+            if g["topic"] not in latest or g["created_at"] > latest[g["topic"]]["created_at"]:
+                latest[g["topic"]] = g
+    return latest
+
+
+def _guide_all(g: dict, levelset: dict[str, set[str]]) -> bool:
+    """Are ALL blocks of the guide at the required level?"""
+    sections = _section_title(g["topic"], g["format"])
+    return bool(sections) and sections <= levelset.get(g["topic"], set())
+
+
+def is_level(topic: str, fmt: str, guides: list[dict], levelset: dict[str, set[str]]) -> bool:
+    """Latest finished guide (topic+format): all blocks at the level of levelset?"""
+    g = _latest_done(guides, fmt).get(topic)
+    return g is not None and _guide_all(g, levelset)
+
+
+def ist_completed(topic: str, fmt: str, guides: list[dict], levels: dict[str, dict[str, set[str]]]) -> bool:
+    """All blocks of the latest finished guide at least beginner (≥20%)?"""
+    return is_level(topic, fmt, guides, levels["beginner"])
+
+
+def topic_completed(topic: str, guides: list[dict], levels: dict[str, dict[str, set[str]]]) -> bool:
+    """Topic done: latest finished guide, all blocks at master (100%)?"""
+    return is_level(topic, "Guide", guides, levels["master"])
+
+
+def formats_stats(guides: list[dict], levels: dict[str, dict[str, set[str]]]) -> dict:
+    """Per format created/completed — per topic only the latest finished guide counts."""
+    formats = {}
+    for fmt in FORMATE:
+        latest = _latest_done(guides, fmt)
+        completed = sum(1 for g in latest.values() if _guide_all(g, levels["beginner"]))
+        formats[fmt] = {"created": len(latest), "completed": completed}
+    return formats
+
+
+def guide_lock(topic: str, fmt: str, guides: list[dict], levels: dict[str, dict[str, set[str]]]) -> str | None:
+    """Reason why a fresh start for topic+format is locked — None = allowed.
+
+    Exactly the rules from POST /guides: blocks required, no duplicate start,
+    learning debt only for genuine new creations (resume/regenerate are free).
+    """
+    if not blocks_path(topic).exists():
+        return "Create blocks first"
+    for g in guides:
+        if g["topic"] == topic and g["format"] == fmt and g["status"] in ("queued", "generating"):
+            return "Generation already running"
+    content = guide_content_path(topic, fmt)
+    if not content.exists() and not guide_slot_files(content):
+        prereq = PRESTAGE.get(fmt)
+        if prereq:
+            level = FREISCHALT_LEVEL[fmt]  # completed=10 · understood=20 · mastered=30
+            if not is_level(topic, prereq, guides, levels[level]):
+                return f"First take the {prereq} of this topic {_LEVEL_WORT[level]}"
+        stat = formats_stats(guides, levels).get(fmt, {"created": 0, "completed": 0})
+        open_count = stat["created"] - stat["completed"]
+        if open_count >= MAX_OFFENE_GUIDES:
+            return f"Complete {fmt}s first — at most {MAX_OFFENE_GUIDES} open allowed ({open_count} open)"
+    return None

backend/tests/conftest.py

@@ -0,0 +1,31 @@
+import sys
+from pathlib import Path
+
+import pytest
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+import database  # noqa: E402
+
+
+@pytest.fixture
+async def testdb(tmp_path, monkeypatch):
+    """Fresh sqlite file per test; resets the module-global connection."""
+    monkeypatch.setattr(database, "DB_PATH", tmp_path / "test.db")
+    database._db = None
+    await database.init_db()
+    yield database
+    await database.close_db()
+
+
+@pytest.fixture
+async def fake_welt(testdb, tmp_path, monkeypatch):
+    """E2E ohne LLM: run_agent überall durch die Fake-Welt ersetzt, Tempo-Bremsen raus.
+    Alle echten Schichten (_race, Quorum, Panels, Producer, QA-Gate) laufen mit."""
+    import qa
+    from fake_agents import Welt, aktivieren
+
+    welt = Welt()
+    aktivieren(welt, setattr_fn=monkeypatch.setattr)
+    monkeypatch.setattr(qa, "QA_DIR", tmp_path / "qa")  # Reports nie in echte Nutzdaten
+    return welt

backend/tests/invarianten.py

@@ -0,0 +1,96 @@
+"""Invarianten nach einem (Fake-)E2E-Lauf: was IMMER gelten muss, egal welches Szenario.
+
+Nutzt bewusst eigene, schlichte Prüfungen statt Pipeline-Heuristiken (Muster qa.py) —
+geteilte blinde Flecken machen den Check wertlos. Rückgabe: Liste von Verstößen,
+leer = alles konsistent.
+"""
+
+import json
+
+import database as db
+from textkit import _norm_title
+
+_LEVELS_OK = {"beginner", "advanced", "expert"}
+_RELEVANZ_OK = {"relevant", "peripheral"}
+
+
+def _json(path):
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+
+
+async def pruefe_invarianten(topic: str, files: dict | None = None,
+                             mit_artefakten: bool = True) -> list[str]:
+    fehler: list[str] = []
+    subs = [dict(r) for r in await db.list_subblocks(topic)]
+    cons = [r for r in subs if r["status"] == "consensus"]
+
+    for r in cons:
+        wo = f"{r['block']}/{r['sub_title']}"
+        fk = None
+        try:
+            fk = json.loads(r["facts"]) if r["facts"] else None
+        except ValueError:
+            fehler.append(f"facts unparsebar: {wo}")
+        if not (isinstance(fk, dict) and (fk.get("key_points") or fk.get("cited_facts"))):
+            fehler.append(f"consensus-Sub ohne facts: {wo}")
+        if r["level"] not in _LEVELS_OK:
+            fehler.append(f"consensus-Sub ohne gültiges level: {wo}")
+        if r["relevance"] not in _RELEVANZ_OK:
+            fehler.append(f"consensus-Sub ohne relevance: {wo}")
+
+    if mit_artefakten:
+        art = [dict(r) for r in await db.get_sub_artefakte(topic)]
+        fragen = [dict(r) for r in await db.list_question_pattern(topic)]
+        versorgt = {(r["block_norm"], r["sub_norm"]) for r in art}
+        versorgt |= {(r["block_norm"], r["sub_norm"]) for r in fragen}
+        lebend = {(r["block_norm"], r["sub_norm"]) for r in subs if r["status"] in ("consensus", "variant")}
+        for r in cons:
+            if r["relevance"] == "relevant" and (r["block_norm"], r["sub_norm"]) not in versorgt:
+                fehler.append(f"relevanter Sub ohne Frage/Artefakt: {r['block']}/{r['sub_title']}")
+        for bn, sn in sorted({(r["block_norm"], r["sub_norm"]) for r in art} |
+                             {(r["block_norm"], r["sub_norm"]) for r in fragen}):
+            if (bn, sn) not in lebend:
+                fehler.append(f"Waise (Ziel-Sub existiert nicht): {bn}/{sn}")
+
+    # keine hängengebliebenen Karten
+    for c in await db.kanban_cards(topic):
+        if c["stage"] == "dead":
+            fehler.append(f"dead-Karte: {c['board']}/{c['card_id']}")
+
+    if files is not None:
+        if not files["final"].exists():
+            fehler.append("blocks.md fehlt")
+        sc = _json(files["sidecar"])
+        if not isinstance(sc, dict):
+            fehler.append("sidecar-Datei fehlt/unparsebar")
+        else:  # Sidecar und DB-consensus müssen dieselbe Sub-Menge tragen
+            db_menge = {(r["block_norm"], r["sub_norm"]) for r in cons}
+            sc_menge = {(_norm_title(bt), _norm_title(str(s.get("title", ""))))
+                        for bt, ss in sc.items() for s in ss if isinstance(s, dict)}
+            for extra in sorted(sc_menge - db_menge):
+                fehler.append(f"Sidecar-Sub fehlt in DB: {extra}")
+            for extra in sorted(db_menge - sc_menge):
+                fehler.append(f"DB-consensus fehlt im Sidecar: {extra}")
+    return fehler
+
+
+async def pruefe_guide_invarianten(topic: str, format_name: str = "Guide") -> list[str]:
+    """Jeder relevante consensus-Sub trägt einen Sub-Marker im Guide (Muster
+    guide_qa.marker_fehlend, ohne LLM)."""
+    import guide_qa
+    fehler: list[str] = []
+    cards = [dict(r) for r in await db.list_guide_cards(topic, format_name)]
+    if not cards:
+        return ["keine Guide-Karten"]
+    for c in cards:
+        if c["status"] != "ok" or not (c.get("md") or "").strip():
+            fehler.append(f"Guide-Karte nicht ok: {c['block']} ({c['status']})")
+    subs_rel: dict[str, set] = {}
+    for r in await db.list_subblocks(topic):
+        if r["status"] == "consensus" and r["relevance"] != "peripheral":
+            subs_rel.setdefault(r["block_norm"], set()).add(r["sub_norm"])
+    fehler += [f"Sub-Marker fehlt: {m}" for m in guide_qa.marker_fehlend(cards, subs_rel)]
+    return fehler

backend/tests/test_agents_api.py

@@ -0,0 +1,255 @@
+"""Direkter Text-API-Pfad (MiniMax) + RAM-Gate für opencode-Spawns."""
+
+import asyncio
+
+import httpx
+import pytest
+
+import agents
+
+TOPIC = "t"
+
+
+# ── Routing: wann läuft ein Call über die API statt über opencode? ───────────────────
+
+def test_use_text_api_routing(monkeypatch):
+    monkeypatch.setenv("MINIMAX_API_KEY", "k")
+    monkeypatch.delenv("CREATOR_TEXT_API", raising=False)
+    api = agents._use_text_api
+    assert api("minimax", "minimax/MiniMax-M3", "none", None) is True
+    assert api("minimax", "minimax-kalt/MiniMax-M2.7-highspeed", "none", None) is True
+    # Tools, Streaming, andere Provider/Modelle → Prozess-Pfad
+    assert api("minimax", "minimax/MiniMax-M3", "files", None) is False
+    assert api("minimax", "minimax/MiniMax-M3", "none", lambda s: None) is False
+    assert api("claude", "claude-sonnet-4-6", "none", None) is False
+    assert api("lokal", "ollama/qwen3.5:9b", "none", None) is False
+    # Kill-Switch und fehlender Key → Fallback
+    monkeypatch.setenv("CREATOR_TEXT_API", "0")
+    assert api("minimax", "minimax/MiniMax-M3", "none", None) is False
+    monkeypatch.delenv("CREATOR_TEXT_API")
+    monkeypatch.delenv("MINIMAX_API_KEY")
+    assert api("minimax", "minimax/MiniMax-M3", "none", None) is False
+
+
+async def test_run_agent_dispatches_to_api(monkeypatch):
+    """none+minimax → API-Runner; opencode wird nicht angefasst (auch kein which-Check)."""
+    called = {}
+
+    async def fake_api(agent_key, prompt, timeout, model, label=""):
+        called["api"] = (agent_key, model)
+        return 0, "out", "", {"input": 1, "output": 1, "reasoning": 0, "cache_read": 0, "cache_write": 0}
+
+    async def fail_oc(*a, **kw):
+        raise AssertionError("opencode-Pfad darf nicht laufen")
+
+    monkeypatch.delenv("CREATOR_FAKE_AGENTS", raising=False)
+    monkeypatch.setenv("MINIMAX_API_KEY", "k")
+    monkeypatch.setattr(agents, "_run_text_api", fake_api)
+    monkeypatch.setattr(agents, "_run_opencode", fail_oc)
+    monkeypatch.setattr(agents.shutil, "which", lambda c: None)  # API-Pfad braucht kein Binary
+    monkeypatch.setattr(agents, "resolve_role", lambda p, r: ("minimax", "minimax/MiniMax-M3"))
+    rc, out, err = await agents.run_agent("blocks-t-a", "p", 5, provider="minimax", role="judge")
+    assert (rc, out) == (0, "out") and called["api"][1] == "minimax/MiniMax-M3"
+
+
+async def test_run_agent_kill_switch_uses_opencode(monkeypatch):
+    called = {}
+
+    async def fake_oc(agent_key, prompt, timeout, provider, model, capabilities, on_line=None, label=""):
+        called["oc"] = agent_key
+        return 0, "out", ""
+
+    monkeypatch.delenv("CREATOR_FAKE_AGENTS", raising=False)
+    monkeypatch.setenv("MINIMAX_API_KEY", "k")
+    monkeypatch.setenv("CREATOR_TEXT_API", "0")
+    monkeypatch.setattr(agents, "_run_opencode", fake_oc)
+    monkeypatch.setattr(agents.shutil, "which", lambda c: "/bin/true")
+    monkeypatch.setattr(agents, "resolve_role", lambda p, r: ("minimax", "minimax/MiniMax-M3"))
+    rc, *_ = await agents.run_agent("blocks-t-b", "p", 5, provider="minimax")
+    assert rc == 0 and called["oc"] == "blocks-t-b"
+
+
+async def test_run_agent_api_tokens_in_event_meta(monkeypatch):
+    """API-Tokens landen im Event-Meta; die OpenCode-Session-DB wird NICHT konsultiert."""
+    recorded = []
+
+    async def sink(**kw):
+        recorded.append(kw)
+
+    async def fake_api(agent_key, prompt, timeout, model, label=""):
+        return 0, "out", "", {"input": 5, "output": 2, "reasoning": 0, "cache_read": 100, "cache_write": 0}
+
+    monkeypatch.delenv("CREATOR_FAKE_AGENTS", raising=False)
+    monkeypatch.setenv("MINIMAX_API_KEY", "k")
+    monkeypatch.setattr(agents, "on_event", sink)
+    monkeypatch.setattr(agents, "_run_text_api", fake_api)
+    monkeypatch.setattr(agents, "_session_tokens", lambda k: pytest.fail("Session-DB-Lookup im API-Pfad"))
+    monkeypatch.setattr(agents.shutil, "which", lambda c: "/bin/true")
+    monkeypatch.setattr(agents, "resolve_role", lambda p, r: ("minimax", "minimax/MiniMax-M3"))
+    rc, *_ = await agents.run_agent("blocks-t-tok", "p", 5, provider="minimax", scope=TOPIC)
+    assert rc == 0
+    assert recorded and recorded[0]["meta"]["tokens"] == {
+        "input": 5, "output": 2, "reasoning": 0, "cache_read": 100, "cache_write": 0}
+
+
+# ── API-Runner: Request-Bau, Antwort-Extraktion, Fehlerfälle ─────────────────────────
+
+class _FakeResp:
+    def __init__(self, status_code=200, data=None, text=""):
+        self.status_code = status_code
+        self._data = data or {}
+        self.text = text
+
+    def json(self):
+        return self._data
+
+
+def _fake_client(monkeypatch, seen, resp=None, exc=None):
+    class _Client:
+        def __init__(self, **kw):
+            seen["client_kw"] = kw
+
+        async def __aenter__(self):
+            return self
+
+        async def __aexit__(self, *a):
+            return False
+
+        async def post(self, url, json=None, headers=None):
+            seen.update(url=url, body=json, headers=headers)
+            if exc is not None:
+                raise exc
+            return resp
+
+    monkeypatch.setattr(agents.httpx, "AsyncClient", _Client)
+
+
+async def test_api_request_and_response(monkeypatch):
+    monkeypatch.setenv("MINIMAX_API_KEY", "geheim")
+    seen = {}
+    resp = _FakeResp(data={
+        "content": [{"type": "thinking", "thinking": "hm"},
+                    {"type": "text", "text": "A"}, {"type": "text", "text": "B"}],
+        "usage": {"input_tokens": 5, "output_tokens": 2,
+                  "cache_read_input_tokens": 100, "cache_creation_input_tokens": 1},
+        "stop_reason": "end_turn"})
+    _fake_client(monkeypatch, seen, resp=resp)
+    rc, out, err, tokens = await agents._run_text_api("k", "PROMPT", 5, "minimax-kalt/MiniMax-M3")
+    assert (rc, out, err) == (0, "AB", "")  # Thinking-Block übersprungen
+    assert tokens == {"input": 5, "output": 2, "reasoning": 0, "cache_read": 100, "cache_write": 1}
+    assert seen["url"] == agents._API_URL
+    assert seen["headers"]["x-api-key"] == "geheim"
+    assert seen["headers"]["anthropic-version"] == agents._API_VERSION
+    b = seen["body"]
+    assert b["model"] == "MiniMax-M3" and b["max_tokens"] == agents._API_MAX_TOKENS
+    assert b["messages"] == [{"role": "user", "content": "PROMPT"}]
+    assert b["temperature"] == 0.2 and b["thinking"] == {"type": "disabled"}  # kalt-Route
+
+
+async def test_api_model_options_per_route(monkeypatch):
+    monkeypatch.setenv("MINIMAX_API_KEY", "k")
+    seen = {}
+    resp = _FakeResp(data={"content": [{"type": "text", "text": "x"}], "usage": {}})
+    _fake_client(monkeypatch, seen, resp=resp)
+    await agents._run_text_api("k", "p", 5, "minimax-kalt/MiniMax-M2.7-highspeed")
+    assert seen["body"]["temperature"] == 0.3 and "thinking" not in seen["body"]
+    await agents._run_text_api("k", "p", 5, "minimax/MiniMax-M3")  # nativ: Endpunkt-Defaults
+    assert "temperature" not in seen["body"] and "thinking" not in seen["body"]
+
+
+async def test_api_errors(monkeypatch):
+    monkeypatch.setenv("MINIMAX_API_KEY", "k")
+    seen = {}
+    _fake_client(monkeypatch, seen, resp=_FakeResp(status_code=500, text="kaputt"))
+    rc, out, err, tokens = await agents._run_text_api("k", "p", 5, "minimax/MiniMax-M3")
+    assert rc == 1 and out == "" and "HTTP 500" in err and tokens is None
+
+    _fake_client(monkeypatch, seen, exc=httpx.ConnectError("down"))
+    rc, _, err, _ = await agents._run_text_api("k", "p", 5, "minimax/MiniMax-M3")
+    assert rc == 1 and "ConnectError" in err
+
+    _fake_client(monkeypatch, seen, exc=httpx.ReadTimeout("langsam"))
+    with pytest.raises(asyncio.TimeoutError):
+        await agents._run_text_api("k", "p", 5, "minimax/MiniMax-M3")
+
+    # leere Antwort (nur Thinking) → rc 1, Tokens bleiben sichtbar
+    resp = _FakeResp(data={"content": [{"type": "thinking", "thinking": "…"}],
+                           "usage": {"input_tokens": 3}, "stop_reason": "end_turn"})
+    _fake_client(monkeypatch, seen, resp=resp)
+    rc, _, err, tokens = await agents._run_text_api("k", "p", 5, "minimax/MiniMax-M3")
+    assert rc == 1 and "empty response" in err and tokens["input"] == 3
+
+
+async def test_api_truncation_flagged(monkeypatch):
+    monkeypatch.setenv("MINIMAX_API_KEY", "k")
+    seen = {}
+    resp = _FakeResp(data={"content": [{"type": "text", "text": "halb"}],
+                           "usage": {}, "stop_reason": "max_tokens"})
+    _fake_client(monkeypatch, seen, resp=resp)
+    rc, out, err, _ = await agents._run_text_api("k", "p", 5, "minimax/MiniMax-M3")
+    assert rc == 0 and out == "halb" and "max_tokens" in err
+
+
+# ── RAM-Gate ─────────────────────────────────────────────────────────────────────────
+
+@pytest.fixture
+def ram_gate(monkeypatch):
+    monkeypatch.setattr(agents, "RAM_MIN_FREE_PCT", 20)
+    monkeypatch.setattr(agents, "_RAM_POLL_S", 0.01)
+    monkeypatch.setattr(agents, "_opencode_recent_starts", [])
+    return monkeypatch
+
+
+async def test_ram_gate_admits_with_free_ram(ram_gate):
+    ram_gate.setattr(agents, "_opencode_running", 5)
+    ram_gate.setattr(agents, "_meminfo", lambda: (4_000_000, 8_000_000))  # 50 % frei
+    assert await agents._ram_gate("k") is True
+    assert len(agents._opencode_recent_starts) == 1  # Commit registriert
+
+
+async def test_ram_gate_waits_when_low(ram_gate):
+    ram_gate.setattr(agents, "_opencode_running", 5)
+    ram_gate.setattr(agents, "_meminfo", lambda: (800_000, 8_000_000))  # 10 % frei
+    with pytest.raises(asyncio.TimeoutError):
+        await asyncio.wait_for(agents._ram_gate("k"), 0.1)
+    # RAM wird frei → Gate lässt nach ≥1 Poll durch
+    vals = iter([(800_000, 8_000_000)])
+    ram_gate.setattr(agents, "_meminfo", lambda: next(vals, (4_000_000, 8_000_000)))
+    assert await agents._ram_gate("k") is True
+
+
+async def test_ram_gate_floor_and_fail_open(ram_gate):
+    ram_gate.setattr(agents, "_meminfo", lambda: (100_000, 8_000_000))  # fast nichts frei
+    ram_gate.setattr(agents, "_opencode_running", 1)  # unter Floor
+    assert await agents._ram_gate("k") is True
+    ram_gate.setattr(agents, "_opencode_running", 5)
+    ram_gate.setattr(agents, "_meminfo", lambda: None)  # kein /proc/meminfo
+    assert await agents._ram_gate("k") is True
+    ram_gate.setattr(agents, "RAM_MIN_FREE_PCT", 0)  # Gate aus
+    ram_gate.setattr(agents, "_meminfo", lambda: pytest.fail("Gate aus liest kein meminfo"))
+    assert await agents._ram_gate("k") is True
+
+
+async def test_ram_gate_commit_accounting(ram_gate):
+    """Knapp über der Schwelle, aber 2 frische Zulassungen → deren geschätzter RSS zählt."""
+    import time as _time
+    ram_gate.setattr(agents, "_opencode_running", 5)
+    ram_gate.setattr(agents, "_meminfo", lambda: (1_700_000, 8_000_000))  # 21 % frei
+    agents._opencode_recent_starts.extend([_time.monotonic(), _time.monotonic()])
+    with pytest.raises(asyncio.TimeoutError):
+        await asyncio.wait_for(agents._ram_gate("k"), 0.1)
+
+
+async def test_ram_gate_cancelled_scope(ram_gate):
+    ram_gate.setattr(agents, "_opencode_running", 5)
+    ram_gate.setattr(agents, "_meminfo", lambda: (800_000, 8_000_000))
+    agents.cancel_scope("blocks-cxl-")
+    try:
+        assert await agents._ram_gate("blocks-cxl-x") is False
+    finally:
+        agents.clear_scope("blocks-cxl-")
+
+
+def test_meminfo_reads_proc():
+    mem = agents._meminfo()
+    assert mem is not None and 0 < mem[0] <= mem[1]  # Linux-Testumgebung

backend/tests/test_block_calls.py

@@ -0,0 +1,538 @@
+"""Verschmolzene Board-2-Calls (block_calls.py): Generate-Konsens, Verify-Faltung mit
+Fix-Tail, Artefakte in einem Durchgang — Agenten gefaked, gegen Test-DB."""
+
+import json
+
+import pytest
+
+import block_calls as bc
+import blocks as blx
+import board_artefacts as ba
+from pipeline import FAILED, OK, GenContext
+from textkit import _norm_title
+
+TOPIC = "t"
+
+
+def _ctx():
+    return GenContext(topic=TOPIC, provider="claude", is_cancelled=lambda: False)
+
+
+def _sub(title, level="beginner", relevance="relevant", kp=None, cf=None):
+    return {"title": title, "level": level, "relevance": relevance,
+            "key_points": [f"kp {title}"] if kp is None else kp,
+            "prerequisites": "", "hurdles": "", "cited_facts": cf or [], "example_idea": ""}
+
+
+# ── Schemas ─────────────────────────────────────────────────────────────────────────
+
+def test_gen_schema_normalisiert():
+    """Gültige Einträge werden normalisiert; ungültiges level/relevance fällt auf ""
+    (Stimme entfällt, der Sub bleibt); Einträge ohne Titel fliegen."""
+    out = bc._gen_schema({"subs": [
+        {"title": " **A** ", "level": "Beginner", "relevance": "RELEVANT",
+         "key_points": ["k", ""], "cited_facts": [{"text": "t", "source": " s "},
+                                                  {"text": ""}, "quatsch"]},
+        {"title": "B", "level": "profi", "relevance": "mittel"},
+        {"title": "  "},
+    ]})
+    assert [e["title"] for e in out] == ["A", "B"]
+    assert out[0]["level"] == "beginner" and out[0]["relevance"] == "relevant"
+    assert out[0]["key_points"] == ["k"]
+    assert out[0]["cited_facts"] == [{"text": "t", "source": "s"}]
+    assert out[1]["level"] == "" and out[1]["relevance"] == ""
+
+
+def test_gen_schema_kaputt_ist_none():
+    assert bc._gen_schema(None) is None
+    assert bc._gen_schema({"subs": "x"}) is None
+    assert bc._gen_schema({"subs": []}) is None
+    assert bc._gen_schema({"subs": [{"level": "beginner"}]}) is None  # nur titellose Einträge
+
+
+def test_verify_schema_pflichtkeys_und_leeres_verdikt():
+    """Mindestens EIN Pflicht-Key muss da sein; leere Listen heißen „alles ok"."""
+    assert bc._verify_schema({}, 3) is None
+    assert bc._verify_schema({"irgendwas": 1}, 3) is None
+    v = bc._verify_schema({"gruppen": []}, 3)
+    assert v["gruppen"] == [] and v["fremd"] == set() and v["luecken"] == []
+    assert v["uebernehmen"] == {} and v["facts_probleme"] == [] and v["levels"] == {}
+
+
+def test_verify_schema_grenzen_und_normalisierung():
+    """ids außerhalb 1..n und bools fallen raus; Ein-Element-Gruppen zählen nicht;
+    uebernehmen/levels werden casefolded bzw. enum-geprüft."""
+    v = bc._verify_schema({
+        "gruppen": [{"haupt": 2, "weitere": [1, 9, True]}, {"haupt": 3, "weitere": []}],
+        "kataloge": [{"titel": " K ", "mitglieder": [1, 2]}, {"titel": "", "mitglieder": [1, 2]}],
+        "fremd": [True, 1, "2", 9],
+        "luecken": ["  x  ", "", 7],
+        "uebernehmen": {"3": " JA ", "9": "ja"},
+        "facts_probleme": [{"nr": 2, "discard": 1, "hinweis": " h "}, {"nr": 9}, "quatsch"],
+        "levels": {"1": "expert", "2": "quatsch"},
+        "relevanz": {"1": "peripheral"},
+    }, 3)
+    assert v["gruppen"] == [{"haupt": 2, "ids": [1, 2]}]
+    assert v["kataloge"] == [{"titel": "K", "ids": [1, 2]}]
+    assert v["fremd"] == {1, 2}
+    assert v["luecken"] == ["x"]
+    assert v["uebernehmen"] == {3: "ja"}
+    assert v["facts_probleme"] == [{"nr": 2, "discard": True, "hinweis": "h"}]
+    assert v["levels"] == {1: "expert"} and v["relevanz"] == {1: "peripheral"}
+
+
+def test_art_gen_schema_pattern_ist_pflicht():
+    """Ohne verwertbares pattern kein Verdikt (Leitner hängt an den Fragen);
+    cards/examples sind best-effort und werden einzeln validiert."""
+    assert bc._art_gen_schema({"cards": [], "examples": []}) is None
+    assert bc._art_gen_schema("x") is None
+    out = bc._art_gen_schema({
+        "pattern": [{"block": "B", "subblock": "S", "question": "F?"},
+                    {"block": "B", "subblock": "", "question": "F?"}],
+        "cards": [{"block": "B", "subblock": "S", "question": "F?", "answer": "A"},
+                  {"block": "B", "subblock": "S", "question": "F?"}],
+        "examples": [{"block": "B", "subblock": "S", "problem": "P", "steps": ["s1", ""], "result": ""},
+                     {"block": "B", "subblock": "S", "problem": "P", "steps": []}],
+    })
+    assert len(out["pattern"]) == 1 and len(out["cards"]) == 1
+    assert out["examples"] == [{"block": "B", "subblock": "S", "problem": "P",
+                                "steps": ["s1"], "result": ""}]
+
+
+def test_art_check_schema_varianten():
+    """{"ok": true} → leeres Verdikt; ohne bekannten Key None; Beispiel-Indizes sind
+    1-basiert, bools/0 zählen nicht."""
+    ok = bc._art_check_schema({"ok": True})
+    assert ok == {"pattern": [], "pattern_ergaenzt": [], "examples_probleme": set()}
+    assert bc._art_check_schema({"foo": 1}) is None
+    v = bc._art_check_schema({"examples_probleme": [1, "2", {"index": 3}, True, 0, -1],
+                              "pattern_ergaenzt": [{"block": "B", "subblock": "S", "question": "F?"}]})
+    assert v["examples_probleme"] == {1, 2, 3}
+    assert len(v["pattern_ergaenzt"]) == 1 and v["pattern"] == []
+
+
+# ── Generate ────────────────────────────────────────────────────────────────────────
+
+@pytest.fixture
+def env(testdb, tmp_path, monkeypatch):
+    """Ohne Modell (exakte Norm-Gleichheit), ohne Korpus (thema-Selbst-Recherche)."""
+    monkeypatch.setattr(bc, "EMBEDDING_AKTIV", False)
+    monkeypatch.setattr(blx, "EMBEDDING_AKTIV", False)  # _dedup_subblocks aus
+    monkeypatch.setattr(bc, "material_folder", lambda t: None)
+    monkeypatch.setattr(bc, "load_source", lambda t: {"type": "thema"})
+    return testdb, _ctx(), {"arbeit": tmp_path}
+
+
+def _mk_gen_race(outputs):
+    """_race-Fake: pro Generator-Slot (…-gN) die gescriptete Antwort als Text;
+    fehlender Eintrag = Ausfall."""
+    calls = []
+
+    async def fake_race(topic, label, slots, quorum, timeout, provider, on_update=None,
+                        cancelled=None, **kw):
+        outs = []
+        for slot in slots:
+            calls.append(slot["key"])
+            g = int(slot["key"].rsplit("-g", 1)[1])
+            out = outputs.get(g)
+            if out is not None:
+                outs.append(slot["payload"]((0, json.dumps(out), "")))
+        return [o for o in outs if o] or None
+
+    fake_race.calls = calls
+    return fake_race
+
+
+async def test_generate_schnittmenge_wird_consensus(env, monkeypatch):
+    """Von beiden Generatoren genannt → consensus (Facts-Union); Einzelnennungen
+    werden unsicher und gehen zum Prüfer."""
+    db, ctx, files = env
+    monkeypatch.setattr(bc, "_race", _mk_gen_race({
+        1: {"subs": [_sub("Sub A", kp=["k1"]), _sub("Sub B")]},
+        2: {"subs": [_sub("Sub A", kp=["k2"]), _sub("Sub C")]},
+    }))
+    gen = await bc._generate_block(ctx, files, "Alpha", "Grundkonzept")
+    assert gen["raw"] == {"Alpha": ["Sub A"]}
+    assert gen["facts"]["Alpha"]["sub a"]["key_points"] == ["k1", "k2"]  # Union beider Nennungen
+    assert {u["title"] for u in gen["unsicher"]} == {"Sub B", "Sub C"}
+    assert gen["votes"]["sub a"]["level"] == ["beginner", "beginner"]
+    rows = {r["sub_norm"]: r["status"] for r in await db.list_subblocks(TOPIC, "alpha")}
+    assert rows["sub a"] == "consensus"
+    assert rows["sub b"] == rows["sub c"] == "candidate"
+
+
+async def test_generate_degraded_alles_unsicher(env, monkeypatch):
+    """Liefert nur EIN Generator, ist kein Konsens möglich — alles wird unsicher,
+    der Prüfer entscheidet mit Material."""
+    db, ctx, files = env
+    monkeypatch.setattr(bc, "_race", _mk_gen_race({
+        1: {"subs": [_sub("Sub A"), _sub("Sub B")]},  # g2 fällt aus
+    }))
+    gen = await bc._generate_block(ctx, files, "Alpha", "Grundkonzept")
+    assert gen["raw"] == {"Alpha": []}
+    assert {u["title"] for u in gen["unsicher"]} == {"Sub A", "Sub B"}
+    assert not any(r["status"] == "consensus" for r in await db.list_subblocks(TOPIC, "alpha"))
+
+
+async def test_generate_beide_ausgefallen_ist_none(env, monkeypatch):
+    db, ctx, files = env
+    monkeypatch.setattr(bc, "_race", _mk_gen_race({}))
+    assert await bc._generate_block(ctx, files, "Alpha", "d") is None
+
+
+async def test_generate_seed_garantie(env, monkeypatch):
+    """Ungedeckte Seeds gehen als unsicher zum Prüfer (Beleg-Gate liegt dort);
+    lexikalisch gedeckte Seeds erzeugen keine Dublette."""
+    db, ctx, files = env
+    monkeypatch.setattr(bc, "_race", _mk_gen_race({
+        1: {"subs": [_sub("Sub A")]}, 2: {"subs": [_sub("Sub A")]},
+    }))
+    gen = await bc._generate_block(ctx, files, "Alpha", "d",
+                                   seeds=["Escaping Regeln", "Sub"])
+    assert gen["raw"] == {"Alpha": ["Sub A"]}
+    assert [u["title"] for u in gen["unsicher"]] == ["Escaping Regeln"]  # „Sub" ist gedeckt
+    assert gen["unsicher"][0]["key_points"] == []  # Seeds kommen ohne Beleg
+
+
+async def test_generate_resume_ohne_neue_calls(env, monkeypatch):
+    """Vorhandene gen-Dateien → kein neuer _race-Call, Ergebnis wird übernommen."""
+    db, ctx, files = env
+    fake = _mk_gen_race({1: {"subs": [_sub("Sub A")]}, 2: {"subs": [_sub("Sub A")]}})
+    monkeypatch.setattr(bc, "_race", fake)
+    gen1 = await bc._generate_block(ctx, files, "Alpha", "d")
+    n = len(fake.calls)
+    gen2 = await bc._generate_block(ctx, files, "Alpha", "d")
+    assert len(fake.calls) == n  # alles resumed
+    assert gen2["raw"] == gen1["raw"]
+
+
+# ── Verify (+ Fix-Tail) ─────────────────────────────────────────────────────────────
+
+def _gen_von(title, subs, unsicher=None, votes=None):
+    """Karten-Payload wie aus _generate_block: raw/facts/unsicher/votes."""
+    return {"raw": {title: list(subs)},
+            "facts": {title: {_norm_title(s): {"key_points": [f"kp {s}"], "prerequisites": "",
+                                               "hurdles": "", "cited_facts": [], "example_idea": ""}
+                              for s in subs}},
+            "unsicher": unsicher or [], "votes": votes or {}}
+
+
+def _judge_slot(antworten, fix=None):
+    """run_single_slot-Fake: Prüfer-Antwort je j-Suffix, Fix-Antwort für -sb-fix-;
+    fehlender Eintrag = FAILED."""
+    calls = []
+
+    async def fake(ctx, label, *, key, prompt, role, capabilities, payload, timeout, on_line=None):
+        calls.append({"key": key, "prompt": prompt})
+        if "-sb-fix-" in key:
+            if fix is None:
+                return FAILED, None
+            return OK, payload((0, json.dumps(fix), ""))
+        j = key.rsplit("-j", 1)[-1]
+        antwort = antworten.get(j)
+        if antwort is None:
+            return FAILED, None
+        return OK, payload((0, json.dumps(antwort), ""))
+
+    fake.calls = calls
+    return fake
+
+
+async def _seed_rows(db, bnorm, titles, status="consensus"):
+    for t in titles:
+        await db.put_subblock(TOPIC, bnorm, _norm_title(t), bnorm.title(), t, status=status)
+
+
+async def test_verify_gruppe_faltet_einstimmig(env, monkeypatch):
+    """Beide Prüfer gruppieren 1+2 → haupt gewinnt, Verlierer wird variant und seine
+    Facts wandern per Union zum Gewinner; Dissens-Gruppen falten nicht."""
+    db, ctx, files = env
+    subs = ["Marker Regel", "Marker Regel im Detail erklärt", "Eigenes Thema"]
+    await _seed_rows(db, "alpha", subs)
+    verdikt = {"gruppen": [{"haupt": 2, "weitere": [1]}]}
+    fake = _judge_slot({"1": verdikt, "2": {"gruppen": [{"haupt": 2, "weitere": [1]},
+                                                        {"haupt": 3, "weitere": [2]}]}})
+    monkeypatch.setattr(bc, "run_single_slot", fake)
+    res = await bc._verify_block(ctx, files, "Alpha", _gen_von("Alpha", subs), {})
+    assert res["raw"] == {"Alpha": [subs[1], subs[2]]}  # Gruppe 2+3 war einseitig → kein Fold
+    wf = res["facts"]["Alpha"][_norm_title(subs[1])]
+    assert wf["key_points"] == [f"kp {subs[1]}", f"kp {subs[0]}"]  # Union geerbt
+    rows = {r["sub_norm"]: r["status"] for r in await db.list_subblocks(TOPIC, "alpha")}
+    assert rows[_norm_title(subs[0])] == "variant"
+    assert rows[_norm_title(subs[1])] == "consensus"
+
+
+async def test_verify_fremd_nur_einstimmig(env, monkeypatch):
+    """Fremd 2/2 → discarded + raus; einseitig fremd → bleibt."""
+    db, ctx, files = env
+    subs = ["CSS Regel", "Echte Regel"]
+    await _seed_rows(db, "alpha", subs)
+    fake = _judge_slot({"1": {"fremd": [1, 2]}, "2": {"fremd": [1]}})
+    monkeypatch.setattr(bc, "run_single_slot", fake)
+    res = await bc._verify_block(ctx, files, "Alpha", _gen_von("Alpha", subs), {})
+    assert res["raw"] == {"Alpha": ["Echte Regel"]}
+    rows = {r["sub_norm"]: r["status"] for r in await db.list_subblocks(TOPIC, "alpha")}
+    assert rows["css regel"] == "discarded" and rows["echte regel"] == "consensus"
+
+
+async def test_verify_uebernahme_braucht_beide(env, monkeypatch):
+    """Unsicher-Eintrag wird nur bei 2/2 „ja" consensus (samt Generator-Facts);
+    sonst discarded."""
+    db, ctx, files = env
+    subs = ["Sub A"]
+    unsicher = [_sub("Unsicher B", kp=["kp b"]), _sub("Unsicher C")]
+    await _seed_rows(db, "alpha", subs)
+    await _seed_rows(db, "alpha", ["Unsicher B", "Unsicher C"], status="candidate")
+    fake = _judge_slot({"1": {"uebernehmen": {"2": "ja", "3": "ja"}},
+                        "2": {"uebernehmen": {"2": "ja", "3": "nein"}}})
+    monkeypatch.setattr(bc, "run_single_slot", fake)
+    res = await bc._verify_block(ctx, files, "Alpha", _gen_von("Alpha", subs, unsicher=unsicher), {})
+    assert res["raw"] == {"Alpha": ["Sub A", "Unsicher B"]}
+    assert res["facts"]["Alpha"]["unsicher b"]["key_points"] == ["kp b"]
+    rows = {r["sub_norm"]: r["status"] for r in await db.list_subblocks(TOPIC, "alpha")}
+    assert rows["unsicher b"] == "consensus" and rows["unsicher c"] == "discarded"
+    # der Prüfer-Prompt weist die Unsicher-Nummern aus
+    assert "UNSICHER" in fake.calls[0]["prompt"] and "entries 2–3" in fake.calls[0]["prompt"]
+
+
+async def test_verify_facts_discard_nur_2von2(env, monkeypatch):
+    """Facts-Discard ist irreversibel → nur 2/2; die einseitige Stimme ohne Hinweis
+    löst auch keinen Fix aus."""
+    db, ctx, files = env
+    subs = ["Sub A", "Sub B"]
+    await _seed_rows(db, "alpha", subs)
+    fake = _judge_slot({"1": {"facts_probleme": [{"nr": 1, "discard": True},
+                                                 {"nr": 2, "discard": True}]},
+                        "2": {"facts_probleme": [{"nr": 1, "discard": True}]}})
+    monkeypatch.setattr(bc, "run_single_slot", fake)
+    res = await bc._verify_block(ctx, files, "Alpha", _gen_von("Alpha", subs), {})
+    assert res["raw"] == {"Alpha": ["Sub B"]}
+    assert not any("-sb-fix-" in c["key"] for c in fake.calls)
+    rows = {r["sub_norm"]: r["status"] for r in await db.list_subblocks(TOPIC, "alpha")}
+    assert rows["sub a"] == "discarded" and rows["sub b"] == "consensus"
+
+
+async def test_verify_korrektur_ab_einer_stimme(env, monkeypatch):
+    """Ein Hinweis EINES Prüfers reicht: der Fix-Call läuft und ersetzt die Facts des
+    beanstandeten Subs; die Einstufung bleibt."""
+    db, ctx, files = env
+    subs = ["Sub A", "Sub B"]
+    await _seed_rows(db, "alpha", subs)
+    fix = {"subs": [_sub("Sub A", kp=["korrigierte Aussage"])]}
+    fake = _judge_slot({"1": {"facts_probleme": [{"nr": 1, "hinweis": "Zahl falsch"}]},
+                        "2": {"gruppen": []}}, fix=fix)
+    monkeypatch.setattr(bc, "run_single_slot", fake)
+    res = await bc._verify_block(ctx, files, "Alpha", _gen_von("Alpha", subs), {})
+    assert any("-sb-fix-" in c["key"] for c in fake.calls)
+    side = {s["title"]: s for s in res["sidecar"]["Alpha"]}
+    assert side["Sub A"]["facts"]["key_points"] == ["korrigierte Aussage"]
+    assert res["facts"]["Alpha"]["sub a"]["key_points"] == ["korrigierte Aussage"]
+    assert side["Sub B"]["facts"]["key_points"] == ["kp Sub B"]  # unbeanstandet
+
+
+async def test_verify_luecke_belegt_wird_neuer_sub(env, monkeypatch):
+    """Lücken-Schnitt beider Prüfer → Fix legt den belegten Fund als neuen consensus-Sub
+    an; ein unbelegter „Fund" verfällt am Beleg-Gate."""
+    db, ctx, files = env
+    subs = ["Sub A"]
+    await _seed_rows(db, "alpha", subs)
+    fix = {"subs": [_sub("Escaping von Sonderzeichen", level="expert", kp=["belegt"]),
+                    _sub("Unbelegte Behauptung", kp=[])]}
+    fake = _judge_slot({"1": {"luecken": ["Escaping fehlt"]},
+                        "2": {"luecken": ["Escaping unbehandelt"]}}, fix=fix)
+    monkeypatch.setattr(bc, "run_single_slot", fake)
+    res = await bc._verify_block(ctx, files, "Alpha", _gen_von("Alpha", subs), {})
+    assert res["raw"] == {"Alpha": ["Sub A", "Escaping von Sonderzeichen"]}
+    neu = next(s for s in res["sidecar"]["Alpha"] if s["title"] == "Escaping von Sonderzeichen")
+    assert neu["level"] == "expert" and neu["facts"]["key_points"] == ["belegt"]
+    rows = {r["sub_norm"]: r["status"] for r in await db.list_subblocks(TOPIC, "alpha")}
+    assert rows[_norm_title("Escaping von Sonderzeichen")] == "consensus"
+    assert _norm_title("Unbelegte Behauptung") not in rows
+
+
+async def test_verify_ersatzrichter_bei_ausfall(env, monkeypatch):
+    """Fällt EIN Prüfer aus, springt der Ersatz jE ein — Einstimmigkeit mit ihm faltet."""
+    db, ctx, files = env
+    subs = ["CSS Regel", "Echte Regel"]
+    await _seed_rows(db, "alpha", subs)
+    fake = _judge_slot({"1": {"fremd": [1]}, "E": {"fremd": [1]}})  # j2 → FAILED
+    monkeypatch.setattr(bc, "run_single_slot", fake)
+    res = await bc._verify_block(ctx, files, "Alpha", _gen_von("Alpha", subs), {})
+    assert res["raw"] == {"Alpha": ["Echte Regel"]}
+    assert [c["key"].rsplit("-j", 1)[-1] for c in fake.calls] == ["1", "2", "E"]
+
+
+async def test_verify_failopen_verwirft_nur_unsicher(env, monkeypatch):
+    """Nur 1 Prüfer (auch der Ersatz fällt aus) → fail-open: consensus bleibt unangetastet,
+    unsicher wird verworfen (ohne Panel keine Übernahme-Entscheidung)."""
+    db, ctx, files = env
+    subs = ["Sub A"]
+    unsicher = [_sub("Unsicher B")]
+    await _seed_rows(db, "alpha", subs)
+    await _seed_rows(db, "alpha", ["Unsicher B"], status="candidate")
+    fake = _judge_slot({"1": {"fremd": [1], "uebernehmen": {"2": "ja"}}})  # j2+jE → FAILED
+    monkeypatch.setattr(bc, "run_single_slot", fake)
+    res = await bc._verify_block(ctx, files, "Alpha", _gen_von("Alpha", subs, unsicher=unsicher), {})
+    assert res["raw"] == {"Alpha": ["Sub A"]}  # fremd-Einzelstimme wirkt NICHT
+    rows = {r["sub_norm"]: r["status"] for r in await db.list_subblocks(TOPIC, "alpha")}
+    assert rows["sub a"] == "consensus" and rows["unsicher b"] == "discarded"
+
+
+async def test_verify_level_korrektur_wiegt_doppelt(env, monkeypatch):
+    """Explizite Prüfer-Korrektur (×2) schlägt die Generator-Stimme; Patt fällt auf
+    advanced/relevant (heutige Defaults)."""
+    db, ctx, files = env
+    subs = ["Sub A", "Sub B"]
+    await _seed_rows(db, "alpha", subs)
+    votes = {"sub a": {"level": ["beginner"], "relevance": []},
+             "sub b": {"level": ["beginner", "expert"], "relevance": []}}
+    fake = _judge_slot({"1": {"levels": {"1": "expert"}}, "2": {"gruppen": []}})
+    monkeypatch.setattr(bc, "run_single_slot", fake)
+    res = await bc._verify_block(ctx, files, "Alpha", _gen_von("Alpha", subs, votes=votes), {})
+    side = {s["title"]: s for s in res["sidecar"]["Alpha"]}
+    assert side["Sub A"]["level"] == "expert"     # 2× Korrektur > 1× Generator
+    assert side["Sub B"]["level"] == "advanced"   # 1:1-Patt → Default
+    assert side["Sub A"]["relevance"] == "relevant"  # keine Stimme → Default
+
+
+async def test_verify_resume_ohne_neue_calls(env, monkeypatch):
+    """Vorhandene verify-j-Dateien → kein neuer Prüfer-Call."""
+    db, ctx, files = env
+    subs = ["Sub A"]
+    await _seed_rows(db, "alpha", subs)
+    fake = _judge_slot({"1": {"gruppen": []}, "2": {"gruppen": []}})
+    monkeypatch.setattr(bc, "run_single_slot", fake)
+    await bc._verify_block(ctx, files, "Alpha", _gen_von("Alpha", subs), {})
+    n = len(fake.calls)
+    await bc._verify_block(ctx, files, "Alpha", _gen_von("Alpha", subs), {})
+    assert len(fake.calls) == n
+
+
+# ── Artefakte ───────────────────────────────────────────────────────────────────────
+
+def _sidecar(titles):
+    return [{"title": t, "level": "beginner", "relevance": "relevant",
+             "facts": {"key_points": [f"kp {t}"]}} for t in titles]
+
+
+def _art_slot(gen_out, check_out):
+    """run_single_slot-Fake für Artefakte: gen_out je Teil (dict oder callable(prompt)),
+    check_out fürs Prüfer-Verdikt."""
+    calls = []
+
+    async def fake(ctx, label, *, key, prompt, role, capabilities, payload, timeout, on_line=None):
+        calls.append({"key": key, "prompt": prompt})
+        if "-art-gen-" in key:
+            out = gen_out(prompt) if callable(gen_out) else gen_out
+            return OK, payload((0, json.dumps(out), ""))
+        if "-art-check-" in key:
+            if check_out is None:
+                return FAILED, None
+            return OK, payload((0, json.dumps(check_out), ""))
+        raise AssertionError(f"unerwarteter Call {key}")
+
+    fake.calls = calls
+    return fake
+
+
+async def test_artefakte_ein_call_liefert_alles(env, monkeypatch):
+    """EIN Generator-Call liefert pattern+cards+examples, der Prüfer sagt ok →
+    Rohfassung wird übernommen, block-Feld auf den Karten-Block normiert."""
+    db, ctx, files = env
+    gen_out = {"pattern": [{"block": "Echo", "subblock": "Sub A", "question": "F?"}],
+               "cards": [{"block": "Echo", "subblock": "Sub A", "question": "F?", "answer": "A"}],
+               "examples": [{"block": "Echo", "subblock": "Sub A", "problem": "P",
+                             "steps": ["s1"], "result": "R"}]}
+    fake = _art_slot(gen_out, {"ok": True})
+    monkeypatch.setattr(bc, "run_single_slot", fake)
+    res = await bc._artefakte_block(ctx, files, "Alpha", _sidecar(["Sub A"]))
+    assert [c["key"] for c in fake.calls if "-art-gen-" in c["key"]].__len__() == 1
+    assert res["pattern"] == {"Alpha": [{"subblock": "Sub A", "question": "F?"}]}
+    assert res["artefacts"]["flashcard"] == [{"block": "Alpha", "subblock": "Sub A",
+                                              "question": "F?", "answer": "A"}]
+    assert res["artefacts"]["example"][0]["block"] == "Alpha"  # Agent-Echo „Echo" normiert
+
+
+async def test_artefakte_check_entfernt_beispiel_und_ergaenzt_frage(env, monkeypatch):
+    """examples_probleme wirft das beanstandete Beispiel; pattern_ergaenzt füllt die
+    fehlende Frage nach — der Prüfer-Prompt listet den fraglosen Sub."""
+    db, ctx, files = env
+    gen_out = {"pattern": [{"block": "Alpha", "subblock": "Sub A", "question": "F?"}],
+               "cards": [],
+               "examples": [{"block": "Alpha", "subblock": "Sub A", "problem": "P1", "steps": ["x"], "result": ""},
+                            {"block": "Alpha", "subblock": "Sub A", "problem": "P2", "steps": ["y"], "result": ""}]}
+    check = {"examples_probleme": [{"index": 1}],
+             "pattern_ergaenzt": [{"block": "Alpha", "subblock": "Sub B", "question": "F B?"}]}
+    fake = _art_slot(gen_out, check)
+    monkeypatch.setattr(bc, "run_single_slot", fake)
+    res = await bc._artefakte_block(ctx, files, "Alpha", _sidecar(["Sub A", "Sub B"]))
+    assert [e["problem"] for e in res["artefacts"]["example"]] == ["P2"]
+    assert res["pattern"]["Alpha"] == [{"subblock": "Sub A", "question": "F?"},
+                                       {"subblock": "Sub B", "question": "F B?"}]
+    check_prompt = next(c["prompt"] for c in fake.calls if "-art-check-" in c["key"])
+    assert "STILL MISSING A QUESTION" in check_prompt and "Sub B" in check_prompt
+
+
+async def test_artefakte_split_ab_schwelle(env, monkeypatch):
+    """> ART_SPLIT_SUBS Subs → ZWEI parallele Generator-Calls, jeder sieht nur seine
+    Hälfte; die Ergebnisse werden zusammengeführt."""
+    db, ctx, files = env
+    monkeypatch.setattr(bc, "ART_SPLIT_SUBS", 2)
+
+    def gen_out(prompt):
+        subs = [t for t in ("Sub A", "Sub B", "Sub C") if f"- {t}" in prompt]
+        return {"pattern": [{"block": "Alpha", "subblock": s, "question": f"F {s}?"} for s in subs],
+                "cards": [], "examples": []}
+
+    fake = _art_slot(gen_out, {"ok": True})
+    monkeypatch.setattr(bc, "run_single_slot", fake)
+    res = await bc._artefakte_block(ctx, files, "Alpha", _sidecar(["Sub A", "Sub B", "Sub C"]))
+    gen_keys = [c["key"] for c in fake.calls if "-art-gen-" in c["key"]]
+    assert len(gen_keys) == 2 and gen_keys[0].endswith("-t1") and gen_keys[1].endswith("-t2")
+    assert [p["subblock"] for p in res["pattern"]["Alpha"]] == ["Sub A", "Sub B", "Sub C"]
+
+
+async def test_artefakte_check_ausfall_uebernimmt_rohfassung(env, monkeypatch):
+    """Prüfer ohne Ergebnis → fail-open, die Generator-Rohfassung zählt."""
+    db, ctx, files = env
+    gen_out = {"pattern": [{"block": "Alpha", "subblock": "Sub A", "question": "F?"}],
+               "cards": [], "examples": []}
+    fake = _art_slot(gen_out, None)
+    monkeypatch.setattr(bc, "run_single_slot", fake)
+    res = await bc._artefakte_block(ctx, files, "Alpha", _sidecar(["Sub A"]))
+    assert res["pattern"] == {"Alpha": [{"subblock": "Sub A", "question": "F?"}]}
+
+
+async def test_artefakte_leerer_block(env):
+    db, ctx, files = env
+    res = await bc._artefakte_block(ctx, files, "Alpha", [])
+    assert res == {"pattern": {"Alpha": []}, "artefacts": {"flashcard": [], "example": []}}
+
+
+# ── Migration der alten Stage-Treppe ────────────────────────────────────────────────
+
+async def test_migriere_alt_karten(testdb):
+    """Karten in alten Stages gehen mit reduziertem Payload zurück nach generate
+    (alte Zwischenstände sind für die verschmolzenen Calls wertlos); Terminal- und
+    Neu-Struktur-Karten bleiben unangetastet."""
+    db = testdb
+    await db.kanban_upsert_card(TOPIC, "artefacts", "alpha", "ablock", "facts",
+                                {"title": "Alpha", "description": "d", "n_size": 3,
+                                 "sources": ["s1"], "raw": {"Alpha": ["alt"]},
+                                 "facts": {"Alpha": {}}})
+    await db.kanban_upsert_card(TOPIC, "artefacts", "beta", "ablock", "question_pattern",
+                                {"title": "Beta", "sidecar": {}})
+    await db.kanban_upsert_card(TOPIC, "artefacts", "gamma", "ablock", "done_artefact",
+                                {"title": "Gamma", "raw": {"Gamma": ["bleibt"]}})
+    await db.kanban_upsert_card(TOPIC, "artefacts", "delta", "ablock", "verify",
+                                {"title": "Delta", "raw": {"Delta": ["neu"]}})
+    n = await ba.migriere_alt_karten(TOPIC)
+    assert n == 2
+    alpha = await db.kanban_get_card(TOPIC, "artefacts", "alpha")
+    assert alpha["stage"] == "generate"
+    assert alpha["payload"] == {"title": "Alpha", "description": "d", "n_size": 3, "sources": ["s1"]}
+    assert (await db.kanban_get_card(TOPIC, "artefacts", "beta"))["stage"] == "generate"
+    gamma = await db.kanban_get_card(TOPIC, "artefacts", "gamma")
+    assert gamma["stage"] == "done_artefact" and gamma["payload"]["raw"] == {"Gamma": ["bleibt"]}
+    delta = await db.kanban_get_card(TOPIC, "artefacts", "delta")
+    assert delta["stage"] == "verify" and delta["payload"]["raw"] == {"Delta": ["neu"]}

backend/tests/test_e2e_fake.py

@@ -0,0 +1,198 @@
+"""E2E über die ECHTE Engine mit Fake-Agenten: kompletter Generierungspfad in Sekunden.
+
+Anders als test_board_inventory (dort sind die Block-Funktionen gefakt) läuft hier alles
+bis run_agent echt — _race, Quorum, Panels, Konsolidierung, Cross-Block, QA-Gate.
+"""
+
+import asyncio
+
+import pytest
+
+import board_inventory as bi
+from pipeline import GenContext
+from tests.invarianten import pruefe_invarianten, pruefe_guide_invarianten
+
+TOPIC = "t"
+
+
+def _files(tmp_path):
+    work = tmp_path / "arbeit"
+    work.mkdir(exist_ok=True)
+    return {"arbeit": work, "final": tmp_path / "blocks.md",
+            "sub_roh": tmp_path / "sub_roh.json", "sidecar": tmp_path / "subblocks.json",
+            "facts": tmp_path / "facts.json", "question_pattern": tmp_path / "question_pattern.json",
+            "artefakte": tmp_path / "artefakte.json", "outline": tmp_path / "outline.json",
+            "outline_slots": [tmp_path / f"outline-{i}.json" for i in (1, 2, 3)],
+            "research": [work / f"research-{i}.md" for i in (1, 2, 3, 4, 5)]}
+
+
+async def _lauf(tmp_path, research=True, qa_force=False, timeout=120):
+    ctx = GenContext(topic=TOPIC, provider="claude", is_cancelled=lambda: False)
+    files = _files(tmp_path)
+    ok = await asyncio.wait_for(
+        bi.run_boards(ctx, lambda *a, **k: None, files, {"type": "thema"}, None, "",
+                      research=research, qa_force=qa_force), timeout=timeout)
+    return ok, files
+
+
+async def test_e2e_thema_vollpfad(fake_welt, testdb, tmp_path):
+    """Research → Inventar → QA-Gate → Artefakte → Finalize, alle Schichten echt."""
+    ok, files = await _lauf(tmp_path)
+    assert ok
+    db = testdb
+    done = [c for c in await db.kanban_cards(TOPIC, board="inventory", stage="done_block")]
+    titel = {c["payload"]["title"] for c in done}
+    assert titel == {"Alpha-Konzept", "Beta-Verfahren", "Gamma-Anwendung"}
+    # Cross-Block-Dublette: „Gemeinsamer Grundbegriff" überlebt in genau EINEM Block
+    subs = [dict(r) for r in await db.list_subblocks(TOPIC)]
+    gemeinsam = [r for r in subs if r["sub_norm"] == "gemeinsamer grundbegriff"]
+    assert sorted(r["status"] for r in gemeinsam) == ["consensus", "variant"]
+    fehler = await pruefe_invarianten(TOPIC, files)
+    assert fehler == []
+
+
+async def test_e2e_guide(fake_welt, testdb, tmp_path):
+    """Auf den Vollpfad folgt der Guide-Bau — Gate/Coverage/Lese-Stages laufen echt."""
+    import guide_board
+    ok, files = await _lauf(tmp_path)
+    assert ok
+    db = testdb
+    done = await db.kanban_cards(TOPIC, board="inventory", stage="done_block")
+    entries = {i: f"{c['payload']['title']} — {c['payload'].get('description', '')}"
+               for i, c in enumerate(done, 1)}
+    chapters = await asyncio.wait_for(
+        guide_board.run_guide_board("g-e2e", TOPIC, "Guide", entries, "", "claude",
+                                    tmp_path / "guides" / "Guide.json"), timeout=120)
+    assert chapters is not None
+    assert await pruefe_guide_invarianten(TOPIC) == []
+
+
+async def test_e2e_rerun_idempotent(fake_welt, testdb, tmp_path):
+    """Zweiter Lauf (Continue, research=False) hinterlässt keine Waisen/Reste."""
+    ok, files = await _lauf(tmp_path)
+    assert ok
+    db = testdb
+    vorher = {(r["block_norm"], r["sub_norm"], r["status"])
+              for r in await db.list_subblocks(TOPIC)}
+    ok2, _f = await _lauf(tmp_path, research=False)
+    assert ok2
+    nachher = {(r["block_norm"], r["sub_norm"], r["status"])
+               for r in await db.list_subblocks(TOPIC)}
+    assert nachher == vorher
+    assert await pruefe_invarianten(TOPIC, files) == []
+
+
+@pytest.mark.parametrize("stoerung", [
+    {"muster": r"-sub-crossblock-.*-j1$", "modus": "fehler", "mal": 3},   # Ersatzrichter jE
+    {"muster": r"-sb-verify-.*-j1$", "modus": "garbage", "mal": 1},       # Ersatz-Richter jE
+    {"muster": r"-sb-gen-.*-g1$", "modus": "fehler", "mal": 1},           # degraded: 1 Generator
+    {"muster": r"-art-gen-.*-t1$", "modus": "fehler", "mal": 1},          # Slot-Restart
+    {"muster": r"-research-2$", "modus": "fehler", "mal": 3},             # 1 Producer tot
+])
+async def test_e2e_stoerungen_flow_endet(fake_welt, testdb, tmp_path, stoerung):
+    """Einzel-Ausfälle dürfen weder den Flow stoppen noch Invarianten reißen."""
+    fake_welt.stoerungen.append(dict(stoerung, rest=stoerung["mal"]))
+    ok, files = await _lauf(tmp_path)
+    assert ok
+    assert await pruefe_invarianten(TOPIC, files) == []
+
+
+async def test_e2e_crossblock_dissent_failopen(fake_welt, testdb, tmp_path):
+    """j1 sagt a, j2 sagt b, j3 fällt aus → Paar bleibt (fail-open), Rest konsistent."""
+    fake_welt.stoerungen += [
+        {"muster": r"-sub-crossblock-.*-j2$", "modus": "antwort",
+         "antwort": '{"pairs": {"1": "b"}}', "mal": 1, "rest": 1},
+        {"muster": r"-sub-crossblock-.*-j3$", "modus": "fehler", "mal": 3, "rest": 3},
+    ]
+    ok, files = await _lauf(tmp_path)
+    assert ok
+    db = testdb
+    subs = [dict(r) for r in await db.list_subblocks(TOPIC)]
+    gemeinsam = [r for r in subs if r["sub_norm"] == "gemeinsamer grundbegriff"]
+    assert sorted(r["status"] for r in gemeinsam) == ["consensus", "consensus"]  # kein Fold
+    assert await pruefe_invarianten(TOPIC, files) == []
+
+
+async def test_e2e_inblock_gruppe_faltet(fake_welt, testdb, tmp_path):
+    """Welt-Regel: „Alpha Eigenschaften" faltet unter „Definition Alpha" — beide Judges
+    liefern die Gruppe, der Verlierer wird variant, seine facts wandern zum Gewinner."""
+    fake_welt.gruppen.append(("Definition Alpha", ["Alpha Eigenschaften"]))
+    ok, files = await _lauf(tmp_path)
+    assert ok
+    db = testdb
+    rows = {r["sub_norm"]: r["status"] for r in await db.list_subblocks(TOPIC, "alpha-konzept")}
+    assert rows.get("alpha eigenschaften") == "variant"
+    assert rows.get("definition alpha") == "consensus"
+    assert await pruefe_invarianten(TOPIC, files) == []
+
+
+async def test_e2e_gate_vollinventur_ohne_fix(fake_welt, testdb, tmp_path):
+    """Gate-Judge liefert eine Voll-Inventur (belegte Claims mit „Belegt…"-Grund) —
+    der Schema-Filter wirft sie raus, es läuft KEIN Fakten-Fix."""
+    import json
+    antwort = json.dumps({"claims": [
+        {"text": "Aussage 1", "grund": "Belegt durch Quelle", "urteil": "unbelegt"},
+        {"text": "Aussage 2", "grund": "Belegt durch Fakten", "urteil": "unbelegt"},
+        {"text": "Aussage 3", "grund": "Belegt: steht im Skript", "urteil": "unbelegt"}]})
+    fake_welt.stoerungen.append({"muster": r"-gate-", "modus": "antwort",
+                                 "antwort": antwort, "mal": 99, "rest": 99})
+    import guide_board
+    ok, _files = await _lauf(tmp_path)
+    assert ok
+    db = testdb
+    done = await db.kanban_cards(TOPIC, board="inventory", stage="done_block")
+    entries = {i: c["payload"]["title"] for i, c in enumerate(done, 1)}
+    chapters = await asyncio.wait_for(
+        guide_board.run_guide_board("g-vi", TOPIC, "Guide", entries, "", "claude",
+                                    tmp_path / "guides" / "Guide.json"), timeout=120)
+    assert chapters is not None
+    assert not any("-gatefix-" in k for k in fake_welt.calls)
+
+
+async def test_e2e_echtheits_flattern_gestoppt(fake_welt, testdb, tmp_path):
+    """QA-Pass 1 flaggt alle Blöcke als unecht (Judge-Flattern) — der Bestätiger-Pass
+    widerspricht, die Gate-Note bleibt sauber, der Flow läuft durch."""
+    import json
+    fake_welt.stoerungen.append({"muster": r"^qa-t-bausteine-0$", "modus": "antwort",
+                                 "antwort": json.dumps({"relevant": {"1": "nein", "2": "nein", "3": "nein"}}),
+                                 "mal": 1, "rest": 1})
+    ok, files = await _lauf(tmp_path)
+    assert ok  # Gate hat nicht pausiert — der Zufalls-Verdacht wurde nicht bestätigt
+    assert any("bausteine-b2" in k for k in fake_welt.calls)
+    assert await pruefe_invarianten(TOPIC, files) == []
+
+
+async def test_e2e_uni_anker_gate(fake_welt, testdb, tmp_path, monkeypatch):
+    """uni-Modus mit Mini-Korpus: der Kanon-Titel ohne Korpus-Anker wird deterministisch
+    rejected (leeres Evidence-Pack), die belegten Blöcke laufen durch; QA misst gegen
+    den echten Korpus."""
+    import blocks as blx
+    fake_welt.bloecke["Kanon-Klassiker"] = {
+        "beschreibung": "Beruehmtes Lehrbuchproblem", "subs": ["Klassiker Detail"]}
+    korpus = tmp_path / "korpus"
+    korpus.mkdir()
+    zeilen = []
+    for t, b in fake_welt.bloecke.items():
+        if t == "Kanon-Klassiker":
+            continue  # kommt bewusst NICHT im Material vor
+        zeilen.append(f"Kapitel {t}: {b['beschreibung']}. " +
+                      " ".join(f"Wir behandeln {s}." for s in b["subs"]))
+    (korpus / "skript.txt").write_text("\n\n".join(zeilen), encoding="utf-8")
+    monkeypatch.setattr(bi, "source_folder", lambda t: korpus)
+    monkeypatch.setattr(blx, "source_folder", lambda t: korpus)
+
+    ctx = GenContext(topic=TOPIC, provider="claude", is_cancelled=lambda: False)
+    files = _files(tmp_path)
+    ok = await asyncio.wait_for(
+        bi.run_boards(ctx, lambda *a, **k: None, files, {"type": "uni", "location": str(korpus)},
+                      korpus, "", research=True, qa_force=True), timeout=120)
+    assert ok
+    db = testdb
+    alle = [dict(c) for c in await db.kanban_cards(TOPIC, board="inventory")]
+    assert any(c["stage"] == "rejected" and c["payload"].get("title") == "Kanon-Klassiker"
+               for c in alle)
+    assert not any(c["kind"] == "block" and c["payload"].get("title") == "Kanon-Klassiker"
+                   for c in alle)  # nie zum Block geworden
+    done = {c["payload"].get("title") for c in alle
+            if c["kind"] == "block" and c["stage"] == "done_block"}
+    assert {"Alpha-Konzept", "Beta-Verfahren", "Gamma-Anwendung"} <= done

backend/tests/test_events.py

@@ -0,0 +1,319 @@
+"""Event-Tracking (events-Tabelle) + Agenten-Labels."""
+
+import asyncio
+
+import agents
+from pipeline import GenContext
+
+TOPIC = "t"
+
+
+async def _events(db, kind=None):
+    conn = await db.get_db()
+    q = "SELECT topic, kind, key, label, status, dur_ms, wait_ms FROM events WHERE topic = ?"
+    args = [TOPIC]
+    if kind:
+        q += " AND kind = ?"
+        args.append(kind)
+    cur = await conn.execute(q, args)
+    return [dict(zip(("topic", "kind", "key", "label", "status", "dur_ms", "wait_ms"), r))
+            for r in await cur.fetchall()]
+
+
+async def test_advance_many_writes_stage_events(testdb):
+    db = testdb
+    await db.kanban_upsert_card(TOPIC, "inventory", "a", "block", "s1")
+    await db.kanban_upsert_card(TOPIC, "inventory", "b", "block", "s1")
+    await db.kanban_advance_many(TOPIC, "inventory", [("a", "s2"), ("b", "s2")])
+    evs = await _events(db, "stage")
+    assert {(e["key"], e["status"]) for e in evs} == {("inventory:a", "s2"), ("inventory:b", "s2")}
+
+
+async def test_fail_card_events_retry_then_dead(testdb):
+    db = testdb
+    await db.kanban_upsert_card(TOPIC, "inventory", "a", "block", "s1")
+    assert await db.kanban_fail_card(TOPIC, "inventory", "a", "boom", max_retries=2) is False
+    assert await db.kanban_fail_card(TOPIC, "inventory", "a", "boom", max_retries=2) is True
+    evs = await _events(db, "fail")
+    assert [e["status"] for e in evs] == ["retry1", "dead"]
+
+
+async def test_guide_stage_event(testdb):
+    db = testdb
+    await db.upsert_guide_card(TOPIC, "Guide", "alpha", "Alpha")
+    await db.set_guide_card(TOPIC, "Guide", "alpha", stage="writer")
+    evs = await _events(db, "stage")
+    assert evs and evs[-1]["key"] == "guide:Guide:alpha" and evs[-1]["status"] == "writer"
+
+
+async def test_run_agent_emits_event_and_survives_broken_sink(testdb, monkeypatch):
+    recorded = []
+
+    async def sink(**kw):
+        recorded.append(kw)
+
+    async def fake_cli(agent_key, prompt, timeout, model, capabilities, label=""):
+        return 0, "out", ""
+
+    monkeypatch.setattr(agents, "on_event", sink)
+    monkeypatch.setattr(agents, "_run_claude_cli", fake_cli)
+    monkeypatch.setattr(agents.shutil, "which", lambda c: "/bin/true")
+    monkeypatch.setattr(agents, "resolve_role", lambda p, r: ("claude", "test-model"))
+    rc, out, err = await agents.run_agent("blocks-t-x", "p", 5, provider="claude",
+                                          role="judge", scope=TOPIC, label="Alpha · Judge")
+    assert rc == 0
+    assert recorded and recorded[0]["kind"] == "agent"
+    assert recorded[0]["label"] == "Alpha · Judge" and recorded[0]["status"] == "ok"
+    assert isinstance(recorded[0]["wait_ms"], int) and isinstance(recorded[0]["dur_ms"], int)
+
+    # broken sink never breaks the call; interactive/scope-less calls don't log
+    async def broken(**kw):
+        raise RuntimeError("sink down")
+    monkeypatch.setattr(agents, "on_event", broken)
+    rc, _, _ = await agents.run_agent("blocks-t-y", "p", 5, provider="claude", scope=TOPIC)
+    assert rc == 0
+    monkeypatch.setattr(agents, "on_event", sink)
+    recorded.clear()
+    await agents.run_agent("chat-1", "p", 5, provider="claude", lane="interactive")
+    assert recorded == []
+
+
+async def test_active_agents_carry_labels():
+    async def run(key, label):
+        return await agents._communicate(key, ["sleep", "0.4"], None, 5, label=label)
+
+    t1 = asyncio.create_task(run("blocks-t-x", "Alpha · Facts 1"))
+    t2 = asyncio.create_task(run("blocks-t-x", "Alpha · Facts 2"))  # key collision → ~2
+    await asyncio.sleep(0.15)
+    agents_now = agents.active_agents("blocks-t-")
+    assert sorted(a["label"] for a in agents_now) == ["Alpha · Facts 1", "Alpha · Facts 2"]
+    assert {a["key"] for a in agents_now} == {"blocks-t-x", "blocks-t-x~2"}
+    await asyncio.gather(t1, t2)
+    assert agents.active_agents("blocks-t-") == []
+
+async def test_pull_prefers_bigger_blocks(testdb):
+    """LPT: Karten mit größerem subs_n werden zuerst gezogen; ohne Feld bleibt FIFO."""
+    db = testdb
+    await db.kanban_upsert_card(TOPIC, "artefacts", "klein", "ablock", "facts", {"subs_n": 5})
+    await db.kanban_upsert_card(TOPIC, "artefacts", "gross", "ablock", "facts", {"subs_n": 40})
+    await db.kanban_upsert_card(TOPIC, "artefacts", "mittel", "ablock", "facts", {"subs_n": 15})
+    pulled = await db.kanban_pull(TOPIC, "artefacts", "facts", 10)
+    assert [c["card_id"] for c in pulled] == ["gross", "mittel", "klein"]
+    # ohne subs_n: FIFO nach updated_at
+    await db.kanban_upsert_card(TOPIC, "inventory", "a", "block", "s1")
+    await db.kanban_upsert_card(TOPIC, "inventory", "b", "block", "s1")
+    pulled = await db.kanban_pull(TOPIC, "inventory", "s1", 10)
+    assert [c["card_id"] for c in pulled] == ["a", "b"]
+    # n_size (Board 1) ist der Fallback-Schätzer; subs_n behält Vorrang
+    await db.kanban_upsert_card(TOPIC, "inventory", "n-klein", "block", "s2", {"n_size": 2})
+    await db.kanban_upsert_card(TOPIC, "inventory", "n-gross", "block", "s2", {"n_size": 9})
+    await db.kanban_upsert_card(TOPIC, "inventory", "n-ohne", "block", "s2")
+    await db.kanban_upsert_card(TOPIC, "inventory", "n-subs", "block", "s2", {"subs_n": 3, "n_size": 1})
+    pulled = await db.kanban_pull(TOPIC, "inventory", "s2", 10)
+    assert [c["card_id"] for c in pulled] == ["n-gross", "n-subs", "n-klein", "n-ohne"]
+
+
+async def test_learnstate_smoke(testdb):
+    """Regression: P5-Ausbau hatte die _LEVEL_CASE-Konstante mitgerissen —
+    load_learnstate (Guide-Start-Pfad) muss ohne NameError laufen."""
+    from rules import load_learnstate
+    guides, levels = await load_learnstate()
+    assert isinstance(levels, dict)
+
+
+async def test_guide_error_event(testdb):
+    db = testdb
+    await db.upsert_guide_card(TOPIC, "Guide", "alpha", "Alpha")
+    await db.set_guide_card(TOPIC, "Guide", "alpha", status="error", gate_info="Writer ohne Ergebnis")
+    evs = await _events(db, "fail")
+    assert evs and evs[-1]["key"] == "guide:Guide:alpha" and "Writer" in evs[-1]["status"]
+
+
+def test_timeout_calibration_smoke():
+    from pipeline import _timeout
+    assert _timeout("subblock", 10) == 400 + 150
+    assert _timeout("content", 10) == 450 + 300
+
+
+def test_env_file_wins(tmp_path, monkeypatch):
+    """Regression: geerbte (veraltete) Env-Werte dürfen die .env nicht mehr überstimmen."""
+    import config
+    monkeypatch.setenv("X_CREATOR_TESTKEY", "alt")
+    p = tmp_path / ".env"
+    p.write_text("X_CREATOR_TESTKEY=neu\n", encoding="utf-8")
+    config._load_env(p)
+    import os
+    assert os.environ["X_CREATOR_TESTKEY"] == "neu"
+
+
+async def test_restart_artefact_card_wipes_only_that_block(testdb):
+    import board_inventory as bi
+    db = testdb
+    for norm in ("alpha", "beta"):
+        await db.kanban_upsert_card(TOPIC, "artefacts", norm, "ablock", "done_artefact",
+                                    {"title": norm.title(), "raw": {norm: ["S"]}, "facts": {}})
+        await db.upsert_subblock(TOPIC, norm, "s1", norm.title(), "Sub Eins")
+        await db.upsert_question_pattern(TOPIC, norm, "s1", norm.title(), "Sub Eins", "Frage?")
+        await db.put_sub_artifact(TOPIC, norm, "s1", "flashcard", norm.title(), "Sub Eins", "{}")
+    assert await bi.restart_artefact_card(TOPIC, "alpha") is True
+    assert (await db.kanban_get_card(TOPIC, "artefacts", "alpha"))["stage"] == "generate"
+    assert await db.list_subblocks(TOPIC, "alpha") == []
+    assert len(await db.list_subblocks(TOPIC, "beta")) == 1  # untouched
+    assert await bi.restart_artefact_card(TOPIC, "gibtsnicht") is False
+
+
+async def test_guide_reset_card_single(testdb):
+    import guide_board as gb
+    db = testdb
+    for n in ("alpha", "beta"):
+        await db.upsert_guide_card(TOPIC, "Guide", n, n.title())
+        await db.set_guide_card(TOPIC, "Guide", n, stage="done", status="ok",
+                                writer_rounds=2, md="# SECTION Text", gate_info="x")
+        await db.put_lernziel(TOPIC, n, "z1", "Ziel eins")
+    assert await gb.reset_card(TOPIC, "Guide", "alpha", 0) is True
+    cards = {c["block_norm"]: c for c in await db.list_guide_cards(TOPIC, "Guide")}
+    assert cards["alpha"]["stage"] == "lernziele" and cards["alpha"]["md"] == "" and cards["alpha"]["writer_rounds"] == 0
+    assert cards["beta"]["stage"] == "done" and cards["beta"]["md"]  # untouched
+    assert await db.list_lernziele(TOPIC) and all(z["block_norm"] != "alpha" for z in await db.list_lernziele(TOPIC))
+    # ab_stage 3 (pruefer) behält md
+    assert await gb.reset_card(TOPIC, "Guide", "beta", 3) is True
+    cards = {c["block_norm"]: c for c in await db.list_guide_cards(TOPIC, "Guide")}
+    assert cards["beta"]["stage"] == "pruefer" and cards["beta"]["md"]
+
+
+async def test_completeness_route(testdb, tmp_path, monkeypatch):
+    import routes, paths
+    db = testdb
+    monkeypatch.setattr(paths, "arbeit_dir", lambda t: tmp_path)
+    await db.upsert_block(TOPIC, "alpha", "Alpha", "d", "[]")
+    await db.set_block_status(TOPIC, "alpha", "consensus")
+    await db.upsert_subblock(TOPIC, "alpha", "s1", "Alpha", "Sub Eins")
+    await db.set_subblock_fields(TOPIC, "alpha", "s1", status="consensus")
+    await db.upsert_question_pattern(TOPIC, "alpha", "s1", "Alpha", "Sub Eins", "Frage?")
+    await db.put_sub_artifact(TOPIC, "alpha", "s1", "flashcard", "Alpha", "Sub Eins", "{}")
+    await db.put_lernziel(TOPIC, "alpha", "z1", "Ziel")
+    await db.set_ziel_covered(TOPIC, "alpha", "z1", True)
+    (tmp_path / "inventar-filter-x.json").write_text(
+        '{"degradiert": 3, "ueberstimmt": ["A"], "floor_veto": []}', encoding="utf-8")
+    res = await routes.blocks_completeness(TOPIC)
+    assert res["bloecke"] == 1 and res["subs"] == 1
+    assert res["frage_bloecke"] == 1 and res["lernkarten"] == 1
+    assert res["ziele_total"] == 1 and res["ziele_covered"] == 1
+    assert res["degradiert_geprueft"] == 3 and res["panel_gerettet"] == 1
+    assert res["dead"] == 0
+
+
+async def test_blocks_ready_from_db(testdb, monkeypatch):
+    """Regression: gesynctes Topic ohne blocks.md muss trotzdem ready sein (DB zählt)."""
+    import blocks as blx
+    db = testdb
+    await db.kanban_upsert_card(TOPIC, "inventory", "b-1", "block", "done_block", {"title": "Alpha"})
+    st = await blx.blocks_status(TOPIC)
+    assert st["ready"] is True and st["partial"] is False
+
+
+async def test_remove_guide_format_clears_everything(testdb, monkeypatch):
+    """Board-Remove räumt ALLE Läufe eines Formats + Karten (8 error-Zeilen stapelten sich)."""
+    import routes
+    from models import GuideFormatRequest
+    db = testdb
+    for i in range(3):
+        await db.create_guide({"id": f"g{i}", "topic": TOPIC, "format": "Guide",
+                               "instructions": "", "status": "error", "progress": None,
+                               "created_at": "2026-01-01", "updated_at": "2026-01-01"})
+    await db.upsert_guide_card(TOPIC, "Guide", "alpha", "Alpha")
+    res = await routes.remove_guide_format(GuideFormatRequest(topic=TOPIC, format="Guide"))
+    assert res["removed"] == 3
+    assert await db.list_guides() == [] or all(g["topic"] != TOPIC for g in await db.list_guides())
+    assert await db.list_guide_cards(TOPIC, "Guide") == []
+
+
+# ── Token-Logging pro Agent (OpenCode-Session → Event-Meta) ──────────────────────────
+
+def test_session_tokens_reads_newest(tmp_path, monkeypatch):
+    """--title = Agent-Key: neueste Session gewinnt (Retry); fehlende DB/Zeile → None."""
+    import sqlite3
+    dbf = tmp_path / "oc.db"
+    con = sqlite3.connect(dbf)
+    con.execute("CREATE TABLE session (title TEXT, time_created INT, tokens_input INT,"
+                " tokens_output INT, tokens_reasoning INT, tokens_cache_read INT, tokens_cache_write INT)")
+    con.execute("INSERT INTO session VALUES ('k', 1, 1, 1, 0, 10, 0)")
+    con.execute("INSERT INTO session VALUES ('k', 2, 7, 3, 0, 99, 5)")
+    con.commit()
+    con.close()
+    monkeypatch.setattr(agents, "_OPENCODE_DB", dbf)
+    assert agents._session_tokens("k") == {"input": 7, "output": 3, "reasoning": 0,
+                                           "cache_read": 99, "cache_write": 5}
+    assert agents._session_tokens("fehlt") is None
+    monkeypatch.setattr(agents, "_OPENCODE_DB", tmp_path / "nope.db")
+    assert agents._session_tokens("k") is None
+
+
+async def test_opencode_cmd_sets_title(monkeypatch):
+    """Der Agent-Key wird Session-Titel — der Join-Schlüssel fürs Token-Logging."""
+    seen = {}
+
+    async def fake_comm(agent_key, cmd, stdin, timeout, stagger=False, on_line=None, label="", env=None):
+        seen["cmd"] = cmd
+        return 0, "", ""
+
+    monkeypatch.setattr(agents, "_communicate", fake_comm)
+    await agents._run_opencode("blocks-t-z", "p", 5, "minimax", "m", "none")
+    i = seen["cmd"].index("--title")
+    assert seen["cmd"][i + 1] == "blocks-t-z"
+
+
+async def test_run_agent_logs_opencode_tokens(testdb, monkeypatch):
+    """OpenCode-Lauf: Token-Zähler der Session landen im Event-Meta."""
+    recorded = []
+
+    async def sink(**kw):
+        recorded.append(kw)
+
+    async def fake_oc(agent_key, prompt, timeout, provider, model, capabilities, on_line=None, label=""):
+        return 0, "out", ""
+
+    monkeypatch.setattr(agents, "on_event", sink)
+    monkeypatch.setattr(agents, "_run_opencode", fake_oc)
+    monkeypatch.setattr(agents.shutil, "which", lambda c: "/bin/true")
+    monkeypatch.setattr(agents, "resolve_role", lambda p, r: ("minimax", "test-model"))
+    monkeypatch.setattr(agents, "_session_tokens",
+                        lambda k: {"input": 5, "output": 2, "reasoning": 0,
+                                   "cache_read": 100, "cache_write": 0})
+    rc, *_ = await agents.run_agent("blocks-t-tok", "p", 5, provider="minimax", scope=TOPIC)
+    assert rc == 0
+    assert recorded and recorded[0]["meta"]["tokens"]["cache_read"] == 100
+
+
+# ── run_id-Registry + Lauf-Summary ───────────────────────────────────────────────────
+
+async def test_run_id_stamped_on_events(testdb):
+    """Registry gesetzt → Agent- und Stage-Events tragen die run_id; geleert → leer."""
+    db = testdb
+    db.set_current_run(TOPIC, "20260703-1200-abcd")
+    await db.add_event(TOPIC, "agent", key="k1", status="ok",
+                       meta={"tokens": {"input": 10, "output": 2, "cache_read": 50, "cache_write": 1}})
+    await db.kanban_upsert_card(TOPIC, "inventory", "c1", "block", "ingest", {})
+    await db.kanban_advance(TOPIC, "inventory", "c1", "cluster")
+    db.set_current_run(TOPIC, None)
+    await db.add_event(TOPIC, "agent", key="k2", status="ok")
+    conn = await db.get_db()
+    rows = await (await conn.execute("SELECT key, run_id FROM events WHERE topic=? ORDER BY id", (TOPIC,))).fetchall()
+    by_key = {k: r for k, r in rows}
+    assert by_key["k1"] == "20260703-1200-abcd"
+    assert by_key["inventory:c1"] == "20260703-1200-abcd"
+    assert by_key["k2"] == ""
+
+
+async def test_events_run_summary_aggregates(testdb):
+    db = testdb
+    db.set_current_run(TOPIC, "r1")
+    await db.add_event(TOPIC, "agent", key="a", status="ok", dur_ms=1000,
+                       meta={"tokens": {"input": 10, "output": 2, "cache_read": 50, "cache_write": 1}})
+    await db.add_event(TOPIC, "agent", key="b", status="timeout", dur_ms=120000,
+                       meta={"tokens": {"input": 5, "output": 0, "cache_read": 30, "cache_write": 0}})
+    db.set_current_run(TOPIC, None)
+    s = await db.events_run_summary(TOPIC, "r1")
+    assert s["agents"]["gesamt"] == 2 and s["agents"]["ok"] == 1 and s["agents"]["timeout"] == 1
+    assert s["agents"]["verlorene_min"] == 2
+    assert s["tokens"] == {"input": 15, "output": 2, "cache_read": 80, "cache_write": 1}

backend/tests/test_guide_board.py

@@ -0,0 +1,446 @@
+"""Guide board: schema parsers + card reset semantics (no LLM)."""
+
+import guide_board as gb
+
+TOPIC, FMT = "t", "Guide"
+
+
+def test_ziele_schema():
+    ok = gb._ziele_schema({"ziele": [{"id": "z1", "text": "Erklären, warum X", "sub": "S"},
+                                     {"id": "z2", "text": "Nennen von Y"}]})
+    assert [z["id"] for z in ok] == ["z1", "z2"]
+    assert gb._ziele_schema({"ziele": []}) is None
+    assert gb._ziele_schema({"ziele": [{"id": "z1", "text": "a"}, {"id": "z1", "text": "b"}]}) \
+        == [{"id": "z1", "text": "a", "sub": ""}]  # duplicate ids fold
+    assert gb._ziele_schema("quatsch") is None
+
+
+def test_gate_schema():
+    assert gb._gate_schema({"ok": True}) == []
+    claims = gb._gate_schema({"claims": [{"text": "Falsch", "grund": "fehlt"}]})
+    assert claims == [{"text": "Falsch", "grund": "fehlt", "urteil": "unbelegt"}]
+    assert gb._gate_schema({}) is None
+    # urteil "falsch" wird durchgereicht, alles andere defaultet auf unbelegt
+    claims = gb._gate_schema({"claims": [{"text": "A", "grund": "widerspricht", "urteil": "FALSCH"},
+                                         {"text": "B", "grund": "x", "urteil": "quatsch"}]})
+    assert [c["urteil"] for c in claims] == ["falsch", "unbelegt"]
+    # Voll-Inventur-Rauschen: als belegt begründete Einträge fliegen raus
+    claims = gb._gate_schema({"claims": [{"text": "A", "grund": "Belegt durch Quelle X"},
+                                         {"text": "B", "grund": "nicht ableitbar"}]})
+    assert [c["text"] for c in claims] == ["B"]
+
+
+def test_pruefer_schema():
+    """Verschmolzenes Verdikt: ok-Kurzform, Claims-Normalisierung, Ziel-Vollständigkeit."""
+    assert gb._pruefer_schema({"ok": True}, {"z1"}) == {
+        "claims": [], "ziele": {}, "luecken": [], "ballast": [], "lese_probleme": []}
+    res = gb._pruefer_schema({"claims": [{"text": "A", "grund": "x", "urteil": "FALSCH"}],
+                              "ziele": {"z1": True, "z2": "false"},
+                              "luecken": [{"ziel": "z2", "fehlt": "Beweis"}],
+                              "ballast": ["Abschweifung"],
+                              "lese_probleme": [{"problem": "zu lang"}]}, {"z1", "z2"})
+    assert res["claims"] == [{"text": "A", "grund": "x", "urteil": "falsch"}]
+    assert res["ziele"] == {"z1": True, "z2": False}
+    assert res["luecken"][0]["fehlt"] == "Beweis" and res["lese_probleme"] == ["zu lang"]
+    assert gb._pruefer_schema({"ziele": {"z1": True}}, {"z1", "z2"}) is None  # z2 fehlt
+    assert gb._pruefer_schema({"lese_probleme": []}, set()) is not None  # leeres Verdikt ok
+    assert gb._pruefer_schema("quatsch", set()) is None
+
+
+def test_auftraege_schwelle_und_kritisch():
+    """1–2 nur-unbelegt-Claims verfallen (GATE_FIX_MIN); falsch/Lücken sind kritisch."""
+    leer = {"claims": [], "ziele": {}, "luecken": [], "ballast": [], "lese_probleme": []}
+    z, k = gb._auftraege({**leer, "claims": [{"text": "c", "grund": "", "urteil": "unbelegt"}] * 2}, [])
+    assert z == [] and k is False
+    z, k = gb._auftraege({**leer, "claims": [{"text": "c", "grund": "w", "urteil": "falsch"}]}, [])
+    assert len(z) == 1 and k is True
+    z, k = gb._auftraege({**leer, "luecken": [{"ziel": "z1", "fehlt": "X"}]}, ["Länge 2000"])
+    assert len(z) == 2 and k is True
+
+
+async def test_reset_from_stage(testdb):
+    db = testdb
+    await db.upsert_guide_card(TOPIC, FMT, "a", "A")
+    await db.upsert_guide_card(TOPIC, FMT, "b", "B")
+    await db.set_guide_card(TOPIC, FMT, "a", stage="done", md="text", writer_rounds=2)
+    await db.set_guide_card(TOPIC, FMT, "b", stage="pruefer", md="text")
+    await db.put_lernziel(TOPIC, "a", "z1", "Ziel")
+    # reset ab writer (idx 2): beide Karten zurück, md geleert, Ziele bleiben
+    moved = await gb.reset_from_stage(TOPIC, FMT, 2)
+    assert moved == 2
+    cards = {c["block_norm"]: c for c in await db.list_guide_cards(TOPIC, FMT)}
+    assert cards["a"]["stage"] == "writer" and cards["a"]["md"] == "" and cards["a"]["writer_rounds"] == 0
+    assert cards["b"]["stage"] == "writer"
+    assert await db.list_lernziele(TOPIC, "a")
+    # reset ab lernziele (idx 0): Ziele weg
+    await gb.reset_from_stage(TOPIC, FMT, 0)
+    assert not await db.list_lernziele(TOPIC, "a")
+    assert (await db.list_guide_cards(TOPIC, FMT))[0]["stage"] == "lernziele"
+
+
+async def test_done_step(testdb):
+    db = testdb
+    assert await gb.done_step(TOPIC, FMT) == -1
+    await db.upsert_guide_card(TOPIC, FMT, "a", "A")
+    assert await gb.done_step(TOPIC, FMT) == -1     # alles in lernziele
+    await db.set_guide_card(TOPIC, FMT, "a", stage="pruefer")
+    assert await gb.done_step(TOPIC, FMT) == 2      # bis writer fertig
+    await db.set_guide_card(TOPIC, FMT, "a", stage="done")
+    assert await gb.done_step(TOPIC, FMT) == len(gb.GUIDE_STAGES)
+
+
+async def test_run_card_sets_and_clears_live_info(testdb, monkeypatch):
+    """Regression: _live nutzte env.format_name (existiert nicht) → AttributeError beim
+    ersten Stage-Start. Treibt eine Karte durch _run_card mit Fake-Stage."""
+    import asyncio
+    from types import SimpleNamespace
+    import guide_board as gb
+    db = testdb
+    await db.upsert_guide_card("t", "Guide", "alpha", "Alpha")
+    env = SimpleNamespace(ctx=None, guide_id="g-live", topic="t", format="Guide")
+    card = {"block_norm": "alpha", "block": "Alpha", "stage": "lernziele", "status": "open"}
+    seen = {}
+
+    async def fake_stage(env2, card2):
+        seen.update(dict(gb._live_info))
+        card2["stage"] = "done"
+        return True
+
+    monkeypatch.setattr(gb, "_STAGE_FN", {"lernziele": fake_stage})
+    await gb._run_card(env, card, asyncio.Semaphore(1))
+    assert card["stage"] == "done"
+    assert ("t", "Guide", "alpha") in seen          # live info stand während der Stage
+    assert ("t", "Guide", "alpha") not in gb._live_info  # und wurde aufgeräumt
+
+
+def test_merge_split_sections_one_section_all_markers():
+    import guide_board as gb
+    from textkit import _parse_fragment
+    a = _parse_fragment("""<!-- section: Front Matter -->
+<!-- compact -->
+Kurzer Einstieg kompakt.
+<!-- sub: beginner | YAML-Basics -->
+YAML kompakt.
+<!-- ausführlich -->
+Einstieg ausführlich.
+<!-- sub: beginner | YAML-Basics -->
+YAML ausführlich.""")[0]
+    b = _parse_fragment("""<!-- section: Front Matter (Teil 2) -->
+<!-- compact -->
+<!-- sub: advanced | TOML-Sektionen -->
+TOML kompakt.
+<!-- ausführlich -->
+Unerwünschter zweiter Einstieg.
+<!-- sub: advanced | TOML-Sektionen -->
+TOML ausführlich.""")[0]
+    merged = gb._merge_split_sections(a, b)
+    secs = _parse_fragment(merged)
+    assert len(secs) == 1
+    sec = secs[0]
+    assert sec["title"] == "Front Matter"
+    assert [s["title"] for s in sec["subs"]] == ["YAML-Basics", "TOML-Sektionen"]
+    assert sec["anchor"] == "Einstieg ausführlich."  # Teil-B-Einstieg verworfen
+    assert "TOML ausführlich." in sec["md"] and "YAML kompakt." in sec["compact"]
+
+
+async def test_card_examples_filters_and_formats(testdb):
+    """_card_examples: Norm-Matching auf die übergebenen Subs; unmatchte Beispiele nur
+    beim Voll-Writer/Teil 1 (include_unmatched) — nie stillschweigend weg."""
+    import json as _json
+    import guide_board as gb
+    from types import SimpleNamespace
+    db = testdb
+    await db.put_sub_artifact("t", "gross", "sub eins", "example",
+                              _json.dumps({"problem": "P1", "steps": ["a", "b"], "result": "R1"}),
+                              "Gross", "Sub Eins")
+    await db.put_sub_artifact("t", "gross", "verwaist", "example",
+                              _json.dumps({"problem": "P2", "steps": ["x"], "result": "R2"}),
+                              "Gross", "Verwaister Sub")
+    env = SimpleNamespace(topic="t")
+    subs = [{"title": "Sub Eins", "level": "beginner"}]
+    full = await gb._card_examples(env, "gross", subs)
+    assert "Sub Eins" in full and "P1" in full and "1) a 2) b" in full and "R1" in full
+    assert "Subbaustein unklar" in full and "P2" in full  # orphan attached with hint
+    half = await gb._card_examples(env, "gross", subs, include_unmatched=False)
+    assert "P1" in half and "P2" not in half  # split half: only its own subs
+    assert await gb._card_examples(env, "leer", subs) == ""
+
+
+def test_writer_template_has_examples_placeholder():
+    """Smoke: alle Platzhalter versorgt — ein fehlender Kwarg stürbe als KeyError."""
+    from pipeline import _prompt
+    text = _prompt("Guide-Writer-Board", topic="t", format_name="Guide", chapter="K1",
+                   assignment="- B", ziele="- z", facts="F", examples="", gaps="",
+                   budget=2000, spec="", out_path="/tmp/x.md", extra="")
+    assert "VERIFIED FACTS" in text and "2000 characters" in text
+
+
+async def test_pruefer_counts_examples_as_facts(testdb, monkeypatch, tmp_path):
+    """Prüfer-Prompt enthält die Beispiele als verifizierte Fakten — sonst fliegen
+    gerechnete Beispielwerte als „nicht belegt" raus."""
+    import json as _json
+    import guide_board as gb
+    from types import SimpleNamespace
+    db = testdb
+    await db.upsert_guide_card("t", "Guide", "gross", "Gross")
+    await db.put_sub_artifact("t", "gross", "sub eins", "example",
+                              _json.dumps({"problem": "P1", "steps": ["a"], "result": "R1"}),
+                              "Gross", "Sub Eins")
+    captured = {}
+
+    async def fake_slot(ctx, label, *, key, prompt, role, capabilities, payload, timeout, on_line=None):
+        captured["prompt"] = prompt
+        return "ok", payload((0, '{"ok": true}', ""))
+
+    monkeypatch.setattr(gb, "run_single_slot", fake_slot)
+    monkeypatch.setattr(gb, "_card_facts", lambda e, b: "FAKT X")
+    monkeypatch.setattr(gb, "READABILITY_ACTIVE", False)
+    env = SimpleNamespace(ctx=SimpleNamespace(topic="t", provider="p", is_cancelled=lambda: False),
+                          guide_id="g", topic="t", format="Guide", instructions="",
+                          subs_by_title={"Gross": [{"title": "Sub Eins", "level": "beginner"}]},
+                          spec="", slot=lambda name: tmp_path / name)
+    md = ("<!-- section: Gross -->\n<!-- ausführlich -->\n" + "Text im Rahmen. " * 20)
+    card = {"block_norm": "gross", "block": "Gross", "stage": "pruefer", "status": "open",
+            "writer_rounds": 0, "gate_info": "", "md": md}
+    ok = await gb._stage_pruefer(env, card)
+    assert ok is True
+    assert "VERIFIED WORKED EXAMPLES" in captured["prompt"] and "P1" in captured["prompt"]
+
+
+async def test_writer_splits_oversized_first_draft(testdb, monkeypatch, tmp_path):
+    import guide_board as gb
+    from types import SimpleNamespace
+    db = testdb
+    await db.upsert_guide_card("t", "Guide", "gross", "Gross")
+    calls = []
+
+    async def fake_slot(ctx, label, *, key, prompt, role, capabilities, payload, timeout, on_line=None):
+        calls.append(label)
+        part = "2" if key.endswith("-b") else "1"
+        p = tmp_path / f"out-{key[-1]}.md"
+        p.write_text(f"<!-- section: Gross -->\n<!-- ausführlich -->\n"
+                     + ("Einstieg.\n" if part == "1" else "")
+                     + f"<!-- sub: beginner | Sub {part} -->\nText {part}.", encoding="utf-8")
+        # payload liest die ECHTE Slot-Datei — wir schreiben direkt an deren Pfad
+        import re as _re
+        m = _re.search(r"(/\S+\.md)", prompt)
+        with open(m.group(1), "w", encoding="utf-8") as f:
+            f.write(p.read_text(encoding="utf-8"))
+        return "ok", payload(None)
+
+    monkeypatch.setattr(gb, "run_single_slot", fake_slot)
+    subs = [{"title": f"Sub {i}", "level": "beginner", "relevance": "relevant"} for i in range(31)]
+    env = SimpleNamespace(ctx=SimpleNamespace(topic="t", provider="p", is_cancelled=lambda: False),
+                          guide_id="g", topic="t", format="Guide", instructions="",
+                          subs_by_title={"Gross": subs}, spec="",
+                          slot=lambda name: tmp_path / name)
+    monkeypatch.setattr(gb, "_card_facts", lambda e, b: "")
+    card = {"block_norm": "gross", "block": "Gross", "stage": "writer", "status": "open",
+            "writer_rounds": 0, "gate_info": "", "md": "", "chapter": "K1"}
+    ok = await gb._stage_writer(env, card)
+    assert ok is True
+    assert [c for c in calls if "(1/2)" in c] and [c for c in calls if "(2/2)" in c]
+    from textkit import _parse_fragment
+    secs = _parse_fragment(card["md"])
+    assert len(secs) == 1 and [s["title"] for s in secs[0]["subs"]] == ["Sub 1", "Sub 2"]
+    assert card["stage"] == "pruefer"
+
+
+async def test_lernziele_retry_bei_leerer_liste(testdb, tmp_path, monkeypatch):
+    """Leere Ziele-Liste → genau EIN Ersatz-Versuch (Key-Suffix -2); dessen Ziele landen in der DB."""
+    db = testdb
+    await db.upsert_guide_card(TOPIC, FMT, "alpha", "Alpha")
+    env = gb._Env(None, "g-r", TOPIC, FMT, "", tmp_path / "Guide.json",
+                  {"Alpha": [{"title": "S1", "level": "beginner"}]}, {}, "(quelle)", "spec")
+    card = {"block_norm": "alpha", "block": "Alpha", "writer_rounds": 0}
+    calls = []
+
+    async def fake_slot(ctx, label, *, key, prompt, role, capabilities, payload, timeout):
+        calls.append(key)
+        if len(calls) == 1:
+            return gb.OK, []
+        return gb.OK, [{"id": "z1", "text": "Ziel", "sub": "S1"}]
+
+    monkeypatch.setattr(gb, "run_single_slot", fake_slot)
+    assert await gb._stage_lernziele(env, card)
+    assert len(calls) == 2 and calls[1].endswith("-2")
+    assert [z["ziel_id"] for z in await db.list_lernziele(TOPIC, "alpha")] == ["z1"]
+
+
+async def test_lernziele_zweimal_leer_laeuft_weiter(testdb, tmp_path, monkeypatch):
+    db = testdb
+    await db.upsert_guide_card(TOPIC, FMT, "alpha", "Alpha")
+    env = gb._Env(None, "g-r2", TOPIC, FMT, "", tmp_path / "Guide.json", {"Alpha": []}, {}, "(q)", "spec")
+    card = {"block_norm": "alpha", "block": "Alpha", "writer_rounds": 0}
+
+    async def leer(ctx, label, *, key, prompt, role, capabilities, payload, timeout):
+        return gb.OK, []
+
+    monkeypatch.setattr(gb, "run_single_slot", leer)
+    assert await gb._stage_lernziele(env, card)
+    assert (await db.list_guide_cards(TOPIC, FMT))[0]["stage"] == "zuweisung"
+    assert not await db.list_lernziele(TOPIC, "alpha")
+
+
+async def test_pruefer_text_sink_ohne_befund_done(testdb, tmp_path, monkeypatch):
+    """Prüfer antwortet als Text (Engine-Sink, capabilities none); ohne Befund → done."""
+    db = testdb
+    await db.upsert_guide_card(TOPIC, FMT, "alpha", "Alpha")
+    env = gb._Env(None, "g-l", TOPIC, FMT, "", tmp_path / "Guide.json", {"Alpha": []}, {}, "(q)", "spec")
+    md = ("<!-- kapitel: K -->\n<!-- section: Alpha -->\n<!-- compact -->\n- x\n"
+          "<!-- ausführlich -->\n" + "Text im Längen-Rahmen. " * 20)  # ~460 Z. — kein Längen-Trigger
+    card = {"block_norm": "alpha", "block": "Alpha", "writer_rounds": 0, "md": md}
+    seen = {}
+
+    async def fake_slot(ctx, label, *, key, prompt, role, capabilities, payload, timeout):
+        seen["caps"] = capabilities
+        return gb.OK, payload((0, '{"ok": true}', ""))
+
+    monkeypatch.setattr(gb, "run_single_slot", fake_slot)
+    monkeypatch.setattr(gb, "READABILITY_ACTIVE", False)
+    assert await gb._stage_pruefer(env, card)
+    assert seen["caps"] == "none"
+    assert (await db.list_guide_cards(TOPIC, FMT))[0]["stage"] == "done"
+
+
+async def test_writer_prompt_traegt_budget(testdb, tmp_path, monkeypatch):
+    db = testdb
+    await db.upsert_guide_card(TOPIC, FMT, "alpha", "Alpha")
+    env = gb._Env(None, "g-w", TOPIC, FMT, "", tmp_path / "Guide.json",
+                  {"Alpha": [{"title": "S1", "level": "beginner"},
+                             {"title": "S2", "level": "beginner"}]}, {}, "(q)", "spec")
+    card = {"block_norm": "alpha", "block": "Alpha", "writer_rounds": 0, "chapter": "K", "gate_info": ""}
+    seen = {}
+
+    async def fake_slot(ctx, label, *, key, prompt, role, capabilities, payload, timeout):
+        seen["prompt"] = prompt
+        return gb.FAILED, None
+
+    monkeypatch.setattr(gb, "run_single_slot", fake_slot)
+    await gb._stage_writer(env, card)
+    assert str(gb.block_budget(env.subs_by_title["Alpha"])) in seen["prompt"]  # 2× Basis-Budget
+
+
+async def test_pruefer_claims_schwelle(testdb, tmp_path, monkeypatch):
+    """1–2 nur-unbelegt-Claims → kein Fix (Karte direkt done); die Schwelle lebt in _auftraege."""
+    db = testdb
+    await db.upsert_guide_card(TOPIC, FMT, "alpha", "Alpha")
+    env = gb._Env(None, "g-g", TOPIC, FMT, "", tmp_path / "Guide.json", {"Alpha": []}, {}, "(q)", "spec")
+    md = "<!-- section: Alpha -->\n<!-- ausführlich -->\n" + "Text im Rahmen. " * 20
+    card = {"block_norm": "alpha", "block": "Alpha", "writer_rounds": 0, "md": md}
+
+    async def fake_slot(ctx, label, *, key, prompt, role, capabilities, payload, timeout):
+        antwort = '{"claims": [{"text": "c1", "grund": ""}, {"text": "c2", "grund": ""}]}'
+        return gb.OK, payload((0, antwort, ""))
+
+    monkeypatch.setattr(gb, "run_single_slot", fake_slot)
+    monkeypatch.setattr(gb, "READABILITY_ACTIVE", False)
+    assert await gb._stage_pruefer(env, card)
+    assert (await db.list_guide_cards(TOPIC, FMT))[0]["stage"] == "done"
+
+
+async def test_load_subblocks_defaultet_levellose(testdb):
+    """Consensus-Row ohne level fällt NICHT mehr raus — Default 'advanced'.
+    (Re-Run-Resume hinterließ 25 solcher Rows; der Writer verlor sie stumm.)"""
+    from guide import _load_subblocks
+    db = testdb
+    await db.put_subblock("t", "block", "mit level", "Block", "Mit Level",
+                          level="beginner", status="consensus")
+    await db.put_subblock("t", "block", "ohne level", "Block", "Ohne Level", status="consensus")
+    subs = await _load_subblocks("t")
+    by_title = {s["title"]: s["level"] for s in subs["Block"]}
+    assert by_title == {"Mit Level": "beginner", "Ohne Level": "advanced"}
+
+
+async def test_falsch_claim_erzwingt_fix_und_repruefer(testdb, tmp_path, monkeypatch):
+    """Ein einzelner FALSCH-Claim läuft in den Fix, auch unter GATE_FIX_MIN; nach
+    angewandtem Fix läuft GENAU EIN Re-Prüfer-Pass (der alte Lese-Fix blieb ungeprüft)."""
+    db = testdb
+    await db.upsert_guide_card(TOPIC, FMT, "alpha", "Alpha")
+    env = gb._Env(None, "g-gf", TOPIC, FMT, "", tmp_path / "Guide.json", {"Alpha": []}, {}, "(q)", "spec")
+    md = "<!-- section: Alpha -->\n<!-- ausführlich -->\n" + "Text im Rahmen. " * 20
+    card = {"block_norm": "alpha", "block": "Alpha", "writer_rounds": 0, "md": md, "gate_info": ""}
+    keys = []
+
+    async def fake_slot(ctx, label, *, key, prompt, role, capabilities, payload, timeout):
+        keys.append(key)
+        if "-pruef-" in key and key.endswith("-re"):
+            return gb.OK, payload((0, '{"ok": true}', ""))
+        if "-pruef-" in key:
+            return gb.OK, payload((0, '{"claims": [{"text": "c1", "grund": "widerspricht", "urteil": "falsch"}]}', ""))
+        if "-gfix-" in key:  # Fix liefert eine valide Section über die Slot-Datei
+            import re as _re
+            m = _re.search(r"(/\S+\.md)", prompt)
+            with open(m.group(1), "w", encoding="utf-8") as f:
+                f.write(md.replace("Text im Rahmen.", "Korrigiert."))
+            return gb.OK, payload(None)
+        raise AssertionError(key)
+
+    monkeypatch.setattr(gb, "run_single_slot", fake_slot)
+    monkeypatch.setattr(gb, "READABILITY_ACTIVE", False)
+    assert await gb._stage_pruefer(env, card)
+    karte = (await db.list_guide_cards(TOPIC, FMT))[0]
+    assert karte["stage"] == "fix" and karte["gate_info"].startswith("KRITISCH")
+    card.update(stage="fix", gate_info=karte["gate_info"])
+    assert await gb._stage_fix(env, card)
+    assert any("-gfix-" in k for k in keys)
+    assert any(k.endswith("-re") for k in keys)  # Re-Prüfer lief
+    karte = (await db.list_guide_cards(TOPIC, FMT))[0]
+    assert karte["stage"] == "done" and "Korrigiert." in karte["md"]
+
+
+async def test_laengen_trigger_startet_fix(testdb, tmp_path, monkeypatch):
+    """Ausführlich-Teil über der Obergrenze → deterministisches Längen-Problem mit hartem
+    Zeichenziel landet als Auftrag in der Fix-Stage (unkritisch → kein Re-Prüfer)."""
+    db = testdb
+    await db.upsert_guide_card(TOPIC, FMT, "alpha", "Alpha")
+    env = gb._Env(None, "g-lz", TOPIC, FMT, "", tmp_path / "Guide.json",
+                  {"Alpha": [{"title": "S1", "level": "beginner", "relevance": "relevant"}]},
+                  {}, "(q)", "spec")
+    md = ("<!-- section: Alpha -->\n<!-- compact -->\n- x\n<!-- ausführlich -->\n"
+          + "Viel zu langer Sockeltext. " * 80)  # ~2160 Z./Sub > 1200×0.9
+    card = {"block_norm": "alpha", "block": "Alpha", "writer_rounds": 0, "md": md, "gate_info": ""}
+    seen = {}
+
+    async def fake_slot(ctx, label, *, key, prompt, role, capabilities, payload, timeout):
+        if "-gfix-" in key:
+            seen["auftraege"] = prompt
+            return gb.FAILED, None
+        if key.endswith("-re"):
+            raise AssertionError("unkritischer Befund darf keinen Re-Prüfer starten")
+        return gb.OK, payload((0, '{"ok": true}', ""))  # Prüfer: keine LLM-Befunde
+
+    monkeypatch.setattr(gb, "run_single_slot", fake_slot)
+    monkeypatch.setattr(gb, "READABILITY_ACTIVE", False)
+    assert await gb._stage_pruefer(env, card)
+    assert (await db.list_guide_cards(TOPIC, FMT))[0]["stage"] == "fix"
+    card.update(stage="fix", gate_info=(await db.list_guide_cards(TOPIC, FMT))[0]["gate_info"])
+    assert await gb._stage_fix(env, card)
+    budget = gb.block_budget(env.subs_by_title["Alpha"])
+    assert "Länge" in seen["auftraege"] and f"etwa {budget} Zeichen GESAMT" in seen["auftraege"]
+
+
+async def test_repair_karten_setzt_befundkarten_auf_pruefer(testdb, tmp_path, monkeypatch):
+    """Guide-Repair: Karten mit QA-Befunden (alle Befundklassen-Formate) → pruefer,
+    md bleibt; Karten ohne Befund unangetastet. Kein Report → leere Liste."""
+    import json as _json
+    import qa as qa_mod
+    db = testdb
+    monkeypatch.setattr(qa_mod, "QA_DIR", tmp_path / "qa")
+    for n in ("alpha", "beta", "gamma"):
+        await db.upsert_guide_card(TOPIC, FMT, n, n.title())
+        await db.set_guide_card(TOPIC, FMT, n, stage="done", status="ok", md="<!-- section: X -->\nText")
+    assert await gb.repair_karten(TOPIC, FMT) == []  # kein Report
+    tdir = tmp_path / "qa" / TOPIC
+    tdir.mkdir(parents=True)
+    (tdir / "guide-20260705-000000.json").write_text(_json.dumps({
+        "marker_fehlend": ["Alpha · sub eins"],
+        "fachlich_falsch": ["Beta"],
+        "ziel_ohne_anker": [], "laengen_ausreisser": [], "redundanz": [], "lesbarkeit": [],
+    }), encoding="utf-8")
+    betroffen = await gb.repair_karten(TOPIC, FMT)
+    assert sorted(betroffen) == ["Alpha", "Beta"]
+    cards = {c["block_norm"]: c for c in await db.list_guide_cards(TOPIC, FMT)}
+    assert cards["alpha"]["stage"] == cards["beta"]["stage"] == "pruefer"
+    assert cards["alpha"]["md"]  # Text bleibt — der Prüfer arbeitet auf dem Bestand
+    assert cards["gamma"]["stage"] == "done"

backend/tests/test_guide_qa.py

@@ -0,0 +1,120 @@
+"""Guide-QA: Fehler-Injektion auf Mini-Guide-Karten — deterministisch, ohne LLM."""
+
+import guide_qa as gq
+import qa
+
+
+def _card(block, md):
+    return {"block": block, "block_norm": block.casefold(), "md": md}
+
+
+AUSF = ("<!-- section: Alpha -->\n<!-- compact -->\n- m\n<!-- ausführlich -->\n"
+        "Einstieg in den Block.\n"
+        "<!-- sub: beginner | Kantenzug Definition -->\n"
+        "Ein Kantenzug verbindet Knoten über Kanten im Graphen.\n")
+
+
+def test_ausfuehrlich_extrahiert_lerntext():
+    assert gq._ausfuehrlich(AUSF).startswith("\nEinstieg")
+    assert gq._ausfuehrlich("nur text") == "nur text"
+
+
+def test_marker_fehlend():
+    cards = [_card("Alpha", AUSF)]
+    rel = {"alpha": {"kantenzug definition", "fehlender aspekt"}}
+    out = gq.marker_fehlend(cards, rel)
+    assert out == ["Alpha · fehlender aspekt"]
+
+
+def test_ziel_ohne_anker():
+    cards = [_card("Alpha", AUSF)]
+    ziele = [{"block_norm": "alpha", "ziel_id": "z1", "text": "Kantenzug im Graphen erklären"},
+             {"block_norm": "alpha", "ziel_id": "z2", "text": "Adjazenzmatrix aufstellen können"}]
+    out = gq.ziel_ohne_anker(cards, ziele)
+    assert len(out) == 1 and "z2" in out[0]
+
+
+def test_laengen_ausreisser():
+    """Budget-Band statt Festrahmen: zu dünn und zu dick fallen auf, ohne Budget kein Urteil."""
+    duenn = _card("Alpha", "<!-- ausführlich -->\nkurz")
+    ok = _card("Beta", "<!-- ausführlich -->\n" + "x" * 500)
+    dick = _card("Gamma", "<!-- ausführlich -->\n" + "x" * 2000)
+    ohne = _card("Delta", "<!-- ausführlich -->\nkurz")
+    budgets = {"alpha": 500, "beta": 500, "gamma": 500}  # delta: kein Inventar → übersprungen
+    out = gq.laengen_ausreisser([duenn, ok, dick, ohne], budgets)
+    assert [x["block"] for x in out] == ["Alpha", "Gamma"]
+    assert out[1]["zeichen"] >= 2000 and out[1]["budget"] == 500
+
+
+def test_budget_aus_substanz():
+    """Dichte Subs bekommen mehr Budget; periphere zählen nicht."""
+    dicht = {"relevance": "relevant", "facts": {"key_points": ["a", "b"], "cited_facts": [{}], "example_idea": "x"}}
+    duenn = {"relevance": "relevant", "facts": {}}
+    peripher = {"relevance": "peripheral", "facts": {"key_points": ["a"] * 9}}
+    assert gq.sub_budget(dicht["facts"]) > gq.sub_budget(duenn["facts"])
+    assert gq.block_budget([dicht, duenn, peripher]) == gq.block_budget([dicht, duenn])
+
+
+def test_redundanz_findet_absatz_doppel():
+    a = "Der Kantenzug verbindet Knoten über mehrere Kanten und darf Knoten wiederholen. " * 3
+    b = "Der Kantenzug verbindet Knoten über mehrere Kanten und darf Knoten wiederholen, genau. " * 3
+    c = "Völlig anderes Thema: Matrizen, Determinanten und lineare Abbildungen im Vektorraum. " * 3
+    cards = [_card("Alpha", f"<!-- ausführlich -->\n{a}\n\n{c}"),
+             _card("Beta", f"<!-- ausführlich -->\n{b}")]
+    out = gq.redundanz(cards)
+    assert len(out) == 1 and out[0]["a"].startswith("Alpha")
+
+
+def test_lesbarkeit_fail_open(monkeypatch):
+    def kaputt(md_by_num):
+        raise RuntimeError("Modell fehlt")
+    monkeypatch.setattr(gq.readability, "rate_sections", kaputt)
+    assert gq.lesbarkeit([_card("Alpha", AUSF)]) == []
+
+
+def test_note_guide_kalibrierung():
+    """Gewicht = Punktabzug bei 100 %: 10 % fachlich falsch × 3.0 → 7.0; ungemessen zählt nicht."""
+    assert qa.note({"fachlich_falsch": 0.1}, gq.NOTE_GEWICHTE_GUIDE) == 7.0
+    ohne = {"marker_fehlend": 0.0, "ziel_ohne_anker": 0.0}
+    assert qa.note(ohne, gq.NOTE_GEWICHTE_GUIDE) == 10.0
+
+
+def test_marker_escaping_tolerant():
+    """Escapte Titel (h\\~2\\~o) sind kein „Marker fehlt" — Writer und DB escapen verschieden."""
+    md = "<!-- ausführlich -->\n<!-- sub: beginner | ^ und ~ müssen escaped werden (h\\\\~2\\\\~o) -->\nText."
+    cards = [{"block": "Hoch", "block_norm": "hoch", "md": md}]
+    rel = {"hoch": {gq._norm_title("^ und ~ müssen escaped werden (h~2~o)")}}
+    assert gq.marker_fehlend(cards, rel) == []
+
+
+async def test_fachlich_falsch_braucht_beide_bestaetiger(monkeypatch):
+    """Befund zählt nur, wenn BEIDE Bestätiger zustimmen — Einzel-/Zweifach-Urteile
+    ließen die Note desselben Guides zwischen 2.0 und 6.6 springen."""
+    import agents
+    calls = {"n": 0}
+
+    async def fake_agent(key, prompt, timeout, **kw):
+        calls["n"] += 1
+        if "-fakten-3-" in key:    # Bestätiger 2: nur #1 bleibt
+            return 0, '{"relevant": {"1": "ja"}}', ""
+        if "-fakten-2-" in key:    # Bestätiger 1: #1 und #2
+            return 0, '{"relevant": {"1": "ja", "2": "ja"}}', ""
+        return 0, '{"relevant": {"1": "ja", "2": "ja", "3": "nein"}}', ""  # Pass 1
+
+    monkeypatch.setattr(agents, "run_agent", fake_agent)
+    cards = [_card("Alpha", AUSF), _card("Beta", AUSF), _card("Gamma", AUSF)]
+    out = await gq._fachlich_falsch("t", cards)
+    assert out == ["Alpha"] and calls["n"] == 3
+
+
+async def test_fachlich_falsch_ohne_verdacht_kein_zweiter_pass(monkeypatch):
+    import agents
+    calls = {"n": 0}
+
+    async def fake_agent(key, prompt, timeout, **kw):
+        calls["n"] += 1
+        return 0, '{"relevant": {"1": "nein", "2": "nein"}}', ""
+
+    monkeypatch.setattr(agents, "run_agent", fake_agent)
+    out = await gq._fachlich_falsch("t", [_card("Alpha", AUSF), _card("Beta", AUSF)])
+    assert out == [] and calls["n"] == 1

backend/tests/test_kanban.py

@@ -0,0 +1,128 @@
+"""Engine tests with fake processors (no LLM): flow, barrier, retry/dead-letter, producer race."""
+
+import asyncio
+
+import pytest
+
+import kanban
+from kanban import Flow, Stage, chain_stages, run_flow
+
+TOPIC = "t"
+BOARD = "inventory"
+
+
+def _advance_proc(db, to_stage):
+    async def proc(cards):
+        await db.kanban_advance_many(TOPIC, BOARD, [(c["card_id"], to_stage) for c in cards])
+    return proc
+
+
+async def _seed(db, n, stage="s1"):
+    for i in range(n):
+        await db.kanban_upsert_card(TOPIC, BOARD, f"card-{i}", "title", stage, {"title": f"T{i}"})
+
+
+async def test_cards_flow_through_stages(testdb):
+    db = testdb
+    await _seed(db, 7)
+    flow = Flow(TOPIC)
+    stages = chain_stages([
+        Stage(BOARD, "s1", _advance_proc(db, "s2")),
+        Stage(BOARD, "s2", _advance_proc(db, "done")),
+    ])
+    await asyncio.wait_for(run_flow(flow, stages), timeout=10)
+    assert await db.kanban_count(TOPIC, "done", board=BOARD) == 7
+    assert await db.kanban_count(TOPIC, ["s1", "s2"], board=BOARD) == 0
+
+
+async def test_barrier_waits_for_upstream(testdb):
+    db = testdb
+    await _seed(db, 6)
+    upstream_left: list[int] = []
+
+    async def slow_s1(cards):
+        await asyncio.sleep(0.05)  # keep upstream busy so an eager barrier would see queued cards
+        await db.kanban_advance_many(TOPIC, BOARD, [(c["card_id"], "gate") for c in cards])
+
+    async def barrier_proc(cards):
+        upstream_left.append(await db.kanban_count(TOPIC, ["s1"], board=BOARD))
+        await db.kanban_advance_many(TOPIC, BOARD, [(c["card_id"], "done") for c in cards])
+
+    flow = Flow(TOPIC)
+    stages = chain_stages([
+        Stage(BOARD, "s1", slow_s1),
+        Stage(BOARD, "gate", barrier_proc, barrier=True),
+    ])
+    await asyncio.wait_for(run_flow(flow, stages), timeout=10)
+    assert await db.kanban_count(TOPIC, "done", board=BOARD) == 6
+    assert upstream_left and all(n == 0 for n in upstream_left)  # barrier never ran with s1 queued
+
+
+async def test_retry_backoff_then_dead(testdb, monkeypatch):
+    db = testdb
+    monkeypatch.setattr(kanban, "RETRY_BACKOFF", 0.02)
+    await _seed(db, 1)
+    attempts = []
+
+    async def failing(cards):
+        attempts.append(cards[0]["retries"])
+        raise RuntimeError("kaputt")
+
+    flow = Flow(TOPIC)
+    stages = chain_stages([Stage(BOARD, "s1", failing)])
+    await asyncio.wait_for(run_flow(flow, stages), timeout=10)
+    card = await db.kanban_get_card(TOPIC, BOARD, "card-0")
+    assert card["stage"] == "dead"
+    assert card["retries"] == kanban.MAX_CARD_RETRIES
+    assert "kaputt" in card["last_error"]
+    assert attempts == [0, 1, 2]  # backoff between attempts, then dead-letter
+
+
+async def test_requeue_dead(testdb):
+    db = testdb
+    await db.kanban_upsert_card(TOPIC, BOARD, "card-0", "title", "s1")
+    for _ in range(kanban.MAX_CARD_RETRIES):
+        await db.kanban_fail_card(TOPIC, BOARD, "card-0", "x", kanban.MAX_CARD_RETRIES, 0.0)
+    assert (await db.kanban_get_card(TOPIC, BOARD, "card-0"))["stage"] == "dead"
+    assert await db.kanban_requeue_dead(TOPIC, BOARD, "s1") == 1
+    card = await db.kanban_get_card(TOPIC, BOARD, "card-0")
+    assert card["stage"] == "s1" and card["retries"] == 0
+
+
+async def test_producer_attach_in_idle_lull(testdb):
+    """Fix-6 regression: a producer attached while workers sit in the exit grace poll
+    must keep the flow alive and its cards must still be processed."""
+    db = testdb
+    flow = Flow(TOPIC)
+    stages = chain_stages([Stage(BOARD, "s1", _advance_proc(db, "done"))])
+
+    async def producer_a():
+        await db.kanban_upsert_card(TOPIC, BOARD, "card-a", "title", "s1")
+        flow.wake.set()
+        flow.done_producer()
+
+    async def attacher():
+        while await db.kanban_count(TOPIC, "done", board=BOARD) == 0:  # wait for card-a done
+            await asyncio.sleep(0.01)
+        flow.add_producer()  # synchronous BEFORE the work — the grace poll must see it
+
+        async def producer_b():
+            await db.kanban_upsert_card(TOPIC, BOARD, "card-b", "title", "s1")
+            flow.wake.set()
+            flow.done_producer()
+        await producer_b()
+
+    flow.add_producer()  # producer_a, counted before run_flow (sync add)
+    asyncio.get_event_loop().create_task(attacher())
+    await asyncio.wait_for(run_flow(flow, stages, producers=[producer_a()]), timeout=10)
+    assert await db.kanban_count(TOPIC, "done", board=BOARD) == 2
+
+
+async def test_backoff_delays_pull(testdb, monkeypatch):
+    db = testdb
+    await db.kanban_upsert_card(TOPIC, BOARD, "card-0", "title", "s1")
+    await db.kanban_fail_card(TOPIC, BOARD, "card-0", "x", 5, 0.2)
+    assert await db.kanban_pull(TOPIC, BOARD, "s1", 10) == []   # in backoff → not pullable
+    assert await db.kanban_count(TOPIC, "s1", board=BOARD) == 1  # but still counts as queued
+    await asyncio.sleep(0.25)
+    assert len(await db.kanban_pull(TOPIC, BOARD, "s1", 10)) == 1

backend/tests/test_konsolidierung.py

@@ -0,0 +1,265 @@
+"""Cross-Block-Konsolidierung (board_artefacts._proc_konsolidierung) und Finalize —
+Judges gefaked, gegen Test-DB. Die In-Block-Konsolidierung lebt seit dem Verschmelzungs-
+Umbau in block_calls._verify_block und wird in tests/test_block_calls.py getestet."""
+
+import json
+
+import numpy as np
+
+import blocks
+import board_artefacts as ba
+from kanban import Flow
+from pipeline import FAILED, OK, GenContext
+
+TOPIC = "konsolidierung"
+
+
+def _ctx():
+    return GenContext(topic=TOPIC, provider="test", is_cancelled=lambda: False)
+
+
+def _fake_slot(antworten):
+    """run_single_slot-Fake: pro Judge-Key eine Antwort; schreibt via payload (wie der Engine-Sink)."""
+    calls = []
+
+    async def fake(ctx, label, *, key, prompt, role, capabilities, payload, timeout):
+        calls.append({"key": key, "prompt": prompt})
+        j = key.rsplit("-", 1)[-1]  # "j1"/"j2"
+        antwort = antworten.get(j)
+        if antwort is None:
+            return FAILED, None
+        return OK, payload((0, json.dumps(antwort), ""))
+
+    fake.calls = calls
+    return fake
+
+
+async def _seed_block(db, bnorm, subs):
+    for s in subs:
+        await db.put_subblock(TOPIC, bnorm, blocks._norm_title(s), bnorm.title(), s, status="consensus")
+
+
+def test_luecken_schnitt_cap():
+    l1 = [f"Aspekt-{k} fehlt" for k in ("eins", "zwei", "drei", "vier", "fünf")]
+    assert blocks._luecken_schnitt(l1, list(l1)) == l1[:3]  # Cap 3
+    assert blocks._luecken_schnitt(["Inline-HTML"], ["Tabellen-Syntax"]) == []
+
+
+def test_neg_set_lemmatisiert():
+    """kein/keine/keinen falten auf einen Stamm; nicht vs. ohne bleiben verschieden."""
+    a = blocks._neg_set("Fehlerverhalten (kein Syntaxfehler)")
+    b = blocks._neg_set("Fehlerverhalten (keine Syntax-Fehlermeldung)")
+    assert a == b == frozenset({"kein"})
+    assert blocks._neg_set("nicht expandiert") != blocks._neg_set("ohne Expansion")
+    assert blocks._neg_set("niemals gerendert") == blocks._neg_set("nie gerendert")
+
+
+async def test_finalize_purges_stale_rows(testdb, tmp_path):
+    """Re-Run-Waisen: Finalize löscht Alt-Fragen/-Artefakte des Blocks vor dem Upsert."""
+    db = testdb
+    await db.upsert_question_pattern(TOPIC, "alpha", "alt-sub", "Alpha", "Alt", "Alte Frage?")
+    await db.put_sub_artifact(TOPIC, "alpha", "alt-sub", "flashcard", "{}", "Alpha", "Alt")
+    await db.kanban_upsert_card(TOPIC, "artefacts", "alpha", "ablock", "finalize", {})
+    files = {k: tmp_path / f"{k}.json" for k in
+             ("sub_roh", "facts", "sidecar", "question_pattern", "artefakte")}
+    card = {"card_id": "alpha", "payload": {
+        "title": "Alpha", "raw": {"Alpha": ["Neu"]}, "facts": {},
+        "sidecar": {"Alpha": [{"title": "Neu", "level": "beginner"}]},
+        "pattern": {"Alpha": [{"subblock": "Neu", "question": "F?"}]},
+        "artefacts": {"flashcard": [{"block": "Alpha", "subblock": "Neu", "front": "F", "back": "B"}]}}}
+    flow = Flow(TOPIC, work_dir=tmp_path)
+    await ba._proc_finalize(_ctx(), flow, files, [card])
+    assert {r["sub_norm"] for r in await db.list_question_pattern(TOPIC)} == {"neu"}
+    assert {(r["sub_norm"], r["type"]) for r in await db.get_sub_artefakte(TOPIC)} == {("neu", "flashcard")}
+
+
+# ── Cross-Block ─────────────────────────────────────────────────────────────────────
+
+class _FakeEmb:
+    """Gleicher Text → gleicher Einheitsvektor, sonst orthogonal (cos 1.0 / 0.0)."""
+
+    @staticmethod
+    def available():
+        return True
+
+    @staticmethod
+    def embed_sims(texts):
+        uniq = {t: k for k, t in enumerate(dict.fromkeys(texts))}
+        arr = np.zeros((len(texts), max(len(uniq), 1)))
+        for r, t in enumerate(texts):
+            arr[r, uniq[t]] = 1.0
+        return arr @ arr.T
+
+
+async def _cross_env(db, tmp_path, finalisiert=True):
+    """Zwei finalisierte Karten in der End-Barriere; die Sub-Rows liegen in der DB
+    (post-finalize ist die DB die Wahrheit, nicht mehr das Karten-Payload)."""
+    flow = Flow(TOPIC, work_dir=tmp_path)
+    cards = []
+    for bnorm, subs in (("alpha", ["Gleiche Aussage", "Nur in Alpha"]),
+                        ("beta", ["Gleiche Aussage", "Nur in Beta"])):
+        payload = {"title": bnorm.title()}
+        if finalisiert:
+            payload.update(pattern={}, artefacts={})
+        await db.kanban_upsert_card(TOPIC, "artefacts", bnorm, "ablock", "konsolidierung", payload)
+        await _seed_block(db, bnorm, subs)
+        cards.append({"card_id": bnorm, "payload": payload})
+    files = {k: tmp_path / f"{k}.json" for k in
+             ("sub_roh", "facts", "sidecar", "question_pattern", "artefakte")}
+    return flow, cards, files
+
+
+async def test_crossblock_folds_loser(testdb, tmp_path, monkeypatch):
+    """Einstimmig „a" → Betas geteilte Aussage wird variant, ihre Frage wandert zum
+    Gewinner (falte_sub), Karten gehen auf DONE."""
+    db = testdb
+    flow, cards, files = await _cross_env(db, tmp_path)
+    sn = blocks._norm_title("Gleiche Aussage")
+    await db.upsert_question_pattern(TOPIC, "beta", sn, "Beta", "Gleiche Aussage", "F?")
+    monkeypatch.setattr(ba, "embedding", _FakeEmb)
+    fake = _fake_slot({"j1": {"pairs": {"1": "a"}}, "j2": {"pairs": {"1": "a"}}})
+    monkeypatch.setattr(ba, "run_single_slot", fake)
+    await ba._proc_konsolidierung(_ctx(), flow, files, "", cards)
+    assert "Gleiche Aussage" in fake.calls[0]["prompt"]
+    for cid in ("alpha", "beta"):
+        assert (await db.kanban_get_card(TOPIC, "artefacts", cid))["stage"] == ba.DONE
+    beta_rows = {r["sub_norm"]: r["status"] for r in await db.list_subblocks(TOPIC, "beta")}
+    assert beta_rows[sn] == "variant"
+    alpha_rows = {r["sub_norm"]: r["status"] for r in await db.list_subblocks(TOPIC, "alpha")}
+    assert alpha_rows[sn] == "consensus"
+    fragen = await db.list_question_pattern(TOPIC)
+    assert {(r["block_norm"], r["sub_norm"]) for r in fragen} == {("alpha", sn)}  # umgehängt
+
+
+async def test_crossblock_tiebreaker_folds(testdb, tmp_path, monkeypatch):
+    """j1/j2 uneinig → j3 entscheidet mit Mehrheit; hier „a" → Beta verliert."""
+    db = testdb
+    flow, cards, files = await _cross_env(db, tmp_path)
+    monkeypatch.setattr(ba, "embedding", _FakeEmb)
+    fake = _fake_slot({"j1": {"pairs": {"1": "a"}}, "j2": {"pairs": {"1": "nein"}},
+                       "j3": {"pairs": {"1": "a"}}})
+    monkeypatch.setattr(ba, "run_single_slot", fake)
+    await ba._proc_konsolidierung(_ctx(), flow, files, "", cards)
+    assert len(fake.calls) == 3
+    rows = {r["sub_norm"]: r["status"] for r in await db.list_subblocks(TOPIC, "beta")}
+    assert rows[blocks._norm_title("Gleiche Aussage")] == "variant"
+
+
+async def test_crossblock_dissent_without_tiebreaker_keeps_both(testdb, tmp_path, monkeypatch):
+    """j3 liefert nichts (FAILED) → fail-open, Paar bleibt."""
+    db = testdb
+    flow, cards, files = await _cross_env(db, tmp_path)
+    monkeypatch.setattr(ba, "embedding", _FakeEmb)
+    fake = _fake_slot({"j1": {"pairs": {"1": "a"}}, "j2": {"pairs": {"1": "b"}}})  # j3 fehlt → FAILED
+    monkeypatch.setattr(ba, "run_single_slot", fake)
+    await ba._proc_konsolidierung(_ctx(), flow, files, "", cards)
+    assert (await db.kanban_get_card(TOPIC, "artefacts", "beta"))["stage"] == ba.DONE
+    rows = {r["sub_norm"]: r["status"] for r in await db.list_subblocks(TOPIC, "beta")}
+    assert rows[blocks._norm_title("Gleiche Aussage")] == "consensus"
+
+
+async def test_crossblock_ersatzrichter(testdb, tmp_path, monkeypatch):
+    """Nur ein Richter liefert → Ersatz jE als zweite Stimme; Einstimmigkeit faltet."""
+    db = testdb
+    flow, cards, files = await _cross_env(db, tmp_path)
+    monkeypatch.setattr(ba, "embedding", _FakeEmb)
+    fake = _fake_slot({"j1": {"pairs": {"1": "a"}}, "jE": {"pairs": {"1": "a"}}})  # j2 → FAILED
+    monkeypatch.setattr(ba, "run_single_slot", fake)
+    await ba._proc_konsolidierung(_ctx(), flow, files, "", cards)
+    rows = {r["sub_norm"]: r["status"] for r in await db.list_subblocks(TOPIC, "beta")}
+    assert rows[blocks._norm_title("Gleiche Aussage")] == "variant"
+
+
+async def test_crossblock_without_embedding_advances(testdb, tmp_path, monkeypatch):
+    db = testdb
+    flow, cards, files = await _cross_env(db, tmp_path)
+
+    class _Aus:
+        @staticmethod
+        def available():
+            return False
+
+    async def kein_agent(*a, **kw):
+        raise AssertionError("ohne Embedding kein Judge")
+
+    monkeypatch.setattr(ba, "embedding", _Aus)
+    monkeypatch.setattr(ba, "run_single_slot", kein_agent)
+    await ba._proc_konsolidierung(_ctx(), flow, files, "", cards)
+    for cid in ("alpha", "beta"):
+        assert (await db.kanban_get_card(TOPIC, "artefacts", cid))["stage"] == ba.DONE
+
+
+async def test_crossblock_nachzuegler_zurueck_zum_erzeugen(testdb, tmp_path, monkeypatch):
+    """Resume-Karte ohne pattern im Payload → zurück nach generate (bzw. artefakte bei
+    vorhandenem sidecar), KEIN Dedup — finalize würde den Fold sonst re-spiegeln."""
+    db = testdb
+    flow, cards, files = await _cross_env(db, tmp_path, finalisiert=False)
+    cards[1]["payload"]["sidecar"] = {"Beta": []}  # hat Verify schon hinter sich
+    await db.kanban_set_payload(TOPIC, "artefacts", "beta", cards[1]["payload"])
+
+    async def kein_agent(*a, **kw):
+        raise AssertionError("Nachzügler dürfen keinen Dedup auslösen")
+
+    monkeypatch.setattr(ba, "embedding", _FakeEmb)
+    monkeypatch.setattr(ba, "run_single_slot", kein_agent)
+    await ba._proc_konsolidierung(_ctx(), flow, files, "", cards)
+    assert (await db.kanban_get_card(TOPIC, "artefacts", "alpha"))["stage"] == "generate"
+    assert (await db.kanban_get_card(TOPIC, "artefacts", "beta"))["stage"] == "artefakte"
+    rows = {r["sub_norm"]: r["status"] for r in await db.list_subblocks(TOPIC, "beta")}
+    assert rows[blocks._norm_title("Gleiche Aussage")] == "consensus"
+
+
+async def test_finalize_defaultet_level_nachzuegler(testdb, tmp_path):
+    """Finalize klassifiziert level-/relevance-lose consensus-Rows (Default advanced/relevant)."""
+    db = testdb
+    await db.put_subblock(TOPIC, "alpha", "nachzuegler", "Alpha", "Nachzügler", status="consensus")
+    await db.kanban_upsert_card(TOPIC, "artefacts", "alpha", "ablock", "finalize", {})
+    files = {k: tmp_path / f"{k}.json" for k in
+             ("sub_roh", "facts", "sidecar", "question_pattern", "artefakte")}
+    card = {"card_id": "alpha", "payload": {"title": "Alpha", "raw": {}, "facts": {},
+                                            "sidecar": {}, "pattern": {}, "artefacts": {}}}
+    await ba._proc_finalize(_ctx(), Flow(TOPIC, work_dir=tmp_path), files, [card])
+    row = next(r for r in await db.list_subblocks(TOPIC, "alpha"))
+    assert row["level"] == "advanced" and row["relevance"] == "relevant"
+
+
+async def test_finalize_loescht_stale_consensus(testdb, tmp_path):
+    """Alt-consensus-Rows, die der Lauf-Sidecar nicht mehr trägt, fliegen raus —
+    variant-Rows bleiben (QA liest die Status). Wurzel der 25 Board-2-losen Waisen."""
+    db = testdb
+    await db.put_subblock(TOPIC, "alpha", "alt-rest", "Alpha", "Alt-Rest", status="consensus")
+    await db.put_subblock(TOPIC, "alpha", "alte-variante", "Alpha", "Alte Variante", status="variant")
+    await db.kanban_upsert_card(TOPIC, "artefacts", "alpha", "ablock", "finalize", {})
+    files = {k: tmp_path / f"{k}.json" for k in
+             ("sub_roh", "facts", "sidecar", "question_pattern", "artefakte")}
+    card = {"card_id": "alpha", "payload": {
+        "title": "Alpha", "raw": {"Alpha": ["Neu"]}, "facts": {},
+        "sidecar": {"Alpha": [{"title": "Neu", "level": "beginner"}]},
+        "pattern": {}, "artefacts": {}}}
+    await ba._proc_finalize(_ctx(), Flow(TOPIC, work_dir=tmp_path), files, [card])
+    rows = {r["sub_norm"]: r["status"] for r in await db.list_subblocks(TOPIC, "alpha")}
+    assert rows == {"neu": "consensus", "alte-variante": "variant"}
+
+
+async def test_crossblock_chunking_faltet_global(testdb, tmp_path, monkeypatch):
+    """Paare werden gechunkt beurteilt (ein Hänger blockiert nur noch seinen Chunk);
+    die Verdicts falten global über alle Chunks."""
+    db = testdb
+    flow = Flow(TOPIC, work_dir=tmp_path)
+    cards = []
+    for bnorm, subs in (("alpha", ["Gleiche Aussage", "Zweite gleiche Aussage", "Nur in Alpha"]),
+                        ("beta", ["Gleiche Aussage", "Zweite gleiche Aussage"])):
+        payload = {"title": bnorm.title(), "pattern": {}, "artefacts": {}}
+        await db.kanban_upsert_card(TOPIC, "artefacts", bnorm, "ablock", "konsolidierung", payload)
+        await _seed_block(db, bnorm, subs)
+        cards.append({"card_id": bnorm, "payload": payload})
+    files = {k: tmp_path / f"{k}.json" for k in
+             ("sub_roh", "facts", "sidecar", "question_pattern", "artefakte")}
+    monkeypatch.setattr(ba, "embedding", _FakeEmb)
+    monkeypatch.setattr(ba, "CROSS_CHUNK_PAARE", 1)  # 2 Paare → 2 Chunks
+    fake = _fake_slot({"j1": {"pairs": {"1": "a"}}, "j2": {"pairs": {"1": "a"}}})
+    monkeypatch.setattr(ba, "run_single_slot", fake)
+    await ba._proc_konsolidierung(_ctx(), flow, files, "", cards)
+    assert len(fake.calls) == 4  # 2 Chunks × j1/j2
+    rows = {r["sub_norm"]: r["status"] for r in await db.list_subblocks(TOPIC, "beta")}
+    assert set(rows.values()) == {"variant"}  # beide Dubletten global gefaltet

backend/tests/test_pdf_convert.py

@@ -0,0 +1,71 @@
+"""PDF→Text-Konvertierung: pymupdf4llm primär, pdftotext-Fallback, mtime-Cache."""
+
+import os
+import time
+
+import fitz  # PyMuPDF
+import pytest
+
+import blocks as blx
+
+
+def _mini_pdf(path, text="Approximationsalgorithmen sind wichtig."):
+    doc = fitz.open()
+    page = doc.new_page()
+    page.insert_text((72, 72), text, fontsize=12)
+    doc.save(str(path))
+    doc.close()
+
+
+def test_convert_writes_markdown_txt(tmp_path):
+    _mini_pdf(tmp_path / "skript.pdf")
+    blx._convert_pdfs(tmp_path)
+    out = (tmp_path / "skript.txt").read_text(encoding="utf-8")
+    assert "Approximationsalgorithmen" in out
+
+
+def test_cache_skips_fresh_txt(tmp_path):
+    _mini_pdf(tmp_path / "a.pdf")
+    marker = tmp_path / "a.txt"
+    marker.write_text("MARKER", encoding="utf-8")
+    now = time.time() + 60
+    os.utime(marker, (now, now))
+    blx._convert_pdfs(tmp_path)
+    assert marker.read_text(encoding="utf-8") == "MARKER"  # nicht neu konvertiert
+
+
+def test_fallback_to_pdftotext(tmp_path, monkeypatch):
+    _mini_pdf(tmp_path / "b.pdf")
+    monkeypatch.setattr(blx, "_pdf_markdown", lambda p: None)
+    monkeypatch.setattr(blx, "_pdf_plaintext", lambda p: "fallback")
+    blx._convert_pdfs(tmp_path)
+    assert (tmp_path / "b.txt").read_text(encoding="utf-8") == "fallback"
+
+
+def test_ocr_languages_from_tessdata(tmp_path, monkeypatch):
+    import pymupdf
+
+    monkeypatch.setattr(pymupdf, "get_tessdata", lambda: str(tmp_path))
+    assert blx._ocr_languages() is None  # keine Sprachdaten → OCR aus
+    (tmp_path / "eng.traineddata").touch()
+    assert blx._ocr_languages() == "eng"
+    (tmp_path / "deu.traineddata").touch()
+    assert blx._ocr_languages() == "deu+eng"
+    monkeypatch.setattr(pymupdf, "get_tessdata", lambda: (_ for _ in ()).throw(RuntimeError()))
+    assert blx._ocr_languages() is None
+
+
+def test_fidelity_guard_prefers_faithful_plaintext():
+    plain = "Definition. P = {L ⊆ Σ | A ∈ L} und ≤ sowie häufig über. " * 20
+    # Markdown verlor die Formeln (Symbole weg) → plain gewinnt
+    md_lossy = "Definition. und sowie h¨aufig ¨uber. " * 20
+    text, tool = blx._pick_conversion(md_lossy, plain)
+    assert tool == "pdftotext"
+    # Markdown treu (Symbole + Länge da) → md gewinnt
+    md_ok = "# Def\n" + plain
+    text, tool = blx._pick_conversion(md_ok, plain)
+    assert tool == "pymupdf4llm"
+    # nur eine Quelle verfügbar
+    assert blx._pick_conversion(None, plain)[1] == "pdftotext"
+    assert blx._pick_conversion(md_ok, None)[1] == "pymupdf4llm"
+    assert blx._pick_conversion(None, None) is None

backend/tests/test_practice.py

@@ -0,0 +1,146 @@
+"""Flashcard-Übungspool: Leitner-Schritte, Deck-Bau (Level-Gate, fällig/neu), Persistenz."""
+
+import json
+from datetime import datetime, timedelta, timezone
+
+from learning import LEITNER_MAX_BOX, PRACTICE_NEW_PER_SESSION, leitner_step
+
+TOPIC = "t"
+
+
+def _iso(days: float = 0) -> str:
+    return (datetime.now(timezone.utc) + timedelta(days=days)).isoformat()
+
+
+async def _card(db, bn, sn, sub_title="Sub", q="Q?", block="Block"):
+    await db.put_sub_artifact(TOPIC, bn, sn, "flashcard",
+                              json.dumps({"question": q, "answer": "A"}), block, sub_title)
+
+
+# ── Leitner rein funktional ──────────────────────────────────────────────────────────
+
+def test_leitner_step_transitions():
+    assert leitner_step(None, True) == (2, 1)    # neue Karte gewusst → Box 2, morgen
+    assert leitner_step(None, False) == (1, 0)   # neue Karte falsch → Box 1, sofort
+    assert leitner_step(2, True) == (3, 3)
+    assert leitner_step(LEITNER_MAX_BOX, True) == (LEITNER_MAX_BOX, 21)  # Cap
+    assert leitner_step(4, False) == (1, 0)      # falsch → zurück auf Anfang
+
+
+# ── Persistenz ───────────────────────────────────────────────────────────────────────
+
+async def test_progress_upsert_roundtrip(testdb):
+    db = testdb
+    await db.upsert_practice_progress(TOPIC, "b", "s", 2, _iso(1))
+    await db.upsert_practice_progress(TOPIC, "b", "s", 3, _iso(3))
+    rows = await db.get_practice_progress(TOPIC)
+    assert len(rows) == 1 and rows[0]["box"] == 3
+
+
+async def test_progress_survives_artefakte_wipe(testdb):
+    db = testdb
+    await _card(db, "b", "s")
+    await db.upsert_practice_progress(TOPIC, "b", "s", 4, _iso(7))
+    await db.delete_sub_artefakte(TOPIC)  # Regenerations-Wipe
+    assert (await db.get_practice_progress(TOPIC))[0]["box"] == 4
+
+
+async def test_delete_topic_pipeline_clears_progress(testdb):
+    db = testdb
+    await db.upsert_practice_progress(TOPIC, "b", "s", 2, _iso(1))
+    await db.delete_topic_pipeline(TOPIC)
+    assert await db.get_practice_progress(TOPIC) == []
+
+
+async def test_sub_levels_norm_and_counts(testdb):
+    db = testdb
+    await db.put_subblock(TOPIC, "b", "s1", "Block", "S1", level="beginner")
+    await db.put_subblock(TOPIC, "b", "s2", "Block", "S2", level="expert")
+    await db.put_subblock(TOPIC, "b", "s3", "Block", "S3", level="beginner", relevance="peripheral")
+    await db.put_subblock(TOPIC, "b", "s4", "Block", "S4", level="beginner", status="variant")
+    levels = await db.sub_levels_norm(TOPIC)
+    assert levels[("b", "s1")] == 1 and levels[("b", "s2")] == 3 and levels[("b", "s3")] == 4
+    assert ("b", "s4") not in levels  # non-consensus ausgeschlossen
+    counts = await db.subs_per_level_norm(TOPIC)
+    assert counts["b"] == {1: 1, 2: 0, 3: 1, 4: 1}
+
+
+# ── Deck-Bau ─────────────────────────────────────────────────────────────────────────
+
+async def test_deck_level_gate_and_unlock(testdb):
+    from routes import build_practice_deck
+    db = testdb
+    # block_norm muss _norm_title(Roh-Titel) sein — so entsteht er auch in der Pipeline
+    await db.put_subblock(TOPIC, "block", "s1", "Block", "S1", level="beginner")
+    await db.put_subblock(TOPIC, "block", "s2", "Block", "S2", level="expert")
+    await _card(db, "block", "s1", "S1")
+    await _card(db, "block", "s2", "S2")
+    deck = await build_practice_deck(TOPIC)
+    assert [c["sub_norm"] for c in deck["cards"]] == ["s1"]  # expert gesperrt
+    assert deck["counts"]["gesperrt"] == 1
+    # Score über S1+S2-Schwelle (2 Subs × 25 = 50) → expert (Level 3) frei
+    await db.set_block_score_and_streak(TOPIC, "Block", 50, 0)
+    deck = await build_practice_deck(TOPIC)
+    assert {c["sub_norm"] for c in deck["cards"]} == {"s1", "s2"}
+
+
+async def test_deck_due_before_new_oldest_first(testdb):
+    from routes import build_practice_deck
+    db = testdb
+    for sn in ("s1", "s2", "s3"):
+        await db.put_subblock(TOPIC, "b", sn, "Block", sn.upper(), level="beginner")
+        await _card(db, "b", sn, sn.upper())
+    await db.upsert_practice_progress(TOPIC, "b", "s2", 2, _iso(-1))
+    await db.upsert_practice_progress(TOPIC, "b", "s3", 2, _iso(-5))
+    deck = await build_practice_deck(TOPIC)
+    assert [c["sub_norm"] for c in deck["cards"]] == ["s3", "s2", "s1"]  # älteste fällige zuerst
+    assert [c["status"] for c in deck["cards"]] == ["due", "due", "new"]
+    assert deck["counts"] == {"due": 2, "new": 1, "new_total": 1, "gesperrt": 0}
+
+
+async def test_deck_caps_new_and_reports_total(testdb):
+    from routes import build_practice_deck
+    db = testdb
+    for i in range(PRACTICE_NEW_PER_SESSION + 5):
+        sn = f"s{i:02d}"
+        await db.put_subblock(TOPIC, "b", sn, "Block", sn, level="beginner")
+        await _card(db, "b", sn, sn)
+    deck = await build_practice_deck(TOPIC)
+    assert deck["counts"]["new"] == PRACTICE_NEW_PER_SESSION
+    assert deck["counts"]["new_total"] == PRACTICE_NEW_PER_SESSION + 5
+
+
+async def test_deck_future_due_sets_next_due_at(testdb):
+    from routes import build_practice_deck
+    db = testdb
+    await db.put_subblock(TOPIC, "b", "s1", "Block", "S1", level="beginner")
+    await _card(db, "b", "s1", "S1")
+    await db.upsert_practice_progress(TOPIC, "b", "s1", 3, _iso(3))
+    deck = await build_practice_deck(TOPIC)
+    assert deck["cards"] == [] and deck["counts"]["due"] == 0
+    assert deck["next_due_at"] is not None
+
+
+async def test_deck_orphan_progress_and_legacy_block(testdb):
+    from routes import build_practice_deck
+    db = testdb
+    # Orphan: Progress ohne Karte → unschädlich, taucht nicht auf
+    await db.upsert_practice_progress(TOPIC, "weg", "s0", 2, _iso(-1))
+    # Legacy: Karte ohne subblocks-Zeilen → ungefiltert durchlassen
+    await _card(db, "leg", "sx", "SX")
+    deck = await build_practice_deck(TOPIC)
+    assert [c["block_norm"] for c in deck["cards"]] == ["leg"]
+
+
+async def test_answer_books_without_card(testdb):
+    """Antwort während Regeneration: bucht immer, kein Fehlerpfad."""
+    from models import PracticeAnswerRequest
+    from routes import practice_answer
+    db = testdb
+    res = await practice_answer(PracticeAnswerRequest(
+        topic=TOPIC, block_norm="b", sub_norm="s", correct=True))
+    assert res["box"] == 2
+    res = await practice_answer(PracticeAnswerRequest(
+        topic=TOPIC, block_norm="b", sub_norm="s", correct=False))
+    assert res["box"] == 1
+    assert (await db.get_practice_progress(TOPIC))[0]["box"] == 1

backend/tests/test_qa.py

@@ -0,0 +1,271 @@
+"""QA-Detektoren: Fehler-Injektion auf Mini-Korpus — deterministisch, ohne LLM/Embedding."""
+
+import json
+
+import qa
+
+
+CORPUS = {"Skript.txt": (
+    "Kapitel 1: Vertex Cover — Definition, Approximation und Beweis der Guete.\n\n"
+    "Kapitel 2: Matching in Graphen — perfektes Matching und Augmentationswege.")}
+BLOCKS = [
+    {"title": "Vertex Cover", "description": "Knotenüberdeckung", "sources": ["Skript.txt"]},
+    {"title": "Matching", "description": "Paarung in Graphen", "sources": ["Skript.txt"]},
+]
+SUBS = {"vertex cover": ["Approximation der Guete"], "matching": ["Matching in Graphen", "Augmentationswege"]}
+
+
+def test_baseline_clean(monkeypatch):
+    """Sauberes Soll-Inventar → alle Detektoren still (jeder Absatz ein Abschnitt)."""
+    monkeypatch.setattr(qa, "SECTION_CHARS", 20)
+    assert qa.dubletten(BLOCKS, emb_on=False) == []
+    assert qa.luecken(BLOCKS, SUBS, CORPUS) == []
+    assert qa.fremd(BLOCKS, CORPUS) == []
+    assert qa.hygiene(BLOCKS) == []
+
+
+def test_injected_duplicate_found():
+    b = BLOCKS + [{"title": "Vertex-Cover-Problem", "description": "", "sources": []}]
+    pairs = qa.dubletten(b, emb_on=False)
+    assert any({p["a"], p["b"]} == {"Vertex Cover", "Vertex-Cover-Problem"} for p in pairs)
+
+
+def test_acronym_signal():
+    b = BLOCKS + [{"title": "VC (Vertex Cover)", "description": "", "sources": []}]
+    pairs = qa.dubletten(b, emb_on=False)
+    hit = next(p for p in pairs if "VC (Vertex Cover)" in (p["a"], p["b"]) and "Vertex Cover" in (p["a"], p["b"]))
+    assert hit["signale"].get("akronym") is True
+
+
+def test_relation_operand_not_suspicious():
+    """Relation vs. Operand ist per Design getrennt — kein Verdachtspaar."""
+    b = BLOCKS + [{"title": "3-SAT ≤ Vertex Cover", "description": "", "sources": []}]
+    pairs = qa.dubletten(b, emb_on=False)
+    assert not any("≤" in p["a"] + p["b"] for p in pairs)
+
+
+def test_removed_block_creates_gap(monkeypatch):
+    monkeypatch.setattr(qa, "SECTION_CHARS", 20)
+    only_vc = [BLOCKS[0]]
+    gaps = qa.luecken(only_vc, {"vertex cover": SUBS["vertex cover"]}, CORPUS)
+    assert len(gaps) == 1 and "Matching" in gaps[0]["vorschau"]
+
+
+def test_foreign_block_flagged():
+    b = BLOCKS + [{"title": "Quantencomputer Grundlagen", "description": "", "sources": []}]
+    assert qa.fremd(b, CORPUS) == ["Quantencomputer Grundlagen"]
+
+
+def test_beleg_flags_unbacked_sub():
+    rows = [{"block": "Matching", "sub_title": "Erfunden", "mentions": 0, "status": "consensus"},
+            {"block": "Matching", "sub_title": "Belegt", "mentions": 3, "status": "consensus"}]
+    r = qa.beleg([{"title": "Matching", "sources": []}], rows)
+    assert r["subs_ohne_beleg"] == ["Matching · Erfunden"]
+    assert r["bloecke_ohne_quelle"] == ["Matching"]
+
+
+def test_hygiene_flags():
+    b = [{"title": "**Fett**", "description": "", "sources": []},
+         {"title": "Block (2)", "description": "ok", "sources": []}]
+    h = {x["titel"]: x["probleme"] for x in qa.hygiene(b)}
+    assert "markdown" in h["**Fett**"] and "leere-beschreibung" in h["**Fett**"]
+    assert h["Block (2)"] == ["kollisions-suffix"]
+
+
+def test_sections_split_on_paragraphs():
+    secs = qa._sections("a\n\nb\n\nc", goal=3)
+    assert len(secs) >= 2 and "".join(secs).replace("\n", "") == "abc"
+
+
+def test_note_deterministic_and_monotonic():
+    """Saubere Quoten → 10; jede zusätzliche Quote drückt die Note."""
+    sauber = {k: 0 for k in qa.NOTE_GEWICHTE}
+    assert qa.note(sauber) == 10.0
+    schlechter = dict(sauber, luecken=0.05)
+    noch_schlechter = dict(schlechter, fremd=0.05)
+    assert 10.0 > qa.note(schlechter) > qa.note(noch_schlechter) >= 0.0
+    assert qa.note({k: 1 for k in qa.NOTE_GEWICHTE}) == 0.0
+
+
+def test_note_kalibrierung():
+    """Gewicht = Punktabzug bei 100 %: 5 % Fremd × 2.5 → −1.25 → 8.8 gerundet."""
+    assert qa.note({"fremd": 0.05}) == 8.8
+    assert qa.note({"fremd": 1.0}) == 0.0  # komplett fremdes Inventar = 0, nicht 7.7
+
+
+def test_note_verdacht_zaehlt_nicht():
+    """dubletten_verdacht ist Verdachtsliste, kein Urteil — beeinflusst die Note nicht."""
+    assert qa.note({"dubletten_verdacht": 1.0}) == 10.0
+
+
+def test_note_artefakte_getrennt():
+    """Subs/Artefakte haben eigene Gewichte — zur Gate-Zeit existieren sie noch nicht
+    und dürfen die Inventar-Note weder schönen noch drücken."""
+    assert "subs_ohne_beleg" not in qa.NOTE_GEWICHTE
+    assert qa.note({"subs_ohne_beleg": 0.0, "verwaiste": 0.1}, qa.NOTE_GEWICHTE_ARTEFAKTE) == 9.0
+    assert qa.note({"subs_ohne_beleg": 1.0}, qa.NOTE_GEWICHTE_ARTEFAKTE) == 0.0
+
+
+def test_artefakte_coverage_and_orphans():
+    subs = [{"block_norm": "b", "sub_norm": "s1: lange beschreibung", "status": "consensus"},
+            {"block_norm": "b", "sub_norm": "s2", "status": "consensus"},
+            {"block_norm": "b", "sub_norm": "alt", "status": "variant"},
+            {"block_norm": "b", "sub_norm": "weg", "status": "discarded"}]
+    arts = [{"block_norm": "b", "sub_norm": "s1", "type": "flashcard"},   # Präfix-Treffer
+            {"block_norm": "b", "sub_norm": "alt", "type": "flashcard"},  # variant → lebt, keine Waise
+            {"block_norm": "b", "sub_norm": "weg", "type": "flashcard"},  # verworfen → Waise
+            {"block_norm": "b", "sub_norm": "tot", "type": "flashcard"}]  # fehlt → Waise
+    fragen = [{"block_norm": "b", "sub_norm": "s1: lange beschreibung"},
+              {"block_norm": "b", "sub_norm": "s2"}]
+    r = qa.artefakte(subs, arts, fragen)
+    assert r["frage_abdeckung"] == 1.0
+    assert r["flashcard_abdeckung"] == 0.5  # nur s1 der beiden consensus-Subs
+    assert r["verwaiste"] == ["flashcard: b · tot", "flashcard: b · weg"]
+
+
+def test_artefakte_prefix_family_resolves_to_consensus():
+    """Kurz-Key trifft consensus-Sub PLUS gefaltete Varianten mit gleichem Präfix —
+    das ist keine Waise, das Ziel ist der consensus-Sub."""
+    subs = [{"block_norm": "b", "sub_norm": "auto: echte fassung", "status": "consensus"},
+            {"block_norm": "b", "sub_norm": "auto: variante eins", "status": "variant"},
+            {"block_norm": "b", "sub_norm": "auto: variante zwei", "status": "variant"}]
+    arts = [{"block_norm": "b", "sub_norm": "auto", "type": "example"}]
+    r = qa.artefakte(subs, arts, [])
+    assert r["verwaiste"] == []
+    assert r["beispiel_abdeckung"] == 1.0
+
+
+def test_artefakte_not_generated():
+    assert qa.artefakte([{"block_norm": "b", "sub_norm": "s", "status": "consensus"}], [], []) == {"status": "nicht generiert"}
+
+
+def test_fremd_glued_prefix_not_whitewashed():
+    """'αÜbergang' darf nicht über den Substring 'bergang'⊂'Übergang' als belegt gelten;
+    Symbol-Varianten (Δ/∆) bleiben über die ASCII-Form gedeckt."""
+    corpus = {"S.txt": "Der Übergang ist wichtig.\n\nDer ∆TSP1 Algorithmus folgt."}
+    b = [{"title": "αÜbergang", "description": "", "sources": []},
+         {"title": "ΔTSP1-Algorithmus", "description": "", "sources": []}]
+    assert qa.fremd(b, corpus) == ["αÜbergang"]
+
+
+def test_note_ignores_unmeasured_quotes():
+    """unechte_bloecke zählt nur, wenn gemessen (--llm) — sonst weder Schaden noch Schönung."""
+    ohne = {k: 0.02 for k in qa.NOTE_GEWICHTE if k != "unechte_bloecke"}
+    mit_null = dict(ohne, unechte_bloecke=0.0)
+    mit_schaden = dict(ohne, unechte_bloecke=0.5)
+    assert qa.note(mit_null) == qa.note(ohne)
+    assert qa.note(mit_schaden) < qa.note(ohne)
+
+
+class _FakeEmb:
+    """Gleicher Text → gleicher Einheitsvektor, sonst orthogonal (cos 1.0 / 0.0)."""
+
+    @staticmethod
+    def available():
+        return True
+
+    @staticmethod
+    def embed(texts):
+        import numpy as np
+        uniq = {t: k for k, t in enumerate(dict.fromkeys(texts))}
+        arr = np.zeros((len(texts), max(len(uniq), 1)))
+        for r, t in enumerate(texts):
+            arr[r, uniq[t]] = 1.0
+        return arr
+
+
+def test_sub_dubletten_detector(monkeypatch):
+    """Kandidaten in-block UND cross-block; nur consensus-Subs zählen."""
+    monkeypatch.setattr(qa, "embedding", _FakeEmb)
+    rows = [{"block": "Alpha", "block_norm": "alpha", "sub_title": "Gleiche Aussage", "status": "consensus"},
+            {"block": "Beta", "block_norm": "beta", "sub_title": "Gleiche Aussage", "status": "consensus"},
+            {"block": "Beta", "block_norm": "beta", "sub_title": "Andere Aussage", "status": "consensus"},
+            {"block": "Beta", "block_norm": "beta", "sub_title": "Gleiche Aussage", "status": "variant"}]
+    pairs = qa.sub_dubletten(rows)
+    assert len(pairs) == 1
+    assert pairs[0]["cross"] is True and pairs[0]["cos"] == 1.0
+    assert qa.sub_dubletten(rows, emb_on=False) == []
+
+
+def test_note_sub_dubletten():
+    """Bestätigte Sub-Dubletten drücken die Artefakt-Note; der bloße Verdacht nicht."""
+    assert qa.note({"sub_dubletten": 0.1}, qa.NOTE_GEWICHTE_ARTEFAKTE) == 9.0
+    assert qa.note({"sub_dubletten_verdacht": 1.0}, qa.NOTE_GEWICHTE_ARTEFAKTE) == 10.0
+
+
+def test_zaehlbare_luecken():
+    """Mit LLM zählen widerlegte Lücken nicht; unbeurteilte ('?'/ohne Key) konservativ schon."""
+    lk = [{"llm": "ja"}, {"llm": "nein"}, {"llm": "?"}, {}]
+    assert len(qa._zaehlbare_luecken(lk, llm=True)) == 3
+    assert len(qa._zaehlbare_luecken(lk, llm=False)) == 4
+
+
+def test_description_anchors_cover(monkeypatch):
+    """Am Gate existieren keine Subs — Beschreibungs-Tokens müssen Abschnitte decken."""
+    monkeypatch.setattr(qa, "SECTION_CHARS", 20)
+    corpus = {"S.txt": "Kapitel 9: Augmentationswege und perfektes Matching."}
+    block = [{"title": "Paarungen", "description": "perfektes Matching mit Augmentationswege", "sources": []}]
+    assert qa.luecken(block, {}, corpus) == []
+    ohne = [{"title": "Paarungen", "description": "", "sources": []}]
+    assert len(qa.luecken(ohne, {}, corpus)) == 1
+
+
+def test_fremd_digit_suffix_tolerant():
+    """'ΔTSP1' matcht Korpus-'∆TSP' (tokenisiert zu 'tsp') via Ziffern-Suffix-Fallback."""
+    corpus = {"S.txt": "Der ∆TSP Algorithmus verdoppelt Kanten im Graphen."}
+    b = [{"title": "ΔTSP1-Algorithmus", "description": "", "sources": []},
+         {"title": "Quantencomputer", "description": "", "sources": []}]
+    assert qa.fremd(b, corpus) == ["Quantencomputer"]
+
+
+async def test_unecht_braucht_doppelt_nein(testdb, tmp_path, monkeypatch):
+    """Echtheits-Urteil zählt nur nach Bestätiger-Pass: der Einzel-Judge flaggte pro Lauf
+    andere Blöcke und pendelte die Note (aak: 9.3↔10.0 bei identischem Bestand)."""
+    db = testdb
+    for cid, titel in (("b1", "Wackelkandidat"), ("b2", "Zufallstreffer"), ("b3", "Solide")):
+        await db.kanban_upsert_card("t", "inventory", cid, "block", "done_block",
+                                    {"title": titel, "description": "d"})
+    monkeypatch.setattr(qa, "QA_DIR", tmp_path)
+
+    async def fake_verdicts(template, topic, key, items):
+        if template != "QA-Bausteine":
+            return {}
+        if key.startswith("bausteine-b2"):  # Bestätiger sieht nur die Geflaggten
+            assert len(items) == 2
+            return {1: "nein", 2: "ja"}  # nur der erste wird bestätigt
+        return {1: "nein", 2: "nein", 3: "ja"}  # Pass 1 flaggt zwei
+
+    monkeypatch.setattr(qa, "_llm_verdicts", fake_verdicts)
+    report = await qa.qa_report("t", llm=True)
+    assert report["unecht"] == ["Wackelkandidat"]
+
+
+async def test_write_report_spiegelt_note_als_event(testdb, tmp_path, monkeypatch):
+    """Report-JSONs liegen nur auf der Lauf-Maschine — write_report spiegelt Note/Quoten
+    als kind='qa'-Event in die DB, damit ein DB-Pull für die Run-Analyse reicht."""
+    db = testdb
+    monkeypatch.setattr(qa, "QA_DIR", tmp_path)
+    report = {"topic": "t", "run_id": "20260704-1452-b223", "note": 9.3, "note_artefakte": 8.0,
+              "quoten": {"luecken": 0.1}, "quoten_artefakte": {"verwaiste": 0.0}}
+    path = await qa.write_report(report)
+    assert path.stem == "20260704-1452-b223"
+    conn = await db.get_db()
+    row = await (await conn.execute(
+        "SELECT key, meta, run_id FROM events WHERE topic='t' AND kind='qa'")).fetchone()
+    assert row and row[0] == "20260704-1452-b223"
+    meta = json.loads(row[1])
+    assert meta["note"] == 9.3 and meta["note_artefakte"] == 8.0
+    assert meta["quoten"] == {"luecken": 0.1} and meta["quoten_artefakte"] == {"verwaiste": 0.0}
+    assert row[2] == ""  # manuelle QA ohne Lauf → leeres run_id ist korrekt
+
+
+async def test_topic_delete_entfernt_qa_ordner(testdb, tmp_path, monkeypatch):
+    """DELETE /topics räumt auch storage/qa/<topic>/ — Reports gehören zum Topic."""
+    import routes
+    monkeypatch.setattr(routes, "topic_dir", lambda t: tmp_path / "topics" / t)
+    monkeypatch.setattr(qa, "QA_DIR", tmp_path / "qa")
+    qdir = tmp_path / "qa" / "t"
+    qdir.mkdir(parents=True)
+    (qdir / "alt.json").write_text("{}", encoding="utf-8")
+    await routes.remove_topic("t")
+    assert not qdir.exists()

backend/tests/test_race.py

@@ -0,0 +1,156 @@
+"""_race-Hedging: Stall-Slots bekommen einen parallelen Zwilling statt den Timeout-Cap
+abzuwarten (gemessen: 4 Panel-Stalls à 160–230 s pro Lauf auf dem kritischen Pfad)."""
+
+import asyncio
+
+import pipeline
+
+
+def _slot(payload=lambda r: r[1]):
+    return {"key": "k1", "prompt": "p", "role": "judge", "capabilities": "none", "payload": payload}
+
+
+async def test_hedge_zwilling_rettet_stall(monkeypatch):
+    """Original stallt → nach HEDGE_NACH_S startet der Zwilling (key -h), sein Ergebnis
+    gewinnt, das hängende Original wird gekillt."""
+    calls, killed = [], []
+
+    async def fake_agent(key, prompt, timeout, **kw):
+        calls.append(key)
+        if key.endswith("-h"):
+            return (0, "zwilling", "")
+        await asyncio.sleep(30)  # Stall — würde sonst den ganzen Cap verbrennen
+        return (0, "original", "")
+
+    monkeypatch.setattr(pipeline, "run_agent", fake_agent)
+    monkeypatch.setattr(pipeline, "kill_process", lambda k: killed.append(k))
+    monkeypatch.setattr(pipeline, "_HEDGE_NACH_S", 0.05)
+    res = await pipeline._race("t", "Test", [_slot()], 1, 0.1, "claude")
+    assert res == ["zwilling"]
+    assert calls == ["k1", "k1-h"]
+    assert "k1" in killed  # das hängende Original läuft nicht weiter
+
+
+async def test_hedge_original_gewinnt_zwilling_wird_gekillt(monkeypatch):
+    """Kommt das Original doch noch vor dem Zwilling an, wird der Zwilling gekillt
+    und sein spätes Ergebnis nicht gewertet."""
+    killed = []
+
+    async def fake_agent(key, prompt, timeout, **kw):
+        await asyncio.sleep(0.3 if key.endswith("-h") else 0.15)
+        return (0, key, "")
+
+    monkeypatch.setattr(pipeline, "run_agent", fake_agent)
+    monkeypatch.setattr(pipeline, "kill_process", lambda k: killed.append(k))
+    monkeypatch.setattr(pipeline, "_HEDGE_NACH_S", 0.05)
+    res = await pipeline._race("t", "Test", [_slot()], 1, 0.1, "claude")
+    assert res == ["k1"]
+    assert "k1-h" in killed
+
+
+async def test_hedge_aus_bei_null(monkeypatch):
+    """HEDGE_NACH_S=0 → kein Zwilling, Verhalten wie zuvor."""
+    calls = []
+
+    async def fake_agent(key, prompt, timeout, **kw):
+        calls.append(key)
+        await asyncio.sleep(0.1)
+        return (0, "ok", "")
+
+    monkeypatch.setattr(pipeline, "run_agent", fake_agent)
+    monkeypatch.setattr(pipeline, "_HEDGE_NACH_S", 0)
+    res = await pipeline._race("t", "Test", [_slot()], 1, 0.1, "claude")
+    assert res == ["ok"]
+    assert calls == ["k1"]
+
+
+async def test_hedge_schwelle_skaliert_mit_timeout(monkeypatch):
+    """Die Schwelle ist max(HEDGE_NACH_S, timeout/2): ein gesunder Call, der länger als
+    die Untergrenze, aber kürzer als das halbe Timeout läuft, bekommt KEINEN Zwilling
+    (pauschale 90 s hedgten jeden normalen Fix-Call)."""
+    calls = []
+
+    async def fake_agent(key, prompt, timeout, **kw):
+        calls.append(key)
+        await asyncio.sleep(0.15)  # > Untergrenze 0.05, < timeout/2 = 0.5
+        return (0, "ok", "")
+
+    monkeypatch.setattr(pipeline, "run_agent", fake_agent)
+    monkeypatch.setattr(pipeline, "_HEDGE_NACH_S", 0.05)
+    res = await pipeline._race("t", "Test", [_slot()], 1, 1.0, "claude")
+    assert res == ["ok"]
+    assert calls == ["k1"]
+
+
+async def test_late_fold_nachzuegler_zaehlt_nach(monkeypatch):
+    """Quorum 2 kehrt sofort zurück; der dritte Slot wird nicht gekillt, sein Ergebnis
+    geht an `late` (ersetzt den grace-Timer der Finder-Runden)."""
+    import time
+    killed, spaet = [], []
+
+    async def fake_agent(key, prompt, timeout, **kw):
+        if key == "k3":
+            await asyncio.sleep(0.2)
+            return (0, "dritter", "")
+        return (0, key, "")
+
+    async def late(val):
+        spaet.append(val)
+
+    monkeypatch.setattr(pipeline, "run_agent", fake_agent)
+    monkeypatch.setattr(pipeline, "kill_process", lambda k: killed.append(k))
+    monkeypatch.setattr(pipeline, "_HEDGE_NACH_S", 0)
+    slots = [{"key": f"k{i}", "prompt": "p", "role": "quick", "capabilities": "none",
+              "payload": lambda r: r[1]} for i in (1, 2, 3)]
+    t0 = time.monotonic()
+    res = await pipeline._race("t", "Test", slots, 2, 60, "claude", late=late)
+    assert time.monotonic() - t0 < 0.15  # kein Warten auf k3
+    assert sorted(res) == ["k1", "k2"]
+    assert "k3" not in killed
+    await asyncio.sleep(0.3)
+    assert spaet == ["dritter"]
+
+
+async def test_late_fold_invalider_nachzuegler_ignoriert(monkeypatch):
+    """Nachzügler mit invalidem Payload löst late NICHT aus (best-effort)."""
+    spaet = []
+
+    async def fake_agent(key, prompt, timeout, **kw):
+        if key == "k3":
+            await asyncio.sleep(0.1)
+            return (1, "", "kaputt")
+        return (0, key, "")
+
+    async def late(val):
+        spaet.append(val)
+
+    monkeypatch.setattr(pipeline, "run_agent", fake_agent)
+    monkeypatch.setattr(pipeline, "kill_process", lambda k: None)
+    monkeypatch.setattr(pipeline, "_HEDGE_NACH_S", 0)
+    slots = [{"key": f"k{i}", "prompt": "p", "role": "quick", "capabilities": "none",
+              "payload": lambda r: r[1]} for i in (1, 2, 3)]
+    res = await pipeline._race("t", "Test", slots, 2, 60, "claude", late=late)
+    assert res is not None
+    await asyncio.sleep(0.25)
+    assert spaet == []
+
+
+async def test_hedge_zwilling_ersetzt_restart(monkeypatch):
+    """Scheitert das Original, während der Zwilling noch läuft, gibt es KEINEN
+    zusätzlichen Restart — der Zwilling ist der Retry."""
+    calls = []
+
+    async def fake_agent(key, prompt, timeout, **kw):
+        calls.append(key)
+        if key.endswith("-h"):
+            await asyncio.sleep(0.2)
+            return (0, "zwilling", "")
+        await asyncio.sleep(0.1)
+        return (1, "", "kaputt")  # Fehler NACH dem Hedge-Start
+
+    monkeypatch.setattr(pipeline, "run_agent", fake_agent)
+    monkeypatch.setattr(pipeline, "kill_process", lambda k: None)
+    monkeypatch.setattr(pipeline, "_HEDGE_NACH_S", 0.05)
+    res = await pipeline._race("t", "Test", [_slot()], 1, 0.1, "claude")
+    assert res == ["zwilling"]
+    assert calls == ["k1", "k1-h"]  # kein dritter Spawn

backend/tests/test_repair.py

@@ -0,0 +1,300 @@
+"""Befund-Repair: gezielte Aktionen aus dem QA-Report (repair.py) — ohne Flow, gegen Test-DB."""
+
+import json
+
+import pytest
+
+import repair
+import qa as qa_mod
+
+TOPIC = "reparatur"
+
+
+def _report(**over):
+    r = {"topic": TOPIC, "note": 9.0, "quoten": {}, "hygiene": [], "dubletten": [],
+         "fremd": [], "unecht": [], "luecken": [], "artefakte": {"verwaiste": []}}
+    r.update(over)
+    return r
+
+
+@pytest.fixture
+async def env(testdb, tmp_path, monkeypatch):
+    """Zwei fertige Blöcke auf beiden Boards + Subs/Artefakte + Sidecar-Dateien."""
+    db = testdb
+    monkeypatch.setattr(qa_mod, "QA_DIR", tmp_path / "qa")
+    files = {"sidecar": tmp_path / "sidecar.json", "facts": tmp_path / "facts.json",
+             "question_pattern": tmp_path / "qp.json", "sub_roh": tmp_path / "roh.json",
+             "artefakte": tmp_path / "artefakte.json"}
+    monkeypatch.setattr(repair, "_blocks_files", lambda t: files)
+    # frisches Abschluss-QA im Repair stumm schalten (eigener Test deckt qa_report ab)
+    async def _no_qa(topic, llm=False):
+        return None
+    monkeypatch.setattr(qa_mod, "qa_report", _no_qa)
+
+    async def _seed(title, desc, subs=1):
+        norm = repair._norm_title(title)
+        cid = "b-" + norm.replace(" ", "")[:10]
+        await db.kanban_upsert_card(TOPIC, "inventory", cid, "block", "done_block",
+                                    {"title": title, "description": desc, "sources": [f"{title}.txt"],
+                                     "readers": ["r1"], "mirrored_norm": norm})
+        await db.kanban_upsert_card(TOPIC, "artefacts", norm, "ablock", "done_artefact", {"title": title})
+        await db.upsert_block(TOPIC, norm, title, desc, [f"{title}.txt"])
+        await db.set_block_status(TOPIC, norm, "consensus")
+        for i in range(subs):
+            await db.put_subblock(TOPIC, norm, f"sub{i}", title, f"Sub {i}")
+        await db.put_sub_artifact(TOPIC, norm, "sub0", "flashcard", "{}", title, "Sub 0")
+        return cid
+
+    for p in files.values():
+        p.write_text("{}", encoding="utf-8")
+    (tmp_path / "qa" / TOPIC).mkdir(parents=True)
+
+    def write_report(r):
+        (tmp_path / "qa" / TOPIC / "r.json").write_text(json.dumps(r), encoding="utf-8")
+
+    return db, _seed, files, write_report
+
+
+async def test_merge_confirmed_duplicate(env, monkeypatch):
+    db, seed, files, write_report = env
+    cid_a = await seed("Alpha", "kurz")
+    cid_b = await seed("Alpha Problem", "deutlich längere Beschreibung — Gewinner")
+    write_report(_report(dubletten=[{"a": "Alpha", "b": "Alpha Problem", "llm": "ja"},
+                                    {"a": "Alpha", "b": "Beta", "llm": "nein"}]))
+    calls = []
+
+    async def fake_agent(key, prompt, timeout, **kw):
+        calls.append(prompt)
+        return 0, '{"relevant": {"1": "ja"}}', ""
+
+    monkeypatch.setattr(repair, "run_agent", fake_agent)
+    res = await repair.repair_befunde(TOPIC)
+    assert res["merges"] == ["Alpha → Alpha Problem"]
+    assert len(calls) == 1 and "Beta" not in calls[0]  # nur das llm=ja-Paar zum Judge
+    verlierer = await db.kanban_get_card(TOPIC, "inventory", cid_a)
+    assert verlierer["stage"] == "grouped" and verlierer["payload"]["merged_into"] == "Alpha Problem"
+    gewinner = await db.kanban_get_card(TOPIC, "inventory", cid_b)
+    assert "Alpha.txt" in gewinner["payload"]["sources"]  # Union
+    assert await db.kanban_get_card(TOPIC, "artefacts", "alpha") is None
+    assert not [r for r in await db.list_subblocks(TOPIC, "alpha")]
+
+
+async def test_fremd_removed_only_on_nein(env, monkeypatch):
+    db, seed, files, write_report = env
+    cid_f = await seed("Fremdling", "gehört nicht rein")
+    cid_e = await seed("Echter", "belegt")
+    write_report(_report(fremd=["Fremdling", "Echter"]))
+
+    async def fake_agent(key, prompt, timeout, **kw):
+        if "-st-" in key:  # Stichentscheid über den strittigen „Echter": behalten
+            return 0, '{"relevant": {"1": "ja"}}', ""
+        return 0, '{"relevant": {"1": "nein", "2": "ja"}}', ""
+
+    monkeypatch.setattr(repair, "run_agent", fake_agent)
+    monkeypatch.setattr(repair, "source_folder", lambda t: None)
+    res = await repair.repair_befunde(TOPIC)
+    assert res["entfernt"] == ["Fremdling"]
+    weg = await db.kanban_get_card(TOPIC, "inventory", cid_f)
+    assert weg["stage"] == "rejected" and weg["payload"]["reason"] == "qa-fremd"
+    bleibt = await db.kanban_get_card(TOPIC, "inventory", cid_e)
+    assert bleibt["stage"] == "done_block"
+
+
+async def test_judge_failure_keeps_everything(env, monkeypatch):
+    db, seed, files, write_report = env
+    cid = await seed("Wackelig", "unsicher")
+    write_report(_report(unecht=["Wackelig"]))
+
+    async def broken_agent(key, prompt, timeout, **kw):
+        raise RuntimeError("boom")
+
+    monkeypatch.setattr(repair, "run_agent", broken_agent)
+    res = await repair.repair_befunde(TOPIC)
+    assert res["entfernt"] == []
+    card = await db.kanban_get_card(TOPIC, "inventory", cid)
+    assert card["stage"] == "done_block"  # fail-open
+
+
+async def test_hygiene_cleans_title_norm_invariant(env, monkeypatch):
+    db, seed, files, write_report = env
+    cid = await seed("**Fetter Titel**", "beschreibung")
+    files["sidecar"].write_text(json.dumps({"**Fetter Titel**": ["s"]}), encoding="utf-8")
+    write_report(_report(hygiene=[{"titel": "**Fetter Titel**", "probleme": ["markdown"]}]))
+
+    async def no_agent(*a, **kw):
+        raise AssertionError("Hygiene braucht keinen Agenten")
+
+    monkeypatch.setattr(repair, "run_agent", no_agent)
+    res = await repair.repair_befunde(TOPIC)
+    assert res["hygiene"] == ["**Fetter Titel** → Fetter Titel"]
+    card = await db.kanban_get_card(TOPIC, "inventory", cid)
+    assert card["payload"]["title"] == "Fetter Titel"
+    assert json.loads(files["sidecar"].read_text()) == {"Fetter Titel": ["s"]}
+    rows = await db.list_blocks(TOPIC)
+    assert any(r["title"] == "Fetter Titel" and r["status"] == "consensus" for r in rows)
+
+
+async def test_no_report_is_clean_error(env):
+    db, seed, files, write_report = env
+    res = await repair.repair_befunde("gibtsnicht")
+    assert "fehler" in res
+
+
+async def test_abschluss_qa_misst_mit_llm(env, monkeypatch):
+    """Repair-Abschlussreport misst mit LLM — der llm=False-Report blendete
+    sub_dubletten aus und ließ die Note zwischen 10.0 und ~9 pendeln."""
+    db, seed, files, write_report = env
+    write_report(_report())
+    import qa as qa_mod
+    seen = {}
+
+    async def spy(topic, llm=False):
+        seen["llm"] = llm
+        return None
+
+    monkeypatch.setattr(qa_mod, "qa_report", spy)
+    await repair.repair_befunde(TOPIC)
+    assert seen["llm"] is True
+
+
+async def test_sub_dubletten_merge(env, monkeypatch):
+    """Bestätigtes Sub-Paar + Zweitmeinung ja → Verlierer variant, Frage/Artefakt
+    wandern zum Gewinner (bzw. fallen weg, wenn er den Typ schon hat)."""
+    db, seed, files, write_report = env
+    await seed("Alpha", "beschr")
+    norm = repair._norm_title("Alpha")
+    await db.put_subblock(TOPIC, norm, "gewinner sub", "Alpha", "Gewinner Sub",
+                          facts='{"key_points": ["a", "b"]}', status="consensus")
+    await db.put_subblock(TOPIC, norm, "verlierer sub", "Alpha", "Verlierer Sub",
+                          facts='{"key_points": ["x"]}', status="consensus")
+    await db.put_sub_artifact(TOPIC, norm, "verlierer sub", "example", "{}", "Alpha", "Verlierer Sub")
+    await db.upsert_question_pattern(TOPIC, norm, "verlierer sub", "Alpha", "Verlierer Sub", "Frage V?")
+    write_report(_report(sub_dubletten=[
+        {"a": "[Alpha] Gewinner Sub", "b": "[Alpha] Verlierer Sub", "llm": "ja"},
+        {"a": "[Alpha] Gibtsnicht", "b": "[Alpha] Verlierer Sub", "llm": "ja"}]))  # tote Zeile → skip
+
+    async def fake_agent(key, prompt, timeout, **kw):
+        assert "Gibtsnicht" not in prompt
+        return 0, '{"relevant": {"1": "ja"}}', ""
+
+    monkeypatch.setattr(repair, "run_agent", fake_agent)
+    res = await repair.repair_befunde(TOPIC)
+    assert res["sub_merges"] == ["Verlierer Sub → Gewinner Sub"]
+    rows = {r["sub_norm"]: r["status"] for r in await db.list_subblocks(TOPIC, norm)}
+    assert rows["verlierer sub"] == "variant" and rows["gewinner sub"] == "consensus"
+    arts = {(r["sub_norm"], r["type"]) for r in await db.get_sub_artefakte(TOPIC)}
+    assert ("gewinner sub", "example") in arts and ("verlierer sub", "example") not in arts
+    fragen = {r["sub_norm"]: r["question"] for r in await db.list_question_pattern(TOPIC)}
+    assert fragen.get("gewinner sub") == "Frage V?" and "verlierer sub" not in fragen
+
+
+async def test_sub_dubletten_zweitmeinung_nein(env, monkeypatch):
+    db, seed, files, write_report = env
+    await seed("Alpha", "beschr")
+    norm = repair._norm_title("Alpha")
+    await db.put_subblock(TOPIC, norm, "sub a", "Alpha", "Sub A", status="consensus")
+    await db.put_subblock(TOPIC, norm, "sub b", "Alpha", "Sub B", status="consensus")
+    write_report(_report(sub_dubletten=[{"a": "[Alpha] Sub A", "b": "[Alpha] Sub B", "llm": "ja"}]))
+
+    async def fake_agent(key, prompt, timeout, **kw):
+        return 0, '{"relevant": {"1": "nein"}}', ""
+
+    monkeypatch.setattr(repair, "run_agent", fake_agent)
+    res = await repair.repair_befunde(TOPIC)
+    assert res["sub_merges"] == []
+    rows = {r["sub_norm"]: r["status"] for r in await db.list_subblocks(TOPIC, norm)}
+    assert rows["sub a"] == rows["sub b"] == "consensus"
+
+
+async def test_sub_dubletten_stichentscheid_faltet(env, monkeypatch):
+    """Dissens QA (Befund) vs. Zweitmeinung (behalten) → Stichentscheid-Judge (Key -st)
+    entscheidet mit 2:1 für den Befund → Merge. Vorher pendelte die Note dauerhaft
+    unter 10 ohne Fix-Pfad („keine behebbaren Befunde" trotz Befund)."""
+    db, seed, files, write_report = env
+    await seed("Alpha", "beschr")
+    norm = repair._norm_title("Alpha")
+    await db.put_subblock(TOPIC, norm, "sub a", "Alpha", "Sub A",
+                          facts='{"key_points": ["a"]}', status="consensus")
+    await db.put_subblock(TOPIC, norm, "sub b", "Alpha", "Sub B", status="consensus")
+    write_report(_report(sub_dubletten=[{"a": "[Alpha] Sub A", "b": "[Alpha] Sub B", "llm": "ja"}]))
+
+    async def fake_agent(key, prompt, timeout, **kw):
+        if "-st-" in key:  # Stichentscheid bestätigt den QA-Befund
+            return 0, '{"relevant": {"1": "ja"}}', ""
+        return 0, '{"relevant": {"1": "nein"}}', ""  # Zweitmeinung widerspricht
+
+    monkeypatch.setattr(repair, "run_agent", fake_agent)
+    res = await repair.repair_befunde(TOPIC)
+    assert res["sub_merges"] == ["Sub B → Sub A"]
+    rows = {r["sub_norm"]: r["status"] for r in await db.list_subblocks(TOPIC, norm)}
+    assert rows["sub b"] == "variant" and rows["sub a"] == "consensus"
+
+
+async def test_stichentscheid_behalten_persistiert_freispruch(env, monkeypatch):
+    """2:1 „behalten" (Zweitmeinung + j3 einig gegen den QA-Befund) → Freispruch wird
+    persistiert und der Report des nächsten qa_report zählt das Paar nicht mehr —
+    vorher pendelte die Note dauerhaft unter 10 ohne Fix-Pfad."""
+    import qa as qa_mod
+    db, seed, files, write_report = env
+    await seed("Alpha", "beschr")
+    norm = repair._norm_title("Alpha")
+    await db.put_subblock(TOPIC, norm, "sub a", "Alpha", "Sub A", status="consensus")
+    await db.put_subblock(TOPIC, norm, "sub b", "Alpha", "Sub B", status="consensus")
+    write_report(_report(sub_dubletten=[{"a": "[Alpha] Sub A", "b": "[Alpha] Sub B", "llm": "ja"}]))
+
+    async def fake_agent(key, prompt, timeout, **kw):
+        return 0, '{"relevant": {"1": "nein"}}', ""  # beide Repair-Judges: behalten
+
+    monkeypatch.setattr(repair, "run_agent", fake_agent)
+    res = await repair.repair_befunde(TOPIC)
+    assert res["sub_merges"] == [] and len(res["freigesprochen"]) == 1
+    frei = qa_mod.lade_freispruch(TOPIC)
+    key = qa_mod._paar_key("[Alpha] Sub A", "[Alpha] Sub B")
+    assert key in set(frei.get("sub_dubletten") or [])
+    # QA-Seite: bestätigtes, aber freigesprochenes Paar zählt nicht in die Quote
+    sd = [{"a": "[Alpha] Sub A", "b": "[Alpha] Sub B", "llm": "ja"}]
+    frei_sub = set(frei["sub_dubletten"])
+    zaehlt = sum(1 for p in sd if p.get("llm") == "ja"
+                 and qa_mod._paar_key(p["a"], p["b"]) not in frei_sub)
+    assert zaehlt == 0
+
+
+async def test_fremd_stichentscheid_behalten(env, monkeypatch):
+    """Dissens bei fremd, Stichentscheid sagt ebenfalls behalten (ja) → Block bleibt
+    (fail-open bei 1:2 gegen den Befund)."""
+    db, seed, files, write_report = env
+    await seed("Alpha", "beschr")
+    write_report(_report(fremd=["Alpha"]))
+
+    async def fake_agent(key, prompt, timeout, **kw):
+        return 0, '{"relevant": {"1": "ja"}}', ""  # beide: belegt/behalten
+
+    monkeypatch.setattr(repair, "run_agent", fake_agent)
+    res = await repair.repair_befunde(TOPIC)
+    assert res["entfernt"] == []
+
+
+async def test_waisen_cleanup(env, monkeypatch):
+    """Artefakte/Fragen auf verworfene oder fehlende Subs fliegen; lebende und
+    mehrdeutig-präfixige bleiben."""
+    db, seed, files, write_report = env
+    await seed("Alpha", "beschreibung")  # legt sub0 (consensus) + flashcard auf sub0 an
+    norm = repair._norm_title("Alpha")
+    await db.put_subblock(TOPIC, norm, "weg", "Alpha", "Weg", status="discarded")
+    await db.put_subblock(TOPIC, norm, "doppel: eins", "Alpha", "Doppel eins")
+    await db.put_subblock(TOPIC, norm, "doppel: zwei", "Alpha", "Doppel zwei")
+    await db.put_sub_artifact(TOPIC, norm, "weg", "flashcard", "{}", "Alpha", "Weg")      # tot
+    await db.put_sub_artifact(TOPIC, norm, "fehlt", "example", "{}", "Alpha", "Fehlt")    # tot
+    await db.put_sub_artifact(TOPIC, norm, "doppel", "example", "{}", "Alpha", "Doppel")  # mehrdeutig → bleibt
+    await db.upsert_question_pattern(TOPIC, norm, "fehlt", "Alpha", "Fehlt", "Frage?")    # tot
+    write_report(_report())
+
+    async def no_agent(*a, **kw):
+        raise AssertionError("Aufräumen braucht keinen Agenten")
+
+    monkeypatch.setattr(repair, "run_agent", no_agent)
+    res = await repair.repair_befunde(TOPIC)
+    assert res["aufgeraeumt"] == 3
+    rest = {(r["sub_norm"], r["type"]) for r in await db.get_sub_artefakte(TOPIC)}
+    assert rest == {("sub0", "flashcard"), ("doppel", "example")}
+    assert not [r for r in await db.list_question_pattern(TOPIC)]

backend/tests/test_roles.py

@@ -0,0 +1,41 @@
+"""Role routing: resolve_role maps (run_provider, role) → (provider, model) across stacks."""
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+import config
+from config import PROVIDERS, resolve_role
+
+
+def test_default_quick_routes_to_minimax(monkeypatch):
+    monkeypatch.setitem(config.ROLE_ROUTING, "quick", "minimax")
+    assert resolve_role("claude", "quick") == ("minimax", PROVIDERS["minimax"]["quick"])
+
+
+def test_default_judge_routes_to_claude(monkeypatch):
+    monkeypatch.setitem(config.ROLE_ROUTING, "judge", "claude")
+    assert resolve_role("minimax", "judge") == ("claude", PROVIDERS["claude"]["judge"])
+
+
+def test_empty_routing_keeps_run_provider(monkeypatch):
+    monkeypatch.setitem(config.ROLE_ROUTING, "fast", "")
+    assert resolve_role("claude", "fast") == ("claude", PROVIDERS["claude"]["fast"])
+    assert resolve_role("minimax", "fast") == ("minimax", PROVIDERS["minimax"]["fast"])
+
+
+def test_explicit_model_syntax(monkeypatch):
+    monkeypatch.setitem(config.ROLE_ROUTING, "guide", "claude:claude-opus-4-8")
+    assert resolve_role("minimax", "guide") == ("claude", "claude-opus-4-8")
+
+
+def test_unknown_target_falls_back_to_run_provider(monkeypatch):
+    monkeypatch.setitem(config.ROLE_ROUTING, "quick", "gibtsnicht")
+    assert resolve_role("claude", "quick") == ("claude", PROVIDERS["claude"]["quick"])
+
+
+def test_unknown_role_yields_empty_model():
+    provider, model = resolve_role("claude", "nope")
+    assert provider == "claude"
+    assert model == ""

backend/tests/test_subblocks.py

@@ -0,0 +1,190 @@
+"""Subbaustein-Helfer: Varianten-Cluster, Evidence-Packs, Outline-Review, Hash/Key-Auflösung.
+Die verschmolzene Block-Pipeline (Generate/Verify/Artefakte) testet tests/test_block_calls.py."""
+
+import json
+
+import numpy as np
+
+import blocks as blx
+from pipeline import GenContext
+
+TOPIC = "t"
+
+
+# ── _variant_clusters (pure) ─────────────────────────────────────────────────────────
+
+def _sims(pairs, n):
+    m = np.eye(n)
+    for i, j, v in pairs:
+        m[i][j] = m[j][i] = v
+    return m
+
+
+def test_variant_clusters_folds_paraphrases():
+    titles = ["Harte Umbrüche brauchen Marker", "Harte Umbrüche erfordern explizite Marker!",
+              "Tabs werden expandiert"]
+    cl = blx._variant_clusters(titles, [1, 1, 1], _sims([(0, 1, 0.95)], 3))
+    by_rep = {c["rep"]: c for c in cl}
+    assert by_rep[1]["mentions"] == 2 and sorted(by_rep[1]["members"]) == [0, 1]  # longest wins
+    assert by_rep[2]["mentions"] == 1
+
+
+def test_variant_clusters_negation_guard():
+    titles = ["Fenced können Absätze unterbrechen", "Fenced können Absätze nicht unterbrechen"]
+    cl = blx._variant_clusters(titles, [1, 1], _sims([(0, 1, 0.95)], 2))
+    assert len(cl) == 2  # antonyms never merge, no matter the cosine
+
+
+# ── Outline-Review ───────────────────────────────────────────────────────────────────
+
+def test_outline_review_schema():
+    valid = {1, 2, 3, 4, 5, 6}
+    ok = blx._outline_review_schema({"moves": {"3": 2}}, valid, 2, 6)
+    assert ok == {3: 2}
+    assert blx._outline_review_schema({"moves": {}}, valid, 2, 6) == {}
+    assert blx._outline_review_schema({"moves": {"9": 1}}, valid, 2, 6) is None  # unknown block
+    assert blx._outline_review_schema({"moves": {"1": 5}}, valid, 2, 6) is None  # chapter range
+    assert blx._outline_review_schema({"moves": {"1": 2, "2": 2, "3": 2}}, valid, 2, 6) is None  # mass move
+    assert blx._outline_review_schema({"chapters": []}, valid, 2, 6) is None
+
+
+async def test_outline_review_moves_block(testdb, tmp_path, monkeypatch):
+    """Review verschiebt einen fehlplatzierten Block; kaputtes Review lässt den Plan unverändert."""
+    entries = {i: f"Block {i} — d" for i in range(1, 7)}
+    slots = [tmp_path / f"outline-{i}.json" for i in (1, 2, 3)]
+    plan_a = {"chapters": [{"title": "K1", "numbers": [1, 2, 6]}, {"title": "K2", "numbers": [3, 4, 5]}]}
+    for p in slots[:2]:
+        p.write_text(json.dumps(plan_a), encoding="utf-8")
+    files = {"arbeit": tmp_path, "outline": tmp_path / "outline.json", "outline_slots": slots,
+             "facts": tmp_path / "facts.json"}
+
+    review_out = {"val": {"moves": {"6": 2}}}
+
+    async def fake_slot(ctx, label, *, key, prompt, role, capabilities, payload, timeout, on_line=None):
+        out = None
+        if key.endswith("outline-prereqs"):
+            out = {"prereqs": {}}
+        elif key.endswith("outline-judge"):
+            out = plan_a
+        elif key.endswith("outline-review"):
+            out = review_out["val"]
+        if out is not None:  # neue Semantik: Antwort als TEXT, der Sink persistiert
+            return "ok", payload((0, json.dumps(out), ""))
+        return "ok", payload(None)
+
+    monkeypatch.setattr(blx, "run_single_slot", fake_slot)
+    ctx = GenContext(topic=TOPIC, provider="claude", is_cancelled=lambda: False)
+    plan = await blx._outline_block(ctx, lambda *a, **k: None, files, entries, "")
+    assert plan["chapters"][0]["numbers"] == [1, 2]
+    assert plan["chapters"][1]["numbers"] == [3, 4, 5, 6]
+
+    # broken review (mass move) → schema rejects, plan unchanged
+    review_out["val"] = {"moves": {"1": 2, "2": 2, "3": 1}}
+    (tmp_path / "outline-review.json").unlink()
+    (tmp_path / "outline.json").unlink()
+    plan2 = await blx._outline_block(ctx, lambda *a, **k: None, files, entries, "")
+    assert plan2["chapters"][0]["numbers"] == [1, 2, 6]
+
+
+# ── Inline-Evidenz (Evidence-Packs für die verschmolzenen Calls) ─────────────────────
+
+def _corpus(tmp_path):
+    d = tmp_path / "korpus"
+    d.mkdir()
+    (d / "Skript.txt").write_text(
+        "Kapitel 1\nAlpha Grundlagen: der Kernbegriff.\nMehr Text dazu.\n\n"
+        "Kapitel 2\nGamma Randnotiz ohne Bezug.\n", encoding="utf-8")
+    (d / "Aufgaben.txt").write_text("Übung 1\nAlpha Vertiefung der Konzepte.\n", encoding="utf-8")
+    return d
+
+
+def test_evidence_pack_selects_matching_sections(tmp_path):
+    d = _corpus(tmp_path)
+    pack = blx._evidence_pack(d, None, ["Alpha Grundlagen"])
+    assert "── Skript.txt" in pack and "Kernbegriff" in pack
+    pack2 = blx._evidence_pack(d, ["Aufgaben.txt"], ["Alpha"])  # genannte Quellen engen ein
+    assert "Skript.txt" not in pack2 and "Aufgaben.txt" in pack2
+    assert blx._evidence_pack(None, None, ["x"]) == ""  # kein Korpus → Selbst-Recherche bleibt
+
+
+def test_evidence_pack_budget_and_guarantee(tmp_path):
+    d = tmp_path / "korpus"
+    d.mkdir()
+    (d / "A.txt").write_text("Alpha wichtig. " * 50, encoding="utf-8")
+    (d / "B.txt").write_text("Beta anderes Thema. " * 50, encoding="utf-8")
+    pack = blx._evidence_pack(d, None, ["Alpha"], budget=10)
+    assert "Alpha" in pack  # Abdeckungs-Garantie schlägt das Budget
+    assert "Beta" not in pack  # Top-up respektiert das Budget
+
+
+def test_cite_ref_parses_positions(tmp_path):
+    d = _corpus(tmp_path)
+    files = blx._corpus_files(d, None)
+    f, lo, hi = blx._cite_ref("Skript.txt, Übung 6.47, Z.2-3", files)
+    assert f.name == "Skript.txt" and (lo, hi) == (2, 3)
+    f2, lo2, hi2 = blx._cite_ref("Aufgaben.txt Zeile 2", files)
+    assert f2.name == "Aufgaben.txt" and lo2 == hi2 == 2
+    assert blx._cite_ref("Skript.txt, Übung 6.47", files) is None  # keine Zeilenangabe
+    assert blx._cite_ref("Z.5 irgendwo", files) is None  # keine Datei
+    # englische Zitierformen (Quellen sind nicht immer deutsch)
+    f3, lo3, hi3 = blx._cite_ref("Skript.txt, line 2", files)
+    assert f3.name == "Skript.txt" and lo3 == hi3 == 2
+    f4, lo4, hi4 = blx._cite_ref("Aufgaben.txt, lines 1-2", files)
+    assert f4.name == "Aufgaben.txt" and (lo4, hi4) == (1, 2)
+
+
+def test_cited_evidence_lines_and_fallback(tmp_path):
+    d = _corpus(tmp_path)
+    ev = blx._cited_evidence(d, None, ["Skript.txt, Z.2"], ["Alpha"])
+    assert "── Skript.txt · Z." in ev and "Kernbegriff" in ev
+    ev2 = blx._cited_evidence(d, None, ["ohne Position"], ["Alpha Grundlagen"])
+    assert "Kernbegriff" in ev2  # Keyword-Fallback
+
+
+def test_sink_json_writes_only_valid(tmp_path):
+    p = tmp_path / "level-final-c1.json"
+    ok = blx._sink_json((0, 'Vorab {"levels": {"1": "beginner"}} nach', ""), p,
+                        lambda d: blx._levels_schema(d, {1}))
+    assert ok == {1: "beginner"}
+    assert json.loads(p.read_text(encoding="utf-8"))["levels"]["1"] == "beginner"
+    bad = blx._sink_json((0, "kein json", ""), tmp_path / "x.json", lambda d: d)
+    assert bad is None and not (tmp_path / "x.json").exists()
+
+
+def test_material_folder_fallbacks(monkeypatch, tmp_path):
+    """Echte Quelle gewinnt; sonst arbeit/material mit Inhalt; sonst None."""
+    monkeypatch.setattr(blx, "source_folder", lambda t: tmp_path / "quelle")
+    assert blx.material_folder("t") == tmp_path / "quelle"
+    monkeypatch.setattr(blx, "source_folder", lambda t: None)
+    monkeypatch.setattr(blx, "arbeit_dir", lambda t: tmp_path / "arbeit")
+    assert blx.material_folder("t") is None  # kein Material-Ordner
+    md = tmp_path / "arbeit" / "material"
+    md.mkdir(parents=True)
+    assert blx.material_folder("t") is None  # leer zählt nicht
+    (md / "research-1.txt").write_text("x", encoding="utf-8")
+    assert blx.material_folder("t") == md
+
+
+def test_sub_key_resolves_short_titles():
+    """Artefakt-Agenten echoen den Kurztitel; der Sub-Key heißt 'kurztitel: beschreibung'.
+    Eindeutiger Präfix wird aufgelöst, Mehrdeutiges und Fehlendes bleibt unverändert."""
+    import board_artefacts as ba
+    existing = {"autolink mit url: erzeugt link", "bilder: bindet bilder ein",
+                "doppel: eins", "doppel: zwei", "exakt"}
+    assert ba._sub_key(existing, "exakt") == "exakt"
+    assert ba._sub_key(existing, "autolink mit url") == "autolink mit url: erzeugt link"
+    assert ba._sub_key(existing, "doppel") == "doppel"        # mehrdeutig → unverändert
+    assert ba._sub_key(existing, "fehlt") == "fehlt"          # kein Treffer → unverändert
+    # Fuzzy: Paraphrase/Kürzung ohne Doppelpunkt-Präfix löst eindeutig auf
+    lang = {"der backslash selbst muss mit escaped werden, um literal zu erscheinen"}
+    assert ba._sub_key(lang, "der backslash selbst muss mit escaped werden") == next(iter(lang))
+    assert ba._sub_key(lang | {"der backslash am zeilenende"}, "der backslash") == "der backslash"  # mehrdeutig
+
+
+def test_subs_hash_invalidiert_bei_neuem_zuschnitt():
+    """Gleicher Sub-Satz → gleicher Hash (Resume greift); geänderter → neuer Hash.
+    raw-Form (Strings) und sidecar-Form (dicts) hashen identisch."""
+    a = {"Block": ["s1", "s2"]}
+    assert blx._subs_hash(a) == blx._subs_hash({"Block": ["s1", "s2"]})
+    assert blx._subs_hash(a) != blx._subs_hash({"Block": ["s1", "s3"]})
+    assert blx._subs_hash(a) == blx._subs_hash({"Block": [{"title": "s1"}, {"title": "s2"}]})

backend/tests/test_train.py

@@ -0,0 +1,162 @@
+"""Training-Harness: Registry↔config, ENV-Override, ACO-Trainer (Stub-Runner), Soll-Abgleich."""
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+import config
+import train_params
+from train import AmeisenTrainer, score
+from train_lauf import soll_abgleich
+
+BACKEND = Path(__file__).resolve().parent.parent
+
+
+def test_registry_spiegelt_config():
+    """Jeder Registry-Parameter existiert in config mit identischem Default, flow-sicheren
+    Rändern und einer Fidelity-Zuordnung — sonst optimiert der Trainer Phantome."""
+    for name, p in train_params.PARAMS.items():
+        assert getattr(config, name, None) == p["default"], name
+        assert p["min"] <= p["default"] <= p["max"], name
+        assert p["step"] > 0, name
+        assert p["fidelity"] in ("board2", "voll"), name
+
+
+def test_creator_params_override_wirkt_im_subprozess():
+    out = subprocess.run(
+        [sys.executable, "-c", "import config; print(config.FACTS_CHUNK_SUBS, config.TIMEOUTS['subblock_check'][0])"],
+        capture_output=True, text=True, cwd=BACKEND,
+        env={"PATH": "/usr/bin:/bin", "CREATOR_PARAMS": '{"FACTS_CHUNK_SUBS": 6, "TIMEOUT_subblock_check_base": 77}'})
+    assert out.stdout.split() == ["6", "77"], out.stderr
+
+
+def test_creator_params_unbekannter_name_bricht_ab():
+    out = subprocess.run([sys.executable, "-c", "import config"],
+                         capture_output=True, text=True, cwd=BACKEND,
+                         env={"PATH": "/usr/bin:/bin", "CREATOR_PARAMS": '{"GIBT_ES_NICHT": 1}'})
+    assert out.returncode != 0 and "GIBT_ES_NICHT" in out.stderr
+
+
+def _metrics(note=8.0, dauer=10.0, tokens=1_000_000, **quoten):
+    return {"note": note, "quoten": quoten, "quoten_artefakte": {},
+            "dauer_min": dauer, "tokens": {"input": tokens, "output": 0}, "agents": {}}
+
+
+def _stub(score_fn):
+    """Runner-Paar (F1/F2 + F0) für Tests: score_fn(params) → Metriken."""
+    calls = []
+
+    async def runner(params, fidelity, suffix=""):
+        calls.append((dict(params), fidelity))
+        return score_fn(params)
+
+    async def f0(params):
+        return {"ok": True, "invarianten_fehler": [], "calls": 100}
+
+    runner.calls = calls
+    return runner, f0
+
+
+def _trainer(tmp_path, runner, f0, **kw):
+    args = dict(max_trials=999, max_stunden=1, ameisen=3, seed=7, f2_intervall=1000)
+    args.update(kw)
+    return AmeisenTrainer(tmp_path / "s", runner=runner, runner_f0=f0, **args)
+
+
+async def test_aco_konvergiert_auf_optimum(tmp_path):
+    """Gepflanztes Optimum (GEN_PANEL=3) wird gefunden und bestätigt übernommen;
+    die Pheromon-Spur konzentriert sich dort."""
+    def bewertung(params):
+        return _metrics(note=9.5, dauer=7.0) if params.get("GEN_PANEL") == 3 else _metrics()
+
+    runner, f0 = _stub(bewertung)
+    t = _trainer(tmp_path, runner, f0, max_trials=120)
+    best = await t.run()
+    assert best.get("GEN_PANEL") == 3
+    taus = t.pheromon["GEN_PANEL"]
+    assert max(taus, key=lambda k: taus[k]) == "3"
+
+
+async def test_uebernahme_braucht_bestaetigung(tmp_path):
+    """Einmaliger Glückstreffer ohne bestätigten Zweitlauf wird nicht Bester."""
+    zustand = {"mal": 0}
+
+    def bewertung(params):
+        if params.get("GEN_PANEL") == 3:
+            zustand["mal"] += 1
+            return _metrics(note=9.5) if zustand["mal"] == 1 else _metrics(note=8.0)
+        return _metrics()
+
+    runner, f0 = _stub(bewertung)
+    t = _trainer(tmp_path, runner, f0, max_trials=40)
+    best = await t.run()
+    assert best.get("GEN_PANEL") != 3
+
+
+async def test_f0_filter_verwirft_kaputte_kandidaten(tmp_path):
+    """Kandidaten mit Invarianten-Fehlern erreichen nie einen bezahlten Lauf."""
+    runner, _f0 = _stub(lambda p: _metrics())
+
+    async def f0_kaputt(params):
+        if params:  # nur Nicht-Baseline
+            return {"ok": True, "invarianten_fehler": ["kaputt"], "calls": 100}
+        return {"ok": True, "invarianten_fehler": [], "calls": 100}
+
+    t = _trainer(tmp_path, runner, f0_kaputt, max_trials=20)
+    await t.run()
+    bezahlt_mit_params = [c for c, _f in runner.calls if c]
+    assert bezahlt_mit_params == []  # nur Baselines liefen
+
+
+async def test_resume_laedt_pheromon_und_cache(tmp_path):
+    def bewertung(params):
+        return _metrics(note=9.5) if params.get("GEN_PANEL") == 3 else _metrics()
+
+    runner, f0 = _stub(bewertung)
+    t = _trainer(tmp_path, runner, f0, max_trials=60)
+    await t.run()
+    best, tau = t.best_params, dict(t.pheromon["GEN_PANEL"])
+    runner2, f02 = _stub(bewertung)
+    t2 = _trainer(tmp_path, runner2, f02, max_trials=0)  # kein Budget: alles aus Persistenz
+    assert t2.best_params == best
+    assert t2.pheromon["GEN_PANEL"] == tau
+
+
+async def test_budget_stoppt(tmp_path):
+    runner, f0 = _stub(lambda p: _metrics())
+    t = _trainer(tmp_path, runner, f0, max_trials=4)
+    await t.run()
+    assert len(runner.calls) <= 4
+
+
+def test_score_richtungen():
+    basis = _metrics()
+    assert score(_metrics(note=9.0), basis) > score(basis, basis)
+    assert score(_metrics(dauer=20.0, tokens=2_000_000), basis) < score(basis, basis)
+    assert score(_metrics(fremd=0.2, luecken=0.1), basis) < score(basis, basis)
+    mit_soll = dict(_metrics(), soll={"f1": 1.0})
+    ohne_soll = dict(_metrics(), soll={"f1": 0.5})
+    assert score(mit_soll, basis) > score(ohne_soll, basis)
+
+
+def test_soll_abgleich():
+    soll = {"bloecke": [{"titel": "Symmetrische Verschlüsselung"},
+                        {"titel": "Asymmetrische Verschlüsselung",
+                         "alternativen": ["Public-Key-Kryptographie"]},
+                        {"titel": "Digitale Signaturen"}]}
+    r = soll_abgleich(["Symmetrische Verschlüsselung", "Public-Key-Kryptographie", "Quantencomputer"], soll)
+    assert r["fehlend"] == ["Digitale Signaturen"]
+    assert r["extra"] == ["Quantencomputer"]
+    assert 0 < r["f1"] < 1
+
+
+async def test_copy_topic_dupliziert_karten_und_bloecke(testdb):
+    db = testdb
+    await db.kanban_upsert_card("q", "inventory", "b1", "block", "done_block", {"title": "Alpha"})
+    await db.upsert_block("q", "alpha", "Alpha", "Beschreibung", ["s1"], "r1")
+    await db.copy_topic("q", "z")
+    karten = await db.kanban_cards("z")
+    assert [c["card_id"] for c in karten] == ["b1"]
+    bloecke = await db.list_blocks("z")
+    assert [b["title"] for b in bloecke] == ["Alpha"]

backend/textkit.py

@@ -0,0 +1,250 @@
+"""Pure text helpers: title normalization, list parsers, chunk splitting.
+
+No state, no IO — safe to import anywhere.
+"""
+
+import re
+import unicodedata
+
+_CATEGORIES = ("KERN", "WICHTIG", "REST")  # only for the legacy-format reader now
+
+
+def _norm_title(s: str) -> str:
+    """Normalize a title for key comparison.
+
+    NFKC + casefold catch Unicode variants; quotes, markdown emphasis
+    and dash variants come out of AI output in every shape.
+    """
+    s = unicodedata.normalize("NFKC", s)
+    s = re.sub(r"[`'\"<>„“”‚’«»*_]", "", s)
+    s = re.sub(r"[–—‐]", "-", s)
+    s = re.sub(r"\s+", " ", s).strip().strip(".:;").strip()
+    return s.casefold()
+
+
+def _title(entry: str) -> str:
+    return entry.split(" — ")[0].strip() or entry
+
+
+def clean_title(s: str) -> str:
+    """Strip markdown noise from a DISPLAY title (norm keys use _norm_title).
+    Only clearly-markdown characters go: `**` pairs and backticks. Single `*`,
+    underscores and pipes stay — they are legitimate in math titles
+    („2|prec, pi∈{1,2}|Cmax", „x_i", „P*")."""
+    s = (s or "").replace("**", "").replace("`", "")
+    return re.sub(r"\s+", " ", s).strip()
+
+
+def _unique_title(entries: dict[int, str]) -> dict[int, str]:
+    """Make titles unique (suffix " (2)", " (3)" …) so they work as keys."""
+    seen: dict[str, int] = {}
+    out: dict[int, str] = {}
+    for num, text in entries.items():
+        title = _title(text)
+        key = _norm_title(title)
+        seen[key] = seen.get(key, 0) + 1
+        if seen[key] > 1:
+            rest = text.split(" — ", 1)
+            text = f"{title} ({seen[key]})" + (f" — {rest[1]}" if len(rest) == 2 else "")
+    # a second pass isn't needed: suffixes practically never collide
+        out[num] = text
+    return out
+
+
+
+
+def _title_index(entries: dict[int, str]) -> dict[str, int]:
+    return {_norm_title(_title(text)): num for num, text in entries.items()}
+
+
+def _resolve_title(idx: dict[str, int], t: str) -> int | None:
+    """Title → number; tolerates trailing descriptions ("Title — …")."""
+    if not isinstance(t, str):
+        return None
+    return idx.get(_norm_title(t)) or idx.get(_norm_title(_title(t)))
+
+
+def _norm_dash(s: str) -> str:
+    """Dash variants (en/em/figure/bar) with whitespace on AT LEAST ONE side → uniform separator ' — '.
+    Some models (especially non-western ones) use an en-dash "–" instead of the em-dash; without
+    normalization the ` — ` split fails entirely and the whole entry becomes the title. A one-sided
+    space ("Titel —Beschreibung" / "Titel— Beschreibung") also breaks the split and leaks the source
+    filename into the description — so a dash with a space on either side is repaired too. The ASCII
+    hyphen "-" is deliberately NOT in the class (would split "n - 1"/"3-SAT"); requiring ≥1 surrounding
+    space keeps glued compounds like "Backtracking—Verfahren" and number ranges like "12–15" untouched."""
+    return re.sub(r"\s*[‒–—―]\s+|\s+[‒–—―]\s*", " — ", s)
+
+
+def _parse_selection(text: str) -> dict[int, str]:
+    """Parse a block list: `N. Title — short description` per line."""
+    entries: dict[int, str] = {}
+    last = None
+    for line in text.splitlines():
+        m = re.match(r"\s*(\d+)[.)]\s+(.*\S)", line)
+        if m:
+            last = int(m.group(1))
+            entries[last] = _norm_dash(m.group(2))
+        elif last is not None and line.strip():
+            entries[last] += " " + _norm_dash(line.strip())
+    return entries
+
+
+def _parse_categories(text: str) -> dict[str, list[str]]:
+    """Legacy-format reader: final block file with ## KERN/WICHTIG/REST sections."""
+    cats: dict[str, list[str]] = {}
+    current = None
+    for line in text.splitlines():
+        s = line.strip()
+        m = re.match(r"#+\s*(KERN|WICHTIG|REST)\b", s, re.IGNORECASE)
+        if m:
+            current = m.group(1).upper()
+            cats.setdefault(current, [])
+            continue
+        m = re.match(r"(\d+)[.)]\s+(.*\S)", s)
+        if m and current:
+            cats[current].append(m.group(2))
+    return cats
+
+
+def _load_blocks(text: str) -> dict[int, str]:
+    """Load the final block file — sorted list (new) or categories (legacy format)."""
+    if re.search(r"^#+\s*KERN\b", text, re.IGNORECASE | re.MULTILINE):
+        cats = _parse_categories(text)
+        texts = [t for cat in _CATEGORIES for t in cats.get(cat, [])]
+        return {i: t for i, t in enumerate(texts, 1)}
+    return _parse_selection(text)
+
+
+_FRAGMENT_KAPITEL_RE = re.compile(r"<!--\s*kapitel\s*:\s*(.*?)\s*-->", re.IGNORECASE)
+_FRAGMENT_SECTION_RE = re.compile(r"<!--\s*section\s*:\s*(.*?)\s*-->", re.IGNORECASE)
+_FRAGMENT_SUB_RE = re.compile(r"<!--\s*sub\s*:\s*(.*?)\s*-->", re.IGNORECASE)
+_FRAGMENT_BAUSTEIN_RE = re.compile(r"<!--\s*block\s*:\s*(.*?)\s*-->", re.IGNORECASE)
+# Two reading layers per section: compact (key sentences) + detailed (explanation).
+_FRAGMENT_KOMPAKT_RE = re.compile(r"<!--\s*compact\s*-->", re.IGNORECASE)
+_FRAGMENT_AUSF_RE = re.compile(r"<!--\s*ausf(?:ü|ue)hrlich\s*-->", re.IGNORECASE)
+# Learning-path levels + peripheral; old difficulty values accepted for backward compatibility.
+_STUFEN = ("beginner", "advanced", "expert", "peripheral", "easy", "medium", "hard")
+
+
+def _parse_fragment(text: str) -> list[dict]:
+    """Parse a writer file → [{kapitel, title, md, compact, anker, anker_compact, subs}].
+
+    Two reading layers per section via `<!-- compact -->` / `<!-- ausführlich -->`. Within
+    both, `<!-- sub: level | title -->` markers mark a block per subblock; the same
+    sub title in both layers is merged → `sec["subs"] = [{level, title, md, compact}]`.
+    Text BEFORE the first sub marker is the anchor (framing) → `anker`/`anker_compact`.
+    `md`/`compact` stay the FULL version (anchor + all subs) — backward compatible.
+    """
+    sections: list[dict] = []
+    kapitel = None
+    current = None
+    cur_sub = None
+    cur_layer = "md"  # default: anything without a layer marker is the detailed version
+    for line in text.splitlines():
+        s = line.strip()
+        m = _FRAGMENT_KAPITEL_RE.match(s)
+        if m:
+            kapitel = m.group(1)
+            current = None
+            cur_sub = None
+            continue
+        m = _FRAGMENT_SECTION_RE.match(s)
+        if m:
+            current = {"chapters": kapitel, "title": m.group(1), "md": [], "compact": [],
+                       "anker_md": [], "anker_compact": [], "_submap": {}, "_suborder": []}
+            cur_sub = None
+            cur_layer = "md"
+            sections.append(current)
+            continue
+        if current is not None and _FRAGMENT_KOMPAKT_RE.match(s):
+            cur_layer = "compact"
+            cur_sub = None
+            continue
+        if current is not None and _FRAGMENT_AUSF_RE.match(s):
+            cur_layer = "md"
+            cur_sub = None
+            continue
+        m = _FRAGMENT_SUB_RE.match(s)
+        if m and current is not None:
+            parts = m.group(1).split("|", 1)
+            level = parts[0].strip().casefold()
+            title = parts[1].strip() if len(parts) == 2 else ""
+            key = title.casefold() or f"_pos{len(current['_suborder'])}"
+            cur_sub = current["_submap"].get(key)
+            if cur_sub is None:
+                cur_sub = {"level": level if level in _STUFEN else "beginner", "title": title, "md": [], "compact": []}
+                current["_submap"][key] = cur_sub
+                current["_suborder"].append(key)
+            elif level in _STUFEN:
+                cur_sub["level"] = level
+            continue
+        if current is not None:
+            current[cur_layer].append(line)
+            if cur_sub is not None:
+                cur_sub[cur_layer].append(line)
+            else:
+                current["anker_" + cur_layer].append(line)
+    out: list[dict] = []
+    for sec in sections:
+        subs = []
+        for key in sec["_suborder"]:
+            sub = sec["_submap"][key]
+            sub["md"] = "\n".join(sub["md"]).strip()
+            sub["compact"] = "\n".join(sub["compact"]).strip()
+            if sub["md"] or sub["compact"]:
+                subs.append(sub)
+        out.append({
+            "chapters": sec["chapters"], "title": sec["title"],
+            "md": "\n".join(sec["md"]).strip(),
+            "compact": "\n".join(sec["compact"]).strip(),
+            "anchor": "\n".join(sec["anker_md"]).strip(),
+            "anker_compact": "\n".join(sec["anker_compact"]).strip(),
+            "subs": subs,
+        })
+    return out
+
+
+def _parse_subblocks(text: str) -> dict[str, list[str]]:
+    """Parse a subblock file → {block title: [subblock, …]} in order.
+
+    Format: `<!-- block: Title -->` followed by list lines `- Subblock`.
+    """
+    out: dict[str, list[str]] = {}
+    current = None
+    for line in text.splitlines():
+        s = line.strip()
+        m = _FRAGMENT_BAUSTEIN_RE.match(s)
+        if m:
+            current = m.group(1).strip()
+            out.setdefault(current, [])
+            continue
+        if current is None:
+            continue
+        m = re.match(r"[-*]\s+(.*\S)", s)
+        if m:
+            out[current].append(m.group(1).strip())
+    return {k: v for k, v in out.items() if v}
+
+
+def _split_chunks(chapters: list[dict], n: int) -> list[list[dict]]:
+    """Split chapters into up to n contiguous chunks, balanced by section count."""
+    n = max(1, min(n, len(chapters)))
+    chunks: list[list[dict]] = []
+    current: list[dict] = []
+    count = 0
+    remaining_total = sum(len(c["nums"]) for c in chapters)
+    remaining_chunks = n
+    for ch in chapters:
+        current.append(ch)
+        count += len(ch["nums"])
+        if remaining_chunks > 1 and count >= remaining_total / remaining_chunks:
+            chunks.append(current)
+            remaining_total -= count
+            remaining_chunks -= 1
+            current = []
+            count = 0
+    if current:
+        chunks.append(current)
+    return chunks
+
+

backend/train.py

@@ -0,0 +1,342 @@
+"""make train: Ameisen-Optimierung (ACO) der Pipeline-Parameter — anytime, multi-fidelity.
+
+Prinzip: Pheromon-Gewichte je (Parameter, Stufe) steuern, welche Kandidaten („Ameisen")
+als Nächstes getestet werden. Gute Kandidaten verstärken ihre Stufen, Verdunstung hält
+die Suche offen — je länger der Trainer läuft, desto gezielter werden die Tests.
+Jederzeit stoppbar; der Stand (beste_params.json/report.md) ist immer aktuell.
+
+Fidelity-Kaskade pro Kandidat:
+  F0  Fake-E2E (train_f0.py, Sekunden, 0 Tokens): Invarianten + Struktur-Proxy — Filter.
+  F1  Frozen-Inventar (train_lauf.py --board2, ~5–8 min): misst Board-2/Guide-Parameter.
+  F2  Volllauf inkl. Soll-Abgleich: alle N Runden für den Besten + Inventar-Parameter.
+
+CLI: python3 train.py [--stunden 8] [--trials 60] [--ameisen 3] [--seed 0]
+     [--sitzung NAME] [--f2-intervall 5]
+     python3 train.py --init   (baut das Frozen-Inventar-Vorlage-Topic, einmalig)
+Ergebnis: storage/train/<sitzung>/{trials.jsonl, pheromon.json, report.md, beste_params.json}
+"""
+
+import argparse
+import asyncio
+import hashlib
+import json
+import os
+import random
+import sys
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+
+from config import STORAGE_DIR
+from train_params import PARAMS
+
+VORLAGE_TOPIC = "train-vorlage"
+BENCHMARK = "benchmarks/pruefstand"
+# Score-Gewichte: Qualität + Auswahl dominieren (Entwicklungsphase), Kosten ziehen ab.
+W_NOTE, W_AUSWAHL, W_ZEIT, W_TOKEN = 4.0, 4.0, 1.0, 1.0
+RHO = 0.2            # Pheromon-Verdunstung je Runde
+SPARSITY = 0.5       # Wahrscheinlichkeit, dass eine Ameise einen Parameter auf Default lässt
+F0_CALL_FAKTOR = 1.5  # Struktur-Proxy: mehr als 1.5× Baseline-Calls → Kandidat verworfen
+# Trainings-Fixa (Speed, kein Suchraum): Abschluss-QA ohne Judges, kurze Nachzügler-Gnade
+TRAIN_FIXA = {"ABSCHLUSS_QA_LLM": 0, "CONSENSUS_GRACE": 60}
+
+
+def stufen(name: str) -> list[float]:
+    p = PARAMS[name]
+    out, w = [], p["min"]
+    while w <= p["max"] + 1e-9:
+        out.append(round(w, 4))
+        w += p["step"]
+    return out
+
+
+def score(m: dict, basis: dict) -> float:
+    """Skalarer Vergleichswert. note 0–10; auswahl aus Soll-Abgleich (F2) oder MECE-Quoten;
+    Zeit/Tokens normiert auf die Baseline derselben Fidelity."""
+    if m.get("soll"):
+        auswahl = 10.0 * m["soll"]["f1"]
+    else:
+        q = m.get("quoten") or {}
+        qa_ = m.get("quoten_artefakte") or {}
+        auswahl = 10.0 * max(0.0, 1.0 - min(1.0, (
+            q.get("dubletten_verdacht", 0) + q.get("luecken", 0) + q.get("fremd", 0)
+            + qa_.get("sub_dubletten_verdacht", 0) + qa_.get("verwaiste", 0))))
+    zeit = (m.get("dauer_min") or 0) / max(basis.get("dauer_min") or 1, 0.1)
+    tok = _tokens(m) / max(_tokens(basis), 1)
+    return round(W_NOTE * (m.get("note") or 0) + W_AUSWAHL * auswahl
+                 - W_ZEIT * 10 * zeit - W_TOKEN * 10 * tok, 2)
+
+
+def _tokens(m: dict) -> int:
+    t = m.get("tokens") or {}
+    return int(t.get("input") or 0) + int(t.get("output") or 0)
+
+
+class AmeisenTrainer:
+    def __init__(self, sitzung: Path, *, max_trials: int, max_stunden: float, ameisen: int = 3,
+                 seed: int = 0, f2_intervall: int = 5, runner=None, runner_f0=None):
+        self.dir = sitzung
+        self.dir.mkdir(parents=True, exist_ok=True)
+        self.rng = random.Random(seed)
+        self.ameisen = ameisen
+        self.f2_intervall = max(f2_intervall, 1)
+        self.max_trials = max_trials
+        self.deadline = time.monotonic() + max_stunden * 3600
+        self.gezahlt = 0
+        self.runner = runner or self._subprozess       # (params, fidelity) -> metrics|None
+        self.runner_f0 = runner_f0 or self._subprozess_f0  # (params) -> {"ok","calls",…}|None
+        self.log: list[str] = []
+        self.basis: dict[str, dict] = {}               # Fidelity → Baseline-Metriken
+        self.f0_basis: int | None = None
+        self.best_params: dict = {}
+        self.best_score: float | None = None
+        self.rauschen = 0.5
+        # Pheromon + Trial-Cache (Resume)
+        self.pheromon: dict[str, dict[str, float]] = {
+            n: {str(s): 1.0 for s in stufen(n)} for n in PARAMS}
+        ph = self.dir / "pheromon.json"
+        if ph.exists():
+            gespeichert = json.loads(ph.read_text(encoding="utf-8"))
+            for n, taus in gespeichert.get("pheromon", {}).items():
+                if n in self.pheromon:
+                    self.pheromon[n].update({k: float(v) for k, v in taus.items()})
+            self.best_params = gespeichert.get("best_params", {})
+            self.best_score = gespeichert.get("best_score")
+        self.cache_pfad = self.dir / "trials.jsonl"
+        self.cache: dict[str, dict] = {}
+        if self.cache_pfad.exists():
+            for line in self.cache_pfad.read_text(encoding="utf-8").splitlines():
+                e = json.loads(line)
+                self.cache[e["key"]] = e["metrics"]
+
+    # ── Kandidaten ──────────────────────────────────────────────────────────────────
+    def kandidat(self, fidelity: str) -> dict:
+        """Eine Ameise: je Parameter der Fidelity mit SPARSITY auf Default, sonst
+        Pheromon-gewichtete Stufe. Sparsame Kandidaten → saubere Attribution."""
+        params = {}
+        for name, p in PARAMS.items():
+            if fidelity == "board2" and p["fidelity"] != "board2":
+                continue
+            if self.rng.random() < SPARSITY:
+                continue
+            st = stufen(name)
+            taus = [self.pheromon[name][str(s)] for s in st]
+            wert = self.rng.choices(st, weights=taus)[0]
+            if wert != p["default"]:
+                params[name] = wert
+        return params
+
+    # ── Trial-Ausführung ────────────────────────────────────────────────────────────
+    def _key(self, params: dict, fidelity: str, tag: str = "") -> str:
+        raw = json.dumps({"p": params, "f": fidelity, "tag": tag}, sort_keys=True)
+        return hashlib.md5(raw.encode()).hexdigest()[:12]
+
+    async def trial(self, params: dict, fidelity: str, tag: str = "") -> dict | None:
+        key = self._key(params, fidelity, tag)
+        if key in self.cache:
+            return self.cache[key]
+        if self.gezahlt >= self.max_trials or time.monotonic() > self.deadline:
+            return None
+        self.gezahlt += 1
+        metrics = await self.runner(params, fidelity, "0")
+        if metrics is not None:
+            with open(self.cache_pfad, "a", encoding="utf-8") as f:
+                f.write(json.dumps({"key": key, "params": params, "fidelity": fidelity,
+                                    "tag": tag, "metrics": metrics}, ensure_ascii=False) + "\n")
+            self.cache[key] = metrics
+        return metrics
+
+    async def _subprozess(self, params: dict, fidelity: str, topic_suffix: str = "0") -> dict | None:
+        out = self.dir / f"metrics-{self._key(params, fidelity)}{topic_suffix}.json"
+        topic = f"train-t{topic_suffix}"
+        args = ([topic, VORLAGE_TOPIC, str(out), "--board2"] if fidelity == "board2"
+                else [topic, BENCHMARK, str(out)])
+        env = {**os.environ, "CREATOR_PARAMS": json.dumps({**TRAIN_FIXA, **params})}
+        proc = await asyncio.create_subprocess_exec(sys.executable, "train_lauf.py", *args, env=env)
+        rc = await proc.wait()
+        if rc != 0 or not out.exists():
+            self._log(f"Trial fehlgeschlagen (rc={rc}, {fidelity}, params={params})")
+            return None
+        return json.loads(out.read_text(encoding="utf-8"))
+
+    async def _subprozess_f0(self, params: dict) -> dict | None:
+        out = self.dir / f"f0-{self._key(params, 'f0')}.json"
+        env = {**os.environ, "CREATOR_PARAMS": json.dumps(params)}
+        proc = await asyncio.create_subprocess_exec(sys.executable, "train_f0.py", str(out), env=env)
+        rc = await proc.wait()
+        return json.loads(out.read_text(encoding="utf-8")) if rc == 0 and out.exists() else None
+
+    def _log(self, msg: str) -> None:
+        line = f"{datetime.now(timezone.utc).isoformat()[11:19]} {msg}"
+        print(line, flush=True)
+        self.log.append(line)
+
+    # ── Pheromon ────────────────────────────────────────────────────────────────────
+    def verstaerke(self, params: dict, delta: float) -> None:
+        for name, wert in params.items():
+            taus = self.pheromon[name]
+            key = str(wert)
+            if key in taus:
+                taus[key] += delta
+
+    def verdunste(self) -> None:
+        for taus in self.pheromon.values():
+            for k in taus:
+                taus[k] = max(0.1, (1 - RHO) * taus[k] + RHO * 1.0)  # Drift zurück zu uniform
+
+    # ── Hauptschleife ───────────────────────────────────────────────────────────────
+    async def run(self) -> dict:
+        # Baseline F1 ×2 → Score-Basis + Rausch-Schwelle; F0-Basis für den Struktur-Proxy
+        f0 = await self.runner_f0({})
+        self.f0_basis = (f0 or {}).get("calls")
+        b1 = await self.trial({}, "board2", tag="baseline-1")
+        b2 = await self.trial({}, "board2", tag="baseline-2")
+        if not b1 or not b2:
+            self._log("Baseline unvollständig — Abbruch.")
+            return self.best_params
+        self.basis["board2"] = b1
+        s1, s2 = score(b1, b1), score(b2, b1)
+        self.rauschen = max(abs(s1 - s2), 0.5)
+        if self.best_score is None:
+            self.best_score = max(s1, s2)
+        self._log(f"Baseline {s1}/{s2}, Rauschen {self.rauschen}, F0-Basis {self.f0_basis} Calls")
+
+        runde, stagnation, gezahlt_vorher = 0, 0, self.gezahlt
+        while (self.gezahlt < self.max_trials and time.monotonic() < self.deadline
+               and stagnation < 20):  # konvergiert: nur noch Cache-Treffer → fertig
+            if runde > 0:
+                stagnation = stagnation + 1 if self.gezahlt == gezahlt_vorher else 0
+            gezahlt_vorher = self.gezahlt
+            runde += 1
+            fidelity = "voll" if runde % self.f2_intervall == 0 else "board2"
+            if fidelity == "voll" and "voll" not in self.basis:
+                base = await self.trial({}, "voll", tag="baseline-voll")
+                if base is None:
+                    break
+                self.basis["voll"] = base
+            kandidaten = []
+            for _ in range(self.ameisen * 3):  # ziehen bis K einzigartige nicht-leere da sind
+                k = self.kandidat(fidelity)
+                if k and k not in kandidaten and k != self.best_params:
+                    kandidaten.append(k)
+                if len(kandidaten) >= self.ameisen:
+                    break
+            if not kandidaten:
+                continue
+            # F0-Filter: Invarianten + Struktur-Proxy, parallel, kostenlos
+            f0s = await asyncio.gather(*[self.runner_f0(k) for k in kandidaten])
+            ueberlebende = []
+            for k, f in zip(kandidaten, f0s):
+                if f is None or not f.get("ok") or f.get("invarianten_fehler"):
+                    self._log(f"F0 verwirft {k} (Invarianten)")
+                elif self.f0_basis and f.get("calls", 0) > self.f0_basis * F0_CALL_FAKTOR:
+                    self._log(f"F0 verwirft {k} (Calls {f['calls']} > {self.f0_basis}×{F0_CALL_FAKTOR})")
+                else:
+                    ueberlebende.append(k)
+            if not ueberlebende:
+                self.verdunste()
+                continue
+            # F1/F2 parallel (eigene Topic-Namen)
+            ergebnisse = await asyncio.gather(*[
+                self._bewertet(k, fidelity, str(i + 1)) for i, k in enumerate(ueberlebende)])
+            bewertet = [(k, m, score(m, self.basis[fidelity]))
+                        for k, m in ergebnisse if m is not None]
+            if not bewertet:
+                continue
+            bewertet.sort(key=lambda x: -x[2])
+            self.verdunste()
+            top_k, _top_m, top_s = bewertet[0]
+            self._log(f"Runde {runde} ({fidelity}): top {top_s} {top_k} "
+                      f"(best {self.best_score})")
+            if top_s > (self.best_score or 0):
+                self.verstaerke(top_k, delta=1.0)
+            if top_s > (self.best_score or 0) + self.rauschen:
+                m2 = await self.trial(top_k, fidelity, tag="bestaetigung")
+                if m2 is not None and score(m2, self.basis[fidelity]) > self.best_score + self.rauschen:
+                    self.best_params = top_k
+                    self.best_score = min(top_s, score(m2, self.basis[fidelity]))
+                    self._log(f"NEUER BESTER {self.best_params} → {self.best_score}")
+                else:
+                    self._log(f"{top_k}: nicht bestätigt")
+            self.verstaerke(self.best_params, delta=0.5)  # Elite hält die Spur warm
+            self._speichern()
+        self._speichern()
+        return self.best_params
+
+    async def _bewertet(self, params: dict, fidelity: str, suffix: str):
+        if self.gezahlt >= self.max_trials or time.monotonic() > self.deadline:
+            return params, None
+        key = self._key(params, fidelity)
+        if key in self.cache:
+            return params, self.cache[key]
+        self.gezahlt += 1
+        m = await self.runner(params, fidelity, suffix)
+        if m is not None:
+            with open(self.cache_pfad, "a", encoding="utf-8") as f:
+                f.write(json.dumps({"key": key, "params": params, "fidelity": fidelity,
+                                    "tag": "", "metrics": m}, ensure_ascii=False) + "\n")
+            self.cache[key] = m
+        return params, m
+
+    def _speichern(self) -> None:
+        from fsutil import atomic_write_json, atomic_write_text
+        atomic_write_json(self.dir / "pheromon.json",
+                          {"pheromon": self.pheromon, "best_params": self.best_params,
+                           "best_score": self.best_score}, indent=1)
+        atomic_write_json(self.dir / "beste_params.json", self.best_params, indent=1)
+        staerkste = sorted(((n, max(t.items(), key=lambda x: x[1]))
+                            for n, t in self.pheromon.items()),
+                           key=lambda x: -x[1][1])[:10]
+        report = ["# Trainings-Report (Ameisen)", "",
+                  f"Bezahlte Läufe: {self.gezahlt}/{self.max_trials}",
+                  f"Bester Score: {self.best_score} (Rauschband {self.rauschen})",
+                  f"Beste Parameter: `{json.dumps(self.best_params, ensure_ascii=False)}`",
+                  "", "Stärkste Pheromon-Spuren:",
+                  *[f"- {n}={s} (τ={t:.1f})" for n, (s, t) in staerkste],
+                  "", "Nutzung: `CREATOR_PARAMS=$(cat beste_params.json)` —",
+                  "Übernahme nach config.py bleibt eine manuelle Entscheidung.", "", "## Log", ""]
+        report += [f"- {l}" for l in self.log[-200:]]
+        atomic_write_text(self.dir / "report.md", "\n".join(report))
+
+
+async def init_vorlage() -> None:
+    """Einmalig: Prüfstand-Volllauf mit Defaults, Ergebnis bleibt als Frozen-Inventar-Vorlage
+    liegen (Topic train-vorlage). Nach Korpus-/Prompt-Änderungen neu ausführen."""
+    import agents
+    import database
+    from blocks import generate_blocks
+    from fsutil import atomic_write_json as awj
+    from paths import source_path
+    await database.init_db()
+    agents.on_event = database.add_event
+    await database.create_topic(VORLAGE_TOPIC)
+    qp = source_path(VORLAGE_TOPIC)
+    qp.parent.mkdir(parents=True, exist_ok=True)
+    awj(qp, {"type": "uni", "location": BENCHMARK, "spec": ""})
+    await generate_blocks(VORLAGE_TOPIC, provider="minimax", research=True, qa_force=True)
+    await database.close_db()
+    print(f"Vorlage {VORLAGE_TOPIC} steht — Training kann starten (make train).")
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--init", action="store_true", help="Frozen-Inventar-Vorlage bauen")
+    ap.add_argument("--trials", type=int, default=60)
+    ap.add_argument("--stunden", type=float, default=8.0)
+    ap.add_argument("--ameisen", type=int, default=3)
+    ap.add_argument("--seed", type=int, default=0)
+    ap.add_argument("--f2-intervall", type=int, default=5)
+    ap.add_argument("--sitzung", default="aco")  # fester Default: Resume über Sitzungen hinweg
+    args = ap.parse_args()
+    if args.init:
+        asyncio.run(init_vorlage())
+        return
+    trainer = AmeisenTrainer(STORAGE_DIR / "train" / args.sitzung,
+                             max_trials=args.trials, max_stunden=args.stunden,
+                             ameisen=args.ameisen, seed=args.seed,
+                             f2_intervall=args.f2_intervall)
+    asyncio.run(trainer.run())
+
+
+if __name__ == "__main__":
+    main()

backend/train_f0.py

@@ -0,0 +1,60 @@
+"""Fidelity 0 des Trainers: Fake-E2E-Lauf im Subprozess — Sekunden, null Tokens.
+
+Misst mit den CREATOR_PARAMS des Kandidaten: (a) halten die Invarianten? (b) wie viele
+Agenten-Calls erzeugt die Struktur (Proxy für Tokens/Laufzeit)? Unsinnige Kandidaten
+fallen hier raus, bevor ein echter Lauf Geld kostet.
+
+CLI: python3 train_f0.py <ausgabe.json>   (CREATOR_PARAMS im ENV)
+"""
+
+import asyncio
+import json
+import sys
+import tempfile
+import time
+from pathlib import Path
+
+# WICHTIG: config (mit CREATOR_PARAMS) lädt vor allen Pipeline-Modulen
+import database
+from config import DEFAULT_PROVIDER
+from fake_agents import Welt, aktivieren
+from fsutil import atomic_write_json
+
+
+async def f0(out: str) -> None:
+    tmp = Path(tempfile.mkdtemp(prefix="train-f0-"))
+    database.DB_PATH = tmp / "f0.db"
+    database._db = None
+    await database.init_db()
+    welt = Welt()
+    aktivieren(welt)
+    import board_inventory as bi
+    import qa
+    qa.QA_DIR = tmp / "qa"
+    from pipeline import GenContext
+
+    work = tmp / "arbeit"
+    work.mkdir()
+    files = {"arbeit": work, "final": tmp / "blocks.md",
+             "sub_roh": tmp / "sub_roh.json", "sidecar": tmp / "subblocks.json",
+             "facts": tmp / "facts.json", "question_pattern": tmp / "question_pattern.json",
+             "artefakte": tmp / "artefakte.json", "outline": tmp / "outline.json",
+             "outline_slots": [tmp / f"outline-{i}.json" for i in (1, 2, 3)],
+             "research": [work / f"research-{i}.md" for i in (1, 2, 3, 4, 5)]}
+    ctx = GenContext(topic="f0", provider=DEFAULT_PROVIDER, is_cancelled=lambda: False)
+    start = time.monotonic()
+    ok = await asyncio.wait_for(
+        bi.run_boards(ctx, lambda *a, **k: None, files, {"type": "thema"}, None, "",
+                      research=True, qa_force=True), timeout=180)
+    from tests.invarianten import pruefe_invarianten
+    fehler = await pruefe_invarianten("f0", files)
+    atomic_write_json(Path(out), {
+        "ok": bool(ok), "invarianten_fehler": fehler, "calls": len(welt.calls),
+        "dauer_s": round(time.monotonic() - start, 1)}, indent=1)
+    await database.close_db()
+
+
+if __name__ == "__main__":
+    if len(sys.argv) != 2:
+        raise SystemExit("Nutzung: python3 train_f0.py <ausgabe.json>")
+    asyncio.run(f0(sys.argv[1]))

backend/train_lauf.py

@@ -0,0 +1,127 @@
+"""EIN Trainings-Trial: frischer Prozess (CREATOR_PARAMS wirkt beim Import), ein Mini-Lauf,
+deterministische Metriken als JSON — danach ist das Trial-Topic weg.
+
+Fidelity-Modi:
+  voll    python3 train_lauf.py <topic> <benchmark-location> <ausgabe.json>
+          — kompletter Lauf (Research + Board 1 + Board 2) + Soll-Abgleich gegen
+            <benchmark-location>/soll.json (falls vorhanden)
+  board2  python3 train_lauf.py <topic> <vorlage-topic> <ausgabe.json> --board2
+          — Frozen-Inventar: Vorlage kopieren, Board 2 komplett neu (research=False)
+"""
+
+import asyncio
+import shutil
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+import agents
+import database
+import qa
+from blocks import generate_blocks
+from fsutil import atomic_write_json
+from paths import blocks_path, source_path, topic_dir
+from textkit import _norm_title
+
+
+def soll_abgleich(ist_titel: list[str], soll: dict) -> dict:
+    """Ground-Truth-Vergleich: welche Soll-Blöcke fehlen, was ist überzählig.
+    Match über Norm-Gleichheit gegen Titel+Alternativen, Fallback beidseitiges Containment."""
+    ist = {_norm_title(t): t for t in ist_titel}
+    treffer, fehlend, belegt = [], [], set()
+    for block in soll.get("bloecke", []):
+        formen = {_norm_title(block["titel"])} | {_norm_title(a) for a in block.get("alternativen", [])}
+        gefunden = next((n for n in ist if n in formen), None)
+        if gefunden is None:
+            gefunden = next((n for n in ist if any(f and (f in n or n in f) for f in formen)), None)
+        if gefunden:
+            treffer.append(block["titel"])
+            belegt.add(gefunden)
+        else:
+            fehlend.append(block["titel"])
+    extra = [t for n, t in ist.items() if n not in belegt]
+    n_soll = max(len(soll.get("bloecke", [])), 1)
+    praezision = len(treffer) / max(len(ist), 1)
+    recall = len(treffer) / n_soll
+    f1 = 2 * praezision * recall / max(praezision + recall, 1e-9)
+    return {"treffer": treffer, "fehlend": fehlend, "extra": extra, "f1": round(f1, 3)}
+
+
+async def trial(topic: str, quelle: str, out: str, board2: bool) -> None:
+    await database.init_db()
+    agents.on_event = database.add_event  # sonst keine Dauer-/Token-Events (main.py-lifespan-Pendant)
+    try:
+        await _aufraeumen(topic)  # Reste eines abgebrochenen Trials
+        await database.create_topic(topic)
+        start = datetime.now(timezone.utc)
+        if board2:
+            await _frozen_inventar(topic, vorlage=quelle)
+            await generate_blocks(topic, provider="minimax", research=False, qa_force=True)
+        else:
+            qp = source_path(topic)
+            qp.parent.mkdir(parents=True, exist_ok=True)
+            atomic_write_json(qp, {"type": "uni", "location": quelle, "spec": ""})
+            # qa_force=True: das Gate misst nichts und pausiert nie
+            await generate_blocks(topic, provider="minimax", research=True, qa_force=True)
+        dauer_min = round((datetime.now(timezone.utc) - start).total_seconds() / 60, 1)
+        report = await qa.qa_report(topic, llm=False) or {}
+        lauf = report.get("lauf") or {}
+        metrics = {
+            "topic": topic,
+            "fidelity": "board2" if board2 else "voll",
+            "note": report.get("note"),
+            "note_artefakte": report.get("note_artefakte"),
+            "quoten": report.get("quoten") or {},
+            "quoten_artefakte": report.get("quoten_artefakte") or {},
+            "bloecke": report.get("bloecke"),
+            "dauer_min": lauf.get("dauer_min") or dauer_min,
+            "tokens": (lauf.get("tokens") or {}),
+            "agents": (lauf.get("agents") or {}),
+        }
+        if not board2:
+            soll_pfad = Path(__file__).resolve().parent.parent / quelle / "soll.json"
+            if soll_pfad.exists():
+                import json
+                done = await database.kanban_cards(topic, board="inventory", stage="done_block")
+                titel = [c["payload"].get("title", "") for c in done if c["kind"] == "block"]
+                metrics["soll"] = soll_abgleich(titel, json.loads(soll_pfad.read_text(encoding="utf-8")))
+        atomic_write_json(Path(out), metrics, indent=1)
+    finally:
+        await _aufraeumen(topic)
+        await database.close_db()
+
+
+async def _frozen_inventar(topic: str, vorlage: str) -> None:
+    """Board-1-Stand der Vorlage übernehmen und Board 2 auf Start zurücksetzen —
+    reset_board_from_stage räumt DB-Spiegel, globale Dateien und Resume-Slots."""
+    import board_inventory
+    from blocks import _blocks_files
+    await database.copy_topic(vorlage, topic)
+    tdir = topic_dir(topic)
+    tdir.mkdir(parents=True, exist_ok=True)
+    for src, dst in ((source_path(vorlage), source_path(topic)),
+                     (blocks_path(vorlage), blocks_path(topic))):
+        if src.exists():
+            shutil.copy(src, dst)
+    files = _blocks_files(topic)
+    files["arbeit"].mkdir(parents=True, exist_ok=True)
+    await board_inventory.reset_board_from_stage(topic, "artefacts", "generate", files)
+
+
+async def _aufraeumen(topic: str) -> None:
+    """Topic restlos entfernen (DELETE-/topics-Sequenz aus routes.py)."""
+    await database.delete_topic(topic)
+    await database.delete_block_data(topic)
+    await database.delete_topic_pipeline(topic)
+    await database.kanban_reset(topic)
+    await database.delete_source(topic)
+    await database.delete_guide_content(topic)
+    shutil.rmtree(topic_dir(topic), ignore_errors=True)
+    shutil.rmtree(qa.QA_DIR / topic, ignore_errors=True)
+
+
+if __name__ == "__main__":
+    args = [a for a in sys.argv[1:] if a != "--board2"]
+    if len(args) != 3:
+        raise SystemExit("Nutzung: python3 train_lauf.py <topic> <quelle> <ausgabe.json> [--board2]")
+    asyncio.run(trial(args[0], args[1], args[2], board2="--board2" in sys.argv))

backend/train_params.py

@@ -0,0 +1,48 @@
+"""Suchraum fürs Training (make train): welche config-Parameter der Trainer bewegen darf.
+
+Je Parameter: default (muss config spiegeln — Test prüft das), min/max (harte Ränder,
+flow-sicher), step (Schrittweite der Koordinaten-Suche), kategorie (welches Ziel er
+primär bewegt: qualitaet/auswahl/laufzeit/tokens). QA-/Detektor-Konstanten stehen
+bewusst NICHT hier — die Messlatte darf nie Teil des Suchraums sein.
+"""
+
+PARAMS: dict[str, dict] = {
+    # Recherche / Inventar
+    "RESEARCH_THEMA_AGENTS":  {"default": 5,    "min": 2,    "max": 8,    "step": 1,    "kategorie": "qualitaet", "fidelity": "voll"},
+    "RESEARCH_READERS":       {"default": 2,    "min": 1,    "max": 3,    "step": 1,    "kategorie": "qualitaet", "fidelity": "voll"},
+    "RESEARCH_SECTION_CHARS": {"default": 12000, "min": 6000, "max": 24000, "step": 3000, "kategorie": "tokens", "fidelity": "voll"},
+    "DEDUP_PAIR_FLOOR":       {"default": 0.6,  "min": 0.45, "max": 0.8,  "step": 0.05, "kategorie": "auswahl", "fidelity": "voll"},
+    "DEDUP_TITLE_AUTO":       {"default": 0.95, "min": 0.9,  "max": 0.99, "step": 0.01, "kategorie": "auswahl", "fidelity": "voll"},
+    "DEDUP_GLOBAL_FLOOR":     {"default": 0.65, "min": 0.5,  "max": 0.8,  "step": 0.05, "kategorie": "auswahl", "fidelity": "voll"},
+    "DEDUP_PAIRS_CHUNK":      {"default": 40,   "min": 15,   "max": 80,   "step": 10,   "kategorie": "laufzeit", "fidelity": "voll"},
+    "FILTER_CHUNK":           {"default": 35,   "min": 15,   "max": 60,   "step": 10,   "kategorie": "laufzeit", "fidelity": "voll"},
+    "FILTER_RECHECK_PANEL":   {"default": 3,    "min": 1,    "max": 5,    "step": 1,    "kategorie": "qualitaet", "fidelity": "voll"},
+    "CONSOLIDATION_PANEL":    {"default": 3,    "min": 1,    "max": 5,    "step": 1,    "kategorie": "qualitaet", "fidelity": "voll"},
+    # Board 2, verschmolzene Calls (block_calls.py)
+    "GEN_PANEL":              {"default": 2,    "min": 1,    "max": 3,    "step": 1,    "kategorie": "qualitaet", "fidelity": "board2"},
+    "VERIFY_PANEL":           {"default": 2,    "min": 1,    "max": 3,    "step": 1,    "kategorie": "qualitaet", "fidelity": "board2"},
+    "ART_SPLIT_SUBS":         {"default": 20,   "min": 10,   "max": 40,   "step": 5,    "kategorie": "laufzeit", "fidelity": "board2"},
+    # Embedding-Schwellen (Auswahl-Kern)
+    "SUB_VARIANT_COS":        {"default": 0.90, "min": 0.85, "max": 0.96, "step": 0.01, "kategorie": "auswahl", "fidelity": "board2"},
+    "SEED_COVER_COS":         {"default": 0.80, "min": 0.7,  "max": 0.9,  "step": 0.02, "kategorie": "auswahl", "fidelity": "board2"},
+    "SUB_DUP_KANDIDAT_COS":   {"default": 0.75, "min": 0.65, "max": 0.85, "step": 0.02, "kategorie": "auswahl", "fidelity": "board2"},
+    "EMBEDDING_BLOCK_FLOOR":  {"default": 0.5,  "min": 0.35, "max": 0.65, "step": 0.05, "kategorie": "auswahl", "fidelity": "voll"},
+    "CROSS_CHUNK_PAARE":      {"default": 40,   "min": 15,   "max": 80,   "step": 10,   "kategorie": "laufzeit", "fidelity": "board2"},
+    # Guide
+    "GATE_FIX_MIN":           {"default": 3,    "min": 1,    "max": 6,    "step": 1,    "kategorie": "qualitaet", "fidelity": "board2"},
+    "WRITER_SPLIT_SUBS":      {"default": 30,   "min": 15,   "max": 45,   "step": 5,    "kategorie": "qualitaet", "fidelity": "board2"},
+    # Engine / Kosten
+    "CONSENSUS_GRACE":        {"default": 300,  "min": 0,    "max": 600,  "step": 60,   "kategorie": "laufzeit", "fidelity": "board2"},
+    "MAX_RESTARTS":           {"default": 2,    "min": 1,    "max": 3,    "step": 1,    "kategorie": "laufzeit", "fidelity": "board2"},
+    "HEDGE_NACH_S":           {"default": 90,   "min": 30,   "max": 240,  "step": 30,   "kategorie": "laufzeit", "fidelity": "board2"},
+    "EVIDENCE_BUDGET_CHARS":  {"default": 48000, "min": 16000, "max": 64000, "step": 8000, "kategorie": "tokens", "fidelity": "board2"},
+    "QUELLE_RELEVANZ_CHUNK":  {"default": 12,   "min": 6,    "max": 24,   "step": 3,    "kategorie": "laufzeit", "fidelity": "voll"},
+}
+
+
+def schritte(name: str) -> tuple[float, float]:
+    """(wert_runter, wert_hoch) je einen step von default, an die Ränder geklemmt."""
+    p = PARAMS[name]
+    lo = max(p["min"], round(p["default"] - p["step"], 4))
+    hi = min(p["max"], round(p["default"] + p["step"], 4))
+    return lo, hi

benchmarks/fotografie/skript.txt

@@ -0,0 +1,23 @@
+Kapitel 1: Die Blende
+
+Die Blende ist eine verstellbare Öffnung im Objektiv, die die einfallende Lichtmenge steuert. Ihre Größe wird als Blendenzahl angegeben, dem Verhältnis von Brennweite zu Öffnungsdurchmesser: f/2.8 bezeichnet eine große, f/16 eine kleine Öffnung. Eine ganze Blendenstufe halbiert oder verdoppelt die Lichtmenge; die Reihe ganzer Stufen lautet f/1.4, f/2, f/2.8, f/4, f/5.6, f/8, f/11, f/16, f/22. Die Blende steuert zugleich die Schärfentiefe: Eine offene Blende (kleine Blendenzahl) erzeugt geringe Schärfentiefe und Freistellung, eine geschlossene Blende große Schärfentiefe. Jenseits von etwa f/16 sinkt die Detailschärfe durch Beugung.
+
+Kapitel 2: Die Belichtungszeit
+
+Die Belichtungszeit ist die Dauer, während der der Sensor Licht sammelt. Sie wird in Sekundenbruchteilen angegeben; jede Halbierung oder Verdopplung entspricht einer Lichtwertstufe. Kurze Zeiten frieren Bewegung ein: 1/1000 Sekunde genügt für Sport, 1/250 Sekunde für gehende Personen. Lange Zeiten erzeugen Bewegungsunschärfe, etwa fließendes Wasser ab 1/4 Sekunde. Als Faustregel für verwacklungsfreies Fotografieren aus der Hand gilt: Belichtungszeit höchstens eins durch Brennweite (Kleinbild-äquivalent), also 1/50 Sekunde bei 50 Millimetern. Bildstabilisatoren verlängern diese Grenze um drei bis fünf Stufen.
+
+Kapitel 3: Der ISO-Wert
+
+Der ISO-Wert beschreibt die Signalverstärkung des Sensors. Die Basisempfindlichkeit liegt bei den meisten Kameras bei ISO 100; jede Verdopplung entspricht einer Lichtwertstufe. Höhere ISO-Werte ermöglichen kürzere Belichtungszeiten bei wenig Licht, verstärken aber das Bildrauschen und verringern den Dynamikumfang. Modernes Rauschverhalten erlaubt bei Vollformatsensoren meist saubere Bilder bis ISO 3200 bis 6400. ISO-invariante Sensoren erlauben es, die Aufhellung ins RAW-Processing zu verschieben, ohne zusätzliches Rauschen einzuhandeln.
+
+Kapitel 4: Das Belichtungsdreieck
+
+Blende, Belichtungszeit und ISO-Wert bilden das Belichtungsdreieck: Alle drei Größen bestimmen gemeinsam die Bildhelligkeit, und eine Stufe bei einer Größe lässt sich durch eine Stufe einer anderen ausgleichen. Ein Beispiel: f/8 bei 1/125 Sekunde und ISO 100 belichtet identisch wie f/5.6 bei 1/250 Sekunde und ISO 100 oder f/8 bei 1/250 Sekunde und ISO 200. Die Wahl innerhalb dieser äquivalenten Kombinationen ist eine gestalterische Entscheidung über Schärfentiefe, Bewegungsdarstellung und Rauschen.
+
+Kapitel 5: Der Weißabgleich
+
+Der Weißabgleich gleicht die Farbtemperatur der Lichtquelle aus, gemessen in Kelvin: Kerzenlicht liegt bei etwa 1800 Kelvin, Glühlampen bei 2700 Kelvin, Tageslicht bei 5500 Kelvin, bedeckter Himmel bei 6500 bis 7500 Kelvin. Ein zu niedrig eingestellter Weißabgleich macht das Bild blau, ein zu hoher macht es orange. Wer in RAW fotografiert, kann den Weißabgleich verlustfrei nachträglich setzen; bei JPEG ist die Korrektur begrenzt.
+
+Kapitel 6: Autofokus-Betriebsarten
+
+Der Einzel-Autofokus (AF-S) stellt einmal scharf und verriegelt die Entfernung — geeignet für statische Motive. Der kontinuierliche Autofokus (AF-C) führt die Schärfe laufend nach und ist die Wahl für bewegte Motive; die Trefferquote hängt von der Motivverfolgung ab. Beim Fokus-und-Verschwenken-Verfahren wird mit dem mittleren Feld scharfgestellt und dann der Bildausschnitt verändert; bei offener Blende und naher Distanz führt das Verschwenken zu Fokusfehlern, weil sich die Fokusebene dreht.

benchmarks/fotografie/uebungen.txt

@@ -0,0 +1,13 @@
+Übungsblatt Fotografie-Grundlagen
+
+Aufgabe 1: Sie fotografieren mit f/8, 1/125 Sekunde, ISO 100. Das Bild ist eine Stufe zu dunkel. Nennen Sie drei Korrekturen, die je genau eine Lichtwertstufe aufhellen: Blende auf f/5.6 öffnen, Belichtungszeit auf 1/60 Sekunde verlängern oder ISO auf 200 verdoppeln.
+
+Aufgabe 2: Ordnen Sie die Blendenzahlen f/4, f/11, f/2 nach Öffnungsgröße, beginnend mit der größten Öffnung. Reihenfolge: f/2, f/4, f/11.
+
+Aufgabe 3: Sie fotografieren mit einem 200-Millimeter-Objektiv ohne Stabilisator aus der Hand. Welche längste Belichtungszeit empfiehlt die Faustregel? 1/200 Sekunde.
+
+Aufgabe 4: Ein Porträt vor unruhigem Hintergrund soll freigestellt werden. Welche Blendenwahl unterstützt das, und welcher Nebeneffekt ist zu beachten? Offene Blende wie f/2, dabei geringe Schärfentiefe — die Fokusebene muss exakt auf den Augen liegen.
+
+Aufgabe 5: Das Bild einer Kunstlicht-Szene wirkt stark orange. In welche Richtung war der Weißabgleich falsch eingestellt, und wie lautet die passende Farbtemperatur für Glühlampenlicht? Der Weißabgleich stand zu hoch; passend sind etwa 2700 Kelvin.
+
+Aufgabe 6: Warum führt Fokus-und-Verschwenken bei f/1.8 und einem Meter Abstand zu unscharfen Augen? Beim Verschwenken dreht sich die Fokusebene aus dem Motiv heraus; die geringe Schärfentiefe verzeiht die Abweichung nicht.

benchmarks/pruefstand/skript.txt

@@ -0,0 +1,27 @@
+Skript: Grundlagen der Verschlüsselung
+
+Kapitel 1: Symmetrische Verschlüsselung
+
+Symmetrische Verschlüsselung verwendet denselben Schlüssel zum Ver- und Entschlüsseln. Sender und Empfänger müssen den Schlüssel vorab über einen sicheren Kanal austauschen. Der Schlüsselraum muss groß genug sein, dass vollständiges Durchprobieren aussichtslos bleibt: 128 Bit gelten als sicher gegen Brute-Force. Symmetrische Verfahren sind schnell und eignen sich für große Datenmengen. Blockchiffren verarbeiten die Nachricht in festen Blöcken, etwa 128 Bit bei AES; Stromchiffren verschlüsseln Bit für Bit mit einem Schlüsselstrom. Das Kerckhoffs-Prinzip verlangt, dass die Sicherheit allein am Schlüssel hängt, nie an der Geheimhaltung des Verfahrens.
+
+Kapitel 2: Betriebsmodi von Blockchiffren
+
+Ein Betriebsmodus legt fest, wie eine Blockchiffre Nachrichten länger als einen Block verarbeitet. Die wichtigsten Modi sind ein kleiner Katalog: ECB verschlüsselt jeden Block unabhängig, CBC verkettet jeden Block mit dem Vorgänger-Geheimtext, CTR macht aus der Blockchiffre eine Stromchiffre über einen Zähler, und GCM ergänzt CTR um einen Authentizitäts-Tag. ECB gilt als unsicher, weil gleiche Klartextblöcke gleiche Geheimtextblöcke ergeben und Muster sichtbar bleiben. CBC braucht einen zufälligen Initialisierungsvektor je Nachricht. CTR und GCM sind parallelisierbar; GCM ist der Standard für authentifizierte Verschlüsselung.
+
+Kapitel 3: Asymmetrische Verschlüsselung
+
+Asymmetrische Verschlüsselung, im Englischen public key cryptography, arbeitet mit einem Schlüsselpaar: Der öffentliche Schlüssel verschlüsselt, der private entschlüsselt. Der öffentliche Schlüssel darf jeder kennen; der private verlässt den Besitzer nie. Damit entfällt der sichere Kanal für den Schlüsselaustausch. Die Sicherheit beruht auf mathematisch schweren Problemen: RSA auf der Faktorisierung großer Zahlen, Elliptische-Kurven-Verfahren auf dem diskreten Logarithmus. Asymmetrische Verfahren sind um Größenordnungen langsamer als symmetrische. In der Praxis verschlüsselt man deshalb hybrid: asymmetrisch nur den Sitzungsschlüssel, die Daten symmetrisch.
+
+Anders formuliert löst die Public-Key-Kryptographie das Verteilungsproblem: Zwei Parteien ohne gemeinsames Geheimnis können vertraulich kommunizieren, weil das Schlüsselpaar die Rollen trennt — verschlüsseln kann jeder, entschlüsseln nur der Inhaber des privaten Schlüssels.
+
+Kapitel 4: Kryptographische Hashfunktionen
+
+Eine kryptographische Hashfunktion bildet beliebig lange Eingaben auf einen Wert fester Länge ab, den Digest. Drei Eigenschaften machen sie kryptographisch: Einwegfunktion (aus dem Digest ist die Eingabe praktisch nicht rekonstruierbar), schwache Kollisionsresistenz (zu gegebener Eingabe ist keine zweite mit gleichem Digest findbar) und starke Kollisionsresistenz (es ist praktisch unmöglich, irgendein kollidierendes Paar zu finden). Nach dem Geburtstagsparadoxon (Satz 3.2) sinkt der Kollisionsaufwand auf die Wurzel des Werteraums: Bei einem 256-Bit-Digest liegt er bei 2 hoch 128 Versuchen. Kleine Eingabeänderungen kippen im Mittel die Hälfte der Digest-Bits; das heißt Lawineneffekt. Hashfunktionen speichern Passwörter, prüfen Datenintegrität und bilden die Basis von Signaturen.
+
+Kapitel 5: Digitale Signaturen
+
+Eine digitale Signatur weist Urheberschaft und Unverändertheit einer Nachricht nach. Der Absender hasht die Nachricht und verschlüsselt den Digest mit seinem privaten Schlüssel; jeder kann die Signatur mit dem öffentlichen Schlüssel prüfen. Stimmen berechneter und entschlüsselter Digest überein, ist die Nachricht unverändert und stammt vom Schlüsselinhaber. Signaturen liefern damit drei Garantien: Integrität, Authentizität und Nichtabstreitbarkeit. Signiert wird immer der Hash, nie die Nachricht selbst — aus Effizienz und weil manche Verfahren nur kurze Eingaben verarbeiten. Gängige Verfahren sind RSA-PSS und ECDSA.
+
+Kapitel 6: Zertifikate und PKI
+
+Ein Zertifikat bindet einen öffentlichen Schlüssel an eine Identität. Es enthält Inhaber, Schlüssel, Gültigkeitszeitraum und die Signatur einer Zertifizierungsstelle (CA). Die Public-Key-Infrastruktur (PKI) ordnet CAs hierarchisch: Eine Wurzel-CA signiert Zwischen-CAs, diese signieren Endzertifikate — die Vertrauenskette. Browser prüfen die Kette bis zu einer vorinstallierten Wurzel. Widerrufene Zertifikate landen in Sperrlisten (CRL) oder werden per OCSP live abgefragt. Am Rande: Das X.690-Format kodiert Zertifikatsfelder in ASN.1-Strukturen — ein Implementierungsdetail, das für das Verständnis der Vertrauenskette nicht nötig ist.

benchmarks/pruefstand/soll.json

@@ -0,0 +1,16 @@
+{
+  "bloecke": [
+    {"titel": "Symmetrische Verschlüsselung", "alternativen": ["Symmetrische Kryptographie", "Symmetrische Verfahren"]},
+    {"titel": "Betriebsmodi von Blockchiffren", "alternativen": ["Betriebsmodi", "Blockchiffren-Modi", "Betriebsarten von Blockchiffren"]},
+    {"titel": "Asymmetrische Verschlüsselung", "alternativen": ["Public-Key-Kryptographie", "Asymmetrische Kryptographie", "Public Key Cryptography"]},
+    {"titel": "Kryptographische Hashfunktionen", "alternativen": ["Hashfunktionen", "Hash-Funktionen"]},
+    {"titel": "Digitale Signaturen", "alternativen": ["Signaturen", "Digitale Signatur"]},
+    {"titel": "Zertifikate und PKI", "alternativen": ["Zertifikate", "Public-Key-Infrastruktur", "PKI", "Zertifikate und Public-Key-Infrastruktur"]}
+  ],
+  "fallen": {
+    "dublette": "Asymmetrische Verschlüsselung und Public-Key-Kryptographie (Kapitel 3, zwei Formulierungen + DE/EN) dürfen nur EINEN Block ergeben.",
+    "katalog": "ECB/CBC/CTR/GCM gehören als Katalog unter Betriebsmodi — keine vier Einzelblöcke.",
+    "peripheral": "X.690/ASN.1 ist als Implementierungsdetail markiert — höchstens peripheral, nie eigener Kern-Block.",
+    "referenz_titel": "„Geburtstagsparadoxon (Satz 3.2)" darf nicht als Referenz-Titel überleben (Naming-Regel)."
+  }
+}

benchmarks/sortierverfahren/skript.txt

@@ -0,0 +1,23 @@
+Kapitel 1: Grundbegriffe des Sortierens
+
+Ein Sortierverfahren ordnet eine Folge von n Elementen nach einem Ordnungskriterium, meist aufsteigend nach einem Schlüssel. Ein Verfahren heißt stabil, wenn Elemente mit gleichem Schlüssel ihre ursprüngliche Reihenfolge behalten. Ein Verfahren arbeitet in-place, wenn es neben der Eingabefolge nur konstant viel zusätzlichen Speicher benötigt. Die Laufzeit wird in Vergleichen und Vertauschungen gemessen; die untere Schranke für vergleichsbasierte Verfahren liegt bei n log n Vergleichen im schlechtesten Fall.
+
+Kapitel 2: Bubblesort
+
+Bubblesort durchläuft die Folge wiederholt von links nach rechts und vertauscht benachbarte Elemente, wenn sie in falscher Reihenfolge stehen. Nach dem ersten Durchlauf steht das größte Element sicher am rechten Ende; nach k Durchläufen stehen die k größten Elemente an ihren endgültigen Positionen. Das Verfahren endet, wenn ein Durchlauf ohne Vertauschung bleibt. Bubblesort ist stabil und arbeitet in-place. Die Laufzeit beträgt im schlechtesten und mittleren Fall Theta(n Quadrat) Vergleiche; im besten Fall (bereits sortierte Folge) genügt ein Durchlauf mit n minus 1 Vergleichen, sofern die Abbruchbedingung implementiert ist.
+
+Kapitel 3: Insertionsort
+
+Insertionsort baut den sortierten Bereich am linken Rand schrittweise auf: Das jeweils nächste Element wird von rechts nach links durch Vergleiche an seine Einfügeposition geschoben. Insertionsort ist stabil, arbeitet in-place und benötigt im schlechtesten Fall n mal (n minus 1) durch 2 Vergleiche. Auf fast sortierten Folgen ist Insertionsort ausgesprochen schnell: Die Laufzeit ist linear in der Zahl der Fehlstellungen (Inversionen). Deshalb wird Insertionsort in der Praxis als Basisfall in hybriden Verfahren eingesetzt, etwa für Teilfolgen unter etwa 16 Elementen.
+
+Kapitel 4: Mergesort
+
+Mergesort teilt die Folge in zwei Hälften, sortiert beide rekursiv und mischt die sortierten Hälften in linearer Zeit zusammen (Merge-Schritt). Der Merge-Schritt vergleicht die jeweils vordersten Elemente beider Hälften und übernimmt das kleinere. Mergesort ist stabil, benötigt aber ein Hilfsarray der Größe n und arbeitet damit nicht in-place. Die Laufzeit beträgt in allen Fällen Theta(n log n). Mergesort ist das Standardverfahren für externes Sortieren, weil es sequentiell auf Datenströmen arbeiten kann.
+
+Kapitel 5: Quicksort
+
+Quicksort wählt ein Pivot-Element, partitioniert die Folge in Elemente kleiner und größer als das Pivot und sortiert beide Teile rekursiv. Die Partitionierung nach Lomuto verwendet das letzte Element als Pivot und einen Lauffinger; die Partitionierung nach Hoare arbeitet mit zwei gegenläufigen Zeigern und weniger Vertauschungen. Quicksort ist nicht stabil. Die mittlere Laufzeit beträgt Theta(n log n) mit kleiner Konstante; der schlechteste Fall Theta(n Quadrat) tritt bei ungünstiger Pivot-Wahl auf, etwa beim ersten Element auf sortierter Eingabe. Randomisierte Pivot-Wahl oder Median-aus-drei machen den schlechten Fall unwahrscheinlich.
+
+Kapitel 6: Heapsort
+
+Heapsort baut aus der Folge einen Max-Heap: einen binären Baum in Array-Darstellung, bei dem jeder Knoten mindestens so groß ist wie seine Kinder. Der Aufbau gelingt in linearer Zeit durch absinken lassen (sift-down) von der Mitte an rückwärts. Danach wird wiederholt die Wurzel (das Maximum) mit dem letzten Heap-Element getauscht, der Heap um eins verkürzt und die neue Wurzel abgesenkt. Heapsort arbeitet in-place und garantiert Theta(n log n) im schlechtesten Fall, ist aber nicht stabil und hat schlechtere Cache-Lokalität als Quicksort.

benchmarks/sortierverfahren/uebungen.txt

@@ -0,0 +1,13 @@
+Übungsblatt Sortierverfahren
+
+Aufgabe 1: Sortieren Sie die Folge 5, 2, 8, 1, 9 mit Bubblesort. Notieren Sie nach jedem Durchlauf den Zustand der Folge und die Zahl der Vertauschungen. Nach Durchlauf 1: 2, 5, 1, 8, 9 (drei Vertauschungen). Nach Durchlauf 2: 2, 1, 5, 8, 9 (eine Vertauschung). Nach Durchlauf 3: 1, 2, 5, 8, 9 (eine Vertauschung). Durchlauf 4 bleibt ohne Vertauschung, das Verfahren endet.
+
+Aufgabe 2: Zeigen Sie, dass Insertionsort auf einer Folge mit k Inversionen höchstens n minus 1 plus k Vergleiche benötigt. Hinweis: Jeder Vergleich, der zu einer Verschiebung führt, beseitigt genau eine Inversion.
+
+Aufgabe 3: Führen Sie den Merge-Schritt für die sortierten Hälften 1, 4, 7 und 2, 3, 9 durch. Ergebnisfolge: 1, 2, 3, 4, 7, 9 mit fünf Vergleichen.
+
+Aufgabe 4: Geben Sie für Quicksort mit Lomuto-Partitionierung und letztem Element als Pivot eine Eingabe der Länge 5 an, die den schlechtesten Fall erzeugt. Die bereits sortierte Folge 1, 2, 3, 4, 5 erzeugt Partitionen der Größen 4, 3, 2, 1 und damit quadratische Laufzeit.
+
+Aufgabe 5: Bauen Sie aus der Folge 3, 7, 1, 9, 4 einen Max-Heap in Array-Darstellung. Ergebnis nach dem Heap-Aufbau: 9, 7, 1, 3, 4. Begründen Sie, warum der Aufbau von der Mitte an rückwärts in linearer Zeit gelingt.
+
+Aufgabe 6: Welche der Verfahren Bubblesort, Insertionsort, Mergesort, Quicksort, Heapsort sind stabil? Stabil sind Bubblesort, Insertionsort und Mergesort; Quicksort und Heapsort sind nicht stabil.

dev-ops/opencode-slim.json

@@ -0,0 +1,113 @@
+// Auto-Ableitung von opencode.json OHNE mcp-Server: Batch-Agenten (files/readonly/text)
+// brauchen keine Web-MCPs — jeder opencode-Prozess startet sonst ~3 MCP-Prozesse (~300 MB).
+// Bei Änderungen an opencode.json hier nachziehen (nur der mcp-Block fehlt).
+{
+  "$schema": "https://opencode.ai/config.json",
+  "provider": {
+    "minimax": {
+      "options": {
+        "apiKey": "{env:MINIMAX_API_KEY}"
+      },
+      "models": {
+        "MiniMax-M3": {
+          "name": "MiniMax M3"
+        }
+      }
+    },
+    "minimax-kalt": {
+      "npm": "@ai-sdk/anthropic",
+      "name": "MiniMax (kalt — niedrige Temperature, ohne Thinking)",
+      "options": {
+        "baseURL": "https://api.minimax.io/anthropic/v1",
+        "apiKey": "{env:MINIMAX_API_KEY}"
+      },
+      "models": {
+        "MiniMax-M3": {
+          "name": "MiniMax M3 (kalt)",
+          "options": {
+            "temperature": 0.2,
+            "thinking": {
+              "type": "disabled"
+            }
+          }
+        },
+        "MiniMax-M2.7-highspeed": {
+          "name": "MiniMax M2.7 highspeed (kalt)",
+          "options": {
+            "temperature": 0.3
+          }
+        }
+      }
+    },
+    "ollama": {
+      "npm": "@ai-sdk/openai-compatible",
+      "name": "Ollama (lokal)",
+      "options": {
+        "baseURL": "http://localhost:11434/v1"
+      },
+      "models": {
+        "qwen3.6:27b": {
+          "name": "Qwen3.6 27B"
+        },
+        "qwen3.5:9b": {
+          "name": "Qwen3.5 9B"
+        }
+      }
+    }
+  },
+  "agent": {
+    "full": {
+      "description": "Alle Tools: Dateien, Bash, Websuche",
+      "permission": {
+        "edit": "allow",
+        "bash": "allow",
+        "webfetch": "allow"
+      }
+    },
+    "files": {
+      "description": "Dateien lesen/schreiben + Bash, keine Websuche",
+      "permission": {
+        "edit": "allow",
+        "bash": "allow",
+        "webfetch": "deny"
+      },
+      "tools": {
+        "minimax-search*": false,
+        "searxng*": false
+      }
+    },
+    "readonly": {
+      "description": "Nur Dateien lesen",
+      "permission": {
+        "edit": "deny",
+        "bash": "deny",
+        "webfetch": "deny"
+      },
+      "tools": {
+        "write": false,
+        "edit": false,
+        "bash": false,
+        "minimax-search*": false,
+        "searxng*": false
+      }
+    },
+    "text": {
+      "description": "Reine Textantwort, keine Tools",
+      "permission": {
+        "edit": "deny",
+        "bash": "deny",
+        "webfetch": "deny"
+      },
+      "tools": {
+        "write": false,
+        "edit": false,
+        "bash": false,
+        "read": false,
+        "glob": false,
+        "grep": false,
+        "minimax-search*": false,
+        "searxng*": false
+      }
+    }
+  }
+}

dev-ops/opencode.json

@@ -11,19 +11,26 @@
         }
       }
     },
-    "minimax-direkt": {
+    "minimax-kalt": {
       "npm": "@ai-sdk/anthropic",
-      "name": "MiniMax (ohne Thinking)",
+      "name": "MiniMax (kalt — niedrige Temperature, ohne Thinking)",
       "options": {
         "baseURL": "https://api.minimax.io/anthropic/v1",
         "apiKey": "{env:MINIMAX_API_KEY}"
       },
       "models": {
         "MiniMax-M3": {
-          "name": "MiniMax M3 (ohne Thinking)",
+          "name": "MiniMax M3 (kalt)",
           "options": {
+            "temperature": 0.2,
             "thinking": { "type": "disabled" }
           }
+        },
+        "MiniMax-M2.7-highspeed": {
+          "name": "MiniMax M2.7 highspeed (kalt)",
+          "options": {
+            "temperature": 0.3
+          }
         }
       }
     },

docker-compose.yml

@@ -7,11 +7,13 @@ services:
     environment:
       - CLAUDE_CODE_OAUTH_TOKEN=${CLAUDE_CODE_OAUTH_TOKEN:-}
       - MINIMAX_API_KEY=${MINIMAX_API_KEY:-}
+      - DEFAULT_PROVIDER=${DEFAULT_PROVIDER:-}
     networks:
       - web
     volumes:
       - ./storage:/app/storage
       - ./projects:/app/projects
+      - ./uni:/app/uni
       - ./.claude-data:/home/app/.claude
     labels:
       - "traefik.enable=true"

frontend/package-lock.json

@@ -10,6 +10,7 @@
       "dependencies": {
         "dompurify": "^3.4.7",
         "highlight.js": "^11.11.1",
+        "katex": "^0.17.0",
         "marked": "^18.0.4",
         "marked-highlight": "^2.2.4",
         "vue": "^3.5.32"
@@ -1187,6 +1188,15 @@
       ],
       "license": "CC-BY-4.0"
     },
+    "node_modules/commander": {
+      "version": "8.3.0",
+      "resolved": "https://registry.npmjs.org/commander/-/commander-8.3.0.tgz",
+      "integrity": "sha512-OkTL9umf+He2DZkUq8f8J9of7yL6RJKI24dVITBmNfZBmri9zYZQrKkuXiKhyfPSu8tUhnVBB1iKXevvnlR4Ww==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 12"
+      }
+    },
     "node_modules/convert-source-map": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/convert-source-map/-/convert-source-map-2.0.0.tgz",
@@ -1468,6 +1478,22 @@
         "node": ">=6"
       }
     },
+    "node_modules/katex": {
+      "version": "0.17.0",
+      "resolved": "https://registry.npmjs.org/katex/-/katex-0.17.0.tgz",
+      "integrity": "sha512-Vdw0ATsQ9V+LuegM/BTwQqV/6cTl5lbGcIrU+BCgLxyf6bo38ybOr372tuSIxir3CN720flu1meYR6XzNMwQnw==",
+      "funding": [
+        "https://opencollective.com/katex",
+        "https://github.com/sponsors/katex"
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "commander": "^8.3.0"
+      },
+      "bin": {
+        "katex": "cli.js"
+      }
+    },
     "node_modules/kolorist": {
       "version": "1.8.0",
       "resolved": "https://registry.npmjs.org/kolorist/-/kolorist-1.8.0.tgz",

frontend/package.json

@@ -11,6 +11,7 @@
   "dependencies": {
     "dompurify": "^3.4.7",
     "highlight.js": "^11.11.1",
+    "katex": "^0.17.0",
     "marked": "^18.0.4",
     "marked-highlight": "^2.2.4",
     "vue": "^3.5.32"

frontend/src/App.vue

@@ -1,42 +1,48 @@
 <script setup>
-import { ref, computed, watch, onMounted, onUnmounted, nextTick } from 'vue'
-import { fetchGuides, fetchTopics, createTopic as apiCreateTopic, deleteTopic as apiDeleteTopic, createGuide as apiCreate, deleteGuide, cancelGuide as apiCancel, fetchBausteineStatus, fetchActiveBausteine, createBausteine as apiCreateBausteine, cancelBausteine as apiCancelBausteine, deleteBausteine as apiDeleteBausteine, fetchProjects, deleteProject as apiDeleteProject, fetchProviders, fetchStats, fetchTopicFortschritt } from './api.js'
+import { ref, computed, watch, onMounted } from 'vue'
+import { fetchGuides, fetchTopics, deleteTopic as apiDeleteTopic, createGuide as apiCreate, deleteGuide, cancelGuide as apiCancel, fetchBlocksStatus, fetchActiveBlocks, createBlocks as apiCreateBausteine, resetBlocksStage as apiResetBlocksStage, addBlocksResearch as apiAddResearch, requeueBlocksDead as apiRequeueDead, resetGuideBoard as apiResetGuideBoard, restartBlocksCard as apiRestartBlocksCard, resetGuideCard as apiResetGuideCard, removeGuideFormat as apiRemoveGuideFormat, cancelBlocks as apiCancelBausteine, deleteBlocks as apiDeleteBausteine, fetchProviders, fetchStats, fetchTopicProgress, fetchFolders, updateSource as apiUpdateQuelle } from './api.js'
+import { usePolling } from './composables/usePolling.js'
 import TopicSidebar from './components/TopicSidebar.vue'
 import TopicDetail from './components/TopicDetail.vue'
-import ElementsSidebar from './components/ElementsSidebar.vue'
-import ElementsOverview from './components/ElementsOverview.vue'
+import BlocksOverview from './components/BlocksOverview.vue'
+import GenerationView from './components/GenerationView.vue'
+import GeneralExamPanel from './components/GeneralExamPanel.vue'
+import PracticePanel from './components/PracticePanel.vue'
 
 const guides = ref([])
-const projects = ref([])
 const backendTopics = ref([])
 const selectedTopic = ref(null)
 const previewGuide = ref(null)
 const sidebarPinned = ref(localStorage.getItem('sidebarPinned') !== 'false')
 const sidebarSticky = ref(false)
+const focusOpen = ref(false)   // block fullscreen active → lift sidebar as overlay above the focus overlay
 const darkMode = ref(
   localStorage.getItem('darkMode') === null
     ? window.matchMedia('(prefers-color-scheme: dark)').matches
     : localStorage.getItem('darkMode') === 'true',
 )
-const EMPTY_BAUSTEINE = { ready: false, generating: false, progress: null, error: null, partial: false, steps: [] }
-const bausteine = ref({ ...EMPTY_BAUSTEINE })
-const activeBausteine = ref([])
+const EMPTY_BLOCKS = { ready: false, generating: false, progress: null, error: null, partial: false, steps: [], feine_steps: [] }
+const blocks = ref({ ...EMPTY_BLOCKS })
+const activeBlocks = ref([])
 const provider = ref(localStorage.getItem('provider') || 'claude')
 const providers = ref([])
+const folders = ref({ projekt: [], uni: [] })   // folders for the sources picker
+const mainView = ref('blocks')   // blocks | generation | general | practice | detail — exclusive main-area view
+const guideBoardFormat = ref('Guide')
+const viewMode = ref('compact')              // compact | erklärend — per topic, default compact
+const _storedLevel = localStorage.getItem('level')
+const levelView = ref(_storedLevel === 'auto' || !_storedLevel ? 'auto' : Number(_storedLevel) || 'auto')  // 'auto' | 1-4
 const stats = ref(null)
-const fortschritt = ref({})
-const elementsOpen = ref(false)      // rechte Sidebar
-const elementsView = ref(false)      // Übersicht im Hauptbereich
-const elementsVersion = ref(0)       // Erhöhung = Übersicht neu laden
-const elementOpenId = ref(null)      // Element aus Übersicht in Sidebar öffnen
-const elementOpenTick = ref(0)
+const progress = ref({})
+const uiError = ref(null)   // surface rejected actions (409/400)
+
+// Run a loader, log + swallow its error (a failed background load must not break the UI).
+async function guard(label, fn) {
+  try { return await fn() } catch (e) { console.error(label, e) }
+}
 
 async function loadStats() {
-  try {
-    stats.value = await fetchStats()
-  } catch (e) {
-    console.error('Fehler beim Laden der Statistik:', e)
-  }
+  await guard('Failed to load stats:', async () => { stats.value = await fetchStats() })
 }
 
 function setProvider(id) {
@@ -44,19 +50,23 @@ function setProvider(id) {
   localStorage.setItem('provider', id)
 }
 
+async function loadFolders() {
+  await guard('Failed to load folders:', async () => {
+    const [projekt, uni] = await Promise.all([fetchFolders('projekt'), fetchFolders('uni')])
+    folders.value = { projekt, uni }
+  })
+}
+
 async function loadProviders() {
-  try {
+  await guard('Failed to load providers:', async () => {
     providers.value = await fetchProviders()
     const current = providers.value.find((p) => p.id === provider.value)
     if (current && !current.available) {
       const fallback = providers.value.find((p) => p.available)
       if (fallback) setProvider(fallback.id)
     }
-  } catch (e) {
-    console.error('Fehler beim Laden der Provider:', e)
-  }
+  })
 }
-let pollTimer = null
 
 function applyTheme() {
   document.documentElement.classList.toggle('dark', darkMode.value)
@@ -84,12 +94,7 @@ function onSidebarLeave() {
   if (!sidebarPinned.value) sidebarSticky.value = false
 }
 
-const projectNames = computed(() => projects.value.map((p) => p.name))
-
-const topics = computed(() => {
-  const isProject = new Set(projectNames.value)
-  return backendTopics.value.filter((t) => !isProject.has(t))
-})
+const topics = computed(() => backendTopics.value)
 
 const doneByFormat = computed(() => {
   const map = {}
@@ -122,174 +127,284 @@ async function loadTopics() {
   try {
     backendTopics.value = await fetchTopics()
   } catch (e) {
-    console.error('Fehler beim Laden der Themen:', e)
+    console.error('Failed to load topics:', e)
   }
 }
 
-// Fehlermeldungen verhalten sich wie Flash-Messages: × blendet aus,
-// beim Reload sind Alt-Fehler von vornherein ausgeblendet.
-const dismissedErrors = ref(new Set())
-let errorsInitialized = false
+// Dismissed errors stay dismissed — even across reloads (localStorage).
+// Errors that aren't dismissed stay visible until the user closes them.
+const dismissedErrors = ref(new Set(JSON.parse(localStorage.getItem('dismissedErrors') || '[]')))
+
+function persistDismissed() {
+  localStorage.setItem('dismissedErrors', JSON.stringify([...dismissedErrors.value]))
+}
 
 function handleDismissError(guideId) {
   dismissedErrors.value = new Set([...dismissedErrors.value, guideId])
+  persistDismissed()
 }
 
 async function loadGuides() {
   try {
     guides.value = await fetchGuides()
-    if (!errorsInitialized) {
-      errorsInitialized = true
-      dismissedErrors.value = new Set(guides.value.filter((g) => g.status === 'error').map((g) => g.id))
+    // Prune IDs whose guide no longer exists as an error
+    const errorIds = new Set(guides.value.filter((g) => g.status === 'error').map((g) => g.id))
+    if ([...dismissedErrors.value].some((id) => !errorIds.has(id))) {
+      dismissedErrors.value = new Set([...dismissedErrors.value].filter((id) => errorIds.has(id)))
+      persistDismissed()
     }
     loadStats()
   } catch (e) {
-    console.error('Fehler beim Laden:', e)
+    console.error('Failed to load:', e)
   }
 }
 
-async function loadBausteine() {
+async function loadBlocks() {
   try {
-    activeBausteine.value = await fetchActiveBausteine()
+    activeBlocks.value = await fetchActiveBlocks()
     if (selectedTopic.value) {
-      bausteine.value = await fetchBausteineStatus(selectedTopic.value)
-      fortschritt.value = await fetchTopicFortschritt(selectedTopic.value)
+      blocks.value = await fetchBlocksStatus(selectedTopic.value)
+      progress.value = await fetchTopicProgress(selectedTopic.value)
     } else {
-      bausteine.value = { ...EMPTY_BAUSTEINE }
-      fortschritt.value = {}
+      blocks.value = { ...EMPTY_BLOCKS }
+      progress.value = {}
     }
-    if (activeBausteine.value.length && !pollTimer) startPolling()
+    if (activeBlocks.value.length && !polling.running()) startPolling()
   } catch (e) {
-    console.error('Fehler beim Laden der Bausteine:', e)
+    console.error('Failed to load blocks:', e)
   }
 }
 
-async function loadProjects() {
-  try {
-    projects.value = await fetchProjects()
-  } catch (e) {
-    console.error('Fehler beim Laden der Projekte:', e)
-  }
-}
-
-const FORMAT_ORDER = ['OnePager', 'MiniGuide', 'Guide', 'FullGuide']
-
-function autoPreview() {
-  const map = doneByFormat.value
-  for (const f of FORMAT_ORDER) {
-    if (map[f]) {
-      previewGuide.value = map[f]
-      return
-    }
-  }
-  previewGuide.value = null
-}
-
 function selectTopic(topic) {
   selectedTopic.value = topic
   previewGuide.value = null
   sidebarSticky.value = false
-  elementsOpen.value = false
-  elementsView.value = false
-  elementOpenId.value = null
+  mainView.value = 'generation'   // topic click → generation board (guide only on pill click)
+  viewMode.value = localStorage.getItem('ansicht_' + topic) === 'erklärend' ? 'erklärend' : 'compact'
   localStorage.setItem('lastTopic', topic)
-  loadBausteine()
-  nextTick(autoPreview)
+  loadBlocks()
 }
 
-// Beim Reload dort landen, wo man vorher war (Thema + Format)
+// On reload, land where you were before (topic + format)
 watch(previewGuide, (g) => {
   if (g) localStorage.setItem('lastFormat', g.format)
 })
 
-async function createTopic(topic) {
-  await apiCreateTopic(topic)
-  await loadTopics()
-  selectedTopic.value = topic
-  previewGuide.value = null
-  loadBausteine()
-}
-
-async function handleCancelBausteine() {
+async function handleCancelBlocks() {
   if (!selectedTopic.value) return
   await apiCancelBausteine(selectedTopic.value)
-  await loadBausteine()
+  await loadBlocks()
 }
 
-async function handleResetBausteine() {
+async function handleResetBlocks() {
   if (!selectedTopic.value) return
   await apiDeleteBausteine(selectedTopic.value)
-  await loadBausteine()
+  await loadBlocks()
 }
 
-async function handleBausteineClick({ instructions }) {
+async function handleResetStage({ board, stage, restart = false }) {
   if (!selectedTopic.value) return
-  await apiCreateBausteine(selectedTopic.value, instructions, provider.value)
-  await loadBausteine()
+  uiError.value = null
+  try {
+    await apiResetBlocksStage(selectedTopic.value, board, stage)
+    if (restart) await apiCreateBausteine(selectedTopic.value, '', provider.value, undefined, undefined, false)  // Continue: Queue abarbeiten
+  } catch (e) {
+    uiError.value = e.message
+    return
+  }
+  await loadBlocks()
+  if (restart) startPolling()
+}
+
+async function handleAddResearch() {
+  if (!selectedTopic.value) return
+  uiError.value = null
+  try {
+    await apiAddResearch(selectedTopic.value, provider.value)
+  } catch (e) {
+    uiError.value = e.message
+    return
+  }
+  await loadBlocks()
   startPolling()
 }
 
-async function handleFormatClick({ format, instructions }) {
+async function handleRequeueDead() {
   if (!selectedTopic.value) return
-  // Kein Duplikat-Start: läuft für Thema+Format schon eine Generierung, ignorieren
+  await apiRequeueDead(selectedTopic.value)
+  await apiCreateBausteine(selectedTopic.value, '', provider.value, undefined, undefined, false)
+  await loadBlocks()
+  startPolling()
+}
+
+async function handleBlocksClick({ instructions = '', research = true, qaForce = false }) {
+  if (!selectedTopic.value) return
+  uiError.value = null
+  try {
+    // research=true = Start/mehr Research anhängen; false = Continue (Queue abarbeiten).
+    await apiCreateBausteine(selectedTopic.value, instructions, provider.value, undefined, undefined, research, qaForce)
+  } catch (e) {
+    uiError.value = e.message
+    return
+  }
+  await loadBlocks()
+  startPolling()
+}
+
+async function handleCreateTopic({ topic, instructions, sourceType, sourceOrt }) {
+  uiError.value = null
+  try {
+    await apiCreateBausteine(topic, instructions, provider.value, sourceType, sourceOrt)
+  } catch (e) {
+    uiError.value = e.message
+    return
+  }
+  await loadTopics()
+  selectTopic(topic)
+  mainView.value = 'generation'  // frisches Topic: die Boards sind das Einzige, was passiert
+  startPolling()
+}
+
+async function handleUpdateSource({ topic, type, ort, spec }) {
+  uiError.value = null
+  try {
+    await apiUpdateQuelle(topic, { type, ort, spec })
+  } catch (e) {
+    uiError.value = e.message
+    return
+  }
+  await loadBlocks()  // the step display may follow the new source (e.g. link → "load source")
+}
+
+function setView(modus) {
+  viewMode.value = modus
+  if (selectedTopic.value) localStorage.setItem('ansicht_' + selectedTopic.value, modus)
+}
+
+function setLevel(k) {
+  levelView.value = k
+  localStorage.setItem('level', String(k))
+}
+
+function handleOpenBlocksView() {
+  if (!selectedTopic.value) return
+  mainView.value = 'blocks'
+  previewGuide.value = null
+}
+
+async function handleFormatClick({ format, instructions = '', abStep = null }) {
+  if (!selectedTopic.value) return
+  // No duplicate start: if a generation is already running for topic+format, ignore
   const running = guides.value.some(
     (g) => g.topic === selectedTopic.value && g.format === format
       && (g.status === 'generating' || g.status === 'queued'),
   )
-  if (running) return
-  await apiCreate(selectedTopic.value, format, instructions, provider.value)
+  if (running) { handleOpenGuideBoard(format); return }
+  uiError.value = null
+  try {
+    await apiCreate(selectedTopic.value, format, instructions, provider.value, abStep)
+  } catch (e) {
+    uiError.value = e.message
+    return
+  }
+  handleOpenGuideBoard(format)  // Start → direkt aufs Live-Board
   await loadGuides()
   startPolling()
 }
 
-async function handleDeleteProject(name) {
-  await apiDeleteProject(name)
-  if (selectedTopic.value === name) {
-    selectedTopic.value = null
-    previewGuide.value = null
+function handleOpenGuideBoard(format = 'Guide') {
+  if (!selectedTopic.value) return
+  guideBoardFormat.value = format
+  mainView.value = 'generation'
+  previewGuide.value = null
+}
+
+function handleOpenGeneration() {
+  if (!selectedTopic.value) return
+  mainView.value = 'generation'
+  previewGuide.value = null
+}
+
+async function handleRemoveGuideFormat(format) {
+  uiError.value = null
+  try {
+    await apiRemoveGuideFormat(selectedTopic.value, format)
+  } catch (e) {
+    uiError.value = e.message
+    return
   }
-  await loadProjects()
+  await loadGuides()
+}
+
+async function handleRestartCard(cardId) {
+  uiError.value = null
+  try {
+    await apiRestartBlocksCard(selectedTopic.value, cardId)
+    await handleBlocksClick({ research: false })  // Continue: der Flow zieht die Karte
+  } catch (e) {
+    uiError.value = e.message
+  }
+}
+
+async function handleResetGuideCard({ format, blockNorm, abStage }) {
+  uiError.value = null
+  try {
+    await apiResetGuideCard(selectedTopic.value, format, blockNorm, abStage)
+  } catch (e) {
+    uiError.value = e.message
+  }
+}
+
+async function handleGuideBoardReset({ format, abStage }) {
+  uiError.value = null
+  try {
+    await apiResetGuideBoard(selectedTopic.value, format, abStage)
+  } catch (e) {
+    uiError.value = e.message
+  }
+}
+
+function handleGuideBoardPreview() {
+  const g = doneByFormat.value[guideBoardFormat.value]
+  if (g) handlePreview(g)
 }
 
 function handlePreview(guide) {
   previewGuide.value = guide
-  elementsView.value = false
+  mainView.value = 'detail'
 }
 
-function handleOpenElements() {
+function handleGeneralExam() {
   if (!selectedTopic.value) return
-  elementsView.value = true
-  // Rechte Sidebar bleibt zu — sie öffnet erst beim Klick auf ein Element.
+  mainView.value = 'general'
+  previewGuide.value = null
 }
 
-function handleOpenElementDetail(el) {
-  elementOpenId.value = el.id
-  elementOpenTick.value++
-  elementsOpen.value = true
+function handlePractice() {
+  if (!selectedTopic.value) return
+  mainView.value = 'practice'
+  previewGuide.value = null
 }
 
 async function handleDeleteGuide(guideId, slots = false) {
-  await deleteGuide(guideId, slots)
+  uiError.value = null
+  try {
+    await deleteGuide(guideId, slots)
+  } catch (e) {
+    uiError.value = e.message
+    return
+  }
   if (previewGuide.value?.id === guideId) {
     previewGuide.value = null
   }
   await loadGuides()
 }
 
-function startPolling() {
-  stopPolling()
-  pollTimer = setInterval(async () => {
-    await Promise.all([loadGuides(), loadBausteine(), loadTopics()])
-    if (!hasActiveGuides.value && !activeBausteine.value.length) stopPolling()
-  }, 3000)
-}
-
-function stopPolling() {
-  if (pollTimer) {
-    clearInterval(pollTimer)
-    pollTimer = null
-  }
-}
+const polling = usePolling(
+  () => Promise.all([loadGuides(), loadBlocks(), loadTopics()]),
+  () => hasActiveGuides.value || activeBlocks.value.length > 0,
+)
+const startPolling = polling.start
 
 async function handleCancel(guideId) {
   await apiCancel(guideId)
@@ -311,107 +426,121 @@ async function handleDeleteTopic(topic) {
   await loadGuides()
 }
 
-function onVisibility() {
-  if (document.hidden) {
-    stopPolling()
-  } else {
-    loadGuides()
-    loadBausteine()
-    if (hasActiveGuides.value || activeBausteine.value.length) startPolling()
-  }
-}
-
 onMounted(async () => {
-  await Promise.all([loadGuides(), loadTopics(), loadProjects(), loadProviders()])
+  await Promise.all([loadGuides(), loadTopics(), loadProviders(), loadFolders()])
   const savedTopic = localStorage.getItem('lastTopic')
-  const savedFormat = localStorage.getItem('lastFormat')
-  if (savedTopic && [...topics.value, ...projectNames.value].includes(savedTopic)) {
-    selectTopic(savedTopic)
-    await nextTick()
-    const g = doneByFormat.value[savedFormat]
-    if (g) previewGuide.value = g
+  if (savedTopic && topics.value.includes(savedTopic)) {
+    selectTopic(savedTopic)  // lands on the blocks overview
   } else if (!selectedTopic.value && topics.value.length) {
     selectTopic(topics.value[0])
   }
-  document.addEventListener('visibilitychange', onVisibility)
-})
-
-onUnmounted(() => {
-  stopPolling()
-  document.removeEventListener('visibilitychange', onVisibility)
 })
 </script>
 
 <template>
-  <div class="layout" :class="{ 'sidebar-floating': !sidebarPinned, 'sidebar-open': sidebarSticky }">
+  <div class="layout" :class="{ 'sidebar-floating': !sidebarPinned, 'sidebar-open': sidebarSticky, 'sidebar-over-fokus': focusOpen && sidebarSticky }">
     <div v-if="!sidebarPinned" class="hover-zone" @click="clickHoverZone"></div>
-    <div v-if="!sidebarPinned && sidebarSticky" class="sidebar-backdrop" @click="sidebarSticky = false"></div>
+    <div v-if="(!sidebarPinned && sidebarSticky) || (focusOpen && sidebarSticky)" class="sidebar-backdrop" @click="sidebarSticky = false"></div>
     <TopicSidebar
       :topics="topics"
-      :projects="projectNames"
       :selectedTopic="selectedTopic"
       :stats="stats"
-      :fortschritt="fortschritt"
+      :fortschritt="progress"
+      :uiError="uiError"
       :doneByFormat="doneByFormat"
       :latestByFormat="latestByFormat"
       :allGuides="guides"
       :dismissedErrors="dismissedErrors"
-      :bausteine="bausteine"
-      :activeBausteine="activeBausteine"
+      :blocks="blocks"
+      :activeBausteine="activeBlocks"
       :pinned="sidebarPinned"
       :dark="darkMode"
       :provider="provider"
       :providers="providers"
+      :folders="folders"
+      :ansichtModus="viewMode"
+      :stufeAnsicht="levelView"
       @setProvider="setProvider"
       @toggleDark="toggleDark"
+      @setAnsicht="setView"
+      @setStufe="setLevel"
+      @generalExam="handleGeneralExam"
+      @practice="handlePractice"
       @select="selectTopic"
-      @create="createTopic"
-      @formatClick="handleFormatClick"
-      @bausteineClick="handleBausteineClick"
-      @cancelBausteine="handleCancelBausteine"
-      @resetBausteine="handleResetBausteine"
+      @createThema="handleCreateTopic"
+      @updateSource="handleUpdateSource"
+      @openBausteineView="handleOpenBlocksView"
+      @openGuideBoard="handleOpenGuideBoard"
+      @bausteineClick="handleBlocksClick"
       @deleteTopic="handleDeleteTopic"
-      @deleteProject="handleDeleteProject"
-      @cancelGuide="handleCancel"
-      @deleteGuide="handleDeleteGuide"
       @dismissError="handleDismissError"
+      @dismissUiError="uiError = null"
       @preview="handlePreview"
-      @openElements="handleOpenElements"
+      @openGeneration="handleOpenGeneration"
       @togglePin="toggleSidebarPin"
       @sidebarLeave="onSidebarLeave"
     />
-    <ElementsOverview
-      v-if="selectedTopic && elementsView"
+    <BlocksOverview
+      v-if="selectedTopic && mainView === 'blocks'"
+      :topic="selectedTopic"
+      :generating="blocks.generating"
+      :progress="blocks.progress"
+      :ready="blocks.ready"
+      :partial="blocks.partial"
+      @close="mainView = 'detail'"
+      @openGeneration="handleOpenGeneration"
+    />
+    <GenerationView
+      v-else-if="selectedTopic && mainView === 'generation'"
+      :topic="selectedTopic"
+      :generating="blocks.generating"
+      :progress="blocks.progress"
+      :ready="blocks.ready"
+      :partial="blocks.partial"
+      :guideFormat="guideBoardFormat"
+      @close="mainView = 'blocks'"
+      @resetStage="handleResetStage"
+      @restartAll="() => handleBlocksClick({ research: true })"
+      @continueAll="(opts) => handleBlocksClick({ research: false, qaForce: !!(opts && opts.qaForce) })"
+      @addResearch="handleAddResearch"
+      @requeueDead="handleRequeueDead"
+      @removeAll="handleResetBlocks"
+      @cancel="handleCancelBlocks"
+      @cancelGuide="handleCancel"
+      @startGuide="handleFormatClick"
+      @resetGuideStage="handleGuideBoardReset"
+      @preview="handleGuideBoardPreview"
+      @removeFormat="handleRemoveGuideFormat"
+      @restartCard="handleRestartCard"
+      @resetGuideCard="handleResetGuideCard"
+    />
+    <GeneralExamPanel
+      v-else-if="selectedTopic && mainView === 'general'"
+      :topic="selectedTopic"
+      :provider="provider"
+      @progressChanged="loadStats(); loadBlocks()"
+      @fokus-active="focusOpen = $event"
+    />
+    <PracticePanel
+      v-else-if="selectedTopic && mainView === 'practice'"
+      :key="selectedTopic"
       :topic="selectedTopic"
-      :version="elementsVersion"
-      @open="handleOpenElementDetail"
     />
     <TopicDetail
       v-else-if="selectedTopic"
       :previewGuide="previewGuide"
-      :dark="darkMode"
       :provider="provider"
-      :elementsOpen="elementsOpen"
-      @progressChanged="loadStats(); loadBausteine()"
-      @openElements="elementsOpen = true"
+      :themaAbgeschlossen="!!progress.completed"
+      :ansichtModus="viewMode"
+      :stufeAnsicht="levelView"
+      @progressChanged="loadStats(); loadBlocks()"
+      @setAnsicht="setView"
+      @open-sidebar="sidebarSticky = true"
+      @fokus-active="focusOpen = $event"
     />
     <div v-else class="empty-main">
-      <p>Thema in der Sidebar anlegen oder auswählen.</p>
+      <p>Create or select a topic in the sidebar.</p>
     </div>
-    <div
-      v-if="elementsOpen && selectedTopic"
-      class="elements-backdrop"
-      @click="elementsOpen = false"
-    ></div>
-    <ElementsSidebar
-      v-if="elementsOpen && selectedTopic"
-      :topic="selectedTopic"
-      :provider="provider"
-      :openId="elementOpenId"
-      :openTick="elementOpenTick"
-      @close="elementsOpen = false"
-      @changed="elementsVersion++"
-    />
   </div>
 </template>
 
@@ -435,6 +564,11 @@ onUnmounted(() => {
   --success-soft: #d1fae5;
   --success-soft-hover: #a7f3d0;
   --success-border: #34d399;
+  /* 4 learning levels: green/blue/purple/gold = Beginner/Advanced/Expert/Master */
+  --level-beginner: #22c55e;
+  --level-advanced: #3b82f6;
+  --level-expert: #8b5cf6;
+  --level-master: #d4af37;
   --warning: #92400e;
   --warning-soft: #fef3c7;
   --warning-border: #fbbf24;
@@ -510,8 +644,8 @@ textarea::placeholder {
   cursor: pointer;
 }
 
-/* Unsichtbare Fläche hinter der offenen Floating-Sidebar.
-   Tipp/Klick daneben schließt sie — ohne sie gibt es auf Touch keinen Ausweg. */
+/* Invisible surface behind the open floating sidebar.
+   A tap/click next to it closes it — without it there's no way out on touch. */
 .sidebar-backdrop {
   position: fixed;
   inset: 0;
@@ -536,6 +670,21 @@ textarea::placeholder {
   transform: translateX(0);
 }
 
+/* Block fullscreen: lift the sidebar as an overlay ABOVE the focus overlay (z-index 40).
+   Applies for pinned AND floating. */
+.layout.sidebar-over-fokus > .sidebar {
+  position: fixed;
+  left: 0;
+  top: 0;
+  height: 100dvh;
+  transform: translateX(0);
+  z-index: 50;
+  box-shadow: 0 0 16px var(--shadow);
+}
+.layout.sidebar-over-fokus .sidebar-backdrop {
+  z-index: 49;
+}
+
 .empty-main {
   flex: 1;
   display: flex;
@@ -545,19 +694,4 @@ textarea::placeholder {
   font-size: 1rem;
 }
 
-/* Nur sichtbar, wenn die Elemente-Sidebar mobil als Overlay liegt.
-   Tipp daneben schließt sie. */
-.elements-backdrop {
-  display: none;
-}
-
-@media (max-width: 768px) {
-  .elements-backdrop {
-    display: block;
-    position: fixed;
-    inset: 0;
-    z-index: 29;
-    background: var(--shadow);
-  }
-}
 </style>

frontend/src/api.js

@@ -1,48 +1,195 @@
 const BASE = '/api'
 
+// Backend-Fehler (400/409 mit detail) als Error werfen statt sie zu verschlucken
+async function jsonOrThrow(res) {
+  if (!res.ok) {
+    let detail = `Fehler (HTTP ${res.status})`
+    try {
+      const data = await res.json()
+      if (data.detail) detail = typeof data.detail === 'string' ? data.detail : JSON.stringify(data.detail)
+    } catch { /* kein JSON-Body */ }
+    throw new Error(detail)
+  }
+  return res.json()
+}
+
 export async function fetchGuides() {
   const res = await fetch(`${BASE}/guides`)
   return res.json()
 }
 
-export async function createGuide(topic, format, instructions = '', provider = 'claude') {
+export async function createGuide(topic, format, instructions = '', provider = 'claude', abStep = null) {
   const res = await fetch(`${BASE}/guides`, {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ topic, format, instructions, provider }),
+    body: JSON.stringify({ topic, format, instructions, provider, ab_step: abStep }),
   })
+  return jsonOrThrow(res)
+}
+
+export async function fetchActiveBlocks() {
+  const res = await fetch(`${BASE}/blocks/active`)
   return res.json()
 }
 
-export async function fetchActiveBausteine() {
-  const res = await fetch(`${BASE}/bausteine/active`)
+export async function fetchBlocksStatus(topic) {
+  const res = await fetch(`${BASE}/blocks/status?topic=${encodeURIComponent(topic)}`)
   return res.json()
 }
 
-export async function fetchBausteineStatus(topic) {
-  const res = await fetch(`${BASE}/bausteine/status?topic=${encodeURIComponent(topic)}`)
-  return res.json()
-}
-
-export async function createBausteine(topic, instructions = '', provider = 'claude') {
-  const res = await fetch(`${BASE}/bausteine`, {
+export async function createBlocks(topic, instructions = '', provider = 'claude', sourceType = 'thema', sourceOrt = '', research = true, qaForce = false) {
+  const res = await fetch(`${BASE}/blocks`, {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ topic, instructions, provider }),
+    body: JSON.stringify({ topic, instructions, provider, source_type: sourceType, source_location: sourceOrt, research, qa_force: qaForce }),
   })
-  return res.json()
+  return jsonOrThrow(res)
 }
 
-export async function cancelBausteine(topic) {
-  await fetch(`${BASE}/bausteine/cancel?topic=${encodeURIComponent(topic)}`, { method: 'POST' })
+// Live-Kanban-Board der Blocks-Erzeugung (Spalten + Karten + Agenten + Dead-Letter).
+export async function fetchBlocksBoard(topic) {
+  const res = await fetch(`${BASE}/blocks/board?topic=${encodeURIComponent(topic)}`)
+  return jsonOrThrow(res)
 }
 
-export async function deleteBausteine(topic) {
-  await fetch(`${BASE}/bausteine?topic=${encodeURIComponent(topic)}`, { method: 'DELETE' })
+// Manueller QA-Lauf (wie das Gate, inkl. LLM-Stichprobe); Badge liest den neuen Report.
+export async function runQa(topic, llm = true) {
+  const res = await fetch(`${BASE}/blocks/qa`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ topic, llm }),
+  })
+  return jsonOrThrow(res)
 }
 
-export async function fetchTopicFortschritt(topic) {
-  const res = await fetch(`${BASE}/topics/fortschritt?topic=${encodeURIComponent(topic)}`)
+// QA-Befunde gezielt beheben (Hygiene, bestätigte Dubletten, Fremd/Unecht nach Gegen-Judge).
+export async function runRepair(topic) {
+  const res = await fetch(`${BASE}/blocks/repair`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ topic }),
+  })
+  return jsonOrThrow(res)
+}
+
+// Karten ab Spalte zurücksetzen (keine Generierung).
+export async function resetBlocksStage(topic, board, stage) {
+  const res = await fetch(`${BASE}/blocks/reset-stage`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ topic, board, stage }),
+  })
+  return jsonOrThrow(res)
+}
+
+// Einen weiteren Research-Agenten anhängen (Attach-or-Start).
+export async function addBlocksResearch(topic, provider = 'claude') {
+  const res = await fetch(`${BASE}/blocks/research?topic=${encodeURIComponent(topic)}&provider=${encodeURIComponent(provider)}`, { method: 'POST' })
+  return jsonOrThrow(res)
+}
+
+export async function restartBlocksCard(topic, cardId) {
+  const res = await fetch(`${BASE}/blocks/card-restart`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ topic, card_id: cardId }),
+  })
+  return jsonOrThrow(res)
+}
+
+export async function removeGuideFormat(topic, format) {
+  const res = await fetch(`${BASE}/guides/board/remove`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ topic, format }),
+  })
+  return jsonOrThrow(res)
+}
+
+export async function resetGuideCard(topic, format, blockNorm, abStage) {
+  const res = await fetch(`${BASE}/guides/board/card-reset`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ topic, format, block_norm: blockNorm, ab_stage: abStage }),
+  })
+  return jsonOrThrow(res)
+}
+
+export async function requeueBlocksDead(topic) {
+  const res = await fetch(`${BASE}/blocks/requeue-dead?topic=${encodeURIComponent(topic)}`, { method: 'POST' })
+  return jsonOrThrow(res)
+}
+
+// Live-Board der Guide-Erzeugung.
+export async function fetchGuideBoard(topic, format = 'Guide') {
+  const res = await fetch(`${BASE}/guides/board?topic=${encodeURIComponent(topic)}&format=${encodeURIComponent(format)}`)
+  return jsonOrThrow(res)
+}
+
+export async function resetGuideBoard(topic, format, abStage) {
+  const res = await fetch(`${BASE}/guides/board/reset`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ topic, format, ab_stage: abStage }),
+  })
+  return jsonOrThrow(res)
+}
+
+// Befunde beheben: Karten mit QA-Befunden zurück auf Prüfen + Resume-Lauf.
+export async function repairGuideBoard(topic, format) {
+  const res = await fetch(`${BASE}/guides/board/repair`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ topic, format, ab_stage: 0 }),
+  })
+  return jsonOrThrow(res)
+}
+
+export async function cancelBlocks(topic) {
+  await fetch(`${BASE}/blocks/cancel?topic=${encodeURIComponent(topic)}`, { method: 'POST' })
+}
+
+export async function deleteBlocks(topic) {
+  await fetch(`${BASE}/blocks?topic=${encodeURIComponent(topic)}`, { method: 'DELETE' })
+}
+
+// --- Block-Learning: Chat, Exam ---
+
+export async function fetchBlockLearnState(topic) {
+  const res = await fetch(`${BASE}/blocks/learnstate?topic=${encodeURIComponent(topic)}`)
+  return jsonOrThrow(res)
+}
+
+export async function chatBlock({ topic, block, section, section_compact = '', messages, provider }) {
+  const res = await fetch(`${BASE}/blocks/chat`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ topic, block, section, section_compact, messages, provider }),
+  })
+  return jsonOrThrow(res)
+}
+
+export async function examBlock({
+  topic, block, section, section_compact = '', provider,
+  action = 'question', question = '', last_rating = '', avoid = [],
+  asked_again = false, reason = '', pattern = '', cap = 6, messages = [], thorough = false,
+  selection = [], correct = [], solution = '', alternatives = [], input = '', schwer = false,
+}) {
+  const res = await fetch(`${BASE}/blocks/exam`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ topic, block, section, section_compact, action, question, last_rating, avoid, asked_again, reason, pattern, cap, messages, provider, thorough, selection, correct, solution, alternatives, input, schwer }),
+  })
+  return jsonOrThrow(res)
+}
+
+export async function fetchQuestionPattern(topic, block) {
+  const res = await fetch(`${BASE}/blocks/question-pattern?topic=${encodeURIComponent(topic)}&block=${encodeURIComponent(block)}`)
+  return jsonOrThrow(res)
+}
+
+export async function fetchTopicProgress(topic) {
+  const res = await fetch(`${BASE}/topics/progress?topic=${encodeURIComponent(topic)}`)
   return res.json()
 }
 
@@ -56,13 +203,33 @@ export async function fetchProviders() {
   return res.json()
 }
 
-export async function fetchProjects() {
-  const res = await fetch(`${BASE}/projects`)
-  return res.json()
+export async function fetchFolders(kind) {
+  const res = await fetch(`${BASE}/folders?kind=${encodeURIComponent(kind)}`)
+  return jsonOrThrow(res)
 }
 
-export async function deleteProject(name) {
-  await fetch(`${BASE}/projects/${encodeURIComponent(name)}`, { method: 'DELETE' })
+export async function fetchSource(topic) {
+  const res = await fetch(`${BASE}/blocks/source?topic=${encodeURIComponent(topic)}`)
+  return jsonOrThrow(res)
+}
+
+export async function updateSource(topic, { type, ort = '', spec = '' }) {
+  const res = await fetch(`${BASE}/blocks/source`, {
+    method: 'PUT',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ topic, type, location: ort, spec }),
+  })
+  return jsonOrThrow(res)
+}
+
+export async function fetchBlocksCompleteness(topic) {
+  const res = await fetch(`${BASE}/blocks/completeness?topic=${encodeURIComponent(topic)}`)
+  return jsonOrThrow(res)
+}
+
+export async function fetchBlocksOverview(topic) {
+  const res = await fetch(`${BASE}/blocks/overview?topic=${encodeURIComponent(topic)}`)
+  return jsonOrThrow(res)
 }
 
 export async function cancelGuide(id) {
@@ -73,12 +240,53 @@ export async function deleteGuide(id, slots = false) {
   await fetch(`${BASE}/guides/${id}${slots ? '?slots=1' : ''}`, { method: 'DELETE' })
 }
 
-export async function fetchGuideContent(id) {
-  const res = await fetch(`${BASE}/guides/${id}/content`)
-  if (!res.ok) throw new Error(`Inhalt nicht verfügbar (${res.status})`)
+export async function fetchGuideContent(id, level = 4) {
+  const res = await fetch(`${BASE}/guides/${id}/content?level=${level}`)
+  if (!res.ok) throw new Error(`Content not available (${res.status})`)
   return res.json()
 }
 
+// Übungspool: fällige + neue Flashcards des Themas (Leitner, ein Stapel).
+export async function fetchPracticeDeck(topic) {
+  const res = await fetch(`${BASE}/practice/deck?topic=${encodeURIComponent(topic)}`)
+  return jsonOrThrow(res)
+}
+
+// Leitner-Schritt buchen (correct = „Gewusst").
+export async function answerPracticeCard({ topic, block_norm, sub_norm, correct }) {
+  const res = await fetch(`${BASE}/practice/answer`, {
+    method: 'POST', headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ topic, block_norm, sub_norm, correct }),
+  })
+  return jsonOrThrow(res)
+}
+
+// Einen Markdown-Block on-demand gegen die Guide-Rules prüfen (Fokus, Rechtsklick).
+export async function pruefeBlock(id, { block, spot, snippet, hint = '', provider }) {
+  const res = await fetch(`${BASE}/guides/${id}/block/pruefen`, {
+    method: 'POST', headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ block, spot, snippet, hint, provider }),
+  })
+  return jsonOrThrow(res)
+}
+
+// Geprüften Block persistent übernehmen (alt → new im jeweiligen Feld).
+export async function uebernehmeBlock(id, { block, spot, alt, revised, provider }) {
+  const res = await fetch(`${BASE}/guides/${id}/block/uebernehmen`, {
+    method: 'POST', headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ block, spot, alt, revised, provider }),
+  })
+  return jsonOrThrow(res)
+}
+
+// Reset a block's learning progress to zero (score/streak/flags/open question).
+export async function resetBlockProgress(topic, block) {
+  const res = await fetch(`${BASE}/blocks/progress?topic=${encodeURIComponent(topic)}&block=${encodeURIComponent(block)}`, {
+    method: 'DELETE',
+  })
+  return jsonOrThrow(res)
+}
+
 export async function fetchTopics() {
   const res = await fetch(`${BASE}/topics`)
   return res.json()
@@ -96,20 +304,6 @@ export async function deleteTopic(name) {
   await fetch(`${BASE}/topics?topic=${encodeURIComponent(name)}`, { method: 'DELETE' })
 }
 
-export async function fetchProgress(id) {
-  const res = await fetch(`${BASE}/guides/${id}/progress`)
-  return res.json()
-}
-
-export async function setProgress(id, chapter, done) {
-  const res = await fetch(`${BASE}/guides/${id}/progress`, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ chapter, done }),
-  })
-  return res.json()
-}
-
 export async function chatGuide(id, { section, outline, messages, provider = 'claude' }) {
   const res = await fetch(`${BASE}/guides/${id}/chat`, {
     method: 'POST',
@@ -119,68 +313,3 @@ export async function chatGuide(id, { section, outline, messages, provider = 'cl
   return res.json()
 }
 
-export async function fetchElements(topic) {
-  const res = await fetch(`${BASE}/elements?topic=${encodeURIComponent(topic)}`)
-  return res.json()
-}
-
-export async function createElement(topic, hint = '', provider = 'claude') {
-  const res = await fetch(`${BASE}/elements`, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ topic, hint, provider }),
-  })
-  return res.json()
-}
-
-export async function chatElement(id, messages, provider = 'claude') {
-  const res = await fetch(`${BASE}/elements/${id}/chat`, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ messages, provider }),
-  })
-  return res.json()
-}
-
-export async function deleteElement(id) {
-  await fetch(`${BASE}/elements/${id}`, { method: 'DELETE' })
-}
-
-export async function updateElement(id, fields) {
-  const res = await fetch(`${BASE}/elements/${id}`, {
-    method: 'PUT',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify(fields),
-  })
-  return res.json()
-}
-
-export async function styleElement(id, provider = 'claude') {
-  const res = await fetch(`${BASE}/elements/${id}/style`, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ provider }),
-  })
-  if (!res.ok) throw new Error(`Stil-Prüfung fehlgeschlagen (${res.status})`)
-  return res.json()
-}
-
-export async function refineSuggestion(id, suggestion, instruction, provider = 'claude') {
-  const res = await fetch(`${BASE}/elements/${id}/refine`, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ suggestion, instruction, provider }),
-  })
-  if (!res.ok) throw new Error(`Überarbeitung fehlgeschlagen (${res.status})`)
-  return res.json()
-}
-
-export async function checkElement(id, provider = 'claude') {
-  const res = await fetch(`${BASE}/elements/${id}/check`, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ provider }),
-  })
-  if (!res.ok) throw new Error(`Prüfung fehlgeschlagen (${res.status})`)
-  return res.json()
-}

frontend/src/assets/markdown.css

@@ -0,0 +1,134 @@
+/* Gemeinsames Markdown-Styling für v-html-Inhalte (renderMarkdown).
+   v-html-Kinder tragen keine data-v-Attribute — daher globale Regeln statt
+   :deep()-Kopien in jeder Komponente. Komponenten-Overrides bleiben scoped
+   und gewinnen per Spezifität (z. B. pre-Scroll in TopicDetail). */
+
+.markdown p {
+  margin: 0 0 0.5em;
+}
+
+/* KaTeX: lange Block-Formeln scrollen statt das Layout zu sprengen.
+   Sichtbarer dünner Scrollbalken (statt unsichtbarem Overlay) → man erkennt,
+   dass die Formel weitergeht und nicht abgeschnitten ist. */
+.markdown .katex-display {
+  overflow-x: auto;
+  overflow-y: hidden;
+  padding: 0.2em 0 0.45em;
+  scrollbar-width: thin;
+  scrollbar-color: var(--border) transparent;
+}
+.markdown .katex-display::-webkit-scrollbar {
+  height: 6px;
+}
+.markdown .katex-display::-webkit-scrollbar-thumb {
+  background: var(--border);
+  border-radius: 3px;
+}
+
+.markdown p:last-child {
+  margin-bottom: 0;
+}
+
+.markdown ul,
+.markdown ol {
+  margin: 0.3em 0;
+  padding-left: 1.2em;
+}
+
+.markdown li {
+  margin: 0.15em 0;
+}
+
+.markdown code {
+  background: var(--border);
+  padding: 1px 4px;
+  border-radius: 4px;
+  font-family: "SF Mono", Consolas, monospace;
+  font-size: 0.85em;
+  /* Lange Bezeichner (Namespaces, Pfade) dürfen umbrechen statt zu überlaufen */
+  overflow-wrap: anywhere;
+}
+
+.markdown pre {
+  background: var(--code-bg, #1e2330);
+  color: var(--code-fg, #e6e8ee);
+  padding: 10px 12px;
+  border-radius: 8px;
+  /* Default: umbrechen (schmale Sidebars/Karten) — die breite Lese-Ansicht
+     in TopicDetail überschreibt auf horizontales Scrollen */
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+  margin: 0.5em 0;
+}
+
+.markdown pre code {
+  background: none;
+  padding: 0;
+  color: inherit;
+  font-size: 0.85em;
+}
+
+.markdown h1,
+.markdown h2,
+.markdown h3 {
+  font-size: 0.95em;
+  margin: 0.6em 0 0.3em;
+}
+
+.markdown a {
+  color: var(--accent-hover);
+}
+
+.markdown table {
+  border-collapse: collapse;
+  font-size: 0.95em;
+}
+
+.markdown th,
+.markdown td {
+  border: 1px solid var(--border-strong);
+  padding: 2px 6px;
+}
+
+/* Stufen-Segmente (Vollansicht): dezenter Rand + A/F/E-Badge. Global, weil TopicDetail
+   das Markup per v-html injiziert (scoped-Styles greifen dort nicht). */
+.sub-stufe {
+  position: relative;
+  border-left: 3px solid color-mix(in srgb, var(--stufe-farbe) 55%, transparent);
+  padding-left: 0.75rem;
+  margin: 0.5rem 0;
+  border-radius: 2px;
+}
+.sub-stufe-badge {
+  position: absolute;
+  top: 0.1rem;
+  right: 0;
+  font-size: 0.62rem;
+  font-weight: 700;
+  color: var(--stufe-farbe);
+  border: 1px solid color-mix(in srgb, var(--stufe-farbe) 60%, transparent);
+  border-radius: 4px;
+  padding: 0 4px;
+  opacity: 0.55;
+}
+
+/* Neu freigeschaltete Subbausteine (Auto-Stufe): kräftigerer Rand + Stufen-Badge */
+.sub-neu {
+  position: relative;
+  border-left: 3px solid var(--neu-farbe);
+  padding-left: 0.75rem;
+  margin: 0.5rem 0;
+  border-radius: 2px;
+}
+.sub-neu-badge {
+  position: absolute;
+  top: 0.1rem;
+  right: 0;
+  font-size: 0.62rem;
+  font-weight: 700;
+  color: var(--neu-farbe);
+  border: 1px solid var(--neu-farbe);
+  border-radius: 4px;
+  padding: 0 4px;
+  opacity: 0.8;
+}

frontend/src/components/BlockFocus.vue

@@ -0,0 +1,436 @@
+<script setup>
+import BlockPanel from './BlockPanel.vue'
+import { renderMarkdown, renderBlocks } from '../markdown.js'
+import { stufeFuer, SUB_RANK, VIEW_KURZ, VIEW_FARBE } from '../levels.js'
+import { pruefeBlock, uebernehmeBlock, resetBlockProgress } from '../api.js'
+import { clearPruef } from '../pruefungCache.js'
+import { useConfirm } from '../composables/useConfirm.js'
+
+const props = defineProps({
+  block: { type: Object, required: true }, // { title, md, num }
+  topic: { type: String, required: true },
+  provider: { type: String, default: 'claude' },
+  status: { type: Object, default: null },
+  cap: { type: Number, default: 6 },
+  guideId: { type: String, default: '' },
+  tab: { type: String, default: 'exam' },
+  ansicht: { type: String, default: 'compact' }, // compact | erklärend — left guide column
+  hasPrev: { type: Boolean, default: false },
+  hasNext: { type: Boolean, default: false },
+  fortschritt: { type: Object, default: () => ({ total: 0, beginner: 0, advanced: 0, expert: 0, master: 0 }) },
+})
+
+import { computed, onMounted, onUnmounted, reactive, ref, watch } from 'vue'
+
+const emit = defineEmits(['close', 'prev', 'next', 'statusChanged', 'setAnsicht', 'openSidebar', 'sectionUpdated'])
+
+// --- Reset per block: questions session (slot) resp. progress (score) ---
+const { isArmed, armOrRun } = useConfirm()
+const resetN = ref(0)  // increment → panel remount (fresh slot, patterns reset)
+const examKey = computed(() => `${props.topic}::${props.block.title}`)
+
+// New question session: discard slot → remount loads patterns + pool fresh (fixes explain-only).
+function resetQuestions() {
+  clearPruef(examKey.value)
+  resetN.value++
+}
+
+// Progress to 0: delete DB row, zero badge/learn state, fresh session.
+async function resetProgress() {
+  try {
+    await resetBlockProgress(props.topic, props.block.title)
+    emit('statusChanged', { block: props.block.title, good_answers: 0, streak: 0, cap: props.cap })
+    clearPruef(examKey.value)
+    resetN.value++
+  } catch (e) { /* stay quiet — reset failed */ }
+}
+
+const guideEl = ref(null)  // left guide column (scroll target for ALT+↑/↓)
+const rightEl = ref(null)  // right column (exam panel with input field)
+
+// ALT is the modifier of the focus view. Plain arrows stay browser-default.
+// ALT+←/→ pages blocks, ALT+↑/↓ scrolls the guide. A bare ALT tap
+// (press+release without another key) toggles focus on the input field.
+let altAlone = false
+function onKeyDown(e) {
+  if (e.key === 'Alt') { altAlone = true; e.preventDefault(); return }  // suppresses the Firefox menu bar
+  if (e.ctrlKey || e.metaKey || !e.altKey) return  // plain/other → normal
+  altAlone = false                                  // ALT+anything = no lone tap
+  if (e.key === 'ArrowLeft') { e.preventDefault(); if (!e.repeat && props.hasPrev) emit('prev') }
+  else if (e.key === 'ArrowRight') { e.preventDefault(); if (!e.repeat && props.hasNext) emit('next') }
+  else if (e.key === 'ArrowUp') { e.preventDefault(); guideEl.value?.scrollBy(0, -120) }
+  else if (e.key === 'ArrowDown') { e.preventDefault(); guideEl.value?.scrollBy(0, 120) }
+}
+function onKeyUp(e) {
+  if (e.key === 'Alt') { e.preventDefault(); if (altAlone) { altAlone = false; toggleInput() } }
+}
+function resetAlt() { altAlone = false }  // window blur (ALT+Tab) → no false tap
+function toggleInput() {
+  // Answer field of the current form: explain = textarea, free gap-text = input.
+  const el = rightEl.value?.querySelector('textarea, input')
+  if (!el) return
+  document.activeElement === el ? el.blur() : el.focus()
+}
+onMounted(() => {
+  window.addEventListener('keydown', onKeyDown)
+  window.addEventListener('keyup', onKeyUp)
+  window.addEventListener('blur', resetAlt)
+})
+onUnmounted(() => {
+  window.removeEventListener('keydown', onKeyDown)
+  window.removeEventListener('keyup', onKeyUp)
+  window.removeEventListener('blur', resetAlt)
+})
+
+const pct = (n) => (100 * n / (props.fortschritt.total || 1)) + '%'
+
+// Accent color by the current block's level (green/blue/purple/gold) or neutral.
+const levelColor = computed(() => {
+  const s = props.status || {}
+  return stufeFuer(s.good_answers || 0, s.cap || props.cap)?.farbe || 'var(--border)'
+})
+const level = computed(() => {
+  const s = props.status || {}
+  return stufeFuer(s.good_answers || 0, s.cap || props.cap)
+})
+
+// --- Check block (right-click on a section) ---
+const displayedText = computed(() =>
+  props.ansicht === 'compact' ? (props.block.compact || props.block.md) : props.block.md,
+)
+// Stufen-Segmente: mit subs wird je Sub separat gerendert (Rand+Badge in Stufen-Farbe),
+// ohne subs (Legacy) bleibt der flache Pfad. Globaler Block-Index läuft über alle
+// Segmente durch — Check/Vorschläge arbeiten unverändert über Index + raw.
+const segments = computed(() => {
+  const compact = props.ansicht === 'compact'
+  const subs = props.block.subs
+  let i = 0
+  const seg = (level, text) => ({ level, blocks: renderBlocks(text).map((b) => ({ ...b, i: i++ })) })
+  if (!subs || !subs.length) return [seg('', displayedText.value)]
+  const out = []
+  const anchor = compact ? (props.block.anker_compact || '') : (props.block.anchor || '')
+  if (anchor.trim()) out.push(seg('', anchor))
+  for (const sub of subs) {
+    const body = compact ? (sub.compact || sub.md) : (sub.md || sub.compact)
+    if (body && body.trim()) out.push(seg(sub.level, body))
+  }
+  return out
+})
+const blocks = computed(() => segments.value.flatMap((s) => s.blocks))
+// Field that edits are applied to (must match the displayed text).
+const spot = computed(() => (props.ansicht === 'compact' && props.block.compact) ? 'compact' : 'ausführlich')
+
+const menu = reactive({ show: false, x: 0, y: 0, index: null })
+function blockMenu(i, e) { menu.show = true; menu.x = e.clientX; menu.y = e.clientY; menu.index = i }
+function closeMenu() { menu.show = false }
+
+// Suggestion per block index: { new, running, error, editOpen, hint }
+const suggestions = reactive({})
+
+async function checkBlock(i, extra = '') {
+  const raw = blocks.value[i]?.raw
+  if (!raw || !props.guideId) return
+  closeMenu()
+  suggestions[i] = { revised: '', running: true, error: '', editOpen: false, hint: '' }
+  try {
+    const res = await pruefeBlock(props.guideId, { block: props.block.title, spot: spot.value, snippet: raw, hint: extra, provider: props.provider })
+    suggestions[i] = { revised: res.revised, running: false, error: '', editOpen: false, hint: '' }
+  } catch (e) {
+    suggestions[i] = { revised: '', running: false, error: e.message || 'Exam failed', editOpen: false, hint: '' }
+  }
+}
+
+async function applyBlock(i) {
+  const v = suggestions[i]; const raw = blocks.value[i]?.raw
+  if (!v || v.running || !raw) return
+  v.running = true; v.error = ''
+  try {
+    const res = await uebernehmeBlock(props.guideId, { block: props.block.title, spot: spot.value, alt: raw, revised: v.revised, provider: props.provider })
+    if (res.found) emit('sectionUpdated', { title: props.block.title, compact: res.compact, md: res.md })
+    else { v.running = false; v.error = 'Spot not found — may have already changed.' }
+  } catch (e) { v.running = false; v.error = e.message || 'Apply failed' }
+}
+
+function discardBlock(i) { delete suggestions[i] }
+function editBlock(i) { const v = suggestions[i]; if (v) v.editOpen = !v.editOpen }
+function sendBlockEdit(i) {
+  const z = (suggestions[i]?.hint || '').trim()
+  if (z) checkBlock(i, z)
+}
+
+// Block/content switch → reset suggestions + menu (block indices change).
+watch(() => `${props.block.title}|${props.block.md}|${props.block.compact || ''}`, () => {
+  for (const k of Object.keys(suggestions)) delete suggestions[k]
+  closeMenu()
+})
+</script>
+
+<template>
+  <div class="fokus-overlay" :style="{ '--stand': levelColor }">
+    <div class="fokus-bar">
+      <div class="fokus-bar-inner">
+        <button class="fokus-btn" title="Open navigation" @click="$emit('openSidebar')">☰</button>
+        <button class="fokus-btn" :disabled="!hasPrev" title="Previous block" @click="$emit('prev')">←</button>
+        <button class="fokus-btn" :disabled="!hasNext" title="Next block" @click="$emit('next')">→</button>
+        <span class="fokus-title">{{ block.title }}</span>
+        <span v-if="level" class="stand-badge" :style="{ color: level.farbe, borderColor: level.farbe }">{{ level.kurz }} {{ level.label }}</span>
+        <span class="fokus-spacer"></span>
+        <button class="fokus-btn" title="Reset questions (new question session)" @click="resetQuestions">↻</button>
+        <button
+          class="fokus-btn"
+          :class="{ armed: isArmed('reset-fortschritt') }"
+          :title="isArmed('reset-fortschritt') ? 'Click again: set progress to 0' : 'Reset progress (score to 0)'"
+          @click="armOrRun('reset-fortschritt', resetProgress)"
+        >⟲</button>
+        <button class="fokus-btn" title="Exit full view" @click="$emit('close')">✕</button>
+      </div>
+    </div>
+    <div class="fokus-xp" :title="`${fortschritt.beginner}/${fortschritt.total} from Beginner · ${fortschritt.advanced} Advanced · ${fortschritt.expert} Expert · ${fortschritt.master} Master`">
+      <div class="xp-seg" :style="{ width: pct(fortschritt.master), background: 'var(--level-master)' }"></div>
+      <div class="xp-seg" :style="{ width: pct(fortschritt.expert - fortschritt.master), background: 'var(--level-expert)' }"></div>
+      <div class="xp-seg" :style="{ width: pct(fortschritt.advanced - fortschritt.expert), background: 'var(--level-advanced)' }"></div>
+      <div class="xp-seg" :style="{ width: pct(fortschritt.beginner - fortschritt.advanced), background: 'var(--level-beginner)' }"></div>
+    </div>
+    <div class="fokus-body">
+      <div ref="guideEl" class="fokus-col left">
+        <div class="markdown">
+          <template v-for="(seg, si) in segments" :key="si">
+            <div :class="{ 'sub-stufe': !!seg.level }"
+                 :style="seg.level ? { '--stufe-farbe': VIEW_FARBE[SUB_RANK[seg.level] || 1] } : null">
+              <span v-if="seg.level" class="sub-stufe-badge"
+                    :title="`Stufe ${VIEW_KURZ[SUB_RANK[seg.level] || 1]}`">{{ VIEW_KURZ[SUB_RANK[seg.level] || 1] }}</span>
+              <template v-for="b in seg.blocks" :key="b.i">
+                <div class="md-block" v-html="b.html" @contextmenu.prevent="blockMenu(b.i, $event)"></div>
+                <div v-if="suggestions[b.i]" class="block-vorschlag">
+                  <div v-if="suggestions[b.i].running" class="bv-status">Check Section…</div>
+                  <template v-else>
+                    <p v-if="suggestions[b.i].error" class="bv-fehler">{{ suggestions[b.i].error }}</p>
+                    <div class="markdown bv-new" v-html="renderMarkdown(suggestions[b.i].revised)"></div>
+                    <div class="bv-aktionen">
+                      <button class="bv-btn ja" title="Apply" @click="applyBlock(b.i)">✓</button>
+                      <button class="bv-btn" title="Discard" @click="discardBlock(b.i)">✗</button>
+                      <button class="bv-btn" :class="{ aktiv: suggestions[b.i].editOpen }" title="Add hint" @click="editBlock(b.i)">✏️</button>
+                    </div>
+                    <div v-if="suggestions[b.i].editOpen" class="bv-edit">
+                      <input v-model="suggestions[b.i].hint" class="bv-input" placeholder="Extra info → check again" @keyup.enter="sendBlockEdit(b.i)" />
+                      <button class="bv-btn ja" title="Check again" @click="sendBlockEdit(b.i)">↻</button>
+                    </div>
+                  </template>
+                </div>
+              </template>
+            </div>
+          </template>
+        </div>
+      </div>
+      <div v-if="menu.show" class="menu-overlay" @click="closeMenu" @contextmenu.prevent="closeMenu">
+        <div class="block-menu" :style="{ top: menu.y + 'px', left: menu.x + 'px' }" @click.stop>
+          <button class="bm-item" @click="checkBlock(menu.index)">Check</button>
+        </div>
+      </div>
+      <div ref="rightEl" class="fokus-col right">
+        <BlockPanel
+          mode="full"
+          :key="block.title + '|' + tab + '|' + resetN"
+          :initial-tab="tab"
+          :topic="topic"
+          :block="block.title"
+          :section="block.md"
+          :section-compact="block.compact || ''"
+          :provider="provider"
+          :status="status"
+          :cap="cap"
+          :ansicht="ansicht"
+          @set-ansicht="$emit('setAnsicht', $event)"
+          @status-changed="$emit('statusChanged', $event)"
+        />
+      </div>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.fokus-overlay {
+  position: fixed;
+  inset: 0;
+  z-index: 40;
+  /* Semi-transparent + blur: the guide list behind shows blurred through the gray surfaces. */
+  background: color-mix(in srgb, var(--bg-preview) 60%, transparent);
+  backdrop-filter: blur(10px);
+  display: grid;
+  grid-template-rows: auto auto 1fr; /* header / XP bar / body */
+}
+.fokus-bar {
+  padding: 0.5rem 0;
+  border-bottom: 1px solid var(--border);
+  background: var(--panel);
+}
+/* Header content aligns with the body (same max-width + inner padding). */
+.fokus-bar-inner {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  max-width: 1600px;
+  width: 100%;
+  margin-inline: auto;
+  padding-inline: 1.25rem;
+}
+.fokus-spacer { flex: 1; }
+
+.stand-badge {
+  margin-left: 0.5rem;
+  padding: 0.12rem 0.6rem;
+  font-size: 0.72rem; font-weight: 600;
+  border-radius: 999px; border: 1px solid; white-space: nowrap;
+}
+.stand-badge.gruen { background: var(--success-soft); border-color: var(--success-border); color: var(--success); }
+.stand-badge.lila  { background: color-mix(in srgb, #8b5cf6 16%, var(--panel)); border-color: #8b5cf6; color: #6d28d9; }
+.stand-badge.gold  { background: color-mix(in srgb, #d4af37 20%, var(--panel)); border-color: #d4af37; color: #8a6d12; }
+
+/* Experience bar on top: fills from the left — gold (mastered) → purple (understood) → green (completed). */
+.fokus-xp { position: relative; display: flex; height: 8px; background: var(--panel-soft); }
+/* 9 divider lines every 10% → 10 visible segments (fill stays continuous). */
+.fokus-xp::after {
+  content: '';
+  position: absolute; inset: 0;
+  pointer-events: none;
+  background: repeating-linear-gradient(
+    to right,
+    transparent 0,
+    transparent calc(10% - 2px),
+    var(--panel) calc(10% - 2px),
+    var(--panel) 10%
+  );
+}
+.xp-seg { height: 100%; transition: width 0.3s ease; }
+.xp-seg.gold { background: #d4af37; }
+.xp-seg.lila { background: #8b5cf6; }
+.xp-seg.gruen { background: var(--success-border); }
+.fokus-title { font-weight: 600; font-size: 0.95rem; margin-left: 0.5rem; }
+.fokus-btn {
+  display: inline-flex; align-items: center; justify-content: center;
+  min-width: 2rem; height: 2rem; padding: 0 0.5rem;
+  font-size: 1rem;
+  border: 1px solid var(--border-strong);
+  border-radius: 6px;
+  background: var(--panel);
+  color: var(--text);
+  cursor: pointer;
+}
+.fokus-btn:hover { border-color: var(--accent); }
+.fokus-btn:disabled { opacity: 0.4; cursor: default; }
+.fokus-btn.armed { border-color: var(--danger, #dc2626); color: var(--danger, #dc2626); background: color-mix(in srgb, var(--danger, #dc2626) 12%, var(--panel)); }
+
+/* Two raised cards on a gray "desk" (--bg-preview from the overlay). */
+.fokus-body {
+  min-height: 0;
+  display: flex;
+  gap: 1.25rem;
+  padding: 1.25rem;
+  max-width: 1600px;
+  width: 100%;
+  margin-inline: auto;
+}
+.fokus-col {
+  min-height: 0;
+  overflow-y: auto;
+  overflow-x: hidden;
+  /* Card tilts by block level: colored border + tinted background (green/purple/gold). */
+  background: color-mix(in srgb, var(--stand) 7%, var(--panel));
+  border: 1px solid var(--stand);
+  border-top: 3px solid var(--stand);
+  border-radius: 12px;
+  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.06);
+}
+/* Left: wide reading card, text centered at reading width. */
+.fokus-col.left { flex: 1; padding: 2rem 2.5rem; }
+.fokus-col.left > * { max-width: 74ch; margin-inline: auto; }
+/* Right: work card; the panel inside is borderless (the card is the frame). */
+.fokus-col.right { flex: none; width: clamp(440px, 34%, 600px); padding: 1.5rem; }
+.fokus-col.right :deep(.bp) { margin-top: 0; }
+.fokus-col.right :deep(.bp-panel) { border: none; background: transparent; padding: 0; }
+.fokus-h2 { font-size: 1.1rem; margin: 0 0 0.75rem; }
+
+/* Desktop: the right card as a flex column — exam/chat history fills the
+   full height and scrolls internally, input + buttons stay at the bottom. */
+@media (min-width: 901px) {
+  .fokus-col.right { display: flex; flex-direction: column; overflow: hidden; }
+  .fokus-col.right :deep(.bp) { flex: 1; display: flex; flex-direction: column; min-height: 0; }
+  .fokus-col.right :deep(.bp-panel) { flex: 1; display: flex; flex-direction: column; min-height: 0; overflow-y: auto; }
+  .fokus-col.right :deep(.bp-panel > div) { flex: 1; display: flex; flex-direction: column; min-height: 0; }
+  .fokus-col.right :deep(.bp-messages) { flex: 1; min-height: 0; max-height: none; }
+}
+
+@media (max-width: 900px) {
+  .fokus-body { flex-direction: column; overflow-y: auto; }
+  .fokus-col { overflow-y: visible; }
+  .fokus-col.right { width: auto; }
+}
+
+/* Check block: right-click menu + suggestion below the section */
+/* Keep the spacing on the wrapper — the inner p is now :last-child (margin 0). */
+.md-block { border-radius: 6px; transition: background 0.15s; margin-bottom: 0.8em; }
+.md-block:last-child { margin-bottom: 0; }
+.md-block > :first-child { margin-top: 0; }
+.md-block > :last-child { margin-bottom: 0; }
+.md-block:hover { background: color-mix(in srgb, var(--accent) 6%, transparent); }
+
+.menu-overlay { position: fixed; inset: 0; z-index: 60; }
+.block-menu {
+  position: fixed;
+  min-width: 8rem;
+  padding: 0.25rem;
+  background: var(--panel);
+  border: 1px solid var(--border-strong);
+  border-radius: 8px;
+  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.18);
+}
+.bm-item {
+  display: block;
+  width: 100%;
+  padding: 0.4rem 0.7rem;
+  text-align: left;
+  font-size: 0.9rem;
+  border: none;
+  border-radius: 5px;
+  background: transparent;
+  color: var(--text);
+  cursor: pointer;
+}
+.bm-item:hover { background: color-mix(in srgb, var(--accent) 14%, transparent); }
+
+.block-vorschlag {
+  margin: 0.5rem 0 1rem;
+  padding: 0.75rem 1rem;
+  border: 1px solid var(--accent);
+  border-left: 3px solid var(--accent);
+  border-radius: 8px;
+  background: color-mix(in srgb, var(--accent) 6%, var(--panel));
+}
+.bv-status { font-size: 0.9rem; color: var(--text-soft, #888); }
+.bv-fehler { color: var(--danger, #dc2626); font-size: 0.88rem; margin: 0 0 0.5rem; }
+.bv-new > :first-child { margin-top: 0; }
+.bv-new > :last-child { margin-bottom: 0; }
+.bv-aktionen { display: flex; gap: 0.4rem; margin-top: 0.6rem; }
+.bv-btn {
+  min-width: 2rem; height: 2rem; padding: 0 0.5rem;
+  font-size: 0.95rem;
+  border: 1px solid var(--border-strong);
+  border-radius: 6px;
+  background: var(--panel);
+  color: var(--text);
+  cursor: pointer;
+}
+.bv-btn:hover { border-color: var(--accent); }
+.bv-btn.aktiv { border-color: var(--accent); background: color-mix(in srgb, var(--accent) 14%, var(--panel)); }
+.bv-btn.ja { border-color: var(--success-border); color: var(--success); }
+.bv-edit { display: flex; gap: 0.4rem; margin-top: 0.5rem; }
+.bv-input {
+  flex: 1;
+  padding: 0.4rem 0.6rem;
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  background: var(--panel);
+  color: var(--text);
+  font-size: 0.9rem;
+}
+</style>

frontend/src/components/BlockPanel.vue

@@ -0,0 +1,966 @@
+<script setup>
+import { computed, nextTick, onMounted, onUnmounted, ref } from 'vue'
+import { chatBlock, examBlock, fetchQuestionPattern } from '../api.js'
+import { usePruefSlot } from '../pruefungCache.js'
+import { renderMarkdown, renderMarkdownInline } from '../markdown.js'
+import { stufeFuer, malusRegel } from '../levels.js'
+import { useChat, istUnten } from '../composables/useChat.js'
+
+const props = defineProps({
+  topic: { type: String, required: true },
+  block: { type: String, required: true },
+  section: { type: String, default: '' },          // detailed version
+  sectionKompakt: { type: String, default: '' },   // compact version (key points) — exam/chat context
+  provider: { type: String, default: 'claude' },
+  status: { type: Object, default: null }, // {good_answers, streak, completed, understood, mastered}
+  cap: { type: Number, default: 6 }, // score cap = max of the highest format (6/12/18/30)
+  // 'trigger' (list): only tab bar, click opens the fullscreen focus.
+  // 'full' (focus): tabs + panel content as before.
+  mode: { type: String, default: 'trigger' },
+  initialTab: { type: String, default: null },
+  ansicht: { type: String, default: 'compact' },   // compact | erklärend — controls the left guide column
+})
+
+const emit = defineEmits(['statusChanged', 'openFokus', 'setAnsicht'])
+
+// Learning levels relative to the cap (levels.js): green/blue/purple/gold @ 20/40/60/100 %.
+// Exam is ALWAYS random from 5 forms (with pattern); cap = 4×relevant subblocks.
+// Four question forms, random. No more easy/hard — the difficulty is set by the backend
+// via the learner level (addressee role). gapchoice = term choice · gaptext = free.
+const MODES = ['quiz', 'gapchoice', 'gaptext', 'erklaeren']
+const st = computed(() => props.status || { good_answers: 0, streak: 0, cap: props.cap })
+const score = computed(() => st.value.good_answers || 0)
+const cap = computed(() => st.value.cap || props.cap)
+const scoreDisplay = computed(() => Math.min(score.value, cap.value))  // legacy data may exceed cap
+const level = computed(() => stufeFuer(score.value, cap.value))   // object {key,label,kurz,farbe} | null
+const atCap = computed(() => score.value >= cap.value)
+// With question pattern random from 5 forms; without pattern (old block) only Explain.
+const currentBand = computed(() => patternMode.value ? 'zufall' : 'erklaeren')
+const inRandom = computed(() => currentBand.value === 'zufall')
+const activeMode = computed(() => currentBand.value)  // 'zufall' | 'erklaeren'
+const activeForm = computed(() => inRandom.value ? 'quiz' : 'erklaeren')  // placeholder; drawn object overrides
+// Displayed form: follows the active form, freezes while a drawn question is visible.
+const displayForm = ref(null)
+const shownForm = computed(() => displayForm.value || activeForm.value)
+const displayBand = ref(null)
+const sectionChange = computed(() => displayBand.value && displayBand.value !== currentBand.value)
+// Difficulty of the currently shown widget (from the drawn object).
+const currentHard = computed(() => {
+  if (shownForm.value === 'quiz' && quizCurrent.value) return quizCurrent.value.schwer
+  if (shownForm.value === 'gaptext' && clozeCurrent.value) return clozeCurrent.value.schwer
+  return false
+})
+const modeRule = computed(() => {
+  const m = malusRegel(score.value, cap.value)  // '0' | '−1' | '−2' | '−3' by progress
+  if (shownForm.value === 'quiz') return currentHard.value ? `x of 4 · +3/${m}` : `1 of 4 · +1/${m}`
+  if (shownForm.value === 'gaptext') return currentHard.value ? `free text · +3/${m}` : `term from 4 · +1/${m}`
+  return `+1/+2/+3 · error ${m}`
+})
+const bandTarget = computed(() => cap.value)
+const FORM_NAME = { quiz: 'Quiz', gaptext: 'Cloze', erklaeren: 'Explain' }
+
+// --- Toggle area ---
+const activeTab = ref(props.mode === 'full' ? props.initialTab : null) // null | 'chat' | 'exam'
+
+// Click on a tab: in the list open the focus, in the focus toggle the tab.
+function tabClick(tab) {
+  if (props.mode === 'trigger') { emit('openFokus', tab); return }
+  activeTab.value = activeTab.value === tab ? null : tab
+}
+
+// --- Block chat (ephemeral) ---
+const chat = useChat((msgs) => chatBlock({
+  topic: props.topic, block: props.block, section: props.section, section_compact: props.sectionKompakt,
+  messages: msgs, provider: props.provider,
+}))
+
+// --- Exam: guided dialog ---
+// Phases: 'idle' (request question) | 'question_offen' (answer/ask) | 'bewertet' (discuss/re-evaluate/continue)
+// Durable state lives in a SHARED slot per block (module store): survives
+// remounting and a late-arriving question is immediately reactive and visible.
+const examKey = `${props.topic}::${props.block}`
+const slot = usePruefSlot(examKey)
+const examMessages = slot.messages // {role, kind: 'question'|'nachfrage'|'answer'|'feedback'|'discussion'|'fehler', content, rating?}
+const examPhase = slot.phase
+const currentQuestion = slot.aktuelleFrage      // anchors evaluation/discussion
+const lastFeedback = slot.letztesFeedback  // context for the discussion about an evaluation
+const patternSource = slot.musterQuelle  // immutable full list of question patterns (empty = fallback)
+const patternPool = slot.musterPool      // working copy, without replacement; empty → reset
+const patternLoaded = slot.musterGeladen
+const poolForm = slot.poolForm          // form the pool is filled for
+const quizCurrent = slot.quizAktuell    // running quiz question (widget state)
+const clozeCurrent = slot.lueckAktuell  // running cloze task (widget state)
+// Transient (per instance): input draft, loading spinner.
+const examInput = ref('')
+const examLoading = ref(false)
+const asked_again = ref(false)   // the running question used asked_again → gain max +1
+const thoroughMsg = ref(null)  // feedback bubble whose thorough field is open
+const thoroughText = ref('')   // optional reason for "check thoroughly"
+
+const examMessagesEl = ref(null)
+const examInputEl = ref(null)
+const examStick = ref(true)     // only auto-scroll when the user is (almost) at the bottom
+let examRun = 0
+
+function onExamScroll() {
+  if (examMessagesEl.value) examStick.value = istUnten(examMessagesEl.value)
+}
+
+function applyExam(res) {
+  // res.streak only set on answer_check (binding, persisted); otherwise leave streak unchanged.
+  emit('statusChanged', { block: props.block, ...st.value, good_answers: res.good_answers, streak: res.streak ?? st.value.streak, cap: res.cap ?? cap.value })
+}
+
+async function examScroll() {
+  await nextTick()
+  if (examMessagesEl.value && examStick.value) examMessagesEl.value.scrollTop = examMessagesEl.value.scrollHeight
+}
+
+// Only real conversation turns go to the backend; feedback stays a pure UI artifact.
+function examDialog() {
+  return examMessages.value
+    .filter((m) => m.kind !== 'feedback' && m.kind !== 'fehler')
+    .map((m) => ({ role: m.role, content: m.content }))
+}
+
+async function examSend(payload, onOk) {
+  const run = ++examRun
+  examStick.value = true // own action = to the end; scrolling up while waiting sets it back to false
+  examLoading.value = true
+  examScroll()
+  try {
+    const res = await examBlock({
+      topic: props.topic, block: props.block, section: props.section, section_compact: props.sectionKompakt,
+      provider: props.provider, messages: examDialog(), ...payload,
+    })
+    if (run !== examRun) return
+    onOk(res)
+    applyExam(res)
+    examScroll()
+    nextTick(() => examInputEl.value?.focus())
+  } catch {
+    if (run === examRun) examMessages.value.push({ role: 'assistant', kind: 'fehler', content: 'Didn\'t work — please try again.' })
+  } finally {
+    if (run === examRun) examLoading.value = false
+  }
+}
+
+// Show question (fresh or queued). Base/streak is tracked by the server per question.
+function showQuestion(text) {
+  currentQuestion.value = text
+  lastFeedback.value = ''
+  asked_again.value = false
+  thoroughMsg.value = null
+  examMessages.value.push({ role: 'assistant', kind: 'question', content: text })
+  examPhase.value = 'question_offen'
+}
+
+// Dedup: detect already-asked questions (the generator repeats itself on small blocks).
+function normQuestion(t) { return (t || '').toLowerCase().replace(/\s+/g, ' ').trim() }
+function askedQuestions() {
+  return new Set(examMessages.value.filter((m) => m.kind === 'question').map((m) => normQuestion(m.content)))
+}
+
+// --- Questions pool: TARGET pre-formulated question OBJECTS of the active form (in the slot) ---
+// Each object: {form, question, options?|sentence?|solution?|alternatives?}. When the
+// active form changes, the pool is cleared and refilled for the new form.
+const POOL_TARGET = 5
+const pool = slot.pool
+const inflight = slot.inflight
+const examError = ref('')  // error hint for quiz/cloze (no bubble history)
+let poolMiss = 0  // fallback only: consecutive duplicates/errors — cap against an infinite loop
+
+// Pattern mode active once loaded and patterns present; otherwise fallback (only Explain).
+const patternMode = computed(() => patternLoaded.value && patternSource.value.length > 0)
+
+function objText(o) { return (o && (o.question || o.sentence)) || '' }
+
+// Render cloze sentence: split at "___", parts inline (with $…$ math), gap as a span.
+// This keeps the gap and markdown does not touch the underscores.
+function clozeSentenceHtml(sentence) {
+  sentence = String(sentence || '')
+  const m = sentence.match(/_{3,}/)  // first gap (three or more underscores)
+  if (!m) return renderMarkdownInline(sentence)
+  // Is the gap INSIDE a $…$ formula (odd number of $ before it)? Then do not split
+  // (that tears the formula) — instead replace it with a KaTeX line, render the sentence whole.
+  const inFormula = ((sentence.slice(0, m.index).match(/\$/g) || []).length % 2) === 1
+  if (inFormula) return renderMarkdownInline(sentence.replace(/_{3,}/, '\\rule{2.5em}{0.4pt}'))
+  // Gap in text: split + gap span.
+  return sentence.split(/_{3,}/).map((t) => renderMarkdownInline(t)).join('<span class="bp-luecke">______</span>')
+}
+
+function isKnown(o) {
+  const n = normQuestion(objText(o))
+  return !n || askedQuestions().has(n) || pool.value.some((f) => normQuestion(objText(f)) === n)
+}
+
+// Already-asked + queued questions — fallback mode only (Explain without pattern).
+function avoidList() {
+  const asked = examMessages.value.filter((m) => m.kind === 'question').map((m) => m.content)
+  return [...asked, ...pool.value.map(objText)]
+}
+
+// Load pattern sidecar once per block (slot-cached). Empty → fallback.
+async function loadPatterns() {
+  if (patternLoaded.value) return
+  try {
+    const res = await fetchQuestionPattern(props.topic, props.block)
+    patternSource.value = (res.pattern || []).map((m) => (m.question || '').trim()).filter(Boolean)
+    patternLoaded.value = true  // ONLY on success — otherwise a failed attempt freezes the session to Explain-only
+  } catch {
+    patternSource.value = []     // patternLoaded stays false → next turn retries
+  }
+}
+
+function mischen(arr) {  // Fisher-Yates
+  const a = [...arr]
+  for (let i = a.length - 1; i > 0; i--) {
+    const j = Math.floor(Math.random() * (i + 1))
+    ;[a[i], a[j]] = [a[j], a[i]]
+  }
+  return a
+}
+
+// Draw a pattern without replacement; pool empty → reset (reshuffle). null = fallback.
+function takePattern() {
+  if (!patternSource.value.length) return null
+  if (!patternPool.value.length) patternPool.value = mischen(patternSource.value)
+  return patternPool.value.shift()
+}
+
+// Pool key = form + difficulty; in the random band a mixed pool ('zufall').
+const poolKey = computed(() => inRandom.value ? 'zufall' : 'erklaeren')
+
+// Mode of the next question: in the random band (score 19–30) random from all 5 modes.
+function nextMode() {
+  return inRandom.value ? MODES[Math.floor(Math.random() * MODES.length)] : activeMode.value
+}
+
+// Generate a question object of a given mode (from a drawn seed; Explain has a fallback).
+function buildSingleQuestion(mode = nextMode()) {
+  const form = mode === 'quiz' ? 'quiz' : mode.startsWith('gap') ? 'gaptext' : 'erklaeren'
+  const istLueckFrei = mode === 'gaptext'  // free text vs. gapchoice = term from 4
+  const pattern = takePattern()
+  const base = {
+    topic: props.topic, block: props.block, section: props.section,
+    section_compact: props.sectionKompakt, provider: props.provider,
+  }
+  if (form === 'quiz' && pattern) {
+    return examBlock({ ...base, action: 'quiz_question', pattern })  // single choice, level controls
+      .then((r) => ({ form, schwer: false, question: r.question, options: r.options }))
+  }
+  if (form === 'gaptext' && pattern) {
+    return examBlock({ ...base, action: 'gap_question', pattern, schwer: istLueckFrei })
+      .then((r) => istLueckFrei
+        ? ({ form, schwer: true, question: r.sentence, sentence: r.sentence, solution: r.solution, alternatives: r.alternatives })
+        : ({ form, schwer: false, question: r.sentence, sentence: r.sentence, options: r.options }))
+  }
+  if (pattern) {  // erklaeren from pattern
+    return examBlock({ ...base, action: 'question', pattern }).then((r) => ({ form: 'erklaeren', question: r.question }))
+  }
+  // Fallback (no pattern sidecar): Explain live with an avoid list.
+  return examBlock({ ...base, action: 'question', messages: examDialog(), avoid: avoidList() })
+    .then((r) => ({ form: 'erklaeren', question: r.question }))
+}
+
+// Clear the pool when form or difficulty changed (band boundary or ALT+E).
+function checkPoolForm() {
+  if (poolForm.value !== poolKey.value) {
+    pool.value = []
+    poolForm.value = poolKey.value
+    poolMiss = 0
+  }
+}
+
+// Fill the pool in PARALLEL: each draws a DISTINCT pattern → no collision.
+function fillPool() {
+  checkPoolForm()
+  const keyStart = poolKey.value
+  const missCap = patternMode.value ? Infinity : 3
+  while (pool.value.length + inflight.value < POOL_TARGET && poolMiss < missCap) {
+    inflight.value++
+    buildSingleQuestion()
+      .then((obj) => {
+        if (obj && objText(obj) && poolKey.value === keyStart && (patternMode.value || !isKnown(obj))) { pool.value.push(obj); poolMiss = 0 }
+        else poolMiss++
+      })
+      .catch(() => { poolMiss++ })
+      .finally(() => { inflight.value--; fillPool() })
+  }
+}
+
+// Draw a question from the pool — random, never the fastest.
+// First load (pool empty + nothing in progress): generate 5, await ALL, then draw.
+async function drawQuestion() {
+  const firstLoad = !pool.value.length && !inflight.value
+  fillPool()  // start/keep up to 5
+  examLoading.value = true
+  try {
+    const missCap = patternMode.value ? Infinity : 3
+    if (firstLoad) {
+      // only at the start: wait until all 5 are done (speed must not decide the form)
+      while ((inflight.value > 0 || pool.value.length < POOL_TARGET) && poolMiss < missCap) {
+        if (!inflight.value) fillPool()
+        await new Promise((r) => setTimeout(r, 80))
+      }
+    } else if (!pool.value.length) {
+      // pool drained (fast user): wait for the first finished one
+      while (!pool.value.length && (inflight.value > 0 || poolMiss < missCap)) {
+        if (!inflight.value) fillPool()
+        await new Promise((r) => setTimeout(r, 80))
+      }
+    }
+    if (!pool.value.length) return null
+    const i = Math.floor(Math.random() * pool.value.length)
+    return pool.value.splice(i, 1)[0]
+  } finally { examLoading.value = false }
+}
+
+// Show a drawn object in the matching form (Explain bubble or quiz/cloze widget).
+function showQuestionObj(obj) {
+  examError.value = ''
+  displayForm.value = obj.form  // bind display to the drawn question (freeze the form)
+  displayBand.value = currentBand.value  // band at draw time (before the answer)
+  if (obj.form === 'quiz') {
+    quizCurrent.value = { question: obj.question, options: obj.options, schwer: obj.schwer, gewaehlt: [], done: false, points: null, rating: null, feedback: '' }
+  } else if (obj.form === 'gaptext') {
+    clozeCurrent.value = { sentence: obj.sentence, schwer: obj.schwer, options: obj.options || null, solution: obj.solution || '', alternatives: obj.alternatives || [], input: '', gewaehlt: [], done: false, points: null, rating: null, feedback: '' }
+    if (obj.schwer) nextTick(() => document.getElementById('bp-gap-input')?.focus())
+  } else {
+    showQuestion(obj.question)
+    nextTick(() => examInputEl.value?.focus())
+  }
+}
+
+// First / next question: load patterns, roll the form, fetch exactly that form.
+async function showNextQuestion() {
+  if (examLoading.value) return
+  poolMiss = 0
+  examError.value = ''
+  await loadPatterns()
+  const obj = await drawQuestion()  // first load: await all 5; then draw randomly
+  if (obj) {
+    showQuestionObj(obj)
+    examScroll()
+  } else if (activeForm.value === 'erklaeren') {
+    examMessages.value.push({ role: 'assistant', kind: 'fehler', content: 'No question — please try again.' })
+  } else {
+    examError.value = 'No question — please try again.'
+  }
+  fillPool()
+}
+const requestQuestion = showNextQuestion
+
+// Milestone exceeded: release the freeze (result was visible) without drawing a new
+// question → idle state of the new band ("request question").
+function toNextSection() {
+  displayForm.value = null
+  displayBand.value = null
+  quizCurrent.value = null
+  clozeCurrent.value = null
+  examMessages.value = []  // discard the old Explain history (new section)
+  examPhase.value = 'idle'
+  examError.value = ''
+}
+
+// --- Quiz: easy = single select (exactly 1) · hard = multi select. Deterministic. ---
+function quizToggle(i) {
+  const q = quizCurrent.value
+  if (!q || q.done) return
+  if (!q.schwer) { q.gewaehlt = q.gewaehlt.includes(i) ? [] : [i]; return }
+  const idx = q.gewaehlt.indexOf(i)
+  if (idx >= 0) q.gewaehlt.splice(idx, 1)
+  else q.gewaehlt.push(i)
+}
+
+async function quizAnswer() {
+  const q = quizCurrent.value
+  if (!q || q.done || examLoading.value) return
+  examLoading.value = true
+  examError.value = ''
+  try {
+    const correct = q.options.map((o, i) => (o.correct ? i : -1)).filter((i) => i >= 0)
+    const res = await examBlock({
+      topic: props.topic, block: props.block, section: props.section, section_compact: props.sectionKompakt,
+      provider: props.provider, action: 'quiz_answer', question: q.question, cap: props.cap,
+      selection: q.gewaehlt, correct, schwer: q.schwer,
+    })
+    q.done = true; q.points = res.points; q.rating = res.rating; q.feedback = res.feedback
+    applyExam(res)
+  } catch {
+    examError.value = 'Didn\'t work — please try again.'
+  } finally {
+    examLoading.value = false
+  }
+}
+
+// --- Cloze: easy = term from 4 (single select) · hard = free text ---
+function clozeToggle(i) {
+  const l = clozeCurrent.value
+  if (!l || l.done || l.schwer) return
+  l.gewaehlt = l.gewaehlt.includes(i) ? [] : [i]
+}
+
+async function clozeAnswer() {
+  const l = clozeCurrent.value
+  if (!l || l.done || examLoading.value) return
+  if (l.schwer ? !l.input.trim() : !l.gewaehlt.length) return
+  examLoading.value = true
+  examError.value = ''
+  try {
+    const specific = l.schwer
+      ? { schwer: true, solution: l.solution, alternatives: l.alternatives, input: l.input }
+      : { schwer: false, selection: l.gewaehlt, correct: l.options.map((o, i) => (o.correct ? i : -1)).filter((i) => i >= 0) }
+    const res = await examBlock({
+      topic: props.topic, block: props.block, section: props.section, section_compact: props.sectionKompakt,
+      provider: props.provider, action: 'gap_answer', question: l.sentence, cap: props.cap, ...specific,
+    })
+    l.done = true; l.points = res.points; l.rating = res.rating; l.feedback = res.feedback
+    applyExam(res)
+  } catch {
+    examError.value = 'Didn\'t work — please try again.'
+  } finally {
+    examLoading.value = false
+  }
+}
+
+function askFollowUp() {
+  const text = examInput.value.trim()
+  if (!text || examLoading.value) return
+  asked_again.value = true  // help used → gain for this question max +1
+  examMessages.value.push({ role: 'user', kind: 'nachfrage', content: text })
+  examInput.value = ''
+  examSend(
+    { action: 'discussion', question: currentQuestion.value, last_rating: lastFeedback.value },
+    (res) => examMessages.value.push({ role: 'assistant', kind: 'discussion', content: res.reply }),
+  )
+}
+
+let lastFeedbackMsg = null // last shown evaluation bubble
+let evalRun = 0           // only the most recent quick evaluation may display
+
+function ratingPayload() {
+  return { question: currentQuestion.value, cap: props.cap, asked_again: asked_again.value }
+}
+
+// Agent 1 (fast): show immediate level + points, then Agent 2 (precise) in the background.
+async function quickEvaluate() {
+  const mine = ++evalRun
+  examStick.value = true
+  examLoading.value = true
+  examScroll()
+  try {
+    const res = await examBlock({
+      topic: props.topic, block: props.block, section: props.section, section_compact: props.sectionKompakt,
+      provider: props.provider, messages: examDialog(), action: 'answer', ...ratingPayload(),
+    })
+    if (mine !== evalRun) return
+    // Agent 1 does NOT change the score — only show feedback + expected points.
+    lastFeedback.value = res.feedback || ''
+    examMessages.value.push({ role: 'assistant', kind: 'feedback', content: res.feedback || '', rating: res.rating, points: res.points, checked: false })
+    lastFeedbackMsg = examMessages.value[examMessages.value.length - 1]
+    examPhase.value = 'bewertet'
+    examScroll()
+    nextTick(() => examInputEl.value?.focus())
+    preciseEvaluate() // Agent 2 evaluates bindingly (sets the score)
+  } catch {
+    if (mine === evalRun) examMessages.value.push({ role: 'assistant', kind: 'fehler', content: 'Didn\'t work — please try again.' })
+  } finally {
+    if (mine === evalRun) examLoading.value = false
+  }
+}
+
+// Agent 2 (precise): evaluator + critic. Corrects bubble + score (server truth, always apply).
+// thorough=true: strong model, optionally with the learner's reason.
+async function preciseEvaluate(thorough = false, reason = '') {
+  const target = lastFeedbackMsg
+  if (thorough) examLoading.value = true
+  try {
+    const res = await examBlock({
+      topic: props.topic, block: props.block, section: props.section, section_compact: props.sectionKompakt,
+      provider: props.provider, messages: examDialog(), action: 'answer_check', ...ratingPayload(), thorough, reason,
+    })
+    applyExam(res)
+    if (target) {
+      target.content = res.feedback || target.content
+      target.rating = res.rating
+      target.points = res.points
+      target.checked = true
+    }
+  } catch {
+    if (target) target.checked = true
+  } finally {
+    if (thorough) examLoading.value = false
+  }
+}
+
+function submitAnswer() {
+  const text = examInput.value.trim()
+  if (!text || examLoading.value) return
+  examMessages.value.push({ role: 'user', kind: 'answer', content: text })
+  examInput.value = ''
+  quickEvaluate()
+}
+
+// Was there already a discussion? Then the history may be evaluated directly.
+const hasDiscussion = computed(() => examMessages.value.some((m) => m.kind === 'nachfrage' || m.kind === 'discussion'))
+
+// "Evaluate history": evaluate the dialog so far as the answer (field is ignored).
+function evaluateHistory() {
+  if (examLoading.value) return
+  quickEvaluate()
+}
+
+// Right-click an evaluation → open the thorough field; submitting re-evaluates (with reason).
+function openThorough(msg) {
+  thoroughText.value = ''
+  thoroughMsg.value = msg
+  nextTick(() => document.getElementById('bp-thorough-input')?.focus())
+}
+function submitThorough() {
+  if (examLoading.value) return
+  lastFeedbackMsg = thoroughMsg.value || lastFeedbackMsg
+  const text = thoroughText.value.trim()
+  thoroughMsg.value = null
+  preciseEvaluate(true, text)
+}
+
+function pointsLabel(p) {
+  if (p == null) return ''
+  return p > 0 ? `+${p}` : p < 0 ? String(p) : '±0'
+}
+
+// Cancel like in chat: increment the run counter → the running result (examSend
+// and quickEvaluate) is discarded, buttons free immediately. Agent finishes server-side.
+function examCancel() {
+  if (!examLoading.value) return
+  examRun++
+  evalRun++
+  examLoading.value = false
+  examMessages.value.push({ role: 'assistant', kind: 'fehler', content: 'Cancelled.' })
+}
+
+// ESC cancels — window listener, because after a button click the focus leaves the panel.
+function onWindowKey(e) {
+  if (e.key === 'Escape' && examLoading.value) { e.preventDefault(); examCancel() }
+}
+onMounted(() => {
+  if (props.mode !== 'full') return  // trigger mode (list): only tab bar, no exam/text logic
+  window.addEventListener('keydown', onWindowKey)
+  window.addEventListener('keydown', onExamKey)
+  loadPatterns()  // GET (no agent) — sets the active form early correctly (quiz/cloze/explain)
+})
+onUnmounted(() => {
+  window.removeEventListener('keydown', onWindowKey)
+  window.removeEventListener('keydown', onExamKey)
+})
+
+// Quiz / cloze choice is a choice widget with keys 1–4; otherwise text field/bubble.
+const choiceWidget = computed(() => {
+  if (shownForm.value === 'quiz') return quizCurrent.value
+  if (shownForm.value === 'gaptext' && clozeCurrent.value && !clozeCurrent.value.schwer) return clozeCurrent.value
+  return null
+})
+// After an answer: on milestone crossing go to the new section, otherwise next question.
+function continueAction() {
+  if (sectionChange.value) toNextSection()
+  else showNextQuestion()
+}
+// Primary action per form: no question → request · open → answer · done → continue.
+function primaryAction() {
+  if (examLoading.value) return
+  const f = shownForm.value
+  if (f === 'quiz') { if (!quizCurrent.value) requestQuestion(); else if (!quizCurrent.value.done) quizAnswer(); else continueAction(); return }
+  if (f === 'gaptext') { if (!clozeCurrent.value) requestQuestion(); else if (!clozeCurrent.value.done) clozeAnswer(); else continueAction(); return }
+  if (examPhase.value === 'idle') requestQuestion()
+  else if (examPhase.value === 'question_offen') { if (examInput.value.trim()) submitAnswer() }
+  else continueAction()
+}
+
+// 1–4 (bare): toggle option in the choice widget. Alt alone: jump to the input field.
+// Alt+2 primary (answer/next) · Alt+Q view · Alt+1/3 Explain.
+function onExamKey(e) {
+  if (e.repeat) return
+  if (props.mode !== 'full' || activeTab.value !== 'exam') return
+  // Alt alone toggles the focus (BlockFocus lone-tap) → do NOT focus here,
+  // otherwise keydown focus (here) and keyup toggle (focus) fight → "only while held".
+  if (e.key === 'Alt') return
+  if (!e.altKey) {
+    // Bare 1–4: toggle the choice widget — but not while a text field has focus.
+    if (['1', '2', '3', '4'].includes(e.key) && choiceWidget.value && !choiceWidget.value.done) {
+      const ae = document.activeElement
+      if (ae && (ae.tagName === 'INPUT' || ae.tagName === 'TEXTAREA')) return
+      e.preventDefault()
+      const i = Number(e.key) - 1
+      if (i < choiceWidget.value.options.length) (shownForm.value === 'quiz' ? quizToggle : clozeToggle)(i)
+    }
+    return
+  }
+  if (e.code === 'KeyQ') {
+    e.preventDefault()
+    emit('setAnsicht', props.ansicht === 'compact' ? 'erklärend' : 'compact')
+    return
+  }
+  if (e.key === '2') { e.preventDefault(); primaryAction(); return }
+  // Explain special keys
+  if (e.key === '1') { e.preventDefault(); if (shownForm.value === 'erklaeren' && examPhase.value === 'question_offen' && examInput.value.trim()) askFollowUp(); return }
+  if (e.key === '3') { e.preventDefault(); if (shownForm.value === 'erklaeren' && examPhase.value === 'question_offen' && hasDiscussion.value) evaluateHistory() }
+}
+</script>
+
+<template>
+  <div class="bp">
+    <div class="bp-toggles">
+      <!-- View switcher (fullscreen only): controls the left guide column, left of the tabs -->
+      <div v-if="mode === 'full'" class="bp-ansicht">
+        <button :class="{ active: ansicht === 'compact' }" title="Key points" @click="emit('setAnsicht', 'compact')">Compact</button>
+        <button :class="{ active: ansicht === 'erklärend' }" title="Detailed explanation" @click="emit('setAnsicht', 'erklärend')">Explanatory</button>
+      </div>
+      <button :class="{ active: activeTab === 'chat' }" @click="tabClick('chat')">
+        Chat
+      </button>
+      <button :class="{ active: activeTab === 'exam' }" @click="tabClick('exam')">
+        Exam
+        <span v-if="level" class="bp-chip" :style="{ borderColor: level.farbe, color: level.farbe }" :title="`${level.label} (${cap})`">{{ level.kurz }} {{ scoreDisplay }}/{{ cap }}</span>
+        <span v-else-if="score" class="bp-chip">{{ scoreDisplay }}/{{ cap }}</span>
+      </button>
+    </div>
+
+    <div v-if="mode === 'full' && activeTab" class="bp-panel">
+      <!-- Block chat -->
+      <div v-if="activeTab === 'chat'">
+        <div :ref="chat.messagesEl" class="bp-messages" @scroll="chat.onScroll">
+          <p v-if="!chat.messages.value.length" class="bp-hint">Ask something about this block. The history is not saved.</p>
+          <template v-for="(m, i) in chat.messages.value" :key="i">
+            <div v-if="m.role === 'assistant'" class="bp-msg assistant markdown" v-html="renderMarkdown(m.content)"></div>
+            <div v-else class="bp-msg user">{{ m.content }}</div>
+          </template>
+          <div v-if="chat.loading.value" class="bp-msg assistant bp-typing">Thinking…</div>
+        </div>
+        <div class="bp-input">
+          <textarea
+            :ref="chat.inputEl"
+            v-model="chat.input.value"
+            rows="2"
+            placeholder="Question about the block…"
+            @keydown.enter.exact.prevent="chat.send"
+          ></textarea>
+          <button :disabled="!chat.input.value.trim() && !chat.loading.value" :class="{ cancel: chat.loading.value }" @click="chat.send">
+            {{ chat.loading.value ? '✕' : '➤' }}
+          </button>
+        </div>
+      </div>
+
+      <!-- Exam: guided dialog -->
+      <div v-else>
+        <p class="bp-hint">
+          <template v-if="atCap">{{ FORM_NAME[shownForm] }} · {{ scoreDisplay }}/{{ cap }} — <strong>Max</strong>.</template>
+          <template v-else-if="inRandom && !displayForm">Random · {{ scoreDisplay }}/{{ cap }}</template>
+          <template v-else-if="inRandom">{{ FORM_NAME[shownForm] }} · {{ scoreDisplay }}/{{ cap }} · {{ modeRule }}</template>
+          <template v-else>{{ FORM_NAME[shownForm] }} · {{ score }}/{{ bandTarget }} · {{ modeRule }}</template>
+        </p>
+
+        <!-- Quiz: question + multiple choice (widget stays even at the cap — practice without points) -->
+        <template v-if="shownForm === 'quiz'">
+          <div v-if="!quizCurrent" class="bp-actions">
+            <button v-if="examLoading" class="bp-action cancel" title="ESC" @click="examCancel">Cancel</button>
+            <button v-else class="bp-action primary" @click="requestQuestion">Request question</button>
+          </div>
+          <div v-else class="bp-quiz">
+            <p class="bp-quiz-question markdown" v-html="renderMarkdownInline(quizCurrent.question)"></p>
+            <div class="bp-quiz-grid">
+              <button
+                v-for="(o, i) in quizCurrent.options" :key="i"
+                type="button"
+                class="bp-quiz-opt"
+                :class="{ gewaehlt: quizCurrent.gewaehlt.includes(i), correct: quizCurrent.done && o.correct, falsch: quizCurrent.done && !o.correct && quizCurrent.gewaehlt.includes(i) }"
+                :disabled="quizCurrent.done"
+                :title="`${i + 1}`"
+                @click="quizToggle(i)"
+              >
+                <span class="markdown" v-html="renderMarkdownInline(o.text)"></span>
+              </button>
+            </div>
+            <p v-if="examError" class="bp-error">{{ examError }}</p>
+            <div class="bp-actions">
+              <button v-if="!quizCurrent.done" class="bp-action primary" title="Alt+2" :disabled="examLoading" @click="quizAnswer">Answer</button>
+              <template v-else>
+                <span class="bp-tier" :class="quizCurrent.rating">{{ pointsLabel(quizCurrent.points) }}</span>
+                <span class="bp-form-feedback">{{ quizCurrent.feedback }}</span>
+                <button class="bp-action primary" @click="continueAction">{{ sectionChange ? 'To next section' : 'Next' }}</button>
+              </template>
+            </div>
+          </div>
+        </template>
+
+        <!-- Cloze: sentence with gap + input -->
+        <template v-else-if="shownForm === 'gaptext'">
+          <div v-if="!clozeCurrent" class="bp-actions">
+            <button v-if="examLoading" class="bp-action cancel" title="ESC" @click="examCancel">Cancel</button>
+            <button v-else class="bp-action primary" @click="requestQuestion">Request question</button>
+          </div>
+          <div v-else class="bp-gap">
+            <p class="bp-gap-sentence markdown" v-html="clozeSentenceHtml(clozeCurrent.sentence)"></p>
+            <!-- hard: free text -->
+            <input
+              v-if="clozeCurrent.schwer"
+              id="bp-gap-input"
+              v-model="clozeCurrent.input"
+              :disabled="clozeCurrent.done"
+              placeholder="Term for the gap…"
+              @keyup.enter="clozeAnswer"
+            />
+            <p v-if="clozeCurrent.schwer && clozeCurrent.done && !clozeCurrent.feedback.startsWith('Correct')" class="bp-gap-solution">Solution: <span class="markdown" v-html="renderMarkdownInline(clozeCurrent.solution)"></span></p>
+            <!-- easy: choose term from 4 -->
+            <div v-if="!clozeCurrent.schwer" class="bp-quiz-grid">
+              <button
+                v-for="(o, i) in clozeCurrent.options" :key="i"
+                type="button"
+                class="bp-quiz-opt"
+                :class="{ gewaehlt: clozeCurrent.gewaehlt.includes(i), correct: clozeCurrent.done && o.correct, falsch: clozeCurrent.done && !o.correct && clozeCurrent.gewaehlt.includes(i) }"
+                :disabled="clozeCurrent.done"
+                :title="`${i + 1}`"
+                @click="clozeToggle(i)"
+              >
+                <span class="markdown" v-html="renderMarkdownInline(o.text)"></span>
+              </button>
+            </div>
+            <p v-if="examError" class="bp-error">{{ examError }}</p>
+            <div class="bp-actions">
+              <button v-if="!clozeCurrent.done" class="bp-action primary" title="Alt+2" :disabled="examLoading || (clozeCurrent.schwer ? !clozeCurrent.input.trim() : !clozeCurrent.gewaehlt.length)" @click="clozeAnswer">Answer</button>
+              <template v-else>
+                <span class="bp-tier" :class="clozeCurrent.rating">{{ pointsLabel(clozeCurrent.points) }}</span>
+                <span class="bp-form-feedback">{{ clozeCurrent.feedback }}</span>
+                <button class="bp-action primary" @click="continueAction">{{ sectionChange ? 'To next section' : 'Next' }}</button>
+              </template>
+            </div>
+          </div>
+        </template>
+
+        <!-- Explain: guided dialog (existing) -->
+        <template v-else>
+          <div v-if="examMessages.length" ref="examMessagesEl" class="bp-messages" @scroll="onExamScroll">
+            <template v-for="(m, i) in examMessages" :key="i">
+              <div v-if="m.kind === 'feedback'" class="bp-feedback" :class="m.rating" title="Click: check thoroughly" @click="openThorough(m)">
+                <span v-if="m.points != null" class="bp-tier">{{ pointsLabel(m.points) }}</span>{{ m.content }}<span v-if="!m.checked" class="bp-pruefend"> · being checked…</span>
+                <div v-if="thoroughMsg === m" class="bp-thorough" @click.stop>
+                  <input id="bp-thorough-input" v-model="thoroughText" placeholder="Why unsatisfied? (optional)" @keyup.enter="submitThorough" />
+                  <button class="bp-action primary" @click="submitThorough">Check thoroughly</button>
+                  <button class="bp-action" @click="thoroughMsg = null">×</button>
+                </div>
+              </div>
+              <div v-else-if="m.kind === 'fehler'" class="bp-error">{{ m.content }}</div>
+              <div v-else-if="m.role === 'assistant'" class="bp-msg assistant markdown" v-html="renderMarkdown(m.content)"></div>
+              <div v-else class="bp-msg user">{{ m.content }}</div>
+            </template>
+            <div v-if="examLoading" class="bp-msg assistant bp-typing">…</div>
+          </div>
+
+          <div v-if="examPhase === 'idle'" class="bp-actions">
+            <button v-if="examLoading" class="bp-action cancel" title="ESC" @click="examCancel">Cancel</button>
+            <button v-else class="bp-action primary" @click="requestQuestion">Request question</button>
+          </div>
+
+          <template v-else>
+            <div v-if="examPhase === 'question_offen'" class="bp-input">
+              <textarea
+                ref="examInputEl"
+                v-model="examInput"
+                rows="2"
+                placeholder="Answer — or ask if unclear…"
+              ></textarea>
+            </div>
+            <div class="bp-actions">
+              <button v-if="examLoading" class="bp-action cancel" title="ESC" @click="examCancel">Cancel</button>
+              <template v-else-if="examPhase === 'question_offen'">
+                <button class="bp-action" title="Alt+1" :disabled="!examInput.trim()" @click="askFollowUp"><span class="bp-kbd">1</span>Ask</button>
+                <button class="bp-action primary" title="Alt+2" :disabled="!examInput.trim()" @click="submitAnswer"><span class="bp-kbd">2</span>Submit answer</button>
+                <button v-if="hasDiscussion" class="bp-action" title="Alt+3" @click="evaluateHistory"><span class="bp-kbd">3</span>Evaluate history</button>
+              </template>
+              <template v-else>
+                <button class="bp-action primary" title="Alt+2" @click="continueAction"><span class="bp-kbd">2</span>{{ sectionChange ? 'To next section' : 'Next question' }}</button>
+              </template>
+            </div>
+          </template>
+        </template>
+      </div>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.bp { margin-top: 0.75rem; }
+
+.bp-toggles { display: flex; gap: 0.4rem; }
+.bp-toggles button {
+  display: inline-flex; align-items: center; gap: 0.35rem;
+  padding: 0.25rem 0.7rem;
+  font-size: 0.8rem;
+  border: 1px solid var(--border);
+  border-radius: 999px;
+  background: var(--panel-soft);
+  color: var(--text-muted);
+  cursor: pointer;
+}
+.bp-toggles button:hover { border-color: var(--border-strong); color: var(--text); }
+.bp-toggles button.active { background: var(--accent); border-color: var(--accent); color: var(--on-accent); }
+
+/* View switcher (Compact/Explanatory) — segmented, left of the tabs */
+.bp-ansicht { display: inline-flex; margin-right: 0.5rem; }
+.bp-ansicht button {
+  padding: 0.25rem 0.6rem;
+  font-size: 0.75rem;
+  border: 1px solid var(--border);
+  background: var(--panel-soft);
+  color: var(--text-muted);
+  cursor: pointer;
+}
+.bp-ansicht button:first-child { border-radius: 999px 0 0 999px; }
+.bp-ansicht button:last-child { border-radius: 0 999px 999px 0; }
+.bp-ansicht button + button { border-left: none; }
+.bp-ansicht button:hover { color: var(--text); }
+.bp-ansicht button.active { background: var(--accent); border-color: var(--accent); color: var(--on-accent); }
+
+
+.bp-chip {
+  font-size: 0.7rem;
+  padding: 0 0.35rem;
+  border-radius: 999px;
+  background: var(--panel);
+  border: 1px solid var(--border);
+  color: var(--text-muted);
+}
+.bp-chip.done { background: var(--success-soft); border-color: var(--success-border); color: var(--success); }
+.bp-chip.lila { background: color-mix(in srgb, #8b5cf6 16%, var(--panel)); border-color: #8b5cf6; color: #6d28d9; }
+.bp-chip.gold { background: color-mix(in srgb, #d4af37 20%, var(--panel)); border-color: #d4af37; color: #8a6d12; }
+
+.bp-panel {
+  margin-top: 0.6rem;
+  padding: 0.75rem 0.9rem;
+  border: 1px solid var(--border);
+  border-radius: 8px;
+  background: var(--panel-soft);
+}
+
+.bp-hint { font-size: 0.85rem; color: var(--text-muted); margin: 0 0 0.5rem; }
+.bp-hint-key { font-size: 0.72rem; opacity: 0.7; white-space: nowrap; }
+.bp-error { font-size: 0.85rem; color: var(--danger); margin: 0.5rem 0 0; }
+
+.bp-action {
+  margin-top: 0.5rem;
+  padding: 0.3rem 0.8rem;
+  font-size: 0.8rem;
+  border: 1px solid var(--border-strong);
+  border-radius: 6px;
+  background: var(--panel);
+  color: var(--text);
+  cursor: pointer;
+}
+.bp-action:hover { border-color: var(--accent); }
+.bp-action:disabled { opacity: 0.5; cursor: default; }
+.bp-action.primary { background: var(--accent); border-color: var(--accent); color: var(--on-accent); }
+.bp-action.primary:hover { background: var(--accent-hover); border-color: var(--accent-hover); }
+.bp-action.cancel { background: var(--danger); border-color: var(--danger); color: var(--on-accent); }
+
+.bp-actions { display: flex; flex-wrap: wrap; gap: 0.4rem; margin-top: 0.5rem; }
+.bp-actions .bp-action { margin-top: 0; }
+
+.bp-kbd {
+  display: inline-flex; align-items: center; justify-content: center;
+  min-width: 1rem; height: 1rem; padding: 0 0.2rem; margin-right: 0.35rem;
+  font-size: 0.65rem; font-weight: 600; border-radius: 3px;
+  background: var(--panel); border: 1px solid var(--border); color: var(--text-muted);
+}
+.bp-action.primary .bp-kbd { background: color-mix(in srgb, var(--on-accent) 20%, transparent); border-color: transparent; color: var(--on-accent); }
+
+.bp-messages { display: flex; flex-direction: column; gap: 0.4rem; max-height: 320px; overflow-y: auto; }
+.bp-msg {
+  max-width: 88%;
+  padding: 0.4rem 0.65rem;
+  border-radius: 10px;
+  font-size: 0.88rem;
+  line-height: 1.45;
+  overflow-wrap: anywhere;
+}
+.bp-msg.user { align-self: flex-end; background: var(--accent); color: var(--on-accent); white-space: pre-wrap; }
+.bp-msg.assistant { align-self: flex-start; background: var(--panel); border: 1px solid var(--border); }
+.bp-typing { color: var(--text-faint); font-style: italic; }
+
+/* Evaluation of the last answer — separated above the next question */
+.bp-feedback {
+  align-self: flex-start;
+  max-width: 88%;
+  padding: 0.3rem 0.6rem;
+  border-radius: 8px;
+  font-size: 0.82rem;
+  line-height: 1.4;
+  border: 1px solid var(--border);
+}
+.bp-pruefend { font-style: italic; opacity: 0.7; font-size: 0.92em; }
+.bp-feedback { cursor: pointer; }
+.bp-feedback.gut { background: var(--success-soft); border-color: var(--success-border); color: var(--success); }
+.bp-feedback.neutral { background: var(--warning-soft); border-color: var(--warning-border); color: var(--warning); }
+.bp-feedback.schlecht { background: var(--danger-soft, #fee2e2); border-color: var(--danger-border, #f87171); color: var(--danger); }
+.bp-tier { font-weight: 700; text-transform: uppercase; font-size: 0.62rem; letter-spacing: 0.03em; margin-right: 0.4rem; opacity: 0.85; }
+.bp-tier.gut { color: var(--success); }
+.bp-tier.neutral { color: var(--warning); }
+.bp-tier.schlecht { color: var(--danger); }
+
+/* Quiz: question + multiple choice */
+.bp-quiz, .bp-gap { margin-top: 0.6rem; }
+.bp-quiz-question, .bp-gap-sentence { font-size: 0.9rem; font-weight: 600; margin: 0 0 0.5rem; line-height: 1.5; }
+.bp-luecke { font-weight: 700; letter-spacing: 1px; color: var(--accent); padding: 0 0.15rem; }
+.bp-quiz-opt .markdown, .bp-quiz-question.markdown, .bp-gap-sentence.markdown { display: inline; }
+.bp-quiz-opt .markdown { min-width: 0; overflow-wrap: anywhere; }
+.bp-quiz-grid { display: grid; grid-template-columns: 1fr 1fr; gap: 0.5rem; margin-bottom: 0.5rem; }
+.bp-quiz-opt {
+  display: flex; gap: 0.45rem; align-items: flex-start; text-align: left;
+  min-width: 0; overflow-wrap: anywhere;
+  padding: 0.5rem 0.6rem;
+  border: 1px solid var(--border); border-radius: 8px;
+  background: var(--panel); color: var(--text); cursor: pointer; font-size: 0.85rem;
+}
+.bp-quiz-opt:disabled { cursor: default; }
+.bp-quiz-opt.gewaehlt { border-color: var(--accent); background: var(--accent-soft, rgba(99, 102, 241, 0.12)); }
+.bp-quiz-opt.correct { background: var(--success-soft); border-color: var(--success-border); }
+.bp-quiz-opt.falsch { background: var(--danger-soft, #fee2e2); border-color: var(--danger-border, #f87171); }
+.bp-form-feedback { font-size: 0.82rem; color: var(--text-muted); flex: 1; }
+
+/* Cloze: sentence + input */
+.bp-gap input {
+  width: 100%; box-sizing: border-box; padding: 0.45rem 0.6rem; font: inherit; font-size: 0.88rem;
+  border: 1px solid var(--border); border-radius: 8px; background: var(--panel); color: var(--text);
+}
+.bp-gap input:disabled { opacity: 0.7; }
+.bp-gap-solution { font-size: 0.82rem; color: var(--success); margin: 0.35rem 0 0; }
+/* Thorough-check field (via right-click) inside the evaluation bubble */
+.bp-thorough { display: flex; gap: 0.3rem; margin-top: 0.4rem; align-items: center; }
+.bp-thorough input {
+  flex: 1; min-width: 0; padding: 0.3rem 0.5rem; font: inherit; font-size: 0.8rem;
+  border: 1px solid var(--border-strong); border-radius: 6px; background: var(--panel); color: var(--text);
+}
+.bp-thorough .bp-action { margin-top: 0; }
+
+.bp-input { display: flex; gap: 0.4rem; margin-top: 0.55rem; align-items: flex-end; }
+.bp-input textarea {
+  flex: 1;
+  resize: none;
+  padding: 0.45rem 0.6rem;
+  font: inherit;
+  font-size: 0.88rem;
+  border: 1px solid var(--border);
+  border-radius: 8px;
+  background: var(--panel);
+  color: var(--text);
+}
+.bp-input button {
+  padding: 0.45rem 0.7rem;
+  border: none;
+  border-radius: 8px;
+  background: var(--accent);
+  color: var(--on-accent);
+  cursor: pointer;
+}
+.bp-input button:disabled { opacity: 0.5; cursor: default; }
+.bp-input button.cancel { background: var(--danger); }
+</style>

frontend/src/components/BlocksOverview.vue

@@ -0,0 +1,342 @@
+<script setup>
+import { ref, computed, watch, onUnmounted } from 'vue'
+import { fetchBlocksOverview, fetchBlocksCompleteness } from '../api.js'
+
+const props = defineProps({
+  topic: { type: String, required: true },
+  generating: { type: Boolean, default: false },
+  progress: { type: String, default: null },
+  ready: { type: Boolean, default: false },
+  partial: { type: Boolean, default: false },
+})
+const emit = defineEmits(['close', 'openGeneration'])
+
+const items = ref([])
+const loading = ref(true)
+const error = ref(null)
+const comp = ref(null)      // Vollständigkeits-Beleg (nur wenn ready)
+const compOpen = ref(false)
+
+async function loadCompleteness() {
+  if (!props.ready) { comp.value = null; return }
+  try {
+    comp.value = await fetchBlocksCompleteness(props.topic)
+  } catch { comp.value = null }
+}
+watch(() => [props.topic, props.ready, props.generating], loadCompleteness, { immediate: true })
+
+// Während einer Generierung wächst das Grid live nach (leichter Overview-Poll,
+// das Kanban-Board selbst lebt in der Generierungs-View).
+let timer = null
+function startPoll() { stopPoll(); timer = setInterval(load, 5000) }
+function stopPoll() { if (timer) { clearInterval(timer); timer = null } }
+watch(() => props.topic, () => { items.value = []; load() }, { immediate: true })
+watch(() => props.generating, (g) => { if (g) startPoll(); else { stopPoll(); load() } }, { immediate: true })
+onUnmounted(stopPoll)
+
+// ── Fertige Blöcke (Grid) ──────────────────────────────────────────────────────
+const LEVELS = [
+  { key: 'beginner', label: 'Beginner' },
+  { key: 'advanced', label: 'Advanced' },
+  { key: 'expert', label: 'Expert' },
+]
+const LEGACY_LEVEL = { einfach: 'beginner', mittel: 'advanced', schwer: 'expert' }
+
+async function load() {
+  if (!items.value.length) loading.value = true  // Spinner nur beim Erstladen, Live-Reload flackert nicht
+  error.value = null
+  try {
+    items.value = await fetchBlocksOverview(props.topic)
+  } catch (e) {
+    items.value = []
+    error.value = 'Overview not available — create blocks first.'
+  } finally {
+    loading.value = false
+  }
+}
+
+function relevant(b) {
+  const withRelevance = (b.subblocks || []).filter((s) => s.relevance)
+  return !withRelevance.length || withRelevance.some((s) => s.relevance === 'relevant')
+}
+
+function groups(b) {
+  return LEVELS
+    .map((st) => ({ ...st, subs: (b.subblocks || []).filter((s) => (LEGACY_LEVEL[s.level] || s.level) === st.key) }))
+    .filter((g) => g.subs.length)
+}
+
+const subTotal = computed(() => items.value.reduce((n, b) => n + (b.subblocks?.length || 0), 0))
+</script>
+
+<template>
+  <div class="bk-view">
+    <header class="bk-head">
+      <h1>{{ topic }}</h1>
+      <span class="bk-sub">Blocks overview</span>
+      <span v-if="items.length" class="bk-count">{{ items.length }} Blocks · {{ subTotal }} Subblocks</span>
+      <span class="bk-spacer"></span>
+      <button class="bk-close" title="Close" @click="emit('close')">✕</button>
+    </header>
+
+    <button v-if="generating" class="bk-banner" @click="emit('openGeneration')">
+      <span class="bk-progress-dot"></span>
+      Generierung läuft{{ progress ? ' · ' + progress : '' }} — Board öffnen →
+    </button>
+    <button v-else-if="!ready && !partial && !items.length && !loading" class="bk-banner idle" @click="emit('openGeneration')">
+      Noch keine Bausteine — zur Generierung →
+    </button>
+
+    <section v-if="comp" class="bk-panel" :class="{ ok: comp.vollstaendig }">
+      <button class="bk-panel-row" @click="compOpen = !compOpen">
+        <span class="bk-panel-status">{{ comp.vollstaendig ? '✓ Zerlegung vollständig' : '○ Zerlegung unvollständig' }}</span>
+        <span class="bk-panel-stat">{{ comp.bloecke }} Blöcke</span>
+        <span class="bk-panel-stat">{{ comp.subs }} Subbausteine</span>
+        <span v-if="comp.ziele_total" class="bk-panel-stat">Lernziele {{ comp.ziele_covered }}/{{ comp.ziele_total }}</span>
+        <span class="bk-panel-stat">{{ comp.frage_bloecke }}/{{ comp.bloecke }} mit Prüfungsfragen</span>
+        <span class="bk-panel-stat">{{ comp.lernkarten }} Lernartefakte</span>
+        <span v-if="comp.dead" class="bk-panel-stat warn">{{ comp.dead }} dead</span>
+        <span class="bk-panel-toggle">{{ compOpen ? '▴' : '▾' }}</span>
+      </button>
+      <div v-if="compOpen" class="bk-panel-detail">
+        <span>{{ comp.verworfen }} Kandidaten geprüft verworfen</span>
+        <span>{{ comp.zusammengelegt }} zusammengelegt (Dubletten/Umbrellas)</span>
+        <span>{{ comp.degradiert_geprueft }} Fragmente degradiert (Panel-geprüft)</span>
+        <span v-if="comp.panel_gerettet">{{ comp.panel_gerettet }} vom Panel gerettet</span>
+        <span v-if="comp.lauf_minuten">Lauf: {{ comp.lauf_minuten }} min</span>
+      </div>
+    </section>
+
+    <div v-if="loading" class="bk-empty-state">Loading…</div>
+    <div v-else-if="error && !generating" class="bk-empty-state">{{ error }}</div>
+    <div v-else-if="!items.length" class="bk-empty-state">No blocks yet.</div>
+
+    <div v-else class="bk-grid">
+      <article
+        v-for="b in items"
+        :key="b.num"
+        class="bk-card"
+        :class="{ 'bk-irrelevant': !relevant(b) }"
+        :title="relevant(b) ? null : 'Not relevant — comes later in the &quot;Rest&quot;'"
+      >
+        <h3 class="bk-title"><span class="bk-num">{{ b.num }}</span>{{ b.title }}</h3>
+        <p v-if="b.description" class="bk-desc">{{ b.description }}</p>
+        <div v-if="b.subblocks && b.subblocks.length" class="bk-levels">
+          <div v-for="g in groups(b)" :key="g.key" class="bk-level" :class="'st-' + g.key">
+            <span class="bk-level-label">{{ g.label }}</span>
+            <ul>
+              <li v-for="s in g.subs" :key="s.title" :class="{ rand: s.relevance === 'peripheral' }">
+                {{ s.title }}<span v-if="s.relevance === 'peripheral'" class="rand-tag" title="Peripheral topic — comes later in the 'Rest'">Edge</span>
+              </li>
+            </ul>
+          </div>
+        </div>
+        <p v-else class="bk-no-subs">No subblocks.</p>
+      </article>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.bk-view {
+  flex: 1;
+  min-width: 0;
+  height: 100dvh;
+  display: flex;
+  flex-direction: column;
+  overflow-y: auto;   /* EIN Seitenfluss: Board scrollt mit, nur der Kopf bleibt stehen */
+  background: var(--bg-preview);
+}
+
+.bk-head {
+  position: sticky;
+  top: 0;
+  z-index: 3;
+  display: flex;
+  align-items: baseline;
+  gap: 0.75rem;
+  padding: 1.25rem 2rem;
+  border-bottom: 1px solid var(--border);
+  background: var(--panel);
+}
+.bk-head h1 { font-size: 1.5rem; }
+.bk-sub { color: var(--text-faint); font-size: 0.9rem; font-weight: 600; }
+.bk-count { color: var(--text-muted); font-size: 0.82rem; }
+.bk-spacer { flex: 1; }
+.bk-close {
+  align-self: center;
+  border: 1px solid var(--border-strong);
+  border-radius: 6px;
+  background: var(--panel);
+  color: var(--text);
+  width: 2rem;
+  height: 2rem;
+  cursor: pointer;
+}
+.bk-close:hover { border-color: var(--accent); }
+
+.bk-progress-dot {
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  background: var(--accent);
+  animation: bk-pulse 1.2s ease-in-out infinite;
+}
+@keyframes bk-pulse { 0%, 100% { opacity: 1; } 50% { opacity: 0.3; } }
+
+
+
+
+
+.bk-banner {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  margin: 0.85rem 2rem 0;
+  padding: 0.55rem 0.9rem;
+  border: 1px solid var(--accent);
+  border-radius: 8px;
+  background: var(--panel);
+  color: var(--accent);
+  font-size: 0.84rem;
+  font-weight: 600;
+  cursor: pointer;
+  text-align: left;
+}
+.bk-banner.idle { border-color: var(--border-strong); color: var(--text-muted); }
+.bk-banner:hover { background: var(--panel-soft); }
+
+.bk-panel {
+  margin: 0.85rem 2rem 0;
+  border: 1px solid var(--border-strong);
+  border-radius: 8px;
+  background: var(--panel);
+}
+.bk-panel.ok { border-color: var(--level-beginner); }
+.bk-panel-row {
+  width: 100%;
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 0.4rem 1.1rem;
+  padding: 0.55rem 0.9rem;
+  border: none;
+  background: none;
+  color: var(--text);
+  font-size: 0.82rem;
+  cursor: pointer;
+  text-align: left;
+}
+.bk-panel-status { font-weight: 700; }
+.bk-panel.ok .bk-panel-status { color: var(--level-beginner); }
+.bk-panel-stat { color: var(--text-muted); }
+.bk-panel-stat.warn { color: var(--danger); font-weight: 600; }
+.bk-panel-toggle { margin-left: auto; color: var(--text-faint); }
+.bk-panel-detail {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.3rem 1.1rem;
+  padding: 0 0.9rem 0.6rem;
+  font-size: 0.78rem;
+  color: var(--text-faint);
+  border-top: 1px dashed var(--border);
+  padding-top: 0.5rem;
+}
+
+.bk-empty-state {
+  flex: 1;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  color: var(--text-muted);
+}
+
+.bk-grid {
+  flex: 1;
+  padding: 1.5rem 2rem 4rem;
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(320px, 1fr));
+  gap: 1rem;
+  align-content: start;
+}
+
+.bk-card {
+  background: var(--panel);
+  border: 1px solid var(--border);
+  border-top: 3px solid var(--accent-border);
+  border-radius: 10px;
+  padding: 1rem 1.1rem;
+}
+.bk-card.bk-irrelevant { opacity: 0.5; }
+
+.bk-title {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  font-size: 1rem;
+  margin-bottom: 0.4rem;
+}
+.bk-num {
+  flex: 0 0 auto;
+  min-width: 26px;
+  height: 26px;
+  padding: 0 6px;
+  border-radius: 7px;
+  background: var(--accent);
+  color: var(--on-accent);
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  font-size: 0.78rem;
+  font-weight: 700;
+}
+.bk-desc {
+  color: var(--text-muted);
+  font-size: 0.85rem;
+  line-height: 1.45;
+  margin-bottom: 0.7rem;
+}
+
+.bk-levels { display: flex; flex-direction: column; gap: 0.55rem; }
+.bk-level {
+  border-left: 3px solid var(--st);
+  padding-left: 0.6rem;
+}
+.bk-level.st-beginner { --st: var(--level-beginner); }
+.bk-level.st-advanced { --st: var(--level-advanced); }
+.bk-level.st-expert { --st: var(--level-expert); }
+
+.bk-level-label {
+  font-size: 0.66rem;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  color: var(--st);
+}
+.bk-level ul {
+  list-style: disc;
+  margin: 0.25rem 0 0;
+  padding-left: 1.15rem;
+}
+.bk-level li {
+  font-size: 0.85rem;
+  color: var(--text);
+  line-height: 1.35;
+  margin-bottom: 2px;
+}
+.bk-level li::marker { color: var(--text-faint); }
+.bk-level li.rand { color: var(--text-faint); }
+.rand-tag {
+  margin-left: 0.4rem;
+  font-size: 0.6rem;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.03em;
+  color: var(--text-faint);
+  border: 1px solid var(--border-strong);
+  border-radius: 4px;
+  padding: 0 4px;
+}
+
+.bk-no-subs { color: var(--text-faint); font-size: 0.8rem; font-style: italic; }
+</style>

frontend/src/components/ElementSuggestion.vue

@@ -1,212 +0,0 @@
-<script setup>
-import { ref, nextTick } from 'vue'
-import { renderMarkdown } from '../markdown.js'
-
-const props = defineProps({
-  change: { type: Object, required: true },
-  busy: { type: Boolean, default: false },
-})
-
-const emit = defineEmits(['apply', 'dismiss', 'refine'])
-
-const ACTION_LABELS = { entfernen: 'Entfernen:', anpassen: 'Anpassen:', hinzufuegen: 'Hinzufügen:' }
-
-const editing = ref(false)
-const instruction = ref('')
-const inputEl = ref(null)
-
-function toggleEdit() {
-  editing.value = !editing.value
-  if (editing.value) nextTick(() => inputEl.value?.focus())
-}
-
-function submit() {
-  const text = instruction.value.trim()
-  if (!text || props.busy) return
-  emit('refine', text)
-  instruction.value = ''
-  editing.value = false
-}
-</script>
-
-<template>
-  <div class="style-sugg" :class="{ busy }">
-    <div class="style-sugg-text"><strong>{{ ACTION_LABELS[change.action] }}</strong> {{ change.text }}</div>
-    <div v-if="change.content" class="style-sugg-preview markdown" v-html="renderMarkdown(change.content)"></div>
-    <div class="style-sugg-actions">
-      <button class="sugg-ok" :disabled="busy" @click="emit('apply')">Bestätigen</button>
-      <button class="sugg-no" :disabled="busy" @click="emit('dismiss')">Ablehnen</button>
-      <button class="sugg-edit" :disabled="busy" title="Vorschlag per Anweisung anpassen" @click="toggleEdit">✏️</button>
-    </div>
-    <div v-if="editing" class="sugg-edit-row">
-      <input
-        ref="inputEl"
-        v-model="instruction"
-        placeholder="Anweisung zum Vorschlag…"
-        @keyup.enter="submit"
-      />
-      <button :disabled="!instruction.trim() || busy" @click="submit">➤</button>
-    </div>
-  </div>
-</template>
-
-<style scoped>
-.style-sugg {
-  margin: 0.3rem 0 0.6rem;
-  padding: 0.5rem 0.6rem;
-  border: 1px dashed var(--accent);
-  border-radius: 8px;
-  background: var(--panel-soft);
-}
-
-.style-sugg.busy {
-  animation: pulse 1.5s ease-in-out infinite;
-}
-
-@keyframes pulse {
-  50% { opacity: 0.45; }
-}
-
-.style-sugg-text {
-  font-size: 0.76rem;
-  line-height: 1.4;
-  color: var(--text);
-}
-
-.style-sugg-text strong {
-  color: var(--accent);
-}
-
-.style-sugg-preview {
-  margin-top: 0.35rem;
-  font-size: 0.76rem;
-  line-height: 1.45;
-  color: var(--text-muted);
-}
-
-.style-sugg-actions {
-  display: flex;
-  align-items: center;
-  gap: 6px;
-  margin-top: 0.45rem;
-}
-
-.sugg-ok,
-.sugg-no {
-  padding: 4px 10px;
-  border-radius: 6px;
-  font-size: 0.74rem;
-  font-weight: 600;
-  cursor: pointer;
-}
-
-.sugg-ok {
-  border: none;
-  background: var(--accent);
-  color: var(--on-accent);
-}
-
-.sugg-no {
-  border: 1px solid var(--border-strong);
-  background: none;
-  color: var(--text-muted);
-}
-
-.sugg-no:hover {
-  border-color: var(--danger);
-  color: var(--danger);
-}
-
-.sugg-edit {
-  border: none;
-  background: none;
-  font-size: 0.8rem;
-  cursor: pointer;
-  padding: 2px 4px;
-  border-radius: 6px;
-  filter: grayscale(0.4);
-}
-
-.sugg-edit:hover {
-  background: var(--border);
-  filter: none;
-}
-
-.sugg-ok:disabled,
-.sugg-no:disabled,
-.sugg-edit:disabled {
-  opacity: 0.4;
-  cursor: not-allowed;
-}
-
-.sugg-edit-row {
-  display: flex;
-  gap: 6px;
-  margin-top: 0.45rem;
-}
-
-.sugg-edit-row input {
-  flex: 1;
-  padding: 5px 8px;
-  border: 1px solid var(--border-strong);
-  border-radius: 6px;
-  font-size: 0.76rem;
-  background: var(--panel);
-  color: var(--text);
-  outline: none;
-}
-
-.sugg-edit-row input:focus {
-  border-color: var(--accent);
-}
-
-.sugg-edit-row button {
-  width: 30px;
-  border: none;
-  border-radius: 6px;
-  background: var(--accent);
-  color: var(--on-accent);
-  font-size: 0.8rem;
-  cursor: pointer;
-}
-
-.sugg-edit-row button:disabled {
-  opacity: 0.4;
-  cursor: not-allowed;
-}
-
-/* Markdown in der Vorschau */
-.markdown :deep(p) {
-  margin: 0 0 0.4em;
-}
-
-.markdown :deep(p:last-child) {
-  margin-bottom: 0;
-}
-
-.markdown :deep(code) {
-  background: var(--border);
-  padding: 1px 4px;
-  border-radius: 4px;
-  font-family: "SF Mono", Consolas, monospace;
-  font-size: 0.85em;
-  overflow-wrap: anywhere;
-}
-
-.markdown :deep(pre) {
-  background: var(--code-bg, #1e2330);
-  color: var(--code-fg, #e6e8ee);
-  padding: 6px 8px;
-  border-radius: 6px;
-  white-space: pre-wrap;
-  overflow-wrap: anywhere;
-  margin: 0.3em 0;
-}
-
-.markdown :deep(pre code) {
-  background: none;
-  padding: 0;
-  color: inherit;
-  font-size: 0.85em;
-}
-</style>

frontend/src/components/ElementsOverview.vue

@@ -1,205 +0,0 @@
-<script setup>
-import { ref, watch } from 'vue'
-import { fetchElements } from '../api.js'
-import { renderMarkdown } from '../markdown.js'
-
-const props = defineProps({
-  topic: { type: String, required: true },
-  version: { type: Number, default: 0 }, // Erhöhung = Elemente neu laden
-})
-
-const emit = defineEmits(['open'])
-
-const elements = ref([])
-
-watch([() => props.topic, () => props.version], load, { immediate: true })
-
-async function load() {
-  try {
-    elements.value = await fetchElements(props.topic)
-  } catch (e) {
-    console.error('Fehler beim Laden der Elemente:', e)
-  }
-}
-
-function plain(text) {
-  return (text || '').replace(/```[a-z]*\n?/g, '').replace(/[`*_#]/g, '')
-}
-</script>
-
-<template>
-  <div class="elements-overview">
-    <div class="overview-scroll">
-      <div class="overview-content">
-        <header class="overview-head">
-          <h1>{{ topic }}</h1>
-          <span class="overview-format">Elemente</span>
-        </header>
-        <p v-if="!elements.length" class="overview-empty">
-          Noch keine Elemente. Rechts in der Sidebar Stichwort eingeben und + klicken.
-        </p>
-        <div class="element-grid">
-          <article
-            v-for="el in elements"
-            :key="el.id"
-            class="element-card"
-            @click="emit('open', el)"
-          >
-            <h3>{{ plain(el.title) }}</h3>
-            <div class="markdown" v-html="renderMarkdown(el.description)"></div>
-            <div v-for="(ex, i) in el.examples" :key="i" class="markdown el-example" v-html="renderMarkdown(ex)"></div>
-            <div v-if="el.hints.length" class="el-hints-block">
-              <h4>Hinweise</h4>
-              <ul>
-                <li v-for="(h, i) in el.hints" :key="i" class="markdown" v-html="renderMarkdown(h)"></li>
-              </ul>
-            </div>
-          </article>
-        </div>
-      </div>
-    </div>
-  </div>
-</template>
-
-<style scoped>
-.elements-overview {
-  flex: 1;
-  min-width: 0;
-  display: flex;
-  flex-direction: column;
-  background: var(--bg-preview);
-}
-
-.overview-scroll {
-  flex: 1;
-  overflow-y: auto;
-}
-
-.overview-content {
-  max-width: 1000px;
-  margin: 0 auto;
-  padding: 2.5rem 2rem 4rem;
-}
-
-.overview-head {
-  display: flex;
-  align-items: baseline;
-  gap: 0.8rem;
-  margin-bottom: 1.5rem;
-}
-
-.overview-head h1 {
-  margin: 0;
-  font-size: 2.2rem;
-  color: var(--text);
-}
-
-.overview-format {
-  font-size: 1rem;
-  font-weight: 600;
-  color: var(--text-faint);
-}
-
-.overview-empty {
-  color: var(--text-muted);
-}
-
-.element-grid {
-  display: grid;
-  grid-template-columns: repeat(auto-fill, minmax(340px, 1fr));
-  gap: 1rem;
-  align-items: start;
-}
-
-.element-card {
-  background: var(--panel);
-  border: 1px solid var(--border);
-  border-top: 3px solid var(--accent);
-  border-radius: 10px;
-  padding: 1rem 1.1rem;
-  cursor: pointer;
-  transition: box-shadow 0.15s, transform 0.15s;
-}
-
-.element-card:hover {
-  box-shadow: 0 4px 16px var(--shadow);
-  transform: translateY(-1px);
-}
-
-.element-card h3 {
-  margin: 0 0 0.5rem;
-  font-size: 1.05rem;
-  color: var(--text);
-}
-
-.el-example {
-  margin-top: 0.5rem;
-}
-
-.el-hints-block {
-  margin-top: 0.7rem;
-}
-
-.el-hints-block h4 {
-  margin: 0 0 0.3rem;
-  font-size: 0.72rem;
-  font-weight: 700;
-  text-transform: uppercase;
-  letter-spacing: 0.05em;
-  color: var(--text-faint);
-}
-
-.el-hints-block ul {
-  margin: 0;
-  padding-left: 1.1rem;
-}
-
-.el-hints-block li {
-  font-size: 0.85rem;
-  line-height: 1.5;
-  color: var(--text);
-  margin-bottom: 0.2rem;
-}
-
-/* Markdown im Guide-Stil */
-.markdown {
-  font-size: 0.9rem;
-  line-height: 1.55;
-  color: var(--text);
-}
-
-.markdown :deep(p) {
-  margin: 0 0 0.5em;
-}
-
-.markdown :deep(p:last-child) {
-  margin-bottom: 0;
-}
-
-.markdown :deep(code) {
-  background: var(--border);
-  padding: 1px 4px;
-  border-radius: 4px;
-  font-family: "SF Mono", Consolas, monospace;
-  font-size: 0.85em;
-  overflow-wrap: anywhere;
-}
-
-.markdown :deep(pre) {
-  background: var(--code-bg, #1e2330);
-  color: var(--code-fg, #e6e8ee);
-  padding: 10px 12px;
-  border-radius: 8px;
-  /* Umbrechen statt horizontal scrollen — Scrollbar verdeckt sonst die Code-Zeile */
-  white-space: pre-wrap;
-  overflow-wrap: anywhere;
-  margin: 0.4em 0;
-}
-
-.markdown :deep(pre code) {
-  background: none;
-  padding: 0;
-  color: inherit;
-  font-size: 0.85em;
-}
-</style>

frontend/src/components/FlashcardWidget.vue

@@ -0,0 +1,60 @@
+<script setup>
+import { ref, watch } from 'vue'
+import { renderMarkdownInline } from '../markdown.js'
+
+// Reine Flip-Karte: der Übungspool (PracticePanel) steuert Stapel und Leitner —
+// die Karte zeigt nur Frage/Antwort und meldet die Bewertung nach oben.
+const props = defineProps({ card: { type: Object, required: true } }) // { question, answer }
+const emit = defineEmits(['answer']) // answer(correct: boolean)
+
+const flipped = ref(false)
+watch(() => props.card, () => { flipped.value = false })
+</script>
+
+<template>
+  <div class="fc-body">
+    <div class="fc-card" :class="{ flipped }" @click="flipped = !flipped">
+      <div v-if="!flipped" class="fc-seite">
+        <span class="fc-label">Frage</span>
+        <div class="fc-text" v-html="renderMarkdownInline(card.question)"></div>
+        <span class="fc-hint">Klicken zum Umdrehen</span>
+      </div>
+      <div v-else class="fc-seite">
+        <span class="fc-label">Antwort</span>
+        <div class="fc-text" v-html="renderMarkdownInline(card.answer)"></div>
+      </div>
+    </div>
+    <div v-if="flipped" class="fc-aktionen">
+      <button class="fc-btn nochmal" @click="emit('answer', false)">Nochmal</button>
+      <button class="fc-btn gewusst" @click="emit('answer', true)">Gewusst</button>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.fc-body { margin-top: 0.5rem; }
+.fc-card {
+  position: relative; min-height: 120px; cursor: pointer;
+  border: 1px solid var(--border); border-radius: 10px;
+  padding: 1rem 1.1rem; background: var(--panel-soft);
+  display: flex; align-items: center; justify-content: center; text-align: center;
+  transition: border-color 0.15s;
+}
+.fc-card.flipped { border-color: var(--accent); }
+.fc-seite { display: flex; flex-direction: column; gap: 0.4rem; align-items: center; }
+.fc-label {
+  font-size: 0.66rem; text-transform: uppercase; letter-spacing: 0.05em;
+  color: var(--text-faint); font-weight: 700;
+}
+.fc-text { font-size: 0.98rem; line-height: 1.45; }
+.fc-hint { font-size: 0.7rem; color: var(--text-faint); margin-top: 0.2rem; }
+
+.fc-aktionen { display: flex; gap: 8px; margin-top: 0.5rem; }
+.fc-btn {
+  flex: 1; padding: 0.5rem; border-radius: 8px; cursor: pointer;
+  font-size: 0.82rem; font-weight: 600; border: 1px solid var(--border-strong);
+  background: var(--panel);
+}
+.fc-btn.gewusst { background: var(--success-soft); border-color: var(--success-border); color: var(--success); }
+.fc-btn.nochmal { color: var(--text-muted); }
+</style>

frontend/src/components/GeneralExamPanel.vue

@@ -0,0 +1,120 @@
+<script setup>
+// Topic-wide mixed exam: picks a block (prioritized: not yet at max), then random
+// within it, and reuses the normal BlockPanel. Each block has its own exam slot
+// (pruefungCache), so the question pools stay separate. Booking runs per block via the
+// normal exam route. Total cap = Σ cap_final of all checkable blocks.
+import { ref, computed, onMounted, onUnmounted } from 'vue'
+import { fetchGuides, fetchGuideContent, fetchBlockLearnState } from '../api.js'
+import BlockPanel from './BlockPanel.vue'
+
+const props = defineProps({
+  topic: { type: String, required: true },
+  provider: { type: String, default: 'claude' },
+})
+const emit = defineEmits(['progressChanged', 'fokus-active'])
+
+const sections = ref([])   // [{title, md, compact, num}] — checkable sections of the full version
+const learnstate = ref({})  // title -> {good_answers, streak, cap, cap_aktuell, freie_level}
+const active = ref(null)    // current block title
+const loadError = ref(null)
+
+const checkable = computed(() => sections.value.filter((s) => (learnstate.value[s.title]?.cap || 0) > 0))
+
+// Total progress: Σ min(score, cap_final) / Σ cap_final over all checkable blocks.
+const total = computed(() => {
+  let score = 0, cap = 0
+  for (const s of checkable.value) {
+    const l = learnstate.value[s.title] || {}
+    score += Math.min(l.good_answers || 0, l.cap || 0)
+    cap += l.cap || 0
+  }
+  return { score, cap }
+})
+
+const activeSection = computed(() => sections.value.find((s) => s.title === active.value) || null)
+const activeStatus = computed(() => learnstate.value[active.value] || null)
+
+// Priority: blocks not yet at cap_final; among those random.
+function pickBlock() {
+  const unfinished = checkable.value.filter((s) => {
+    const l = learnstate.value[s.title] || {}
+    return (l.good_answers || 0) < (l.cap || 0)
+  })
+  const pool = unfinished.length ? unfinished : checkable.value
+  active.value = pool.length ? pool[Math.floor(Math.random() * pool.length)].title : null
+}
+
+async function loadLearnState() {
+  try {
+    learnstate.value = (await fetchBlockLearnState(props.topic)).blocks || {}
+  } catch { /* offline → keep old state */ }
+}
+
+onMounted(async () => {
+  emit('fokus-active', true)
+  try {
+    const guides = await fetchGuides()
+    const g = guides
+      .filter((x) => x.topic === props.topic && x.format === 'Guide' && x.status === 'done')
+      .sort((a, b) => (a.created_at < b.created_at ? 1 : -1))[0]
+    if (!g) { loadError.value = 'No finished guide — create a guide first.'; return }
+    const content = await fetchGuideContent(g.id, 4)  // full version (all subs)
+    sections.value = (content.chapters || [])
+      .flatMap((ch) => ch.sections || [])
+      .filter((s) => s.checkable !== false)
+      .map((s) => ({ title: s.title, md: s.md, compact: s.compact, num: s.num }))
+    await loadLearnState()
+    pickBlock()
+  } catch {
+    loadError.value = 'Could not load the exam.'
+  }
+})
+
+onUnmounted(() => emit('fokus-active', false))
+
+async function onStatus() {
+  await loadLearnState()  // cap_aktuell/freie_level may have grown after an answer
+  emit('progressChanged')
+}
+</script>
+
+<template>
+  <div class="ge-panel">
+    <div class="ge-head">
+      <h2>General Exam</h2>
+      <span v-if="!loadError" class="ge-score">{{ total.score }} / {{ total.cap }}</span>
+      <button v-if="active" class="ge-next" title="Check another block" @click="pickBlock">⟳ Another block</button>
+    </div>
+
+    <p v-if="loadError" class="ge-msg">{{ loadError }}</p>
+    <p v-else-if="!checkable.length" class="ge-msg">No checkable blocks yet.</p>
+    <p v-else-if="!active" class="ge-msg">Everything maxed out — nothing left to check. 🎉</p>
+
+    <div v-else class="ge-body">
+      <div class="ge-block">Block: <strong>{{ active }}</strong></div>
+      <BlockPanel
+        :key="active"
+        mode="full"
+        :topic="topic"
+        :block="active"
+        :section="activeSection?.md || ''"
+        :section-compact="activeSection?.compact || ''"
+        :provider="provider"
+        :status="activeStatus"
+        :cap="activeStatus?.cap || 0"
+        @statusChanged="onStatus"
+      />
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.ge-panel { padding: 16px 20px; max-width: 900px; margin: 0 auto; }
+.ge-head { display: flex; align-items: center; gap: 14px; margin-bottom: 12px; }
+.ge-head h2 { margin: 0; font-size: 1.1rem; }
+.ge-score { font-variant-numeric: tabular-nums; color: var(--text-muted); font-weight: 600; }
+.ge-next { margin-left: auto; padding: 5px 10px; border: 1px solid var(--border-strong); border-radius: 6px; background: var(--bg); cursor: pointer; }
+.ge-next:hover { color: var(--accent-hover); }
+.ge-msg { color: var(--text-muted); }
+.ge-block { margin-bottom: 8px; color: var(--text-muted); font-size: 0.9rem; }
+</style>

frontend/src/components/GenerationView.vue

@@ -0,0 +1,343 @@
+<script setup>
+import { ref, computed, watch, onUnmounted } from 'vue'
+import { fetchBlocksBoard, runQa, runRepair } from '../api.js'
+import KanbanBoard from './KanbanBoard.vue'
+import GuideBoardSection from './GuideBoardSection.vue'
+
+const props = defineProps({
+  topic: { type: String, required: true },
+  generating: { type: Boolean, default: false },
+  progress: { type: String, default: null },
+  ready: { type: Boolean, default: false },
+  partial: { type: Boolean, default: false },
+  guideFormat: { type: String, default: 'Guide' },
+})
+const emit = defineEmits(['close', 'resetStage', 'restartAll', 'continueAll', 'addResearch',
+  'requeueDead', 'removeAll', 'cancel', 'cancelGuide', 'startGuide', 'resetGuideStage', 'preview', 'removeFormat', 'restartCard', 'resetGuideCard'])
+
+// ── Blocks-Pipeline (Poll 1.2s solange generiert) ──────────────────────────────
+const board = ref(null)
+let timer = null
+
+async function pollBoard() {
+  try {
+    board.value = await fetchBlocksBoard(props.topic)
+  } catch { /* Board noch leer */ }
+}
+function startPoll() { stopPoll(); timer = setInterval(pollBoard, 1200) }
+function stopPoll() { if (timer) { clearInterval(timer); timer = null } }
+
+watch(() => props.topic, () => { board.value = null; pollBoard() }, { immediate: true })
+watch(() => props.generating, (g) => {
+  if (g) startPoll()
+  else { stopPoll(); pollBoard() }  // Endstand nachladen
+}, { immediate: true })
+onUnmounted(stopPoll)
+
+const inventoryCols = computed(() => (board.value?.columns || []).filter((c) => c.board === 'inventory'))
+const artefactCols = computed(() => (board.value?.columns || []).filter((c) => c.board === 'artefacts'))
+const dead = computed(() => board.value?.dead || [])
+const qa = computed(() => board.value?.qa || null)
+
+// Spalten, auf die zurückgesetzt werden kann (Terminal-Spalten sind kein Reset-Ziel).
+const RESETTABLE = new Set(['ingest', 'cluster', 'pair_check', 'consensus_gate', 'clarify', 'naming',
+  'naming_check', 'fragment_filter', 'grouping', 'gap_check', 'done',
+  'subblocks', 'facts', 'konsolidierung', 'levels', 'relevance', 'question_pattern', 'artefacts', 'finalize', 'outline'])
+const sel = ref(null)          // gewählte Spalte {board, key, label}
+const selCard = ref(null)      // gewählte Karte (Einzel-Restart, nur artefacts)
+const confirm = ref(null)      // 2-Klick-Bestätigung für destruktive Aktionen
+
+function stageClick(c) {
+  if (props.generating || !RESETTABLE.has(c.key)) return
+  confirm.value = null
+  selCard.value = null
+  sel.value = sel.value?.key === c.key ? null : { board: c.board, key: c.key, label: c.label }
+}
+
+function cardClick(k) {
+  if (props.generating || k.kind !== 'ablock') return  // Einzel-Restart nur für Artefakt-Karten
+  confirm.value = null
+  sel.value = null
+  selCard.value = selCard.value?.card_id === k.card_id ? null : k
+}
+
+function restartCard() {
+  const k = selCard.value
+  selCard.value = null
+  confirm.value = null
+  later(() => emit('restartCard', k.card_id))
+}
+function arm(action, fn) {
+  if (confirm.value === action) { confirm.value = null; fn() }
+  else confirm.value = action
+}
+function later(fn) {  // Aktion emitten, Board kurz danach neu laden (kein generating-Poll aktiv)
+  fn()
+  setTimeout(pollBoard, 600)
+}
+
+function resetHere(restart) {
+  const s = sel.value
+  sel.value = null
+  confirm.value = null
+  later(() => emit('resetStage', { board: s.board, stage: s.key, restart }))
+}
+
+const qaBusy = ref(false)
+const guideRefresh = ref(0)  // QA/Repair schreiben auch den Guide-Report → Badge neu laden
+async function runQaClick() {
+  if (qaBusy.value) return
+  qaBusy.value = true
+  try {
+    await runQa(props.topic)
+  } finally {
+    qaBusy.value = false
+    pollBoard()
+    guideRefresh.value++
+  }
+}
+
+const repairBusy = ref(false)
+const repairInfo = ref('')
+async function repairClick() {
+  if (repairBusy.value) return
+  repairBusy.value = true
+  repairInfo.value = ''
+  try {
+    const r = await runRepair(props.topic)
+    const n = (r.hygiene || []).length + (r.merges || []).length + (r.sub_merges || []).length
+      + (r.entfernt || []).length + (r.aufgeraeumt || 0) + (r.freigesprochen || []).length
+    repairInfo.value = n === 0
+      ? 'keine behebbaren Befunde'
+      : `${(r.hygiene || []).length} Titel · ${(r.merges || []).length} Merges · ${(r.sub_merges || []).length} Sub-Merges · ${(r.entfernt || []).length} entfernt · ${r.aufgeraeumt || 0} aufgeräumt · ${(r.freigesprochen || []).length} freigesprochen`
+  } catch (e) {
+    repairInfo.value = String(e.message || e)
+  } finally {
+    repairBusy.value = false
+    pollBoard()
+  }
+}
+</script>
+
+<template>
+  <div class="gen-view">
+    <header class="gen-head">
+      <h1>{{ topic }}</h1>
+      <span class="gen-sub">Generierung</span>
+      <span class="gen-spacer"></span>
+      <button class="gen-close" title="Close" @click="emit('close')">✕</button>
+    </header>
+
+    <div v-if="qa && qa.pausiert" class="qa-pause">
+      <strong>QA-Gate: Note {{ qa.note.toFixed(1) }} unter Schwelle {{ qa.schwelle }} — pausiert.</strong>
+      <span v-if="qa.befunde.length"> Befunde: {{ qa.befunde.join(' · ') }}</span>
+      <button class="gen-act" @click="emit('continueAll', { qaForce: true })">Trotzdem fortsetzen</button>
+    </div>
+    <section class="gen-section">
+      <div class="gen-steps-top">
+        <span class="gen-title">Bausteine</span>
+        <div v-if="progress" class="gen-progress"><span class="gen-progress-dot"></span>{{ progress }}</div>
+        <div v-if="!generating" class="gen-actions">
+          <button class="gen-act" :disabled="qaBusy" title="QA-Lauf wie am Gate (inkl. LLM-Stichprobe)"
+                  @click="runQaClick">{{ qaBusy ? 'QA läuft…' : 'QA' }}</button>
+          <button v-if="qa" class="gen-act" :disabled="repairBusy"
+                  title="QA-Befunde gezielt beheben: Hygiene, bestätigte Dubletten mergen, Fremd/Unecht nach Gegen-Judge entfernen"
+                  @click="repairClick">{{ repairBusy ? 'Repariert…' : 'Befunde beheben' }}</button>
+          <span v-if="repairInfo" class="repair-info">{{ repairInfo }}</span>
+          <button class="gen-act play" @click="emit('restartAll')">{{ ready || partial ? '+ Research' : 'Generate' }}</button>
+          <button v-if="partial" class="gen-act" @click="emit('continueAll')">Continue</button>
+          <button
+            v-if="ready || partial"
+            class="gen-act danger"
+            :class="{ armed: confirm === 'remove' }"
+            @click="arm('remove', () => later(() => emit('removeAll')))"
+          >{{ confirm === 'remove' ? 'Sure?' : 'Remove' }}</button>
+        </div>
+        <div v-else class="gen-actions">
+          <button class="gen-act" @click="emit('addResearch')">+ Research</button>
+          <button class="gen-act danger" @click="emit('cancel')">Cancel</button>
+        </div>
+        <button
+          v-if="dead.length"
+          class="gen-act"
+          :title="dead.map((d) => d.title + ': ' + d.error).join('\n')"
+          @click="later(() => emit('requeueDead'))"
+        >⟳ {{ dead.length }} dead</button>
+      </div>
+
+      <div class="gen-board-label">
+        Inventar
+        <span v-if="qa" class="qa-note" :class="qa.note >= qa.schwelle ? 'ok' : 'bad'"
+              :title="'QA-Schwelle ' + qa.schwelle">QA {{ qa.note.toFixed(1) }}/10</span>
+      </div>
+      <KanbanBoard
+        :columns="inventoryCols"
+        :agents="board?.agents || []"
+        :generating="generating"
+        :selectable="!generating"
+        :selectedKey="sel?.board === 'inventory' ? sel.key : null"
+        @stageClick="stageClick"
+      />
+      <div class="gen-board-label">
+        Artefakte
+        <span v-if="qa && qa.note_artefakte != null" class="qa-note"
+              :class="qa.note_artefakte >= qa.schwelle ? 'ok' : 'bad'"
+              title="Beleg-Quote + verwaiste Artefakte">QA {{ qa.note_artefakte.toFixed(1) }}/10</span>
+      </div>
+      <KanbanBoard
+        :columns="artefactCols"
+        :generating="generating"
+        :selectable="!generating"
+        :cardSelectable="!generating"
+        :selectedKey="sel?.board === 'artefacts' ? sel.key : null"
+        @stageClick="stageClick"
+        @cardClick="cardClick"
+      />
+
+      <div v-if="selCard && !generating" class="gen-step-actions">
+        <span class="gen-step-actions-label">Karte «{{ selCard.title }}»:</span>
+        <button class="gen-act play" :class="{ armed: confirm === 'card' }" @click="confirm === 'card' ? restartCard() : confirm = 'card'">{{ confirm === 'card' ? 'Sure?' : '↻ Karte neu generieren' }}</button>
+        <button class="gen-act ghost" @click="selCard = null; confirm = null">Abbrechen</button>
+      </div>
+      <div v-if="sel && !generating" class="gen-step-actions">
+        <span class="gen-step-actions-label">Ab «{{ sel.label }}»:</span>
+        <button class="gen-act play" @click="resetHere(true)">↻ neu generieren</button>
+        <button class="gen-act danger" :class="{ armed: confirm === 'reset' }" @click="arm('reset', () => resetHere(false))">{{ confirm === 'reset' ? 'Sure?' : '✕ nur zurücksetzen' }}</button>
+        <button class="gen-act ghost" @click="sel = null; confirm = null">Abbrechen</button>
+      </div>
+    </section>
+
+    <section class="gen-section">
+      <GuideBoardSection
+        :topic="topic"
+        :format="guideFormat"
+        :refresh="guideRefresh"
+        @cancelGuide="(id) => emit('cancelGuide', id)"
+        @startGuide="(p) => emit('startGuide', p)"
+        @resetStage="(p) => emit('resetGuideStage', p)"
+        @preview="emit('preview')"
+        @removeFormat="(f) => emit('removeFormat', f)"
+        @resetCard="(p) => emit('resetGuideCard', p)"
+      />
+    </section>
+  </div>
+</template>
+
+<style scoped>
+.gen-view {
+  flex: 1;
+  min-width: 0;
+  height: 100dvh;
+  display: flex;
+  flex-direction: column;
+  overflow-y: auto;
+  background: var(--bg-preview);
+}
+.gen-head {
+  position: sticky;
+  top: 0;
+  z-index: 3;
+  display: flex;
+  align-items: baseline;
+  gap: 0.75rem;
+  padding: 1.25rem 2rem;
+  border-bottom: 1px solid var(--border);
+  background: var(--panel);
+}
+.gen-head h1 { font-size: 1.5rem; }
+.gen-sub { color: var(--text-faint); font-size: 0.9rem; font-weight: 600; }
+.gen-spacer { flex: 1; }
+.gen-close {
+  align-self: center;
+  border: 1px solid var(--border-strong);
+  border-radius: 6px;
+  background: var(--panel);
+  color: var(--text);
+  width: 2rem;
+  height: 2rem;
+  cursor: pointer;
+}
+.gen-close:hover { border-color: var(--accent); }
+
+.gen-section {
+  padding: 0.85rem 2rem;
+  border-bottom: 1px solid var(--border);
+  background: var(--panel-soft);
+}
+.gen-title { font-size: 0.9rem; font-weight: 700; }
+.gen-board-label {
+  font-size: 0.64rem;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: var(--text-faint);
+  margin: 0.5rem 0 0.3rem;
+}
+.gen-progress {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  font-size: 0.84rem;
+  color: var(--accent);
+  font-weight: 600;
+}
+.gen-progress-dot {
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  background: var(--accent);
+  animation: gen-pulse 1.2s ease-in-out infinite;
+}
+@keyframes gen-pulse { 0%, 100% { opacity: 1; } 50% { opacity: 0.3; } }
+
+.gen-steps-top { display: flex; align-items: center; gap: 1rem; min-height: 1.9rem; margin-bottom: 0.4rem; }
+.gen-actions { margin-left: auto; display: flex; gap: 0.4rem; }
+
+.gen-step-actions {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  margin-top: 0.75rem;
+  padding-top: 0.7rem;
+  border-top: 1px dashed var(--border-strong);
+}
+.gen-step-actions-label { font-size: 0.8rem; font-weight: 600; color: var(--text-muted); }
+
+.gen-act {
+  border: 1px solid var(--border-strong);
+  border-radius: 6px;
+  background: var(--panel);
+  color: var(--text);
+  font-size: 0.8rem;
+  padding: 0.3rem 0.7rem;
+  cursor: pointer;
+  font-weight: 600;
+}
+.gen-act:hover { border-color: var(--accent); }
+.gen-act.play { background: var(--accent); color: var(--on-accent); border-color: var(--accent); }
+.gen-act.play:hover { background: var(--accent-hover); }
+.gen-act.danger { color: var(--danger); border-color: var(--danger); background: transparent; }
+.gen-act.danger.armed { background: var(--danger); color: #fff; }
+.gen-act.ghost { color: var(--text-muted); }
+.qa-note {
+  font-size: 0.78rem;
+  font-weight: 600;
+  padding: 0.1rem 0.5rem;
+  border-radius: 999px;
+}
+.qa-note.ok { background: color-mix(in srgb, #22c55e 18%, transparent); color: #16a34a; }
+.qa-note.bad { background: color-mix(in srgb, #ef4444 18%, transparent); color: #dc2626; }
+.repair-info { font-size: 0.78rem; color: var(--text-muted); }
+.qa-pause {
+  display: flex;
+  align-items: center;
+  gap: 0.6rem;
+  flex-wrap: wrap;
+  padding: 0.5rem 0.8rem;
+  margin-bottom: 0.8rem;
+  border: 1px solid color-mix(in srgb, #ef4444 40%, transparent);
+  border-radius: 8px;
+  background: color-mix(in srgb, #ef4444 8%, transparent);
+  font-size: 0.85rem;
+}
+</style>

frontend/src/components/GuideBoardSection.vue

@@ -0,0 +1,207 @@
+<script setup>
+import { ref, computed, watch, onUnmounted } from 'vue'
+import { fetchGuideBoard, repairGuideBoard } from '../api.js'
+import KanbanBoard from './KanbanBoard.vue'
+
+const props = defineProps({
+  topic: { type: String, required: true },
+  format: { type: String, default: 'Guide' },
+  refresh: { type: Number, default: 0 },  // Eltern-Signal: QA/Repair schrieben einen Guide-Report
+})
+const emit = defineEmits(['cancelGuide', 'startGuide', 'resetStage', 'preview', 'removeFormat', 'resetCard'])
+
+const board = ref(null)
+let timer = null
+
+async function poll() {
+  try {
+    board.value = await fetchGuideBoard(props.topic, props.format)
+  } catch { /* Board noch leer */ }
+}
+function startPoll() { stopPoll(); timer = setInterval(poll, 1200) }
+function stopPoll() { if (timer) { clearInterval(timer); timer = null } }
+
+watch(() => props.topic, () => { board.value = null; poll() }, { immediate: true })
+watch(() => props.refresh, () => poll())
+watch(() => board.value?.generating, (g) => { if (g) startPoll(); else stopPoll() })
+onUnmounted(stopPoll)
+
+const generating = computed(() => !!board.value?.generating)
+const columns = computed(() => board.value?.columns || [])
+const total = computed(() => columns.value.reduce((n, c) => n + c.total, 0))
+const done = computed(() => columns.value.find((c) => c.key === 'done')?.total || 0)
+
+// Stage-Index für ab_step (Reihenfolge = Spalten ohne "done").
+const STAGES = ['lernziele', 'zuweisung', 'writer', 'pruefer', 'fix']
+const sel = ref(null)
+const selCard = ref(null)
+const confirm = ref(null)
+
+function stageClick(c) {
+  if (generating.value || !STAGES.includes(c.key)) return
+  confirm.value = null
+  selCard.value = null
+  sel.value = sel.value?.key === c.key ? null : { key: c.key, label: c.label, idx: STAGES.indexOf(c.key) }
+}
+
+function cardClick(k) {
+  if (generating.value || !k.card_id) return
+  confirm.value = null
+  sel.value = null
+  const idx = Math.max(0, STAGES.indexOf(k.column))
+  selCard.value = selCard.value?.card_id === k.card_id ? null : { ...k, idx }
+}
+
+function resetCardHere() {
+  const k = selCard.value
+  selCard.value = null
+  confirm.value = null
+  emit('resetCard', { format: props.format, blockNorm: k.card_id, abStage: 0 })
+  setTimeout(poll, 400)
+}
+function arm(action, fn) {
+  if (confirm.value === action) { confirm.value = null; fn() }
+  else confirm.value = action
+}
+const repairBusy = ref(false)
+const repairInfo = ref('')
+async function repairClick() {
+  repairBusy.value = true
+  repairInfo.value = ''
+  try {
+    const r = await repairGuideBoard(props.topic, props.format)
+    repairInfo.value = (r.betroffen || []).length
+      ? `${r.betroffen.length} Abschnitt(e) → Prüfen`
+      : 'keine Befunde im letzten QA-Report'
+    if ((r.betroffen || []).length) startPoll()
+  } catch (e) {
+    repairInfo.value = String(e.message || e)
+  } finally {
+    repairBusy.value = false
+  }
+}
+function restartHere() {
+  const s = sel.value
+  sel.value = null
+  emit('startGuide', { format: props.format, abStep: s.idx })
+  startPoll()
+}
+function resetHere() {
+  const s = sel.value
+  sel.value = null
+  emit('resetStage', { format: props.format, abStage: s.idx })
+  setTimeout(poll, 400)
+}
+</script>
+
+<template>
+  <section class="gb-board">
+    <div class="gb-top">
+      <span class="gb-title">Guide · {{ format }}</span>
+      <span v-if="board?.qa_guide != null" class="gb-qa" :class="board.qa_guide >= 9 ? 'ok' : 'bad'"
+            title="Guide-QA (make qa-guide)">QA {{ board.qa_guide.toFixed(1) }}/10</span>
+      <span v-if="total" class="gb-count">{{ done }}/{{ total }} Karten fertig</span>
+      <div v-if="board?.progress && generating" class="gb-progress"><span class="gb-progress-dot"></span>{{ board.progress }}</div>
+      <div v-if="board?.error" class="gb-error">{{ board.error }}</div>
+      <div class="gb-actions">
+        <template v-if="generating">
+          <button class="gb-act danger" @click="emit('cancelGuide', board?.guide_id)">Abbrechen</button>
+        </template>
+        <template v-else>
+          <button class="gb-act play" @click="emit('startGuide', { format, abStep: null }); startPoll()">{{ total && done < total ? 'Fortsetzen' : total ? 'Neu generieren' : 'Generieren' }}</button>
+          <button v-if="done === total && total" class="gb-act" @click="emit('preview')">Guide öffnen</button>
+          <button v-if="total && board?.qa_guide != null && board.qa_guide < 10" class="gb-act"
+                  :disabled="repairBusy" @click="repairClick">{{ repairBusy ? 'Repariert…' : 'Befunde beheben' }}</button>
+          <span v-if="repairInfo" class="gb-count">{{ repairInfo }}</span>
+          <button v-if="total" class="gb-act danger" :class="{ armed: confirm === 'delete' }" @click="arm('delete', () => { emit('removeFormat', format); setTimeout(poll, 600) })">{{ confirm === 'delete' ? 'Sure?' : 'Remove' }}</button>
+        </template>
+      </div>
+    </div>
+
+    <KanbanBoard
+      :columns="columns"
+      :agents="board?.agents || []"
+      :generating="generating"
+      :selectable="!generating"
+      :cardSelectable="!generating"
+      :selectedKey="sel?.key || null"
+      @stageClick="stageClick"
+      @cardClick="cardClick"
+    />
+
+    <div v-if="selCard && !generating" class="gb-stage-actions">
+      <span class="gb-stage-label">Karte «{{ selCard.title }}»:</span>
+      <button class="gb-act play" :class="{ armed: confirm === 'card' }" @click="confirm === 'card' ? resetCardHere() : confirm = 'card'">{{ confirm === 'card' ? 'Sure?' : '↻ Karte neu (ab Lernziele)' }}</button>
+      <button class="gb-act ghost" @click="selCard = null; confirm = null">Abbrechen</button>
+    </div>
+    <div v-if="sel && !generating" class="gb-stage-actions">
+      <span class="gb-stage-label">Ab «{{ sel.label }}»:</span>
+      <button class="gb-act play" @click="restartHere">↻ neu generieren</button>
+      <button class="gb-act danger" :class="{ armed: confirm === 'reset' }" @click="arm('reset', resetHere)">{{ confirm === 'reset' ? 'Sure?' : '✕ nur zurücksetzen' }}</button>
+      <button class="gb-act ghost" @click="sel = null; confirm = null">Abbrechen</button>
+    </div>
+
+    <div v-if="!total && !generating" class="gb-empty">Noch kein Board — «Generieren» erzeugt eine Karte je Baustein und schiebt sie live durch die Spalten.</div>
+  </section>
+</template>
+
+<style scoped>
+.gb-board { padding: 0.85rem 0 0; }
+.gb-top { display: flex; align-items: center; gap: 1rem; min-height: 1.9rem; margin-bottom: 0.6rem; }
+.gb-title { font-size: 0.9rem; font-weight: 700; }
+.gb-count { color: var(--text-muted); font-size: 0.82rem; }
+.gb-qa {
+  font-size: 0.78rem;
+  font-weight: 600;
+  padding: 0.1rem 0.5rem;
+  border-radius: 999px;
+}
+.gb-qa.ok { background: color-mix(in srgb, #22c55e 18%, transparent); color: #16a34a; }
+.gb-qa.bad { background: color-mix(in srgb, #ef4444 18%, transparent); color: #dc2626; }
+.gb-progress {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  font-size: 0.84rem;
+  color: var(--accent);
+  font-weight: 600;
+}
+.gb-progress-dot {
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  background: var(--accent);
+  animation: gb-pulse 1.2s ease-in-out infinite;
+}
+@keyframes gb-pulse { 0%, 100% { opacity: 1; } 50% { opacity: 0.3; } }
+.gb-error { color: var(--danger); font-size: 0.82rem; }
+.gb-actions { margin-left: auto; display: flex; gap: 0.4rem; }
+
+.gb-stage-actions {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  margin-top: 0.75rem;
+  padding-top: 0.7rem;
+  border-top: 1px dashed var(--border-strong);
+}
+.gb-stage-label { font-size: 0.8rem; font-weight: 600; color: var(--text-muted); }
+.gb-empty { color: var(--text-faint); font-size: 0.85rem; padding: 1rem 0; }
+
+.gb-act {
+  border: 1px solid var(--border-strong);
+  border-radius: 6px;
+  background: var(--panel);
+  color: var(--text);
+  font-size: 0.8rem;
+  padding: 0.3rem 0.7rem;
+  cursor: pointer;
+  font-weight: 600;
+}
+.gb-act:hover { border-color: var(--accent); }
+.gb-act.play { background: var(--accent); color: var(--on-accent); border-color: var(--accent); }
+.gb-act.play:hover { background: var(--accent-hover); }
+.gb-act.danger { color: var(--danger); border-color: var(--danger); background: transparent; }
+.gb-act.danger.armed { background: var(--danger); color: #fff; }
+.gb-act.ghost { color: var(--text-muted); }
+</style>

frontend/src/components/KanbanBoard.vue

@@ -0,0 +1,263 @@
+<script setup>
+// Gemeinsame Live-Board-Komponente (Blocks + Guide): Spalten mit Count-Badge und
+// Karten-Titeln. Spaltenkopf-Klick (wenn erlaubt) → stageClick für Reset-Aktionen.
+const props = defineProps({
+  columns: { type: Array, default: () => [] },   // [{key, board?, label, total, cards:[{title,status,info,retries?,rounds?,ziele?}]}]
+  agents: { type: Array, default: () => [] },    // [{label, runtime}]
+  generating: { type: Boolean, default: false },
+  selectable: { type: Boolean, default: false }, // Spaltenkopf klickbar (Reset ab Spalte)
+  cardSelectable: { type: Boolean, default: false }, // Karten klickbar (Einzel-Restart)
+  selectedKey: { type: String, default: null },
+  hideEmpty: { type: Boolean, default: false },  // leere Spalten ausblenden (Terminal-Spalten)
+})
+const emit = defineEmits(['stageClick', 'cardClick'])
+
+function visible(c) {
+  return !props.hideEmpty || c.total > 0
+}
+
+function fmtRuntime(s) {
+  return s >= 60 ? `${Math.floor(s / 60)}m${String(Math.round(s % 60)).padStart(2, '0')}s` : `${Math.round(s)}s`
+}
+</script>
+
+<template>
+  <div class="kb">
+    <div v-if="agents.length" class="kb-agents">
+      <span class="kb-agents-label">{{ agents.length }} Agent(en):</span>
+      <span v-for="(a, i) in agents" :key="a.key || i" class="kb-agent" :title="a.key">{{ a.label }} · {{ fmtRuntime(a.runtime) }}</span>
+    </div>
+    <div class="kb-cols">
+      <div
+        v-for="c in columns.filter(visible)"
+        :key="(c.board || '') + c.key"
+        class="kb-col"
+        :class="{ active: c.total > 0, sel: selectedKey === c.key, collapsed: !c.total }"
+      >
+        <button
+          class="kb-col-head"
+          :disabled="!selectable"
+          :title="selectable ? `Aktionen ab «${c.label}»` : c.label"
+          @click="selectable && emit('stageClick', c)"
+        >
+          <span class="kb-col-label">{{ c.label }}</span>
+          <span class="kb-col-count" :class="{ zero: !c.total }">{{ c.total }}</span>
+        </button>
+        <ul v-if="c.cards && c.cards.length" class="kb-cards">
+          <li
+            v-for="(k, i) in c.cards" :key="i" class="kb-card"
+            :class="[k.status, { klickbar: cardSelectable && k.card_id }]"
+            :title="cardSelectable && k.card_id ? `${k.title} — Klick: Karte neu generieren` : (k.info || k.title)"
+            @click="cardSelectable && k.card_id && emit('cardClick', { ...k, column: c.key, colBoard: c.board })"
+          >
+            <div class="kb-card-row">
+              <span class="kb-dot" :class="[k.status, { pulse: generating && k.status === 'active' }]"></span>
+              <span class="kb-card-title">{{ k.title }}</span>
+              <span v-if="k.rounds" class="kb-badge" title="Writer-Runden">R{{ k.rounds }}</span>
+              <span v-if="k.ziele" class="kb-badge ziele" title="Lernziele abgedeckt">{{ k.ziele }}</span>
+            </div>
+            <div v-if="k.info && k.status === 'active'" class="kb-card-info">{{ k.info }}</div>
+            <div v-if="k.step_n && k.status === 'active'" class="kb-steps" :title="k.steps ? k.steps.join(' → ') : ''">
+              <span
+                v-for="s in k.step_n" :key="s" class="kb-step"
+                :class="{ done: s < k.step_i, act: s === k.step_i }"
+                :title="k.steps ? k.steps[s - 1] : ''"
+              ></span>
+            </div>
+          </li>
+          <li v-if="c.total > c.cards.length" class="kb-more">+{{ c.total - c.cards.length }} weitere</li>
+        </ul>
+      </div>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.kb { display: flex; flex-direction: column; gap: 0.5rem; }
+
+.kb-agents {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.35rem 0.7rem;
+  font-size: 0.72rem;
+  color: var(--text-muted);
+}
+.kb-agents-label { font-weight: 700; color: var(--accent); }
+.kb-agent {
+  border: 1px solid var(--border);
+  border-radius: 5px;
+  padding: 0 0.35rem;
+  background: var(--panel);
+  white-space: nowrap;
+}
+
+.kb-cols {
+  display: flex;
+  gap: 0.45rem;
+  overflow-x: auto;   /* Fallback (schmale Screens) — am Desktop passt alles dank Kollaps */
+  align-items: stretch;
+  padding-bottom: 0.3rem;
+}
+.kb-col {
+  flex: 1 1 150px;
+  min-width: 140px;
+  max-width: 230px;
+  align-self: flex-start;
+  border: 1px solid var(--border);
+  border-radius: 8px;
+  background: var(--panel);
+  opacity: 0.6;
+}
+.kb-col.active { opacity: 1; border-color: var(--border-strong); }
+.kb-col.sel { border-color: var(--accent); box-shadow: 0 0 0 2px var(--accent-soft); }
+
+/* Leere Spalten kollabieren zu schmalen Säulen (Jira-Muster) — der Kopf bleibt
+   klickbar (Reset ab Spalte), das Label läuft vertikal. */
+.kb-col.collapsed {
+  flex: 0 0 auto;
+  min-width: 0;
+  width: 32px;
+  align-self: stretch;
+  opacity: 0.5;
+}
+.kb-col.collapsed:hover { opacity: 0.85; }
+.kb-col.collapsed .kb-col-head {
+  flex-direction: column-reverse;
+  justify-content: flex-end;
+  align-items: center;
+  gap: 0.4rem;
+  height: 100%;
+  min-height: 130px;
+  border-bottom: none;
+  border-radius: 8px;
+  padding: 0.4rem 0;
+}
+.kb-col.collapsed .kb-col-label {
+  writing-mode: vertical-rl;
+  transform: rotate(180deg);
+  font-size: 0.6rem;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  max-height: 150px;
+}
+
+.kb-col-head {
+  width: 100%;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.3rem;
+  border: none;
+  border-bottom: 1px solid var(--border);
+  background: var(--panel-soft);
+  border-radius: 8px 8px 0 0;
+  padding: 0.3rem 0.5rem;
+  cursor: pointer;
+  color: var(--text-muted);
+}
+.kb-col-head:disabled { cursor: default; }
+.kb-col-head:hover:not(:disabled) { color: var(--accent); }
+.kb-col-label {
+  font-size: 0.68rem;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.03em;
+  white-space: nowrap;
+}
+.kb-col-count {
+  min-width: 1.3rem;
+  text-align: center;
+  border-radius: 6px;
+  background: var(--accent);
+  color: var(--on-accent);
+  font-size: 0.7rem;
+  font-weight: 700;
+  padding: 0 0.25rem;
+}
+.kb-col-count.zero { background: var(--border-strong); color: var(--text-faint); }
+
+.kb-cards {
+  list-style: none;
+  margin: 0;
+  padding: 0.3rem;
+  display: flex;
+  flex-direction: column;
+  gap: 0.25rem;
+  max-height: 240px;
+  overflow-y: auto;
+}
+.kb-card {
+  font-size: 0.74rem;
+  line-height: 1.25;
+  padding: 0.2rem 0.3rem;
+  border: 1px solid var(--border);
+  border-radius: 5px;
+  background: var(--bg);
+}
+.kb-card.error { border-color: var(--danger); }
+.kb-card.active { border-color: var(--accent-border); }
+.kb-card-row { display: flex; align-items: center; gap: 0.35rem; }
+.kb-card.klickbar { cursor: pointer; }
+.kb-card.klickbar:hover { border-color: var(--accent); }
+
+.kb-card-info {
+  margin: 0.15rem 0 0 1rem;
+  font-size: 0.66rem;
+  color: var(--text-faint);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+/* Phase stepper: one segment per fine step of the card's stage */
+.kb-steps {
+  display: flex;
+  gap: 3px;
+  margin: 0.25rem 0 0.05rem 1rem;
+}
+.kb-step {
+  flex: 1;
+  max-width: 26px;
+  height: 3px;
+  border-radius: 2px;
+  background: var(--border, #444);
+}
+.kb-step.done { background: var(--accent, #7aa2f7); opacity: 0.55; }
+.kb-step.act {
+  background: var(--accent, #7aa2f7);
+  animation: kbStepPulse 1.2s ease-in-out infinite;
+}
+@keyframes kbStepPulse {
+  0%, 100% { opacity: 1; }
+  50% { opacity: 0.35; }
+}
+.kb-card-title {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.kb-dot {
+  flex: 0 0 auto;
+  width: 7px;
+  height: 7px;
+  border-radius: 50%;
+  background: var(--text-faint);
+}
+.kb-dot.error { background: var(--danger); }
+.kb-dot.pulse { background: var(--accent); animation: kb-pulse 1.2s ease-in-out infinite; }
+@keyframes kb-pulse { 0%, 100% { opacity: 1; } 50% { opacity: 0.25; } }
+
+.kb-badge {
+  flex: 0 0 auto;
+  font-size: 0.6rem;
+  font-weight: 700;
+  border: 1px solid var(--warning-border);
+  color: var(--warning);
+  border-radius: 4px;
+  padding: 0 3px;
+}
+.kb-badge.ziele { border-color: var(--success-border); color: var(--success); }
+.kb-more { font-size: 0.68rem; color: var(--text-faint); padding: 0.1rem 0.3rem; }
+</style>

frontend/src/components/PracticePanel.vue

@@ -0,0 +1,114 @@
+<script setup>
+// Übungspool: EIN Leitner-Stapel pro Thema (fällige Karten zuerst, dann neue).
+// Der Server wählt und ordnet die Karten (Entscheidungs-Entlastung); „Nochmal"
+// schiebt die Karte ans Rundenende, gebucht wird jede Antwort sofort.
+import { ref, computed, onMounted } from 'vue'
+import { fetchPracticeDeck, answerPracticeCard } from '../api.js'
+import FlashcardWidget from './FlashcardWidget.vue'
+
+const props = defineProps({
+  topic: { type: String, required: true },
+})
+
+const deck = ref([])        // Karten in Übungsreihenfolge
+const counts = ref(null)    // {due, new, new_total, gesperrt}
+const nextDueAt = ref(null)
+const loadError = ref(null)
+const loading = ref(true)
+const erledigt = ref(0)
+
+const current = computed(() => deck.value[0] || null)
+const offen = computed(() => deck.value.length)
+
+async function loadDeck() {
+  loading.value = true
+  loadError.value = null
+  erledigt.value = 0
+  try {
+    const d = await fetchPracticeDeck(props.topic)
+    deck.value = d.cards || []
+    counts.value = d.counts || null
+    nextDueAt.value = d.next_due_at
+  } catch (e) {
+    loadError.value = e.message || 'Übungsstapel nicht ladbar.'
+  } finally {
+    loading.value = false
+  }
+}
+
+onMounted(loadDeck)
+
+async function onAnswer(correct) {
+  const card = current.value
+  if (!card) return
+  try {
+    await answerPracticeCard({
+      topic: props.topic, block_norm: card.block_norm,
+      sub_norm: card.sub_norm, correct,
+    })
+  } catch { /* Buchung offline fehlgeschlagen — Durchgang läuft lokal weiter */ }
+  deck.value.shift()
+  if (correct) {
+    erledigt.value += 1
+  } else {
+    deck.value.push(card) // Rundenende: Box 1 ist sofort wieder fällig
+  }
+}
+
+function naechsteFaelligkeit() {
+  if (!nextDueAt.value) return null
+  const d = new Date(nextDueAt.value)
+  return d.toLocaleDateString(undefined, { weekday: 'short', day: 'numeric', month: 'short' })
+}
+</script>
+
+<template>
+  <div class="pr-panel">
+    <div class="pr-head">
+      <h2>Üben</h2>
+      <span v-if="counts" class="pr-counts">
+        {{ counts.due }} fällig · {{ counts.new }} neu<template v-if="counts.new_total > counts.new"> (von {{ counts.new_total }})</template>
+      </span>
+      <span v-if="offen" class="pr-rest">{{ offen }} übrig</span>
+    </div>
+
+    <p v-if="loadError" class="pr-msg">{{ loadError }}</p>
+    <p v-else-if="loading" class="pr-msg">Lade Stapel…</p>
+
+    <div v-else-if="current" class="pr-body">
+      <div class="pr-kontext">{{ current.block }} · {{ current.subblock }}</div>
+      <FlashcardWidget :card="current" @answer="onAnswer" />
+    </div>
+
+    <div v-else class="pr-done">
+      <p class="pr-done-title">Alles erledigt ✓</p>
+      <p v-if="erledigt" class="pr-msg">{{ erledigt }} Karten in dieser Runde.</p>
+      <p v-if="nextDueAt" class="pr-msg">Nächste Karten fällig: {{ naechsteFaelligkeit() }}</p>
+      <button
+        v-if="counts && counts.new_total > counts.new"
+        class="pr-mehr" @click="loadDeck"
+      >Weitere neue Karten üben</button>
+      <p v-if="counts && counts.gesperrt" class="pr-msg pr-faint">
+        {{ counts.gesperrt }} Karten schalten sich über Block-Prüfungen frei.
+      </p>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.pr-panel { padding: 16px 20px; max-width: 720px; margin: 0 auto; }
+.pr-head { display: flex; align-items: center; gap: 14px; margin-bottom: 12px; }
+.pr-head h2 { margin: 0; font-size: 1.1rem; }
+.pr-counts { color: var(--text-muted); font-weight: 600; font-variant-numeric: tabular-nums; }
+.pr-rest { margin-left: auto; color: var(--text-faint); font-size: 0.85rem; font-variant-numeric: tabular-nums; }
+.pr-msg { color: var(--text-muted); }
+.pr-faint { color: var(--text-faint); font-size: 0.85rem; }
+.pr-kontext { margin-bottom: 6px; color: var(--text-muted); font-size: 0.88rem; }
+.pr-done { text-align: center; padding: 2.5rem 0; }
+.pr-done-title { font-size: 1.15rem; font-weight: 700; margin-bottom: 0.6rem; }
+.pr-mehr {
+  margin-top: 0.6rem; padding: 7px 14px; border: 1px solid var(--border-strong);
+  border-radius: 8px; background: var(--bg); cursor: pointer; font-weight: 600;
+}
+.pr-mehr:hover { color: var(--accent-hover); }
+</style>

frontend/src/components/TopicDetail.vue

@@ -1,84 +1,207 @@
 <script setup>
-import { computed, ref, watch, nextTick, onMounted, onUnmounted } from 'vue'
-import { fetchGuideContent, chatGuide, fetchProgress, setProgress } from '../api.js'
+import { computed, reactive, ref, watch, nextTick, onMounted, onUnmounted } from 'vue'
+import { fetchGuideContent, chatGuide, fetchBlockLearnState } from '../api.js'
 import { renderMarkdown } from '../markdown.js'
+import { stufeFuer, schwelle, SUB_RANK, VIEW_KURZ, VIEW_FARBE, viewLevelFuer } from '../levels.js'
+import { useChat } from '../composables/useChat.js'
+import BlockPanel from './BlockPanel.vue'
+import BlockFocus from './BlockFocus.vue'
 
 const props = defineProps({
   previewGuide: { type: Object, default: null },
-  dark: { type: Boolean, default: false },
   provider: { type: String, default: 'claude' },
-  elementsOpen: { type: Boolean, default: false }, // Element-Sidebar offen → Chat nach links
+  themaAbgeschlossen: { type: Boolean, default: false },
+  ansichtModus: { type: String, default: 'compact' }, // compact | erklärend
+  stufeAnsicht: { type: [Number, String], default: 'auto' },  // 'auto' | 1=A · 2=F · 3=E · 4=V
 })
 
-const emit = defineEmits(['progressChanged', 'openElements'])
+const emit = defineEmits(['progressChanged', 'setAnsicht', 'openSidebar', 'fokusActive'])
 
-const isOnePager = computed(() => props.previewGuide?.format === 'OnePager')
-
-// Rotierende Kapitel-Akzentfarben (passend zum OnePager-Cheat-Sheet, ohne Rot)
+// Rotating chapter accent colors (no red)
 const CH_COLORS = ['#3b82f6', '#8b5cf6', '#14b8a6', '#f59e0b', '#22c55e', '#6366f1']
 
-// --- Inhalt laden ---
+// --- Load content ---
 const content = ref(null)
 const loadError = ref(null)
-const doneChapters = ref(new Set())
 const scrollEl = ref(null)
+const learnstate = ref({}) // exam state per block title — BEFORE the immediate watch (loadContent uses it)
+
+// --- Lazy render + markdown cache: parse only visible sections, each only once.
+// Fixes the freeze on open (160× marked/highlight.js) and re-parse on every update. ---
+const mdCache = new Map()       // `${mode}:${num}` → html
+const visible = reactive({})   // num → true (stays true once ever visible)
+let mdObserver = null
+
+// Auto: Ansichtsstufe des Blocks folgt dem Prüfungs-Score (Erreicht + 1); Override = global fest.
+function viewLevelFor(title) {
+  if (props.stufeAnsicht !== 'auto') return Number(props.stufeAnsicht)
+  const l = learnstate.value[title]
+  return viewLevelFuer(l?.good_answers || 0, l?.cap || 10)
+}
+
+function htmlFor(s) {
+  const lvl = viewLevelFor(s.title)
+  const key = `${props.ansichtModus}:${s.num}:${lvl}:${props.stufeAnsicht}`
+  let h = mdCache.get(key)
+  if (h !== undefined) return h
+  const compact = props.ansichtModus === 'compact'
+  if (!s.subs || !s.subs.length) {  // Legacy-Abschnitt ohne Marker → ungefiltert
+    h = renderMarkdown(compact ? (s.compact || s.md) : s.md)
+  } else {
+    const anchor = compact ? (s.anker_compact || '') : (s.anchor || '')
+    const parts = [renderMarkdown(anchor)]
+    for (const sub of s.subs) {
+      const rank = SUB_RANK[sub.level] || 1
+      if (rank > lvl) continue
+      const body = renderMarkdown(compact ? (sub.compact || sub.md) : (sub.md || sub.compact))
+      if (props.stufeAnsicht === 'auto' && lvl > 1 && rank === lvl) {
+        parts.push(`<div class="sub-neu" style="--neu-farbe:${VIEW_FARBE[rank]}"><span class="sub-neu-badge" title="Neu ab Stufe ${VIEW_KURZ[rank]}">${VIEW_KURZ[rank]}</span>${body}</div>`)
+      } else if (Number(props.stufeAnsicht) === 4) {
+        // Vollansicht: jede Stufe dezent kennzeichnen (Rand + Badge in Stufen-Farbe)
+        parts.push(`<div class="sub-stufe" style="--stufe-farbe:${VIEW_FARBE[rank]}"><span class="sub-stufe-badge" title="Stufe ${VIEW_KURZ[rank]}">${VIEW_KURZ[rank]}</span>${body}</div>`)
+      } else {
+        parts.push(body)
+      }
+    }
+    h = parts.join('')
+  }
+  mdCache.set(key, h)
+  return h
+}
+
+// Sections render only when (almost) in the viewport — observer on the scroll container.
+function setupLazy() {
+  mdObserver?.disconnect()
+  if (!scrollEl.value) return
+  mdObserver = new IntersectionObserver((entries) => {
+    for (const e of entries) {
+      if (!e.isIntersecting) continue
+      visible[Number(e.target.dataset.num)] = true
+      mdObserver.unobserve(e.target)
+    }
+  }, { root: scrollEl.value, rootMargin: '800px 0px' })
+  for (const el of scrollEl.value.querySelectorAll('.section-card')) mdObserver.observe(el)
+}
+
+watch(content, () => nextTick(setupLazy))
+onUnmounted(() => mdObserver?.disconnect())
 
 watch(() => props.previewGuide?.id, loadContent, { immediate: true })
+// Level view (E/M/S/F) changed → reload guide content with the matching depth filter.
+watch(() => props.stufeAnsicht, () => mdCache.clear())
 
 async function loadContent() {
   content.value = null
   loadError.value = null
-  doneChapters.value = new Set()
+  learnstate.value = {}
+  mdCache.clear()
+  for (const k in visible) delete visible[k]
   const g = props.previewGuide
   if (!g || g.status !== 'done') return
   try {
-    content.value = await fetchGuideContent(g.id)
+    content.value = await fetchGuideContent(g.id, 4)  // Stufen-Filterung passiert lokal (auto/Override)
   } catch (e) {
-    console.error('Fehler beim Laden des Guides:', e)
-    loadError.value = 'Inhalt nicht verfügbar — die Datei fehlt. Guide neu generieren (▶).'
+    console.error('Error loading guide:', e)
+    loadError.value = 'Content unavailable — the file is missing. Regenerate the guide (▶).'
     return
   }
   try {
-    const res = await fetchProgress(g.id)
-    doneChapters.value = new Set(res.chapters || [])
-  } catch { /* offline → leer */ }
-  nextTick(scrollToFirstOpen)
+    learnstate.value = (await fetchBlockLearnState(g.topic)).blocks || {}
+  } catch { /* offline → empty */ }
+  // On open, scroll to the first not-yet-mastered checkable block.
+  await nextTick()
+  const target = blocks.value.find((s) => isCheckable(s) && levelOf(s.title)?.key !== 'master')
+  if (target) scrollEl.value?.querySelector(`[data-num="${target.num}"]`)?.scrollIntoView({ block: 'start' })
 }
 
-// Zum ersten noch offenen Kapitel springen — aber nur, wenn schon etwas erledigt ist.
-function scrollToFirstOpen() {
-  if (!doneChapters.value.size || !content.value) return
-  const chapters = Array.from(scrollEl.value?.querySelectorAll('section.chapter') || [])
-  const firstOpen = chapters.find((el) => !el.classList.contains('ch-complete'))
-  if (firstOpen && firstOpen !== chapters[0]) firstOpen.scrollIntoView({ block: 'start' })
+// --- Block learning: exam state per block title (learnstate declared above) ---
+function levelOf(title) {
+  const l = learnstate.value[title]
+  return l ? stufeFuer(l.good_answers || 0, l.cap || 10) : null
+}
+function onBlockStatus(block, status) {
+  const prevKey = levelOf(block)?.key || null
+  learnstate.value = { ...learnstate.value, [block]: status }
+  const newKey = stufeFuer(status.good_answers || 0, status.cap || 10)?.key || null
+  if (newKey !== prevKey) emit('progressChanged') // level change → reload locks/stats
 }
 
-// --- Kapitel-Fortschritt ---
-async function toggleChapter(title) {
-  const newState = !doneChapters.value.has(title)
-  const optimistic = new Set(doneChapters.value)
-  if (newState) optimistic.add(title)
-  else optimistic.delete(title)
-  doneChapters.value = optimistic
-  try {
-    const res = await setProgress(props.previewGuide.id, title, newState)
-    doneChapters.value = new Set(res.chapters || [])
-    emit('progressChanged')
-  } catch {
-    const rollback = new Set(doneChapters.value)
-    if (newState) rollback.delete(title)
-    else rollback.add(title)
-    doneChapters.value = rollback
+// Replace the section in content after check/fix/rewrite + clear the markdown cache.
+function onSectionUpdated({ title, compact, md }) {
+  if (!content.value) return
+  for (const ch of content.value.chapters) {
+    for (const s of ch.sections) {
+      if (s.title !== title) continue
+      s.md = md
+      s.compact = compact
+      for (const k of [...mdCache.keys()]) if (k.endsWith(`:${s.num}`)) mdCache.delete(k)
+    }
   }
 }
 
-// --- Chat ---
+// --- Fullscreen focus: one block large, guide left + exam right ---
+const focusIndex = ref(null)        // index in the flat block list; null = closed
+const focusTab = ref('exam')
+const blocks = computed(() =>
+  !content.value ? [] : content.value.chapters.flatMap((ch) => ch.sections),
+)
+const focusBlock = computed(() => (focusIndex.value === null ? null : blocks.value[focusIndex.value]))
+
+// Report focus state to App (for the sidebar above the overlay); a topic change closes the focus.
+watch(focusIndex, (v) => emit('fokusActive', v !== null))
+watch(() => props.previewGuide?.id, () => { focusIndex.value = null })
+
+function openFocus(block, tab) {
+  if (!isCheckable(block)) return // read-only sections (Rest/edge) don't open an exam focus
+  const i = blocks.value.findIndex((s) => s.title === block.title)
+  if (i === -1) return
+  focusIndex.value = i
+  focusTab.value = tab || 'exam'
+}
+// Only jump to checkable sections in focus (FullGuide has read-only sections in between).
+function focusPrev() {
+  for (let i = focusIndex.value - 1; i >= 0; i--) if (isCheckable(blocks.value[i])) { focusIndex.value = i; return }
+}
+function focusNext() {
+  for (let i = focusIndex.value + 1; i < blocks.value.length; i++) if (isCheckable(blocks.value[i])) { focusIndex.value = i; return }
+}
+
+// Experience bar: cumulative level state over all blocks (gold ⊆ purple ⊆ blue ⊆ green).
+const progress = computed(() => {
+  const z = { total: blocks.value.length, beginner: 0, advanced: 0, expert: 0, master: 0 }
+  for (const s of blocks.value) {
+    const l = learnstate.value[s.title]
+    if (!l) continue
+    const sc = l.good_answers || 0, cp = l.cap || 10
+    if (sc >= schwelle(0.2, cp)) z.beginner++
+    if (sc >= schwelle(0.4, cp)) z.advanced++
+    if (sc >= schwelle(0.6, cp)) z.expert++
+    if (sc >= schwelle(1.0, cp)) z.master++
+  }
+  return z
+})
+
+// cap per block = 4×relevant subblocks (provided by the backend in learnstate[title].cap).
+function capOf(title) {
+  return learnstate.value[title]?.cap || 10
+}
+
+// Section checkable? Rest never. Otherwise checkable, unless the field is explicitly false (FullGuide edge).
+// Missing field (old guides without `checkable`) → checkable, so existing guides keep working.
+function isCheckable(s) {
+  return props.previewGuide?.format !== 'Rest' && s.checkable !== false
+}
+
+// --- Chat (mechanics in useChat; context extraction stays here) ---
+const chat = useChat((msgs) => {
+  const { section, outline } = extractContext()
+  return chatGuide(props.previewGuide.id, {
+    section, outline, messages: msgs, provider: props.provider,
+  })
+})
+const { messages, input, loading, messagesEl, inputEl, onScroll, send } = chat
+const autoGrow = () => chat.autoGrow()
 const chatOpen = ref(false)
-const messages = ref([])
-const input = ref('')
-const loading = ref(false)
-const messagesEl = ref(null)
-const inputEl = ref(null)
 const panelEl = ref(null)
 
 function openChat() {
@@ -88,8 +211,7 @@ function openChat() {
 
 function closeChat() {
   chatOpen.value = false
-  messages.value = []
-  input.value = ''
+  chat.reset()
 }
 
 function onDocMouseDown(e) {
@@ -98,7 +220,7 @@ function onDocMouseDown(e) {
   closeChat()
 }
 
-// Enter öffnet den Chat (wenn zu, nicht in Eingabefeld); ESC schließt ihn
+// Enter opens the chat (when closed, not in an input field); ESC closes it
 function onDocKeyDown(e) {
   if (e.key === 'Escape' && chatOpen.value) {
     e.preventDefault()
@@ -128,7 +250,7 @@ function extractContext() {
     .join('\n')
     .slice(0, 7000)
 
-  // Aktuelle Section = letzte Karte, deren Oberkante oben im Viewport oder darüber liegt
+  // Current section = last card whose top edge is at or above the top of the viewport
   let section = ''
   const cards = Array.from(scrollEl.value?.querySelectorAll('.section-card') || [])
   let current = null
@@ -141,58 +263,27 @@ function extractContext() {
   return { section, outline }
 }
 
-async function scrollToBottom() {
-  await nextTick()
-  if (messagesEl.value) messagesEl.value.scrollTop = messagesEl.value.scrollHeight
-}
-
-function autoGrow() {
-  const el = inputEl.value
-  if (!el) return
-  el.style.height = 'auto'
-  el.style.height = Math.min(el.scrollHeight, 140) + 'px'
-}
-
-async function send() {
-  const text = input.value.trim()
-  if (!text || loading.value || !props.previewGuide) return
-  messages.value.push({ role: 'user', content: text })
-  input.value = ''
-  nextTick(autoGrow)
-  loading.value = true
-  scrollToBottom()
-  try {
-    const { section, outline } = extractContext()
-    const res = await chatGuide(props.previewGuide.id, {
-      section,
-      outline,
-      messages: messages.value,
-      provider: props.provider,
-    })
-    messages.value.push({ role: 'assistant', content: res.reply || '…' })
-  } catch {
-    messages.value.push({ role: 'assistant', content: 'Fehler bei der Anfrage.' })
-  } finally {
-    loading.value = false
-    scrollToBottom()
-    nextTick(() => inputEl.value?.focus())
-  }
-}
 </script>
 
 <template>
   <div class="detail">
     <div v-if="previewGuide && content" ref="scrollEl" class="guide-scroll">
-      <div class="guide-content" :class="{ onepager: isOnePager }">
+      <div class="guide-content">
         <header class="guide-head">
           <h1>{{ previewGuide.topic }}</h1>
           <span class="guide-format">{{ previewGuide.format }}</span>
+          <span v-if="themaAbgeschlossen" class="thema-done" title="All blocks mastered">✓ Topic completed</span>
+          <span class="gh-spacer"></span>
+          <div class="ansicht-toggle" title="Toggle verbosity">
+            <button :class="{ active: ansichtModus === 'compact' }" @click="$emit('setAnsicht', 'compact')">Compact</button>
+            <button :class="{ active: ansichtModus === 'erklärend' }" @click="$emit('setAnsicht', 'erklärend')">Explanatory</button>
+          </div>
         </header>
+
         <section
           v-for="(ch, ci) in content.chapters"
           :key="ch.title"
           class="chapter"
-          :class="{ 'ch-complete': doneChapters.has(ch.title) }"
           :style="{ '--ch-accent': CH_COLORS[ci % CH_COLORS.length] }"
         >
           <h2 class="chapter-title"><span class="ch-num">{{ ci + 1 }}</span>{{ ch.title }}</h2>
@@ -200,57 +291,93 @@ async function send() {
             <article
               v-for="s in ch.sections"
               :key="s.num"
-              :class="['section-card', isOnePager && s.key ? 'op-card op-' + s.key : '']"
-              :style="isOnePager && s.key ? { gridArea: s.key } : null"
+              :data-num="s.num"
+              class="section-card"
+              :style="levelOf(s.title) ? { borderLeftColor: levelOf(s.title).farbe } : {}"
             >
-              <h3>{{ s.title }}</h3>
-              <div class="section-body markdown" v-html="renderMarkdown(s.md)"></div>
+              <h3 :class="{ 'block-klick': isCheckable(s) }" @click="isCheckable(s) && openFocus(s, 'exam')">
+                {{ s.title }}
+                <template v-if="isCheckable(s) && levelOf(s.title)">
+                  <span class="block-done" :style="{ color: levelOf(s.title).farbe, borderColor: levelOf(s.title).farbe }" :title="`${levelOf(s.title).label} (${capOf(s.title)})`">{{ levelOf(s.title).kurz }} {{ levelOf(s.title).label }}</span>
+                </template>
+              </h3>
+              <div v-if="visible[s.num]" class="section-body markdown" v-html="htmlFor(s)"></div>
+              <div v-else class="section-body skeleton"></div>
+              <BlockPanel
+                v-if="isCheckable(s)"
+                mode="trigger"
+                :block="s.title"
+                :status="learnstate[s.title]"
+                :cap="capOf(s.title)"
+                :topic="previewGuide.topic"
+                @open-fokus="(tab) => openFocus(s, tab)"
+              />
             </article>
           </div>
-          <button
-            v-if="!isOnePager"
-            class="ch-toggle"
-            :class="{ 'is-done': doneChapters.has(ch.title) }"
-            @click="toggleChapter(ch.title)"
-          >{{ doneChapters.has(ch.title) ? '✓ Erledigt – rückgängig' : 'Kapitel als erledigt markieren' }}</button>
         </section>
       </div>
     </div>
 
     <div v-else-if="previewGuide" class="empty-preview">
-      <p>{{ loadError || 'Lade Inhalt…' }}</p>
+      <p>{{ loadError || 'Loading content…' }}</p>
     </div>
 
     <div class="empty-preview" v-else>
-      <p>Guide-Format anklicken um zu generieren oder Vorschau zu öffnen.</p>
+      <p>Click a guide format to generate or open a preview.</p>
     </div>
 
-    <button v-if="previewGuide && !chatOpen" class="chat-fab" :class="{ shifted: elementsOpen }" title="Fragen zum Guide" @click="openChat">💬</button>
-    <button v-if="previewGuide && !chatOpen && !elementsOpen" class="chat-fab elements-fab" title="Elemente öffnen" @click="emit('openElements')">🗂</button>
+    <BlockFocus
+      v-if="focusBlock"
+      :block="focusBlock"
+      :topic="previewGuide.topic"
+      :guide-id="previewGuide.id"
+      :provider="provider"
+      :fortschritt="progress"
+      :status="learnstate[focusBlock.title]"
+      :cap="capOf(focusBlock.title)"
+      :tab="focusTab"
+      :ansicht="ansichtModus"
+      :has-prev="focusIndex > 0"
+      :has-next="focusIndex < blocks.length - 1"
+      @prev="focusPrev"
+      @next="focusNext"
+      @close="focusIndex = null"
+      @set-ansicht="$emit('setAnsicht', $event)"
+      @status-changed="(st) => onBlockStatus(st.block, st)"
+      @open-sidebar="$emit('openSidebar')"
+      @section-updated="onSectionUpdated"
+    />
 
-    <div v-if="previewGuide && chatOpen" ref="panelEl" class="chat-panel" :class="{ shifted: elementsOpen }">
+    <button v-if="previewGuide && !chatOpen && focusIndex === null" class="chat-fab" title="Questions about the guide" @click="openChat">💬</button>
+
+    <div v-if="previewGuide && chatOpen" ref="panelEl" class="chat-panel">
       <header class="chat-header">
-        <span>Fragen zum Guide</span>
-        <button class="chat-close" title="Chat beenden" @click="closeChat">×</button>
+        <span>Questions about the guide</span>
+        <button class="chat-close" title="Close chat" @click="closeChat">×</button>
       </header>
-      <div ref="messagesEl" class="chat-messages">
-        <p v-if="!messages.length" class="chat-hint">Stell eine Frage zum aktuellen Abschnitt.</p>
+      <div ref="messagesEl" class="chat-messages" @scroll="onScroll">
+        <p v-if="!messages.length" class="chat-hint">Ask a question about the current section.</p>
         <template v-for="(m, i) in messages" :key="i">
           <div v-if="m.role === 'assistant'" class="chat-msg assistant markdown" v-html="renderMarkdown(m.content)"></div>
           <div v-else class="chat-msg user">{{ m.content }}</div>
         </template>
-        <div v-if="loading" class="chat-msg assistant chat-typing">Denkt…</div>
+        <div v-if="loading" class="chat-msg assistant chat-typing">Thinking…</div>
       </div>
       <div class="chat-input">
         <textarea
           ref="inputEl"
           v-model="input"
           rows="3"
-          placeholder="Frage stellen…"
+          placeholder="Ask a question…"
           @input="autoGrow"
           @keydown.enter.exact.prevent="send"
         ></textarea>
-        <button :disabled="!input.trim() || loading" @click="send">➤</button>
+        <button
+          :disabled="!input.trim() && !loading"
+          :class="{ cancel: loading }"
+          :title="loading ? 'Cancel' : 'Send'"
+          @click="send"
+        >{{ loading ? '✕' : '➤' }}</button>
       </div>
     </div>
   </div>
@@ -259,8 +386,8 @@ async function send() {
 <style scoped>
 .detail {
   flex: 1;
-  /* Flex-Item darf schmaler werden als seine Code-Blöcke — sonst sprengt
-     deren Mindestbreite auf Mobile das Layout */
+  /* Flex item may shrink below its code blocks — otherwise their
+     min width breaks the layout on mobile */
   min-width: 0;
   height: 100dvh;
   position: relative;
@@ -269,7 +396,7 @@ async function send() {
 .guide-scroll {
   height: 100%;
   overflow-y: auto;
-  /* Kein horizontales Pannen der ganzen Seite — Code-Blöcke scrollen intern */
+  /* No horizontal panning of the whole page — code blocks scroll internally */
   overflow-x: hidden;
   background: var(--bg-preview);
 }
@@ -278,7 +405,7 @@ async function send() {
   max-width: 880px;
   margin: 0 auto;
   padding: 2rem 2.5rem 5rem;
-  /* Lese-Zoom nur für den Inhalt — Sidebar/Chat bleiben unverändert */
+  /* Reading zoom only for the content — sidebar/chat stay unchanged */
   zoom: 1;
 }
 
@@ -293,18 +420,57 @@ async function send() {
   align-items: baseline;
   gap: 0.75rem;
   margin-bottom: 1.5rem;
+  /* Sticky: the verbosity toggle stays reachable while scrolling. */
+  position: sticky;
+  top: 0;
+  z-index: 10;
+  background: var(--bg-preview);
+  padding: 0.6rem 0 0.5rem;
 
   h1 {
     font-size: 1.7rem;
   }
 }
 
+.gh-spacer { flex: 1; }
+
+.ansicht-toggle {
+  align-self: center;
+  display: inline-flex;
+  border: 1px solid var(--border);
+  border-radius: 8px;
+  overflow: hidden;
+}
+.ansicht-toggle button {
+  border: none;
+  background: var(--panel);
+  color: var(--text-muted);
+  font-size: 0.8rem;
+  font-weight: 600;
+  padding: 0.3rem 0.7rem;
+  cursor: pointer;
+}
+.ansicht-toggle button.active {
+  background: var(--accent);
+  color: var(--on-accent);
+}
+
 .guide-format {
   color: var(--text-faint);
   font-size: 0.9rem;
   font-weight: 600;
 }
 
+.thema-done {
+  font-size: 0.8rem;
+  font-weight: 600;
+  padding: 0.15rem 0.6rem;
+  border-radius: 999px;
+  background: color-mix(in srgb, #d4af37 20%, var(--panel));
+  border: 1px solid #d4af37;
+  color: #8a6d12;
+}
+
 .chapter {
   margin-bottom: 2.5rem;
 }
@@ -333,10 +499,6 @@ async function send() {
   font-weight: 700;
 }
 
-.chapter.ch-complete .sections {
-  opacity: 0.4;
-}
-
 .section-card {
   background: var(--panel);
   border: 1px solid var(--border);
@@ -345,8 +507,53 @@ async function send() {
   margin-bottom: 0.75rem;
 }
 
-/* Guides: Karten tragen die Kapitel-Akzentfarbe (OnePager hat eigene op-card-Farben) */
-.guide-content:not(.onepager) .section-card {
+.block-done {
+  float: right;
+  margin-left: 0.5rem;
+  padding: 0.12rem 0.6rem;
+  font-size: 0.68em;
+  font-weight: 600;
+  line-height: 1.5;
+  border-radius: 999px;
+  background: var(--success-soft);
+  border: 1px solid var(--success-border);
+  color: var(--success);
+  white-space: nowrap;
+}
+
+/* Completed blocks: card visibly flips to green */
+.guide-content .section-card.completed {
+  border-color: var(--success-border);
+  border-top: 3px solid var(--success);
+  background: color-mix(in srgb, var(--success) 5%, var(--panel));
+}
+
+/* Understood blocks (10/10): purple */
+.block-done.understood {
+  background: color-mix(in srgb, #8b5cf6 16%, var(--panel));
+  border-color: #8b5cf6;
+  color: #6d28d9;
+}
+.guide-content .section-card.understood {
+  border-color: #8b5cf6;
+  border-top: 3px solid #8b5cf6;
+  background: color-mix(in srgb, #8b5cf6 7%, var(--panel));
+}
+
+/* Mastered blocks (master path 25/25): gold */
+.block-done.mastered {
+  background: color-mix(in srgb, #d4af37 20%, var(--panel));
+  border-color: #d4af37;
+  color: #8a6d12;
+}
+.guide-content .section-card.mastered {
+  border-color: #d4af37;
+  border-top: 3px solid #d4af37;
+  background: color-mix(in srgb, #d4af37 8%, var(--panel));
+}
+
+/* Guides: cards carry the chapter accent color */
+.guide-content .section-card {
   border-top: 3px solid color-mix(in srgb, var(--ch-accent, var(--accent)) 65%, transparent);
   background: color-mix(in srgb, var(--ch-accent, var(--accent)) 3%, var(--panel));
 }
@@ -359,136 +566,13 @@ async function send() {
   }
 }
 
-/* OnePager: festes 3×3-Raster über volle Breite und Höhe.
-   Kein Lese-Zoom (bricht 100%-Höhen) — stattdessen sind die Schriften unten 1.2× skaliert. */
-.guide-content.onepager {
-  max-width: none;
-  height: 100%;
-  zoom: 1;
-  padding: 0.9rem 1rem;
-  display: flex;
-  flex-direction: column;
-}
+/* Title click opens the full view. */
+.section-card h3.block-klick { cursor: pointer; width: fit-content; }
+.section-card h3.block-klick:hover { color: var(--accent); }
 
-.guide-content.onepager .guide-head,
-.guide-content.onepager .chapter-title {
-  display: none; /* Thema steht in der Info-Karte — Platz fürs Raster */
-}
-
-.guide-content.onepager .chapter {
-  flex: 1;
-  min-height: 0;
-  margin-bottom: 0;
-}
-
-.guide-content.onepager .sections {
-  height: 100%;
-  display: grid;
-  grid-template-columns: repeat(3, 1fr);
-  grid-template-rows: repeat(3, 1fr);
-  grid-template-areas:
-    "info beispiel voraussetzungen"
-    "eigenschaften beispiel modern"
-    "eigenschaften zusammenhaenge veraltet";
-  gap: 0.6rem;
-}
-
-.guide-content.onepager .section-card {
-  margin-bottom: 0;
-  padding: 0.7rem 0.9rem;
-  min-height: 0;
-  overflow-y: auto;
-
-  h3 {
-    font-size: 1.06rem;
-    margin-bottom: 0.3rem;
-  }
-
-  .section-body {
-    font-size: 0.98rem;
-  }
-}
-
-/* Farbkodiertes Cheat-Sheet: feste Akzentfarbe + Icon pro Karte */
-.op-info { --op-accent: #3b82f6; }
-.op-eigenschaften { --op-accent: #8b5cf6; --op-icon: "☰"; }
-.op-beispiel { --op-accent: #64748b; --op-icon: "❯"; }
-.op-zusammenhaenge { --op-accent: #14b8a6; --op-icon: "⇄"; }
-.op-voraussetzungen { --op-accent: #f59e0b; --op-icon: "✓"; }
-.op-modern { --op-accent: #22c55e; --op-icon: "✦"; }
-.op-veraltet { --op-accent: #ef4444; --op-icon: "⚠"; }
-
-.guide-content.onepager .section-card.op-card {
-  border-top: 3px solid var(--op-accent);
-  background: color-mix(in srgb, var(--op-accent) 5%, var(--panel));
-
-  h3 {
-    color: var(--op-accent);
-    font-size: 0.95rem;
-    font-weight: 700;
-    text-transform: uppercase;
-    letter-spacing: 0.05em;
-  }
-
-  h3::before {
-    content: var(--op-icon, "");
-    margin-right: 7px;
-  }
-}
-
-/* Info-Karte: Thema als große Headline statt Uppercase-Label */
-.guide-content.onepager .op-card.op-info h3 {
-  font-size: 1.5rem;
-  text-transform: none;
-  letter-spacing: 0;
-  color: var(--text);
-}
-
-/* Mobil: eine Spalte in Quellreihenfolge (info → … → veraltet) */
-@media (max-width: 900px) {
-  .guide-content.onepager {
-    height: auto;
-  }
-
-  .guide-content.onepager .sections {
-    height: auto;
-    display: flex;
-    flex-direction: column;
-  }
-
-  .guide-content.onepager .section-card {
-    overflow-y: visible;
-  }
-}
-
-.ch-toggle {
-  display: block;
-  width: 100%;
-  margin-top: 0.5rem;
-  padding: 0.8rem 1rem;
-  border: 1.5px dashed var(--border-strong);
-  border-radius: 10px;
-  background: var(--panel-soft);
-  color: var(--text-muted);
-  font: 600 0.9rem/1.2 inherit;
-  font-family: inherit;
-  text-align: center;
-  cursor: pointer;
-  transition: all 0.12s;
-
-  &:hover {
-    border-color: var(--accent);
-    color: var(--accent);
-    background: transparent;
-  }
-
-  &.is-done {
-    border-style: solid;
-    border-color: var(--success-border);
-    background: var(--success-soft);
-    color: var(--success);
-  }
-}
+/* Placeholder for not-yet-rendered sections (lazy render). Stable height,
+   so the IntersectionObserver detects the following cards in a staggered way. */
+.section-body.skeleton { min-height: 160px; }
 
 .empty-preview {
   display: flex;
@@ -498,59 +582,16 @@ async function send() {
   color: var(--text-muted);
 }
 
-/* --- Markdown (Sections + Chat) --- */
-.markdown :deep(p) {
-  margin: 0 0 0.5em;
-}
-
-.markdown :deep(p:last-child) {
-  margin-bottom: 0;
-}
-
-.markdown :deep(ul),
-.markdown :deep(ol) {
-  margin: 0.3em 0;
-  padding-left: 1.2em;
-}
-
-.markdown :deep(li) {
-  margin: 0.15em 0;
-}
-
-.markdown :deep(code) {
-  background: var(--border);
-  padding: 1px 4px;
-  border-radius: 4px;
-  font-family: "SF Mono", Consolas, monospace;
-  font-size: 0.85em;
-  /* Lange Bezeichner (Namespaces, Pfade) dürfen umbrechen statt zu überlaufen */
-  overflow-wrap: anywhere;
-}
+/* --- Markdown: base global (assets/markdown.css), here only reading-view overrides --- */
 
+/* Wide reading view: code scrolls horizontally instead of wrapping */
 .markdown :deep(pre) {
-  background: var(--code-bg, #1e2330);
-  color: var(--code-fg, #e6e8ee);
-  padding: 10px 12px;
-  border-radius: 8px;
+  white-space: pre;
+  overflow-wrap: normal;
   overflow-x: auto;
-  margin: 0.5em 0;
 }
 
-.markdown :deep(pre code) {
-  background: none;
-  padding: 0;
-  color: inherit;
-  font-size: 0.85em;
-}
-
-.markdown :deep(h1),
-.markdown :deep(h2),
-.markdown :deep(h3) {
-  font-size: 0.95em;
-  margin: 0.6em 0 0.3em;
-}
-
-/* „Beispiel"-Überschriften in Karten als dezentes Uppercase-Label */
+/* "Example" headings in cards as a subtle uppercase label */
 .section-card .markdown :deep(h3) {
   font-size: 0.74em;
   text-transform: uppercase;
@@ -559,23 +600,8 @@ async function send() {
   margin: 0.9em 0 0.35em;
 }
 
-.markdown :deep(a) {
-  color: var(--accent-hover);
-}
-
-.markdown :deep(table) {
-  border-collapse: collapse;
-  font-size: 0.95em;
-}
-
-.markdown :deep(th),
-.markdown :deep(td) {
-  border: 1px solid var(--border-strong);
-  padding: 2px 6px;
-}
-
-/* Lesbarkeit: ~17px Fließtext, Zeilenhöhe 1.6, Textspalte max. ~70 Zeichen —
-   Code-Blöcke dürfen die volle Kartenbreite nutzen */
+/* Readability: ~17px body text, line height 1.6, text column max ~70 chars —
+   code blocks may use the full card width */
 .section-body {
   font-size: 1.0625rem;
   line-height: 1.6;
@@ -587,12 +613,6 @@ async function send() {
   max-width: 70ch;
 }
 
-.onepager .section-card .markdown :deep(p),
-.onepager .section-card .markdown :deep(ul),
-.onepager .section-card .markdown :deep(ol) {
-  max-width: none; /* OnePager-Zellen sind selbst schmal genug */
-}
-
 /* --- Chat --- */
 .chat-fab {
   position: fixed;
@@ -614,19 +634,6 @@ async function send() {
   background: var(--accent-hover);
 }
 
-.elements-fab {
-  right: 5.25rem;
-}
-
-/* Element-Sidebar (320px) offen → Chat links daneben anzeigen */
-.chat-fab.shifted {
-  right: calc(1.5rem + 320px);
-}
-
-.chat-panel.shifted {
-  right: calc(1.5rem + 320px);
-}
-
 .chat-panel {
   position: fixed;
   right: 1.5rem;
@@ -756,4 +763,10 @@ async function send() {
   opacity: 0.4;
   cursor: not-allowed;
 }
+
+.chat-input button.cancel {
+  background: var(--danger);
+}
+
+/* .sub-neu/.sub-stufe: global in assets/markdown.css — scoped greift nicht auf v-html-Inhalt. */
 </style>

frontend/src/composables/useChat.js

@@ -0,0 +1,89 @@
+import { ref, nextTick } from 'vue'
+
+// (Almost) at the bottom edge? Threshold absorbs sub-pixels and small gaps.
+export function istUnten(el, threshold = 60) {
+  return el.scrollHeight - el.scrollTop - el.clientHeight < threshold
+}
+
+// Shared chat mechanics: send, cancel (run counter), scroll, focus.
+// performRequest(messages) → Promise<{ reply, … }>; send() returns the response
+// so the caller can evaluate extras (e.g. changes).
+export function useChat(performRequest) {
+  const messages = ref([])
+  const input = ref('')
+  const loading = ref(false)
+  const messagesEl = ref(null) // template ref: messages container
+  const inputEl = ref(null)    // template ref: textarea
+  const stick = ref(true)      // "pinned" to the bottom — only then auto-scroll
+  let run = 0 // identify the running request; cancel ignores its result
+
+  // @scroll handler: pins only when the user is (almost) at the bottom.
+  function onScroll() {
+    if (messagesEl.value) stick.value = istUnten(messagesEl.value)
+  }
+
+  async function scrollToBottom() {
+    await nextTick()
+    if (messagesEl.value && stick.value) messagesEl.value.scrollTop = messagesEl.value.scrollHeight
+  }
+
+  function autoGrow(max = 140) {
+    const el = inputEl.value
+    if (!el) return
+    el.style.height = 'auto'
+    el.style.height = Math.min(el.scrollHeight, max) + 'px'
+  }
+
+  function cancel() {
+    run++
+    loading.value = false
+    messages.value.push({ role: 'assistant', content: 'Cancelled.' })
+  }
+
+  function reset() {
+    run++
+    loading.value = false
+    messages.value = []
+    input.value = ''
+  }
+
+  async function send() {
+    if (loading.value) { // second click = cancel
+      cancel()
+      return null
+    }
+    const text = input.value.trim()
+    if (!text) return null
+    stick.value = true // own send = jump to end; scrolling up while waiting resets it to false
+    const current = ++run
+    messages.value.push({ role: 'user', content: text })
+    input.value = ''
+    nextTick(() => autoGrow())
+    loading.value = true
+    scrollToBottom()
+    try {
+      const res = await performRequest(messages.value)
+      if (current !== run) return null
+      // Exam returns `question` (+ separate `feedback`); other chats `reply`.
+      messages.value.push({
+        role: 'assistant',
+        content: res.question ?? res.reply ?? '…',
+        feedback: res.feedback ?? null,
+        rating: res.rating ?? null,
+      })
+      return res
+    } catch {
+      if (current !== run) return null
+      messages.value.push({ role: 'assistant', content: 'Request failed.' })
+      return null
+    } finally {
+      if (current === run) {
+        loading.value = false
+        scrollToBottom()
+        nextTick(() => inputEl.value?.focus())
+      }
+    }
+  }
+
+  return { messages, input, loading, messagesEl, inputEl, stick, onScroll, send, cancel, reset, scrollToBottom, autoGrow }
+}

frontend/src/composables/useConfirm.js

@@ -0,0 +1,32 @@
+import { ref, onUnmounted } from 'vue'
+
+// Inline confirmation instead of confirm(): first click arms ("Sure?"),
+// second click runs it. Browser dialogs can be suppressed (Firefox).
+export function useConfirm(timeoutMs = 3000) {
+  const pending = ref(null) // currently armed key
+  let timer = null
+
+  function armOrRun(key, action) {
+    clearTimeout(timer)
+    if (pending.value === key) {
+      pending.value = null
+      action()
+    } else {
+      pending.value = key
+      timer = setTimeout(() => { pending.value = null }, timeoutMs)
+    }
+  }
+
+  function isArmed(key) {
+    return pending.value === key
+  }
+
+  function reset() {
+    clearTimeout(timer)
+    pending.value = null
+  }
+
+  onUnmounted(() => clearTimeout(timer))
+
+  return { pending, isArmed, armOrRun, reset }
+}

frontend/src/composables/usePolling.js

@@ -0,0 +1,44 @@
+import { onUnmounted } from 'vue'
+
+// Polling with a visibility pause: tab hidden → stop; visible again →
+// immediate tick, then continue if isActive(). Stops itself as soon as
+// isActive() returns false after a tick.
+export function usePolling(tick, isActive, interval = 3000) {
+  let timer = null
+
+  function stop() {
+    if (timer) {
+      clearInterval(timer)
+      timer = null
+    }
+  }
+
+  function start() {
+    stop()
+    timer = setInterval(async () => {
+      await tick()
+      if (!isActive()) stop()
+    }, interval)
+  }
+
+  function running() {
+    return !!timer
+  }
+
+  async function onVisibility() {
+    if (document.hidden) {
+      stop()
+    } else {
+      await tick()
+      if (isActive()) start()
+    }
+  }
+
+  document.addEventListener('visibilitychange', onVisibility)
+  onUnmounted(() => {
+    stop()
+    document.removeEventListener('visibilitychange', onVisibility)
+  })
+
+  return { start, stop, running }
+}

frontend/src/levels.js

@@ -0,0 +1,45 @@
+// Learning levels per block — identical to the backend (learning.py LEVELS).
+// Floor in % of cap_final (cap_final = all subblocks × 25).
+// green=Beginner 20% · blue=Advanced 40% · purple=Expert 60% · gold=Master 100%.
+export const LEVELS = [
+  { key: 'beginner', label: 'Beginner', kurz: '✓', floor: 0.2, farbe: 'var(--level-beginner)' },
+  { key: 'advanced', label: 'Advanced', kurz: '✓✓', floor: 0.4, farbe: 'var(--level-advanced)' },
+  { key: 'expert', label: 'Expert', kurz: '✓✓✓', floor: 0.6, farbe: 'var(--level-expert)' },
+  { key: 'master', label: 'Master', kurz: '★', floor: 1.0, farbe: 'var(--level-master)' },
+]
+
+export function schwelle(floor, cap) {
+  return Math.round(floor * cap)
+}
+
+// Highest reached level (object) or null (below Beginner, <20%).
+export function stufeFuer(score, cap) {
+  let s = null
+  for (const st of LEVELS) if (score >= schwelle(st.floor, cap)) s = st
+  return s
+}
+
+// Error-penalty display by progress (against cap_aktuell): ≤25%→−5 · ≤50%→−10 · ≤75%→−15 · >75%→−20.
+export function malusRegel(score, cap) {
+  const pct = cap ? score / cap : 0
+  if (pct <= 0.25) return '−5'
+  if (pct <= 0.5) return '−10'
+  if (pct <= 0.75) return '−15'
+  return '−20'
+}
+
+// Sub-level tag (from the guide markers) → view level 1..4 (A/F/E/V).
+export const SUB_RANK = { beginner: 1, advanced: 2, expert: 3, peripheral: 4, einfach: 1, mittel: 2, schwer: 3 }
+export const VIEW_KURZ = { 1: 'A', 2: 'F', 3: 'E', 4: 'V' }
+export const VIEW_FARBE = {
+  1: 'var(--level-beginner)', 2: 'var(--level-advanced)',
+  3: 'var(--level-expert)', 4: 'var(--level-master)',
+}
+
+// Auto view level per block: reached learning level + 1 (nothing reached → A).
+// beginner → F unlocked, advanced → E, expert/master → V.
+export function viewLevelFuer(score, cap) {
+  const s = stufeFuer(score, cap)
+  if (!s) return 1
+  return Math.min(4, LEVELS.findIndex((l) => l.key === s.key) + 2)
+}

frontend/src/main.js

@@ -1,4 +1,5 @@
 import { createApp } from 'vue'
 import App from './App.vue'
+import './assets/markdown.css'
 
 createApp(App).mount('#app')

frontend/src/markdown.js

@@ -2,6 +2,8 @@ import { marked } from 'marked'
 import { markedHighlight } from 'marked-highlight'
 import hljs from 'highlight.js'
 import 'highlight.js/styles/github-dark.css'
+import katex from 'katex'
+import 'katex/dist/katex.min.css'
 import DOMPurify from 'dompurify'
 
 marked.use(markedHighlight({
@@ -15,8 +17,42 @@ marked.use(markedHighlight({
 }))
 marked.setOptions({ breaks: true, gfm: true })
 
-// Rohes HTML im Markdown (z. B. <p>, <img> ohne Backticks aus Agenten-Output)
-// als Text anzeigen statt rendern — sonst verschluckt der Browser den Inhalt.
+// LaTeX math via KaTeX. Own marked extensions (instead of marked-katex-extension,
+// which lags behind marked v18). marked tokenizes code first → $…$ inside code
+// blocks is NOT treated as math. throwOnError:false renders broken TeX in red.
+function renderTex(tex, displayMode) {
+  return katex.renderToString(tex, { displayMode, throwOnError: false, output: 'html' })
+}
+
+const blockMath = {
+  name: 'blockMath',
+  level: 'block',
+  start(src) { const i = src.indexOf('$$'); return i < 0 ? undefined : i },
+  tokenizer(src) {
+    const m = /^\$\$([\s\S]+?)\$\$/.exec(src)
+    if (m) return { type: 'blockMath', raw: m[0], text: m[1].trim() }
+  },
+  renderer(token) { return renderTex(token.text, true) },
+}
+
+const inlineMath = {
+  name: 'inlineMath',
+  level: 'inline',
+  start(src) { const i = src.indexOf('$'); return i < 0 ? undefined : i },
+  tokenizer(src) {
+    // $…$: no $$, no space right after the opening $ or before the closing $
+    // (pandoc style) → reduces collisions with dollar signs in prose.
+    const m = /^\$(?![\s$])((?:\\\$|[^$])+?)\$/.exec(src)
+    if (!m || /\s$/.test(m[1])) return
+    return { type: 'inlineMath', raw: m[0], text: m[1].trim() }
+  },
+  renderer(token) { return renderTex(token.text, false) },
+}
+
+marked.use({ extensions: [blockMath, inlineMath] })
+
+// Raw HTML in markdown (e.g. <p>, <img> without backticks from agent output)
+// shown as text instead of rendered — otherwise the browser swallows the content.
 marked.use({
   renderer: {
     html(token) {
@@ -29,3 +65,19 @@ marked.use({
 export function renderMarkdown(text) {
   return DOMPurify.sanitize(marked.parse(text || ''))
 }
+
+// Inline variant (no <p> wrapping) for short texts like quiz options or
+// gap-text sentence fragments — renders $…$ math and markdown without a block break.
+export function renderMarkdownInline(text) {
+  return DOMPurify.sanitize(marked.parseInline(text || ''))
+}
+
+// Strip markdown to plain text (code fences + inline marks) — for previews/search.
+// Split markdown into top-level blocks: each block { raw (exact source), html }.
+// raw is lossless (tokens.map(raw).join('') === original) → block-precise replacement.
+export function renderBlocks(text) {
+  const tokens = marked.lexer(text || '')
+  return tokens
+    .filter((t) => t.type !== 'space' && (t.raw || '').trim())
+    .map((t) => ({ raw: t.raw, html: DOMPurify.sanitize(marked.parser([t])) }))
+}

frontend/src/pruefungCache.js

@@ -0,0 +1,31 @@
+// Shared exam state per block.
+// The durable refs live here as a module map: all BlockPanel instances of the same
+// block use the SAME refs. So the history survives remounting (block switch, focus
+// open/close) AND a late-arriving question is immediately reactive and visible.
+// Lost on page reload (module re-init) — deliberately no DB overhead.
+
+import { ref } from 'vue'
+
+const store = new Map() // key "topic::block" -> refs (history + questions pool)
+
+export function usePruefSlot(key) {
+  if (!store.has(key)) {
+    store.set(key, {
+      messages: ref([]),
+      phase: ref('idle'),
+      aktuelleFrage: ref(''),
+      letztesFeedback: ref(''),
+      pool: ref([]),        // pre-built question objects of the CURRENT form ({form, ...})
+      inflight: ref(0),     // running pool generations (coordinated across instances)
+      poolForm: ref(''),    // form the pool is filled for — clear on switch
+      musterQuelle: ref([]), // immutable full list of question patterns (empty = fallback)
+      musterPool: ref([]),  // working copy: drawn seed without replacement; empty → reset
+      musterGeladen: ref(false), // pattern sidecar already fetched?
+      quizAktuell: ref(null), // running quiz question {question, options, gewaehlt, done, ...}
+      lueckAktuell: ref(null), // running gap-text task {sentence, solution, ..., done}
+    })
+  }
+  return store.get(key)
+}
+
+export const clearPruef = (key) => store.delete(key)

frontend/vite.config.js

@@ -10,6 +10,12 @@ export default defineConfig({
     vue(),
     vueDevTools(),
   ],
+  // Default-cssTarget enthält alte Browser (firefox78) — esbuild optimiert dann die
+  // unprefixed backdrop-filter weg und lässt nur -webkit (in Firefox unsichtbar).
+  // Moderne Ziele + Safari erzwingen, dass BEIDE Varianten erhalten bleiben.
+  build: {
+    cssTarget: ['chrome90', 'firefox103', 'safari15', 'edge90'],
+  },
   resolve: {
     alias: {
       '@': fileURLToPath(new URL('./src', import.meta.url))

recherche.txt

@@ -0,0 +1,167 @@
+================================================================================
+RECHERCHE: Guide-Generierungskette erweitern
+Ziel: Lernen ohne Angst vor (a) Falschem, (b) fehlenden Infos,
+      (c) nervigem Aufbau, (d) Überforderung durch Struktur/Auswahl/Lesbarkeit.
+Bestehende Kette: Auswahl → Gliederung → Inhalte → Inhalts-Check → Writer → Lese-Check.
+================================================================================
+
+## META-ERKENNTNIS (gilt übergreifend)
+- "Mehr gleiche Agenten" sättigt früh und erzeugt Echo-Kammer: identische Modelle
+  teilen dieselben systematischen Fehler. Voting/Debatte schlagen Single-Agent nur
+  moderat und nicht zuverlässig besser als Self-Consistency.
+- Echte Hebel: HETEROGENITÄT (andere Modelle), EXTERNE ERDUNG (Quellen/Tools/Websuche),
+  ROLLEN-TRENNUNG, GATES zwischen Stufen.
+- Selbst-Korrektur OHNE externes Feedback verbessert Faktualität kaum, kann verschlechtern
+  (CommonSenseQA 75,8 → 38,1 nach 1 Runde). Nur MIT Quelle/Tool/Oracle einsetzen.
+- ~41,8 % der Multi-Agent-Fehler sind System-/Spezifikations-Design, nicht Modell-Fähigkeit
+  (MAST). → Architektur (Rollen, Gates, Stopp-Logik) ist der größte Hebel.
+
+
+================================================================================
+A) GEGEN FALSCHES (faktische Korrektheit)
+================================================================================
+1. RAG / Grounding gegen verlässliche Quellen — stärkster Hebel gegen erfundene Fakten.
+   Generierung auf abgerufene Quell-Passagen beschränken. (Inhalte/Prüfen)
+2. Zitat-Pflicht + Attribution: jeder Fakt braucht Inline-Quelle; gilt nur als belegt,
+   wenn aus dem Zitat ableitbar. Macht Fehler sichtbar/prüfbar. (Schreiben/Prüfen)
+3. Claim-Extraktion + Verifikation (FActScore-Stil): Text in atomare Fakten zerlegen,
+   jeden einzeln gegen Quelle prüfen. Fängt einzelne falsche Sätze. (Prüfen)
+4. SAFE (Search-Augmented Factuality Evaluator): Claims zerlegen → pro Claim Websuche →
+   per Reasoning prüfen. Übertrifft menschliche Annotatoren, ~20x billiger.
+   Ideal, da Websuche schon vorhanden. (Prüfen)
+5. Abstention bei Unsicherheit: unbelegte/inkonsistente Fakten weglassen oder markieren
+   statt raten. Tauscht Coverage gegen Korrektheit — für Lerninhalte oft richtig.
+6. Chain-of-Verification (CoVe): Entwurf → Verifikationsfragen → einzeln beantworten →
+   revidieren. Günstig (reines Prompting). (Prüfen, pro Baustein)
+7. Self-Consistency: mehrere Pfade samplen, Mehrheit wählen. Nur für Varianz-Reduktion,
+   NICHT für Wahrheit (systematische Fehler bleiben). Sweet Spot 10–20 Samples.
+8. Post-hoc Revision (RARR): fertigen Text nehmen, pro Claim Evidenz suchen, widersprechende
+   Claims editieren, Originaltext maximal erhalten. (zwischen Schreiben und Lesbarkeit)
+9. Stärkerer Verifier statt mehr gleicher Agenten: generieren günstig, verifizieren mit
+   stärkerem/anderem Modell. Lohnt bei schwierigen/seltenen Fakten. (Prüfen)
+10. Self-Refine/Reflexion NUR mit externem Feedback (Tool/Quelle). Intrinsisch verschlechtert.
+
+Quellen A:
+- SAFE / Long-form Factuality: https://openreview.net/pdf?id=4M9f8VMt2C
+- FActScore (Primer): https://aman.ai/primers/ai/factuality-in-LLMs/
+- Chain-of-Verification: https://arxiv.org/pdf/2309.11495
+- Grounded Attribution + Refuse: https://arxiv.org/pdf/2409.11242
+- Self-Correction braucht externes Feedback: https://arxiv.org/abs/2310.01798
+- When Can LLMs Self-Correct (TACL): https://direct.mit.edu/tacl/article/doi/10.1162/tacl_a_00713/125177/
+- RARR: https://aclanthology.org/2023.acl-long.910/
+- Weaver / Generation-Verification-Gap: https://arxiv.org/pdf/2506.18203
+- Abstention-Survey: https://direct.mit.edu/tacl/article/doi/10.1162/tacl_a_00754/131566/
+
+
+================================================================================
+B) GEGEN LÜCKEN (Vollständigkeit)
+================================================================================
+1. Backward Design (Stufe 0): zuerst Lernziele definieren, DANN Inhalt generieren.
+   3 Schichten: "familiar with" / "important to know" / "enduring understanding".
+2. Lernziele explizit als Anker-Liste (Bloom-Verben). Jeder Abschnitt wird genau einem
+   Lernziel zugeordnet. Ziel ohne Inhalt = Lücke; Inhalt ohne Ziel = Ballast.
+3. Curriculum-Mapping / Alignment-Matrix (Lernziel × Abschnitt × Assessment) als eigene
+   Stufe: prüft Abdeckung, Doppelungen, hängende Ziele gleichzeitig.
+4. "What's missing"-Critic-Agent: bekommt Thema + Guide + Referenzfakten, sucht NUR
+   fehlende korrekte Punkte, bessert minimal nach. Discrimination von Revision trennen.
+5. "Das Wichtige" verlässlich via Mehrquellen-Konsens (Triangulation): Standard-Curricula
+   + mehrere unabhängige Quellen (Schnittmenge = Kern) + LLM-Delphi (Konsens-Topics).
+
+Quellen B:
+- Backward Design: https://fctl.ucf.edu/teaching-resources/course-design/backward-design/
+- Understanding by Design: https://en.wikipedia.org/wiki/Understanding_by_Design
+- GPT-4 Learning Objectives: https://arxiv.org/pdf/2306.17459
+- Curriculum Mapping: https://pce.sandiego.edu/curriculum-mapping/
+- Critique-Guided Improvement: https://arxiv.org/pdf/2503.16024
+- Delphi-Konsens (PMC): https://pmc.ncbi.nlm.nih.gov/articles/PMC8178515/
+
+
+================================================================================
+C) GEGEN ÜBERFORDERUNG (Struktur, Reihenfolge, Lesbarkeit)
+================================================================================
+1. Prerequisite-/Concept-Dependency-Graph: Konzepte = Knoten, "X braucht Y" = Kante.
+   Topologische Sortierung → gültige Reihenfolge (Basics zuerst). LLM extrahiert Kanten,
+   Zyklus-Check. Knoten mit vielen ausgehenden Kanten = Kernkonzepte, früh.
+2. Knowledge-Space-Theorie (Doignon/Falmagne, ALEKS): erlaubte Wissenszustände statt fixer
+   Linie. Validiert Reihenfolge, schließt unmögliche Pfade aus.
+3. Bloom-Progression: Remember → Understand → Apply → Analyze → Evaluate → Create.
+   Jeden Abschnitt taggen, monotone Progression prüfen.
+4. Cognitive Load GLOBAL budgetieren (nicht nur pro Abschnitt): Working Memory ~4–7
+   Einheiten. Neue Konzepte/Abschnitt begrenzen, Spitzen glätten, schwer/leicht abwechseln.
+5. Chunking + einfach→komplex: Teilfertigkeiten zuerst, dann zusammensetzen. Lange
+   Abschnitte automatisch splitten (Max-Chunk-Regel).
+6. Scaffolding mit Fading: anfangs viele Worked Examples, Stütze schrittweise zurücknehmen.
+   Achtung Expertise-Reversal: was Novizen hilft, bremst Fortgeschrittene.
+7. Diátaxis-Struktur: Tutorial / How-to / Reference / Explanation NICHT mischen
+   (häufigste Ursache verwirrender Doku). Für Lern-Guide: Tutorial + Explanation trennen.
+8. Spiral-Curriculum + Spaced Retrieval: Kernideen wiederkehren lassen, aktives Abrufen.
++ Lesbarkeit (frühere Recherche): Ø-Satz ≤ 20 W, keiner > 40; ≤ ~4 neue Begriffe/Abschnitt;
+  eine Idee pro Absatz; Listen statt Aufzählungssätze.
+
+Quellen C:
+- Concept Graph (CMU): https://www.cs.cmu.edu/~hanxiaol/publications/yang-wsdm15.pdf
+- Prerequisite Relations (AAAI): https://ojs.aaai.org/index.php/AAAI/article/view/10550
+- Knowledge Spaces / ALEKS: https://www.aleks.com/about_aleks/Science_Behind_ALEKS.pdf
+- Cognitive Load Strategien: https://www.structural-learning.com/post/cognitive-load-theory-a-teachers-guide
+- Expertise Reversal: https://en.wikipedia.org/wiki/Expertise_reversal_effect
+- Diátaxis: https://diataxis.fr/start-here/
+- Spiral Curriculum: https://www.structural-learning.com/post/the-spiral-curriculum-a-teachers-guide
+
+
+================================================================================
+D) ARCHITEKTUR-METHODEN (Pipeline-Qualität)
+================================================================================
+1. Generator–Critic-Loop NUR mit externer Erdung (Self-Refine ~+20 % bei offenen Aufgaben;
+   intrinsisch ohne Signal verschlechtert). Für Faktenprüfung Tool-Erdung (CRITIC).
+2. Stopp-Kriterien: fast alle Gewinne in Runde 1–2. Stoppen bei Stabilität/Score-Delta<1/
+   Draft-Ähnlichkeit>0,90. Bestes Draft per Validierung wählen, nicht das letzte.
+3. Rollen-Spezialisierung statt Klone: Faktenprüfer ≠ Didaktiker ≠ Lektor ≠ Zielgruppen-
+   Anwalt. Erlaubt kleinere/billigere Modelle pro Teilschritt.
+4. Heterogenität ist der Wirkstoff von Debatte: Gewinn kommt aus VERSCHIEDENEN Modellen,
+   nicht aus dem Mechanismus. Identische Modelle ≈ Self-Consistency, nur teurer.
+5. LLM-as-Judge mit Rubrik, BINÄR (pass/fail) statt 1–5; Multi-Kriterien getrennt; vage
+   Begriffe definieren; niedrige Temperatur; gegen 1 Experten kalibrieren.
+6. Eval-Harness + Regression-Evals (CI-Gate): Golden-Set (25–50 Fälle reichen anfangs),
+   wächst mit jedem Produktionsfehler. PR/Release blockt unter Schwelle.
+7. Diminishing Returns: Voting Sweet Spot 10–20 Samples; Debatte-Plateau ~3 Runden;
+   bei sequentiellen Aufgaben degradiert jede Multi-Agent-Variante um 39–70 %.
+8. Fehler-Akkumulation: 95 %/Schritt × 10 = 59 %; 90 % → 35 %. Verifier-Gate ZWISCHEN
+   die Stufen; zentrale Koordination begrenzt Verstärkung (4,4x statt 17,2x).
+9. Pitfall Sycophancy/Konsens-Bias: Modelle stimmen zu (~42–58 %); Peer-Druck-Flip ~48 %.
+   Fix STRUKTURELL: Mehrheit klein halten (6→3 Agenten senkt Konformität 70 %→33 %),
+   isolierte Selbstkorrektur vor Konsens. Prompt-Nudges ("sei standhaft") wirken NICHT.
+10. Pitfall Self-Preference: Judge bevorzugt eigene Outputs (GPT-4 ~+10 %, Claude ~+25 %).
+    Fix: Judge ≠ Generator-Modell (Cross-Model-Judging), Positionen tauschen+mitteln.
+11. Human-in-the-Loop kalibrierend, NICHT als blindes Reward (OpenAI GPT-4o-Sycophancy-
+    Vorfall April 2025 durch Thumbs-up/down). Experten-Review-Gate behalten.
+12. MAST-Failure-Taxonomie als Architektur-Checkliste (System-Design / Inter-Agent /
+    Verification-Termination).
+
+Quellen D:
+- Self-Refine: https://arxiv.org/pdf/2303.17651
+- CRITIC: https://arxiv.org/abs/2305.11738
+- Multiagent Debate: https://arxiv.org/abs/2305.14325 ; Stop Overvaluing: https://arxiv.org/pdf/2502.08788
+- LLM-as-Judge (MT-Bench): https://arxiv.org/abs/2306.05685 ; G-Eval: https://aclanthology.org/2023.emnlp-main.153/
+- Eval-Prozess (Hamel): https://hamel.dev/blog/posts/llm-judge/
+- Google Scaling Agent Systems: https://research.google/blog/towards-a-science-of-scaling-agent-systems-when-and-why-agent-systems-work/
+- Sycophancy: https://arxiv.org/abs/2310.13548 ; Conformity: https://arxiv.org/abs/2505.21588
+- MAST: https://arxiv.org/abs/2503.13657
+- OpenAI Sycophancy-Postmortem: https://venturebeat.com/ai/openai-rolls-back-chatgpts-sycophancy-and-explains-what-went-wrong
+
+
+================================================================================
+EMPFOHLENE NÄCHSTE STUFEN FÜR UNSERE KETTE (priorisiert, größter Nutzen/Aufwand)
+================================================================================
+0. (Stufe ganz vorn) Lernziele definieren (Backward Design) + "das Wichtige" via
+   Mehrquellen-Konsens → ankert Auswahl UND Vollständigkeit.
+1. Reihenfolge: Prerequisite-Graph + topologische Sortierung in/nach der Gliederung
+   (Basics zuerst, keine Vorgriffe).
+2. Faktencheck-Gate (SAFE/CoVe) in der Inhalts-Prüfung — nutzt vorhandene Websuche;
+   Verifier = anderes/stärkeres Modell, BINÄRE Urteile.
+3. Abstention: unbelegte Fakten raus/markieren.
+4. Coverage-/"Was-fehlt"-Critic + Lernziel↔Inhalt-Mapping als Schluss-Gate (zurück bei Lücken).
+5. Cognitive-Load-Pass über den ganzen Guide (neue Begriffe/Abschnitt begrenzen, schwer/leicht mischen).
+6. Architektur-Hygiene: Gate zwischen jeder Stufe (Judge ≠ Generator), Loops nach 1–2 Runden
+   stoppen, Voting 10–20 Samples, kleine Mehrheiten (Konsens-Bias), Golden-Set-Regression-Evals.
+
+WARNUNG: NICHT auf "mehr gleiche Agenten" setzen. Heterogenität + externe Erdung + Gates.

templates/Format/Section.md

@@ -1,26 +1,80 @@
 SECTION-AUFBAU
 
-Jeder Baustein wird GENAU eine Section mit:
-1. Titel — der Baustein-Titel (kommt aus dem Marker, nicht in den Body schreiben)
-2. Beschreibung — was es ist und wozu: MAXIMAL 1–2 Sätze
-3. Beispiele — KURZ und SIMPEL: wenige Zeilen Code, das Minimalbeispiel, keine Realwelt-Komplexität. Höchstens 1 knapper Satz Einordnung dazu. Ein Beispiel pro relevanter Variante: simple Bausteine eines, variantenreiche mehrere. Geordnet vom Üblichen zum Speziellen. Weglassen, wenn ohne Mehrwert.
+Jeder Baustein ist ein kleiner, eigenständiger Lern-Guide: er stellt EIN Konzept vor, erklärt es von Grund auf und macht es nutzbar. Zielgruppe: ein Junior-Entwickler, der das Thema NEU lernt und KEIN Vorwissen mitbringt. Du holst ihn ab und bringst ihm die Sache bei. Eine Section ist kein Stichwort-Zettel zum Nachschlagen.
+
+Aufbau je Baustein — drei Beats, fließend ineinander, OHNE Zwischenüberschriften:
+1. Einordnung (PFLICHT, der Ankerpunkt) — welches Problem löst der Baustein, wozu braucht man ihn? Knüpfe an etwas Bekanntes/Alltägliches an, bevor das Neue kommt. Ohne diesen Anker steht ein Neuling im Leeren. Nie weglassen.
+2. Erklärung — was es ist UND wie/warum es funktioniert. Alltagssprache, von der Intuition zum Detail. JEDEN Fachbegriff beim ersten Auftreten in einem Halbsatz auflösen — auch Begriffe aus dem Section-Titel oder anderen Bausteinen NIE als bekannt voraussetzen. Eine Analogie oder ein Bild ist erlaubt und oft besser als eine Definition. „Wie"-Abläufe Schritt für Schritt zeigen (nicht nur das Ergebnis nennen). Kleine Beispiele/Mini-Snippets dürfen schon hier mitten im Text stehen, wo sie einen Punkt sofort greifbar machen.
+3. Beispiel(e) — das Konzept konkret gemacht (siehe BEISPIELFORMAT).
+
+LESBARKEIT — wichtiger als Kürze:
+- Kurze Sätze: eine Aussage pro Satz. Richtwert höchstens ~20 Wörter, nie über 25. Keine Schachtelsätze mit mehreren Einschüben (Gedankenstrich-Einschübe vermeiden).
+- Kurze Absätze: eine Idee pro Absatz. Lieber zwei kurze Absätze als ein dichter Block. Keine Textwand.
+- Aufzählungen (Schritte, Optionen, Anforderungen, mehrere gleichrangige Punkte) als Markdown-Liste mit `-`, NIE in einen langen Aufzählungssatz pressen.
+- Wenige neue Fachbegriffe pro Section. Jeden beim ersten Auftreten in Alltagssprache auflösen. Lieber eine Stufe einfacher erklären als mehr Fakten stapeln.
+- Im Zweifel ein Satz mehr und klar — statt verdichtet. Verständlichkeit schlägt Knappheit.
+
+LÄNGE — so lang wie nötig:
+- KEIN festes Wortlimit. Die Länge richtet sich nach der Schwierigkeit des Konzepts.
+- Verständnis-Test: Versteht ein NEULING das Konzept allein aus dieser Section, ohne anderswo nachzulesen? Wenn nein → einen Schritt mehr erklären (Warum + Wie), NICHT verdichten. Diese Section trägt die volle Tiefe selbst — es gibt keine zweite Ausbaustufe mehr, die nachliefert.
+- Weglassen: Füllsätze, Einleitungsfloskeln („In diesem Abschnitt…"), Wiederholungen, Fazit. Nicht jeden Randfall nennen — das Übliche erklären, seltene Varianten in die Beispiele.
+
+BEISPIELFORMAT — am Thema ausrichten, nicht pauschal an Code:
+- Code-/Tool-Thema (Sprache, Framework, CLI, Konfiguration): Codeblock mit Sprachangabe, wenige Zeilen, Minimalbeispiel.
+- Sprach-Thema (Vokabeln, Grammatik, Formulierungen): 1–3 Beispielsätze oder ein Mini-Dialog, fremdsprachiger Teil *kursiv*, deutsche Übersetzung in Klammern wo nötig.
+- Konzept-Thema (Psychologie, Kommunikation, Methoden, Theorie, Mathe): ein Mini-Szenario in 2–4 Sätzen (Situation → Anwendung → Wirkung), ein Schema oder eine durchgerechnete Formel mit kleinen Zahlen.
+Mischthemen: pro Beispiel das Format wählen, das den Punkt am direktesten zeigt.
+Ein Beispiel ist immer KONKRET (echter Code, echte Sätze, echte Situation) — nie die Beschreibung, was ein Beispiel zeigen würde.
+Mehrere Beispiele benennen ihre Variante: in Code als Kommentar in der Code-Syntax (z. B. `<!-- Einzelner Absatz -->`, `// Mit Default-Wert`), in Prosa als vorangestelltes fettes Label (z. B. **Höfliche Bitte:**). Bei nur einem Beispiel ist kein Label nötig.
 
 Jede Section ist ATOMAR: allein verständlich, ohne dass der Leser eine andere Section gelesen hat. Test: Ergibt der Text Sinn, wenn man NUR diese Section liest? Verweise auf andere Bausteine sind erlaubt, ihr Inhalt darf aber nie vorausgesetzt werden — benutzte Begriffe in einem Halbsatz auflösen.
 
-Umfang: kurz. Die Länge einer Section kommt aus der ZAHL der Beispiele (Varianten), nie aus langen Texten.
+Tonalität: klares, direktes Deutsch. Du erklärst, du referierst nicht. Praxisorientiert, ohne Füllsätze.
 
-Tonalität: klares Deutsch, direkt, praxisorientiert. Fachbegriffe beim ersten Auftreten kurz erklären. Keine Füllsätze, keine Einleitungsfloskeln.
+Markdown im Section-Body: erklärende Absätze in normalem Text, Aufzählungen als Markdown-Liste (`-`), `inline-code` für Bezeichner, Codeblöcke mit Sprachangabe NUR für Code-Beispiele — Beispielsätze, Dialoge und Szenarien als normaler Text, NIE in einen Codeblock zwingen. **fett** sparsam für Kernaussagen und Beispiel-Labels. Keine eigenen Überschriften außer `### Beispiel` bzw. `### Beispiele` vor den Beispielen.
 
-Markdown im Section-Body: normale Absätze, `inline-code` für Bezeichner, Codeblöcke mit Sprachangabe, **fett** sparsam für Kernaussagen. Keine eigenen Überschriften außer `### Beispiel` bzw. `### Beispiele` vor den Beispielen.
+Mathematik IMMER als LaTeX schreiben: inline zwischen `$…$` (z. B. `$\Sigma^*$`, `$L \subseteq U$`, `$k = 3$`), abgesetzte Formeln zwischen `$$…$$`. KEINE Unicode-Sonderzeichen als Mathe-Ersatz (nicht `x₁`, `¬`, `∨`, `≤` — stattdessen `$x_1$`, `$\neg$`, `$\lor$`, `$\le$`) und keine nackten Formeln ohne `$`. Außerhalb von Mathe normaler Text.
 
-Beispiel einer fertigen Section (nur der Body):
+Formeln brechen NICHT automatisch um — lange Mathe läuft sonst über den Rand. Darum:
+- **Inline `$…$` nur für KURZE Symbole/Terme** — einzelne Variablen, Mengen, kurze Relationen (`$\Sigma^*$`, `$k = 3$`, `$x \notin L$`). NIE einen ganzen Ausdruck mit mehreren Teilen oder Sätzen inline (auch nicht in einem Listenpunkt).
+- **Lange oder mehrteilige Formeln IMMER abgesetzt zwischen `$$…$$` auf eigener Zeile** — besonders Mengen-/Set-Builder-Definitionen (`\{ … \mid … \}`). Nicht inline, nicht in eine Aufzählung quetschen.
+- **KEINE Prosa in `\text{…}`.** Bedingungen und Erklärungen als normalen deutschen Text NEBEN oder UNTER die Formel, nicht in sie hinein. Also nicht `$$L = \text{CLIQUE} = \{ u\#v \mid u \text{ kodiert die Adjazenzmatrix …}\}$$`, sondern die Formel knapp (`$$L = \{\, u\#v \mid \dots \,\}$$`) und die Bedeutung von `u`, `v` im Fließtext erklären.
+- Lange Definitionen oder Gleichungsketten mit `$$\begin{aligned} … \\ … \end{aligned}$$` über mehrere Zeilen umbrechen.
 
-Arrays speichern mehrere Werte unter einem Namen. PHP unterscheidet indizierte Arrays (`[0 => 'a']`) und assoziative Arrays (`['key' => 'wert']`) — intern sind beide geordnete Hashmaps.
+Beispiel einer fertigen Section (Code-Thema, nur der Body):
+
+Arrays lösen ein simples Problem: Du willst viele Werte unter einem Namen halten, statt für jeden eine eigene Variable. In PHP gibt es zwei Sorten. Indizierte Arrays nummerieren die Werte durch (`[0 => 'a']`). Assoziative Arrays geben jedem Wert einen eigenen Schlüssel (`['key' => 'wert']`) — praktisch, wenn die Position egal ist, der Name aber zählt. Intern sind beide dasselbe: geordnete Hashmaps.
 
 ### Beispiel
 ```php
 $preise = ['apfel' => 1.20, 'birne' => 1.50];
-$preise['kirsche'] = 3.90;   // ergänzen
-echo $preise['apfel'];       // 1.2
+$preise['kirsche'] = 3.90;   // neuen Schlüssel ergänzen
+echo $preise['apfel'];       // 1.2 — Zugriff über den Namen
 ```
-Assoziative Arrays sind der Arbeitsalltag: Datenbankzeilen, Konfiguration, JSON.
+So sieht der Alltag aus: Datenbankzeilen, Konfiguration, JSON landen fast immer in assoziativen Arrays.
+
+Beispiel einer fertigen Section (Konzept-Thema, nur der Body):
+
+Im Streit reden zwei oft aneinander vorbei, weil keiner sicher ist, ob er den anderen richtig verstanden hat. Paraphrasieren setzt genau hier an: Du wiederholst die Aussage des Gegenübers in eigenen Worten und fragst nach, ob das so stimmt. Das prüft dein Verständnis und nimmt Tempo aus dem Konflikt — der andere fühlt sich gehört, statt sich verteidigen zu müssen. Wichtig: Du bestätigst nicht den Vorwurf, du spiegelst nur die Botschaft dahinter.
+
+### Beispiel
+A: „Nie hältst du dich an Absprachen!"
+B: „Du bist sauer, weil ich den Termin gestern verschoben habe — richtig?"
+B übernimmt nicht das Wort „nie", sondern benennt das konkrete Anliegen. Das öffnet das Gespräch, statt es zu eskalieren.
+
+Beispiel einer fertigen Section mit Aufzählung (Liste statt Aufzählungssatz):
+
+Bevor du Shopware installierst, muss dein Server die Software tragen können. Sonst bricht die Installation ab. Shopware 6 braucht ein paar feste Bausteine:
+
+- **PHP 8.2, 8.3 oder 8.4** — die Sprache, in der Shopware läuft.
+- **MySQL ab 8.0.17** oder **MariaDB ab 10.11** — die Datenbank für deine Artikel und Bestellungen.
+- **Composer ab 2.2** — lädt die PHP-Bibliotheken, die Shopware mitbringt.
+- **Node.js 20+** — baut die JavaScript- und CSS-Dateien zusammen.
+
+### Beispiel
+```bash
+php -v          # PHP-Version prüfen
+composer -V     # Composer-Version
+node -v         # Node-Version
+```
+Stimmt eine Version nicht, aktualisierst du sie zuerst. Eine zu alte Version ist die häufigste Ursache für eine fehlgeschlagene Installation.

templates/Prompt/Artefakt-Check.md

@@ -0,0 +1,21 @@
+You are the quality checker for the learning artefacts of ONE block of the topic "{topic}". Another agent produced question patterns and worked examples. Check both.
+
+GROUND TRUTH — the supported facts (measure only against these):
+{facts}
+
+QUESTION PATTERNS (rows: (subblock) question):
+{table}
+{fehlend}
+WORKED EXAMPLES (numbered; PROBLEM / STEPS / RESULT):
+{examples}
+
+TASKS:
+1. **pattern** — return the CLEANED-UP final version of ALL patterns: each question EXACTLY ONE question mark, one thing, 1–2 sentences, neutral, hits the subblock's core, answerable from the facts without invented assumptions. Keep good ones unchanged; rephrase violations. Exactly one pattern per subblock; carry `block`/`subblock` over unchanged. Questions in GERMAN.
+2. **pattern_ergaenzt** — for each subblock listed above as MISSING a question: create ONE pattern (same rules). Empty list if none are missing.
+3. **examples_probleme** — object to an example ONLY if clearly faulty: calculation error, wrong inference, contradicts/invents beyond the facts, or would imprint a wrong path. Recompute yourself; conservative — when in doubt, keep. Give 1-based `index`.
+
+Reply with ONLY the JSON — no code fences, no other text. Format:
+{{"pattern": [{{"block": "…", "subblock": "…", "question": "…"}}],
+ "pattern_ergaenzt": [{{"block": "…", "subblock": "…", "question": "…"}}],
+ "examples_probleme": [{{"index": 2}}]}}
+{extra}