Research and publication layout

analysis/ is the presentation copy: finished findings, interactive browsers, decoded resources used by those browsers, music auditions and article figures. It is deliberately selected rather than being the output directory for every experiment.

work/research/ is the local working tree. Generators and original-code probes write here. It contains replay streams, memory dumps, mission cases and fixtures, private DOSBox installations, disassembly projects, build products and capture logs, as well as the source outputs for the presentation copy. Keep this tree local. It is excluded by the root .gitignore.

docs/ contains the written findings and research record. tools/ contains the reproducible extraction, comparison and publishing tools. Original media, comparison installations and extracted game resources remain in install media/, installs/ and extracted/ respectively.

Publishing completed work

Run the relevant generator or check, inspect its output in work/research, then:

python3 tools/publish_analysis.py --dry-run
python3 tools/publish_analysis.py
python3 tools/publish_analysis.py --check

The explicit selection is in tools/analysis_publication.json. When a new result is ready to present, add its browser, figures or report there. Do not add whole capture directories: they often contain copied game installations or large binary snapshots alongside useful illustrations. The publisher follows local HTML links to supporting reports; dynamically loaded resources have explicit allowlist entries. Replay contact sheets and shell screenshots are selected from their catalogues.

The published copy has independent files and a SHA-256 inventory in analysis/publication-manifest.json. Subsequent publications update changed files and remove previously published files that leave the selection. The publisher refuses to overwrite hand-edited published files or an unmanaged output tree. Make intended changes in the generating tool and its working output before republishing. Changes to docs/ are made directly.

To browse with documentation links working, serve the project root and visit http://127.0.0.1:8766/analysis/:

python3 -m http.server 8766 --bind 127.0.0.1

The browser pages also support opening directly from disk. Research browser checks write their own screenshots and results into work/research, even when checking the published pages over HTTP.

Existing evidence

On 6 November 2026 the complete former analysis/ tree was moved to work/research/. No capture, fixture or original input was discarded. Its 65,679 files occupied 8.55 GiB of content. File sizes, inodes and modification times were checked before and after the directory move. The relocation inventory and copies of source files changed during the reorganization are retained locally in work/reorganization-2026-11-06/.

Historical paths embedded in captures and provenance records still describe where those files were created. For a historical analysis/... raw-evidence path, use work/research/... now. The relative layout below that root is unchanged. Tools, current documentation links and the C++ fixture importers use the new working paths. Public article import scripts also read the working outputs, so publishing a browser selection cannot remove their research inputs.

The C++ repository keeps its own committed regression fixtures. Regenerating those fixtures uses ../earthsiege-reverse/work/research; building or testing the C++ game does not require this local working tree.

This separation reduces what is presented in analysis/; it does not reclaim the retained research storage. The curated copy occupies additional space so new experiments cannot modify an already inspected publication through shared hard links.

Remote web archive

The separate publish.sh script turns the curated copy and named reports into web-stage/, with Markdown rendered as HTML and links checked. Use ./publish.sh --build-only for local inspection, ./publish.sh --dry-run for an rsync preview, and ./publish.sh to upload to the configured Earthsiege directory on lostengines.com. It never stages work/research/ or install media. See the publisher guide.