project documentation
=====================

reading guide: start with DREAMBOOK.md for vision, then architecture-plan.txt
for the big picture, then object-model.rst for the core data model. everything
else builds on those three.

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
------

read architecture-plan first (big picture), then object-model (core hierarchy).
zones/things build on object-model. commands/terrain/persistence/prompt are
mostly standalone subsystems.

- ``docs/how/architecture-plan.txt`` — engine/content boundary, mode stack, entity model, game loop (start here)
- ``docs/how/object-model.rst`` — object hierarchy, containment, verbs, location system (core data model)
- ``docs/how/zones-and-building.rst`` — zones as spatial unit, procedural overworld, player homes (builds on object-model)
- ``docs/how/things-and-building.rst`` — interactive objects, python class decorators (builds on object-model)
- ``docs/how/commands.txt`` — command registration, async handlers, aliases, mode filtering
- ``docs/how/terrain-generation.txt`` — perlin noise, elevation thresholds, river tracing
- ``docs/how/persistence.txt`` — SQLite storage, what's persisted vs runtime
- ``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
-------------------

if-journey.rst is the master doc. everything else is supporting material
(audits, implementation details, performance work, design plans).

- ``docs/how/if-journey.rst`` — master IF doc: five integration levels, audit findings, milestones (start here)
- ``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/roadmap.rst`` — master plan: 12 phases from object model through DSL (start here)
- ``docs/plans/if-terminal.txt`` — level 1 IF architecture design (predates implementation)
- ``docs/plans/zmachine-game-compatibility.rst`` — game test plan for interpreter