Training-Harness (ACO, Multi-Fidelity), Prüfstand-Benchmark, Agenten-README

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

.env.example

@@ -5,3 +5,10 @@ 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=

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 \

Makefile

@@ -1,4 +1,4 @@
-.PHONY: install dev prod stop logs remove auth sync sync-projects sync-all projects 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
 
 COMPOSE = docker compose
 
@@ -12,11 +12,12 @@ auth:
 	@echo "Verzeichnisse angelegt und auf uid 1000 chowned."
 
 install:
-	pip install --break-system-packages fastapi uvicorn[standard] aiosqlite uv playwright transformers
+	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
@@ -61,13 +62,18 @@ ollama:
 	ollama pull qwen3.5:9b
 	@echo "Ollama bereit — Provider 'Lokal' ist aktiv (Modelle anpassen: backend/config.py + dev-ops/opencode.json)."
 
+# 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/themen
+	@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 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/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.
@@ -79,4 +85,51 @@ sync-projects:
 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)
+
+# 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,29 +1,50 @@
-"""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, MAX_CONCURRENT_AGENTS, MAX_CONCURRENT_INTERACTIVE
+from config import (PROVIDERS, DEFAULT_PROVIDER, MAX_CONCURRENT_AGENTS,
+                    MAX_CONCURRENT_AGENTS_PER_TOPIC, MAX_CONCURRENT_INTERACTIVE,
+                    resolve_role)
 
 log = logging.getLogger("creator.agents")
 
 _active_processes: dict[str, asyncio.subprocess.Process] = {}
+_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)
 
-# Abgebrochene Scopes (Schlüssel-Präfixe, symmetrisch zu kill_process). Ein Agent, dessen
-# Key mit einem dieser Präfixe beginnt, bricht VOR dem Spawn ab — so werden auch in der
-# Semaphore-Schlange WARTENDE Agenten beim Abbruch sofort gestoppt, statt noch zu starten.
+
+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 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()
 
 
@@ -38,17 +59,99 @@ def clear_scope(prefix: str) -> None:
 def _scope_cancelled(agent_key: str) -> bool:
     return any(agent_key.startswith(p) for p in _cancelled_prefixes)
 
-# Deckelt die realen CLI-Prozesse — unabhängig von der Pipeline-Semaphore in
-# generator.py. Acquire passiert VOR dem Spawn, damit Wartezeit in der Queue
-# nicht gegen den Agent-Timeout zählt.
-_batch_sem = asyncio.Semaphore(MAX_CONCURRENT_AGENTS)
+# 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)
 _interactive_sem = asyncio.Semaphore(MAX_CONCURRENT_INTERACTIVE)
 
-# OpenCode-Starts serialisieren: gleichzeitig startende Prozesse kollidieren an
-# der internen Session-DB ("database is locked", Exit nach <1s). Der kurze
-# Versatz entzerrt die Starts; danach laufen die Prozesse normal parallel.
+# 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):
+    """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."""
+    topic_sem = _topic_sems.setdefault(scope, _PrioritySemaphore(MAX_CONCURRENT_AGENTS_PER_TOPIC)) if scope else None
+    if topic_sem is not None:
+        await topic_sem.acquire(priority)
+    await _batch_sem.acquire(priority)
+    try:
+        yield
+    finally:
+        _batch_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 = 1.0
+_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))
+
+_SLIM_CONFIG = Path(__file__).resolve().parent.parent / "dev-ops" / "opencode-slim.json"
 
 # Capability → Claude --allowedTools
 _CLAUDE_TOOLS = {
@@ -58,7 +161,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",
@@ -85,9 +188,25 @@ def provider_available(provider: str) -> bool:
     return True
 
 
+# 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:
-    """Killt den Agenten samt Kindprozessen über die Prozess-Gruppe (sonst überleben die
-    von der CLI gestarteten Kinder, halten die Pipes offen und blockieren communicate())."""
+    """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):
@@ -98,16 +217,22 @@ def _kill(process) -> None:
 
 
 def kill_process(agent_key_prefix: str) -> None:
-    """Killt alle aktiven Prozesse, deren Key mit dem Prefix beginnt (deckt -plan/-w1… ab)."""
+    """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:  # tote Einträge beim Iterieren aufräumen
+        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(
     agent_key: str,
     prompt: str,
@@ -116,23 +241,69 @@ async def run_agent(
     role: str = "fast",
     capabilities: str = "none",
     lane: str = "batch",
+    scope: str | None = None,
+    on_line=None,
+    label: str = "",
 ) -> tuple[int, str, str]:
-    if _scope_cancelled(agent_key):  # vor dem Anstehen: gar nicht erst in die Schlange
-        return 1, "", "abgebrochen"
+    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}"
+        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})"
     if shutil.which(PROVIDERS[provider]["cli"]) is None:
-        return 1, "", f"CLI '{PROVIDERS[provider]['cli']}' nicht installiert (Provider: {provider})"
-    sem = _interactive_sem if lane == "interactive" else _batch_sem
-    async with sem:
-        if _scope_cancelled(agent_key):  # nach dem Acquire: in der Schlange abgebrochen → kein Spawn
-            return 1, "", "abgebrochen"
+        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))
+    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 = ""
+        try:
+            log.info("agent %s: %s %s (role %s)", agent_key, provider, model, role)
             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)
+                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 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, stagger: bool = False) -> tuple[int, str, str]:
+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():
@@ -141,18 +312,42 @@ async def _communicate(agent_key: str, cmd: list[str], stdin_data: bytes | None,
             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,  # eigene Prozess-Gruppe → killpg killt auch Kindprozesse
+            start_new_session=True,  # own process group → killpg also kills child processes
+            env=env,
         )
 
     if stagger:
-        async with _opencode_start_lock:
+        await _opencode_slot()  # spaced start slot; spawn itself is not serialized
     process = await spawn()
-            await asyncio.sleep(_OPENCODE_START_DELAY)
+    # 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:
+            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:
-        process = await spawn()
-    _active_processes[agent_key] = process
-    try:
-        try:
                 stdout, stderr = await asyncio.wait_for(
                     process.communicate(input=stdin_data),
                     timeout=timeout,
@@ -163,49 +358,85 @@ async def _communicate(agent_key: str, cmd: list[str], stdin_data: bytes | None,
                 await asyncio.wait_for(process.wait(), timeout=5)
             except asyncio.TimeoutError:
                 pass
-            log.info("agent %s: Timeout nach %ds", agent_key, timeout)
+            log.info("agent %s: timeout after %ds", agent_key, timeout)
             raise
         log.info(
-            "agent %s: exit %s nach %.1fs (%d Bytes stdout)",
+            "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:
-        # Pop nur bei Identität: ein Slot-Restart unter demselben Key darf den
-        # NEUEN Prozess nicht aus dem Tracking werfen.
-        if _active_processes.get(agent_key) is process:
-            del _active_processes[agent_key]
+        # 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, stagger=True)
-        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)
 
@@ -214,7 +445,7 @@ _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/board_artefacts.py

@@ -0,0 +1,661 @@
+"""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:
+  subblocks → facts → levels → relevance → question_pattern → artefacts → finalize
+finalize (SERIAL) merges the block's results into the global sidecar/facts/pattern/artefakte
+files + the DB tables. `outline` is a topic-wide BARRIER singleton at the very end
+(prerequisite graph → chapter order), re-run once per generation run.
+
+The heavy lifting is the existing per-block functions in blocks.py — each card gets its own
+work subdirectory + facts/artefakte paths, so their slot files never collide across blocks."""
+
+import asyncio
+import hashlib
+import json
+import logging
+import re
+
+import database as db
+import blocks
+import embedding
+from blocks import (
+    ARTEFACT_TYPES, _artefacts_block, _facts_block, _facts_nachfass, _konsolidiere_subblocks,
+    _levels_block, _luecken_runde, _match_sub, _neg_set, _question_pattern_block, _relevance_block,
+    _sink_json, _subblocks_block, _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", "subblocks", {
+            "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
+
+
+async def _proc_subblocks(ctx: GenContext, flow: Flow, files: dict, instructions: str, cards):
+    topic = flow.topic
+    # Fix 4: 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"]
+        instr = instructions
+        sd = [s for s in seeds.get(norm, []) if s]
+        if sd:
+            instr = (instructions + "\n\nBereits identifizierte Unterpunkt-Kandidaten dieses "
+                     "Blocks (prüfen; wenn belegt UND noch nicht durch einen anderen Eintrag "
+                     "abgedeckt, aufnehmen — nicht wörtlich übernehmen, sondern als eigenständige "
+                     "Aussage formulieren):\n"
+                     + "\n".join(f"- {s}" for s in sd))
+        raw = await _subblocks_block(ctx, _card_set_p(flow, norm), _pfiles(files, norm),
+                                     {1: _entry_line(p)}, instr, wipe=False, ns=f"{_safe(norm)}-",
+                                     seeds=sd or None, lbl=f"{p.get('title', norm)} · ",
+                                     sources=p.get("sources"))
+        if raw is None:
+            return _fail_or_cancel(ctx, f"Subblocks {p.get('title', norm)}")
+        p["raw"] = raw
+        p["subs_n"] = sum(len(v) for v in raw.values())  # LPT: bigger blocks pull first
+        await db.kanban_set_payload(topic, BOARD, norm, p)
+        await db.kanban_advance(topic, BOARD, norm, "facts")
+
+    await _gather_cards(ctx, flow, cards, one)
+
+
+async def _proc_facts(ctx: GenContext, flow: Flow, files: dict, q: dict, folder,
+                      instructions: str, cards):
+    topic = flow.topic
+
+    async def one(c):
+        p = c["payload"]
+        norm = c["card_id"]
+        raw = p.get("raw") or {}
+        res = await _facts_block(ctx, _card_set_p(flow, norm), _pfiles(files, norm), raw, q,
+                                 folder, instructions, ns=f"{_safe(norm)}-",
+                                 lbl=f"{p.get('title', norm)} · ", sources=p.get("sources"))
+        if res is None:
+            return _fail_or_cancel(ctx, f"Facts {p.get('title', norm)}")
+        facts_map, discarded = res
+        if discarded:  # unsupportable subs vanish from raw too (guide never sees them)
+            for bt, sns in discarded.items():
+                if bt in raw:
+                    raw[bt] = [s for s in raw[bt] if _norm_title(s) not in sns]
+            raw = {bt: subs for bt, subs in raw.items() if subs}
+        # In-block consolidation: two-judge panel folds same-statement/subset subs, bundles
+        # catalogs, drops off-topic ones — the facts are in hand (key points as evidence),
+        # questions/artefacts not yet built. Reported gaps get ONE follow-up finder round.
+        luecken = await _konsolidiere_subblocks(ctx, _pfiles(files, norm), raw, facts_map,
+                                                instructions, ns=f"{_safe(norm)}-",
+                                                lbl=f"{p.get('title', norm)} · ")
+        if ctx.is_cancelled():
+            return None
+        nachgefasst = 0
+        for bt, lk in (luecken or {}).items():
+            nachgefasst += await _luecken_runde(ctx, _pfiles(files, norm), bt, lk, raw, facts_map,
+                                                q, folder, instructions, ns=f"{_safe(norm)}-",
+                                                lbl=f"{p.get('title', norm)} · ", sources=p.get("sources"))
+        if ctx.is_cancelled():
+            return None
+        if nachgefasst:  # close the loop: follow-up finds get the SAME duplicate test as the
+            # rest (new subs-hash → fresh judge files); their gap report is deliberately ignored
+            await _konsolidiere_subblocks(ctx, _pfiles(files, norm), raw, facts_map,
+                                          instructions, ns=f"{_safe(norm)}-",
+                                          lbl=f"{p.get('title', norm)} · ")
+        if ctx.is_cancelled():
+            return None
+        raw = {bt: subs for bt, subs in raw.items() if subs}
+        # consolidation renames/catalogs can leave consensus subs without grounding — the
+        # guide fact gate then flags their correct statements wholesale (measured: 74/210)
+        await _facts_nachfass(ctx, _pfiles(files, norm), raw, facts_map, q, folder,
+                              instructions, ns=f"{_safe(norm)}-",
+                              lbl=f"{p.get('title', norm)} · ", sources=p.get("sources"))
+        if ctx.is_cancelled():
+            return None
+        p["raw"], p["facts"] = raw, facts_map
+        await db.kanban_set_payload(topic, BOARD, norm, p)
+        await db.kanban_advance(topic, BOARD, norm, "levels")
+
+    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 — 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. The loser leaves its card's raw/facts and turns DB `variant` — before
+    questions/artefacts exist, so no orphans. Fail-open on judge failure/dissent."""
+    topic = flow.topic
+    work_dir = flow.work_dir
+    package_norms = {c["card_id"] for c in cards}
+    entries: list[tuple[int, str, str]] = []  # (card idx, block title, sub title); idx -1 = context
+    for ci, c in enumerate(cards):
+        for bt, subs in (c["payload"].get("raw") or {}).items():
+            for s in subs:
+                entries.append((ci, bt, s))
+    n_pkg = len(entries)
+    # Context: consensus subs of blocks already PAST this barrier (late spawns via the
+    # gap-check feedback would otherwise never be compared). Context never folds —
+    # its card payload lives downstream (board-1 rule: confirmed context always wins).
+    for r in await db.list_subblocks(topic):
+        if r["status"] == "consensus" and r["block_norm"] not in package_norms:
+            entries.append((-1, r["block"], r["sub_title"]))
+    ctx_facts: dict[str, dict] = {}  # facts of downstream cards (DB rows carry none yet)
+    for bc in await db.kanban_cards(topic, board=BOARD, kind="ablock"):
+        if bc["card_id"] not in package_norms:
+            for bt, fm in (bc["payload"].get("facts") or {}).items():
+                ctx_facts[_norm_title(bt)] = fm
+
+    async def _advance_all():
+        await db.kanban_advance_many(topic, BOARD, [(c["card_id"], "question_pattern") for c in cards])
+        flow.wake.set()
+
+    if n_pkg < 1 or len(entries) < 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, [s for _, _, s in entries])
+    if sims is None:
+        await _advance_all()
+        return
+    negs = [_neg_set(s) for _, _, s in entries]
+    pairs = [(i, j) for i in range(len(entries)) for j in range(i + 1, len(entries))
+             if entries[i][0] != entries[j][0] and negs[i] == negs[j]
+             and float(sims[i][j]) >= SUB_DUP_KANDIDAT_COS]
+    if not pairs:
+        await _advance_all()
+        return
+
+    def _kp(ci: int, bt: str, s: str) -> list:
+        if ci < 0:
+            f = ctx_facts.get(_norm_title(bt)) or {}
+        else:
+            f = (cards[ci]["payload"].get("facts") or {}).get(bt) or {}
+        return (f.get(_norm_title(s)) or {}).get("key_points") or []
+
+    def _side(tag: str, ci: int, bt: str, s: str) -> str:
+        return f"{tag}: [Block: {bt}] {s}" + "".join(f"\n   - {p}" for p in _kp(ci, bt, s))
+
+    # 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', *entries[i])}\n{_side('B', *entries[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', *entries[chunk[k - 1][0]])}\n{_side('B', *entries[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[int] = set()
+    touched: set[int] = set()
+    for k, (i, j) in enumerate(pairs, 1):
+        verdict = final_all.get(k, "nein")
+        journal["verdicts"].append({"a": f"{entries[i][1]} · {entries[i][2]}",
+                                    "b": f"{entries[j][1]} · {entries[j][2]}",
+                                    "verdict": verdict})
+        if verdict not in ("a", "b"):
+            continue
+        lose = j if verdict == "a" else i
+        if entries[lose][0] < 0:  # context never folds — the package side goes instead
+            lose = i if lose == j else j
+        keep = i if lose == j else j
+        if lose in gone or keep in gone:  # keeper already folded → don't chain away the content
+            continue
+        ci, bt, s = entries[lose]
+        p = cards[ci]["payload"]
+        if s in (p.get("raw") or {}).get(bt, []):
+            p["raw"][bt].remove(s)
+            (p.get("facts") or {}).get(bt, {}).pop(_norm_title(s), None)
+            sc = (p.get("sidecar") or {}).get(bt)
+            if isinstance(sc, list):  # questions/artefacts consume the sidecar downstream
+                p["sidecar"][bt] = [e for e in sc
+                                    if _norm_title(str((e or {}).get("title", ""))) != _norm_title(s)]
+            await db.set_subblock_fields(topic, _norm_title(bt), _norm_title(s), status="variant")
+            gone.add(lose)
+            touched.add(ci)
+            journal["gefaltet"].append({"weg": f"{bt} · {s}",
+                                        "bleibt": f"{entries[keep][1]} · {entries[keep][2]}"})
+    for ci in touched:
+        p = cards[ci]["payload"]
+        p["raw"] = {bt: subs for bt, subs in (p.get("raw") or {}).items() if subs}
+        await db.kanban_set_payload(topic, BOARD, cards[ci]["card_id"], p)
+    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()
+
+
+async def _proc_levels(ctx: GenContext, flow: Flow, files: dict, instructions: str, cards):
+    topic = flow.topic
+
+    async def one(c):
+        p = c["payload"]
+        norm = c["card_id"]
+        sidecar = await _levels_block(ctx, _card_set_p(flow, norm), _pfiles(files, norm),
+                                      p.get("raw") or {}, instructions, ns=f"{_safe(norm)}-",
+                                      lbl=f"{p.get('title', norm)} · ")
+        if sidecar is None:
+            return _fail_or_cancel(ctx, f"Levels {p.get('title', norm)}")
+        facts_map = p.get("facts") or {}
+        for btitle, subs in sidecar.items():  # merge facts into the subs (mirror + guide)
+            fm = facts_map.get(btitle, {})
+            for sub in subs:
+                # level agents paraphrase titles — exact miss falls back to the unique
+                # prefix/containment match, else the sub silently loses its grounding
+                sn = _sub_key(set(fm), _norm_title(sub["title"]))
+                if (fk := fm.get(sn)):
+                    sub["facts"] = fk
+        p["sidecar"] = sidecar
+        await db.kanban_set_payload(topic, BOARD, norm, p)
+        await db.kanban_advance(topic, BOARD, norm, "relevance")
+
+    await _gather_cards(ctx, flow, cards, one)
+
+
+async def _proc_relevance(ctx: GenContext, flow: Flow, files: dict, instructions: str, cards):
+    topic = flow.topic
+
+    async def one(c):
+        p = c["payload"]
+        norm = c["card_id"]
+        sidecar = p.get("sidecar") or {}
+        rel = await _relevance_block(ctx, _card_set_p(flow, norm), _pfiles(files, norm),
+                                     sidecar, instructions, ns=f"{_safe(norm)}-",
+                                     lbl=f"{p.get('title', norm)} · ")
+        if rel is None:
+            return _fail_or_cancel(ctx, f"Relevance {p.get('title', norm)}")
+        gid = 0
+        for subs in sidecar.values():
+            for sub in subs:
+                gid += 1
+                sub["relevance"] = rel.get(gid, "relevant")
+        p["sidecar"] = sidecar
+        await db.kanban_set_payload(topic, BOARD, norm, p)
+        await db.kanban_advance(topic, BOARD, norm, "konsolidierung")
+
+    await _gather_cards(ctx, flow, cards, one)
+
+
+async def _proc_question_pattern(ctx: GenContext, flow: Flow, files: dict, instructions: str, cards):
+    topic = flow.topic
+
+    async def one(c):
+        p = c["payload"]
+        norm = c["card_id"]
+        pattern = await _question_pattern_block(ctx, _card_set_p(flow, norm), _pfiles(files, norm),
+                                                p.get("sidecar") or {}, instructions,
+                                                ns=f"{_safe(norm)}-", lbl=f"{p.get('title', norm)} · ")
+        if pattern is None:
+            return _fail_or_cancel(ctx, f"Fragen {p.get('title', norm)}")
+        p["pattern"] = pattern
+        await db.kanban_set_payload(topic, BOARD, norm, p)
+        await db.kanban_advance(topic, BOARD, norm, "artefacts")
+
+    await _gather_cards(ctx, flow, cards, one)
+
+
+async def _proc_artefacts(ctx: GenContext, flow: Flow, files: dict, instructions: str, cards):
+    topic = flow.topic
+
+    async def one(c):
+        p = c["payload"]
+        norm = c["card_id"]
+        artefacts = await _artefacts_block(ctx, _card_set_p(flow, norm), _pfiles(files, norm),
+                                           p.get("sidecar") or {}, instructions,
+                                           ns=f"{_safe(norm)}-", lbl=f"{p.get('title', norm)} · ")
+        if artefacts is None and ctx.is_cancelled():
+            return None
+        p["artefacts"] = artefacts or {}  # artefacts are optional — never fatal
+        await db.kanban_set_payload(topic, BOARD, norm, p)
+        await db.kanban_advance(topic, BOARD, norm, "finalize")
+
+    await _gather_cards(ctx, flow, cards, one)
+
+
+# ── 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"], DONE)
+        _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) ─────────────────────────────
+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, "subblocks", lambda cs: _proc_subblocks(ctx, flow, files, instructions, cs)),
+        Stage(BOARD, "facts", lambda cs: _proc_facts(ctx, flow, files, q, folder, instructions, cs)),
+        Stage(BOARD, "levels", lambda cs: _proc_levels(ctx, flow, files, instructions, cs)),
+        Stage(BOARD, "relevance", lambda cs: _proc_relevance(ctx, flow, files, instructions, cs)),
+        # Barrier sits AFTER the sub-local stages: cards used to idle here median 36 min
+        # while levels/relevance work was still ahead of them
+        Stage(BOARD, "konsolidierung",
+              lambda cs: _proc_konsolidierung(ctx, flow, files, instructions, cs),
+              barrier=True, drain=True),
+        Stage(BOARD, "question_pattern",
+              lambda cs: _proc_question_pattern(ctx, flow, files, instructions, cs)),
+        Stage(BOARD, "artefacts", lambda cs: _proc_artefacts(ctx, flow, files, instructions, cs)),
+        Stage(BOARD, "finalize", lambda cs: _proc_finalize(ctx, flow, files, cs), serial=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
@@ -8,103 +9,257 @@ 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
 
-# Lesbarkeits-Gate: deterministischer Prüfer (kleines deutsches Komplexitäts-Modell,
-# Skala 1–7). Zu schwere Sections gehen in die Lese-Prüfungs-Überarbeitung.
-# Fehlen transformers/torch oder das Modell → Gate stumm aus.
-LESBARKEIT_AKTIV = True
-LESBARKEIT_MODELL = "MiriUll/distilbert-german-text-complexity"
-# Anker auf der 1–7-Skala (TextComplexityDE): Leichte Sprache ~1,2; Wikipedia-Schnitt
-# ~3,22; ab MOS > 4 gilt ein Satz als „echt komplex" (Vereinfachungs-Grenze des Papers).
-LESBARKEIT_MAX = 3.5          # Section zu schwer, wenn der Satz-Schnitt darüber liegt
-LESBARKEIT_HART = 4.0         # Einzelsatz ab hier „hart"
-LESBARKEIT_HART_ANTEIL = 0.30  # … ODER wenn dieser Anteil der Sätze hart ist
+# 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
 
-# Deckel für gleichzeitige CLI-Agenten-Prozesse (über alle Generierungen hinweg).
-# Eigene Spur für interaktive Aufrufe (Chat, Elemente), damit sie nicht hinter
-# laufenden Writern in der Warteschlange hängen.
-MAX_CONCURRENT_AGENTS = 10
-MAX_CONCURRENT_INTERACTIVE = 4
+# 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
 
-# Grace-Fenster der Konsens-Races (Bausteine, Guide, OnePager): Nach dem ersten
-# gültigen Ergebnis dürfen die übrigen Agenten noch so viele Sekunden fertig
-# werden (Kill nur, wenn das Minimum schon steht).
-KONSENS_GRACE = 300
+# 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
 
-# Recherche-Race: längeres Grace-Fenster. Recherche treibt die ganze Bausteine-Anzahl;
-# bei langsamen Providern (z.B. MiniMax) sollen ALLE 5 Agenten fertig werden, nicht nur
-# das Quorum von 3. Pro-Agent-Timeout (TIMEOUTS["recherche"]=1800s) deckelt echte Hänger.
-RECHERCHE_GRACE = 900
+# 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
+MAX_CONCURRENT_AGENTS_PER_TOPIC = int(os.getenv("MAX_CONCURRENT_AGENTS_PER_TOPIC", "12"))  # per topic
+MAX_CONCURRENT_INTERACTIVE = 8
 
-# Cap der Klärungs- und Prüf-Loops: maximale Runden, bis alles entschieden sein
-# muss. In der letzten Runde MUSS der Mapping-Agent jeden Eintrag entscheiden;
-# Prüf-Loops lassen Rest-Beanstandungen danach stehen.
-KONSENS_MAX_RUNDEN = 3
+# 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
 
-# Crawler-Sichtung (Content/Noise) — deterministischer Regel-Filter statt LLM.
-# Match: Substring (klein) gegen URL UND Dateiname. Reihenfolge: keep > noise > min_chars > behalten.
-# Sonderregeln einfach hier ergänzen.
-CRAWL_KEEP_PATTERNS = ["learn-unit", "learn-course"]            # immer Content
-CRAWL_NOISE_PATTERNS = [                                         # eindeutig themenfremd → raus
+# 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                                            # zu wenig Text → raus
+CRAWL_MIN_CHARS = 400                                            # too little text → out
 
-# 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.
+# 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
+
+# Guide section length per relevant sub (ausführlich part) — QA detector AND the
+# deterministic readability-stage trigger share these bounds (writers overshot 2.7–4.1×).
+GUIDE_LAENGE_MIN = 150
+GUIDE_LAENGE_MAX = 1200
+
+# 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)
+SUBBLOCK_CAP = 900         # subblock find loop per chunk (seconds)
+SUBBLOCK_MIN = 5           # below this consensus count → focused catch-up rounds
+SUBBLOCK_EXTRA_ROUNDS = 2  # max catch-up rounds
+SUBBLOCK_MAX_ROUNDS = 3    # hard round cap (rounds 4–5 burned 29 % of finders for ~0 gain)
+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
+FILTER_RECHECK_PANEL = 3   # judges in the survivor-recheck
+MAX_WRITER_ROUNDS = 2      # guide coverage→writer loop cap
+GATE_FIX_MIN = 3           # fact-gate: unbelegt-claims below this → 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
+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
-    "recherche_mapping": (600, 3),  # n = vorgemergte Einträge
-    "auswahl_mapping":   (600, 2),  # n = Rest-Einträge (Bausteine-Inventar)
-    "ergaenzung":    (900, 0),   # Themenfeld-Ergänzung bei Projekten (Web-Recherche)
+    "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),
-    "plan_judge":    (600, 5),    # Judge liest bis zu 5 Gliederungen, n = Sections
-    "inhalt":        (600, 90),   # Inhalte je Baustein im Chunk identifizieren (Websuche)
-    "inhalt_check":  (300, 10),   # Inhalts-Prüfung je Baustein im Paket
-    "subbaustein":       (900, 45),  # Subbausteine je Baustein im Chunk finden (Websuche)
-    "subbaustein_check": (300, 15),  # Judge entscheidet strittige Subbausteine im Chunk
-    "stufe":             (300, 10),  # Subbausteine einstufen je Chunk
-    "stufe_check":       (300, 10),  # Judge entscheidet strittige Stufen im Chunk
-    "relevanz":          (300, 10),  # Subbausteine relevant/rand je Chunk
-    "relevanz_check":    (300, 10),  # Judge entscheidet strittige Relevanz im Chunk
-    "frage_muster":      (300, 15),  # Frage-Muster je Baustein (Subbausteine × Typen)
-    "frage_muster_check": (300, 10),  # Kritiker bereinigt die Muster-Tabelle je Baustein
-    "writer":        (600, 120),  # pro Section im Chunk
-    "lese_check":    (300, 10),   # pro Section im Paket
+    "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
+    "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
 }
 
-# Zweck je Format — fließt in den Gliederungs-Judge (was der Guide leisten soll).
-FORMAT_ZWECK = {
+# 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"  = Interaktion + Voten (Chat, Prüfung, Klärung, Elemente),
-#         "judge" = Mapping-/Judge-/Prüf-Agenten — kalt (niedrige Temperature,
-#                   ohne Thinking) für stabile Urteile; Claude/Lokal mappen auf "fast",
-#         "guide" = große Generierung (Vorschläge, Writer).
+# 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).
 DEFAULT_PROVIDER = "claude"
 PROVIDERS = {
     "claude": {
         "cli": "claude",
         "guide": "claude-opus-4-8[1m]",
         "fast": "claude-sonnet-4-6",
-        "judge": "claude-sonnet-4-6",  # CLI kennt keine Temperature
+        "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/…" ist KEIN eigener Stack, nur ein opencode-Provider-Eintrag
-    # (dev-ops/opencode.json) mit niedriger Temperature; M3 dort ohne Thinking.
+    # "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-kalt/MiniMax-M2.7-highspeed",
-        "judge": "minimax-kalt/MiniMax-M3",
+        "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",
     },
@@ -115,6 +270,59 @@ PROVIDERS = {
         "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

@@ -1,9 +1,9 @@
-"""Geboundeter Domain-Crawler für Link-Quellen — rendert JS via Playwright (Chromium).
+"""Bounded domain crawler for link sources — renders JS via Playwright (Chromium).
 
-Lädt ab einer Start-URL Seiten + PDFs — NUR dieselbe Domain, begrenzte Tiefe und
-Seitenzahl. HTML-Seiten werden im Headless-Browser gerendert (für SPAs nötig), dann
-Links + Text aus dem fertigen DOM gezogen. PDFs werden direkt als Bytes geladen.
-Deterministisch, gebounded; läuft via asyncio.to_thread (Sync-API, kein Event-Loop).
+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
@@ -17,22 +17,23 @@ from fsutil import atomic_write_text
 
 log = logging.getLogger("creator.crawl")
 
-MAX_TIEFE = 3
-MAX_SEITEN = 500
-SEITE_TIMEOUT = 30        # Sekunden pro Seite (Render bzw. PDF-Download)
-MAX_BYTES = 10_000_000    # 10 MB Deckel pro PDF
+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:
-    """PDF-Bytes per urllib laden (kein Rendering nötig). None bei Fehler/zu groß."""
+    """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=SEITE_TIMEOUT) as resp:
+        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 fehlgeschlagen %s: %s", url, e)
+        log.debug("crawl: PDF fetch failed %s: %s", url, e)
         return None
 
 
@@ -46,56 +47,89 @@ def _is_pdf(url: str) -> bool:
     return url.lower().split("?")[0].rstrip("/").endswith(".pdf")
 
 
-def crawl(start_url: str, ziel: Path, *, max_tiefe: int = MAX_TIEFE, max_seiten: int = MAX_SEITEN, cancelled=None) -> int:
-    """Crawlt ab start_url (nur gleiche Domain), rendert JS und legt Seiten/PDFs in `ziel` ab.
+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 ""
 
-    BFS bis `max_tiefe` / `max_seiten`. Fehler einzelner Seiten werden übersprungen.
-    Schreibt am ENDE einen `.done`-Marker; ein Abbruch (`cancelled()` → True) lässt ihn weg,
-    sodass ein Neustart neu crawlt. Gibt die Zahl gespeicherter Quellen zurück.
+
+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: so startet das Backend auch ohne installiertes Playwright; nur das Crawlen schlägt dann fehl.
+    # Lazy: this way the backend starts even without Playwright installed; only crawling then fails.
     from playwright.sync_api import sync_playwright
 
-    ziel.mkdir(parents=True, exist_ok=True)
+    target.mkdir(parents=True, exist_ok=True)
     domain = urlparse(start_url).netloc
-    gesehen: set[str] = set()
+    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)]
-    gespeichert = 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 gespeichert < max_seiten:
+            while queue and saved < max_pages:
                 if cancelled and cancelled():
-                    return gespeichert  # Abbruch → KEIN .done-Marker → Neustart crawlt neu
-                url, tiefe = queue.pop(0)
-                if url in gesehen:
+                    return saved  # abort → NO .done marker → restart crawls again
+                url, depth = queue.pop(0)
+                if url in seen:
                     continue
-                gesehen.add(url)
+                seen.add(url)
 
-                # PDFs brauchen kein Rendering — direkt laden.
+                # PDFs need no rendering — load directly.
                 if _is_pdf(url):
                     data = _fetch_bytes(url)
                     if data:
-                        p = ziel / _name(url, ".pdf")
+                        p = target / _name(url, ".pdf")
                         if not p.exists():
                             p.write_bytes(data)
-                        gespeichert += 1
+                        saved += 1
                     continue
 
                 try:
-                    page.goto(url, wait_until="networkidle", timeout=SEITE_TIMEOUT * 1000)
+                    page.goto(url, wait_until="domcontentloaded", timeout=PAGE_TIMEOUT * 1000)
                 except Exception as e:
-                    log.debug("crawl: goto unvollständig %s: %s", url, e)  # trotzdem versuchen, Inhalt zu lesen
+                    log.debug("crawl: goto incomplete %s: %s", url, e)  # still try to read the content
                 try:
-                    text = page.inner_text("body").strip()
+                    page.wait_for_load_state("networkidle", timeout=CRAWL_SETTLE_MS)
                 except Exception:
-                    text = ""
+                    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(ziel / _name(url, ".txt"), f"QUELLE: {url}\n\n{text}")
-                    gespeichert += 1
-                if tiefe < max_tiefe:
+                    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:
@@ -103,11 +137,12 @@ def crawl(start_url: str, ziel: Path, *, max_tiefe: int = MAX_TIEFE, max_seiten:
                     for href in hrefs:
                         nxt = urldefrag(href)[0]
                         if (nxt.startswith(("http://", "https://"))
-                                and urlparse(nxt).netloc == domain and nxt not in gesehen):
-                            queue.append((nxt, tiefe + 1))
+                                and urlparse(nxt).netloc == domain and _in_scope(nxt, prefix)
+                                and nxt not in seen):
+                            queue.append((nxt, depth + 1))
         finally:
             browser.close()
 
-    (ziel / ".done").write_text("ok", encoding="utf-8")  # sauber durchgelaufen
-    log.info("crawl %s → %d Quellen in %s", start_url, gespeichert, ziel)
-    return gespeichert
+    (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/elements.py

@@ -1,261 +0,0 @@
-"""Elemente (persönliche Zusammenfassung) und Tutor-Chat zum Guide."""
-
-import json
-import logging
-import uuid
-
-from agents import run_agent
-from config import DEFAULT_PROVIDER
-from jsonio import parse_json_text as _parse_json_text, read_json_file as _json_datei
-from paths import bausteine_path, guide_content_path
-from pipeline import _prompt
-
-log = logging.getLogger("creator.elements")
-
-
-# --- Tutor-Chat ---
-
-def _build_guide_chat_prompt(topic: str, format_name: str, section: str, outline: str, messages: list[dict]) -> str:
-    transcript = "\n".join(
-        f"{'Nutzer' if m.get('role') == 'user' else 'Assistent'}: {m.get('content', '')}"
-        for m in messages
-    )
-    return _prompt(
-        "Chat",
-        topic=topic, format_name=format_name,
-        outline_block=outline.strip() or "(keine)",
-        section_block=section.strip() or "(kein Abschnitt erkannt)",
-        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 "Entschuldigung, das hat nicht geklappt. Bitte versuche es erneut."
-        reply = stdout.strip()
-        return reply or "Entschuldigung, ich habe keine Antwort erhalten."
-    except Exception:
-        log.warning("[%s] Guide-Chat fehlgeschlagen", topic, exc_info=True)
-        return "Entschuldigung, das hat nicht geklappt. Bitte versuche es erneut."
-
-
-# --- Elemente ---
-
-def _element_fields(data: dict) -> dict | None:
-    """Validiert KI-Element-JSON und normalisiert auf die DB-Felder."""
-    if not isinstance(data, dict):
-        return None
-    title = str(data.get("title", "")).strip()
-    if not title:
-        return None
-    listen = {}
-    for key in ("examples", "hints"):
-        raw = data.get(key, [])
-        listen[key] = [str(e).strip() for e in raw if str(e).strip()] if isinstance(raw, list) else []
-    return {
-        "title": title[:200],
-        "description": str(data.get("description", "")).strip(),
-        "examples": listen["examples"],
-        "hints": listen["hints"],
-    }
-
-
-def _topic_context(topic: str, limit: int = 12000) -> str:
-    """Bausteine + Guide-Inhalte des Themas als Kontext-Text (gekürzt)."""
-    parts: list[str] = []
-    bp = bausteine_path(topic)
-    if bp.exists():
-        parts.append(bp.read_text(encoding="utf-8"))
-    for fmt in ("Guide", "FullGuide"):  # bester verfügbarer Prosa-Guide als Chat-Kontext
-        content = _json_datei(guide_content_path(topic, fmt))
-        if content:
-            for ch in content.get("chapters", []):
-                for sec in ch.get("sections", []):
-                    parts.append(sec if isinstance(sec, str) else json.dumps(sec, ensure_ascii=False))
-            break  # bester verfügbarer Guide reicht
-    text = "\n\n".join(parts).strip()
-    return text[:limit] if text else "(kein Material vorhanden)"
-
-
-async def generate_element(topic: str, hint: str, provider: str = DEFAULT_PROVIDER, extra_context: str = "") -> dict:
-    """Erstellt Element-Felder per KI. Fallback: nur Titel aus dem Stichwort."""
-    fallback = {"title": hint.strip() or "Neues Element", "description": "", "examples": [], "hints": []}
-    try:
-        context = _topic_context(topic)
-        if extra_context.strip():
-            context = (extra_context.strip() + "\n\n" + context)[:12000]
-        prompt = _prompt(
-            "Element-Create",
-            topic=topic, hint=hint.strip() or "(keins — wähle selbst ein Kernkonzept)",
-            context=context,
-        )
-        returncode, stdout, _ = await run_agent(
-            "element-" + str(uuid.uuid4()), prompt, 240, provider=provider, role="fast", capabilities="none", lane="interactive"
-        )
-        if returncode != 0:
-            return fallback
-        return _element_fields(_parse_json_text(stdout)) or fallback
-    except Exception:
-        log.warning("[%s] Element-Erstellung fehlgeschlagen", topic, exc_info=True)
-        return fallback
-
-
-def _parse_suggestions(stdout: str) -> list[dict] | None:
-    """Validiert Vorschlags-JSON aus KI-Output. None bei ungültigem JSON."""
-    data = _parse_json_text(stdout)
-    if not isinstance(data, dict):
-        return None
-    suggestions = []
-    for s in data.get("suggestions", []):
-        if not isinstance(s, dict):
-            continue
-        text = str(s.get("text", "")).strip()
-        target = s.get("target")
-        content = str(s.get("content", "")).strip()
-        if text and content and target in ("description", "examples", "hints"):
-            suggestions.append({"text": text, "target": target, "content": content})
-    return suggestions
-
-
-async def check_element(element: dict, provider: str = DEFAULT_PROVIDER) -> list[dict] | None:
-    """Zweischrittige Prüfung auf fehlende Infos: Recherche → Verifizieren. None bei Fehler."""
-    try:
-        element_json = json.dumps(
-            {k: element[k] for k in ("title", "description", "examples", "hints")},
-            ensure_ascii=False, indent=1,
-        )
-        context = _topic_context(element["topic"])
-
-        # Schritt 1: Recherche — breit Kandidaten sammeln
-        prompt = _prompt("Element-Check", topic=element["topic"], element_json=element_json, context=context)
-        returncode, stdout, _ = await run_agent(
-            "element-check-" + str(uuid.uuid4()), prompt, 240, provider=provider, role="fast", capabilities="none", lane="interactive"
-        )
-        if returncode != 0:
-            return None
-        candidates = _parse_suggestions(stdout)
-        if candidates is None:
-            return None
-        if not candidates:
-            return []
-
-        # Schritt 2: Verifizieren — nur Wichtiges, nicht Redundantes durchlassen
-        prompt = _prompt(
-            "Element-Verify",
-            topic=element["topic"], element_json=element_json,
-            candidates_json=json.dumps({"suggestions": candidates}, ensure_ascii=False, indent=1),
-            context=context,
-        )
-        returncode, stdout, _ = await run_agent(
-            "element-verify-" + str(uuid.uuid4()), prompt, 240, provider=provider, role="fast", capabilities="none", lane="interactive"
-        )
-        if returncode != 0:
-            return None
-        return _parse_suggestions(stdout)
-    except Exception:
-        log.warning("[%s] Element-Prüfung fehlgeschlagen", element.get("topic", "?"), exc_info=True)
-        return None
-
-
-def _element_json(element: dict) -> str:
-    return json.dumps(
-        {k: element[k] for k in ("title", "description", "examples", "hints")},
-        ensure_ascii=False, indent=1,
-    )
-
-
-def _validate_change(c, element: dict) -> dict | None:
-    """Validiert einen Änderungs-Vorschlag aus KI-Output gegen das Element."""
-    if not isinstance(c, dict):
-        return None
-    text = str(c.get("text", "")).strip()
-    action = c.get("action")
-    target = c.get("target")
-    index = c.get("index")
-    content = str(c.get("content", "")).strip()
-    if not text or action not in ("entfernen", "anpassen", "hinzufuegen"):
-        return None
-    if target not in ("title", "description", "examples", "hints"):
-        return None
-    if action in ("anpassen", "hinzufuegen") and not content:
-        return None
-    if action == "entfernen" and target not in ("examples", "hints"):
-        return None
-    # Index nur für anpassen/entfernen in Listen-Feldern; muss existieren
-    if target in ("examples", "hints") and action in ("anpassen", "entfernen"):
-        if not isinstance(index, int) or not (0 <= index < len(element[target])):
-            return None
-    else:
-        index = None
-    return {"text": text, "action": action, "target": target, "index": index, "content": content}
-
-
-async def chat_with_element(element: dict, messages: list[dict], provider: str = DEFAULT_PROVIDER) -> tuple[str, list[dict]]:
-    """Chat zum Element. Gibt (Antwort, Änderungs-Vorschläge) zurück — ändert nichts direkt."""
-    fehler = "Entschuldigung, das hat nicht geklappt. Bitte versuche es erneut."
-    try:
-        transcript = "\n".join(
-            f"{'Nutzer' if m.get('role') == 'user' else 'Assistent'}: {m.get('content', '')}"
-            for m in messages
-        )
-        prompt = _prompt("Element-Chat", topic=element["topic"], element_json=_element_json(element), transcript=transcript)
-        returncode, stdout, _ = await run_agent(
-            "element-chat-" + str(uuid.uuid4()), prompt, 240, provider=provider, role="fast", capabilities="none", lane="interactive"
-        )
-        if returncode != 0:
-            return fehler, []
-        data = _parse_json_text(stdout)
-        if not isinstance(data, dict):
-            return fehler, []
-        changes = [v for c in data.get("changes", []) if (v := _validate_change(c, element))]
-        reply = str(data.get("reply", "")).strip() or ("Vorschläge erstellt." if changes else fehler)
-        return reply, changes
-    except Exception:
-        log.warning("[%s] Element-Chat fehlgeschlagen", element.get("topic", "?"), exc_info=True)
-        return fehler, []
-
-
-async def style_element(element: dict, provider: str = DEFAULT_PROVIDER) -> list[dict] | None:
-    """Prüft ein Element auf die Stil-Regeln und schlägt Änderungen vor. None bei Fehler."""
-    try:
-        prompt = _prompt("Element-Stil", topic=element["topic"], element_json=_element_json(element))
-        returncode, stdout, _ = await run_agent(
-            "element-stil-" + str(uuid.uuid4()), prompt, 240, provider=provider, role="fast", capabilities="none", lane="interactive"
-        )
-        if returncode != 0:
-            return None
-        data = _parse_json_text(stdout)
-        if not isinstance(data, dict):
-            return None
-        return [v for c in data.get("changes", []) if (v := _validate_change(c, element))]
-    except Exception:
-        log.warning("[%s] Stil-Prüfung fehlgeschlagen", element.get("topic", "?"), exc_info=True)
-        return None
-
-
-async def refine_suggestion(element: dict, suggestion: dict, instruction: str, provider: str = DEFAULT_PROVIDER) -> dict | None:
-    """Überarbeitet einen einzelnen Vorschlag nach Nutzer-Anweisung. None bei Fehler."""
-    try:
-        prompt = _prompt(
-            "Element-Refine",
-            topic=element["topic"], element_json=_element_json(element),
-            suggestion_json=json.dumps(suggestion, ensure_ascii=False, indent=1),
-            instruction=instruction,
-        )
-        returncode, stdout, _ = await run_agent(
-            "element-refine-" + str(uuid.uuid4()), prompt, 240, provider=provider, role="fast", capabilities="none", lane="interactive"
-        )
-        if returncode != 0:
-            return None
-        data = _parse_json_text(stdout)
-        if not isinstance(data, dict):
-            return None
-        return _validate_change(data.get("change"), element)
-    except Exception:
-        log.warning("[%s] Vorschlags-Überarbeitung fehlgeschlagen", element.get("topic", "?"), exc_info=True)
-        return None

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,345 @@
+"""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 "-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
+        if "-luecken-" in key:
+            return "<!-- block: leer -->\n"  # Lücken-Nachfass findet nichts Neues
+        if "-subblock-final-" in key or "-subblock-" in key:  # Finder + Judge, gleiches Format
+            teile = []
+            for t in self._bloecke_im_prompt(prompt):
+                subs = "\n".join(f"- {s}" for s in self.bloecke[t]["subs"])
+                teile.append(f"<!-- block: {t} -->\n{subs}")
+            return "\n".join(teile) or "<!-- block: leer -->\n"
+        if "-sub-konsolidierung-" 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})
+            return j({"gruppen": gruppen, "kataloge": kataloge, "fremd": [], "luecken": []})
+        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 "-facts-check-" in key:
+            return j({"ok": True})
+        if "-facts-" in key:  # facts / facts-fix / facts-erg: gleiches Format
+            eintraege = []
+            for t in self._bloecke_im_prompt(prompt):
+                for s in self.bloecke[t]["subs"]:
+                    if s in prompt:
+                        eintraege.append(self._fakt(t, s))
+                for kt, _m in self.kataloge:
+                    if kt in prompt:
+                        eintraege.append(self._fakt(t, kt))
+            if not eintraege:  # Nachfass-Fälle: Subs ohne Blockkontext im Prompt
+                eintraege = [self._fakt(bt, s) for bt, b in self.bloecke.items()
+                             for s in b["subs"] if s in prompt]
+            return j({"facts": eintraege})
+        if "-level-" in key:  # Rater + final: alle geforderten Nummern
+            nums = {m.group(1) for m in _NUM_RE.finditer(prompt)}
+            return j({"levels": {k: "beginner" for k in sorted(nums, key=int)} or {"1": "beginner"}})
+        if "-relevance-" in key:
+            nums = {m.group(1) for m in _NUM_RE.finditer(prompt)}
+            return j({"relevance": {k: "relevant" for k in sorted(nums, key=int)} or {"1": "relevant"}})
+        if "-question-pattern-" in key:
+            eintraege = []
+            for t in self._bloecke_im_prompt(prompt):
+                for s in self._subs_im_prompt(prompt):
+                    eintraege.append({"block": t, "subblock": s, "question": f"Was ist {s}?"})
+            return j({"pattern": eintraege})
+        if "-artifact-example-check-" in key:
+            return j({"ok": True})
+        if "-artifact-flashcard-" in key:
+            karten = [{"block": t, "subblock": s, "question": f"F: {s}?", "answer": f"A: {s}"}
+                      for t in self._bloecke_im_prompt(prompt) for s in self._subs_im_prompt(prompt)]
+            return j({"cards": karten})
+        if "-artifact-example-" in key:
+            bsp = [{"block": t, "subblock": s, "problem": f"Aufgabe zu {s}",
+                    "steps": ["Schritt 1", "Schritt 2"], "result": "Ergebnis"}
+                   for t in self._bloecke_im_prompt(prompt) for s in self._subs_im_prompt(prompt)]
+            return j({"examples": bsp})
+        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 "-gatefix-" in key or "-lesefix-" in key:
+            return self._section_aus_prompt(prompt) or "<!-- section: X -->\nRepariert."
+        if "-gate-" in key:
+            return j({"ok": True})
+        if "-cov-" in key:
+            ids = sorted(set(_ZIEL_RE.findall(prompt)))
+            return j({"ziele": {z: True for z in ids}, "luecken": [], "ballast": []})
+        if "-lese-" in key:
+            return j({"ok": True})
+        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="claude", 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

@@ -1,7 +1,7 @@
-"""Atomare Datei-Writes: erst .tmp im selben Verzeichnis, dann os.replace.
+"""Atomic file writes: first a .tmp in the same directory, then os.replace.
 
-Ein Crash hinterlässt höchstens eine .tmp-Datei — nie eine halb geschriebene
-Zieldatei. Die .tmp wird beim nächsten erfolgreichen Write überschrieben.
+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

backend/guide_board.py

@@ -0,0 +1,758 @@
+"""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
+  fakten_gate judge-Rolle   CoVe: atomic claims, each binary against the facts → minimal fix
+  coverage    judge-Rolle   objective↔section mapping; gap → back to writer (max 2 rounds)
+  lesbarkeit  judge-Rolle   Lese-Check + deterministic readability gate → fix → done
+
+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, GUIDE_LAENGE_MAX, GUIDE_LAENGE_MIN, READABILITY_ACTIVE,
+                    TEMPLATES_DIR, MAX_CONCURRENT_AGENTS_PER_TOPIC)
+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", "fakten_gate", "coverage", "lesbarkeit")
+STAGE_LABELS = {"lernziele": "Lernziele", "zuweisung": "Zuweisung", "writer": "Writer",
+                "fakten_gate": "Fakten-Gate", "coverage": "Coverage",
+                "lesbarkeit": "Lesbarkeit", "done": "Fertig"}
+from config import GATE_FIX_MIN, MAX_WRITER_ROUNDS, 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 _coverage_schema(data, ziel_ids: set[str]):
+    """{"ziele":{id:bool}, "luecken":[{ziel,fehlt}], "ballast":[str]} — ziele must cover all ids."""
+    if not isinstance(data, dict) or not isinstance(data.get("ziele"), dict):
+        return None
+    ziele = {}
+    for k, v in data["ziele"].items():
+        ziele[str(k)] = str(v).strip().casefold() in ("true", "ja", "yes", "1")
+    if 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()]
+    return {"ziele": ziele, "luecken": luecken, "ballast": ballast}
+
+
+def _problems_schema(data):
+    """Lese-Check: {"ok":true} → [] · {"problems":[{section,problem}]} → [problem…]."""
+    if not isinstance(data, dict):
+        return None
+    if data.get("ok") is True:
+        return []
+    probs = data.get("problems")
+    if not isinstance(probs, list) or not probs:
+        return None
+    out = [str(p.get("problem", "")).strip() for p in probs
+           if isinstance(p, dict) and str(p.get("problem", "")).strip()]
+    return out or None
+
+
+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)
+
+
+def _writer_budget(n_subs: int, sockel: int = 800) -> int:
+    """Length guideline (chars) for the detailed version — unguided sections measured 2–4×
+    too long (23k) or, after the readability fix, far too thin (180 chars/sub)."""
+    return sockel + 400 * max(n_subs, 1)
+
+
+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=_writer_budget(len(parts[i]), sockel=400),
+                           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)"
+    gaps = ""
+    if card["writer_rounds"] > 0 and card.get("gate_info"):
+        gaps = ("\nREVISION ROUND — a previous version exists. Revise it: close exactly the gaps "
+                "below, cut the listed ballast, keep everything else as-is.\n"
+                f"PREVIOUS VERSION:\n{card.get('md', '')}\n\nGAPS/BALLAST:\n{card['gate_info']}\n")
+    # 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="fakten_gate", 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=gaps, spec=env.spec,
+                       budget=_writer_budget(len(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="fakten_gate", status="open")
+    return True
+
+
+async def _stage_fakten_gate(env: _Env, card: dict) -> bool:
+    norm = card["block_norm"]
+    sec = _first_section(card["md"])
+    if sec is None:
+        await _set(env, card, status="error", gate_info="Writer-Fragment unlesbar")
+        return False
+    facts = _card_facts(env, card["block"])
+    ex = await _card_examples(env, norm, env.subs_by_title.get(card["block"], []))
+    if ex:  # the fix agent sees the same facts variable — examples survive the fix pass
+        facts += "\n\nVERIFIED WORKED EXAMPLES (count as verified facts for this check):\n" + ex
+    path = env.slot(f"gate-{_safe(norm)}-r{card['writer_rounds']}.json")
+    status, claims = await run_single_slot(
+        env.ctx, f"Fakten-Gate {card['block']}", key=f"{env.guide_id}-gate-{_safe(norm)}-r{card['writer_rounds']}",
+        prompt=_prompt("Guide-Fakten-Gate", topic=env.topic, block=card["block"],
+                       section=sec["md"], facts=facts, out_path=path,
+                       extra=_extra(env.instructions)),
+        role="judge", capabilities="files",
+        payload=lambda result: _gate_schema(_json_file(path)),
+        timeout=_timeout("fakten_gate", 1))
+    if status == CANCELLED:
+        return False
+    if status == FAILED:
+        claims = []  # gate failure must not block the card — logged, text stands
+        _log(env.topic, f"Fakten-Gate {card['block']}: kein Ergebnis — Text bleibt ungeprüft")
+    falsch = [c for c in claims if c.get("urteil") == "falsch"] if claims else []
+    if claims and not falsch and len(claims) < GATE_FIX_MIN:
+        # 1–2 merely UNSUPPORTED claims don't justify a fix pass (it ran for 19/20 blocks,
+        # 40 agent-minutes) — but a WRONG claim always does: one slipped through this
+        # threshold and cost the guide 1.5 QA points
+        _log(env.topic, f"Fakten-Gate {card['block']}: {len(claims)} Claim(s) unter Schwelle — kein Fix")
+        claims = []
+    if claims:
+        _log(env.topic, f"Fakten-Gate {card['block']}: {len(claims)} Claims ({len(falsch)} falsch) → Fix")
+        fixp = env.slot(f"gatefix-{_safe(norm)}-r{card['writer_rounds']}.md")
+        fixp.unlink(missing_ok=True)
+        claims_text = "\n".join(f"- {c['text']}" + (f" ({c['grund']})" if c["grund"] else "")
+                                for c in claims)
+
+        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"Fakten-Fix {card['block']}", key=f"{env.guide_id}-gatefix-{_safe(norm)}-r{card['writer_rounds']}",
+            prompt=_prompt("Guide-Fakten-Fix", topic=env.topic, block=card["block"],
+                           section=card["md"], claims=claims_text, facts=facts,
+                           out_path=fixp, extra=_extra(env.instructions)),
+            role="guide", capabilities="files", payload=_fixload,  # Fix auf der Schreib-Rolle, Gate auf der Judge-Rolle
+            timeout=_timeout("fakten_gate", 1))
+        if fstatus == CANCELLED:
+            return 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"Fakten-Fix {card['block']} ohne Sub-Marker — verworfen")
+            else:
+                card["md"] = fixed
+    await _set(env, card, md=card["md"], stage="coverage", status="open")
+    return True
+
+
+async def _stage_coverage(env: _Env, card: dict) -> bool:
+    norm = card["block_norm"]
+    ziele = await db.list_lernziele(env.topic, norm)
+    if not ziele:
+        await _set(env, card, stage="lesbarkeit")
+        return True
+    sec = _first_section(card["md"])
+    ziele_text = "\n".join(f"- ({z['ziel_id']}) {z['text']}" for z in ziele)
+    path = env.slot(f"coverage-{_safe(norm)}-r{card['writer_rounds']}.json")
+    ids = {z["ziel_id"] for z in ziele}
+    status, res = await run_single_slot(
+        env.ctx, f"Coverage {card['block']}", key=f"{env.guide_id}-cov-{_safe(norm)}-r{card['writer_rounds']}",
+        prompt=_prompt("Guide-Coverage", topic=env.topic, block=card["block"],
+                       ziele=ziele_text, section=sec["md"] if sec else card["md"],
+                       out_path=path, extra=_extra(env.instructions)),
+        role="judge", capabilities="files",
+        payload=lambda result: _coverage_schema(_json_file(path), ids),
+        timeout=_timeout("coverage", len(ziele)))
+    if status == CANCELLED:
+        return False
+    if status == FAILED:
+        _log(env.topic, f"Coverage {card['block']}: kein Ergebnis — weiter ohne Gate")
+        await _set(env, card, stage="lesbarkeit")
+        return True
+    for zid, ok in res["ziele"].items():
+        if zid in ids:
+            await db.set_ziel_covered(env.topic, norm, zid, ok)
+    if res["luecken"] and card["writer_rounds"] < MAX_WRITER_ROUNDS:
+        info = "\n".join(f"- Lücke ({l['ziel']}): {l['fehlt']}" for l in res["luecken"])
+        if res["ballast"]:
+            info += "\n" + "\n".join(f"- Ballast (kürzen): {b}" for b in res["ballast"])
+        _log(env.topic, f"Coverage {card['block']}: {len(res['luecken'])} Lücke(n) → Writer-Runde "
+                        f"{card['writer_rounds'] + 1}")
+        await _set(env, card, writer_rounds=card["writer_rounds"] + 1, gate_info=info,
+                   stage="writer", status="open")
+        return True
+    if res["luecken"]:
+        _log(env.topic, f"Coverage {card['block']}: Lücken bleiben nach {MAX_WRITER_ROUNDS} Runden")
+    await _set(env, card, gate_info="", stage="lesbarkeit")
+    return True
+
+
+async def _stage_lesbarkeit(env: _Env, card: dict) -> bool:
+    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
+    problems: list[str] = []
+    path = env.slot(f"lese-{_safe(norm)}-r{card['writer_rounds']}.json")
+    # Text-Antwort + Engine-Sink: Datei-schreibende Judges lieferten invalides JSON
+    # (3 kaputte Check-Dateien im Messlauf) — der Sink validiert vor dem Persistieren
+    status, res = await run_single_slot(
+        env.ctx, f"Lese-Check {card['block']}", key=f"{env.guide_id}-lese-{_safe(norm)}",
+        prompt=_prompt("Guide-Lese-Check", topic=env.topic, format_name=env.format,
+                       spec=env.spec, sections=f"SECTION: {card['block']}\n{sec['md']}",
+                       extra=_extra(env.instructions)),
+        role="judge", capabilities="none",
+        payload=lambda result: _sink_json(result, path, _problems_schema),
+        timeout=_timeout("lese_check", 1))
+    if status == CANCELLED:
+        return False
+    if status == OK and res:
+        problems += res
+    if READABILITY_ACTIVE:  # deterministic gate, external grounding
+        hints = await asyncio.to_thread(readability.rate_sections, {1: sec["md"]})
+        if hints.get(1):
+            problems.append(hints[1])
+    # deterministic length trigger, same formula as the QA detector: prompt guidelines
+    # alone left writers 2.7–4.1× over target — a measured overshoot forces the fix pass
+    subs_all = env.subs_by_title.get(card["block"], [])
+    n_rel = max(sum(1 for s in subs_all if s.get("relevance") != "peripheral"), 1)
+    aus = re.split(r"<!--\s*ausführlich\s*-->", sec["md"], maxsplit=1)
+    pro_sub = len(aus[1] if len(aus) == 2 else sec["md"]) / n_rel
+    if not (GUIDE_LAENGE_MIN <= pro_sub <= GUIDE_LAENGE_MAX * 0.9):
+        ziel = _writer_budget(len(subs_all))
+        problems.append(
+            f"Länge {round(pro_sub)} Zeichen/Sub (Rahmen {GUIDE_LAENGE_MIN}–{round(GUIDE_LAENGE_MAX * 0.9)}): "
+            f"schreibe den ausführlich-Teil auf etwa {ziel} Zeichen GESAMT um — Sockel-Prosa und "
+            f"Wiederholungen streichen, alle Sub-Marker und Beispiele behalten")
+    if problems:
+        from guide import _level_label
+        subs = env.subs_by_title.get(card["block"], [])
+        sub_list = "\n".join(f"- [{_level_label(s)}] {s['title']}" for s in subs) or "(none)"
+        tasks = (f"SECTION: {card['block']}\n"
+                 f"SUBBLOCKS (set one `<!-- sub: LABEL | title -->` marker each, label/order as here):\n{sub_list}\n"
+                 f"LENGTH TARGET: about {_writer_budget(len(subs))} characters for the detailed "
+                 f"version (guideline — covering every subblock beats brevity).\n"
+                 f"PROBLEM: {' · '.join(problems)}\nCURRENT CONTENT:\n{sec['md']}")
+        fixp = env.slot(f"lesefix-{_safe(norm)}.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"Lese-Fix {card['block']}", key=f"{env.guide_id}-lesefix-{_safe(norm)}",
+            prompt=_prompt("Guide-Sections-Fix", topic=env.topic, format_name=env.format,
+                           facts=_card_facts(env, card["block"]), spec=env.spec, tasks=tasks,
+                           out_path=fixp, extra=_extra(env.instructions)),
+            role="guide", capabilities="files", payload=_fixload,
+            timeout=_timeout("writer", 1))
+        if fstatus == CANCELLED:
+            return False
+        if fstatus == OK and fixed:
+            new_sec = _first_section(fixed)
+            if sec.get("subs") and not (new_sec and new_sec.get("subs")):
+                _log(env.topic, f"Lese-Fix {card['block']} ohne Sub-Marker — verworfen")
+            else:
+                card["md"] = fixed
+    await _set(env, card, md=card["md"], stage="done", status="ok", gate_info="")
+    return True
+
+
+_STAGE_FN = {"lernziele": _stage_lernziele, "zuweisung": _stage_zuweisung,
+             "writer": _stage_writer, "fakten_gate": _stage_fakten_gate,
+             "coverage": _stage_coverage, "lesbarkeit": _stage_lesbarkeit}
+
+
+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]}")
+    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()
+            db.set_current_run(topic, None)
+    else:
+        db.set_current_run(topic, None)
+    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
+
+
+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 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,223 @@
+"""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 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
+
+from config import GUIDE_LAENGE_MAX as LAENGE_MAX, GUIDE_LAENGE_MIN as LAENGE_MIN
+
+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
+
+
+def laengen_ausreisser(cards: list[dict], subs_rel: dict[str, set]) -> list[dict]:
+    out = []
+    for c in cards:
+        n = max(len(subs_rel.get(c["block_norm"], set())), 1)
+        pro_sub = len(_ausfuehrlich(c["md"])) / n
+        if not (LAENGE_MIN <= pro_sub <= LAENGE_MAX):
+            out.append({"block": c["block"], "zeichen_pro_sub": round(pro_sub)})
+    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] = {}
+    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"])
+    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, subs_rel)
+    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

@@ -1,8 +1,8 @@
-"""Toleranter JSON-Parser für KI-Output — als Text oder aus Dateien.
+"""Tolerant JSON parser for AI output — from text or from files.
 
-Verkraftet Code-Fences, Drumherum-Text und unescapte Anführungszeichen in
-Strings (z. B. MiniMax: "Titel „p" geändert"): das letzte `"` vor der
-Fehlerstelle wird escapet und erneut geparst.
+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
@@ -14,7 +14,7 @@ log = logging.getLogger("creator.jsonio")
 
 
 def parse_json_text(text: str):
-    """Parst JSON aus KI-Output; None bei nicht reparierbarem Input."""
+    """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:
@@ -36,14 +36,14 @@ def parse_json_text(text: str):
 
 
 def read_json_file(path: Path):
