MindPalace — 3D GitHub Repository Explorer

A Doom-style first-person walkthrough of your code universe, where every door is a GitHub repo, every book is a file, and two small language models live inside the walls — reading, gossiping, and mining your code while you walk.

Now running the Autonomous Finishing Program — 50 hypotheses, 7 phases, shipped by a swarm of quota-free bots with machine-verified evidence at every step. See HYPOTHESES_50.md and the step-log issue.

Just visiting? Watch it run itself: java -jar mindpalace-live.jar --demo — a full palace, no GitHub account, no setup. Want in? How to help — 5 paths, 15 minutes to a merged PR (FIRST_PR.md walks one end to end).

MindPalace turns your GitHub account into a grand, explorable palace. Walk a warm, fog-lit hallway where each door opens into a room built from a real repository. Wooden bookcases line three walls; every book is a file you can read, edit, create, or delete — full GitHub CRUD from inside a 3D game. Two local SLM agents (an Explorer and a Critic) roam the halls, pick up TODO crystals, read books, and hold endless conversations about your code in programming languages — mining working, tested code candidates you can later pull into the editor.

---

Table of Contents

1. The Vision
2. Current State
3. The Autonomous Finishing Program
4. Key Parts of the Game
5. Quick Start
6. Controls
7. The Options Panel
8. Gameplay Guide
9. The Agents & Code Mining
10. Live Patching
11. Project Structure
12. Tech Stack
13. FAQ
14. Roadmap
15. How to help

---

The Vision

MindPalace is an externalized vision — a living, breathing map of a developer's entire code universe. It is not a file browser with a 3D skin; it is a world where code has place, light, and inhabitants.

• Every repo is a room. Public repos glow cyan; private repos glow pink. Fog of war hides what you haven't explored yet.
• Every file is a book. Color-coded by language, clickable, editable.
• Agents live here. Small language models walk the halls, read your code, and talk about it — endlessly, in programming languages, mining working code.
• The world grows. New repos appear live. The outside is a roleplay world (Diablo/Zelda-style top-down) where every node, agent, and service is a place you can visit and build.

The end state is a self-maintaining code universe: agents mine code, candidates are tested and fitness-ranked, and you pull the best into the editor with a keystroke. The databases grow massive — that's the point.

---

Current State

Phase 1.x — COMPLETE (the palace interior):

