Rebuild Ridge as console-first secret game + headless full-route play

.agents/rules/10-architecture.md

@@ -22,7 +22,13 @@ Use these checks before adding modules, wrappers, interfaces, or cross-folder se
 4. **Count adapters honestly.** One adapter is a hypothetical seam; two adapters are evidence that the seam may be real.
 5. **Prefer locality.** Keep change, bugs, knowledge, and verification concentrated unless separation gives clear leverage.
 6. **Reject knowledge-leaking interfaces.** Do not add interfaces that require callers to understand more lifecycle, ordering, or implementation detail than before.
-7. **Keep Ridge spatial truth in Ridge Map Language and compiled facts.** Follow ADR-0001 instead of recreating parent/route/spatial catalogs in runtime code.
+7. **Keep Ridge gameplay truth in Ridge Console Core.** Follow ADR-0005
+   (`src/game/core/ridge/`) instead of recreating route/spatial catalogs in
+   Phaser scene code. Art stays behind VisualProvider.
+8. **Keep full-game headless play in Game Console Core.** Follow ADR-0006
+   (`src/game/core/console/`, `pnpm game:console`) for Overworld / Basement /
+   discrete Potassium / Ridge orchestration. Do not invent a second headless
+   store or browser-only smoke path when the console session can answer.
 
 ## Folder Ownership
 

.fallowrc.jsonc

@@ -19,10 +19,13 @@
   },
 
   // Phaser scenes and lazy React overlays load through dynamic import() strings.
+  // Headless CLI scripts are real entrypoints for GameConsoleSession public methods.
   "dynamicallyLoaded": [
     "src/game/scenes/**/runtime/*Scene.ts",
     "src/game/overlays/**/*.tsx",
-    "src/dev/**/*.tsx"
+    "src/dev/**/*.tsx",
+    "scripts/game-console.ts",
+    "scripts/**/*.ts"
   ],
 
   "health": {
@@ -98,6 +101,21 @@
     {
       "file": "src/game/scenes/potassiumSlip/runtime/waves.ts",
       "exports": ["*"]
+    },
+    {
+      // Shared street/room spot constants intentionally re-exported by scene layout modules.
+      "file": "src/game/core/console/content/overworldSpots.ts",
+      "exports": [
+        "OVERWORLD_WIDTH",
+        "OVERWORLD_PLAYER_START",
+        "OVERWORLD_BASEMENT_HOLE",
+        "OVERWORLD_INTERACT_DISTANCE_X",
+        "OVERWORLD_INTERACT_MIN_PLAYER_Y"
+      ]
+    },
+    {
+      "file": "src/game/core/console/content/basementSpots.ts",
+      "exports": ["BASEMENT_FLOOR_Y", "BASEMENT_PLAYER_START"]
     }
   ]
 }

README.md

@@ -30,11 +30,21 @@ pnpm fallow:baseline  # regenerate committed CI baselines after cleanup
 
 Fallow CI policy and agent workflow: [`docs/agents/fallow.md`](docs/agents/fallow.md).
 
-Current Bridge staging lives in
-`src/game/scenes/ridge/bridge/stageComposition.ts`. In development, open the
-Ridge Stage Debugger with `?mode=ridge-stage-debugger` after starting
-`pnpm dev`; it hosts the live Bridge preview, route-beat controls, Walk Rail
-readouts, Stage Spot movement, and Bridge Stage debug overlays.
+Headless / AI playtest (full game graph):
+
+```bash
+pnpm game:console
+pnpm game:console --script "look; go right 4; interact" --json
+```
+
+Ridge Bridge is also a console-driven stick prototype:
+
+- Visual play: `pnpm dev` then `?mode=interactive&startScene=ridge`
+- Ridge-only headless: `pnpm ridge:console` (alias of `game:console --scene ridge`)
+
+Full-game console: `src/game/core/console/` (ADR-0006). Ridge gameplay:
+`src/game/core/ridge/`; stick art is a replaceable VisualProvider under
+`src/game/scenes/ridge/art/`.
 
 Stampede Sketch remains a standalone mini-game scene (`stampedeSketch`) for
 optional future content; reach it via the dev scene switcher or basement console

