Update docs: add reading guide to index, refresh stale references

docs/how/architecture-plan.txt

@@ -193,7 +193,9 @@ a definition came from.
 the entity model
 ================
 
-current: Player is a dataclass. no mobs, no items, no NPCs yet.
+current: Entity base class with Player and Mob subclasses. see
+object-model.rst for the concrete class hierarchy (Object → Zone, Entity,
+Thing) and the location-based containment system.
 
 the ecosystem shows two paths:
   - deep inheritance (evennia: Object > Character > NPC, most traditional MUDs)
@@ -375,3 +377,4 @@ this document       docs/how/architecture-plan.txt
 dreambook           DREAMBOOK.md
 ecosystem research  docs/how/mud-ecosystem.txt
 landscape research  docs/how/mudlib-landscape.txt
+object model        docs/how/object-model.rst

docs/how/persistence.txt

@@ -7,7 +7,7 @@ WHAT'S PERSISTED
 Player accounts:
 - Username (case-insensitive)
 - Password (hashed with PBKDF2-HMAC-SHA256 and random salt)
-- Position (x, y coordinates)
+- Position (zone, x, y — see object-model.rst for location system)
 - Combat stats (pl, stamina, max_stamina)
 - Flying status
 - Created timestamp
@@ -53,6 +53,21 @@ WHEN SAVES HAPPEN
 The periodic auto-save runs in the game loop alongside combat and effects
 processing. It only triggers if at least one player is connected.
 
+WHAT'S NOT YET PERSISTED
+
+The object model (object-model.rst) introduces containment, inventory, and
+zones. Persistence for these is an open question:
+
+- Player inventory (Things with location=player)
+- Item instances on the ground (Things with location=zone)
+- Container state (open/closed/locked, contents)
+- Zone edits from paint mode (tile changes)
+- Mob respawn state
+
+These will be addressed as each system gets implemented. Player inventory
+will likely go in SQLite alongside account data. Zone edits will persist to
+TOML files. Mob instances probably don't persist (respawn from templates).
+
 IMPLEMENTATION NOTES
 
 Password hashing:

docs/index.rst

@@ -1,7 +1,9 @@
 project documentation
 =====================
 
-all project docs, grouped by topic.
+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
 ------
@@ -13,13 +15,17 @@ vision
 engine
 ------
 
-- ``docs/how/architecture-plan.txt`` — engine/content boundary, mode stack, entity model, game loop
+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/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/persistence.txt`` — SQLite storage, what's persisted vs runtime
-- ``docs/how/zones-and-building.rst`` — zones as spatial unit, procedural overworld, player homes
-- ``docs/how/object-model.rst`` — object hierarchy, containment, verbs, location system
 - ``docs/how/prompt-system.txt`` — modal prompts, color markup, per-player customization
 
 combat
@@ -30,7 +36,10 @@ combat
 interactive fiction
 -------------------
 
-- ``docs/how/if-journey.rst`` — master IF doc: five integration levels, audit findings, milestones
+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