-    """Liest eine JSON-Datei mit derselben Toleranz; None bei fehlend/ungültig."""
+    """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-Datei nicht lesbar: %s (%s)", path, e)
+        log.debug("JSON file not readable: %s (%s)", path, e)
         return None
     if data is None:
-        log.debug("JSON-Datei ungültig: %s", path)
+        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/lernen.py

@@ -1,537 +0,0 @@
-"""Baustein-Lernen: Vertiefung, Bausteinchat und Prüfung zu einzelnen Guide-Sections.
-
-Alle Aufrufe sind interaktiv (stdout-Antwort, lane "interactive") und stateless —
-der Chat-/Prüfungs-Verlauf kommt vom Frontend, persistiert wird nur der
-Prüfungs-Zähler (DB) und die Vertiefung (DB).
-"""
-
-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 create_element, list_elements
-from elements import generate_element
-from jsonio import parse_json_text as _parse_json_text
-from pipeline import _prompt, _probleme_schema
-from textkit import _norm_titel
-
-log = logging.getLogger("creator.lernen")
-
-# Meilensteine je Baustein (Score 0–30). Form ergibt sich aus dem Score-Band:
-# 0–6 Quiz, 7–12 Lückentext, 13–18 Erklären, 19–30 frei.
-NOETIG = 6     # MiniGuide-Meilenstein → „absolviert" (Quiz-Band durch)
-MASTERY = 12   # Guide-Meilenstein → „verstanden" (Lückentext-Band durch)
-MEISTERN = 18  # ProGuide-Meilenstein → „gemeistert" (Erklären-Band durch, Thema fertig)
-MAX_VOLL = 30  # FullGuide-Maximum (freie Formwahl ab 18)
-CHAT_TIMEOUT = 240
-PRUEFUNG_TIMEOUT = 120  # kurze JSON-Turns; deckelt die Serien-Latenz pro Prüfungs-Schritt
-GRUENDLICH_TIMEOUT = 600  # „Gründlich prüfen": starkes Modell (role guide) braucht länger
-KRITIK_MAX_RUNDEN = 2   # Generator → Kritiker → ggf. Neu, höchstens so oft
-
-# Fragetypen für Active Recall — pro Frage einer, zufällig gewählt. Schafft Vielfalt.
-FRAGETYPEN = {
-    "abruf": "Free Recall: Lass den Lerner die Kernidee frei aus dem Kopf erklären (offene Verständnisfrage).",
-    "punkt": "Cued Recall: Frag gezielt EIN konkretes Detail oder eine Abgrenzung ab.",
-    "warum": "Warum-Frage: Frag nach dem Grund/Mechanismus — warum funktioniert oder gilt das so?",
-    "anwendung": "Anwendung: Lass das Konzept auf EIN kurzes, neues Beispiel/Szenario anwenden.",
-    "pruefen": "Bei Code-/Tool-Themen: kleinen Schnipsel zeigen — Output vorhersagen ODER den Fehler finden. Kein Code-Thema → stattdessen eine Anwendungsfrage.",
-}
-
-
-# Antwort-Niveau (wie sehr der Kern getroffen ist) → Punkt-Delta.
-NIVEAUS = {
-    "kaum": -1,       # < 25 % richtig
-    "teilweise": 0,   # 25–49 %
-    "solide": 1,      # 50–74 %
-    "stark": 2,       # 75–99 %
-    "komplett": 3,    # 100 %
-}
-
-
-def score_berechnen(basis: int, delta: int, floor: int, cap: int) -> int:
-    """Neuer Score · driftfrei aus der Basis. `delta` liefert die Route je Prüfungsform
-    (Quiz +1/+3, Lückentext +1/+3, Erklären −1…+3; falsch −1). Auf [floor, cap] geklemmt.
-    floor = höchster erreichter Meilenstein (6/12/18); cap = Max des höchsten Formats.
-    Am Format-Deckel (basis ≥ cap) eingefroren: „Max" — weder + noch −, bis das nächste
-    Format freischaltet. Bei cap 30 (FullGuide) bleibt 30 endgültig."""
-    if basis >= cap:
-        return basis
-    return max(floor, min(cap, basis + delta))
-
-
-def _zufall_malus(basis: int, delta: int) -> int:
-    """Im Zufallband (Score ≥ MEISTERN=18, FullGuide) kostet jeder Fehler −3 statt −1 —
-    die 30 erreicht man nur mit Sicherheit. Richtige Antworten bleiben unverändert."""
-    return -3 if (basis >= MEISTERN and delta < 0) else delta
-
-
-def floor_aus_meilensteinen(absolviert: bool, verstanden: bool, gemeistert: bool) -> int:
-    """Untergrenze des Scores: ein erreichter Meilenstein hält (kein Rückfall ins Band davor)."""
-    if gemeistert:
-        return MEISTERN
-    if verstanden:
-        return MASTERY
-    if absolviert:
-        return NOETIG
-    return 0
-
-
-def _transcript(messages: list[dict]) -> str:
-    return "\n".join(
-        f"{'Nutzer' if m.get('role') == 'user' else 'Assistent'}: {m.get('content', '')}"
-        for m in messages
-    ) or "(leer)"
-
-
-async def baustein_chat(topic: str, baustein: str, section: str, kompakt: str | None, messages: list[dict], provider: str = DEFAULT_PROVIDER) -> str:
-    try:
-        prompt = _prompt(
-            "Baustein-Chat",
-            topic=topic, baustein=baustein,
-            section_block=section.strip() or "(keine Guide-Fassung übergeben)",
-            kompakt_block=(kompakt or "").strip() or "(keine)",
-            transcript=_transcript(messages),
-        )
-        returncode, stdout, _ = await run_agent(
-            "bausteinchat-" + str(uuid.uuid4()), prompt, CHAT_TIMEOUT,
-            provider=provider, role="fast", capabilities="none", lane="interactive",
-        )
-        if returncode != 0:
-            return "Entschuldigung, das hat nicht geklappt. Bitte versuche es erneut."
-        reply = stdout.strip()
-        return reply or "Entschuldigung, ich habe keine Antwort erhalten."
-    except Exception:
-        log.warning("[%s] Baustein-Chat fehlgeschlagen (%s)", topic, baustein, exc_info=True)
-        return "Entschuldigung, das hat nicht geklappt. Bitte versuche es erneut."
-
-
-def _frage_schema(data) -> dict | None:
-    """{"frage": str} · sonst None."""
-    if not isinstance(data, dict):
-        return None
-    frage = str(data.get("frage", "")).strip()
-    return {"frage": frage} if frage else None
-
-
-def _bewertung_schema(data) -> dict | None:
-    """{"feedback": str, "niveau": ∈ NIVEAUS} · sonst None."""
-    if not isinstance(data, dict):
-        return None
-    feedback = str(data.get("feedback", "")).strip()
-    niveau = data.get("niveau")
-    if not feedback or niveau not in NIVEAUS:
-        return None
-    return {"feedback": feedback, "niveau": niveau}
-
-
-async def _gen_call(name: str, role: str, schema, provider: str, timeout: int = PRUEFUNG_TIMEOUT, **kwargs) -> dict | None:
-    """Generator-Agent: Template füllen, laufen lassen, per schema parsen · None bei Fehler."""
-    returncode, stdout, _ = await run_agent(
-        name.lower() + "-" + str(uuid.uuid4()), _prompt(name, **kwargs), timeout,
-        provider=provider, role=role, capabilities="none", lane="interactive",
-    )
-    return schema(_parse_json_text(stdout)) if returncode == 0 else None
-
-
-async def _kritik_call(name: str, provider: str, role: str = "judge", timeout: int = PRUEFUNG_TIMEOUT, **kwargs) -> list[str]:
-    """Kritiker-Agent (Default role judge): leere Liste = in Ordnung. Fail-open: Ausfall des
-    Kritikers darf den Turn nicht blockieren, also dann ebenfalls leere Liste."""
-    returncode, stdout, _ = await run_agent(
-        name.lower() + "-" + str(uuid.uuid4()), _prompt(name, **kwargs), timeout,
-        provider=provider, role=role, capabilities="none", lane="interactive",
-    )
-    if returncode != 0:
-        return []
-    return _probleme_schema(_parse_json_text(stdout)) or []
-
-
-def _kritik_block(vorversion: str, probleme: list[str]) -> str:
-    punkte = "\n".join(f"- {p}" for p in probleme)
-    return (
-        f"Deine vorige Fassung war:\n«{vorversion}»\n\n"
-        f"Der Prüfer bemängelt:\n{punkte}\n\nBehebe diese Punkte."
-    )
-
-
-def _bewertung_text(bew: dict) -> str:
-    return f"Niveau: {bew['niveau']}\nFeedback: {bew['feedback']}"
-
-
-# Deterministischer Guard gegen Doppelfragen — der KI-Kritiker übersieht „…, und welchen…".
-_FRAGEWORT = r"(was|welche[rsnm]?|wie|wieso|warum|wofür|wozu|wann|wo|wer|wem|wen|nenne)"
-_DOPPEL_RE = re.compile(r"[,;]?\s+(und|sowie|außerdem|bzw\.?)\s+" + _FRAGEWORT + r"\b", re.IGNORECASE)
-
-
-def _doppelfrage_mangel(frage: str) -> str | None:
-    """Erkennt zwei verkettete Fragen. None = ok. Flaggt NUR 'und/sowie' + Fragewort."""
-    if frage.count("?") > 1:
-        return "Mehr als ein Fragezeichen — stelle GENAU EINE Frage."
-    if _DOPPEL_RE.search(frage):
-        return "Zwei Fragen mit 'und'/'sowie' verkettet — stelle GENAU EINE Frage, eine Sache."
-    return None
-
-
-async def _frage_mit_kritik(
-    topic: str, baustein: str, section_block: str, kompakt_block: str,
-    transcript: str, vermeide_block: str, typ_block: str, fokus_block: str, provider: str,
-) -> str | None:
-    """Frage generieren, vom Kritiker prüfen lassen, bei Mängeln neu (max KRITIK_MAX_RUNDEN)."""
-    kritik_block = "(keine)"
-    frage = None
-    for _ in range(KRITIK_MAX_RUNDEN):
-        data = await _gen_call(
-            "Baustein-Frage", "fast", _frage_schema, provider,
-            topic=topic, baustein=baustein, section_block=section_block,
-            kompakt_block=kompakt_block, transcript=transcript, vermeide_block=vermeide_block,
-            typ_block=typ_block, fokus_block=fokus_block, kritik_block=kritik_block,
-        )
-        if data is None:
-            return None
-        frage = data["frage"]
-        probleme = await _kritik_call(
-            "Baustein-Frage-Kritik", provider, role="guide",  # starke KI prüft die Regeln
-            topic=topic, baustein=baustein, section_block=section_block,
-            kompakt_block=kompakt_block, transcript=transcript, vermeide_block=vermeide_block,
-            typ_block=typ_block, fokus_block=fokus_block, frage=frage,
-        )
-        hart = _doppelfrage_mangel(frage)  # erzwingt Neugenerierung, auch wenn der KI-Kritiker es übersah
-        if hart:
-            probleme = [hart, *(probleme or [])]
-        if not probleme:
-            return frage
-        kritik_block = _kritik_block(frage, probleme)
-    return frage  # best-effort nach der letzten Runde
-
-
-async def _bewertung_mit_kritik(
-    topic: str, baustein: str, section_block: str, kompakt_block: str,
-    frage: str, transcript: str, begruendung_block: str, provider: str, role: str = "judge",
-) -> dict | None:
-    """Antwort bewerten (Niveau), vom Kritiker prüfen lassen, bei Fehlurteil neu.
-
-    `frage` ankert die geprüfte Frage; der Dialog (transcript) liefert Antwort + Diskussion.
-    `begruendung_block` = optionale Unzufriedenheit des Lerners (nur bei „Gründlich prüfen").
-    `role` = "judge" (schnell) oder "guide" (gründlich, starkes Modell mit Thinking).
-    """
-    timeout = GRUENDLICH_TIMEOUT if role == "guide" else PRUEFUNG_TIMEOUT
-    kritik_block = "(keine)"
-    bew = None
-    for _ in range(KRITIK_MAX_RUNDEN):
-        bew = await _gen_call(
-            "Baustein-Bewertung", role, _bewertung_schema, provider, timeout,
-            topic=topic, baustein=baustein, section_block=section_block,
-            kompakt_block=kompakt_block, frage=frage, transcript=transcript,
-            begruendung_block=begruendung_block, kritik_block=kritik_block,
-        )
-        if bew is None:
-            return None
-        probleme = await _kritik_call(
-            "Baustein-Bewertung-Kritik", provider, role=role, timeout=timeout,
-            topic=topic, baustein=baustein, section_block=section_block,
-            kompakt_block=kompakt_block, frage=frage, transcript=transcript,
-            bewertung_block=_bewertung_text(bew),
-        )
-        if not probleme:
-            return bew
-        kritik_block = _kritik_block(_bewertung_text(bew), probleme)
-    return bew  # best-effort nach der letzten Runde
-
-
-def _bloecke(section: str, kompakt: str | None) -> tuple[str, str]:
-    return (
-        section.strip() or "(keine Guide-Fassung übergeben)",
-        (kompakt or "").strip() or "(keine)",
-    )
-
-
-def _vermeide_block(vermeide: list[str] | None) -> str:
-    eintraege = [f.strip() for f in (vermeide or []) if f and f.strip()]
-    return "\n".join(f"- {f}" for f in eintraege) or "(keine)"
-
-
-async def pruefung_frage(
-    topic: str, baustein: str, section: str, kompakt: str | None,
-    messages: list[dict], subbausteine: list[str] | None = None,
-    vermeide: list[str] | None = None, provider: str = DEFAULT_PROVIDER,
-) -> str | None:
-    """Aktion 'frage': eine Frage generieren — zufälliger Typ zu einem zufälligen Subbaustein,
-    dann Kritiker (Generator → Kritiker sequenziell) · None bei Fehler."""
-    try:
-        section_block, kompakt_block = _bloecke(section, kompakt)
-        transcript = _transcript(messages) if messages else "(leer)"
-        typ_block = FRAGETYPEN[random.choice(list(FRAGETYPEN))]
-        subs = [s for s in (subbausteine or []) if s and s.strip()]
-        fokus = random.choice(subs) if subs else ""
-        fokus_block = (
-            f"Konzentriere die Frage auf diesen Subbaustein: „{fokus}\"" if fokus
-            else "(ganzer Baustein — kein bestimmter Subbaustein)"
-        )
-        return await _frage_mit_kritik(
-            topic, baustein, section_block, kompakt_block, transcript,
-            _vermeide_block(vermeide), typ_block, fokus_block, provider,
-        )
-    except Exception:
-        log.warning("[%s] Frage fehlgeschlagen (%s)", topic, baustein, exc_info=True)
-        return None
-
-
-async def pruefung_frage_variante(
-    topic: str, baustein: str, section: str, kompakt: str | None,
-    muster: str, provider: str = DEFAULT_PROVIDER,
-) -> str | None:
-    """Aktion 'frage' mit Muster: aus einem vordefinierten Muster eine konkrete, im
-    Wortlaut leicht andere Frage formulieren. Kein Kritiker (Muster ist build-geprüft).
-    Stil-Guard bleibt als billiger Schutz gegen Doppelfragen · None bei Fehler."""
-    try:
-        section_block, kompakt_block = _bloecke(section, kompakt)
-        data = await _gen_call(
-            "Baustein-Frage-Variante", "fast", _frage_schema, provider,
-            topic=topic, baustein=baustein, section_block=section_block,
-            kompakt_block=kompakt_block, muster=muster,
-        )
-        if data is None:
-            return None
-        return data["frage"]
-    except Exception:
-        log.warning("[%s] Frage-Variante fehlgeschlagen (%s)", topic, baustein, exc_info=True)
-        return None
-
-
-def _optionen_schema(opts) -> list[dict] | None:
-    """[{text, korrekt}]×4 → validierte Liste · sonst 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()
-        korrekt = o.get("korrekt")
-        if not text or not isinstance(korrekt, bool):
-            return None
-        out.append({"text": text, "korrekt": korrekt})
-    return out
-
-
-def _quiz_schema(data, schwer: bool = False) -> dict | None:
-    """{"frage": str, "optionen": [{text, korrekt}]×4} → validiert · sonst None.
-    leicht: genau 1 richtig (Single) · schwer: mindestens 2 richtig (mehrdeutig)."""
-    if not isinstance(data, dict):
-        return None
-    frage = str(data.get("frage", "")).strip()
-    out = _optionen_schema(data.get("optionen"))
-    if not frage or out is None:
-        return None
-    n_korrekt = sum(o["korrekt"] for o in out)
-    if (n_korrekt < 2 if schwer else n_korrekt != 1):
-        return None
-    return {"frage": frage, "optionen": out}
-
-
-def _lueckwahl_schema(data) -> dict | None:
-    """{"satz": str (mit ___), "optionen": [{text, korrekt}]×4} → genau 1 korrekt · sonst None."""
-    if not isinstance(data, dict):
-        return None
-    satz = str(data.get("satz", "")).strip()
-    out = _optionen_schema(data.get("optionen"))
-    if not satz or "___" not in satz or out is None or sum(o["korrekt"] for o in out) != 1:
-        return None
-    return {"satz": satz, "optionen": out}
-
-
-async def quiz_generieren(
-    topic: str, baustein: str, section: str, kompakt: str | None,
-    muster: str, schwer: bool = False, provider: str = DEFAULT_PROVIDER,
-) -> dict | None:
-    """Aus einem Muster eine Multiple-Choice-Frage. schwer: 0–4 richtig (Multi).
-    leicht: genau 1 richtig (Single). Starkes Modell (role guide) für korrekte Flags.
-    → {frage, optionen:[{text,korrekt}]} · None bei Fehler."""
-    try:
-        section_block, kompakt_block = _bloecke(section, kompakt)
-        anzahl_block = (
-            "MINDESTENS ZWEI Optionen sind richtig (gern auch drei) — NIEMALS nur eine. Mische bewusst, welche."
-            if schwer else
-            "GENAU EINE Option ist richtig, die anderen drei sind klar falsch."
-        )
-        return await _gen_call(
-            "Baustein-Quiz", "guide", (lambda d: _quiz_schema(d, schwer=schwer)), provider,
-            topic=topic, baustein=baustein, section_block=section_block,
-            kompakt_block=kompakt_block, muster=muster, anzahl_block=anzahl_block,
-        )
-    except Exception:
-        log.warning("[%s] Quiz-Frage fehlgeschlagen (%s)", topic, baustein, exc_info=True)
-        return None
-
-
-async def lueckwahl_generieren(
-    topic: str, baustein: str, section: str, kompakt: str | None,
-    muster: str, provider: str = DEFAULT_PROVIDER,
-) -> dict | None:
-    """Lückentext mit Auswahl (leichte Variante): Satz mit ___ + 4 Begriffe, genau 1 richtig.
-    → {satz, optionen:[{text,korrekt}]} · None bei Fehler."""
-    try:
-        section_block, kompakt_block = _bloecke(section, kompakt)
-        return await _gen_call(
-            "Baustein-Lueckwahl", "guide", _lueckwahl_schema, provider,
-            topic=topic, baustein=baustein, section_block=section_block,
-            kompakt_block=kompakt_block, muster=muster,
-        )
-    except Exception:
-        log.warning("[%s] Lückentext-Auswahl fehlgeschlagen (%s)", topic, baustein, exc_info=True)
-        return None
-
-
-def _lueck_schema(data) -> dict | None:
-    """{"satz": str (mit ___), "loesung": str, "alternativen": [str]} → validiert · sonst None."""
-    if not isinstance(data, dict):
-        return None
-    satz = str(data.get("satz", "")).strip()
-    loesung = str(data.get("loesung", "")).strip()
-    alt = data.get("alternativen", [])
-    if not satz or "___" not in satz or not loesung:
-        return None
-    alternativen = [str(a).strip() for a in alt if isinstance(a, str) and str(a).strip()] if isinstance(alt, list) else []
-    return {"satz": satz, "loesung": loesung, "alternativen": alternativen}
-
-
-async def lueckentext_generieren(
-    topic: str, baustein: str, section: str, kompakt: str | None,
-    muster: str, provider: str = DEFAULT_PROVIDER,
-) -> dict | None:
-    """Aus einem Muster eine Lückentext-Aufgabe (Satz mit ___, Lösung, Synonyme).
-    → {satz, loesung, alternativen} · None bei Fehler."""
-    try:
-        section_block, kompakt_block = _bloecke(section, kompakt)
-        return await _gen_call(
-            "Baustein-Lueckentext", "fast", _lueck_schema, provider,
-            topic=topic, baustein=baustein, section_block=section_block,
-            kompakt_block=kompakt_block, muster=muster,
-        )
-    except Exception:
-        log.warning("[%s] Lückentext-Frage fehlgeschlagen (%s)", topic, baustein, exc_info=True)
-        return None
-
-
-def _norm_begriff(t: str) -> str:
-    return re.sub(r"[^\wäöüß]", "", str(t or "").lower())
-
-
-def _richtig_schema(data) -> dict | None:
-    if not isinstance(data, dict) or not isinstance(data.get("richtig"), bool):
-        return None
-    return {"richtig": data["richtig"]}
-
-
-async def lueckentext_pruefen(
-    topic: str, baustein: str, satz: str, loesung: str, alternativen: list[str],
-    eingabe: str, provider: str = DEFAULT_PROVIDER,
-) -> bool:
-    """Lückentext-Antwort prüfen: erst normalisierter Vergleich (Lösung + Synonyme),
-    sonst 1 KI-Call für Synonym-Toleranz. Fail-open zu RICHTIG nur bei exaktem Match."""
-    if not eingabe.strip():
-        return False
-    norm = _norm_begriff(eingabe)
-    if norm and norm in {_norm_begriff(loesung), *(_norm_begriff(a) for a in alternativen)}:
-        return True
-    data = await _gen_call(
-        "Baustein-Lueckentext-Pruefung", "fast", _richtig_schema, provider,
-        topic=topic, baustein=baustein, satz=satz, loesung=loesung,
-        alternativen=", ".join(alternativen) or "(keine)", eingabe=eingabe,
-    )
-    return bool(data and data["richtig"])
-
-
-async def pruefung_bewertung_schnell(
-    topic: str, baustein: str, section: str, kompakt: str | None,
-    frage: str, messages: list[dict], provider: str = DEFAULT_PROVIDER,
-) -> dict | None:
-    """Aktion 'antwort' (Agent 1, schnell): nur Evaluator, kein Kritiker. → {feedback, niveau}."""
-    try:
-        section_block, kompakt_block = _bloecke(section, kompakt)
-        transcript = _transcript(messages) if messages else "(leer)"
-        return await _gen_call(
-            "Baustein-Bewertung", "judge", _bewertung_schema, provider,
-            topic=topic, baustein=baustein, section_block=section_block, kompakt_block=kompakt_block,
-            frage=frage.strip() or "(keine Frage übergeben)", transcript=transcript,
-            begruendung_block="(keine)", kritik_block="(keine)",
-        )
-    except Exception:
-        log.warning("[%s] Schnell-Bewertung fehlgeschlagen (%s)", topic, baustein, exc_info=True)
-        return None
-
-
-async def pruefung_bewertung(
-    topic: str, baustein: str, section: str, kompakt: str | None,
-    frage: str, messages: list[dict], provider: str = DEFAULT_PROVIDER,
-    role: str = "judge", begruendung: str = "",
-) -> dict | None:
-    """Aktion 'antwort_pruefen' (Agent 2, genau): Evaluator + Kritiker. → {feedback, niveau}.
-
-    `role` = "guide" für „Gründlich prüfen" (starkes Modell). `begruendung` = optionale
-    Unzufriedenheit des Lerners mit einer früheren Bewertung.
-    """
-    try:
-        section_block, kompakt_block = _bloecke(section, kompakt)
-        transcript = _transcript(messages) if messages else "(leer)"
-        begruendung_block = begruendung.strip() or "(keine)"
-        return await _bewertung_mit_kritik(
-            topic, baustein, section_block, kompakt_block,
-            frage.strip() or "(keine Frage übergeben)", transcript, begruendung_block, provider, role,
-        )
-    except Exception:
-        log.warning("[%s] Bewertung fehlgeschlagen (%s)", topic, baustein, exc_info=True)
-        return None
-
-
-async def baustein_diskussion(
-    topic: str, baustein: str, section: str, kompakt: str | None,
-    frage: str, letzte_bewertung: str | None, messages: list[dict], provider: str = DEFAULT_PROVIDER,
-) -> str | None:
-    """Aktion 'diskussion': Tutor erklärt/diskutiert die Frage oder eine Bewertung.
-
-    Kein Bewerten, kein Kritiker — hier ist der Mensch der Prüfer. None bei Fehler.
-    """
-    try:
-        section_block, kompakt_block = _bloecke(section, kompakt)
-        prompt = _prompt(
-            "Baustein-Pruefung-Diskussion",
-            topic=topic, baustein=baustein,
-            section_block=section_block, kompakt_block=kompakt_block,
-            frage=frage.strip() or "(keine Frage übergeben)",
-            letzte_bewertung_block=(letzte_bewertung or "").strip() or "(noch keine)",
-            transcript=_transcript(messages) if messages else "(leer)",
-        )
-        returncode, stdout, _ = await run_agent(
-            "pruefungdiskussion-" + 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] Prüfungs-Diskussion fehlgeschlagen (%s)", topic, baustein, exc_info=True)
-        return None
-
-
-async def baustein_element_anlegen(topic: str, baustein: str, section: str, provider: str = DEFAULT_PROVIDER) -> None:
-    """Hintergrund-Task nach dem Absolvieren: Baustein als Element anlegen.
-
-    Dedup über normalisierte Titel — existiert schon ein Element zum Baustein,
-    passiert nichts. Darf nie eine Exception nach außen werfen.
-    """
-    try:
-        vorhanden = {_norm_titel(e["title"]) for e in await list_elements(topic)}
-        if _norm_titel(baustein) in vorhanden:
-            return
-        fields = await generate_element(topic, hint=baustein, provider=provider, extra_context=section)
-        if _norm_titel(fields["title"]) in vorhanden:
-            return
-        now = datetime.now(timezone.utc).isoformat()
-        await create_element({"id": str(uuid.uuid4()), "topic": topic, **fields, "created_at": now, "updated_at": now})
-        log.info("[%s] Baustein als Element angelegt: %s", topic, fields["title"])
-    except Exception:
-        log.warning("[%s] Element-Anlage nach Prüfung fehlgeschlagen (%s)", topic, baustein, exc_info=True)

backend/lesbarkeit.py

@@ -1,115 +0,0 @@
-"""Deterministisches Lesbarkeits-Gate für Guide-Sections.
-
-Ein kleines deutsches Komplexitäts-Modell (DistilBERT, GermEval 2022, Skala 1–7)
-bewertet die Verständlichkeit der Fließtext-Prosa. guide.py meldet zu schwere
-Sections in die bestehende Lese-Prüfungs-/Überarbeitungs-Schleife — kein Prompt,
-kein Raten.
-
-Optional: fehlen `transformers`/`torch` oder lädt das Modell nicht, ist das Gate
-stumm deaktiviert (das Backend läuft unverändert weiter). CPU genügt; der Aufrufer
-wrappt die Bewertung in `asyncio.to_thread` (blockierende Modell-Inferenz).
-"""
-
-import logging
-import re
-
-from config import (
-    LESBARKEIT_AKTIV, LESBARKEIT_HART, LESBARKEIT_HART_ANTEIL, LESBARKEIT_MAX, LESBARKEIT_MODELL,
-)
-
-log = logging.getLogger("creator.lesbarkeit")
-
-_modell_cache = None      # (tokenizer, model, torch) — Singleton
-_ladeversuch = False      # schon versucht zu laden?
-
-# Markup raus → reiner Fließtext (Code zählt nicht zur Lesbarkeit).
-_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+")
-_SATZ = re.compile(r"(?<=[.!?])\s+")
-
-
-def _modell():
-    """Lädt das Modell einmalig. None = Gate aus (deaktiviert oder Lade-Fehler)."""
-    global _modell_cache, _ladeversuch
-    if _ladeversuch:
-        return _modell_cache
-    _ladeversuch = True
-    if not LESBARKEIT_AKTIV:
-        return None
-    try:
-        import torch
-        from transformers import AutoModelForSequenceClassification, AutoTokenizer
-        tok = AutoTokenizer.from_pretrained(LESBARKEIT_MODELL)
-        model = AutoModelForSequenceClassification.from_pretrained(LESBARKEIT_MODELL)
-        model.eval()
-        _modell_cache = (tok, model, torch)
-        log.info("Lesbarkeits-Modell geladen: %s (num_labels=%d)", LESBARKEIT_MODELL, model.config.num_labels)
-    except Exception as e:
-        log.warning("Lesbarkeits-Gate deaktiviert (Modell nicht ladbar): %s", e)
-        _modell_cache = None
-    return _modell_cache
-
-
-def _prosa(md: str) -> str:
-    """Markdown/Code strippen → reiner Fließtext für die Bewertung."""
-    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 _saetze(text: str) -> list[str]:
-    """Fließtext in Sätze splitten; sehr kurze Fragmente verwerfen."""
-    return [s.strip() for s in _SATZ.split(text) if len(s.strip()) >= 15]
-
-
-def _scores(saetze: list[str]) -> list[float]:
-    """Komplexität je Satz (1–7). Regression (num_labels=1) oder Erwartungswert über Klassen."""
-    tok, model, torch = _modell_cache
-    werte: list[float] = []
-    n = model.config.num_labels
-    for i in range(0, len(saetze), 16):
-        batch = saetze[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)
-            stufen = torch.arange(1, n + 1, dtype=probs.dtype)
-            vals = (probs * stufen).sum(-1).reshape(-1).tolist()
-        werte.extend(vals)
-    return werte
-
-
-def bewerte_sections(md_by_num: dict[int, str]) -> dict[int, str]:
-    """{num: section_md} → {num: Hinweis} nur für zu schwere Sections.
-
-    Leeres dict, wenn das Gate aus ist. Blockierend (CPU) — in to_thread aufrufen.
-    """
-    if _modell() is None:
-        return {}
-    out: dict[int, str] = {}
-    for num, md in md_by_num.items():
-        saetze = _saetze(_prosa(md or ""))
-        if len(saetze) < 2:  # fast nur Code / zu kurz → überspringen
-            continue
-        werte = _scores(saetze)
-        if not werte:
-            continue
-        schnitt = sum(werte) / len(werte)
-        hart = sum(1 for w in werte if w > LESBARKEIT_HART) / len(werte)
-        # Zu schwer = hoher Schnitt ODER zu viele harte Einzelsätze (Ausreißer-Nester).
-        if schnitt > LESBARKEIT_MAX or hart >= LESBARKEIT_HART_ANTEIL:
-            out[num] = (
-                f"Zu schwer lesbar (Ø {schnitt:.1f}/7, {hart * 100:.0f}% harte Sätze): "
-                "kürzere Sätze, einfachere Wörter, weniger Schachtelsätze, mehr Beispiele."
-            )
-    return out

backend/logsetup.py

@@ -1,4 +1,4 @@
-"""Zentrales Logging-Setup — einmal in main.py aufrufen, bevor die App entsteht."""
+"""Central logging setup — call once in main.py before the app is created."""
 
 import logging
 import os

backend/main.py

@@ -2,12 +2,15 @@ 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
@@ -15,16 +18,32 @@ 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

@@ -17,69 +17,118 @@ class GuideCreateRequest(BaseModel):
     format: FormatType
     instructions: str = Field(default="", max_length=2000)
     provider: ProviderType = "claude"
-    ab_step: int | None = Field(default=None, ge=0, le=4)  # Re-Run ab Guide-Schritt (0 Gliederung … 4 Lese-Prüfung); None = voll/Resume
+    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"
     source_type: SourceType = "thema"
-    source_ort: str = Field(default="", max_length=2000)
-    ab_phase: int | None = Field(default=None, ge=1, le=6)  # Re-Run ab grober Phase (Position in _phasen(topic), 1-based); None = Resume/Fortsetzen ohne Löschen
+    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] = []
-
-
-class ProjectResponse(BaseModel):
-    name: str
+    steps: list[BlocksStep] = []
+    feine_steps: list[BlocksFineStep] = []
 
 
 class FolderResponse(BaseModel):
     name: str
