command -v yq >/dev/null 2>&1 && yq --version 2>&1 | head -1

yq '{"name": .name, "start_node": .start_node, "initial_character": .initial_character, "initial_world": .initial_world, "ending_ids": [.endings | keys | .[]]}' scenario.yaml

Read scenario file with limit: 200

yq '.nodes.NODE_ID' scenario.yaml

yq '.nodes.NODE_ID as $n | {"narrative": $n.narrative, "prompt": $n.choice.prompt, "options": [$n.choice.options[] | {"id": .id, "text": .text, "cell": .cell, "precondition": .precondition, "next_node": .next_node, "has_improvise": (.next == "improvise"), "outcome_nodes": .outcome_nodes}]}' scenario.yaml

Pattern: "^  {node_id}:"
Context: -A 80
Path: scenario file

yq '.nodes as $all | .nodes.NODE_ID.choice.options[] | select(.next == "improvise") | .outcome_nodes | to_entries | .[] | {"cell": .key, "node": $all[.value]}' scenario.yaml

# Find nodes by keyword/theme
yq '.nodes | keys | .[]' scenario.yaml | grep -i 'keyword1\|keyword2\|theme'

# Example: Finding morning-after scenes
yq '.nodes | keys | .[]' scenario.yaml | grep -i 'morning\|wake\|dawn'

grep -i 'keyword' scenario.yaml | grep -E '^\s{2}\w+:'

GAME_STATE:
  scenario_name: string       # e.g., "dragon_quest"
  current_node: string        # Current node ID
  previous_node: string       # Previous node ID (for blocked restoration)

  # 3-Level Counter (see lib/framework/presentation.md)
  turn: number                # Major node transitions
  scene: number               # Groupings within turn (resets on turn++)
  beat: number                # Individual moments (resets on scene++)
  scene_title: string         # Auto-generated or from scenario
  scene_location: string      # Location when scene started

  # Beat log for export reconstruction
  beat_log: [                 # Cleared on session end or export
    {turn, scene, beat, type, action, consequences}
  ]

  character:
    exists: boolean           # false = None (character ceased)
    traits: {name: value}     # courage, wisdom, luck, etc.
    inventory: [items]        # Items held
    flags: {flag: boolean}    # Character-specific flags

  world:
    current_location: string  # Location ID
    time: number              # Time in seconds since game start
    flags: {flag: boolean}    # World state flags
    location_state:           # Per-location mutable state
      [location_id]:
        flags: {flag: boolean}
        properties: {name: number}
        environment: {lighting: "dim", temperature: 20}  # Environmental conditions

    # NEW in Phase 4 (v5)
    npc_locations:            # NPC position tracking
      [npc_id]: location_id   # Maps NPC to their current location

    scheduled_events:         # Pending events
      - event_id: string
        trigger_at: number    # Time (seconds) when event fires
        consequences: [...]   # Consequences to apply

    triggered_events: [string]  # IDs of events that have fired

  settings:
    improvisation_temperature: number  # 0-10, controls narrative adaptation
                                       # 0 = verbatim, 5 = balanced, 10 = fully adaptive
    gallery_mode: boolean              # Enable meta-commentary
    foresight: number                  # 0-10, controls hint specificity
    classic_mode: boolean              # Hide scripted options (parser mode)

  recent_history: [string]    # Last 3-5 turns for context

