.

.claude/projects/-home-cliffe-Files-Projects-Code-BreakEscape-BreakEscape/memory/MEMORY.md

@@ -0,0 +1,6 @@
+# Memory Index
+
+- [Terminals are minigames, not ink](terminals-are-minigames-not-ink.md) — terminal task completion goes via globals + eventMappings, never ink
+- [Use objective_task_completed event pattern](m02-event-pattern-objective-task-completed.md) — NPC eventMappings: objective_task_completed:<id>, not task_completed:<id>
+- [Ink decompiler tooling](ink-decompiler-tooling.md) — recover .ink from compiled inkVersion-21 .json + verify round-trip
+- [Phone NPC targetKnot limitation](phone-npc-targetknot-limitation.md) — targetKnot only works first-contact; use setGlobal+sendTimedMessage otherwise

.claude/projects/-home-cliffe-Files-Projects-Code-BreakEscape-BreakEscape/memory/ink-decompiler-tooling.md

@@ -0,0 +1,13 @@
+---
+name: ink-decompiler-tooling
+description: Scripts to recover .ink source from compiled inkVersion-21 .json
+metadata:
+  type: reference
+---
+
+When a scenario's `.ink` source is missing but the compiled `.json` exists (e.g. only compiled ink was committed), recover editable source with:
+
+- `scripts/decompile_ink.py <compiled.json>` — emits readable inkVersion-21 ink (knots, choices, conditionals, var ops, tags, external calls, diverts) to stdout.
+- `scripts/verify_ink_roundtrip.py <original.json> <recompiled.json>` — recompile the decompiled `.ink` with `bin/inklecate` and confirm a normalized semantic trace (text, tags, VAR= targets, x() calls, knot names) matches the original. **Always verify before trusting** — the game runs from `.json`, so a divergent decompile could change behaviour on recompile.
+
+Used to recover all of m03_ghost_in_the_machine's ink (8 files, all trace-matched). Recompile in-sync with `./scripts/compile-ink.sh <scenario>`. Gotcha found: inklecate rejects `not (x)` for a parenthesised bare identifier — emit `not x`.

.claude/projects/-home-cliffe-Files-Projects-Code-BreakEscape-BreakEscape/memory/m02-event-pattern-objective-task-completed.md

@@ -0,0 +1,10 @@
+---
+name: m02-event-pattern-objective-task-completed
+description: NPC eventMappings must use objective_task_completed:<id>, not task_completed:<id>
+metadata:
+  type: project
+---
+
+To react to an objective task completing, NPC `eventMappings` must use eventPattern **`objective_task_completed:<taskId>`**. The engine emits `objective_task_completed:<id>` (objectives-manager.js) and `task_completed_by_npc`, but **never `task_completed:<id>`**. m02_ransomed_trust originally used `task_completed:<id>` in 8 mappings, which silently never fired (lost most of Agent 0x99/Ghost guidance).
+
+**How to apply:** When wiring NPC reactions to task completion, use `objective_task_completed:`. For reacting to globals set by minigames/terminals, use `global_variable_changed:<var>`. Related: [[terminals-are-minigames-not-ink]].

.claude/projects/-home-cliffe-Files-Projects-Code-BreakEscape-BreakEscape/memory/phone-npc-targetknot-limitation.md

@@ -0,0 +1,12 @@
+---
+name: phone-npc-targetknot-limitation
+description: Phone NPC eventMappings with targetKnot only work on first contact
+metadata:
+  type: project
+---
+
+For **phone** NPCs, an `eventMapping` with `targetKnot` only works the FIRST time that phone story is opened. Once a storyState is saved, `targetKnot` is ignored on reopen. The validator flags phone eventMappings that use `targetKnot` without `conversationMode`.
+
+**How to apply:**
+- First-contact phone cutscenes (e.g. a planted-device phone, a closing-debrief phone) may use `targetKnot` — add `"conversationMode": "phone-chat"` so it opens a fresh phone-chat to that knot (matches m02 ghost, m03 closing_debrief).
+- For a phone the player has already opened (e.g. the always-available handler 0x99), do NOT rely on `targetKnot` for later events. Use `setGlobal` a flag + `sendTimedMessage` to notify, and add a conditional hub option `+ {flag} [..] -> knot` in the Ink. This is the m01/m02 handler-guidance pattern. Related: [[m02-event-pattern-objective-task-completed]], [[terminals-are-minigames-not-ink]].

.claude/projects/-home-cliffe-Files-Projects-Code-BreakEscape-BreakEscape/memory/terminals-are-minigames-not-ink.md