-    ort: str  # relativer Pfad ab Repo-Root (z.B. "projects/foo")
+    location: str  # path relative to the repo root (e.g. "projects/foo")
 
 
-class BausteineQuelleUpdate(BaseModel):
+class BlocksSourceUpdate(BaseModel):
     topic: str = Field(min_length=1, max_length=100)
     type: SourceType = "thema"
-    ort: str = Field(default="", max_length=2000)
+    location: str = Field(default="", max_length=2000)
     spec: str = Field(default="", max_length=2000)
 
 
-class BausteineQuelleResponse(BaseModel):
+class BlocksSourceResponse(BaseModel):
     type: SourceType
-    ort: str
+    location: str
     spec: str
 
 
-class SubbausteinInfo(BaseModel):
-    titel: str
-    stufe: Literal["einfach", "mittel", "schwer"]
-    relevanz: Literal["relevant", "rand"] | None = None
+class SubblockInfo(BaseModel):
+    title: str
+    level: Literal["beginner", "advanced", "expert", "easy", "medium", "hard"]
+    relevance: Literal["relevant", "peripheral"] | None = None
 
 
-class BausteinUebersicht(BaseModel):
+class BlockOverview(BaseModel):
     num: int
-    titel: str
-    beschreibung: str = ""
-    subbausteine: list[SubbausteinInfo] = []
+    title: str
+    description: str = ""
+    subblocks: list[SubblockInfo] = []
 
 
 class ProviderInfo(BaseModel):
@@ -115,156 +164,104 @@ class GuideChatResponse(BaseModel):
     reply: str
 
 
-class ElementResponse(BaseModel):
-    id: str
-    topic: str
-    title: str
-    description: str = ""
-    examples: list[str] = []
-    hints: list[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
-
-
-class ElementCheckRequest(BaseModel):
-    provider: ProviderType = "claude"
-
-
-class ElementSuggestion(BaseModel):
-    text: str
-    target: Literal["description", "examples", "hints"]
-    content: str
-
-
-class ElementCheckResponse(BaseModel):
-    suggestions: list[ElementSuggestion]
-
-
-class ElementStyleChange(BaseModel):
-    text: str
-    action: Literal["entfernen", "anpassen", "hinzufuegen"]
-    target: Literal["title", "description", "examples", "hints"]
-    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"
 
 
-class ElementChatResponse(BaseModel):
-    reply: str
-    changes: list[ElementStyleChange] = []
-
-
-class ElementRefineRequest(BaseModel):
-    suggestion: ElementStyleChange
-    instruction: str = Field(min_length=1, max_length=2000)
-    provider: ProviderType = "claude"
-
-
-class ElementRefineResponse(BaseModel):
-    change: ElementStyleChange
-
-
-class ProgressUpdate(BaseModel):
-    chapter: str = Field(min_length=1, max_length=100)
-    done: bool
-
-
-class ProgressResponse(BaseModel):
-    chapters: list[str]
-
-
-# --- Baustein-Lernen ---
-
-class BausteinChatRequest(BaseModel):
-    topic: str = Field(min_length=1, max_length=100)
-    baustein: str = Field(min_length=1, max_length=200)
-    section: str = Field(default="", max_length=20000)         # ausführliche Fassung
-    section_kompakt: str = Field(default="", max_length=20000)  # kompakte Fassung (Merksätze)
-    messages: list[ChatMessage] = Field(min_length=1)
-    provider: ProviderType = "claude"
-
-
-class BausteinChatResponse(BaseModel):
+class BlockChatResponse(BaseModel):
     reply: str
 
 
-class BausteinPruefungRequest(BaseModel):
+class BlockExamRequest(BaseModel):
     topic: str = Field(min_length=1, max_length=100)
-    baustein: str = Field(min_length=1, max_length=200)
-    section: str = Field(default="", max_length=20000)         # ausführliche Fassung
-    section_kompakt: str = Field(default="", max_length=20000)  # kompakte Fassung (Merksätze)
-    aktion: Literal[
-        "frage", "diskussion", "antwort", "antwort_pruefen",
-        "quiz_frage", "quiz_antwort", "lueck_frage", "lueck_antwort",
-    ] = "frage"
-    frage: str = Field(default="", max_length=2000)  # aktuell geprüfte Frage (für diskussion/antwort); Anker der Basis
-    auswahl: list[int] = []  # Quiz/Lückentext-Auswahl: vom Lerner gewählte Options-Indizes
-    korrekt: list[int] = []  # Quiz/Lückentext-Auswahl: korrekte Indizes (Client hält sie aus der Generierung)
-    loesung: str = Field(default="", max_length=500)  # Lückentext frei: erwarteter Begriff
-    alternativen: list[str] = []  # Lückentext frei: akzeptierte Synonyme
-    eingabe: str = Field(default="", max_length=500)  # Lückentext frei: getippter Begriff
-    schwer: bool = False  # Variante: leicht (+1/−1) vs schwer (+3/−1)
-    letzte_bewertung: str = Field(default="", max_length=2000)  # Feedback der letzten Bewertung (Kontext für diskussion)
-    vermeide: list[str] = []  # schon gestellte + vorgemerkte Fragen — sinngemäß nicht wiederholen
-    nachgefragt: bool = False  # für diese Frage wurde nachgefragt → Gewinn auf +1 gedeckelt
-    begruendung: str = Field(default="", max_length=2000)  # „Gründlich prüfen": warum mit der Bewertung unzufrieden
-    muster: str = Field(default="", max_length=2000)  # gezogenes Frage-Muster (Saat); leer → Live-Generierung (Fallback)
-    # Basis wird serverseitig je Frage geführt (offene_frage-Anker) — nicht mehr vom Client.
-    cap: int = Field(default=6, ge=6, le=30)  # Score-Deckel = Max des höchsten erstellten Formats (6/12/18/30)
-    messages: list[ChatMessage] = []  # Dialog bisher; leer = erste Frage
+    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 = "claude"
-    gruendlich: bool = False  # „Gründlich prüfen": Bewertung mit starkem Modell (role guide)
+    thorough: bool = False  # "thorough check": rating with a strong model (role guide)
 
 
 class QuizOption(BaseModel):
     text: str
-    korrekt: bool
+    correct: bool
 
 
-class BausteinPruefungResponse(BaseModel):
-    frage: str | None = None
+class BlockExamResponse(BaseModel):
+    question: str | None = None
     reply: str | None = None
     feedback: str | None = None
-    punkte: int | None = None  # Punkt-Delta dieser Antwort (−2 … +3); schnell = voraussichtlich
-    bewertung: Literal["gut", "neutral", "schlecht"] | None = None  # aus Vorzeichen, fürs Einfärben
-    optionen: list[QuizOption] | None = None  # Quiz: 4 Optionen + Korrekt-Flags
-    satz: str | None = None  # Lückentext: Satz mit Lücke (___)
-    loesung: str | None = None  # Lückentext: erwarteter Begriff
-    alternativen: list[str] | None = None  # Lückentext: akzeptierte Synonyme
-    gute_antworten: int
-    absolviert: bool
-    verstanden: bool = False
-    gemeistert: bool = False
+    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 BausteinLernstand(BaseModel):
-    gute_antworten: int
+class BlockLearnState(BaseModel):
+    good_answers: int
     streak: int = 0
-    absolviert: bool
-    verstanden: bool
-    gemeistert: bool
+    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 BausteinLernstandResponse(BaseModel):
-    bausteine: dict[str, BausteinLernstand]
+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 = "claude"
+
+
+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 = "claude"
+
+
+class BlockUebernehmenResponse(BaseModel):
+    compact: str
+    md: str
+    found: bool

backend/paths.py

@@ -2,7 +2,7 @@ from pathlib import Path
 
 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,42 +10,42 @@ 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 subbausteine_path(topic: str) -> Path:
-    """Sidecar: pro Baustein die Subbausteine mit Stufe (von allen Guides geteilt)."""
-    return topic_dir(topic) / "subbausteine.json"
+def subblocks_path(topic: str) -> Path:
+    """Sidecar: the subblocks with level per block (shared by all guides)."""
+    return topic_dir(topic) / "subblocks.json"
 
 
-def frage_muster_path(topic: str) -> Path:
-    """Sidecar: pro Baustein vordefinierte Frage-Muster (Subbaustein × Typ → Beispielfrage)."""
-    return topic_dir(topic) / "frage_muster.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 quelle_path(topic: str) -> Path:
-    """Persistierte Quellen-Wahl pro Thema: {type, ort, spec}."""
-    return topic_dir(topic) / "quelle.json"
+def source_path(topic: str) -> Path:
+    """Persisted source choice per topic: {type, location, spec}."""
+    return topic_dir(topic) / "source.json"
 
 
-def quelle_crawl_dir(topic: str) -> Path:
-    """Zielordner für gecrawlte Link-Quellen (Seiten + PDF-.txt)."""
-    return topic_dir(topic) / "quelle"
+def source_crawl_dir(topic: str) -> Path:
+    """Target folder for crawled link sources (pages + PDF .txt)."""
+    return topic_dir(topic) / "source"
 
 
-def safe_ordner(ort: str) -> Path | None:
-    """Ordnerpfad relativ zum Repo-Root, gesandboxt. None bei leer/Ausbruch (../, absolut außerhalb)."""
-    if not ort or not ort.strip():
+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 / ort.strip()).resolve()
+    p = (PROJECT_ROOT / location.strip()).resolve()
     try:
         p.relative_to(PROJECT_ROOT)
     except ValueError:
@@ -57,11 +57,11 @@ 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

@@ -1,8 +1,8 @@
-"""Pipeline-Grundbausteine: Agent-Races (mit Grace), Single-Slot, Schemata, Prompts, Guide-Status.
+"""Pipeline building blocks: agent races (with grace), single-slot, schemas, prompts, guide status.
 
-Hält den mutablen Pipeline-Zustand (Generierungs-Semaphore, Cancel-Set).
-Zugriff auf das Cancel-Set NUR über die Funktionen hier — kopierte Referenzen
-in anderen Modulen würden bei einem Re-Assign auseinanderlaufen.
+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
@@ -15,7 +15,7 @@ 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_datei
+from jsonio import read_json_file as _json_file
 from textkit import _STUFEN
 
 log = logging.getLogger("creator.pipeline")
@@ -26,10 +26,10 @@ _cancelled: set[str] = set()
 
 async def cancel_guide(guide_id: str) -> bool:
     _cancelled.add(guide_id)
-    cancel_scope(f"{guide_id}-")  # wartende Agenten bailen vorm Spawn
-    kill_process(guide_id)        # laufende Subprozesse killen
+    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="Abgebrochen — Fortschritt bleibt erhalten", updated_at=now)
+    await update_guide(guide_id, status="error", progress=None, error_msg="Cancelled — progress is preserved", updated_at=now)
     return True
 
 
@@ -39,7 +39,7 @@ def is_guide_cancelled(guide_id: str) -> bool:
 
 def clear_guide_cancelled(guide_id: str) -> None:
     _cancelled.discard(guide_id)
-    clear_scope(f"{guide_id}-")  # Scope leeren → Neustart blockiert nicht
+    clear_scope(f"{guide_id}-")  # clear scope → restart not blocked
 
 
 async def _set_progress(guide_id: str, progress: str) -> None:
@@ -63,7 +63,7 @@ def _prompt(name: str, **kwargs) -> str:
 
 
 def _extra(instructions: str) -> str:
-    return f"\n\nZUSÄTZLICHE ANWEISUNGEN VOM NUTZER:\n{instructions}\n" if instructions else ""
+    return f"\n\nADDITIONAL INSTRUCTIONS FROM THE USER:\n{instructions}\n" if instructions else ""
 
 
 def _log(topic: str, msg: str) -> None:
@@ -76,8 +76,8 @@ def _claude_error(label: str, returncode: int, stdout: str, stderr: str) -> str:
         return f"{label}: {stderr[:1000]}"
     tail = (stdout or "").strip()[-500:]
     if tail:
-        return f"{label} (exit {returncode}, stderr leer): …{tail}"
-    return f"{label} (exit {returncode}, ohne Ausgabe)"
+        return f"{label} (exit {returncode}, stderr empty): …{tail}"
+    return f"{label} (exit {returncode}, no output)"
 
 
 def _gather_error(label: str, results: list) -> str:
@@ -87,7 +87,7 @@ def _gather_error(label: str, results: list) -> str:
         returncode, stdout, stderr = r
         if returncode != 0:
             return _claude_error(label, returncode, stdout, stderr)
-    return f"{label}: kein verwertbares Ergebnis"
+    return f"{label}: no usable result"
 
 
 def _timeout(step: str, n: int = 0) -> int:
@@ -95,124 +95,112 @@ def _timeout(step: str, n: int = 0) -> int:
     return base + per * n
 
 
-def _probleme_schema(data):
-    """{"ok": true} → [] · {"probleme": [str]} → Liste · sonst None."""
+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("probleme")
+    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_liste(val) -> list[str] | None:
-    """Liste nicht-leerer Strings → gestrippte Liste (leer erlaubt) · sonst 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 _rest_schema(data):
-    """{"uebernehmen": [str]} → Liste (leer erlaubt) · sonst None."""
-    if not isinstance(data, dict):
-        return None
-    return _str_liste(data.get("uebernehmen"))
 
 
 def _runde_schema(data, final: bool = False):
-    """{"aufnehmen": [str], "rest": [str]} → (aufnehmen, rest) · sonst None.
+    """{"keep": [str], "rest": [str]} → (include, rest) · else None.
 
-    final=True: letzte Klärungs-Runde — ein nicht-leerer Rest ist ungültig.
+    final=True: last clarification round — a non-empty rest is invalid.
     """
     if not isinstance(data, dict):
         return None
-    aufnehmen = _str_liste(data.get("aufnehmen"))
-    rest = _str_liste(data.get("rest"))
-    if aufnehmen is None or rest is None or (final and rest):
+    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 aufnehmen, rest
+    return include, rest
 
 
-def _stufen_schema(data, ids: set[int] | None = None):
-    """{"stufen": {"1": "einfach", …}} → {id: stufe} · sonst None.
+_RELEVANCE = ("relevant", "peripheral")
+_YESNO = ("ja", "nein")
 
-    Stufe ∈ {einfach, mittel, schwer}. Sind `ids` gegeben, müssen mindestens
-    diese abgedeckt sein (Extras erlaubt); der Aufrufer filtert dann auf `ids`.
-    """
-    if not isinstance(data, dict) or not isinstance(data.get("stufen"), dict) or not data["stufen"]:
+
+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["stufen"].items():
+        for k, v in data[key].items():
             try:
                 num = int(k)
             except (ValueError, TypeError):
                 return None
-        stufe = str(v).strip().casefold()
-        if stufe not in _STUFEN:
+            value = str(v).strip().casefold()
+            if value not in allowed:
                 return None
-        out[num] = stufe
+            out[num] = value
         if ids is not None and not ids <= set(out):
             return None
         return out
+    return parse
 
 
-_RELEVANZ = ("relevant", "rand")
+_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
 
 
-def _relevanz_schema(data, ids: set[int] | None = None):
-    """{"relevanz": {"1": "relevant", …}} → {id: relevanz} · sonst None.
-
-    Relevanz ∈ {relevant, rand} (binär). Wie `_stufen_schema`: sind `ids` gegeben,
-    müssen mindestens diese abgedeckt sein (Extras erlaubt).
-    """
-    if not isinstance(data, dict) or not isinstance(data.get("relevanz"), dict) or not data["relevanz"]:
-        return None
-    out: dict[int, str] = {}
-    for k, v in data["relevanz"].items():
-        try:
-            num = int(k)
-        except (ValueError, TypeError):
-            return None
-        wert = str(v).strip().casefold()
-        if wert not in _RELEVANZ:
-            return None
-        out[num] = wert
-    if ids is not None and not ids <= set(out):
-        return None
-    return out
+from config import MAX_RESTARTS as _MAX_RESTARTS  # noqa: E402 — zentral tunebar
 
 
-_MAX_RESTARTS = 2
+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) -> 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).
 
-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) -> list | None:
-    """Startet alle Slots parallel und sammelt `quorum` gültige Ergebnisse.
+    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.
 
-    Slot-Spec: {key, prompt, role, capabilities, payload}. `payload(result)`
-    prüft die Gültigkeit und liefert das Slot-Ergebnis oder None.
-    Fehler/Timeout/ungültig → Slot-Neustart (max. _MAX_RESTARTS). Sobald das
-    Quorum steht, werden die übrigen Agenten gekillt. None = Quorum verfehlt.
-    `cancelled()` → True bricht ab (keine Restarts, Rückgabe None).
-
-    Mit `grace` wird `quorum` zum Minimum: Das erste gültige Ergebnis startet
-    einen Timer von `grace` Sekunden. Nach dessen Ablauf werden laufende
-    Agenten nur gekillt, wenn das Minimum steht — sonst läuft das Race samt
-    Restarts weiter, bis es steht. Rückgabe: `quorum` bis `len(slots)` Ergebnisse.
+    `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.
     """
     attempts = {i: 0 for i in range(len(slots))}
     tasks: dict[asyncio.Task, int] = {}
     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) -> None:
         slot = slots[i]
