Adressen: Slug und Version im Pfad statt Parameter

Seite: /<slug>[/v<N>][/lauf|/buch|/lesen][/<Abschnitt>], Zurück-Taste je
Abschnitt. API: /api/themen/<slug>/v<N>/… mit Version als Pflichtteil des
Pfads; /api/topics entfällt. Slugs stehen in thema.json und werden beim
Start nachgetragen. Unbekannte API-Pfade liefern 404 statt der Seite.

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

API.md

@@ -2,24 +2,36 @@
 
 Backend: FastAPI auf Port 8020, liefert `frontend/dist/` aus. Alle Pfade unter `/api`.
 
-## Themen
+## Adressen
 
-- `GET /api/topics` → `[{name, titel, status, laeuft, stufe}]`
-  - `status`: `neu | laeuft | pausiert | fertig | fehler`
-- `POST /api/topics` `{name, hinweise}` → Topic (name = Thema, z. B. „Godot 4“; hinweise optional, z. B. „für Entwickler, ab Version 4.6“)
-- `DELETE /api/topics/{name}`
-- `POST /api/topics/{name}/start` – startet oder setzt fort (resümiert an der Stufe, die noch offen ist)
-- `POST /api/topics/{name}/pause` – bricht laufende Agenten ab; Neustart mit `start`
-- `POST /api/topics/{name}/reset` – löscht alles außer `thema.json`
+Ein Thema hat einen Slug („Godot 4“ → `godot-4`) und Versionen `v1`, `v2`, … mit eigenem Lauf, Buch, Quellen und Leseposition.
+Die Version ist in der API immer Teil des Pfads; „neueste“ löst die Oberfläche selbst auf.
+
+Seite: `/<slug>`, `/<slug>/v2/lauf`, `/<slug>/v2/buch`, `/<slug>/v2/buch/3.4` (Abschnitt; `3` = Kapitel, `vorwort`), `/<slug>/v2/lesen`.
+Ohne `v2` gilt die neueste Version.
+
+## Themen und Versionen
+
+- `GET /api/themen` → `[{slug, name, titel, hinweise, angelegt, status, laeuft, stufe, versionen: [{v, status, laeuft, stufe, angelegt, kosten_usd}]}]`
+  – `status/laeuft/stufe` gelten für die neueste Version; `status`: `neu | laeuft | pausiert | fertig | fehler`
+- `POST /api/themen` `{name, hinweise}` → Thema wie oben (legt `v1` an)
+- `GET /api/themen/{slug}` → Thema wie oben
+- `DELETE /api/themen/{slug}` – ganzes Thema
+- `POST /api/themen/{slug}/versionen` → `{"v": N}` – nächste Version, gleiche Eingaben, ohne Start
+- `DELETE /api/themen/{slug}/v{N}` – nur diese Version
+- `POST /api/themen/{slug}/v{N}/start` – startet oder setzt fort (resümiert an der offenen Stufe)
+- `POST /api/themen/{slug}/v{N}/pause` – bricht laufende Agenten ab; Neustart mit `start`
+- `POST /api/themen/{slug}/v{N}/reset` – löscht alles in der Version außer dem Zustand „neu“
+- `GET|PUT /api/themen/{slug}/v{N}/position` – Leseposition `{abschnitt, lesemodus}`
 
 ## Zustand eines Laufs
 
-`GET /api/topics/{name}/state` →
+`GET /api/themen/{slug}/v{N}` →
 
 ```json
 {
-  "name": "Godot 4", "titel": "Godot 4", "hinweise": "…",
-  "status": "laeuft", "grund": "", "stufe": "schreiben",
+  "slug": "godot-4", "name": "Godot 4", "version": 1, "titel": "Godot 4", "hinweise": "…",
+  "status": "laeuft", "grund": "", "stufe": "schreiben", "angelegt": "2026-09-28T10:00:00Z",
   "deutung": {"titel": "Godot 4", "untertitel": "…", "deutung": "…", "buchtyp": "werkzeug|wissen", "zielgruppe": "…"},
   "stufen": [
     {"id": "recherche", "titel": "Thema deuten und Quellen beschaffen", "status": "fertig", "fertig": 1, "gesamt": 1,
@@ -32,10 +44,10 @@ Backend: FastAPI auf Port 8020, liefert `frontend/dist/` aus. Alle Pfade unter `
   ],
   "kosten_usd": 12.3, "tokens": 4100000,
   "agenten": [
-    {"id": "schreiben-03", "stufe": "schreiben", "name": "Kapitel 3 schreiben", "status": "laeuft|fertig|fehler|abgebrochen",
-     "kosten_usd": 0.9, "tokens": 180000, "werkzeuge": 41, "gestartet": "…", "beendet": "…", "bericht": "<Abschlussbericht des Agenten, Markdown>"}
+    {"id": "kapitel-03", "stufe": "schreiben", "name": "Kapitel 3 schreiben", "status": "laeuft|fertig|fehler|abgebrochen",
+     "kosten_usd": 0.9, "tokens": 180000, "werkzeuge": 41, "gestartet": "…", "beendet": "…", "bericht": "<Abschlussbericht, Markdown>"}
   ],