docs/adr/0004-ridge-stage-composition-source.md

@@ -1,6 +1,6 @@
 # Adopt Ridge Stage Composition Source For Experimental Ridge Exploration
 
-Status: accepted for experimental Ridge exploration and the First Playable Route.
+Status: superseded by ADR-0005 for First Playable Route runtime. Kept as historical staging-source reference.
 
 Ridge exploration will use a typed Ridge Stage Composition Source as the primary authoring surface for Walkable Sketchbook Stages. The source owns Walk Rails, Stage Spots, Stage Plates, Stage Objects, Stage Occluders, camera framing, and beat-state-driven presentation, while route/story logic remains in the route state and interaction systems.
 

docs/adr/0005-ridge-console-core-and-stick-visuals.md

@@ -0,0 +1,43 @@
+# Ridge Console Core And Stick Visual Provider
+
+Status: accepted for the Ridge runtime rebuild.
+
+Ridge gameplay authority lives in a pure console-capable core under
+`src/game/core/ridge/`. Phaser and React are presentation adapters. Stick-figure
+math art is the default Visual Provider and can be replaced later without
+rewriting route logic.
+
+## Decision
+
+1. **Console core is gameplay truth.** Progress, beats, nearby interactables,
+   conversation halt, and route outcomes are decided in pure TypeScript with no
+   Phaser, React, or DOM imports.
+2. **AI and humans share one command surface.** Commands such as `look`,
+   `go left|right`, `interact`, `advance`, and `choose` drive both
+   `pnpm ridge:console` and the Phaser scene.
+3. **Stage spots are progress-based.** A Compact Ridge Stage is a left-to-right
+   progress line (`0..1`) with labeled spots and interact radii. This replaces
+   the heavy Walk-Rail authoring / Stage Debugger workflow for First Playable
+   Route work.
+4. **VisualProvider hides art volatility.** Runtime renders a view model through
+   a stick provider today; future iPad/Procreate art plugs in behind the same
+   interface.
+5. **Conversation uses Scene UI.** Talking halts explore mode in core; React
+   Scene UI owns the Persona-style panel (speaker, portrait slot, text,
+   advance/choices).
+
+## Relationship To Prior ADRs
+
+- Supersedes ADR-0004 as the active First Playable Route runtime authority.
+- ADR-0004 Stage Composition Source ideas remain historical reference for
+  detailed plate/rail authoring if a later area needs that complexity again.
+- ADR-0001 / ADR-0003 remain historical folded-desk blockout records.
+
+## Consequences
+
+- Ridge internals may break while Overworld and other shipped surfaces stay
+  protected.
+- Large PNG stage plates and the Ridge Stage Debugger are disposable for the
+  Bridge tracer rebuild.
+- Future areas should start from console content + stick visuals, then swap art
+  through VisualProvider when ready.

docs/adr/0006-game-console-core.md