+        lbl = slot.get("label") or (label if len(slots) == 1 else f"{label} {i + 1}")
         task = asyncio.create_task(run_agent(
             slot["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
 
@@ -224,12 +212,22 @@ async def _race(topic: str, label: str, slots: list[dict], quorum: int, timeout:
         while tasks:
             if cancelled and cancelled():
                 return None
-            if deadline is not None and len(results) >= quorum and loop.time() >= deadline:
+            # 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:
                 return results
-            # Grace gesetzt und Minimum erreicht → nur bis zum Deadline-Rest warten
-            wait_timeout = None
+            # Wake up for the earliest relevant deadline (grace, min, or max).
+            waits = []
             if deadline is not None and len(results) >= quorum:
-                wait_timeout = max(0.0, deadline - loop.time())
+                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())
+            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
@@ -239,13 +237,13 @@ async def _race(topic: str, label: str, slots: list[dict], quorum: int, timeout:
                 try:
                     result = task.result()
                     if result[0] != 0:
-                        err = _claude_error("Fehler", *result)
+                        err = _claude_error("Error", *result)
                     else:
                         payload = slots[i]["payload"](result)
                         if payload is None:
-                            err = "Ergebnis ungültig/nicht parsebar"
+                            err = "result invalid/not parseable"
                 except asyncio.TimeoutError:
-                    err = f"Timeout nach {timeout}s"
+                    err = f"Timeout after {timeout}s"
                 except Exception as e:
                     err = f"{type(e).__name__}: {e}"
 
@@ -253,23 +251,24 @@ async def _race(topic: str, label: str, slots: list[dict], quorum: int, timeout:
                     results.append(payload)
                     if grace is not None and deadline is None:
                         deadline = loop.time() + grace
-                        _log(topic, f"{label}: erstes Ergebnis — Grace {grace}s läuft")
+                        _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):
+                    if (len(results) >= quorum and (grace is None or loop.time() >= deadline)
+                            and (min_deadline is None or loop.time() >= min_deadline)):
                         return results
                     continue
 
-                _log(topic, f"{label} {i + 1} (Versuch {attempts[i] + 1}): {err}")
+                _log(topic, f"{label} {i + 1} (attempt {attempts[i] + 1}): {err}")
                 attempts[i] += 1
-                # Steht das Minimum schon, sind Restarts sinnlos — der Neustart
-                # würde am Grace-Ende ohnehin gekillt.
-                satt = grace is not None and len(results) >= quorum
-                if attempts[i] <= _MAX_RESTARTS and not satt and not (cancelled and cancelled()):
+                # If the minimum already stands, restarts are pointless — the restart
+                # would be killed at the grace end anyway.
+                enough = grace is not None and len(results) >= quorum
+                if attempts[i] <= _MAX_RESTARTS and not enough and not (cancelled and cancelled()):
                     spawn(i)
-        if len(results) >= quorum:  # alle Slots durch, Minimum steht (nur mit grace erreichbar)
+        if len(results) >= quorum:  # all slots done, minimum stands (only reachable with grace)
             return results
-        _log(topic, f"{label}: Quorum {quorum} nicht erreicht ({len(results)} gültig)")
+        _log(topic, f"{label}: quorum {quorum} not reached ({len(results)} valid)")
         return None
     finally:
         for task, i in tasks.items():
@@ -281,26 +280,26 @@ async def _race(topic: str, label: str, slots: list[dict], quorum: int, timeout:
 
 @dataclass
 class GenContext:
-    """Durchgereichte Pipeline-Parameter — erspart lange Argument-Signaturen."""
+    """Pipeline parameters passed through — saves long argument signatures."""
     topic: str
     provider: str
     is_cancelled: Callable[[], bool]
     guide_id: str | None = None
 
 
-# Ergebnis-Status von run_single_slot
+# 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,
+    key: str, prompt: str, role: str, capabilities: str, payload, timeout: int, on_line=None,
 ) -> tuple[str, object]:
-    """Ein Agent, ein gültiges Ergebnis (Race mit Quorum 1).
+    """One agent, one valid result (race with quorum 1).
 
-    → (OK, wert) | (CANCELLED, None) | (FAILED, None)
+    → (OK, value) | (CANCELLED, None) | (FAILED, None)
     """
-    slots = [{"key": key, "prompt": prompt, "role": role, "capabilities": capabilities, "payload": payload}]
+    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
@@ -309,9 +308,9 @@ async def run_single_slot(
     return OK, res[0]
 
 
-async def _gather_fortschritt(coros, total, melde, start=0):
-    """Läuft `coros` nebenläufig und meldet Live-Fortschritt: `await melde(fertig, total)`
-    nach jedem Abschluss (und einmal initial). Ergebnisse in Reihenfolge, return_exceptions=True."""
+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):
@@ -320,9 +319,7 @@ async def _gather_fortschritt(coros, total, melde, start=0):
             return await c
         finally:
             done += 1
-            await melde(done, total)
+            await report(done, total)
 
-    await melde(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,456 @@
+"""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 ──────────────────────────────────────────────────────────────────────────
+
+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
+
+    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, "?")
+    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"]
+
+    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
+            quoten_art["sub_dubletten"] = round(sum(1 for p in sd if p.get("llm") == "ja") / 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 {}),
+        "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
+
+
+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, _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/regeln.py

@@ -1,140 +0,0 @@
-"""Lernschulden-Regeln: Progression und Deckel für offene Guides — die EINZIGE Quelle.
-
-Regeln (nur Neu-Erstellungen; Themen + Bausteine unbegrenzt):
-- Format „Guide": höchstens 3 erstellte, nicht absolvierte Guides
-- Keine Progression/Vorstufe mehr (nur ein Guide-Format).
-- Absolviert: ALLE Bausteine (Section-Titel) des neuesten fertigen Guides haben
-  eine bestandene Prüfung. Rest ist read-only (kein Fortschritt, keine Prüfung).
-Alle Funktionen arbeiten auf einmal geladenen Daten (lade_lernstand) — keine
-Query-Schleifen mehr pro Guide.
-"""
-
-import json
-
-from database import list_baustein_levels_all, list_guides, list_progress_all
-from guide import guide_slot_dateien
-from paths import bausteine_path, guide_content_path
-from textkit import _norm_titel
-
-MAX_OFFENE_GUIDES = 3
-# Nur noch EIN Format „Guide" (alle relevanten Bausteine, Prüfung 0–30). Keine Progression,
-# keine Vorstufe → der Guide ist immer freischaltbar. „Rest"/FullGuide separat.
-VORSTUFE: dict[str, str] = {}
-FREISCHALT_LEVEL: dict[str, str] = {}
-FORMATE = ("Guide",)
-
-# Geforderter Score je Freischalt-Niveau — nur für die Sperr-Meldung.
-_LEVEL_WORT = {
-    "absolviert": "absolvieren (alle Bausteine auf 6)",
-    "verstanden": "verstehen (alle Bausteine auf 12)",
-    "gemeistert": "meistern (alle Bausteine auf 18)",
-}
-
-
-async def lade_lernstand() -> tuple[list[dict], dict[str, set[str]], dict[str, dict[str, set[str]]]]:
-    """Guides + Kapitel-Fortschritt + Bausteine je Meilenstein.
-
-    levels: {"absolviert"/"verstanden"/"gemeistert": {topic → normalisierte Titel}}.
-    """
-    roh = await list_baustein_levels_all()
-    levels = {
-        stufe: {topic: {_norm_titel(b) for b in titel} for topic, titel in pro_topic.items()}
-        for stufe, pro_topic in roh.items()
-    }
-    return await list_guides(), await list_progress_all(), 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 _kapitel_titel(topic: str, fmt: str) -> set[str] | None:
-    content = _content_json(topic, fmt)
-    if content is None:
-        return None
-    return {c.get("title") for c in content.get("chapters", [])}
-
-
-def _section_titel(topic: str, fmt: str) -> set[str] | None:
-    """Normalisierte Baustein-Titel (Sections) aus dem Guide-Content."""
-    content = _content_json(topic, fmt)
-    if content is None:
-        return None
-    return {
-        _norm_titel(s.get("title", ""))
-        for ch in content.get("chapters", [])
-        for s in ch.get("sections", [])
-    }
-
-
-def _neueste_done(guides: list[dict], fmt: str) -> dict[str, dict]:
-    """Pro Thema der neueste fertige Guide dieses Formats."""
-    neueste: dict[str, dict] = {}
-    for g in guides:
-        if g["format"] == fmt and g["status"] == "done":
-            if g["topic"] not in neueste or g["created_at"] > neueste[g["topic"]]["created_at"]:
-                neueste[g["topic"]] = g
-    return neueste
-
-
-def _guide_alle(g: dict, progress: dict[str, set[str]], levelset: dict[str, set[str]]) -> bool:
-    """Sind ALLE Bausteine des Guides auf dem geforderten Niveau?"""
-    sections = _section_titel(g["topic"], g["format"])
-    return bool(sections) and sections <= levelset.get(g["topic"], set())
-
-
-def ist_level(topic: str, fmt: str, guides: list[dict], progress: dict[str, set[str]], levelset: dict[str, set[str]]) -> bool:
-    """Neuester fertiger Guide (Thema+Format): alle Bausteine auf dem Niveau von levelset?"""
-    g = _neueste_done(guides, fmt).get(topic)
-    return g is not None and _guide_alle(g, progress, levelset)
-
-
-def ist_absolviert(topic: str, fmt: str, guides: list[dict], progress: dict[str, set[str]], levels: dict[str, dict[str, set[str]]]) -> bool:
-    """Alle Bausteine des neuesten fertigen Guides absolviert (≥3)?"""
-    return ist_level(topic, fmt, guides, progress, levels["absolviert"])
-
-
-def thema_abgeschlossen(topic: str, guides: list[dict], progress: dict[str, set[str]], levels: dict[str, dict[str, set[str]]]) -> bool:
-    """Thema fertig: neuester fertiger Guide, alle Bausteine gemeistert (18)?"""
-    return ist_level(topic, "Guide", guides, progress, levels["gemeistert"])
-
-
-def formate_stats(guides: list[dict], progress: dict[str, set[str]], levels: dict[str, dict[str, set[str]]]) -> dict:
-    """Pro Format erstellt/absolviert — pro Thema zählt nur der neueste fertige Guide."""
-    formate = {}
-    for fmt in FORMATE:
-        neueste = _neueste_done(guides, fmt)
-        absolviert = sum(1 for g in neueste.values() if _guide_alle(g, progress, levels["absolviert"]))
-        formate[fmt] = {"erstellt": len(neueste), "absolviert": absolviert}
-    return formate
-
-
-def guide_lock(topic: str, fmt: str, guides: list[dict], progress: dict[str, set[str]], levels: dict[str, dict[str, set[str]]]) -> str | None:
-    """Grund, warum ein Neu-Start für Thema+Format gesperrt ist — None = erlaubt.
-
-    Exakt die Regeln aus POST /guides: Bausteine nötig, kein Duplikat-Start,
-    Lernschulden nur für echte Neu-Erstellungen (Resume/Regenerieren frei).
-    """
-    if not bausteine_path(topic).exists():
-        return "Erst Bausteine erstellen"
-    for g in guides:
-        if g["topic"] == topic and g["format"] == fmt and g["status"] in ("queued", "generating"):
-            return "Generierung läuft bereits"
-    content = guide_content_path(topic, fmt)
-    if not content.exists() and not guide_slot_dateien(content):
-        vorstufe = VORSTUFE.get(fmt)
-        if vorstufe:
-            stufe = FREISCHALT_LEVEL[fmt]  # absolviert=10 · verstanden=20 · gemeistert=30
-            if not ist_level(topic, vorstufe, guides, progress, levels[stufe]):
-                return f"Erst den {vorstufe} dieses Themas {_LEVEL_WORT[stufe]}"
-        stat = formate_stats(guides, progress, levels).get(fmt, {"erstellt": 0, "absolviert": 0})
-        offen = stat["erstellt"] - stat["absolviert"]
-        if offen >= MAX_OFFENE_GUIDES:
-            return f"Erst {fmt}s absolvieren — maximal {MAX_OFFENE_GUIDES} offene erlaubt ({offen} offen)"
-    return None

backend/repair.py

@@ -0,0 +1,324 @@
+"""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 asyncio
+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 = await _merge_sub_dubletten(topic, report, files)
+    entfernt = 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 asyncio.to_thread(qa._write_report, neu)
+    return {"hygiene": hygiene, "merges": merges, "sub_merges": sub_merges, "entfernt": entfernt,
+            "aufgeraeumt": aufgeraeumt, "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
+
+
+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 = await _judge("QA-Dubletten", topic, "dubletten", "pairs",
+                     [f"A: {p['a']}\nB: {p['b']}" for p in paare])
+    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 _merge_sub_dubletten(topic: str, report: dict, files: dict) -> 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 = await _judge("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])
+    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 db.set_subblock_fields(topic, lose["block_norm"], lose["sub_norm"], status="variant")
+        gone.add(lk)
+        # Fragen/Artefakte des Verlierers: umhängen, wenn der Gewinner den Typ nicht hat
+        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"])
+        merged.append(f"{lose['sub_title'][:40]} → {win['sub_title'][:40]}")
+    return merged
+
+
+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) -> list[str]:
+    out = []
+    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 = await _judge("QA-Repair-Beleg", topic, "fremd", "blocks", lines)
+        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 = await _judge("QA-Bausteine", topic, "unecht", "blocks", lines)
+        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
+
+
+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

@@ -2,6 +2,8 @@ fastapi
 uvicorn[standard]
 aiosqlite
 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_e2e_fake.py

@@ -0,0 +1,197 @@
+"""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"-sub-konsolidierung-.*-j1$", "modus": "garbage", "mal": 1},  # Retry heilt
+    {"muster": r"-facts-c\d+$", "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"] == "subblocks"
+    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 (fakten_gate) 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"] == "fakten_gate" 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,386 @@
+"""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_coverage_schema():
+    res = gb._coverage_schema({"ziele": {"z1": True, "z2": "false"},
+                               "luecken": [{"ziel": "z2", "fehlt": "Beweis"}],
+                               "ballast": ["Abschweifung"]}, {"z1", "z2"})
+    assert res["ziele"] == {"z1": True, "z2": False}
+    assert res["luecken"][0]["fehlt"] == "Beweis"
+    assert gb._coverage_schema({"ziele": {"z1": True}}, {"z1", "z2"}) is None  # z2 missing
+
+
+def test_problems_schema():
+    assert gb._problems_schema({"ok": True}) == []
+    assert gb._problems_schema({"problems": [{"section": "S", "problem": "zu lang"}]}) == ["zu lang"]
+    assert gb._problems_schema({"problems": []}) is None
+
+
+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="coverage", 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="coverage")
+    assert await gb.done_step(TOPIC, FMT) == 3      # bis fakten_gate 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_fakten_gate_counts_examples_as_facts(testdb, monkeypatch, tmp_path):
+    """Gate-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", []
+
+    monkeypatch.setattr(gb, "run_single_slot", fake_slot)
+    monkeypatch.setattr(gb, "_card_facts", lambda e, b: "FAKT X")
+    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)
+    card = {"block_norm": "gross", "block": "Gross", "stage": "fakten_gate", "status": "open",
+            "writer_rounds": 0, "gate_info": "",
+            "md": "<!-- section: Gross -->\n<!-- ausführlich -->\nText."}
+    ok = await gb._stage_fakten_gate(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"] == "fakten_gate"
+
+
+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_lese_check_text_sink(testdb, tmp_path, monkeypatch):
+    """Lese-Check antwortet als Text, Engine-Sink persistiert; capabilities none."""
+    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_lesbarkeit(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._writer_budget(2)) in seen["prompt"]  # 800 + 2×400
+
+
+async def test_fakten_gate_schwelle(testdb, tmp_path, monkeypatch):
+    """1–2 Claims → kein Fix-Rewrite (nur Log); ab GATE_FIX_MIN läuft der Fix."""
+    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 -->\nText."
+    card = {"block_norm": "alpha", "block": "Alpha", "writer_rounds": 0, "md": md}
+    keys = []
+
+    async def fake_slot(ctx, label, *, key, prompt, role, capabilities, payload, timeout):
+        keys.append(key)
+        if "-gate-" in key:
+            return gb.OK, [{"text": "c1", "grund": ""}, {"text": "c2", "grund": ""}]
+        raise AssertionError("Fix darf unter der Schwelle nicht laufen")
+
+    monkeypatch.setattr(gb, "run_single_slot", fake_slot)
+    assert await gb._stage_fakten_gate(env, card)
+    assert all("-gate-" in k for k in keys)
+
+
+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_fakten_gate_falsch_claim_erzwingt_fix(testdb, tmp_path, monkeypatch):
+    """Ein einzelner FALSCH-Claim läuft in den Fix, auch unter GATE_FIX_MIN —
+    ein durchgerutschter kostete den Guide 1.5 QA-Punkte."""
+    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 -->\nText."
+    card = {"block_norm": "alpha", "block": "Alpha", "writer_rounds": 0, "md": md}
+    keys = []
+
+    async def fake_slot(ctx, label, *, key, prompt, role, capabilities, payload, timeout):
+        keys.append(key)
+        if "-gate-" in key:
+            return gb.OK, [{"text": "c1", "grund": "widerspricht", "urteil": "falsch"}]
+        return gb.FAILED, None  # Fix-Agent liefert nichts — Text bleibt, aber der Call MUSS kommen
+
+    monkeypatch.setattr(gb, "run_single_slot", fake_slot)
+    assert await gb._stage_fakten_gate(env, card)
+    assert any("-gatefix-" in k for k in keys)
+
+
+async def test_laengen_trigger_startet_lesefix(testdb, tmp_path, monkeypatch):
+    """Ausführlich-Teil über der Obergrenze → deterministisches Längen-Problem
+    mit hartem Zeichenziel landet im Lese-Fix-Auftrag."""
+    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}
+    seen = {}
+
+    async def fake_slot(ctx, label, *, key, prompt, role, capabilities, payload, timeout):
+        if "-lesefix-" in key:
+            seen["tasks"] = prompt
+            return gb.FAILED, None
+        return gb.OK, payload((0, '{"ok": true}', ""))  # Lese-Check: keine Probleme
+
+    monkeypatch.setattr(gb, "run_single_slot", fake_slot)
+    monkeypatch.setattr(gb, "READABILITY_ACTIVE", False)
+    assert await gb._stage_lesbarkeit(env, card)
+    assert "Länge" in seen["tasks"] and str(gb._writer_budget(1)) in seen["tasks"]

backend/tests/test_guide_qa.py

@@ -0,0 +1,106 @@
+"""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():
+    duenn = _card("Alpha", "<!-- ausführlich -->\nkurz")
+    ok = _card("Beta", "<!-- ausführlich -->\n" + "x" * 500)
+    out = gq.laengen_ausreisser([duenn, ok], {"alpha": {"s1"}, "beta": {"s1"}})
+    assert [x["block"] for x in out] == ["Alpha"]
+
+
+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,608 @@
+"""Sub-Konsolidierung: In-Block-Panel (blocks._konsolidiere_subblocks) und
+Cross-Block-Barrier (board_artefacts._proc_konsolidierung) — Judges gefaked, gegen Test-DB."""
+
+import json
+
+import numpy as np
+import pytest
+
+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")
+
+
+# ── In-Block ────────────────────────────────────────────────────────────────────────
+
+async def test_merge_on_unanimity(testdb, tmp_path, monkeypatch):
+    """Beide Judges gruppieren 1+2 → Gewinner (mehr key_points) bleibt, facts-Union,
+    Verlierer wird DB-variant und fliegt aus raw/facts_map."""
+    db = testdb
+    subs = ["Durchstreichung: ~~text~~", "Durchstreichung: ~~text~~ streicht Text durch", "Fett: **text**"]
+    await _seed_block(db, "betonung", subs)
+    raw = {"Betonung": list(subs)}
+    facts = {"Betonung": {
+        blocks._norm_title(subs[0]): {"key_points": ["kp-a"], "cited_facts": [{"text": "z1"}]},
+        blocks._norm_title(subs[1]): {"key_points": ["kp-b", "kp-c"], "cited_facts": [{"text": "z1"}, {"text": "z2"}]},
+    }}
+    fake = _fake_slot({"j1": {"gruppen": [[1, 2]], "luecken": ["Marker-Escaping fehlt"]},
+                       "j2": {"gruppen": [[2, 1]], "luecken": ["Escaping von Markern"]}})
+    monkeypatch.setattr(blocks, "run_single_slot", fake)
+    await blocks._konsolidiere_subblocks(_ctx(), {"arbeit": tmp_path}, raw, facts)
+    assert raw["Betonung"] == [subs[1], "Fett: **text**"]  # Gewinner: 2 key_points > 1
+    wf = facts["Betonung"][blocks._norm_title(subs[1])]
+    assert wf["key_points"] == ["kp-b", "kp-c", "kp-a"]
+    assert wf["cited_facts"] == [{"text": "z1"}, {"text": "z2"}]  # Union ohne Doppel
+    assert blocks._norm_title(subs[0]) not in facts["Betonung"]
+    rows = {r["sub_norm"]: r["status"] for r in await db.list_subblocks(TOPIC, "betonung")}
+    assert rows[blocks._norm_title(subs[0])] == "variant"
+    assert rows[blocks._norm_title(subs[1])] == "consensus"
+    journale = list(tmp_path.glob("sub-konsolidierung-*.json"))
+    j = json.loads([p for p in journale if "-j" not in p.stem][0].read_text())
+    # Lücken-Schnitt: Token-Überlappung beider Judges, Formulierung von j1 gewinnt
+    assert j["gruppen"][0]["behalten"] == subs[1] and j["luecken"] == ["Marker-Escaping fehlt"]
+
+
+async def test_dissent_keeps_everything(testdb, tmp_path, monkeypatch):
+    """Nur ein Judge gruppiert → keine Einstimmigkeit → kein Merge."""
+    db = testdb
+    subs = ["Eintrag eins", "Eintrag zwei"]
+    await _seed_block(db, "block", subs)
+    raw = {"Block": list(subs)}
+    fake = _fake_slot({"j1": {"gruppen": [[1, 2]], "luecken": []},
+                       "j2": {"gruppen": [], "luecken": []}})
+    monkeypatch.setattr(blocks, "run_single_slot", fake)
+    await blocks._konsolidiere_subblocks(_ctx(), {"arbeit": tmp_path}, raw, {})
+    assert raw["Block"] == subs
+    assert all(r["status"] == "consensus" for r in await db.list_subblocks(TOPIC, "block"))
+
+
+async def test_judge_failure_fail_open(testdb, tmp_path, monkeypatch):
+    """Ein Judge UND der Ersatz ohne Ergebnis → fail-open, nichts ändert sich."""
+    db = testdb
+    subs = ["Eintrag eins", "Eintrag zwei"]
+    await _seed_block(db, "block", subs)
+    raw = {"Block": list(subs)}
+    fake = _fake_slot({"j1": {"gruppen": [[1, 2]], "luecken": []}})  # j2 UND j3 → FAILED
+    monkeypatch.setattr(blocks, "run_single_slot", fake)
+    await blocks._konsolidiere_subblocks(_ctx(), {"arbeit": tmp_path}, raw, {})
+    assert raw["Block"] == subs
+    assert len(fake.calls) == 3  # j1, j2, Ersatz j3
+
+
+async def test_ersatzrichter_bei_ausfall(testdb, tmp_path, monkeypatch):
+    """j1 fällt aus → Ersatz j3 springt ein; Einstimmigkeit j2+j3 faltet.
+    Vorher entwertete EIN Timeout die gute Stimme (13 Links-Dubletten überlebten)."""
+    db = testdb
+    subs = ["Kurz", "Deutlich längerer Eintrag"]
+    await _seed_block(db, "block", subs)
+    raw = {"Block": list(subs)}
+    fake = _fake_slot({"j2": {"gruppen": [[1, 2]], "luecken": []},
+                       "j3": {"gruppen": [[2, 1]], "luecken": []}})  # j1 → FAILED
+    monkeypatch.setattr(blocks, "run_single_slot", fake)
+    await blocks._konsolidiere_subblocks(_ctx(), {"arbeit": tmp_path}, raw, {})
+    assert raw["Block"] == ["Deutlich längerer Eintrag"]
+
+
+async def test_negation_guard_blocks_merge(testdb, tmp_path, monkeypatch):
+    """Gegensätzliche Aussagen werden selbst bei einstimmigen Judges nicht gefaltet."""
+    db = testdb
+    subs = ["Tabs werden expandiert", "Tabs werden nicht expandiert"]
+    await _seed_block(db, "tabs", subs)
+    raw = {"Tabs": list(subs)}
+    fake = _fake_slot({"j1": {"gruppen": [[1, 2]], "luecken": []},
+                       "j2": {"gruppen": [[1, 2]], "luecken": []}})
+    monkeypatch.setattr(blocks, "run_single_slot", fake)
+    await blocks._konsolidiere_subblocks(_ctx(), {"arbeit": tmp_path}, raw, {})
+    assert raw["Tabs"] == subs
+
+
+async def test_resume_skips_judges(testdb, tmp_path, monkeypatch):
+    """Vorhandene j-Dateien → kein neuer Agenten-Call, Ergebnis wird übernommen."""
+    db = testdb
+    subs = ["Eintrag eins", "Eintrag zwei lang"]
+    await _seed_block(db, "block", subs)
+    raw = {"Block": list(subs)}
+    import hashlib
+    h = hashlib.md5("\n".join(subs).encode()).hexdigest()[:8]
+    for j in (1, 2):
+        (tmp_path / f"sub-konsolidierung-{h}-j{j}.json").write_text(
+            json.dumps({"gruppen": [[1, 2]], "luecken": []}), encoding="utf-8")
+
+    async def kein_agent(*a, **kw):
+        raise AssertionError("Resume darf keinen Agenten starten")
+
+    monkeypatch.setattr(blocks, "run_single_slot", kein_agent)
+    await blocks._konsolidiere_subblocks(_ctx(), {"arbeit": tmp_path}, raw, {})
+    assert raw["Block"] == ["Eintrag zwei lang"]
+
+
+def test_schema_accepts_both_group_forms():
+    """Alte Listenform [1,4] und neue {haupt, weitere}-Form parsen beide; kataloge/fremd optional."""
+    alt = blocks._konsolidierung_schema({"gruppen": [[1, 4]], "luecken": []}, 5)
+    assert alt["gruppen"] == [{"haupt": None, "ids": [1, 4]}] and alt["fremd"] == set()
+    neu = blocks._konsolidierung_schema(
+        {"gruppen": [{"haupt": 4, "weitere": [1]}],
+         "kataloge": [{"titel": "Katalog: Symbole", "mitglieder": [2, 3]}],
+         "fremd": [5], "luecken": ["x"]}, 5)
+    assert neu["gruppen"] == [{"haupt": 4, "ids": [1, 4]}]
+    assert neu["kataloge"] == [{"titel": "Katalog: Symbole", "ids": [2, 3]}]
+    assert neu["fremd"] == {5} and neu["luecken"] == ["x"]
+    assert blocks._konsolidierung_schema({"gruppen": [{"haupt": 9, "weitere": [1]}]}, 5) == \
+        {"gruppen": [], "kataloge": [], "fremd": set(), "luecken": []}  # id out of range
+
+
+async def test_haupt_beats_heuristic(testdb, tmp_path, monkeypatch):
+    """Judges nennen den kürzeren Eintrag als haupt → er gewinnt trotz weniger key_points."""
+    db = testdb
+    subs = ["Basis", "Detailregel mit sehr langem Titel und Facts"]
+    await _seed_block(db, "block", subs)
+    raw = {"Block": list(subs)}
+    facts = {"Block": {blocks._norm_title(subs[1]): {"key_points": ["a", "b", "c"]}}}
+    fake = _fake_slot({"j1": {"gruppen": [{"haupt": 1, "weitere": [2]}], "luecken": []},
+                       "j2": {"gruppen": [{"haupt": 1, "weitere": [2]}], "luecken": []}})
+    monkeypatch.setattr(blocks, "run_single_slot", fake)
+    await blocks._konsolidiere_subblocks(_ctx(), {"arbeit": tmp_path}, raw, facts)
+    assert raw["Block"] == ["Basis"]
+    assert facts["Block"][blocks._norm_title("Basis")]["key_points"] == ["a", "b", "c"]  # Union geerbt
+
+
+async def test_katalog_bundles_to_new_row(testdb, tmp_path, monkeypatch):
+    """Einstimmige Katalog-Mitglieder → neue consensus-Zeile mit Facts-Union, Mitglieder variant."""
+    db = testdb
+    subs = ["Pfeilsymbole: a b c", "Mengensymbole: d e f", "Eigene Regel"]
+    await _seed_block(db, "mathe", subs)
+    raw = {"Mathe": list(subs)}
+    facts = {"Mathe": {blocks._norm_title(subs[0]): {"key_points": ["kp1"]},
+                       blocks._norm_title(subs[1]): {"key_points": ["kp2"]}}}
+    kat = {"titel": "Symbolkatalog: Pfeile und Mengen", "mitglieder": [1, 2]}
+    fake = _fake_slot({"j1": {"gruppen": [], "kataloge": [kat], "luecken": []},
+                       "j2": {"gruppen": [], "kataloge": [kat], "luecken": []}})
+    monkeypatch.setattr(blocks, "run_single_slot", fake)
+    await blocks._konsolidiere_subblocks(_ctx(), {"arbeit": tmp_path}, raw, facts)
+    assert raw["Mathe"] == ["Eigene Regel", "Symbolkatalog: Pfeile und Mengen"]
+    kn = blocks._norm_title("Symbolkatalog: Pfeile und Mengen")
+    assert sorted(facts["Mathe"][kn]["key_points"]) == ["kp1", "kp2"]
+    rows = {r["sub_norm"]: r["status"] for r in await db.list_subblocks(TOPIC, "mathe")}
+    assert rows[kn] == "consensus"
+    assert rows[blocks._norm_title(subs[0])] == "variant"
+
+
+async def test_katalog_dissent_keeps_members(testdb, tmp_path, monkeypatch):
+    db = testdb
+    subs = ["Pfeilsymbole: a b c", "Mengensymbole: d e f"]
+    await _seed_block(db, "mathe", subs)
+    raw = {"Mathe": list(subs)}
+    fake = _fake_slot({"j1": {"gruppen": [], "kataloge": [{"titel": "K", "mitglieder": [1, 2]}], "luecken": []},
+                       "j2": {"gruppen": [], "kataloge": [], "luecken": []}})
+    monkeypatch.setattr(blocks, "run_single_slot", fake)
+    await blocks._konsolidiere_subblocks(_ctx(), {"arbeit": tmp_path}, raw, {})
+    assert raw["Mathe"] == subs
+
+
+async def test_fremd_unanimous_discards(testdb, tmp_path, monkeypatch):
+    """Einstimmig fremd → discarded + raus; einseitig fremd → bleibt."""
+    db = testdb
+    subs = ["CSS display überschreibt Verhalten", "Echte Markdown-Regel", "Nur einer hält es für fremd"]
+    await _seed_block(db, "block", subs)
+    raw = {"Block": list(subs)}
+    fake = _fake_slot({"j1": {"gruppen": [], "fremd": [1, 3], "luecken": []},
+                       "j2": {"gruppen": [], "fremd": [1], "luecken": []}})
+    monkeypatch.setattr(blocks, "run_single_slot", fake)
+    luecken = await blocks._konsolidiere_subblocks(_ctx(), {"arbeit": tmp_path}, raw, {})
+    assert raw["Block"] == [subs[1], subs[2]]
+    rows = {r["sub_norm"]: r["status"] for r in await db.list_subblocks(TOPIC, "block")}
+    assert rows[blocks._norm_title(subs[0])] == "discarded"
+    assert rows[blocks._norm_title(subs[2])] == "consensus"
+    assert luecken == {}
+
+
+async def test_luecken_nur_bei_einstimmigkeit(testdb, tmp_path, monkeypatch):
+    """Nur Lücken mit Token-Überlappung BEIDER Judges überleben; einseitige fallen weg."""
+    db = testdb
+    subs = ["Eintrag eins", "Eintrag zwei"]
+    await _seed_block(db, "block", subs)
+    raw = {"Block": list(subs)}
+    fake = _fake_slot({"j1": {"gruppen": [], "luecken": ["Inline-HTML fehlt", "Front-Matter"]},
+                       "j2": {"gruppen": [], "luecken": ["nichts zu Inline-HTML"]}})
+    monkeypatch.setattr(blocks, "run_single_slot", fake)
+    luecken = await blocks._konsolidiere_subblocks(_ctx(), {"arbeit": tmp_path}, raw, {})
+    assert luecken == {"Block": ["Inline-HTML fehlt"]}
+
+
+async def test_kp_deckel_im_judge_prompt(testdb, tmp_path, monkeypatch):
+    """Prompt zeigt max. 3 key_points je Sub (Timeout-Schutz); die Union bleibt voll."""
+    db = testdb
+    subs = ["Eintrag eins", "Eintrag zwei"]
+    await _seed_block(db, "block", subs)
+    raw = {"Block": list(subs)}
+    facts = {"Block": {blocks._norm_title(subs[0]): {"key_points": [f"kp{i}" for i in range(1, 6)]}}}
+    fake = _fake_slot({"j1": {"gruppen": [], "luecken": []}, "j2": {"gruppen": [], "luecken": []}})
+    monkeypatch.setattr(blocks, "run_single_slot", fake)
+    await blocks._konsolidiere_subblocks(_ctx(), {"arbeit": tmp_path}, raw, facts)
+    prompt = fake.calls[0]["prompt"]
+    assert "kp3" in prompt and "kp4" not in prompt
+
+
+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")
+
+
+# ── Lücken-Nachfass ─────────────────────────────────────────────────────────────────
+
+async def _nachfass_env(db, monkeypatch, facts_result):
+    subs = ["Eintrag eins"]
+    await _seed_block(db, "block", subs)
+    raw = {"Block": list(subs)}
+    facts_map = {"Block": {}}
+
+    async def fake_race(topic, label, slots, quorum, timeout, provider, cancelled=None, grace=0):
+        return [{"Block": ["Eintrag eins", "Neuer Aspekt"]}]
+
+    async def fake_facts(ctx, set_p, files, fraw, q, folder, instructions, ns="", lbl="", sources=None, slim=False):
+        assert slim is True  # Nachfass nutzt die schlanke Facts-Variante
+        assert list(fraw["Block"]) == ["Neuer Aspekt"]  # nur der frische Fund geht ins Gate
+        return facts_result
+
+    monkeypatch.setattr(blocks, "_race", fake_race)
+    monkeypatch.setattr(blocks, "_facts_block", fake_facts)
+    monkeypatch.setattr(blocks, "EMBEDDING_AKTIV", False)
+    return raw, facts_map
+
+
+async def test_nachfass_adopts_backed_find(testdb, tmp_path, monkeypatch):
+    db = testdb
+    nn = blocks._norm_title("Neuer Aspekt")
+    raw, facts_map = await _nachfass_env(db, monkeypatch,
+                                         ({"Block": {nn: {"key_points": ["kp"]}}}, {}))
+    n = await blocks._luecken_runde(_ctx(), {"arbeit": tmp_path}, "Block", ["Aspekt"],
+                                    raw, facts_map, {"type": "thema"}, None)
+    assert n == 1 and raw["Block"] == ["Eintrag eins", "Neuer Aspekt"]
+    assert facts_map["Block"][nn]["key_points"] == ["kp"]
+    rows = {r["sub_norm"]: r["status"] for r in await db.list_subblocks(TOPIC, "block")}
+    assert rows[nn] == "consensus"
+
+
+async def test_nachfass_drops_unbacked_find(testdb, tmp_path, monkeypatch):
+    db = testdb
+    nn = blocks._norm_title("Neuer Aspekt")
+    raw, facts_map = await _nachfass_env(db, monkeypatch, ({}, {"Block": {nn}}))
+    n = await blocks._luecken_runde(_ctx(), {"arbeit": tmp_path}, "Block", ["Aspekt"],
+                                    raw, facts_map, {"type": "thema"}, None)
+    assert n == 0 and raw["Block"] == ["Eintrag eins"]
+    assert not any(r["sub_norm"] == nn for r in await db.list_subblocks(TOPIC, "block"))
+
+
+async def test_nachfass_drops_find_without_facts(testdb, tmp_path, monkeypatch):
+    """HARTES Gate: kein Facts-Eintrag = kein Beleg = keine Übernahme — nicht nur
+    aktiv Verworfenes fliegt (Bilder-Lauf: 13 von 18 kamen ohne Beleg durch)."""
+    db = testdb
+    raw, facts_map = await _nachfass_env(db, monkeypatch, ({}, {}))  # Facts fand NICHTS
+    n = await blocks._luecken_runde(_ctx(), {"arbeit": tmp_path}, "Block", ["Aspekt"],
+                                    raw, facts_map, {"type": "thema"}, None)
+    assert n == 0 and raw["Block"] == ["Eintrag eins"]
+
+
+async def test_facts_stage_konsolidiert_nachfass_funde_erneut(testdb, tmp_path, monkeypatch):
+    """Kreis geschlossen: nach Übernahmen läuft die Konsolidierung ein zweites Mal;
+    deren Lücken lösen KEINEN weiteren Nachfass aus."""
+    db = testdb
+    payload = {"title": "Alpha", "raw": {"Alpha": ["s1"]}}
+    await db.kanban_upsert_card(TOPIC, "artefacts", "alpha", "ablock", "facts", payload)
+    calls = {"kons": 0, "nf": 0}
+
+    async def fake_facts(ctx, set_p, files, raw, q, folder, instructions, ns="", lbl="", sources=None, slim=False):
+        return {"Alpha": {}}, {}
+
+    async def fake_kons(ctx, files, raw, facts_map, instructions="", ns="", lbl=""):
+        calls["kons"] += 1
+        return {"Alpha": ["Lücke X"]}  # meldet auch in Runde 2 — darf nicht erneut nachfassen
+
+    async def fake_nf(ctx, files, title, luecken, raw, facts_map, q, folder,
+                      instructions="", ns="", lbl="", sources=None):
+        calls["nf"] += 1
+        return 2
+
+    monkeypatch.setattr(ba, "_facts_block", fake_facts)
+    monkeypatch.setattr(ba, "_konsolidiere_subblocks", fake_kons)
+    monkeypatch.setattr(ba, "_luecken_runde", fake_nf)
+    flow = Flow(TOPIC, work_dir=tmp_path)
+    await ba._proc_facts(_ctx(), flow, {"arbeit": tmp_path}, {"type": "thema"}, None, "",
+                         [{"card_id": "alpha", "payload": payload}])
+    assert calls == {"kons": 2, "nf": 1}
+    assert (await db.kanban_get_card(TOPIC, "artefacts", "alpha"))["stage"] == "levels"
+
+
+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):
+    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(),
+                   "raw": {bnorm.title(): list(subs)},
+                   "sidecar": {bnorm.title(): [{"title": s, "level": "beginner"} for s in subs]},
+                   "facts": {bnorm.title(): {blocks._norm_title(s): {"key_points": [f"kp {s}"]} for s in subs}}}
+        await db.kanban_upsert_card(TOPIC, "artefacts", bnorm, "ablock", "konsolidierung", payload)
+        await _seed_block(db, bnorm, subs)
+        cards.append({"card_id": bnorm, "payload": payload})
+    return flow, cards
+
+
+async def test_crossblock_folds_loser(testdb, tmp_path, monkeypatch):
+    """Einstimmig „a" → Beta verliert die geteilte Aussage, Karten wandern zu levels."""
+    db = testdb
+    flow, cards = await _cross_env(db, tmp_path)
+    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, {}, "", cards)
+    assert "Gleiche Aussage" in fake.calls[0]["prompt"]
+    beta = await db.kanban_get_card(TOPIC, "artefacts", "beta")
+    assert beta["stage"] == "question_pattern"
+    assert beta["payload"]["raw"]["Beta"] == ["Nur in Beta"]
+    assert blocks._norm_title("Gleiche Aussage") not in beta["payload"]["facts"]["Beta"]
+    # Barriere liegt jetzt hinter levels/relevance → auch die sidecar muss den Fold tragen
+    assert [e["title"] for e in beta["payload"]["sidecar"]["Beta"]] == ["Nur in Beta"]
+    alpha = await db.kanban_get_card(TOPIC, "artefacts", "alpha")
+    assert alpha["stage"] == "question_pattern"
+    assert alpha["payload"]["raw"]["Alpha"] == ["Gleiche Aussage", "Nur in Alpha"]
+    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_tiebreaker_folds(testdb, tmp_path, monkeypatch):
+    """j1/j2 uneinig → j3 entscheidet mit Mehrheit; hier „a" → Beta verliert."""
+    db = testdb
+    flow, cards = 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, {}, "", cards)
+    assert len(fake.calls) == 3
+    beta = await db.kanban_get_card(TOPIC, "artefacts", "beta")
+    assert beta["payload"]["raw"]["Beta"] == ["Nur in Beta"]
+
+
+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 = 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, {}, "", cards)
+    beta = await db.kanban_get_card(TOPIC, "artefacts", "beta")
+    assert beta["stage"] == "question_pattern"
+    assert beta["payload"]["raw"]["Beta"] == ["Gleiche Aussage", "Nur in Beta"]
+
+
+async def test_crossblock_ersatzrichter(testdb, tmp_path, monkeypatch):
+    """Nur ein Richter liefert → Ersatz jE als zweite Stimme; Einstimmigkeit faltet."""
+    db = testdb
+    flow, cards = 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, {}, "", cards)
+    beta = await db.kanban_get_card(TOPIC, "artefacts", "beta")
+    assert beta["payload"]["raw"]["Beta"] == ["Nur in Beta"]
+
+
+async def test_crossblock_without_embedding_advances(testdb, tmp_path, monkeypatch):
+    db = testdb
+    flow, cards = 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, {}, "", cards)
+    for cid in ("alpha", "beta"):
+        assert (await db.kanban_get_card(TOPIC, "artefacts", cid))["stage"] == "question_pattern"
+
+
+async def test_crossblock_context_wins(testdb, tmp_path, monkeypatch):
+    """Kontext-Sub (Block schon hinter der Barrier) gewinnt auch bei Verdict „b" —
+    die Paket-Seite fällt, der Kontext bleibt unangetastet."""
+    db = testdb
+    flow = Flow(TOPIC, work_dir=tmp_path)
+    payload = {"title": "Alpha", "raw": {"Alpha": ["Gleiche Aussage"]}, "facts": {"Alpha": {}}}
+    await db.kanban_upsert_card(TOPIC, "artefacts", "alpha", "ablock", "konsolidierung", payload)
+    await _seed_block(db, "alpha", ["Gleiche Aussage"])
+    cards = [{"card_id": "alpha", "payload": payload}]
+    # Kontext-Block "gamma" ist bereits weiter (Stage levels) und hält dieselbe Aussage
+    await db.kanban_upsert_card(TOPIC, "artefacts", "gamma", "ablock", "levels",
+                                {"title": "Gamma", "raw": {"Gamma": ["Gleiche Aussage"]}, "facts": {}})
+    await _seed_block(db, "gamma", ["Gleiche Aussage"])
+    monkeypatch.setattr(ba, "embedding", _FakeEmb)
+    # Verdict „a": das Paket (A) soll behalten — Kontext faltet trotzdem nie
+    fake = _fake_slot({"j1": {"pairs": {"1": "a"}}, "j2": {"pairs": {"1": "a"}}})
+    monkeypatch.setattr(ba, "run_single_slot", fake)
+    await ba._proc_konsolidierung(_ctx(), flow, {}, "", cards)
+    alpha = await db.kanban_get_card(TOPIC, "artefacts", "alpha")
+    assert alpha["payload"]["raw"].get("Alpha", []) == []  # Paket-Seite gefaltet
+    gamma_rows = {r["sub_norm"]: r["status"] for r in await db.list_subblocks(TOPIC, "gamma")}
+    assert gamma_rows[blocks._norm_title("Gleiche Aussage")] == "consensus"  # Kontext unberührt
+
+
+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(),
+                   "raw": {bnorm.title(): list(subs)},
+                   "sidecar": {bnorm.title(): [{"title": s, "level": "beginner"} for s in subs]},
+                   "facts": {bnorm.title(): {blocks._norm_title(s): {"key_points": []} for s in subs}}}
+        await db.kanban_upsert_card(TOPIC, "artefacts", bnorm, "ablock", "konsolidierung", payload)
+        await _seed_block(db, bnorm, subs)
+        cards.append({"card_id": bnorm, "payload": payload})
+    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, {}, "", cards)
+    assert len(fake.calls) == 4  # 2 Chunks × j1/j2
+    beta = await db.kanban_get_card(TOPIC, "artefacts", "beta")
+    assert beta["payload"]["raw"].get("Beta", []) == []  # beide Dubletten global gefaltet
+
+
+async def test_facts_nachfass_holt_nur_fehlende(testdb, tmp_path, monkeypatch):
+    """Nachfass ruft den slim-Facts-Lauf NUR mit den facts-losen Subs und merged die Funde;
+    Vorhandenes bleibt unberührt, Subs werden nie verworfen."""
+    gesehen = {}
+
+    async def fake_facts_block(ctx, set_p, files, raw, q, folder, instructions, ns="", lbl="",
+                               sources=None, slim=False):
+        gesehen["raw"] = raw
+        gesehen["slim"] = slim
+        return ({"Alpha": {"ohne beleg": {"key_points": ["kp neu"]},
+                           "mit beleg": {"key_points": ["DARF NICHT GEWINNEN"]}}},
+                {"Alpha": {"ohne beleg"}})  # discard-Urteil wird ignoriert
+
+    monkeypatch.setattr(blocks, "_facts_block", fake_facts_block)
+    raw = {"Alpha": ["Mit Beleg", "Ohne Beleg"]}
+    facts_map = {"Alpha": {"mit beleg": {"key_points": ["kp alt"]}}}
+    ctx = GenContext(topic=TOPIC, provider="claude", is_cancelled=lambda: False)
+    n = await blocks._facts_nachfass(ctx, {"arbeit": tmp_path}, raw, facts_map, {}, None)
+    assert n == 1
+    assert gesehen["slim"] and gesehen["raw"] == {"Alpha": ["Ohne Beleg"]}
+    assert facts_map["Alpha"]["ohne beleg"]["key_points"] == ["kp neu"]
+    assert facts_map["Alpha"]["mit beleg"]["key_points"] == ["kp alt"]
+    assert raw["Alpha"] == ["Mit Beleg", "Ohne Beleg"]  # kein Verwurf
+
+
+async def test_levels_merge_fuzzy_match(testdb, tmp_path, monkeypatch):
+    """Levels-Agent paraphrasiert den Sub-Titel → facts hängen trotzdem am Sidecar-Eintrag
+    (eindeutiger Präfix-Match statt stillem Grounding-Verlust)."""
+    db = testdb
+    payload = {"title": "Alpha", "raw": {"Alpha": ["Marker Regel: Details dazu"]},
+               "facts": {"Alpha": {blocks._norm_title("Marker Regel: Details dazu"):
+                                   {"key_points": ["kp"]}}}}
+    await db.kanban_upsert_card(TOPIC, "artefacts", "alpha", "ablock", "levels", payload)
+    cards = [{"card_id": "alpha", "payload": payload}]
+
+    async def fake_levels_block(ctx, set_p, files, raw, instructions, ns="", lbl=""):
+        return {"Alpha": [{"title": "Marker Regel", "level": "beginner"}]}  # gekürzter Titel
+
+    monkeypatch.setattr(ba, "_levels_block", fake_levels_block)
+    await ba._proc_levels(_ctx(), Flow(TOPIC, work_dir=tmp_path), {"arbeit": tmp_path}, "", cards)
+    card = await db.kanban_get_card(TOPIC, "artefacts", "alpha")
+    assert card["payload"]["sidecar"]["Alpha"][0]["facts"] == {"key_points": ["kp"]}

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,250 @@
+"""QA-Detektoren: Fehler-Injektion auf Mini-Korpus — deterministisch, ohne LLM/Embedding."""
+
+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_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_repair.py