TURN:
  1. Get current node:
     - Standard mode: Access scenario.nodes[current_node] from cached scenario
     - Lazy mode: Grep for "^  {current_node}:" with -A 80, parse YAML

  1a. Process elapsed_since_previous (NEW in v5):
      - If node has elapsed_since_previous:
        - Convert to seconds: amount * TIME_UNITS[unit]
        - Add to world.time
        - Check scheduled events (step 1b)

  1b. Check and process scheduled events (NEW in v5):
      - For each event in scheduled_events where trigger_at <= world.time:
        - Apply event consequences
        - Add event_id to triggered_events
        - Remove from scheduled_events
      - Process events in order (lowest trigger_at first)
      - Max cascade depth: 10 (prevent infinite loops from event chains)

  2. Check for ending:
     - If current_node is in scenario.endings → display ending, save state, EXIT
     - If character.exists == false → display death ending, save state, EXIT

  2a. Check node precondition (if present):
     - If current node has `precondition`:
       - Evaluate precondition against current state
       - If FAILS:
         - Display blocked message (see "Blocked Display Format" below)
         - Restore: current_node = previous node (the node we came from)
         - Do NOT increment turn counter
         - GOTO step 4 (re-present previous choices)
       - If PASSES: continue normally

  3. Display narrative (with temperature adaptation):
     - Read settings.improvisation_temperature (default: 5)
     - Collect relevant improv_* flags from character.flags
     - IF temperature > 0 AND improv_* flags exist:
       - Generate contextual framing based on temperature level
       - Weave into or prepend to narrative text
       - See lib/framework/improvisation.md → "Improvisation Temperature"
     - Output the (possibly adapted) narrative with formatting
     - Show character stats line

  4. Evaluate available choices (with temperature adaptation):
     - For each option in node.choice.options:
       - Evaluate precondition against current state
       - If passes: add to available choices
       - If fails: EXCLUDE from choices (do not show)
     - IF temperature >= 4 AND improv_* flags exist:
       - Enrich option descriptions with improv context
       - E.g., "Attack with your sword (you recall its scarred side)"
     - IF temperature >= 7 AND improv_* flags suggest bonus action:
       - Generate at most 1 bonus option based on improv flags
       - Bonus options use soft consequences only (like free-text improv)
       - See lib/framework/improvisation.md → "Bonus Options"

  5. Present choices via AskUserQuestion:

     **IF settings.classic_mode == true:**
     ```json
     {
       "questions": [{
         "question": "[node.choice.prompt]",
         "header": "Action",
         "multiSelect": false,
         "options": [
           {"label": "Look around", "description": "Survey your surroundings"},
           {"label": "Inventory", "description": "Check what you're carrying"},
           {"label": "Show help", "description": "See commands that might work here"}
         ]
       }]
     }
     ```

     **ELSE (classic_mode == false):**
     ```json
     {
       "questions": [{
         "question": "[node.choice.prompt]",
         "header": "Choice",
         "multiSelect": false,
         "options": [available choices + bonus option if generated]
       }]
     }
     ```

  6. Wait for user selection

  6a. IF selection doesn't match any predefined option (free-text via "Other"):
      - Classify intent (Explore/Interact/Act/Meta)
      - Check feasibility against current state
      - Generate narrative response matching scenario tone
      - Apply soft consequences only (trait ±1, add_history, improv_* flags)
      - Beat++ (log to beat_log with type: "improv", action: summary)
      - Check scene triggers: location change, time skip, beat >= 5
        - If triggered: Scene++, beat→1, update scene_title
      - Display response with consequence indicators
      - Present same choices again (step 5)
      - Do NOT advance node or turn
      - GOTO step 6

  6b. IF selected option has `next: improvise` (scripted Unknown path):
      - Execute Scripted Improvisation Flow (see below)
      - GOTO step 1 if outcome node specified, else GOTO step 5

  6c. IF selection is a generated bonus option:
      - Treat like emergent improvisation (same as 6a)
      - Generate narrative response matching scenario tone
      - Apply soft consequences only (trait ±1, add_history, improv_* flags)
      - Beat++ (log to beat_log with type: "bonus", action: option label)
      - Check scene triggers (same as 6a)
      - Display response with consequence indicators
      - Present same choices again (step 5) — bonus option remains available
      - Do NOT advance node or turn
      - GOTO step 6

  6d. IF selection is "Look around" (classic mode):
      - Re-display current node narrative (abbreviated if long)
      - Extract and list exits mentioned in narrative
      - Extract and list notable items/NPCs if mentioned
      - Format as atmospheric description, not menu
      - Beat++ (log to beat_log with type: "look")
      - Present choices again
      - Do NOT advance node or turn
      - GOTO step 6

  6e. IF selection is "Inventory" (classic mode):
      - Display character.inventory as formatted list
      - If empty: "You are empty-handed."
      - If items: List each with brief description if available
      - Beat++ (log to beat_log with type: "inventory")
      - Present choices again
      - Do NOT advance node or turn
      - GOTO step 6

  6f. IF selection is "Show help" (classic mode):
      - Generate adaptive help from hidden options (see below)
      - Beat++ (log to beat_log with type: "help")
      - Present choices again
      - Do NOT advance node or turn
      - GOTO step 6

      **Adaptive Help Generation:**

      1. Extract verbs from hidden options:
         - Read all `options[].text` from current node
         - Parse the leading verb (e.g., "Open the mailbox" → "open")
         - Lowercase and deduplicate verbs

      2. Categorize by action type:
         ```
         MOVEMENT:     go, enter, climb, descend, exit, flee, leave, walk
         EXAMINE:      examine, look, read, search, inspect, study
         INTERACT:     open, close, take, drop, give, use, push, pull, turn
         COMBAT:       attack, fight, defend, strike, parry
         COMMUNICATE:  say, ask, talk, tell, shout, whisper
         ```

      3. Generate contextual help output:
         ```
         ═══════════════════════════════════════════════════════════════════════
         COMMANDS THAT MIGHT WORK HERE
         ═══════════════════════════════════════════════════════════════════════

         Movement:    go [direction], enter
         Examine:     examine [thing], read
         Interact:    open, take

         UNIVERSAL COMMANDS
         inventory    - check what you're carrying
         look         - survey surroundings
         save         - save your game
         ═══════════════════════════════════════════════════════════════════════
         ```

      4. What to include/exclude:
         - INCLUDE: Verbs extracted from available options
         - INCLUDE: Universal commands (inventory, look, save)
         - EXCLUDE: Specific objects (say "open" not "open mailbox")
         - EXCLUDE: Which directions are valid
         - EXCLUDE: Options blocked by preconditions

      5. If no contextual verbs found (node has no options):
         - Show only universal commands section

  7. Display option narrative (if present):
     - Check if selected option has a `narrative` field
     - If present: display it (plain text, no box format)
     - This is the immediate feedback to the player's choice

  8. Apply consequences of chosen option:
     - Execute each consequence type (see Consequence Application table)
     - Update character/world state in memory
     - After all consequences: re-check scheduled events (step 1b)
       - This handles advance_time or schedule_event consequences

  9. Advance state:
     - Log current beat: beat_log.append({turn, scene, beat, type: "scripted_choice", action: option.text})
     - Set previous_node = current_node   # Save for blocked restoration
     - Set current_node = option.next_node
     - Turn++ (resets scene→1, beat→1)
     - Update scene_location = world.current_location
     - Generate scene_title from new node context
     - Add choice to recent_history (keep last 5)

  10. GOTO step 1 (next turn)

