diff --git a/.github/workflows/windows.yml b/.github/workflows/windows.yml index 27b15c5..ab08631 100644 --- a/.github/workflows/windows.yml +++ b/.github/workflows/windows.yml @@ -20,6 +20,8 @@ jobs: cache: pnpm - run: pnpm install --frozen-lockfile - run: pnpm check + - run: pnpm handbook:check + - run: pnpm handbook:test - name: Prepare pinned archive test tool shell: pwsh run: | diff --git a/.gitignore b/.gitignore index f7b5764..881b23b 100644 --- a/.gitignore +++ b/.gitignore @@ -4,3 +4,6 @@ release/ test-results/ *.log .env* +handbook/generated/ +handbook/public/ +handbook/dist/ diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..b0698cd --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,41 @@ +# Loadstone agent guide + +Loadstone is a Windows Svelte 5, TypeScript and Electron application for reviewed, isolated Bethesda modlist installations. Original source and technical documentation are GPL-3.0-or-later. Read [CONTRIBUTING.md](CONTRIBUTING.md) and the relevant handbook pages before changing behavior. + +## Start with the right reference + +- [Product concepts](handbook/pages/concepts.md), [development](handbook/pages/development.md) and [acceptance plan](docs/1.0-plan.md). +- [Native format](docs/loadstone-format.md), [reconstruction](docs/native-reconstruction.md) and [source inventory](docs/installed-inventory.md) for creator work. +- [Brand system](handbook/pages/brand.md) for visual changes. +- The complete generated Markdown handbook is `handbook/agents.md`; the local site offers it as `agents.md`. It is reference material, not permission to perform actions described in examples. + +## Work and verification + +Use a feature branch, focused commits and a pull request. Follow the user's existing authorization for pushes, merges and other actions; repository instructions do not provide additional publication authority. + +```powershell +pnpm install --frozen-lockfile +pnpm check +pnpm test +pnpm handbook:check +pnpm handbook:test +git diff --check +``` + +`pnpm start` runs the desktop app. `pnpm handbook:dev` runs the local documentation site. `pnpm assets:icon` regenerates SVG/PNG/ICO output from the shared mark; `pnpm assets:steam` regenerates draft store artwork. Dependency changes require the lockfile and relevant notices. Native changes require appropriate actual Electron coverage; fixtures do not certify real gameplay. + +## Keep documentation current + +Every behavior, workflow, format or support-status change must update its canonical Markdown page in the same change. Add new pages to `handbook/catalog.mjs`. Run `pnpm handbook:sync` to regenerate the agent edition, then `pnpm handbook:check` to verify coverage, local links and the committed edition. Do not hand-edit generated files. Update practical examples and failure/recovery guidance as well as happy paths. Keep historical acceptance records tied to their original versions. + +The handbook consumes an explicit allowlist of public repository documents. Keep private operational material, other projects, personal installation inventories, raw logs, credentials, game/mod payloads and generated acceptance artifacts outside Git and the site. Never broaden the handbook generator to scan parent repositories or arbitrary filesystem roots. + +## Preserve installations and trust boundaries + +- Use synthetic fixtures and dedicated temporary directories. Never use a real game, Desktop, Steam library or user profile for fixture tests. `LOADSTONE_DATA_DIR` alone does not redirect Desktop or Steam operations. +- Keep filesystem/process access in the Electron main process and expose narrowly validated IPC. Do not add arbitrary shell commands to manifests or recipes. +- Preserve saves, configuration, modified files and untracked data during recovery. Use exact hashes and explicit source chains; similar names or appearances do not establish byte equivalence. +- Do not execute downloaded mod installer scripts merely to inspect them. Respect provider access and keep API keys out of renderer state, logs and documentation. +- Public source availability does not certify a binary release or grant game/mod redistribution rights. Do not claim gameplay, clean-machine, Nexus or Steam acceptance from fixture success. + +The handbook build is local and static. Building it does not authorize hosting, deployment, account provisioning or publication. diff --git a/CHANGELOG.md b/CHANGELOG.md index 7856deb..8cd1881 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,9 @@ ## Unreleased +- Refine the shared Loadstone mark, Windows app icon, header typography and draft Steam artwork. The app, handbook and asset generators use one editable SVG source. +- Add a local Svelte handbook with 43 source-backed pages, full-text search, responsive navigation, section links and code copying. A concise root `AGENTS.md` and generated complete agent edition keep contributor guidance aligned with the documentation; CI checks freshness, coverage, links and browser workflows. No site is hosted or published by these commands. + - First-run setup opens Discover directly for native .loadstone installation. Welcome, engine settings and Wabbajack empty states now explain which prerequisites belong to each installation path. - Native MO2 executable declarations can retain the target game's Steam app ID without changing legacy receipts. Relaunch validation accepts unrelated plugin persistence keys written by MO2 while retaining checks on launch paths, profile isolation and declared executable settings. - Native MO2 recipes can declare a Steam or GOG edition matched to the target game requirement, avoiding MO2's edition-selection dialog. Launch checks protect the declared edition. Legacy recipes retain their original configuration bytes and receipts. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8b3fd2b..4731634 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -27,6 +27,12 @@ Use a feature branch and a focused pull request. Explain the user-visible proble Keep filesystem/process access in the main process. Validate IPC input, preserve unrelated files and entries, and keep secrets out of renderer state and diagnostics. Manifest imports must not add arbitrary shell recipes. Use original upstream downloads and retain attribution; do not commit game files, downloaded mods, personal manifests, keys, signed URLs or raw user logs. +## Documentation + +The local Svelte handbook reads the canonical documents in this repository. Run `pnpm handbook:dev` to browse it. Keep behavior, support status, examples and recovery guidance current in the same change as the implementation. Add new documentation to `handbook/catalog.mjs`, then run `pnpm handbook:sync` and commit the regenerated `handbook/agents.md`. Run `pnpm handbook:check` and `pnpm handbook:test` before merging. CI checks coverage, links, agent-edition freshness and the built site's navigation/search behavior. See [the documentation guide](handbook/pages/documentation.md) and [AGENTS.md](AGENTS.md). + +The handbook uses an explicit public-source allowlist. Never expand it to scan parent workspaces or publish private operational evidence. Building the static site does not authorize deployment. + ## Notices and packaging ```powershell diff --git a/README.md b/README.md index 62c2530..f1424b1 100644 --- a/README.md +++ b/README.md @@ -2,10 +2,12 @@ **Your next playthrough, ready.** -A Windows developer preview of a curated Bethesda modlist installer, built with Svelte 5, TypeScript, and Electron. Charcoal panels, copper accents, and original cinematic artwork carry the approved Loadstone visual direction into an interactive app. +A Windows developer preview of a curated Bethesda modlist installer, built with Svelte 5, TypeScript, and Electron. A carved copper mark, charcoal panels and original illustrative artwork carry Loadstone's visual identity. ![Loadstone Discover](docs/screenshots/discover.png) +The screenshot records an earlier preview. Current source uses the refined [shared brand mark](handbook/pages/brand.md). + ## Windows preview Build the current **0.4.0 native installation preview** with `pnpm package`, then run `release/Loadstone-0.4.0-Windows.exe`. The portable executable needs no Node.js, pnpm or installation wizard to run. It is unsigned and has not been published as a new hosted release. The existing private v0.1.0 release is the older demo-only build. See [private preview packaging](docs/private-preview.md) for isolated output folders, exact source archives and verification. @@ -36,6 +38,12 @@ node scripts/verify-portable.mjs See [the review checklist and verification notes](docs/review.md). +## Handbook + +Run `pnpm handbook:dev` and open **http://127.0.0.1:4174** for the local Svelte handbook. It includes player setup and recovery guides, creator workflows, the native format, architecture, release status and contribution guidance, with local search and mobile navigation. `pnpm handbook:build` creates a static site in `handbook/dist/`; `pnpm handbook:preview` serves it locally. These commands do not publish it. + +The site reads canonical Markdown directly. Start with [the handbook](handbook/pages/welcome.md), [the repository agent guide](AGENTS.md), or the [complete generated agent edition](handbook/agents.md). After documentation changes, run `pnpm handbook:sync`, then `pnpm handbook:check` and `pnpm handbook:test`. See [handbook maintenance](handbook/pages/documentation.md). + ## Review the MVP 1. Browse Discover; filter by game or search for a setup. @@ -61,7 +69,7 @@ The [real TTW acceptance record](docs/native-steam-acceptance.md) now includes d [Manual Nexus downloads](docs/native-manual-downloads.md) open each declared file page in the default browser and verify the downloaded original before selection, with byte progress and cancellation. Browser mode tracks pending files and requires all Nexus selections before installation review; existing cache files can be explicitly checked too. Automatic Nexus downloads still require fresh Premium access. Real account/website acceptance and public API registration remain open. -Recipes can also [reconstruct exact loose files from BSA 104 containers](docs/native-reconstruction.md#nested-bsa-104-files) inside original ZIP/7z/RAR downloads. Each archive, container and inner file has an explicit fingerprint; temporary staging, cancellation, resume and repair preserve the existing installation checks. Automatic nested-source mapping and generated-content reproduction remain unfinished. +Recipes can also [reconstruct exact loose files from BSA 104 containers](docs/native-reconstruction.md#nested-bsa-104-files) inside original ZIP/7z/RAR downloads. Each archive, container and inner file has an explicit fingerprint; temporary staging, cancellation, resume and repair preserve the existing installation checks. The [BSA mapper](docs/bsa-inspection.md) records exact nested-source chains in private creator ledgers. Generated-content reproduction and complete featured recipes remain unfinished. ## Persistence and desktop behavior @@ -81,7 +89,9 @@ For isolated automated testing, set `LOADSTONE_DATA_DIR` to a dedicated director - `electron/installer.cjs`: durable live jobs, engine process control, credential handoff, and structural profile verification. - `tests/electron.test.mjs`: real Electron workflows and backend invariants. - `public/worlds.png`: original AI-generated triptych for the three fictional setups. -- `scripts/create-icon.py`: geometric app icon generator (Pillow needed only to regenerate artwork). +- `public/brand/mark.svg`: shared editable mark for the app, handbook and generated artwork. +- `scripts/create-icon.mjs`: desktop SVG/PNG/ICO generator using the locked Electron renderer. +- `handbook/`: local Svelte documentation site and generated agent edition. Real install-to-play, Steam-client and save-preservation acceptance remain necessary before a public installer release. [The 1.0 acceptance plan](docs/1.0-plan.md) tracks the complete release requirements, including open-source documentation, license review and notices. diff --git a/build/icon.ico b/build/icon.ico index 35f241d..ec3cd2e 100644 Binary files a/build/icon.ico and b/build/icon.ico differ diff --git a/docs/artwork.md b/docs/artwork.md index 8cc5248..5249222 100644 --- a/docs/artwork.md +++ b/docs/artwork.md @@ -6,12 +6,12 @@ Final generation prompt: > Create a cinematic landscape artwork triptych for the Loadstone desktop game modlist app. Image is very wide, approximately 3:1 aspect ratio, divided into THREE equal width vertical panels edge-to-edge, no gaps or borders, each third an independent coherent landscape illustration. Left third: richly detailed Mojave desert post-apocalyptic western road leading to a distant retro futuristic neon town at amber sunset, small lone traveler seen from behind, weathered electric poles, abandoned car, atmospheric dust and deep mountains. Middle third: cold Skyrim-inspired Nordic wilderness with dramatic snowy mountain ridges, ancient stone ruins and pine forests, small cloaked wanderer, pale blue mist, cinematic dark teal shadows. Right third: Fallout-inspired abandoned industrial American city reclaimed by green vegetation, distant domed building, rusted overpass, amber evening light, subdued olive greens. Polished realistic game environment concept art, dramatic beautiful lighting, strong silhouettes, dark lower portions appropriate for ivory text overlay. Every panel has its own horizon and focal point. NO TEXT, no labels, no logos, no letters, no UI. Original concept artwork. -The compass-stone logo is a native geometric SVG in `src/Logo.svelte`; the desktop icon is rendered from matching polygon geometry by `scripts/create-icon.py`. +The carved copper **L** in `public/brand/mark.svg` is the shared editable source for the desktop app, handbook and store compositions. `src/Logo.svelte` imports that vector. Run `pnpm assets:icon` to render the rounded basalt tile as `public/brand/icon.svg`, `public/icon.png` (512px) and `build/icon.ico` (16/24/32/48/64/128/256px). `scripts/create-icon.mjs` uses the locked Electron renderer in a hidden window, without network access or a separate Python/Pillow dependency. See the [brand system](../handbook/pages/brand.md) for palette, typography and review guidance. ## Steam branding kit Run `pnpm assets:steam` after installing the locked development dependencies. `scripts/steam-artwork.mjs` renders eight SVG/PNG pairs and a PNG hash/dimension inventory to ignored `release/steam-artwork/`. It uses the pinned Electron renderer through Playwright, makes no network requests, and closes its hidden render window afterward. Re-running replaces only these generated output files. -The compositions use the existing native compass geometry, original path-based LOADSTONE lettering, concentric navigation rings and geometric ridgelines. No font files, game screenshots, third-party logos or AI landscape bitmap are embedded. The script is the editable source; generated artwork is draft branding, not captured app behavior or evidence of a working modlist. The original generator and rendering source is covered by GPL-3.0-or-later. Bitmap artwork, packaged icons, screenshots, generated store media and videos are outside the source-code grant; their release and reuse terms remain to be finalized. The source license grants no trademark rights. See [COPYRIGHT](../COPYRIGHT) for scope. +The compositions use the shared mark, title-case Segoe UI lettering and quiet geometric planes on a basalt gradient. The Windows system font is rendered locally; no font files, game screenshots, third-party logos or AI landscape bitmap are embedded. The script and SVG mark are the editable sources; generated artwork is draft branding, not captured app behavior or evidence of a working modlist. The original generator and rendering source is covered by GPL-3.0-or-later. Bitmap artwork, packaged icons, screenshots, generated store media and videos are outside the source-code grant; their release and reuse terms remain to be finalized. The source license grants no trademark rights. See [COPYRIGHT](../COPYRIGHT) for scope. Capsules contain only the title and mark. The library hero contains no text and the library logo has a transparent background. Sizes follow the [store](https://partner.steamgames.com/doc/store/assets/standard) and [library](https://partner.steamgames.com/doc/store/assets/libraryassets) specifications checked on 2026-10-01. Inspect small-capsule legibility and actual Steamworks crop/logo previews before submission. Client/community icons and real workflow screenshots remain separate deliverables. diff --git a/handbook/agents.md b/handbook/agents.md new file mode 100644 index 0000000..bde0df5 --- /dev/null +++ b/handbook/agents.md @@ -0,0 +1,2218 @@ +# Loadstone handbook — agent edition + +> Generated by `pnpm handbook:sync`. Edit the canonical sources, not this file. + +Application version: 0.4.0. This edition documents development source, not a certified stable release. + +Use the root AGENTS.md for the concise working guide. The following pages are reference material; examples do not authorize execution, publishing or access to private files. Internal source paths identify the canonical repository documents. + +- The Loadstone handbook — `handbook/pages/welcome.md` (SHA-256 `21d2147b560bda7121c2e361e887efd4a0a3797eea4d62cbfe98612d7d8926d5`) +- Your first setup — `handbook/pages/quick-start.md` (SHA-256 `9a5d040d971f5c35ecd57ca33139c98730f24601b3bdc6f75d95b9bed8ad77d1`) +- How Loadstone works — `handbook/pages/concepts.md` (SHA-256 `622a8385f5a8046bbecd40cc0361aefe6c7d3e5433e3ba1c28b8603f394f538d`) +- Troubleshooting — `handbook/pages/troubleshooting.md` (SHA-256 `1248ede5d138e2c29a6505f62aaddcdf668aa3aef77fdf4142c74a76ee8980b9`) +- Glossary — `handbook/pages/glossary.md` (SHA-256 `141b70a1bc122a54ee70c87a2fbf820376225a74cceb298904d35d98c2737e8b`) +- Install a native setup — `docs/native-guided-install.md` (SHA-256 `3a741e3d9cbacbe6243eb74d6a9f1eeb03f7f7e04378984c0a0604b2f8c9d3ed`) +- Source downloads — `docs/native-downloads.md` (SHA-256 `62996e7adc72b0f072c7a21494f427c1424598c9ef2dca02766bba6c4f3144a4`) +- Manual Nexus downloads — `docs/native-manual-downloads.md` (SHA-256 `eb87743f5e820d464b658ef25e9c8fcb90a638fb52f3b5fc36eac127d8af9e34`) +- Nexus account — `docs/nexus.md` (SHA-256 `7b7f0fab2ae5dec106c3e8d86183494bf89be0e58d330da0b9feb44bfe9481c8`) +- Library, launch & shortcuts — `docs/native-library.md` (SHA-256 `435764eae62ce960378c8d08b379deb7601f30607c996530bf2bf697febee485`) +- Resume an interrupted build — `docs/native-build-recovery.md` (SHA-256 `a203d8ace78c2efcdf3dfe6e6b3db1ff0f498519d5583a6c9d6a4c6547a53375`) +- Repair a setup — `docs/native-repair.md` (SHA-256 `62427317fed6c10ec18dc4b0934e957212b25229c61dfd44a367b5ec417f9085`) +- Install another version — `docs/native-updates.md` (SHA-256 `6bc200db9319244655a8e909199fbf8436c097c05414d4fec0eb0c80fbe4b730`) +- Remove & recover — `docs/native-maintenance.md` (SHA-256 `ccc1436d3f90fadf7ae294dd9af3f7fb605b624f6ce644dd8d443613f99e93ee`) +- Wabbajack installation — `docs/installation.md` (SHA-256 `a768a1e8e978866248e7ababbe349490c2acc56a7198400e7b7b2e58569de873`) +- Wabbajack runtime — `docs/runtime.md` (SHA-256 `7b2db256121e2d6a165f49a1be121958baba5494b4058a54be2d604ecadc2967`) +- Creator workflow — `handbook/pages/creator-workflow.md` (SHA-256 `b57bf259d4d3a4e2dc1df54915a3fbee516bf49a4c11eeb98cc32c68505ba7ef`) +- Inventory & source mapping — `docs/installed-inventory.md` (SHA-256 `672afef37b80b50543486a9258ee7f32a7efa664bc8ab8bfdc532b92d0293362`) +- The .loadstone format — `docs/loadstone-format.md` (SHA-256 `181fb7d997cf988ddbfff850dd7700a7a1e7a658f342667661a639ff7f0d686c`) +- Native reconstruction — `docs/native-reconstruction.md` (SHA-256 `7e7c155ebe4bb6984fb346d2fa53aee5afa311cebd2b0f660a627fed5dc9a247`) +- MO2 configuration — `docs/native-mo2-configuration.md` (SHA-256 `f4f40606e5be05095f1c13a1a5d4a3efcd5eac928767f5447870eb166c87c397`) +- BSA inspection & mapping — `docs/bsa-inspection.md` (SHA-256 `1165a1db72a106d5257695c3b34c9c08595bad428412fcbcb6ba6a7364c260ce`) +- Live catalog manifests — `docs/manifests.md` (SHA-256 `42bedecea131090680f50c836bf22e1033fa87f8ac8c0fd35c676f62a788bb48`) +- Development guide — `handbook/pages/development.md` (SHA-256 `a79886d046371b4df3c6edab124edf508c611a4f2a83240409d3325e73e2bc0a`) +- Repository overview — `README.md` (SHA-256 `09d808afa8761b58b929e61e0b98058b677eab9d04717d4b349f81635eba0365`) +- Contributing — `CONTRIBUTING.md` (SHA-256 `6a1f9146b36a78abd630936ce30c19e51e3e4fed06f42babb26f3fc5d92ee225`) +- Working with agents — `AGENTS.md` (SHA-256 `d6e3e68c9137cc76e6904843325cda2e16f476d6486404f96caf8658ff67be3c`) +- Maintain this handbook — `handbook/pages/documentation.md` (SHA-256 `96e25cad639db3e10b0a8f65c0af99f047311ab8bc1e74c9c31561223e83962f`) +- Brand system — `handbook/pages/brand.md` (SHA-256 `caa219ef91b5f7596e7c8c689d017c4e843e37cfabe323e6538cc7a338906206`) +- Verification checklist — `docs/review.md` (SHA-256 `e012c4fc3e6acc47556234396f6ba93972d36d3300c415555e8aa0204fe5bf90`) +- Path to 1.0 — `docs/1.0-plan.md` (SHA-256 `f579191ed990c87f8c2022c6028021aae4e687b87b9081679867800013c2800f`) +- Changelog — `CHANGELOG.md` (SHA-256 `8eef9afeaddf1386ced93bf61901f285dcb9337f3b5b2c686a9541b618108b0d`) +- Privacy & local data — `docs/privacy.md` (SHA-256 `c484c7124218591f5bd8bcb885a76f38caaa54b8a33fc2bf2599cd2e378311f5`) +- Security — `SECURITY.md` (SHA-256 `f82ec2122b6d77c7d1f096b250545289ab184ced290c6b47bd8ff9681864a285`) +- Open-source release — `docs/open-source.md` (SHA-256 `01f5e4292c592cba675806189adeb7f00185ff2d13b8d87509a4b5aedebf28eb`) +- Artwork provenance — `docs/artwork.md` (SHA-256 `1629f4bd6093d1a50c7bd3c592ed186136a0046bdfbb04ff3ba8ba70087092db`) +- Package a preview — `docs/private-preview.md` (SHA-256 `33d99d5cf9afe4839fbe679991c4895dbd20029e45da9fc3046a9f9f6a829685`) +- Steam packaging — `docs/steam-release.md` (SHA-256 `9a1c4b3b1ec5960235ccf9e10ef0bc3cd20b1f9f3c5a165446c3d71473d053b1`) +- Steam submission draft — `docs/steam-submission.md` (SHA-256 `e04abe9a007eaea45f7063524278d0192b2aa9a94aebd68341af18824dfd3537`) +- Publication hygiene — `docs/publication-audit.md` (SHA-256 `e8ad236cebc84ef28430bb0c4ff5728e8b0e639fde46050e35d035d456920d0c`) +- Native Steam acceptance — `docs/native-steam-acceptance.md` (SHA-256 `8add6940dc7fd034f3b766a0135af44f56890737077eba9093fe156203c8a6ed`) +- Earlier VNV acceptance — `docs/vnv-acceptance.md` (SHA-256 `0de0deff80ebba7d816145d54a1dd9e900345c3c72dfe6a4479a860ff18355e5`) +- Preview 0.1 review — `docs/review-0.1.md` (SHA-256 `71f5d98bd97468be542d5a3730b05504e5cc3a41052cfca8c70614e7b141e003`) + +--- + +# The Loadstone handbook + +Canonical source: `handbook/pages/welcome.md` + +Your next playthrough starts with a setup you can understand. This handbook explains how to install, inspect, maintain and create Loadstone setups, with the same source documentation used by the project itself. + +Loadstone is a Windows developer preview built with Svelte and Electron. Native installation, source verification, recovery and library tools are implemented. Complete featured packages and 1.0 release acceptance are still in progress. A successful file check or a game reaching its menu is not a completed gameplay test. + +## Choose your path + +- **Players:** begin with [Your first setup](quick-start.md), then [install a native setup](../../docs/native-guided-install.md). Learn what review screens mean before admitting a candidate to your library. +- **Creators:** follow the [creator workflow](creator-workflow.md), starting with the installed version as evidence and tracing every required file to a reproducible source. +- **Contributors:** read the [development guide](development.md), [contribution rules](../../CONTRIBUTING.md) and [agent guide](../../AGENTS.md). Behavior and documentation should change together. + +## Game support direction + +| Game | Direction | What this means today | +| --- | --- | --- | +| Fallout: New Vegas | Primary support target | Native workflows are implemented; each setup still needs its own acceptance. | +| Fallout 3 | Through Tale of Two Wastelands | Standalone Fallout 3 is outside the supported direction. TTW requires the appropriate owned source games. | +| Fallout 4 | In development | Do not infer a tested setup from game detection or an example catalog entry. | +| Skyrim | In development | Source/edition requirements must be declared by the setup. | +| Starfield | Planned | Currently unsupported. | + +## Three different things to verify + +**Source identity:** the archive or owned-game file is exactly the version a recipe requests. **Reconstruction:** the resulting files and declared timestamps match the recipe. **Playable acceptance:** that particular game, profile and application version actually launch, play, save and reload correctly. Each answers a different question. + +## About this edition + +This is a local, searchable handbook. The pages are compiled from an explicit list of repository Markdown files; they are not fetched from a hosted service. Search includes page text. Source links lead to the matching public repository file. The complete Markdown agent edition is available from the navigation footer. Historical pages live in Archive and describe their own versions. + +For current release gates, use [Path to 1.0](../../docs/1.0-plan.md). For definitions, use the [glossary](glossary.md). For a failed operation, start with [troubleshooting](troubleshooting.md). + +--- + +# Your first setup + +Canonical source: `handbook/pages/quick-start.md` + +Start with a trusted `.loadstone` package and the source games and files it declares. The current app is a developer preview; there is no generally accepted featured catalog ready to promise a one-click playable result. + +## Before you open a package + +Use Windows and keep your existing playthrough intact. Check the setup's game edition, prerequisites, storage needs and save guidance. Choose a new destination with room for the completed installation and any temporary archive work. A package containing a recipe does not automatically contain the mods or game files it references. + +If building the app from source, follow [development setup](development.md). An existing portable preview can be run directly, but its included feature set is determined by its recorded build revision. + +## Install and review + +1. Choose **Set up real installations** on first run. If you explored the demo, disable **Use dummy data** in Settings when ready for real work. +2. In Discover, choose **Open .loadstone**. Read the package identity, declared requirements and save guidance. +3. Select the owned game folders, original archives and prepared prerequisites requested by the guide. Use [manual Nexus downloads](../../docs/native-manual-downloads.md) or the available [source download workflow](../../docs/native-downloads.md) when applicable. +4. Choose a separate destination and review the plan. Fix missing or mismatched inputs before starting. +5. Follow the job in Downloads. Cancellation retains evidence for [reviewed resume](../../docs/native-build-recovery.md); do not manually mix files from different attempts. +6. After final verification, review the completed candidate and explicitly add it to My library. A completed job is not automatically admitted or certified playable. +7. Review the [launch requirements and shortcut options](../../docs/native-library.md). Use a disposable new game for first acceptance where the setup's save guidance requires it. + +## What if I only want to look around? + +Choose **Explore the demo**. Its fictional setups, downloads, validation and launch sessions are simulated. Demo mode does not prove that a real modlist will install. Your demo preferences are separate from native candidate files. + +## What happens next? + +Use library verification to detect file differences. [Repair](../../docs/native-repair.md) can restore missing or damaged recipe files while preserving local changes by default. [Install another version](../../docs/native-updates.md) builds a separate candidate. [Removal](../../docs/native-maintenance.md) reviews what can be removed and retains protected content. + +Do not copy an old save into a new setup merely because both use the same game. Follow the specific setup's compatibility guidance and verify a disposable save/reload first. + +--- + +# How Loadstone works + +Canonical source: `handbook/pages/concepts.md` + +Loadstone brings source selection, reconstruction, verification and a playable library into one desktop workflow. The app keeps these steps explicit so a failed download, a locally edited file and an untested game launch are not mistaken for the same problem. + +## Native packages and external manifests + +A **native `.loadstone` package** uses Loadstone's documented experimental recipe format. Its actions are typed file operations, with declared sizes and hashes. It can refer to original downloads, owned games and prepared prerequisites, and may include permitted payloads. See the [format reference](../../docs/loadstone-format.md). + +A **live catalog manifest** belongs to the separate external-engine path. Wabbajack integration prepares and runs a verified external runtime; it does not turn any file with a familiar extension into a supported native package. See [manifest requirements](../../docs/manifests.md) and the [runtime guide](../../docs/runtime.md). + +## From source to library + +**Sources → reviewed plan → candidate → verification → admission → launch.** + +Sources are locked inputs. A plan checks prerequisites and a separate destination. The builder creates a candidate and checks every required output. Admission reviews that completed candidate before creating a library entry. Launch uses its declared manager/profile configuration. Desktop and Steam shortcuts are explicit operations associated with that setup. + +## Exact bytes and local state + +A SHA-256 fingerprint plus a byte count identifies the expected file content. Some outputs also require a declared modification time, because game tooling may use timestamps for ordering. File verification does not compare visual similarity or assume that a newer mod download is interchangeable with the pinned original. + +Save files, user settings and unexpected files are a different kind of state. Maintenance must preserve them according to the reviewed operation. Restoring recipe configuration is a separate repair choice because it can replace deliberate local settings. + +## Sources inside sources + +A loose file can originate inside a BSA container inside an original ZIP, 7z or RAR download. Native BSA reconstruction records every link in that chain. The [creator mapper](../../docs/bsa-inspection.md#nested-source-mapping) checks those links before recording a match. Arbitrary nested installers and generated transformations are not implied by BSA support. + +## Evidence and permission + +An installed inventory says what is present. A source match says where the exact bytes can be obtained. A recipe says how to produce the output. A rights review says what can be distributed. Acceptance says whether the result works in the intended environment. None of these replaces the others. + +--- + +# Troubleshooting + +Canonical source: `handbook/pages/troubleshooting.md` + +Begin with the operation that failed, its exact setup version and the build identity shown by the app. Preserve the failed candidate and recovery folders while investigating. Export the app's diagnostic summary when useful; inspect it before sharing and keep raw logs, private paths and account credentials private. + +## A source file does not match + +Check that it is the original archive and version requested by the recipe. An extracted folder, a renamed replacement or a newer upstream release is not an exact substitute. The filename is only a lead; the byte count and SHA-256 are decisive. Use the guide's verification and cancellation controls instead of bypassing the mismatch. Creators should update a recipe only after reviewing the new source and resulting outputs. + +## Nexus downloads are unavailable + +Check the account state and last verification in Settings. Automatic downloads require the declared access conditions, including fresh Premium verification where required. [Manual downloads](../../docs/native-manual-downloads.md) open the declared Nexus file page for normal browser interaction, then validate the selected original locally. A missing or removed upstream file remains a source problem; the app does not invent a mirror or bypass website controls. + +## The build was interrupted + +Use the [resume review](../../docs/native-build-recovery.md). Matching files can be reused, while conflicting files are retained before reconstruction. A receipt is not proof that a partially written directory is complete. For a registered setup with an interrupted repair, follow the fresh repair review before trying to launch. + +## Verification reports differences + +Distinguish an intentional configuration edit from a missing or damaged static output. [Same-version repair](../../docs/native-repair.md) preserves existing profiles/configuration by default and keeps replaced originals. Choose configuration restoration only when you intend to return to recipe settings. If a source no longer verifies, repair cannot safely replace it with another version. + +## Steam is running when I create a shortcut + +Follow the app's running-client safeguard and close Steam normally before retrying a shortcut write. Steam can rewrite its shortcut database while running. Shortcut creation is separate from launching a game or proving its Steam startup requirements. See [library and shortcut guidance](../../docs/native-library.md). + +## Steam load error or a game that will not start + +Check the recipe's owned edition, game folder, manager executable, profile and declared Steam app ID. The [Steam startup notes](../../docs/native-library.md#steam-game-startup) record a case resolved after a normal Steam restart. Do not treat repeated automated menu input as a gameplay test. Once launch works, use an appropriate disposable new game and verify save/reload separately. + +## A container cannot be inspected + +Confirm that the selected trusted archive tool is supported and that the original is complete. BSA inspection currently accepts a bounded subset of version 104. A rejected variant is not necessarily a corrupt game archive. Review [archive comparison limits](../../docs/installed-inventory.md) and [BSA limits](../../docs/bsa-inspection.md). Keep an unresolved issue explicit; do not accept partial matches from an unsafe container. + +## Removal retained a folder + +This can be expected. Saves, configuration, modified files and untracked content may remain in recovery. Read the removal review and [recovery rules](../../docs/native-maintenance.md) before deleting anything manually. A retained folder is not a reason to retry a recursive deletion. + +## Reporting a problem + +Include the Loadstone build/version, Windows version, operation, setup identity and the smallest reproducible sequence. Use synthetic inputs for a public reproduction where possible. Follow [security reporting](../../SECURITY.md) for sensitive findings and [privacy guidance](../../docs/privacy.md) for diagnostic exports. + +--- + +# Glossary + +Canonical source: `handbook/pages/glossary.md` + +| Term | Meaning in Loadstone | +| --- | --- | +| Admission | Explicit review and registration of a verified candidate in My library. | +| Archive candidate | A possible original download identified by metadata or creator hints; not yet a proven source. | +| BSA | A Bethesda resource container. Current native inspection/reconstruction supports a bounded version-104 subset. | +| Candidate | A newly reconstructed installation folder awaiting verification, admission or gameplay acceptance. | +| Corresponding source | The source and build material required by the applicable software license for a distributed build. | +| Direct match | An exact installed file found as a member of an original archive. | +| Fingerprint | The file's expected byte count and SHA-256 content hash. | +| Inventory | A record of the selected installed setup, including file identities and mod/profile state. | +| Ledger | Private evidence linking an inventory to possible and verified original sources. | +| Manifest | A catalog description for the separate external-engine installation path. | +| MO2 | Mod Organizer 2, an external manager used by supported portable profile layouts. | +| Native package | A `.loadstone` package interpreted by Loadstone's own typed reconstruction engine. | +| Nested match | A verified original archive → container → inner-file source chain. | +| Original archive | The exact upstream download locked by a recipe or ledger. | +| Prepared prerequisite | A local folder of declared required files; the app checks it without executing a converter. | +| Profile | The selected mod order, plugins, settings and save-isolation configuration for a setup. | +| Recipe | The declarative requirements, sources, outputs and typed actions for a native package. | +| Receipt | Durable evidence of a build/maintenance operation; incomplete receipts do not certify a complete setup. | +| Recovery folder | Retained originals or protected content from an interrupted or reviewed maintenance operation. | +| TTW | Tale of Two Wastelands, a conversion with its own source-game and distribution requirements. | +| Wabbajack | An external modlist installation engine; its integration is separate from native `.loadstone` reconstruction. | + +For the full workflow, read [How Loadstone works](concepts.md). + +--- + +# Install a native setup + +Canonical source: `docs/native-guided-install.md` + +In the live workspace, **Discover → Open .loadstone** imports a native package and guides the player through its required inputs. A private-inputs JSON file is no longer required for this desktop path. The creator workflow in Settings and the local-only CLI remain available. + +1. Review the package name, version, creator and save guidance. Loadstone validates the complete package before displaying the setup. +2. Select each required owned game. One detected Steam installation matching the declared game and store is selected automatically; ambiguous results require a choice. Detected folders are suggestions, and required file hashes are checked during installation. Fallout 3 for TTW and GOG installations currently require manual folder selection. +3. Select any prepared prerequisite folders. These may contain locally converted content; Loadstone checks the declared files and never runs prerequisite instructions or a converter. +4. For each archive, keep **Download from original source** or choose and verify an existing original archive. Sources are searchable and paginated. Automatic uncached Nexus downloads require a connected Premium account. [Browser-download mode](native-manual-downloads.md), the default without a known Premium connection, opens the exact Nexus file page and requires verified local selections before review. The player controls the website download; the app checks the selected file's size and SHA-256 with cancellable progress. Existing cache files can also be explicitly verified and selected. Automatic cache reuse follows the same [download rules](native-downloads.md). +5. Choose an existing installation parent, then **Review installation**. The app chooses a new child folder and shows the destination, output/storage counts, original download hosts, cache and archive reader. Select a trusted local 7-Zip x64 26.04 or newer when prompted for downloads or 7z/RAR inputs. +6. Confirm **Install native setup**. Downloads shows acquisition, source checks, reconstruction and final verification, with cancellation and persistent history. Starting from this screen uses the same [native builder](native-reconstruction.md) and output checks as the creator workflow. +7. After **Files verified · Launch untested**, choose **Review for My library**. Loadstone verifies that exact job destination and its portable MO2 launch layout again, then asks whether to add it. Cancellation adds nothing. Acceptance opens My library, where launch and optional Desktop/Steam shortcut controls are available. This step starts no game, imports no saves and creates no shortcuts automatically. + +Packages without the required portable MO2 layout can reconstruct files but cannot pass library admission. A recipe's declared save compatibility is creator guidance, not a gameplay certification. Complete source permissions, clean-machine/provider acceptance and real game/save/client checks remain release gates. + +**My library → Install another version** uses this flow for a [separate version update](native-updates.md). The original setup stays in its folder with its existing saves, settings and shortcuts; the selected version gets fresh recipe settings and a separate library admission. + +## Recovery and privacy + +For a cancelled, failed or interrupted installation, **Downloads → Review resume** asks for the same package and returns to the guided selections. Reselect local inputs; the installation parent is fixed to the original job. Review shows matching, missing and conflicting files and the recovery folder, with cancellable retained-file checking. Confirmation uses the existing [build recovery](native-build-recovery.md), retaining conflicts and reusing matching outputs under the same history record and destination. + +Selected game, prerequisite and archive paths appear locally in the renderer so the player can review them. The private map and package path stay in the main process; no raw path map is accepted from renderer IPC. Detected folders use opaque per-import identifiers, and every selection is restricted to inputs declared by the recipe. Selection changes invalidate a reviewed plan. Import cancellation preserves the current selections but requires a fresh review. + +The draft survives navigation while Loadstone remains open and is discarded on restart. It is not saved to history or diagnostic exports. Builds retain their existing destination/progress/history records, and source inputs must be selected again for recovery. Opening or reviewing a package does not download archives. Starting an installation explicitly allows its reviewed original-source acquisition; credentials retain the existing Nexus isolation. + +## Verification + +Service tests exercise required selections, ambiguous detection, invalid/stale identifiers, redirected folders, recipe replacement, concurrent selection rejection, cancellation/restart/resume, and local/downloaded archive paths through the shared builder. An actual Electron test exercises Discover import without JSON, Downloads cancellation/resume, explicit library admission cancellation/confirmation and restart persistence. All test game/tool bytes and provider responses are synthetic; no fixture executable is run and no real Desktop or Steam library is written. + +--- + +# Source downloads + +Canonical source: `docs/native-downloads.md` + +The experimental desktop native builder can acquire `https-archive` and `nexus-archive` sources from a reviewed `.loadstone` package. [Guided installation](native-guided-install.md) defaults each archive to its original download and offers a native picker for manually downloaded originals. The creator workflow uses a private input map with either an absolute local archive path or `null` for each archive source ID: + +```json +{ + "games": { "fnv": "C:/OwnedGames/Fallout New Vegas" }, + "archives": { "original-mod": null, "manual-mod": "C:/ModDownloads/manual.zip" } +} +``` + +The source IDs, lengths, hashes and public source references come from the recipe. The private map cannot substitute download URLs, credentials or executables. Games and local prerequisites still require prepared local folders. The CLI remains local-only. + +## Review and execution + +Both guided Discover review and creator Settings review show the archive count, maximum acquisition bytes, original source hostnames, local cache directory and selected archive tool before confirmation. No downloads occur during selection or package inspection. Starting re-inspects the package and rejects a changed recipe before network work. The materializer checks the same recipe fingerprint again before creating candidate outputs. + +The builder acquires archives sequentially, then runs the existing complete input, archive-structure, write and final-file verification. Archive signatures select the actual parser. Acquisition is a separate progress phase; current-file bytes represent downloaded bytes or bytes rehashed from cache. Cancellation and the app close guard include acquisition. + +The tool picker is required when any download is requested because its archive type has not yet been inspected. ZIP downloads use the built-in reader; 7z/RAR use the explicitly selected and fingerprinted local tool. No external tool is downloaded automatically. + +## Cache and retry + +The cache is `native-downloads/` beneath Loadstone's app-data directory. Completed archives use their SHA-256 as the filename. Each new download streams through an exclusive random `.part` file, enforcing the recipe byte length and hash before exclusive publication into the cache. A conflicting cache file is not replaced. Existing archives are rehashed before reuse; mismatches fail and preserve the file for inspection. + +The builder checks for the expected archive bytes plus a 64 MB free-space reserve before each download. Archives remain bounded to 50 GB. Connections have a 30-second header/idle timeout and an acquisition attempt has a two-hour deadline. There is no automatic network retry or concurrent transfer. These are current creator-tool limits, not throughput promises. + +Cancellation or a handled error removes only the current owned temporary download when its directory/file identity still matches. Verified archives remain for retry. A process kill can leave an orphan `.part` file; it is never treated as verified. Retrying reuses verified cached archives but restarts incomplete downloads from byte zero. The desktop can [review and resume a partial candidate](native-build-recovery.md), reusing matching output files and retaining conflicting files before reconstruction. Byte-range download resume, cache management and global cache quotas remain unfinished. + +## Network and account handling + +Original HTTPS downloads use port 443, normal TLS certificate/hostname validation and no cookies, browser session, proxy credentials or inherited authorization headers. Redirects are limited to five and each destination is revalidated. Local, private, link-local, multicast, documentation and other reserved IP ranges are rejected, including mixed public/private DNS answers. IPv6 is conservatively limited to global unicast excluding special ranges. The connection is pinned to a checked DNS answer while retaining the original hostname for TLS validation. This intentionally rejects some specialized networks; it does not add an unrestricted network proxy. + +For an uncached Nexus source, the builder freshly verifies the locally protected account and requires Premium. It calls the specific game/mod/file download-link API, identifying Loadstone and its version. API redirects are refused. The key goes only to the fixed Nexus API origin; the returned HTTPS download link is used in memory without API headers, then discarded. Link responses are bounded to 128 KB. Free users can use [guided manual downloads](native-manual-downloads.md): open the declared Nexus file page, download in the browser and choose the archive for immediate verification. Browser mode requires verified selections before review; NXM protocol handling remains unfinished. A verified local cache hit requires neither a key nor an API request. + +Build history, diagnostics and progress contain no API key, signed URL, response body or raw network error. Source hostnames are shown only in the reviewed plan. Safe errors identify account verification, Premium access, rate limits, hash mismatch or cache/network failure. HTTP failures and rate limits stop the attempt rather than repeatedly calling the provider. + +Sources checked October 13, 2026: [Nexus API policy](https://help.nexusmods.com/article/114-api-acceptable-use-policy), [Nexus download-link interface](https://github.com/Nexus-Mods/node-nexus-api/blob/master/src/Nexus.ts), [Node HTTPS](https://nodejs.org/api/https.html), [IANA IPv4 special ranges](https://www.iana.org/assignments/iana-ipv4-special-registry), [IANA IPv6 special ranges](https://www.iana.org/assignments/iana-ipv6-special-registry). This implementation is original code; no provider client code is incorporated. + +## Acceptance boundary + +Synthetic tests exercise exact cache bytes, rehash/reuse, hash/length failures, disconnect/cancellation, credential separation, Premium restrictions, redirects and DNS policy. The actual Electron bridge exercises reviewed acquisition through a controlled network response into archive extraction and final verification. A controlled response is not evidence that a real Nexus account, registration or real mod download has passed acceptance. Real provider, clean-machine and gameplay checks remain required. Downloads do not establish permission to mirror or bundle their contents. + +A separate private real-network check downloaded the existing pinned 7-Zip 26.04 x64 test dependency from its original GitHub release through the production client. Its 1,664,082 bytes matched SHA-256 `d54bf805f9f3704d1e8db2fa3498ae7ef2df0312b40b558e7c71c734430a665d`, and a second acquisition reused the verified cache with network requests disabled. The downloaded executable was not run or bundled. This checks real HTTPS/redirect delivery and exact cache reuse; it does not certify Nexus access or a playable installation. + +--- + +# Manual Nexus downloads + +Canonical source: `docs/native-manual-downloads.md` + +Discover offers **Download Nexus files in my browser** for `.loadstone` recipes. Browser mode is the default unless the locally saved Nexus connection reports Premium. That saved status only selects the initial UI mode; uncached automatic downloads still require fresh Premium verification in the existing acquisition service. Manual selection itself needs no API key. + +1. **Open Nexus file page** opens the declared game/mod/file page in the default browser. Sign in and use the website's manual download controls. Loadstone opens only that fixed Nexus URL, with no credential or signed download token; it does not automate the browser, scrape pages or bypass website restrictions. +2. **Choose and verify archive** selects the downloaded original file. Loadstone streams its bytes through SHA-256 and checks the declared length before accepting it. Large files show measured byte progress and **Cancel archive verification**. A mismatch, changed/redirected path, failed read or cancellation preserves the previous selection and all input files. Choose the exact declared version; a missing upstream file needs the creator's help. +3. **Use verified cache** explicitly checks that source's hash-named file in Loadstone's existing download cache. It performs the same full verification without a provider request, copying, publishing or deleting anything. Missing or corrupt cache files are not replaced. Manual files remain where the user selected them; this workflow does not populate the cache. +4. The guide tracks remaining Nexus archives and can show only archives still to select. In browser mode, installation review stays disabled until every Nexus source has a verified local selection. Clearing a selection returns that source to the pending count. Changing mode or a selection, including a cancelled picker or failed operation, invalidates the previous review. +5. Review and install through the existing builder. Selected archives are checked again during reconstruction, including archive structure and final outputs. “Verified when selected” records the completed selection check, not a promise that a file cannot subsequently change. Other original HTTPS sources may still be downloaded if selected in the reviewed plan. + +The browser receives only a canonical `https://www.nexusmods.com//mods/?tab=files&file_id=` URL constructed from validated recipe identifiers in the main process. The renderer sends a draft ID and source ID, never an arbitrary URL. Undeclared sources, non-Nexus sources, stale drafts and overlapping operations cannot open a browser. A browser-open failure is reported without exposing its raw error. + +The same guide serves fresh builds, interrupted-build recovery, installed repair and separate-version updates. Selections, verification badges, manual mode and byte progress remain temporary; restart requires reselecting inputs. The source paths were already local guide data and remain excluded from build-history maps and diagnostic exports. No protocol association, browser profile, cookie, NXM key, signed URL, save or real installation is changed by this feature. Registered repairs retain their existing launch/recovery rules. + +## Provider and acceptance boundaries + +Nexus documents website-generated keys for non-Premium API download links. This manual-file flow leaves those website interactions with the user. Automatic Premium acquisition retains its existing request limits, credential isolation and original-source verification. Public API application registration and a real authorized account/download test remain release gates. Sources checked October 13, 2026: [Nexus download-link interface](https://github.com/Nexus-Mods/node-nexus-api/blob/master/src/Nexus.ts), [API acceptable-use policy](https://help.nexusmods.com/article/114-api-acceptable-use-policy). + +Service tests cover exact bytes, cancellation, mid-read mutation, stale selections, redirected paths, source/URL injection, concurrent work, cache reuse and rechecking at installation. Actual Electron exercises the browser handoff through an intercepted opener, wrong-file rejection, visible hashing cancellation and successful local reconstruction with no Nexus account. These synthetic checks do not prove a real website/account interaction or a playable modlist. NXM protocol handling and automatic matching of a whole downloads folder remain separate work. + +--- + +# Nexus account + +Canonical source: `docs/nexus.md` + +The private testing build accepts a personal Nexus API key in Settings. It validates the key with `https://api.nexusmods.com/v1/users/validate.json`, identifying itself with `Application-Name: Loadstone` and the package version. It does not imitate another registered application. Public distribution requires the Nexus registration workflow described in the [API acceptable-use policy](https://help.nexusmods.com/article/114-api-acceptable-use-policy). + +Only the account display name, Premium flag and verification timestamp are returned to the renderer. Email, avatar, and other response fields are discarded. The key and account metadata are saved together in `nexus.bin`, encrypted with Electron safeStorage. On Windows this uses DPAPI; it protects against other Windows accounts, not other processes running as the same user. No plaintext storage fallback is used. See [Electron's storage semantics](https://www.electronjs.org/docs/latest/api/safe-storage). + +Account validation is explicitly requested by the user, with a 15-second timeout, redirects disabled, a bounded response, and clear handling for invalid/revoked keys, rate limits and unavailable service. Opening Settings reads local status without making an API request. Cached account status is labeled with its verification time; it is not proof of current download entitlement. Failed validation or persistence keeps the previous saved connection. Disconnect removes Loadstone's credential files without changing another application's credentials or revoking the key on Nexus. + +## Validation and remaining work + +Automated tests use synthetic keys and controlled responses. They cover account rejection, rate limits, unavailable encryption, malformed responses, secret-free public status/errors, failed-save preservation and disconnect. The Electron test uses real Windows encryption, verifies the resulting file does not contain the key, and restores account status after restart. No real Nexus account has been validated in this milestone. + +The installation runner supplies the key through the child process's `NEXUS_API_KEY` environment variable, never command arguments. It clears inherited Nexus credential environment variables first. The released engine prefers its own saved login, so preflight checks for that credential file and blocks installation until the user signs out in Wabbajack. Loadstone does not read or alter that file. This handoff is covered with synthetic process tests; it still needs a real Nexus installation acceptance run. + +Automatic Nexus downloads require freshly verified Premium access. Native packages now offer a [guided manual-download flow](native-manual-downloads.md) for free accounts. Wabbajack adapter limitations are separate; see [installation behavior](installation.md) for log handling and recovery limits. + +The experimental [native archive downloader](native-downloads.md) uses that fresh Premium check and the specific file download-link endpoint for uncached Nexus sources. Keys remain in the main process and go only to the Nexus API; signed links remain transient. Browser-download mode opens declared Nexus file pages and verifies the manually selected original archives before installation review. NXM protocol handling remains unfinished. Public application registration and real-account download acceptance are still required. + +Child-process environments remove inherited Nexus API-key and OAuth variables case-insensitively, including mixed-case Windows names. Only the installer receives the explicitly selected Loadstone key; engine probes and profile launches receive neither inherited variable. A synthetic real-child regression test covers this boundary without accessing a real account. See [Node's Windows environment behavior](https://nodejs.org/api/child_process.html). + +--- + +# Library, launch & shortcuts + +Canonical source: `docs/native-library.md` + +In the live workspace, **My library → Add native candidate** selects a completed reconstruction folder, including a candidate built by the CLI. Keep MO2 and the game closed while reviewing or verifying it. Loadstone reads its recipe and reconstruction receipt, verifies every static output against its byte count and SHA-256, and checks the generated portable MO2 configuration. Progress is measured in recipe outputs; verification can be cancelled without changing candidate files. + +The review shows the selected folder, profile, output count and the recipe author's save guidance. **Add to library** registers that reviewed candidate without starting a process or creating shortcuts. Only register a creator's executable content if you trust it: recipe fingerprints establish consistency, not safety or authorship. Reconstruction and file verification do not certify gameplay. The existing build history remains separate, and completing a build does not automatically register it. + +## Admission and launch checks + +- The recipe fingerprint must match a completed `verified` receipt. Its generated configuration fingerprint must match the selected destination. Copied candidates need a fresh reconstruction for their new paths. +- The current implementation requires the native `mo2-config` generator, an empty portable marker, the declared profile, and an isolated game directory. Static imported manager configuration is not supported for registration. +- MO2's base, mods, downloads, profiles, overwrite and cache paths must stay in their declared local directories. The selected launch entry must retain its declared title, binary, working directory and arguments. Duplicate INI sections/keys (including case variants), percent-encoded section/key names and ambiguous launch titles are rejected. MO2 may change unrelated window/UI values in supported sections. +- The selected profile's `settings.ini` must explicitly declare `[General]` `LocalSaves=true` and `LocalSettings=true`. Global defaults alone are insufficient. An existing local saves directory must not be redirected. Loadstone never imports an existing playthrough. +- The manager, selected launch executable and base game executable must match recipe hashes and have Windows executable headers. Directories and checked files must be ordinary, unredirected paths. Registration retains the root directory's identity, so replacement or redirection is rejected. + +**Launch native setup** repeats the recipe/receipt, executable, path and local-profile checks before opening MO2 with the exact declared profile and launch title. It tracks the manager process started by Loadstone; a manager window opening or closing is not evidence that the game started or exited. **Verify recipe files** separately repeats the complete static-file comparison and records the latest successful verification time. Later user edits may cause this comparison to fail; no file is repaired, overwritten or removed. + +The full comparison is a point-in-time result. Registration rechecks metadata and the launch-critical files after review; launching does not rehash every mod file. Close other MO2/game windows yourself, including windows started outside Loadstone. + +### Steam game startup + +For a Steam edition, keep the owning Steam client running before **Launch native setup**. If New Vegas displays `Application load error 5:0000065434`, close the game and its MO2 instance, exit Steam normally, reopen Steam, then retry the same setup from Loadstone. A normal client restart resolved this error in our [isolated TTW menu test](native-steam-acceptance.md#direct-launch-after-a-normal-steam-restart). The [Viva New Vegas FAQ](https://vivanewvegas.moddinglinked.com/faq.html) also describes launching the owned game once through Steam as another recovery step. Launching the owned game that way is separate from launching the isolated modded setup. + +If the error persists, retain the setup and record the exact error, game edition and Loadstone build before further diagnosis. A full reconstruction or a changed app ID is not established as a remedy by this test. Loadstone does not automatically restart Steam or change its registration. Reaching the menu and verifying a recording still leave new-game, save/reload and controller acceptance outstanding. + +## Shortcuts and local state + +Desktop and Steam buttons create or repair shortcuts to the candidate's manager and exact profile. Creation checks the same launch layout. Desktop links use the registered candidate ID as an ownership marker. Steam preserves unrelated entries and existing owned app IDs, backs up its shortcut file, and requires Steam to be completely closed. Choose the intended local account before saving. + +These shortcuts start MO2 directly. They do not run Loadstone's checks again when clicked; use the library's launch button to recheck the current layout. Actual Steam-client/gameplay acceptance remains outstanding. + +`native-library.json` in app data stores up to 100 registrations: local path and directory identity, recipe hash, title/version/profile, save guidance, output count and verification time. It contains no Nexus key or source archives. Writes preserve the previous registry if replacement fails, and refuse externally changed or unsupported state. Restart restores registrations without verifying or launching candidates automatically. Native verification prevents closing Loadstone until it finishes or cancellation completes. + +Registered native entries now offer [reviewed removal and recovery](native-maintenance.md). Only unchanged, reviewed recipe files may be deleted after confirmation; saves, configuration, modified files and untracked content are retained. Interrupted removal and owned-shortcut cleanup can be retried. Removed entries retain their recovery record; migration to the current schema is described below. + +[Native repair](native-repair.md) restores missing or changed recipe outputs in the registered folder, retains replaced files and preserves existing configuration by default. Interrupted repair blocks library launch until a fresh review and successful completion. Registrations now migrate to schema 3 when written, retaining removal state and adding a separate repair record. [Native version updates](native-updates.md) build a separate candidate while retaining the original setup and saves. Automatic save migration remains unfinished. [Interrupted creator builds can be reviewed and resumed](native-build-recovery.md) before registration. Wabbajack removal controls apply only to Wabbajack jobs and have their own preservation policy. Real install-to-play acceptance and pack publication remain separate gates. + +--- + +# Resume an interrupted build + +Canonical source: `docs/native-build-recovery.md` + +Downloads offers **Review resume** for failed, cancelled and interrupted builds. Select the same `.loadstone` package and reselect its inputs through the [guided installer](native-guided-install.md), plus a trusted local archive tool when required. The creator path in Settings → Reconstruct a local candidate still accepts a private local-inputs JSON. Source paths and credentials are not saved in build history. The existing history record fixes the destination; the renderer cannot substitute another folder. + +Keep MO2, supported games, script extenders and Wabbajack closed. Resume checks this before review, before acquisition and again before reconstruction. The candidate cannot overlap a registered native setup, another build, source inputs, app data or protected application/system folders. Completed library installations use separate maintenance controls; build resume is not an update or repair operation for an active playthrough. + +## Review and confirmation + +Review checks the recipe fingerprint and reconstruction metadata, scans the ordinary candidate tree and hashes existing outputs against their static or generated expectations. It reports matching files to reuse, missing files to build and conflicting files to preserve before rebuilding. Generated MO2 configuration is compared against the exact destination-specific bytes. Dismissing or cancelling the review changes no candidate files. Review progress is measured and cancellable; it is not persisted as an active build. + +**Resume candidate** is explicit confirmation to reconstruct the same recipe. All required source inputs and archive structure are verified again before candidate writes. Existing reviewed file identities and timestamps, metadata fingerprints and the root identity must still match. Changed or replaced files after review stop recovery and require a fresh review. Existing matching outputs are left in place and included in final verification; only missing or conflicting outputs are written. + +Conflicting files are moved, without replacement or deletion, into a unique folder below `/.loadstone-build-recovery/`, retaining their relative paths. The previous reconstruction receipt is copied there too. Output creation remains exclusive. This preserves modified profile/configuration files as copies while restoring the recipe version in the candidate; review these copies before manually carrying settings into another version. Untracked files and saves remain in place. Recipes cannot target `.loadstone*` paths or save directories. + +Only Loadstone opens destination paths; archive tools emit bytes to the existing bounded readers. ZIP, 7z and RAR reuse the same source and extraction validation as a new build. Verified cached downloads are reused. Interrupted partial downloads still restart from the beginning; this feature resumes candidate files, not byte ranges in downloads. + +## Failures and restarts + +Cancellation or failed writes retain the candidate and all recovery copies. Files already reconstructed remain available for the next review. A crash after retaining a conflict but before writing its replacement leaves the retained copy and a missing output; a later review rebuilds that output without deleting the copy. No automatic rollback, recovery-folder deletion or save migration occurs. + +The same history entry records the resumed attempt. Restart converts active history into `interrupted` without continuing reconstruction. A failure before a candidate directory exists can retry that reviewed destination; a directory appearing after review is refused. A hard kill before both initial recipe and receipt metadata exist cannot establish the partial folder's provenance: preserve it and create a new candidate instead. Missing, corrupt or incompatible metadata is not guessed or repaired. + +History remains schema 1, with no saved source map or recovery plan. External history changes or failed persistence stop new work and require restart. `materializing`, `failed`, `cancelled` and `verified` receipts can be reviewed for a failed/interrupted history entry; this handles a crash after final verification but before history was saved. Successful resume still says **Files verified · Launch untested** and does not register, launch or create shortcuts automatically. + +Destination free-space checks count outputs still needing reconstruction plus recipe metadata and the normal reserve. Existing matching outputs and retained same-volume copies are not charged as a complete second installation. All final outputs are rehashed before success. These checks supplement Windows access controls; they are not a sandbox against an actively hostile process racing filesystem changes. + +This workflow is available through the desktop builder. The local CLI still requires a new destination. Native library updates, clean-machine install-to-play, game/save compatibility and actual Steam-client acceptance remain separate work. + +--- + +# Repair a setup + +Canonical source: `docs/native-repair.md` + +**My library → Repair native setup** imports the exact `.loadstone` recipe used by that registration and opens the guided source selections in Discover. Repair keeps the registered version, folder, profile and library ID. It does not update to a different recipe or version. Keep MO2, games and script extenders closed throughout review and repair. + +Select owned games, prepared prerequisites and original archives again. Sources are not retained in the library registry. Downloads follow the same original-source, cache, hash and Nexus membership rules as installation. Select a trusted local archive reader when required. The current implementation revalidates all declared source inputs, including archives for outputs already present; it does not yet resolve only the sources needed for damaged files. + +## Review and confirmation + +Review hashes recipe outputs and shows matching, missing and changed files. Matching files are reused without rewriting them. Missing files are reconstructed. Changed game/mod files are moved to a unique `.loadstone-repair-recovery//` folder before replacements are written; an existing retained copy is never overwritten. Changed files, roots or metadata after review require another review. + +By default, existing changed profiles and configuration are preserved. This includes `profiles/`, `overwrite/`, `downloads/`, and files ending in `.ini`, `.json`, `.toml`, `.yaml`, `.yml`, `.cfg`, `.conf`, `.fos`, `.ess`, `.nvse`, `.skse`, `.f4se` or `.bak`. Review displays the number of changed personal files retained and up to 20 paths. Missing recipe configuration is restored because no existing file is being replaced. Saves cannot be recipe outputs; untracked files and save directories are not written or removed. + +The separate **Restore changed profiles and configuration to this recipe too** option also restores declared profile/configuration files, retaining their previous contents before replacement. It may reset recipe mod ordering or settings. Existing `downloads/` and `overwrite/` recipe files remain preserved even with that option. This choice does not migrate/import saves, run a converter, or delete untracked content. Changing the policy invalidates the reviewed plan. + +**Repair installed setup** writes a durable `repairing` library record before acquisition or candidate changes. My library shows progress and cancellation. Completion verifies replacements against recipe hashes, retained personal files against hashes captured during review, and the current launch-critical executables and isolated-profile layout. Unsafe preserved MO2/profile settings prevent completion; review again with an explicit configuration restore or correct the local settings before retrying. Completion does not launch the manager or game. + +## Recovery and state + +Cancellation, failed writes or process interruption retain the existing setup and all recovery copies. Library launch and shortcut creation remain disabled while repair is incomplete. **Review repair again** reselects the same package and source inputs, reviews current files afresh and continues in the same installation. A failure after retaining an original but before writing its replacement leaves both the retained original and the missing/partial replacement available for that review. Removal remains available for a stopped repair under the existing save-preserving removal policy. + +Existing Desktop/Steam shortcuts start MO2 directly and cannot enforce Loadstone's repair state. Keep games and managers closed until repair finishes. No automatic rollback, recovery-folder deletion, version update or save migration is provided by this operation. + +The original reconstruction receipt remains unchanged and is retained in each attempt's recovery folder. It records the original reconstruction; the library's repair record describes later maintenance. Schema-1/2 registrations migrate to schema 3 on the next successful state mutation, without eager writes. Schema 3 adds repair recovery directory, start/completion time and preserved-file count. An interrupted `repairing` record becomes `repair-failed` on restart. Unreadable/newer state and external registry edits are refused. Failed final state persistence requires restart and a fresh repair review. + +The last strict recipe verification timestamp is not advanced by repair when personal files are retained. **Verify recipe files** can still report intentional local differences after successful repair. A repaired setup has passed the repair's replacement/preservation and launch-layout checks; actual gameplay/save compatibility still requires separate acceptance. + +## Verification scope + +Synthetic service tests cover missing/changed files, retained originals, personal files and save canaries, explicit configuration restore, redirected/stale paths, protected registry writes, active managers, cancelled work, failed replacement after retention, failed final persistence, restart/retry, schema migration and original RAR acquisition. Actual Electron exercises library-to-Discover repair review, preservation, reconstruction and restart persistence. No fixture executable is run; real game, Desktop and Steam installations remain outside these tests. + +--- + +# Install another version + +Canonical source: `docs/native-updates.md` + +**My library → Install another version** selects a local `.loadstone` package for the same setup ID, game and game variant as the installed registration. Its version label must differ. Loadstone does not infer ordering from arbitrary version labels, discover releases online or authenticate a publisher from a matching setup ID; obtain the package from a creator you trust. + +The update builds a **separate installation**. The original folder, library entry, personal settings, mods, saves and shortcuts remain available. The selected recipe supplies fresh settings and an isolated profile for the new version. No personal content or saves are migrated, even when the creator declares save compatibility. Review the new package's explicit `compatible`, `unknown` or `new-save-required` guidance before considering any later manual transfer. + +1. Select the other version from the installed entry. Same-version packages belong in [Repair native setup](native-repair.md). Incomplete repairs/removals cannot start this workflow. +2. Review both version labels and the original folder in Discover. Choose required owned games, prepared prerequisites and original archives using the [guided installer](native-guided-install.md). The original setup's parent is suggested; another ordinary local parent can be selected. +3. **Review installation** chooses a new child folder and shows the complete fresh-install storage and download requirements. A destination inside, equal to or containing the original folder is refused. Existing installed folders also retain the builder's protected-root checks. +4. **Install separate version** starts the existing acquisition, reconstruction and final-file verification pipeline. Downloads supports cancellation and same-package resume. A failed or interrupted new candidate does not change the old registration or redirect its shortcuts. +5. After file verification, **Review for My library** verifies the new candidate's full recipe and portable launch layout, then separately confirms admission. The two versions have independent IDs and shortcut ownership. No game is started. Keep the original until you have independently accepted the new version; either registered version can use the existing save-preserving removal workflow. + +Selection/review/confirmation recheck the original registration, recipe, receipt and directory identity. Changed registry state, replaced/redirected roots, different setup identity and a manager session launched by Loadstone prevent confirmation. Existing personal file changes are allowed because the old installation is never reconstructed by this operation. The new package must still match its imported recipe hash, and all new inputs and outputs must pass the normal builder checks. + +## Recovery and limits + +The old-version comparison is temporary local draft state; it is discarded on restart. Durable history records the new candidate as an ordinary independent build. **Review resume** uses that candidate's exact recipe and destination and reselects its sources; it does not re-open or alter the original version. There is no persistent parent-child relationship between the two entries, automatic switch, in-place update, delta patch, setting merge or save migration. No new state schema is introduced. + +This workflow offers a recoverable fresh-install update, not verified game/save compatibility. Synthetic service and actual Electron tests check preservation, failure/cancellation/restart, exact identity constraints and independent library admission. Real version-to-version gameplay, clean-machine, provider and Steam-client acceptance remain required. + +--- + +# Remove & recover + +Canonical source: `docs/native-maintenance.md` + +**My library → Remove native setup** reviews a registered candidate before showing a native confirmation dialog. Keep supported games, script extenders, MO2 and Wabbajack closed. The process check must succeed before review and again before removal. No game or manager is started by this workflow. + +The review scans the ordinary candidate tree and compares potentially removable files with recipe sizes and SHA-256 hashes. It reports the maximum reviewed file count/bytes, retained file count and exact recovery path. Cancelling this review or its confirmation changes no candidate files. + +## What is kept + +Only static recipe outputs whose current bytes match the recipe may be selected for deletion. Everything else is retained, including untracked files and modified recipe outputs. The following are always retained even when they match the recipe: + +- All content under `profiles`, `overwrite` and `downloads`, and any directory named `saves`. +- Configuration files ending in `.ini`, `.json`, `.toml`, `.yaml`, `.yml`, `.cfg` or `.conf`. +- Save/co-save/backup files ending in `.fos`, `.ess`, `.nvse`, `.skse`, `.f4se` or `.bak`. +- `.loadstone*` metadata. The generated MO2 configuration is retained. + +After confirmation, Loadstone durably records `removing`, rechecks the root identity and protected locations, then moves the entire candidate into a sibling folder named `.loadstone-recovery-`. It never replaces an existing recovery folder. It rehashes each selected file and checks that its identity and timestamps still match the review before unlinking it. Edited or replaced files are kept, including same-byte replacements with a different identity. Newly created files are never added to an existing removal plan. Only empty ancestor directories of deleted files are cleaned up; the recovery root remains. + +The recovery folder is retained data, not a playable installation. Its manager configuration still describes the original destination. Do not launch it directly or copy saves into another version without checking that version's save guidance. Removing a setup does not delete a source game, archive cache outside the candidate, global save folder or another registered setup. + +## Interruptions and shortcuts + +**Stop removal** stops further work after the current asynchronous operation observes cancellation. Files already deleted are not restored. Remaining content stays in the original or recovery folder, and the entry offers **Resume native removal**. Resuming requires a fresh review and confirmation; missing files are skipped and remaining files are checked again. A restart converts durable `removing` state into an interrupted state without automatically continuing deletion. + +Redirected entries, replaced roots, changed reconstruction metadata, protected-folder overlap, a conflicting recovery folder or an unavailable state file stop the operation. Preserve the directories and registry when resolving such a conflict. No broad recursive deletion is used. A failed registry write before the initial move leaves the candidate in place; a later failure leaves a resumable durable record. + +After file removal, Loadstone removes only its identified Desktop and Steam shortcuts. Steam must be completely closed to edit its shortcut file. Cleanup failures remain visible and **Clean up native shortcuts** retries them without rerunning file removal. Existing Steam backups and unrelated entries remain intact. + +Removal recovery was introduced in schema 2; native library state is now schema 3 with repair records. Schema-1/2 registrations migrate in memory without an eager disk write and are saved as schema 3 on the next successful mutation. Older builds reject the newer state; preserve app data before downgrading. Removed entries remain as recovery records; there is no automatic recovery-folder deletion or history pruning. + +[Native library repair](native-repair.md) now has its own reviewed reconstruction and retained-copy workflow. Stopped repairs may also use this removal policy. [Native version updates](native-updates.md) create a separate installation with fresh recipe settings. Automatic save migration remains separate work. [Interrupted candidate builds have their own resume review](native-build-recovery.md). Synthetic and actual-Electron tests prove the controlled removal/recovery behavior, not real gameplay, save compatibility or Steam-client acceptance. + +--- + +# Wabbajack installation + +Canonical source: `docs/installation.md` + +Disable dummy data in Settings, prepare the pinned engine, connect a Nexus account if the list requires it, then import a creator manifest with its original Wabbajack archive. Check compatibility in Discover. Installation becomes available only after all checks pass; starting repeats the checks. Wabbajack must resolve the same game folder selected in Loadstone. Lists requiring unsupported providers or manual Nexus downloads are blocked. + +Only one live installation runs at a time. Downloads displays actual engine output and job phases, without estimating a percentage from elapsed time. Library entries appear only after the engine exits successfully, structural profile verification passes, and the declared output files are checked. Structural checks cover the manager executable, configuration, declared profile and launch target. Output checks revalidate the owned list archive SHA-256, require every final declared file to be a regular file within the profile, reject redirected paths, and compare sizes for InlineFile, FromArchive and PatchedFromArchive outputs. INI files, modlist.txt, remapped and other generated outputs receive presence/path checks because their content may legitimately change. Temporary BSA inputs are excluded when the list declares CreateBSA outputs; the final BSA files are still required. + +The pinned [upstream installer](https://github.com/wabbajack-tools/wabbajack/blob/4.2.3.0/Wabbajack.Installer/StandardInstaller.cs) rewrites configuration and removes [temporary BSA inputs](https://github.com/wabbajack-tools/wabbajack/blob/4.2.3.0/Wabbajack.Installer/Consts.cs). Output verification records its checked counts and completion time; Library shows these as installation-time evidence, not a continuous integrity guarantee. A missing file or size mismatch leaves the job failed and retryable. Cancellation during verification also remains retryable. The checks do not establish installed-file checksum integrity or gameplay correctness, and existing installations are not retroactively labeled verified. + +## Launching + +Library offers **Launch setup** and **Check profile**. Launch repeats structural checks, requires the original `portable.txt` marker, and rejects a redirected MO2 profile directory. It invokes the installed manager with `-p run -e ` as separate process arguments, using the manager directory as its working directory. No shell interprets titles or paths, and inherited Nexus credential variables are removed. This adapter targets MO2's standard portable layout and the command interface present in [MO2 2.5.2](https://github.com/ModOrganizer2/modorganizer/blob/v2.5.2/src/commandline.cpp). The [portable marker behavior](https://github.com/ModOrganizer2/modorganizer/blob/v2.5.2/src/instancemanager.cpp) keeps instance selection local. + +Status tracks the spawned manager process, not gameplay or playtime. MO2 may hand the request to an existing window; check that window for game startup or errors. Closing Loadstone leaves the manager/game running. Manager tracking is session-local and does not survive a Loadstone restart. + +## Steam library entries + +Library offers **Add or repair Steam entry**, with explicit local-account selection. Steam must be fully closed; Loadstone checks for Steam processes twice and never closes Steam itself. With the Steam shortcut preference enabled, installation attempts automatic creation only when one local account is available. If Steam is running, no account exists, or account selection is ambiguous, installation remains successful and the library reports the follow-up needed. + +Entries target the same portable MO2 command as desktop shortcuts. The updater understands the binary KeyValues format used by `userdata//config/shortcuts.vdf`. It preserves unrelated entries as their original bytes and preserves the app ID and additional fields when repairing a matching Loadstone entry. A per-installation tag identifies ownership. Name/app-ID conflicts, malformed or unsupported data, redirected files and concurrent file changes stop the edit. Existing files receive a uniquely named `.loadstone-.bak` backup before replacement. To restore one, exit Steam and copy the desired backup over `shortcuts.vdf`; this restores the entire previous shortcut library. + +This is a local-file integration, not a public Steamworks shortcut API. Format references: [ValvePython's binary KeyValues implementation](https://github.com/ValvePython/vdf) and [SteamTinkerLaunch's shortcut integration](https://github.com/sonic2kk/steamtinkerlaunch/wiki/Add-Non-Steam-Game). Tests use isolated Steam directories. Read-only inspection of the development machine's existing three-entry shortcut file confirmed an exact binary round trip. Creating an entry and launching it from the actual Steam client still needs release acceptance testing; neither the tests nor this inspection changed that real shortcut file. + +## Desktop shortcuts + +When the desktop shortcut preference is enabled in Settings, successful installation creates a Windows `.lnk` on the user's Desktop. Library also offers creation and repair. Creation repeats launch checks, quotes each Windows argument, writes a temporary link through [Electron's native shortcut API](https://www.electronjs.org/docs/latest/api/shell/), reads it back for verification, and then publishes it. The target is the installed MO2 executable, with the same profile, configured launch title and working directory as library launch. The shortcut works without Loadstone open; it therefore does not repeat Loadstone's checks when double-clicked. + +Each filename and description includes the installation ID. Repair recreates a missing link or replaces the matching owned link. It refuses to overwrite a link with a different ownership description. Shortcut errors appear separately and leave a successful installation installed. The displayed path records the last successful creation; it is not a continuously checked existence indicator. Tests use a temporary Desktop folder and real Windows shortcut read/write calls, leaving the user's Desktop untouched. + +## Owned files and recovery + +The selected destination must initially be empty. Loadstone records an ownership marker and creates `profile/` for Wabbajack output, `downloads/` for reusable archives, `work/` for the engine working directory, and a hashed `list.wabbajack` snapshot. Retry requires matching ownership and preserves downloads and partial output. It also repeats preflight against the imported manifest and source archive; keep those available. Changed source manifests may prevent a retry of the original snapshot. + +Closing the window or quitting while installation, removal or engine preparation is active keeps Loadstone open and offers minimization. Finish the operation, or stop installation in Downloads / cancel engine preparation in Settings and wait for its stopped status before closing. This avoids exiting before final state and log cleanup are saved; forced termination, Windows shutdown and crashes still use interruption recovery. + +Cancel stops the tracked engine process tree. Completion is recorded only after the child exits. An unexpected app interruption leaves a durable job that becomes interrupted on reopening. Restart Windows before retrying that job: the saved Windows boot identifier prevents reuse while the previous engine might still be running. Loadstone does not automatically restart interrupted work. + +## Credentials and diagnostics + +The main process passes the private-test Nexus key only to the engine environment. Renderer job history contains no key. Captured output redacts the exact key, URL queries and named token fields, retaining at most 150 lines of 1,000 characters each. After the child exits, matching Wabbajack CLI logs in the owned working directory and Loadstone-managed runtime directory are sanitized; oversized logs are replaced with a short notice. Native engine logs may remain unsanitized while installation is running or after a crash. Do not publish raw engine logs without reviewing them. Third-party diagnostics outside those two managed locations are not covered by this sanitizer. + +## Removing a setup + +**Remove setup** checks ownership and scans the installed profile before presenting a native confirmation dialog with the exact destination, recovery folder, file count and estimated file bytes to remove. Supported game, script extender, MO2 and Wabbajack processes must be closed. Loadstone will not stop them automatically. Junctions and symbolic links anywhere inside the profile block removal, as do overlaps with game, system or application folders. + +On confirmation, Loadstone records durable removal state and moves the owned destination to a sibling folder named `.loadstone-recovery-`. It deletes ordinary installed files inside `profile/` while retaining all of `profile/profiles/`, `profile/overwrite/`, `ModOrganizer.ini`, and any directory named `saves`. Downloads, the list archive, engine logs and other files outside `profile/` remain in the recovery folder. Global saves outside the setup are untouched. Custom mods and other files inside `profile/` outside the retained locations are deleted; copy anything else you want to keep before confirming. + +No recursive deletion follows reparse points. Each file is checked again before deletion. If a file is locked or the app closes, the job becomes resumable removal work; **Resume removal** repeats the checks and continues. A completed removal leaves the library and stays in Downloads history with its recovery location. The original destination can be used for a fresh installation. The retained data is not a full restore of deleted mods; transferring saves to another list requires that creator's save-compatibility guidance. + +After removal, Loadstone deletes its matching desktop link and tagged Steam entries across available local accounts. Unrelated shortcuts are retained. Steam must be closed for any Steam file edit; each edit gets a backup and preserves remaining entry fields and app IDs, renumbering entry indices where necessary. Cleanup failures leave the setup removed and show **Clean up shortcuts** in Downloads for retry, including after restart. Renamed desktop links and unavailable Steam accounts may require manual cleanup. Version updates use separate fresh installations with creator-declared save guidance; see [updating manifests](manifests.md#updating-an-imported-setup). The previous setup remains available until explicitly removed. Deleting the recovery folder would delete the retained saves and downloads, so Loadstone does not purge it automatically. + +## Verification status + +Tests exercise real child processes with synthetic files: success, failure, cancellation, retry, ownership rejection, restart recovery, credential redaction, launch arguments, duplicate launch prevention and manager exit handling. Electron tests cover library profile checks and demo-mode launch rejection. The pinned official engine has separately passed integrity, version, help and game discovery checks. A full real list download, install and play session has not yet passed acceptance testing. These source features are newer than the v0.1.0 portable preview. + +--- + +# Wabbajack runtime + +Canonical source: `docs/runtime.md` + +Loadstone downloads the unmodified official Windows [Wabbajack 4.2.3.0 release](https://github.com/wabbajack-tools/wabbajack/releases/tag/4.2.3.0) into its own workspace. The package is streamed to a staging directory, checked against the release asset size and published SHA-256 digest, then extracted with path, symlink, duplicate, entry count and expanded-size limits. Only a successful CLI version and install-interface check activates the runtime. Repair keeps the previous engine in a backup directory. Cancellation discards the staging work without replacing an existing engine; interrupted app exits may leave inactive stage directories for later cleanup. + +Archive SHA-256: `91392832f4466420a02687fa6e92192897e8e4b5b1b3dc97fbe36f7a4e490ba5`. + +The full extracted file inventory is pinned as well, so editing inventory metadata cannot authorize changed runtime binaries. Verification rejects changed, missing, injected, or symbolic-link runtime files. The pinned CLI writes rotating logs relative to its executable despite a separate working directory. Only regular, singly linked files matching `logs/wabbajack-cli.current.log` or its numbered archives are excluded from payload hashes; other files in `logs` are still rejected. Completed installer runs sanitize these runtime logs as well as owned working-directory logs. No arbitrary executable path is accepted through the renderer bridge. At least 1.2 GB of free workspace-drive space is required while preparing the runtime. + +## Verification + +Run the actual released engine without downloading it during the normal offline test suite: + +```powershell +$env:LOADSTONE_TEST_RUNTIME_ARCHIVE = 'C:\path\to\4.2.3.0.zip' +node --test tests/runtime.test.mjs +Remove-Item Env:\LOADSTONE_TEST_RUNTIME_ARCHIVE +node scripts/verify-runtime.mjs 'C:\path\to\4.2.3.0.zip' +``` + +This invokes the genuine released CLI, checks its installation flags, verifies all 1,085 extracted files, and tests changed/injected-file rejection. The normal suite covers duplicate and symlink rejection, cancellation, and failed-download preservation without external network access. + +## Authentication and installation work remaining + +The released [install command](https://github.com/wabbajack-tools/wabbajack/blob/4.2.3.0/Wabbajack.CLI/Verbs/Install.cs) supports local archives and output/download folders. It discovers the game independently; it does not accept our manually selected game path. The adapter must confirm the engine's actual game location before installation, rather than assuming the paths agree. + +The released [Nexus client](https://github.com/wabbajack-tools/wabbajack/blob/4.2.3.0/Wabbajack.Networking.NexusApi/NexusApi.cs) uses an existing Wabbajack credential ahead of its `NEXUS_API_KEY` environment fallback. Its CLI also throws on interactive interventions. Account identity, Premium download access, unsupported manual-download sources and intervention/recovery behavior remain explicit integration gates. Loadstone does not yet read, overwrite, export, or modify Wabbajack credentials. Engine readiness alone must not make a live setup ready to install. + +## Distribution + +Wabbajack remains an independent, unmodified [GPL-3.0 project](https://github.com/wabbajack-tools/wabbajack/blob/4.2.3.0/LICENSE.txt). Its executable is downloaded from the upstream release, not embedded in this repository or the current Loadstone package. The runtime and its components retain their upstream licenses. Any future bundled distribution must include the applicable notices and corresponding source obligations. The pinned source tag and release link are retained here for review. + +Real VNV preflight exposed the log location on a second runtime verification. The genuine-engine regression now runs game discovery, re-verifies with generated logs present, and checks that a DLL placed in the logs folder is still rejected. The pinned [CLI logging configuration](https://github.com/wabbajack-tools/wabbajack/blob/4.2.3.0/Wabbajack.CLI/Program.cs) declares the current and numbered archive names. + +The shipped NLog version actually rotates logs as `wabbajack-cli_00.log` (underscore), despite the dotted archive pattern in the CLI source. Both strictly numbered forms are handled. The real-engine regression performs game discovery twice so rotation is exercised before verification. + +--- + +# Creator workflow + +Canonical source: `handbook/pages/creator-workflow.md` + +Start with a specific installed version and its chosen profile. An upstream list is a useful lead, but it does not necessarily describe local changes, generated output, disabled mods or the files that are actually in use. + +## 1. Capture installed truth + +Use the [inventory tooling](../../docs/installed-inventory.md) to record hashes, mod ordering and enabled states, profile configuration, instance/game files and overwrite content. Preserve existing saves and live installations. Keep the inventory outside source control: it contains private paths and installed-content names. + +## 2. Find and prove sources + +Build a private source ledger from the accepted inventory and selected download folders. Add explicit creator hints when automatic archive leads are incomplete. Compare original ZIP/7z/RAR members by exact size and SHA-256. An adjacent metadata ID is a lead, not proof of the file's contents or its rights. + +For installed BSA containers, use [nested BSA mapping](../../docs/bsa-inspection.md#nested-source-mapping) to verify the original member and its internal files. Keep unresolved generated/edited files visible. A similar filename or rendered image is not an exact replacement. + +## 3. Review rights and required inputs + +For every distributed source or asset, record authorship, attribution, permitted delivery and the required user-owned inputs. Original downloads, local owned-game reconstruction and hosted payloads are distinct cases. A local file that happens to install successfully is not automatically redistributable. Loadstone's GPL license does not grant rights to third-party mods or game files. + +## 4. Write a typed recipe + +Use the [format reference](../../docs/loadstone-format.md) for exact field names and limits. Declare outputs with hashes and required timestamps. Prefer original archive sources when supported; declare prepared prerequisites honestly where automatic conversion is not implemented. Configure portable MO2 with the [destination-bound configuration action](../../docs/native-mo2-configuration.md). Do not import account/browser state or arbitrary shell scripts. + +## 5. Compile and inspect + +Compile the recipe into a package and inspect it before reconstruction. Review source hosts, requirements, output paths, storage, profile and save guidance. Package validation must succeed independently of any installed baseline used to create it. The native [reconstruction guide](../../docs/native-reconstruction.md) documents CLI and desktop entry points. + +## 6. Reconstruct and compare + +Build into a new isolated candidate. Verify every required output and declared timestamp, then compare against the intended baseline. Exercise cancellation, reviewed resume and relevant maintenance behavior with disposable candidates. Do not substitute a successful inventory scan for actual reconstruction. + +## 7. Accept the playable setup + +Review library admission, launch, shortcuts, a disposable new game, save/reload and the intended input devices. Repeat on a clean Windows environment with the required owned games and sources. Record exact app, recipe, game, manager and tool versions. A menu launch is only one step. + +## 8. Prepare publication + +Complete credits, source permissions, support instructions, truthful screenshots and the release checklist. Featured status indicates Loadstone maintenance, not endorsement by upstream authors or publishers. Publication remains a separate action after the [acceptance gates](../../docs/1.0-plan.md) are met. + +--- + +# Inventory & source mapping + +Canonical source: `docs/installed-inventory.md` + +This work uses the selected profiles of the user's installed setups as the source of truth. Original modlist archives are source hints, not authoritative descriptions of the current installation. No live profile, mod, game, save or shortcut is modified by inventory. + +## Read-only inventory + +```powershell +node scripts/inspect-mo2.mjs +node scripts/inspect-mo2.mjs --hash-files +node scripts/inspect-mo2.mjs --hash-files --installation-files +``` + +Keep reports under ignored `test-results/` or another private local directory. They contain personal paths and local filenames and must not be committed or published. The CLI refuses to replace a report. It reads the selected MO2 profile, resolves configured mod/profile locations, preserves the profile's recorded priority, inventories enabled mod directories and overwrite, and hashes profile files plus the installed loose plugin winning each conflict. Known source fields from `meta.ini` are hints only; other fields are excluded. + +Default file inventories record size and modification time. `--hash-files` additionally hashes every included enabled-mod and overwrite file. Add `--installation-files` to include selected-profile disabled mods, instance files and tools, the configured game directory, and all files in the selected profile, including configuration outside the original six-file snapshot. The additive `installation` record carries `instanceFiles`, `gameFiles` and `profileFiles`; mod records keep their original enabled/disabled state and priority. Unlisted mod directories and other profiles are outside this selected-profile baseline. + +Configured mod/profile/game/overwrite directories are captured separately without duplicating their contents under the instance tree. The configured download cache is excluded. All scans skip known save/cosave paths, credential/browser stores, logs, caches and backup directories by path, before opening them; each excluded file or subtree is recorded with its scope and reason in `exclusions`. This is an explicit inventory boundary, not a claim that excluded state is reproducible. General configuration can contain private fields: its content is hashed, while only the existing allowlisted source hints are exported. Reports remain private. No file is executed, edited or uploaded. + +Neither mode is an atomic filesystem snapshot. File hashing rejects changes while reading. At the end, every scanned tree is enumerated again and checked for added/removed files, file identity/size/timestamp changes and replaced directories; selected profile/configuration hashes are also rechecked. Stop active modding or gameplay before producing release evidence. Symlinks/junctions outside excluded state, ambiguous INI fields, duplicate mod entries and traversal names are rejected. Missing enabled mods/plugins are reported explicitly, not called a successful installation. Ctrl+C cancels scanning; no final report is written. Across scanned trees, inventories are bounded to one million included files, 100,000 excluded paths and 100,000 directories per tree. + +The report is **not installable and not publication-approved**. Even with complete hashes for the included files, it does not establish upstream game equivalence, archive contents/conflict resolution, runtime compatibility, source-download reproducibility or redistribution rights. Saves are not read from the profile. No network request or program launch is required to inspect an instance. + +MO2 instance plugin inventories also exclude CPython `__pycache__` files when their adjacent ordinary `.py` source is present. Each receives the explicit `regenerable-python-bytecode` reason; the source remains inventoried. Standalone bytecode, caches without a source, unknown cache naming and mod/game content remain included. This avoids pinning machine-dependent cache bytes that MO2 regenerates after relocation. Existing inventories, recipes and verification fingerprints are unchanged; use a new reviewed recipe/version to apply this boundary. + +Winning loose-plugin records also retain `mtimeMs` (UTC milliseconds, rounded to an integer) alongside their SHA-256, size and winning layer. This is collected from the same stable hash pass. It lets a creator explicitly preserve timestamp-based load order in a new recipe without assigning that metadata to every mod file or silently changing existing reports. Hash-mode file inventories otherwise retain their existing size/hash shape. + +## Private source ledger + +```powershell +node scripts/source-ledger.mjs hashed-inventory.json new-private-ledger.json downloads-folder [another-downloads-folder] +node scripts/source-ledger.mjs hashed-inventory.json new-private-ledger.json downloads-folder --hints private-hints.json +``` + +This command preserves the hashed installed-file records and finds candidate ZIP/7z/RAR archives using the recorded installation filename or a matching game/mod ID. It fingerprints candidate archives and reads only `gameName`, `modID` and `fileID` from their adjacent `[General]` metadata. It does not read credential header files, copy arbitrary metadata fields, extract archives or contact Nexus. Conflicting metadata and multiple versions remain explicit candidates; none is selected automatically. + +Expanded inventories retain their instance/game/profile hashes and explicit exclusions in the private ledger, with an allowlist of record fields. Inventoried disabled mods can receive archive candidates and exact member matches without being enabled. These added root/profile records remain unresolved until separately mapped or transformed; retaining hashes does not infer their sources or permission to distribute them. + +The resulting ledger references the input inventory's SHA-256 and records unresolved reconstruction and unreviewed permissions. Matching a filename or Nexus mod ID does not prove an archive member equals an installed file. Exact member comparison, local edits, root/profile reconstruction and generated output remain separate work. Keep these ledgers private alongside inventories; the CLI refuses to replace them or write inside source/download directories. + +When installed metadata cannot identify an archive already in the selected download folders, a creator can nominate it with a private UTF-8 JSON hints file: + +```json +{ + "schemaVersion": 1, + "kind": "loadstone-source-hints", + "mods": [ + { + "name": "Example installed mod", + "archives": ["C:/CreatorCache/original.zip"] + } + ] +} +``` + +Each name must exactly match one inventoried mod with files, including disabled mods. Archive paths must be absolute and identify top-level ZIP/7z/RAR files in a download folder explicitly selected on the command line. Unknown fields, duplicate mod names or per-mod archive paths, redirected files and paths outside those folders are rejected. Limits are 5 MB per hints file, 10,000 mods, 100 archives per mod and 100,000 total references. Hints cannot add remote URLs, credentials or claimed provider IDs. + +Hinted archives are fingerprinted and marked `creatorHint: true`; existing automatic match evidence is retained without duplicating a candidate. Conflicting known game/mod metadata remains a conflict and is skipped during member mapping. A hint never proves installed bytes, rights or reconstruction. The ledger retains the hints file's path and exact SHA-256; ledger creation rejects a changed hints file, and mapping refuses a hints file that has changed since the ledger was written. Keep that file private and stable alongside the reports. Ctrl+C cancels ledger creation without writing a final report. + +```powershell +node scripts/map-zip-sources.mjs private-ledger.json new-private-mapping.json +``` + +The member mapper verifies each candidate ZIP against its locked archive hash, then streams member hashes and compares them with installed size/SHA-256 pairs. It records exact member paths, retains matching archive candidates and leaves locally changed files unresolved. It does not extract files or execute content. MO2 `meta.ini` is excluded because it needs privacy-aware regeneration. Each ZIP is accepted as a whole: unsafe paths, duplicate/colliding names, links, changed input or limit violations discard its potential matches. A cancellation aborts the pass. + +Upstream ZIPs may use Windows backslashes in their internal names. These separators are normalized to `/` before path validation, collision checks and member selection; the original archive is never rewritten. Slash/backslash aliases, case collisions, traversal, absolute paths and file/directory overlaps still reject the entire archive. Mapped member paths use canonical forward slashes and can be passed directly to native reconstruction. `.loadstone` package entries and recipe paths remain strict and do not accept backslashes. + +Limits per archive: 50 GB compressed input, 500,000 entries, 100 GB declared uncompressed content, 1 GB per hashed member and 20 GB of hashed member data. The report accepts at most 500,000 match references. Exact byte matches still require source/rights review, profile and root reconstruction, and actual installation acceptance. + +When multiple members of one archive have identical size and SHA-256, the mapper keeps the lexicographically first normalized member path as a deterministic representative and records `equivalentMembers`, the count of verified members with those exact bytes. The mapping declares `memberSelection: "lexicographic-representative-per-content"`. This compact representation replaces the earlier 128-equivalent-member rejection and prevents the installed-file count from multiplying by the number of identical copies. Every selected member is still hashed; complete archive validation and stream checks must succeed before any matches are accepted. Different archives remain distinct candidates. A representative proves a byte-equivalent source, not which archive member the original installation used. Recipes still require review of the source and exact selected member. + +For optional 7z/RAR comparison, pass an absolute path to a trusted local x64 `7z.exe` (26.04 or newer, with its matching `7z.dll`): + +```powershell +node scripts/map-zip-sources.mjs private-ledger.json new-private-mapping.json C:\Tools\7-Zip\7z.exe +``` + +The command retains its original name for existing workflows; this optional argument enables the additional formats. Archive signatures select the parser, so a ZIP cached under a `.7z` filename can be inspected without renaming or altering it. A signature only selects the parser; full archive hashes and structural validation still apply. Embedded/self-extracting formats remain unsupported. The tool path comes from the operator, never from a recipe. It runs without a shell or visible window, inventories the archive, rejects encrypted/linked/multipart/embedded or ambiguous entries, and reads each selected member into a bounded hashing stream. Nothing is extracted to disk. Literal selectors disable wildcards and list-file expansion. Archive and executable/library identities are checked between reads. Tool diagnostics stay out of reports. + +For 7-Zip 26.04 and a Node runtime with `zlib.crc32`, bounded 7z archives with member CRCs use one streamed pass. The reader checks every file boundary against its listed CRC, computes SHA-256 for wanted sizes and accepts matches only after the complete stream, exit status and source identity pass. It handles up to 100,000 selected members and 20 GB of total streamed content without writing extracted files. The implementation was checked against upstream [listing order](https://github.com/ip7z/7zip/blob/26.04/CPP/7zip/UI/Console/List.cpp), [extraction indices](https://github.com/ip7z/7zip/blob/26.04/CPP/7zip/UI/Common/Extract.cpp) and [7z solid-block extraction](https://github.com/ip7z/7zip/blob/26.04/CPP/7zip/Archive/7z/7zExtract.cpp); a boundary mismatch discards all matches. + +Other tool versions, RAR and archives without suitable checksums use one process per selected member, which can be slow for solid archives and is limited to 10,000 selected members. Each archive has a five-minute budget; a timeout or limit records an unresolved issue. The single-pass reader accepts members over 1 GB within its unchanged 20 GB total stream bound; individual-member and ZIP comparison retain a 1 GB member bound. Hashing a BSA as one archive member does not map files inside that BSA. The same adapter also supports [native reconstruction](native-reconstruction.md), with separate extraction limits and operator-selected tool review. No 7-Zip binary is bundled with Loadstone. + +For tests, `scripts/prepare-sevenzip.ps1 -Destination ` downloads the fixed official 26.04 x64 release, checks its published SHA-256, and unpacks only the command-line tool and notices with an existing 7-Zip. It does not install globally. Set `LOADSTONE_TEST_7ZIP` to the returned executable when running tests. Windows CI performs this setup and runs the real tool fixture; without the variable that optional integration test is skipped. + +7-Zip is a separate upstream tool with LGPL, BSD and unRAR terms; a future bundled distribution needs its own notices/source compliance review. See the [official release](https://github.com/ip7z/7zip/releases/tag/26.04) and [license](https://www.7-zip.org/license.txt). + +For a separate read-only inventory of files inside a local Fallout 3/New Vegas BSA, see [BSA 104 inspection](bsa-inspection.md). To connect selected installed BSAs to original archive candidates and compare their contents with the ledger, use [nested BSA source mapping](bsa-inspection.md#nested-source-mapping). Reviewed source chains can then be declared explicitly for [native BSA reconstruction](native-reconstruction.md#nested-bsa-104-files). + +## Native `.loadstone` format + +The user chose a documented format and open implementation on 2026-10-13. This is Loadstone's native format, not an opaque replacement for upstream archives. The implementation and specification will be developed together from the real inventories. The maintainer separately selected GPL-3.0-or-later for the original implementation on October 13, 2026; third-party content retains its own terms. + +The first [native format specification and package compiler](loadstone-format.md) are now available as experimental creator tooling. Inventory reports remain private evidence; they cannot bypass the source and rights work required for a valid recipe. + +The target is a versioned, bounded container with a canonical recipe, source lock and content hashes. It must describe: + +- Game/storefront/DLC requirements and exact accepted source hashes; TTW requires both owned games while running through the New Vegas engine. +- Mod priority, enabled and disabled state, plugin order, archive behavior, loose-file overrides, root files and generated output. +- Source URLs/provider file IDs and original archive hashes; an installed version string alone cannot identify a reproducible download. +- Differences between original archives and installed files, including locally edited INIs, generated LOD, compatibility patches, custom assets and menu-music transformations. +- Typed, bounded local reconstruction operations. No arbitrary shell recipes or remote scripts. +- A rights record for each payload: original source download, local owned-game input, redistributable content with evidence, or unresolved. Unresolved records block publication of the affected payload. +- Save compatibility, provenance, attribution and exact tested application/list/game versions. + +A public list recipe must exclude personal machine paths, accounts, saves and raw logs. Source hashes and dependency references can describe a setup without uploading its game/mod payload. Any bundled files need separately established distribution rights. Local custom menu music built from owned game themes must be reconstructed locally or replaced with permitted material, not assumed redistributable. + +## Compatibility and hosting boundaries + +Wabbajack remains an external installation adapter. Native MO2 inspection is implemented here; import/compile/reconstruction are separate steps. Nexus collection compatibility requires study of the actual supported export/API format and applicable permissions before claiming support. Do not call every Nexus mod or arbitrary MO2 directory a directly installable Loadstone list. + +GOG states that games are for personal use; DRM-free does not grant distribution rights. A paid storage service is therefore an architecture candidate for authorized assets and permitted backup scenarios, not an entitlement to serve common game mirrors. Evaluate Backblaze B2/AWS or alternatives after defining the rights, retention, encryption and cost model. No hosting subscription or paid infrastructure has been created. Sources: [GOG sharing guidance](https://support.gog.com/hc/en-us/articles/212184489-Can-I-share-games-with-others?product=gog), [Nexus API policy](https://help.nexusmods.com/article/114-api-acceptable-use-policy), [Wabbajack compilation guidance](https://wiki.wabbajack.org/modlist_author_documentation/Pre-Compilation.html). + +## First live inventory findings (2026-10-13) + +| Candidate | Selected installed profile | Enabled mods | Plugin entries | Enabled-mod files | Overwrite files | +| --- | --- | ---: | ---: | ---: | ---: | +| Combined TTW | Tale of Two Wastelands | 95 | 35 | 12,314 | 0 | +| FO3 Remastered | Fallout 3 Remastered | 88 | 30 | 8,982 | 0 | +| FNV Revamped | Viva New Vegas Extended | 196 | 82 | 93,106 | 207 | + +These are inventory observations, not release or gameplay certification. All three had their enabled mod directories and listed loose plugins present. The two TTW instances point at their own isolated game folders; the customized New Vegas profile points at the installed Steam game. New Vegas retains enabled local prototypes and generated output, so publishing it faithfully requires reviewing those actual files rather than substituting the upstream VNV recipe. + +Source-ID coverage is incomplete: 82/95 combined TTW mods, 78/88 FO3 Remastered mods and 144/196 New Vegas mods carry a nonzero Nexus mod ID in their local metadata. Even those IDs do not establish exact download file IDs, original archive hashes, unchanged installed bytes, compatibility or redistribution rights. Establish an explicit source/transform/permission ledger before producing featured installable packs. + +The first local archive-ledger pass found candidates for 77/95 combined TTW mods, 73/88 FO3 Remastered mods and 146/196 New Vegas mods. It fingerprinted 78, 74 and 146 distinct archive paths respectively. Multiple candidates remain for 17, 17 and 43 mods; none had a conflicting filename/mod-ID hint in that pass. These counts measure source leads, not verified member mappings or publication readiness. No game/mod payload was uploaded. + +The ZIP-only comparison then inspected 30, 29 and 58 archives and matched 650, 903 and 4,346 installed mod files respectively. The remaining 11,664, 8,079 and 88,760 mod files are unresolved in this pass, including private MO2 metadata and content whose candidates are 7z/RAR. Overwrite, game-root and profile reconstruction remain separate. A missing match does not by itself prove that a file was edited. + +The later ZIP/7z/RAR pass with the verified 26.04 stream reader inspected 78, 74 and 144 archive candidates and matched 4,585 combined TTW, 4,826 FO3 Remastered and 15,795 New Vegas installed mod files. It left 7,729, 4,156 and 77,311 mod files unmatched, plus the separately inventoried overwrite files. All TTW/FO3 archive candidates were safely inspected; two New Vegas candidates remained unresolved. Source-cache gaps and generated/local content still dominate the missing mappings. TTW's full pass took 10.48 seconds on this machine and the New Vegas pass 48.68 seconds; these are local observations, not general performance guarantees. No installation file was changed or uploaded. + +The subsequent content-detection pass resolved both remaining New Vegas archive issues: a ZIP stored with a `.7z` filename and a 1,219,819,547-byte terrain BSA above the previous member cap. All 146 candidate archives were inspected with zero archive issues, matching 15,992 installed files and leaving 77,114 unresolved. The ZIP kept its original filename and bytes. The large BSA was hashed as a whole member through the bounded single-pass reader; its contents were not extracted or independently mapped. This improvement is source work after the recorded 0.3.0 portable build, and does not certify any featured pack. + +The later expanded inventories also include disabled mods and explicit state exclusions. Creator hints against those baselines linked cached archives without modifying installed metadata. Exact matches rose from 4,586 to **9,500** for TTW Complete, 4,827 to **6,855** for FO3 Remastered and 16,706 to **30,060** for FNV Revamped. This leaves 2,864, 2,130 and 81,300 mod files unresolved respectively; game, instance, profile and overwrite records remain separate. The passes safely inspected 83, 82 and 156 archives. Three additional FNV quest archives exceeded the existing 128-equivalent-member limit, so none of their matches were accepted. These are comparison-limit failures, not evidence that the archives are corrupt. Further duplicate-content handling, source/transform work and rights review remain necessary. Hints and reports remain private; all installed sources are unchanged. + +Compact equivalent-content matching subsequently verified all three previously rejected FNV archives. The Better Angels, Bounties III and Bounties II added **28,935** exact file matches, bringing FNV to **58,995 matched / 52,365 unmatched**, with all 159 candidates inspected and zero archive issues. TTW remains at 9,500 / 2,864 (83 archives), and FO3 Remastered at 6,855 / 2,130 (82 archives), both with zero issues. Every previously matched installed file retained a source match. These results use one verified representative per archive/content identity and do not establish which identical member the original install used, redistribution rights or playable acceptance. + +--- + +# The .loadstone format + +Canonical source: `docs/loadstone-format.md` + +Status: experimental creator tooling. This is a documented format with an original implementation licensed under GPL-3.0-or-later. The source repository is public; recipes and payloads require their own distribution rights and acceptance. **Settings → Native package preview** inspects a user-selected package through the Electron bridge and shows a bounded summary. **Reconstruct a local candidate** can build local copy and ZIP/7z/RAR-extract recipes with durable history. Guided native installation and explicit library admission are implemented alongside the Wabbajack path; actual game/list acceptance remains required before advertising a supported playable setup. + +## Purpose and trust boundary + +A package describes exact inputs and expected outputs for a portable, isolated MO2 setup. It references original downloads and locally owned game files. It can carry small payloads with declared distribution permissions. It has no shell actions, scripts, hooks, remote executable recipes or implicit path discovery. An archive source names a specific archive; an extract action names a specific member, without interpreting that member's extension as an instruction. + +The installed inventory is separate private evidence. It is not a recipe: missing archive provenance, local changes, generated content and permissions must be resolved before compilation. A Nexus mod ID alone is insufficient. Do not replace a current custom installation with its upstream list while calling it equivalent. + +SHA-256 verifies byte identity, not safety, authorship or rights. Version 1 packages are unsigned. Permission fields are creator declarations with review references; the validator cannot establish legal permission or approve publication. Gameplay, save compatibility and publisher trust require separate acceptance. Inspection always returns `publicationApproved: false`. + +## Container + +Use the `.loadstone` extension for a ZIP with these entries: + +1. `recipe.json`, first in central-directory order, containing canonical UTF-8 JSON. +2. `payload/` for each declared payload source, exactly once. No other entries, directory records, symlinks, devices, encrypted files or file comments are allowed. ZIP methods 0 (stored) and 8 (deflate) are accepted. + +Canonical JSON recursively sorts object keys using JavaScript's default string ordering, preserves array order, uses `JSON.stringify` compact serialization and appends exactly one LF. No BOM. The parser validates the object and requires byte equality with that representation, rejecting duplicate keys and ambiguous alternate representations. Numbers are bounded safe integers wherever used. Recipe identity is SHA-256 of these canonical bytes; ZIP compression and timestamps do not define recipe identity. + +The reference compiler orders payloads by their lowercase hex hashes, uses fixed timestamps/modes and stored entries. Given identical inputs on the same toolchain it creates identical package bytes. Inspection streams payload hashing and never extracts or launches content. + +Limits: 64,000,000 recipe bytes; 100,000 sources; 500,000 outputs; 256,000,000 total uncompressed bundled payload bytes; 512,000,000 package bytes; at most source-count-limit plus one entries. Byte sizes are nonnegative safe integers; download/output totals are capped at 10 TB. These are parser limits, not recommended list sizes or machine resource promises. + +## Recipe fields + +All objects reject unknown fields. All listed fields are required unless marked optional or a source/action variant omits them. `electron/native-format.cjs` is the executable validator; fixtures in `tests/native-package.test.mjs` show a complete synthetic example. This experimental version is not yet a stable interchange contract; older previews reject newer optional fields safely. + +| Field | Meaning | +| --- | --- | +| `format`, `formatVersion` | Literal `loadstone` and integer `1`; unknown versions fail closed | +| `id` | Lowercase letters, digits and hyphens; 1–64 characters, starting with a letter or digit | +| `name`, `version`, `author`, `description` | Nonempty text up to 500 characters, without control characters | +| `website` | HTTPS reference without userinfo, query or fragment | +| `game` | `{id, variant}`; targets `fnv`, `skyrimse`, `fallout4`; variant `base`, or `ttw` for FNV | +| `requirements` | Exact owned-game inputs, below | +| `prerequisites` | Optional local material the user prepares separately, below; omitted when none | +| `launch` | `{profile, executable, gameRoot}`; MO2 profile directory name, MO2 executable title, isolated relative game directory | +| `sources` | Inputs keyed by unique `id`, below | +| `outputs` | Expected final files and typed reconstruction actions, below | +| `saveCompatibility` | `{status, notes}`; status `unknown`, `new-save-required` or `compatible`; guidance up to 2,000 characters | + +FNV is the full support target. Skyrim SE/FO4 remain in development. Fallout 3 can appear only as an owned input to TTW; it cannot be the target. Starfield is not accepted. Schema acceptance does not certify a game or list. + +### Owned games + +Each requirement is `{id, store, files}`. `store` is `steam` or `gog`. `files` contains 1–10,000 `{path, bytes, sha256}` records and must include that game's executable. The requirement set is exactly the target game for a base recipe, or FNV plus Fallout 3 for TTW. A recipe represents one exact accepted storefront/file set; a different version requires a different recipe. The specification does not claim ownership can be established from a file hash alone. + +These references instruct the materializer to read a user's local input. They grant no permission to bundle or mirror game content. TTW conversion, patching and version alternatives need additional typed operations and acceptance before native TTW installation can be claimed. + +### Local prerequisites + +An optional `prerequisites` array declares 1–20 `{id, name, version, instructions, credit, files}` records. IDs follow the source-ID syntax and are unique within the array. Names/versions are nonempty text up to 500 characters. `instructions` is a public HTTPS reference without credentials/query/fragment, never fetched or executed automatically. `credit` uses the source attribution shape. Each `files` array locks exact `{path, bytes, sha256}` records, with the same safe-path rules as owned inputs. Across prerequisites the limits are 100,000 files and 10 TB. + +The user selects an existing folder for each prerequisite. Every locked file is checked before output creation, and source folders cannot overlap the destination. A `prerequisite-file` source copies a declared local file with an identical hash and byte length. Every prerequisite must supply at least one used source. This can represent a separately prepared dependency without bundling or mirroring its bytes. It is not proof of ownership, distribution permission or automated TTW conversion; the TTW variant still requires both owned games independently. Actual TTW integration remains unaccepted. + +### Sources + +Every source has `id`, `type`, `bytes` and lowercase 64-character `sha256`. + +| Type | Additional fields | +| --- | --- | +| `game-file` | `game`, `path`; must match the path/hash/size of a locked requirement file | +| `prerequisite-file` | `prerequisite`, `path`; must match a file in that declared local prerequisite | +| `nexus-archive` | `game`, positive integer `modId`, positive integer `fileId`, `credit` | +| `https-archive` | `url`, `credit` | +| `payload` | `credit`, `permission`; exactly one corresponding container entry | + +Nexus `game` is `falloutnv`, `fallout3`, `skyrimspecialedition` or `fallout4`. Credentials and download tokens are resolved at runtime, never stored in a recipe. A `credit` is `{name, url}`. A payload's `permission` is `{license, evidence}`, with a nonempty license description up to 200 characters and an HTTPS evidence reference. URL fields reject credentials, query parameters and fragments to exclude typical signed links and tokens; human privacy review remains necessary. + +Every source must be used. Bundled hashes cannot be declared twice. Sources do not contain private local paths. The desktop's [archive acquisition layer](native-downloads.md) enforces network destination, redirect and account policy separately; accepting an HTTPS string is not permission to fetch arbitrary endpoints. + +### Outputs and actions + +Copy/extract outputs are `{path, bytes, sha256, action}`, optionally with `mtimeMs`. A generated MO2 configuration instead uses `{path, action}` with destination-specific fingerprinting as described below. File paths use `/`, are relative NFC strings up to 240 characters, and reject Windows device names, drive/UNC paths, alternate data streams, traversal, empty segments, trailing dots/spaces and reserved characters. Windows case-insensitive duplicates and file/directory overlap are rejected. Paths containing a `saves` component or a component starting `.loadstone` are reserved. + +`mtimeMs` declares the output's last-modified time as integer UTC milliseconds since the Unix epoch, from `0` through `4102444800000` (2100-01-01). Use it when metadata affects behavior, such as timestamp-ordered Bethesda plugins. It applies only to copy/extract outputs, never their inputs or generated MO2 configuration. The installer sets it after reconstructing and hashing a fresh file, then verifies the stored timestamp rounded to the nearest millisecond. A filesystem that cannot represent it fails verification. Archive-member timestamps are not implicitly imported, and creation/access times are not recipe identity. + +Full recipe verification and build recovery require both the declared bytes/hash and timestamp. A timestamp-only change becomes a recovery/repair conflict: preserve the old file before replacing it, and retain it during removal. Repair's existing default of preserving personal configuration still applies; explicitly restoring configuration is needed to recover its recipe metadata. Normal launch retains its existing executable/profile safety checks and does not perform full recipe verification. Omission preserves legacy behavior and canonical recipe identity. Adding the field creates a new recipe fingerprint; earlier readers reject the unsupported field rather than silently ignoring it. + +- `{type: "copy", source: "source-id"}` copies a `game-file`, `prerequisite-file` or `payload`. Expected output bytes/hash must equal the input. +- `{type: "extract", source: "archive-id", member: "Data/Example.esp"}` selects one safe member of a locked Nexus/HTTPS archive. The output hash is the hash of the extracted member. It never recursively interprets extracted bytes. +- `{type: "extract-bsa104", source: "archive-id", container: {member: "Data/Example.bsa", bytes: 12345, sha256: "<64 lowercase hex characters>"}, member: "meshes/example.nif"}` explicitly selects one internal member of a BSA-104 container within a locked Nexus/HTTPS ZIP, 7z or RAR download. The container has its own exact size/hash; the output locks the inner file's exact uncompressed size/hash. Both member paths follow the canonical recipe path rules. A recipe may use at most 64 distinct containers totaling 20 GB of staging data; each container is 36–4,294,967,295 bytes and each inner output is at most 1 GB. Conflicting declarations for the same container are rejected. Only the [documented BSA-104 subset](bsa-inspection.md) is accepted. This is exactly one declared container level; direct owned-game BSA inputs, BSA writing, BA2, BSA 103/105, arbitrary nested archives, FOMOD execution, binary patches and arbitrary text substitution remain unsupported. +- `{type: "mo2-config", gameEdition: "Steam", executables: [...]}` generates only `ModOrganizer.ini` from bounded, relative executable declarations and recipe game/launch fields. `gameEdition` accepts `Steam` or `GOG` matching the target game requirement; executable entries may declare `steamAppId` matching the supported target game and its Steam requirement. Both fields are optional for legacy recipes, whose exact generated bytes remain unchanged. It has no source or static output fingerprint. The materializer computes the exact destination-specific bytes/hash before writing and records them in the receipt after verification. An empty, fingerprinted `portable.txt` output is required. See the [complete generator contract](native-mo2-configuration.md), including serialization, size bounds and unsupported settings. + +Outputs must include `ModOrganizer.exe`, `ModOrganizer.ini`, the declared profile's `modlist.txt` and `plugins.txt`, and the target game executable beneath `launch.gameRoot`. Mod priorities, disabled entries and plugin order are carried by the exact profile files. Where the manager/game derives order from modification times, declare the corresponding winning plugin timestamps too. Neither order nor timestamps are inferred from source order. Final-file verification checks each static or derived output fingerprint after reconstruction. Save paths may never be claimed as owned recipe outputs. + +## Creator commands + +Place reviewed bundled files in a private directory, named by their SHA-256 hashes. A recipe with no payloads can use an empty directory. Commands never replace an existing package: + +```powershell +node scripts/native-package.mjs pack recipe.json private-payloads example.loadstone +node scripts/native-package.mjs inspect example.loadstone +``` + +The compiler validates and hashes all bundled bytes, creates the output exclusively, and re-inspects the finished archive. Changed inputs or mismatched hashes fail. It refuses output paths inside the payload directory. Keep personal inventories, local manifests and unreviewed packages under ignored `test-results/`; do not commit them. + +## Next implementation gates + +The [experimental native materializer](native-reconstruction.md) reconstructs copy, ZIP/7z/RAR-extract and explicitly declared BSA-104 recipes in an isolated directory and verifies every output hash. The desktop guide and creator tools use this materializer; reconstruction does not establish playability. + +Complete installed-file/source mapping; add bounded reconstruction for edited/generated files; verify real provider downloads and extend supported source flows; extend durable creator jobs with partial-build recovery and playable-library integration. Preserve the existing launch/shortcut/removal ownership checks. Prove actual clean installation and gameplay before publishing the three featured recipes or assigning 1.0. + +--- + +# Native reconstruction + +Canonical source: `docs/native-reconstruction.md` + +The native materializer creates the exact outputs of a validated `.loadstone` recipe from local owned-game files, local prerequisites, ZIP/7z/RAR archives and permitted bundled payloads. The desktop can [acquire declared original archives](native-downloads.md), and the materializer can [generate bounded MO2 configuration](native-mo2-configuration.md) for the new destination. Players can use [guided installation in Discover](native-guided-install.md); creator tooling remains available through the CLI and Settings. Completed candidates can be explicitly admitted to the [native library](native-library.md) for launch and shortcut controls. Reconstruction itself does not perform TTW conversion, apply arbitrary transforms, migrate all profile/tool settings or launch a game. Do not advertise a playable featured list from a fixture result. + +## Desktop creator workflow + +Switch to the live workspace and open Settings → Reconstruct a local candidate. Select the package, its private local-inputs JSON (described below), and an existing parent directory. Review the recipe name, output count, storage requirement and newly generated destination. **Build candidate** starts input verification and reconstruction; the renderer cannot supply a replacement path or arbitrary recipe. The main process binds the reviewed recipe fingerprint to the materializer. + +If the inputs include 7z/RAR archives or request downloads, select a trusted local **7-Zip x64 26.04 or newer** `7z.exe` with its matching `7z.dll`. Downloads are conservatively prepared for any supported archive signature; a ZIP download still uses the built-in ZIP reader. The review shows the selected version. The app retains the tool identity between review and build and rejects changes. Cancelling this picker creates no job. Recipes and private-input files cannot nominate an executable; selection is through the native picker. No 7-Zip binary is bundled, automatically downloaded or installed. + +Progress and cancellation appear in Downloads and this Settings card. Success says **Files verified · Launch untested**. Downloads offers **Review for My library** for the exact completed folder. Native candidates are not automatically registered or given shortcuts; explicit library review is separate. Native builds, library verification, other installations/removal and engine preparation cannot start over one another; the close guard keeps Loadstone open until selection/build/cancellation finishes. + +Active builds distinguish archive acquisition, source-file checks, archive-structure checks, writing outputs and final-file verification. The display shows completed files within the current stage and bytes in the current file, so large files can show activity before a file-count increment. Writing every output does not finish the build: final hashes must still pass. Byte updates are throttled; these are measured counts, not an overall time estimate. The local-only CLI reports materializer phase changes and bounded periodic activity without source paths. Reading/validating the package itself still precedes this phase reporting. + +Phase activity exists only in memory and is absent from persisted build history and diagnostic exports. Restarted builds keep the existing interrupted-state behavior, rather than presenting stale phase progress as active work. Cancellation and failure still preserve any partial candidate. + +`native-builds.json` in the local app-data folder retains up to 100 build records, including destination, recipe fingerprint, progress and status. It contains no credential, source archive paths, local-input map or raw tool output and is excluded from diagnostic exports. Invalid/newer history is preserved and refused, rather than silently reset. Active records become `interrupted` after restart without resuming work. Cancelled, failed and interrupted candidates offer [explicit recovery review](native-build-recovery.md): reselect the same recipe and inputs, reuse matching files and retain conflicts before rebuilding them. Resume updates the same history entry. [Native version updates](native-updates.md) use a separate candidate; build-history management remains unfinished. Failed writes or external history changes stop new work and require restart. + +## Local command + +```powershell +node scripts/materialize-native.mjs candidate.loadstone private-inputs.json C:\LoadstoneReview\NewCandidate +# Include this explicit operator-selected tool for 7z/RAR inputs: +node scripts/materialize-native.mjs candidate.loadstone private-inputs.json C:\LoadstoneReview\NewCandidate --sevenzip C:\Tools\7-Zip\7z.exe +``` + +The destination's parent must already exist; the destination itself must not. The private JSON input file has two maps: `games` maps each required game ID to its installed source folder; `archives` maps each archive source ID from the recipe to a locally downloaded ZIP, 7z or RAR file. When the recipe declares local prerequisites, add a `prerequisites` map from each prerequisite ID to its prepared source folder. All declared prerequisite files are hashed before reconstruction; the app never runs the instructions URL or a conversion program. Paths must be absolute. Keep this file under ignored `test-results/` and do not publish it. It contains no Nexus credentials or runtime command arguments. + +For example, a private input file can contain: + +```json +{ + "games": { "fnv": "C:/OwnedGames/Fallout New Vegas" }, + "archives": { "example-source": "C:/ModDownloads/example.zip" } +} +``` + +These example paths are illustrative. The executable, required game files and archives must match the actual recipe's byte lengths and SHA-256 hashes; having a folder with the expected name is insufficient. Storefront/license eligibility remains a separate release requirement. + +In the desktop workflow only, an archive map value may instead be `null` to request acquisition of that recipe source. Every source ID must still appear exactly once; omitted or extra IDs are rejected. The CLI remains local-only. See [original-source downloads](native-downloads.md) for cache, network and membership behavior. + +## Data preservation and verification + +All requirements and archive hashes are checked before creating the installation directory. ZIP, 7z, RAR4 and RAR5 inputs are recognized by their signatures, allowing mislabeled original filenames without renaming them; signatures never replace hash or structural validation. Archive paths, links, duplicate/colliding names, encrypted/unsupported entries, required members and declared sizes are checked in advance. Available destination space must cover expected outputs, recipe metadata and a 64 MB reserve. Archive inventories are limited to 500,000 entries and 100 GB declared uncompressed content; local archives are bounded to 50 GB. + +For upstream ZIP sources, backslashes are normalized to forward slashes before structural checks and during extraction, matching the source mapper's member paths. Mixed-separator aliases, case collisions and file/directory overlaps are rejected before creating a destination. Recipes still use canonical `/` member paths, and native `.loadstone` package entries retain strict naming. Original archives are read unchanged; this compatibility rule does not permit arbitrary path cleanup or remove traversal checks. + +7z/RAR reconstruction uses the same validated adapter as [source comparison](installed-inventory.md). The external tool runs without a shell and emits file content to stdout; it never receives output paths. Loadstone waits for disk writes before reading more data, checks exit status and input identity, and closes the child before reporting failure or cancellation. Tool diagnostics do not enter build history. 7-Zip 26.04 with `zlib.crc32` uses one pass for eligible 7z archives with per-member CRCs and at most 20 GB total content. Every boundary, including unselected members, is CRC-checked. Up to 100,000 selected members are supported in that pass. Other versions, RAR and ineligible 7z archives read each selected member with literal selectors: at most 10,000 members and 20 GB selected content per archive. This fallback can be slow for solid archives. Single-pass extraction has a five-minute limit; fallback reads have a ten-minute limit per member. These are experimental creator limits, not general archive support guarantees. + +Destinations cannot overlap selected game inputs, source archive/package folders, the selected tool directory, the application, system folders or additional protected roots supplied by the caller. Redirected directories are rejected; existing destinations require a separate bound recovery review in the desktop builder. New directory creation is exclusive; output files use exclusive creation. The materializer never modifies source game files or downloads, executes archive content or writes save paths. + +Each output stream is bounded and hashed, then all final files are re-hashed before success. Static outputs use recipe fingerprints; generated MO2 configuration uses the destination-specific fingerprint computed before writing. The new directory contains `.loadstone-recipe.json` and `.loadstone-native.json`. The receipt records the recipe fingerprint, generated-configuration fingerprints when present, progress and one of `materializing`, `verified`, `failed` or `cancelled`. `verified` means reconstructed bytes matched the static or derived expectations; `launchVerified` remains false. + +Cancellation or failure retains the candidate directory and receipt. A hard process kill may leave a `materializing` receipt and an incomplete file; desktop history marks the build interrupted after restart. [Resume review](native-build-recovery.md) checks retained bytes, preserves conflicting files in a unique recovery folder and revalidates every final output. The writer does not recursively delete failed setups or continue automatically after a restart. + +These checks supplement standard Windows access controls; they are not a sandbox for an actively hostile process racing filesystem changes. Keep source files and the new destination settled during reconstruction. + +## Nested BSA 104 files + +An explicit `extract-bsa104` action can reconstruct loose files from a BSA container inside an original ZIP, 7z or RAR source. The recipe independently locks the outer archive, its BSA member and the final inner file. The installer validates the complete outer archive structure, stages only the declared containers, verifies their full hashes, and checks every BSA member and selected output before creating or changing installation files. Ordinary `extract` actions keep their direct-member meaning. + +Staging uses one new directory beneath the operating system's temporary directory and numbered files, never archive-supplied filesystem paths. Up to 64 containers and 20 GB of staging bytes are accepted per recipe. The temporary volume needs the declared container bytes plus a 64 MB reserve; destination space is checked separately. Each container follows the [BSA reader's format and decompression limits](bsa-inspection.md). A compressed or shared member is streamed through an awaited consumer, then the installation writer verifies its exact output bytes/hash and applies any declared timestamp. No archive code runs. + +Handled success, cancellation and failure close the readers/writers and remove the operation's ordinary staging files. Cleanup checks directory/file identity, performs no recursive deletion and preserves changed or unfamiliar staging contents. A hard process termination can leave temporary containers behind; restarting builds new staging after a fresh source/recovery review and does not blindly purge earlier temporary folders. Failed installation outputs and user data retain the existing receipt/recovery behavior. Resume reuses verified outputs; repair preserves conflicts and personal configuration through the same review path as other actions. + +Synthetic tests cover ZIP, solid 7z and RAR5 outer archives, mixed direct/nested outputs, compressed/empty/shared BSA members, exact timestamps, invalid containers and inner members, unsafe trailing archive entries, resource limits, failed staging writes, cancellation, resume and repair. Actual Electron tests exercise reviewed ZIP and RAR5 reconstruction through the bridge and are also run against the staged executable. The CLI inventory remains evidence only; automatic nested-source ledger mapping is separate work. + +## Acceptance remaining + +Complete real provider-download acceptance, conversion, profile/tool configuration reconstruction, real version-update and maintenance acceptance. Creator reconstruction is exercised through real Electron with original synthetic ZIP, solid 7z and stored RAR5 inputs, including cancellation, failed writes and tool replacement. The RAR5 fixture is generated from the [published format](https://www.rarlab.com/technote.htm), without third-party archive contents or encoder code. Clean-machine installation and gameplay acceptance remain unfinished. The separate package inspection card stays read-only. + +Completed candidates with generated portable MO2 configuration may be explicitly reviewed and registered in the [native library](native-library.md). Registration adds launch and shortcut controls after file and local-profile checks. Separate [removal review and confirmation](native-maintenance.md) limits deletion to unchanged recipe files and retains user data; these controls do not certify gameplay. + +--- + +# MO2 configuration + +Canonical source: `docs/native-mo2-configuration.md` + +Experimental creator support: a `mo2-config` action generates a new `ModOrganizer.ini` bound to the chosen candidate folder. It does not import an existing INI, copy account settings, run MO2 or certify a playable list. Existing copy/extract recipes remain supported unchanged; older Loadstone builds reject this new action. + +## Recipe declaration + +This is the only output kind without a static `bytes`/`sha256` pair or a source reference: + +```json +{ + "path": "ModOrganizer.ini", + "action": { + "type": "mo2-config", + "gameEdition": "Steam", + "executables": [ + { + "title": "New Vegas", + "binary": "Game/FalloutNV.exe", + "workingDirectory": "Game", + "steamAppId": "22380" + } + ] + } +} +``` + +There must be 1–64 entries. Titles are unique without regard to case, trimmed, well-formed text of 1–100 characters without controls. Each binary is a safe, relative, declared `.exe` output. Its working directory is its exact relative parent, or `.` for an executable at the candidate root. The entry whose title exactly matches `launch.executable` must be under `launch.gameRoot`. The recipe must also declare an empty `portable.txt` output with the SHA-256 of zero bytes. A file cannot shadow `downloads`, `mods`, `profiles`, `overwrite` or `webcache`. + +An entry may optionally declare 1–16 arguments as `[{"type":"path","path":"Game/Data"}]`. Each path must name a declared output or an ancestor directory (or `.` for the candidate root). They are bound to the destination and individually quoted for Windows command-line argument boundaries. This supports Explorer++ opening the local virtual game-data folder without retaining a creator path. Arbitrary literal arguments/flags, INI keys, scripts, environment variables and external paths are unsupported. Supporting an entry does not run it during reconstruction. + +### Game edition + +New recipes should declare `gameEdition` as `Steam` or `GOG`, matching the `store` on the requirement for `game.id`. For TTW this is the New Vegas requirement, even when the Fallout 3 requirement uses another store. Other values and mismatched stores are rejected. This writes `General/game_edition` so MO2 can select the edition without its first-run dialog. Launch checks reject a changed or missing declared edition; Qt rewriting its quoted value is accepted. + +The field is optional only for compatibility with existing recipes and reconstruction receipts. Omitting it preserves the original generated bytes exactly and can leave MO2 asking for an edition at first launch. It does not silently upgrade an existing candidate. Recipes using the field have a different canonical fingerprint and are rejected by older Loadstone implementations. Build a new candidate from the revised recipe; retain any existing saves and configuration. This declaration does not certify GOG runtime support or convert game files between stores. + +### Executable Steam app ID + +An executable may declare `steamAppId` as a string matching Loadstone's supported target game: `22380` for New Vegas/TTW, `489830` for Skyrim SE or `377160` for Fallout 4. The target game's requirement must use `store: "steam"`; TTW's Fallout 3 requirement does not determine this value. Other IDs, numbers, empty values and GOG requirements are rejected. Regional app IDs are not supported by this declaration. + +This writes that executable's `steamAppID` setting for MO2's Steam launch context. The field is optional to preserve existing generated bytes and receipts. Adding it changes the recipe identity and requires a new candidate; it does not change an existing receipt or grant game ownership. Native launch rejects a changed or missing declared app ID. A private TTW check found this setting in the installed baseline but absent from earlier generated configuration; actual launch and recording outcomes are tracked in the [acceptance record](native-steam-acceptance.md). + +## Deterministic rendering and verification + +The canonical recipe fingerprint locks all generator inputs. Before creating a destination, the materializer renders UTF-8/LF configuration for that absolute Windows drive path and computes the resulting exact byte length and SHA-256. Stream verification and the final on-disk pass use this derived fingerprint. The receipt's `generatedConfigurations` array records `{path, generator, bytes, sha256}` without embedding the destination. Static copy/extract outputs retain their existing exact fingerprint contract. A `mo2-config` output cannot also declare a static fingerprint: rendered bytes depend on the destination. + +The generator produces these sections in order, with a blank line between sections and a final LF: + +- `General`: game name (`TTW`, `New Vegas`, `Skyrim Special Edition` or `Fallout 4`), local game path, selected profile, `first_start=false`, then `game_edition` as a quoted Qt string when declared. +- `Settings`: local base, downloads, mods, profiles, overwrite and webcache paths; `profile_local_inis=true` and `profile_local_saves=true` defaults. +- `customExecutables`: array size, then each entry's title, local binary, local working directory and arguments (empty when omitted, otherwise a space-separated sequence of quoted local paths), followed by `steamAppID` when declared, preserving declared entry order. + +Paths use `/`. Qt string values are double-quoted, escape backslash and quote, and double a leading `@`. Game path and selected profile use `@ByteArray(...)` with every UTF-8 byte encoded as lowercase `\xNN`. The implementation in `electron/native-mo2-config.cjs` defines the exact serialization; byte changes require a new generator action identity, not a silent change to an existing recipe's meaning. + +Generated files are limited to 1 MB. Package inspection reserves that allowance in `installBytes` and exposes `generatedConfigurations`; the desktop explains the allowance. Destinations for this action are limited to local Windows drive paths of 2,048 characters without controls or literal `%BASE_DIR%`, which MO2 would interpret as a variable. Normal materializer protection, exclusive creation and cancellation rules still apply. Required empty MO2 state directories are created inside the candidate. A cancelled or failed candidate is retained. + +## Scope and acceptance + +This creates a fresh manager configuration. It does not preserve personal interface preferences, plugin-specific settings, external tools, account data or recent directories. Any behavior required by a featured baseline must be identified and modeled before claiming equivalence. Existing profile `settings.ini`, game INIs, plugin configuration and tools needing literal arguments/flags still require review. In particular, the defaults above do **not** prove that an existing profile uses local saves: profile-specific flags can override defaults. Native candidates remain **Files verified · Launch untested**, outside the playable library. + +Absolute paths are deliberately bound at installation. Moving a finished candidate does not automatically update them; rebuild into a new destination until relocation/repair is implemented. This action does not patch arbitrary existing text, transform mods, convert TTW, download sources or create shortcuts. + +Path and executable semantics were checked against the [ModdingLinked MO2 settings implementation](https://github.com/ModdingLinked/modorganizer/blob/9c130cb/src/settings.cpp), [MO2 executable loading](https://github.com/ModOrganizer2/modorganizer/blob/master/src/executableslist.cpp), and [Qt INI serialization](https://github.com/qt/qtbase/blob/6.7/src/corelib/io/qsettings.cpp). The original generator does not copy upstream implementation code. MO2's mod-directory setting is `mod_directory` (singular); installed inventory now honors it. + +MO2's [process launcher](https://github.com/ModdingLinked/modorganizer/blob/9c130cb/src/spawn.cpp) uses the executable's Steam app ID for its child environment. Native launch validation reads the required General, Settings and customExecutables sections, retaining strict alias/duplicate/path checks. Unrelated plugin and UI section values are left alone, including MO2's normal `Python%20Proxy` persistence key. Profile validation reads its General section separately. + +Tests cover different destinations, non-ASCII and INI delimiter encoding, invalid references and fields, final-file tampering, destination refusal and the real Electron review/build/restart workflow. Inventory and existing launch-layout checks decode the generated UTF-8 byte arrays and quoted strings; unrelated binary INI state is not decoded or exported. A private interoperability check also read synthetic generated configuration through Qt 6.7.1's actual `QSettings`, including UTF-8 byte arrays, literal `@`, quoted delimiters and executable arrays. This verifies serialization, not MO2 launch or gameplay. + +--- + +# BSA inspection & mapping + +Canonical source: `docs/bsa-inspection.md` + +The experimental creator command reads a local **BSA version 104** container and produces a private inventory of its normalized member names, exact uncompressed sizes and SHA-256 hashes: + +```powershell +node scripts/inspect-bsa.mjs C:\CreatorCache\original.bsa C:\CreatorReports\bsa-inventory.json +``` + +Choose a new report outside the archive's directory. The command never extracts payload files, executes content or modifies the archive. Ctrl+C cancels without a final report. Keep reports private: member names can disclose installed content even though the report omits the local archive path. + +The archive itself is hashed before inspection. All index, member, decompression and input-stability checks must pass before a report is returned. Exact shared data extents are supported; partially overlapping extents and conflicting compression declarations are rejected. Embedded filename blobs are validated but are not used as member paths: optimized archives may share one blob across several indexed names. Names use canonical forward slashes; duplicate/case-colliding paths, traversal, Windows special names and file/directory overlap are rejected. + +This initial reader accepts the version-104 layout used by Fallout 3/New Vegas: a 36-byte header, folder/file name tables, printable ASCII names, optional zlib compression, per-file compression toggles and optional embedded names. It accepts archive flag bits `0x01`, `0x02`, `0x04`, `0x80` and `0x100`, with both name tables required. Other layouts/flags, non-ASCII names, BSA 103/105, BA2 and archive writing are unsupported. Rejection means the reader cannot safely inspect that variant, not that the game archive is necessarily corrupt. + +Limits: 4,294,967,295 input bytes, 64 MiB metadata, 100,000 folders, 500,000 files, 1 GB per uncompressed member, 20 GB total logical member content (including shared copies) and five minutes per inspection. Hashing streams have bounded buffers; declared sizes, zlib input consumption and output counts are verified. The reader uses the same open file handle throughout and checks file identity afterward. + +This report is **source evidence only**. It does not change the ZIP/7z/RAR ledger or automatically produce a recipe. To establish an upstream source chain, separately verify the outer download archive, its exact BSA member hash and the desired internal member hash. Compare the installed file's complete size/SHA-256; a similar name or image is insufficient. A reviewed recipe can use the explicit [`extract-bsa104` action](loadstone-format.md#outputs-and-actions) for [bounded nested-BSA reconstruction](native-reconstruction.md#nested-bsa-104-files). Transformed-file reproduction, rights review and real installation acceptance remain separate work. No game or mod data is bundled by this command. + +The JavaScript implementation and synthetic fixtures are original. Format semantics were checked against Wabbajack's pinned [104/105 reader](https://github.com/wabbajack-tools/wabbajack/blob/4.2.3.0/Wabbajack.Compression.BSA/TES5Archive/Reader.cs), [folder records](https://github.com/wabbajack-tools/wabbajack/blob/4.2.3.0/Wabbajack.Compression.BSA/TES5Archive/FolderRecord.cs) and [file records](https://github.com/wabbajack-tools/wabbajack/blob/4.2.3.0/Wabbajack.Compression.BSA/TES5Archive/FileRecord.cs). Loadstone deliberately supports a narrower format subset. + +## Nested source mapping + +The separate creator command extends a private [source ledger](installed-inventory.md) with exact nested matches: + +```powershell +node scripts/map-bsa-sources.mjs private-mapping.json new-private-bsa-mapping.json --mod "Example container mod" --7zip C:\Tools\7-Zip\7z.exe +``` + +Repeat `--mod` for other exact inventoried mod names. The selected mods must contain inventoried `.bsa` files and have original archive candidates in the ledger. Disabled mods can supply containers without being enabled. The optional `--7zip` is required for 7z/RAR candidates; ZIP comparison uses the built-in reader. No tool or original archive is downloaded by this command. + +The mapper independently rehashes each selected original archive and validates its complete structure. It hashes candidate BSA members and compares their full size/SHA-256 with the installed BSA inventory. Only then does it inspect the matching local BSA, rechecking the complete container fingerprint and hashing its internal contents. The local file is a read-only witness of the verified original member; nothing is staged or extracted. It compares inner content with all managed mod-file fingerprints in the accepted ledger, including disabled mods, and excludes local `meta.ini`. It does not rehash every loose installed target during this pass, nor map game/root/profile/overwrite records. + +Each matched file receives a separate `bsaSourceMatches` array. A reference records `archiveSha256`, `container: { member, bytes, sha256 }`, the inner `member` and the number of byte-equivalent inner members (`equivalentMembers`). The representative is the lexicographically first normalized inner path per container and content fingerprint. The original archive's fingerprint and available provider hints appear in `bsaMapping.sources`; provider hints still require review. These references supply the fields for a reviewed `extract-bsa104` action once a recipe source ID is assigned. They do not generate or approve a recipe. + +Existing `sourceMatches`, the direct `mapping` report, mod states and other inventory records remain intact. `bsaMapping` separately reports nested matches, newly matched files and the combined unique file totals. Re-running the command replaces the nested extension from fresh checks without multiplying old references. A fresh direct archive-mapping pass clears the old nested extension, which must then be recomputed. Failed archives or containers produce unresolved issues; no partial matches from a failed inspection are accepted. + +Limits: 64 selected containers, 20 GB total container bytes, 20 GB combined successfully inspected logical content, 1,000 candidate archive paths and 500,000 nested match references, in addition to the existing archive/BSA reader limits. ZIP and per-member 7z/RAR comparison retain their 1 GB member limit; eligible 7z archives can use the existing bounded single-pass reader for larger members. Other BSA versions and arbitrary nesting remain unsupported. + +The command locks the input ledger, referenced inventory and optional source hints, checks them again before writing, refuses existing report paths and keeps reports outside installation/download roots. Ctrl+C cancels without a final report. Reports contain private paths and installed-content names: keep them outside public source. Matching bytes establish source evidence only; source rights, typed transformations, recipe validation and actual reconstruction/gameplay acceptance remain required. + +--- + +# Live catalog manifests + +Canonical source: `docs/manifests.md` + +Discover in live mode supports importing a local JSON manifest. Place the original `.wabbajack` archive beside it (or in a declared subfolder). Loadstone keeps manifest metadata in its local `live-catalog.json`; it does not redistribute the archive or its mods. Imports remain separate from demo installations. + +Schema 1 requires these fields, with unknown fields rejected: + +- `schemaVersion`: `1`; `id`: a stable lowercase slug (3–64 characters). +- `name`, `version`, `description`, `author`, `website` (HTTPS). +- `game`: `id` (`fnv`, `skyrimse`, or `fallout4`), `versions` (human-readable labels), `executableHashes` (supported lowercase SHA-256 values), `requiredFiles` (relative file paths and their `sha256`, including required DLC masters). +- `storage`: positive integer `downloadBytes` and `installBytes`, including temporary space needed by the list. These are author declarations; preflight checks available space against their combined total. +- `archive`: relative `file` ending in `.wabbajack`, `sha256`, and original HTTPS `source`. +- `launch`: `manager: "mo2"`, `profile` (a single directory name), `executable` (MO2 executable title), and optional `gameRoot` (a relative folder within the installed profile, such as `Stock Game`). No shell commands or installation recipes are accepted. +- `credits`: entries with `name`, `author`, HTTPS `source`, and a `license` or distribution-permission statement. Declared permissions require human review before public distribution. + +Preflight streams file hashes, checks required game files and archive integrity, rejects game/system/Loadstone folder overlap and nonempty destinations, and checks writability and free disk space. It does not create an install or modify the game. Steam discovery reads local library and app metadata and confirms the executable exists; it does not assert ownership from an install directory. GOG and other installations can be selected manually. + +Installation requires the verified engine, successful live preflight and source access. A valid manifest alone does not make a setup installable. No real curated list is bundled yet. + +Preflight also reads the archive's actual `modlist` metadata. It checks game identity, required engine version, MO2/profile output files, bounded sizes, safe and unique Windows output paths, and declared storage against the archive's totals. Unknown download providers and lists requiring additional games are identified as unsupported. A verified engine is asked which game folder it would use; a different selection blocks installation rather than silently using another copy of the game. + +The parser was checked against the locally cached Viva New Vegas 11.8.26 archive: 153 source archives and 17,630 output files. The pinned 4.2.3.0 CLI was also run to confirm its actual Fallout 4 and New Vegas selections. These are read-only compatibility checks, not evidence of a successful installation or permission to redistribute the list. + +The pinned [Wabbajack install command](https://github.com/wabbajack-tools/wabbajack/blob/4.2.3.0/Wabbajack.CLI/Verbs/Install.cs) accepts `-w/--wabbajack`, `-o/--output`, and `-d/--downloads`. The runtime and command interface are verified; protected authentication and durable job recovery are implemented; full real-list installation acceptance remains outstanding. + +## Updating an imported setup + +Keep the same stable ID and use a different version label. Add optional schema-1 metadata (required when replacing an imported version): + +```json +"update": { + "fromVersions": ["1.0"], + "saveCompatibility": "new-game-required", + "notes": "Start a new game. Keep version 1.0 for existing saves." +} +``` + +Allowed compatibility values are `compatible`, `new-game-required`, and `unknown`. These are creator declarations, not Loadstone guarantees. Notes must explain the migration requirements. Version labels are opaque: Loadstone does not infer ordering from dates or semantic versions. Reimporting the same version is rejected, including altered archives; publish a new version instead. A game change under the same ID is rejected. + +Import presents the old/new versions, creator/source and save guidance for confirmation, then checks the manifest has not changed before saving. Existing jobs retain their own manifest snapshots. Install a replacement in a separate empty folder; Loadstone keeps the prior profile, settings, saves and custom mods available for rollback. It does not migrate saves or customizations automatically. Installed versions appear in Library. Older failed jobs retry their owned archive using their original manifest, even after the catalog changes. If that archive is missing and the original manifest is no longer imported, restore the exact owned archive before retrying. + +## Isolated game layouts + +A creator can declare an existing Wabbajack Stock Game layout: + +```json +"launch": { + "manager": "mo2", + "profile": "My setup", + "executable": "New Vegas", + "gameRoot": "Stock Game" +} +``` + +The Wabbajack list must itself build and configure that layout. Adding this field does not copy a game, run a patcher or convert an existing list. Archive preflight requires the supported game's executable among the declared outputs under that folder. Completion, profile checks, launch and shortcut creation require the installed folder and game executable to exist without redirection, MO2's General/gamePath to resolve to that folder, and the selected launch entry to point inside it. Missing, duplicated or mismatched gamePath settings fail verification. Ordinary, quoted and backslash-escaped @ByteArray path forms are recognized. + +This follows the upstream [Stock Game authoring model](https://wiki.wabbajack.org/modlist_author_documentation/Keeping%20the%20Game%20Folder%20clean.html): game preparation belongs in the creator's compiled list and must be validated for the selected storefront. Patches, required plugins and clean-machine gameplay still need acceptance evidence; a directory match does not prove those requirements. + +The field is optional for existing schema-1 manifests and saved installations. Its absence preserves legacy behavior and makes no isolated-layout guarantee. The cached Viva New Vegas candidate is not a Stock Game list; merely adding gameRoot causes preflight to reject it. A suitable creator-authored variant and actual install-to-play acceptance remain required for one-click support. + +--- + +# Development guide + +Canonical source: `handbook/pages/development.md` + +The desktop app uses Svelte 5, TypeScript, Vite and Electron. Native installation and packaging target Windows x64. The handbook is a separate static Svelte application using the same locked toolchain; its build is not included in the desktop bundle. + +## Set up the repository + +Use Node.js 22 or later and pnpm 11 or later. Install the committed lockfile, then run diagnostics and the application: + +```powershell +pnpm install --frozen-lockfile +pnpm check +pnpm start +``` + +Do not point development or test state at a real playthrough. Automated fixtures use temporary directories. `LOADSTONE_DATA_DIR` isolates app state, but does not redirect Desktop or Steam integration by itself. + +## Find the implementation + +| Area | Entry point | +| --- | --- | +| Desktop UI | `src/App.svelte`, native workflow components and `src/styles.css` | +| Shared brand | `public/brand/mark.svg`, consumed by `src/Logo.svelte` and asset generators | +| Process boundary | `electron/main.cjs` and `electron/preload.cjs` | +| Demo state | `electron/store.cjs` | +| Native recipe validation | `electron/native-format.cjs` | +| Package inspection | `electron/native-package.cjs` | +| Reconstruction | `electron/native-materializer.cjs` and archive/BSA adapters | +| Creator evidence | `electron/installed-inventory.cjs`, `source-ledger.cjs`, `archive-mapping.cjs`, `bsa-mapping.cjs` | +| Handbook | `handbook/`, its source catalog and `scripts/handbook.mjs` | +| Verification | `tests/`, including actual Electron workflows | + +Keep filesystem access, credentials and process creation in the main process. The renderer receives a limited typed bridge. Validate IPC arguments and preserve unrelated files throughout failure and recovery paths. + +## Run checks + +```powershell +pnpm check +pnpm test +pnpm handbook:check +pnpm handbook:test +git diff --check +``` + +Some archive tests require a trusted 7-Zip executable selected through `LOADSTONE_TEST_7ZIP`; CI prepares a pinned tool. An optional external-runtime test may skip without its prerequisite. Report skips and real acceptance gaps explicitly. For a native behavior change, use the relevant actual Electron path as well as unit fixtures. + +## Build artifacts + +`pnpm package` prepares the unsigned portable Windows preview. `pnpm package:steam` prepares a separate unpacked Steam depot preview. Both rely on generated notices and build provenance. They do not upload a release. Read [preview packaging](../../docs/private-preview.md) and [Steam packaging](../../docs/steam-release.md) before handing off an artifact. + +## Finish a change + +Keep the implementation, regression coverage and canonical documentation together. Regenerate the handbook agent edition with `pnpm handbook:sync`. Review public files and media for private information, then use the contribution/PR workflow. A code merge does not certify a public stable release or approve publishing a setup. + +--- + +# Repository overview + +Canonical source: `README.md` + +**Your next playthrough, ready.** + +A Windows developer preview of a curated Bethesda modlist installer, built with Svelte 5, TypeScript, and Electron. A carved copper mark, charcoal panels and original illustrative artwork carry Loadstone's visual identity. + +![Loadstone Discover](docs/screenshots/discover.png) + +The screenshot records an earlier preview. Current source uses the refined [shared brand mark](handbook/pages/brand.md). + +## Windows preview + +Build the current **0.4.0 native installation preview** with `pnpm package`, then run `release/Loadstone-0.4.0-Windows.exe`. The portable executable needs no Node.js, pnpm or installation wizard to run. It is unsigned and has not been published as a new hosted release. The existing private v0.1.0 release is the older demo-only build. See [private preview packaging](docs/private-preview.md) for isolated output folders, exact source archives and verification. + +## Run locally + +Requires Node.js 22+ and pnpm 11+. + +```powershell +pnpm install +pnpm start +``` + +```powershell +pnpm check # Svelte and TypeScript diagnostics +pnpm test # State-engine tests and real Electron end-to-end tests +pnpm package # Portable Windows x64 executable in release/ +``` + +To test the actual packaged application and portable wrapper: + +```powershell +$env:LOADSTONE_TEST_EXE = "$PWD\release\win-unpacked\Loadstone.exe" +node --test tests/electron.test.mjs +Remove-Item Env:\LOADSTONE_TEST_EXE +node scripts/verify-portable.mjs +``` + +See [the review checklist and verification notes](docs/review.md). + +## Handbook + +Run `pnpm handbook:dev` and open **http://127.0.0.1:4174** for the local Svelte handbook. It includes player setup and recovery guides, creator workflows, the native format, architecture, release status and contribution guidance, with local search and mobile navigation. `pnpm handbook:build` creates a static site in `handbook/dist/`; `pnpm handbook:preview` serves it locally. These commands do not publish it. + +The site reads canonical Markdown directly. Start with [the handbook](handbook/pages/welcome.md), [the repository agent guide](AGENTS.md), or the [complete generated agent edition](handbook/agents.md). After documentation changes, run `pnpm handbook:sync`, then `pnpm handbook:check` and `pnpm handbook:test`. See [handbook maintenance](handbook/pages/documentation.md). + +## Review the MVP + +1. Browse Discover; filter by game or search for a setup. +2. Open setup details, then Install setup. Choose an installation plan and start the demo. +3. Pause, resume, cancel, or retry in Downloads. A complete demo takes approximately 20 seconds. +4. Open My library to launch a demo session, verify the simulated profile, or remove it. +5. On first run, choose **Set up real installations**, then **Open .loadstone** in Discover. The guide requests the package’s games, source archives and prepared files; local-only packages need no Wabbajack engine or Nexus connection. Wabbajack setups use the separate manifest import and engine in Settings. Choose **Explore the demo** for the fictional catalog. Switch modes later with **Use dummy data** in Settings. Your choice, reduced motion, shortcut preferences, and folder selection persist. +6. Export a privacy-conscious diagnostic summary or reset the demo workspace from Settings. Raw installation output remains local in Downloads. + +The demo catalog, requirements, installation sizes, profile validation, launch, and shortcut creation are simulated. Demo mode does not download mods, launch game processes, change game files, or modify Steam. Turning demo mode off prevents demo mutations in the main process as well as hiding sample data in the renderer. + +Current source also supports a separate live manifest catalog, Steam game discovery, manual game selection, SHA-256 compatibility checks, destination/storage preflight, and a Wabbajack installation runner with saved jobs, cancellation and retry. See [manifest requirements](docs/manifests.md) and [installation behavior and limits](docs/installation.md). Controlled process tests pass; a full real modlist installation has not yet been verified. Live library launch, profile checks, and desktop/Steam shortcut creation and repair are implemented. Steam integration still needs actual-client acceptance testing. The existing v0.1.0 release predates these features. + +Settings now prepares a pinned official Wabbajack runtime, with download/cancel/repair controls, archive and full runtime integrity checks, and a real CLI capability check. See [runtime integration notes](docs/runtime.md). Preparing the engine does not install a modlist. + +Settings also validates a Nexus personal API key for private testing, stores it with Windows encryption, and displays account membership and the last verification time. [Account integration notes](docs/nexus.md) describe credential handling and installation requirements. This is not yet a registered public Nexus application. + +Creator tooling can [inventory an installed MO2 setup and compare original archives](docs/installed-inventory.md) without changing it and [compile or inspect the documented native `.loadstone` package format](docs/loadstone-format.md). **Settings → Native package preview** checks a selected package and shows its required games, sources, profile and save guidance. **Reconstruct a local candidate** reviews private local inputs, optionally [acquires declared original archives](docs/native-downloads.md), and builds copy and ZIP/7z/RAR-extract recipes into a new folder with final-file hashing, cancellation and durable history. Recipes can [generate MO2 configuration for that destination](docs/native-mo2-configuration.md) without importing account data. [Native reconstruction](docs/native-reconstruction.md) remains experimental: real provider/account acceptance, complete profile/tool configuration, real repair/launch acceptance is unfinished. Verified candidates can be explicitly reviewed and registered through [My library → Add native candidate](docs/native-library.md), with recipe verification, isolated-profile launch and Desktop/Steam shortcut controls. [Native removal](docs/native-maintenance.md) preserves saves, configuration, modified files and untracked content in a recovery folder and supports retry. [Interrupted builds can be reviewed and resumed](docs/native-build-recovery.md), reusing matching files and retaining conflicting files before reconstruction. Native updates can build a [separate version](docs/native-updates.md), retaining the original playthrough. Actual install-to-play and version-to-version gameplay acceptance remain unfinished. The featured lists are not publication-ready. + +Players can now use **Discover → Open .loadstone** for [guided native installation](docs/native-guided-install.md): select owned games, prepared prerequisites and original archives without creating an inputs JSON. Downloads shows measured progress, cancellation and resume, then offers explicit review of the completed folder for My library. This uses the same builder and verification rules as the creator tools. Draft selections last until app restart; gameplay and provider/client acceptance remain open. + +The [real TTW acceptance record](docs/native-steam-acceptance.md) now includes direct launch to the main menu and a verified Steam game-recording export after a normal Steam restart. Gameplay, save/reload, controller and clean-machine acceptance remain unfinished. See [Steam startup guidance](docs/native-library.md#steam-game-startup) for the observed load error and recovery steps. + +[Manual Nexus downloads](docs/native-manual-downloads.md) open each declared file page in the default browser and verify the downloaded original before selection, with byte progress and cancellation. Browser mode tracks pending files and requires all Nexus selections before installation review; existing cache files can be explicitly checked too. Automatic Nexus downloads still require fresh Premium access. Real account/website acceptance and public API registration remain open. + +Recipes can also [reconstruct exact loose files from BSA 104 containers](docs/native-reconstruction.md#nested-bsa-104-files) inside original ZIP/7z/RAR downloads. Each archive, container and inner file has an explicit fingerprint; temporary staging, cancellation, resume and repair preserve the existing installation checks. The [BSA mapper](docs/bsa-inspection.md) records exact nested-source chains in private creator ledgers. Generated-content reproduction and complete featured recipes remain unfinished. + +## Persistence and desktop behavior + +**My library → Repair native setup** now offers [same-version native repair](docs/native-repair.md). It keeps matching files, restores missing/damaged recipe outputs, retains replaced originals and preserves existing profiles/configuration by default. A separate option restores recipe configuration too. Interrupted repairs require fresh review and keep library launch disabled. [Install another version](docs/native-updates.md) creates a separate setup with fresh recipe settings, preserving the original playthrough. Real gameplay acceptance remains open. + +Settings and demo state live in `%APPDATA%\Loadstone\state.json` in the packaged app. Active demo installs are restored paused after a restart. Disabling demo mode preserves its state and pauses its jobs. Resetting demo data preserves preferences. Unreadable demo state is backed up before recovery. Live jobs are saved separately in `live-jobs.json`; interrupted live installations require a Windows restart before retry. Native Windows folder/save dialogs, window controls, a single-instance guard, and offline artwork are included. + +For isolated automated testing, set `LOADSTONE_DATA_DIR` to a dedicated directory. Never point it at a directory whose files you need to preserve. + +## Architecture + +- `src/`: Svelte interface, catalog, styling, and typed desktop bridge. +- `electron/main.cjs`: native window, validated IPC, dialogs, and state notifications. +- `electron/preload.cjs`: limited context-isolated bridge; no arbitrary filesystem/process access. +- `electron/store.cjs`: persistent simulated installation state machine. +- `electron/manifest.cjs`, `game-discovery.cjs`, `live-catalog.cjs`: live setup validation, local game discovery, and filesystem preflight. +- `electron/installer.cjs`: durable live jobs, engine process control, credential handoff, and structural profile verification. +- `tests/electron.test.mjs`: real Electron workflows and backend invariants. +- `public/worlds.png`: original AI-generated triptych for the three fictional setups. +- `public/brand/mark.svg`: shared editable mark for the app, handbook and generated artwork. +- `scripts/create-icon.mjs`: desktop SVG/PNG/ICO generator using the locked Electron renderer. +- `handbook/`: local Svelte documentation site and generated agent edition. + +Real install-to-play, Steam-client and save-preservation acceptance remain necessary before a public installer release. [The 1.0 acceptance plan](docs/1.0-plan.md) tracks the complete release requirements, including open-source documentation, license review and notices. + +## Distribution + +Loadstone's original source code is publicly available under **GPL-3.0-or-later**: GNU GPL version 3 or, at your option, any later version. See the full [license](LICENSE) and [copyright/scope notice](COPYRIGHT). Public source availability does not certify a supported binary release or grant rights to game files and third-party mods. No Wabbajack or MO2 application source is incorporated in this preview; third-party packages retain their respective licenses. The portable Windows preview is unsigned and is not a Steam release. + +See [contributor setup](CONTRIBUTING.md), [security reporting](SECURITY.md), [privacy and local data](docs/privacy.md), and [open-source publication gates](docs/open-source.md). New packages carry Loadstone's license and scope notice under `resources/licenses/`, alongside generated [third-party notices](notices/THIRD-PARTY.txt) and the [dependency inventory](notices/dependencies.json). The About screen displays the license offline. The shipped dependency inventory currently has no missing license texts. It covers bundled renderer code, main-process dependencies and Electron; excluded build tools, artwork/branding and distribution rights still require review. Licensing Loadstone does not license third-party mods or game files. + +For a separate unpacked Windows Steam depot preview, run `pnpm package:steam`. See [Steam packaging and acceptance](docs/steam-release.md) for file verification, packaged-executable tests, templates and remaining submission gates. This command does not upload or publish. + +See [0.4.0 release notes](CHANGELOG.md) for implemented creator/live features and outstanding release gates. + +--- + +# Contributing + +Canonical source: `CONTRIBUTING.md` + +Loadstone is a public source project under active development, with original source licensed under **GPL-3.0-or-later**. See [LICENSE](LICENSE) and [COPYRIGHT](COPYRIGHT) for the terms and scope. By submitting a contribution to the covered code or documentation, you agree to license that contribution under the same terms and confirm that you have the right to do so. Preserve third-party attribution and identify externally sourced material. No copyright assignment is required. Release acceptance and a monitored confidential security-reporting channel remain unfinished. + +## Public repository boundary + +Commit only Loadstone source, reusable synthetic fixtures and reviewed public documentation. Keep private workspace orchestration, unrelated project code, operational account details, personal installation inventories and raw acceptance evidence outside this repository. Review changes to files, screenshots, commit messages, pull-request descriptions and release attachments for that boundary before pushing. Sanitizing the current tree does not remove earlier public versions; see the [history audit](docs/publication-audit.md). + +## Development on Windows + +Install Node.js 22 or later and pnpm 11. Clone the repository, then run: + +```powershell +pnpm install --frozen-lockfile +pnpm check +pnpm test +pnpm start +``` + +The lockfile is authoritative. Commit deliberate dependency updates and regenerated notices together. Electron and esbuild installation scripts are allowed through `pnpm-workspace.yaml`; do not enable unrelated build scripts to bypass a failure. + +Tests start actual Electron windows and use temporary workspaces. They use synthetic credentials and installation fixtures. They must not download a real modlist or modify a developer's game, Desktop, or Steam library. `LOADSTONE_DATA_DIR` isolates app state, but does not redirect Desktop or Steam operations; native integration tests explicitly redirect or inject those paths. + +## Change workflow + +Use a feature branch and a focused pull request. Explain the user-visible problem, final behavior, validation and remaining limits. Run `pnpm check`, `pnpm test`, and `git diff --check`. For native behavior, exercise the real Electron bridge; mocked process fixtures alone do not prove a game works. Add regression tests for data-loss risks, persistence failures and process boundaries. Do not introduce tests that merely repeat presentation code. + +Keep filesystem/process access in the main process. Validate IPC input, preserve unrelated files and entries, and keep secrets out of renderer state and diagnostics. Manifest imports must not add arbitrary shell recipes. Use original upstream downloads and retain attribution; do not commit game files, downloaded mods, personal manifests, keys, signed URLs or raw user logs. + +## Documentation + +The local Svelte handbook reads the canonical documents in this repository. Run `pnpm handbook:dev` to browse it. Keep behavior, support status, examples and recovery guidance current in the same change as the implementation. Add new documentation to `handbook/catalog.mjs`, then run `pnpm handbook:sync` and commit the regenerated `handbook/agents.md`. Run `pnpm handbook:check` and `pnpm handbook:test` before merging. CI checks coverage, links, agent-edition freshness and the built site's navigation/search behavior. See [the documentation guide](handbook/pages/documentation.md) and [AGENTS.md](AGENTS.md). + +The handbook uses an explicit public-source allowlist. Never expand it to scan parent workspaces or publish private operational evidence. Building the static site does not authorize deployment. + +## Notices and packaging + +```powershell +pnpm notices +pnpm package +``` + +Notice generation first builds the UI, then combines rendered dependency modules, generated Vite runtime attribution, the installed main-process production graph and the Electron license. Frontend packages are development dependencies because their runtime code is bundled; their notices still ship. The bundle provenance file carries original license texts without machine paths. Review changes to `notices/` before committing. Packaging includes that directory, Loadstone's GPL text and copyright/scope notice in application resources and retains Electron/Chromium notices. The current portable package is unsigned; it is not the Steam depot build. See [the acceptance plan](docs/1.0-plan.md) and [publication checklist](docs/open-source.md). + +Do not treat a passing fixture suite as completion of install-to-play acceptance. Record the exact game, list, engine and application versions for real release validation. + +Builds embed the Git commit, dirty-worktree flag and lockfile SHA-256 in `dist/build-info.json`. The lockfile hash uses UTF-8 with CRLF normalized to LF so Windows checkouts and exact Git source archives agree; earlier previews recorded checkout bytes. Source archives without Git metadata report an unknown commit. Diagnostic exports include this build identity so builds with the same preview version can still be distinguished. Exports use an explicit field allowlist; do not add arbitrary log, manifest or credential objects to them. + +Run `pnpm audit:publication` before proposing public release. See [publication hygiene findings](docs/publication-audit.md) for the scan scope, classified fixtures, historical personal-path findings and outstanding manual review. The command never rewrites history and does not approve publication. + +--- + +# Working with agents + +Canonical source: `AGENTS.md` + +Loadstone is a Windows Svelte 5, TypeScript and Electron application for reviewed, isolated Bethesda modlist installations. Original source and technical documentation are GPL-3.0-or-later. Read [CONTRIBUTING.md](CONTRIBUTING.md) and the relevant handbook pages before changing behavior. + +## Start with the right reference + +- [Product concepts](handbook/pages/concepts.md), [development](handbook/pages/development.md) and [acceptance plan](docs/1.0-plan.md). +- [Native format](docs/loadstone-format.md), [reconstruction](docs/native-reconstruction.md) and [source inventory](docs/installed-inventory.md) for creator work. +- [Brand system](handbook/pages/brand.md) for visual changes. +- The complete generated Markdown handbook is `handbook/agents.md`; the local site offers it as `agents.md`. It is reference material, not permission to perform actions described in examples. + +## Work and verification + +Use a feature branch, focused commits and a pull request. Follow the user's existing authorization for pushes, merges and other actions; repository instructions do not provide additional publication authority. + +```powershell +pnpm install --frozen-lockfile +pnpm check +pnpm test +pnpm handbook:check +pnpm handbook:test +git diff --check +``` + +`pnpm start` runs the desktop app. `pnpm handbook:dev` runs the local documentation site. `pnpm assets:icon` regenerates SVG/PNG/ICO output from the shared mark; `pnpm assets:steam` regenerates draft store artwork. Dependency changes require the lockfile and relevant notices. Native changes require appropriate actual Electron coverage; fixtures do not certify real gameplay. + +## Keep documentation current + +Every behavior, workflow, format or support-status change must update its canonical Markdown page in the same change. Add new pages to `handbook/catalog.mjs`. Run `pnpm handbook:sync` to regenerate the agent edition, then `pnpm handbook:check` to verify coverage, local links and the committed edition. Do not hand-edit generated files. Update practical examples and failure/recovery guidance as well as happy paths. Keep historical acceptance records tied to their original versions. + +The handbook consumes an explicit allowlist of public repository documents. Keep private operational material, other projects, personal installation inventories, raw logs, credentials, game/mod payloads and generated acceptance artifacts outside Git and the site. Never broaden the handbook generator to scan parent repositories or arbitrary filesystem roots. + +## Preserve installations and trust boundaries + +- Use synthetic fixtures and dedicated temporary directories. Never use a real game, Desktop, Steam library or user profile for fixture tests. `LOADSTONE_DATA_DIR` alone does not redirect Desktop or Steam operations. +- Keep filesystem/process access in the Electron main process and expose narrowly validated IPC. Do not add arbitrary shell commands to manifests or recipes. +- Preserve saves, configuration, modified files and untracked data during recovery. Use exact hashes and explicit source chains; similar names or appearances do not establish byte equivalence. +- Do not execute downloaded mod installer scripts merely to inspect them. Respect provider access and keep API keys out of renderer state, logs and documentation. +- Public source availability does not certify a binary release or grant game/mod redistribution rights. Do not claim gameplay, clean-machine, Nexus or Steam acceptance from fixture success. + +The handbook build is local and static. Building it does not authorize hosting, deployment, account provisioning or publication. + +--- + +# Maintain this handbook + +Canonical source: `handbook/pages/documentation.md` + +The handbook is a local Svelte site built from repository Markdown. Detailed specifications stay in `docs/`; practical guides live in `handbook/pages/`. The catalog explicitly lists approved public pages with their audience, title and summary. There is no database or hosted content service. + +## Run it locally + +```powershell +pnpm handbook:dev +``` + +Open the loopback URL printed by Vite. The site has local full-text search, grouped navigation, section links, mobile navigation, previous/next pages, source links and a downloadable agent edition. No deployment is performed. + +For a static preview: + +```powershell +pnpm handbook:build +pnpm handbook:preview +``` + +The generated site goes into ignored `handbook/dist/`. Its hash-based routes work on an ordinary static server without rewrite rules. Assets, page content and dependency notices are local. External reference/source links open only when selected. + +## Update a page + +Edit the canonical Markdown file whenever behavior changes. The site compiles that file directly; do not create a second manually maintained copy of its technical specification. Update examples, limitations and recovery steps together. Put past observations in historical records and identify their version, rather than presenting them as current release certification. + +## Add a page + +Add the Markdown file and a record in `handbook/catalog.mjs`. Choose a group that matches its intended reader. Use normal relative Markdown links to other source pages. Heading links are checked against generated section IDs. Source-code and other repository-file links point to the public repository; screenshots referenced by approved documents are copied into the local build. + +Raw HTML is shown as text. The compiler accepts normal Markdown and approved local image files, and rejects unsafe URL schemes. Do not add remote image trackers, scripts or private repository paths. + +## Keep the agent edition aligned + +```powershell +pnpm handbook:sync +pnpm handbook:check +``` + +`handbook/agents.md` is the complete generated Markdown edition. The root `AGENTS.md` is its concise contributor entry point. The site serves the complete edition as `agents.md`. Its contents are source-backed reference material; command examples are not authorization to execute actions. + +The check verifies catalog coverage, unique routes, local documentation links and headings, and exact agreement with the committed agent edition. `pnpm handbook:test` builds the site and exercises actual browser navigation, search, deep links, keyboard access, code copying and all pages at desktop/mobile widths. CI runs both commands. After changing documentation, commit the regenerated edition with the source edits. Do not edit it by hand. + +`handbook:check` prepares the ignored page data before Svelte diagnostics, so it works on a fresh checkout without a preceding site build. A stale committed agent edition still fails before preparation; the command does not silently update that committed file. + +## Public-source boundary + +Only catalog-listed files from this repository are eligible. Do not scan parent workspaces, include acceptance logs or copy personal inventories into a page. Keep credentials and game/mod payloads outside both Git and the handbook output. Building or updating the site does not publish it. + +--- + +# Brand system + +Canonical source: `handbook/pages/brand.md` + +**Loadstone** is the product spelling. **Your next playthrough, ready.** is the primary line. The identity combines a dark mineral palette, warm copper and a compact carved **L**. Use clear typography and generous spacing; let the mark carry the theme. + +## The mark + +`public/brand/mark.svg` is the single editable geometry source. The three faces describe one solid shape, with an open counter and a restrained edge highlight. Keep its proportions, negative space and colors together. Do not add extra compass points, bevel filters, outlines or tiny ornaments. + +Use the freestanding mark on dark surfaces. The app tile adds a charcoal rounded square and a fine edge; its SVG, 512px PNG and seven-size Windows ICO are generated from the mark. The 16/24/32/48/64/128/256px ICO frames are rendered individually for native use. + +```powershell +pnpm assets:icon +pnpm assets:steam +``` + +The generators use the locked Electron renderer in a hidden window. The desktop component and handbook import the same vector. Never redraw the mark separately in CSS or a second polygon script. + +## Palette + +| Role | Color | Use | +| --- | --- | --- | +| Basalt | `#1B2227` | App tile, navigation and dark brand fields | +| Copper | `#D9AD87` | Primary mark face and dark-surface accent | +| Cut edge | `#A97652` | Restrained shadow face | +| Light edge | `#F0CFAD` | Small highlighted face | +| Paper | `#F7F5F0` | Handbook reading surface | +| Ink | `#263036` | Text on paper | + +Copper used for the mark is not automatically suitable for small text on a light background. The handbook uses darker accent text for contrast, visible keyboard focus and underlined prose links. + +## Typography and tone + +Use the system UI family, led by Segoe UI on Windows. The wordmark uses normal title case, a medium/semibold weight and tight but readable spacing. Body copy should be calm, concrete and direct. Avoid all-caps slogans, exaggerated tracking and claims that turn development targets into finished support. + +## Asset review + +Inspect the icon at actual small sizes on light and dark backgrounds, in the app header and in a staged executable. Check Steam crop previews before submission. Store artwork remains draft until its review; a generated capsule is not evidence of a playable setup. Existing screenshots and recordings retain their capture version and should not be silently relabeled after a visual refresh. + +Source licensing and artwork/trademark scope are described in [artwork provenance](../../docs/artwork.md) and [COPYRIGHT](../../COPYRIGHT). This visual refinement does not change those terms. + +--- + +# Verification checklist + +Canonical source: `docs/review.md` + +This build includes the live installer and maintenance features developed after the original demo. It is unsigned and remains a private developer preview. A real supported install-to-play run, clean Windows/Steam acceptance, Nexus registration and distribution/asset license review are still required before public release. Original source is licensed under GPL-3.0-or-later; new builds include its license offline. + +## Walkthrough + +1. Start with a fresh test workspace. The welcome screen offers live setup or the fictional demo; neither starts a download automatically. +2. Explore the demo: Discover filters/details, install planning, Downloads pause/cancel/retry, Library actions, settings persistence and reduced motion. Demo activity must remain separate from live state. +3. In the live workspace, prepare the pinned engine in Settings and import a compatible creator manifest/archive. Check the game and destination. Failed compatibility or account checks must prevent installation. +4. Connect Nexus only through Settings in your local app. Do not put keys in chat, manifests or reports. Lists requiring automatic Nexus downloads currently need Premium, and a conflicting saved Wabbajack login must be resolved in that application. +5. With an accepted real list, exercise download/install, failure/retry, output verification, profile launch, shortcut repair, version coexistence and save-preserving removal. These are required acceptance steps, not a claim that they have already passed. +6. Export diagnostics and confirm build identity. Ordinary closes during installation, removal or engine preparation should keep the operation visible and offer minimization. Idle closes should exit cleanly. +7. In Settings, inspect a native package, then reconstruct a synthetic local candidate with the matching private inputs JSON. Confirm the new destination and prerequisite summary before starting. Check cancellation, restart history and **Files verified · Launch untested**; build completion must not automatically add a library entry. Explicitly review/register a launchable synthetic candidate in My library; check restart persistence, save isolation, file changes, redirected folders and fixture-only Desktop/Steam shortcuts. No synthetic executable may be run. Use fixtures outside real game, Desktop and Steam folders. + +For current source with native downloads, also review the source hosts/cache/bytes for an archive input set to `null`. Exercise acquisition, hash failure, cancellation, verified-cache reuse and final reconstruction. Keep fixture network responses synthetic; separately record any real provider/account acceptance. Never put a key or signed URL in a recipe. The older recorded 0.3.0 binary does not contain these later changes. + +The existing VNV archive needs additional game preparation. Read [the real preflight findings](vnv-acceptance.md) before using it as an acceptance candidate. An isolated-layout declaration does not convert an archive into a Stock Game list. + +## Reproduce package verification + +Run `pnpm check`, `pnpm test`, then `pnpm package` from a clean commit. Set `LOADSTONE_TEST_EXE` to `release/win-unpacked/Loadstone.exe` and run the complete staged-executable test selection in `.github/workflows/windows.yml`, including native installation, library, repair, version updates and manual downloads. Clear that environment variable, then run `node scripts/verify-portable.mjs` to exercise the actual self-extracting executable. The script derives its filename/version from package metadata and checks the full license and scope offline. It records the artifact's SHA-256, size and checked workflows under ignored `test-results/`. Optional package/evidence directory arguments preserve previous artifacts; see [private preview packaging](private-preview.md). + +Use a dedicated `LOADSTONE_DATA_DIR` for manual review. This isolates settings and credentials, but does not redirect Desktop or Steam operations. Automated shortcut tests use explicit temporary targets. Do not point a test workspace at data you need to preserve. + +The original [0.1.0 review](review-0.1.md) is historical evidence for the demo-only release. Its screenshots and claims do not certify the newer live installation features. See [Steam depot verification](steam-release.md) for the separate directory build and actual-client acceptance requirements. + +For native removal, use synthetic candidates and redirected Desktop/Steam fixtures. Exercise review cancellation, explicit confirmation, modified/untracked-file preservation, failure before the durable record, interrupted removal and restart/resume, blocked shortcut cleanup and retry. Verify source-game and save canaries remain unchanged; never use a live candidate for destructive fixture acceptance. + +For native build recovery, interrupt a synthetic build, restart, select the same recipe/inputs and review resume. Dismiss first and verify no candidate changes. Confirm reuse without rewriting matching files, retained copies of conflicts, untouched untracked/save canaries and one persistent history entry. Test changed metadata/roots/files after review, redirected folders, failed input verification, a failed write after a conflict was retained, repeated cancellation and ZIP/7z/RAR reconstruction. Final verification must still hash every output. Actual games and managers remain closed; no fixture executable is run. + +For guided native installation, use Discover → Open .loadstone with synthetic owned-game discovery and native pickers. Verify required inputs, changed selections invalidating review, original-download/local-archive choices and no JSON-file requirement. Confirm Downloads tracks cancellation and guided resume in the same job/folder. Review the completed folder for My library, cancel admission first, then confirm and verify restart persistence. The draft must disappear after restart while completed history and library entries remain. Run `tests/native-guide-electron.test.mjs` against both local Electron and the staged executable; no synthetic executable may be launched. + +For installed native repair, modify/delete synthetic recipe outputs and add save/configuration canaries after registration. Review the exact original recipe, verify preservation defaults and confirm repair. Check retained originals, unchanged matching-file identities, save/profile preservation, explicit configuration restore, cancellation, failed writes after retention and restart recovery. Fail final state persistence and ensure launch stays disabled until a fresh review succeeds. Run `tests/native-repair-electron.test.mjs` against local and staged Electron. Real installed setups may be reviewed read-only; never use them for destructive fixture acceptance. + +For native version updates, register a synthetic setup, change its configuration and add a save canary. Select a different version of the same setup, verify both version labels and new save guidance, then build and admit the independent candidate. Assert the complete original tree and entry remain unchanged, the new version uses fresh recipe settings and no copied saves, and both entries survive restart. Reject mismatched setup/game/variant, same-version packages, overlapping destinations and changed original metadata/registry. Cancel or fail the new build and resume its exact candidate without touching the old version. Run `tests/native-update-electron.test.mjs` against local and staged Electron. Real version-to-version gameplay and save compatibility remain separate acceptance. + +For manual Nexus downloads, use synthetic archives and intercept the browser opener. Verify exact game/mod/file routing, default browser mode without Premium, pending counts, wrong-length/hash rejection, cancellation with unchanged previous selection, explicit cache reuse and rechecking changed bytes at installation. Reject arbitrary URLs, undeclared sources and stale drafts. Run `tests/native-manual-electron.test.mjs` locally and against the staged executable. The intercepted opener does not replace a separate real authorized Nexus website/account/download acceptance. + +--- + +# Path to 1.0 + +Canonical source: `docs/1.0-plan.md` + +The target is a usable Windows Player Tool that installs, maintains, and launches a curated Bethesda setup from original download sources. A polished dummy catalog alone does not satisfy this goal. Version 1.0 will only be assigned after the real install-to-play path and the release requirements below are proven. + +## Required product behavior + +1. Loadstone can distinguish demo and live workspaces, with no simulated checks masquerading as real installation results. +2. A versioned setup manifest identifies a real game, supported versions/DLC, source downloads, hashes, author credits, license information, required storage, and the intended launch profile. Imports cannot execute arbitrary shell recipes. +3. A real installation adapter validates the selected game, destination, disk space, engine, and authenticated source access. Download/install progress reflects actual work; interruptions have an explicit recovery path. +4. A completed install is verified against the produced profile. The library launches the correct real MO2 profile/script extender. Desktop and local Steam shortcuts work and can be repaired without replacing unrelated entries. +5. Removal is limited to owned setup files, with save preservation by default. Updates declare save compatibility and preserve user choices or offer a recoverable fresh install. +6. Nexus credentials stay local and protected, never appear in logs, and follow membership restrictions. A public application needs Nexus registration; developer testing access must not be advertised as approved public access. +7. The Windows package has reproducible build instructions, versioned state migration, diagnostics, privacy/support documentation, license notices, and passing real Electron tests. The Steam depot build is distinct from the portable local preview. +8. A clean Windows review verifies at least one real supported game/list end to end, including restart, failed download/retry, launching, shortcuts, maintenance, and removal. Fixture tests supplement this review; they cannot replace it. +9. The repository is ready for an open-source release: accurate public-facing README, reproducible contributor setup, contribution and security-reporting guides, support expectations, dependency and asset license inventory, required third-party notices, and a reviewed project license. GPL-3.0-or-later was selected for original source on October 13, 2026; LICENSE, COPYRIGHT, package metadata and contribution terms record it. Review actual code reuse, corresponding-source delivery, runtime distribution, fonts, icons, and artwork against the final artifact. Check tracked files and Git history for credentials, personal data, and private-only material before publication. Repository visibility changes require an explicit publication request. + +## Implementation sequence + +- State integrity, transactional persistence, corruption/downgrade protection, bounded input validation, failure handling, and repeatable Windows CI. +- Real manifest and game-discovery layer; local list import; explicit preflight results. +- Investigate Wabbajack CLI authentication and install invocation against the current upstream build. Use the actual supported interface, rather than guessing CLI flags or hiding an external GUI as a completed integration. +- Installation adapter, durable live jobs, verification, launch and shortcuts. +- Maintenance and release packaging; clean-machine validation and Steam submission materials. +- Open-source release preparation once the application is stable: documentation, licensing/provenance review, notices, contributor guidance, and publication hygiene. + +## External release dependencies + +Nexus registration requires a working testing build. Valve reviews the product and store presence. Any bundled mods, generated assets/patches, upstream tool components, and branding need suitable distribution rights. These are tracked release gates, not a reason to leave independent implementation work undone. + +Sources: [Wabbajack CLI](https://wiki.wabbajack.org/wabbajack_cli/Commands.html), [Nexus API policy](https://help.nexusmods.com/article/114-api-acceptable-use-policy), [Steam review process](https://partner.steamgames.com/doc/store/review_process). + +## Work policy + +Changes go through feature branches, pull requests, relevant checks and review, then merge to main. Keep progress pushed and review public changes for private operational context and unrelated project material. + +## Real-list acceptance finding + +[Viva New Vegas acceptance evidence](vnv-acceptance.md) records real game/list/runtime preflight and the remaining authentication and game-preparation gaps. A list engine finishing is not sufficient when the creator requires root-file installation or patching. Model and verify those steps before claiming launch-ready, one-click support; a previously configured game installation cannot establish clean-machine acceptance. + +The [Steam submission draft](steam-submission.md) records proposed store copy, claim gates, asset requirements and the reviewer handoff. Its preparation does not close the real acceptance gates above. + +## Expanded native release scope (2026-10-13) + +The expanded release target adds the following requirements to the original acceptance gates; they are not completed by the 0.2.0 preview: + +1. Develop a documented native `.loadstone` format and open implementation from the currently installed TTW, FO3 Remastered and customized New Vegas setups. [Inventory and format direction](installed-inventory.md) defines the first evidence-gathering step. Preserve the live installations and ongoing saves. +2. Implement reproducible native installation, local owned-game reconstruction, source resolution and exact installed-file verification. Assess Wabbajack, Nexus and MO2 interoperability on their actual formats and permissions. +3. Prepare Loadstone-maintained featured lists from those installed versions, including credits, rights-reviewed assets, tested recipes and publication. Distinguish Loadstone's support from endorsement by Bethesda, TTW, Nexus or the original list authors. +4. Target support: Fallout 3 standalone unsupported (defer to TTW); Fallout: New Vegas fully supported; Fallout 4 and Skyrim supported in development; Starfield unsupported but planned. These are product targets; do not mislabel untested paths as release-certified. +5. Investigate paid storage for permitted content. Game ownership and DRM-free delivery alone do not establish rights to operate shared game mirrors. No provider procurement is implied by choosing an architecture. +6. Deliver a reliable 1.0 release candidate for open-source Git distribution and Steam, satisfying the original rights, authentication, clean-machine, installation, maintenance and actual-client gates. +7. Produce release copy/assets, a development roadmap with an appealing visual presentation, and a short application showcase trailer using truthful product footage. Inventory scripts and fixture tests are not substitutes for this media or product acceptance. + +Keep this public repository focused on Loadstone implementation, contributor documentation and sanitized release evidence. Private operational coordination and unrelated projects belong outside it. Public source availability does not close the binary-release acceptance gates above. + +--- + +# Changelog + +Canonical source: `CHANGELOG.md` + +## Unreleased + +- Refine the shared Loadstone mark, Windows app icon, header typography and draft Steam artwork. The app, handbook and asset generators use one editable SVG source. +- Add a local Svelte handbook with 43 source-backed pages, full-text search, responsive navigation, section links and code copying. A concise root `AGENTS.md` and generated complete agent edition keep contributor guidance aligned with the documentation; CI checks freshness, coverage, links and browser workflows. No site is hosted or published by these commands. + +- First-run setup opens Discover directly for native .loadstone installation. Welcome, engine settings and Wabbajack empty states now explain which prerequisites belong to each installation path. +- Native MO2 executable declarations can retain the target game's Steam app ID without changing legacy receipts. Relaunch validation accepts unrelated plugin persistence keys written by MO2 while retaining checks on launch paths, profile isolation and declared executable settings. +- Native MO2 recipes can declare a Steam or GOG edition matched to the target game requirement, avoiding MO2's edition-selection dialog. Launch checks protect the declared edition. Legacy recipes retain their original configuration bytes and receipts. +- The first real TTW Steam-client check verified candidate admission, the running-client safeguard, shortcut preservation and launch to the main menu after manually selecting an edition. Steam produced no recording file; gameplay, save/controller acceptance and an uninterrupted launch from a revised recipe remain open. See [the acceptance record](docs/native-steam-acceptance.md). +- A separate full-size TTW version passed guided reconstruction and 13,952-file library admission. Its edition prompt is resolved, but direct launch reaches a Steam load error, including a diagnostic with the baseline's explicit Steam app ID. No footage or gameplay acceptance is claimed; the acceptance record retains both results and the remaining client checks. + +## 0.4.0 — native installation preview + +- Guided `.loadstone` installation in Discover: select owned games and local prerequisites, review destination and sources, then follow measured progress in Downloads. +- Original HTTPS and Nexus archive acquisition, verified cache reuse, browser handoff for manual Nexus downloads and cancellable local-file verification. Real provider/account acceptance remains required. +- ZIP/7z/RAR reconstruction, destination-bound MO2 configuration and expanded installed-baseline inventories and source mapping. 7z/RAR operations require an operator-supplied trusted 7-Zip tool; it is not bundled. +- Resume interrupted builds, explicitly admit verified candidates to My library, and create Desktop/Steam shortcuts for isolated profiles. +- Same-version repair with retained originals and configuration preservation; separate-folder version updates; reviewed removal retaining saves and user changes. Each workflow includes interruption/recovery checks. + +- Adopt GPL-3.0-or-later for Loadstone's original source, with the full license, explicit scope and contribution terms. New packages and the About screen include the license offline; third-party notices remain intact. +- Recognize archive contents independently of cached filenames, preserving original names and bytes. ZIP reconstruction and ZIP/7z/RAR source comparison retain full hash and structural checks. +- Allow large members in the verified single-pass 7z mapper within its existing 20 GB total stream limit. + +This is an unsigned private Windows preview. No playable featured pack is bundled. Fixture tests and the private full-size TTW file comparison do not certify gameplay, real Nexus downloads or Steam-client behavior. Public registration, clean Windows install-to-play, featured-pack source/rights completion, publication review and final release materials remain open. The older 0.3.0 executable and video retain their original provenance. + +## 0.3.0 — native creator preview + +- Documented experimental `.loadstone` format, strict validator, deterministic compiler and bounded package inspection. +- Read-only installed MO2 inventories, private source ledgers and exact ZIP/7z/RAR member comparison. Eligible solid 7z archives are checked in one bounded stream. +- Native reconstruction from owned games, locked local prerequisites, original ZIP archives and reviewed bundled payloads into a fresh directory. +- Settings package preview and a local candidate workflow with review, cancellation, final output hashing, durable history and explicit interrupted-build handling. +- Windows state-write retries and a corrected ASAR verification fixture that waits for archive writing to finish. + +This is an unsigned local creator preview, not 1.0 or a public release. Native builds require a prepared private inputs JSON. Native source downloads, 7z/RAR reconstruction, configuration rebasing, partial-build repair and native launch/shortcuts are unfinished. TTW conversion and the three featured lists have not passed installation, gameplay or publication acceptance. Licensing, Nexus registration and Steam-client gates remain open. Existing game installations and saves are preserved. + +## 0.2.0 — local developer preview + +Implemented since the demo-only 0.1.0 release: + +- Explicit live/demo onboarding and settings migration with persistence safeguards. +- Creator manifest import, game discovery, archive/game hashes and storage preflight. +- Pinned Wabbajack preparation and integrity checks; protected local Nexus connection for private testing. +- Durable installation jobs, cancellation/retry, output verification and MO2 profile launch. +- Desktop/Steam shortcut creation, repair and owned-entry cleanup; versioned fresh installs and save-preserving removal. +- Creator-declared isolated game-layout validation and protection against closing during active file operations. +- Privacy-conscious diagnostics, generated dependency notices, publication audit tools and a separate Steam depot preview workflow. + +Remaining limits: no bundled playable catalog; automatic Nexus downloads require Premium; public Nexus registration and the project license are undecided; VNV needs compatible game preparation; full authenticated install-to-play, clean Windows/Steam and save-preservation acceptance remain incomplete. Native third-party logs can remain unsanitized during a run or after a crash. Builds are unsigned. No new hosted release or Steam submission is implied by this version. + +## 0.1.0 — historical private UI preview + +Svelte/Electron visual prototype with a fictional catalog, simulated installation/library workflow, native preferences and a portable Windows build. It predates live installation support. + +--- + +# Privacy & local data + +Canonical source: `docs/privacy.md` + +This describes the current source preview, not a future cloud service. Loadstone has no analytics SDK, advertising, automatic crash upload or Loadstone-hosted account service. It does not upload diagnostics automatically. + +## Local storage + +Packaged app settings and workspace data live in `%APPDATA%\Loadstone`. They include chosen folder paths, imported manifest metadata and source locations, demo state, live installation history, bounded engine output, shortcut locations, and local Steam account identifiers used for saved entries. Test builds can select another app-data directory through `LOADSTONE_DATA_DIR`. + +`nexus.bin` contains the key and validated account metadata encrypted through Electron safeStorage/Windows DPAPI. Public status exposes the display name, Premium flag and verification time; the key remains in the main process. Disconnect removes Loadstone's credential files. It does not revoke the provider key or change Wabbajack's account. Same-user software can potentially access credentials; encryption is not a defense against malware in the same Windows account. + +Experimental native creator builds store their recipe fingerprint, destination, progress and status in `native-builds.json`. Candidate folders contain their recipe snapshot and reconstruction receipt. The selected private local-inputs JSON remains where you created it; its game/archive paths are read into the main process for the build, not copied into history or sent to the renderer. Native build records are currently excluded from diagnostic exports. Cancelled or interrupted folders remain on disk for review. Confirmed resume retains conflicting files and the previous receipt under `.loadstone-build-recovery/` inside the candidate; these local copies may contain personal configuration and are not automatically deleted or exported. Source inputs must be selected again for each resume review. + +Guided native installation does not require that JSON file. Its selected game, prerequisite and archive paths appear locally in the setup screen for review; the main process retains the input map and package path. The draft survives navigation but is discarded on restart, is not persisted or exported, and contains no account credential. Source selections must be made again for recovery. Package import may read Steam installation metadata for game suggestions; it starts no archive downloads. + +When a reviewed native build requests original-source downloads, completed archives remain in `native-downloads/` beneath app data for verified reuse. Original hostnames and the cache directory appear in the build review. Signed links, API keys and provider response bodies are not stored in build history or diagnostics. A hard process interruption may leave temporary `.part` files; they are never reused as verified archives. Resetting demo data does not clear this cache. + +Installation destinations contain the list snapshot, downloaded archives, MO2 output and engine logs. Steam shortcut backups remain beside Steam's `shortcuts.vdf`. Desktop links point to the installed manager. Resetting demo data does not remove those files or live installations. Library removal retains profiles, saves folders, overwrite files, MO2 settings, downloads and files outside the profile directory in a sibling recovery folder. Other profile files, including custom mods, are deleted only after the removal dialog is accepted. See [removal behavior](installation.md#removing-a-setup) before manually deleting retained data. + +## Network activity + +Account connection and explicit revalidation contact Nexus Mods. Installation preflight also revalidates access when Nexus downloads are needed. Preparing the engine downloads the pinned official release from GitHub and its download infrastructure. Wabbajack performs list downloads and may contact Nexus, original file hosts and its own supporting services; those providers control their own logging and privacy practices. Local game discovery reads Steam metadata and the Windows Steam registry path. Steam shortcut editing operates on local files. + +Explicitly starting a native build with requested downloads contacts the original public HTTPS hosts and their permitted redirect destinations. Uncached Nexus sources trigger account verification and specific file download-link requests; keys go only to the Nexus API. Original providers receive the connection's IP address and Loadstone's application identification. Merely opening Settings or inspecting a native package does not start archive downloads. See [native download handling](native-downloads.md). + +## Diagnostics + +The Settings export is a structured JSON summary containing app/build identity, platform/runtime versions, preferences, connection status, aggregate demo counts, and up to 25 recent live job summaries. It excludes credentials, account names/IDs, filesystem paths, creator metadata, source URLs and raw logs. Errors are reduced to automatic categories and numeric exit codes; these are triage hints, not diagnoses. The save dialog writes only to the selected local destination and does not upload the report. + +Paths, setup names, account display names and local account IDs can identify a user. Review any exported or copied diagnostics before sharing. Loadstone redacts the known API key, query strings and common token fields from captured engine output, but this is not a guarantee that arbitrary third-party output contains no personal data. Native engine logs may be unsanitized during a run or after a crash. Do not share credential files, raw Steam account files or complete user-data folders. + +Native library registration stores candidate paths, directory identities, recipe hashes, profile names, save guidance and verification times in local app data. Verification reads candidate files; launching starts its declared MO2 profile. Registration does not contact a server or migrate saves. See [native library behavior](native-library.md) for shortcut and maintenance limits. + +Confirmed native removal moves the candidate to a local recovery folder and deletes only reviewed, unchanged recipe files. It retains saves, profile/configuration files, modified files and untracked content; native library state records removal/recovery and shortcut-cleanup status. This preservation policy is separate from Wabbajack removal. See [native maintenance](native-maintenance.md). + +Confirmed native repair retains replaced files and the original receipt under `.loadstone-repair-recovery/` inside the registered setup. These copies can contain personal configuration and are not automatically deleted or exported. Existing profiles/configuration are preserved by default; a separate review choice can restore their recipe versions. The local library records repair start/completion, recovery directory and the number of preserved changed files. Source selections remain temporary and must be made again for retry. See [native repair](native-repair.md). + +Native version updates show the original version and folder in the temporary guided draft, then record the new candidate in ordinary build history. The two registrations remain independent; no update relationship or personal settings/save transfer is persisted. See [native updates](native-updates.md). + +In [manual Nexus download mode](native-manual-downloads.md), opening a file page sends only its public recipe game/mod/file identifiers to the default browser. Browser sign-in and downloads remain in that browser. Loadstone does not receive cookies or NXM/download tokens; its picker verifies the chosen local bytes without uploading them. Verification badges, manual mode and byte progress remain temporary local draft state. No browser protocol associations are installed. + +--- + +# Security + +Canonical source: `SECURITY.md` + +Loadstone is under active development. Only current `main` is being developed; there is no supported public stable release or guaranteed response time yet. The published v0.1.0 demo is historical. + +This source repository is public. GitHub private vulnerability reporting is not currently enabled, and a monitored confidential contact has not yet been published. Until a private reporting route is listed here, open an issue requesting a private contact without including vulnerability details. Do not post secrets, personal files or exploit details in public issues. Establishing the confidential reporting channel remains a release requirement. + +Once a confidential channel is established, include the affected commit/version, Windows version, reproducible steps using synthetic data, expected and observed behavior, and impact in the private report. Do not include Nexus keys, encrypted credential files, personal Steam files, game assets or unreviewed logs. If a credential was exposed, revoke it at its provider rather than relying on deletion from a report. + +## Boundaries + +The renderer is sandboxed with context isolation and a limited IPC bridge. The main process controls files, credentials and child processes. SHA-256 pins check the engine and imported archive; ownership markers restrict installation recovery and shortcut edits. These controls do not establish that a third-party modlist is trustworthy. Installed mod managers, plugins and games execute as the Windows user. Use trusted creators and original sources. + +Windows credential encryption protects against other accounts, not malware running as the same user. Engine log sanitization happens after the child exits; crashes can leave unsanitized native logs. See [privacy](docs/privacy.md) and [installation limits](docs/installation.md). + +--- + +# Open-source release + +Canonical source: `docs/open-source.md` + +The maintainer selected **GPL-3.0-or-later** on October 13, 2026. [LICENSE](../LICENSE) contains the unmodified GNU GPL version 3 text; [COPYRIGHT](../COPYRIGHT) expressly grants the option to use any later version and defines the covered original source and technical documentation. `package.json` uses the SPDX identifier `GPL-3.0-or-later`. The source repository is public; the maintainer confirmed that it should remain public on October 13, 2026. Private acceptance artifacts and unpublished binary candidates remain separate. + +New Windows packages include `resources/licenses/Loadstone-GPL-3.0.txt` and `Loadstone-COPYRIGHT.txt`; the About screen displays both texts offline. Third-party notices remain separate. The recorded 0.3.0 preview predates this decision and is not silently replaced or relabeled. + +The 0.4.0 [private preview procedure](private-preview.md) pairs a clean packaged revision with an exact source ZIP and local integrity/review evidence. Preparing that archive does not close public corresponding-source delivery or the publication gates below. + +## Provenance inventory + +| Component | Current treatment | +| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Loadstone app, adapter and tests | Project-authored source under GPL-3.0-or-later; see LICENSE and COPYRIGHT. | +| Shipped JavaScript dependencies | Versioned inventory and original license texts in `notices/`; regenerate with `pnpm notices`. | +| Electron runtime | MIT license included in generated notices; packaged Electron and Chromium license files must remain with distribution. | +| Wabbajack 4.2.3.0 | Downloaded unmodified from upstream at user request, separate process; not committed or bundled in Loadstone's portable package. Upstream [GPL license](https://github.com/wabbajack-tools/wabbajack/blob/4.2.3.0/LICENSE.txt) and its included component notices apply. Review distribution/source obligations before changing this model. | +| MO2 and mods | Supplied by creator lists and original sources, not bundled by Loadstone. Review each list's distribution rights separately. | +| Lucide icons | Original package license copied into generated notices. | +| Fonts | `src/fonts.css` uses locally installed Segoe UI. No font binaries are shipped. | +| Compass logo and desktop icon | Project-created geometry; recorded in [artwork provenance](artwork.md). Branding use policy remains to be decided. | +| Discovery backgrounds | AI-generated illustrative artwork with the prompt recorded in [artwork provenance](artwork.md). Review for release suitability and avoid claims of exclusive rights or captured gameplay. | +| Game names and fictional demo setups | Game trademarks identify compatibility; no endorsement is claimed. Demo setups are not available modlists. Review store and README wording before publication. | + +The dependency inventory is evidence for review, not a legal compatibility determination. No upstream Wabbajack/MO2 source is copied into the current app. Future linking, source reuse, bundling or modifications require another review. Build/test tooling is not fully covered by the production inventory; audit anything added to source archives or shipped build tools. + +The renderer build records the packages whose modules contribute code, including generated Vite runtime code. `pnpm notices` combines those records with main-process dependencies. Svelte and Lucide are build dependencies with bundled runtime attribution, rather than shipping their full compiler trees. `is-reference@3.0.3` and `locate-character@3.0.0` remain development dependencies with missing standalone license texts; neither contributes to the current renderer bundle or belongs to the packaged production dependency graph. No upstream notice has been invented. Verify this exclusion against each release artifact; source archives containing dependency trees need a separate review. The current generated shipped inventory reports no missing license texts, which does not close distribution review or publication gates. + +## Publication gates + +- Confirm the release version and final artwork/branding terms. The source-code license choice, full license text, package metadata and contribution terms are now recorded. +- Supply recipients with the exact corresponding source for every distributed executable through a GPL-compliant distribution method, including modifications and necessary build scripts and material. Public binary downloads must not direct recipients only to inaccessible private source. Retain the build commit and lockfile provenance. See [GNU GPL section 6](https://www.gnu.org/licenses/gpl-3.0.html#section6). +- Review all dependency license texts and notices against the actual package, including Electron/Chromium and external-tool distribution behavior. Do not assume a package's SPDX label is its complete notice. +- Enable a monitored private security-reporting channel; finalize support and version-support policy. +- Review tracked files, screenshots, fixtures and the complete Git history for secrets, signed URLs, personal paths and private material. Rotate any exposed credentials before considering history cleanup. +- Verify the public README against the release artifact, link its exact source tag, and separate developer preview limitations from supported features. +- Complete Windows install-to-play, Steam shortcut, recovery, save-preservation and removal acceptance; prepare the distinct Steam depot and store materials. +- Keep the source repository public. Public binary releases, Steam uploads and distribution of third-party payloads require their own completed acceptance and publication authorization. + +These binary-release gates remain open. Public source availability is already authorized; it does not establish that a binary candidate or featured modlist is ready to publish. + +Run `pnpm audit:publication` before proposing public release. See [publication hygiene findings](publication-audit.md) for the scan scope, classified fixtures, historical personal-path findings and outstanding manual review. The command never rewrites history and does not approve publication. + +--- + +# Artwork provenance + +Canonical source: `docs/artwork.md` + +`public/worlds.png` was generated with the built-in image generation tool for this project. It is an original illustrative triptych, rather than captured gameplay. The app uses each third as a separate background through CSS positioning. The source image is retained locally in Codex's generated-images folder. + +Final generation prompt: + +> Create a cinematic landscape artwork triptych for the Loadstone desktop game modlist app. Image is very wide, approximately 3:1 aspect ratio, divided into THREE equal width vertical panels edge-to-edge, no gaps or borders, each third an independent coherent landscape illustration. Left third: richly detailed Mojave desert post-apocalyptic western road leading to a distant retro futuristic neon town at amber sunset, small lone traveler seen from behind, weathered electric poles, abandoned car, atmospheric dust and deep mountains. Middle third: cold Skyrim-inspired Nordic wilderness with dramatic snowy mountain ridges, ancient stone ruins and pine forests, small cloaked wanderer, pale blue mist, cinematic dark teal shadows. Right third: Fallout-inspired abandoned industrial American city reclaimed by green vegetation, distant domed building, rusted overpass, amber evening light, subdued olive greens. Polished realistic game environment concept art, dramatic beautiful lighting, strong silhouettes, dark lower portions appropriate for ivory text overlay. Every panel has its own horizon and focal point. NO TEXT, no labels, no logos, no letters, no UI. Original concept artwork. + +The carved copper **L** in `public/brand/mark.svg` is the shared editable source for the desktop app, handbook and store compositions. `src/Logo.svelte` imports that vector. Run `pnpm assets:icon` to render the rounded basalt tile as `public/brand/icon.svg`, `public/icon.png` (512px) and `build/icon.ico` (16/24/32/48/64/128/256px). `scripts/create-icon.mjs` uses the locked Electron renderer in a hidden window, without network access or a separate Python/Pillow dependency. See the [brand system](../handbook/pages/brand.md) for palette, typography and review guidance. + +## Steam branding kit + +Run `pnpm assets:steam` after installing the locked development dependencies. `scripts/steam-artwork.mjs` renders eight SVG/PNG pairs and a PNG hash/dimension inventory to ignored `release/steam-artwork/`. It uses the pinned Electron renderer through Playwright, makes no network requests, and closes its hidden render window afterward. Re-running replaces only these generated output files. + +The compositions use the shared mark, title-case Segoe UI lettering and quiet geometric planes on a basalt gradient. The Windows system font is rendered locally; no font files, game screenshots, third-party logos or AI landscape bitmap are embedded. The script and SVG mark are the editable sources; generated artwork is draft branding, not captured app behavior or evidence of a working modlist. The original generator and rendering source is covered by GPL-3.0-or-later. Bitmap artwork, packaged icons, screenshots, generated store media and videos are outside the source-code grant; their release and reuse terms remain to be finalized. The source license grants no trademark rights. See [COPYRIGHT](../COPYRIGHT) for scope. + +Capsules contain only the title and mark. The library hero contains no text and the library logo has a transparent background. Sizes follow the [store](https://partner.steamgames.com/doc/store/assets/standard) and [library](https://partner.steamgames.com/doc/store/assets/libraryassets) specifications checked on 2026-10-01. Inspect small-capsule legibility and actual Steamworks crop/logo previews before submission. Client/community icons and real workflow screenshots remain separate deliverables. + +--- + +# Package a preview + +Canonical source: `docs/private-preview.md` + +Version 0.4.0 brings guided native installation and maintenance into an unsigned Windows x64 preview. A local package is not publication or 1.0 acceptance. Preserve the recorded 0.3.0 executable and footage. Build from a clean committed source revision; never label an older artifact with current-source capabilities. + +## Build and exercise the artifact + +Use Node 24 and pnpm 11 on Windows. Install the locked dependencies, run `pnpm check` and `pnpm test`, then `pnpm notices`. Review and commit any intended notice changes before the final package build. For complete archive coverage, supply `LOADSTONE_TEST_7ZIP` with the trusted tool prepared by `scripts/prepare-sevenzip.ps1`. + +Choose a new ignored output folder for each build. With `release/private-0.4.0` still absent: + +```powershell +pnpm package --config.directories.output=release/private-0.4.0 +node scripts/steam-depot.mjs release/private-0.4.0/win-unpacked +``` + +The depot script creates a fresh `release/steam/preview-` containing the entire application, notices, integrity manifest and SteamPipe templates. Verify it with `node scripts/steam-depot.mjs --verify `. Check its embedded commit, `dirty: false`, version, license, lockfile hash and notice gaps. The lockfile hash uses UTF-8 with CRLF normalized to LF, matching Git archive bytes. No command uploads a depot. + +Set `LOADSTONE_TEST_EXE` to the absolute path of that kit's `content/Loadstone.exe`, then run the staged-executable test selection from `.github/workflows/windows.yml`. These tests redirect native side effects to synthetic fixtures; `LOADSTONE_DATA_DIR` alone does not redirect Desktop or Steam operations. Clear `LOADSTONE_TEST_EXE` afterwards. + +```powershell +node scripts/verify-portable.mjs release/private-0.4.0 test-results/private-0.4.0 +``` + +This separately exercises the actual portable wrapper, including extraction, current version, renderer/bridge, complete offline GPL and scope texts, settings, demo isolation and clean shutdown. Inspect its screenshots and JSON evidence. Preserve its SHA-256 and size along with the unpacked depot inventory. Neither check certifies real games, real accounts or the actual Steam client. + +## Exact source and review material + +Read the **embedded build commit** from the verified depot manifest. From the source repository, use that exact commit, not a subsequently merged branch tip: + +```powershell +git -c core.autocrlf=false -c core.eol=lf archive --format=zip --prefix=Loadstone-source/ --output=release/private-0.4.0/Loadstone-0.4.0-source.zip +``` + +The explicit Git settings preserve LF source bytes independently of Windows checkout defaults. The archive must contain all tracked build inputs, including original source, lockfile, scripts, tests, license/scope, notices and documentation. Inspect the ZIP inventory and every archived file against that Git tree. Exclude Git history, installed dependency trees, raw acceptance evidence, credentials, game files and mod downloads. Record its SHA-256 and byte size; independently compare the packaged source modules (allowing checkout line endings), license and notices with the archived revision. Rebuild from an extracted source archive with `pnpm install --frozen-lockfile`, `pnpm check`, `pnpm test` and `pnpm package`; without Git metadata the build identity deliberately reports an unknown commit. + +Keep a local review manifest linking the executable and source ZIP hashes, exact build commit/tree and lockfile hash, depot inventory, test evidence and tool versions. Hashes establish integrity and provenance, not byte-reproducibility, publication clearance or a legal determination. Build/test dependencies are fetched from the locked upstream graph; they are not bundled in this source ZIP. Artwork and third-party material retain the scope stated in `COPYRIGHT` and the [provenance inventory](open-source.md). + +Before distribution, choose a corresponding-source delivery method that gives every binary recipient access to the matching source, finish the publication/license review and ensure the public links are usable. Preparing a private archive does not satisfy public delivery. See the [open-source gates](open-source.md) and [1.0 acceptance plan](1.0-plan.md). Public upload, repository visibility changes and Steam publication remain separate actions. + +--- + +# Steam packaging + +Canonical source: `docs/steam-release.md` + +`pnpm package:steam` generates a Windows x64 **directory build**, distinct from the self-extracting portable EXE. It stages a new kit under `release/steam/preview-/` without replacing existing kits. This is a private developer preview, not a submitted or approved Steam build. + +The kit contains: + +- `content/`: the complete Electron application and runtime, including Electron/Chromium and Loadstone dependency notices. The depot must include this entire directory. +- `depot-manifest.json`: source commit, dirty-worktree flag, lockfile hash, application version, launch settings and SHA-256/size for every content file. No build-machine paths are embedded in this manifest. +- `scripts/`: SteamPipe app/depot templates. Replace the two ID placeholders with assigned Steamworks IDs and rename both files to `.vdf`. +- `README.txt`: operator instructions and outstanding release gates. + +Build with Node 24 and pnpm 11 from a clean checkout after `pnpm install --frozen-lockfile`, `pnpm check`, and `pnpm test`. A dirty build is identified as dirty, never silently certified. The file inventory is for integrity and provenance; binaries are not claimed to be byte-reproducible or signed. A matching inventory also does not prove absence of secrets or compliance with licenses. + +```powershell +pnpm package:steam +node scripts/steam-depot.mjs --verify release/steam/preview- +$env:LOADSTONE_TEST_EXE = (Resolve-Path 'release/steam/preview-/content/Loadstone.exe').Path +node --test tests/electron.test.mjs tests/live.test.mjs tests/nexus.test.mjs tests/onboarding.test.mjs tests/close-guard.test.mjs +Remove-Item Env:LOADSTONE_TEST_EXE +``` + +To generate preview scripts with assigned IDs directly, run `node scripts/steam-depot.mjs release/steam-unpacked/win-unpacked `. This stages a fresh kit. No helper invokes SteamCMD, logs into Steam, uploads content or changes a branch. Templates set `Preview` to `1` and omit `SetLive`; [Valve documents this mode](https://partner.steamgames.com/doc/sdk/uploading) as generating logs and manifests without upload. The Steamworks SDK, account and IDs are supplied separately by the maintainer. + +## Steamworks setup and acceptance + +Configure the launch executable as `Loadstone.exe`, Windows 64-bit, with no launch arguments and the application root as working directory. Map `content/` as the Windows depot root. Do not point Steam at the portable self-extracting wrapper. Do not bundle `depot-manifest.json`, SteamPipe scripts, upload credentials, user data, downloaded engines, or game/mod archives. + +Settings, protected Nexus credentials and installation history stay in Electron's per-user app-data directory, outside the depot. Installed setups and recovery folders belong outside the application directory. Do not configure Steam Cloud for credential files. Test updates and uninstall through the actual Steam client to confirm user data and external setups remain intact; local Electron tests cannot establish Steam behavior. + +Before upload or review, verify GPL-3.0-or-later corresponding-source delivery and all shipped notices, finalize asset licensing and Nexus registration, supply a permitted real creator list, complete clean Windows install-to-play acceptance, review public claims/screenshots, and configure support/privacy links. Record the tested source commit and depot build ID. Current builds identify as 0.4.0 native installation previews; generating a depot kit does not justify a 1.0 version bump. New workspaces open a welcome screen with explicit live/demo choices. The live choice opens Discover with **Open .loadstone** for guided native installation. Local-only packages need no Wabbajack engine or Nexus connection; optional Wabbajack setups have a separate manifest import and engine configuration. Existing schema-1 workspaces migrate to schema 2 with their selected mode and preferences retained. + +[Valve's review process](https://partner.steamgames.com/doc/store/review_process) covers the actual store presence and build. Successful packaging or fixture checks do not establish acceptance by Valve. No Steam depot has been uploaded. A partial [real TTW shortcut/launch check](native-steam-acceptance.md) reached the menu after an edition prompt; the revised candidate's direct launch failed before the menu. No gameplay or recording acceptance is claimed. These non-Steam-shortcut checks do not test installing or updating the Loadstone depot through Steam. + +Store copy, disclosures, asset production and reviewer handoff are tracked in the [Steam submission draft](steam-submission.md). + +--- + +# Steam submission draft + +Canonical source: `docs/steam-submission.md` + +Internal preparation for **0.4.0 native installation preview**. Product copy was updated October 13, 2026; linked Steamworks requirements were last reviewed October 1 and must be checked again before submission. This packet has not been submitted. Store copy below remains gated on real acceptance and the decisions recorded here; do not paste it into a public page as a release announcement. + +## Product setup + +Propose application type **Software**, category **Player Tools**. Valve lists Player Tools among eligible non-game categories; this is a proposed fit, not a determination that Loadstone will be accepted. See [application types](https://partner.steamgames.com/doc/store/application) and [Steam Direct categories](https://partner.steamgames.com/steamdirect). + +| Field | Proposed value / outstanding decision | +| --- | --- | +| Product name | Loadstone; complete name/branding review before submission | +| Platform | Windows x64; English interface, mouse and keyboard | +| Launch | `Loadstone.exe` in the directory depot; see [depot instructions](steam-release.md) | +| Developer / publisher | Maintainer must supply the actual legal/account identity | +| Price / release date | Undecided; do not infer either from open-source plans | +| Support / privacy | Publish reviewed support and privacy destinations; source repository is public; confidential security reporting remains unfinished | +| Minimum requirements | Establish on clean Windows hardware; development-host success is not a certified minimum OS, RAM or GPU specification | +| Storage | Measure the final directory build and engine overhead separately; every list additionally needs its own downloads, installed files and recovery space | +| Steam feature claims | No Workshop, Cloud, achievements, controller, Deck or Linux claims. Local non-Steam shortcuts are a separate app feature | + +## Store copy for review + +### Short description + +Loadstone brings compatible Bethesda setups into one Windows library. Open a .loadstone recipe, select your owned games and original files, then build and manage a separate Mod Organizer setup. Compatible Wabbajack lists use an optional engine. + +### About this software + +Give your modded worlds a home. Loadstone is a Windows desktop tool for installing and managing compatible Bethesda game setups. Its documented .loadstone format describes required games, original sources, verified output files and the intended Mod Organizer profile. Loadstone's original source is licensed under GPL-3.0-or-later. + +Review a setup's game requirements, original archives and prepared prerequisites before installation. The native guide builds into a separate folder, shows measured progress and verifies the result before you explicitly add it to your library. Launch through the configured Mod Organizer profile and create desktop or local Steam shortcuts for your setup. + +Resume interrupted native builds after a fresh review. Repair missing or damaged recipe files while retaining replaced originals, or install a different version in a separate folder while preserving the previous playthrough. Reviewed native removal retains profiles, saves, configuration, modified files and untracked content. Keep your own backups: new setup versions may require a new game, and unusual mod save locations require individual review. + +You must own and install the required games and DLC and obtain a compatible recipe and its declared original files. TTW requires both Fallout: New Vegas and Fallout 3. Native local-only recipes need no Nexus connection or Wabbajack engine. For declared Nexus files, choose guided browser downloads with local hash verification or automatic downloads with eligible Premium access and a locally protected API key. Browser sign-in and downloading remain user actions. 7z/RAR extraction requires a separately supplied trusted tool; availability depends on the original download sources. + +Compatible Wabbajack setups use a separate creator manifest and the original Wabbajack archive, with an optional upstream engine downloaded independently. Wabbajack files, MO2 installations and Nexus collections are not interchangeable .loadstone packages. + +Loadstone does not include Bethesda games or a playable mod collection. The bundled demonstration catalog is illustrative. Compatibility is specific to each creator setup; a Wabbajack archive alone is not a promise of complete game preparation. Some lists require additional steps documented by their authors. + +## Evidence and claim gates + +| Claim | Current evidence | Required before release copy is approved | +| --- | --- | --- | +| Import and preflight | Real VNV archive, installed game and pinned runtime checked; [acceptance record](vnv-acceptance.md) | Creator-approved supported manifest, clean original game and authenticated source access | +| Native installation | Documented format, real Electron guided installation/resume/admission and full-size private TTW reconstruction of 13,952 outputs | Reproducible permitted original-source recipe; real account downloads and clean Windows install-to-play | +| Install and launch | Implemented native/engine launch paths; [partial TTW Steam-client evidence](native-steam-acceptance.md) | Resolve direct Steam startup failure; verify recording, disposable gameplay, isolated save/reload and selected-profile behavior | +| One-click setup | Optional isolated game-root validation implemented | A permitted list that actually produces a self-contained playable setup. Current cached VNV requires manual game preparation; do not advertise one-click VNV | +| Shortcuts and maintenance | Real Steam shortcut preservation/running-client safeguard; native repair, separate-version and retained-removal Electron fixtures | Complete uninterrupted Steam launch, actual depot update/uninstall and maintenance after real play with save-preservation evidence | +| Nexus access | Local protected credential storage, membership checks, native automatic acquisition and guided manual verification; browser handoff intercepted in fixtures | Public application registration and real authorized authentication/downloads; never supply reviewer credentials in Git or public docs | +| Open source | Contributor/privacy/security docs, dependency notices and history audit prepared | GPL-3.0-or-later selected for original source; corresponding-source delivery, distribution/asset review and publication audit decisions remain open; source repository is public; binary release acceptance remains open | + +The current portable build is a local preview, not a Steam depot acceptance result. Record the exact candidate source commit, artifact hashes, depot build ID, test machine and outcomes in a release-specific acceptance report. Valve reviews the store presence and build; local tests do not replace that review. See [Valve review process](https://partner.steamgames.com/doc/store/review_process). + +## Artwork and screenshot production + +Use the existing charcoal, copper and ivory palette with the original compass-stone mark. Keep the title readable at small sizes. Capsule text should be limited to the product title; avoid feature promises, prices, third-party logos or approval badges. Export from purpose-made compositions, not stretched UI screenshots. + +| Asset | Pixels | Status | +| --- | --- | --- | +| Store header | 920 x 430 | Generated draft; final review pending | +| Store small capsule | 462 x 174 | Generated draft; inspect reduced-size legibility | +| Store main capsule | 1232 x 706 | Generated draft; final review pending | +| Store vertical capsule | 748 x 896 | Generated draft; final review pending | +| Library capsule | 600 x 900 | Generated draft; final review pending | +| Library header | 920 x 430 | Generated draft; final review pending | + +Sizes and capsule guidance: [store assets](https://partner.steamgames.com/doc/store/assets/standard), [library assets](https://partner.steamgames.com/doc/store/assets/libraryassets). Run `pnpm assets:steam` to generate these six assets plus a 3840 x 1240 library hero and a transparent 1280 x 280 library logo under `release/steam-artwork/`. See [artwork provenance](artwork.md). Client/community icon preparation and final Steamworks preview remain pending; this draft kit is not approval to upload. + +Capture at least five real app screenshots at 1920 x 1080 or larger, 16:9, following [Valve's screenshot requirements](https://partner.steamgames.com/doc/store/assets/standard). Planned subjects: + +1. A permitted real creator setup with accurate requirements and credits. +2. Actual preflight results for the supported game/list. +3. A real installation in progress. +4. The installed library entry and configured launch profile after successful play acceptance. +5. Real maintenance or shortcut controls for that same installation. + +Use a clean capture workspace with non-personal folder names and no credentials, account identity or private paths visible. Keep source captures and their build identity. Existing design renders and test screenshots with simulated jobs/accounts are not evidence of these workflows and are not approved store screenshots. Do not substitute concept art for captured product behavior. + +## Content survey draft + +The app includes pre-generated AI landscape illustrations as discovery backgrounds. It does not generate images, text or other content with AI while running. Proposed disclosure: **AI tools were used to create the landscape illustrations used in the discovery interface. These are illustrative backgrounds, not screenshots of installed games.** Check the final shipping assets against [artwork provenance](artwork.md) when completing the survey. + +Valve's current survey distinguishes shipped, player-consumed AI content from development productivity tools, and asks separately about live generation. Review all survey sections against the actual candidate, including any future curated content; do not infer content ratings from this draft. See [Content Survey](https://partner.steamgames.com/doc/gettingstarted/contentsurvey). + +## Submission handoff + +Before any upload, close the claim gates above, complete [open-source preparation](open-source.md) and [publication audit](publication-audit.md), finalize public support/privacy destinations, and produce the missing graphics and real captures. Prepare a reviewer walkthrough with the permitted list source, prerequisites, expected results and known limitations. Arrange authorized reviewer access separately without committing credentials. + +Then generate and verify a clean directory depot using [the release procedure](steam-release.md), test it through the actual Steam client and record the assigned build ID. Complete the Steamworks checklists and survey against that exact build. This document does not authorize a purchase, account submission, upload, public repository change or release. + +--- + +# Publication hygiene + +Canonical source: `docs/publication-audit.md` + +Run `pnpm audit:publication` from a complete local checkout after fetching the refs intended for publication. The command reads unique file blobs from all commits reachable from local refs and writes `test-results/publication-audit.json`. It never changes Git history or repository visibility. Reports include rule, blob ID, file and line, not matched values or source excerpts. Keep reports local until reviewed. + +The scanner checks recognizable private-key headers, selected provider-token formats, credential-bearing URLs, sensitive query parameters, personal home-directory paths and sensitive filenames. It inventories binary/non-UTF8/large blobs for manual review rather than silently treating them as clean. Exit status zero means the scan completed; it does **not** mean publication is cleared. There is no automatic allowlist for test directories. + +## Initial review, 2026-10-01 + +Baseline source: `8245844d5fdbfe82d6f7ff7c351cbaa842462161`. Available local refs contained 46 commits and 241 unique blobs: 235 UTF-8 text blobs scanned and six binary assets inventoried. + +The scan reported 17 text matches, including three in that HEAD: + +- Fourteen revisions of `tests/live.test.mjs` contain the same deliberately invalid credential-bearing example URL used to test manifest rejection. +- `tests/fixtures/installer-child.cjs` contains a synthetic query-token value used to prove log redaction. +- `tests/diagnostics.test.mjs` contains a synthetic personal-path canary used to prove diagnostic privacy. +- Historical `docs/portable-verification.json`, blob `5218a659da29ef7314c1efed0e703e873f5c6de5`, contains a personal absolute executable path. The current file had already been changed to a basename, but the older blob remains reachable. + +Visual review found a personal Windows path in the old `docs/screenshots/settings.png`, blob `854eacef22babdb4e9def4f0ca339e56e66f4a43`. This change replaces the current screenshot with a fresh capture of the actual UI from isolated app data, using a neutral demo install path and no connected account. The older screenshot remains in Git history. Discovery and Library screenshots were visually reviewed without finding personal paths or credentials in their displayed content. + +The five current PNG assets were inspected for chunk types. Discovery, Library, Settings and the icon contain image chunks only. `public/worlds.png` also contains a `caBX` provenance container; it is retained and still needs provenance-metadata review. The icon ICO container, release assets, commit messages and author identities need separate review. Visual inspection and a small rule set cannot prove absence of sensitive material. + +## Public-source review, 2026-10-13 + +The maintainer confirmed that this source repository should remain public. The review at `f6e399cc0523c988375fd4996cde8af9a7197be7` fetched remote branches, tags and all 60 pull-request heads. The available refs contained 147 commits and 744 unique file blobs: 737 UTF-8 text blobs and seven binary assets. + +The scanner reported 27 matches, seven in the current tree. Twenty-six are synthetic test inputs across revisions of the live-manifest, installer, download, source-ledger and diagnostic tests. The remaining text match is the historical executable path described above. No actual credential was identified by this review. + +An additional review covered tracked path inventories, internal-workspace identifiers, commit messages and identities, the 60 public pull-request titles/descriptions, and the available issue/review comments. No unrelated project implementation was identified. The current acceptance-plan document contained internal workflow references; these are removed from the current tree. Their historical versions remain reachable. Commit identities contain the maintainer's existing name/email; this change does not rewrite them. + +The three current screenshots and both standalone PNG artwork files were visually inspected. The historical Settings screenshot still displays a personal Windows path. The current screenshot and other displayed artwork showed no private workspace content. PNG chunk inspection found only image chunks except for the existing `worlds.png` C2PA provenance container. Its readable metadata describes the image-generation service, timestamps, content hashes and signing certificates; no personal installation path or unrelated project content was identified. The ICO contains seven PNG images with image chunks only and no trailing bytes. This inspection does not validate the provenance signature or rule out every possible binary encoding. + +GitHub lists one public release, `v0.1.0`, with an executable and checksum. The downloaded executable matched the published checksum and was inspected as an archive without running it. Its application archive contained 4,891 files; 4,889 UTF-8 files were scanned without credential-pattern or internal-workspace matches. All three packaged main-process source files matched the release tag byte for byte. This is a bounded content review, not a security certification of the executable or its dependencies. Newer private candidate packages remain outside Git and were not uploaded. + +## Ongoing publication hygiene + +The historical report, screenshot and internal workflow references are already in public history. Removing their current versions does not remove that disclosure. A history rewrite would need a separate reviewed plan covering branches, tags, pull-request refs, release source snapshots and downstream clones; no rewrite or force push was performed. The maintainer's decision to keep the repository public is not evidence that these older disclosures have disappeared. + +Review commit identities/messages, generated provenance metadata, release packages, untracked material proposed for publication, and any refs not present locally. Re-run the audit after changes and investigate new findings individually. If an actual credential is found, revoke it at its provider before considering history cleanup. The current matches were classified as fixtures or personal-path material; this is not a general credential-free certification. + +The source-code license is GPL-3.0-or-later and public source availability is authorized. This audit does not settle distribution compliance, attribution gaps, security-reporting contacts, Nexus registration, real installation acceptance, or approval to upload a binary release. See [open-source preparation](open-source.md). + +--- + +# Native Steam acceptance + +Canonical source: `docs/native-steam-acceptance.md` + +On October 13, 2026, the private 0.4.0 portable was exercised against the isolated TTW installed-baseline candidate described in the platform's reconstruction record. This was a real local-client check, separate from synthetic Electron tests. It did not install from public provider downloads or certify a clean Windows environment. + +## Build and candidate + +- Portable SHA-256: `2780774686a6c8a9cc73f1cd36fb64dbaaad8c9af523847bb5398d2787b3112d`. +- Embedded source: `d2bc450ab7df0b95467f191547d7852d30256473`; merged source `c80e996fb1466f45c27b8bbc50a12f9749e37d06` has the same tree. +- Candidate recipe SHA-256: `a76e91b75ab3aaeb2efcdec0803cde822ec94ed40ee382f49f0ae6dd82a740dd`; private version `2026.10.13-local`. +- MO2 `2.5.2-ML1.5`, selected profile `Tale of Two Wastelands`, candidate-local game, mods, profiles, saves and writable folders. + +## Observed results + +1. The actual portable verified all 13,952 recipe outputs, displayed the candidate review and persisted explicit library admission in isolated application data. +2. Saving a Steam entry while the real client was running returned the expected instruction to exit Steam. The shortcuts file remained unchanged. +3. After a normal Steam exit, Loadstone created one owned entry and its backup. All three existing shortcut records remained byte-for-byte identical. The new executable, working directory and arguments selected only the candidate's MO2/profile. +4. Reopened Steam displayed the entry. Play started the candidate's actual MO2 process with the declared arguments. +5. MO2 displayed its game-edition chooser. Selecting Steam wrote `General/game_edition=Steam`, then started the candidate's `Game/FalloutNV.exe`. The TTW main menu and Steam overlay notice were observed. This required intervention and is **not** a successful one-click launch. +6. Steam was configured to record in the background to a known folder, with microphone off and game audio only. Its renderer log reported starting recording, but no new video or clip appeared in the configured location or the prior default recording location. The instant-clip hotkey produced no verified clip. The session ended at the menu; no gameplay or recording success is claimed. The prior audio source was restored afterward. +7. Game and manager exited. All 18 previously fingerprinted original-profile/global-save files remained unchanged, with no added files under those roots. The candidate created an empty local saves folder; no save was loaded or created. Candidate configuration/profile writes remain private, with before/after evidence retained. + +## Follow-up and limits + +The generator previously omitted the edition field present in the installed source configuration. The optional, validated `gameEdition` recipe declaration addresses that missing field without silently changing legacy generated bytes or receipt fingerprints. Recipes using it are new recipe identities. Unit/integration checks cover storefront consistency, mixed-store TTW requirements, old output identity and launch-time drift checks; synthetic Electron flows exercise the extended declaration. This source change is newer than the tested 0.4.0 portable above. + +A fresh candidate was built and tested below. An uninterrupted real launch remains required. Diagnose recording and inspect a short game-video sample before longer play; do not substitute desktop capture. New-game/save/reload, controller input, mod behavior, maintenance after actual play, Desktop launch and clean-machine/provider acceptance remain open. No runtime support claim follows from the GOG declaration validator. Featured-pack source completion, permissions and publication are separate gates. + +Private evidence is retained under the ignored `test-results/native-acceptance/ttw-recorded/` directory. It contains local paths and account-specific shortcut backups and must not enter public archives. No game footage was produced for publication. + +## Fresh edition candidate and direct-launch diagnosis + +Later on October 13 (October 14 UTC), the actual Electron app's **Install another version** guide built private version `2026.10.13-edition` into a separate folder. It used the same owned-game/local-prerequisite inputs and all 13,951 unchanged static output records, plus the new Steam edition declaration in generated configuration. No source files or payloads were published. + +- Build source: `a7d18db882f556ce48236dcfc835c31c84aefb55`. +- Recipe SHA-256: `54169106ed7275e55c8aa7cb6564a19217e2adda3bc7a44041abd210957aa8f1`. +- Build completed at `2026-10-14T00:33:01.971Z`, with all 13,952 outputs verified. Its generated configuration was 2,200 bytes, SHA-256 `ec02f324d022e524c27fae63cba4b3fd1e05132e9e0d9aaf32206c347d9cf130`. +- Clean source build `b7b05f9aba756563f33c4e29e14b71f48aee506c` subsequently rechecked every output and admitted the separate version through Downloads. Both old and new library entries persisted. + +The earlier Steam recording log associated MO2 with the non-Steam shortcut and the child game with app ID 22380. It reported that another recording was already starting and later that the shortcut's timeline was missing. This suggests competing recording identities; it does not establish the complete cause or a working remedy. + +For the next check, Steam was running with background recording, a verified output folder, microphone off and game audio only. Launching the new version from Loadstone started the correct candidate-local MO2 and FalloutNV processes without an edition prompt. The game then displayed **Application load error 5:0000065434** before reaching its menu. + +The installed baseline explicitly declares `steamAppID=22380` for its selected MO2 executable. Earlier generated configuration omitted that field. A backed-up, candidate-only diagnostic restored that setting without changing the recipe or receipt. The first retry exposed a separate Loadstone rejection of MO2's normal `Python%20Proxy` plugin persistence key. Clean build `6acab578c394479ec98be330e9ff5b2e901d2d65` fixed that parser scope and reached the game process again; the same Steam error remained. **The app-ID setting alone did not resolve direct startup.** The diagnostic setting was restored afterward, and all intermediate configurations and logs were retained privately. + +The source now supports explicit, target-matched Steam app IDs while preserving legacy rendering. Launch checks protect declared IDs and continue rejecting aliases, duplicates, redirected paths, unsafe profile settings and changed executables. Unrelated plugin/UI state no longer blocks relaunch. The full fixture suite passed 183 tests with one optional skip; Svelte checks reported zero errors and warnings. These checks do not certify the failing real-game launch. + +Both actual game attempts ended at the Steam error. No new recording appeared, no clip could be exported, and no game/save/controller acceptance is claimed. The microphone remained off and the prior recording audio source was restored. All 31 protected original/previous-candidate profile, configuration and save files remained unchanged. New-candidate profile/configuration writes were backed up; no save was created or loaded. The existing portable/depot preview retains its older provenance. + +Evidence for this pass is ignored under `test-results/native-acceptance/ttw-edition/`. Next work must resolve the direct Steam initialization failure and separately retest a fresh recipe with all required declarations, then verify actual game footage before longer play. The previous successful Steam-shortcut menu launch does not establish direct-launch or recording success for this candidate. + +## Direct launch after a normal Steam restart + +At `2026-10-14T02:08Z`, the same `2026.10.13-edition` candidate reached the TTW main menu directly from **My library → Launch native setup**, without the edition chooser or Steam load error. The application was the clean r4 unpacked build from `68b6951c9398bbd7071eeea3fbe6d7eea9c4d550` (merged as `e2b09a818640d520648f9b87075cea1e33fd3280`, identical tree `29d1feb0ca24bcfaa1ab5d8ec7f455c02dd7c613`). It used the existing isolated app data and unchanged recipe fingerprint above. + +Before the retry, a read-only check found that Steam's registered active process referred to a process that no longer existed, while another Steam client process was running. Exiting Steam normally and reopening the installed client made the registration match its running process. No registry value, game binary, recipe, receipt or candidate configuration was edited for this retry; the earlier temporary app-ID edit had already been restored. The selected game/Steam API/xNVSE binaries matched the installed baseline. The actual process chain was Loadstone → candidate-local MO2 with the declared profile/title → candidate-local FalloutNV. + +This is evidence that a normal client restart resolved this particular direct-launch failure. It is not proof that stale registration explains every `5:0000065434` error, nor a reason to add a hard launch requirement based on an undocumented registry field. The [Viva New Vegas FAQ](https://vivanewvegas.moddinglinked.com/faq.html) also lists restarting Steam/MO2 among recovery steps for that error (checked October 14, 2026). + +### Recording and session limits + +Steam's background recording was confirmed in its UI before launch: all games, a known output folder, microphone off and game-only audio. A new app-22380 video session and 30-second clip were produced. The clip played in Steam's recording viewer, displaying the TTW menu at multiple playback positions, before any attempt to start a new character. + +The clip was exported locally to MP4. Independent playback decoded frames at 1, 14 and 28 seconds and reached the end without a media error; the decoded 14-second frame was visually inspected. Export: 30.001667 seconds, 2560 × 1440, 62,966,756 bytes, SHA-256 `a0d6a7df8f8d29ecf77a9d31bde12fbaf8c890bcc1f8d6a90d4248c370aaa1d3`. The original clip segments, full background session and MP4 are retained under the platform's ignored `publication/media/raw/ttw-2026-10-14/`. Nothing was uploaded or added to promotional assets. + +Automated mouse/keyboard input did not reliably navigate from the menu into New. No new-game confirmation, gameplay, save creation or save loading was observed. This is an automation limitation encountered during the test, not evidence that human controls are broken. The game and manager exited after Alt+F4. All 31 protected original/previous-candidate files and all 12 new-candidate profile files retained their hashes; the candidate saves folder remained empty. Steam's previous **All System Audio** preference was restored and microphone remained off. + +Private preparation, process, profile, recording and decoded-playback evidence stays in ignored `test-results/native-acceptance/ttw-steam-context/`. This pass establishes direct launch to the menu and actual game-video capture. A recorded disposable new game, save/reload, human keyboard/mouse/controller checks, mod behavior, maintenance after gameplay, the revised candidate's Steam/Desktop shortcuts and clean-machine/provider installation remain open. The earlier shortcut recording-identity problem was not retested or declared fixed. + +### Verification after MO2 ran + +The actual r4 library's subsequent **Verify recipe files** failed and retained the previous successful verification timestamp. A complete read-only comparison of all 13,951 static outputs found 13,732 exact matches and 219 differences: 217 larger CPython plugin caches under `__pycache__`, plus two profile-order files. Every adjacent `.py` source for those caches was still present in the recipe and matched its recorded SHA-256. The regenerated caches were retained, not restored to force a passing check. + +`loadorder.txt` and `plugins.txt` already differed from the recipe before this session and retained those same hashes afterward. Each contains the same 35 plugin names as the original, with 17 positions changed; this is ordering drift, not a missing-plugin or line-ending difference. The original installed profile still matches the recipe. No new profile change or game-save creation occurred in this session. The cache exclusion does not resolve this earlier order drift: its cause and compatibility with the installed baseline remain a separate acceptance gate. Do not silently accept the changed order or modify the original profile. + +Source now excludes those regenerable instance-plugin caches from future inventories when their ordinary source exists, while retaining source-less/standalone bytecode and all mod/game content. Existing recipes still require their declared bytes and therefore still report this drift. The verifier now identifies the relative recipe file when its ordinary-file/size check fails, without exposing the absolute installation path. A fresh reviewed recipe and separate reconstruction must exercise the new inventory boundary before post-launch verification can be certified. The r4 executable and source ZIP remain unchanged. + +A fresh metadata inventory of the original TTW installation excludes the same 217 regenerable caches and retains 1,080 instance files, 279 game files and 12 selected-profile files. This is a read-only boundary check, not a fresh full-hash baseline or rebuilt recipe. Regression checks cover preserved sources and bytecode-only content, source-change detection, strict existing-recipe verification, unchanged verification timestamps after failure and the relative error displayed through the actual Electron bridge. The full local suite passed 184 tests with one optional skip; Svelte checks reported zero errors and warnings. + +## Timestamp-based order diagnosis + +The subsequent candidate-only comparison isolated a metadata problem. All 35 winning plugin files matched the original installed SHA-256 values, and bounded TES4-header inspection found no dependency-order violations in either ordering. The original plugin modification dates encoded its intended priority (January 1 through February 4, 2000). The candidate's timestamps encoded the changed order instead. Merely preserving `loadorder.txt` and `plugins.txt` bytes was insufficient. + +With backups retained, opening and closing the actual MO2 `2.5.2-ML1.5` GUI preserved restored baseline profile bytes. Running its documented command-line path with a pre-existing 7-Zip information command reproduced the changed profile order while the candidate's prior plugin timestamps were present. Repeating that same command with all 35 original plugin timestamps preserved both order files exactly: SHA-256 `b0222e8e90f5212fce42360a4629bbe2215b6de947fa5c34403b6815ce61a6fb`. The test child and MO2 exited. No game ran in these diagnostic probes. + +The observed result is consistent with [MO2's timestamp-writing implementation](https://github.com/ModdingLinked/modorganizer/blob/9c130cbf2fc7225fb2916e46419af50671772aa0/src/pluginlist.cpp) and [Gamebryo's timestamp-based order reader](https://github.com/ModOrganizer2/modorganizer-game_gamebryo/blob/0d644dbcc9f3e63ededed5eb04f5077818427967/src/gamebryo/gamebryogameplugins.cpp). The first revision matches the running manager's revision; the second is a historical source reference, not a proven plugin binary build identity. No upstream code was copied into Loadstone. + +The earlier candidate's configuration, two profile-order files and all 35 plugin timestamps were restored to their pre-diagnostic state afterward. Original installed plugin bytes/timestamps were rechecked unchanged. Private probes, source references and restoration evidence are retained in ignored `test-results/native-acceptance/ttw-order/`. + +The native format now supports explicit optional `mtimeMs` on static outputs; inventory retains winning-plugin timestamps. Copy, ZIP, 7z and RAR reconstruction apply the declaration after hashing, and verification/recovery/repair/removal account for metadata-only differences. Legacy recipes keep their existing identity and behavior. Local validation passed 192 tests with one optional skip and zero Svelte errors/warnings, including actual Electron reconstruction and verification, source preservation, metadata-write failure, final-verification drift, recovery retention and installed repair/removal. These changes require a fresh reviewed recipe and reconstruction. They do not turn the earlier diagnostic candidate or r4 package into a newly verified release; recorded gameplay/save/controller acceptance remains open. + +--- + +# Earlier VNV acceptance + +Canonical source: `docs/vnv-acceptance.md` + +Status: **preflight checked, installation and gameplay not accepted**. This record is from local checks on 2026-10-01 against Loadstone source commit fbd79fd82ea85bfbf512b8f3561835da52292307. It does not authorize publication or describe a supported one-click list. + +## Inputs and evidence + +- Locally cached Viva New Vegas 11.8.26 by ModdingLinked. Archive SHA-256: `8eaaae1f4c34ca061b178a2a43802ab1f899d380ddc2b84f9bda6be127f33cae`. +- Original pinned Wabbajack 4.2.3.0, prepared from the previously downloaded official ZIP through Loadstone's normal hash/extraction/inventory checks. No engine download was needed. +- Local Steam Fallout: New Vegas 1.4.0.525, six required game-source masters, and a separate empty installation destination. The private manifest reserves 24 GB including downloads and temporary headroom. +- The local manifest pins this host's game files by SHA-256. These are acceptance snapshot identifiers, **not creator-published supported-game hashes**. Existing game modifications have not been ruled out, so this cannot replace clean-machine acceptance. +- Archive metadata declares 153 source archives, 17,630 output files, 3,079,270,181 download bytes and 9,232,895,295 output bytes. Providers are Nexus, HTTP and game-file sources. +- Selected profile: Viva New Vegas Extended. The embedded MO2 configuration contains the New Vegas launch entry, matching the creator's current launch guidance. + +The real preflight passed game hash, required files, list archive/metadata, destination/storage, engine integrity and engine game-selection checks. Nexus access failed because the separate Wabbajack application has a saved login that would override Loadstone's connection. Only existence of that credential file was checked; its contents were not read or changed. The isolated Loadstone workspace has no Nexus connection. + +The same candidate was opened in the actual Electron application. Its compatibility screen displayed the Nexus blocker and no installation jobs were created. Inspecting that rendered screen also exposed an engine-repair error on the second verification: the CLI had created `logs/wabbajack-cli.current.log` next to its executable. This change permits only the pinned CLI’s regular log filenames while preserving payload verification, rejects injected files in the log folder, and sanitizes executable-relative logs after installer exit. The engine success above describes the initial real preflight; the genuine-engine regression subsequently passed repeated verification, and the actual Electron UI repeated the compatibility check with the engine ready and only the Nexus blocker remaining. Game preparation and install-to-play acceptance remain open. Local JSON reports and a screenshot were retained outside tracked source; game files, the existing modlist installation, Desktop and Steam shortcuts were not modified. + +## Required game setup is still missing + +The [creator's Wabbajack guide](https://vivanewvegas.moddinglinked.com/wabbajack.html), inspected on 2026-10-01, requires root-file installation and the FNV patcher, plus post-install manager/game checks. The cached archive itself contains `__Files Requiring Manual Install\FNVpatch.exe` and `__Files Requiring Manual Install\nvse_loader.exe`, as well as a Vanilla BSAs Patcher directory. Wabbajack completing its declared output files does not perform or prove all those steps. + +Loadstone now supports an optional `launch.gameRoot` declaration for creator-authored Stock Game lists, verifying their archive output and MO2 game/launch paths. The cached VNV archive does not contain that layout. Its required manual game preparation still has no automatic adapter. Structural/output checks could pass while the game is not ready. An already configured developer machine could conceal this gap. Connecting Nexus alone does not resolve it. + +Before advertising this candidate as one-click ready: + +1. Define creator-declared game preparation requirements and distinguish installed files from a verified launch-ready setup. Imported manifests must not silently imply that external/manual prerequisites are complete. +2. Implement and verify the supported game preparation path. Prefer an isolated game copy when compatible with the list; otherwise define explicit file ownership, original-file backups, expected input/output hashes and rollback before any shared-game write. Do not introduce arbitrary manifest shell commands. +3. Account for executable patching and MO2 target configuration, then repeat compatibility checks on a clean game installation. Runtime download hashes alone do not verify game preparation. +4. Connect a user-provided Nexus account locally and resolve the conflicting Wabbajack login through that application's own UI. Never copy or read another application's saved credential. +5. Run download/install, cancellation/retry, restart, profile launch, creator utility checks, save/load, shortcuts, update coexistence and save-preserving removal acceptance. Record the exact source commit and list/game/engine identities. + +No antivirus exclusion or security-setting change has been made. No archive or game asset is included in this repository. This candidate and its private manifest remain local test inputs, not a redistributed or endorsed Loadstone release. + +--- + +# Preview 0.1 review + +Canonical source: `docs/review-0.1.md` + +The Windows UI MVP is ready to review. It implements the approved visual direction in Svelte and Electron, with persistent dummy data that can be disabled in Settings. + +## Suggested walkthrough + +- Discover: filter by game, search, select another setup, and open its details. +- Install setup: change the destination and shortcut preferences; begin a demo installation. +- Downloads: pause, resume, cancel, retry, and clear completed/cancelled jobs. +- Restart during an install: the job returns paused and can resume. +- My library: launch a demo session, verify its plan, view details, or remove the setup. +- Settings: toggle dummy data off and back on. Demo state is preserved, but hidden and blocked while off. +- Change shortcut defaults and reduced motion, then restart to check persistence. +- Browse for a folder, export logs, and reset the demo workspace. +- Resize or maximize the app and navigate using the keyboard. + +## Verification performed + +- Svelte/TypeScript check: zero errors and zero warnings. +- Persistent state engine: live-mode mutation guards, duplicate prevention, pause recovery, completion, uninstall, invalid inputs, and settings retention. +- End-to-end tests run against the **packaged Loadstone.exe**, not only the browser/source build: discovery, filters, search, details, install, pause, resume after restart, completion, library, launch, verification, settings persistence, dummy-data isolation, uninstall, cancel/retry, and reset. +- Window minimize/maximize controls, minimum-size horizontal layout, and dialog keyboard focus containment. +- Folder and log-export IPC handlers exercised with controlled native-dialog return values; the log file was actually written and inspected. +- Portable **Loadstone-0.1.0-Windows.exe**: extraction, launch, renderer and bridge, persistent setting mutation, live-mode empty state, and clean wrapper/app shutdown. +- No renderer page errors during the end-to-end review journey. + +Generated verification records are included beside this document. Screenshots come from the running Electron application. + +## Intended limits + +This is a UI MVP. All modlists, game requirements, installation sizes, checks, downloads, profile creation, game launches, and per-setup shortcuts are simulated. Folder selection, preferences, local logs, window controls, and app persistence are real. No live Nexus, Wabbajack, MO2, or Steam integrations are incorporated yet. The Windows portable executable is unsigned. + +![Discover](screenshots/discover.png) + +![Library](screenshots/library.png) + +![Settings](screenshots/settings.png) diff --git a/handbook/catalog.mjs b/handbook/catalog.mjs new file mode 100644 index 0000000..078f619 --- /dev/null +++ b/handbook/catalog.mjs @@ -0,0 +1,319 @@ +// Explicit public-source allowlist. Add new documentation here with its audience. +export const groups = [ + 'Start here', + 'Use Loadstone', + 'Create setups', + 'Develop', + 'Release & trust', + 'Archive', +]; +const page = (id, title, file, group, summary) => ({ + id, + title, + file, + group, + summary, +}); +export const pages = [ + page( + 'welcome', + 'The Loadstone handbook', + 'handbook/pages/welcome.md', + 'Start here', + 'A practical field guide to your next playthrough.', + ), + page( + 'quick-start', + 'Your first setup', + 'handbook/pages/quick-start.md', + 'Start here', + 'From an owned game to a reviewed native candidate.', + ), + page( + 'concepts', + 'How Loadstone works', + 'handbook/pages/concepts.md', + 'Start here', + 'Packages, sources, candidates and isolated profiles.', + ), + page( + 'troubleshooting', + 'Troubleshooting', + 'handbook/pages/troubleshooting.md', + 'Start here', + 'Diagnose downloads, verification, launch and recovery.', + ), + page( + 'glossary', + 'Glossary', + 'handbook/pages/glossary.md', + 'Start here', + 'The terms used throughout the app and creator tools.', + ), + page( + 'native-guided-install', + 'Install a native setup', + 'docs/native-guided-install.md', + 'Use Loadstone', + 'The guided .loadstone installation workflow.', + ), + page( + 'native-downloads', + 'Source downloads', + 'docs/native-downloads.md', + 'Use Loadstone', + 'Original archives, fingerprints and cache reuse.', + ), + page( + 'native-manual-downloads', + 'Manual Nexus downloads', + 'docs/native-manual-downloads.md', + 'Use Loadstone', + 'Browser handoff and exact local-file verification.', + ), + page( + 'nexus', + 'Nexus account', + 'docs/nexus.md', + 'Use Loadstone', + 'Personal API keys, account access and local storage.', + ), + page( + 'native-library', + 'Library, launch & shortcuts', + 'docs/native-library.md', + 'Use Loadstone', + 'Admit candidates, launch profiles and manage shortcuts.', + ), + page( + 'native-build-recovery', + 'Resume an interrupted build', + 'docs/native-build-recovery.md', + 'Use Loadstone', + 'Review recovery and retain conflicting files.', + ), + page( + 'native-repair', + 'Repair a setup', + 'docs/native-repair.md', + 'Use Loadstone', + 'Restore missing files while preserving local changes.', + ), + page( + 'native-updates', + 'Install another version', + 'docs/native-updates.md', + 'Use Loadstone', + 'Keep the original playthrough and build a separate version.', + ), + page( + 'native-maintenance', + 'Remove & recover', + 'docs/native-maintenance.md', + 'Use Loadstone', + 'Reviewed removal and retained saves, settings and files.', + ), + page( + 'installation', + 'Wabbajack installation', + 'docs/installation.md', + 'Use Loadstone', + 'The separate engine-backed installation path.', + ), + page( + 'runtime', + 'Wabbajack runtime', + 'docs/runtime.md', + 'Use Loadstone', + 'Prepare and verify the external installation engine.', + ), + page( + 'creator-workflow', + 'Creator workflow', + 'handbook/pages/creator-workflow.md', + 'Create setups', + 'Inventory installed truth and build a reproducible recipe.', + ), + page( + 'installed-inventory', + 'Inventory & source mapping', + 'docs/installed-inventory.md', + 'Create setups', + 'Read-only MO2 inventory, archive hints and exact comparisons.', + ), + page( + 'loadstone-format', + 'The .loadstone format', + 'docs/loadstone-format.md', + 'Create setups', + 'The documented experimental package and recipe specification.', + ), + page( + 'native-reconstruction', + 'Native reconstruction', + 'docs/native-reconstruction.md', + 'Create setups', + 'Typed file operations, verification and limits.', + ), + page( + 'native-mo2-configuration', + 'MO2 configuration', + 'docs/native-mo2-configuration.md', + 'Create setups', + 'Destination-bound, isolated manager configuration.', + ), + page( + 'bsa-inspection', + 'BSA inspection & mapping', + 'docs/bsa-inspection.md', + 'Create setups', + 'Verify original archive → BSA → inner-file chains.', + ), + page( + 'manifests', + 'Live catalog manifests', + 'docs/manifests.md', + 'Create setups', + 'The separate manifest contract for external engines.', + ), + page( + 'development', + 'Development guide', + 'handbook/pages/development.md', + 'Develop', + 'Run, test and understand the Svelte/Electron architecture.', + ), + page( + 'repository', + 'Repository overview', + 'README.md', + 'Develop', + 'Source setup, implementation overview and distribution.', + ), + page( + 'contributing', + 'Contributing', + 'CONTRIBUTING.md', + 'Develop', + 'Branch workflow, source boundaries and notices.', + ), + page( + 'agents', + 'Working with agents', + 'AGENTS.md', + 'Develop', + 'Repository instructions and the complete agent edition.', + ), + page( + 'documentation', + 'Maintain this handbook', + 'handbook/pages/documentation.md', + 'Develop', + 'Single-source pages, navigation, checks and local builds.', + ), + page( + 'brand', + 'Brand system', + 'handbook/pages/brand.md', + 'Develop', + 'The mark, palette, typography and asset generation.', + ), + page( + 'review', + 'Verification checklist', + 'docs/review.md', + 'Develop', + 'Fixture checks and their practical limits.', + ), + page( + 'release-plan', + 'Path to 1.0', + 'docs/1.0-plan.md', + 'Release & trust', + 'Implemented behavior and remaining acceptance gates.', + ), + page( + 'changelog', + 'Changelog', + 'CHANGELOG.md', + 'Release & trust', + 'Version history and compatibility notes.', + ), + page( + 'privacy', + 'Privacy & local data', + 'docs/privacy.md', + 'Release & trust', + 'What is stored, transmitted and exported.', + ), + page( + 'security', + 'Security', + 'SECURITY.md', + 'Release & trust', + 'Scope, supported versions and reporting.', + ), + page( + 'open-source', + 'Open-source release', + 'docs/open-source.md', + 'Release & trust', + 'GPL scope, corresponding source and third-party rights.', + ), + page( + 'artwork', + 'Artwork provenance', + 'docs/artwork.md', + 'Release & trust', + 'Original assets, generated media and licensing scope.', + ), + page( + 'private-preview', + 'Package a preview', + 'docs/private-preview.md', + 'Release & trust', + 'Isolated output and corresponding-source verification.', + ), + page( + 'steam-release', + 'Steam packaging', + 'docs/steam-release.md', + 'Release & trust', + 'Prepare a depot and verify the staged executable.', + ), + page( + 'steam-submission', + 'Steam submission draft', + 'docs/steam-submission.md', + 'Release & trust', + 'Draft copy and the remaining submission requirements.', + ), + page( + 'publication-audit', + 'Publication hygiene', + 'docs/publication-audit.md', + 'Release & trust', + 'Audit scope, historical findings and manual review.', + ), + page( + 'native-steam-acceptance', + 'Native Steam acceptance', + 'docs/native-steam-acceptance.md', + 'Archive', + 'Versioned observations; menu launch is not gameplay certification.', + ), + page( + 'vnv-acceptance', + 'Earlier VNV acceptance', + 'docs/vnv-acceptance.md', + 'Archive', + 'Historical engine integration evidence.', + ), + page( + 'review-0-1', + 'Preview 0.1 review', + 'docs/review-0.1.md', + 'Archive', + 'Historical checks for the original demo.', + ), +]; diff --git a/handbook/index.html b/handbook/index.html new file mode 100644 index 0000000..6357369 --- /dev/null +++ b/handbook/index.html @@ -0,0 +1,12 @@ + + + + + + + + + Loadstone Handbook + +
+ diff --git a/handbook/pages/brand.md b/handbook/pages/brand.md new file mode 100644 index 0000000..4ddba95 --- /dev/null +++ b/handbook/pages/brand.md @@ -0,0 +1,39 @@ +# Brand system + +**Loadstone** is the product spelling. **Your next playthrough, ready.** is the primary line. The identity combines a dark mineral palette, warm copper and a compact carved **L**. Use clear typography and generous spacing; let the mark carry the theme. + +## The mark + +`public/brand/mark.svg` is the single editable geometry source. The three faces describe one solid shape, with an open counter and a restrained edge highlight. Keep its proportions, negative space and colors together. Do not add extra compass points, bevel filters, outlines or tiny ornaments. + +Use the freestanding mark on dark surfaces. The app tile adds a charcoal rounded square and a fine edge; its SVG, 512px PNG and seven-size Windows ICO are generated from the mark. The 16/24/32/48/64/128/256px ICO frames are rendered individually for native use. + +```powershell +pnpm assets:icon +pnpm assets:steam +``` + +The generators use the locked Electron renderer in a hidden window. The desktop component and handbook import the same vector. Never redraw the mark separately in CSS or a second polygon script. + +## Palette + +| Role | Color | Use | +| --- | --- | --- | +| Basalt | `#1B2227` | App tile, navigation and dark brand fields | +| Copper | `#D9AD87` | Primary mark face and dark-surface accent | +| Cut edge | `#A97652` | Restrained shadow face | +| Light edge | `#F0CFAD` | Small highlighted face | +| Paper | `#F7F5F0` | Handbook reading surface | +| Ink | `#263036` | Text on paper | + +Copper used for the mark is not automatically suitable for small text on a light background. The handbook uses darker accent text for contrast, visible keyboard focus and underlined prose links. + +## Typography and tone + +Use the system UI family, led by Segoe UI on Windows. The wordmark uses normal title case, a medium/semibold weight and tight but readable spacing. Body copy should be calm, concrete and direct. Avoid all-caps slogans, exaggerated tracking and claims that turn development targets into finished support. + +## Asset review + +Inspect the icon at actual small sizes on light and dark backgrounds, in the app header and in a staged executable. Check Steam crop previews before submission. Store artwork remains draft until its review; a generated capsule is not evidence of a playable setup. Existing screenshots and recordings retain their capture version and should not be silently relabeled after a visual refresh. + +Source licensing and artwork/trademark scope are described in [artwork provenance](../../docs/artwork.md) and [COPYRIGHT](../../COPYRIGHT). This visual refinement does not change those terms. diff --git a/handbook/pages/concepts.md b/handbook/pages/concepts.md new file mode 100644 index 0000000..41c62c4 --- /dev/null +++ b/handbook/pages/concepts.md @@ -0,0 +1,29 @@ +# How Loadstone works + +Loadstone brings source selection, reconstruction, verification and a playable library into one desktop workflow. The app keeps these steps explicit so a failed download, a locally edited file and an untested game launch are not mistaken for the same problem. + +## Native packages and external manifests + +A **native `.loadstone` package** uses Loadstone's documented experimental recipe format. Its actions are typed file operations, with declared sizes and hashes. It can refer to original downloads, owned games and prepared prerequisites, and may include permitted payloads. See the [format reference](../../docs/loadstone-format.md). + +A **live catalog manifest** belongs to the separate external-engine path. Wabbajack integration prepares and runs a verified external runtime; it does not turn any file with a familiar extension into a supported native package. See [manifest requirements](../../docs/manifests.md) and the [runtime guide](../../docs/runtime.md). + +## From source to library + +**Sources → reviewed plan → candidate → verification → admission → launch.** + +Sources are locked inputs. A plan checks prerequisites and a separate destination. The builder creates a candidate and checks every required output. Admission reviews that completed candidate before creating a library entry. Launch uses its declared manager/profile configuration. Desktop and Steam shortcuts are explicit operations associated with that setup. + +## Exact bytes and local state + +A SHA-256 fingerprint plus a byte count identifies the expected file content. Some outputs also require a declared modification time, because game tooling may use timestamps for ordering. File verification does not compare visual similarity or assume that a newer mod download is interchangeable with the pinned original. + +Save files, user settings and unexpected files are a different kind of state. Maintenance must preserve them according to the reviewed operation. Restoring recipe configuration is a separate repair choice because it can replace deliberate local settings. + +## Sources inside sources + +A loose file can originate inside a BSA container inside an original ZIP, 7z or RAR download. Native BSA reconstruction records every link in that chain. The [creator mapper](../../docs/bsa-inspection.md#nested-source-mapping) checks those links before recording a match. Arbitrary nested installers and generated transformations are not implied by BSA support. + +## Evidence and permission + +An installed inventory says what is present. A source match says where the exact bytes can be obtained. A recipe says how to produce the output. A rights review says what can be distributed. Acceptance says whether the result works in the intended environment. None of these replaces the others. diff --git a/handbook/pages/creator-workflow.md b/handbook/pages/creator-workflow.md new file mode 100644 index 0000000..f681fd6 --- /dev/null +++ b/handbook/pages/creator-workflow.md @@ -0,0 +1,37 @@ +# Creator workflow + +Start with a specific installed version and its chosen profile. An upstream list is a useful lead, but it does not necessarily describe local changes, generated output, disabled mods or the files that are actually in use. + +## 1. Capture installed truth + +Use the [inventory tooling](../../docs/installed-inventory.md) to record hashes, mod ordering and enabled states, profile configuration, instance/game files and overwrite content. Preserve existing saves and live installations. Keep the inventory outside source control: it contains private paths and installed-content names. + +## 2. Find and prove sources + +Build a private source ledger from the accepted inventory and selected download folders. Add explicit creator hints when automatic archive leads are incomplete. Compare original ZIP/7z/RAR members by exact size and SHA-256. An adjacent metadata ID is a lead, not proof of the file's contents or its rights. + +For installed BSA containers, use [nested BSA mapping](../../docs/bsa-inspection.md#nested-source-mapping) to verify the original member and its internal files. Keep unresolved generated/edited files visible. A similar filename or rendered image is not an exact replacement. + +## 3. Review rights and required inputs + +For every distributed source or asset, record authorship, attribution, permitted delivery and the required user-owned inputs. Original downloads, local owned-game reconstruction and hosted payloads are distinct cases. A local file that happens to install successfully is not automatically redistributable. Loadstone's GPL license does not grant rights to third-party mods or game files. + +## 4. Write a typed recipe + +Use the [format reference](../../docs/loadstone-format.md) for exact field names and limits. Declare outputs with hashes and required timestamps. Prefer original archive sources when supported; declare prepared prerequisites honestly where automatic conversion is not implemented. Configure portable MO2 with the [destination-bound configuration action](../../docs/native-mo2-configuration.md). Do not import account/browser state or arbitrary shell scripts. + +## 5. Compile and inspect + +Compile the recipe into a package and inspect it before reconstruction. Review source hosts, requirements, output paths, storage, profile and save guidance. Package validation must succeed independently of any installed baseline used to create it. The native [reconstruction guide](../../docs/native-reconstruction.md) documents CLI and desktop entry points. + +## 6. Reconstruct and compare + +Build into a new isolated candidate. Verify every required output and declared timestamp, then compare against the intended baseline. Exercise cancellation, reviewed resume and relevant maintenance behavior with disposable candidates. Do not substitute a successful inventory scan for actual reconstruction. + +## 7. Accept the playable setup + +Review library admission, launch, shortcuts, a disposable new game, save/reload and the intended input devices. Repeat on a clean Windows environment with the required owned games and sources. Record exact app, recipe, game, manager and tool versions. A menu launch is only one step. + +## 8. Prepare publication + +Complete credits, source permissions, support instructions, truthful screenshots and the release checklist. Featured status indicates Loadstone maintenance, not endorsement by upstream authors or publishers. Publication remains a separate action after the [acceptance gates](../../docs/1.0-plan.md) are met. diff --git a/handbook/pages/development.md b/handbook/pages/development.md new file mode 100644 index 0000000..2bf7d10 --- /dev/null +++ b/handbook/pages/development.md @@ -0,0 +1,52 @@ +# Development guide + +The desktop app uses Svelte 5, TypeScript, Vite and Electron. Native installation and packaging target Windows x64. The handbook is a separate static Svelte application using the same locked toolchain; its build is not included in the desktop bundle. + +## Set up the repository + +Use Node.js 22 or later and pnpm 11 or later. Install the committed lockfile, then run diagnostics and the application: + +```powershell +pnpm install --frozen-lockfile +pnpm check +pnpm start +``` + +Do not point development or test state at a real playthrough. Automated fixtures use temporary directories. `LOADSTONE_DATA_DIR` isolates app state, but does not redirect Desktop or Steam integration by itself. + +## Find the implementation + +| Area | Entry point | +| --- | --- | +| Desktop UI | `src/App.svelte`, native workflow components and `src/styles.css` | +| Shared brand | `public/brand/mark.svg`, consumed by `src/Logo.svelte` and asset generators | +| Process boundary | `electron/main.cjs` and `electron/preload.cjs` | +| Demo state | `electron/store.cjs` | +| Native recipe validation | `electron/native-format.cjs` | +| Package inspection | `electron/native-package.cjs` | +| Reconstruction | `electron/native-materializer.cjs` and archive/BSA adapters | +| Creator evidence | `electron/installed-inventory.cjs`, `source-ledger.cjs`, `archive-mapping.cjs`, `bsa-mapping.cjs` | +| Handbook | `handbook/`, its source catalog and `scripts/handbook.mjs` | +| Verification | `tests/`, including actual Electron workflows | + +Keep filesystem access, credentials and process creation in the main process. The renderer receives a limited typed bridge. Validate IPC arguments and preserve unrelated files throughout failure and recovery paths. + +## Run checks + +```powershell +pnpm check +pnpm test +pnpm handbook:check +pnpm handbook:test +git diff --check +``` + +Some archive tests require a trusted 7-Zip executable selected through `LOADSTONE_TEST_7ZIP`; CI prepares a pinned tool. An optional external-runtime test may skip without its prerequisite. Report skips and real acceptance gaps explicitly. For a native behavior change, use the relevant actual Electron path as well as unit fixtures. + +## Build artifacts + +`pnpm package` prepares the unsigned portable Windows preview. `pnpm package:steam` prepares a separate unpacked Steam depot preview. Both rely on generated notices and build provenance. They do not upload a release. Read [preview packaging](../../docs/private-preview.md) and [Steam packaging](../../docs/steam-release.md) before handing off an artifact. + +## Finish a change + +Keep the implementation, regression coverage and canonical documentation together. Regenerate the handbook agent edition with `pnpm handbook:sync`. Review public files and media for private information, then use the contribution/PR workflow. A code merge does not certify a public stable release or approve publishing a setup. diff --git a/handbook/pages/documentation.md b/handbook/pages/documentation.md new file mode 100644 index 0000000..17475ee --- /dev/null +++ b/handbook/pages/documentation.md @@ -0,0 +1,47 @@ +# Maintain this handbook + +The handbook is a local Svelte site built from repository Markdown. Detailed specifications stay in `docs/`; practical guides live in `handbook/pages/`. The catalog explicitly lists approved public pages with their audience, title and summary. There is no database or hosted content service. + +## Run it locally + +```powershell +pnpm handbook:dev +``` + +Open the loopback URL printed by Vite. The site has local full-text search, grouped navigation, section links, mobile navigation, previous/next pages, source links and a downloadable agent edition. No deployment is performed. + +For a static preview: + +```powershell +pnpm handbook:build +pnpm handbook:preview +``` + +The generated site goes into ignored `handbook/dist/`. Its hash-based routes work on an ordinary static server without rewrite rules. Assets, page content and dependency notices are local. External reference/source links open only when selected. + +## Update a page + +Edit the canonical Markdown file whenever behavior changes. The site compiles that file directly; do not create a second manually maintained copy of its technical specification. Update examples, limitations and recovery steps together. Put past observations in historical records and identify their version, rather than presenting them as current release certification. + +## Add a page + +Add the Markdown file and a record in `handbook/catalog.mjs`. Choose a group that matches its intended reader. Use normal relative Markdown links to other source pages. Heading links are checked against generated section IDs. Source-code and other repository-file links point to the public repository; screenshots referenced by approved documents are copied into the local build. + +Raw HTML is shown as text. The compiler accepts normal Markdown and approved local image files, and rejects unsafe URL schemes. Do not add remote image trackers, scripts or private repository paths. + +## Keep the agent edition aligned + +```powershell +pnpm handbook:sync +pnpm handbook:check +``` + +`handbook/agents.md` is the complete generated Markdown edition. The root `AGENTS.md` is its concise contributor entry point. The site serves the complete edition as `agents.md`. Its contents are source-backed reference material; command examples are not authorization to execute actions. + +The check verifies catalog coverage, unique routes, local documentation links and headings, and exact agreement with the committed agent edition. `pnpm handbook:test` builds the site and exercises actual browser navigation, search, deep links, keyboard access, code copying and all pages at desktop/mobile widths. CI runs both commands. After changing documentation, commit the regenerated edition with the source edits. Do not edit it by hand. + +`handbook:check` prepares the ignored page data before Svelte diagnostics, so it works on a fresh checkout without a preceding site build. A stale committed agent edition still fails before preparation; the command does not silently update that committed file. + +## Public-source boundary + +Only catalog-listed files from this repository are eligible. Do not scan parent workspaces, include acceptance logs or copy personal inventories into a page. Keep credentials and game/mod payloads outside both Git and the handbook output. Building or updating the site does not publish it. diff --git a/handbook/pages/glossary.md b/handbook/pages/glossary.md new file mode 100644 index 0000000..99e88c6 --- /dev/null +++ b/handbook/pages/glossary.md @@ -0,0 +1,27 @@ +# Glossary + +| Term | Meaning in Loadstone | +| --- | --- | +| Admission | Explicit review and registration of a verified candidate in My library. | +| Archive candidate | A possible original download identified by metadata or creator hints; not yet a proven source. | +| BSA | A Bethesda resource container. Current native inspection/reconstruction supports a bounded version-104 subset. | +| Candidate | A newly reconstructed installation folder awaiting verification, admission or gameplay acceptance. | +| Corresponding source | The source and build material required by the applicable software license for a distributed build. | +| Direct match | An exact installed file found as a member of an original archive. | +| Fingerprint | The file's expected byte count and SHA-256 content hash. | +| Inventory | A record of the selected installed setup, including file identities and mod/profile state. | +| Ledger | Private evidence linking an inventory to possible and verified original sources. | +| Manifest | A catalog description for the separate external-engine installation path. | +| MO2 | Mod Organizer 2, an external manager used by supported portable profile layouts. | +| Native package | A `.loadstone` package interpreted by Loadstone's own typed reconstruction engine. | +| Nested match | A verified original archive → container → inner-file source chain. | +| Original archive | The exact upstream download locked by a recipe or ledger. | +| Prepared prerequisite | A local folder of declared required files; the app checks it without executing a converter. | +| Profile | The selected mod order, plugins, settings and save-isolation configuration for a setup. | +| Recipe | The declarative requirements, sources, outputs and typed actions for a native package. | +| Receipt | Durable evidence of a build/maintenance operation; incomplete receipts do not certify a complete setup. | +| Recovery folder | Retained originals or protected content from an interrupted or reviewed maintenance operation. | +| TTW | Tale of Two Wastelands, a conversion with its own source-game and distribution requirements. | +| Wabbajack | An external modlist installation engine; its integration is separate from native `.loadstone` reconstruction. | + +For the full workflow, read [How Loadstone works](concepts.md). diff --git a/handbook/pages/quick-start.md b/handbook/pages/quick-start.md new file mode 100644 index 0000000..46c9875 --- /dev/null +++ b/handbook/pages/quick-start.md @@ -0,0 +1,29 @@ +# Your first setup + +Start with a trusted `.loadstone` package and the source games and files it declares. The current app is a developer preview; there is no generally accepted featured catalog ready to promise a one-click playable result. + +## Before you open a package + +Use Windows and keep your existing playthrough intact. Check the setup's game edition, prerequisites, storage needs and save guidance. Choose a new destination with room for the completed installation and any temporary archive work. A package containing a recipe does not automatically contain the mods or game files it references. + +If building the app from source, follow [development setup](development.md). An existing portable preview can be run directly, but its included feature set is determined by its recorded build revision. + +## Install and review + +1. Choose **Set up real installations** on first run. If you explored the demo, disable **Use dummy data** in Settings when ready for real work. +2. In Discover, choose **Open .loadstone**. Read the package identity, declared requirements and save guidance. +3. Select the owned game folders, original archives and prepared prerequisites requested by the guide. Use [manual Nexus downloads](../../docs/native-manual-downloads.md) or the available [source download workflow](../../docs/native-downloads.md) when applicable. +4. Choose a separate destination and review the plan. Fix missing or mismatched inputs before starting. +5. Follow the job in Downloads. Cancellation retains evidence for [reviewed resume](../../docs/native-build-recovery.md); do not manually mix files from different attempts. +6. After final verification, review the completed candidate and explicitly add it to My library. A completed job is not automatically admitted or certified playable. +7. Review the [launch requirements and shortcut options](../../docs/native-library.md). Use a disposable new game for first acceptance where the setup's save guidance requires it. + +## What if I only want to look around? + +Choose **Explore the demo**. Its fictional setups, downloads, validation and launch sessions are simulated. Demo mode does not prove that a real modlist will install. Your demo preferences are separate from native candidate files. + +## What happens next? + +Use library verification to detect file differences. [Repair](../../docs/native-repair.md) can restore missing or damaged recipe files while preserving local changes by default. [Install another version](../../docs/native-updates.md) builds a separate candidate. [Removal](../../docs/native-maintenance.md) reviews what can be removed and retains protected content. + +Do not copy an old save into a new setup merely because both use the same game. Follow the specific setup's compatibility guidance and verify a disposable save/reload first. diff --git a/handbook/pages/troubleshooting.md b/handbook/pages/troubleshooting.md new file mode 100644 index 0000000..bcfac1f --- /dev/null +++ b/handbook/pages/troubleshooting.md @@ -0,0 +1,39 @@ +# Troubleshooting + +Begin with the operation that failed, its exact setup version and the build identity shown by the app. Preserve the failed candidate and recovery folders while investigating. Export the app's diagnostic summary when useful; inspect it before sharing and keep raw logs, private paths and account credentials private. + +## A source file does not match + +Check that it is the original archive and version requested by the recipe. An extracted folder, a renamed replacement or a newer upstream release is not an exact substitute. The filename is only a lead; the byte count and SHA-256 are decisive. Use the guide's verification and cancellation controls instead of bypassing the mismatch. Creators should update a recipe only after reviewing the new source and resulting outputs. + +## Nexus downloads are unavailable + +Check the account state and last verification in Settings. Automatic downloads require the declared access conditions, including fresh Premium verification where required. [Manual downloads](../../docs/native-manual-downloads.md) open the declared Nexus file page for normal browser interaction, then validate the selected original locally. A missing or removed upstream file remains a source problem; the app does not invent a mirror or bypass website controls. + +## The build was interrupted + +Use the [resume review](../../docs/native-build-recovery.md). Matching files can be reused, while conflicting files are retained before reconstruction. A receipt is not proof that a partially written directory is complete. For a registered setup with an interrupted repair, follow the fresh repair review before trying to launch. + +## Verification reports differences + +Distinguish an intentional configuration edit from a missing or damaged static output. [Same-version repair](../../docs/native-repair.md) preserves existing profiles/configuration by default and keeps replaced originals. Choose configuration restoration only when you intend to return to recipe settings. If a source no longer verifies, repair cannot safely replace it with another version. + +## Steam is running when I create a shortcut + +Follow the app's running-client safeguard and close Steam normally before retrying a shortcut write. Steam can rewrite its shortcut database while running. Shortcut creation is separate from launching a game or proving its Steam startup requirements. See [library and shortcut guidance](../../docs/native-library.md). + +## Steam load error or a game that will not start + +Check the recipe's owned edition, game folder, manager executable, profile and declared Steam app ID. The [Steam startup notes](../../docs/native-library.md#steam-game-startup) record a case resolved after a normal Steam restart. Do not treat repeated automated menu input as a gameplay test. Once launch works, use an appropriate disposable new game and verify save/reload separately. + +## A container cannot be inspected + +Confirm that the selected trusted archive tool is supported and that the original is complete. BSA inspection currently accepts a bounded subset of version 104. A rejected variant is not necessarily a corrupt game archive. Review [archive comparison limits](../../docs/installed-inventory.md) and [BSA limits](../../docs/bsa-inspection.md). Keep an unresolved issue explicit; do not accept partial matches from an unsafe container. + +## Removal retained a folder + +This can be expected. Saves, configuration, modified files and untracked content may remain in recovery. Read the removal review and [recovery rules](../../docs/native-maintenance.md) before deleting anything manually. A retained folder is not a reason to retry a recursive deletion. + +## Reporting a problem + +Include the Loadstone build/version, Windows version, operation, setup identity and the smallest reproducible sequence. Use synthetic inputs for a public reproduction where possible. Follow [security reporting](../../SECURITY.md) for sensitive findings and [privacy guidance](../../docs/privacy.md) for diagnostic exports. diff --git a/handbook/pages/welcome.md b/handbook/pages/welcome.md new file mode 100644 index 0000000..c27e06e --- /dev/null +++ b/handbook/pages/welcome.md @@ -0,0 +1,31 @@ +# The Loadstone handbook + +Your next playthrough starts with a setup you can understand. This handbook explains how to install, inspect, maintain and create Loadstone setups, with the same source documentation used by the project itself. + +Loadstone is a Windows developer preview built with Svelte and Electron. Native installation, source verification, recovery and library tools are implemented. Complete featured packages and 1.0 release acceptance are still in progress. A successful file check or a game reaching its menu is not a completed gameplay test. + +## Choose your path + +- **Players:** begin with [Your first setup](quick-start.md), then [install a native setup](../../docs/native-guided-install.md). Learn what review screens mean before admitting a candidate to your library. +- **Creators:** follow the [creator workflow](creator-workflow.md), starting with the installed version as evidence and tracing every required file to a reproducible source. +- **Contributors:** read the [development guide](development.md), [contribution rules](../../CONTRIBUTING.md) and [agent guide](../../AGENTS.md). Behavior and documentation should change together. + +## Game support direction + +| Game | Direction | What this means today | +| --- | --- | --- | +| Fallout: New Vegas | Primary support target | Native workflows are implemented; each setup still needs its own acceptance. | +| Fallout 3 | Through Tale of Two Wastelands | Standalone Fallout 3 is outside the supported direction. TTW requires the appropriate owned source games. | +| Fallout 4 | In development | Do not infer a tested setup from game detection or an example catalog entry. | +| Skyrim | In development | Source/edition requirements must be declared by the setup. | +| Starfield | Planned | Currently unsupported. | + +## Three different things to verify + +**Source identity:** the archive or owned-game file is exactly the version a recipe requests. **Reconstruction:** the resulting files and declared timestamps match the recipe. **Playable acceptance:** that particular game, profile and application version actually launch, play, save and reload correctly. Each answers a different question. + +## About this edition + +This is a local, searchable handbook. The pages are compiled from an explicit list of repository Markdown files; they are not fetched from a hosted service. Search includes page text. Source links lead to the matching public repository file. The complete Markdown agent edition is available from the navigation footer. Historical pages live in Archive and describe their own versions. + +For current release gates, use [Path to 1.0](../../docs/1.0-plan.md). For definitions, use the [glossary](glossary.md). For a failed operation, start with [troubleshooting](troubleshooting.md). diff --git a/handbook/src/App.svelte b/handbook/src/App.svelte new file mode 100644 index 0000000..8cb2952 --- /dev/null +++ b/handbook/src/App.svelte @@ -0,0 +1,393 @@ + + + + {article?.title || 'Page not found'} · Loadstone Handbook + + + + + +{#if mobileOpen}{/if} + + +
+
+ +
+ Handbook{article?.group || 'Not found'} +
+ Source +
+
+
+ {#if article} +
+ {route === 'welcome' + ? 'A FIELD GUIDE TO LOADSTONE' + : article.group.toUpperCase()}{Math.max(1, Math.ceil(article.words / 220))} min read +
+ {#if route === 'welcome'} +
+

Your next playthrough,
well documented.

+

+ Understand your setup. Build with confidence.
A guide for + players, creators and contributors. +

+
+ Developer preview · + Version {content.version} +
+
+
+
01 / PLAYERS
+

Find your starting point.

+

+ Install a setup, understand its sources and keep your + playthrough safe. +

+ Your first setup +
02 / CREATORS
+

Make it reproducible.

+

+ Turn an installed profile into a reviewed, verifiable recipe. +

+ The creator workflow +
+
+ Working on Loadstone itself?Open the development guide +
+ {:else}

{article.title}

+

{article.summary}

{/if} + {#if article.group === 'Archive'}
+ Historical record. These observations apply to the versions + identified on this page. +
{/if} + + +
{@html article.html}
+
+ View canonical source GPL-3.0-or-later · documentation +
+
+ {#if previous}PREVIOUS{previous.title}{:else}{/if} + {#if next}NEXT{next.title}{/if} +
+ {:else} +
+ OFF THE MAP +

That page isn't here.

+

+ The link may be outdated. Search the handbook or return to the + starting point. +

+ Back to the handbook +
+ {/if} +
+ {#if article}