@@ -0,0 +1,230 @@
+"""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):
+        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_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,444 @@
+"""Subbaustein-Qualität: Varianten-Konsens, Seed-Garantie, Nachfass, Outline-Review."""
+
+import json
+import re
+
+import numpy as np
+import pytest
+
+import blocks as blx
+from pipeline import GenContext
+
+TOPIC = "t"
+_MD_PATH = re.compile(r"(/\S+\.md)")
+
+
+# ── _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
+
+
+# ── _subblocks_block integration (fake race + fake embeddings) ──────────────────────
+
+def _fake_sims(texts):
+    """Markertoken matrix: same first word → 0.95, else 0."""
+    n = len(texts)
+    m = np.eye(n)
+    key = lambda t: t.split()[0].casefold()
+    for i in range(n):
+        for j in range(n):
+            if i != j and key(texts[i]) == key(texts[j]):
+                m[i][j] = 0.95
+    return m
+
+
+def _mk_race(finder_by_agent):
+    """Key-routed _race fake. Finder round 1 → scripted per-agent subs; later finder and
+    catch-up rounds → nothing; clarify judges echo the consensus lines from their prompt."""
+    prompts = []
+
+    async def fake_race(topic, label, slots, quorum, timeout, provider, on_update=None,
+                        cancelled=None, *, grace=None, min_runtime=None, max_runtime=None):
+        outs = []
+        for slot in slots:
+            key, prompt = slot["key"], slot["prompt"]
+            prompts.append((key, prompt))
+            fake_race.slots_seen.append(slot)
+            if "-subblock-final-" in key:
+                # no-tool judges reply as TEXT; the payload sink writes the j-file itself
+                kons = re.search(r"Konsens \(≥2 finders\):\n(.*?)\nUnsicher", prompt, re.S)
+                subs = [l[2:] for l in (kons.group(1).splitlines() if kons else [])
+                        if l.startswith("- ") and l != "- (keiner)"]
+                if subs:
+                    text = "<!-- block: Alpha -->\n" + "\n".join(f"- {s}" for s in subs)
+                    outs.append(slot["payload"]((0, text, "")))
+                continue
+            if "-r1-" in key:
+                agent = int(key.rsplit("-", 1)[1])
+                subs = finder_by_agent.get(agent) or []
+                if subs and (m := _MD_PATH.search(prompt)):
+                    text = "<!-- block: Alpha -->\n" + "\n".join(f"- {s}" for s in subs)
+                    with open(m.group(1), "w", encoding="utf-8") as f:
+                        f.write(text)
+                    outs.append(slot["payload"](None))
+        outs = [o for o in outs if o]
+        return outs or None
+    fake_race.slots_seen = []
+    return fake_race, prompts
+
+
+@pytest.fixture
+def sub_env(testdb, tmp_path, monkeypatch):
+    monkeypatch.setattr(blx, "EMBEDDING_AKTIV", True)
+    monkeypatch.setattr(blx.embedding, "available", lambda: True)
+    monkeypatch.setattr(blx.embedding, "embed_sims", _fake_sims)
+    ctx = GenContext(topic=TOPIC, provider="claude", is_cancelled=lambda: False)
+    files = {"arbeit": tmp_path}
+    return testdb, ctx, files
+
+
+async def _run(ctx, files, monkeypatch, finder_by_agent, seeds=None):
+    fake, prompts = _mk_race(finder_by_agent)
+    monkeypatch.setattr(blx, "_race", fake)
+    raw = await blx._subblocks_block(ctx, lambda *a, **k: None, files, {1: "Alpha — Grundkonzept"},
+                                     "", wipe=False, ns="x-", seeds=seeds)
+    return raw, prompts
+
+
+async def test_variant_consensus_end_to_end(sub_env, monkeypatch):
+    """3 Einzelfunde in 3 Formulierungen → EIN consensus-Repräsentant; Varianten gehen
+    nicht als „Unsicher" ins Panel."""
+    db, ctx, files = sub_env
+    raw, prompts = await _run(ctx, files, monkeypatch, {
+        1: ["Umbruch braucht Marker"],
+        2: ["Umbruch erfordert explizite Marker!"],
+        3: ["Umbruch verlangt zwei Leerzeichen als Marker"],
+    })
+    assert raw == {"Alpha": ["Umbruch verlangt zwei Leerzeichen als Marker"]}  # longest = rep
+    rows = await db.list_subblocks(TOPIC, "alpha")
+    status = sorted(r["status"] for r in rows)
+    assert status == ["consensus", "variant", "variant"]
+    clarify_prompts = [p for k, p in prompts if "-subblock-final-" in k]
+    assert clarify_prompts and "Umbruch braucht Marker" not in clarify_prompts[0]
+
+
+async def test_seed_promotes_single_find(sub_env, monkeypatch):
+    """Seed deckt einen verworfenen Einzelfund lexikalisch → Promotion zu consensus."""
+    db, ctx, files = sub_env
+    raw, _ = await _run(ctx, files, monkeypatch, {
+        1: ["Alpha Grundlagen", "Zeilenumbruch Regeln im Detail"],
+        2: ["Alpha Grundlagen"],
+    }, seeds=["Zeilenumbruch Regeln"])
+    assert "Zeilenumbruch Regeln im Detail" in raw["Alpha"]
+    row = next(r for r in await db.list_subblocks(TOPIC, "alpha")
+               if r["sub_norm"] == "zeilenumbruch regeln im detail")
+    assert row["status"] == "consensus"
+
+
+async def test_seed_inserted_when_nothing_found(sub_env, monkeypatch):
+    """Seed ohne jeden Fund wird als eigener consensus-Sub eingefügt (Facts-Gate prüft später)."""
+    db, ctx, files = sub_env
+    raw, _ = await _run(ctx, files, monkeypatch, {
+        1: ["Alpha Grundlagen"], 2: ["Alpha Grundlagen"],
+    }, seeds=["Fußnoten Syntax"])
+    assert "Fußnoten Syntax" in raw["Alpha"]
+    row = next(r for r in await db.list_subblocks(TOPIC, "alpha")
+               if r["sub_title"] == "Fußnoten Syntax")
+    assert row["status"] == "consensus"
+
+
+async def test_seed_covered_no_duplicate(sub_env, monkeypatch):
+    """Seed lexikalisch von einem consensus-Sub abgedeckt → nichts eingefügt."""
+    db, ctx, files = sub_env
+    raw, _ = await _run(ctx, files, monkeypatch, {
+        1: ["Tabs werden zu Leerzeichen expandiert"], 2: ["Tabs werden zu Leerzeichen expandiert"],
+    }, seeds=["Tabs"])
+    assert raw == {"Alpha": ["Tabs werden zu Leerzeichen expandiert"]}
+
+
+async def test_wipe_false_is_idempotent(sub_env, monkeypatch):
+    """Zweiter Karten-Lauf kumuliert keine Mentions (per-Block-Wipe)."""
+    db, ctx, files = sub_env
+    await _run(ctx, files, monkeypatch, {1: ["Alpha Grundlagen"], 2: ["Alpha Grundlagen"]})
+    first = {r["sub_norm"]: r["mentions"] for r in await db.list_subblocks(TOPIC, "alpha")}
+    await _run(ctx, files, monkeypatch, {1: ["Alpha Grundlagen"], 2: ["Alpha Grundlagen"]})
+    second = {r["sub_norm"]: r["mentions"] for r in await db.list_subblocks(TOPIC, "alpha")}
+    assert first == second
+
+
+async def test_catchup_adds_and_stops(sub_env, monkeypatch, tmp_path):
+    """Block unter SUBBLOCK_MIN: Nachfass-Runde findet Neues → eigenes Final-File,
+    Konsens wächst; zweite Runde ohne Neues → Ende."""
+    db, ctx, files = sub_env
+    fake, prompts = _mk_race({1: ["Alpha Grundlagen"], 2: ["Alpha Grundlagen"]})
+    base = fake
+    hit = {"n": 0}
+
+    async def with_catchup(topic, label, slots, *a, **k):
+        if any("-subblock-x" in s["key"] for s in slots):
+            hit["n"] += 1
+            if hit["n"] == 1:  # first catch-up round: both agents agree on one new sub
+                for slot in slots[:2]:
+                    m = _MD_PATH.search(slot["prompt"])
+                    with open(m.group(1), "w", encoding="utf-8") as f:
+                        f.write("<!-- block: Alpha -->\n- Vertiefung der Konzepte")
+                return [slot["payload"](None) for slot in slots[:2]]
+            return None
+        return await base(topic, label, slots, *a, **k)
+
+    monkeypatch.setattr(blx, "_race", with_catchup)
+    raw = await blx._subblocks_block(ctx, lambda *a, **k: None, files, {1: "Alpha — Grundkonzept"},
+                                     "", wipe=False, ns="x-")
+    assert set(raw["Alpha"]) == {"Alpha Grundlagen", "Vertiefung der Konzepte"}
+    assert (tmp_path / "subblock-final-c1-x1.md").exists()
+    assert hit["n"] == 2  # round 2 ran, found nothing, loop ended
+
+
+# ── 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]
+
+async def test_paraphrase_saturation_stops_early(sub_env, monkeypatch):
+    """Runde 2 liefert nur eine Paraphrase → zählt nicht als neu, Schleife endet ohne r3.
+    Die Paraphrase liegt trotzdem in der DB (Mention fürs Cluster-Voting)."""
+    db, ctx, files = sub_env
+    base_fake, prompts = _mk_race({1: ["Umbruch braucht Marker"], 2: ["Umbruch braucht Marker"]})
+
+    async def with_r2(topic, label, slots, *a, **k):
+        if any("-r2-" in s["key"] for s in slots):
+            outs = []
+            for slot in slots[:2]:
+                m = _MD_PATH.search(slot["prompt"])
+                with open(m.group(1), "w", encoding="utf-8") as f:
+                    f.write("<!-- block: Alpha -->\n- Umbruch erfordert explizite Marker!")
+                outs.append(slot["payload"](None))
+            return outs
+        return await base_fake(topic, label, slots, *a, **k)
+
+    monkeypatch.setattr(blx, "_race", with_r2)
+    raw = await blx._subblocks_block(ctx, lambda *a, **k: None, files, {1: "Alpha — Grundkonzept"},
+                                     "", wipe=False, ns="x-")
+    assert raw["Alpha"]  # Konsens steht
+    assert not any("-r3-" in k for k, _ in prompts)  # Paraphrase hielt die Schleife NICHT am Leben
+    rows = await db.list_subblocks(TOPIC, "alpha")
+    assert any(r["sub_title"] == "Umbruch erfordert explizite Marker!" for r in rows)
+
+
+async def test_round_cap_stops_endless_finders(sub_env, monkeypatch):
+    """Jede Runde ein echt neues Konzept → hartes Cap stoppt bei SUBBLOCK_MAX_ROUNDS."""
+    db, ctx, files = sub_env
+    _, prompts = _mk_race({})
+
+    async def endless(topic, label, slots, *a, **k):
+        if "-subblock-final-" in slots[0]["key"]:
+            return None  # panel fails → consensus fallback
+        outs = []
+        import re as _re
+        rn = _re.search(r"-r(\d+)-", slots[0]["key"])
+        n = rn.group(1) if rn else "x"
+        for slot in slots[:2]:
+            m = _MD_PATH.search(slot["prompt"])
+            with open(m.group(1), "w", encoding="utf-8") as f:
+                f.write(f"<!-- block: Alpha -->\n- Konzept{n} ist eigenständig")
+            prompts.append((slot["key"], slot["prompt"]))
+            outs.append(slot["payload"](None))
+        return outs
+
+    monkeypatch.setattr(blx, "_race", endless)
+    await blx._subblocks_block(ctx, lambda *a, **k: None, files, {1: "Alpha — Grundkonzept"},
+                               "", wipe=False, ns="x-")
+    max_round = max(int(k.split("-r")[1].split("-")[0]) for k, _ in prompts if "-r" in k and "-subblock-c" in k)
+    assert max_round == blx.SUBBLOCK_MAX_ROUNDS
+
+
+# ── Inline-Evidenz für Judges (Token-Umbau) ──────────────────────────────────────────
+
+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()
+
+
+async def test_clarify_inline_evidence_no_tools(sub_env, monkeypatch, tmp_path):
+    """Mit Korpus: Judges bekommen Auszüge inline und laufen ohne Tools (Text-Antwort);
+    die j-Datei schreibt die Engine. Finder bleiben unverändert bei capabilities=files."""
+    db, ctx, files = sub_env
+    d = _corpus(tmp_path)
+    monkeypatch.setattr(blx, "source_folder", lambda t: d)
+    monkeypatch.setattr(blx, "load_source", lambda t: {"type": "uni"})
+    fake, prompts = _mk_race({1: ["Alpha Grundlagen"], 2: ["Alpha Grundlagen"]})
+    monkeypatch.setattr(blx, "_race", fake)
+    raw = await blx._subblocks_block(ctx, lambda *a, **k: None, files, {1: "Alpha — Grundkonzept"},
+                                     "", wipe=False, ns="x-", sources=["Skript.txt"])
+    assert raw == {"Alpha": ["Alpha Grundlagen"]}
+    judges = [s for s in fake.slots_seen if "-subblock-final-" in s["key"]]
+    finders = [s for s in fake.slots_seen if "-r1-" in s["key"]]
+    assert judges and all(s["capabilities"] == "none" for s in judges)
+    assert "── Skript.txt" in judges[0]["prompt"]
+    assert "ls/find" not in judges[0]["prompt"]  # keine Selbst-Recherche-Anweisung mehr
+    assert finders and all(s["capabilities"] == "files" for s in finders)
+    assert list(tmp_path.glob("subblock-final-*-j*.md"))  # Engine persistiert die Judge-Antwort
+
+
+async def test_facts_check_inline_cited_evidence(sub_env, monkeypatch, tmp_path):
+    """Facts-Check: zitierte Zeilenbereiche gehen inline mit, Judge läuft ohne Tools,
+    die Check-Datei schreibt die Engine aus der Text-Antwort."""
+    db, ctx, files = sub_env
+    d = _corpus(tmp_path)
+    facts = {"facts": [{"block": "Alpha", "subblock": "Sub Eins", "key_points": ["k"],
+                        "prerequisites": "", "hurdles": "",
+                        "cited_facts": [{"text": "T", "source": "Skript.txt, Z.2"}],
+                        "example_idea": ""}]}
+
+    sh = blx._subs_hash({"Alpha": ["Sub Eins"]})  # Resume-Dateien tragen den Sub-Satz-Hash
+
+    async def fake_slot(ctx2, label, *, key, prompt, role, capabilities, payload, timeout, on_line=None):
+        if "-facts-erg-" in key:
+            return blx.FAILED, None
+        (tmp_path / f"facts-{sh}-c0.json").write_text(json.dumps(facts), encoding="utf-8")
+        return blx.OK, None
+
+    seen = []
+
+    async def fake_agent(key, prompt, timeout, provider="", role="", capabilities="", scope=None, label="", **kw):
+        seen.append((key, capabilities, prompt))
+        return (0, '{"ok": true}', "")
+
+    monkeypatch.setattr(blx, "run_single_slot", fake_slot)
+    monkeypatch.setattr(blx, "run_agent", fake_agent)
+    res = await blx._facts_block(ctx, lambda *a, **k: None, {"arbeit": tmp_path},
+                                 {"Alpha": ["Sub Eins"]}, {"type": "uni"}, d, "", ns="x-")
+    assert res is not None
+    facts_map, discarded = res
+    assert "Alpha" in facts_map and not discarded
+    assert len(seen) == blx.FACTS_CHECK_PANEL
+    key, caps, prompt = seen[0]
+    assert caps == "none" and "── Skript.txt · Z." in prompt
+    assert (tmp_path / f"facts-check-{sh}-c0-j1.json").exists()  # Engine persistiert die Antwort
+
+
+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 (FACTS_CHUNK_SUBS=6) 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("FACTS_CHUNK_SUBS") == 6 else _metrics()
+
+    runner, f0 = _stub(bewertung)
+    t = _trainer(tmp_path, runner, f0, max_trials=120)
+    best = await t.run()
+    assert best.get("FACTS_CHUNK_SUBS") == 6
+    taus = t.pheromon["FACTS_CHUNK_SUBS"]
+    assert max(taus, key=lambda k: taus[k]) == "6"
+
+
+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("FACTS_CHUNK_SUBS") == 6:
+            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("FACTS_CHUNK_SUBS") != 6
+
+
+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("FACTS_CHUNK_SUBS") == 6 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["FACTS_CHUNK_SUBS"])
+    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["FACTS_CHUNK_SUBS"] == 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

@@ -1,19 +1,19 @@
-"""Reine Text-Helfer: Titel-Normalisierung, Listen-Parser, Chunk-Aufteilung.
+"""Pure text helpers: title normalization, list parsers, chunk splitting.
 
-Kein Zustand, keine IO — überall gefahrlos importierbar.
+No state, no IO — safe to import anywhere.
 """
 
 import re
 import unicodedata
 
-_CATEGORIES = ("KERN", "WICHTIG", "REST")  # nur noch für den Altformat-Reader
+_CATEGORIES = ("KERN", "WICHTIG", "REST")  # only for the legacy-format reader now
 
 
-def _norm_titel(s: str) -> str:
-    """Normalisiert einen Titel für den Schlüssel-Vergleich.
+def _norm_title(s: str) -> str:
+    """Normalize a title for key comparison.
 
-    NFKC + casefold fangen Unicode-Varianten; Anführungszeichen, Markdown-
-    Emphasis und Dash-Varianten kommen aus KI-Output in allen Spielarten.
+    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)
@@ -22,77 +22,75 @@ def _norm_titel(s: str) -> str:
     return s.casefold()
 
 
-def _titel(entry: str) -> str:
+def _title(entry: str) -> str:
     return entry.split(" — ")[0].strip() or entry
 
 
-def _eindeutige_titel(entries: dict[int, str]) -> dict[int, str]:
-    """Macht Titel eindeutig (Suffix " (2)", " (3)" …), damit sie als Schlüssel taugen."""
+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():
-        titel = _titel(text)
-        key = _norm_titel(titel)
+        title = _title(text)
+        key = _norm_title(title)
         seen[key] = seen.get(key, 0) + 1
         if seen[key] > 1:
             rest = text.split(" — ", 1)
-            text = f"{titel} ({seen[key]})" + (f" — {rest[1]}" if len(rest) == 2 else "")
-    # zweiter Durchlauf nicht nötig: Suffixe kollidieren praktisch nicht
+            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 _vormerge(listen: list[dict[int, str]]) -> list[tuple[str, int]]:
-    """Vereinigt Baustein-Listen: exakte Titel-Dubletten (per _norm_titel) zusammenführen.
-
-    → [("Titel — Beschreibung", nennungen)] in Erstnennungs-Reihenfolge.
-    nennungen = Anzahl der Listen, die den Titel nennen (Dublette innerhalb
-    einer Liste zählt nicht doppelt). Repräsentant ist die Erstnennung; ein
-    drittes " — "-Segment (Quelle) wird verworfen.
-    """
-    merged: dict[str, tuple[str, int]] = {}
-    for liste in listen:
-        gesehen: set[str] = set()
-        for text in liste.values():
-            key = _norm_titel(_titel(text))
-            if key in gesehen:
-                continue
-            gesehen.add(key)
-            if key in merged:
-                repr_text, n = merged[key]
-                merged[key] = (repr_text, n + 1)
-            else:
-                merged[key] = (" — ".join(text.split(" — ")[:2]), 1)
-    return list(merged.values())
 
 
-def _titel_index(entries: dict[int, str]) -> dict[str, int]:
-    return {_norm_titel(_titel(text)): num for num, text in entries.items()}
+def _title_index(entries: dict[int, str]) -> dict[str, int]:
+    return {_norm_title(_title(text)): num for num, text in entries.items()}
 
 
-def _titel_aufloesen(idx: dict[str, int], t: str) -> int | None:
-    """Titel → Nummer; toleriert mitgeschleppte Beschreibungen ("Titel — …")."""
+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_titel(t)) or idx.get(_norm_titel(_titel(t)))
+    return idx.get(_norm_title(t)) or idx.get(_norm_title(_title(t)))
 
 
-def _parse_auswahl(text: str) -> dict[int, str]:
-    """Parst eine Baustein-Liste: `N. Titel — Kurzbeschreibung` pro Zeile."""
+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] = m.group(2)
+            entries[last] = _norm_dash(m.group(2))
         elif last is not None and line.strip():
-            entries[last] += " " + line.strip()
+            entries[last] += " " + _norm_dash(line.strip())
     return entries
 
 
-def _parse_kategorien(text: str) -> dict[str, list[str]]:
-    """Altformat-Reader: finale Baustein-Datei mit ## KERN/WICHTIG/REST-Abschnitten."""
+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():
@@ -108,38 +106,40 @@ def _parse_kategorien(text: str) -> dict[str, list[str]]:
     return cats
 
 
