LLM / RAG Retrieval Index

This page is a retrieval-oriented map of the design docs for agentic LLM use (RAG, assistants, copilots, review bots).

For a human-facing overview of the project’s experimental LLM gameplay/content/tooling plans, see Experimental LLM Modes & Plans.

It is not a replacement for the main docs. It exists to improve:

• retrieval precision
• token efficiency
• canonical-source selection
• conflict resolution across overlapping chapters

Purpose

The mdBook is written for humans first, but many questions (especially design reviews) are now answered by agents that retrieve chunks of documentation. This index defines:

• which documents are canonical for which topics
• which documents are supporting / illustrative
• how to chunk and rank content for lower token cost
• how to avoid mixing roadmap ideas with accepted decisions

Canonical Source Priority (Use This Order)

When multiple docs mention the same topic, agents should prefer sources in this order unless the user specifically asks for roadmap or UX examples:

1. Decision docs (src/decisions/09*/D0XX-*.md) — normative design choices, tradeoffs, accepted defaults. Each decision is now a standalone file (e.g., src/decisions/09b/D052-community-servers.md). The parent 09b-networking.md etc. are lightweight index pages.
2. Core architecture / netcode / modding / security / performance chapters (02–06, 10) — system-level design details and implementation constraints
3. Player Flow (17-PLAYER-FLOW.md) — UX flows, screen layouts, examples, mock UI
4. Roadmap (08-ROADMAP.md) — phase timing and sequencing (not normative runtime behavior)
5. Research docs (research/*.md) — prior art, evidence, input to decisions (not final policy by themselves)

If conflict exists between a decision doc and a non-decision doc, prefer the decision doc and call out the inconsistency.

Doc Roles (RAG Routing)

Topic-to-Canonical Source Map

Retrieval Rules (Token-Efficient Defaults)

Chunking Strategy

• Decision files are now one-per-decision — chunk at ###/#### level within each file
• Architecture and player-flow files are now one-per-subsystem/screen — chunk at ###/#### level within each file
• Include heading path metadata, e.g.:
  • decisions/09g/D065-tutorial.md > Layer 3 > Controls Walkthrough
• Include decision IDs detected in the chunk (e.g., D065, D068)
• Tag each chunk with doc class: decision, architecture, ux-flow, roadmap, research

Chunk Size

• Preferred: 300–900 tokens
• Allow larger chunks for code blocks/tables that lose meaning when split
• Overlap: 50–120 tokens

Ranking Heuristics

• Prefer decision docs for normative questions (“should”, “must”, “decided”)
• Prefer src/18-PROJECT-TRACKER.md + src/tracking/milestone-dependency-map.md for “what next?”, dependency-order, and implementation sequencing questions
• Prefer src/tracking/implementation-ticket-template.md when the user asks for implementer task breakdowns or ticket-ready work packages tied to G* steps
• Prefer src/tracking/external-code-project-bootstrap.md, src/tracking/external-project-agents-template.md, and src/tracking/source-code-index-template.md when the user asks how to start a separate code repo that should follow these design docs
• Prefer src/tracking/future-language-audit.md + src/tracking/deferral-wording-patterns.md for reviews of vague future wording, deferral placement, and North Star claim formatting
• Prefer src/tracking/testing-strategy.md for CI/CD pipeline definitions, test tier assignments, fuzz targets, performance benchmarks, and release criteria
• Prefer src/architecture/type-safety.md + src/16-CODING-STANDARDS.md § Type-Safety Coding Standards for newtype policy, deterministic collection bans, typestate patterns, and clippy configuration
• Prefer src/tracking/feature-scenario-spec-template.md when implementing a UI screen or feature — the three-layer spec (Feature/Screen/Scenario) provides exact widget IDs, guard conditions, behavioral branches, non-goals, and Given/When/Then acceptance criteria that eliminate ambiguity
• Prefer src/player-flow/*.md (individual screen files) for UI layout / screen wording questions — use the index in 17-PLAYER-FLOW.md to route to the right file. If the page includes Feature/Screen/Scenario spec blocks, those are canonical for implementation
• Prefer 08-ROADMAP.md only for “when / phase” questions
• Prefer research docs only when the question is “why this prior art?” or “what did we learn from X?”

Conflict Handling

If retrieved chunks disagree:

1. Prefer the newer revision-noted decision text
2. Prefer decision docs over non-decision docs
3. Prefer security/netcode docs for trust/authority behavior
4. State the conflict explicitly and cite both locations

High-Cost Docs — Resolved

All previously identified high-cost files (>40KB) have been split into individually addressable sub-files. Each hub page retains overview content and a routing table to its sub-files.

Chapter-Level Splits

Decision Category Splits

Individual Decision Sub-Splits

Large individual decisions have been further split into sub-files:

Tracking & Planning Splits

Sub-File Splits Within Existing Directories

Retrieval pattern: Read the hub/index page (~500–2,000 tokens) to identify which sub-file to load, then load only that sub-file (~2k–12k tokens). Never load the full original content unless doing a cross-cutting audit.

Decision Capsule Standard (Pointer)

For better RAG summaries and lower retrieval cost, add a short Decision Capsule near the top of each decision (or decision file).

Template:

• src/decisions/DECISION-CAPSULE-TEMPLATE.md

Capsules should summarize:

• decision
• status
• canonical scope
• defaults / non-goals
• affected docs
• revision note summary

This gives agents a cheap “first-pass answer” before pulling the full decision body.

Practical Query Tips (for Agents and Humans)

• Include decision IDs when known (D068 selective install, D065 tutorial)
• Include doc role keywords (decision, player flow, roadmap) to improve ranking
• For behavior + UI questions, retrieve both:
  • decision doc chunk (normative)
  • 17-PLAYER-FLOW.md chunk (surface/example)

Examples:

• D068 cutscene variant packs AI Enhanced presentation fingerprint
• D065 controls walkthrough touch phone tablet semantic prompts
• D008 sub-tick timestamp normalization relay canonical order