dworzycp/adventure-book

Livro de Aventura

Você está transformando um documento em uma jornada. O leitor percorre, etapa por etapa, uma história ilustrada no tema escolhido pelo usuário, e cada palavra marcada na história pode ser clicada para revelar a coisa real que ela representa: o comando real, a regra, a decisão ou o fato do documento de origem. O resultado é um único arquivo .html que funciona offline, sem dependências.

O motor (navegação, gaveta deslizante, codex, mapa de progresso, parallax, teclado, layout móvel, movimento reduzido) já está embutido em assets/template.html. O script scripts/build_book.py monta seu conteúdo nele. Seu trabalho é a parte criativa e fiel: a história, a alegoria, a prosa, os pop-ups e a arte das cenas.

Três referências guiam o ofício: references/story.md (estrutura — leia-a sempre), references/themes.md (voz e alegoria por tema) e references/scenes.md (desenho).

Os dois fracassos contra os quais projetar são muitas palavras e nenhuma história por baixo delas: um livro que renomeia as seções do documento fantasiadas, etapa após etapa, e enterra os fatos reais na atmosfera. Menos palavras, uma jornada clara.

Fluxo de Trabalho

1. Leia a fonte inteira. Anote seus cabeçalhos, a ordem em que as coisas acontecem, o que se espera que o leitor seja capaz de fazer depois, e quaisquer fatos fáceis de errar (comandos exatos, nomes, números, regras). Esses fatos são o que os pop-ups existem para proteger.
2. Defina o tema e a alegoria. Pegue o tema que o usuário deu; se nenhum foi dado, escolha um que se adeque ao material e diga qual você escolheu. Leia a seção correspondente de references/themes.md para sua voz, motivos, arquétipo de herói e padrão de nomeação de etapas. Em seguida, escreva uma breve tabela de mapeamento para si mesmo: cada conceito real na fonte e sua contraparte temática (VPN = o Véu, banco de dados = a grande besta domada, pipeline de CI = o campo de provas). Mantenha todo mapeamento estável por todo o livro. Leitores aprendem a alegoria uma vez; se o Véu se torna a Névoa no capítulo quatro, o livro para de ensinar.
3. Modele a história. Leia references/story.md e preencha sua espinha dorsal para este livro antes de planejar qualquer coisa: o objetivo que o herói deve alcançar, a cadeia "por causa disso" que o leva até lá, o erro que comete perto do fim e a imagem com que o livro se encerra. Um documento é uma lista de seções; um livro é uma cadeia de consequências, e transformar um no outro é o trabalho todo. Não pule isso porque a fonte parece uma lista simples — são essas que saem como apresentações de slides.
4. Planeje as etapas. Mire de 5 a 9, uma batida cada, mapeadas na espinha dorsal (uma etapa de chegada, três a seis de meio crescente, uma em que dá errado, uma de recompensa). Cada etapa é geralmente uma seção da fonte: mescle seções muito finas para carregar uma batida e divida aquelas que precisariam de mais de cerca de 120 palavras de narrativa. Ordene as etapas conforme o leitor precisaria do conhecimento, que geralmente é a ordem do documento. Dê a cada uma um título na voz do tema e um cabeçalho source: para que o leitor possa desenrolar a seção original de dentro da etapa.
5. Escreva os arquivos de conteúdo em uma pasta de trabalho (book.json, stages/NN-nome.md, scenes/*.svg). Os formatos estão abaixo.
6. Corte e, em seguida, execute a lista de verificação. Releia cada etapa comparando com "Escrevendo a história" e remova cerca de um terço das palavras; os primeiros rascunhos são quase sempre duas vezes mais longos do que o necessário, e cada frase que você deleta torna as palavras marcadas mais fáceis de ver. Em seguida, percorra a lista de verificação no final de references/story.md e corrija o que falhar. Ambas as ações acontecem antes de você construir; nenhuma é um polimento opcional.
7. Construa e leia os avisos. Corrija todo "nenhum pop-up com id", "cabeçalho não encontrado" e aviso de cobertura. Reconstrói até que o relatório esteja limpo ou cada aviso restante seja deliberado.
8. Verifique e entregue. Abra o arquivo (open <arquivo>.html no macOS) ou pelo menos tire um print com headless Chrome se disponível. Diga ao usuário onde o arquivo está, como navegar por ele (teclas de seta, clique no mapa, clique nas palavras brilhantes) e qual tema você usou.

Formatos de conteúdo

book.json (caminhos relativos ao arquivo JSON):

{
  "title": "A Busca pelo Portal",
  "subtitle": "A jornada de um cavaleiro através de AGENTS.md",
  "theme": "knight",
  "source": "../AGENTS.md",
  "cover":  { "eyebrow": "Uma aventura interativa", "scene": "scenes/cover.svg", "blurb": "cover.md" },
  "stages": [ "stages/01-portoes.md", "stages/02-forja.md" ],
  "ending": { "scene": "scenes/ending.svg", "blurb": "ending.md",
              "recap": [ "Atravesse o [[Véu|vpn]] antes de qualquer outra coisa", "Todo pacote voa com o banner `@internal/`" ] }
}

Cada etapa é um arquivo Markdown:

---
id: portoes
title: Os Portões da Fortaleza
chapter: Capítulo I
source: Configuração de Desenvolvimento Local
scene: scenes/01-portoes.svg
---
A névoa se agarra à estrada enquanto você se aproxima da fortaleza. Um guarda barra o caminho: ninguém pode
entrar sem ter passado [[pelo Véu|vpn]] ...

## popout: vpn
title: VPN
Você precisa estar na VPN da empresa antes que qualquer outra coisa funcione, porque o
registro de pacotes interno e os serviços só são acessíveis de dentro da rede.

Regras que o script de construção aplica ou avisa:

• Cada campo de prosa é Markdown. Cada cena é SVG inline, fornecido como um caminho para um arquivo .svg.
• [[texto de exibição|id]] marca um link de pop-up; [[docker]] usa o texto como o id. Cada id precisa de um bloco ## popout: id na mesma etapa (ou um array popouts no nível do livro em book.json).
• source: no frontmatter nomeia um cabeçalho no documento de origem. O script extrai essa seção literalmente e a mostra atrás do botão "rolagem original". Um bloco de pop-up também pode carregar source: <cabeçalho> para anexar a seção relevante sob sua explicação — mas deve ficar nas linhas de cabeçalho do pop-up, diretamente abaixo de ## popout: id junto com title:, não após a explicação. Mal colocado, é lido silenciosamente como prosa e a seção fica descoberta.
• Tema é um nome de predefinição (knight, space, pirate, noir, expedition, deepsea) ou um objeto { "extends": "knight", "colors": {...}, "fonts": {...}, "vocabulary": {...} }. As predefinições vivem em assets/themes.json; copie uma como ponto de partida para um tema inventado.

Construção:

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

Escrevendo a história

Segunda pessoa, presente do indicativo, uma cena e uma batida por etapa. "Você" é o herói. Uma etapa não é uma descrição de um lugar; é algo acontecendo em um. Você chega, encontra uma pessoa ou um problema, faz uma coisa e sai mudado ou melhor equipado. Se uma etapa se resume "você está em algum lugar e parece atmosférico", ainda não tem batida: encontre uma na seção de origem — a coisa que o leitor deve fazer, o erro que não deve cometer, a decisão que foi tomada — e construa a cena em torno disso.

Mantenha a forma que você planejou. references/story.md é a autoridade em estrutura: o objetivo declarado no início, etapas unidas por "portanto" e "mas" em vez de "e então", o meio crescendo, um erro real perto do fim, um refrão ou objeto carregado