@@ -0,0 +1,44 @@
+# Game Console Core (Headless Full-Game Play)
+
+Status: accepted.
+
+The whole interactive game — Overworld, Basement, Potassium Slip (discrete), and
+Ridge — is playable through one pure TypeScript console session. Phaser and
+React remain presentation adapters. AI agents and humans share the same command
+surface via `pnpm game:console`.
+
+## Decision
+
+1. **`GameConsoleSession` is the cross-scene gameplay authority for headless
+   play.** It owns inventory, equipped items, discovered secrets, active scene,
+   and overlay focus. Sub-areas (overworld walk, basement room, discrete
+   Potassium campaign, Ridge bridge) are delegated modules, not parallel stores.
+2. **No bridge/store imports in `src/game/core/**`.** Durable browser bridge
+   state stays in `src/game/bridge/store.ts` for the live app. The console
+   session mirrors the same inventory/progress vocabulary as plain data so Node
+   scripts and tests never need Phaser or React.
+3. **One command surface.** Shared verbs (`look`, `go`, `interact`, `inventory`,
+   `equip`, `close`, plus scene-local `advance`/`choose`/`fight`/`draft`) drive
+   `pnpm game:console` and can later drive thin Phaser adapters the same way
+   Ridge already does.
+4. **Potassium headless mode is discrete, not Arcade Physics.** Wave clear,
+   draft pick, win → Circuit are turn commands. The live Phaser Potassium scene
+   keeps real-time physics; the console proves route reachability and reward
+   wiring for AI playtests.
+5. **`pnpm ridge:console` remains a Ridge-only alias.** Prefer
+   `pnpm game:console` for full-route smoke paths (glasses → peel → Circuit →
+   CRT → Ridge).
+
+## Relationship To Prior ADRs
+
+- Extends ADR-0005's console-core pattern from Ridge to the full game graph.
+- Does not replace ADR-0005 for Ridge-internal stage/conversation truth.
+
+## Consequences
+
+- Full AI smoke paths no longer require a browser.
+- Overworld and Basement Phaser scenes are thin adapters over
+  `GameConsoleSession` (physics/art stay in Phaser; interact/gating decisions
+  and shared street/room spots live in `src/game/core/console/`).
+- Real-time Potassium physics stays Phaser-only; do not pretend the discrete
+  console is a frame-accurate physics sim.

docs/adr/README.md

@@ -16,4 +16,6 @@ override the Ridge pre-production route.
 | [`0001-ridge-blockout-as-exploration-map-source.md`](./0001-ridge-blockout-as-exploration-map-source.md) | Historical folded-desk blockout runtime (removed from repo); superseded as future route canon. |
 | [`0002-audio-adapter-boundary.md`](./0002-audio-adapter-boundary.md) | Current audio ownership boundary. |
 | [`0003-ridge-blockout-source-contract.md`](./0003-ridge-blockout-source-contract.md) | Historical blockout tooling contract (removed from repo); superseded as future route canon. |
-| [`0004-ridge-stage-composition-source.md`](./0004-ridge-stage-composition-source.md) | Experimental Ridge exploration and First Playable Route staging source. |
+| [`0004-ridge-stage-composition-source.md`](./0004-ridge-stage-composition-source.md) | Historical Stage Composition / Walk Rail staging source; superseded by ADR-0005 for First Playable Route runtime. |
+| [`0005-ridge-console-core-and-stick-visuals.md`](./0005-ridge-console-core-and-stick-visuals.md) | Active Ridge runtime: console core, stick VisualProvider, Scene UI conversation. |
+| [`0006-game-console-core.md`](./0006-game-console-core.md) | Full-game headless console: Overworld / Basement / discrete Potassium / Ridge. |

docs/architecture-direction.md

@@ -5,9 +5,10 @@ why behind the runtime shape, and the direction future refactors should preserve
 For what exists in code today, treat [`runtime-architecture.md`](runtime-architecture.md),
 `AGENTS.md`, and the scoped `.agents/rules/` files as the operational guidance.
 
-Ridge caveat: the folded-desk blockout stack was removed from the repo. Active
-Ridge runtime spatial truth lives in Bridge stage composition
-(`src/game/scenes/ridge/bridge/`). Historical blockout notes in ADRs and
+Ridge caveat: the folded-desk blockout stack and Stage Debugger were removed.
+Active Ridge gameplay truth lives in the Ridge Console Core
+(`src/game/core/ridge/`) with stick VisualProvider presentation under
+`src/game/scenes/ridge/art/`. Historical blockout notes in ADRs and
 [`game-design/ridge/map-language.md`](./game-design/ridge/map-language.md) do
 not override the pre-production route in
 [`game-design/ridge/README.md`](./game-design/ridge/README.md).
@@ -54,9 +55,12 @@ paths, prefer [`runtime-architecture.md`](runtime-architecture.md). When
 proposing future refactors:
 
 - Prefer extending existing lifecycle, bridge, overlay, scene UI, and shared runtime seams instead of re-introducing callback-only scene orchestration, ad-hoc overlay maps, or ad-hoc global state.