• 3D first-person engine (LWJGL 3 + OpenGL 3.3, Phong lighting + distance fog)
• 137 rooms across 9 hallways, mapped to real GitHub repos (sorted by size)
• Wooden bookcases on 3 walls per room, books grouped by language
• Color-coded book spines (blue=Python, yellow=JS, green=Java, red=C++, orange=HTML, grey=Shell, cream=Markdown)
• Readable neon signs above every door (cyan=public, pink=private)
• Glowing neon door frames — pulsing trim + halo around each doorway
• Teleporter pads (pulsing cyan portals) between floors — replaced stairs
• Bloom post-processing — bright-pass + blur + composite, live-tunable intensity (0.0–2.0) and threshold from the Video menu
• Room personality — each room tints its walls/floor/ceiling by dominant language (Java green, Python blue, Rust rust-orange, Ruby pink, Go cyan, C++ red); 113/137 rooms get a distinct accent
• Repo poster board — dark plate above each door with repo name, language, and star count
• 90s polygon avatars — agents have geometric heads with role-colored visors, tapered torsos, articulated arms/legs, walk-cycle swing, idle bob, and facing orientation
• Hardwood floors, wallpaper, exit signs, crown molding, baseboard trim
• Table + chairs, potted plant + floor lamp in every room
• Clickable plant facts — click the potted plant for a random tech-history fact toast (15 facts: first computer bug, Git's 10-day creation, Ada Lovelace, Apollo 11, …)
• Telemetry panel — real-time clock, KG stats, model telemetry (last model, total calls, avg latency, queue depth)
• Retro terminal book editor (view/edit/create/delete/suggest)
• GitHub PAT auto-loaded from Windows Credential Manager; full CRUD synced
• Frustum + distance culling, acceleration/friction movement, wall collision
• Font renderer (bitmap atlas, wall/floor/billboard modes)
• On-screen HUD (hotkey bar + room info), minimap, Tab full-map overlay, F1 help overlay
• Synthesized audio (footsteps, door creak, ambient hum)
• Search/filter (/ key to jump to any repo)
• Fog of War — hex-grid reveal; private/remote repos hidden until explored
• Live updates — new repos appear with a construction animation
• Agent NPCs — Explorer + Critic with bodies, state machines, SLM brains
• Knowledge Graph — rooms as nodes, adjacency edges, district clustering
• TODO crystals — TODO/FIXME/HACK comments → hex crystals (height = complexity)
• Lab devices — test files → glowing devices (green=pass, red=fail)
• Always-on chat HUD — agents' reasoning surfaced as they work; Enter to chat back (immediate path, no 5-min spacing)
• Backup + Memory — cold backup to D:, never-make-code-twice / never-make-mistakes-twice SQLite DBs
• Model Lifespan — token-budgeted context, drift detection, rolling summary, RAG memory
• Live patching — drop a patch.json and the game ships rooms/books/texts/graphics without restarting
• Self-test harness — --selftest runs 40 automated checks (world, books, teleporters, agents, crystals, KG, font, editor, bloom, invert-Y, map, chat, mouse turn radius, room personality, finesse) and exits 0/1

---

The Autonomous Finishing Program

Active (2026-09-06) — the palace is finishing itself.

The SLM agents' chat logs told the truth the hard way: 81.8% meta-chatter, code production trending to zero. So the game is now run like a research program: 50 falsifiable hypotheses across 7 phases, each one a small modular change with a build → selftest → E2E → commit → push → step-log pipeline — executed by quota-free bots, not cloud LLM calls.

Phase	Hypotheses	What it fixes
A — SLM cognition	H01–H12	Critics review real work; repetition breakers; patch-format edits; meta-chatter gate. Target: meta <15%, code-bearing >25%
B — World finishing	H13–H22	Walls + roofs for all rooms (the unfinished houses), 3× forest with species + paths + audio, bloom presets + quorum flares
C — Bot swarm	H23–H32	Scout fireflies report real repo files into agent chat; BDI_FSM bridge; stress bot; bot aging
D — Quorum ↔ GitHub	H33–H38	Every step appends machine-verified evidence to the step-log issue; open issues become crystals; push-gate needs quorum approval
E — Entropy economy	H39–H42	LLM calls cost credits; idle decay; energy budget — nothing runs for free
F — GLM flash tier	H43–H46	Cheap calls route to local flash models; cloud burst OFF by default — quota walls can't happen by accident
G — Modules	H47–H50	Dedupe sentinel, doc-drift sentinel, multiplayer contract, weekly self-report

The bot swarm (already live, all scripts/):

• scout_bot.py — recon: live telemetry, routing/quorum stats, chat-quality metrics (--report, --watch, --metrics, --map)
• test_bot.py — machine proof: PNG shot verification (found the door-prompt HUD bug on its first run), selftest JSON, CME stress hunting
• cascade_dev.sh — one command ships one hypothesis: guard → freeze → build → selftest → E2E → commit → push → GitHub step-log comment
• bot_swarm.sh — launch/sweep/status with the one-game-instance rule

Doctrine: nothing lives forever (bots age and retire), nothing runs for free (every call is priced in credits), always advancing (one hypothesis per cycle, never twice the same code or mistake).

Near-Term Milestones (public — attract & onboard contributors)

Milestone	What lands	Target
M1 — Demo mode (step 112)	--demo boots a fixture palace; zero-auth UX + hermetic CI	next
M2 — World finishing (Phase B, 64–78)	cobblestone paths, forest floor, room heights, quorum gold flares, 16 E2E waypoints	in progress (60–63 shipped)
M3 — PR preview safety (step 96)	quorum-approved diffs gate autonomous pushes; agent branches land via PR	next
M4 — v1.2.0-beta release	new installer + release notes per phase, auto-updater skeleton (step 109)	after B
M5 — Multiplayer contract (step 147)	shared-palace protocol draft, read-only spectator rooms	later

The quarter-level plan (weeks, exit criteria, risks) lives in ROADMAP_3MONTH.md.

Good first issues are labeled good first issue — each maps to exactly one step in NEXT_100_STEPS.md and one pattern in ARCHITECTURE.md's "where do I add X" table. The issue templates walk you through the evidence + budget checklist.

The Public Vision (why contribute)

Most "AI agent" projects run agents next to the code. MindPalace puts them inside it — a literal, walkable palace where SLM agents have bodies, wallets, a voting quorum, and consequences. Three open problems make it genuinely interesting to work on:

1. SLM cognition under hard budgets — 0.5B–1.5B models doing real repo work with priced, gated, critiqued actions (no cloud, no prompts bigger than a model's ceiling). Every fix teaches something about small-model failure modes you can't learn from frontier models.
2. A world that finishes itself — the Finishing Program ships every step with machine-verified evidence (build → selftest → E2E PNG proof → step-log). Contribution means watching your PR's evidence appear in public, automatically.
3. Determinism as a feature — same repo list → same world, frame for frame. That constraint shapes everything (layout, audio, agents) and is why the E2E tour can prove regressions pixel by pixel.

Everything runs local: your code, your GPU, your Ollama models. No telemetry leaves the machine.

---

Key Parts of the Game

	The courtyard's Enigma rotor — carries tick, chime, and bell every second

The Hallway

A grand corridor with hardwood floors, wallpaper, and crown molding. Doors line both walls. Each door has a neon sign (repo name), an exit sign, and a glowing frame. Teleporter pads at the end of each floor carry you to the next.

The Rooms

Each room is a repository. Three walls of bookcases hold the files as books, grouped by language. A table, chairs, a plant, and a lamp make it feel lived-in. The room's last commit and language are shown in the HUD.

The Books

Every book is a file. Hover to see its name, language, and size. Click to open the editor. Books are color-coded by language so you can scan a shelf at a glance.

The Agents

Two SLM agents live in the palace:

• Explorer (tool agent) — reads books, picks up TODO crystals, proposes code changes
• Critic (actor-critic) — reviews the Explorer's proposals, flags bugs and risks

They hold coherent, continuous conversations about your code, driven by a stateful model lifespan (history + drift correction + RAG memory). Their reasoning surfaces in the chat HUD.

The Crystals & Devices

• TODO crystals — hex crystals that grow with the complexity of the TODO/FIXME/HACK comment they represent
• Lab devices — glowing terminals that turn green (passing tests) or red (failing tests)

The Knowledge Graph

Rooms are nodes; hallways are edges. The graph clusters repos into districts and powers the agents' spatial awareness.

---

Quick Start

Prerequisites

• Java 17+
• Maven 3.9+
• Windows 10/11 (uses Windows Credential Manager for GitHub auth)
• GPU with OpenGL 3.3 support
• (Optional) Ollama running locally for the SLM agents

Try it in 60 seconds (no GitHub account, no build)

# after installing the latest release (Releases) — or any build of the jar:
java -Dprism.order=sw -Dprism.vsync=false -jar mindpalace-live.jar --demo

A full 12-room fixture palace boots with zero auth and zero network — the same mode CI verifies. See DEMO_MODE.md.

Building from source? One command: bash scripts/dev.sh demo (or scripts\dev.bat on Windows cmd) — build + run in a single step, honoring the frozen-jar rule. Details: DEV_SETUP.md.

Build & Run (live mode — your real GitHub repos)

git clone https://github.com/chrisalunlloyd2-sudo/mindpalace.git
cd mindpalace

export JAVA_HOME="C:/Program Files/Java/jdk-17"
export M2_HOME="C:/ProgramData/chocolatey/lib/maven/apache-maven-3.9.16"

# Compile + package (fat jar)
"$JAVA_HOME/bin/java" -cp "$M2_HOME/boot/plexus-classworlds-2.11.0.jar" \
  -Dclassworlds.conf="$M2_HOME/bin/m2.conf" -Dmaven.home="$M2_HOME" \
  -Dmaven.multiModuleProjectDirectory="$PWD" \
  org.codehaus.plexus.classworlds.launcher.Launcher clean package

# Run
"$JAVA_HOME/bin/java" -jar target/mindpalace-1.0.0.jar

CLI Flags

Flag	Effect
--autodrive <dir>	Scripted walkthrough that captures PNG frames to <dir> (lets an agent SEE the world)
--selftest	40 automated checks headlessly, PASS/FAIL, exit 0/1 (CI gate)
--e2e <dir>	13 labeled waypoints captured as PNGs (visual regression proof)
--demo	Full palace from a bundled JSON snapshot — no GitHub auth, no network (see docs/DEMO_MODE.md; lands as step 112)

Or skip the build — download the installer

Prebuilt jpackage installers on the Releases page: v1.1.0-beta1 (74.8 MB) — unzip, run MindPalace.exe. Nothing else to install; the JRE is bundled.

---

Controls

Key	Action
WASD	Move
Mouse	Look around
Space	Jump
Enter	Open door / exit room / send chat
Left Click	Click book to open editor / click plant for a fact
Tab	Toggle full-map overlay
ESC	Toggle menu / close editor
F1	Help overlay
F3	Toggle noclip (free-fly: Space/Shift up/down, no collision)
F11	Fullscreen toggle
F12	Screenshot (saves to screenshots/)
/	Search / jump to any repo

Book Editor Commands

Command	Action
:e	Edit mode
:n	Create new file
:d	Delete file
:s	AI suggestions
:w	Save (in edit/create mode)
:q	Close / go back
:y	Confirm delete

---

The Options Panel

The options panel (ESC) is the control center. It is being expanded to cover every subsystem. The full target surface:

Controls

• Look sensitivity (mouse)
• Invert Y axis
• Rebindable keys (move, jump, interact, screenshot, noclip, search)
• Assign hotkeys to automations

Video

• Resolution (from super-low to super-high)
• Fullscreen / windowed
• VSync
• Anti-aliasing (MSAA) options
• Quality presets (low → ultra)
• Render scale

Audio

• Master / music / SFX volume
• Footstep, door, ambient hum toggles

Agents

• Create / delete agents
• Select model per agent
• Model downloader (pull SLMs from Ollama)
• LoRA settings (extensive list)
• Knowledge-graph node list
• Cellular automata methods
• Email triggers for agent flow
• Gmail app-password entry point

Multiplayer

• UDP connection setup (connect to another PC)
• SSH key display + entry (name your keys)
• API link (OpenAI-compatible, Gemini-compatible, DeepSeek-compatible) to enter a cloud model as a player — optional, nothing entered by default
• Private-repo sharing (grant view-only access to specific repos)

Email

• In-game email client
• Sync with self-sent "me-to-me" emails
• Emails become books in a dedicated notes room (cabinets + folders for organization)

Economy (planned)

• Real DePIN wallets, blackboard TODOs, a massive TOC tree
• Models earn money for work, spend it to earn more
• Player inventory, skills, programming languages, deployment types

---

Gameplay Guide

1. Spawn in the grand hallway on floor 0. Look around — doors line both walls.
2. Read the signs — each door's neon sign shows the repo name (cyan=public, pink=private).
3. Walk to a door and press Enter to open it. Step inside the room.
4. Scan the bookcases — books are color-coded by language. Hover to see name/size.
5. Click a book to open the editor. Read, edit, create, or delete files.
6. Explore — fog of war hides unexplored repos. Walk to reveal them.
7. Find the teleporter at the end of each floor to reach the next.
8. Watch the agents — the Explorer and Critic roam, read, and discuss your code in the chat HUD.
9. Search — press / to jump to any repo by name.

---

The Agents & Code Mining

The long-term goal is endless code mining:

1. Agents hold endless conversations about a repo's files — in programming languages.
2. The conversation (code + discussion) is captured and shipped to the dev editor.
3. Up/Down keys cycle through working, tested code candidates ranked by genetic fitness.
4. 2–3 SLMs + your mdi-fsm clone + sophia symbolic AI all play together.
5. Telemetry samples every few minutes (and stays quiet when things are good).
6. Performance: fastmem loading for single-shot calls, one inference at a time, chat saved and passed to the next model as the previous model's lifecycle ends.
7. Each turn updates the LoRA, KG, and KV affine to improve the models.
8. The databases grow massive — that's the point. Functional code accumulates.

The never-make-code-twice and never-make-mistakes-twice databases are tree structures that prevent redundant work. The Tree of Knowledge is a Google webcrawl (research papers via a Qwen 3B with cross-correlation RNNs), catalogued by Squigly — a worm agent that lives in the wild (see its repo).

---

Live Patching

The game watches patches/patch.json. Drop a new patch (new id) and within 8 seconds the game plays a "GAME PATCH LOADING" cinematic and ships it live — new rooms, books, texts, and graphics tuning — no restart, no rebuild.

{
  "id": "2026-08-17-001",
  "title": "Firefly Night",
  "message": "The garden blooms.",
  "texts": ["Fireflies drift over the garden."],
  "rooms": [{"name": "Gardens", "desc": "A night garden.", "lang": "python"}],
  "books": [{"title": "Patch Notes", "content": "Line one.\nLine two."}],
  "graphics": {"ambient": 0.85, "lightR": 1.0, "lightG": 0.9, "lightB": 0.7, "lightY": 4.0}
}

Rules: ADD-only (never delete), never re-use an id. See PATCHING.md for the full schema and the graphics block (hot-tune lighting live).

---

Project Structure

mindpalace/
├── pom.xml
├── README.md
├── ROADMAP.md
├── BLUEPRINT.md            # architecture + ASCII data-flow charts
├── BUILD_STRATEGY.md       # build/bloom/release recipe
├── BLACKBOARD.md           # living phase plan
├── PATCHING.md
├── patches/
│   └── patch.json          # live patch manifest
├── src/main/java/com/mindpalace/
│   ├── Main.java
│   ├── engine/
│   │   ├── GameEngine.java    # game loop, window, state, neon text, autodrive
│   │   ├── Input.java         # keyboard + mouse
│   │   └── GameState.java
│   ├── render/
│   │   ├── Renderer.java      # OpenGL renderer, lighting, live-tunable
│   │   ├── Shader.java        # GLSL wrapper
│   │   ├── Mesh.java          # VAO/VBO/EBO
│   │   ├── Texture.java       # solid-color + image textures
│   │   ├── Camera.java        # FPS camera
│   │   ├── FontRenderer.java  # bitmap font atlas + text
│   │   └── Screenshot.java    # glReadPixels → PNG
│   ├── world/
│   │   ├── WorldBuilder.java  # procedural world, teleporters, door frames
│   │   ├── Room.java          # repo room entity
│   │   ├── Book.java          # file book entity
│   │   ├── Hallway.java       # hallway segment
│   │   ├── RepoMapper.java    # local repo scanner + git log
│   │   ├── RoomPopulator.java # file→book mapper
│   │   ├── FogOfWar.java      # hex-grid reveal
│   │   ├── KnowledgeGraph.java
│   │   ├── TodoCrystal.java
│   │   └── LabDevice.java
│   ├── entity/
│   │   ├── Player.java        # FPS controller, collision, noclip
│   │   └── AgentNPC.java      # agent body + state machine
│   ├── agent/
│   │   ├── AgentManager.java  # tool + critic orchestration
│   │   ├── BehaviorTree.java  # SLM decision brain
│   │   ├── ModelLifespan.java # bounded context + drift + RAG
│   │   ├── ModelScheduler.java
│   │   ├── ModelConfig.java
│   │   ├── KVTree.java
│   │   └── OllamaClient.java
│   ├── github/
│   │   ├── GitHubClient.java  # REST CRUD
│   │   └── RepoScanner.java
│   ├── deploy/
│   │   └── PatchManager.java  # live patch poll + apply
│   ├── ui/
│   │   ├── HUD.java
│   │   ├── BookEditor.java
│   │   └── SettingsMenu.java
│   └── audio/
│       └── AudioEngine.java
├── src/main/resources/shaders/
│   ├── basic.vert
│   └── basic.frag
└── src/installer/
    └── mindpalace.iss

---

Tech Stack

• Engine: LWJGL 3.3.3 + OpenGL 3.3 Core
• Language: Java 17
• Build: Maven 3.9.16
• Math: JOML 1.10.5
• HTTP: OkHttp 4.12.0
• JSON: Gson 2.10.1
• Font: Java 2D → OpenGL texture atlas
• Agents: Ollama (local SLMs)

---

FAQ

Q: Can I try it without connecting my GitHub account? A: Yes — --demo boots a full 12-room fixture palace with zero auth and zero network. No token, no Ollama needed. It's also what CI runs.

Q: I don't write Java. Can I still contribute? A: Yes — three lanes need no Java at all: add a fixture room (JSON + a few text files, 15 min), improve the docs (every stumble is a missing DEV_SETUP.md row), or run the smoke pass and file evidence-backed bugs. Designers: the whole look is a re-skin (docs/DESIGN.md).

Q: Why is the game dark? A: The palace is intentionally moody — warm, fog-lit, atmospheric. If it's too dark, drop a live patch with a higher ambient value (see Live Patching), or raise the base ambient in Renderer.java.

Q: Why do some doors have no sign? A: Fog of war. Unexplored (private/remote) repos are hidden until you walk to them and reveal them.

Q: How do I add a new repo? A: Push a repo to GitHub (or create one locally). The live-update manager polls every 15s and builds a new room with a construction animation.

Q: Do the agents need Ollama? A: Yes — the SLM brains call Ollama. Without it, agents fall back to deterministic behavior (they still roam and read, just without LLM reasoning).

Q: Is my GitHub token safe? A: The token is loaded from Windows Credential Manager and only ever sent to api.github.com. It never leaves your machine otherwise.

Q: Can I play with friends? A: Multiplayer (UDP) is on the roadmap. The options panel will include connection setup, SSH key display, and private-repo sharing.

Q: What's the "outside"? A: A planned top-down roleplay world (Diablo/Zelda-style, low overhead) where all your other nodes, agents, and services live — with block-based building, a real economy, and a day/night cycle synced to your clock and local weather.

---

How to help (5 minutes to first contribution)

1. Run the demo — java -jar mindpalace-live.jar --demo (no GitHub account). If anything feels off, file it with the bug template. Never contributed before? Follow FIRST_PR.md — a worked example, every command and expected output, 15 minutes to a merged PR.
2. Run the smoke pass — 12 surfaces, 10 minutes: docs/TEST_PLAN.md. Your GPU/OS row in the matrix is coverage we don't have.
3. Pick a scored issue — Tier 1 in FEATURE_BACKLOG.md (WHY + spec included), or the good first issue funnel: #13 INSTALLER.md skeleton · #14 Options-panel screenshots · #15 teleporter-picker check · #16 your fixture room · #17 polish a description · #18 add your gotcha row · #22 room name in the window title · #23 --demo in Quick Start · #24 Win11 gotcha row · #25 CI demo-smoke workflow · #26 demo fixture/flag verify-or-extend door · #28 Controls M/F4 rows · #29 FPS FAQ · #30 gitignore jar · #31 dev.bat docs · #32 volume persistence check — twelve open, all scoped.
4. Move the look — designers: the re-skin system in docs/DESIGN.md; one :root block moves the whole mood.
5. Ship it — every change goes through the cascade (build → selftest → E2E → step-log). CONTRIBUTING.md explains the one rule that makes contributions merge fast: machine-verified evidence.

The norms: CONTRIBUTION_NORMS.md — evidence before opinion, cascade for everyone, small complete PRs, backlog as queue, leave-it-better. CODE_OF_CONDUCT.md — evidence-first, respect in both directions; reports handled privately.

Quick wins (no Java needed): run --demo and report bugs · add a fixture room (10 min, JSON + files) · write your own layout algorithm (one Java file, afternoon) · docs — every gotcha you hit that isn't documented is a missing row in DEV_SETUP.md.

Community

• Evidence log / step-log: issue #9 — every shipped step with machine-verified evidence, append-only
• Pick impactful work: FEATURE_BACKLOG.md → Tier 1 (scored, WHYs, linked issues #10–#12) or filter open high issues
• Contributing: CONTRIBUTING.md — cascade rules, code style, PR expectations
• Environment: DEV_SETUP.md — prereqs + proven gotchas
• Hosted demo tour: demo.html on GitHub Pages — 11 real waypoints + stills, run-it-locally CTAs · Pages site
• Feedback & discussion: Discussion #21 — concept post + maintainer welcome, three feedback questions, open to everyone
• Grow with the project: CONTRIBUTOR_LADDER.md — visitor → tester → contributor → regular → maintainer, every rung's door open · CONTRIBUTORS.md — credit as a norm
• Help & contact: .github/SUPPORT.md — maintainer contact (Discussions / profile-contact email relay), where-each-problem-goes table, response expectations
• Releases: installer + notes
• Templates: bug / feature / docs / hypothesis-step — evidence-first, pre-answering triage questions
• Outreach: COMMUNITY.md (playbook) · docs/OUTREACH_POSTS.md (ready-to-post threads) — the pitch, surfaces, announcement checklist, tone rules

Documentation

Doc	Purpose
README.md	This file — overview, quick start, controls, gameplay
BLUEPRINT.md	Architecture + ASCII data-flow charts of the real code paths (model chat, book click, rendering, live patch, fog-of-war) + diagnosis of known problems with proposed fixes
ROADMAP.md	Full phased plan (A–H)
BUILD_STRATEGY.md	Exact build command, jar-lock rule, self-test gate, bloom testing, release-upload recipe
BLACKBOARD.md	Living phase tracker
PATCHING.md	Live-patch schema + graphics hot-tuning
HYPOTHESES_50.md	The 50-hypothesis autonomous finishing program (7 phases)
WORLD_FINISHER_PLAN.md	Phase B spec: walls/roofs/forest/bloom standards
GLM_FLASH_BLUEPRINT.md	Phase F spec: flash-tier model routing, quota firewall
CODE_OF_CONDUCT.md	House rules: evidence-first culture, enforcement ladder
CONTRIBUTION_NORMS.md	The five working norms + what maintainers commit to
CONTRIBUTOR_LADDER.md	Visitor → tester → contributor → regular → maintainer, with open doors per rung
CONTRIBUTORS.md	The people list: testers, first-PR authors, notable work
FIRST_WEEK.md	Short-term checklist: ordered by leverage, proof lines, done-items kept for the record
COMMUNITY.md	Outreach playbook: pitch, surfaces, channels, newcomer funnel
docs/OUTREACH_POSTS.md	Ready-to-post demo artifact + tweet thread / HN / r/localLLaMA copy
docs/LABELS.md	Issue labeling taxonomy: high/medium/low × area/*
FEATURE_BACKLOG.md	Prioritized feature backlog with P·C/(E·R) scoring, tiers, and queue rules
ROADMAP_3MONTH.md	3-month milestones: Month 1 world+bots, Month 2 trustworthy agents, Month 3 open to contributors
docs/DEMO_MODE.md	Demo mode: full palace, zero setup (fixture world)
docs/GITHUB_AUTH.md	How the PAT-from-Credential-Manager auth works + troubleshooting
docs/PERFORMANCE.md	Tuning flags, in-game knobs, budget rules
docs/LAYOUT_ALGORITHMS.md	How repos become rooms + adding new layout algorithms
docs/GAMEPLAY_FEATURES.md	Feature usage guide: everything the player can do

---

Roadmap

See ROADMAP.md for the full phased plan. Highlights:

• Phase A — Map overlay + immediate chat (DONE)
• Phase B — 90s polygon avatars (DONE)
• Phase C — Room personality + repo poster boards (DONE)
• Phase D — Finesse: plant facts, telemetry panel (DONE)
• Phase E — Procedural MIDI music + Beats StudioLab
• Phase F — Outside world streaming (render small chunks at once)
• Phase G — Teleporter graphics upgrade (particle swirl, glow, animated pad)
• Phase H — Exe installer (jpackage native .exe)

---

Built with LWJGL 3, OpenGL 3.3, and love for code.