Adventure Book

¿Qué hace Adventure Book?

Estás convirtiendo un documento en un viaje. El lector avanza etapa por etapa a través de un cuento ilustrado en el tema elegido, y cada palabra marcada en el cuento se puede hacer clic para ver lo real que representa: el comando, la regla, la decisión o el hecho del documento fuente. El resultado es un archivo .html que funciona sin conexión y sin dependencias.

El motor (navegación, cajón emergente, codex, mapa de progreso, paralaje, teclado, diseño móvil, movimiento reducido) ya está integrado en assets/template.html. scripts/build_book.py ensambla tu contenido en él. Tu trabajo es la parte creativa y fiel: la historia, la alegoría, la prosa, las ventanas emergentes y el arte de las escenas.

Tres referencias guían el oficio: references/story.md (estructura — léela cada vez), references/themes.md (voz y alegoría por tema) y references/scenes.md (dibujo).

Los dos fracasos contra los que diseñar son demasiadas palabras y ninguna historia debajo: un libro que renombra las secciones del documento disfrazadas, etapa tras etapa, y entierra los hechos reales en la atmósfera. Menos palabras, un viaje claro.

Flujo de trabajo

1. Lee toda la fuente. Anota sus encabezados, el orden en que suceden las cosas, qué debería ser capaz de hacer un lector después, y cualquier hecho fácil de equivocar (comandos exactos, nombres, números, reglas). Esos hechos existen para que las ventanas emergentes los protejan.
2. Fija el tema y la alegoría. Toma el tema que dio el usuario; si no dio ninguno, elige uno que se adapte al material y di cuál elegiste. Lee la sección correspondiente de references/themes.md para su voz, motivos, arquetipo del héroe y patrón de nombres de etapas. Luego escribe una tabla de mapeo breve para ti: cada concepto real de la fuente y su contraparte temática (VPN = el Velo, base de datos = la gran bestia domada, pipeline CI = el campo de pruebas). Mantén cada mapeo estable para todo el libro. Los lectores aprenden la alegoría una vez; si el Velo se convierte en la Niebla en el capítulo cuatro, el libro deja de enseñar.
3. Da forma a la historia. Lee references/story.md y completa su esqueleto narrativo para este libro antes de planificar nada: el objetivo que el héroe debe alcanzar, la cadena de "por eso" que lo lleva allí, el error que comete cerca del final y la imagen con la que cierra el libro. Un documento es una lista de secciones; un libro es una cadena de consecuencias, y convertir una en la otra es todo el trabajo. No te saltes esto porque la fuente parezca una lista simple — esas son las que terminan siendo presentaciones de diapositivas.
4. Planifica las etapas. Apunta a 5 a 9, un compás cada una, mapeadas en el esqueleto (una etapa de llegada, tres a seis de mitad creciente, una donde algo sale mal, una de recompensa). Cada etapa suele ser una sección de la fuente: fusiona secciones demasiado finas para sostener un compás y divide aquellas que necesitarían más de unas 120 palabras de narrativa. Ordena las etapas como el lector necesitaría el conocimiento, que suele ser el orden del documento. Dale a cada una un título con la voz del tema y un encabezado source: para que el lector pueda desplegar la sección original desde dentro de la etapa.
5. Escribe los archivos de contenido en una carpeta de trabajo (book.json, stages/NN-nombre.md, scenes/*.svg). Los formatos están abajo.
6. Recorta, luego ejecuta la lista de verificación. Relee cada etapa con "Escribiendo el cuento" y elimina aproximadamente un tercio de las palabras; los primeros borradores casi siempre son el doble de largos de lo necesario, y cada oración que eliminas hace que las palabras marcadas sean más fáciles de ver. Luego recorre la lista de verificación al final de references/story.md y corrige lo que falle. Ambas cosas ocurren antes de construir; ninguna es un retoque opcional.
7. Construye y lee las advertencias. Corrige cada "no pop-out with id", "heading not found" y advertencia de cobertura. Reconstruye hasta que el informe esté limpio o cada advertencia restante sea deliberada.
8. Verifica y entrega. Abre el archivo (open <archivo>.html en macOS) o al menos haz una captura de pantalla con Chrome sin cabeza si está disponible. Dile al usuario dónde está el archivo, cómo navegar por él (teclas de flecha, clic en el mapa, clic en las palabras brillantes) y qué tema usaste.

Formatos de contenido

book.json (rutas relativas al archivo JSON):

{
  "title": "La búsqueda del portal",
  "subtitle": "El viaje de un caballero a través de AGENTS.md",
  "theme": "knight",
  "source": "../AGENTS.md",
  "cover":  { "eyebrow": "Una aventura interactiva", "scene": "scenes/cover.svg", "blurb": "cover.md" },
  "stages": [ "stages/01-puertas.md", "stages/02-forja.md" ],
  "ending": { "scene": "scenes/ending.svg", "blurb": "ending.md",
              "recap": [ "Cruza el [[Velo|vpn]] antes que nada", "Cada paquete lleva la bandera `@internal/`" ] }
}

Cada etapa es un archivo Markdown:

---
id: puertas
title: Las puertas de la fortaleza
chapter: Capítulo I
source: Configuración del desarrollo local
scene: scenes/01-puertas.svg
---
La niebla se adhiere al camino mientras te acercas a la fortaleza. Un guardia bloquea el paso: nadie
puede entrar si no ha atravesado [[el Velo|vpn]] ...

## popout: vpn
title: VPN
Tienes que estar en la VPN de la empresa antes de que funcione cualquier otra cosa, porque el
registro de paquetes interno y los servicios solo son accesibles desde dentro de la red.

Reglas que el script de construcción aplica o advierte:

• Cada campo de prosa es Markdown. Cada escena es SVG en línea, dada como ruta a un archivo .svg.
• [[texto mostrado|id]] marca un enlace emergente; [[docker]] usa el texto como id. Cada id necesita un bloque ## popout: id en la misma etapa (o un array popouts a nivel de libro en book.json).
• source: en el frontmatter nombra un encabezado en el documento fuente. El script extrae esa sección textualmente y la muestra detrás del botón "rollo original". Un bloque emergente también puede llevar source: <encabezado> para adjuntar la sección relevante debajo de su explicación — pero debe colocarse en las líneas de cabecera del emergente, directamente debajo de ## popout: id junto a title:, no después de la explicación. Si se coloca mal, se lee silenciosamente como prosa y la sección queda descubierta.
• El tema es un nombre predefinido (knight, space, pirate, noir, expedition, deepsea) o un objeto { "extends": "knight", "colors": {...}, "fonts": {...}, "vocabulary": {...} }. Los predefinidos viven en assets/themes.json; copia uno como punto de partida para un tema inventado.

Construir:

python3 <directorio-habilidad>/scripts/build_book.py --content work/book.json --out <nombre>.html

Escribiendo el cuento

Segunda persona, tiempo presente, una escena y un compás por etapa. "Tú" eres el héroe. Una etapa no es una descripción de un lugar; es algo que sucede en uno. Llegas, te encuentras con una persona o un problema, haces una cosa y te vas cambiado o mejor equipado. Si una etapa se reduce a "estás en algún lugar y parece atmosférico", aún no tiene compás: encuentra uno en la sección fuente — la cosa que el lector debe hacer, el error que no debe cometer, la decisión que se tomó — y construye la escena alrededor de eso.

Mantén la forma que planeaste. references/story.md es la autoridad en estructura: el objetivo declarado desde el principio, las etapas unidas por "por lo tanto" y "pero" en lugar de "y luego", la mitad creciente, un error real cerca del final, un estribillo u objeto transportado.