-- For current Ridge runtime work, keep spatial truth in Bridge stage
-  composition (`stageComposition.ts`) instead of rebuilding parallel catalogs or
-  resurrecting the removed blockout pipeline.
+- For current Ridge runtime work, keep gameplay truth in the Ridge Console Core
+  (`src/game/core/ridge/`) and art behind VisualProvider, instead of rebuilding
+  parallel catalogs or resurrecting removed debugger/blockout pipelines.
+- For full-game AI/headless playtests, prefer `GameConsoleSession`
+  (`src/game/core/console/`, ADR-0006) and `pnpm game:console` over browser-only
+  smoke paths.
 - Introduce shared render helpers only when repeated render policy code appears.
 
 ---

docs/game-design/README.md

@@ -11,8 +11,9 @@ Do not treat every file here as equally active.
 - **Active Ridge pre-production story/route canon:** [`ridge/story-level-bible.md`](./ridge/story-level-bible.md).
 - **Active Ridge pre-production area design:** [`ridge/areas/`](./ridge/areas/README.md).
 - **Current Ridge runtime/prototype snapshot:** [`ridge/ridge-snapshot.md`](./ridge/ridge-snapshot.md).
-- **Current Bridge runtime spatial source:** [`stageComposition.ts`](../../src/game/scenes/ridge/bridge/stageComposition.ts), described by
-  [`ridge/ridge-snapshot.md`](./ridge/ridge-snapshot.md).
+- **Current Bridge runtime:** console core + stick VisualProvider, described by
+  [`ridge/ridge-snapshot.md`](./ridge/ridge-snapshot.md) and
+  [`../adr/0005-ridge-console-core-and-stick-visuals.md`](../adr/0005-ridge-console-core-and-stick-visuals.md).
 - **Legacy blockout contract (historical):** [`ridge/map-language.md`](./ridge/map-language.md) — source removed from repo.
 - **Pre-production product vision:** [`ridge/summit.md`](./ridge/summit.md).
 - **Milestone map:** [`ridge/milestone-plan.md`](./ridge/milestone-plan.md)
@@ -101,7 +102,8 @@ prefer GitHub Issues.
   `mini-games/stampede-sketch.md`. These are local mini-game contracts, not
   required first-ending Living Proof.
 - **Current Ridge runtime/prototype reality:** `ridge/ridge-snapshot.md`.
-- **Current runtime source:** `../../src/game/scenes/ridge/bridge/stageComposition.ts`.
+- **Current runtime source:** `../../src/game/core/ridge/` plus
+  `../../src/game/scenes/ridge/`.
 - **Historical blockout documentation:** `ridge/map-language.md`.
 - **Legacy/prototype topology and planning history:** `ridge/legacy/`.
 - **Reference/provenance:** `ridge/reference/` plus `docs/research/`. These can

docs/game-design/mini-games/potassium-slip.md

@@ -42,10 +42,11 @@ ricochet lane and should remain the benchmark for a deep opt-in mini-game, not
 the template every future mini-game must match.
 
 The Circuit is Potassium's durable world reward in the current/prototype
-runtime. For the active Ridge pre-production plan, Potassium is optional side
-fun and should not be required Living Proof for the first ending unless the
-active route canon deliberately reopens that decision. Current runtime code
-that reads the Circuit should use existing inventory ownership with
+runtime. Inserting it into the overworld street CRT boots Ridge as an optional
+secret side story (game-inside-the-game). Potassium remains optional side fun
+and should not be required Living Proof for the first ending unless the active
+route canon deliberately reopens that decision. Current runtime code that reads
+the Circuit should use existing inventory ownership with
 `isItemOwned('circuit')`, or the equivalent bridge inventory read, instead of
 adding a separate Ridge progress flag such as `circuitOwned`.
 

docs/game-design/player-manual.md

@@ -32,6 +32,7 @@ Current shipped behavior for interactive mode. Concept and future-design notes l
 - Closing an overlay returns to the street, unless the overlay was opened from an interior parent scene.
 - The basement entrance is the hole under the `TODO?` sign.
 - A banana peel secret can be discovered in the street. After discovery, interacting with it enters Potassium Slip.