-def _lade_bausteine(text: str) -> dict[int, str]:
-    """Lädt die finale Baustein-Datei — sortierte Liste (neu) oder Kategorien (Altformat)."""
+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_kategorien(text)
+        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_auswahl(text)
+    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*baustein\s*:\s*(.*?)\s*-->", re.IGNORECASE)
-# Zwei Lese-Schichten je Section: kompakt (Merksätze) + ausführlich (Erklärung).
-_FRAGMENT_KOMPAKT_RE = re.compile(r"<!--\s*kompakt\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)
-_STUFEN = ("einfach", "mittel", "schwer")
+# 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]:
-    """Parst eine Writer-Datei → [{"kapitel", "titel", "md", "kompakt", "subs"}] in Reihenfolge.
+    """Parse a writer file → [{kapitel, title, md, compact, anker, anker_compact, subs}].
 
-    Zwei optionale Lese-Schichten je Section über `<!-- kompakt -->` / `<!-- ausführlich -->`:
-    Zeilen nach `kompakt` landen in `sec["kompakt"]`, sonst in `sec["md"]` (= ausführlich,
-    auch der Default ohne Marker → rückwärtskompatibel). Optionale `<!-- sub: -->`-Marker
-    sammeln sich weiter in `sec["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: alles ohne Schicht-Marker ist die ausführliche Fassung
+    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)
@@ -150,13 +150,14 @@ def _parse_fragment(text: str) -> list[dict]:
             continue
         m = _FRAGMENT_SECTION_RE.match(s)
         if m:
-            current = {"kapitel": kapitel, "titel": m.group(1), "md": [], "kompakt": [], "subs": []}
+            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 = "kompakt"
+            cur_layer = "compact"
             cur_sub = None
             continue
         if current is not None and _FRAGMENT_AUSF_RE.match(s):
@@ -165,32 +166,48 @@ def _parse_fragment(text: str) -> list[dict]:
             continue
         m = _FRAGMENT_SUB_RE.match(s)
         if m and current is not None:
-            teil = m.group(1).split("|", 1)
-            stufe = teil[0].strip().casefold()
-            cur_sub = {
-                "stufe": stufe if stufe in _STUFEN else "einfach",
-                "titel": teil[1].strip() if len(teil) == 2 else "",
-                "md": [],
-            }
-            current["subs"].append(cur_sub)
+            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 and cur_layer == "md":
-                cur_sub["md"].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:
-        sec["md"] = "\n".join(sec["md"]).strip()
-        sec["kompakt"] = "\n".join(sec["kompakt"]).strip()
-        for sub in sec["subs"]:
+        subs = []
+        for key in sec["_suborder"]:
+            sub = sec["_submap"][key]
             sub["md"] = "\n".join(sub["md"]).strip()
-        sec["subs"] = [sub for sub in sec["subs"] if sub["md"]]
-    return sections
+            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_subbausteine(text: str) -> dict[str, list[str]]:
-    """Parst eine Subbaustein-Datei → {Baustein-Titel: [Subbaustein, …]} in Reihenfolge.
+def _parse_subblocks(text: str) -> dict[str, list[str]]:
+    """Parse a subblock file → {block title: [subblock, …]} in order.
 
-    Format: `<!-- baustein: Titel -->` gefolgt von Listenzeilen `- Subbaustein`.
+    Format: `<!-- block: Title -->` followed by list lines `- Subblock`.
     """
     out: dict[str, list[str]] = {}
     current = None
@@ -210,7 +227,7 @@ def _parse_subbausteine(text: str) -> dict[str, list[str]]:
 
 
 def _split_chunks(chapters: list[dict], n: int) -> list[list[dict]]:
-    """Teilt Kapitel in bis zu n zusammenhängende Chunks, balanciert nach Section-Anzahl."""
+    """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] = []
@@ -231,9 +248,3 @@ def _split_chunks(chapters: list[dict], n: int) -> list[list[dict]]:
     return chunks
 
 
-def _zuteilung_text(chunk: list[dict], entries: dict[int, str]) -> str:
-    lines = []
-    for ch in chunk:
-        lines.append(f"KAPITEL: {ch['title']}")
-        lines.extend(f"- {entries[num]}" for num in ch["nums"])
-    return "\n".join(lines)

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,59 @@
+"""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 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="claude", 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", "subblocks", 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,56 @@
+"""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"},
+    # Subbausteine
+    "SUBBLOCK_CHUNK":         {"default": 10,   "min": 4,    "max": 20,   "step": 2,    "kategorie": "laufzeit", "fidelity": "board2"},
+    "SUBBLOCK_MIN":           {"default": 5,    "min": 2,    "max": 10,   "step": 1,    "kategorie": "auswahl", "fidelity": "board2"},
+    "SUBBLOCK_MAX_ROUNDS":    {"default": 3,    "min": 1,    "max": 5,    "step": 1,    "kategorie": "auswahl", "fidelity": "board2"},
+    "SUBBLOCK_EXTRA_ROUNDS":  {"default": 2,    "min": 0,    "max": 4,    "step": 1,    "kategorie": "auswahl", "fidelity": "board2"},
+    "SUBBLOCK_PANEL":         {"default": 3,    "min": 1,    "max": 5,    "step": 1,    "kategorie": "qualitaet", "fidelity": "board2"},
+    # Facts / Artefakte / Fragen
+    "FACTS_CHUNK_SUBS":       {"default": 10,   "min": 4,    "max": 20,   "step": 2,    "kategorie": "laufzeit", "fidelity": "board2"},
+    "FACTS_CHECK_PANEL":      {"default": 3,    "min": 1,    "max": 5,    "step": 1,    "kategorie": "qualitaet", "fidelity": "board2"},
+    "QUESTION_CHUNK_SUBS":    {"default": 25,   "min": 10,   "max": 50,   "step": 5,    "kategorie": "laufzeit", "fidelity": "board2"},
+    "QUESTION_MAX_ROUNDS":    {"default": 3,    "min": 1,    "max": 5,    "step": 1,    "kategorie": "qualitaet", "fidelity": "board2"},
+    "ARTEFACT_CHUNK_SUBS":    {"default": 25,   "min": 10,   "max": 50,   "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
+    "MAX_WRITER_ROUNDS":      {"default": 2,    "min": 1,    "max": 3,    "step": 1,    "kategorie": "qualitaet", "fidelity": "board2"},
+    "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"},
+    "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
+      }
+    }
+  }
+}

frontend/src/App.vue

@@ -1,12 +1,13 @@
 <script setup>
-import { ref, computed, watch, onMounted, 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, fetchProviders, fetchStats, fetchTopicFortschritt, fetchGuideLocks, fetchGuideSteps, fetchFolders, updateQuelle as apiUpdateQuelle } 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 BausteineUebersicht from './components/BausteineUebersicht.vue'
-import ElementsSidebar from './components/elements/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 backendTopics = ref([])
@@ -14,36 +15,34 @@ 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: [] })   // Ordner für die Quellen-Auswahl
-const bausteineView = ref(false)                 // Bausteine-Übersicht im Hauptbereich
-const ansichtModus = ref('kompakt')              // kompakt | erklärend — je Thema, Default kompakt
+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 locks = ref({})       // Sperr-Gründe pro Format (Backend = einzige Regel-Quelle)
-const guideStepsDone = ref({}) // höchster fertiger Schritt-Index je Format (artefakt-basiert)
-const uiError = ref(null)   // abgewiesene Aktionen (409/400) sichtbar machen
-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) {
@@ -52,25 +51,21 @@ function setProvider(id) {
 }
 
 async function loadFolders() {
-  try {
+  await guard('Failed to load folders:', async () => {
     const [projekt, uni] = await Promise.all([fetchFolders('projekt'), fetchFolders('uni')])
     folders.value = { projekt, uni }
-  } catch (e) {
-    console.error('Fehler beim Laden der Ordner:', e)
-  }
+  })
 }
 
 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)
-  }
+  })
 }
 
 function applyTheme() {
@@ -132,12 +127,12 @@ 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)
   }
 }
 
-// Weggeklickte Fehler bleiben weggeklickt — auch über Reloads (localStorage).
-// Nicht weggeklickte Fehler bleiben sichtbar, bis der Nutzer sie schließt.
+// 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() {
@@ -152,7 +147,7 @@ function handleDismissError(guideId) {
 async function loadGuides() {
   try {
     guides.value = await fetchGuides()
-    // IDs prunen, deren Guide nicht mehr als Fehler existiert
+    // 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)))
@@ -160,97 +155,103 @@ async function loadGuides() {
     }
     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)
-      locks.value = await fetchGuideLocks(selectedTopic.value)
-      guideStepsDone.value = await fetchGuideSteps(selectedTopic.value)
+      blocks.value = await fetchBlocksStatus(selectedTopic.value)
+      progress.value = await fetchTopicProgress(selectedTopic.value)
     } else {
-      bausteine.value = { ...EMPTY_BAUSTEINE }
-      fortschritt.value = {}
-      locks.value = {}
-      guideStepsDone.value = {}
+      blocks.value = { ...EMPTY_BLOCKS }
+      progress.value = {}
     }
-    if (activeBausteine.value.length && !polling.running()) 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)
   }
 }
 
-const FORMAT_ORDER = ['Guide', 'FullGuide', 'Rest']
-
-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
-  bausteineView.value = false
-  elementOpenId.value = null
-  ansichtModus.value = localStorage.getItem('ansicht_' + topic) === 'erklärend' ? 'erklärend' : 'kompakt'
+  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, abPhase = null }) {
+async function handleResetStage({ board, stage, restart = false }) {
   if (!selectedTopic.value) return
   uiError.value = null
   try {
-    // Quelle ist hier schon festgeschrieben; nur abPhase steuert den Re-Run-Umfang.
-    await apiCreateBausteine(selectedTopic.value, instructions, provider.value, undefined, undefined, abPhase)
+    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 loadBausteine()
+  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 handleCreateThema({ topic, instructions, sourceType, sourceOrt }) {
+async function handleRequeueDead() {
+  if (!selectedTopic.value) return
+  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)
@@ -260,10 +261,11 @@ async function handleCreateThema({ topic, instructions, sourceType, sourceOrt })
   }
   await loadTopics()
   selectTopic(topic)
+  mainView.value = 'generation'  // frisches Topic: die Boards sind das Einzige, was passiert
   startPolling()
 }
 
-async function handleUpdateQuelle({ topic, type, ort, spec }) {
+async function handleUpdateSource({ topic, type, ort, spec }) {
   uiError.value = null
   try {
     await apiUpdateQuelle(topic, { type, ort, spec })
@@ -271,29 +273,33 @@ async function handleUpdateQuelle({ topic, type, ort, spec }) {
     uiError.value = e.message
     return
   }
-  await loadBausteine()  // Schritt-Anzeige folgt ggf. der neuen Quelle (z.B. Link → „Quelle laden")
+  await loadBlocks()  // the step display may follow the new source (e.g. link → "load source")
 }
 
-function setAnsicht(modus) {
-  ansichtModus.value = modus
+function setView(modus) {
+  viewMode.value = modus
   if (selectedTopic.value) localStorage.setItem('ansicht_' + selectedTopic.value, modus)
 }
 
-function handleOpenBausteineView() {
+function setLevel(k) {
+  levelView.value = k
+  localStorage.setItem('level', String(k))
+}
+
+function handleOpenBlocksView() {
   if (!selectedTopic.value) return
-  bausteineView.value = true
-  elementsView.value = false
+  mainView.value = 'blocks'
   previewGuide.value = null
 }
 
-async function handleFormatClick({ format, instructions, abStep = null }) {
+async function handleFormatClick({ format, instructions = '', abStep = null }) {
   if (!selectedTopic.value) return
-  // Kein Duplikat-Start: läuft für Thema+Format schon eine Generierung, ignorieren
+  // 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
+  if (running) { handleOpenGuideBoard(format); return }
   uiError.value = null
   try {
     await apiCreate(selectedTopic.value, format, instructions, provider.value, abStep)
@@ -301,31 +307,93 @@ async function handleFormatClick({ format, instructions, abStep = null }) {
     uiError.value = e.message
     return
   }
+  handleOpenGuideBoard(format)  // Start → direkt aufs Live-Board
   await loadGuides()
   startPolling()
 }
 
+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 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
-  bausteineView.value = false
+  mainView.value = 'detail'
 }
 
-function handleOpenElements() {
+function handleGeneralExam() {
   if (!selectedTopic.value) return
-  elementsView.value = true
-  bausteineView.value = false
-  // 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) {
+  uiError.value = null
+  try {
     await deleteGuide(guideId, slots)
+  } catch (e) {
+    uiError.value = e.message
+    return
+  }
   if (previewGuide.value?.id === guideId) {
     previewGuide.value = null
   }
@@ -333,8 +401,8 @@ async function handleDeleteGuide(guideId, slots = false) {
 }
 
 const polling = usePolling(
-  () => Promise.all([loadGuides(), loadBausteine(), loadTopics()]),
-  () => hasActiveGuides.value || activeBausteine.value.length > 0,
+  () => Promise.all([loadGuides(), loadBlocks(), loadTopics()]),
+  () => hasActiveGuides.value || activeBlocks.value.length > 0,
 )
 const startPolling = polling.start
 
@@ -361,12 +429,8 @@ async function handleDeleteTopic(topic) {
 onMounted(async () => {
   await Promise.all([loadGuides(), loadTopics(), loadProviders(), loadFolders()])
   const savedTopic = localStorage.getItem('lastTopic')
-  const savedFormat = localStorage.getItem('lastFormat')
   if (savedTopic && topics.value.includes(savedTopic)) {
-    selectTopic(savedTopic)
-    await nextTick()
-    const g = doneByFormat.value[savedFormat]
-    if (g) previewGuide.value = g
+    selectTopic(savedTopic)  // lands on the blocks overview
   } else if (!selectedTopic.value && topics.value.length) {
     selectTopic(topics.value[0])
   }
@@ -374,91 +438,109 @@ onMounted(async () => {
 </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"
       :selectedTopic="selectedTopic"
       :stats="stats"
-      :fortschritt="fortschritt"
-      :locks="locks"
-      :guideStepsDone="guideStepsDone"
+      :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="ansichtModus"
+      :ansichtModus="viewMode"
+      :stufeAnsicht="levelView"
       @setProvider="setProvider"
       @toggleDark="toggleDark"
-      @setAnsicht="setAnsicht"
+      @setAnsicht="setView"
+      @setStufe="setLevel"
+      @generalExam="handleGeneralExam"
+      @practice="handlePractice"
       @select="selectTopic"
-      @create="createTopic"
-      @createThema="handleCreateThema"
-      @updateQuelle="handleUpdateQuelle"
-      @openBausteineView="handleOpenBausteineView"
-      @formatClick="handleFormatClick"
-      @bausteineClick="handleBausteineClick"
-      @cancelBausteine="handleCancelBausteine"
-      @resetBausteine="handleResetBausteine"
+      @createThema="handleCreateTopic"
+      @updateSource="handleUpdateSource"
+      @openBausteineView="handleOpenBlocksView"
+      @openGuideBoard="handleOpenGuideBoard"
+      @bausteineClick="handleBlocksClick"
       @deleteTopic="handleDeleteTopic"
-      @cancelGuide="handleCancel"
-      @deleteGuide="handleDeleteGuide"
       @dismissError="handleDismissError"
       @dismissUiError="uiError = null"
       @preview="handlePreview"
-      @openElements="handleOpenElements"
+      @openGeneration="handleOpenGeneration"
       @togglePin="toggleSidebarPin"
       @sidebarLeave="onSidebarLeave"
     />
-    <BausteineUebersicht
-      v-if="selectedTopic && bausteineView"
+    <BlocksOverview
+      v-if="selectedTopic && mainView === 'blocks'"
       :topic="selectedTopic"
-      @close="bausteineView = false"
+      :generating="blocks.generating"
+      :progress="blocks.progress"
+      :ready="blocks.ready"
+      :partial="blocks.partial"
+      @close="mainView = 'detail'"
+      @openGeneration="handleOpenGeneration"
     />
-    <ElementsOverview
-      v-else-if="selectedTopic && elementsView"
+    <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"
-      :doneByFormat="doneByFormat"
-      :themaAbgeschlossen="!!fortschritt.abgeschlossen"
-      :ansichtModus="ansichtModus"
-      @progressChanged="loadStats(); loadBausteine()"
-      @setAnsicht="setAnsicht"
+      :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>
 
@@ -482,6 +564,11 @@ onMounted(async () => {
   --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;
@@ -557,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;
@@ -583,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;
@@ -592,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

@@ -18,16 +18,6 @@ export async function fetchGuides() {
   return res.json()
 }
 
-export async function fetchGuideSteps(topic) {
-  const res = await fetch(`${BASE}/guides/steps?topic=${encodeURIComponent(topic)}`)
-  return res.json()
-}
-
-export async function fetchGuideLocks(topic) {
-  const res = await fetch(`${BASE}/guides/locks?topic=${encodeURIComponent(topic)}`)
-  return res.json()
-}
-
 export async function createGuide(topic, format, instructions = '', provider = 'claude', abStep = null) {
   const res = await fetch(`${BASE}/guides`, {
     method: 'POST',
@@ -37,70 +27,159 @@ export async function createGuide(topic, format, instructions = '', provider = '
   return jsonOrThrow(res)
 }
 
-export async function fetchActiveBausteine() {
-  const res = await fetch(`${BASE}/bausteine/active`)
+export async function fetchActiveBlocks() {
+  const res = await fetch(`${BASE}/blocks/active`)
   return res.json()
 }
 
-export async function fetchBausteineStatus(topic) {
-  const res = await fetch(`${BASE}/bausteine/status?topic=${encodeURIComponent(topic)}`)
+export async function fetchBlocksStatus(topic) {
+  const res = await fetch(`${BASE}/blocks/status?topic=${encodeURIComponent(topic)}`)
   return res.json()
 }
 
-export async function createBausteine(topic, instructions = '', provider = 'claude', sourceType = 'thema', sourceOrt = '', abPhase = null) {
-  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, source_type: sourceType, source_ort: sourceOrt, ab_phase: abPhase }),
+    body: JSON.stringify({ topic, instructions, provider, source_type: sourceType, source_location: sourceOrt, research, qa_force: qaForce }),
   })
   return jsonOrThrow(res)
 }
 
-export async function cancelBausteine(topic) {
-  await fetch(`${BASE}/bausteine/cancel?topic=${encodeURIComponent(topic)}`, { method: 'POST' })
-}
-
-export async function deleteBausteine(topic) {
-  await fetch(`${BASE}/bausteine?topic=${encodeURIComponent(topic)}`, { method: 'DELETE' })
-}
-
-// --- Baustein-Lernen: Chat, Prüfung ---
-
-export async function fetchBausteinLernstand(topic) {
-  const res = await fetch(`${BASE}/bausteine/lernstand?topic=${encodeURIComponent(topic)}`)
+// 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 chatBaustein({ topic, baustein, section, section_kompakt = '', messages, provider }) {
-  const res = await fetch(`${BASE}/bausteine/chat`, {
+// 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, baustein, section, section_kompakt, messages, provider }),
+    body: JSON.stringify({ topic, llm }),
   })
   return jsonOrThrow(res)
 }
 
-export async function pruefeBaustein({
-  topic, baustein, section, section_kompakt = '', provider,
-  aktion = 'frage', frage = '', letzte_bewertung = '', vermeide = [],
-  nachgefragt = false, begruendung = '', muster = '', cap = 6, messages = [], gruendlich = false,
-  auswahl = [], korrekt = [], loesung = '', alternativen = [], eingabe = '', schwer = false,
+// 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)
+}
+
+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}/bausteine/pruefung`, {
+  const res = await fetch(`${BASE}/blocks/exam`, {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ topic, baustein, section, section_kompakt, aktion, frage, letzte_bewertung, vermeide, nachgefragt, begruendung, muster, cap, messages, provider, gruendlich, auswahl, korrekt, loesung, alternativen, eingabe, schwer }),
+    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 fetchFrageMuster(topic, baustein) {
-  const res = await fetch(`${BASE}/bausteine/frage-muster?topic=${encodeURIComponent(topic)}&baustein=${encodeURIComponent(baustein)}`)
+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 fetchTopicFortschritt(topic) {
-  const res = await fetch(`${BASE}/topics/fortschritt?topic=${encodeURIComponent(topic)}`)
+export async function fetchTopicProgress(topic) {
+  const res = await fetch(`${BASE}/topics/progress?topic=${encodeURIComponent(topic)}`)
   return res.json()
 }
 
@@ -114,37 +193,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 fetchQuelle(topic) {
-  const res = await fetch(`${BASE}/bausteine/quelle?topic=${encodeURIComponent(topic)}`)
+export async function fetchSource(topic) {
+  const res = await fetch(`${BASE}/blocks/source?topic=${encodeURIComponent(topic)}`)
   return jsonOrThrow(res)
 }
 
-export async function updateQuelle(topic, { type, ort = '', spec = '' }) {
-  const res = await fetch(`${BASE}/bausteine/quelle`, {
+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, ort, spec }),
+    body: JSON.stringify({ topic, type, location: ort, spec }),
   })
   return jsonOrThrow(res)
 }
 
-export async function fetchBausteineUebersicht(topic) {
-  const res = await fetch(`${BASE}/bausteine/uebersicht?topic=${encodeURIComponent(topic)}`)
+export async function fetchBlocksCompleteness(topic) {
+  const res = await fetch(`${BASE}/blocks/completeness?topic=${encodeURIComponent(topic)}`)
   return jsonOrThrow(res)
 }
 
-export async function deleteProject(name) {
-  await fetch(`${BASE}/projects/${encodeURIComponent(name)}`, { method: 'DELETE' })
+export async function fetchBlocksOverview(topic) {
+  const res = await fetch(`${BASE}/blocks/overview?topic=${encodeURIComponent(topic)}`)
+  return jsonOrThrow(res)
 }
 
 export async function cancelGuide(id) {
@@ -155,12 +230,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()
@@ -187,68 +303,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

@@ -7,11 +7,22 @@
   margin: 0 0 0.5em;
 }
 
-/* KaTeX: lange Block-Formeln scrollen statt das Layout zu sprengen */
+/* 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;
+  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 {

frontend/src/components/BausteinFokus.vue

@@ -1,218 +0,0 @@
-<script setup>
-import BausteinPanel from './BausteinPanel.vue'
-import { renderMarkdown } from '../markdown.js'
-
-const props = defineProps({
-  baustein: { 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 },
-  tab: { type: String, default: 'pruefung' },
-  ansicht: { type: String, default: 'kompakt' }, // kompakt | erklärend — linke Guide-Spalte
-  hasPrev: { type: Boolean, default: false },
-  hasNext: { type: Boolean, default: false },
-  fortschritt: { type: Object, default: () => ({ total: 0, absolviert: 0, verstanden: 0, gemeistert: 0 }) },
-})
-
-import { computed, onMounted, onUnmounted, ref } from 'vue'
-
-const emit = defineEmits(['close', 'prev', 'next', 'statusChanged', 'setAnsicht'])
-
-const guideEl = ref(null)  // linke Guide-Spalte (Scroll-Ziel für ALT+↑/↓)
-const rightEl = ref(null)  // rechte Spalte (Prüfungs-Panel mit Eingabefeld)
-
-// ALT ist der Modifier der Fokus-Ansicht. Plain Pfeile bleiben Browser-Standard.
-// ALT+←/→ blättert Baustein, ALT+↑/↓ scrollt den Guide. Ein reiner ALT-Tipp
-// (drücken+loslassen ohne andere Taste) toggelt den Fokus aufs Eingabefeld.
-let altAlone = false
-function onKeyDown(e) {
-  if (e.key === 'Alt') { altAlone = true; e.preventDefault(); return }  // unterdrückt Firefox-Menüleiste
-  if (e.ctrlKey || e.metaKey || !e.altKey) return  // plain/andere → normal
-  altAlone = false                                  // ALT+irgendwas = kein 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 }  // Fenster-Blur (ALT+Tab) → kein falscher Tipp
-function toggleInput() {
-  // Antwortfeld der aktuellen Form: Erklären = textarea, Lückentext-frei = 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)) + '%'
-
-// Akzentfarbe nach Stand des aktuellen Bausteins: gemeistert=gold, verstanden=lila, absolviert=grün.
-const standFarbe = computed(() => {
-  const s = props.status || {}
-  if (s.gemeistert) return '#d4af37'
-  if (s.verstanden) return '#8b5cf6'
-  if (s.absolviert) return 'var(--success-border)'
-  return 'var(--border)'
-})
-</script>
-
-<template>
-  <div class="fokus-overlay" :style="{ '--stand': standFarbe }">
-    <div class="fokus-bar">
-      <div class="fokus-bar-inner">
-        <button class="fokus-btn" :disabled="!hasPrev" title="Voriger Baustein" @click="$emit('prev')">←</button>
-        <button class="fokus-btn" :disabled="!hasNext" title="Nächster Baustein" @click="$emit('next')">→</button>
-        <span class="fokus-titel">{{ baustein.title }}</span>
-        <span v-if="status?.gemeistert" class="stand-badge gold">✓✓✓ Gemeistert</span>
-        <span v-else-if="status?.verstanden" class="stand-badge lila">✓✓ Verstanden</span>
-        <span v-else-if="status?.absolviert" class="stand-badge gruen">✓ Absolviert</span>
-        <span class="fokus-spacer"></span>
-        <button class="fokus-btn" title="Vollansicht beenden" @click="$emit('close')">✕</button>
-      </div>
-    </div>
-    <div class="fokus-xp" :title="`${fortschritt.absolviert}/${fortschritt.total} absolviert · ${fortschritt.verstanden} verstanden · ${fortschritt.gemeistert} gemeistert`">
-      <div class="xp-seg gold" :style="{ width: pct(fortschritt.gemeistert) }"></div>
-      <div class="xp-seg lila" :style="{ width: pct(fortschritt.verstanden - fortschritt.gemeistert) }"></div>
-      <div class="xp-seg gruen" :style="{ width: pct(fortschritt.absolviert - fortschritt.verstanden) }"></div>
-    </div>
-    <div class="fokus-body">
-      <div ref="guideEl" class="fokus-col left">
-        <div class="markdown" v-html="renderMarkdown(ansicht === 'kompakt' ? (baustein.kompakt || baustein.md) : baustein.md)"></div>
-      </div>
-      <div ref="rightEl" class="fokus-col right">
-        <BausteinPanel
-          mode="full"
-          :key="baustein.title + '|' + tab"
-          :initial-tab="tab"
-          :topic="topic"
-          :baustein="baustein.title"
-          :section="baustein.md"
-          :section-kompakt="baustein.kompakt || ''"
-          :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;
-  /* Halbtransparent + Blur: die Guide-Liste dahinter scheint verschwommen durch die grauen Flächen. */
-  background: color-mix(in srgb, var(--bg-preview) 60%, transparent);
-  backdrop-filter: blur(10px);
-  display: grid;
-  grid-template-rows: auto auto 1fr; /* Header / XP-Leiste / Body */
-}
-.fokus-bar {
-  padding: 0.5rem 0;
-  border-bottom: 1px solid var(--border);
-  background: var(--panel);
-}
-/* Header-Inhalt fluchtet mit dem Body (gleiche max-width + Innenabstand). */
-.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; }
-
-/* Erfahrungsleiste oben: füllt sich von links — gold (gemeistert) → lila (verstanden) → grün (absolviert). */
-.fokus-xp { display: flex; height: 6px; background: var(--panel-soft); }
-.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-titel { 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; }
-
-/* Zwei abgehobene Karten auf grauem „Schreibtisch" (--bg-preview vom 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;
-  /* Karte kippt nach Baustein-Stand: farbiger Rahmen + getönter Hintergrund (grün/lila/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);
-}
-/* Links: breite Lese-Karte, Text in Lesebreite zentriert. */
-.fokus-col.left { flex: 1; padding: 2rem 2.5rem; }
-.fokus-col.left > * { max-width: 74ch; margin-inline: auto; }
-/* Rechts: Arbeits-Karte; Panel darin randlos (Karte ist der Rahmen). */
-.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: die rechte Karte als Flex-Spalte — Prüfungs-/Chat-Verlauf füllt die
-   volle Höhe und scrollt intern, Eingabe + Buttons bleiben unten. */
-@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; }
-}
-</style>

frontend/src/components/BausteineUebersicht.vue

@@ -1,225 +0,0 @@
-<script setup>
-import { ref, computed, watch } from 'vue'
-import { fetchBausteineUebersicht } from '../api.js'
-
-const props = defineProps({
-  topic: { type: String, required: true },
-})
-const emit = defineEmits(['close'])
-
-const items = ref([])
-const loading = ref(true)
-const error = ref(null)
-
-// Stufen-Reihenfolge + Anzeige-Label (Farbe via CSS-Klasse st-<key>)
-const STUFEN = [
-  { key: 'einfach', label: 'Einfach' },
-  { key: 'mittel', label: 'Mittel' },
-  { key: 'schwer', label: 'Schwer' },
-]
-
-watch(() => props.topic, load, { immediate: true })
-
-async function load() {
-  loading.value = true
-  error.value = null
-  items.value = []
-  try {
-    items.value = await fetchBausteineUebersicht(props.topic)
-  } catch (e) {
-    error.value = 'Übersicht nicht verfügbar — bitte erst Bausteine erstellen.'
-  } finally {
-    loading.value = false
-  }
-}
-
-// Baustein relevant = hat ≥1 relevanten Subbaustein (gleiche Regel wie der Guide).
-// Ohne Relevanz-Daten (Alt-Themen) nicht dimmen.
-function relevant(b) {
-  const mitRelevanz = (b.subbausteine || []).filter((s) => s.relevanz)
-  return !mitRelevanz.length || mitRelevanz.some((s) => s.relevanz === 'relevant')
-}
-
-// Nur nicht-leere Stufen-Gruppen je Baustein (v-if + v-for nicht auf einem Element)
-function gruppen(b) {
-  return STUFEN
-    .map((st) => ({ ...st, subs: (b.subbausteine || []).filter((s) => s.stufe === st.key) }))
-    .filter((g) => g.subs.length)
-}
-
-const subTotal = computed(() => items.value.reduce((n, b) => n + (b.subbausteine?.length || 0), 0))
-</script>
-
-<template>
-  <div class="bk-view">
-    <header class="bk-head">
-      <h1>{{ topic }}</h1>
-      <span class="bk-sub">Bausteine-Übersicht</span>
-      <span v-if="items.length" class="bk-count">{{ items.length }} Bausteine · {{ subTotal }} Subbausteine</span>
-      <span class="bk-spacer"></span>
-      <button class="bk-close" title="Schließen" @click="emit('close')">✕</button>
-    </header>
-
-    <div v-if="loading" class="bk-empty-state">Lade…</div>
-    <div v-else-if="error" class="bk-empty-state">{{ error }}</div>
-    <div v-else-if="!items.length" class="bk-empty-state">Noch keine Bausteine.</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 : 'Nicht relevant — kommt später in den „Rest“'"
-      >
-        <h3 class="bk-title"><span class="bk-num">{{ b.num }}</span>{{ b.titel }}</h3>
-        <p v-if="b.beschreibung" class="bk-desc">{{ b.beschreibung }}</p>
-        <div v-if="b.subbausteine && b.subbausteine.length" class="bk-stufen">
-          <div v-for="g in gruppen(b)" :key="g.key" class="bk-stufe" :class="'st-' + g.key">
-            <span class="bk-stufe-label">{{ g.label }}</span>
-            <ul>
-              <li v-for="s in g.subs" :key="s.titel" :class="{ rand: s.relevanz === 'rand' }">
-                {{ s.titel }}<span v-if="s.relevanz === 'rand'" class="rand-tag" title="Randthema — kommt später in den „Rest“">Rand</span>
-              </li>
-            </ul>
-          </div>
-        </div>
-        <p v-else class="bk-no-subs">Keine Subbausteine.</p>
-      </article>
-    </div>
-  </div>
-</template>
-
-<style scoped>
-.bk-view {
-  flex: 1;
-  min-width: 0;
-  height: 100dvh;
-  display: flex;
-  flex-direction: column;
-  background: var(--bg-preview);
-}
-
-.bk-head {
-  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-empty-state {
-  flex: 1;
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  color: var(--text-muted);
-}
-
-.bk-grid {
-  flex: 1;
-  overflow-y: auto;
-  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;
-}
-/* Nicht relevante Bausteine (kein relevanter Subbaustein) gedimmt */
-.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-stufen { display: flex; flex-direction: column; gap: 0.55rem; }
-.bk-stufe {
-  border-left: 3px solid var(--st);
-  padding-left: 0.6rem;
-}
-.bk-stufe.st-einfach { --st: var(--success-border); }
-.bk-stufe.st-mittel { --st: var(--warning-border); }
-.bk-stufe.st-schwer { --st: var(--danger); }
-
-.bk-stufe-label {
-  font-size: 0.66rem;
-  font-weight: 700;
-  text-transform: uppercase;
-  letter-spacing: 0.04em;
-  color: var(--st);
-}
-.bk-stufe ul {
-  list-style: disc;
-  margin: 0.25rem 0 0;
-  padding-left: 1.15rem;
-}
-.bk-stufe li {
-  font-size: 0.85rem;
-  color: var(--text);
-  line-height: 1.35;
-  margin-bottom: 2px;
-}
-.bk-stufe li::marker { color: var(--text-faint); }
-.bk-stufe 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/BlockFocus.vue

@@ -0,0 +1,411 @@
+<script setup>
+import BlockPanel from './BlockPanel.vue'
+import { renderMarkdown, renderBlocks } from '../markdown.js'
+import { stufeFuer } 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,
+)
+const blocks = computed(() => renderBlocks(displayedText.value))
+// 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="(b, i) in blocks" :key="i">
+            <div class="md-block" v-html="b.html" @contextmenu.prevent="blockMenu(i, $event)"></div>
+            <div v-if="suggestions[i]" class="block-vorschlag">
+              <div v-if="suggestions[i].running" class="bv-status">Check Section…</div>
+              <template v-else>
+                <p v-if="suggestions[i].error" class="bv-fehler">{{ suggestions[i].error }}</p>
+                <div class="markdown bv-new" v-html="renderMarkdown(suggestions[i].revised)"></div>
+                <div class="bv-aktionen">
+                  <button class="bv-btn ja" title="Apply" @click="applyBlock(i)">✓</button>
+                  <button class="bv-btn" title="Discard" @click="discardBlock(i)">✗</button>
+                  <button class="bv-btn" :class="{ aktiv: suggestions[i].editOpen }" title="Add hint" @click="editBlock(i)">✏️</button>
+                </div>
+                <div v-if="suggestions[i].editOpen" class="bv-edit">
+                  <input v-model="suggestions[i].hint" class="bv-input" placeholder="Extra info → check again" @keyup.enter="sendBlockEdit(i)" />
+                  <button class="bv-btn ja" title="Check again" @click="sendBlockEdit(i)">↻</button>
+                </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/ElementsOverview.vue

@@ -1,170 +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: Basis global (assets/markdown.css), hier nur Grundschrift der Karten */
-.markdown {
-  font-size: 0.9rem;
-  line-height: 1.55;
-  color: var(--text);
-}
-</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)
+    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`
+  } 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,187 @@
+<script setup>
+import { ref, computed, watch, onUnmounted } from 'vue'
+import { fetchGuideBoard } 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', 'fakten_gate', 'coverage', 'lesbarkeit']
+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
+}
+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" 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,104 +1,195 @@
 <script setup>
-import { computed, ref, watch, nextTick, onMounted, onUnmounted } from 'vue'
-import { fetchGuideContent, chatGuide, fetchBausteinLernstand } 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 BausteinPanel from './BausteinPanel.vue'
-import BausteinFokus from './BausteinFokus.vue'
+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
-  doneByFormat: { type: Object, default: () => ({}) }, // Format → fertiger Guide (Themen-bezogen)
   themaAbgeschlossen: { type: Boolean, default: false },
-  ansichtModus: { type: String, default: 'kompakt' }, // kompakt | erklärend
+  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', 'setAnsicht'])
+const emit = defineEmits(['progressChanged', 'setAnsicht', 'openSidebar', 'fokusActive'])
 
-// Rotierende Kapitel-Akzentfarben (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 scrollEl = ref(null)
-const lernstand = ref({}) // Prüfungs-Stand pro Baustein-Titel — VOR dem immediate-Watch (loadContent nutzt es)
+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 {
+        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
-  lernstand.value = {}
+  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 {
-    lernstand.value = (await fetchBausteinLernstand(g.topic)).bausteine || {}
-  } catch { /* offline → leer */ }
+    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' })
 }
 
-// --- Baustein-Lernen: Prüfungs-Stand pro Baustein-Titel (lernstand oben deklariert) ---
-function onBausteinStatus(baustein, status) {
-  const warAbsolviert = lernstand.value[baustein]?.absolviert
-  lernstand.value = { ...lernstand.value, [baustein]: status }
-  if (status.absolviert && !warAbsolviert) emit('progressChanged') // Locks/Stats neu laden
+// --- 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
 }
 
-// --- Vollbild-Fokus: ein Baustein groß, Guide links + Prüfung rechts ---
-const fokusIndex = ref(null)        // Index in der flachen Baustein-Liste; null = zu
-const fokusTab = ref('pruefung')
-const bausteine = computed(() =>
+// 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)
+    }
+  }
+}
+
+// --- 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 fokusBaustein = computed(() => (fokusIndex.value === null ? null : bausteine.value[fokusIndex.value]))
+const focusBlock = computed(() => (focusIndex.value === null ? null : blocks.value[focusIndex.value]))
 
-function openFokus(baustein, tab) {
-  if (!istPruefbar(baustein)) return // reine Lese-Sections (Rest/Rand) öffnen keinen Prüfungs-Fokus
-  const i = bausteine.value.findIndex((s) => s.title === baustein.title)
+// 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
-  fokusIndex.value = i
-  fokusTab.value = tab || 'pruefung'
+  focusIndex.value = i
+  focusTab.value = tab || 'exam'
 }
-// Nur prüfbare Sections im Fokus anspringen (FullGuide hat dazwischen reine Lese-Sections).
-function fokusPrev() {
-  for (let i = fokusIndex.value - 1; i >= 0; i--) if (istPruefbar(bausteine.value[i])) { fokusIndex.value = i; return }
+// 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 fokusNext() {
-  for (let i = fokusIndex.value + 1; i < bausteine.value.length; i++) if (istPruefbar(bausteine.value[i])) { fokusIndex.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 }
 }
 
-// Erfahrungsleiste: Lernstand über alle Bausteine des Guides (sticky, absolviert ⊇ verstanden ⊇ gemeistert).
-const fortschritt = computed(() => {
-  let a = 0, v = 0, g = 0
-  for (const s of bausteine.value) {
-    const l = lernstand.value[s.title] || {}
-    if (l.absolviert) a++
-    if (l.verstanden) v++
-    if (l.gemeistert) g++
+// 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 { total: bausteine.value.length, absolviert: a, verstanden: v, gemeistert: g }
+  return z
 })
 
-// Prüfung läuft voll 0–30, sobald Guide ODER FullGuide fertig ist (gleicher Baustein-Score).
-const cap = computed(() => ((props.doneByFormat?.Guide || props.doneByFormat?.FullGuide) ? 30 : 6))
-
-// Section prüfbar? Rest nie. Sonst prüfbar, außer das Feld ist explizit false (FullGuide-Rand).
-// Fehlt das Feld (alte Guides ohne `pruefbar`) → prüfbar, damit Bestands-Guides weiter funktionieren.
-function istPruefbar(s) {
-  return props.previewGuide?.format !== 'Rest' && s.pruefbar !== false
+// cap per block = 4×relevant subblocks (provided by the backend in learnstate[title].cap).
+function capOf(title) {
+  return learnstate.value[title]?.cap || 10
 }
 
-// --- Chat (Mechanik in useChat; Kontext-Extraktion bleibt hier) ---
+// 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, {
@@ -120,19 +211,13 @@ function closeChat() {
   chat.reset()
 }
 
-// Mobil schließen sich Chat und Elemente-Sidebar gegenseitig aus —
-// nebeneinander ist kein Platz, die Sidebar würde den Chat überdecken.
-watch(() => props.elementsOpen, (open) => {
-  if (open && chatOpen.value && window.matchMedia('(max-width: 768px)').matches) closeChat()
-})
-
 function onDocMouseDown(e) {
   if (!chatOpen.value) return
   if (panelEl.value && panelEl.value.contains(e.target)) return
   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()
@@ -162,7 +247,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
@@ -184,7 +269,12 @@ function extractContext() {
         <header class="guide-head">
           <h1>{{ previewGuide.topic }}</h1>
           <span class="guide-format">{{ previewGuide.format }}</span>
-          <span v-if="themaAbgeschlossen" class="thema-done" title="Alle Bausteine gemeistert (18/18)">✓ Thema abgeschlossen</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
@@ -198,25 +288,26 @@ function extractContext() {
             <article
               v-for="s in ch.sections"
               :key="s.num"
-              :class="['section-card', lernstand[s.title]?.gemeistert ? 'gemeistert' : (lernstand[s.title]?.verstanden ? 'verstanden' : (lernstand[s.title]?.absolviert ? 'absolviert' : ''))]"
+              :data-num="s.num"
+              class="section-card"
+              :style="levelOf(s.title) ? { borderLeftColor: levelOf(s.title).farbe } : {}"
             >
-              <h3 :class="{ 'baustein-klick': istPruefbar(s) }" @click="istPruefbar(s) && openFokus(s, 'pruefung')">
+              <h3 :class="{ 'block-klick': isCheckable(s) }" @click="isCheckable(s) && openFocus(s, 'exam')">
                 {{ s.title }}
-                <template v-if="istPruefbar(s)">
-                  <span v-if="lernstand[s.title]?.gemeistert" class="baustein-done gemeistert" title="Gemeistert (25/25)">✓✓✓ Gemeistert</span>
-                  <span v-else-if="lernstand[s.title]?.verstanden" class="baustein-done verstanden" title="Vollständig verstanden (10/10)">✓✓ Verstanden</span>
-                  <span v-else-if="lernstand[s.title]?.absolviert" class="baustein-done" title="Prüfung bestanden">✓ Absolviert</span>
+                <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 class="section-body markdown" v-html="renderMarkdown(ansichtModus === 'kompakt' ? (s.kompakt || s.md) : s.md)"></div>
-              <BausteinPanel
-                v-if="istPruefbar(s)"
+              <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"
-                :baustein="s.title"
-                :status="lernstand[s.title]"
-                :cap="cap"
+                :block="s.title"
+                :status="learnstate[s.title]"
+                :cap="capOf(s.title)"
                 :topic="previewGuide.topic"
-                @open-fokus="(tab) => openFokus(s, tab)"
+                @open-fokus="(tab) => openFocus(s, tab)"
               />
             </article>
           </div>
@@ -225,60 +316,63 @@ function extractContext() {
     </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>
 
-    <BausteinFokus
-      v-if="fokusBaustein"
-      :baustein="fokusBaustein"
+    <BlockFocus
+      v-if="focusBlock"
+      :block="focusBlock"
       :topic="previewGuide.topic"
+      :guide-id="previewGuide.id"
       :provider="provider"
-      :fortschritt="fortschritt"
-      :status="lernstand[fokusBaustein.title]"
-      :cap="cap"
-      :tab="fokusTab"
+      :fortschritt="progress"
+      :status="learnstate[focusBlock.title]"
+      :cap="capOf(focusBlock.title)"
+      :tab="focusTab"
       :ansicht="ansichtModus"
-      :has-prev="fokusIndex > 0"
-      :has-next="fokusIndex < bausteine.length - 1"
-      @prev="fokusPrev"
-      @next="fokusNext"
-      @close="fokusIndex = null"
+      :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) => onBausteinStatus(st.baustein, st)"
+      @status-changed="(st) => onBlockStatus(st.block, st)"
+      @open-sidebar="$emit('openSidebar')"
+      @section-updated="onSectionUpdated"
     />
 
-    <button v-if="previewGuide && !chatOpen && fokusIndex === null" class="chat-fab" :class="{ shifted: elementsOpen }" title="Fragen zum Guide" @click="openChat">💬</button>
+    <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" :class="{ shifted: elementsOpen }">
+    <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" @scroll="onScroll">
-        <p v-if="!messages.length" class="chat-hint">Stell eine Frage zum aktuellen Abschnitt.</p>
+        <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"
           :class="{ cancel: loading }"
-          :title="loading ? 'Abbrechen' : 'Senden'"
+          :title="loading ? 'Cancel' : 'Send'"
           @click="send"
         >{{ loading ? '✕' : '➤' }}</button>
       </div>
@@ -289,8 +383,8 @@ function extractContext() {
 <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;
@@ -299,7 +393,7 @@ function extractContext() {
 .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);
 }
@@ -308,7 +402,7 @@ function extractContext() {
   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;
 }
 
@@ -323,12 +417,41 @@ function extractContext() {
   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;
@@ -381,7 +504,7 @@ function extractContext() {
   margin-bottom: 0.75rem;
 }
 
-.baustein-done {
+.block-done {
   float: right;
   margin-left: 0.5rem;
   padding: 0.12rem 0.6rem;
@@ -395,38 +518,38 @@ function extractContext() {
   white-space: nowrap;
 }
 
-/* Absolvierte Bausteine: Karte kippt sichtbar auf Grün */
-.guide-content .section-card.absolviert {
+/* 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));
 }
 
-/* Verstandene Bausteine (10/10): Lila */
-.baustein-done.verstanden {
+/* 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.verstanden {
+.guide-content .section-card.understood {
   border-color: #8b5cf6;
   border-top: 3px solid #8b5cf6;
   background: color-mix(in srgb, #8b5cf6 7%, var(--panel));
 }
 
-/* Gemeisterte Bausteine (Meisterpfad 25/25): Gold */
-.baustein-done.gemeistert {
+/* 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.gemeistert {
+.guide-content .section-card.mastered {
   border-color: #d4af37;
   border-top: 3px solid #d4af37;
   background: color-mix(in srgb, #d4af37 8%, var(--panel));
 }
 
-/* Guides: Karten tragen die Kapitel-Akzentfarbe */
+/* 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));
@@ -440,9 +563,13 @@ function extractContext() {
   }
 }
 
-/* Titel-Klick öffnet die Vollansicht. */
-.section-card h3.baustein-klick { cursor: pointer; width: fit-content; }
-.section-card h3.baustein-klick:hover { color: var(--accent); }
+/* 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); }
+
+/* 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;
@@ -452,16 +579,16 @@ function extractContext() {
   color: var(--text-muted);
 }
 
-/* --- Markdown: Basis global (assets/markdown.css), hier nur Lese-Ansicht-Overrides --- */
+/* --- Markdown: base global (assets/markdown.css), here only reading-view overrides --- */
 
-/* Breite Lese-Ansicht: Code scrollt horizontal statt umzubrechen */
+/* Wide reading view: code scrolls horizontally instead of wrapping */
 .markdown :deep(pre) {
   white-space: pre;
   overflow-wrap: normal;
   overflow-x: auto;
 }
 
-/* „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;
@@ -470,8 +597,8 @@ function extractContext() {
   margin: 0.9em 0 0.35em;
 }
 
-/* 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;
@@ -504,23 +631,6 @@ function extractContext() {
   background: var(--accent-hover);
 }
 
-/* Element-Sidebar (320px) offen → Chat links daneben anzeigen */
-.chat-fab.shifted {
-  right: calc(1.5rem + 320px);
-}
-
-.chat-panel.shifted {
-  right: calc(1.5rem + 320px);
-}
-
-/* Mobil liegt die Elemente-Sidebar als Overlay über dem Chat — FAB/Panel ausblenden */
-@media (max-width: 768px) {
-  .chat-fab.shifted,
-  .chat-panel.shifted {
-    display: none;
-  }
-}
-
 .chat-panel {
   position: fixed;
   right: 1.5rem;
@@ -654,4 +764,25 @@ function extractContext() {
 .chat-input button.cancel {
   background: var(--danger);
 }
+
+/* Neu freigeschaltete Subbausteine (Auto-Stufe): dezenter 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;
+}
 </style>

frontend/src/components/TopicSidebar.vue

@@ -1,33 +1,32 @@
 <script setup>
 import { ref, reactive, computed } from 'vue'
 import { useConfirm } from '../composables/useConfirm.js'
-import { fetchQuelle } from '../api.js'
+import { fetchSource } from '../api.js'
 
 const props = defineProps({
   topics: { type: Array, required: true },
   selectedTopic: { type: String, default: null },
   stats: { type: Object, default: null },
   fortschritt: { type: Object, default: () => ({}) },
-  locks: { type: Object, default: () => ({}) },
-  guideStepsDone: { type: Object, default: () => ({}) }, // höchster fertiger Schritt je Format (-1 = keiner)
   uiError: { type: String, default: null },
   doneByFormat: { type: Object, default: () => ({}) },
   latestByFormat: { type: Object, default: () => ({}) },
   allGuides: { type: Array, default: () => [] },
   dismissedErrors: { type: Object, default: () => new Set() },
-  bausteine: { type: Object, default: () => ({ ready: false, generating: false, progress: null, error: null }) },
+  blocks: { type: Object, default: () => ({ ready: false, generating: false, progress: null, error: null }) },
   activeBausteine: { type: Array, default: () => [] },
   pinned: { type: Boolean, default: true },
   dark: { type: Boolean, default: false },
   provider: { type: String, default: 'claude' },
   providers: { type: Array, default: () => [] },
   folders: { type: Object, default: () => ({ projekt: [], uni: [] }) },
-  ansichtModus: { type: String, default: 'kompakt' }, // kompakt | erklärend
+  ansichtModus: { type: String, default: 'compact' }, // compact | erklärend
+  stufeAnsicht: { type: Number, default: 4 },          // 1=A · 2=F · 3=E · 4=V
 })
 
-const emit = defineEmits(['select', 'create', 'createThema', 'updateQuelle', 'formatClick', 'bausteineClick', 'cancelBausteine', 'resetBausteine', 'deleteTopic', 'cancelGuide', 'deleteGuide', 'dismissError', 'dismissUiError', 'preview', 'openBausteineView', 'openElements', 'togglePin', 'sidebarLeave', 'toggleDark', 'setAnsicht', 'setProvider'])
+const emit = defineEmits(['select', 'createThema', 'updateSource', 'bausteineClick', 'deleteTopic', 'dismissError', 'dismissUiError', 'preview', 'openBausteineView', 'openGuideBoard', 'openGeneration', 'togglePin', 'sidebarLeave', 'toggleDark', 'setAnsicht', 'setStufe', 'generalExam', 'practice', 'setProvider'])
 
-// Accordion: höchstens ein Panel offen. IDs: 'bausteine', 'fmt-<Format>', 'topic-<Name>'.
+// Accordion: at most one panel open. IDs: 'blocks', 'fmt-<Format>', 'topic-<Name>'.
 const openPanel = ref(null)
 const isOpen = (id) => openPanel.value === id
 function togglePanel(id) {
@@ -39,79 +38,60 @@ function providerAvailable(id) {
   return p ? p.available : true
 }
 
-const PROVIDER_LABELS = { claude: 'Claude', minimax: 'MiniMax', lokal: 'Lokal' }
+const PROVIDER_LABELS = { claude: 'Claude', minimax: 'MiniMax', lokal: 'Local' }
 
-// Tracker oben in der Navigation: Themen gesamt, pro Format erstellt/absolviert
+// Tracker at the top of the navigation: total topics, created/completed per format
 const trackerItems = computed(() => {
   if (!props.stats) return []
-  const f = props.stats.formate || {}
-  const fmt = (k) => `${f[k]?.absolviert ?? 0}/${f[k]?.erstellt ?? 0}`
+  const f = props.stats.formats || {}
+  const fmt = (k) => `${f[k]?.completed ?? 0}/${f[k]?.erstellt ?? 0}`
   return [
-    { label: 'Themen', value: String(props.stats.themen ?? 0), title: 'Themen inkl. Projekte' },
-    { label: 'Guides', value: fmt('Guide'), title: 'absolviert/erstellt' },
+    { label: 'Topics', value: String(props.stats.topics ?? 0), title: 'Topics incl. projects' },
+    { label: 'Guides', value: fmt('Guide'), title: 'completed/created' },
   ]
 })
 
 const formats = [
   { key: 'Guide', label: 'Guide' },
-  { key: 'FullGuide', label: 'FullGuide' },
-  { key: 'Rest', label: 'Rest' },
 ]
 
-const bausteineState = computed(() => {
-  if (props.bausteine.generating) return 'generating'
-  return props.bausteine.ready ? 'done' : 'none'
+// Level views of the SINGLE guide (filtered by subblock depth).
+const LEVEL_VIEWS = [
+  { k: 'auto', label: '⟳', title: 'Auto — Stufe folgt deinem Prüfungs-Score je Block' },
+  { k: 1, label: 'A', title: 'Beginner' },
+  { k: 2, label: 'F', title: 'Beginner + Advanced' },
+  { k: 3, label: 'E', title: 'up to Expert' },
+  { k: 4, label: 'V', title: 'Complete (incl. edge)' },
+]
+
+const blocksState = computed(() => {
+  if (props.blocks.generating) return 'generating'
+  return props.blocks.ready ? 'done' : 'none'
 })
 
-// Re-Run ab gewählter Phase (1-basiert). null = ab Anfang / Fortsetzen.
-const gewaehltePhase = ref(null)
-// Phasen anklickbar, sobald etwas (teil-)gebaut ist und gerade nicht generiert wird.
-const phasenWaehlbar = computed(() => (props.bausteine.ready || props.bausteine.partial) && !props.bausteine.generating)
-const gewaehltesLabel = computed(() => (props.bausteine.steps || [])[(gewaehltePhase.value || 0) - 1]?.label || '')
+// Re-run from a substep now happens in the blocks overview; the sidebar no longer has phase pills.
 
-function phaseKlick(n) {
-  if (!phasenWaehlbar.value) return
-  gewaehltePhase.value = gewaehltePhase.value === n ? null : n
-}
-
-// Nur FREMDE Themen — das gewählte Thema zeigt seinen Fortschritt inline an der Zeile
+// Only OTHER topics — the selected topic shows its progress inline on the row
 const activeGenerations = computed(() => {
-  const bausteinLines = props.activeBausteine
+  const blockLines = props.activeBausteine
     .filter((b) => b.topic !== props.selectedTopic)
-    .map((b) => `${b.topic} – Bausteine: ${b.progress || 'Wartend…'}`)
+    .map((b) => `${b.topic} – Blocks: ${b.progress || 'Waiting…'}`)
   const guideLines = props.allGuides
     .filter((g) => (g.status === 'generating' || g.status === 'queued') && g.topic !== props.selectedTopic)
-    .map((g) => `${g.topic} – ${g.format}: ${g.progress || 'Wartend…'}`)
-  return [...bausteinLines, ...guideLines]
+    .map((g) => `${g.topic} – ${g.format}: ${g.progress || 'Waiting…'}`)
+  return [...blockLines, ...guideLines]
 })
 
 const { pending: pendingConfirm, armOrRun } = useConfirm()
 
-function confirmCancelBausteine() {
-  armOrRun('bausteine', () => emit('cancelBausteine'))
-}
-
-function confirmResetBausteine() {
-  armOrRun('bausteine', () => emit('resetBausteine'))
-}
-
-function handleBausteinePlay() {
-  if (bausteineState.value === 'generating') return
-  // Nur „Neu generieren" (ready) nutzt eine Phase; Fortsetzen/Erstbau resumen ohne Löschen.
-  const abPhase = props.bausteine.ready ? (gewaehltePhase.value ?? 1) : null
-  emit('bausteineClick', { instructions: '', abPhase })
-  gewaehltePhase.value = null
-}
-
-// Name-Klick = Primäraktion: fertige Bausteine → Übersicht, sonst Panel auf/zu.
-function onBausteineName() {
-  if (props.bausteine.ready && !props.bausteine.generating) emit('openBausteineView')
-  else togglePanel('bausteine')
+// Name click = open the block overview (generate/resume/remove all live there now).
+function onBlocksName() {
+  emit('openBausteineView')
 }
 
 function guideStatus(format) {
-  // Laufende Generierung hat Vorrang — sonst maskiert ein älterer fertiger
-  // Guide den Lauf und ▶ würde Duplikate starten.
+  // Running generation takes precedence — otherwise an older finished
+  // guide masks the run and ▶ would start duplicates.
   const latest = props.latestByFormat[format]
   if (latest && (latest.status === 'generating' || latest.status === 'queued')) return latest.status
   if (props.doneByFormat[format]) return 'done'
@@ -119,99 +99,33 @@ function guideStatus(format) {
   return latest.status
 }
 
-// Schritt-Kugeln der Guide-Pipeline
-const GUIDE_STEPS = ['Gliederung', 'Inhalte', 'Inhalts-Check', 'Schreiben', 'Lese-Prüfung']
-
-// Kugeln aus dem artefakt-basierten „fertig"-Marker (wie Bausteine, nicht aus dem DB-Zähler):
-// ≤ fertig = done. Läuft gerade → der nächste Schritt (fertig+1) ist aktiv.
-function guideSteps(format) {
-  const labels = GUIDE_STEPS
-  const fertig = props.guideStepsDone[format] ?? -1
-  const st = guideStatus(format)
-  const aktiv = st === 'generating' || st === 'queued' ? fertig + 1 : -1
-  return labels.map((label, i) => ({
-    label,
-    state: i <= fertig ? 'done' : i === aktiv ? 'active' : 'pending',
-  }))
-}
-
-// Re-Run ab Guide-Schritt (1-basierte Kugel je Format). null = voll/Resume.
-const gewaehlterStep = reactive({})
-// Kugeln klickbar, sobald Artefakte existieren (Marker ≥ 0 oder fertig) und nicht generiert wird.
-function guideWaehlbar(format) {
-  const st = guideStatus(format)
-  if (st === 'generating' || st === 'queued') return false
-  return (props.guideStepsDone[format] ?? -1) >= 0 || st === 'done'
-}
-function guideStepKlick(format, n) {
-  if (!guideWaehlbar(format)) return
-  gewaehlterStep[format] = gewaehlterStep[format] === n ? null : n
-}
-function gewaehltesStepLabel(format) {
-  return GUIDE_STEPS[(gewaehlterStep[format] || 0) - 1] || ''
-}
-
 function errorMsg(format) {
   const latest = props.latestByFormat[format]
   if (latest?.status !== 'error' || props.dismissedErrors.has(latest.id)) return ''
-  if (abgebrochen(format)) return '' // kein roter Fehler — das Pausiert-Badge zeigt den Zustand
-  return latest.error_msg || 'Fehler bei der Generierung'
+  if (aborted(format)) return '' // no red error — the Paused badge shows the state
+  return latest.error_msg || 'Generation failed'
 }
 
-// Abgebrochener Lauf = Teilfortschritt vorhanden: ▶ setzt fort, ✕ löscht den Fortschritt
-function abgebrochen(format) {
+// Aborted run = partial progress present: ▶ resumes, ✕ deletes the progress
+function aborted(format) {
   const latest = props.latestByFormat[format]
-  return latest?.status === 'error' && (latest.error_msg || '').startsWith('Abgebrochen')
+  return latest?.status === 'error' && (latest.error_msg || '').startsWith('Cancelled')
 }
 
-// Name-Klick: fertiger Guide → Vorschau, sonst Aktions-Panel auf/zu.
+// Name click: finished guide → preview, otherwise the generation view (start/cancel live there).
 function handleFormatClick(format) {
   const guide = props.doneByFormat[format]
   if (guide) emit('preview', guide)
-  else togglePanel('fmt-' + format)
+  else emit('openGuideBoard', format)
 }
 
-// Sperr-Gründe kommen vom Backend (GET /guides/locks) — die Regeln existieren
-// nur noch dort. Solange locks noch nicht geladen sind: Button frei, das
-// Backend weist ungültige Starts ohnehin ab (sichtbar über uiError).
-function playLock(format) {
-  return props.locks?.[format] ?? null
-}
-
-function handlePlay(format) {
-  if (playLock(format)) return
-  // Gewählte Kugel (1-basiert) → ab_step (0-basiert). Nur bei (teil-)gebautem Guide.
-  const abStep = guideWaehlbar(format) && gewaehlterStep[format] ? gewaehlterStep[format] - 1 : null
-  emit('formatClick', { format, instructions: '', abStep })
-  gewaehlterStep[format] = null
-}
-
-// Flash-Message-Verhalten: × blendet nur aus, nichts wird gelöscht
+// Flash-message behavior: × only hides, nothing is deleted
 function dismissError(format) {
   const latest = props.latestByFormat[format]
   if (latest?.status === 'error') emit('dismissError', latest.id)
 }
 
-function handleDelete(format) {
-  if (!props.latestByFormat[format]) return
-  armOrRun('fmt-' + format, () => {
-    // Alle laufenden Generierungen des Formats abbrechen (deckt auch Duplikate ab)
-    const running = props.allGuides.filter(
-      (g) => g.topic === props.selectedTopic && g.format === format
-        && (g.status === 'generating' || g.status === 'queued'),
-    )
-    if (running.length) {
-      for (const g of running) emit('cancelGuide', g.id)
-    } else if (abgebrochen(format)) {
-      // Pausierter Lauf: Teilfortschritt samt Schritt-Dateien löschen (Reset)
-      emit('deleteGuide', props.latestByFormat[format].id, true)
-    } else {
-      emit('deleteGuide', props.latestByFormat[format].id)
-    }
-  })
-}
-
-// Erstellen-Bereich: inline aufklappbar (Name + weitere Infos + Quellen-Typ).
+// Create area: inline expandable (name + more info + source type).
 const dlg = ref(false)
 const form = ref({ name: '', instructions: '', sourceType: 'thema', sourceOrt: '' })
 const canCreate = computed(() => {
@@ -220,12 +134,12 @@ const canCreate = computed(() => {
   return true
 })
 
-function toggleErstellen() {
+function toggleCreate() {
   if (!dlg.value) form.value = { name: '', instructions: '', sourceType: 'thema', sourceOrt: '' }
   dlg.value = !dlg.value
 }
 
-function createThema() {
+function createTopic() {
   if (!canCreate.value) return
   emit('createThema', {
     topic: form.value.name.trim(),
@@ -240,7 +154,7 @@ function confirmDeleteTopic(topic) {
   armOrRun('topic-' + topic, () => emit('deleteTopic', topic))
 }
 
-// --- Thema-Edit: Name-Klick wählt nur; das Chevron klappt die Quellen-Form auf/zu (Default zu) ---
+// --- Topic edit: name click only selects; the chevron toggles the sources form (default closed) ---
 const editTopic = ref(null)
 const editForm = ref({ type: 'thema', ort: '', spec: '' })
 const editLoading = ref(false)
@@ -256,8 +170,8 @@ async function toggleTopicPanel(t) {
   editTopic.value = t
   editLoading.value = true
   try {
-    const q = await fetchQuelle(t)
-    editForm.value = { type: q.type || 'thema', ort: q.ort || '', spec: q.spec || '' }
+    const q = await fetchSource(t)
+    editForm.value = { type: q.type || 'thema', ort: q.location || '', spec: q.spec || '' }
   } catch {
     editForm.value = { type: 'thema', ort: '', spec: '' }
   } finally {
@@ -270,9 +184,9 @@ function setEditType(t) {
   editForm.value.ort = ''
 }
 
-function saveQuelle() {
+function saveSource() {
   if (!canSave.value || !editTopic.value) return
-  emit('updateQuelle', {
+  emit('updateSource', {
     topic: editTopic.value,
     type: editForm.value.type,
     ort: editForm.value.ort.trim(),
@@ -293,22 +207,22 @@ function saveQuelle() {
     <div class="new-topic">
       <button
         class="pin-btn"
-        :title="pinned ? 'Sidebar ausblenden' : 'Sidebar fixieren'"
+        :title="pinned ? 'Hide sidebar' : 'Pin sidebar'"
         @click="emit('togglePin')"
       >{{ pinned ? '⇤' : '⇥' }}</button>
       <button
         class="theme-btn"
-        :title="dark ? 'Hellmodus' : 'Dunkelmodus'"
+        :title="dark ? 'Light mode' : 'Dark mode'"
         @click="emit('toggleDark')"
       >{{ dark ? '☀' : '🌙' }}</button>
       <div v-if="selectedTopic" class="ansicht-toggle">
-        <button :class="{ active: ansichtModus === 'kompakt' }" title="Kurzer Text" @click="emit('setAnsicht', 'kompakt')">
+        <button :class="{ active: ansichtModus === 'compact' }" title="Short text" @click="emit('setAnsicht', 'compact')">
           <svg viewBox="0 0 16 16" width="14" height="14" aria-hidden="true">
             <rect x="2" y="5" width="12" height="1.6" rx="0.8" />
             <rect x="2" y="9" width="7" height="1.6" rx="0.8" />
           </svg>
         </button>
-        <button :class="{ active: ansichtModus === 'erklärend' }" title="Langer Text" @click="emit('setAnsicht', 'erklärend')">
+        <button :class="{ active: ansichtModus === 'erklärend' }" title="Long text" @click="emit('setAnsicht', 'erklärend')">
           <svg viewBox="0 0 16 16" width="14" height="14" aria-hidden="true">
             <rect x="2" y="3" width="12" height="1.4" rx="0.7" />
             <rect x="2" y="6.3" width="12" height="1.4" rx="0.7" />
@@ -317,34 +231,39 @@ function saveQuelle() {
           </svg>
         </button>
       </div>
-      <button class="new-topic-toggle" :class="{ active: dlg }" title="Thema erstellen" @click="toggleErstellen">+</button>
+      <div v-if="selectedTopic" class="level-toggle" title="Depth of guide view">
+        <button v-for="s in LEVEL_VIEWS" :key="s.k"
+          :class="{ active: stufeAnsicht === s.k }" :title="s.title"
+          @click="emit('setStufe', s.k)">{{ s.label }}</button>
+      </div>
+      <button class="new-topic-toggle" :class="{ active: dlg }" title="Create topic" @click="toggleCreate">+</button>
     </div>
 
-    <!-- Erstellen: inline aufklappbar (kein Modal) -->
+    <!-- Create: inline expandable (no modal) -->
     <div v-if="dlg" class="thema-panel">
-      <input class="dlg-input" v-model="form.name" placeholder="Thema-Name…" @keyup.enter="createThema" autofocus />
-      <textarea class="dlg-textarea" v-model="form.instructions" rows="2" placeholder="Weitere Infos (optional)…"></textarea>
+      <input class="dlg-input" v-model="form.name" placeholder="Topic name…" @keyup.enter="createTopic" autofocus />
+      <textarea class="dlg-textarea" v-model="form.instructions" rows="2" placeholder="More info (optional)…"></textarea>
       <div class="dlg-sources">
-        <button :class="{ active: form.sourceType === 'thema' }" @click="form.sourceType = 'thema'; form.sourceOrt = ''">Thema</button>
+        <button :class="{ active: form.sourceType === 'thema' }" @click="form.sourceType = 'thema'; form.sourceOrt = ''">Topic</button>
         <button :class="{ active: form.sourceType === 'link' }" @click="form.sourceType = 'link'; form.sourceOrt = ''">Link</button>
-        <button :class="{ active: form.sourceType === 'projekt' }" @click="form.sourceType = 'projekt'; form.sourceOrt = ''">Projekt</button>
+        <button :class="{ active: form.sourceType === 'projekt' }" @click="form.sourceType = 'projekt'; form.sourceOrt = ''">Project</button>
         <button :class="{ active: form.sourceType === 'uni' }" @click="form.sourceType = 'uni'; form.sourceOrt = ''">Uni</button>
       </div>
       <input
         v-if="form.sourceType === 'link'"
         class="dlg-input" v-model="form.sourceOrt"
-        placeholder="https://…" @keyup.enter="createThema"
+        placeholder="https://…" @keyup.enter="createTopic"
       />
       <select
         v-else-if="form.sourceType === 'projekt' || form.sourceType === 'uni'"
         class="dlg-input" v-model="form.sourceOrt"
       >
-        <option value="" disabled>Ordner wählen…</option>
-        <option v-for="fo in (folders[form.sourceType] || [])" :key="fo.ort" :value="fo.ort">{{ fo.name }}</option>
+        <option value="" disabled>Choose folder…</option>
+        <option v-for="fo in (folders[form.sourceType] || [])" :key="fo.location" :value="fo.location">{{ fo.name }}</option>
       </select>
       <div class="dlg-actions">
-        <button class="dlg-cancel" @click="dlg = false">Abbrechen</button>
-        <button class="dlg-create" :disabled="!canCreate" @click="createThema">Erstellen</button>
+        <button class="dlg-cancel" @click="dlg = false">Cancel</button>
+        <button class="dlg-create" :disabled="!canCreate" @click="createTopic">Create</button>
       </div>
     </div>
     <div class="provider-toggle" v-if="providers.length">
@@ -353,118 +272,74 @@ function saveQuelle() {
         :key="p.id"
         :class="{ active: p.id === provider }"
         :disabled="!p.available"
-        :title="p.available ? '' : 'Nicht konfiguriert (CLI/Key fehlt)'"
+        :title="p.available ? '' : 'Not configured (CLI/key missing)'"
         @click="emit('setProvider', p.id)"
       >{{ PROVIDER_LABELS[p.id] || p.id }}</button>
     </div>
     <div class="format-section" v-if="selectedTopic">
       <div class="format-error ui-error" v-if="uiError">
         <span class="format-error-text">{{ uiError }}</span>
-        <button class="format-error-x" title="Ausblenden" @click="emit('dismissUiError')">×</button>
+        <button class="format-error-x" title="Hide" @click="emit('dismissUiError')">×</button>
       </div>
       <div class="progress-info" v-if="activeGenerations.length">
         <div v-for="(line, i) in activeGenerations" :key="i">{{ line }}</div>
       </div>
-      <div class="ord-bausteine">
+      <div class="ord-blocks">
         <div
-          class="format-row bausteine-row"
-          :class="{ 'is-active': bausteineState === 'generating' || bausteine.partial, 'row-open': isOpen('bausteine') }"
+          class="format-row blocks-row"
+          :class="{ 'is-active': blocksState === 'generating' || blocks.partial }"
         >
-          <button class="format-name bausteine-name" @click="onBausteineName">
-            <span class="format-label">Bausteine</span>
+          <button class="format-name blocks-name" @click="onBlocksName">
+            <span class="format-label">Blocks</span>
             <span
-              v-if="bausteine.partial && bausteineState !== 'generating'"
+              v-if="blocks.partial && blocksState !== 'generating'"
               class="resume-badge"
-              title="Abgebrochen — Fortsetzen möglich"
-            >Pausiert</span>
-            <span class="step-dots">
-              <span
-                v-for="(s, i) in (bausteine.steps || [])"
-                :key="s.label"
-                class="step-pill"
-                :class="[s.state, { sel: gewaehltePhase === i + 1, klickbar: phasenWaehlbar }]"
-                :title="(s.state === 'active' ? (bausteine.progress || s.label) : s.label) + (phasenWaehlbar ? ' — Klick: ab hier neu' : '')"
-                @click.stop="phaseKlick(i + 1)"
-              >{{ i + 1 }}</span>
-            </span>
+              title="Aborted — can be resumed"
+            >Paused</span>
           </button>
-          <button class="panel-toggle" :class="{ open: isOpen('bausteine') }" title="Aktionen" @click.stop="togglePanel('bausteine')">▾</button>
         </div>
-        <div v-if="isOpen('bausteine')" class="action-panel">
-          <template v-if="bausteineState === 'generating'">
-            <button class="panel-btn danger" :class="{ armed: pendingConfirm === 'bausteine' }" @click="confirmCancelBausteine">{{ pendingConfirm === 'bausteine' ? 'Sicher?' : 'Abbrechen' }}</button>
-          </template>
-          <template v-else>
-            <button class="panel-btn play" @click="handleBausteinePlay">{{ bausteine.partial ? 'Fortsetzen' : bausteine.ready ? (gewaehltePhase ? `Ab «${gewaehltesLabel}» neu` : 'Neu generieren') : 'Generieren' }}</button>
-            <button
-              v-if="bausteine.ready || bausteine.partial"
-              class="panel-btn danger"
-              :class="{ armed: pendingConfirm === 'bausteine' }"
-              @click="confirmResetBausteine"
-            >{{ pendingConfirm === 'bausteine' ? 'Sicher?' : 'Entfernen' }}</button>
-          </template>
+        <div v-if="blocksState === 'generating'" class="format-progress">
+          {{ blocks.progress || 'Waiting…' }}
         </div>
-        <div v-if="bausteineState === 'generating'" class="format-progress">
-          {{ bausteine.progress || 'Wartend…' }}
+        <div v-if="blocks.error && !blocks.error.startsWith('Cancelled')" class="format-error">
+          <span class="format-error-text">{{ blocks.error }}</span>
         </div>
-        <div v-if="bausteine.error && !bausteine.error.startsWith('Abgebrochen')" class="format-error">
-          <span class="format-error-text">{{ bausteine.error }}</span>
+        <div class="format-row">
+          <button class="format-name" @click="emit('openGeneration')">
+            <span class="format-label gen-label">Generierung</span>
+            <span v-if="blocksState === 'generating'" class="gen-live-dot" title="Läuft"></span>
+          </button>
         </div>
       </div>
-<!-- Formate stehen per CSS-order nach der Bausteine-Zeile (order 2) -->
+<!-- Formats come after the blocks row via CSS order (order 2) -->
       <div v-for="f in formats" :key="f.key" :style="{ order: 3 }">
-        <div :class="['format-row', 'fmt-' + guideStatus(f.key), { 'fmt-paused': abgebrochen(f.key), 'row-open': isOpen('fmt-' + f.key) }]">
+        <div :class="['format-row', 'fmt-' + guideStatus(f.key), { 'fmt-paused': aborted(f.key) }]">
           <button class="format-name" @click="handleFormatClick(f.key)">
             <span class="format-label">{{ f.label }}</span>
             <span
-              v-if="abgebrochen(f.key)"
+              v-if="aborted(f.key)"
               class="resume-badge"
-              title="Abgebrochen — Fortsetzen möglich"
-            >Pausiert</span>
-            <span class="step-dots" v-if="guideSteps(f.key).length">
-              <span
-                v-for="(s, i) in guideSteps(f.key)"
-                :key="s.label"
-                class="step-pill"
-                :class="[s.state, { sel: gewaehlterStep[f.key] === i + 1, klickbar: guideWaehlbar(f.key) }]"
-                :title="(s.state === 'active' ? (latestByFormat[f.key]?.progress || s.label) : s.label) + (guideWaehlbar(f.key) ? ' — Klick: ab hier neu' : '')"
-                @click.stop="guideStepKlick(f.key, i + 1)"
-              >{{ i + 1 }}</span>
-            </span>
+              title="Aborted — can be resumed"
+            >Paused</span>
           </button>
-          <button class="panel-toggle" :class="{ open: isOpen('fmt-' + f.key) }" title="Aktionen" @click.stop="togglePanel('fmt-' + f.key)">▾</button>
-        </div>
-        <div v-if="isOpen('fmt-' + f.key)" class="action-panel">
-          <template v-if="guideStatus(f.key) === 'generating' || guideStatus(f.key) === 'queued'">
-            <button class="panel-btn danger" :class="{ armed: pendingConfirm === 'fmt-' + f.key }" @click="handleDelete(f.key)">{{ pendingConfirm === 'fmt-' + f.key ? 'Sicher?' : 'Abbrechen' }}</button>
-          </template>
-          <template v-else>
-            <button
-              class="panel-btn play"
-              :title="playLock(f.key) || (abgebrochen(f.key) ? 'Fortsetzen' : 'Generieren')"
-              :disabled="!!playLock(f.key)"
-              @click="handlePlay(f.key)"
-            >{{ gewaehlterStep[f.key] ? `Ab «${gewaehltesStepLabel(f.key)}» neu` : abgebrochen(f.key) ? 'Fortsetzen' : guideStatus(f.key) === 'done' ? 'Neu generieren' : 'Generieren' }}</button>
-            <button
-              v-if="guideStatus(f.key) !== 'none' || abgebrochen(f.key)"
-              class="panel-btn danger"
-              :class="{ armed: pendingConfirm === 'fmt-' + f.key }"
-              @click="handleDelete(f.key)"
-            >{{ pendingConfirm === 'fmt-' + f.key ? 'Sicher?' : abgebrochen(f.key) ? 'Fortschritt löschen' : 'Entfernen' }}</button>
-          </template>
         </div>
         <div
           v-if="guideStatus(f.key) === 'generating' || guideStatus(f.key) === 'queued'"
           class="format-progress"
-        >{{ latestByFormat[f.key]?.progress || 'Wartend…' }}</div>
+        >{{ latestByFormat[f.key]?.progress || 'Waiting…' }}</div>
         <div v-if="errorMsg(f.key)" class="format-error">
           <span class="format-error-text">{{ errorMsg(f.key) }}</span>
-          <button class="format-error-x" title="Ausblenden" @click="dismissError(f.key)">×</button>
+          <button class="format-error-x" title="Hide" @click="dismissError(f.key)">×</button>
         </div>
       </div>
-      <div class="format-row ord-elemente">
-        <button class="format-name elements-btn" @click="emit('openElements')">
-          <span class="format-label">Elemente</span>
+      <div class="format-row ord-exam">
+        <button class="format-name elements-btn" @click="emit('generalExam')">
+          <span class="format-label">General Exam</span>
+        </button>
+      </div>
+      <div class="format-row ord-practice">
+        <button class="format-name elements-btn" @click="emit('practice')">
+          <span class="format-label">Üben</span>
         </button>
       </div>
     </div>
@@ -477,16 +352,16 @@ function saveQuelle() {
       >
         <div class="topic-row">
           <span class="topic-name" @click="emit('select', t)">{{ t }}</span>
-          <button class="panel-toggle" :class="{ open: isOpen('topic-' + t) }" title="Optionen" @click.stop="toggleTopicPanel(t)">▾</button>
+          <button class="panel-toggle" :class="{ open: isOpen('topic-' + t) }" title="Options" @click.stop="toggleTopicPanel(t)">▾</button>
         </div>
         <div v-if="isOpen('topic-' + t)" class="thema-panel edit-panel" @click.stop>
-          <p v-if="editLoading" class="dlg-hint">Lade…</p>
+          <p v-if="editLoading" class="dlg-hint">Loading…</p>
           <template v-else>
-            <textarea class="dlg-textarea" v-model="editForm.spec" rows="2" placeholder="Weitere Infos (optional)…"></textarea>
+            <textarea class="dlg-textarea" v-model="editForm.spec" rows="2" placeholder="More info (optional)…"></textarea>
             <div class="dlg-sources">
-              <button :class="{ active: editForm.type === 'thema' }" @click="setEditType('thema')">Thema</button>
+              <button :class="{ active: editForm.type === 'thema' }" @click="setEditType('thema')">Topic</button>
               <button :class="{ active: editForm.type === 'link' }" @click="setEditType('link')">Link</button>
-              <button :class="{ active: editForm.type === 'projekt' }" @click="setEditType('projekt')">Projekt</button>
+              <button :class="{ active: editForm.type === 'projekt' }" @click="setEditType('projekt')">Project</button>
               <button :class="{ active: editForm.type === 'uni' }" @click="setEditType('uni')">Uni</button>
             </div>
             <input
@@ -498,16 +373,16 @@ function saveQuelle() {
               v-else-if="editForm.type === 'projekt' || editForm.type === 'uni'"
               class="dlg-input" v-model="editForm.ort"
             >
-              <option value="" disabled>Ordner wählen…</option>
-              <option v-for="fo in (folders[editForm.type] || [])" :key="fo.ort" :value="fo.ort">{{ fo.name }}</option>
+              <option value="" disabled>Choose folder…</option>
+              <option v-for="fo in (folders[editForm.type] || [])" :key="fo.location" :value="fo.location">{{ fo.name }}</option>
             </select>
             <div class="dlg-actions">
               <button
                 class="dlg-delete"
                 :class="{ armed: pendingConfirm === 'topic-' + t }"
                 @click="confirmDeleteTopic(t)"
-              >{{ pendingConfirm === 'topic-' + t ? 'Sicher?' : 'Löschen' }}</button>
-              <button class="dlg-create" :disabled="!canSave" @click="saveQuelle">Aktualisieren</button>
+              >{{ pendingConfirm === 'topic-' + t ? 'Sure?' : 'Delete' }}</button>
+              <button class="dlg-create" :disabled="!canSave" @click="saveSource">Update</button>
             </div>
           </template>
         </div>
@@ -592,7 +467,7 @@ function saveQuelle() {
   border-color: var(--accent-border);
 }
 
-/* Ansicht-Umschalter: zwei Icon-Buttons (kurzer / langer Text) */
+/* View switcher: two icon buttons (short / long text) */
 .ansicht-toggle { display: inline-flex; }
 .new-topic .ansicht-toggle button {
   padding: 4px 7px;
@@ -607,6 +482,21 @@ function saveQuelle() {
 .new-topic .ansicht-toggle button:hover { color: var(--accent-hover); }
 .new-topic .ansicht-toggle button.active { background: var(--accent); border-color: var(--accent); color: var(--on-accent); }
 .ansicht-toggle svg { fill: currentColor; display: block; }
+.level-toggle { display: inline-flex; margin-left: 4px; }
+.new-topic .level-toggle button {
+  padding: 4px 6px;
+  background: var(--bg);
+  color: var(--text-muted);
+  border: 1px solid var(--border-strong);
+  font-size: 11px;
+  font-weight: 600;
+  min-width: 20px;
+}
+.new-topic .level-toggle button:first-child { border-radius: 6px 0 0 6px; }
+.new-topic .level-toggle button:last-child { border-radius: 0 6px 6px 0; }
+.new-topic .level-toggle button:not(:first-child) { border-left: none; }
+.new-topic .level-toggle button:hover { color: var(--accent-hover); }
+.new-topic .level-toggle button.active { background: var(--accent); border-color: var(--accent); color: var(--on-accent); }
 
 .stats-bar {
   display: flex;
@@ -634,7 +524,7 @@ function saveQuelle() {
   color: var(--text);
 }
 
-/* Mini-Titel sitzt auf der oberen Kante des Badges (Legenden-Look) */
+/* Mini title sits on the top edge of the badge (legend look) */
 .stat-label {
   position: absolute;
   top: -0.42rem;
@@ -728,53 +618,19 @@ function saveQuelle() {
 }
 
 /* Format section */
-.bausteine-name {
+.blocks-name {
   display: flex;
   align-items: center;
   gap: 8px;
   cursor: pointer;
 }
 
-.step-dots {
-  display: inline-flex;
-  gap: 5px;
-  flex: 1;
-}
 
-/* Grobe Phasen als nummerierte Pillen (1–5) — Anzeige + anklickbar für Re-Run ab hier. */
-.step-pill {
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  width: 17px;
-  height: 17px;
-  border-radius: 50%;
-  background: var(--border-strong);
-  color: var(--bg);
-  font-size: 0.62rem;
-  font-weight: 700;
-  line-height: 1;
-  flex-shrink: 0;
-  border: 1.5px solid transparent;
-}
+/* Coarse phases as numbered pills (1–5) — display + clickable for re-run from here. */
 
-.step-pill.done {
-  background: var(--success-border);
-}
 
-.step-pill.active {
-  background: var(--warning-border);
-  animation: dot-pulse 1.2s ease-in-out infinite;
-}
 
-.step-pill.klickbar {
-  cursor: pointer;
-}
 
-.step-pill.sel {
-  border-color: var(--text);
-  box-shadow: 0 0 0 1px var(--text);
-}
 
 @keyframes dot-pulse {
   0%, 100% { opacity: 1; }
@@ -791,19 +647,33 @@ function saveQuelle() {
   max-height: 60vh;
   overflow-y: auto;
   padding: 0.5rem 0;
-  /* flex + order: Bausteine (order 2) vor den Formaten (order 3) */
+  /* flex + order: blocks (order 2) before the formats (order 3) */
   display: flex;
   flex-direction: column;
 }
 
-.ord-bausteine {
+.gen-label { color: var(--text-muted); font-size: 0.86em; }
+.gen-live-dot {
+  width: 7px;
+  height: 7px;
+  border-radius: 50%;
+  background: var(--accent);
+  animation: gen-side-pulse 1.2s ease-in-out infinite;
+}
+@keyframes gen-side-pulse { 0%, 100% { opacity: 1; } 50% { opacity: 0.3; } }
+
+.ord-blocks {
   order: 2;
 }
 
-.ord-elemente {
+.ord-exam {
   order: 4;
 }
 
+.ord-practice {
+  order: 5;
+}
+
 .elements-btn {
   cursor: pointer;
   color: var(--text);
@@ -822,14 +692,14 @@ function saveQuelle() {
   animation: pulse 1.5s ease-in-out infinite;
 }
 
-/* Abgewiesene Aktion (409/400) — oberhalb aller Format-Zeilen */
+/* Rejected action (409/400) — above all format rows */
 .ui-error {
   order: 0;
   padding: 0.4rem 0.75rem;
   background: var(--warning-soft);
 }
 
-/* Fortschritts-Text direkt unter der laufenden Format-Zeile */
+/* Progress text directly below the running format row */
 .format-progress {
   padding: 0 0.75rem 5px calc(0.75rem + 8px);
   font-size: 0.72rem;
@@ -879,7 +749,7 @@ function saveQuelle() {
   gap: 8px;
 }
 
-/* Accordion: Pfeil-Toggle + aufklappendes Aktions-Panel */
+/* Accordion: arrow toggle + expanding action panel */
 .panel-toggle {
   flex: 0 0 auto;
   background: none;
@@ -897,34 +767,7 @@ function saveQuelle() {
 .format-row.row-open,
 .topic-list li.li-open .topic-row { background: var(--panel-soft); }
 
-.action-panel {
-  display: flex;
-  gap: 0.5rem;
-  padding: 0.15rem 0.75rem 0.55rem calc(0.75rem + 8px);
-}
 
-.panel-btn {
-  flex: 1;
-  padding: 0.45rem 0.6rem;
-  border: 1px solid var(--border-strong);
-  border-radius: 6px;
-  background: var(--panel);
-  color: var(--text);
-  font-size: 0.82rem;
-  font-weight: 600;
-  cursor: pointer;
-  transition: all 0.15s;
-}
-.panel-btn:hover { border-color: var(--accent); }
-.panel-btn:disabled { opacity: 0.4; cursor: not-allowed; }
-.panel-btn:disabled:hover { border-color: var(--border-strong); }
-.panel-btn.play {
-  color: var(--success);
-  background: var(--success-soft);
-  border-color: var(--success-border);
-}
-.panel-btn.play:hover { background: var(--success-soft-hover); }
-.panel-btn.danger { color: var(--danger); }
 .panel-btn.danger:hover { border-color: var(--danger); }
 .panel-btn.armed { background: var(--danger); color: #fff; border-color: var(--danger); }
 
@@ -941,11 +784,11 @@ function saveQuelle() {
   display: inline;
 }
 
-/* Laufend/pausiert: × immer zeigen — Hover gibt es auf Touch nicht */
+/* Running/paused: always show × — there is no hover on touch */
 .fmt-generating .format-x,
 .fmt-queued .format-x,
 .fmt-paused .format-x,
-.bausteine-row.is-active .format-x {
+.blocks-row.is-active .format-x {
   display: inline;
 }
 
@@ -1056,9 +899,9 @@ function saveQuelle() {
   50% { opacity: 0.65; }
 }
 
-/* Erstellen — inline aufklappbar (kein Modal) */
+/* Create — inline expandable (no modal) */
 .new-topic-toggle {
-  margin-left: auto;       /* rechtsbündig statt volle Breite */
+  margin-left: auto;       /* right-aligned instead of full width */
   padding: 6px 12px;
   border: 1px solid transparent;
   border-radius: 6px;
@@ -1120,7 +963,7 @@ function saveQuelle() {
 .dlg-create { background: var(--accent); border-color: var(--accent); color: var(--on-accent); }
 .dlg-create:disabled { opacity: 0.45; cursor: default; }
 
-/* Thema-Edit-Panel: dezent in die Liste eingefügt — keine Box, nur ein linker Akzent */
+/* Topic edit panel: subtly inserted into the list — no box, just a left accent */
 .edit-panel {
   margin: 0;
   padding: 0.5rem 1rem 0.7rem 1.25rem;

frontend/src/components/elements/ElementChatTab.vue

@@ -1,147 +0,0 @@
-<script setup>
-import { watch } from 'vue'
-import { chatElement } from '../../api.js'
-import { useChat } from '../../composables/useChat.js'
-
-const props = defineProps({
-  element: { type: Object, required: true },
-  provider: { type: String, default: 'claude' },
-})
-
-const emit = defineEmits(['changes'])
-
-const chat = useChat((msgs) => chatElement(props.element.id, msgs, props.provider))
-const { messages, input, loading, messagesEl, inputEl, onScroll } = chat
-
-// Anderes Element gewählt → Verlauf verwerfen
-watch(() => props.element.id, () => chat.reset())
-
-async function send() {
-  const res = await chat.send()
-  if (res?.changes?.length) emit('changes', res.changes)
-}
-</script>
-
-<template>
-  <div class="el-chat">
-    <div ref="messagesEl" class="chat-messages" @scroll="onScroll">
-      <p v-if="!messages.length" class="chat-hint">Schreib, was am Element geändert werden soll.</p>
-      <template v-for="(m, i) in messages" :key="i">
-        <div :class="['chat-msg', m.role]">{{ m.content }}</div>
-      </template>
-      <div v-if="loading" class="chat-msg assistant chat-typing">Passt an…</div>
-    </div>
-    <div class="chat-input">
-      <textarea
-        ref="inputEl"
-        v-model="input"
-        placeholder="Element anpassen…"
-        @keydown.enter.exact.prevent="send"
-      ></textarea>
-      <button
-        :disabled="!input.trim() && !loading"
-        :class="{ cancel: loading }"
-        :title="loading ? 'Abbrechen' : 'Senden'"
-        @click="send"
-      >{{ loading ? '✕' : '➤' }}</button>
-    </div>
-  </div>
-</template>
-
-<style scoped>
-.el-chat {
-  display: flex;
-  flex-direction: column;
-  flex: 1;
-  min-height: 0;
-}
-
-.chat-messages {
-  flex: 1;
-  overflow-y: auto;
-  padding: 0.6rem 0.75rem;
-  display: flex;
-  flex-direction: column;
-  gap: 8px;
-}
-
-.chat-hint {
-  color: var(--text-faint);
-  font-size: 0.78rem;
-  text-align: center;
-  margin-top: 0.5rem;
-}
-
-.chat-msg {
-  max-width: 85%;
-  padding: 6px 10px;
-  border-radius: 12px;
-  font-size: 0.82rem;
-  line-height: 1.4;
-  white-space: pre-wrap;
-  word-break: break-word;
-}
-
-.chat-msg.user {
-  align-self: flex-end;
-  background: var(--accent);
-  color: var(--on-accent);
-  border-bottom-right-radius: 3px;
-}
-
-.chat-msg.assistant {
-  align-self: flex-start;
-  background: var(--panel-soft);
-  color: var(--text);
-  border-bottom-left-radius: 3px;
-}
-
-.chat-typing {
-  color: var(--text-faint);
-  font-style: italic;
-}
-
-.chat-input {
-  display: flex;
-  gap: 6px;
-  padding: 0.6rem;
-  border-top: 1px solid var(--border);
-}
-
-.chat-input textarea {
-  flex: 1;
-  resize: none;
-  height: 72px;
-  padding: 8px 10px;
-  border: 1px solid var(--border-strong);
-  border-radius: 8px;
-  font-size: 0.85rem;
-  font-family: inherit;
-  background: var(--panel);
-  color: var(--text);
-  outline: none;
-}
-
-.chat-input textarea:focus {
-  border-color: var(--accent);
-}
-
-.chat-input button {
-  width: 38px;
-  border: none;
-  border-radius: 8px;
-  background: var(--accent);
-  color: var(--on-accent);
-  font-size: 1rem;
-  cursor: pointer;
-}
-
-.chat-input button:disabled {
-  opacity: 0.4;
-  cursor: not-allowed;
-}
-
-.chat-input button.cancel {
-  background: var(--danger);
-}
-</style>

frontend/src/components/elements/ElementDetail.vue

@@ -1,458 +0,0 @@
-<script setup>
-import { ref, watch } from 'vue'
-import { updateElement, checkElement, styleElement, refineSuggestion } from '../../api.js'
-import { renderMarkdown } from '../../markdown.js'
-import ElementSuggestion from './ElementSuggestion.vue'
-import ElementChatTab from './ElementChatTab.vue'
-import ElementEditTab from './ElementEditTab.vue'
-
-const props = defineProps({
-  element: { type: Object, required: true },
-  provider: { type: String, default: 'claude' },
-})
-
-const emit = defineEmits(['back', 'close', 'updated', 'changed'])
-
-const tab = ref('overview') // 'overview' | 'chat' | 'edit'
-const savingEdit = ref(false)
-
-// Markdown-Zeichen aus dem Header-Titel entfernen
-function plain(text) {
-  return (text || '').replace(/```[a-z]*\n?/g, '').replace(/[`*_#]/g, '')
-}
-
-// Anderes Element gewählt → Prüf-Zustand und Tab zurücksetzen
-watch(() => props.element.id, () => {
-  tab.value = 'overview'
-  resetCheck()
-})
-
-// --- KI-Prüfung auf fehlende Infos (Ergebnisse landen als Inline-Vorschläge) ---
-const checking = ref(false)
-const statusMsg = ref(null)
-
-function resetCheck() {
-  checking.value = false
-  statusMsg.value = null
-  resetStyle()
-}
-
-let checkRun = 0 // laufende Prüfung identifizieren; Abbruch ignoriert ihr Ergebnis
-
-async function runCheck() {
-  if (checking.value) { // zweiter Klick = abbrechen
-    checkRun++
-    checking.value = false
-    return
-  }
-  const run = ++checkRun
-  checking.value = true
-  statusMsg.value = null
-  try {
-    const res = await checkElement(props.element.id, props.provider)
-    if (run !== checkRun) return // abgebrochen oder neue Prüfung gestartet
-    const mapped = res.suggestions.map((s) => ({
-      text: s.text, action: 'hinzufuegen', target: s.target, index: null, content: s.content,
-    }))
-    if (mapped.length) styleChanges.value = [...(styleChanges.value || []), ...mapped]
-    else statusMsg.value = 'Keine wichtigen Lücken gefunden.'
-  } catch (e) {
-    if (run !== checkRun) return
-    console.error('Prüfung fehlgeschlagen:', e)
-    statusMsg.value = 'Prüfung fehlgeschlagen — bitte erneut versuchen.'
-  } finally {
-    if (run === checkRun) checking.value = false
-  }
-}
-
-// --- Stil-Prüfung: KI schlägt Änderungen vor, Nutzer bestätigt ---
-const styleChanges = ref(null) // null = noch nicht geprüft
-const styling = ref(false)
-const applyingStyle = ref(false)
-const refiningIdx = ref(null)
-let styleRun = 0
-
-function resetStyle() {
-  styleChanges.value = null
-  styling.value = false
-  applyingStyle.value = false
-  refiningIdx.value = null
-}
-
-function suggBusy(i) {
-  return applyingStyle.value || refiningIdx.value === i
-}
-
-// Einzelnen Vorschlag per Anweisung überarbeiten (Stift-Icon)
-async function refineChange(i, instruction) {
-  if (refiningIdx.value !== null || applyingStyle.value) return
-  refiningIdx.value = i
-  try {
-    const res = await refineSuggestion(props.element.id, styleChanges.value[i], instruction, props.provider)
-    const next = [...styleChanges.value]
-    next[i] = res.change
-    styleChanges.value = next
-  } catch (e) {
-    console.error('Überarbeitung fehlgeschlagen:', e)
-    statusMsg.value = 'Überarbeitung fehlgeschlagen — bitte erneut versuchen.'
-  } finally {
-    refiningIdx.value = null
-  }
-}
-
-async function runStyle() {
-  if (styling.value) { // zweiter Klick = abbrechen
-    styleRun++
-    styling.value = false
-    return
-  }
-  const run = ++styleRun
-  styling.value = true
-  statusMsg.value = null
-  try {
-    const res = await styleElement(props.element.id, props.provider)
-    if (run !== styleRun) return
-    if (res.changes.length) styleChanges.value = [...(styleChanges.value || []), ...res.changes]
-    else statusMsg.value = 'Stil passt bereits.'
-  } catch (e) {
-    if (run !== styleRun) return
-    console.error('Stil-Prüfung fehlgeschlagen:', e)
-    statusMsg.value = 'Stil-Prüfung fehlgeschlagen — bitte erneut versuchen.'
-  } finally {
-    if (run === styleRun) styling.value = false
-  }
-}
-
-// Chat-Vorschläge landen ebenfalls als Inline-Vorschläge in der Übersicht
-function onChatChanges(changes) {
-  styleChanges.value = [...(styleChanges.value || []), ...changes]
-}
-
-// Vorschläge am Ziel-Ort anzeigen: anpassen/entfernen beim betroffenen Eintrag …
-function styleAt(target, index = null) {
-  if (!styleChanges.value) return []
-  return styleChanges.value
-    .map((c, i) => [i, c])
-    .filter(([, c]) => c.target === target && c.index === index && c.action !== 'hinzufuegen')
-}
-
-// … Ergänzungen am Ende der jeweiligen Sektion
-function styleAdds(target) {
-  if (!styleChanges.value) return []
-  return styleChanges.value
-    .map((c, i) => [i, c])
-    .filter(([, c]) => c.target === target && c.action === 'hinzufuegen')
-}
-
-function dismissStyleChange(i) {
-  styleChanges.value = styleChanges.value.filter((_, j) => j !== i)
-}
-
-async function applyStyleChange(i) {
-  if (applyingStyle.value) return
-  const c = styleChanges.value[i]
-  applyingStyle.value = true
-  try {
-    const STRING_TARGETS = ['title', 'description']
-    const fields = {
-      title: props.element.title,
-      description: props.element.description,
-      examples: [...props.element.examples],
-      hints: [...props.element.hints],
-    }
-    if (c.action === 'entfernen') fields[c.target].splice(c.index, 1)
-    else if (c.action === 'hinzufuegen') {
-      if (c.target === 'title') fields.title = c.content
-      else if (c.target === 'description')
-        fields[c.target] = fields[c.target] ? fields[c.target] + '\n\n' + c.content : c.content
-      else fields[c.target].push(c.content)
-    } else if (STRING_TARGETS.includes(c.target)) fields[c.target] = c.content
-    else fields[c.target][c.index] = c.content
-
-    const updated = await updateElement(props.element.id, fields)
-    emit('updated', updated)
-
-    // Rest-Vorschläge behalten; Indizes hinter einer Entfernung rücken auf
-    const rest = styleChanges.value.filter((_, j) => j !== i)
-    if (c.action === 'entfernen') {
-      for (const r of rest) {
-        if (r.target === c.target && r.index !== null && r.index > c.index) r.index--
-      }
-    }
-    styleChanges.value = rest
-  } catch (e) {
-    console.error('Übernehmen fehlgeschlagen:', e)
-  } finally {
-    applyingStyle.value = false
-  }
-}
-
-// --- Bearbeiten-Tab: Felder direkt speichern ---
-async function saveEdit(fields) {
-  if (savingEdit.value) return
-  savingEdit.value = true
-  try {
-    const updated = await updateElement(props.element.id, fields)
-    emit('updated', updated)
-    tab.value = 'overview'
-  } catch (e) {
-    console.error('Speichern fehlgeschlagen:', e)
-  } finally {
-    savingEdit.value = false
-  }
-}
-</script>
-
-<template>
-  <header class="el-header">
-    <button class="el-back" title="Zur Liste" @click="emit('back')">←</button>
-    <span class="el-title">{{ plain(element.title) }}</span>
-    <button
-      class="el-tool" :class="{ busy: checking }"
-      :title="checking ? 'Prüfung abbrechen' : 'Auf fehlende Infos prüfen'" @click="runCheck"
-    >🔍</button>
-    <button
-      class="el-tool" :class="{ busy: styling }"
-      :title="styling ? 'Prüfung abbrechen' : 'Stil prüfen & anpassen'" @click="runStyle"
-    >✨</button>
-    <button class="el-close" title="Schließen" @click="emit('close')">×</button>
-  </header>
-
-  <nav class="el-tabs">
-    <button :class="{ active: tab === 'overview' }" @click="tab = 'overview'">Übersicht</button>
-    <button :class="{ active: tab === 'chat' }" @click="tab = 'chat'">Chat</button>
-    <button :class="{ active: tab === 'edit' }" @click="tab = 'edit'">Bearbeiten</button>
-  </nav>
-
-  <!-- Übersicht: untrennbar mit styleChanges/Apply verzahnt → bleibt hier -->
-  <div v-show="tab === 'overview'" class="el-detail">
-    <div v-if="element.description" class="el-desc markdown" v-html="renderMarkdown(element.description)"></div>
-    <ElementSuggestion
-      v-for="[ci, c] in [...styleAt('title'), ...styleAt('description'), ...styleAdds('description')]"
-      :key="'sgd' + ci" :change="c" :busy="suggBusy(ci)"
-      @apply="applyStyleChange(ci)" @dismiss="dismissStyleChange(ci)" @refine="(t) => refineChange(ci, t)"
-    />
-    <template v-for="(ex, i) in element.examples" :key="i">
-      <div class="el-entry markdown" v-html="renderMarkdown(ex)"></div>
-      <ElementSuggestion
-        v-for="[ci, c] in styleAt('examples', i)"
-        :key="'sge' + ci" :change="c" :busy="suggBusy(ci)"
-        @apply="applyStyleChange(ci)" @dismiss="dismissStyleChange(ci)" @refine="(t) => refineChange(ci, t)"
-      />
-    </template>
-    <ElementSuggestion
-      v-for="[ci, c] in styleAdds('examples')"
-      :key="'sgea' + ci" :change="c" :busy="suggBusy(ci)"
-      @apply="applyStyleChange(ci)" @dismiss="dismissStyleChange(ci)" @refine="(t) => refineChange(ci, t)"
-    />
-    <div v-if="element.hints.length || styleAdds('hints').length" class="el-hints-block">
-      <h4>Hinweise</h4>
-      <ul class="el-hints">
-        <li v-for="(h, i) in element.hints" :key="i">
-          <span class="markdown" v-html="renderMarkdown(h)"></span>
-          <ElementSuggestion
-            v-for="[ci, c] in styleAt('hints', i)"
-            :key="'sgh' + ci" :change="c" :busy="suggBusy(ci)"
-            @apply="applyStyleChange(ci)" @dismiss="dismissStyleChange(ci)" @refine="(t) => refineChange(ci, t)"
-          />
-        </li>
-      </ul>
-      <ElementSuggestion
-        v-for="[ci, c] in styleAdds('hints')"
-        :key="'sgha' + ci" :change="c" :busy="suggBusy(ci)"
-        @apply="applyStyleChange(ci)" @dismiss="dismissStyleChange(ci)" @refine="(t) => refineChange(ci, t)"
-      />
-    </div>
-
-    <div v-if="checking || styling || statusMsg" class="el-check">
-      <p v-if="checking" class="check-empty busy-text">Prüft auf fehlende Infos…</p>
-      <p v-if="styling" class="check-empty busy-text">Prüft den Stil…</p>
-      <p v-if="statusMsg && !checking && !styling" class="check-empty">{{ statusMsg }}</p>
-    </div>
-  </div>
-
-  <!-- v-show erhält den Chat-Verlauf beim Tab-Wechsel -->
-  <ElementChatTab
-    v-show="tab === 'chat'"
-    :element="element"
-    :provider="provider"
-    @changes="onChatChanges"
-  />
-
-  <!-- v-if lädt die Edit-Felder bei jedem Öffnen frisch -->
-  <ElementEditTab
-    v-if="tab === 'edit'"
-    :element="element"
-    :saving="savingEdit"
-    @save="saveEdit"
-  />
-</template>
-
-<style scoped>
-.el-header {
-  display: flex;
-  align-items: center;
-  gap: 6px;
-  padding: 0.6rem 0.9rem;
-  border-bottom: 1px solid var(--border);
-}
-
-.el-title {
-  flex: 1;
-  font-weight: 600;
-  font-size: 0.9rem;
-  color: var(--text);
-  overflow: hidden;
-  text-overflow: ellipsis;
-  white-space: nowrap;
-}
-
-.el-back,
-.el-close {
-  border: none;
-  background: none;
-  color: var(--text-faint);
-  font-size: 1.2rem;
-  line-height: 1;
-  cursor: pointer;
-  padding: 0 4px;
-}
-
-.el-back:hover,
-.el-close:hover {
-  color: var(--text);
-}
-
-.el-tool {
-  border: none;
-  background: none;
-  font-size: 0.95rem;
-  line-height: 1;
-  cursor: pointer;
-  padding: 2px 3px;
-  border-radius: 6px;
-  filter: grayscale(0.4);
-}
-
-.el-tool:hover {
-  background: var(--panel-soft);
-  filter: none;
-}
-
-.el-tool.busy {
-  filter: none;
-  animation: pulse 1.5s ease-in-out infinite;
-}
-
-.busy-text {
-  animation: pulse 1.5s ease-in-out infinite;
-}
-
-@keyframes pulse {
-  50% { opacity: 0.35; }
-}
-
-.el-tabs {
-  display: flex;
-  border-bottom: 1px solid var(--border);
-}
-
-.el-tabs button {
-  flex: 1;
-  padding: 0.5rem 0.25rem;
-  border: none;
-  background: none;
-  color: var(--text-muted);
-  font-size: 0.8rem;
-  font-weight: 600;
-  cursor: pointer;
-  border-bottom: 2px solid transparent;
-}
-
-.el-tabs button.active {
-  color: var(--accent);
-  border-bottom-color: var(--accent);
-}
-
-.el-tabs button:hover:not(.active) {
-  color: var(--text);
-}
-
-.el-detail {
-  flex: 1;
-  overflow-y: auto;
-  padding: 0.9rem;
-}
-
-.el-desc {
-  margin: 0 0 0.9rem;
-  font-size: 0.85rem;
-  line-height: 1.6;
-  color: var(--text);
-}
-
-.el-hints-block {
-  margin-top: 0.9rem;
-}
-
-.el-hints-block h4 {
-  margin: 0 0 0.35rem;
-  font-size: 0.72rem;
-  font-weight: 700;
-  text-transform: uppercase;
-  letter-spacing: 0.05em;
-  color: var(--text-faint);
-}
-
-.el-entry {
-  font-size: 0.82rem;
-  line-height: 1.5;
-  color: var(--text);
-  margin-bottom: 0.4rem;
-}
-
-.el-entry:last-child {
-  margin-bottom: 0;
-}
-
-.el-hints {
-  margin: 0;
-  padding-left: 1.1rem;
-}
-
-.el-hints li {
-  font-size: 0.82rem;
-  line-height: 1.5;
-  color: var(--text);
-  margin-bottom: 0.25rem;
-}
-
-/* Hinweis-Text inline neben dem Bullet halten (p ist sonst block) */
-.el-hints li > .markdown {
-  display: inline;
-}
-
-.el-hints li > .markdown :deep(p) {
-  display: inline;
-  margin: 0;
-}
-
-/* Markdown: Basis global (assets/markdown.css); schmale Sidebar → kompaktere Code-Blöcke */
-.markdown :deep(pre) {
-  padding: 8px 10px;
-}
-
-/* --- KI-Prüfung --- */
-.el-check {
-  margin-top: 1rem;
-  padding-top: 0.8rem;
-  border-top: 1px dashed var(--border-strong);
-}
-
-.check-empty {
-  margin: 0.6rem 0 0;
-  font-size: 0.78rem;
-  color: var(--text-faint);
-  text-align: center;
-}
-</style>

frontend/src/components/elements/ElementEditTab.vue

@@ -1,164 +0,0 @@
-<script setup>
-import { ref, watch } from 'vue'
-
-const props = defineProps({
-  element: { type: Object, required: true },
-  saving: { type: Boolean, default: false },
-})
-
-const emit = defineEmits(['save'])
-
-const edit = ref({ title: '', description: '', examples: [], hints: [] })
-
-watch(() => props.element, load, { immediate: true })
-
-function load() {
-  edit.value = {
-    title: props.element.title,
-    description: props.element.description,
-    examples: [...props.element.examples],
-    hints: [...props.element.hints],
-  }
-}
-
-function save() {
-  if (props.saving) return
-  emit('save', {
-    title: edit.value.title,
-    description: edit.value.description,
-    examples: edit.value.examples.filter((s) => s.trim()),
-    hints: edit.value.hints.filter((s) => s.trim()),
-  })
-}
-</script>
-
-<template>
-  <div class="el-edit">
-    <button class="edit-save" :disabled="saving" @click="save">
-      {{ saving ? 'Speichert…' : 'Speichern' }}
-    </button>
-
-    <label>Titel</label>
-    <input v-model="edit.title" placeholder="Titel" />
-
-    <label>Beschreibung</label>
-    <textarea v-model="edit.description" placeholder="Beschreibung"></textarea>
-
-    <label>Beispiele</label>
-    <div v-for="(ex, i) in edit.examples" :key="'ex' + i" class="edit-row">
-      <textarea v-model="edit.examples[i]" placeholder="Beispiel"></textarea>
-      <button class="edit-del" title="Entfernen" @click="edit.examples.splice(i, 1)">×</button>
-    </div>
-    <button class="edit-add" @click="edit.examples.push('')">+ Beispiel</button>
-
-    <label>Hinweise</label>
-    <div v-for="(h, i) in edit.hints" :key="'hi' + i" class="edit-row">
-      <textarea v-model="edit.hints[i]" placeholder="Hinweis"></textarea>
-      <button class="edit-del" title="Entfernen" @click="edit.hints.splice(i, 1)">×</button>
-    </div>
-    <button class="edit-add" @click="edit.hints.push('')">+ Hinweis</button>
-  </div>
-</template>
-
-<style scoped>
-.el-edit {
-  flex: 1;
-  overflow-y: auto;
-  padding: 0.9rem;
-  display: flex;
-  flex-direction: column;
-  gap: 0.4rem;
-}
-
-.el-edit label {
-  font-size: 0.72rem;
-  font-weight: 700;
-  text-transform: uppercase;
-  letter-spacing: 0.05em;
-  color: var(--text-faint);
-  margin-top: 0.5rem;
-}
-
-.el-edit input,
-.el-edit textarea {
-  width: 100%;
-  padding: 8px 10px;
-  border: 1px solid var(--border-strong);
-  border-radius: 8px;
-  font-size: 0.85rem;
-  font-family: inherit;
-  background: var(--panel);
-  color: var(--text);
-  outline: none;
-}
-
-.el-edit textarea {
-  resize: vertical;
-  min-height: 120px;
-  overflow: auto;
-  line-height: 1.4;
-}
-
-.el-edit input:focus,
-.el-edit textarea:focus {
-  border-color: var(--accent);
-}
-
-.edit-row {
-  display: flex;
-  gap: 6px;
-  align-items: flex-start;
-}
-
-.edit-row textarea {
-  flex: 1;
-}
-
-.edit-del {
-  flex-shrink: 0;
-  width: 30px;
-  align-self: stretch;
-  border: 1px solid var(--border-strong);
-  border-radius: 8px;
-  background: none;
-  color: var(--danger);
-  font-size: 1rem;
-  cursor: pointer;
-}
-
-.edit-add {
-  align-self: flex-start;
-  padding: 5px 10px;
-  border: 1px dashed var(--border-strong);
-  border-radius: 8px;
-  background: none;
-  color: var(--text-muted);
-  font-size: 0.78rem;
-  cursor: pointer;
-}
-
-.edit-add:hover {
-  border-color: var(--accent);
-  color: var(--accent);
-}
-
-.edit-save {
-  position: sticky;
-  top: 0;
-  z-index: 1;
-  margin-bottom: 0.3rem;
-  padding: 9px 10px;
-  border: none;
-  border-radius: 8px;
-  background: var(--accent);
-  color: var(--on-accent);
-  font-size: 0.85rem;
-  font-weight: 600;
-  cursor: pointer;
-}
-
-.edit-save:disabled {
-  opacity: 0.5;
-  cursor: wait;
-}
-</style>

frontend/src/components/elements/ElementList.vue

@@ -1,198 +0,0 @@
-<script setup>
-import { ref, computed } from 'vue'
-import { useConfirm } from '../../composables/useConfirm.js'
-
-const props = defineProps({
-  elements: { type: Array, required: true },
-  creating: { type: Boolean, default: false },
-})
-
-const emit = defineEmits(['select', 'create', 'remove'])
-
-const query = ref('')
-const { isArmed, armOrRun } = useConfirm()
-
-// Markdown-Zeichen für Titel und Listen-Vorschau entfernen
-function plain(text) {
-  return (text || '').replace(/```[a-z]*\n?/g, '').replace(/[`*_#]/g, '')
-}
-
-const filtered = computed(() => {
-  const q = query.value.trim().toLowerCase()
-  if (!q) return props.elements
-  return props.elements.filter(
-    (el) => el.title.toLowerCase().includes(q) || el.description.toLowerCase().includes(q),
-  )
-})
-
-function add() {
-  if (props.creating) return
-  emit('create', query.value.trim())
-  query.value = ''
-}
-
-// Inline-Bestätigung: erster Klick „Sicher?", zweiter löscht
-function confirmDelete(el) {
-  armOrRun('el-' + el.id, () => emit('remove', el))
-}
-</script>
-
-<template>
-  <div class="el-new">
-    <input
-      v-model="query"
-      placeholder="Suchen oder Stichwort…"
-      :disabled="creating"
-      @keyup.enter="add"
-    />
-    <button :disabled="creating" title="Element per KI erstellen" @click="add">+</button>
-  </div>
-  <div v-if="creating" class="el-creating">KI erstellt Element…</div>
-  <ul class="el-list">
-    <li v-for="el in filtered" :key="el.id" @click="emit('select', el)">
-      <div class="el-item-main">
-        <span class="el-item-title">{{ plain(el.title) }}</span>
-        <span class="el-item-desc">{{ plain(el.description) }}</span>
-      </div>
-      <button
-        class="el-delete"
-        :class="{ armed: isArmed('el-' + el.id) }"
-        title="Element löschen"
-        @click.stop="confirmDelete(el)"
-      >{{ isArmed('el-' + el.id) ? 'Sicher?' : '×' }}</button>
-    </li>
-    <li v-if="!filtered.length && !creating" class="el-empty">
-      {{ elements.length ? 'Keine Treffer.' : 'Noch keine Elemente. Stichwort eingeben und + klicken.' }}
-    </li>
-  </ul>
-</template>
-
-<style scoped>
-.el-new {
-  display: flex;
-  gap: 6px;
-  padding: 0.6rem 0.75rem;
-}
-
-.el-new input {
-  flex: 1;
-  padding: 8px 10px;
-  border: 1px solid var(--border-strong);
-  border-radius: 8px;
-  font-size: 0.85rem;
-  background: var(--panel);
-  color: var(--text);
-  outline: none;
-}
-
-.el-new input:focus {
-  border-color: var(--accent);
-}
-
-.el-new button {
-  width: 38px;
-  border: none;
-  border-radius: 8px;
-  background: var(--accent);
-  color: var(--on-accent);
-  font-size: 1.1rem;
-  cursor: pointer;
-}
-
-.el-new button:disabled {
-  opacity: 0.4;
-  cursor: not-allowed;
-}
-
-.el-creating {
-  padding: 0.4rem 0.75rem;
-  font-size: 0.78rem;
-  color: var(--warning);
-  background: var(--warning-soft);
-  animation: pulse 1.5s ease-in-out infinite;
-}
-
-@keyframes pulse {
-  50% { opacity: 0.35; }
-}
-
-.el-list {
-  flex: 1;
-  overflow-y: auto;
-  list-style: none;
-  margin: 0;
-  padding: 0.25rem 0;
-}
-
-.el-list li {
-  display: flex;
-  align-items: center;
-  gap: 6px;
-  padding: 0.5rem 0.75rem;
-  cursor: pointer;
-  transition: background 0.15s;
-}
-
-.el-list li:hover {
-  background: var(--panel-soft);
-}
-
-.el-item-main {
-  flex: 1;
-  min-width: 0;
-}
-
-.el-item-title {
-  display: block;
-  font-size: 0.85rem;
-  font-weight: 600;
-  color: var(--text);
-  overflow: hidden;
-  text-overflow: ellipsis;
-  white-space: nowrap;
-}
-
-.el-item-desc {
-  display: block;
-  font-size: 0.75rem;
-  color: var(--text-faint);
-  overflow: hidden;
-  text-overflow: ellipsis;
-  white-space: nowrap;
-}
-
-.el-delete {
-  border: none;
-  background: none;
-  color: var(--danger);
-  font-size: 1rem;
-  line-height: 1;
-  cursor: pointer;
-  padding: 0 2px;
-  visibility: hidden;
-}
-
-.el-list li:hover .el-delete {
-  visibility: visible;
-}
-
-.el-delete.armed {
-  visibility: visible;
-  font-size: 0.7rem;
-  font-weight: 700;
-  background: var(--danger);
-  color: #fff;
-  border-radius: 4px;
-  padding: 2px 6px;
-}
-
-.el-empty {
-  cursor: default !important;
-  color: var(--text-faint);
-  font-size: 0.8rem;
-}
-
-.el-empty:hover {
-  background: none !important;
-}
-</style>

frontend/src/components/elements/ElementSuggestion.vue

@@ -1,184 +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: Basis global (assets/markdown.css); kompakte Vorschau-Code-Blöcke */
-.markdown :deep(pre) {
-  padding: 6px 8px;
-  border-radius: 6px;
-  margin: 0.3em 0;
-}
-</style>

frontend/src/components/elements/ElementsSidebar.vue

@@ -1,156 +0,0 @@
-<script setup>
-import { ref, watch } from 'vue'
-import { fetchElements, createElement, deleteElement } from '../../api.js'
-import ElementList from './ElementList.vue'
-import ElementDetail from './ElementDetail.vue'
-
-const props = defineProps({
-  topic: { type: String, required: true },
-  provider: { type: String, default: 'claude' },
-  openId: { type: String, default: null },   // Element-ID, die geöffnet werden soll
-  openTick: { type: Number, default: 0 },    // Erhöhung = openId (erneut) öffnen
-})
-
-const emit = defineEmits(['close', 'changed'])
-
-const elements = ref([])
-const creating = ref(false)
-const selected = ref(null)
-
-watch(() => props.topic, load, { immediate: true })
-
-async function load() {
-  selected.value = null
-  try {
-    elements.value = await fetchElements(props.topic)
-  } catch (e) {
-    console.error('Fehler beim Laden der Elemente:', e)
-  }
-  openFromProp()
-}
-
-// Aus der Übersicht im Hauptbereich angeklicktes Element öffnen
-watch(() => props.openTick, openFromProp)
-
-function openFromProp() {
-  if (!props.openId) return
-  const el = elements.value.find((e) => e.id === props.openId)
-  if (el) selected.value = el
-}
-
-async function create(hint) {
-  if (creating.value) return
-  creating.value = true
-  try {
-    const el = await createElement(props.topic, hint, props.provider)
-    elements.value.unshift(el)
-    emit('changed')
-  } catch (e) {
-    console.error('Fehler beim Erstellen des Elements:', e)
-  } finally {
-    creating.value = false
-  }
-}
-
-async function remove(el) {
-  await deleteElement(el.id)
-  elements.value = elements.value.filter((e) => e.id !== el.id)
-  if (selected.value?.id === el.id) selected.value = null
-  emit('changed')
-}
-
-// Bearbeitetes Element in Liste und Auswahl synchron halten
-function onUpdated(el) {
-  selected.value = el
-  const idx = elements.value.findIndex((e) => e.id === el.id)
-  if (idx !== -1) elements.value.splice(idx, 1, el)
-  emit('changed')
-}
-</script>
-
-<template>
-  <aside class="elements-sidebar">
-    <ElementDetail
-      v-if="selected"
-      :element="selected"
-      :provider="provider"
-      @back="selected = null"
-      @close="emit('close')"
-      @updated="onUpdated"
-      @changed="emit('changed')"
-    />
-    <template v-else>
-      <header class="el-header">
-        <span class="el-title">Elemente</span>
-        <button class="el-close" title="Schließen" @click="emit('close')">×</button>
-      </header>
-      <ElementList
-        :elements="elements"
-        :creating="creating"
-        @select="(el) => (selected = el)"
-        @create="create"
-        @remove="remove"
-      />
-    </template>
-  </aside>
-</template>
-
-<style scoped>
-.elements-sidebar {
-  width: 320px;
-  min-width: 320px;
-  height: 100dvh;
-  display: flex;
-  flex-direction: column;
-  background: var(--panel);
-  border-left: 1px solid var(--border);
-  /* Über dem Guide-Chat (FAB/Panel: z-index 20) */
-  position: relative;
-  z-index: 30;
-}
-
-/* Mobil/schmal: als Overlay über den Hauptinhalt legen, statt ihn
-   im Flex-Fluss einzuquetschen. */
-@media (max-width: 768px) {
-  .elements-sidebar {
-    position: fixed;
-    top: 0;
-    right: 0;
-    width: min(100vw, 380px);
-    min-width: 0;
-    box-shadow: -4px 0 16px var(--shadow);
-  }
-}
-
-.el-header {
-  display: flex;
-  align-items: center;
-  gap: 6px;
-  padding: 0.6rem 0.9rem;
-  border-bottom: 1px solid var(--border);
-}
-
-.el-title {
-  flex: 1;
-  font-weight: 600;
-  font-size: 0.9rem;
-  color: var(--text);
-  overflow: hidden;
-  text-overflow: ellipsis;
-  white-space: nowrap;
-}
-
-.el-close {
-  border: none;
-  background: none;
-  color: var(--text-faint);
-  font-size: 1.2rem;
-  line-height: 1;
-  cursor: pointer;
-  padding: 0 4px;
-}
-
-.el-close:hover {
-  color: var(--text);
-}
-</style>

frontend/src/composables/useChat.js

@@ -1,23 +1,23 @@
 import { ref, nextTick } from 'vue'
 
-// (Fast) am unteren Rand? Schwelle fängt Sub-Pixel und kleine Abstände ab.
-export function istUnten(el, schwelle = 60) {
-  return el.scrollHeight - el.scrollTop - el.clientHeight < schwelle
+// (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
 }
 
-// Gemeinsame Chat-Mechanik: senden, abbrechen (Run-Counter), scrollen, Fokus.
-// performRequest(messages) → Promise<{ reply, … }>; send() gibt die Antwort
-// zurück, damit der Aufrufer Extras (z. B. changes) auswerten kann.
+// 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: Nachrichten-Container
-  const inputEl = ref(null)    // Template-Ref: Textarea
-  const stick = ref(true)      // an den Boden „gepinnt" — nur dann auto-scrollen
-  let run = 0 // laufende Anfrage identifizieren; Abbruch ignoriert ihr Ergebnis
+  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: pinnt nur, wenn der Nutzer (fast) unten ist.
+  // @scroll handler: pins only when the user is (almost) at the bottom.
   function onScroll() {
     if (messagesEl.value) stick.value = istUnten(messagesEl.value)
   }
@@ -37,7 +37,7 @@ export function useChat(performRequest) {
   function cancel() {
     run++
     loading.value = false
-    messages.value.push({ role: 'assistant', content: 'Abgebrochen.' })
+    messages.value.push({ role: 'assistant', content: 'Cancelled.' })
   }
 
   function reset() {
@@ -48,13 +48,13 @@ export function useChat(performRequest) {
   }
 
   async function send() {
-    if (loading.value) { // zweiter Klick = abbrechen
+    if (loading.value) { // second click = cancel
       cancel()
       return null
     }
     const text = input.value.trim()
     if (!text) return null
-    stick.value = true // eigenes Senden = ans Ende; Hochscrollen während des Wartens setzt es wieder false
+    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 = ''
@@ -64,17 +64,17 @@ export function useChat(performRequest) {
     try {
       const res = await performRequest(messages.value)
       if (current !== run) return null
-      // Prüfung liefert `frage` (+ getrenntes `feedback`); andere Chats `reply`.
+      // Exam returns `question` (+ separate `feedback`); other chats `reply`.
       messages.value.push({
         role: 'assistant',
-        content: res.frage ?? res.reply ?? '…',
+        content: res.question ?? res.reply ?? '…',
         feedback: res.feedback ?? null,
-        bewertung: res.bewertung ?? null,
+        rating: res.rating ?? null,
       })
       return res
     } catch {
       if (current !== run) return null
-      messages.value.push({ role: 'assistant', content: 'Fehler bei der Anfrage.' })
+      messages.value.push({ role: 'assistant', content: 'Request failed.' })
       return null
     } finally {
       if (current === run) {

frontend/src/composables/useConfirm.js

@@ -1,9 +1,9 @@
 import { ref, onUnmounted } from 'vue'
 
-// Inline-Bestätigung statt confirm(): erster Klick scharfschalten („Sicher?"),
-// zweiter Klick führt aus. Browser-Dialoge können unterdrückt sein (Firefox).
+// 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) // aktuell scharfgeschalteter Key
+  const pending = ref(null) // currently armed key
   let timer = null
 
   function armOrRun(key, action) {

frontend/src/composables/usePolling.js

@@ -1,8 +1,8 @@
 import { onUnmounted } from 'vue'
 
-// Polling mit Visibility-Pause: Tab unsichtbar → stoppen; wieder sichtbar →
-// sofortiger Tick, dann weiter, falls isActive(). Stoppt selbst, sobald
-// isActive() nach einem Tick false liefert.
+// 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
 

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/markdown.js

@@ -17,9 +17,9 @@ marked.use(markedHighlight({
 }))
 marked.setOptions({ breaks: true, gfm: true })
 
-// LaTeX-Mathe via KaTeX. Eigene marked-Extensions (statt marked-katex-extension,
-// die marked v18 hinterherhinkt). marked tokenisiert Code zuerst → $…$ in Code-
-// Blöcken wird NICHT als Mathe erkannt. throwOnError:false zeigt defektes TeX rot.
+// 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' })
 }
@@ -40,8 +40,8 @@ const inlineMath = {
   level: 'inline',
   start(src) { const i = src.indexOf('$'); return i < 0 ? undefined : i },
   tokenizer(src) {
-    // $…$: kein $$, kein Leerzeichen direkt hinter dem öffnenden $ und vor dem
-    // schließenden $ (pandoc-Stil) → mindert Kollisionen mit Fließtext-Dollarzeichen.
+    // $…$: 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() }
@@ -51,8 +51,8 @@ const inlineMath = {
 
 marked.use({ extensions: [blockMath, inlineMath] })
 
-// Rohes HTML im Markdown (z. B. <p>, <img> ohne Backticks aus Agenten-Output)
-// als Text anzeigen statt rendern — sonst verschluckt der Browser den Inhalt.
+// 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) {
@@ -66,8 +66,18 @@ export function renderMarkdown(text) {
   return DOMPurify.sanitize(marked.parse(text || ''))
 }
 
-// Inline-Variante (kein <p>-Wrapping) für kurze Texte wie Quiz-Optionen oder
-// Lückentext-Satzteile — rendert $…$-Mathe und Markdown ohne Block-Umbruch.
+// 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

@@ -1,12 +1,12 @@
-// Geteilter Prüfungs-State pro Baustein.
-// Die durablen Refs leben hier als Modul-Map: alle BausteinPanel-Instanzen desselben
-// Bausteins nutzen DIESELBEN Refs. So überlebt der Verlauf das Remounten (Baustein-
-// Wechsel, Fokus zu/auf) UND eine spät eintreffende Frage ist sofort reaktiv sichtbar.
-// Geht bei Page-Reload verloren (Modul re-init) — bewusst kein DB-Aufwand.
+// 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::baustein" -> Refs (Verlauf + Fragen-Pool)
+const store = new Map() // key "topic::block" -> refs (history + questions pool)
 
 export function usePruefSlot(key) {
   if (!store.has(key)) {
@@ -15,14 +15,14 @@ export function usePruefSlot(key) {
       phase: ref('idle'),
       aktuelleFrage: ref(''),
       letztesFeedback: ref(''),
-      pool: ref([]),        // vorformulierte Frage-Objekte der AKTUELLEN Form ({form, ...})
-      inflight: ref(0),     // laufende Pool-Generierungen (instanzübergreifend koordiniert)
-      poolForm: ref(''),    // Form, für die der Pool gefüllt ist — bei Wechsel leeren
-      musterQuelle: ref([]), // unveränderliche Voll-Liste der Frage-Muster (leer = Fallback)
-      musterPool: ref([]),  // Arbeitskopie: gezogene Saat ohne Zurücklegen; leer → Reset
-      musterGeladen: ref(false), // Muster-Sidecar schon abgerufen?
-      quizAktuell: ref(null), // laufende Quiz-Frage {frage, optionen, gewaehlt, fertig, ...}
-      lueckAktuell: ref(null), // laufende Lückentext-Aufgabe {satz, loesung, ..., fertig}
+      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)

templates/Format/Section.md

@@ -35,6 +35,12 @@ Markdown im Section-Body: erklärende Absätze in normalem Text, Aufzählungen a
 
 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.
 
+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.
+
 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.

templates/Prompt/Artifact-Example-Check.md

@@ -0,0 +1,25 @@
+You are a correctness checker for worked examples on the topic "{topic}". Another agent produced them — they are meant to demonstrate a **correct** solution to the learner. A wrong example imprints a wrong solution path. Find the faulty ones.
+
+GROUND TRUTH — the supported facts (measure only against these):
+{facts}
+
+EXAMPLES TO CHECK (numbered; PROBLEM / STEPS / RESULT):
+{examples}
+
+Object to an example if ANY of these applies:
+- **Calculation error** in a step (a number, a transformation, a unit).
+- **Wrong inference:** a step does not follow from the previous one; the RESULT does not follow from the steps.
+- **Not covered:** a step/value contradicts the facts or invents something not stated there.
+- **Incomplete/misleading:** the path would lead the learner to a wrong conclusion.
+
+Rules:
+- Measure ONLY against the facts + internal logic. Recompute it yourself.
+- **Conservative:** object only to what is **clearly** wrong. When in doubt, keep it.
+- Give the 1-based number (`index`) of each faulty example.
+
+Reply with ONLY the JSON — no other text, no code fences — one of the two:
+{{"ok": true}}
+{{"problems": [{{"index": 2}}, {{"index": 5}}]}}
+
+Output no other text.
+{extra}

templates/Prompt/Artifact-Example.md

@@ -0,0 +1,24 @@
+Build a worked example for the subblocks of the topic "{topic}" — a fully worked-through case that carries understanding.
+
+BLOCKS WITH SUBBLOCKS AND THEIR FACTS (go through EVERY subblock):
+{blocks}
+
+A good worked example:
+- **problem**: a concrete, small task/question about the subblock (1 sentence).
+- **steps**: 2–5 followable steps from the problem to the solution. Each step a brief sentence, in the right order.
+- **result**: the final result / the insight (1 sentence).
+- Rely on `example_idea` and the supported facts of the subblock. Compute cleanly; invent no values that contradict the facts.
+- **Only where it carries:** if a subblock cannot be sensibly shown with an example (a pure definition, meta-knowledge), LEAVE IT OUT — no forced example.
+- **Mathematics ALWAYS as LaTeX**, never as raw characters: inline `$…$` (e.g. `$T_A(n)$`, `$\Sigma^*$`, `$|x| = 5$`, `$O(n^d)$`, `$q_a$`), longer/worked-through formulas set off as `$$…$$`. NO Unicode math substitutes (`≤`, `≥`, `Σ`, `δ`, `∈`, `⊆`, `×`) and no bare `_`/`^` — use `$\le$`, `$\ge$`, `$\Sigma$`, `$\delta$`, `$\in$`, `$\subseteq$`, `$\times$`, `$n^d$`, `$q_a$` instead. Real code/paths/identifiers (not math) in backticks.
+- **The supplied facts often contain math as raw Unicode — convert it to LaTeX, do not take it over raw.**
+
+Write `problem`, the `steps` and `result` in GERMAN.
+
+Reply with ONLY the JSON (all examples) as your final message — no code fences, do NOT write a file. EXACTLY like this:
+{{"examples": [
+  {{"block": "<exact block title>", "subblock": "<exact subblock title>",
+    "problem": "…", "steps": ["…", "…"], "result": "…"}}
+]}}
+
+Output no other text.
+{extra}