Sidebar: Abbrechen/Reset für laufende und pausierte Generierungen immer erreichbar

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Makefile

@@ -1,4 +1,4 @@
-.PHONY: install dev prod stop logs remove auth sync searxng ollama
+.PHONY: install dev prod stop logs remove auth sync sync-projects projects searxng ollama
 
 COMPOSE = docker compose
 
@@ -63,3 +63,12 @@ sync:
 	rsync -avz --progress root@178.104.67.87:/var/www/creator/storage/creator.db storage/
 	rsync -avz --progress --delete root@178.104.67.87:/var/www/creator/storage/themen/ storage/themen/
 	@echo "Sync abgeschlossen."
+
+# Projekte vom Server holen: `make sync-projects` (auch: `make sync projects`).
+# Ohne --delete — lokale Projekte, die es auf dem Server nicht gibt, bleiben.
+sync-projects:
+	@mkdir -p projects
+	rsync -avz --progress root@178.104.67.87:/var/www/creator/projects/ projects/
+	@echo "Projekt-Sync abgeschlossen."
+
+projects: sync-projects

backend/agents.py

@@ -5,17 +5,27 @@ jeweilige Provider fehl — der andere läuft unverändert weiter.
 """
 
 import asyncio
+import logging
 import os
 import re
 import shutil
 import tempfile
+import time
 import urllib.request
 from pathlib import Path
 
-from config import PROVIDERS, DEFAULT_PROVIDER
+from config import PROVIDERS, DEFAULT_PROVIDER, MAX_CONCURRENT_AGENTS, MAX_CONCURRENT_INTERACTIVE
+
+log = logging.getLogger("creator.agents")
 
 _active_processes: dict[str, asyncio.subprocess.Process] = {}
 
+# 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)
+_interactive_sem = asyncio.Semaphore(MAX_CONCURRENT_INTERACTIVE)
+
 # Capability → Claude --allowedTools
 _CLAUDE_TOOLS = {
     "full": "Write,Bash,Read,WebSearch,WebFetch",
@@ -54,7 +64,11 @@ def provider_available(provider: str) -> bool:
 def kill_process(agent_key_prefix: str) -> None:
     """Killt alle aktiven Prozesse, deren Key mit dem Prefix beginnt (deckt -plan/-w1… ab)."""
     for key, process in list(_active_processes.items()):
-        if key.startswith(agent_key_prefix) and process.returncode is None:
+        if process.returncode is not None:  # tote Einträge beim Iterieren aufräumen
+            _active_processes.pop(key, None)
+            continue
+        if key.startswith(agent_key_prefix):
+            log.debug("kill agent %s", key)
             process.kill()
 
 
@@ -65,17 +79,21 @@ async def run_agent(
     provider: str = DEFAULT_PROVIDER,
     role: str = "fast",
     capabilities: str = "none",
+    lane: str = "batch",
 ) -> tuple[int, str, str]:
     if provider not in PROVIDERS:
         return 1, "", f"Unbekannter Provider: {provider}"
     if shutil.which(PROVIDERS[provider]["cli"]) is None:
         return 1, "", f"CLI '{PROVIDERS[provider]['cli']}' nicht installiert (Provider: {provider})"
+    sem = _interactive_sem if lane == "interactive" else _batch_sem
+    async with sem:
         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)
 
 
 async def _communicate(agent_key: str, cmd: list[str], stdin_data: bytes | None, timeout: int) -> tuple[int, str, str]:
+    start = time.monotonic()
     process = await asyncio.create_subprocess_exec(
         *cmd,
         stdin=asyncio.subprocess.PIPE if stdin_data is not None else asyncio.subprocess.DEVNULL,
@@ -95,10 +113,18 @@ 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)
             raise
+        log.info(
+            "agent %s: exit %s nach %.1fs (%d Bytes stdout)",
+            agent_key, process.returncode, time.monotonic() - start, len(stdout),
+        )
         return process.returncode, stdout.decode("utf-8", errors="replace"), stderr.decode("utf-8", errors="replace")
     finally:
-        _active_processes.pop(agent_key, None)
+        # 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]
 
 
 async def _run_claude_cli(agent_key: str, prompt: str, timeout: int, role: str, capabilities: str) -> tuple[int, str, str]:

backend/bausteine.py

@@ -0,0 +1,367 @@
+"""Bausteine-Pipeline: 4x Recherche (3 nötig) → 2x Auswahl (1) → Prüfung — reines Inventar, unsortiert."""
+
+import asyncio
+import logging
+import shutil
+import subprocess
+from pathlib import Path
+
+from agents import kill_process
+from config import DEFAULT_PROVIDER
+from fsutil import atomic_write_text
+from jsonio import read_json_file as _json_datei
+from paths import arbeit_dir, bausteine_path, project_dir
+from pipeline import (
+    CANCELLED, FAILED, GenContext, _extra, _log, _prompt, _race,
+    _semaphore, _timeout, run_single_slot,
+)
+from textkit import _eindeutige_titel, _parse_auswahl, _titel, _titel_aufloesen, _titel_index
+
+log = logging.getLogger("creator.bausteine")
+
+_bausteine_progress: dict[str, str] = {}
+_bausteine_errors: dict[str, str] = {}
+_bausteine_cancelled: set[str] = set()
+_bausteine_step: dict[str, int] = {}
+
+BAUSTEINE_STEPS = ("Recherche", "Auswahl", "Prüfung")
+
+
+def _bausteine_steps(topic: str) -> tuple:
+    """Projekte haben einen 4. Schritt: Themenfeld-Ergänzung per Web-Recherche."""
+    if project_dir(topic).is_dir():
+        return BAUSTEINE_STEPS + ("Ergänzung",)
+    return BAUSTEINE_STEPS
+
+
+def _bausteine_files(topic: str) -> dict:
+    arbeit = arbeit_dir(topic)
+    return {
+        "final": bausteine_path(topic),
+        "arbeit": arbeit,
+        "recherche": [arbeit / f"recherche-{i}.md" for i in (1, 2, 3, 4)],
+        "auswahl": [arbeit / f"auswahl-{i}.md" for i in (1, 2)],
+        "auswahl_check": arbeit / "auswahl-check.json",
+        "ergaenzung": arbeit / "ergaenzung.json",
+    }
+
+
+def _alle_slot_dateien(files: dict) -> list[Path]:
+    return [*files["recherche"], *files["auswahl"], files["auswahl_check"], files["ergaenzung"]]
+
+
+def cancel_bausteine(topic: str) -> bool:
+    if topic not in _bausteine_progress:
+        return False
+    _bausteine_cancelled.add(topic)
+    kill_process(f"bausteine-{topic}-")
+    return True
+
+
+def _resume_step(topic: str) -> int:
+    """Erster noch offener Schritt anhand der persistierten Zwischendateien."""
+    files = _bausteine_files(topic)
+    if sum(p.exists() for p in files["recherche"]) < 3:
+        return 0
+    if not any(p.exists() for p in files["auswahl"]):
+        return 1
+    if not files["auswahl_check"].exists():
+        return 2
+    if project_dir(topic).is_dir() and not files["ergaenzung"].exists():
+        return 3
+    return len(_bausteine_steps(topic))
+
+
+def bausteine_status(topic: str) -> dict:
+    steps = _bausteine_steps(topic)
+    ready = bausteine_path(topic).exists()
+    generating = topic in _bausteine_progress
+    partial = False
+    if generating:
+        current = _bausteine_step.get(topic)
+        states = [
+            "pending" if current is None else "done" if i < current else "active" if i == current else "pending"
+            for i in range(len(steps))
+        ]
+    elif ready:
+        states = ["done"] * len(steps)
+    else:
+        nxt = _resume_step(topic)
+        partial = nxt > 0
+        states = ["done" if i < nxt else "pending" for i in range(len(steps))]
+    return {
+        "ready": ready,
+        "generating": generating,
+        "progress": _bausteine_progress.get(topic),
+        "error": _bausteine_errors.get(topic),
+        "partial": partial,
+        "steps": [{"label": label, "state": s} for label, s in zip(steps, states)],
+    }
+
+
+def active_bausteine() -> list[dict]:
+    return [{"topic": t, "progress": p} for t, p in _bausteine_progress.items()]
+
+
+def reset_bausteine(topic: str) -> None:
+    files = _bausteine_files(topic)
+    files["final"].unlink(missing_ok=True)
+    shutil.rmtree(files["arbeit"], ignore_errors=True)
+    _bausteine_errors.pop(topic, None)
+
+
+def _ergaenzung_schema(data):
+    """{"bausteine": [{"titel", "beschreibung"}]} → Liste (leer erlaubt) · sonst None."""
+    if not isinstance(data, dict) or not isinstance(data.get("bausteine"), list):
+        return None
+    out = []
+    for b in data["bausteine"]:
+        if not isinstance(b, dict) or not isinstance(b.get("titel"), str) or not isinstance(b.get("beschreibung"), str):
+            return None
+        titel, beschreibung = b["titel"].strip(), b["beschreibung"].strip()
+        if not titel:
+            return None
+        out.append((titel, beschreibung))
+    return out
+
+
+def _pdfs_konvertieren(project: Path) -> None:
+    """PDFs im Projekt in .txt wandeln (pdftotext) — Agenten lesen Text statt Seiten-Bildern.
+
+    Wird vor jeder Projekt-Generierung aufgerufen; konvertiert nur, wenn die
+    .txt fehlt oder älter als das PDF ist. Das Original bleibt unangetastet.
+    Fehlt pdftotext und das Projekt enthält PDFs → harter Fehler statt
+    unzuverlässigem Direkt-Lese-Modus (MiniMax-Bilderlimit, Vision-Kosten).
+    """
+    pdfs = list(project.rglob("*.pdf"))
+    if not pdfs:
+        return
+    if shutil.which("pdftotext") is None:
+        raise RuntimeError("pdftotext fehlt (poppler-utils installieren) — PDFs im Projekt können nicht gelesen werden")
+    for pdf in pdfs:
+        txt = pdf.with_suffix(".txt")
+        if txt.exists() and txt.stat().st_mtime >= pdf.stat().st_mtime:
+            continue
+        try:
+            subprocess.run(["pdftotext", "-layout", str(pdf), str(txt)], check=True, timeout=120)
+            _log(project.name, f"PDF konvertiert: {pdf.name} → {txt.name}")
+        except Exception as e:
+            raise RuntimeError(f"PDF-Konvertierung fehlgeschlagen ({pdf.name}): {e}") from e
+
+
+def _build_recherche_prompt(topic: str, out_path: Path, instructions: str = "", project: Path | None = None) -> str:
+    if project:
+        source = _prompt("Bausteine-Quelle-Projekt", project=project)
+    else:
+        source = _prompt("Bausteine-Quelle-Thema", topic=topic)
+    return _prompt(
+        "Bausteine-Recherche",
+        topic=topic, source=source, bausteine_path=out_path, extra=_extra(instructions),
+    )
+
+
+def _file_payload(path: Path):
+    """Gültig, wenn die Slot-Datei existiert und nummerierte Einträge enthält."""
+    if not path.exists():
+        return None
+    text = path.read_text(encoding="utf-8")
+    return text if _parse_auswahl(text) else None
+
+
+def _auswahl_payload(path: Path):
+    if not path.exists():
+        return None
+    text = path.read_text(encoding="utf-8")
+    entries = _parse_auswahl(text)
+    return (text, entries) if entries else None
+
+
+def _auswahl_check_schema(data):
+    """{"nachtraege": [...], "streichen": [...]} — None bei Schema-Verstoß."""
+    if not isinstance(data, dict):
+        return None
+    nach = data.get("nachtraege", [])
+    streich = data.get("streichen", [])
+    if not isinstance(nach, list) or not isinstance(streich, list):
+        return None
+    if not all(isinstance(x, str) for x in [*nach, *streich]):
+        return None
+    return {"nachtraege": nach, "streichen": streich}
+
+
+async def generate_bausteine(topic: str, instructions: str = "", provider: str = DEFAULT_PROVIDER) -> None:
+    if topic in _bausteine_progress:
+        return
+    _bausteine_progress[topic] = "Wartend…"
+    _bausteine_errors.pop(topic, None)
+
+    files = _bausteine_files(topic)
+    final_path = files["final"]
+    project = project_dir(topic) if project_dir(topic).is_dir() else None
+
+    def set_p(msg: str, step: int | None = None) -> None:
+        _bausteine_progress[topic] = msg
+        if step is not None:
+            _bausteine_step[topic] = step
+
+    def is_cancelled() -> bool:
+        return topic in _bausteine_cancelled
+
+    def abgebrochen() -> None:
+        _bausteine_errors[topic] = "Abgebrochen — Fortschritt bleibt erhalten"
+
+    ctx = GenContext(topic=topic, provider=provider, is_cancelled=is_cancelled)
+
+    try:
+        async with _semaphore:
+            files["arbeit"].mkdir(parents=True, exist_ok=True)
+            if project:
+                await asyncio.to_thread(_pdfs_konvertieren, project)
+            # „Neu erstellen": fertige Bausteine → kompletter Frischstart.
+            # Sonst sind Slot-Dateien Reste eines Abbruchs/Fehlers → Resume.
+            if final_path.exists():
+                for p_alt in _alle_slot_dateien(files):
+                    p_alt.unlink(missing_ok=True)
+
+            # Schritt 1: 4 Recherche-Agenten, 3 gültige nötig — vorhandene Slot-Dateien zählen
+            recherchen: list[str] = []
+            offen = []
+            for i, path in enumerate(files["recherche"], 1):
+                text = _file_payload(path)
+                if text is not None and len(recherchen) < 3:
+                    recherchen.append(text)
+                else:
+                    offen.append((i, path))
+            vorhanden = len(recherchen)
+            set_p(f"Recherche läuft ({vorhanden}/3 gültig)…", step=0)
+            if vorhanden < 3:
+                caps = "files" if project else "full"
+                slots = [
+                    {
+                        "key": f"bausteine-{topic}-recherche-{i}",
+                        "prompt": _build_recherche_prompt(topic, path, instructions, project),
+                        "role": "quick", "capabilities": caps,
+                        "payload": (lambda result, p=path: _file_payload(p)),
+                    }
+                    for i, path in offen
+                ]
+                neue = await _race(
+                    topic, "Recherche", slots, 3 - vorhanden, _timeout("recherche"), provider,
+                    on_update=lambda c: set_p(f"Recherche läuft ({vorhanden + c}/3 gültig)…"),
+                    cancelled=is_cancelled,
+                )
+                if is_cancelled():
+                    abgebrochen()
+                    return
+                if neue is None:
+                    _bausteine_errors[topic] = "Recherche fehlgeschlagen (Quorum nicht erreicht)"
+                    return
+                recherchen += neue
+
+            # Schritt 2: 2 Auswahl-Agenten, der erste gewinnt — vorhandene gültige Datei wird übernommen
+            n_est = max(len(_parse_auswahl(t)) for t in recherchen)
+            bestehende = next((res for p in files["auswahl"] if (res := _auswahl_payload(p)) is not None), None)
+            if bestehende is not None:
+                flat, entries = bestehende
+            else:
+                set_p("Konsolidiere Recherche…", step=1)
+                results_block = "\n\n".join(f"### Recherche {i}\n\n{text}" for i, text in enumerate(recherchen, 1))
+                slots = [
+                    {
+                        "key": f"bausteine-{topic}-auswahl-{i}",
+                        "prompt": _prompt("Bausteine-Auswahl", topic=topic, results=results_block, out_path=path),
+                        "role": "fast", "capabilities": "files",
+                        "payload": (lambda result, p=path: _auswahl_payload(p)),
+                    }
+                    for i, path in enumerate(files["auswahl"], 1)
+                ]
+                auswahl = await _race(topic, "Auswahl", slots, 1, _timeout("auswahl", n_est), provider, cancelled=is_cancelled)
+                if is_cancelled():
+                    abgebrochen()
+                    return
+                if auswahl is None:
+                    _bausteine_errors[topic] = "Auswahl fehlgeschlagen (kein gültiges Ergebnis)"
+                    return
+                flat, entries = auswahl[0]
+
+            # Schritt 2b: Auswahl-Prüfung gegen die Recherche-Titel (JSON, nicht fatal)
+            set_p("Prüfe Auswahl…", step=2)
+            check_path = files["auswahl_check"]
+            patch = _auswahl_check_schema(_json_datei(check_path))
+            if patch is None:
+                check_path.unlink(missing_ok=True)
+                titel_listen = "\n\n".join(
+                    f"### Recherche {i}\n" + "\n".join(f"- {_titel(t)}" for t in _parse_auswahl(text).values())
+                    for i, text in enumerate(recherchen, 1)
+                )
+                status, check = await run_single_slot(
+                    ctx, "Auswahl-Check",
+                    key=f"bausteine-{topic}-auswahlcheck-1",
+                    prompt=_prompt("Bausteine-Auswahl-Check", topic=topic, results=titel_listen, auswahl=flat, out_path=check_path),
+                    role="fast", capabilities="files",
+                    payload=lambda result: _auswahl_check_schema(_json_datei(check_path)),
+                    timeout=_timeout("auswahl_check", len(entries)),
+                )
+                if status == CANCELLED:
+                    abgebrochen()
+                    return
+                if status == FAILED:
+                    _log(topic, "Auswahl-Check fehlgeschlagen — fahre ohne Korrekturen fort")
+                else:
+                    patch = check
+            if patch is not None and (patch["streichen"] or patch["nachtraege"]):
+                idx = _titel_index(entries)
+                weg = {num for t in patch["streichen"] if (num := _titel_aufloesen(idx, t)) is not None}
+                if weg:
+                    _log(topic, f"Auswahl-Check streicht Duplikate: {sorted(weg)}")
+                    entries = {n: t for n, t in entries.items() if n not in weg}
+                if patch["nachtraege"]:
+                    _log(topic, f"Auswahl-Check ergänzt {len(patch['nachtraege'])} Bausteine")
+                texts = [t for _, t in sorted(entries.items())] + list(patch["nachtraege"])
+                entries = {i: t for i, t in enumerate(texts, 1)}
+
+            # Schritt 4 (nur Projekte): Themenfeld-Ergänzung — Skript/Projekt ist ein Ausschnitt,
+            # ein Web-Agent ergänzt kanonisch fehlende Bausteine, markiert mit [Ergänzung].
+            if project:
+                set_p("Ergänze Themenfeld…", step=3)
+                erg_path = files["ergaenzung"]
+                ergaenzungen = _ergaenzung_schema(_json_datei(erg_path))
+                if ergaenzungen is None:
+                    erg_path.unlink(missing_ok=True)
+                    status, ergaenzungen = await run_single_slot(
+                        ctx, "Ergänzung",
+                        key=f"bausteine-{topic}-ergaenzung-1",
+                        prompt=_prompt(
+                            "Bausteine-Ergaenzung",
+                            topic=topic, bausteine="\n".join(f"- {t}" for t in entries.values()),
+                            out_path=erg_path, extra=_extra(instructions),
+                        ),
+                        role="quick", capabilities="full",
+                        payload=lambda result: _ergaenzung_schema(_json_datei(erg_path)),
+                        timeout=_timeout("ergaenzung"),
+                    )
+                    if status == CANCELLED:
+                        abgebrochen()
+                        return
+                    if status == FAILED:
+                        _bausteine_errors[topic] = "Ergänzung fehlgeschlagen (kein gültiges Ergebnis)"
+                        return
+                idx = _titel_index(entries)
+                neu = [(t, b) for t, b in ergaenzungen if _titel_aufloesen(idx, t) is None]
+                if neu:
+                    _log(topic, f"Ergänzung: {len(neu)} Baustein(e) aus dem Themenfeld ergänzt")
+                    start = max(entries, default=0) + 1
+                    for off, (t, b) in enumerate(neu):
+                        entries[start + off] = f"{t} — {b} [Ergänzung]"
+
+            # Titel eindeutig machen und unsortiertes Inventar schreiben
+            entries = _eindeutige_titel(entries)
+            atomic_write_text(final_path, "\n".join(f"{i}. {t}" for i, t in entries.items()) + "\n")
+    except Exception as e:
+        log.exception("[%s] Bausteine-Generierung fehlgeschlagen", topic)
+        _bausteine_errors[topic] = str(e)[:2000]
+    finally:
+        # Kein Datei-Cleanup: Zwischendateien bleiben für Resume bzw. Nachvollziehbarkeit.
+        _bausteine_progress.pop(topic, None)
+        _bausteine_step.pop(topic, None)
+        _bausteine_cancelled.discard(topic)

backend/config.py

@@ -9,6 +9,12 @@ PROJECTS_DIR = PROJECT_ROOT / "projects"
 
 MAX_CONCURRENT_GENERATIONS = 10
 
+# 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 = 12
+MAX_CONCURRENT_INTERACTIVE = 4
+
 # 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.
 TIMEOUTS = {

backend/database.py

@@ -42,8 +42,6 @@ CREATE TABLE IF NOT EXISTS elements (
     description TEXT NOT NULL DEFAULT '',
     examples TEXT NOT NULL DEFAULT '[]',
     hints TEXT NOT NULL DEFAULT '[]',
-    aufgabe TEXT NOT NULL DEFAULT '',
-    loesung TEXT NOT NULL DEFAULT '',
     created_at TEXT NOT NULL,
     updated_at TEXT NOT NULL
 )
@@ -62,6 +60,9 @@ async def get_db() -> aiosqlite.Connection:
 
 async def init_db():
     db = await get_db()
+    # WAL übersteht Crashes deutlich besser; busy_timeout fängt kurze Locks ab.
+    await db.execute("PRAGMA journal_mode=WAL")
+    await db.execute("PRAGMA busy_timeout=5000")
     await db.execute(CREATE_GUIDES)
     await db.execute(CREATE_PROGRESS)
     await db.execute(CREATE_TOPICS)
@@ -70,11 +71,6 @@ async def init_db():
         await db.execute("ALTER TABLE guides ADD COLUMN step INTEGER")
     except aiosqlite.OperationalError:
         pass
-    for col in ("aufgabe", "loesung"):  # Migration für Elemente ohne Aufgabe/Lösung
-        try:
-            await db.execute(f"ALTER TABLE elements ADD COLUMN {col} TEXT NOT NULL DEFAULT ''")
-        except aiosqlite.OperationalError:
-            pass
     await db.execute(
         "UPDATE guides SET status = 'error', progress = NULL, error_msg = 'Server-Neustart' "
         "WHERE status IN ('queued', 'generating')"
@@ -173,8 +169,8 @@ def _element_row(row, cursor) -> dict:
 async def create_element(element: dict) -> dict:
     db = await get_db()
     await db.execute(
-        """INSERT INTO elements (id, topic, title, description, examples, hints, aufgabe, loesung, created_at, updated_at)
+        """INSERT INTO elements (id, topic, title, description, examples, hints, created_at, updated_at)
-           VALUES (:id, :topic, :title, :description, :examples, :hints, :aufgabe, :loesung, :created_at, :updated_at)""",
+           VALUES (:id, :topic, :title, :description, :examples, :hints, :created_at, :updated_at)""",
         {**element, "examples": json.dumps(element["examples"], ensure_ascii=False),
          "hints": json.dumps(element["hints"], ensure_ascii=False)},
     )
@@ -220,6 +216,17 @@ async def delete_element(element_id: str) -> bool:
 
 # --- Kapitel-Fortschritt ---
 
+async def list_progress_all() -> dict[str, set[str]]:
+    """Kompletter Kapitel-Fortschritt in einem Query: guide_id → Kapitel-Titel."""
+    db = await get_db()
+    cursor = await db.execute("SELECT guide_id, chapter FROM guide_progress")
+    rows = await cursor.fetchall()
+    out: dict[str, set[str]] = {}
+    for guide_id, chapter in rows:
+        out.setdefault(guide_id, set()).add(chapter)
+    return out
+
+
 async def list_progress(guide_id: str) -> list[str]:
     db = await get_db()
     cursor = await db.execute(

backend/elements.py

@@ -0,0 +1,258 @@
+"""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 ("FullGuide", "Guide", "MiniGuide", "OnePager"):
+        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) -> dict:
+    """Erstellt Element-Felder per KI. Fallback: nur Titel aus dem Stichwort."""
+    fallback = {"title": hint.strip() or "Neues Element", "description": "", "examples": [], "hints": []}
+    try:
+        prompt = _prompt(
+            "Element-Create",
+            topic=topic, hint=hint.strip() or "(keins — wähle selbst ein Kernkonzept)",
+            context=_topic_context(topic),
+        )
+        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/fsutil.py

