Firestaff documentation

This is the documentation map for the Firestaff project. It covers all five supported games, the shared launcher and engine layers, data setup, CI, source-lock evidence and release packaging.

Current project boundary

The public status is intentionally conservative. A parser, fixture or source-lock test proves a narrow contract; it does not by itself prove original-media playability or pixel parity.

Across every game, work is ordered as startup → menu → HUD → viewport. Later presentation claims remain blocked when an earlier source or real-data handoff is not proven.

Documentation roles

Use the following hierarchy when documentation appears to disagree:

1. Current public status: this index, project status, platform status, and the corresponding checked-in wiki pages are the current support contract.
2. Technical reference: format, reverse-engineering and source-lock pages record the evidence, implementation details and known boundaries behind a current claim.
3. Planning and historical records: dated audits, reports, release notes and files under docs/plans/ preserve decisions at the time they were written. They are not current status unless a current-status page links to the specific conclusion.

Current public-status pages must describe only source-owned or real-media-backed behaviour. They must not contain local machine paths, private captures, disassemblies, BIOS/firmware, game archives, saves, or other copyrighted source material. A README screenshot may show Firestaff itself, but is never evidence for an original game’s output. Historical records are being retained as dated research and must not be copied into current status or wiki pages.

Per-game technical notes are grouped under docs/dm1/, docs/csb/, docs/dm2/, docs/nexus/ and docs/theron/. Shared engine, menu and gameplay notes are under docs/shared/; cross-game status and project guides remain at the top of docs/.

Start here

• README — user-facing overview, supported platforms and quick start
• Project status — short cross-game status matrix
• Five-game startup support gap analysis — authenticated CLI coverage and unresolved launcher/runtime gaps
• Platform status — current status for every game and platform
• Active top-10 native-parity queue — current evidence-backed priorities and explicit data blockers
• Game data setup — legal data intake and scanner behavior
• Runtime-media ownership — original container ownership, bounded-memory reads and the no-extraction rule
• Game-data formats — verified containers, record families and save boundaries
• CI guide — GitHub Actions checks and local reproduction
• Verified hashes — canonical data identities
• Historical technical gap analysis — preserved research; use project/platform status and per-game TODO files for active work
• Missing functions by game — code, data and verification gaps
• Synthetic data by game — fixtures, placeholders and real-data replacements
• Preservation and provenance — evidence levels, capture manifests and external data rules
• Preservation status (reviewed 2026-08-12) — cross-game real-media, format and disassembly boundary
• External preservation archive — moved historical runs and checksum manifest
• Archived project history — older mixed completion log
• Legacy DM1 tracking list — superseded by the current per-game TODO and DONE logs
• Latest versioned release summary — older summaries are grouped in the same directory; see the current changelog
• DMWeb and Greatstone references — external provenance index
• Theron input controls — native keyboard mappings, visible in-dungeon mouse movement panel, and Button I/II behavior
• Theron real-data inventory — Track 02/19 media identities and placeholder boundaries
• Theron capture readiness — current authenticated --debug and emulator evidence, capture requirements, and open runtime joins

Per-game technical notes

Focused implementation, format and parity notes are grouped by game. These pages provide starting points; current support claims remain in the status documents above and in the per-game TODO/DONE logs.

Active per-game work logs

These files record implementation evidence and the remaining gaps for each game. Read them with the status matrix above: a completed focused check closes only the behavior and edition it names.

• Dungeon Master TODO and DONE log
• Chaos Strikes Back TODO and DONE log
• Dungeon Master II TODO and DONE log
• Nexus TODO and DONE log
• Theron’s Quest TODO and DONE log

Wiki map

The checked-in pages under docs/wiki/ are the source for the GitHub wiki and are copied by scripts/sync_wiki.sh during release work.

CSB Atari ST provenance

• CSB Atari Mania reference — local Atarimania print-PDF provenance, stated product facts and strict evidence boundary.

Per-game pages

• DM1: technical reference, PC34 internals, reverse engineering, FM Towns guide
• CSB: technical reference, DSA and saves, FM Towns guide, reverse engineering
• DM2: technical reference, GDAT internals, reverse engineering, platform status
• Nexus: technical reference, DGN/PRS3, SAL/MAP, reverse engineering
• Theron: technical reference, Track 02 internals, reverse engineering, input notes, capture readiness

Shared pages

• Wiki home
• Reverse-engineering index
• Game data
• Game-data formats
• Architecture
• Building and installing
• Parity evidence
• Platform guides
• Release process

Evidence vocabulary

• Source-locked: behavior is anchored to a reference source or disassembly and guarded by a focused test.
• Real-data verified: the tested asset is identified by its canonical hash and the relevant parser/loader contract passes.
• Runtime proven: the real-data path reaches the claimed runtime milestone.
• Playable: the public route has end-to-end original-data runtime proof. At present this label is reserved for the DM1 PC 3.4 V1 route.
• Fixture-only: useful for a narrow parser or state-machine contract, but not evidence for original-media rendering.

Rebuilding the documentation

Documentation changes are ordinary repository changes. Before publishing a release, run the focused tests for the affected game, check Markdown links and run the build/CI commands in CI.md. Do not commit original game data, emulator saves, private capture logs or generated placeholder art.

Last reviewed: 2026-10-27 (main 88ef19df). The current status reflects the source and authenticated-media evidence recorded on the linked status and per-game work-log pages. Each receipt remains bounded to its cited edition, route and test; it does not imply complete parity.