-  "ereignisse": [{"zeit": "…", "agent": "schreiben-03", "art": "tool|text|start|ende|fehler", "text": "Write buch/03-dal.md"}]
+  "ereignisse": [{"zeit": "…", "agent": "kapitel-03", "art": "tool|text|start|ende|fehler", "text": "Write buch/03-dal.md"}]
 }
 ```
 
@@ -43,7 +55,7 @@ Backend: FastAPI auf Port 8020, liefert `frontend/dist/` aus. Alle Pfade unter `
 
 ## Buch
 
-`GET /api/topics/{name}/guide` →
+`GET /api/themen/{slug}/v{N}/buch` →
 
 ```json
 {
@@ -62,30 +74,25 @@ Backend: FastAPI auf Port 8020, liefert `frontend/dist/` aus. Alle Pfade unter `
 }
 ```
 
-- `GET /api/topics/{name}/guide.md` – ganzes Buch als Markdown
-- `GET /api/topics/{name}/buch.pdf` – PDF (404, solange nicht gebaut)
+- `GET /api/themen/{slug}/v{N}/buch.md` – ganzes Buch als Markdown
+- `GET /api/themen/{slug}/v{N}/buch.pdf` – PDF (404, solange nicht gebaut)
 
-Solange ein Lauf läuft, enthält `guide` die bereits geschriebenen Kapitel (Status `geschrieben` bis der Prüfer fertig ist).
+Solange ein Lauf läuft, enthält `buch` die bereits geschriebenen Kapitel (Status `geschrieben`, bis der Prüfer fertig ist).
 
 ## Dateien im Speicher
 
 ```
-storage/<name>/
-  thema.json          {name, titel, hinweise, angelegt}
-  state.json          Zustand wie oben (ohne guide)
-  deutung.json        vom Recherche-Agenten
-  quellen/            QUELLEN.md + geklonte/geladene Quellen
-  buch/               STIL.md, GLIEDERUNG.md, 00-vorwort.md, NN-*.md, README.md, buch.md, buch.pdf
-  berichte/           <agent-id>.md (Abschlussberichte)
-  log.jsonl           Ereignisse
+storage/<Thema>/
+  thema.json          {name, slug, titel, hinweise, angelegt}
+  v1/, v2/, …         je Version:
+    state.json        Zustand wie oben (ohne Buch)
+    deutung.json      vom Recherche-Agenten
+    position.json     Leseposition
+    quellen/          QUELLEN.md + geklonte/geladene Quellen
+    buch/             STIL.md, GLIEDERUNG.md, 00-vorwort.md, NN-*.md, README.md, buch.md, buch.pdf
+    berichte/         <agent-id>.md (Abschlussberichte)
+    arbeit/           Arbeitsdateien der Agenten
+    log.jsonl         Ereignisse
 ```
 
-## Versionen
-
-Ein Thema kann mehrere Versionen haben (gleiche Eingaben, unabhängiger Lauf, eigenes Buch und eigene Leseposition).
-Ablage: `storage/<Thema>/thema.json` und `storage/<Thema>/v<N>/…`. Alte Ablagen werden beim Start nach `v1/` verschoben.
-
-- `GET /api/topics` liefert je Thema `versionen: [{v, status, laeuft, stufe, angelegt, kosten_usd}]`; die Felder `status/laeuft/stufe` gelten für die neueste Version.
-- `POST /api/topics/{name}/version` → `{"v": N}` legt die nächste Version an (ohne Start).
-- Alle Endpunkte unter `/api/topics/{name}/…` nehmen `?v=N`; ohne Angabe gilt die neueste Version.
-- `DELETE /api/topics/{name}?v=N` löscht nur diese Version, ohne `v` das ganze Thema.
+Alte Ablagen (alles direkt unter `storage/<Thema>/`) werden beim Start nach `v1/` verschoben, fehlende Slugs nachgetragen.