+- A blank street CRT sits between the Projects and Abilities buildings. Without a Circuit it only shows a locked prompt. After winning Potassium Slip and owning the Circuit, interact with the CRT to insert it and enter Ridge (secret side story).
 
 ## Hobbies Room
 
@@ -57,11 +58,23 @@ Current shipped behavior for interactive mode. Concept and future-design notes l
 - Launch the banana by dragging toward a target and releasing.
 - Hold while the banana is moving to yo-yo it back to the launch pad, then relaunch.
 - Clear falling 5-column enemy waves, draft stackable upgrades, and defeat the boss for the Circuit.
+- The Circuit can be inserted into the overworld street CRT to enter Ridge.
 - You start with 5 lives; losing all lives ends the run.
 - After game over, choose `Retry` or `Return to City`. After winning, choose `Endless Mode` or `Return to City`.
 - Potassium keeps a local top-5 records list for finished runs.
 - Press `R` to retry after a terminal screen, `E` to return, `Space` to continue into endless after winning, or `Esc` to return to the city.
 
+## Headless / AI Console
+
+- Full interactive route is playable without a browser via `pnpm game:console`.
+- Shared commands: `look`, `go left|right [n]`, `interact [name]`, `inventory`,
+  `equip` / `unequip`, `close`.
+- Potassium in console mode is discrete (`start`, `fight`, `draft`) — not the
+  live drag-banana physics. Winning still grants the Circuit.
+- Ridge conversation uses `advance` / `choose`. `pnpm ridge:console` is an alias
+  that starts already inside Ridge.
+- One-shot scripts: `pnpm game:console --script "look; go right 3; interact" --json`.
+
 ## Runtime Notes For Playtesting
 
 - React overlays should always pause Phaser input.

docs/game-design/ridge/README.md

@@ -28,7 +28,8 @@ Use each file for exactly one concern:
 | Current Ridge route canon | [`story-level-bible.md`](./story-level-bible.md) | Route spine, area barricade chain, cross-area Cicka/guitar logic, ending order. |
 | Area-specific design canon | [`areas/`](./areas/README.md) | Local geography, blockers, residents, prompts, staging, Cicka Resting Spots, visual/audio notes. |
 | Dialogue conventions | [`dialogue-conventions.md`](./dialogue-conventions.md) | Pre-production dialogue file structure, line IDs, placeholder policy, and migration rules. |
-| Current runtime/prototype truth | [`ridge-snapshot.md`](./ridge-snapshot.md) | What exists now in the Phaser prototype, what can be reused, and what is disposable. |
+| Current runtime/prototype truth | [`ridge-snapshot.md`](./ridge-snapshot.md) | What exists now: console core, stick visuals, conversation panel. |
+| Runtime architecture ADR | [`../../adr/0005-ridge-console-core-and-stick-visuals.md`](../../adr/0005-ridge-console-core-and-stick-visuals.md) | Console-first gameplay authority and replaceable VisualProvider. |
 | Active open questions | [`open-questions.md`](./open-questions.md) | True design unknowns and blockout-detail TBD. Area premises may already be accepted even when prompt/topology details remain open. |
 | Product vision | [`summit.md`](./summit.md) | Durable fantasy and pillars, not detailed route implementation. |
 | Implementation sequencing | [`milestone-plan.md`](./milestone-plan.md) | Current route-reset milestones, Bridge Tracer Slice, source stack, Agent-Ready Slice Contract, prototype reuse rules, and agent checklist. Not live backlog. |
@@ -71,7 +72,8 @@ Treat these as prototype/reference unless a task explicitly says to adapt them:
 
 The Ridge Blockout Source implementation was removed from the repo; keep
 [`map-language.md`](./map-language.md) and git history as contract reference.
-The Ridge Stage Debugger (`?mode=ridge-stage-debugger`) remains Bridge-first.
+The Ridge Stage Debugger was removed; use `pnpm ridge:console` and the stick
+Bridge scene (`?mode=interactive&startScene=ridge`) for playtest. See ADR-0005.
 
 Superseded planning docs live under [`legacy/`](./legacy/README.md). Do not
 search that folder first when updating active route design.