yq '.nodes.CURRENT_NODE | {"title": (.title // ("Node: " + "CURRENT_NODE")), "preview": (.narrative | split("\n") | map(select(. != "")) | .[0])}' scenario.yaml

current_node_title: "Village Crossroads"      # From .title or generated
current_node_preview: "The village elder..."   # First line of narrative

╭──────────────────────────────────────────────────────────────────────╮
│ ACCESS DENIED                                                        │
╰──────────────────────────────────────────────────────────────────────╯

[access_denied_narrative or generated fallback]

You cannot enter [location name].

╭──────────────────────────────────────────────────────────────────────╮
│ BLOCKED                                                              │
╰──────────────────────────────────────────────────────────────────────╯

[blocked_narrative or generated fallback]

You remain where you are.

ERROR: Start node cannot have a precondition.
The scenario "[name]" has an invalid configuration.

{
  "questions": [{
    "question": "What specifically do you do?",
    "header": "Action",
    "multiSelect": false,
    "options": [
      {"label": "Watch carefully", "description": "Observe and study"},
      {"label": "Wait patiently", "description": "See what happens"},
      {"label": "Look for details", "description": "Search for information"}
    ]
  }]
}

IF response matches any pattern in `permits`:
  cell = Discovery (Unknown + World Permits)

ELSE IF response matches any pattern in `blocks`:
  cell = Revelation (Unknown + World Blocks)

ELSE:
  cell = Limbo (Unknown + World Indeterminate)

outcome_nodes:
  discovery: dragon_notices_patience
  revelation: dragon_dismisses_hesitation
  # limbo: omitted

Option selected: "Wait and observe the dragon"
  └── has next: improvise

Sub-prompt: "What specifically do you do?"
  └── Player response: "I study the inscriptions on its scales"

Pattern match:
  └── permits: ["scales", "inscriptions"] ← MATCH
  └── cell = Discovery

Generate narrative:
  └── "You peer closer at the ancient markings etched into the iron-hard
       scales. They seem to form words in a language older than human
       memory. One pattern repeats - a symbol of greeting, perhaps?"
  └── +1 wisdom - Attention to detail

Outcome nodes:
  └── discovery: dragon_notices_patience
  └── Advance to dragon_notices_patience, turn++

{
  "questions": [{
    "question": "The dragon awaits. What do you do?",
    "header": "Choice",
    "multiSelect": false,
    "options": [
      {"label": "Fight", "description": "Attack with your sword"},
      {"label": "Negotiate", "description": "Attempt to speak with the dragon"},
      {"label": "Flee", "description": "Retreat to safety"}
    ]
  }]
}

╔═══════════════════════════════════════════════════════════╗
| VICTORY                                                   |
╚═══════════════════════════════════════════════════════════╝

[Ending narrative - celebratory tone]

╔═══════════════════════════════════════════════════════════╗
| DEATH                                                     |
╚═══════════════════════════════════════════════════════════╝

[Ending narrative - somber, respectful]

╔═══════════════════════════════════════════════════════════╗
| TRANSCENDENCE                                             |
╚═══════════════════════════════════════════════════════════╝

[Ending narrative - mystical, transformative]

╔═══════════════════════════════════════════════════════════╗
| UNCHANGED                                                 |
╚═══════════════════════════════════════════════════════════╝

[Ending narrative - ironic, reflective]