changes

src/SUMMARY.md

@@ -4,109 +4,110 @@ A practical handbook for designing puzzles in point-and-click adventure games.
 
 ---
 
-## Part I: Foundations
+# Part I: Foundations
 
-- [Introduction](introduction.md)
+- [Introduction](parts/introduction.md)
 - [Why Adventure Games](parts/why-adventure-games.md)
-- [Core Principles](core-principles.md)
+- [Core Principles](parts/core-principles.md)
 
-## Part II: Design Process
+---
 
-- [Dependency Charts](design-process/dependency-charts.md)
-- [Working Backwards](design-process/working-backwards.md)
-- [Bushy Branching](design-process/bushy-branching.md)
-- [Internal Logic & Fairness](design-process/internal-logic-fairness.md)
-- [Player Psychology](design-process/player-psychology.md)
-- [Playtesting Methodology](design-process/playtesting-methodology.md)
-- [Failure Modes](design-process/failure-modes.md)
-- [Hint System Design](design-process/hint-systems.md)
+# Part II: Design Process
 
-## Part III: Puzzle Taxonomy
+- [Dependency Charts](parts/dependency-charts.md)
+- [Working Backwards](parts/working-backwards.md)
+- [Bushy Branching](parts/bushy-branching.md)
+- [Internal Logic & Fairness](parts/internal-logic-fairness.md)
+- [Player Psychology](parts/player-psychology.md)
+- [Playtesting Methodology](parts/playtesting-methodology.md)
+- [Failure Modes](parts/failure-modes.md)
+- [Hint System Design](parts/hint-systems.md)
 
-### Information Discovery Puzzles
-- [Information Discovery Overview](puzzles/information-discovery-overview.md)
-- [Parallel Multi-Faceted Plans](puzzles/multi-faceted-plan.md)
-- [Sequential Construction](puzzles/sequential-construction.md)
-- [Information Brokerage Chains](puzzles/information-brokerage.md)
-- [Environmental Storytelling Discovery](puzzles/environmental-storytelling.md)
-- [Memo Chain Fragments](puzzles/memo-chain.md)
-- [Truth Revelation Mechanic](puzzles/truth-revelation.md)
+---
 
-### Cognitive Transfer Puzzles
-- [Cognitive Transfer Overview](puzzles/cognitive-transfer-overview.md)
-- [Pattern Learning / Knowledge Transfer](puzzles/pattern-learning.md)
-- [Symbol Code Translation](puzzles/symbol-code-translation.md)
-- [Metaphor-to-Literal Bridges](puzzles/metaphor-literal.md)
-- [Sensory Exploitation](puzzles/sensory-exploitation.md)
-- [Observation Replay](puzzles/observation-replay.md)
+# Part III: Puzzle Taxonomy
 
-### Spatial & Temporal Coordination
-- [Spatial & Temporal Overview](puzzles/spatial-temporal-coordination-overview.md)
-- [Cross-Temporal Causality](puzzles/cross-temporal-causality.md)
-- [Cross-Realm Logistics](puzzles/cross-realm-logistics.md)
-- [Multi-Character Coordination](puzzles/multi-character-coordination.md)
-- [Timed Consequence](puzzles/timed-consequence.md)
+- [Overview & How to Use This Section](puzzles/taxonomy-overview.md)
 
-### NPC Interaction & Social Puzzles
-- [NPC Interaction Overview](puzzles/npc-interaction-overview.md)
-- [Comedy-Based Persuasion](puzzles/comedy-based-persuasion.md)
-- [Distraction & Environmental Manipulation](puzzles/distraction-environmental-manipulation.md)
-- [Class-Specific Challenges](puzzles/class-specific-ritual.md)
-- [Multi-Faction Diplomacy](puzzles/multi-faction-diplomacy.md)
+- [Information Discovery Puzzles](puzzles/information-discovery-overview.md)
+  - [Parallel Multi-Faceted Plans](puzzles/multi-faceted-plan.md)
+  - [Sequential Construction](puzzles/sequential-construction.md)
+  - [Information Brokerage Chains](puzzles/information-brokerage.md)
+  - [Environmental Storytelling Discovery](puzzles/environmental-storytelling.md)
+  - [Memo Chain Fragments](puzzles/memo-chain.md)
+  - [Truth Revelation Mechanic](puzzles/truth-revelation.md)
 
