Publishing the full analysis

This build is independent of darker-discovered. It renders the Markdown and stages the analysis files for a static webserver. It does not deploy anything.

Requires Node.js 22 or newer, Python 3 (standard library only), and rsync.

From the investigation root:

npm ci --prefix tools/publish
node tools/publish/build.mjs

The script prints elapsed times for each phase, page/link counts during processing, and any supplementary files it includes. Output uses ordinary lines so it remains readable in CI logs.

The default output is web-stage/:

index.html: entry page for the archive.
analysis/: the full analysis tree, including its generated viewer directory.
docs/index.html: searchable reports directory, grouped by subject.
docs/*.html: rendered reports with contents navigation and source links.
Original Markdown, exports and other assets remain available.
README.html: rendered project notes.
site-assets/: local styles and the optional index filter; reading needs no JavaScript.
build-manifest.json: page counts, link-check totals and supplementary files.

The build copies only explicitly linked supplementary source files outside analysis/ and docs/, such as a report's reference to a JavaScript helper. It does not copy the game installations or the separate C++ and public-site repositories. Everything already in analysis/ is included, including binary exports; this is the full investigation package.

Local Markdown links are rewritten to rendered HTML, except for explicit source downloads. Heading anchors follow GitHub's slug rules. Links in existing HTML are edited at their source locations so inline JavaScript and JSON are preserved. Linked folders without an index receive an evidence listing. All static local links and HTML fragments are checked before publication. Runtime-generated links and network services are not covered by that check. Existing viewers retain any external dependencies they already use.

A failed build leaves the previous stage intact. An existing output directory must be empty or carry this builder's .darker-web-stage marker. The builder refuses source directories and symlinks as output locations. It uses rsync with --link-dest to reuse unchanged files from the previous stage in a fresh temporary directory, without copying their contents again. Changed files are transferred normally. Generated HTML is rebuilt; rewritten files are detached from any hard links before writing. The previous stage is replaced only after validation succeeds, with the staging root set to mode 755. Files removed from the source therefore cannot linger in later builds. Source analysis pages and reports are not modified.

To use a different staging directory:

node tools/publish/build.mjs --output /path/to/staging

The result can be hosted at a domain root or beneath a path. Preview it with any static HTTP server. For example:

python3 -m http.server --directory web-stage 4181

Upload the contents of the directory, including the trailing slash:

rsync -av web-stage/ user@host:/var/www/darker/

Use the server and destination appropriate to your deployment. No remote credentials or host settings are embedded in the build.

Edit site.css for presentation, site.js for report filtering, and the group rules in build.mjs to organise reports. New Markdown files are discovered automatically. tools/build_analysis_index.py separately maintains the viewer catalogue and is called with a staging output path during this build.

The archive home page includes static Open Graph and large-image card metadata for https://lostengines.com/darker/. Its 1200 × 630 JPEG is published at https://lostengines.com/darker/site-assets/darker-social.jpg; that same image can be reused for the Darker entry on the main Lost Engines site.

darker-social.jpg is checked in, so the normal build needs no browser or image tools. The editable composition is social-card.html, with social-city.webp as its source screenshot of reconstructed Delphi. To revise the artwork, open that HTML in Chromium at a 1200 × 630 viewport and capture at device scale 1. The source screenshot is stored here so this publisher remains independent of darker-discovered. The original game geometry and colours are used as rendered by the city viewer.

Metadata follows the Open Graph protocol, including image format, dimensions and alternative text. Upload both the generated index and image before checking a shared link. A local build cannot verify Telegram’s live fetch or invalidate an existing cached preview.