Menu System — Full Specification
Status: ACTIVE (design reference) Agent: opencode/ext-agent (sandshrew) Timestamp UTC: 2026-05-12T00:10:00Z Claim: synthesis | 2026-05-12T00:05:00Z Session: Comprehensive menu tree — every layer from hex grid to raw output, mapped to LangGraph configs
Prior Context
- [[nested-menu-protocol]] — Initial menu tree sketch
- [[langgraph-node-config-catalog]] — 12 configurable node dimensions
- [[output-summary-protocol]] — Summary rendering + zoom-in
- [[langgraph-context-curation-pattern]] — Cross-node context routing
- [[langgraph-live-prompt-injection]] — Player corrections at nodes
- [[example-slice-walkthrough]] — 5-turn gameplay example
LEVEL 0: Hex Grid
__ __ __ __ __ __
__/00\__/01\__/02\__/03\__/04\__/05\__
/06\__/07\__/08\__/09\__/10\__/11\__/12\
\__/13\__/14\__/15\__/16\__/17\__/18\__/ ◉ = unit sprite
/19\__/20\__/21\__/22\__/23\__/24\__/25\
\__/26\__/27\__/28\__/29\__/30\__/31\__/
/32\__/33\__/34\__/35\__/ \__/ \__/ \
\__/ \__/ \__/ \__/ \__/ \__/ \__/
──────────────────────────────────────────────────
UNITS: Rif(5) Echo(3) Sherpa(4) | [A] HEX [X] UNIT LIST [SELECT] PHASE MAP
──────────────────────────────────────────────────
Sidebar (top status line):
- Turn counters per unit: Rif(5) Echo(3) Sherpa(4)
- Active phase indicator: highlighted phase name
- Unit quick-select: X cycles through units, jumps cursor to their hex
Input: D-pad moves cursor across hexes. A selects current hex. X cycles unit focus. SELECT toggles phase color overlay.
State read: state["nodes"], state["units"], phase labels from state["nodes"][hex_id]["phase"]
LEVEL 1: Tile Menu
Opens when A is pressed on a hex. Shows what's on this tile.
┌──────────────────────────────────────────────────────────┐
│ HEX 14 — Design STATUS: ACTIVE │
│──────────────────────────────────────────────────────────│
│ ▶ Rif — Designer │
│ Model: deepseek-v4 / opencode Turn: 5 │
│ Trail: 3 items | Access: 5 sources | History: 4 hexes│
│ │
│ ▶ Node: Hex 14 │
│ Phase: Design | Status: in_progress │
│ Output: 4 sections | Edges: 6 reachable │
│──────────────────────────────────────────────────────────│
│ [X] Unit Menu [Y] Node Menu [A] Quick Move [B] Back│
└──────────────────────────────────────────────────────────┘
If NO unit on this hex: Unit section shows "No unit present." Quick Move greyed out. If NO node on this hex (empty terrain): Node section shows terrain type only. Node Menu greyed out.
State read: state["nodes"]["14"], state["units"]["rif"] (if rif.position == "14")
LEVEL 2a: Unit Menu
Opened with X from Tile Menu. Shows everything about the unit.
┌──────────────────────────────────────────────────────────┐
│ UNIT: Rif — Designer TURN: 5 │
│──────────────────────────────────────────────────────────│
│ ▶ Status → Active at Hex 14, in_progress │
│ ▶ Config → deepseek-v4 / opencode / [read,write]│
│ ▶ Trail → 3 items from prior hexes │
│ ▶ Access → 5 sources available, 1 blocked │
│ ▶ History → 4 hexes visited, 3 outputs produced │
│ ▶ Move → Select destination, configure │
│ ▶ Interact → Live terminal (if unit is active) │
│──────────────────────────────────────────────────────────│
│ [A] Select [B] Back │
└──────────────────────────────────────────────────────────┘
Configs in play: Unit identity, agent config (#4), access lists (#5)
LEVEL 3a: Unit Status
┌──────────────────────────────────────────────────────────┐
│ STATUS: Rif — Hex 14 (Design) in_progress │
│──────────────────────────────────────────────────────────│
│ Current task: "Design sprite sheet layout" │
│ Last action: Agent responded. 180 tokens. 1.4s. │
│ Chain of thought: │
│ "RG40XXV runs pygame 2.5.2. Hex tiles should be..." │
│ Corrections pending: 1 ("128px too heavy — reconsider") │
│ Node output: 4 sections (draft) │
│──────────────────────────────────────────────────────────│
│ [Y] View Output [B] Back │
└──────────────────────────────────────────────────────────┘
State read: state["units"]["rif"], state["node_player_prompts"]["14"], state["nodes"]["14"]["output_summary"]
LEVEL 3b: Unit Config
┌──────────────────────────────────────────────────────────┐
│ CONFIG: Rif │
│──────────────────────────────────────────────────────────│
│ Model: deepseek-v4 [Change] │
│ Harness: opencode [Change] │
│ Tools: [read] [write] [bash] [Edit] │
│ Temperature: 0.7 [Adjust] │
│──────────────────────────────────────────────────────────│
│ [A] Select [B] Back │
└──────────────────────────────────────────────────────────┘
Edits write to state["units"]["rif"]["config"] via Command(update=...).
Config in play: Agent config (#4)
LEVEL 3c: Trail Context
┌──────────────────────────────────────────────────────────┐
│ TRAIL: Rif — Accumulated Context │
│──────────────────────────────────────────────────────────│
│ ☑ Hex 01 (Planning) — Scope definition │
│ ☑ Hex 06 (Research) — Sprite format research (curated) │
│ ☑ Hex 08 (Research) — Tile dimension analysis │
│ ☐ Hex 12 (Define) — Requirements spec │
│──────────────────────────────────────────────────────────│
│ [A] Toggle [X] Select All [Y] Clear All [B] Back │
└──────────────────────────────────────────────────────────┘
Toggle which trail items travel with the unit to the next hex. Unchecked items are left behind (explicit block at destination).
State read/write: state["units"]["rif"]["trail_context"]
LEVEL 3d: Access Lists
┌──────────────────────────────────────────────────────────┐
│ ACCESS: Rif — Allowed Context │
│──────────────────────────────────────────────────────────│
│ ALLOWED: │
│ ▶ node_01/output (Planning — scope) │
│ ▶ node_06/output (Research — sprite formats) │
│ ▶ wiki/langgraph-docs.md (LangGraph documentation) │
│ ▶ routed/14/from_06 (Curated for Hex 14) │
│ │
│ BLOCKED: │
│ ▶ node_12/output (Define — conflicting spec) │
│──────────────────────────────────────────────────────────│
│ [A] Add [X] Remove [B] Back │
└──────────────────────────────────────────────────────────┘
Config in play: Access lists (#5)
LEVEL 3e: Traversal History
┌──────────────────────────────────────────────────────────┐
│ HISTORY: Rif — Traversal │
│──────────────────────────────────────────────────────────│
│ T1: Hex 01 (Planning) → Scope definition │
│ Output: wiki/planning/scope.md │
│ T2: Hex 08 (Research) → Tile dimensions │
│ Output: wiki/research/tile-dims.md │
│ T3: Hex 06 (Research) → Sprite formats │
│ Output: wiki/research/sprite-formats.md │
│ T4: Hex 14 (Design) → Sprite layout (ACTIVE) │
│ Output: (in progress) │
│──────────────────────────────────────────────────────────│
│ [A] Jump to hex [Y] View output [B] Back │
└──────────────────────────────────────────────────────────┘
"A" jumps the cursor to that hex on the grid. "Y" opens that hex's output.
State read: state["units"]["rif"]["history"]
LEVEL 3f: Move Unit → LEVEL 4: Move Config
┌──────────────────────────────────────────────────────────┐
│ MOVE: Rif → Hex 15 (Design) │
│──────────────────────────────────────────────────────────│
│ ▶ Config for this move: │
│ Model: deepseek-v4 [Change] │
│ Harness: opencode [Change] │
│ │
│ ▶ Context to bring: │
│ ☑ Hex 01 output (scope) │
│ ☑ Hex 06 output (sprite formats) │
│ ☑ Hex 08 output (tile dimensions) │
│ │
│ ▶ Context to block at destination: │
│ (none selected) [Add block] │
│──────────────────────────────────────────────────────────│
│ [A] Confirm Move [B] Cancel │
└──────────────────────────────────────────────────────────┘
Confirm → RG sends invoke({action: "move", unit: "rif", target: "15", move_config: {...}}). LangGraph activates hex 15's node function with the unit's config, trail, and blocks.
Configs in play: Agent config (#4), access lists (#5), node function (#2), edges (#8)
LEVEL 3g: Interactive Terminal
Available when unit is active (agent running or at interrupt). This is the "watch and talk" interface.
┌──────────────────────────────────────────────────────────┐
│ TERMINAL: Rif @ Hex 14 (Design) │
│──────────────────────────────────────────────────────────│
│ [Agent] Researching sprite sheet layout... │
│ [Agent] Comparing pygame 2.5.2 capabilities... │
│ [Agent] Recommendation: 128×128 px sprites. │
│ │
│ ⚠ interrupt: "Review output." [Accept] [Correct] │
│ │
│ > █ │
│ (type to send correction, redirect, or ask question) │
│──────────────────────────────────────────────────────────│
│ [A] Send [B] Close terminal │
└──────────────────────────────────────────────────────────┘
The terminal shows:
- Live runtime.stream_writer output as the agent works
- The chain of thought as it develops
- The interrupt prompt when the agent pauses
- A text input for the player to type corrections, questions, or redirects
What the player types is sent via Command(resume={"action": "correct", "prompt": "..."}) or added to node_player_prompts if the unit is between turns.
Configs in play: Interrupt (#9), streaming (#11), live prompt injection, node function (#2)
LEVEL 2b: Node Menu
Opened with Y from Tile Menu. Shows everything about the hex's node.
┌──────────────────────────────────────────────────────────┐
│ NODE: Hex 14 — Design in_progress │
│──────────────────────────────────────────────────────────│
│ ▶ Properties → Phase, status, output locale │
│ ▶ Output → 4 sections (draft) │
│ ▶ Edges → 6 reachable hexes │
│ ▶ Config → Prompt template, model defaults │
│ ▶ History → 3 units visited, 2 outputs produced │
│──────────────────────────────────────────────────────────│
│ [A] Select [B] Back │
└──────────────────────────────────────────────────────────┘
Configs in play: Phase label (#3), status (#7), output locale (#6)
LEVEL 3h: Node Properties
┌──────────────────────────────────────────────────────────┐
│ PROPERTIES: Hex 14 — Design │
│──────────────────────────────────────────────────────────│
│ Phase: Design │
│ Status: in_progress │
│ Output at: wiki/design/sprite-layout.md │
│ Created: 2026-05-11 │
│ Last active: Turn 4 (Rif) │
│──────────────────────────────────────────────────────────│
│ [B] Back │
└──────────────────────────────────────────────────────────┘
State read: state["nodes"]["14"]["phase"], state["nodes"]["14"]["status"], state["nodes"]["14"]["output_locale"]
LEVEL 3i: Output Summary → LEVEL 4a/4b
Shown when node is completed (has output to review).
┌──────────────────────────────────────────────────────────┐
│ OUTPUT — Hex 06 (Sherpa) STATUS: DONE │
│──────────────────────────────────────────────────────────│
│ Sprite Asset Research │
│ │
│ ▶ Recommendation [FINAL] │
│ Use PNG 32×32 px, sprite sheets. │
│ │
│ ▶ Tile Dimensions [FINAL] │
│ Flat-top hex, 100×87 px for 6×6 grid. │
│ │
│ ▶ Color Depth [FINAL] │
│ RGBA for transparency. │
│ │
│ ▶ Performance [OPEN] │
│ Sprite sheets vs individual files? │
│──────────────────────────────────────────────────────────│
│ [A] Zoom in [X] Route to... [Y] Full page [B] Back│
└──────────────────────────────────────────────────────────┘
A on section → LEVEL 4a (Expanded):
┌──────────────────────────────────────────────────────────┐
│ ▶ Recommendation [FINAL] │
│──────────────────────────────────────────────────────────│
│ PNG format at 32×32 pixels is optimal for RG40XXV. │
│ Pygame 2.5.2 supports RGBA PNGs with alpha channel. │
│ Sprite sheets reduce file I/O vs individual files. │
│ 7 terrain tiles + 3 unit icons fit in one 256×256 sheet.│
│ │
│ Source: wiki/research/sprite-formats.md#recommendation │
│──────────────────────────────────────────────────────────│
│ [Y] Full page [B] Back to summary │
└──────────────────────────────────────────────────────────┘
Y → LEVEL 4b (Full Output — cross-device):
┌──────────────────────────────────────────────────────────┐
│ FULL OUTPUT │
│──────────────────────────────────────────────────────────│
│ wiki/research/sprite-formats.md │
│ │
│ This page is too dense for the RG screen. │
│ │
│ Open on Mac? [A] Yes │
│ Force render on RG? [X] Yes (will scroll) │
│ Copy link to clipboard? [Y] Yes │
│ │
│ [B] Back │
└──────────────────────────────────────────────────────────┘
State read: state["nodes"]["06"]["output_summary"]. Config in play: Output locale (#6)
LEVEL 3j: Edges → LEVEL 4c: Routing Action
┌──────────────────────────────────────────────────────────┐
│ EDGES: Hex 14 → Reachable Hexes │
│──────────────────────────────────────────────────────────│
│ ▶ Hex 07 (Research) [Route] │
│ ▶ Hex 08 (Research) [Route] ← completed │
│ ▶ Hex 13 (Define) [Route] │
│ ▶ Hex 15 (Design) [Route] │
│ ▶ Hex 21 (Design) [Route] │
│ ▶ Hex 22 (Develop) [Route] │
│──────────────────────────────────────────────────────────│
│ [A] Select target [B] Back │
└──────────────────────────────────────────────────────────┘
A on target → LEVEL 4c (Routing Action):
┌──────────────────────────────────────────────────────────┐
│ ROUTE: Hex 14 (Design) → Hex 22 (Develop) │
│──────────────────────────────────────────────────────────│
│ Source output: 4 sections, status: in_progress │
│ Target prompt: "Develop implementation for: {task}" │
│──────────────────────────────────────────────────────────│
│ [A] Curate Context │
│ Agent reads Hex 14 output, filters for Hex 22's │
│ prompt thrust. Produces targeted subset. │
│ │
│ [X] Point Wholesale │
│ Hex 22 gets full pointer to Hex 14 output. │
│ No curation — target can pull anything. │
│──────────────────────────────────────────────────────────│
│ [A] Curate [X] Point [B] Cancel │
└──────────────────────────────────────────────────────────┘
Curate → agent runs → writes to state["routed_context"]["22"]["from_14"] → adds to target's access list.
Configs in play: Edges (#8), output locale (#6), access lists (#5), curation node function
LEVEL 3k: Node Config
┌──────────────────────────────────────────────────────────┐
│ CONFIG: Hex 14 — Design │
│──────────────────────────────────────────────────────────│
│ Prompt template: │
│ "Design a solution for: {task}. Consider: {context}." │
│ [Edit] │
│ │
│ Default model: deepseek-v4 [Change] │
│ Default harness: opencode [Change] │
│ │
│ Player corrections (1): │
│ ⚠ "128px too heavy — consult Sherpa's research" │
│ [View] [Clear] │
│──────────────────────────────────────────────────────────│
│ [A] Select [B] Back │
└──────────────────────────────────────────────────────────┘
State read/write: state["nodes"]["14"]["config"], state["node_player_prompts"]["14"]
LEVEL 3l: Node History
┌──────────────────────────────────────────────────────────┐
│ HISTORY: Hex 14 — Past Activity │
│──────────────────────────────────────────────────────────│
│ T3: Rif (Designer) — "Design sprite layout" │
│ Status: in_progress (correction pending) │
│ │
│ Prior: │
│ (no previous units visited this hex) │
│──────────────────────────────────────────────────────────│
│ [A] View unit [B] Back │
└──────────────────────────────────────────────────────────┘
State read: state["nodes"]["14"]["history"]
Full Menu Tree (Collapsed View)
HEX GRID [L0]
│
└── A on hex → TILE MENU [L1]
│
├── X → UNIT MENU [L2a]
│ ├── Status [L3a] → View Output
│ ├── Config [L3b] → Edit model/harness/tools
│ ├── Trail [L3c] → Toggle items
│ ├── Access [L3d] → Add/remove allowed/blocked
│ ├── History [L3e] → Jump to hex / View output
│ ├── Move [L3f] → select hex → MOVE CONFIG [L4] → Confirm → invoke()
│ └── Interact [L3g] → LIVE TERMINAL
│ ├── Watch stream_writer output
│ ├── See chain of thought
│ ├── Type corrections → Command(resume)
│ └── Type redirects → node_player_prompts
│
├── Y → NODE MENU [L2b]
│ ├── Properties [L3h]
│ ├── Output [L3i] (if completed)
│ │ ├── A on section → EXPANDED [L4a]
│ │ │ └── Y → FULL OUTPUT [L4b] (cross-device)
│ │ └── X → Route to other node
│ ├── Edges [L3j] → select target → ROUTING ACTION [L4c]
│ │ ├── Curate Context → agent runs → adds to access
│ │ └── Point Wholesale → adds pointer
│ ├── Config [L3k] → Edit prompt template, view corrections
│ └── History [L3l] → View past activity at this node
│
└── A (Quick Move) → select hex → confirm move (no config)
LangGraph Config → Menu Level Mapping
| Config (#) | Config Name | Menu Levels |
|---|---|---|
| 1 | Node identity | L0 (hex labels), L1 (hex ID) |
| 2 | Node function | L3g (terminal — agent execution) |
| 3 | Phase label | L0 (color border), L1 (phase display) |
| 4 | Agent config | L3b (view/edit), L3f (move override) |
| 5 | Access lists | L3c (trail), L3d (allow/block), L4c (routing) |
| 6 | Output locale | L3i (output summary), L4a (expanded), L4b (full) |
| 7 | Node status | L1 (status badge), L3h (properties) |
| 8 | Edges | L3j (edge list), L4c (routing target) |
| 9 | Interrupt | L3g (terminal — interrupt prompt) |
| 10 | Recursion limit | (not surfaced in menus) |
| 11 | Streaming | L3g (terminal — live output) |
| 12 | Cache policy | (not surfaced in menus) |
Input Mapping
| Button | Context | Action |
|---|---|---|
| D-pad | Grid | Move cursor between hexes |
| D-pad | Menu | Navigate menu items |
| A | Grid | Open Tile Menu |
| A | Menu | Select / Confirm / Drill down |
| B | Any | Back one level |
| X | Grid | Cycle unit focus |
| X | Tile Menu | Open Unit Menu |
| Y | Tile Menu | Open Node Menu |
| Y | Output | Full page (cross-device) |
| SELECT | Grid | Toggle phase color overlay |
| START | Any | Pause menu (save, quit, settings) |
| L1/R1 | Grid | Previous/next unit |
| L2/R2 | Terminal | Page up/down through output |