Read the selected guides in the project documentation library. See Project website for publishing and local development.
Setup and first boot live in the root README; its Quick start is the onboarding path. This directory holds the verified development, architecture, operations, database, and builder references.
docs/
reference/ how the server works persistence/ durability and data lifecycle
guides/ daily development operations/ running and operating it
content/ builders and world content gates/ release gates
records/ standing records adr/ decision records
diagrams/ architecture diagrams assets/ images
design/ feature designs and status examples/ versioned configuration samples
legacy/ inherited upstream text
lib/ runtime game data (not documentation)
reference/ - how the server works
| Document | Purpose |
|---|---|
| ARCHITECTURE.md | Process model, boot gate, game loop, typed persistence, recovery, and networking. |
| EXPERIENCE_TROPHIES.md | In-memory PvE XP observation, checkpoint persistence, and follow-up familiarity policy. |
| BATCH_ITEM_COMMANDS.md | Batch get, put, drop, wear, and remove syntax plus atomic item-transfer behavior. |
| CHAOS_MODE.md | Chaos configuration, durable new-character grants, equipment catalogs, and craft-pouch behavior. |
| CODEBASE.md | Module-by-module map of the server sources. |
| DATABASE.md | Database authority, typed reads/writes, schema, reconciliation, and migrations. |
| EVENTS.md | The nevent deferred-work scheduler: the timer wheel, scheduling, cancellation, the per-pulse budget, and catch-up. |
| api/health.md | The health endpoint contract. |
| api/durisweb.md | DurisWeb transport, challenge authentication, authorization, and privacy contract. |
persistence/ - durability, lifecycle, and privacy
| Document | Purpose |
|---|---|
| PLAYER_SAVE_PIPELINE.md | Revisioned checkpoint coordinator and completion boundary. |
| PLAYER_SAVE_JOURNAL.md | Journal permissions, bounds, replay, and diagnostics. |
| WORLD_RECOVERY_PIPELINE.md | Immutable world generations and exact acknowledgement. |
| CRITICAL_COMMAND_PIPELINE.md | Operation identity, transaction, journal, outbox, replay, and fences. |
| IMMUTABLE_MIGRATIONS.md | Honest baseline adoption and checksummed ordered migration history. |
| RUNTIME_COMPATIBILITY.md | Pre-write schema verification and atomic lookup publication. |
| DATA_LIFECYCLE.md | Complete store inventory and pending-policy boundary. |
| LIFECYCLE_ARCHIVE.md | Bounded archive state machine and disabled canonical scheduler. |
| PERSONAL_DATA_EXPORT.md | Authenticated package contract and pending activation. |
| ACCOUNT_ERASURE.md | Erasure/tombstone contract and restore-time no-resurrection gate. |
| EXCEPTIONAL_TARGET_WINS_MERGE.md | Protected account-parent collision dispositions and aggregate preflight verification. |
| LEGACY_ITEM_QUARANTINE.md | Protected classification, disposition, and recovery planning for ambiguous legacy items. |
| LEGACY_MEMBERSHIP_RECONCILIATION.md | Protected semantic classification, disposition, and clone rehearsal for normalized legacy association/guild state. |
design/ - feature designs and status
| Document | Purpose |
|---|---|
| COLLECTOR_OF_ANTIQUITIES.md | Collector lifecycle policy, authorities, runtime publication, and the disabled-by-default promotion evidence. |
guides/ - daily development
| Document | Purpose |
|---|---|
| BUILDING.md | Build entry points, compile flags, warning profile, sanitizers, and area generation. |
| TESTING.md | Focused, full, isolated-database, workload, fault, and privacy evidence boundaries. |
| CONVENTIONS.md | Repository conventions and their precedence against AGENTS.md. |
| formatting.md | Style, changed-line formatting, and editor setup. |
| MEMORY_CHECKING.md | Sanitizer and leak-checking workflow. |
| valgrind.md | Valgrind invocation, suppressions, and interpretation. |
| VERSIONING.md | Semantic versioning and the canonical version marker. |
| OUTPUT_WORD_STYLING.md | Completed-message rendering, authored-style protection, and output boundaries. |
| OUTPUT_PROFILES.md | Versioned channel profiles, recipe validation, recipient resolution, and snapshot lifetime. |
operations/ - running and operating it
| Document | Purpose |
|---|---|
| RUNBOOK.md | Safe startup, migration, backup, restore, recovery, reconciliation, and the release boundary. |
| PRODUCTION_DEPLOYMENT.md | Live production topology, service and helper locations, Cloudflare Tunnel, and TLS setup. |
| DOCKER.md | End-to-end local Compose deployment, persistent data, upgrades, and reset boundaries. |
| CONFIGURATION.md | Runtime variables, Redis, listeners, proxy handling, and diagnostics. |
| SECURITY_BASELINE.md | Generated dependency baseline and its validation. |
| incident-response.md | Incident handling procedure. |
content/ - builders and world content
| Document | Purpose |
|---|---|
| HELP_SYSTEM.md | Help sources, database import, and rendering. |
| HELP_STYLE_GUIDE.md | House style for help entries. |
| AREA_OBJECT_FORMAT.md | Area object file format and bitvector compatibility. |
| STUDIOPROC.md | Studio proc design and the reasoning behind it. |
| classes_and_races.txt | Class and race reference table. |
gates/ - release gates
Executable gates and required failure behavior. These are enforced by tests and cited by the runbook; they are contracts, not historical evidence.
| Document | Purpose |
|---|---|
| PHASE03_READINESS.md | Strict integrated capacity/fault gate and explicit deferred-run non-claim. |
| PHASE02_DOMAIN_GATE.md | Transactional domain gate for bounded, schema-versioned critical commands. |
| PHASE02_CRASH_MATRIX.md | Required crash and replay behavior for every critical gameplay domain. |
records/ - standing records
Kept when the .spec_system/ tracking tree was retired.
| Document | Purpose |
|---|---|
| CONSIDERATIONS.md | Institutional memory carried forward between phases. |
| SECURITY-COMPLIANCE.md | Cumulative security posture and GDPR compliance record. |
| readiness-report.md | Phase 03 final readiness result and the deferred capacity gate. |
Decisions and diagrams
- Architecture decision template
- Refactor investigations #343-#347: alternatives, chosen ownership boundaries, performance risks, dependencies, and migration/test gates.
- Server architecture diagram and database model
Legacy and runtime-data trees
legacy/is inherited upstream reference text (legacy/areas/,legacy/src/) and may be stale.lib/is not documentation.lib/information/is read by the server at runtime (src/cmd/wikihelp.c,src/account/nanny.c) and byscripts/import_help_to_prod.sh; moving it breaks the running game.