Refine Loadstone branding and add the local Svelte handbook

.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: |

.gitignore

@@ -4,3 +4,6 @@ release/
 test-results/
 *.log
 .env*
+handbook/generated/
+handbook/public/
+handbook/dist/

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.

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.

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

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.
 

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.