dworzycp/adventure-book

Adventure Book

You are turning a document into a journey. The reader travels stage by stage through an illustrated tale in the user's chosen theme, and every marked word in the tale can be clicked to see the real thing it stands for: the actual command, rule, decision, or fact from the source document. The output is one .html file that works offline with no dependencies.

The engine (navigation, pop-out drawer, codex, progress map, parallax, keyboard, mobile layout, reduced-motion) is already built in assets/template.html. scripts/build_book.py assembles your content into it. Your job is the creative and faithful part: the story, the allegory, the prose, the pop-outs, and the scene art.

Three references carry the craft: references/story.md (structure — read it every time), references/themes.md (voice and allegory per theme), and references/scenes.md (drawing).

The two failures to design against are too many words and no story underneath them: a book that renames the document's sections in costume, stage after stage, and buries the real facts in atmosphere. Fewer words, one clear journey.

Workflow

1. Read the whole source. Note its headings, the order things happen in, what a reader is supposed to be able to do afterwards, and any facts that are easy to get wrong (exact commands, names, numbers, rules). Those facts are what the pop-outs exist to protect.
2. Fix the theme and the allegory. Take the theme the user gave; if none, pick one that suits the material and say which you chose. Read the matching section of references/themes.md for its voice, motifs, hero archetype, and stage-naming pattern. Then write a short mapping table for yourself: each real concept in the source and its themed counterpart (VPN = the Veil, database = the great tame beast, CI pipeline = the proving grounds). Keep every mapping stable for the whole book. Readers learn the allegory once; if the Veil becomes the Mist in chapter four, the book stops teaching.
3. Shape the story. Read references/story.md and fill in its story spine for this book before planning anything: the objective the hero must reach, the "because of that" chain that gets them there, the mistake they make near the end, and the image the book closes on. A document is a list of sections; a book is a chain of consequences, and turning one into the other is the whole job. Do not skip this because the source looks like a simple list — those are the ones that come out as slideshows.
4. Plan the stages. Aim for 5 to 9, one beat each, mapped onto the spine (one stage of arrival, three to six of escalating middle, one where it goes wrong, one of payoff). Each stage is usually one source section: merge sections too thin to carry a beat, and split ones that would need more than about 120 words of narrative. Order the stages as the reader would need the knowledge, which is usually the document's order. Give each a title in the theme's voice and a source: heading so the reader can unroll the original section from inside the stage.
5. Write the content files in a working folder (book.json, stages/NN-name.md, scenes/*.svg). Formats are below.
6. Cut, then run the checklist. Reread each stage against "Writing the tale" and take out roughly a third of the words; first drafts are almost always twice as long as they need to be, and every sentence you delete makes the marked words easier to see. Then walk the checklist at the end of references/story.md and fix what fails. Both of these happen before you build; neither is optional polish.
7. Build and read the warnings. Fix every "no pop-out with id", "heading not found", and coverage warning. Rebuild until the report is clean or every remaining warning is deliberate.
8. Verify and hand over. Open the file (open <file>.html on macOS) or at least screenshot it with headless Chrome if available. Tell the user where the file is, how to move through it (arrow keys, click the map, click the glowing words), and which theme you used.

Content formats

book.json (paths relative to the JSON file):

{
  "title": "The Quest for the Portal",
  "subtitle": "A knight's journey through AGENTS.md",
  "theme": "knight",
  "source": "../AGENTS.md",
  "cover":  { "eyebrow": "An interactive adventure", "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": [ "Cross the [[Veil|vpn]] before anything else", "Every package flies the `@internal/` banner" ] }
}

Each stage is a Markdown file:

---
id: gates
title: The Gates of the Keep
chapter: Chapter I
source: Local Development Setup
scene: scenes/01-gates.svg
---
Mist clings to the road as you approach the keep. A guard bars the way: none may
enter who have not passed through [[the Veil|vpn]] ...

## popout: vpn
title: VPN
You have to be on the company VPN before anything else works, because the
internal package registry and services are only reachable from inside the network.

Rules the build script enforces or warns about:

• Every prose field is Markdown. Every scene is inline SVG, given as a path to a .svg file.
• [[display text|id]] marks a pop-out link; [[docker]] uses the text as the id. Each id needs a ## popout: id block in the same stage (or a book-level popouts array in book.json).
• source: in the frontmatter names a heading in the source document. The script extracts that section verbatim and shows it behind the "original scroll" button. A pop-out block may also carry source: <heading> to attach the relevant section under its explanation — but it must sit in the pop-out's header lines, directly under ## popout: id alongside title:, not after the explanation. Misplaced, it is silently read as prose and the section goes uncovered.
• Theme is a preset name (knight, space, pirate, noir, expedition, deepsea) or an object { "extends": "knight", "colors": {...}, "fonts": {...}, "vocabulary": {...} }. Presets live in assets/themes.json; copy one as the starting point for an invented theme.

Build:

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

Writing the tale

Second person, present tense, one scene and one beat per stage. "You" are the hero. A stage is not a description of a place; it is something happening in one. You arrive, you meet a person or a problem, you do one thing, and you leave changed or better equipped. If a stage boils down to "you are somewhere and it looks atmospheric", it has no beat yet: find one in the source section — the thing the reader must do, the mistake they must not make, the decision that was taken — and build the scene around that.

Hold the shape you planned. references/story.md is the authority on structure: the objective stated up front, stages joined by "therefore" and "but" rather than "and then", the middle escalating, a real mistake near the end, a refrain or carried ob