@@ -0,0 +1,22 @@
+"""Atomare Datei-Writes: erst .tmp im selben Verzeichnis, dann 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.
+"""
+
+import json
+import os
+from pathlib import Path
+
+
+def atomic_write_text(path: Path, text: str) -> None:
+    tmp = path.with_name(path.name + ".tmp")
+    with open(tmp, "w", encoding="utf-8") as f:
+        f.write(text)
+        f.flush()
+        os.fsync(f.fileno())
+    os.replace(tmp, path)
+
+
+def atomic_write_json(path: Path, obj, **dumps_kwargs) -> None:
+    atomic_write_text(path, json.dumps(obj, ensure_ascii=False, **dumps_kwargs))

backend/guide.py

@@ -0,0 +1,492 @@
+"""Guide-Generierung: 6 Schritte mit Prüfung nach jeder Phase (OnePager hat einen eigenen Weg).
+
+Prüf-Agenten notieren nur Probleme; das Anpassen übernimmt der jeweilige Erzeuger-Typ.
+Schritt-Dateien bleiben liegen → Abbruch erhält Fortschritt, ▶ setzt am offenen Schritt fort.
+"""
+
+import asyncio
+import json
+import logging
+import math
+from datetime import datetime, timezone
+from pathlib import Path
+
+from agents import run_agent
+from bausteine import _pdfs_konvertieren
+from config import DEFAULT_PROVIDER, FORMAT_ANTEIL, TEMPLATES_DIR
+from database import list_guides, update_guide
+from fsutil import atomic_write_json, atomic_write_text
+from jsonio import read_json_file as _json_datei
+from onepager import _generate_onepager
+from paths import bausteine_path, guide_content_path, project_dir
+from pipeline import (
+    CANCELLED, FAILED, GenContext, _check_then_fix, _claude_error, _extra,
+    _fail, _gather_error, _log, _prompt, _race, _semaphore, _set_progress,
+    _set_step, _timeout, clear_guide_cancelled, is_guide_cancelled,
+    run_single_slot,
+)
+from textkit import (
+    _eindeutige_titel, _lade_bausteine, _parse_fragment, _split_chunks,
+    _titel, _titel_aufloesen, _titel_index, _zuteilung_text,
+)
+
+log = logging.getLogger("creator.guide")
+
+GUIDE_STEPS = ("Auswahl", "Auswahl-Prüfung", "Gliederung", "Gliederungs-Prüfung", "Schreiben", "Lese-Prüfung")
+
+# Writer skalieren mit der Section-Zahl: 1 Writer je ~30 Sections (gedeckelt).
+# Kleine Pakete vermeiden Lazy-Output bei langen Listen und begrenzen den Schaden
+# eines fehlgeschlagenen Writers.
+WRITER_SECTIONS = 30
+WRITER_MAX = 20
+
+
+def _guide_files(content_path: Path) -> dict:
+    d, stem = content_path.parent, content_path.stem
+    return {
+        "auswahl": d / f"{stem}.auswahl.json",
+        "auswahl_check": d / f"{stem}.auswahl-check.json",
+        "gliederung": d / f"{stem}.gliederung.json",
+        "gliederung_check": d / f"{stem}.gliederung-check.json",
+        # chunk-/lese-check-/fix-Dateien sind dynamisch: {stem}.chunk-i.md usw.
+    }
+
+
+def guide_slot_dateien(content_path: Path) -> list[Path]:
+    """Alle Schritt-Dateien eines Guides (für den Frischstart)."""
+    return [p for p in content_path.parent.glob(f"{content_path.stem}.*") if p != content_path]
+
+
+def _resolve_auswahl(data, entries: dict[int, str], k_min: int, k_max: int) -> list[int] | None:
+    """{"bausteine": [Titel]} → Nummern; None bei Schema-Verstoß/Drift/falschem Umfang."""
+    if not isinstance(data, dict) or not isinstance(data.get("bausteine"), list):
+        return None
+    idx = _titel_index(entries)
+    nums: list[int] = []
+    seen: set[int] = set()
+    total = unknown = 0
+    for t in data["bausteine"]:
+        total += 1
+        num = _titel_aufloesen(idx, t) if isinstance(t, str) else None
+        if num is None:
+            unknown += 1
+        elif num not in seen:
+            seen.add(num)
+            nums.append(num)
+    if total == 0 or (total - unknown) / total < 0.85:
+        return None
+    if len(nums) < 0.9 * k_min or len(nums) > 1.1 * k_max:
+        return None
+    return nums
+
+
+def _lese_probleme_schema(data):
+    """{"ok": true} → [] · {"probleme": [{"section", "problem"}]} → Liste · sonst None."""
+    if not isinstance(data, dict):
+        return None
+    if data.get("ok") is True:
+        return []
+    p = data.get("probleme")
+    if not isinstance(p, list) or not p:
+        return None
+    out = []
+    for x in p:
+        if not isinstance(x, dict) or not isinstance(x.get("section"), str) or not isinstance(x.get("problem"), str):
+            return None
+        out.append({"section": x["section"].strip(), "problem": x["problem"].strip()})
+    return out or None
+
+
+def _resolve_gliederung(data, entries: dict[int, str], soll_min: int, soll_max: int) -> list[dict] | None:
+    """{"kapitel": [{"titel", "bausteine": [Titel]}]} → [{"title", "nums"}].
+
+    `soll_min`/`soll_max` = erlaubte Spanne gewählter Bausteine (mit kleiner Toleranz).
+    """
+    if not isinstance(data, dict) or not isinstance(data.get("kapitel"), list):
+        return None
+    idx = _titel_index(entries)
+    chapters: list[dict] = []
+    seen: set[int] = set()
+    total = unknown = 0
+    for ch in data["kapitel"]:
+        if not isinstance(ch, dict) or not isinstance(ch.get("bausteine"), list):
+            return None
+        nums = []
+        for t in ch["bausteine"]:
+            total += 1
+            num = _titel_aufloesen(idx, t) if isinstance(t, str) else None
+            if num is None:
+                unknown += 1
+            elif num not in seen:
+                nums.append(num)
+                seen.add(num)
+        if nums:
+            chapters.append({"title": str(ch.get("titel", "")).strip() or "Kapitel", "nums": nums})
+    if not chapters or total == 0:
+        return None
+    if (total - unknown) / total < 0.85:
+        return None
+    if len(seen) < 0.9 * soll_min or len(seen) > 1.1 * soll_max:
+        return None
+    return chapters
+
+
+async def _generate_sections(
+    guide_id: str, topic: str, format_name: str, entries: dict[int, str],
+    facts: str, instructions: str, provider: str,
+    content_path: Path,
+) -> list[dict] | None:
+    def is_cancelled() -> bool:
+        return is_guide_cancelled(guide_id)
+
+    ctx = GenContext(topic=topic, provider=provider, is_cancelled=is_cancelled, guide_id=guide_id)
+    spec = (TEMPLATES_DIR / "Format" / "Section.md").read_text(encoding="utf-8")
+    files = _guide_files(content_path)
+    bausteine_liste = "\n".join(f"- {t}" for t in entries.values())
+    n = len(entries)
+    anteil_min, anteil_max, minimum, zweck = FORMAT_ANTEIL[format_name]
+    k_min = min(n, max(minimum, math.ceil(anteil_min * n)))
+    k_max = min(n, max(k_min, math.floor(anteil_max * n)))
+    auswahl_auftrag = (
+        f"Wähle MINDESTENS {k_min} und HÖCHSTENS {k_max} der Bausteine und baue daraus {zweck}. "
+        "Wähle, was diesem Zweck dient — lass weg, was dafür nicht nötig ist."
+    )
+
+    # Schritt 1: Auswahl — vorhandene gültige Datei wird übernommen (Resume)
+    auswahl = _resolve_auswahl(_json_datei(files["auswahl"]), entries, k_min, k_max)
+    if auswahl is None:
+        await _set_step(guide_id, 0, "Wähle Bausteine…")
+        files["auswahl"].unlink(missing_ok=True)
+        status, auswahl = await run_single_slot(
+            ctx, "Guide-Auswahl",
+            key=f"{guide_id}-auswahl",
+            prompt=_prompt(
+                "Guide-Auswahl",
+                topic=topic, format_name=format_name, bausteine=bausteine_liste,
+                auswahl_auftrag=auswahl_auftrag, out_path=files["auswahl"], extra=_extra(instructions),
+            ),
+            role="guide", capabilities="files",
+            payload=lambda result: _resolve_auswahl(_json_datei(files["auswahl"]), entries, k_min, k_max),
+            timeout=_timeout("guide_auswahl", n),
+        )
+        if status == CANCELLED:
+            return None
+        if status == FAILED:
+            await _fail(guide_id, "Auswahl fehlgeschlagen")
+            return None
+
+    def auswahl_titel() -> str:
+        return "\n".join(f"- {_titel(entries[num])}" for num in auswahl)
+
+    def auswahl_json() -> str:
+        return json.dumps({"bausteine": [_titel(entries[num]) for num in auswahl]}, ensure_ascii=False)
+
+    # Schritt 2: Auswahl-Prüfung — notiert Probleme; Anpassung macht ein Auswahl-Agent
+    status, fixed = await _check_then_fix(
+        ctx, name="Auswahl", step=1,
+        check_key=f"{guide_id}-auswahl-check",
+        check_prompt=_prompt(
+            "Guide-Auswahl-Check",
+            topic=topic, format_name=format_name, auswahl_auftrag=auswahl_auftrag,
+            bausteine=bausteine_liste, auswahl=auswahl_titel(),
+            out_path=files["auswahl_check"], extra=_extra(instructions),
+        ),
+        check_path=files["auswahl_check"], check_timeout=_timeout("guide_check", len(auswahl)),
+        fix_key=f"{guide_id}-auswahl-fix",
+        build_fix_prompt=lambda probleme: _prompt(
+            "Guide-Auswahl-Fix",
+            topic=topic, format_name=format_name, auswahl_auftrag=auswahl_auftrag,
+            bausteine=bausteine_liste, auswahl=auswahl_titel(),
+            probleme="\n".join(f"- {p}" for p in probleme),
+            out_path=files["auswahl"], extra=_extra(instructions),
+        ),
+        fix_payload=lambda result: _resolve_auswahl(_json_datei(files["auswahl"]), entries, k_min, k_max),
+        fix_timeout=_timeout("guide_auswahl", n), fix_role="guide",
+        on_fix_invalid=lambda: atomic_write_text(files["auswahl"], auswahl_json()),
+    )
+    if status == CANCELLED:
+        return None
+    if status == FAILED:
+        await _fail(guide_id, "Auswahl-Prüfung fehlgeschlagen")
+        return None
+    if fixed is not None:
+        auswahl = fixed
+
+    sel_entries = {num: entries[num] for num in auswahl}
+    soll = len(sel_entries)
+    sel_liste = "\n".join(f"- {t}" for t in sel_entries.values())
+
+    # Schritt 3: Gliederung der festen Auswahl
+    plan = _resolve_gliederung(_json_datei(files["gliederung"]), sel_entries, soll, soll)
+    if plan is None:
+        await _set_step(guide_id, 2, "Plane Gliederung…")
+        files["gliederung"].unlink(missing_ok=True)
+        status, plan = await run_single_slot(
+            ctx, "Gliederung",
+            key=f"{guide_id}-gliederung",
+            prompt=_prompt(
+                "Guide-Gliederung",
+                topic=topic, format_name=format_name, bausteine=sel_liste,
+                out_path=files["gliederung"], extra=_extra(instructions),
+            ),
+            role="guide", capabilities="files",
+            payload=lambda result: _resolve_gliederung(_json_datei(files["gliederung"]), sel_entries, soll, soll),
+            timeout=_timeout("plan", soll),
+        )
+        if status == CANCELLED:
+            return None
+        if status == FAILED:
+            await _fail(guide_id, "Gliederung fehlgeschlagen")
+            return None
+
+    def gliederung_text() -> str:
+        return "\n".join(_zuteilung_text([ch], {num: _titel(entries[num]) for num in ch["nums"]}) for ch in plan)
+
+    def gliederung_json() -> str:
+        return json.dumps(
+            {"kapitel": [{"titel": ch["title"], "bausteine": [_titel(entries[num]) for num in ch["nums"]]} for ch in plan]},
+            ensure_ascii=False,
+        )
+
+    # Schritt 4: Gliederungs-Prüfung
+    status, fixed = await _check_then_fix(
+        ctx, name="Gliederung", step=3,
+        check_key=f"{guide_id}-gliederung-check",
+        check_prompt=_prompt(
+            "Guide-Gliederung-Check",
+            topic=topic, format_name=format_name, zweck=zweck,
+            auswahl=auswahl_titel(), gliederung=gliederung_text(),
+            out_path=files["gliederung_check"], extra=_extra(instructions),
+        ),
+        check_path=files["gliederung_check"], check_timeout=_timeout("guide_check", soll),
+        fix_key=f"{guide_id}-gliederung-fix",
+        build_fix_prompt=lambda probleme: _prompt(
+            "Guide-Gliederung-Fix",
+            topic=topic, format_name=format_name,
+            auswahl=auswahl_titel(), gliederung=gliederung_text(),
+            probleme="\n".join(f"- {p}" for p in probleme),
+            out_path=files["gliederung"], extra=_extra(instructions),
+        ),
+        fix_payload=lambda result: _resolve_gliederung(_json_datei(files["gliederung"]), sel_entries, soll, soll),
+        fix_timeout=_timeout("plan", soll), fix_role="guide",
+        on_fix_invalid=lambda: atomic_write_text(files["gliederung"], gliederung_json()),
+    )
+    if status == CANCELLED:
+        return None
+    if status == FAILED:
+        await _fail(guide_id, "Gliederungs-Prüfung fehlgeschlagen")
+        return None
+    if fixed is not None:
+        plan = fixed
+
+    # Schritt 5: Schreiben — vorhandene Chunk-Dateien werden übernommen (Resume)
+    total_sections = sum(len(c["nums"]) for c in plan)
+    chunks = _split_chunks(plan, min(WRITER_MAX, max(1, math.ceil(total_sections / WRITER_SECTIONS))))
+    zuteilungen = [_zuteilung_text(chunk, entries) for chunk in chunks]
+    chunk_sizes = [sum(len(c["nums"]) for c in chunk) for chunk in chunks]
+    writer_count = len(zuteilungen)
+    paths = [content_path.parent / f"{content_path.stem}.chunk-{i}.md" for i in range(1, writer_count + 1)]
+    offen = [i for i, p in enumerate(paths) if not p.exists()]
+    if offen:
+        await _set_step(guide_id, 4, f"Schreibe Sections ({writer_count} Writer)…" if writer_count > 1 else "Schreibe Sections…")
+        results = await asyncio.gather(*[
+            run_agent(
+                f"{guide_id}-w{i + 1}",
+                _prompt(
+                    "Guide-Writer",
+                    topic=topic, format_name=format_name, zuteilung=zuteilungen[i],
+                    facts=facts, spec=spec, out_path=paths[i], extra=_extra(instructions),
+                ),
+                _timeout("writer", chunk_sizes[i]), provider=provider, role="guide", capabilities="full",
+            )
+            for i in offen
+        ], return_exceptions=True)
+        if is_cancelled():
+            return None
+        for i, r in zip(offen, results):
+            if isinstance(r, BaseException):
+                _log(topic, f"Writer {i + 1}: {type(r).__name__}: {r}")
+            elif r[0] != 0:
+                _log(topic, f"Writer {i + 1}: {_claude_error('Fehler', *r)}")
+            elif not paths[i].exists():
+                _log(topic, f"Writer {i + 1}: keine Ausgabedatei erstellt")
+        if not any(p.exists() for p in paths):
+            await _fail(guide_id, _gather_error("Writer-Fehler", list(results)))
+            return None
+
+    idx = _titel_index(entries)
+    by_num: dict[int, dict] = {}
+    for p in paths:
+        if not p.exists():
+            continue
+        for sec in _parse_fragment(p.read_text(encoding="utf-8")):
+            num = _titel_aufloesen(idx, sec["titel"])
+            if num is None:
+                _log(topic, f"Writer lieferte unbekannte Section '{sec['titel'][:40]}' (ignoriert)")
+            elif num not in by_num:
+                by_num[num] = sec
+    if not by_num:
+        await _fail(guide_id, "Keine Sections in der Writer-Ausgabe gefunden")
+        return None
+
+    # Schritt 6: Lese-Prüfung pro Writer-Paket — Fix beauftragt Writer nur mit beanstandeten Sections
+    chunk_nums = [[num for ch in chunk for num in ch["nums"] if num in by_num] for chunk in chunks]
+    check_paths = [content_path.parent / f"{content_path.stem}.lese-check-{i}.json" for i in range(1, writer_count + 1)]
+    offen_checks = [i for i, p in enumerate(check_paths) if _lese_probleme_schema(_json_datei(p)) is None and chunk_nums[i]]
+    if offen_checks:
+        await _set_step(guide_id, 5, f"Prüfe Lesbarkeit ({len(offen_checks)} Prüfer)…" if len(offen_checks) > 1 else "Prüfe Lesbarkeit…")
+
+        def sections_text(nums: list[int]) -> str:
+            return "\n\n".join(f"SECTION: {_titel(entries[num])}\n{by_num[num]['md']}" for num in nums)
+
+        slots = [{
+            "key": f"{guide_id}-lese-check-{i + 1}",
+            "prompt": _prompt(
+                "Guide-Lese-Check",
+                topic=topic, format_name=format_name, spec=spec,
+                sections=sections_text(chunk_nums[i]),
+                out_path=check_paths[i], extra=_extra(instructions),
+            ),
+            "role": "fast", "capabilities": "files",
+            "payload": (lambda result, p=check_paths[i]: _lese_probleme_schema(_json_datei(p))),
+        } for i in offen_checks]
+        res = await _race(topic, "Lese-Prüfung", slots, len(slots), _timeout("lese_check", max(chunk_sizes)), provider, cancelled=is_cancelled)
+        if is_cancelled():
+            return None
+        if res is None:
+            await _fail(guide_id, "Lese-Prüfung fehlgeschlagen")
+            return None
+
+    probleme_by_num: dict[int, str] = {}
+    for p in check_paths:
+        for item in (_lese_probleme_schema(_json_datei(p)) or []):
+            num = _titel_aufloesen(idx, item["section"])
+            if num in by_num and num not in probleme_by_num:
+                probleme_by_num[num] = item["problem"]
+
+    if probleme_by_num:
+        _log(topic, f"Lese-Prüfung: {len(probleme_by_num)} Section(s) beanstandet")
+        await _set_step(guide_id, 5, f"Überarbeite {len(probleme_by_num)} Section(s)…")
+        fix_chunks = [[num for num in nums if num in probleme_by_num] for nums in chunk_nums]
+        fix_offen = [i for i, nums in enumerate(fix_chunks) if nums]
+        fix_paths = [content_path.parent / f"{content_path.stem}.fix-{i + 1}.md" for i in range(writer_count)]
+
+        def auftraege_text(nums: list[int]) -> str:
+            return "\n\n".join(
+                f"SECTION: {_titel(entries[num])}\nPROBLEM: {probleme_by_num[num]}\nAKTUELLER INHALT:\n{by_num[num]['md']}"
+                for num in nums
+            )
+
+        results = await asyncio.gather(*[
+            run_agent(
+                f"{guide_id}-fix-w{i + 1}",
+                _prompt(
+                    "Guide-Sections-Fix",
+                    topic=topic, format_name=format_name, facts=facts, spec=spec,
+                    auftraege=auftraege_text(fix_chunks[i]),
+                    out_path=fix_paths[i], extra=_extra(instructions),
+                ),
+                _timeout("writer", len(fix_chunks[i])), provider=provider, role="guide", capabilities="full",
+            )
+            for i in fix_offen
+        ], return_exceptions=True)
+        if is_cancelled():
+            return None
+        for i, r in zip(fix_offen, results):
+            if isinstance(r, BaseException) or (not isinstance(r, BaseException) and r[0] != 0):
+                _log(topic, f"Sections-Fix {i + 1} fehlgeschlagen — Original bleibt")
+        ersetzt = 0
+        for i in fix_offen:
+            if not fix_paths[i].exists():
+                continue
+            for sec in _parse_fragment(fix_paths[i].read_text(encoding="utf-8")):
+                num = _titel_aufloesen(idx, sec["titel"])
+                if num in probleme_by_num and sec["md"].strip():
+                    by_num[num] = sec
+                    ersetzt += 1
+        _log(topic, f"Lese-Prüfung: {ersetzt} Section(s) überarbeitet")
+
+    await _set_progress(guide_id, "Setze zusammen…")
+    chapters: list[dict] = []
+    for ch in plan:
+        sections = [
+            {"num": num, "title": _titel(entries[num]), "md": by_num[num]["md"]}
+            for num in ch["nums"] if num in by_num
+        ]
+        if sections:
+            chapters.append({"title": ch["title"], "sections": sections})
+    geplant = {num for ch in plan for num in ch["nums"]}
+    missing = sorted(geplant - set(by_num))
+    if missing:
+        _log(topic, f"Sections fehlen in der Writer-Ausgabe: {[_titel(entries[n]) for n in missing]}")
+    if not chapters:
+        await _fail(guide_id, "Keine Sections in der Writer-Ausgabe gefunden")
+        return None
+    return chapters
+
+
+async def reconcile_guides() -> None:
+    """DB↔Dateisystem abgleichen: status=done ohne Content-Datei → error.
+
+    Läuft beim Server-Start (nach init_db) — fängt Crashes zwischen
+    Datei-Write und Status-Update ab.
+    """
+    for g in await list_guides():
+        if g["status"] == "done" and not guide_content_path(g["topic"], g["format"]).exists():
+            log.warning("[%s] Guide %s: done ohne Content-Datei — auf error gesetzt", g["topic"], g["id"])
+            now = datetime.now(timezone.utc).isoformat()
+            await update_guide(g["id"], status="error", error_msg="Inhalt fehlt — neu generieren", updated_at=now)
+
+
+async def generate_guide(guide_id: str, topic: str, format_name: str, instructions: str = "", provider: str = DEFAULT_PROVIDER) -> None:
+    async with _semaphore:
+        now = datetime.now(timezone.utc).isoformat()
+        await update_guide(guide_id, status="generating", progress="Starte…", updated_at=now)
+
+        content_path = guide_content_path(topic, format_name)
+        content_path.parent.mkdir(parents=True, exist_ok=True)
+        project = project_dir(topic) if project_dir(topic).is_dir() else None
+
+        try:
+            if is_guide_cancelled(guide_id):
+                return
+
+            if project:
+                await asyncio.to_thread(_pdfs_konvertieren, project)
+
+            # „Neu erstellen": fertiger Guide → kompletter Frischstart.
+            # Sonst sind Schritt-Dateien Reste eines Abbruchs/Fehlers → Resume.
+            if content_path.exists():
+                for p_alt in guide_slot_dateien(content_path):
+                    p_alt.unlink(missing_ok=True)
+
+            if format_name == "OnePager":
+                chapters = await _generate_onepager(guide_id, topic, instructions, provider, project, content_path)
+            else:
+                alle = _lade_bausteine(bausteine_path(topic).read_text(encoding="utf-8"))
+                if not alle:
+                    await _fail(guide_id, "Keine Bausteine gefunden")
+                    return
+                entries = _eindeutige_titel(alle)
+                facts = _prompt("Guide-Fakten-Projekt", project=project) if project else _prompt("Guide-Fakten-Thema")
+                chapters = await _generate_sections(
+                    guide_id, topic, format_name, entries,
+                    facts, instructions, provider, content_path,
+                )
+            if chapters is None or is_guide_cancelled(guide_id):
+                return
+
+            atomic_write_json(content_path, {"topic": topic, "format": format_name, "chapters": chapters}, indent=1)
+
+            now = datetime.now(timezone.utc).isoformat()
+            await update_guide(guide_id, status="done", progress=None, step=None, updated_at=now)
+
+        except asyncio.TimeoutError:
+            await _fail(guide_id, "Timeout bei der Generierung")
+        except FileNotFoundError:
+            await _fail(guide_id, "Bausteine fehlen")
+        except Exception as e:
+            log.exception("[%s] Guide-Generierung fehlgeschlagen (%s)", topic, guide_id)
+            await _fail(guide_id, str(e)[:2000])
+        finally:
+            clear_guide_cancelled(guide_id)

