dworzycp/adventure-book

Adventure Book

Du verwandelst ein Dokument in eine Reise. Der Leser reist Stufe für Stufe durch eine bebilderte Erzählung im vom Benutzer gewählten Thema, und jedes markierte Wort in der Erzählung kann angeklickt werden, um die dahinterstehende Realität zu sehen: den tatsächlichen Befehl, die Regel, die Entscheidung oder die Tatsache aus dem Quelldokument. Die Ausgabe ist eine einzige .html-Datei, die offline ohne Abhängigkeiten funktioniert.

Die Engine (Navigation, Pop-out-Drawer, Codex, Fortschrittskarte, Parallaxe, Tastatur, mobiles Layout, Reduzierte-Bewegung) ist bereits in assets/template.html eingebaut. scripts/build_book.py setzt deinen Inhalt darin zusammen. Deine Aufgabe ist der kreative und treue Teil: die Geschichte, die Allegorie, der Prosatext, die Pop-outs und die Szenenkunst.

Drei Referenzen tragen das Handwerk: references/story.md (Struktur – lies sie jedes Mal), references/themes.md (Stimme und Allegorie je Thema) und references/scenes.md (Zeichnen).

Die beiden Fehler, gegen die du entwirfst, sind zu viele Wörter und keine Geschichte darunter: ein Buch, das die Abschnitte des Dokuments nur verkleidet umbenennt, Stufe um Stufe, und die echten Fakten in Atmosphäre begräbt. Weniger Wörter, eine klare Reise.

Arbeitsablauf