@@ -0,0 +1,12 @@
+---
+name: terminals-are-minigames-not-ink
+description: In Break Escape, in-world terminals/consoles are minigames, not ink dialogues
+metadata:
+  type: project
+---
+
+In Break Escape scenarios, interactive **terminals/consoles are implemented as minigames, not ink**. Examples: `backup_recovery` (recovery console), `ransomware_display`, `password`/`pin` locks, vm-launcher/flag-station. The one exception is the phone "hacker mode" overlay that pops up when the player is on another device.
+
+**Why:** A terminal that has a `storyPath` to an ink file is almost always a mistake — the engine launches the minigame for its `type`/`lockType`, and the ink never runs. m02_ransomed_trust had an orphaned `m02_terminal_ransom_interface.ink` that was never referenced; it was deleted.
+
+**How to apply:** Minigames complete objective tasks by *writing globals* (e.g. backup-recovery writes `backup_recovery_source`, `backup_restore_initiated`). To finish a task off a terminal, add an NPC `eventMapping` watching `global_variable_changed:<var>` with `completeTask`/`setGlobal` (sis01's Helen Carver and m02's Agent 0x99 do this). Do NOT wire terminal task completion through ink. Related: [[m02-event-pattern-objective-task-completed]].

.claude/settings.json

@@ -0,0 +1,10 @@
+{
+    "permissions": {
+      "allow": [
+        "Bash(*)",
+        "Write(*)",
+        "Edit(*)",
+        "Read(*)"
+      ]
+    }
+  }

.claude/skills/break-escape-dungeon-graph/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: break-escape-dungeon-graph
+description: Runs the scenario validator and opens the generated dungeon graph for a Break Escape scenario file (.json or .json.erb). Use this skill whenever the user asks for a diagram, graph, map, dependency chart, or visual overview of a scenario's lock/key structure. Also trigger when the user asks to "visualise the mission", "show the lock and key structure", "draw the dungeon graph", "update the diagram", or "confirm the graph is up to date" after editing a scenario.
+---
+
+# Break Escape dungeon graph skill
+
+The dungeon graph is generated automatically by the scenario validator. This skill runs the validator, reports its output, and reads the resulting HTML file.
+
+## Step 1 — resolve the scenario path
+
+The user will provide a scenario file path (e.g. `scenarios/sis01_healthcare/scenario.json.erb`). Work from the repository root (`/home/cliffe/Files/Projects/Code/BreakEscape/BreakEscape`).
+
+## Step 2 — run the validator
+
+```bash
+ruby scripts/validate_scenario.rb <scenario_path>
+```
+
+The validator:
+- Validates JSON structure, schema, and ink files
+- Generates `dungeon_graph.html` (interactive visual) and `dungeon_graph.md` (AI-readable reference with all five Mermaid diagrams and prose descriptions) in the same directory as the scenario file
+- Prints a summary: node/edge counts and the critical path
+
+Report any validation **errors** (❌) and **warnings** (⚠️) to the user. Suppress the ✅/💡 informational lines unless the user asks for them.
+
+## Step 3 — read the generated graph
+
+After the validator succeeds, read the generated `dungeon_graph.html` file (same directory as the scenario, e.g. `scenarios/sis01_healthcare/dungeon_graph.html`) and display it directly using the `show_widget` visualiser tool:
+
+- `title`: `[scenario_id]_dungeon_graph`
+- `widget_code`: the full contents of the generated HTML file
+- `loading_messages`: `["Running validator…", "Reading generated graph…", "Rendering…"]`
+
+## Step 4 — summarise
+
+After rendering, report to the user:
+- Node and edge counts (puzzle / story / integrated)
+- The critical path printed by the validator
+- Any errors or warnings that need attention

.claude/skills/bump-version/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: bump-version
+description: Bumps the BreakEscape gem version and keeps Gemfile.lock in sync. Trigger when the user asks to "bump the version", "release a new version", "increment the version", or "update the version number".
+---
+
+# Break Escape bump-version skill
+
+Update the version in the one canonical place and regenerate the lockfile so CI doesn't fail.
+
+## Step 1 — determine the new version
+
+If the user specified a version, use it. Otherwise read the current version and increment the patch number (third digit), e.g. `1.0.4` → `1.0.5`:
+
+```bash
+cat lib/break_escape/version.rb
+```
+
+## Step 2 — update the version file
+
+Edit `lib/break_escape/version.rb` — change only the `VERSION` constant string. Do not touch `ASSETS_VERSION`.
+
+## Step 3 — update Gemfile.lock manually
+
+The `PATH` section of `Gemfile.lock` embeds the gem version. After changing `VERSION`, it will be out of sync and CI will fail with *"The gemspecs for path gems changed"* in deployment mode.
+
+Update it directly — change only the version on the `break_escape (X.Y.Z)` line in the PATH block:
+
+```
+PATH
+  remote: .
+  specs:
+    break_escape (1.0.5)   ← update this line
+```
+
+Do not run `bundle install` — the global `~/.bundle/config` has a mirror pointing to a local Hacktivity cache path that doesn't exist, which causes bundle install to fail in this project.
+
+## Step 4 — confirm and report
+
+Tell the user:
+- The old version and the new version
+- That `Gemfile.lock` was updated (show the new PATH block)
+- That both files should be committed together
+
+Suggest a commit message like: `chore: bump version to X.Y.Z`