backend/jsonio.py

@@ -0,0 +1,49 @@
+"""Toleranter JSON-Parser für KI-Output — als Text oder aus Dateien.
+
+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.
+"""
+
+import json
+import logging
+import re
+from pathlib import Path
+
+log = logging.getLogger("creator.jsonio")
+
+
+def parse_json_text(text: str):
+    """Parst JSON aus KI-Output; None bei nicht reparierbarem Input."""
+    text = re.sub(r"^```(?:json)?\s*|\s*```$", "", (text or "").strip())
+    start, end = text.find("{"), text.rfind("}")
+    if start == -1 or end <= start:
+        return None
+    candidate = text[start:end + 1]
+    for _ in range(20):
+        try:
+            return json.loads(candidate)
+        except json.JSONDecodeError as e:
+            if not e.msg.startswith(("Expecting ',' delimiter", "Expecting ':' delimiter")):
+                return None
+            q = candidate.rfind('"', 0, e.pos)
+            if q <= 0:
+                return None
+            candidate = candidate[:q] + '\\"' + candidate[q + 1:]
+        except Exception:
+            return None
+    return None
+
+
+def read_json_file(path: Path):
+    """Liest eine JSON-Datei mit derselben Toleranz; None bei fehlend/ungültig."""
+    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)
+        return None
+    if data is None:
+        log.debug("JSON-Datei ungültig: %s", path)
+    return data

backend/logsetup.py

@@ -0,0 +1,11 @@
+"""Zentrales Logging-Setup — einmal in main.py aufrufen, bevor die App entsteht."""
+
+import logging
+import os
+
+
+def setup_logging() -> None:
+    logging.basicConfig(
+        level=os.environ.get("LOG_LEVEL", "INFO").upper(),
+        format="%(asctime)s %(levelname)s %(name)s %(message)s",
+    )

backend/main.py

@@ -3,8 +3,13 @@ from contextlib import asynccontextmanager
 from fastapi import FastAPI
 from fastapi.staticfiles import StaticFiles
 
+from logsetup import setup_logging
+
+setup_logging()
+
 from config import FRONTEND_DIST, STORAGE_DIR
 from database import init_db, close_db
+from guide import reconcile_guides
 from routes import router
 
 
@@ -12,6 +17,7 @@ from routes import router
 async def lifespan(app: FastAPI):
     (STORAGE_DIR / "themen").mkdir(parents=True, exist_ok=True)
     await init_db()
+    await reconcile_guides()
     yield
     await close_db()
 

backend/models.py

@@ -86,8 +86,6 @@ class ElementResponse(BaseModel):
     description: str = ""
     examples: list[str] = []
     hints: list[str] = []
-    aufgabe: str = ""
-    loesung: str = ""
     created_at: str
     updated_at: str
 
@@ -103,8 +101,6 @@ class ElementUpdateRequest(BaseModel):
     description: str | None = None
     examples: list[str] | None = None
     hints: list[str] | None = None
-    aufgabe: str | None = None
-    loesung: str | None = None
 
 
 class ElementCheckRequest(BaseModel):
@@ -113,7 +109,7 @@ class ElementCheckRequest(BaseModel):
 
 class ElementSuggestion(BaseModel):
     text: str
-    target: Literal["description", "examples", "hints", "aufgabe", "loesung"]
+    target: Literal["description", "examples", "hints"]
     content: str
 
 
@@ -124,7 +120,7 @@ class ElementCheckResponse(BaseModel):
 class ElementStyleChange(BaseModel):
     text: str
     action: Literal["entfernen", "anpassen", "hinzufuegen"]
-    target: Literal["title", "description", "examples", "hints", "aufgabe", "loesung"]
+    target: Literal["title", "description", "examples", "hints"]
     index: int | None = None
     content: str = ""
 

backend/onepager.py

@@ -0,0 +1,157 @@
+"""OnePager-Pipeline: Recherche → Recherche-Prüfung → Bauen → Prüfung (7 Karten im 3×3-Raster)."""
+
+from pathlib import Path
+
+from fsutil import atomic_write_json
+from jsonio import read_json_file as _json_datei
+from pipeline import (
+    CANCELLED, FAILED, GenContext, _check_then_fix, _extra, _fail,
+    _prompt, _set_step, _timeout, is_guide_cancelled, run_single_slot,
+)
+
+
+async def _generate_onepager(
+    guide_id: str, topic: str, instructions: str, provider: str,
+    project: Path | None, content_path: Path,
+) -> list[dict] | None:
+    ctx = GenContext(topic=topic, provider=provider, is_cancelled=lambda: is_guide_cancelled(guide_id), guide_id=guide_id)
+
+    # 3×3-Raster: 7 Karten mit festen Schlüsseln (Reihenfolge = Lesereihenfolge mobil)
+    KARTEN_KEYS = ("info", "eigenschaften", "beispiel", "zusammenhaenge", "voraussetzungen", "modern", "veraltet")
+
+    def karten_schema(data):
+        """{"karten": {key: {titel, md}}} → Liste · sonst None."""
+        if not isinstance(data, dict):
+            return None
+        karten = data.get("karten")
+        if not isinstance(karten, dict):
+            return None
+        out = []
+        for key in KARTEN_KEYS:
+            k = karten.get(key)
+            if not isinstance(k, dict) or not isinstance(k.get("titel"), str) or not isinstance(k.get("md"), str):
+                return None
+            titel, md = k["titel"].strip(), k["md"].strip()
+            if not titel or len(md) < 5:  # abgebrochene/leere Karten sind ungültig
+                return None
+            out.append({"key": key, "titel": titel, "md": md})
+        return out
+
+    d, stem = content_path.parent, content_path.stem
+    recherche_path = d / f"{stem}.recherche.md"
+    recherche_check_path = d / f"{stem}.recherche-check.json"
+    karten_path = d / f"{stem}.karten.json"
+    check_path = d / f"{stem}.onepager-check.json"
+
+    # Projekte bekommen eigene Recherche-Dimensionen — Produkt-Fragen
+    # (Version, Lizenz, Alternativen) laufen dort ins Leere.
+    if project:
+        source = _prompt("OnePager-Quelle-Projekt", project=project)
+        recherche_template = "OnePager-Recherche-Projekt"
+        recherche_check_template = "OnePager-Recherche-Check-Projekt"
+    else:
+        source = _prompt("OnePager-Quelle-Thema", topic=topic)
+        recherche_template = "OnePager-Recherche"
+        recherche_check_template = "OnePager-Recherche-Check"
+
+    def recherche_payload(result=None):
+        if not recherche_path.exists():
+            return None
+        text = recherche_path.read_text(encoding="utf-8").strip()
+        return text or None
+
+    # Schritt 1: Recherche — vorhandene Datei wird übernommen (Resume)
+    recherche = recherche_payload()
+    if recherche is None:
+        await _set_step(guide_id, 0, "Recherchiere…")
+        status, recherche = await run_single_slot(
+            ctx, "OnePager-Recherche",
+            key=f"{guide_id}-recherche",
+            prompt=_prompt(recherche_template, topic=topic, source=source, out_path=recherche_path, extra=_extra(instructions)),
+            role="quick", capabilities="files" if project else "full",
+            payload=recherche_payload, timeout=_timeout("onepager_recherche"),
+        )
+        if status == CANCELLED:
+            return None
+        if status == FAILED:
+            await _fail(guide_id, "OnePager-Recherche fehlgeschlagen")
+            return None
+
+    # Schritt 2: Recherche-Prüfung — notiert Probleme; Anpassung macht ein Recherche-Agent
+    status, fixed = await _check_then_fix(
+        ctx, name="Recherche", step=1,
+        check_key=f"{guide_id}-recherche-check",
+        check_prompt=_prompt(recherche_check_template, topic=topic, recherche=recherche, out_path=recherche_check_path),
+        check_path=recherche_check_path, check_timeout=_timeout("onepager_verify"),
+        fix_key=f"{guide_id}-recherche-fix",
+        build_fix_prompt=lambda probleme: _prompt(
+            "OnePager-Recherche-Fix",
+            topic=topic, source=source, recherche=recherche,
+            probleme="\n".join(f"- {p}" for p in probleme),
+            out_path=recherche_path, extra=_extra(instructions),
+        ),
+        fix_payload=recherche_payload, fix_timeout=_timeout("onepager_recherche"),
+        fix_role="quick", fix_caps="files" if project else "full",
+    )
+    if status == CANCELLED:
+        return None
+    if status == FAILED:
+        await _fail(guide_id, "Recherche-Prüfung fehlgeschlagen")
+        return None
+    if fixed is not None:
+        recherche = fixed
+
+    # Schritt 3: Bauen — Karten nur aus der Faktenbasis (Resume: gültige Datei wird übernommen)
+    karten = karten_schema(_json_datei(karten_path))
+    if karten is None:
+        await _set_step(guide_id, 2, "Baue OnePager…")
+        karten_path.unlink(missing_ok=True)
+        status, karten = await run_single_slot(
+            ctx, "OnePager-Bauen",
+            key=f"{guide_id}-bauen",
+            prompt=_prompt("OnePager-Bauen", topic=topic, recherche=recherche, out_path=karten_path, extra=_extra(instructions)),
+            role="fast", capabilities="files",
+            payload=lambda result: karten_schema(_json_datei(karten_path)),
+            timeout=_timeout("onepager_bauen"),
+        )
+        if status == CANCELLED:
+            return None
+        if status == FAILED:
+            await _fail(guide_id, "OnePager-Bau fehlgeschlagen")
+            return None
+
+    def karten_block() -> str:
+        return "\n\n".join(f"### {k['titel']} [{k['key']}]\n{k['md']}" for k in karten)
+
+    # Schritt 4: Prüfung — notiert Probleme; Anpassung macht ein Bauen-Agent
+    status, fixed = await _check_then_fix(
+        ctx, name="OnePager", step=3,
+        check_key=f"{guide_id}-verify",
+        check_prompt=_prompt("OnePager-Verifikation", topic=topic, recherche=recherche, karten=karten_block(), out_path=check_path),
+        check_path=check_path, check_timeout=_timeout("onepager_verify"),
+        fix_key=f"{guide_id}-karten-fix",
+        build_fix_prompt=lambda probleme: _prompt(
+            "OnePager-Fix",
+            topic=topic, recherche=recherche, karten=karten_block(),
+            probleme="\n".join(f"- {p}" for p in probleme),
+            out_path=karten_path, extra=_extra(instructions),
+        ),
+        fix_payload=lambda result: karten_schema(_json_datei(karten_path)),
+        fix_timeout=_timeout("onepager_bauen"),
+        on_fix_invalid=lambda: atomic_write_json(
+            karten_path, {"karten": {k["key"]: {"titel": k["titel"], "md": k["md"]} for k in karten}},
+        ),
+    )
+    if status == CANCELLED:
+        return None
+    if status == FAILED:
+        await _fail(guide_id, "OnePager-Prüfung fehlgeschlagen")
+        return None
+    if fixed is not None:
+        karten = fixed
+
+    sections = [
+        {"num": i, "title": k["titel"], "md": k["md"], "key": k["key"]}
+        for i, k in enumerate(karten, 1)
+    ]
+    return [{"title": topic, "sections": sections}]

backend/pipeline.py

