Documentation Audit — March 19, 2026¶
Executive Summary¶
The EchoSpire documentation is in strong shape for game design and lore but has meaningful gaps in technical, deployment, and operational documentation. The canonical docs/official/ folder is well-organized and current. The GDD.md is comprehensive and consistent with code. Thirteen files in docs/olderreference/ are obsolete and should be archived. Publicly hosted docs are served via MkDocs Material + Docker/Render, but the hosting pipeline itself is underdocumented.
1. docs/ Folder — What's Accurate¶
docs/official/ (23+ files) — CURRENT ✅¶
The canonical documentation set. All major systems are documented and internally consistent. Most files carry March 2026 dates or match current code and architecture.
Key files and status:
| File | Status |
|---|---|
| index.md | ✅ Accurate master directory |
| next-steps.md | ✅ Actively maintained, current priorities |
| technical-architecture.md | ✅ Matches README and project layout |
| world-and-lore.md | ✅ Consistent with GDD |
| gameplay-reference.md | ✅ Matches runtime behavior |
| rules-glossary.md | ✅ Terms match code (Block, Exhaust, Retain, Breach, Drag, Density, Echo-Lock, Overload) |
| realm-framework.md | ✅ Authoritative for realm design |
| campaign-and-conflict-framework.md | ✅ Quest + faction storyline structure |
| production-roadmap.md | ✅ Honest about gaps |
| master-todo.md | ✅ Comprehensive backlog |
| quick-play-end-to-end-plan.md | ✅ Detailed casual-mode spec |
| pseudo-production-and-deployment.md | ✅ Deployment overview |
| hosted-early-dev-deployment.md | ✅ Cloudflare/Render/Neon/Upstash config |
| hosted-early-dev-runbook.md | ✅ Operator steps |
| wpf-mvp-kickoff.md / wpf-ux-flow-map.md | ✅ WPF MVP direction and screen flow |
| unity-client-kickoff.md | ✅ Post-proof upgrade path |
| effect-pipeline-and-modular-deployment.md | ✅ Effect system direction |
| ai-systems-and-agents.md | ✅ AI architecture separation |
| simulation-and-rival-hero-ai.md | ✅ Simulator + enemy AI |
| content-lifecycle-v2.md | ✅ Content authoring workflow |
| error-handling-design.md | ✅ Error patterns |
| document-governance.md | ✅ Doc maintenance rules |
docs/tech/ (2 files) — CURRENT ✅¶
| File | Status |
|---|---|
| Architecture.md | ✅ Current (March 5, 2026). Solution layout, layer separation, "Core is the game" philosophy. |
| DevelopmentStatus.md | ✅ Current (March 5, 2026). 410 tests passing, combat fully built, 5 class mechanics, 5 faction passives. |
docs/gpt54/ (7 files) — REFERENCE ONLY ⚠️¶
Clearly marked as prototype output from GPT-5.4. Not canonical. Index explicitly states these are "derived from current GDD" and not official unless promoted. No action required — labeling is already correct.
docs/copilot/ (4 files) — REFERENCE ONLY ⚠️¶
AI model assessments of opening-story narrative (Gemini, Claude Sonnet 4.6, Claude Opus 4.6, ChatGPT). Not authoritative source documentation. Useful for creative reference.
docs/GraphicNovel/ — EMPTY OR IMAGE-ONLY¶
Folder exists but appears to contain no markdown documentation.
docs/instructions/ — WORK-IN-PROGRESS¶
Contains a single output file (03-18-2026-13-45-results.md) and the current task file (3-19-2026). This is a scratch area for session work, not published documentation.
2. GDD.md Accuracy¶
Verdict: Accurate and comprehensive. The GDD is a ~3000-line game design bible covering:
- Story & Lore: Complete. The Fall of Aevum, 5 Great Houses with founder acts, modern motivations, twists, named faction leaders. "Cathedral Sci-Fi" visual direction.
- 5 Playable Classes: Complete. Anchor (Density), Drifter (Echo-Lock), Conduit (Overload), Machinist (Constructs), Catalyst (Mutations). Each has lore, playstyle, core mechanic, 2 hero abilities, 4-5 faction synergies.
- Rifts, Realms, Map: Complete. Deterministic seeds, Fog of War, Rift Jumping, Transit Interruptions.
- Game Loop & Progression: Complete. Faction Campaign (authored) → Infinite Spire (procedural). Death = "Failed Echo." Rift Run casual mode.
- Universal Mechanics: Complete. Block, Exhaust, Retain, Breach, Drag, plus all class/faction mechanics.
- 5 Faction Tutorials: Comprehensive 8-node tutorial realms with narrative, mechanics, and boss encounters.
Cross-checked against code: All 5 classes, 5 faction passives, Protection Rift encounters, and combat mechanics confirmed in test suites. No contradictions found between GDD and implementation.
Gaps in GDD (intentional — detail lives elsewhere):
- No specific card/relic/enemy rosters (those are in the database)
- No balance values or damage formulas (tuning data, not design doc)
- No hero leveling system (added post-GDD; covered in hero-progression-and-difficulty.md)
- No procedural generation algorithm specs (implementation detail)
3. Documents That Are Old and Should Be Eliminated or Archived¶
docs/olderreference/ — 13 files, ALL OBSOLETE¶
These are outputs from earlier LLM passes (Gemini 3.1, GPT-5.4, Opus 4.6, Claude Sonnet) that have been superseded by the official canon in docs/official/ and the GDD.
| File | What It Was | Why It's Obsolete |
|---|---|---|
| CardsGemini31.md | Card defs from Gemini 3.1 | Superseded by DB + Wave 1 import pipeline |
| CardsGpt54.md | Card defs from GPT-5.4 | Superseded |
| CardsOpus46.md | Card defs from Opus 4.6 | Superseded |
| AbilityDefinitionsGpt54.md | Ability specs | Superseded by effect pipeline docs |
| AbilityDefintionsGpt54Prompts.md | Prompts used | Historical only |
| SuggestionsGemini31.md | Design suggestions | No longer actionable |
| SuggestionsGPT54.md | Design suggestions | No longer actionable |
| SuggestionsOpus46.md | Design suggestions | No longer actionable |
| TutorialsGemini31.md | Tutorial specs | Superseded by FactionTutorials/ and GDD |
| TutorialsGpt54.md | Tutorial specs | Superseded |
| TutorialsOpus46.md | Tutorial specs | Superseded |
| prompts.md | Original prompts | Historical only |
| index.md | Directory | Points to all the above |
Recommendation: Move the entire docs/olderreference/ folder to docs/archive/ and remove it from the mkdocs.yml navigation. This reduces noise without deleting history.
FactionTutorials/ (root level, 5 files)¶
These duplicate tutorial content that also exists in the GDD. They may have been the original narrative design workspace. Consider consolidating: either keep them as standalone narrative docs and remove tutorial content from GDD, or fold them into GDD and remove the folder.
4. Where Are the Publicly Hosted Docs?¶
The documentation site is built and hosted via this pipeline:
| Layer | Config | Details |
|---|---|---|
| Source | docs/ folder (markdown) |
All content authored here |
| Build tool | MkDocs with Material theme | mkdocs.yml at repo root; Python deps in requirements-docs.txt (mkdocs 1.6.1, mkdocs-material 9.7.4) |
| Build output | site/ folder |
Static HTML/CSS/JS; ✅ currently built and committed |
| Docker | docker/docs.Dockerfile |
Containerized doc build |
| Deploy: nginx | deploy/docs/nginx.conf |
Serves the built site |
| Deploy: Render | render.yaml |
API + Admin deployed to Render.com (Oregon, free tier) |
| Deploy: Pseudo-prod | deploy/pseudoprod/ |
docker-compose + Caddy reverse proxy + bootstrap scripts |
Where to access: The render.yaml deploys echospire-api and echospire-admin to Render.com. The docs site has its own Dockerfile and nginx config but is not listed as a Render service — it may be served separately or not yet deployed publicly. Check whether the docs site is currently live on any host.
5. Wiki vs. Current Setup — Recommendation¶
Current Setup: MkDocs Material¶
Strengths: - Docs live in the repo alongside code — changes are versioned with git - Material theme gives search, navigation, responsive design out of the box - Markdown authoring is developer-friendly - Build is reproducible (Docker or local Python venv) - Official docs are well-organized with a governance doc
Weaknesses: - No collaborative editing (no WYSIWYG for non-developers) - No inline comments, discussions, or approval workflows - No automatic link-rot detection - site/ folder is committed — adds binary churn to git history
GitHub Wiki¶
Not recommended. GitHub wikis use a separate git repo under the hood, have no PR/review workflow, limited search, no Material-quality theme, and would fragment documentation away from the codebase.
Recommended Path: Keep MkDocs, Add These Improvements¶
- Stop committing
site/— Addsite/to.gitignoreand build on deploy instead. This eliminates binary churn. - Add docs to Render (or Cloudflare Pages) — Add a
docsservice torender.yamlusingdocker/docs.Dockerfile, or pushsite/to Cloudflare Pages. This makes docs publicly accessible with zero cost. - Add a
docs/archive/folder — Movedocs/olderreference/there and drop it from mkdocs.yml nav. - Add missing technical docs — The biggest gap is operational/engineering documentation:
- API endpoint reference (can be auto-generated from Swagger/OpenAPI)
- Database schema overview
- Local development troubleshooting guide
- Asset pipeline walkthrough
Action Items¶
| # | Action | Priority | Effort |
|---|---|---|---|
| 1 | Move docs/olderreference/ → docs/archive/, remove from mkdocs nav |
High | Low |
| 2 | Add site/ to .gitignore, remove committed build output |
High | Low |
| 3 | Deploy docs site publicly (Render service or Cloudflare Pages) | High | Medium |
| 4 | Clarify FactionTutorials/ — consolidate or keep with clear purpose note |
Medium | Low |
| 5 | Add API reference doc (auto-generate from OpenAPI/Swagger) | Medium | Medium |
| 6 | Add database schema overview doc | Medium | Medium |
| 7 | Add local dev troubleshooting guide | Low | Low |
| 8 | Add asset pipeline walkthrough doc | Low | Medium |
| 9 | Verify telemetry story: Kusto (local dev) vs. ClickHouse (production) and document | Medium | Low |
| 10 | Verify WPF client actual build/runtime status vs. doc claims | Medium | Low |