Adventure Book

Que fait Adventure Book ?

Vous transformez un document en un voyage. Le lecteur progresse étape par étape à travers un récit illustré dans le thème choisi, et chaque mot marqué dans le récit peut être cliqué pour voir la réalité qu'il représente : la commande, la règle, la décision ou le fait concret du document source. Le résultat est un fichier .html qui fonctionne hors ligne sans dépendances.

Le moteur (navigation, tiroir pop-up, codex, carte de progression, parallaxe, clavier, disposition mobile, mouvement réduit) est déjà intégré dans assets/template.html. scripts/build_book.py assemble votre contenu dans ce modèle. Votre travail est la partie créative et fidèle : l'histoire, l'allégorie, la prose, les pop-ups et l'art des scènes.

Trois références guident le travail : references/story.md (structure — lisez-la à chaque fois), references/themes.md (voix et allégorie par thème), et references/scenes.md (dessin).

Les deux échecs à éviter sont trop de mots et pas d'histoire en dessous : un livre qui renomme les sections du document en costume, étape après étape, et enterre les faits réels dans l'atmosphère. Moins de mots, un voyage clair.

Flux de travail

1. Lisez la source en entier. Notez ses titres, l'ordre des événements, ce que le lecteur devrait être capable de faire après, et les faits faciles à mal comprendre (commandes exactes, noms, nombres, règles). Ces faits sont ce que les pop-ups existent pour protéger.
2. Fixez le thème et l'allégorie. Reprenez le thème donné par l'utilisateur ; s'il n'y en a pas, choisissez-en un qui correspond au contenu et dites lequel vous avez choisi. Lisez la section correspondante de references/themes.md pour sa voix, ses motifs, l'archétype du héros et le modèle de nommage des étapes. Écrivez ensuite un court tableau de correspondance pour vous-même : chaque concept réel de la source et son équivalent thématique (VPN = le Voile, base de données = la grande bête apprivoisée, pipeline CI = les terrains d'épreuve). Gardez chaque correspondance stable pour tout le livre. Les lecteurs apprennent l'allégorie une fois ; si le Voile devient la Brume au chapitre quatre, le livre cesse d'enseigner.
3. Façonnez l'histoire. Lisez references/story.md et remplissez sa colonne vertébrale pour ce livre avant de planifier quoi que ce soit : l'objectif que le héros doit atteindre, la chaîne « à cause de cela » qui l'y mène, l'erreur qu'il commet vers la fin, et l'image sur laquelle le livre se ferme. Un document est une liste de sections ; un livre est une chaîne de conséquences, et transformer l'un en l'autre est tout le travail. Ne sautez pas cette étape parce que la source ressemble à une simple liste — ce sont celles-là qui donnent des diaporamas.
4. Planifiez les étapes. Visez de 5 à 9 étapes, un temps chacune, cartographiées sur la colonne vertébrale (une étape d'arrivée, trois à six de milieu croissant, une où ça tourne mal, une de récompense). Chaque étape correspond généralement à une section de la source : fusionnez les sections trop fines pour porter un temps, et divisez celles qui nécessiteraient plus d'environ 120 mots de narration. Ordonnez les étapes comme le lecteur aurait besoin des connaissances, ce qui est généralement l'ordre du document. Donnez à chacune un titre dans la voix du thème et un en-tête source: pour que le lecteur puisse dérouler la section d'origine depuis l'intérieur de l'étape.
5. Écrivez les fichiers de contenu dans un dossier de travail (book.json, stages/NN-nom.md, scenes/*.svg). Les formats sont ci-dessous.
6. Coupez, puis exécutez la liste de vérification. Relisez chaque étape par rapport à « Écrire le récit » et supprimez environ un tiers des mots ; les premiers jets sont presque toujours deux fois plus longs que nécessaire, et chaque phrase que vous supprimez rend les mots marqués plus faciles à voir. Puis parcourez la liste de vérification à la fin de references/story.md et corrigez ce qui échoue. Ces deux étapes se font avant la construction ; aucune n'est une option de polissage.
7. Construisez et lisez les avertissements. Corrigez chaque « aucun pop-up avec l'id », « titre introuvable » et avertissement de couverture. Reconstruisez jusqu'à ce que le rapport soit propre ou que chaque avertissement restant soit délibéré.
8. Vérifiez et remettez. Ouvrez le fichier (open <fichier>.html sur macOS) ou au moins faites-en une capture d'écran avec Chrome sans tête si disponible. Dites à l'utilisateur où se trouve le fichier, comment naviguer (touches fléchées, cliquer sur la carte, cliquer sur les mots lumineux) et quel thème vous avez utilisé.

Formats de contenu

book.json (chemins relatifs au fichier JSON) :

{
  "title": "La Quête du Portail",
  "subtitle": "Le voyage d'un chevalier à travers AGENTS.md",
  "theme": "knight",
  "source": "../AGENTS.md",
  "cover":  { "eyebrow": "Une aventure interactive", "scene": "scenes/cover.svg", "blurb": "cover.md" },
  "stages": [ "stages/01-portes.md", "stages/02-forge.md" ],
  "ending": { "scene": "scenes/ending.svg", "blurb": "ending.md",
              "recap": [ "Traversez le [[Voile|vpn]] avant toute chose", "Chaque paquet porte la bannière `@internal/`" ] }
}

Chaque étape est un fichier Markdown :

---
id: portes
title: Les Portes du Donjon
chapter: Chapitre I
source: Configuration de développement locale
scene: scenes/01-portes.svg
---
La brume colle à la route alors que vous approchez du donjon. Un garde barre le passage : nul ne
peut entrer sans avoir traversé [[le Voile|vpn]] ...

## popout: vpn
title: VPN
Vous devez être sur le VPN de l'entreprise avant que quoi que ce soit ne fonctionne, car
le registre de paquets interne et les services ne sont accessibles que depuis l'intérieur du réseau.

Règles que le script de construction applique ou avertit :

• Chaque champ de prose est en Markdown. Chaque scène est en SVG en ligne, donnée sous forme de chemin vers un fichier .svg.
• [[texte affiché|id]] marque un lien pop-up ; [[docker]] utilise le texte comme id. Chaque id nécessite un bloc ## popout: id dans la même étape (ou un tableau popouts au niveau du livre dans book.json).
• source: dans l'en-tête nomme un titre dans le document source. Le script extrait cette section textuellement et l'affiche derrière le bouton « parchemin original ». Un bloc pop-up peut également porter source: <titre> pour attacher la section pertinente sous son explication — mais il doit se trouver dans les lignes d'en-tête du pop-up, directement sous ## popout: id à côté de title:, pas après l'explication. Mal placé, il est silencieusement lu comme de la prose et la section reste non couverte.
• Le thème est un nom prédéfini (knight, space, pirate, noir, expedition, deepsea) ou un objet { "extends": "knight", "colors": {...}, "fonts": {...}, "vocabulary": {...} }. Les préréglages se trouvent dans assets/themes.json ; copiez-en un comme point de départ pour un thème inventé.

Construction :

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

Écrire le récit

Deuxième personne, présent, une scène et un temps par étape. « Vous » êtes le héros. Une étape n'est pas une description d'un lieu ; c'est quelque chose qui se passe dans un lieu. Vous arrivez, vous rencontrez une personne ou un problème, vous faites une chose, et vous repartez changé ou mieux équipé. Si une étape se résume à « vous êtes quelque part et c'est atmosphérique », elle n'a pas encore de temps : trouvez-en un dans la section source — la chose que le lecteur doit faire, l'erreur qu'il ne doit pas commettre, la décision qui a été prise — et construisez la scène autour de cela.

Tenez la forme que vous avez planifiée. references/story.md est l'autorité sur la structure : l'objectif énoncé d'emblée, les étapes reliées par « donc » et « mais » plutôt que « et puis », le milieu qui monte en puissance, une vraie erreur vers la fin, un refrain ou un objet porté.