@@ -0,0 +1,251 @@
+"""Pipeline-Grundbausteine: Agent-Races, Single-Slot, Check→Fix, 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.
+"""
+
+import asyncio
+import logging
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Callable
+
+from agents import run_agent, kill_process
+from config import MAX_CONCURRENT_GENERATIONS, TEMPLATES_DIR, TIMEOUTS
+from database import update_guide
+from jsonio import read_json_file as _json_datei
+
+log = logging.getLogger("creator.pipeline")
+
+_semaphore = asyncio.Semaphore(MAX_CONCURRENT_GENERATIONS)
+_cancelled: set[str] = set()
+
+
+async def cancel_guide(guide_id: str) -> bool:
+    _cancelled.add(guide_id)
+    kill_process(guide_id)
+    now = datetime.now(timezone.utc).isoformat()
+    await update_guide(guide_id, status="error", progress=None, error_msg="Abgebrochen — Fortschritt bleibt erhalten", updated_at=now)
+    return True
+
+
+def is_guide_cancelled(guide_id: str) -> bool:
+    return guide_id in _cancelled
+
+
+def clear_guide_cancelled(guide_id: str) -> None:
+    _cancelled.discard(guide_id)
+
+
+async def _set_progress(guide_id: str, progress: str) -> None:
+    now = datetime.now(timezone.utc).isoformat()
+    await update_guide(guide_id, progress=progress, updated_at=now)
+
+
+async def _set_step(guide_id: str, step: int, progress: str) -> None:
+    now = datetime.now(timezone.utc).isoformat()
+    await update_guide(guide_id, step=step, progress=progress, updated_at=now)
+
+
+async def _fail(guide_id: str, msg: str) -> None:
+    now = datetime.now(timezone.utc).isoformat()
+    await update_guide(guide_id, status="error", progress=None, error_msg=msg, updated_at=now)
+
+
+def _prompt(name: str, **kwargs) -> str:
+    template = (TEMPLATES_DIR / "Prompt" / f"{name}.md").read_text(encoding="utf-8")
+    return template.format(**kwargs)
+
+
+def _extra(instructions: str) -> str:
+    return f"\n\nZUSÄTZLICHE ANWEISUNGEN VOM NUTZER:\n{instructions}\n" if instructions else ""
+
+
+def _log(topic: str, msg: str) -> None:
+    log.info("[%s] %s", topic, msg)
+
+
+def _claude_error(label: str, returncode: int, stdout: str, stderr: str) -> str:
+    stderr = (stderr or "").strip()
+    if stderr:
+        return f"{label}: {stderr[:1000]}"
+    tail = (stdout or "").strip()[-500:]
+    if tail:
+        return f"{label} (exit {returncode}, stderr leer): …{tail}"
+    return f"{label} (exit {returncode}, ohne Ausgabe)"
+
+
+def _gather_error(label: str, results: list) -> str:
+    for r in results:
+        if isinstance(r, BaseException):
+            return f"{label}: {type(r).__name__}: {r}"
+        returncode, stdout, stderr = r
+        if returncode != 0:
+            return _claude_error(label, returncode, stdout, stderr)
+    return f"{label}: kein verwertbares Ergebnis"
+
+
+def _timeout(step: str, n: int = 0) -> int:
+    base, per = TIMEOUTS[step]
+    return base + per * n
+
+
+def _probleme_schema(data):
+    """{"ok": true} → [] · {"probleme": [str]} → Liste · sonst None."""
+    if not isinstance(data, dict):
+        return None
+    if data.get("ok") is True:
+        return []
+    p = data.get("probleme")
+    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
+
+
+_MAX_RESTARTS = 2
+
+
+async def _race(topic: str, label: str, slots: list[dict], quorum: int, timeout: int, provider: str, on_update=None, cancelled=None) -> list | None:
+    """Startet alle Slots parallel und sammelt `quorum` gültige Ergebnisse.
+
+    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).
+    """
+    attempts = {i: 0 for i in range(len(slots))}
+    tasks: dict[asyncio.Task, int] = {}
+
+    def spawn(i: int) -> None:
+        slot = slots[i]
+        task = asyncio.create_task(run_agent(
+            slot["key"], slot["prompt"], timeout,
+            provider=provider, role=slot["role"], capabilities=slot["capabilities"],
+        ))
+        tasks[task] = i
+
+    for i in range(len(slots)):
+        spawn(i)
+
+    results: list = []
+    try:
+        while tasks:
+            if cancelled and cancelled():
+                return None
+            done, _ = await asyncio.wait(tasks.keys(), return_when=asyncio.FIRST_COMPLETED)
+            for task in done:
+                i = tasks.pop(task)
+                payload, err = None, None
+                try:
+                    result = task.result()
+                    if result[0] != 0:
+                        err = _claude_error("Fehler", *result)
+                    else:
+                        payload = slots[i]["payload"](result)
+                        if payload is None:
+                            err = "Ergebnis ungültig/nicht parsebar"
+                except asyncio.TimeoutError:
+                    err = f"Timeout nach {timeout}s"
+                except Exception as e:
+                    err = f"{type(e).__name__}: {e}"
+
+                if payload is not None:
+                    results.append(payload)
+                    if on_update:
+                        on_update(len(results))
+                    if len(results) >= quorum:
+                        return results
+                    continue
+
+                _log(topic, f"{label} {i + 1} (Versuch {attempts[i] + 1}): {err}")
+                attempts[i] += 1
+                if attempts[i] <= _MAX_RESTARTS and not (cancelled and cancelled()):
+                    spawn(i)
+        _log(topic, f"{label}: Quorum {quorum} nicht erreicht ({len(results)} gültig)")
+        return None
+    finally:
+        for task, i in tasks.items():
+            kill_process(slots[i]["key"])
+            task.cancel()
+        if tasks:
+            await asyncio.gather(*tasks.keys(), return_exceptions=True)
+
+
+@dataclass
+class GenContext:
+    """Durchgereichte Pipeline-Parameter — erspart lange Argument-Signaturen."""
+    topic: str
+    provider: str
+    is_cancelled: Callable[[], bool]
+    guide_id: str | None = None
+
+
+# Ergebnis-Status von run_single_slot/_check_then_fix
+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,
+) -> tuple[str, object]:
+    """Ein Agent, ein gültiges Ergebnis (Race mit Quorum 1).
+
+    → (OK, wert) | (CANCELLED, None) | (FAILED, None)
+    """
+    slots = [{"key": key, "prompt": prompt, "role": role, "capabilities": capabilities, "payload": payload}]
+    res = await _race(ctx.topic, label, slots, 1, timeout, ctx.provider, cancelled=ctx.is_cancelled)
+    if ctx.is_cancelled():
+        return CANCELLED, None
+    if res is None:
+        return FAILED, None
+    return OK, res[0]
+
+
+async def _check_then_fix(
+    ctx: GenContext, *, name: str, step: int,
+    check_key: str, check_prompt: str, check_path: Path, check_timeout: int,
+    fix_key: str, build_fix_prompt, fix_payload, fix_timeout: int,
+    fix_role: str = "fast", fix_caps: str = "files",
+    on_fix_invalid=None,
+) -> tuple[str, object]:
+    """Check→Fix-Muster: Prüf-Agent notiert Probleme (JSON), Fix-Agent behebt sie.
+
+    Resume: existierende Check-Datei überspringt den ganzen Schritt.
+    Check ist fatal (FAILED), Fix nicht — Original bleibt; on_fix_invalid kann
+    das kanonische Original zurückschreiben, falls der Fix-Agent die
+    Artefakt-Datei zerschrieben hat.
+    Lese-Check (Multi-Slot, Section-genau) und Bausteine-Auswahl-Check
+    (Patch-Semantik) passen bewusst NICHT in dieses Muster.
+    → (OK, neues_artefakt | None=unverändert) | (CANCELLED, None) | (FAILED, None)
+    """
+    if check_path.exists():
+        return OK, None
+    await _set_step(ctx.guide_id, step, f"Prüfe {name}…")
+    status, probleme = await run_single_slot(
+        ctx, f"{name}-Prüfung", key=check_key, prompt=check_prompt,
+        role="fast", capabilities="files",
+        payload=lambda result: _probleme_schema(_json_datei(check_path)),
+        timeout=check_timeout,
+    )
+    if status != OK:
+        return status, None
+    if not probleme:
+        return OK, None
+    _log(ctx.topic, f"{name}-Prüfung: {len(probleme)} Problem(e) notiert")
+    await _set_step(ctx.guide_id, step, f"Passe {name} an…")
+    status, fixed = await run_single_slot(
+        ctx, f"{name}-Fix", key=fix_key, prompt=build_fix_prompt(probleme),
+        role=fix_role, capabilities=fix_caps, payload=fix_payload, timeout=fix_timeout,
+    )
+    if status == CANCELLED:
+        return CANCELLED, None
+    if status == FAILED:
+        _log(ctx.topic, f"{name}-Fix ungültig — Original bleibt")
+        if on_fix_invalid:
+            on_fix_invalid()
+        return OK, None
+    return OK, fixed

backend/regeln.py

@@ -0,0 +1,88 @@
+"""Lernschulden-Regeln: Progression und Deckel für offene Guides — die EINZIGE Quelle.
+
+Regeln (nur Neu-Erstellungen; Themen, Bausteine, OnePager unbegrenzt):
+- JE Format (MiniGuide/Guide/FullGuide) höchstens 3 erstellte, nicht absolvierte Guides
+- Progression pro Thema: Guide erst nach absolviertem MiniGuide, FullGuide erst nach absolviertem Guide
+Alle Funktionen arbeiten auf einmal geladenen Daten (lade_lernstand) — keine
+Query-Schleifen mehr pro Guide.
+"""
+
+import json
+
+from database import list_guides, list_progress_all
+from guide import guide_slot_dateien
+from paths import bausteine_path, guide_content_path
+
+MAX_OFFENE_GUIDES = 3
+VORSTUFE = {"Guide": "MiniGuide", "FullGuide": "Guide"}
+FORMATE = ("MiniGuide", "Guide", "FullGuide")
+
+
+async def lade_lernstand() -> tuple[list[dict], dict[str, set[str]]]:
+    """Guides + kompletter Kapitel-Fortschritt in zwei Queries."""
+    return await list_guides(), await list_progress_all()
+
+
+def _kapitel_titel(topic: str, fmt: str) -> set[str] | None:
+    path = guide_content_path(topic, fmt)
+    if not path.exists():
+        return None
+    try:
+        chapters = json.loads(path.read_text(encoding="utf-8")).get("chapters", [])
+    except ValueError:
+        return None
+    return {c.get("title") for c in chapters}
+
+
+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_absolviert(g: dict, progress: dict[str, set[str]]) -> bool:
+    titles = _kapitel_titel(g["topic"], g["format"])
+    return bool(titles) and titles <= progress.get(g["id"], set())
+
+
+def ist_absolviert(topic: str, fmt: str, guides: list[dict], progress: dict[str, set[str]]) -> bool:
+    """Alle Kapitel des neuesten fertigen Guides (Thema+Format) abgehakt?"""
+    g = _neueste_done(guides, fmt).get(topic)
+    return g is not None and _guide_absolviert(g, progress)
+
+
+def formate_stats(guides: list[dict], progress: 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_absolviert(g, progress))
+        formate[fmt] = {"erstellt": len(neueste), "absolviert": absolviert}
+    return formate
+
+
+def guide_lock(topic: str, fmt: str, guides: list[dict], progress: 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 fmt != "OnePager" and 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 fmt != "OnePager" and not content.exists() and not guide_slot_dateien(content):
+        vorstufe = VORSTUFE.get(fmt)
+        if vorstufe and not ist_absolviert(topic, vorstufe, guides, progress):
+            return f"Erst den {vorstufe} dieses Themas absolvieren"
+        stat = formate_stats(guides, progress).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/routes.py

@@ -1,5 +1,4 @@
 import asyncio
-import json
 import shutil
 import uuid
 from datetime import datetime, timezone
@@ -15,11 +14,11 @@ from database import (
     list_progress, set_progress, delete_progress,
     create_element, list_elements, get_element, update_element, delete_element,
 )
-from generator import (
+from bausteine import generate_bausteine, cancel_bausteine, bausteine_status, active_bausteine, reset_bausteine
-    generate_guide, cancel_guide, chat_with_guide, guide_slot_dateien,
+from elements import generate_element, chat_with_guide, chat_with_element, check_element, style_element, refine_suggestion
-    generate_bausteine, cancel_bausteine, bausteine_status, active_bausteine, reset_bausteine,
+from guide import generate_guide, guide_slot_dateien
-    generate_element, chat_with_element, check_element, style_element, refine_suggestion,
+from pipeline import cancel_guide
-)
+from regeln import FORMATE, formate_stats, guide_lock, ist_absolviert, lade_lernstand
 from models import (
     GuideCreateRequest, GuideResponse,
     TopicCreateRequest,
@@ -30,7 +29,7 @@ from models import (
     ElementRefineRequest, ElementRefineResponse,
     ProgressUpdate, ProgressResponse, ProjectResponse, ProviderInfo,
 )
-from paths import bausteine_path, bausteine_topics, guide_content_path, project_dir, topic_dir
+from paths import bausteine_topics, guide_content_path, project_dir, topic_dir
 
 router = APIRouter(prefix="/api")
 
@@ -51,73 +50,21 @@ async def get_topics():
     return db_topics + sorted(derived - set(db_topics))
 
 
-# Lernschulden-Regeln (nur Neu-Erstellungen; Themen, Bausteine, OnePager unbegrenzt):
-# - JE Format (MiniGuide/Guide/FullGuide) höchstens 3 erstellte, nicht absolvierte Guides
-# - Progression pro Thema: Guide erst nach absolviertem MiniGuide, FullGuide erst nach absolviertem Guide
-MAX_OFFENE_GUIDES = 3
-VORSTUFE = {"Guide": "MiniGuide", "FullGuide": "Guide"}
-
-
-async def _ist_absolviert(topic: str, fmt: str) -> bool:
-    """Alle Kapitel des neuesten fertigen Guides (Thema+Format) abgehakt?"""
-    neueste = None
-    for g in await list_guides():
-        if g["topic"] == topic and g["format"] == fmt and g["status"] == "done":
-            if neueste is None or g["created_at"] > neueste["created_at"]:
-                neueste = g
-    if neueste is None:
-        return False
-    path = guide_content_path(topic, fmt)
-    if not path.exists():
-        return False
-    try:
-        chapters = json.loads(path.read_text(encoding="utf-8")).get("chapters", [])
-    except ValueError:
-        return False
-    titles = {c.get("title") for c in chapters}
-    return bool(titles) and titles <= set(await list_progress(neueste["id"]))
-
-
-async def _formate_stats() -> dict:
-    """Pro Format erstellt/absolviert (alle Kapitel abgehakt) — pro Thema zählt nur der neueste fertige Guide."""
-    guides = await list_guides()
-    formate = {}
-    for fmt in ("MiniGuide", "Guide", "FullGuide"):
-        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
-        absolviert = 0
-        for g in neueste.values():
-            path = guide_content_path(g["topic"], fmt)
-            if not path.exists():
-                continue
-            try:
-                chapters = json.loads(path.read_text(encoding="utf-8")).get("chapters", [])
-            except ValueError:
-                continue
-            titles = {c.get("title") for c in chapters}
-            if titles and titles <= set(await list_progress(g["id"])):
-                absolviert += 1
-        formate[fmt] = {"erstellt": len(neueste), "absolviert": absolviert}
-    return formate
-
-
 @router.get("/stats")
 async def get_stats():
     """Tracker: Themen-Anzahl + pro Format erstellt/absolviert."""
-    guides = await list_guides()
+    guides, progress = await lade_lernstand()
     themen = set(await db_list_topics()) | {g["topic"] for g in guides} | set(bausteine_topics())
     if PROJECTS_DIR.is_dir():
         themen |= {e.name for e in PROJECTS_DIR.iterdir() if e.is_dir()}
-    return {"themen": len(themen), "formate": await _formate_stats()}
+    return {"themen": len(themen), "formate": formate_stats(guides, progress)}
 
 
 @router.get("/topics/fortschritt")
 async def topic_fortschritt(topic: str):
     """Absolviert-Status pro Format — fürs Freischalten der nächsten Ausbaustufe."""
-    return {fmt: await _ist_absolviert(topic, fmt) for fmt in ("MiniGuide", "Guide", "FullGuide")}
+    guides, progress = await lade_lernstand()
+    return {fmt: ist_absolviert(topic, fmt, guides, progress) for fmt in FORMATE}
 
 
 @router.post("/topics")
@@ -195,23 +142,10 @@ async def remove_bausteine(topic: str):
 
 @router.post("/guides", response_model=GuideResponse)
 async def create(req: GuideCreateRequest):
-    if req.format != "OnePager" and not bausteine_path(req.topic.strip()).exists():
+    guides, progress = await lade_lernstand()
-        raise HTTPException(400, "Erst Bausteine erstellen")
+    grund = guide_lock(req.topic.strip(), req.format, guides, progress)
-    # Kein Duplikat-Start: pro Thema+Format höchstens eine laufende Generierung
+    if grund:
-    for g in await list_guides():
+        raise HTTPException(400 if grund == "Erst Bausteine erstellen" else 409, grund)
-        if g["topic"] == req.topic.strip() and g["format"] == req.format and g["status"] in ("queued", "generating"):
-            raise HTTPException(409, "Generierung läuft bereits")
-    # Lernschulden-Regeln — nur für Neu-Erstellungen; Resume (Schritt-Dateien
-    # vorhanden) und Neu-Generieren bestehender Guides sind ausgenommen.
-    content = guide_content_path(req.topic.strip(), req.format)
-    if req.format != "OnePager" and not content.exists() and not guide_slot_dateien(content):
-        vorstufe = VORSTUFE.get(req.format)
-        if vorstufe and not await _ist_absolviert(req.topic.strip(), vorstufe):
-            raise HTTPException(409, f"Erst den {vorstufe} dieses Themas absolvieren")
-        stat = (await _formate_stats()).get(req.format, {"erstellt": 0, "absolviert": 0})
-        offen = stat["erstellt"] - stat["absolviert"]
-        if offen >= MAX_OFFENE_GUIDES:
-            raise HTTPException(409, f"Erst {req.format}s absolvieren — maximal {MAX_OFFENE_GUIDES} offene erlaubt ({offen} offen)")
     await create_topic(req.topic.strip())
     now = datetime.now(timezone.utc).isoformat()
     guide = {
@@ -234,6 +168,13 @@ async def list_all():
     return await list_guides()
 
 
+@router.get("/guides/locks")
+async def guide_locks(topic: str):
+    """Sperr-Gründe pro Format für den ▶-Button — None = erstellbar."""
+    guides, progress = await lade_lernstand()
+    return {fmt: guide_lock(topic, fmt, guides, progress) for fmt in ("OnePager", *FORMATE)}
+
+
 @router.get("/guides/{guide_id}", response_model=GuideResponse)
 async def get_one(guide_id: str):
     guide = await get_guide(guide_id)

backend/textkit.py

@@ -0,0 +1,151 @@
+"""Reine Text-Helfer: Titel-Normalisierung, Listen-Parser, Chunk-Aufteilung.
+
+Kein Zustand, keine IO — überall gefahrlos importierbar.
+"""
+
+import re
+import unicodedata
+
+_CATEGORIES = ("KERN", "WICHTIG", "REST")  # nur noch für den Altformat-Reader
+
+
+def _norm_titel(s: str) -> str:
+    """Normalisiert einen Titel für den Schlüssel-Vergleich.
+
+    NFKC + casefold fangen Unicode-Varianten; Anführungszeichen, Markdown-
+    Emphasis und Dash-Varianten kommen aus KI-Output in allen Spielarten.
+    """
+    s = unicodedata.normalize("NFKC", s)
+    s = re.sub(r"[`'\"<>„“”‚’«»*_]", "", s)
+    s = re.sub(r"[–—‐]", "-", s)
+    s = re.sub(r"\s+", " ", s).strip().strip(".:;").strip()
+    return s.casefold()
+
+
+def _titel(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."""
+    seen: dict[str, int] = {}
+    out: dict[int, str] = {}
+    for num, text in entries.items():
+        titel = _titel(text)
+        key = _norm_titel(titel)
+        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
+        out[num] = text
+    return out
+
+
+def _titel_index(entries: dict[int, str]) -> dict[str, int]:
+    return {_norm_titel(_titel(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 — …")."""
+    if not isinstance(t, str):
+        return None
+    return idx.get(_norm_titel(t)) or idx.get(_norm_titel(_titel(t)))
+
+
+def _parse_auswahl(text: str) -> dict[int, str]:
+    """Parst eine Baustein-Liste: `N. Titel — Kurzbeschreibung` pro Zeile."""
+    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)
+        elif last is not None and line.strip():
+            entries[last] += " " + line.strip()
+    return entries
+
+
+def _parse_kategorien(text: str) -> dict[str, list[str]]:
+    """Altformat-Reader: finale Baustein-Datei mit ## KERN/WICHTIG/REST-Abschnitten."""
+    cats: dict[str, list[str]] = {}
+    current = None
+    for line in text.splitlines():
+        s = line.strip()
+        m = re.match(r"#+\s*(KERN|WICHTIG|REST)\b", s, re.IGNORECASE)
+        if m:
+            current = m.group(1).upper()
+            cats.setdefault(current, [])
+            continue
+        m = re.match(r"(\d+)[.)]\s+(.*\S)", s)
+        if m and current:
+            cats[current].append(m.group(2))
+    return cats
+
+
+def _lade_bausteine(text: str) -> dict[int, str]:
+    """Lädt die finale Baustein-Datei — sortierte Liste (neu) oder Kategorien (Altformat)."""
+    if re.search(r"^#+\s*KERN\b", text, re.IGNORECASE | re.MULTILINE):
+        cats = _parse_kategorien(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)
+
+
+_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)
+
+
+def _parse_fragment(text: str) -> list[dict]:
+    """Parst eine Writer-Datei → [{"kapitel", "titel", "md"}] in Datei-Reihenfolge."""
+    sections: list[dict] = []
+    kapitel = None
+    current = None
+    for line in text.splitlines():
+        s = line.strip()
+        m = _FRAGMENT_KAPITEL_RE.match(s)
+        if m:
+            kapitel = m.group(1)
+            current = None
+            continue
+        m = _FRAGMENT_SECTION_RE.match(s)
+        if m:
+            current = {"kapitel": kapitel, "titel": m.group(1), "md": []}
+            sections.append(current)
+            continue
+        if current is not None:
+            current["md"].append(line)
+    for sec in sections:
+        sec["md"] = "\n".join(sec["md"]).strip()
+    return sections
+
+
+def _split_chunks(chapters: list[dict], n: int) -> list[list[dict]]:
+    """Teilt Kapitel in bis zu n zusammenhängende Chunks, balanciert nach Section-Anzahl."""
+    n = max(1, min(n, len(chapters)))
+    chunks: list[list[dict]] = []
+    current: list[dict] = []
+    count = 0
+    remaining_total = sum(len(c["nums"]) for c in chapters)
+    remaining_chunks = n
+    for ch in chapters:
+        current.append(ch)
+        count += len(ch["nums"])
+        if remaining_chunks > 1 and count >= remaining_total / remaining_chunks:
+            chunks.append(current)
+            remaining_total -= count
+            remaining_chunks -= 1
+            current = []
+            count = 0
+    if current:
+        chunks.append(current)
+    return chunks
+
+
+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)

frontend/src/App.vue

@@ -1,9 +1,10 @@
 <script setup>
-import { ref, computed, watch, onMounted, onUnmounted, nextTick } from 'vue'
+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, fetchProjects, deleteProject as apiDeleteProject, fetchProviders, fetchStats, fetchTopicFortschritt } from './api.js'
+import { fetchGuides, fetchTopics, createTopic as apiCreateTopic, deleteTopic as apiDeleteTopic, createGuide as apiCreate, deleteGuide, cancelGuide as apiCancel, fetchBausteineStatus, fetchActiveBausteine, createBausteine as apiCreateBausteine, cancelBausteine as apiCancelBausteine, deleteBausteine as apiDeleteBausteine, fetchProjects, deleteProject as apiDeleteProject, fetchProviders, fetchStats, fetchTopicFortschritt, fetchGuideLocks } from './api.js'
+import { usePolling } from './composables/usePolling.js'
 import TopicSidebar from './components/TopicSidebar.vue'
 import TopicDetail from './components/TopicDetail.vue'
