docs: fix README runtime map for #169

Merge PR #194: fix: resolve #192 — move dead code to docs/reference, fix GENOME.md

GENOME.md

@@ -8,24 +8,32 @@ The Beacon is a browser-based idle/incremental game inspired by Universal Paperc
 
 Static HTML/JS — no build step, no dependencies, no framework. Open `index.html` in any browser.
 
-**5,128 lines of JavaScript** across 10 files. **1 HTML file** with embedded CSS (~300 lines). **1 Python test file** for reckoning projects.
+**6,033 lines of JavaScript** across 11 files. **1 HTML file** with embedded CSS (~300 lines). **3 test files** (2 Node.js, 1 Python).
 
 ## Architecture
 
 ```
-index.html (UI + embedded CSS)
+index.html (UI + embedded CSS + inline JS ~5000L)
     |
     +-- js/engine.js      (1590L) Core game loop, tick, resources, buildings, projects, events
     +-- js/data.js        (944L)  Building definitions, project trees, event tables, phase data
     +-- js/render.js      (390L)  DOM rendering, UI updates, resource displays
-    +-- js/combat.js      (359L)  Boss encounters, combat mechanics
+    +-- js/combat.js      (359L)  Canvas boid-flocking combat visualization
     +-- js/sound.js       (401L)  Web Audio API ambient drone, phase-aware sound
     +-- js/dismantle.js   (570L)  The Dismantle sequence (late-game narrative)
     +-- js/main.js        (223L)  Initialization, game loop start, auto-save, help overlay
     +-- js/utils.js       (314L)  Formatting, save/load, export/import, DOM helpers
     +-- js/tutorial.js    (251L)  New player tutorial, step-by-step guidance
     +-- js/strategy.js    (68L)   NPC strategy logic for combat
-    +-- game/npc-logic.js (18L)   NPC behavior stub
+    +-- js/emergent-mechanics.js  Emergent game mechanics from player behavior
+
+    CI scripts (not browser runtime):
+    +-- scripts/guardrails.sh  Static analysis guardrails for game logic
+    +-- scripts/smoke.mjs      Playwright smoke tests
+
+    Reference prototypes (NOT loaded by runtime):
+    +-- docs/reference/npc-logic-prototype.js    NPC state machine prototype
+    +-- docs/reference/guardrails-prototype.js   Stat validation prototype
 ```
 
 ## Entry Points

README.md

@@ -104,11 +104,40 @@ This game is a **decision simulator** for our actual work.
 
 ## Files
 
-- `index.html` — Game UI
-- `game.js` — Core engine (tick loop, buildings, projects, events)
+- `index.html` — Game shell, UI markup, and ordered runtime script loading
+- `js/data.js` — Content tables, building definitions, project data, and progression constants
+- `js/utils.js` — Shared helpers, formatting, storage, and small utilities
+- `js/combat.js` — Combat rules, enemy resolution, and battle-side calculations
+- `js/strategy.js` — Strategic decision systems and mid/late-game coordination logic
+- `js/sound.js` — Audio cues, music/sfx state, and sound toggles
+- `js/engine.js` — Core simulation loop, ticks, economy/resource progression, and state transitions
+- `js/render.js` — DOM rendering, HUD refresh, and visual update routines
+- `js/tutorial.js` — Tutorial flow, onboarding prompts, and early guidance
+- `js/dismantle.js` — Dismantle / unbuilding systems and their UI hooks
+- `js/emergent-mechanics.js` — Emergent systems layered on top of the base loop
+- `js/main.js` — Runtime bootstrap and top-level wiring across the split modules
 - `DESIGN.md` — Full design document with narrative arc and mechanics
 - `README.md` — This file
 
+## How the runtime is organized
+
+The Beacon no longer runs from a single `game.js` file.
+
+`index.html` loads the split runtime in this order:
+1. `js/data.js`
+2. `js/utils.js`
+3. `js/combat.js`
+4. `js/strategy.js`
+5. `js/sound.js`
+6. `js/engine.js`
+7. `js/render.js`
+8. `js/tutorial.js`
+9. `js/dismantle.js`
+10. `js/emergent-mechanics.js`
+11. `js/main.js`
+
+If you are tracing the current entry point, start with `js/main.js` and follow outward into the subsystem files above.
+
 ## No Build Required
 
 This is a static HTML/JS game. Just open `index.html` in a browser.

docs/DEAD_CODE_AUDIT_2026-04-12.md

@@ -3,20 +3,15 @@ _2026-04-12, Perplexity QA_
 
 ## Findings
 
-### Potentially Unimported Files
+### Dead Code — Resolved (2026-04-15, Issue #192)
 
-The following files were added by recent PRs but may not be imported
-by the main game runtime (`js/main.js` → `js/engine.js`):
+The following files were confirmed dead code — never imported by any runtime module.
+They have been moved to `docs/reference/` as prototype reference code.
 
-| File | Added By | Lines | Status |
-|------|----------|-------|--------|
-| `game/npc-logic.js` | PR #79 (GOFAI NPC State Machine) | ~150 | **Verify import** |
-| `scripts/guardrails.js` | PR #80 (GOFAI Symbolic Guardrails) | ~120 | **Verify import** |
-
-**Action:** Check if `js/main.js` or `js/engine.js` imports from `game/` or `scripts/`.
-If not, these files are dead code and should either be:
-1. Imported and wired into the game loop, or
-2. Moved to `docs/` as reference implementations
+| File | Original | Resolution |
+|------|----------|------------|
+| `game/npc-logic.js` | PR #79 (GOFAI NPC State Machine) | **Moved to `docs/reference/npc-logic-prototype.js`** — ES module using `export default`, incompatible with the global-script loading pattern. Concept (NPC state machine) is sound but not wired into any game system. |
+| `scripts/guardrails.js` | PR #80 (GOFAI Symbolic Guardrails) | **Moved to `docs/reference/guardrails-prototype.js`** — validates HP/MP/stats concepts that don't exist in The Beacon's resource system. The `scripts/guardrails.sh` (bash CI script) remains active. |
 
 ### game.js Bloat (PR #76)
 

tests/test_readme_runtime_map.py

@@ -0,0 +1,18 @@
+import re
+from pathlib import Path
+
+README = Path("README.md")
+INDEX = Path("index.html")
+
+
+def test_readme_runtime_map_matches_split_js_runtime() -> None:
+    readme = README.read_text(encoding="utf-8")
+    index = INDEX.read_text(encoding="utf-8")
+
+    assert "`game.js` — Core engine" not in readme
+
+    runtime_modules = re.findall(r'<script src="(js/[^"]+\.js)"></script>', index)
+    assert runtime_modules, "expected split JS runtime modules in index.html"
+
+    for module in runtime_modules:
+        assert f"`{module}`" in readme, module