-### Systems & Logic Puzzles
-- [Systems & Logic Overview](puzzles/systems-and-logic-overview.md)
-- [Robot Programming / Color-Encoded Sequences](puzzles/robot-programming.md)
-- [Escalating Combat Progression](puzzles/escalating-combat-progression.md)
+- [Cognitive Transfer Puzzles](puzzles/cognitive-transfer-overview.md)
+  - [Pattern Learning / Knowledge Transfer](puzzles/pattern-learning.md)
+  - [Symbol Code Translation](puzzles/symbol-code-translation.md)
+  - [Metaphor-to-Literal Bridges](puzzles/metaphor-literal.md)
+  - [Sensory Exploitation](puzzles/sensory-exploitation.md)
+  - [Observation Replay](puzzles/observation-replay.md)
 
-### Non-Standard Logic Domains
-- [Non-Standard Domains Overview](puzzles/non-standard-domains-overview.md)
-- [Surreal Logic Bridges](puzzles/surreal-logic-bridge.md)
+- [Spatial & Temporal Coordination](puzzles/spatial-temporal-coordination-overview.md)
+  - [Cross-Temporal Causality](puzzles/cross-temporal-causality.md)
+  - [Cross-Realm Logistics](puzzles/cross-realm-logistics.md)
+  - [Multi-Character Coordination](puzzles/multi-character-coordination.md)
+  - [Timed Consequence](puzzles/timed-consequence.md)
 
-## Part IV: Inspiration
+- [NPC Interaction & Social Puzzles](puzzles/npc-interaction-overview.md)
+  - [Comedy-Based Persuasion](puzzles/comedy-based-persuasion.md)
+  - [Distraction & Environmental Manipulation](puzzles/distraction-environmental-manipulation.md)
+  - [Class-Specific Challenges](puzzles/class-specific-ritual.md)
+  - [Multi-Faction Diplomacy](puzzles/multi-faction-diplomacy.md)
 
-- [Inspiration Index](inspiration/cross-reference-index.md)
+- [Systems & Logic Puzzles](puzzles/systems-and-logic-overview.md)
+  - [Robot Programming / Color-Encoded Sequences](puzzles/robot-programming.md)
+  - [Escalating Combat Progression](puzzles/escalating-combat-progression.md)
 
-### Games Analyzed
+- [Non-Standard Logic Domains](puzzles/non-standard-domains-overview.md)
+  - [Surreal Logic Bridges](puzzles/surreal-logic-bridge.md)
 