-import ElementsSidebar from './components/ElementsSidebar.vue'
+import ElementsSidebar from './components/elements/ElementsSidebar.vue'
 import ElementsOverview from './components/ElementsOverview.vue'
 
 const guides = ref([])
@@ -25,6 +26,8 @@ const provider = ref(localStorage.getItem('provider') || 'claude')
 const providers = ref([])
 const stats = ref(null)
 const fortschritt = ref({})
+const locks = ref({})       // Sperr-Gründe pro Format (Backend = einzige Regel-Quelle)
+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
@@ -56,7 +59,6 @@ async function loadProviders() {
     console.error('Fehler beim Laden der Provider:', e)
   }
 }
-let pollTimer = null
 
 function applyTheme() {
   document.documentElement.classList.toggle('dark', darkMode.value)
@@ -126,21 +128,27 @@ async function loadTopics() {
   }
 }
 
-// Fehlermeldungen verhalten sich wie Flash-Messages: × blendet aus,
+// Weggeklickte Fehler bleiben weggeklickt — auch über Reloads (localStorage).
-// beim Reload sind Alt-Fehler von vornherein ausgeblendet.
+// Nicht weggeklickte Fehler bleiben sichtbar, bis der Nutzer sie schließt.
-const dismissedErrors = ref(new Set())
+const dismissedErrors = ref(new Set(JSON.parse(localStorage.getItem('dismissedErrors') || '[]')))
-let errorsInitialized = false
+
+function persistDismissed() {
+  localStorage.setItem('dismissedErrors', JSON.stringify([...dismissedErrors.value]))
+}
 
 function handleDismissError(guideId) {
   dismissedErrors.value = new Set([...dismissedErrors.value, guideId])
+  persistDismissed()
 }
 
 async function loadGuides() {
   try {
     guides.value = await fetchGuides()
-    if (!errorsInitialized) {
+    // IDs prunen, deren Guide nicht mehr als Fehler existiert
-      errorsInitialized = true
+    const errorIds = new Set(guides.value.filter((g) => g.status === 'error').map((g) => g.id))
-      dismissedErrors.value = new Set(guides.value.filter((g) => g.status === 'error').map((g) => g.id))
+    if ([...dismissedErrors.value].some((id) => !errorIds.has(id))) {
+      dismissedErrors.value = new Set([...dismissedErrors.value].filter((id) => errorIds.has(id)))
+      persistDismissed()
     }
     loadStats()
   } catch (e) {
@@ -154,11 +162,13 @@ async function loadBausteine() {
     if (selectedTopic.value) {
       bausteine.value = await fetchBausteineStatus(selectedTopic.value)
       fortschritt.value = await fetchTopicFortschritt(selectedTopic.value)
+      locks.value = await fetchGuideLocks(selectedTopic.value)
     } else {
       bausteine.value = { ...EMPTY_BAUSTEINE }
       fortschritt.value = {}
+      locks.value = {}
     }
-    if (activeBausteine.value.length && !pollTimer) startPolling()
+    if (activeBausteine.value.length && !polling.running()) startPolling()
   } catch (e) {
     console.error('Fehler beim Laden der Bausteine:', e)
   }
@@ -224,7 +234,13 @@ async function handleResetBausteine() {
 
 async function handleBausteineClick({ instructions }) {
   if (!selectedTopic.value) return
+  uiError.value = null
+  try {
     await apiCreateBausteine(selectedTopic.value, instructions, provider.value)
+  } catch (e) {
+    uiError.value = e.message
+    return
+  }
   await loadBausteine()
   startPolling()
 }
@@ -237,7 +253,13 @@ async function handleFormatClick({ format, instructions }) {
       && (g.status === 'generating' || g.status === 'queued'),
   )
   if (running) return
+  uiError.value = null
+  try {
     await apiCreate(selectedTopic.value, format, instructions, provider.value)
+  } catch (e) {
+    uiError.value = e.message
+    return
+  }
   await loadGuides()
   startPolling()
 }
@@ -276,20 +298,11 @@ async function handleDeleteGuide(guideId, slots = false) {
   await loadGuides()
 }
 
-function startPolling() {
+const polling = usePolling(
-  stopPolling()
+  () => Promise.all([loadGuides(), loadBausteine(), loadTopics()]),
-  pollTimer = setInterval(async () => {
+  () => hasActiveGuides.value || activeBausteine.value.length > 0,
-    await Promise.all([loadGuides(), loadBausteine(), loadTopics()])
+)
-    if (!hasActiveGuides.value && !activeBausteine.value.length) stopPolling()
+const startPolling = polling.start
-  }, 3000)
-}
-
-function stopPolling() {
-  if (pollTimer) {
-    clearInterval(pollTimer)
-    pollTimer = null
-  }
-}
 
 async function handleCancel(guideId) {
   await apiCancel(guideId)
@@ -311,16 +324,6 @@ async function handleDeleteTopic(topic) {
   await loadGuides()
 }
 
-function onVisibility() {
-  if (document.hidden) {
-    stopPolling()
-  } else {
-    loadGuides()
-    loadBausteine()
-    if (hasActiveGuides.value || activeBausteine.value.length) startPolling()
-  }
-}
-
 onMounted(async () => {
   await Promise.all([loadGuides(), loadTopics(), loadProjects(), loadProviders()])
   const savedTopic = localStorage.getItem('lastTopic')
@@ -333,12 +336,6 @@ onMounted(async () => {
   } else if (!selectedTopic.value && topics.value.length) {
     selectTopic(topics.value[0])
   }
-  document.addEventListener('visibilitychange', onVisibility)
-})
-
-onUnmounted(() => {
-  stopPolling()
-  document.removeEventListener('visibilitychange', onVisibility)
 })
 </script>
 
@@ -352,6 +349,8 @@ onUnmounted(() => {
       :selectedTopic="selectedTopic"
       :stats="stats"
       :fortschritt="fortschritt"
+      :locks="locks"
+      :uiError="uiError"
       :doneByFormat="doneByFormat"
       :latestByFormat="latestByFormat"
       :allGuides="guides"
@@ -375,6 +374,7 @@ onUnmounted(() => {
       @cancelGuide="handleCancel"
       @deleteGuide="handleDeleteGuide"
       @dismissError="handleDismissError"
+      @dismissUiError="uiError = null"
       @preview="handlePreview"
       @openElements="handleOpenElements"
       @togglePin="toggleSidebarPin"

frontend/src/api.js

@@ -1,17 +1,35 @@
 const BASE = '/api'
 
+// Backend-Fehler (400/409 mit detail) als Error werfen statt sie zu verschlucken
+async function jsonOrThrow(res) {
+  if (!res.ok) {
+    let detail = `Fehler (HTTP ${res.status})`
+    try {
+      const data = await res.json()
+      if (data.detail) detail = typeof data.detail === 'string' ? data.detail : JSON.stringify(data.detail)
+    } catch { /* kein JSON-Body */ }
+    throw new Error(detail)
+  }
+  return res.json()
+}
+
 export async function fetchGuides() {
   const res = await fetch(`${BASE}/guides`)
   return res.json()
 }
 
+export async function fetchGuideLocks(topic) {
+  const res = await fetch(`${BASE}/guides/locks?topic=${encodeURIComponent(topic)}`)
+  return res.json()
+}
+
 export async function createGuide(topic, format, instructions = '', provider = 'claude') {
   const res = await fetch(`${BASE}/guides`, {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
     body: JSON.stringify({ topic, format, instructions, provider }),
   })
-  return res.json()
+  return jsonOrThrow(res)
 }
 
 export async function fetchActiveBausteine() {
@@ -30,7 +48,7 @@ export async function createBausteine(topic, instructions = '', provider = 'clau
     headers: { 'Content-Type': 'application/json' },
     body: JSON.stringify({ topic, instructions, provider }),
   })
-  return res.json()
+  return jsonOrThrow(res)
 }
 
 export async function cancelBausteine(topic) {

frontend/src/assets/markdown.css

@@ -0,0 +1,73 @@
+/* Gemeinsames Markdown-Styling für v-html-Inhalte (renderMarkdown).
+   v-html-Kinder tragen keine data-v-Attribute — daher globale Regeln statt
+   :deep()-Kopien in jeder Komponente. Komponenten-Overrides bleiben scoped
+   und gewinnen per Spezifität (z. B. pre-Scroll in TopicDetail). */
+
+.markdown p {
+  margin: 0 0 0.5em;
+}
+
+.markdown p:last-child {
+  margin-bottom: 0;
+}
+
+.markdown ul,
+.markdown ol {
+  margin: 0.3em 0;
+  padding-left: 1.2em;
+}
+
+.markdown li {
+  margin: 0.15em 0;
+}
+
+.markdown code {
+  background: var(--border);
+  padding: 1px 4px;
+  border-radius: 4px;
+  font-family: "SF Mono", Consolas, monospace;
+  font-size: 0.85em;
+  /* Lange Bezeichner (Namespaces, Pfade) dürfen umbrechen statt zu überlaufen */
+  overflow-wrap: anywhere;
+}
+
+.markdown pre {
+  background: var(--code-bg, #1e2330);
+  color: var(--code-fg, #e6e8ee);
+  padding: 10px 12px;
+  border-radius: 8px;
+  /* Default: umbrechen (schmale Sidebars/Karten) — die breite Lese-Ansicht
+     in TopicDetail überschreibt auf horizontales Scrollen */
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+  margin: 0.5em 0;
+}
+
+.markdown pre code {
+  background: none;
+  padding: 0;
+  color: inherit;
+  font-size: 0.85em;
+}
+
+.markdown h1,
+.markdown h2,
+.markdown h3 {
+  font-size: 0.95em;
+  margin: 0.6em 0 0.3em;
+}
+
+.markdown a {
+  color: var(--accent-hover);
+}
+
+.markdown table {
+  border-collapse: collapse;
+  font-size: 0.95em;
+}
+
+.markdown th,
+.markdown td {
+  border: 1px solid var(--border-strong);
+  padding: 2px 6px;
+}

frontend/src/components/ElementsOverview.vue

@@ -161,45 +161,10 @@ function plain(text) {
   margin-bottom: 0.2rem;
 }
 
-/* Markdown im Guide-Stil */
+/* Markdown: Basis global (assets/markdown.css), hier nur Grundschrift der Karten */
 .markdown {
   font-size: 0.9rem;
   line-height: 1.55;
   color: var(--text);
 }
-
-.markdown :deep(p) {
-  margin: 0 0 0.5em;
-}
-
-.markdown :deep(p:last-child) {
-  margin-bottom: 0;
-}
-
-.markdown :deep(code) {
-  background: var(--border);
-  padding: 1px 4px;
-  border-radius: 4px;
-  font-family: "SF Mono", Consolas, monospace;
-  font-size: 0.85em;
-  overflow-wrap: anywhere;
-}
-
-.markdown :deep(pre) {
-  background: var(--code-bg, #1e2330);
-  color: var(--code-fg, #e6e8ee);
-  padding: 10px 12px;
-  border-radius: 8px;
-  /* Umbrechen statt horizontal scrollen — Scrollbar verdeckt sonst die Code-Zeile */
-  white-space: pre-wrap;
-  overflow-wrap: anywhere;
-  margin: 0.4em 0;
-}
-
-.markdown :deep(pre code) {
-  background: none;
-  padding: 0;
-  color: inherit;
-  font-size: 0.85em;
-}
 </style>

frontend/src/components/TopicDetail.vue

@@ -2,6 +2,7 @@
 import { computed, ref, watch, nextTick, onMounted, onUnmounted } from 'vue'
 import { fetchGuideContent, chatGuide, fetchProgress, setProgress } from '../api.js'
 import { renderMarkdown } from '../markdown.js'
+import { useChat } from '../composables/useChat.js'
 
 const props = defineProps({
   previewGuide: { type: Object, default: null },
@@ -72,13 +73,16 @@ async function toggleChapter(title) {
   }
 }
 
-// --- Chat ---
+// --- Chat (Mechanik in useChat; Kontext-Extraktion bleibt hier) ---
+const chat = useChat((msgs) => {
+  const { section, outline } = extractContext()
+  return chatGuide(props.previewGuide.id, {
+    section, outline, messages: msgs, provider: props.provider,
+  })
+})
+const { messages, input, loading, messagesEl, inputEl, send } = chat
+const autoGrow = () => chat.autoGrow()
 const chatOpen = ref(false)
-const messages = ref([])
-const input = ref('')
-const loading = ref(false)
-const messagesEl = ref(null)
-const inputEl = ref(null)
 const panelEl = ref(null)
 
 function openChat() {
@@ -88,10 +92,15 @@ function openChat() {
 
 function closeChat() {
   chatOpen.value = false
-  messages.value = []
+  chat.reset()
-  input.value = ''
 }
 
+// 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
@@ -141,43 +150,6 @@ function extractContext() {
   return { section, outline }
 }
 
-async function scrollToBottom() {
-  await nextTick()
-  if (messagesEl.value) messagesEl.value.scrollTop = messagesEl.value.scrollHeight
-}
-
-function autoGrow() {
-  const el = inputEl.value
-  if (!el) return
-  el.style.height = 'auto'
-  el.style.height = Math.min(el.scrollHeight, 140) + 'px'
-}
-
-async function send() {
-  const text = input.value.trim()
-  if (!text || loading.value || !props.previewGuide) return
-  messages.value.push({ role: 'user', content: text })
-  input.value = ''
-  nextTick(autoGrow)
-  loading.value = true
-  scrollToBottom()
-  try {
-    const { section, outline } = extractContext()
-    const res = await chatGuide(props.previewGuide.id, {
-      section,
-      outline,
-      messages: messages.value,
-      provider: props.provider,
-    })
-    messages.value.push({ role: 'assistant', content: res.reply || '…' })
-  } catch {
-    messages.value.push({ role: 'assistant', content: 'Fehler bei der Anfrage.' })
-  } finally {
-    loading.value = false
-    scrollToBottom()
-    nextTick(() => inputEl.value?.focus())
-  }
-}
 </script>
 
 <template>
@@ -250,7 +222,12 @@ async function send() {
           @input="autoGrow"
           @keydown.enter.exact.prevent="send"
         ></textarea>
-        <button :disabled="!input.trim() || loading" @click="send">➤</button>
+        <button
+          :disabled="!input.trim() && !loading"
+          :class="{ cancel: loading }"
+          :title="loading ? 'Abbrechen' : 'Senden'"
+          @click="send"
+        >{{ loading ? '✕' : '➤' }}</button>
       </div>
     </div>
   </div>
@@ -498,56 +475,13 @@ async function send() {
   color: var(--text-muted);
 }
 
-/* --- Markdown (Sections + Chat) --- */
+/* --- Markdown: Basis global (assets/markdown.css), hier nur Lese-Ansicht-Overrides --- */
-.markdown :deep(p) {
-  margin: 0 0 0.5em;
-}
-
-.markdown :deep(p:last-child) {
-  margin-bottom: 0;
-}
-
-.markdown :deep(ul),
-.markdown :deep(ol) {
-  margin: 0.3em 0;
-  padding-left: 1.2em;
-}
-
-.markdown :deep(li) {
-  margin: 0.15em 0;
-}
-
-.markdown :deep(code) {
-  background: var(--border);
-  padding: 1px 4px;
-  border-radius: 4px;
-  font-family: "SF Mono", Consolas, monospace;
-  font-size: 0.85em;
-  /* Lange Bezeichner (Namespaces, Pfade) dürfen umbrechen statt zu überlaufen */
-  overflow-wrap: anywhere;
-}
 
+/* Breite Lese-Ansicht: Code scrollt horizontal statt umzubrechen */
 .markdown :deep(pre) {
-  background: var(--code-bg, #1e2330);
+  white-space: pre;
-  color: var(--code-fg, #e6e8ee);
+  overflow-wrap: normal;
-  padding: 10px 12px;
-  border-radius: 8px;
   overflow-x: auto;
-  margin: 0.5em 0;
-}
-
-.markdown :deep(pre code) {
-  background: none;
-  padding: 0;
-  color: inherit;
-  font-size: 0.85em;
-}
-
-.markdown :deep(h1),
-.markdown :deep(h2),
-.markdown :deep(h3) {
-  font-size: 0.95em;
-  margin: 0.6em 0 0.3em;
 }
 
 /* „Beispiel"-Überschriften in Karten als dezentes Uppercase-Label */
@@ -559,21 +493,6 @@ async function send() {
   margin: 0.9em 0 0.35em;
 }
 
-.markdown :deep(a) {
-  color: var(--accent-hover);
-}
-
-.markdown :deep(table) {
-  border-collapse: collapse;
-  font-size: 0.95em;
-}
-
-.markdown :deep(th),
-.markdown :deep(td) {
-  border: 1px solid var(--border-strong);
-  padding: 2px 6px;
-}
-
 /* Lesbarkeit: ~17px Fließtext, Zeilenhöhe 1.6, Textspalte max. ~70 Zeichen —
    Code-Blöcke dürfen die volle Kartenbreite nutzen */
 .section-body {
@@ -627,6 +546,14 @@ async function send() {
   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;
@@ -756,4 +683,8 @@ async function send() {
   opacity: 0.4;
   cursor: not-allowed;
 }
+
+.chat-input button.cancel {
+  background: var(--danger);
+}
 </style>

frontend/src/components/TopicSidebar.vue

@@ -1,5 +1,6 @@
 <script setup>
 import { ref, computed } from 'vue'
+import { useConfirm } from '../composables/useConfirm.js'
 
 const props = defineProps({
   topics: { type: Array, required: true },
@@ -7,6 +8,8 @@ const props = defineProps({
   selectedTopic: { type: String, default: null },
   stats: { type: Object, default: null },
   fortschritt: { type: Object, default: () => ({}) },
+  locks: { type: Object, default: () => ({}) },
+  uiError: { type: String, default: null },
   doneByFormat: { type: Object, default: () => ({}) },
   latestByFormat: { type: Object, default: () => ({}) },
   allGuides: { type: Array, default: () => [] },
@@ -19,7 +22,7 @@ const props = defineProps({
   providers: { type: Array, default: () => [] },
 })
 
-const emit = defineEmits(['select', 'create', 'formatClick', 'bausteineClick', 'cancelBausteine', 'resetBausteine', 'deleteTopic', 'deleteProject', 'cancelGuide', 'deleteGuide', 'dismissError', 'preview', 'openElements', 'togglePin', 'sidebarLeave', 'toggleDark', 'setProvider'])
+const emit = defineEmits(['select', 'create', 'formatClick', 'bausteineClick', 'cancelBausteine', 'resetBausteine', 'deleteTopic', 'deleteProject', 'cancelGuide', 'deleteGuide', 'dismissError', 'dismissUiError', 'preview', 'openElements', 'togglePin', 'sidebarLeave', 'toggleDark', 'setProvider'])
 
 function providerAvailable(id) {
   const p = props.providers.find((x) => x.id === id)
@@ -53,31 +56,18 @@ const bausteineState = computed(() => {
   return props.bausteine.ready ? 'done' : 'none'
 })
 
+// Nur FREMDE Themen — das gewählte Thema zeigt seinen Fortschritt inline an der Zeile
 const activeGenerations = computed(() => {
-  const bausteinLines = props.activeBausteine.map(
+  const bausteinLines = props.activeBausteine
-    (b) => `${b.topic} – Bausteine: ${b.progress || 'Wartend…'}`,
+    .filter((b) => b.topic !== props.selectedTopic)
-  )
+    .map((b) => `${b.topic} – Bausteine: ${b.progress || 'Wartend…'}`)
   const guideLines = props.allGuides
-    .filter((g) => g.status === 'generating' || g.status === 'queued')
+    .filter((g) => (g.status === 'generating' || g.status === 'queued') && g.topic !== props.selectedTopic)
     .map((g) => `${g.topic} – ${g.format}: ${g.progress || 'Wartend…'}`)
   return [...bausteinLines, ...guideLines]
 })
 
-// Inline-Bestätigung statt confirm(): erster Klick scharfschalten („Sicher?"),
+const { pending: pendingConfirm, armOrRun } = useConfirm()
-// zweiter Klick führt aus. Browser-Dialoge können unterdrückt sein (Firefox).
-const pendingConfirm = ref(null)
-let confirmTimer = null
-
-function armOrRun(key, action) {
-  clearTimeout(confirmTimer)
-  if (pendingConfirm.value === key) {
-    pendingConfirm.value = null
-    action()
-  } else {
-    pendingConfirm.value = key
-    confirmTimer = setTimeout(() => { pendingConfirm.value = null }, 3000)
-  }
-}
 
 function confirmCancelBausteine() {
   armOrRun('bausteine', () => emit('cancelBausteine'))
@@ -131,6 +121,7 @@ function guideSteps(format) {
 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'
 }
 
@@ -147,28 +138,11 @@ function handleFormatClick(format) {
   }
 }
 
-// Lernschulden-Regeln (nur Neu-Erstellungen; Resume + Neu-Generieren bestehender erlaubt):
+// Sperr-Gründe kommen vom Backend (GET /guides/locks) — die Regeln existieren
-// Progression pro Thema (MiniGuide → Guide → FullGuide) + max. 3 offene je Format.
+// nur noch dort. Solange locks noch nicht geladen sind: Button frei, das
-const VORSTUFE = { Guide: 'MiniGuide', FullGuide: 'Guide' }
+// Backend weist ungültige Starts ohnehin ab (sichtbar über uiError).
-
-function offeneGuides(format) {
-  const f = props.stats?.formate?.[format]
-  return (f?.erstellt ?? 0) - (f?.absolviert ?? 0)
-}
-
 function playLock(format) {
-  if (format === 'OnePager') return null
+  return props.locks?.[format] ?? null
-  if (!props.bausteine.ready) return 'Erst Bausteine erstellen'
-  if (props.doneByFormat[format] || abgebrochen(format)) return null
-  const vorstufe = VORSTUFE[format]
-  if (vorstufe && !props.fortschritt?.[vorstufe]) {
-    return `Erst den ${vorstufe} dieses Themas absolvieren`
-  }
-  const offen = offeneGuides(format)
-  if (offen >= 3) {
-    return `Erst ${format}s absolvieren — ${offen} offen (max. 3)`
-  }
-  return null
 }
 
 function handlePlay(format) {
@@ -192,6 +166,9 @@ function handleDelete(format) {
     )
     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)
     }
@@ -253,12 +230,24 @@ function confirmDeleteProject(name) {
       >{{ 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>
+      </div>
       <div class="progress-info" v-if="activeGenerations.length">
         <div v-for="(line, i) in activeGenerations" :key="i">{{ line }}</div>
       </div>
-      <div class="format-row bausteine-row ord-bausteine">
+      <div
+        class="format-row bausteine-row ord-bausteine"
+        :class="{ 'is-active': bausteineState === 'generating' || bausteine.partial }"
+      >
         <div class="format-name bausteine-name">
           <span class="format-label">Bausteine</span>
+          <span
+            v-if="bausteine.partial && bausteineState !== 'generating'"
+            class="resume-badge"
+            title="Abgebrochen — ▶ setzt fort"
+          >Pausiert</span>
           <span class="step-dots">
             <span
               v-for="s in (bausteine.steps || [])"
@@ -293,14 +282,22 @@ function confirmDeleteProject(name) {
           </template>
         </div>
       </div>
-      <div v-if="bausteine.error" class="format-error ord-bausteine">
+      <div v-if="bausteineState === 'generating'" class="format-progress ord-bausteine">
+        {{ bausteine.progress || 'Wartend…' }}
+      </div>
+      <div v-if="bausteine.error && !bausteine.error.startsWith('Abgebrochen')" class="format-error ord-bausteine">
         <span class="format-error-text">{{ bausteine.error }}</span>
       </div>
 <!-- OnePager (unabhängig von Bausteinen) steht per CSS-order vor der Bausteine-Zeile -->
       <div v-for="f in formats" :key="f.key" :style="{ order: f.key === 'OnePager' ? 1 : 3 }">
-        <div :class="['format-row', 'fmt-' + guideStatus(f.key)]">
+        <div :class="['format-row', 'fmt-' + guideStatus(f.key), { 'fmt-paused': abgebrochen(f.key) }]">
           <button class="format-name" @click="handleFormatClick(f.key)">
             <span class="format-label">{{ f.label }}</span>
+            <span
+              v-if="abgebrochen(f.key)"
+              class="resume-badge"
+              title="Abgebrochen — ▶ setzt fort"
+            >Pausiert</span>
             <span class="step-dots" v-if="guideSteps(f.key).length">
               <span
                 v-for="s in guideSteps(f.key)"
@@ -311,11 +308,12 @@ function confirmDeleteProject(name) {
               ></span>
             </span>
             <span
-              v-if="guideStatus(f.key) !== 'none'"
+              v-if="guideStatus(f.key) !== 'none' || abgebrochen(f.key)"
               class="format-x"
               :class="{ armed: pendingConfirm === 'fmt-' + f.key }"
               @click.stop="handleDelete(f.key)"
-              :title="guideStatus(f.key) === 'generating' || guideStatus(f.key) === 'queued' ? 'Abbrechen' : 'Löschen'"
+              :title="guideStatus(f.key) === 'generating' || guideStatus(f.key) === 'queued' ? 'Abbrechen'
+                : abgebrochen(f.key) ? 'Fortschritt löschen' : 'Löschen'"
             >{{ pendingConfirm === 'fmt-' + f.key ? 'Sicher?' : '×' }}</span>
           </button>
           <div class="format-actions">
@@ -329,6 +327,10 @@ function confirmDeleteProject(name) {
             </template>
           </div>
         </div>
+        <div
+          v-if="guideStatus(f.key) === 'generating' || guideStatus(f.key) === 'queued'"
+          class="format-progress"
+        >{{ latestByFormat[f.key]?.progress || 'Wartend…' }}</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>
@@ -666,6 +668,35 @@ function confirmDeleteProject(name) {
   animation: pulse 1.5s ease-in-out infinite;
 }
 
+/* Abgewiesene Aktion (409/400) — oberhalb aller Format-Zeilen */
+.ui-error {
+  order: 0;
+  padding: 0.4rem 0.75rem;
+  background: var(--warning-soft);
+}
+
+/* Fortschritts-Text direkt unter der laufenden Format-Zeile */
+.format-progress {
+  padding: 0 0.75rem 5px calc(0.75rem + 8px);
+  font-size: 0.72rem;
+  color: var(--warning);
+  line-height: 1.3;
+  animation: pulse 1.5s ease-in-out infinite;
+}
+
+.resume-badge {
+  flex: 0 0 auto;
+  font-size: 0.6rem;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.03em;
+  color: var(--warning);
+  background: var(--warning-soft);
+  border: 1px solid var(--warning-border);
+  border-radius: 4px;
+  padding: 1px 5px;
+}
+
 .format-row {
   display: flex;
   align-items: center;
@@ -706,6 +737,14 @@ function confirmDeleteProject(name) {
   display: inline;
 }
 
+/* Laufend/pausiert: × immer zeigen — Hover gibt es auf Touch nicht */
+.fmt-generating .format-x,
+.fmt-queued .format-x,
+.fmt-paused .format-x,
+.bausteine-row.is-active .format-x {
+  display: inline;
+}
+
 .format-x.armed,
 .format-error-x.armed,
 .delete-topic.armed {

frontend/src/components/elements/ElementChatTab.vue

@@ -0,0 +1,147 @@
+<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 } = 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">
+      <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

@@ -0,0 +1,458 @@
+<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

@@ -0,0 +1,164 @@
+<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

@@ -0,0 +1,198 @@
+<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,6 +1,6 @@
 <script setup>
 import { ref, nextTick } from 'vue'
-import { renderMarkdown } from '../markdown.js'
+import { renderMarkdown } from '../../markdown.js'
 
 const props = defineProps({
   change: { type: Object, required: true },
@@ -175,38 +175,10 @@ function submit() {
   cursor: not-allowed;
 }
 
-/* Markdown in der Vorschau */
+/* Markdown: Basis global (assets/markdown.css); kompakte Vorschau-Code-Blöcke */
-.markdown :deep(p) {
-  margin: 0 0 0.4em;
-}
-
-.markdown :deep(p:last-child) {
-  margin-bottom: 0;
-}
-
-.markdown :deep(code) {
-  background: var(--border);
-  padding: 1px 4px;
-  border-radius: 4px;
-  font-family: "SF Mono", Consolas, monospace;
-  font-size: 0.85em;
-  overflow-wrap: anywhere;
-}
-
 .markdown :deep(pre) {
-  background: var(--code-bg, #1e2330);
-  color: var(--code-fg, #e6e8ee);
   padding: 6px 8px;
   border-radius: 6px;
-  white-space: pre-wrap;
-  overflow-wrap: anywhere;
   margin: 0.3em 0;
 }
-
-.markdown :deep(pre code) {
-  background: none;
-  padding: 0;
-  color: inherit;
-  font-size: 0.85em;
-}
 </style>

frontend/src/components/elements/ElementsSidebar.vue

@@ -0,0 +1,156 @@
+<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

@@ -0,0 +1,71 @@
+import { ref, nextTick } from 'vue'
+
+// 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.
+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
+  let run = 0 // laufende Anfrage identifizieren; Abbruch ignoriert ihr Ergebnis
+
+  async function scrollToBottom() {
+    await nextTick()
+    if (messagesEl.value) messagesEl.value.scrollTop = messagesEl.value.scrollHeight
+  }
+
+  function autoGrow(max = 140) {
+    const el = inputEl.value
+    if (!el) return
+    el.style.height = 'auto'
+    el.style.height = Math.min(el.scrollHeight, max) + 'px'
+  }
+
+  function cancel() {
+    run++
+    loading.value = false
+    messages.value.push({ role: 'assistant', content: 'Abgebrochen.' })
+  }
+
+  function reset() {
+    run++
+    loading.value = false
+    messages.value = []
+    input.value = ''
+  }
+
+  async function send() {
+    if (loading.value) { // zweiter Klick = abbrechen
+      cancel()
+      return null
+    }
+    const text = input.value.trim()
+    if (!text) return null
+    const current = ++run
+    messages.value.push({ role: 'user', content: text })
+    input.value = ''
+    nextTick(() => autoGrow())
+    loading.value = true
+    scrollToBottom()
+    try {
+      const res = await performRequest(messages.value)
+      if (current !== run) return null
+      messages.value.push({ role: 'assistant', content: res.reply || '…' })
+      return res
+    } catch {
+      if (current !== run) return null
+      messages.value.push({ role: 'assistant', content: 'Fehler bei der Anfrage.' })
+      return null
+    } finally {
+      if (current === run) {
+        loading.value = false
+        scrollToBottom()
+        nextTick(() => inputEl.value?.focus())
+      }
+    }
+  }
+
+  return { messages, input, loading, messagesEl, inputEl, send, cancel, reset, scrollToBottom, autoGrow }
+}

frontend/src/composables/useConfirm.js

@@ -0,0 +1,32 @@
+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).
+export function useConfirm(timeoutMs = 3000) {
+  const pending = ref(null) // aktuell scharfgeschalteter Key
+  let timer = null
+
+  function armOrRun(key, action) {
+    clearTimeout(timer)
+    if (pending.value === key) {
+      pending.value = null
+      action()
+    } else {
+      pending.value = key
+      timer = setTimeout(() => { pending.value = null }, timeoutMs)
+    }
+  }
+
+  function isArmed(key) {
+    return pending.value === key
+  }
+
+  function reset() {
+    clearTimeout(timer)
+    pending.value = null
+  }
+
+  onUnmounted(() => clearTimeout(timer))
+
+  return { pending, isArmed, armOrRun, reset }
+}

frontend/src/composables/usePolling.js

@@ -0,0 +1,44 @@
+import { onUnmounted } from 'vue'
+
+// Polling mit Visibility-Pause: Tab unsichtbar → stoppen; wieder sichtbar →
+// sofortiger Tick, dann weiter, falls isActive(). Stoppt selbst, sobald
+// isActive() nach einem Tick false liefert.
+export function usePolling(tick, isActive, interval = 3000) {
+  let timer = null
+
+  function stop() {
+    if (timer) {
+      clearInterval(timer)
+      timer = null
+    }
+  }
+
+  function start() {
+    stop()
+    timer = setInterval(async () => {
+      await tick()
+      if (!isActive()) stop()
+    }, interval)
+  }
+
+  function running() {
+    return !!timer
+  }
+
+  async function onVisibility() {
+    if (document.hidden) {
+      stop()
+    } else {
+      await tick()
+      if (isActive()) start()
+    }
+  }
+
+  document.addEventListener('visibilitychange', onVisibility)
+  onUnmounted(() => {
+    stop()
+    document.removeEventListener('visibilitychange', onVisibility)
+  })
+
+  return { start, stop, running }
+}

frontend/src/main.js

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

templates/Format/Section.md

@@ -3,7 +3,15 @@ SECTION-AUFBAU
 Jeder Baustein wird GENAU eine Section mit:
 1. Titel — der Baustein-Titel (kommt aus dem Marker, nicht in den Body schreiben)
 2. Beschreibung — was es ist und wozu: MAXIMAL 1–2 Sätze
-3. Beispiele — KURZ und SIMPEL: wenige Zeilen Code, das Minimalbeispiel, keine Realwelt-Komplexität. Höchstens 1 knapper Satz Einordnung dazu. Ein Beispiel pro relevanter Variante: simple Bausteine eines, variantenreiche mehrere. Geordnet vom Üblichen zum Speziellen. Weglassen, wenn ohne Mehrwert.
+3. Beispiele — KURZ und SIMPEL: das Minimalbeispiel im themengerechten Format (siehe BEISPIELFORMAT), keine Realwelt-Komplexität. Höchstens 1 knapper Satz Einordnung dazu. Ein Beispiel pro relevanter Variante: simple Bausteine eines, variantenreiche mehrere. Geordnet vom Üblichen zum Speziellen. Weglassen, wenn ohne Mehrwert.
+
+BEISPIELFORMAT — am Thema ausrichten, nicht pauschal an Code:
+- Code-/Tool-Thema (Sprache, Framework, CLI, Konfiguration): Codeblock mit Sprachangabe, wenige Zeilen, Minimalbeispiel.
+- Sprach-Thema (Vokabeln, Grammatik, Formulierungen): 1–3 Beispielsätze oder ein Mini-Dialog, fremdsprachiger Teil *kursiv*, deutsche Übersetzung in Klammern wo nötig.
+- Konzept-Thema (Psychologie, Kommunikation, Methoden, Theorie): ein Mini-Szenario in 2–4 Sätzen (Situation → Anwendung → Wirkung), ein Schema oder eine Formel.
+Mischthemen: pro Beispiel das Format wählen, das den Punkt am direktesten zeigt.
+Ein Beispiel ist immer KONKRET (echter Code, echte Sätze, echte Situation) — nie die Beschreibung, was ein Beispiel zeigen würde.
+Jedes Beispiel benennt seine Variante: in Code als Kommentar in der Code-Syntax (z. B. `<!-- Einzelner Absatz -->`, `// Mit Default-Wert`), in Prosa als vorangestelltes fettes Label (z. B. **Höfliche Bitte:**).
 
 Jede Section ist ATOMAR: allein verständlich, ohne dass der Leser eine andere Section gelesen hat. Test: Ergibt der Text Sinn, wenn man NUR diese Section liest? Verweise auf andere Bausteine sind erlaubt, ihr Inhalt darf aber nie vorausgesetzt werden — benutzte Begriffe in einem Halbsatz auflösen.
 
@@ -11,9 +19,9 @@ Umfang: kurz. Die Länge einer Section kommt aus der ZAHL der Beispiele (Variant
 
 Tonalität: klares Deutsch, direkt, praxisorientiert. Fachbegriffe beim ersten Auftreten kurz erklären. Keine Füllsätze, keine Einleitungsfloskeln.
 
-Markdown im Section-Body: normale Absätze, `inline-code` für Bezeichner, Codeblöcke mit Sprachangabe, **fett** sparsam für Kernaussagen. Keine eigenen Überschriften außer `### Beispiel` bzw. `### Beispiele` vor den Beispielen.
+Markdown im Section-Body: normale Absätze, `inline-code` für Bezeichner, Codeblöcke mit Sprachangabe NUR für Code-Beispiele — Beispielsätze, Dialoge und Szenarien als normaler Text, NIE in einen Codeblock zwingen. **fett** sparsam für Kernaussagen. Keine eigenen Überschriften außer `### Beispiel` bzw. `### Beispiele` vor den Beispielen.
 
-Beispiel einer fertigen Section (nur der Body):
+Beispiel einer fertigen Section (Code-Thema, nur der Body):
 
 Arrays speichern mehrere Werte unter einem Namen. PHP unterscheidet indizierte Arrays (`[0 => 'a']`) und assoziative Arrays (`['key' => 'wert']`) — intern sind beide geordnete Hashmaps.
 
@@ -24,3 +32,13 @@ $preise['kirsche'] = 3.90;   // ergänzen
 echo $preise['apfel'];       // 1.2
 ```
 Assoziative Arrays sind der Arbeitsalltag: Datenbankzeilen, Konfiguration, JSON.
+
+Beispiel einer fertigen Section (Konzept-Thema, nur der Body):
+
+Paraphrasieren wiederholt die Aussage des Gegenübers in eigenen Worten, um Verständnis zu prüfen und Eskalation zu bremsen.
+
+### Beispiel
+**Vorwurf abfedern:**
+A: „Nie hältst du dich an Absprachen!"
+B: „Du bist sauer, weil ich den Termin gestern verschoben habe — richtig?"
+Die Paraphrase bestätigt nicht den Vorwurf, sondern prüft die Botschaft dahinter.

templates/Prompt/Bausteine-Auswahl-Check.md

@@ -7,7 +7,7 @@ KONSOLIDIERTE LISTE:
 {auswahl}
 
 Prüfe genau zwei Dinge:
-1. FEHLT ein Konzept, das in den Recherchen vorkommt, aber in der konsolidierten Liste nicht enthalten ist — auch nicht unter anderem Titel oder in einem Sammeleintrag?
+1. FEHLT ein Konzept, das in den Recherchen vorkommt, aber in der konsolidierten Liste nicht enthalten ist — auch nicht unter anderem Titel oder in einem Sammeleintrag? Die Zusammenfassung mehrerer Mikro-Einträge zu einer Lerneinheit ist KEIN Verlust — fehlend ist ein Konzept nur, wenn es nirgends, auch nicht innerhalb eines zusammengefassten Bausteins, enthalten ist.
 2. Beschreiben mehrere Einträge der Liste DASSELBE Konzept? Der beste bleibt, die übrigen werden gestrichen.
 
 Schreibe NUR die JSON-Datei nach: {out_path}

templates/Prompt/Bausteine-Auswahl.md

@@ -4,9 +4,10 @@ Drei Recherche-Agenten haben unabhängig voneinander die Bausteine des Themas "{
 
 Regeln:
 - Vereinige die Listen: erkenne gleiche Konzepte unter verschiedenen Titeln und führe sie zu einem Baustein zusammen.
-- Ein Baustein löst GENAU EIN PROBLEM. Einträge, die Varianten derselben Lösung sind, werden zu EINEM Baustein zusammengefasst (richtig: ein Baustein `<input>` für alle Typen; falsch: je ein Eintrag pro input-Typ, aber auch Sammeleinträge, die mehrere Probleme mischen).
+- Ein Baustein löst GENAU EIN PROBLEM. Einträge, die Varianten derselben Lösung sind, werden zu EINEM Baustein zusammengefasst (richtig: ein Baustein `<input>` für alle Typen, ein Baustein "Modalverben" für alle Modalverben; falsch: je ein Eintrag pro input-Typ oder pro Verb, aber auch Sammeleinträge, die mehrere Probleme mischen).
 - Ein Baustein ist ATOMAR: genau eine Idee, vollständig in sich. Test: Man kann nichts entfernen, ohne ihn unvollständig zu machen — und es fehlt nichts, um ihn zu verstehen.
-- Verwirf Bausteine ohne Quelle oder die erfunden wirken. Behalte im Zweifel, was mindestens eine Recherche belegt.
+- KONSOLIDIERE die Granularität: ein Baustein ist eine LERNEINHEIT, kein Lexikon-Eintrag. Liefern die Recherchen dutzende Mikro-Einträge derselben Sorte (eine CSS-Eigenschaft, ein Verb, eine Geste pro Eintrag), fasse sie nach Problem zusammen (richtig: "Flexbox-Ausrichtung" statt sechs Einträge für justify-content, align-items, …). Mehr als ~150 Bausteine sind fast immer ein Granularitäts-Problem — prüfe dann gezielt auf solche Serien.
+- Verwirf Bausteine, die erfunden wirken. Eine fehlende Quelle allein ist kein Streichgrund, wenn mindestens zwei Recherchen den Baustein unabhängig nennen. Behalte im Zweifel, was mindestens eine Recherche belegt.
 - KEINE Kategorien, KEINE Bewertung — eine flache, durchnummerierte Liste.
 - Lass die Quellen weg. Titel und Kurzbeschreibung (max. ~12 Wörter) auf DEUTSCH (Code-Bezeichner bleiben original). Jeder Titel muss EINDEUTIG sein.
 

templates/Prompt/Bausteine-Quelle-Thema.md

@@ -1 +1 @@
-Recherchiere per Websuche und gehe systematisch vor: arbeite die Struktur der offiziellen Dokumentation ab (Handbuch-Kapitel, Feature-Übersichten, Release Notes der letzten Versionen) und erfasse jeden Baustein, dem ein Anwender begegnen kann — von Grundlagen bis Spezialfälle. Achte darauf, dass Versionsangaben und Fakten aktuell sind.
+Recherchiere per Websuche und gehe systematisch vor: arbeite die Struktur der maßgeblichen Quellen ab — bei Software/Tools die offizielle Dokumentation (Handbuch-Kapitel, Feature-Übersichten, Release Notes der letzten Versionen), bei Sprachen und Konzept-Themen Lehrbücher, Curricula und Standardwerke — und erfasse jeden Baustein, dem ein Lerner begegnen kann — von Grundlagen bis Spezialfälle. Achte darauf, dass Versionsangaben bzw. der fachliche Stand aktuell sind.

templates/Prompt/Bausteine-Recherche.md

@@ -1,13 +1,14 @@
-Ermittle ALLE Bausteine (Konzepte/Funktionen/Features) des Themas "{topic}" für einen Lern-Guide.
+Ermittle ALLE Bausteine (Konzepte, Techniken, Regeln, Funktionen — die kleinsten lernbaren Einheiten) des Themas "{topic}" für einen Lern-Guide.
 
 {source}
 
 Regeln:
-- Ein Baustein löst GENAU EIN PROBLEM. Varianten derselben Lösung gehören in den einen Baustein, nicht als eigene Einträge (richtig: `<p>` ist ein Baustein, `<input>` mit allen Typen ist ein Baustein; falsch: 21 Einträge für jeden input-Typ, aber auch Sammeleinträge, die mehrere Probleme mischen).
+- Ein Baustein löst GENAU EIN PROBLEM. Varianten derselben Lösung gehören in den einen Baustein, nicht als eigene Einträge (richtig: `<p>` ist ein Baustein, `<input>` mit allen Typen ist ein Baustein, "Ich-Botschaften" ist ein Baustein, "Present Perfect" mit allen Signalwörtern ist ein Baustein; falsch: 21 Einträge für jeden input-Typ oder je ein Eintrag pro unregelmäßigem Verb, aber auch Sammeleinträge, die mehrere Probleme mischen).
 - Ein Baustein ist ATOMAR: genau eine Idee, vollständig in sich. Test: Man kann nichts entfernen, ohne ihn unvollständig zu machen — und es fehlt nichts, um ihn zu verstehen.
+- Granularität: ein Baustein ist eine LERNEINHEIT, kein Lexikon-Eintrag. Familien, die zusammen gelernt werden (z. B. die font-*-Eigenschaften, die Modalverben), sind EIN Baustein.
 - KEINE Kategorien, KEINE Bewertung, KEINE Reihenfolge nach Wichtigkeit — nur eine flache, durchnummerierte Liste.
 - Es gibt KEINE Ziel-Anzahl. Höre erst auf, wenn die Recherche nichts Neues mehr hergibt.
-- Erfinde nichts: nimm nur Bausteine auf, die du in der Recherche belegt hast. Notiere pro Baustein die Quelle (URL bzw. Dateipfad).
+- Erfinde nichts: nimm nur Bausteine auf, die du in der Recherche belegt hast. Notiere pro Baustein die Quelle (URL bzw. Dateipfad). Gibt es keine Einzel-Quelle, reicht die Sammel-Quelle (Handbuch-Kapitel, Lehrbuch, Übersichtsseite, Verzeichnis).
 - Schreibe Titel und Beschreibung auf DEUTSCH (Fachbegriffe/Code-Bezeichner bleiben original).
 - Beschreibung maximal ~12 Wörter.
 

templates/Prompt/Element-Chat.md

@@ -9,7 +9,7 @@ BISHERIGER CHAT-VERLAUF:
 Setze die letzte Nutzer-Anweisung in Änderungs-Vorschläge um. Halte die Element-Regeln ein:
 1. title — prägnanter Titel (max. 8 Wörter, reiner Text ohne Markdown/Backticks)
 2. description — was es ist und wozu: MAXIMAL 1–2 Sätze
-3. examples — KURZ und SIMPEL: wenige Zeilen Code, das Minimalbeispiel. Jedes beginnt mit einem kurzen Kommentar in der Code-Syntax (z. B. `<!-- Einzelner Absatz -->`), der die Variante benennt. Als Codeblock mit Sprachangabe (```sprache).
+3. examples — KURZ und SIMPEL: das Minimalbeispiel im themengerechten Format (Codeblock mit Sprachangabe bei Code-Themen, sonst Beispielsätze/Mini-Dialog/Mini-Szenario als normaler Text). Jedes mit Varianten-Label: Code-Kommentar (z. B. `<!-- Einzelner Absatz -->`) bzw. **fettes** Label (z. B. **Höfliche Bitte:**).
 4. hints — jeder Hinweis muss WICHTIG oder NÜTZLICH sein. Telegrammstil: nur die Kernaussage. Beispiel: "Keine Blockelemente in `<p>`."
 
 Umfang: SO LANG WIE NÖTIG und SO KURZ WIE MÖGLICH. Markdown: `inline-code` für Bezeichner, Tags und Befehle — IMMER in Backticks. Tonalität: klares Deutsch, direkt, keine Füllsätze.
@@ -17,8 +17,8 @@ Umfang: SO LANG WIE NÖTIG und SO KURZ WIE MÖGLICH. Markdown: `inline-code` fü
 Jeder Vorschlag:
 - text: kurz, was geändert wird (max. 12 Wörter, reiner Text)
 - action: "entfernen" | "anpassen" | "hinzufuegen"
-- target: "title" | "description" | "examples" | "hints" | "aufgabe" | "loesung"
+- target: "title" | "description" | "examples" | "hints"
-- index: 0-basierte Position im AKTUELLEN examples- bzw. hints-Array (bei title/description/aufgabe/loesung und hinzufuegen: null)
+- index: 0-basierte Position im AKTUELLEN examples- bzw. hints-Array (bei title/description und hinzufuegen: null)
 - content: der neue vollständige Inhalt (bei entfernen: leer)
 
 "entfernen" nur für examples/hints. Nur Vorschläge machen, die die Nutzer-Anweisung verlangt.

templates/Prompt/Element-Check.md

@@ -6,12 +6,12 @@ AKTUELLES ELEMENT (JSON):
 KONTEXT (Auszüge aus dem Themen-Material):
 {context}
 
-RECHERCHE — sammle breit alle Kandidaten: fehlende Kernaussagen, wichtige Varianten, typische Stolperfallen, Best Practices. Fehlt eine Übungsaufgabe (aufgabe) oder deren Lösung (loesung), schlage sie vor. Lieber einen Kandidaten zu viel als einen zu wenig — die Bewertung passiert in einem zweiten Schritt. Nichts vorschlagen, was das Element schon enthält.
+RECHERCHE — sammle breit alle Kandidaten: fehlende Kernaussagen, wichtige Varianten, typische Stolperfallen, Best Practices. Lieber einen Kandidaten zu viel als einen zu wenig — die Bewertung passiert in einem zweiten Schritt. Nichts vorschlagen, was das Element schon enthält.
 
 Jeder Kandidat:
 - text: kurze Beschreibung der Lücke (max. 12 Wörter, reiner Text)
-- target: "description" | "examples" | "hints" | "aufgabe" | "loesung"
+- target: "description" | "examples" | "hints"
-- content: fertiger Inhalt zum Einfügen. SO KURZ WIE MÖGLICH, so lang wie nötig. Markdown: `inline-code` für Bezeichner, examples als Codeblock mit Sprachangabe (```sprache), beginnend mit kurzem Kommentar zur Variante (z. B. `<!-- Einzelner Absatz -->`), hints nur wenn WICHTIG oder NÜTZLICH, im Telegrammstil (nur Kernaussage, z. B. "Keine Blockelemente in `<p>`."). aufgabe: EINE konkrete, in Minuten lösbare Übungsaufgabe; loesung: die knappe Musterlösung dazu. Tags/Bezeichner im Fließtext IMMER in Backticks.
+- content: fertiger Inhalt zum Einfügen. SO KURZ WIE MÖGLICH, so lang wie nötig. Markdown: `inline-code` für Bezeichner, examples im themengerechten Format (Codeblock mit Sprachangabe bei Code, sonst Beispielsätze/Mini-Szenario als normaler Text), jeweils mit Varianten-Label (Code-Kommentar bzw. **fettes** Label), hints nur wenn WICHTIG oder NÜTZLICH, im Telegrammstil (nur Kernaussage, z. B. "Keine Blockelemente in `<p>`."). Tags/Bezeichner im Fließtext IMMER in Backticks.
 
 Gib NUR gültiges JSON aus, ohne Code-Fence, ohne weiteren Text:
 {{"suggestions": [{{"text": "...", "target": "hints", "content": "..."}}]}}

templates/Prompt/Element-Create.md

@@ -9,10 +9,16 @@ KONTEXT (Auszüge aus dem Themen-Material):
 Erstelle GENAU EIN Element zum Stichwort:
 1. title — prägnanter Titel (max. 8 Wörter, reiner Text ohne Markdown/Backticks)
 2. description — was es ist und wozu: MAXIMAL 1–2 Sätze
-3. examples — GENAU EIN Beispiel: KURZ und SIMPEL, wenige Zeilen Code, das Minimalbeispiel, keine Realwelt-Komplexität. Beginnt mit einem kurzen Kommentar in der Code-Syntax (z. B. `<!-- Einzelner Absatz -->`, `// Mit Default-Wert`), der die Variante benennt.
+3. examples — GENAU EIN Beispiel: KURZ und SIMPEL, das Minimalbeispiel im themengerechten Format (siehe BEISPIELFORMAT), keine Realwelt-Komplexität.
 4. hints — IMMER leere Liste. Hinweise ergänzt der Nutzer später selbst. (Falls je gefordert: TELEGRAMMSTIL, max. 10 Wörter.)
-5. aufgabe — GENAU EINE kleine Übungsaufgabe zum Konzept: konkret, in wenigen Minuten lösbar, prüft das Verständnis. Markdown, Code als Codeblock mit Sprachangabe.
+
-6. loesung — die Musterlösung zur Aufgabe: knapp, nachvollziehbar, Schritt für Schritt nur wo nötig. Code als Codeblock mit Sprachangabe.
+BEISPIELFORMAT — am Thema ausrichten, nicht pauschal an Code:
+- Code-/Tool-Thema (Sprache, Framework, CLI, Konfiguration): Codeblock mit Sprachangabe, wenige Zeilen, Minimalbeispiel.
+- Sprach-Thema (Vokabeln, Grammatik, Formulierungen): 1–3 Beispielsätze oder ein Mini-Dialog, fremdsprachiger Teil *kursiv*, deutsche Übersetzung in Klammern wo nötig.
+- Konzept-Thema (Psychologie, Kommunikation, Methoden, Theorie): ein Mini-Szenario in 2–4 Sätzen (Situation → Anwendung → Wirkung), ein Schema oder eine Formel.
+Mischthemen: pro Beispiel das Format wählen, das den Punkt am direktesten zeigt.
+Ein Beispiel ist immer KONKRET (echter Code, echte Sätze, echte Situation) — nie die Beschreibung, was ein Beispiel zeigen würde.
+Jedes Beispiel benennt seine Variante: in Code als Kommentar in der Code-Syntax (z. B. `<!-- Einzelner Absatz -->`, `// Mit Default-Wert`), in Prosa als vorangestelltes fettes Label (z. B. **Höfliche Bitte:**).
 
 Das Element ist ATOMAR: allein verständlich, ohne dass der Leser etwas anderes gelesen hat. Benutzte Begriffe in einem Halbsatz auflösen.
 
@@ -20,7 +26,7 @@ Umfang: SO KURZ WIE MÖGLICH, so lang wie nötig — gilt für description, exam
 
 Tonalität: klares Deutsch, direkt, praxisorientiert. Fachbegriffe beim ersten Auftreten kurz erklären. Keine Füllsätze, keine Einleitungsfloskeln.
 
-Markdown in description und examples: normale Absätze, `inline-code` für Bezeichner, Codeblöcke mit Sprachangabe (```sprache), **fett** sparsam für Kernaussagen. Keine Überschriften. Code-Beispiele IMMER als Codeblock, nie als Inline-Code. Bezeichner, Tags und Befehle (z. B. `<p>`, `git add`) im Fließtext IMMER in Backticks — nie nackt.
+Markdown in description und examples: normale Absätze, `inline-code` für Bezeichner, **fett** sparsam für Kernaussagen. Keine Überschriften. Code-Beispiele IMMER als Codeblock mit Sprachangabe (```sprache), nie als Inline-Code; Prosa-Beispiele (Sätze, Dialoge, Szenarien) als normaler Text, NIE in einen Codeblock zwingen. Bezeichner, Tags und Befehle (z. B. `<p>`, `git add`) im Fließtext IMMER in Backticks — nie nackt.
 
 Gib NUR gültiges JSON aus, ohne Code-Fence, ohne weiteren Text:
-{{"title": "...", "description": "...", "examples": ["```sprache\n...\n```"], "hints": [], "aufgabe": "...", "loesung": "..."}}
+{{"title": "...", "description": "...", "examples": ["```sprache\n...\n``` ODER **Variante:** Prosa-Beispiel"], "hints": []}}

templates/Prompt/Element-Refine.md

@@ -11,7 +11,7 @@ ANWEISUNG DES NUTZERS:
 
 Passe den Vorschlag gemäß der Anweisung an. Behalte action/target/index bei, außer die Anweisung verlangt anderes.
 
-Stil-Regeln für content: SO LANG WIE NÖTIG und SO KURZ WIE MÖGLICH. `inline-code` für Bezeichner, Tags und Befehle — IMMER in Backticks. examples als Codeblock mit Sprachangabe und kurzem Varianten-Kommentar (z. B. `<!-- Einzelner Absatz -->`). hints im Telegrammstil: nur die Kernaussage.
+Stil-Regeln für content: SO LANG WIE NÖTIG und SO KURZ WIE MÖGLICH. `inline-code` für Bezeichner, Tags und Befehle — IMMER in Backticks. examples im themengerechten Format (Codeblock mit Sprachangabe NUR bei Code, sonst Beispielsätze/Mini-Szenario) mit Varianten-Label (Code-Kommentar bzw. **fettes** Label). hints im Telegrammstil: nur die Kernaussage.
 
 Felder:
 - text: kurz, was geändert wird (max. 12 Wörter, reiner Text)

templates/Prompt/Element-Stil.md

@@ -6,20 +6,27 @@ AKTUELLES ELEMENT (JSON):
 STIL-REGELN:
 1. title — prägnant, max. 8 Wörter, reiner Text ohne Markdown/Backticks
 2. description — was es ist und wozu: MAXIMAL 1–2 Sätze
-3. examples — KURZ und SIMPEL: wenige Zeilen Code, Minimalbeispiel, keine Realwelt-Komplexität. Ein Beispiel pro relevanter Variante, geordnet vom Üblichen zum Speziellen. Als Codeblock mit Sprachangabe (```sprache), nie als Inline-Code. Jedes Beispiel beginnt mit einem kurzen Kommentar in der Code-Syntax (z. B. `<!-- Einzelner Absatz -->`), der die Variante benennt.
+3. examples — KURZ und SIMPEL: das Minimalbeispiel im themengerechten Format (siehe BEISPIELFORMAT), keine Realwelt-Komplexität. Ein Beispiel pro relevanter Variante, geordnet vom Üblichen zum Speziellen. Ein Codeblock um ein Prosa-Beispiel ist ein Stil-Verstoß — ebenso ein Code-Beispiel ohne Codeblock.
+
+   BEISPIELFORMAT — am Thema ausrichten, nicht pauschal an Code:
+   - Code-/Tool-Thema (Sprache, Framework, CLI, Konfiguration): Codeblock mit Sprachangabe, wenige Zeilen, Minimalbeispiel.
+   - Sprach-Thema (Vokabeln, Grammatik, Formulierungen): 1–3 Beispielsätze oder ein Mini-Dialog, fremdsprachiger Teil *kursiv*, deutsche Übersetzung in Klammern wo nötig.
+   - Konzept-Thema (Psychologie, Kommunikation, Methoden, Theorie): ein Mini-Szenario in 2–4 Sätzen (Situation → Anwendung → Wirkung), ein Schema oder eine Formel.
+   Mischthemen: pro Beispiel das Format wählen, das den Punkt am direktesten zeigt.
+   Ein Beispiel ist immer KONKRET (echter Code, echte Sätze, echte Situation) — nie die Beschreibung, was ein Beispiel zeigen würde.
+   Jedes Beispiel benennt seine Variante: in Code als Kommentar in der Code-Syntax (z. B. `<!-- Einzelner Absatz -->`, `// Mit Default-Wert`), in Prosa als vorangestelltes fettes Label (z. B. **Höfliche Bitte:**).
 4. hints — jeder Hinweis muss WICHTIG oder NÜTZLICH sein: Stolperfalle, Merksatz oder Best Practice mit echtem Praxiswert. Selbstverständliches, Nischenwissen und Redundantes zum Element entfernen. Telegrammstil: nur die Kernaussage, Füllverben und Herleitungen streichen.
-   aufgabe — EINE konkrete, in Minuten lösbare Übungsaufgabe, die das Verständnis prüft. loesung — knappe, nachvollziehbare Musterlösung dazu. Beide: Code als Codeblock mit Sprachangabe.
    Vorher: "Browser fügen standardmäßig vertikalen Abstand vor und nach `<p>` ein — anpassbar mit `margin`."
    Nachher: "Browser-Abstand um `<p>` per `margin` anpassbar."
 5. Umfang: SO LANG WIE NÖTIG und SO KURZ WIE MÖGLICH. Jedes Wort muss seinen Platz verdienen — Füllwörter, Nebensätze ohne Informationswert und Selbstverständliches streichen. Aber: Kürze nie auf Kosten der Verständlichkeit oder Korrektheit.
-6. Markdown: `inline-code` für Bezeichner, Tags und Befehle im Fließtext (z. B. `<p>`, `git add`) — IMMER in Backticks, nie nackt. **fett** sparsam. Keine Überschriften.
+6. Markdown: `inline-code` für Bezeichner, Tags und Befehle im Fließtext (z. B. `<p>`, `git add`) — IMMER in Backticks, nie nackt. Fremdsprachige Beispielsätze *kursiv*. **fett** sparsam. Keine Überschriften.
 7. Tonalität: klares Deutsch, direkt, praxisorientiert. Keine Füllsätze.
 
 Schlage für jeden Stil-Verstoß GENAU EINE Änderung vor:
 - text: kurz, was und warum (max. 12 Wörter, reiner Text)
 - action: "entfernen" | "anpassen" | "hinzufuegen"
-- target: "title" | "description" | "examples" | "hints" | "aufgabe" | "loesung"
+- target: "title" | "description" | "examples" | "hints"
-- index: 0-basierte Position im AKTUELLEN examples- bzw. hints-Array (bei title/description/aufgabe/loesung: null; bei hinzufuegen: null)
+- index: 0-basierte Position im AKTUELLEN examples- bzw. hints-Array (bei title/description: null; bei hinzufuegen: null)
 - content: der neue/vollständige Inhalt (bei entfernen: leer)
 
 "entfernen" nur für examples/hints. "hinzufuegen" sparsam — nur wenn eine Stil-Regel es verlangt (z. B. fehlender Varianten-Kommentar gehört zu "anpassen", nicht "hinzufuegen"). Erfüllt etwas die Regeln schon: NICHT anfassen.

templates/Prompt/Element-Verify.md

@@ -13,9 +13,9 @@ Prüfe JEDEN Kandidaten kritisch:
 1. WICHTIG? Muss ein Lerner das wissen? Nice-to-haves und Nischenwissen ablehnen.
 2. REDUNDANT? Steckt die Info schon im Element oder in einem anderen Kandidaten? Ablehnen bzw. Duplikate zusammenführen.
 3. KORREKT? Fachlich falsch oder irreführend → ablehnen.
-4. PASST das target ("description" | "examples" | "hints" | "aufgabe" | "loesung")? Sonst korrigieren. Höchstens EIN Vorschlag je für "aufgabe" und "loesung".
+4. PASST das target ("description" | "examples" | "hints")? Sonst korrigieren.
 
-Behalte nur Kandidaten, die alle Prüfungen bestehen. Verbessere dabei content auf die Stil-Regeln: SO LANG WIE NÖTIG und SO KURZ WIE MÖGLICH; `inline-code` für Bezeichner; examples als Codeblock mit Sprachangabe und kurzem Varianten-Kommentar; hints im Telegrammstil (nur Kernaussage, Kürze nie auf Kosten der Verständlichkeit).
+Behalte nur Kandidaten, die alle Prüfungen bestehen. Verbessere dabei content auf die Stil-Regeln: SO LANG WIE NÖTIG und SO KURZ WIE MÖGLICH; `inline-code` für Bezeichner; examples im themengerechten Format (Codeblock mit Sprachangabe bei Code, sonst Beispielsätze/Mini-Szenario) mit Varianten-Label; hints im Telegrammstil (nur Kernaussage, Kürze nie auf Kosten der Verständlichkeit).
 
 Gib NUR gültiges JSON aus, ohne Code-Fence, ohne weiteren Text:
 {{"suggestions": [{{"text": "...", "target": "hints", "content": "..."}}]}}

templates/Prompt/Guide-Auswahl.md

@@ -7,7 +7,7 @@ BAUSTEINE (unsortiertes Inventar):
 
 Denke vom Ziel her: Was soll der Leser am Ende KÖNNEN?
 - Wähle, was der Leser dafür praktisch braucht und wirklich benutzt.
-- Lass weg: Interna (was das Werkzeug intern tut, ohne dass man es anfasst), Spezialfälle und Alternativen zum selben Problem — ein Weg reicht.
+- Lass weg: Interna (was das Werkzeug oder die Theorie intern tut, ohne dass man es selbst anfasst), Spezialfälle und Alternativen zum selben Problem — ein Weg reicht.
 - "Klingt fundamental" ist kein Kriterium. Frage stattdessen: Fasst der Leser das selbst an?
 - Verwende die Titel EXAKT so, wie sie in der Liste stehen. Keine neuen erfinden.
 

templates/Prompt/Guide-Fakten-Thema.md

@@ -1 +1 @@
-Prüfe unsichere oder veraltbare Fakten (z. B. Versionsnummern) per Websuche.
+Prüfe unsichere oder veraltbare Fakten (Versionsnummern, aktuelle Empfehlungen, Forschungsstand) per Websuche, BEVOR du sie in eine Section schreibst. Nichts Unbelegtes behaupten.

templates/Prompt/Guide-Lese-Check.md

@@ -9,7 +9,7 @@ SECTIONS:
 
 Prüfe jede Section:
 1. Ist die Beschreibung für Anfänger verständlich und maximal 1–2 Sätze?
-2. Sind die Beispiele kurz, simpel und plausibel korrekt?
+2. Sind die Beispiele kurz, simpel, plausibel korrekt — und im themengerechten Format laut Spezifikation (kein Codeblock um Prosa-Beispiele, kein Prosa-Pseudo-Beispiel, wo Code gefragt ist)?
 3. Ist das Markdown sauber (keine abgebrochenen Code-Blöcke, keine Platzhalter, kein Fremdtext)?
 
 Du PRÜFST nur und notierst Probleme — du änderst nichts. Nur echte Mängel notieren, keine Geschmacksfragen.

templates/Prompt/Guide-Sections-Fix.md

@@ -16,9 +16,7 @@ Schreibe NUR die Datei {out_path} in GENAU diesem Format — für JEDE beanstand
 Beschreibung…
 
 ### Beispiel
-```sprache
+(Beispiel im themengerechten Format laut SECTION-SPEZIFIKATION: Codeblock NUR bei Code-Themen, sonst Beispielsätze oder Mini-Szenario)
-…
-```
 
 Die Marker-Zeilen exakt so schreiben. Kein Text außerhalb der Sections.
 {extra}

templates/Prompt/Guide-Writer.md

@@ -5,7 +5,7 @@ Dir zugeteilt sind folgende Kapitel und Bausteine — verbindlich: jede zugeteil
 
 {facts}
 
-Beispiel-Tiefe für dieses Format ({format_name}): MiniGuide = nur die üblichen Varianten eines Bausteins, Guide = die gängigen Varianten, FullGuide = alle relevanten Varianten inkl. Nischenfällen.
+Beispiel-Tiefe für dieses Format ({format_name}): MiniGuide = nur die üblichen Varianten eines Bausteins, Guide = die gängigen Varianten, FullGuide = alle relevanten Varianten inkl. Nischenfällen. Eine Variante ist eine eigenständige Verwendungsform des Bausteins — Code-Variante, Satzmuster oder Anwendungsfall.
 
 SECTION-SPEZIFIKATION:
 {spec}
@@ -17,9 +17,7 @@ Schreibe NUR die Datei {out_path} in GENAU diesem Format — pro Kapitel ein kap
 Beschreibung…
 
 ### Beispiel
-```sprache
+(Beispiel im themengerechten Format laut SECTION-SPEZIFIKATION: Codeblock NUR bei Code-Themen, sonst Beispielsätze oder Mini-Szenario)
-…
-```
 
 Die Marker-Zeilen exakt so schreiben. Kein Text außerhalb der Sections, kein Dokument-Titel, kein Inhaltsverzeichnis.
 {extra}

templates/Prompt/OnePager-Bauen.md

@@ -4,19 +4,19 @@ FAKTENBASIS (alleinige Quelle, nichts hinzuerfinden):
 {recherche}
 
 Erstelle GENAU diese 7 Karten (JSON-Schlüssel exakt so):
-- "info" — Titel: "{topic}". Kurzbeschreibung in 1–2 Sätzen, darunter technische Daten als Stichpunkte (Art/Typ, Version/Stand, Lizenz/Kosten).
+- "info" — Titel: "{topic}". Kurzbeschreibung in 1–2 Sätzen, darunter Eckdaten als Stichpunkte (je nach Thema: Art/Typ, Version/Lizenz/Verbreitung ODER Ursprung/Stand/Anwendungsfelder).
 - "eigenschaften" — Titel: "Kerneigenschaften". Was einen IM Thema erwartet: kleine Übersicht der Inhalte/Teilgebiete.
-- "beispiel" — Titel: "Beispiel". EIN anschauliches, typisches Codebeispiel (Markdown-Codeblock) mit einem Satz Erklärung.
+- "beispiel" — Titel: "Beispiel". EIN anschauliches, typisches Beispiel mit einem Satz Erklärung — Markdown-Codeblock bei Code-Themen, sonst Beispielsätze oder Mini-Szenario als normaler Text.
 - "zusammenhaenge" — Titel: "Zusammenhänge". Mit welchen ANDEREN Themen es zusammenhängt — Nachbarthemen außerhalb dieses Themas, keine Inhalte des Themas selbst.
 - "voraussetzungen" — Titel: "Voraussetzungen". Welche Themen man vorher bearbeitet haben sollte, um hier klarzukommen.
-- "modern" — Titel: "Moderne Features". NUR was in den letzten Jahren neu dazugekommen ist. Gibt es nichts Neues: ehrlich "Keine." mit einem Satz Begründung.
+- "modern" — Titel: "Neu & aktuell". NUR was in den letzten Jahren neu dazugekommen ist (Features, Erkenntnisse, Empfehlungen). Gibt es nichts Neues: ehrlich "Keine." mit einem Satz Begründung.
-- "veraltet" — Titel: "Veraltete Features". Was nicht mehr verwendet wird. Gibt es nichts Veraltetes: ehrlich "Keine." mit einem Satz Begründung — nichts erfinden.
+- "veraltet" — Titel: "Veraltet & überholt". Was nicht mehr verwendet wird bzw. als überholt gilt. Gibt es nichts Veraltetes: ehrlich "Keine." mit einem Satz Begründung — nichts erfinden.
 
 KOMPAKTHEIT — der OnePager muss OHNE Scrollen auf eine Bildschirmseite passen:
 - Maximal 5 Stichpunkte pro Karte, je maximal ~8 Wörter (Schlagwort + halber Satz).
 - Nur das Wichtigste — nicht alle Varianten aufzählen. Weglassen schlägt Vollständigkeit.
 - Keine Tabellen, keine verschachtelten Listen, keine Einleitungssätze.
-- Codebeispiel maximal ~12 kurze Zeilen.
+- Beispiel maximal ~12 kurze Zeilen (Code) bzw. ~5 Zeilen (Prosa).
 
 Inhalt auf DEUTSCH, alles aus der Faktenbasis belegbar.
 Stichpunkte als Markdown-Liste mit fettem Schlagwort: `- **Schlagwort**: Rest` (kein rohes •).
@@ -25,5 +25,5 @@ Code-Bezeichner und HTML-Tags im Text IMMER in Backticks (`<p>`, `src`) — nie
 Schreibe NUR die JSON-Datei nach: {out_path}
 
 Format:
-{{"karten": {{"info": {{"titel": "{topic}", "md": "…"}}, "eigenschaften": {{"titel": "Kerneigenschaften", "md": "…"}}, "beispiel": {{"titel": "Beispiel", "md": "…"}}, "zusammenhaenge": {{"titel": "Zusammenhänge", "md": "…"}}, "voraussetzungen": {{"titel": "Voraussetzungen", "md": "…"}}, "modern": {{"titel": "Moderne Features", "md": "…"}}, "veraltet": {{"titel": "Veraltete Features", "md": "…"}}}}}}
+{{"karten": {{"info": {{"titel": "{topic}", "md": "…"}}, "eigenschaften": {{"titel": "Kerneigenschaften", "md": "…"}}, "beispiel": {{"titel": "Beispiel", "md": "…"}}, "zusammenhaenge": {{"titel": "Zusammenhänge", "md": "…"}}, "voraussetzungen": {{"titel": "Voraussetzungen", "md": "…"}}, "modern": {{"titel": "Neu & aktuell", "md": "…"}}, "veraltet": {{"titel": "Veraltet & überholt", "md": "…"}}}}}}
 {extra}

templates/Prompt/OnePager-Quelle-Thema.md

@@ -1 +1 @@
-Recherchiere per Websuche: aktuelle Version, die Kernkonzepte und die wichtigsten Fakten zu "{topic}". Nimm nur auf, was du in der Recherche belegt hast.
+Recherchiere per Websuche: aktuellen Stand (Version bzw. Forschungs-/Praxisstand), die Kernkonzepte und die wichtigsten Fakten zu "{topic}". Nimm nur auf, was du in der Recherche belegt hast.

templates/Prompt/OnePager-Recherche-Check.md

@@ -5,15 +5,15 @@ FAKTENBASIS:
 
 Sie muss diese Dimensionen abdecken:
 1. Kurzbeschreibung (1–2 Sätze)
-2. Technische Daten (Art/Typ, Version/Stand, Lizenz/Kosten)
+2. Eckdaten (Art/Typ; bei Software: Version, Lizenz/Kosten; bei Sprachen, Methoden, Theorien: Ursprung/Urheber, heutiger Stand, Anwendungsfelder)
 3. Inhaltsübersicht (was einen im Thema erwartet)
-4. Ein typisches Beispiel
+4. Ein typisches Beispiel im themengerechten Format (Code, Beispielsätze oder Mini-Szenario)
 5. Zusammenhänge mit ANDEREN Themen (Nachbarthemen, nicht Inhalte des Themas selbst)
 6. Voraussetzungen (vorher zu bearbeitende Themen)
 7. Neuerungen der letzten Jahre vs. nicht mehr Verwendetes (oder die ausdrückliche Feststellung, dass es jeweils nichts gibt)
 
 Prüfe:
-1. Ist jede Dimension mit konkreten Fakten belegt (Namen, Versionen, Zahlen — nicht vage)?
+1. Ist jede Dimension mit konkreten Fakten belegt (Namen, Zahlen, Versionen bzw. Urheber/Jahreszahlen — nicht vage)?
 2. Hat jeder Punkt eine Quelle?
 3. Wirkt etwas erfunden oder widersprüchlich?
 

templates/Prompt/OnePager-Recherche.md

@@ -4,9 +4,9 @@ Sammle die Faktenbasis für einen OnePager — ein Übersichtsblatt auf einer Se
 
 Recherchiere gezielt diese Dimensionen:
 1. Kurzbeschreibung: Was ist "{topic}" in 1–2 Sätzen?
-2. Technische Daten: Art/Typ, aktuelle Version/Stand, Lizenz/Kosten, Verbreitung.
+2. Eckdaten: Art/Typ des Themas; bei Software: aktuelle Version, Lizenz/Kosten, Verbreitung; bei Sprachen, Methoden, Theorien: Ursprung/Urheber, heutiger Stand, typische Anwendungsfelder.
 3. Inhaltsübersicht: Was erwartet einen im Thema — die wichtigsten Inhalte/Teilgebiete.
-4. Beispiel: ein minimales, typisches Code-/Anwendungsbeispiel.
+4. Beispiel: ein minimales, typisches Beispiel im themengerechten Format (Code-Beispiel, Beispielsätze/Mini-Dialog oder Mini-Szenario).
 5. Zusammenhänge: mit welchen ANDEREN Themen es zusammenhängt (Nachbarthemen außerhalb von "{topic}").
 6. Voraussetzungen: welche Themen man vorher bearbeitet haben sollte.
 7. Neuerungen vs. Veraltetes: was in den letzten Jahren neu dazugekommen ist — und was nicht mehr verwendet wird (falls es nichts gibt, jeweils ausdrücklich notieren).

templates/Prompt/OnePager-Verifikation.md

@@ -10,7 +10,7 @@ Prüfe:
 1. Sind alle 7 Karten vollständig ausgefüllt (keine abgebrochenen oder leeren Inhalte, keine Platzhalter)?
 2. Stimmen alle Aussagen mit der Faktenbasis überein? Nichts Erfundenes?
 3. Ist jede Karte KOMPAKT — maximal 5 kurze Stichpunkte (je ~8 Wörter), keine Tabellen, Beispiel maximal ~12 Zeilen? Zu lange Karten sind ein Problem.
-4. Ist jede Karte für sich verständlich? Ist das Beispiel ein lauffähig plausibler Codeblock?
+4. Ist jede Karte für sich verständlich? Ist das Beispiel konkret und plausibel — lauffähig wirkender Code bzw. realistische Sätze/realistisches Szenario?
 
 Du PRÜFST nur und notierst Probleme — du änderst nichts. Nenne die betroffene Karte über ihren Schlüssel (info, eigenschaften, beispiel, zusammenhaenge, voraussetzungen, modern, veraltet).