Wiki Depot — Game Surface Integration Design
Status: PROPOSAL
Agent: PERISCOPE (design agent)
Date: 2026-05-12
Target: RG40XXV (640×480, D-pad + A/B/X/Y)
Backend: LangGraph state machine → file-based markdown wiki on Raspberry Pi
Scope: 5 views, button mapping, API contracts, ASCII mockups at 80×30 (8×16 font)
Architecture Overview
┌─────────────────────┐ HTTP GET ┌──────────────────────┐
│ RG40XXV Client │ ◄─────────────── │ Raspberry Pi │
│ │ │ │
│ Renders wiki views │ │ LangGraph state │
│ Reads state only │ │ machine │
│ No local storage │ │ │ │
│ Sends "open on Mac"│ │ ├─ writes .md files │
│ command to Mozart │ │ └─ serves JSON API │
│ Bridge :8318 │ │ │
└─────────────────────┘ └──────────────────────┘
Data Model (Wiki Index JSON)
Every wiki page carries this metadata (served by Pi API as wiki_index.json):
{
"pages": [
{
"id": "architecture-pod",
"title": "Architecture Pod",
"path": "concept/architecture-pod.md",
"category": "concept",
"status": "draft",
"producer_node": "arch-pod-design",
"producer_unit": "HERON",
"phase": "drafting",
"created": "2026-05-12T14:30:00Z",
"updated": "2026-05-12T16:45:00Z",
"tags": ["architecture", "level-design"],
"references": ["core-loop", "combat-loop", "level-design"],
"referenced_by": ["combat-system", "entity-map"],
"harvester_flags": [],
"trail_context_ids": ["ctx-042", "ctx-051"]
}
],
"graph": {
"nodes": [
{
"node_id": "arch-pod-design",
"unit": "HERON",
"phase": "drafting",
"status": "in_progress",
"produced_pages": ["architecture-pod"],
"referenced_pages": ["core-loop", "combat-loop", "level-design"],
"trail": ["ctx-042", "ctx-051", "ctx-067", "ctx-089"]
}
],
"trail_context": [
{
"id": "ctx-042",
"type": "wiki_ref",
"page_id": "core-loop",
"section": "phase-structure",
"summary": "Core loop defines three progression phases",
"timestamp": "2026-05-12T14:31:00Z"
}
]
},
"harvester": {
"flags": [
{
"id": "flag-12",
"text": "Combat flow rate suggests pod density max 5 active per zone",
"source_unit": "PROPHET",
"suggested_for_node": "arch-pod-design",
"topic_tag": "combat-balance",
"status": "pending",
"timestamp": "2026-05-12T15:22:00Z"
}
]
}
}
View 1: Graph-Correlated TOC
Purpose
Browse all wiki pages organized by their relationship to the game graph. Understand at a glance: which phase produced what, which unit wrote what, what's stale, what's disputed.
Layout Strategy
- Top bar: Title + live filter chips (Phase / Unit / Status / Sort)
- Scrollable list: Grouped by primary sort key (default: Phase)
- Per entry: Title (truncated to 45 chars) + unit tag + status badge + relative time
- Bottom bar: Counts + button hints
Interaction Flow
| Input | Action |
|---|---|
| D-pad ↑/↓ | Move cursor through list entries |
| D-pad ←/→ | Jump between filter chips in top bar |
| A | Open selected page detail (View 2) |
| B | Back to game |
| X | Cycle sort/filter mode: Phase → Unit → Status → Recency |
| Y | Send "open on Mac" command for selected page |
| L1/R1 | Jump between group headers |
ASCII Mockup (80×30)
┌──────────────────────────────────────────────────────────────────────────────┐
│ WIKI DEPOT · TOC SORT:[PHASE ▲] [U] [S] [REC] [T] │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ ▸ PHASE: RESEARCH (3) ────────── │
│ │ ▸ Pod·Architecture [HERON] draft 2h ▲ scroll │
│ │ Combat·Base·Loop [TRIDENT] final 5h █ position │
│ │ Level·Topology [KUJO] draft 1d █ │
│ │ ▼ │
│ ▸ PHASE: DRAFTING (5) ────────── │
│ │ ▸ Story·Arc·Act1 [HERON] draft 1h │
│ │ NPC·Relation·Graph [RANGER] final 3h │
│ │ Dialogue·Tree [ARCHITECT] disputed 6h │
│ │ Economy·Model [TRIDENT] draft 1d │
│ │ Item·Manifest [KUJO] final 2d │
│ │
│ ▸ PHASE: REVIEW (1) ────────── │
│ │ Combat·Balance [ACE] draft 4h │
│ │
│ ▸ PHASE: FINAL (2) ────────── │
│ │ Core·Loop [HERON] final 1d │
│ │ Win·Condition [TRIDENT] final 2d │
│ │
│ ▸ RECENCY (last 24h) ────────── │
│ │ 1h Story·Arc·Act1 HERON DRAFTING draft │
│ │ 2h Pod·Architecture HERON RESEARCH draft │
│ │ 4h Combat·Balance ACE REVIEW draft │
│ │ 5h Combat·Base·Loop TRIDENT RESEARCH final │
│ │ 6h Dialogue·Tree ARCHITECT DRAFTING disputed │
│ │
├──────────────────────────────────────────────────────────────────────────────┤
│ [A:Open] [X:Sort] [Y:Mac] 12 pages · 4 phases · 6 units [B:Back] │
└──────────────────────────────────────────────────────────────────────────────┘
Sort Modes (X cycles through)
| Mode | Group By | Description |
|---|---|---|
| Phase | phase label | Research → Drafting → Review → Final |
| Unit | producer_unit | ACE → ARCHITECT → HERON → KUJO → RANGER → TRIDENT |
| Status | status | Final → Draft → Disputed |
| Recency | updated (desc) | Flat list, newest first, time buckets (1h, 6h, 24h, 7d, older) |
| Tags | tags[0] | Group by primary topic tag |
API Endpoint
GET /wiki-index.json
→ Returns full graph + wiki index (cached by Pi, invalidated on state change)
→ Client filters locally (data set is small enough: <200 pages, <50 nodes)
View 2: Per-Node Pointer Links
Purpose
When inspecting a node's work, see everything connected to it: pages it produced, pages it referenced, and nodes that cross-reference the same pages.
Layout Strategy
- Top bar: Node name + unit + phase + status
- Section 1 — Produced: Pages this node wrote (always present, may be empty)
- Section 2 — Referenced: Pages this node used as context (input links)
- Section 3 — Related Nodes: Other nodes that reference the same pages (discover connections)
- Preview panel: Bottom ⅓ of screen shows first ~8 lines of selected page
Interaction Flow
| Input | Action |
|---|---|
| D-pad ↑/↓ | Move cursor through entries (all sections are one flat list) |
| A | Open selected page — full-screen wiki reader on RG |
| B | Back to TOC or previous view |
| X | Toggle preview panel on/off (maximize list space) |
| Y | Send "open on Mac" for selected page |
| Select (hold A) | Jump to Cross-Reference View for selected page (View 5) |
ASCII Mockup (80×30)
┌──────────────────────────────────────────────────────────────────────────────┐
│ NODE: arch-pod-design [HERON] PHASE:drafting STATUS:in_progress [▣ prev]│
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ PRODUCED (1) │
│ ► Pod·Architecture ........... draft concept 2h ─────────────────── │
│ <this page was produced here> │
│ REFERENCED (3) │
│ Core·Loop .................. final concept 1d │
│ Combat·Base·Loop ........... final research 5h │
│ Level·Topology ............. draft concept 1d │
│ │
│ RELATED NODES (2) │
│ combat-system [TRIDENT] — also refs Core·Loop, Combat·Base·Loop │
│ entity-map [RANGER] — also refs Level·Topology │
│ │
│ ┌ PREVIEW: Core·Loop ───────────────────────────────────────────────────┐ │
│ │ # Core Loop concept · final │ │
│ │ │ │
│ │ The player enters through the initial zone and must │ │
│ │ progress through three major phases: exploration, │ │
│ │ combat, and narrative resolution. Each phase feeds │ │
│ │ into the next via a gated transition system... │ │
│ │ │ │
│ │ ## Phase Structure │ │
│ │ 1. Exploration — open world traversal, discovery │ │
│ └────────────────────────────────────────────────────────────────────────┘ │
├──────────────────────────────────────────────────────────────────────────────┤
│ [A:Open] [X:Preview] [Y:Mac] [Hold A:Crossref] 1 produced + 3 refs [B:Back]│
└──────────────────────────────────────────────────────────────────────────────┘
View 3: Trail Context as Navigable Links
Purpose
Walk through a unit's accumulated context step by step. Each context item (seed prompt, wiki reference, memory recall, harvester feed) is a tappable link that opens the relevant wiki section.
Layout Strategy
- Top bar: Unit + phase + step counter (e.g., "Step 3/7")
- Context chain: Scrollable vertical list, each item numbered
- Context types (icon prefix):
[S]SEED — initial prompt given to the unit[R]REF — wiki page reference[M]MEM — memory recall / prior context[F]FEED — harvester intel flag[O]OUT — output produced (final step)- Detail panel: Bottom ⅓ shows expanded context for selected item
- Jump bar: L1/R1 to jump between major context items (skip seeds/mem)
Interaction Flow
| Input | Action |
|---|---|
| D-pad ↑/↓ | Move through context chain entries |
| A | Open linked wiki page (for REF type) / expand detail (for other types) |
| B | Back to node view |
| X | Toggle detail panel |
| Y | Open linked page on Mac |
| L1/R1 | Jump to next/previous REF or OUT entry (skip SEED and MEM) |
ASCII Mockup (80×30)
┌──────────────────────────────────────────────────────────────────────────────┐
│ TRAIL: HERON · arch-pod-design STEP [◄ 3/7 ►] │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ [S] 1 "Design a pod-based architecture system for modular level │
│ construction." ────────── │
│ [R] 2 Core·Loop (concept, final) — refs §phase-structure █ position │
│ [R] 3 Combat·Base·Loop (research, final) — refs §pacing █ │
│ [M] 4 "Previous pod designs used 3×3 grid — consider hex..." █ │
│ [R] 5 Level·Topology (concept, draft) — refs §zones ▼ │
│ [F] 6 Harvester Flag #12: "Pod density max 5/zone" ────────── │
│ [O] 7 Pod·Architecture (concept, draft) │
│ │
│ ┌ STEP 2 ───────────────────────────────────────────────────────────────┐ │
│ │ TYPE: Wiki Reference PAGE: Core·Loop │ │
│ │ PHASE: Research UNIT: HERON │ │
│ │ SECTION: §phase-structure STATUS: final │ │
│ │ │ │
│ │ "The player enters through the initial zone and must progress │ │
│ │ through three major phases: exploration, combat, and narrative │ │
│ │ resolution. Each phase feeds into the next via a gated..." │ │
│ │ │ │
│ │ [A:Open Wiki Page] [Y:Mac] [X:Close Detail] │ │
│ └────────────────────────────────────────────────────────────────────────┘ │
├──────────────────────────────────────────────────────────────────────────────┤
│ [A:Open] [X:Detail] [Y:Mac] [L1/R1:Skip] 7 context items [B:Back] │
└──────────────────────────────────────────────────────────────────────────────┘
View 4: Harvester Intel Feed
Purpose
Review flagged intel items from harvester units (PROPHET, ACE). Triage pending items, review accepted/routed items, dismiss rejected items.
Layout Strategy
- Top bar: Feed title + live status filter chips
- List: Flag items with compact card layout
- Status indicators:
⏳Pending — needs review✓Accepted — routed to a node✗Rejected — dismissed with reason- Filter bar (X cycles): Status → Suggested Node → Topic Tag → Source Unit
- Flag card: Quote text + metadata line (source, target node, time)
Interaction Flow
| Input | Action |
|---|---|
| D-pad ↑/↓ | Move through flag list |
| D-pad ←/→ | When status filter active, cycle status tabs |
| A | Expand flag detail (full text + related pages) |
| B | Back to game |
| X | Cycle filter mode: Pending/All → By Node → By Tag → By Unit |
| Y | Send flag to Mac clipboard (for external triage) |
| Select (hold A) | Mark as accepted / rejected (confirmation dialog) |
ASCII Mockup (80×30)
┌──────────────────────────────────────────────────────────────────────────────┐
│ HARVESTER FEED [⏳PENDING 3] [✓ACCEPTED 5] [✗REJECTED 2] │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ ⏳ "Combat flow rate from Core·Loop suggests pod density max of │
│ 5 active per zone." │
│ → for: arch-pod-design | #combat-balance | PROPHET | 2h │
│ │
│ ⏳ "Architecture pod grid should support diagonal connections, │
│ not just cardinal — increases expressiveness 40%." │
│ → for: arch-pod-design | #architecture | ACE | 3h │
│ │
│ ✓ "Level topology must account for verticality in zone 3 — │
│ current flat model won't support bridge encounters." ─── │
│ → for: level-topology | #level-design | PROPHET | 5h ▲ │
│ █ │
│ ✓ "NPC relation graph needs a 'betrayal' edge type — current █ │
│ model only supports ally/neutral/hostile." █ │
│ → for: npc-relation | #npc | ACE | 6h █ │
│ █ │
│ ✓ "Economy model should use logarithmic scaling for high-level █ │
│ items — prevents inflation in late game." █ │
│ → for: economy-model | #economy | PROPHET | 8h █ │
│ █ │
│ ✗ "Use real-time clock for day/night cycle" █ │
│ → for: core-loop | #time | ACE | 1d █ │
│ Reason: "Game uses in-game time, not real-time — rejected by ▼ │
│ TRIDENT on review." ─── │
│ │
│ ✓ "Combat balance needs diminishing returns on dodge stacking — │
│ currently possible to reach 95% dodge with 3 items." │
│ → for: combat-balance | #combat-balance | PROPHET | 1d │
│ │
├──────────────────────────────────────────────────────────────────────────────┤
│ [A:Expand] [X:Filter] [Y:Clipboard] [Hold A:Triage] 10 flags [B:Back] │
└──────────────────────────────────────────────────────────────────────────────┘
Triage Dialog (hold A on a pending flag)
┌──────────────────────────────────────────────────────────────────────────────┐
│ ┌ TRIAGE FLAG #7 ───────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ "Combat flow rate from Core·Loop suggests pod density max of │ │
│ │ 5 active per zone." │ │
│ │ │ │
│ │ Source: PROPHET | Topic: #combat-balance │ │
│ │ Suggested for: arch-pod-design │ │
│ │ │ │
│ │ [A:ACCEPT] [X:REJECT] [B:CANCEL] │ │
│ │ │ │
│ └────────────────────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────────────────┘
View 5: Cross-Reference View
Purpose
Bidirectional link browsing. From any wiki page or node, discover what else connects to it and what it connects to.
Layout Strategy
- Top bar: Current page/node title + view mode indicator
- Split view: "Referenced By" (incoming) on left, "References" (outgoing) on right
- OR toggle between the two (if too cramped)
- Each entry shows: page title + node/unit that created the link + link context
Interaction Flow
| Input | Action |
|---|---|
| D-pad ↑/↓ | Move through entries in active column |
| D-pad ←/→ | Switch between incoming / outgoing column |
| A | Open selected page |
| B | Back to previous view |
| X | Toggle between split view and full-width single column |
| Y | Open selected page on Mac |
| L1/R1 | Jump between columns |
ASCII Mockup — Split View (80×30)
┌──────────────────────────────────────────────────────────────────────────────┐
│ CROSS-REF: Core·Loop (concept · final · HERON) [◄ ►] │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ REFERENCED BY (4) REFERENCES (3) │
│ ───────────────── ───────────── │
│ │
│ ► Combat·System Combat·Base·Loop │
│ via TRIDENT · drafting research · TRIDENT │
│ §combat-flow-rate │
│ Level·Topology │
│ Arch·Pod·Design concept · KUJO │
│ via HERON · drafting │
│ §phase-structure Win·Condition │
│ final · TRIDENT │
│ Economy·Model │
│ via TRIDENT · drafting │
│ §resource-pacing │
│ │
│ NPC·Relation·Graph │
│ via RANGER · review │
│ §faction-tiers │
│ │
│ │
│ │
├──────────────────────────────────────────────────────────────────────────────┤
│ [A:Open] [X:1-Col] [Y:Mac] [←→:Col] 4 incoming · 3 outgoing [B:Back] │
└──────────────────────────────────────────────────────────────────────────────┘
ASCII Mockup — Single Column (X toggles; 80×30)
┌──────────────────────────────────────────────────────────────────────────────┐
│ CROSS-REF: Core·Loop — INCOMING │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ Pages that REFERENCE Core·Loop (4): │
│ │
│ ► Combat·System draft TRIDENT §combat-flow-rate │
│ │
│ Arch·Pod·Design draft HERON §phase-structure │
│ │
│ Economy·Model draft TRIDENT §resource-pacing │
│ │
│ NPC·Relation·Graph review RANGER §faction-tiers │
│ │
│ │
│ │
│ │
│ │
│ │
│ │
│ │
│ │
│ │
│ │
│ │
├──────────────────────────────────────────────────────────────────────────────┤
│ [A:Open] [X:Split] [Y:Mac] [L/R:Outgoing] 4 incoming [B:Back] │
└──────────────────────────────────────────────────────────────────────────────┘
Button Mapping: Full Reference
| Button | Context | Action |
|---|---|---|
| D-pad ↑/↓ | All views | Move cursor through list |
| D-pad ←/→ | TOC | Navigate filter chips in top bar |
| Cross-Ref | Switch between incoming/outgoing column | |
| Harvester | Cycle status tabs (when filter bar focused) | |
| A | All views | Select / open / confirm |
| A (hold) | Node View | Jump to Cross-Reference for selected page |
| Harvester | Open triage dialog for selected flag | |
| B | All views | Back — return to previous view or game |
| X | TOC | Cycle sort mode (Phase → Unit → Status → Recency) |
| Node View | Toggle preview panel | |
| Trail | Toggle detail panel | |
| Harvester | Cycle filter mode | |
| Cross-Ref | Toggle split/single-column | |
| Y | All views | Send "open on Mac" command (via Mozart Bridge :8318) |
| L1 | All views | Jump to previous group / section / column |
| R1 | All views | Jump to next group / section / column |
"Open on Mac" Protocol (Y button)
When Y is pressed, the RG sends a POST to Mozart Bridge:
POST http://<mac-ip>:8318/wiki/open
{
"page_id": "core-loop",
"page_path": "concept/core-loop.md",
"source_view": "toc"
}
Mozart Bridge opens the file in Typora or the default markdown editor on the Mac. This handles dense wiki content that's hard to read at 640×480.
Navigation Map (View Transitions)
┌─────────────────┐
│ GAME SURFACE │
└────────┬────────┘
│ Menu → "Wiki Depot"
▼
┌─────────────────┐
┌──────│ TOC (View 1) │──────┐
│ └────────┬────────┘ │
│ │ A │ X (filter to unit)
│ ▼ │
│ ┌─────────────────┐ │
│ │ NODE (View 2) │ │
│ └───┬──────┬──────┘ │
│ A │ │ Hold A │
│ (wiki) │ ▼ │
│ │ ┌──────────────┐ │
│ │ │ CROSS-REF │ │
│ │ │ (View 5) │ │
│ │ └──────────────┘ │
│ │ │
│ │ A (on REF item) │
│ ▼ │
│ ┌─────────────────┐ │
│ │ TRAIL (View 3) │ │
│ └────────┬────────┘ │
│ │ A (on FEED item) │
│ ▼ │
│ ┌─────────────────┐ │
└──│ HARVESTER │◄─────────┘
│ (View 4) │
└─────────────────┘
API Contract (Pi Endpoints)
GET /api/wiki-index.json
Full wiki index + graph state. Cached in-memory on Pi, invalidated on state change. Client filters locally.
{
"version": "1",
"generated": "2026-05-12T16:45:00Z",
"pages": [ /* see Data Model above */ ],
"graph": { /* nodes + trail_context */ },
"harvester": { "flags": [ /* ... */ ] }
}
GET /api/wiki-page/{page_id}
Returns full markdown content of a single page, plus its metadata block.
{
"id": "core-loop",
"title": "Core Loop",
"content": "# Core Loop\n\nThe player enters through...",
"metadata": { /* same as in index */ }
}
GET /api/wiki-crossref/{page_id}
Bidirectional references for a page.
{
"page_id": "core-loop",
"referenced_by": [
{ "page_id": "combat-system", "node_id": "combat-system", "unit": "TRIDENT", "section": "combat-flow-rate" }
],
"references": [
{ "page_id": "combat-base-loop", "node_id": "combat-base-loop", "unit": "TRIDENT" }
]
}
POST /api/harvester/triage
Triage a harvester flag (mark accepted or rejected). Pi writes back to LangGraph state.
// Request
{ "flag_id": "flag-12", "action": "accept", "routed_to_node": "arch-pod-design" }
// or
{ "flag_id": "flag-12", "action": "reject", "reason": "Out of scope for current phase" }
Error Responses
All endpoints return { "error": "message" } with appropriate HTTP status. Client displays errors inline in the status bar.
Implementation Notes
Font & Rendering
- Target: 8×16 pixel monospace font → 80 columns × 30 rows
- Use bitmap font from RG40XXV firmware (no TTF needed)
- Render loop: fetch JSON → build display buffer → blit to framebuffer
- No scrolling animation needed (instant redraw on D-pad)
Caching Strategy
- Fetch
wiki-index.jsonon view entry, cache for 5 seconds - Invalidate cache on B-button exit from any wiki view
- All filtering/sorting is client-side (data set fits in RAM)
- Page content fetch (
/api/wiki-page/{id}) is lazy — only when preview or full page is opened
Performance Budget
wiki-index.json: <50KB (estimated for 200 pages, 50 nodes, 100 flags)- Page content fetch: <10KB per page
- Render budget: 16ms per frame (60fps) — should be trivial for JSON→text rendering
- Network: all over local WiFi, <5ms ping
Fallback States
| State | Display |
|---|---|
| Loading | "Fetching wiki..." centered text with spinner animation |
| Empty (no pages) | "No wiki pages yet. Run a graph cycle to generate content." |
| Network error | "Cannot reach Pi at |
| Page not found | "Page deleted or not yet generated." |
"Open on Mac" Implementation
- RG sends POST to Mozart Bridge (Mac IP hardcoded or discovered via mDNS)
- Mozart Bridge runs a small HTTP server on :8318
- Receives
{ "action": "open_wiki_page", "page_path": "..." } - Opens file in Typora:
open -a Typora /workcell/llm-wiki/wiki/<page_path>
End of design. Ready for review.