-- [Beneath a Steel Sky (1994)](inspiration/beneath-a-steel-sky.md)
-- [Broken Sword 1: Shadow of the Templars (1996)](inspiration/broken-sword-1-shadow-of-the-templars.md)
-- [Broken Sword II: The Smoking Mirror (1997)](inspiration/broken-sword-ii-the-smoking-mirror.md)
-- [Day of the Tentacle (1993)](inspiration/day-of-the-tentacle.md)
-- [Full Throttle (1995)](inspiration/full-throttle.md)
-- [Gabriel Knight 1: Sins of the Fathers (1993)](inspiration/gabriel-knight-1-sins-of-the-fathers.md)
-- [Loom (1990)](inspiration/loom.md)
-- [Grim Fandango (1998)](inspiration/grim-fandango.md)
-- [Indiana Jones and the Fate of Atlantis (1992)](inspiration/indiana-jones-and-the-fate-of-atlantis.md)
-- [Indiana Jones and the Last Crusade (1989)](inspiration/indiana-jones-and-the-last-crusade.md)
-- [King's Quest III: To Heir Is Human (1986)](inspiration/kings-quest-iii-to-heir-is-human.md)
-- [King's Quest VI: Heir Today, Gone Tomorrow (1992)](inspiration/kings-quest-vi-heir-today-gone-tomorrow.md)
-- [King's Quest VII: The Princeless Bride (1994)](inspiration/kings-quest-vii-the-princeless-bride.md)
-- [King's Quest VIII: Mask of Eternity (1998)](inspiration/kings-quest-viii-mask-of-eternity.md)
-- [The Legend of Kyrandia: Book One (1992)](inspiration/the-legend-of-kyrandia-book-one.md)
-- [Maniac Mansion (1987)](inspiration/maniac-mansion.md)
-- [Monkey Island 1: The Secret of Monkey Island (1990)](inspiration/monkey-island-1-the-secret-of-monkey-island.md)
-- [Quest for Glory 1: Shadows of Darkness (1989)](inspiration/quest-for-gloves-1-shadows-of-darkness.md)
-- [Quest for Glory II: Trial by Fire (1989)](inspiration/quest-for-glory-ii-trial-by-fire.md)
-- [Quest for Glory III: Wages of War (1992)](inspiration/quest-for-glory-iii-wages-of-war.md)
-- [Quest for Glory IV: Shadows of Darkness (1994)](inspiration/quest-for-glory-iv-shadows-of-darkness.md)
-- [Sam & Max Hit the Road (1993)](inspiration/sam-and-max-hit-the-road.md)
-- [Simon the Sorcerer (1993)](inspiration/simon-the-sorcerer.md)
-- [Space Quest 1: The Sarien Encounter (1986)](inspiration/spacequest-1-the-sarien-encounter.md)
-- [The Dig (1995)](inspiration/the-dig.md)
-- [Syberia (2002)](inspiration/syberia.md)
-- [The Longest Journey (1999)](inspiration/the-longest-journey.md)
-- [Zak McKracken and the Alien Mindbenders (1988)](inspiration/zak-mckracken-and-the-alien-mindbenders.md)
-- [Space Quest II: The Vohaul Assault (1987)](inspiration/spacequest-2-the-vohaul-assault.md)
-- [SpaceQuest III: The Pirates of Pestulon (1989)](inspiration/spacequest-iii-the-pirates-of-pestulon.md)
-- [SpaceQuest IV: The Rogerwars (1991)](inspiration/spacequest-iv-the-rogerwars.md)
+---
 
-## Part V: Reference
+# Part IV: Inspiration
+
+- [Games Analyzed](inspiration/cross-reference-index.md)
+  - [Beneath a Steel Sky (1994)](inspiration/beneath-a-steel-sky.md)
+  - [Broken Sword 1: Shadow of the Templars (1996)](inspiration/broken-sword-1-shadow-of-the-templars.md)
+  - [Broken Sword II: The Smoking Mirror (1997)](inspiration/broken-sword-ii-the-smoking-mirror.md)
+  - [Day of the Tentacle (1993)](inspiration/day-of-the-tentacle.md)
+  - [Full Throttle (1995)](inspiration/full-throttle.md)
+  - [Gabriel Knight 1: Sins of the Fathers (1993)](inspiration/gabriel-knight-1-sins-of-the-fathers.md)
+  - [Loom (1990)](inspiration/loom.md)
+  - [Grim Fandango (1998)](inspiration/grim-fandango.md)
+  - [Indiana Jones and the Fate of Atlantis (1992)](inspiration/indiana-jones-and-the-fate-of-atlantis.md)
+  - [Indiana Jones and the Last Crusade (1989)](inspiration/indiana-jones-and-the-last-crusade.md)
+  - [King's Quest III: To Heir Is Human (1986)](inspiration/kings-quest-iii-to-heir-is-human.md)
+  - [King's Quest VI: Heir Today, Gone Tomorrow (1992)](inspiration/kings-quest-vi-heir-today-gone-tomorrow.md)
+  - [King's Quest VII: The Princeless Bride (1994)](inspiration/kings-quest-vii-the-princeless-bride.md)
+  - [King's Quest VIII: Mask of Eternity (1998)](inspiration/kings-quest-viii-mask-of-eternity.md)
+  - [The Legend of Kyrandia: Book One (1992)](inspiration/the-legend-of-kyrandia-book-one.md)
+  - [Maniac Mansion (1987)](inspiration/maniac-mansion.md)
+  - [Monkey Island 1: The Secret of Monkey Island (1990)](inspiration/monkey-island-1-the-secret-of-monkey-island.md)
+  - [Quest for Glory 1: Shadows of Darkness (1989)](inspiration/quest-for-gloves-1-shadows-of-darkness.md)
+  - [Quest for Glory II: Trial by Fire (1989)](inspiration/quest-for-glory-ii-trial-by-fire.md)
+  - [Quest for Glory III: Wages of War (1992)](inspiration/quest-for-glory-iii-wages-of-war.md)
+  - [Quest for Glory IV: Shadows of Darkness (1994)](inspiration/quest-for-glory-iv-shadows-of-darkness.md)
+  - [Sam & Max Hit the Road (1993)](inspiration/sam-and-max-hit-the-road.md)
+  - [Simon the Sorcerer (1993)](inspiration/simon-the-sorcerer.md)
+  - [Space Quest 1: The Sarien Encounter (1986)](inspiration/spacequest-1-the-sarien-encounter.md)
+  - [The Dig (1995)](inspiration/the-dig.md)
+  - [Syberia (2002)](inspiration/syberia.md)
+  - [The Longest Journey (1999)](inspiration/the-longest-journey.md)
+  - [Zak McKracken and the Alien Mindbenders (1988)](inspiration/zak-mckracken-and-the-alien-mindbenders.md)
+  - [Space Quest II: The Vohaul Assault (1987)](inspiration/spacequest-2-the-vohaul-assault.md)
+  - [Space Quest III: The Pirates of Pestulon (1989)](inspiration/spacequest-iii-the-pirates-of-pestulon.md)
+  - [Space Quest IV: The Rogerwars (1991)](inspiration/spacequest-iv-the-rogerwars.md)
+
+---
+
+# Part V: Reference
 
 - [Common Pitfalls](docs/common-pitfalls.md)
 - [Validation Checklist](docs/validation-checklist.md)
 - [Quick-Start Worksheet](docs/quick-start-worksheet.md)
 
-## Part VI: FAQ
+# Part VI: FAQ
 
 - [FAQ](docs/faq.md)

src/core-principles.md

@@ -1,94 +0,0 @@
-# Core Principles
-
-These principles define adventure game puzzle design at the highest level. Every puzzle type in this handbook manifests these principles in different ways.
-
----
-
-## 1. Limited Actions, Unlimited Combinations
-
-The standard adventure game action set (LOOK, TALK, USE, WALK, TAKE) is applied in novel ways. The puzzle emerges from the *combination* of actions, not from complex input systems.
-
-**What this means:** You don't need more verbs. You need more interesting combinations of existing verbs.
-
----
-
-## 2. Information as Puzzle Element
-
-The puzzle is often "what does the game know that I need to find out?" rather than "what do I need to do?" Information discovery is the primary mechanic.
-
-**What this means:** Often the puzzle isn't the solution—it's figuring out what the problem even is.
-
----
-
-## 3. Failure as Feedback
-
-Failed attempts reveal information about what's missing or wrong. The puzzle teaches through consequences, not explicit instruction.
-
-**What this means:** Every failed attempt should narrow the possibility space, not expand it randomly.
-
----
-
-## 4. Synthesis Over Collection
-
-The solution often requires combining information from multiple sources. No single action completes the puzzle—player must synthesize.
-
-**What this means:** Don't let players "collect" their way to victory. They must understand how pieces connect.
-
----
-
-## 5. Inception Over Extraction
-
-The designer should plant the solution in the player's mind through earlier puzzles, rather than forcing players to guess random combinations.
-
-**Why it matters:** Players who feel clever are engaged. Players who feel like they're guessing are frustrated.
-
-**Source:** [Adventure Puzzle Design](resources/puzzle-design/adventure-puzzle-design-stanislav-costiuc.md)
-
----
-
-## 6. Reward Intent
-
-When players have the right idea, let them succeed. Interface punishment for near-correct actions breaks the contract between designer and player.
-
-**Why it matters:** The #1 complaint about adventure games ("moon logic") often stems from players having the right idea but executing it wrong.
-
-**Source:** [Why Adventure Games Suck](resources/criticism/why-adventure-games-suck-ron-gilbert.md)
-
----
-
-## 7. Internal Logic Must Prevail
-
-Solutions must follow from rules established by the game world. Arbitrary solutions violate the player's mental model.
-
-**Why it matters:** Players build a model of how the world works. When solutions contradict that model, trust breaks.
-
-**Source:** [14 Deadly Sins](resources/criticism/14-deadly-sins-graphic-adventure-design-filfre.md)
-
----
-
-## 8. Clarity of Objective
-
-Players should always know their ultimate goal and their immediate next step. Ambiguity creates frustration, not mystery.
-
-**Why it matters:** "What should I do next?" is the most common stuck-player question. Clear sub-goals prevent stuckness.
-
-**Source:** [Why Adventure Games Suck](resources/criticism/why-adventure-games-suck-ron-gilbert.md)
-
----
-
-## How These Principles Apply
-
-Every puzzle type in this handbook should be evaluated against these principles:
-
-| Principle | Question to Ask |
-|-----------|-----------------|
-| Limited Actions | Could this puzzle work with fewer verbs? |
-| Information First | Does the player know what they need to find? |
-| Failure as Feedback | Does failing teach something useful? |
-| Synthesis | Must player combine multiple sources? |
-| Inception | Does the puzzle teach its own solution? |
-| Reward Intent | Does near-correct execution work? |
-| Internal Logic | Does the solution follow from established rules? |
-| Clarity | Does the player know their goal? |
-
-When designing a puzzle, if you can't answer "yes" to most of these, the puzzle needs redesign.

src/documentation-structure.md

@@ -1,48 +0,0 @@
-# Documentation Structure
-
-Each puzzle type document contains:
-
-- **Information Architecture**: How information is conveyed to the player
-- **Player Action Pattern**: What the player does with that information
-- **Core Mechanic**: The underlying puzzle logic
-- **Variations**: Different ways this type can manifest  
-- **Adventure Game Implementation**: How limited actions (LOOK, TALK, USE, WALK) map to the puzzle
-- **Example Structure**: Generic template showing how the puzzle works
-- **Game Examples**: Concrete instances from walkthroughs
-- **Related Types**: Cross-references to similar puzzle mechanics
-
-## Template Format
-
-```markdown
-# [Type Name]
-
-**Information Architecture**: How player discovers puzzle structure.
-
-**Player Action Pattern**:
-1. Step one
-2. Step two
-3. Solution
-
-**Core Mechanic**: Single sentence explaining underlying logic.
-
-**Variations**: Brief list of possible manifestations
-
----
-
-## Game Examples
-
-### [Game]: [Puzzle Name]
-
-**Setup**: Brief context description.
-
-**Solution Chain**:
-1-5. Actions with discoveries...
-
-**Why It's This Type**: Explicit connection to core mechanic above.
-
----
-
-## Related Types
-
-| Type | Similarity | Distinction |
-```

src/inspiration.md

@@ -1,91 +0,0 @@
-# Inspiration
-
-This section presents a curated sampling of masterful puzzles from over 30 classic point-and-click adventure games spanning the golden era of 1986–2002. Each game featured here demonstrated exceptional design at its release—puzzles that players remembered for all the right reasons, mechanics that rewarded observation and logical reasoning rather than frustrating guesswork.
-
-Why study these puzzles? Because they established patterns still applicable to modern game design. The "Knowledge Transfer" puzzle from Monkey Island teaches responses to insults early, then requires applying them in a completely different context later—no hint connects the two. This is pattern-based learning independent of narrative. Similarly, Loom's musical theme composition translates abstract rules into literal gameplay mechanics, proving that metaphorical thinking can drive concrete player actions across any genre.
-
-The walkthroughs that birthed these games contain invaluable design documentation. When a 1995 guide describes the fertilizer truck chase in Full Throttle as requiring players to "ride through the fertilizer in the road and they will crash," it reveals cause-and-effect clarity absent from contemporary puzzle slop. These mechanical descriptions—not story retellings—form the backbone of this section's analysis.
-
----
-
-## Purpose
-
-This Inspiration section serves three specific goals:
-
-**Understand puzzle type structures independent of plot and setting.** A timed-consequence puzzle works identically whether draining an atomic reactor (Maniac Mansion) or cooling a nuclear fuel rod (Broken Sword 1). This mechanical neutrality enables direct comparison across disparate games.
-
-**Reference implementations from proven, beloved games.** Every puzzle documented here comes from commercial releases that succeeded with actual players. These walkthroughs represent the "canon" of adventure game design—patterns so effective they've persisted in designer consciousness for decades.
-
-**Enable mechanical pattern analysis rather than narrative replay.** Notice the difference: Pattern learning teaches a *system* with reusable rules (learn beavers only swim when lit, apply to three scenarios). Observation replay memorizes a *sequence* to reproduce verbatim (press button A, then B, then C). This section emphasizes the former.
-
----
-
-## Format Requirements
-
-Each puzzle in this section follows a four-part structure:
-
-### Problem
-
-What contrivance or obstacle blocks progress? This identifies the design challenge without revealing the solution. Typically 2–3 sentences describing what exists and why it prevents forward movement.
-
-### Why It Works
-
-What mechanical design choices create satisfaction rather than frustration? Ground analysis in concrete implementation details, not vague praise like "clever" or "creative." Include a walkthrough quote when available demonstrating player discovery. Target 2–3 sentences explaining *how* the mechanism functions.
-
-### Solution
-
-One-sentence outcome achieved. State what changes after completion—no intermediate steps, no vagueness. The beaver gate opens. The tombstone inscription decodes correctly. The union card enters your inventory.
-
-### Steps
-
-Numbered list of specific player actions. Replace "solve puzzle" or "figure out how" with concrete verbs: examine, collect, switch, combine, insert, rotate, observe. Each step should require a discrete input or decision. This is where mechanical patterns become visible across different games.
-
----
-
-## Use This Section
-
-Each game page contains three puzzles analyzed using the format above. At the end of every puzzle entry, you'll find a link to its corresponding pattern type in the Playbook (e.g., [Timed Consequence](../puzzles/timed-consequence.md)). These cross-references enable two modes of study:
-
-**Vertical comparison:** Track how a single mechanic evolves across games. The Multi-Faceted Plan appears in Zak McKracken (gather three components from separate sources), Spacequest 2 (combine four elements for escape), and Syberia (assemble automaton parts)—yet each implementation differs significantly in execution.
-
-**Horizontal exploration:** Examine any specific game page to see its full puzzle ecosystem. Grim Fandango demonstrates Pattern Learning, Meta-Puzzle Construction, and Symbol Code Translation all working within a unified world—proving mechanical diversity strengthens rather than fragments cohesive design.
-
-Pattern type abbreviations appear throughout these pages to reduce repetition: MI1 (Monkey Island 1), MI2 (Monkey Island 2), KQVI (King's Quest VI). These reference implementations signal we're documenting specific, replayable mechanics—not abstract philosophy.
-
----
-
-## At a Glance
-
-| Game | Year | Developer | Featured Puzzles | Notable Pattern Type |
-|------|------|---------|------------------|----------------------|
-| Maniac Mansion | 1987 | Lucasfilm Games / Ron Gilbert | 3 | Timed Consequence |
-| Beneath a Steel Sky | 1994 | Revolution Software | 3 | Sensory Exploitation |
-| Broken Sword 1: Shadow of the Templars | 1996 | Revolution Software | 3 | Meta-Puzzle Construction |
-| Broken Sword II: The Smoking Mirror | 1997 | Revolution Software | 3 | Multi-Character Coordination |
-| Day of the Tentacle | 1993 | Lucasfilm Games / Ron Gilbert | 3 | Cross-Temporal Causality |
-| Full Throttle | 1995 | LucasArts / Ron Gilbert | 3 | Multi-Faceted Plan |
-| Gabriel Knight 1: Sins of the Fathers | 1993 | Sierra On-Line / Jane Jensen | 3 | Symbol Code Translation |
-| Grim Fandango | 1998 | LucasArts / Tim Schafer | 3 | Pattern Learning |
-| Indiana Jones and the Fate of Atlantis | 1992 | Lucasfilm Games | 3 | Metaphor-Literal |
-| Indiana Jones and the Last Crusade | 1989 | Lucasfilm Games / LucaArts | 3 | Symbol Code Translation |
-| King's Quest III: To Heir Is Human | 1986 | Sierra On-Line / Roberta Williams | 3 | Class-Specific Ritual Challenge |
-| King's Quest VII: The Princeless Bride | 1994 | Sierra On-Line | 3 | Multi-Faceted Plan |
-| King's Quest VIII: Mask of Eternity | 1998 | Sierra On-Line | 3 | Pattern Learning |
-| Kyrandria 1: Shadow of the Fox | 1992 | Westwood Studios | 3 | Observation Replay |
-| Loom | 1990 | Lucasfilm Games / Brian Moriarty | 3 | Metaphor-to-Literal |
-| Quest for Glory 1: Shadows of Darkness | 1989 | Sierra On-Line / Cole & Cole | 3 | Meta-Puzzle Construction |
-| Quest for Glory II: Trial by Fire | 1989 | Sierra On-Line / Cole & Cole | 3 | Class-Specific Ritual |
-| Quest for Glory III: Wages of War | 1992 | Sierra On-Line / Cole & Cole | 3 | Pattern Learning |
-| Quest for Glory IV: Shadows of Darkness | 1994 | Sierra Entertainment / Corey Cole | 3 | Multi-Faceted Plan |
-| Sam & Max Hit the Road | 1993 | LucasArts | 3 | Timed Consequence |
-| Simon the Sorcerer | 1993 | Revolution Software / Infogrames | 3 | Meta-Puzzle Construction |
-| Spacequest 1: The Sarien Encounter | 1986 | Sierra On-Line | 3 | Information Brokerage |
-| Spacequest II: The Vohaul Assault | 1987 | Sierra On-Line | 3 | Multi-Faceted Plan |
-| Spacequest III: The Pirates of Pestulon | 1989 | Sierra On-Line | 3 | Pattern Learning |
-| Spacequest IV: The Rogerwars | 1991 | Sierra On-Line | 3 | Timed Consequence |
-| Syberia | 2002 | Microids / Benoît Sokal | 3 | Repair Chain Construction |
-| The Dig | 1995 | LucasArts | 3 | Meta-Puzzle Construction |
-| The Longest Journey | 1999 | Funcom / Ragnar Tørnquist | 3 | Meta-Puzzle Construction |
-| Zak McKracken and the Alien Mindbenders | 1988 | Lucasfilm Games | 3 | Pattern Learning |
-
-**Navigation:** Each game page in this section links its puzzles to Playbook pattern types. To understand a mechanical pattern deeply, follow those links for detailed analysis across multiple implementations.

src/introduction.md

@@ -1,66 +0,0 @@
-# Introduction
-
-## Feeling Smart
-
-Near the end of *Monkey Island 2: LeChuck's Revenge*, you face LeChuck's ghost terrorizing you. No matter what you do, LeChuck finds Guybrush and torchers him. You've gone through the entire game just to be stuck in an endless loop, seemingly. But then, the elevator closes on his beard. That's weird. After harvesting his beard, it gives you, the player a flashback. Days earlier, you had  spent hours constructing a voodoo doll of his henchman Largo—figuring out that you needed thread, a head, some body material, and something dead. Each piece required its own sub-puzzle scattered across the game world.
-
-Now here's LeChuck's floating, invincible specter. The game doesn't explain anything. It doesn't need to.
-
-*Oh*, you think. *Another voodoo doll.*
-
-The rules transfer. You already know how this works. Something of the head, Something of of the Therad, something of the body, something of the dead - the same recipe, not laid out for you, but you get to put the puzzle pieces together. That gentle nudge, when fulfilled, makes you feel smart.
-
-## Feeling Stuck
-
-Years earlier, I sat on my grandfather's desk playing *King's Quest V*. We'd reached what seemed like progress when we hit a wall: sitting in the innkeeper's jail cell, tied up, and game over. This is a classic example of a "dead end" or a "dead man walking" problem, where there is no path forward but to load an old save file and play everything out again. Hours prior, a seemingly unimportant event occured, several screens away from this. A cat was chasing a mouse, caught it, and carried it away. It'd be easy to dismiss this as game flavor, but it turns out that this was important. The player needed to throw a boot at the cat in the nick of time. Nothing tells you this. If the player does this, then a mouse will come and chew through Graham's ropes, saving him.
-
-The only clue about this is that there is a mousehole in the wall in the cellar. This wasn't a puzzle; it was a checkpoint behind a guess.  The experience wasn't challenging in the right way. It was disempowering, and our session ended not with triumph but with the glow of a walkthrough on a monitor.
-
-## Why This Handbook Exists
-
-Those two moments defined my relationship with adventure games. *King's Quest* series played with my grandfather introduced me to interactive storytelling. The frustration of bad puzzles and the satisfaction of good ones showed me that design mattered—that there was actual craft happening beneath the graphics and dialogue.
-
-That realization made me want to be a programmer. More specifically, it made me want to make games where players feel smart, not stuck.
-
-Adventure game puzzle design is fundamentally undertaught. The golden age produced masterworks like *Monkey Island*, *Quest for Glory*, *Grim Fandango*, and *The Longest Journey*—games built by designers who learned through practice and iteration. But nobody wrote the handbook. Nobody documented what made those puzzles work so that the next generation could build on it instead of rediscovering it. I've written on the topic periodically, but far more material explains what not to do than what to do. I hope to aim that
-
-
-### A note on LLMs
-
-I am a huge advocate of AI powered tools. In fact, this book was written over many sessions of interaction with Qwen3.5-27B. I took this as a specific challenge in authoring this book, for several reasons:
-
-1. LLMs -- event SOTA from OpenAI and Anthropic -- absolutely suck at adventure game design. Ask for advice and you'll get the most generic slop game design recommendation. This handbook should be usable by an LLM to help brainstorm ideas with designers.
-2. Qwen3.5-27B is a model that hits way above its weight class. As an open-weight model, and relatively low parameter, if an LLM can help author and use this handbook, then so can the larger models.
-
-This book is not meant to automate the process of adventure game design.  If anything, I think the systems in adventure games *need* a human touch, more than any other game type. But I believe that good games can be made great with the help of this handbook in the hands of an AI practitioner
-
-**This handbook documents those patterns.**
-
-## What's Inside
-
-### The Playbook
-
-The core of this book catalogs puzzle types from thirty-plus classic adventure games. Each entry explains:
-
-- **Core Mechanic**: Three sentences maximum on what this pattern achieves
-- **Solution Chain**: The specific player actions required to solve it
-- **Game Examples**: Three concrete implementations with explicit analysis of why each fits the pattern
-- **Related Types**: How this differs from similar mechanics you might confuse it with
-
-The Playbook covers everything from multi-source discovery (gathering requirements across disparate locations) to sequential construction (where step N's output enables step N+1) to NPC interaction patterns that turn characters into gameplay systems rather than story devices.
-
-### A Sampling of Puzzles
-
-After the Playbook, you'll find detailed analyses of memorable puzzles from games like *Monkey Island 1 & 2*, *King's Quest VI*, *Quest for Glory III & IV*, *The Dig*, *Full Throttle*, and many others. Every example links back to its puzzle type in the Playbook, so you can see patterns in action across different contexts.
-
-### FAQ: Solving Design Problems
-
-The final section addresses common design challenges with actionable solutions grounded in documented patterns. "My puzzle feels like fetch quest" becomes "Here's how to add synthesis." "Players are stuck with no feedback" becomes "Use failure-as-information mechanics from these examples."
-
----
-
-The difference between a voodoo doll puzzle and a cat on a ledge is whether the designer trusts players to learn, adapt, and solve problems using information the game actually provided. One creates advocates who talk about that game for decades. The other creates walkthrough readers.
-
-This handbook exists because adventure games deserve better, and the next generation of designers deserves the craft knowledge that created them.
-
-Let's build more puzzles where the "aha" moment is genuinely earned.

src/parts/bushy-branching.md

@@ -0,0 +1 @@
+# Bushy Branching

src/parts/core-principles.md

@@ -0,0 +1 @@
+# Core Principles

src/parts/dependency-charts.md

@@ -0,0 +1 @@
+# Dependency Charts

src/parts/failure-modes.md

@@ -0,0 +1 @@
+# Failure Modes

src/parts/hint-systems.md

@@ -0,0 +1 @@
+# Hint System Design

src/parts/internal-logic-fairness.md

@@ -0,0 +1 @@
+# Internal Logic & Fairness

src/parts/introduction.md

@@ -0,0 +1 @@
+# Introduction

src/parts/player-psychology.md

@@ -0,0 +1 @@
+# Player Psychology

src/parts/playtesting-methodology.md

@@ -0,0 +1 @@
+# Playtesting Methodology

src/parts/working-backwards.md

@@ -0,0 +1 @@
+# Working Backwards

src/puzzles/taxonomy-overview.md

@@ -0,0 +1 @@
+# Overview & How to Use This Section