1. Lies die gesamte Quelle. Notiere ihre Überschriften, die Reihenfolge der Ereignisse, was ein Leser danach können soll, und alle Fakten, die leicht falsch verstanden werden können (genaue Befehle, Namen, Zahlen, Regeln). Diese Fakten sind es, deren Schutz die Pop-outs dienen.
2. Lege das Thema und die Allegorie fest. Nimm das vom Benutzer vorgegebene Thema; wenn keines genannt wurde, wähle eines, das zum Material passt, und sag, welches du gewählt hast. Lies den passenden Abschnitt von references/themes.md für dessen Stimme, Motive, Helden-Archetyp und Benennungsmuster für Stufen. Schreibe dann eine kurze Zuordnungstabelle für dich selbst: jedes reale Konzept aus der Quelle und seine thematische Entsprechung (VPN = der Schleier, Datenbank = die große gezähmte Bestie, CI-Pipeline = der Prüfstand). Halte jede Zuordnung für das gesamte Buch stabil. Leser lernen die Allegorie einmal; wenn der Schleier in Kapitel vier zum Nebel wird, hört das Buch auf zu lehren.
3. Forme die Geschichte. Lese references/story.md und fülle dessen Erzählgerüst für dieses Buch aus, bevor du irgendetwas planst: das Ziel, das der Held erreichen muss, die „deshalb“-Kette, die ihn dorthin bringt, der Fehler, den er gegen Ende macht, und das Bild, mit dem das Buch schließt. Ein Dokument ist eine Liste von Abschnitten; ein Buch ist eine Kette von Konsequenzen, und das eine in das andere zu verwandeln, ist die ganze Aufgabe. Überspringe dies nicht, weil die Quelle wie eine einfache Liste aussieht – gerade diese werden zu Dia-Shows.
4. Plane die Stufen. Ziel sind 5 bis 9, ein Beat pro Stufe, die auf das Gerüst abgebildet werden (eine Stufe der Ankunft, drei bis sechs der eskalierenden Mitte, eine, in der es schiefgeht, eine der Auflösung). Jede Stufe entspricht normalerweise einem Quellabschnitt: fasse Abschnitte zusammen, die zu dünn für einen Beat sind, und teile solche, die mehr als etwa 120 Wörter Erzählung benötigen würden. Ordne die Stufen so an, wie der Leser das Wissen benötigt, was in der Regel der Reihenfolge des Dokuments entspricht. Gib jeder Stufe einen Titel in der Stimme des Themas und eine source:-Überschrift, damit der Leser den Originalabschnitt aus der Stufe heraus aufklappen kann.
5. Schreibe die Inhaltsdateien in einem Arbeitsordner (book.json, stages/NN-name.md, scenes/*.svg). Die Formate folgen unten.
6. Kürze, dann führe die Checkliste aus. Lies jede Stufe erneut anhand von „Die Geschichte schreiben“ und streiche etwa ein Drittel der Wörter; erste Entwürfe sind fast immer doppelt so lang wie nötig, und jeder Satz, den du löschst, macht die markierten Wörter leichter erkennbar. Gehe dann die Checkliste am Ende von references/story.md durch und behebe, was nicht besteht. Beides geschieht vor dem Bauen; keines ist optionales Feintuning.
7. Baue und lies die Warnungen. Behebe jede „kein Pop-out mit id“, „Überschrift nicht gefunden“ und Abdeckungswarnung. Baue neu, bis der Bericht sauber ist oder jede verbleibende Warnung beabsichtigt ist.
8. Überprüfe und übergib. Öffne die Datei (open <datei>.html unter macOS) oder erstelle zumindest einen Screenshot mit headless Chrome, falls verfügbar. Teile dem Benutzer mit, wo die Datei ist, wie man sich darin bewegt (Pfeiltasten, Klick auf die Karte, Klick auf die leuchtenden Wörter) und welches Thema du verwendet hast.

Inhaltsformate

book.json (Pfade relativ zur JSON-Datei):

{
  "title": "Die Suche nach dem Portal",
  "subtitle": "Die Reise eines Ritters durch die AGENTS.md",
  "theme": "knight",
  "source": "../AGENTS.md",
  "cover":  { "eyebrow": "Ein interaktives Abenteuer", "scene": "scenes/cover.svg", "blurb": "cover.md" },
  "stages": [ "stages/01-gates.md", "stages/02-forge.md" ],
  "ending": { "scene": "scenes/ending.svg", "blurb": "ending.md",
              "recap": [ "Überquere den [[Schleier|vpn]] bevor alles andere",
                          "Jedes Paket trägt das Banner `@internal/`" ] }
}

Jede Stufe ist eine Markdown-Datei:

---
id: gates
title: Die Tore der Festung
chapter: Kapitel I
source: Lokales Entwicklungssetup
scene: scenes/01-gates.svg
---
Nebel liegt auf der Straße, als du dich der Festung näherst. Ein Wächter versperrt den
Weg: Niemand darf eintreten, der nicht [[den Schleier|vpn]] passiert hat ...

## popout: vpn
title: VPN
Du musst mit dem Firmen-VPN verbunden sein, bevor irgendetwas anderes funktioniert, weil
die internen Paketregister und Dienste nur aus dem internen Netzwerk erreichbar sind.

Regeln, die das Build-Skript durchsetzt oder vor denen es warnt:

• Jedes Prosafeld ist Markdown. Jede Szene ist inline-SVG, angegeben als Pfad zu einer .svg-Datei.
• [[Anzeigetext|id]] markiert einen Pop-out-Link; [[docker]] verwendet den Text als die id. Jede id benötigt einen ## popout: id-Block in derselben Stufe (oder ein popouts-Array auf Buchebene in book.json).
• source: im Frontmatter benennt eine Überschrift im Quelldokument. Das Skript extrahiert diesen Abschnitt wörtlich und zeigt ihn hinter dem „Original-Schriftrolle“-Button. Ein Pop-out-Block kann ebenfalls source: <Überschrift> tragen, um den zugehörigen Abschnitt unter seiner Erklärung anzuhängen – aber es muss in den Kopfzeilen des Pop-outs stehen, direkt unter ## popout: id zusammen mit title:, nicht nach der Erklärung. Falsch platziert wird es stillschweigend als Prosa gelesen und der Abschnitt bleibt ungedeckt.
• Thema ist ein vordefinierter Name (knight, space, pirate, noir, expedition, deepsea) oder ein Objekt { "extends": "knight", "colors": {...}, "fonts": {...}, "vocabulary": {...} }. Voreinstellungen leben in assets/themes.json; kopiere eine als Ausgangspunkt für ein erfundenes Thema.

Build:

python3 <skill-verzeichnis>/scripts/build_book.py --content work/book.json --out <name>.html

Die Geschichte schreiben

Zweite Person, Präsens, eine Szene und ein Beat pro Stufe. „Du“ bist der Held. Eine Stufe ist keine Beschreibung eines Ortes; es ist etwas, das an einem Ort geschieht. Du kommst an, triffst auf eine Person oder ein Problem, tust eine Sache und verlässt den Ort verändert oder besser ausgerüstet. Wenn eine Stufe darauf hinausläuft, dass „du irgendwo bist und es stimmungsvoll aussieht“, hat sie noch keinen Beat: Finde einen im Quellabschnitt – die Sache, die der Leser tun muss, der Fehler, den er nicht machen darf, die Entscheidung, die getroffen wurde – und baue die Szene darum herum.

Halte die geplante Form. references/story.md ist die Autorität für die Struktur: das Ziel gleich zu Beginn genannt, Stufen, die durch „deshalb“ und „aber“ verbunden sind, nicht durch „und dann“, die Mitte steigert sich, ein echter Fehler gegen Ende, ein wiederkehrendes Motiv oder Symbol.