アドベンチャーブック
あなたは文書を旅に変えています。読者は、ユーザーが選んだテーマに沿ったイラスト入りの物語を段階的に旅し、物語の中の強調表示された単語をクリックすると、それが表す本当のもの（元の文書に書かれている実際のコマンド、ルール、決定、事実）を見ることができます。出力は1つの.htmlファイルで、オフラインで動作し、依存関係はありません。
エンジン（ナビゲーション、ポップアウトドロワー、コーデックス、進捗マップ、パララックス、キーボード操作、モバイルレイアウト、動きの軽減）は、すでにassets/template.htmlに組み込まれています。scripts/build_book.pyがあなたのコンテンツをそれに組み立てます。あなたの仕事は、創造的で忠実な部分です。つまり、物語、寓話、散文、ポップアウト、そしてシーンアートです。
3つのリファレンスがその技術を支えています。references/story.md（構造 — 毎回読むこと）、references/themes.md（テーマごとの語り口と寓話）、およびreferences/scenes.md（描画）です。
設計上防ぐべき2つの失敗は、言葉が多すぎることとその下に物語がないことです。つまり、文書のセクションに扮装させて名前を変え、舞台を次々と繰り出し、本当の事実を雰囲気で埋もれさせてしまうような本です。より少ない言葉で、1つの明確な旅を。
ワークフロー
- ソース全体を読む。 見出し、物事が起こる順序、読者がその後何ができるようになるべきか、そして間違えやすい事実（正確なコマンド、名前、数値、ルール）に注意してください。これらの事実こそが、ポップアウトが保護するために存在するものです。
- テーマと寓話を固定する。 ユーザーから与えられたテーマを採用します。なければ、素材に合うものを選び、選択したものを伝えてください。対応する
references/themes.mdのセクションを読み、その語り口、モチーフ、英雄の原型、ステージ命名パターンを確認します。次に、簡単なマッピングテーブルを自分用に作成します。ソース内の各実際の概念と、そのテーマ化された対応物（VPN = ヴェール、データベース = 偉大なる飼いならされた獣、CIパイプライン = 試練の場）です。本全体を通して、すべてのマッピングを安定させてください。読者は寓話を一度学びます。ヴェールが第4章で霧になってしまったら、その本は教えることをやめてしまいます。 - 物語を形作る。
references/story.mdを読み、何かを計画する前に、この本のためのストーリースパインを埋めてください。英雄が到達すべき目的、そこに至る「そのせいで」の連鎖、終盤で彼らが犯す過ち、そして本が閉じるイメージです。文書はセクションのリストです。本は結果の連鎖であり、一方を他方に変えることが仕事のすべてです。ソースが単純なリストに見えても、このステップをスキップしないでください。そうしたものこそが、スライドショーになってしまうのです。 - ステージを計画する。 5〜9を目指し、それぞれ1ビートをスパインにマッピングします（到着のステージ1つ、中盤を盛り上げる3〜6つ、事態が悪化する1つ、見返りの1つ）。各ステージは通常、ソースの1セクションに対応します。薄すぎてビートを担えないセクションは統合し、約120語以上のナレーションを必要とするセクションは分割します。読者が知識を必要とする順序（通常は文書の順序）でステージを並べてください。各ステージにテーマの語り口に沿ったタイトルと
source:見出しを付け、読者がステージ内から元のセクションを展開できるようにします。 - コンテンツファイルを書く 作業フォルダ内に（
book.json、stages/NN-name.md、scenes/*.svg）。フォーマットは以下の通りです。 - 削ってから、チェックリストを実行する。 「物語を書く」に照らして各ステージを読み直し、おおよそ3分の1の単語を削除してください。最初の草稿は、必要な長さのほぼ2倍になることがほとんどであり、削除した文ごとに、マークされた単語が見えやすくなります。次に、
references/story.mdの最後にあるチェックリストを実行し、不合格だった点を修正します。これらは両方ともビルドの前に行うものであり、どちらもオプションの仕上げではありません。 - ビルドし、警告を読む。 すべての「idを持つポップアウトが見つかりません」、「見出しが見つかりません」、およびカバレッジ警告を修正します。レポートがクリーンになるか、残っているすべての警告が意図的なものになるまで、再ビルドしてください。
- 検証して引き渡す。 ファイルを開く（macOSでは
open <file>.html）、または少なくとも利用可能な場合はヘッドレスChromeでスクリーンショットを撮ってください。ユーザーにファイルの場所、操作方法（矢印キー、マップのクリック、光る単語のクリック）、および使用したテーマを伝えてください。
コンテンツフォーマット
book.json（パスはJSONファイルからの相対パス）：
{
"title": "ポータルへの探求",
"subtitle": "AGENTS.mdを通る騎士の旅",
"theme": "knight",
"source": "../AGENTS.md",
"cover": { "eyebrow": "インタラクティブアドベンチャー", "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": [ "何よりも先に[[ヴェール|vpn]]を越えよ", "すべてのパッケージは`@internal/`バナーを掲げる" ] }
}
各ステージはMarkdownファイルです：
---
id: gates
title: 城郭の門
chapter: 第I章
source: ローカル開発環境のセットアップ
scene: scenes/01-gates.svg
---
霧が道に立ち込め、あなたが城郭に近づくと、衛兵が道を阻みます。[[ヴェール|vpn]]をくぐらなければ、誰も入城を許されないと言います...
## popout: vpn
title: VPN
何よりも先に会社のVPNに接続する必要があります。内部パッケージレジストリとサービスは、ネットワーク内部からのみ到達可能だからです。
ビルドスクリプトが適用または警告するルール：
- すべての散文フィールドはMarkdownです。すべてのシーンはインラインSVGであり、
.svgファイルへのパスとして指定します。 [[表示テキスト|id]]はポップアウトリンクを示します。[[docker]]はテキストをidとして使用します。各idには、同じステージ内に## popout: idブロックが必要です（またはbook.json内のブックレベルのpopouts配列）。- フロントマターの
source:は、ソース文書内の見出しを指定します。スクリプトはそのセクションをそのまま抽出し、「原典スクロール」ボタンの背後に表示します。ポップアウトブロックは、その説明の下に関連セクションを添付するために、source: <heading>を運ぶこともできます。ただし、それはポップアウトのヘッダー行に、## popout: idの直下でtitle:と並べて配置しなければならず、説明の後に置いてはいけません。誤って配置されると、散文として静かに読み取られ、セクションはカバーされません。 - テーマは、プリセット名（
knight、space、pirate、noir、expedition、deepsea）またはオブジェクト{ "extends": "knight", "colors": {...}, "fonts": {...}, "vocabulary": {...} }です。プリセットはassets/themes.jsonにあり、考案したテーマの出発点として1つをコピーしてください。
ビルド：
python3 <skill-dir>/scripts/build_book.py --content work/book.json --out <name>.html
物語を書く
二人称、現在形、ステージごとに1つのシーンと1つのビート。 「あなた」が英雄です。ステージは場所の説明ではありません。その場所で何かが起こっているのです。あなたは到着し、人または問題に出会い、1つのことを行い、変化するかより良い装備を持って去ります。ステージが「あなたはどこかにいて、雰囲気がある」というだけに要約されるなら、まだビートがありません。ソースセクションからビート（読者がしなければならないこと、してはならない過ち、下された決定）を見つけ、その周りにシーンを構築してください。
計画した形を維持する。 references/story.mdは構造に関する権威です。冒頭で目的を述べ、「そして次に」ではなく「それゆえ」「しかし」で結合されたステージ、盛り上がる中盤、終盤近くでの実際の過ち、繰り返しまたは持ち越されるもの。