From 94a01186c882572b905aecd9efa06fc7b92199c9 Mon Sep 17 00:00:00 2001
From: Jared Miller <jared@smell.flowers>
Date: Wed, 11 Feb 2026 09:39:48 -0500
Subject: [PATCH] Add a doc index

---
 docs/index.rst | 64 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 64 insertions(+)
 create mode 100644 docs/index.rst

diff --git a/docs/index.rst b/docs/index.rst
new file mode 100644
index 0000000..2acda63
--- /dev/null
+++ b/docs/index.rst
@@ -0,0 +1,64 @@
+project documentation
+=====================
+
+all project docs, grouped by topic.
+
+vision
+------
+
+- ``DREAMBOOK.md`` — vision, philosophy, wild ideas
+- ``docs/why/telnet-first.txt`` — why telnet as the protocol
+- ``docs/why/text-worlds.txt`` — why text worlds matter
+
+engine
+------
+
+- ``docs/how/architecture-plan.txt`` — engine/content boundary, mode stack, entity model, game loop
+- ``docs/how/commands.txt`` — command registration, async handlers, aliases, mode filtering
+- ``docs/how/persistence.txt`` — SQLite storage, what's persisted vs runtime
+- ``docs/how/terrain-generation.txt`` — perlin noise, elevation thresholds, river tracing
+- ``docs/how/things-and-building.rst`` — interactive objects, python class decorators
+- ``docs/how/zones-and-building.rst`` — zones as spatial unit, procedural overworld, player homes
+- ``docs/how/prompt-system.txt`` — modal prompts, color markup, per-player customization
+
+combat
+------
+
+- ``docs/how/combat.rst`` — state machine, TOML-defined moves, timing windows
+
+interactive fiction
+-------------------
+
+- ``docs/how/if-journey.rst`` — master IF doc: five integration levels, audit findings, milestones
+- ``docs/how/if-terminal.txt`` — level 1: dfrotz subprocess, spectator broadcasting
+- ``docs/how/if-integration.txt`` — original IF research (predates audits)
+- ``docs/how/viola-embedding-audit.rst`` — viola interpreter audit
+- ``docs/how/zvm-embedding-audit.rst`` — zvm interpreter audit
+- ``docs/how/mojozork-audit.rst`` — MojoZork multiplayer C implementation audit
+- ``docs/how/zmachine-performance.rst`` — profiling, optimization (cold-start 4720ms to 786ms)
+- ``docs/how/multiplayer-zmachine-design.rst`` — level 4 multiplayer design
+- ``docs/plans/zmachine-game-compatibility.rst`` — game test plan for interpreter
+
+research
+--------
+
+- ``docs/how/mudlib-landscape.txt`` — survey of MUD architectures (Diku, MOO, LPC, evennia)
+- ``docs/how/mud-ecosystem.txt`` — catalog of engines, clients, protocols
+- ``docs/how/dsls.md`` — scripting language catalog (MOO, LPC, MUSH) with examples
+- ``docs/research/dbzfe_notes.rst`` — DBZFE MUD reference notes
+- ``docs/research/dbzfe.log`` — sample MUD output
+- ``docs/research/dbzfe.tin`` — TinTin++ config
+
+lessons
+-------
+
+- ``docs/lessons/charset-vs-mtts.txt`` — telnet CHARSET negotiation hang, MTTS workaround
+- ``docs/lessons/dfrotz-prompt-detection.txt`` — dfrotz prompt format varies, detection logic
+- ``docs/how/utf8-design-lesson.rst`` — ASCII bias in UTF-8, international MUD implications
+- ``docs/how/zmachine-garbled-output-investigation.rst`` — string decoding corruption debug trace
+
+plans
+-----
+
+- ``docs/plans/if-terminal.txt`` — level 1 IF architecture design (predates implementation)
+- ``docs/plans/zmachine-game-compatibility.rst`` — game test plan for interpreter