docs(dist): lock in operator-execution guarantees (acquire/verify/footprint)

Makes the user-facing intent binding and verifiable so operator execution
matches documented intent.

Acquisition — two paths, same IUUT.exe (master doc §6.4, docs/INSTALL.md):
  - Path A: download the pre-built IUUT.exe + SHA256SUMS.txt from Releases,
    verify hash + Sigstore build-provenance attestation, double-click.
  - Path B: build from source via the §6.3 publish command.

Integrity — "verified signed hashes" with zero certificate cost:
  - release.yml (new) on a vX.Y.Z tag: builds the self-contained single-file
    IUUT.exe + IUUT-portable.zip, emits SHA256SUMS.txt, and attests build
    provenance via actions/attest-build-provenance (Sigstore). Users verify
    with Get-FileHash + `gh attestation verify`.
  - Authenticode signing documented as a future upgrade (needs a cert).

No-install / fire-and-forget / minimal footprint:
  - NG8: no installer, no admin/UAC, no registry, no Program Files, no
    Start-Menu entries, no machine-wide changes.
  - One state folder: %AppData%\IUUT\ (cache, DPAPI-encrypted key, logs),
    OR portable mode via an `IUUT.portable` marker -> .\IUUT-Data\ (nothing
    in AppData). Native single-file extraction pinned inside that folder.
  - Clean removal = delete the exe + the one folder. Save backups live inside
    the game's PlayerData folder by design (CONSTITUTION III), not scattered.

Auto-link save dir + manual fallback made explicit in §7.1.

Also:
  - Fixed the §7.5.1 cache-path inconsistency (%AppData%\IUUT\, was
    %AppData%\IcarusUltimateUtilityTool\).
  - IUUT.App.csproj: EnableCompressionInSingleFile in Release; footprint note.
  - publish-release.ps1 contract aligned (local dry-run; CI is canonical/attested).
  - README "Get IUUT" + doc index; DEVELOPMENT build-your-own-exe; CICD
    release-integrity model + runbook; MANUAL_CHECKLIST §11 (integrity) + §12
    (footprint/portable); CHANGELOG.
  - Master doc bumped to 1.3.0 (§24).

Verified: dotnet build 0/0, format clean, governance-lint clean (99 files).

Agent: claude-code/2.1.149
Consulted: AGENTS.md, .agent/CONSTITUTION.md#III,#V,#VII, .agent/SECURITY_PROTOCOL.md#5, .agent/HANDOFF_PROTOCOL.md#9, docs/IUUT-PROJECT-DOCUMENTATION.md#3.3,#6.1,#6.3,#6.4,#7.1,#7.5.1,#19,#24
Co-Authored-By: Claude <noreply@anthropic.com>

Author: 2 people

.github/workflows/release.yml

@@ -0,0 +1,103 @@
+name: Release
+
+# Produces the signed, verifiable IUUT.exe release.
+# Triggered when a human pushes a SemVer tag (vX.Y.Z). Agents propose release
+# readiness; humans tag (.agent/HANDOFF_PROTOCOL.md §9).
+#
+# Output (attached to the GitHub Release):
+#   - IUUT.exe              self-contained single-file, win-x64
+#   - IUUT-portable.zip     the same exe + IUUT.portable marker + README
+#   - SHA256SUMS.txt        SHA-256 of both artifacts
+#   - a Sigstore build-provenance attestation (verifiable with `gh attestation verify`)
+#
+# Authority: docs/IUUT-PROJECT-DOCUMENTATION.md §6.4, §19; docs/CICD.md §5.
+
+on:
+  push:
+    tags:
+      - "v[0-9]+.[0-9]+.[0-9]+"
+      - "v[0-9]+.[0-9]+.[0-9]+-*"   # pre-release tags (e.g. v0.1.0-rc1)
+
+permissions:
+  contents: write        # create the GitHub Release + upload assets
+  id-token: write        # required for Sigstore attestation
+  attestations: write    # required for actions/attest-build-provenance
+
+env:
+  DOTNET_CLI_TELEMETRY_OPTOUT: "1"
+  DOTNET_NOLOGO: "1"
+
+jobs:
+  release:
+    name: Build, attest, publish
+    runs-on: windows-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up .NET 8 SDK
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: "8.0.x"
+
+      - name: Restore + test (gate the release on green)
+        run: |
+          dotnet restore IcarusUltimateUtilityTool.sln
+          dotnet test IcarusUltimateUtilityTool.sln -c Release --logger "console;verbosity=minimal"
+
+      - name: Publish self-contained single-file IUUT.exe
+        run: >
+          dotnet publish src/IUUT.App/IUUT.App.csproj
+          -c Release -r win-x64
+          --self-contained true
+          -p:PublishSingleFile=true
+          -p:IncludeNativeLibrariesForSelfExtract=true
+          -p:EnableCompressionInSingleFile=true
+          -o publish
+
+      - name: Stage release artifacts
+        shell: pwsh
+        run: |
+          New-Item -ItemType Directory -Force -Path dist | Out-Null
+          Copy-Item publish/IUUT.exe dist/IUUT.exe
+
+          # Portable bundle: exe + portable marker + a short README
+          New-Item -ItemType Directory -Force -Path portable | Out-Null
+          Copy-Item publish/IUUT.exe portable/IUUT.exe
+          New-Item -ItemType File -Force -Path portable/IUUT.portable | Out-Null
+          @"
+          IUUT portable mode.
+          The presence of the 'IUUT.portable' file next to IUUT.exe makes IUUT keep
+          all of its state in a 'IUUT-Data' folder beside the exe instead of in
+          %AppData%\IUUT. See docs/INSTALL.md section 6.
+          "@ | Set-Content -Path portable/README.txt -Encoding utf8
+          Compress-Archive -Path portable/* -DestinationPath dist/IUUT-portable.zip -Force
+
+      - name: Generate SHA256SUMS.txt
+        shell: pwsh
+        run: |
+          Push-Location dist
+          Get-ChildItem -File -Exclude SHA256SUMS.txt | ForEach-Object {
+            $h = (Get-FileHash $_.Name -Algorithm SHA256).Hash.ToLower()
+            "$h  $($_.Name)"
+          } | Set-Content -Path SHA256SUMS.txt -Encoding ascii
+          Get-Content SHA256SUMS.txt
+          Pop-Location
+
+      - name: Attest build provenance
+        uses: actions/attest-build-provenance@v1
+        with:
+          subject-path: |
+            dist/IUUT.exe
+            dist/IUUT-portable.zip
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: |
+            dist/IUUT.exe
+            dist/IUUT-portable.zip
+            dist/SHA256SUMS.txt
+          generate_release_notes: true
+          fail_on_unmatched_files: true

CHANGELOG.md

@@ -27,6 +27,15 @@ in `docs/GOVERNANCE_CHANGELOG.md`.
 - **DevOps groundwork:** `docs/DEVELOPMENT.md` and `docs/CICD.md` runbooks, Build & Test
   CI workflow, Dependabot config, `CONTRIBUTING.md`, `SECURITY.md`, this changelog,
   `CODEOWNERS`, and issue templates.
+- **Operator-execution guarantees:** `docs/INSTALL.md` operator guide; `release.yml`
+  (single-file `IUUT.exe` + portable zip + `SHA256SUMS.txt` + Sigstore build-provenance
+  attestation on a `vX.Y.Z` tag); master doc §6.4 (two acquisition paths, no-installer /
+  no-admin / no-registry footprint, `%AppData%\IUUT\` default + `IUUT.portable` opt-in,
+  clean removal) and §19 release pipeline + user verification.
+
+### Fixed
+
+- Steam name-cache path inconsistency in master doc §7.5.1 (now `%AppData%\IUUT\`).
 
 ### Notes
 

README.md

@@ -21,6 +21,22 @@ Two equally-valid jobs, from one Windows desktop app:
 
 Three home-screen workflows: **Broken Save Recovery**, **Lazy Max**, and **Custom**.
 
+## Get IUUT
+
+Two ways to get the **same** single-file `IUUT.exe` — full guide in
+**[docs/INSTALL.md](docs/INSTALL.md)**:
+
+- **Download (recommended):** grab `IUUT.exe` + `SHA256SUMS.txt` from
+  [Releases](https://github.com/ImPanick/IUUT/releases), verify the hash and the
+  build-provenance attestation (`gh attestation verify`), then double-click.
+- **Build it yourself:** clone and run the `dotnet publish` command in
+  [docs/INSTALL.md §3](docs/INSTALL.md).
+
+**No install, no admin, no registry.** IUUT is one `.exe`; its only footprint is a
+single `%AppData%\IUUT\` folder (or a portable `IUUT-Data\` beside the exe). Removal =
+delete the exe + that folder. The save folder auto-links on launch; if it can't be
+found you point IUUT at it once.
+
 ## Quick facts
 
 | | |
@@ -95,6 +111,7 @@ pipeline and **[SECURITY.md](SECURITY.md)** for the disclosure policy.
 | --- | --- |
 | [docs/IUUT-PROJECT-DOCUMENTATION.md](docs/IUUT-PROJECT-DOCUMENTATION.md) | Master spec — vision, scope, save model, architecture, features, roadmap |
 | [Icarus-Analysis.md](Icarus-Analysis.md) | Save-format field guide (empirically verified) |
+| [docs/INSTALL.md](docs/INSTALL.md) | **Operator guide** — get, verify, run, footprint, portable, removal |
 | [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) | Local developer runbook |
 | [docs/CICD.md](docs/CICD.md) | CI/CD, branch protection, versioning, releases |
 | [AGENTS.md](AGENTS.md) + [.agent/](.agent/) | Multi-agent governance contract |

docs/CICD.md

@@ -19,9 +19,10 @@ Two GitHub Actions workflows gate every PR into `main`:
 | --- | --- | --- | --- |
 | **Governance Check** | `.github/workflows/governance-check.yml` | PR open/sync/edit | Validates PR-body contract sections, commit trailers, and runs `governance-lint.ps1` (PII + style). |
 | **Build & Test** | `.github/workflows/build.yml` | PR + push to main | Restore → build (warnings-as-errors) → test → `dotnet format --verify-no-changes`. |
+| **Release** | `.github/workflows/release.yml` | push of a `vX.Y.Z` tag | Build single-file `IUUT.exe` + portable zip → `SHA256SUMS.txt` → Sigstore build-provenance attestation → GitHub Release. |
 
-Both must be green to merge. Neither builds artifacts — release packaging is a
-separate, human-triggered process (§5).
+The first two gate every merge. Release runs only on a tag and produces the verifiable
+artifacts (§5).
 
 ```
    ┌──────────────┐     PR      ┌─────────────────────┐
@@ -127,20 +128,33 @@ Milestones map to master doc §16: `0.1` MVP (Lazy Max + backup + Main-Menu veri
 
 ### Release runbook
 
-1. Confirm `main` is green (both workflows).
+1. Confirm `main` is green (Governance Check + Build & Test).
 2. Open a `release-readiness` issue; an agent may assemble the checklist, a human signs off.
-3. Run the relevant items in `tests/MANUAL_CHECKLIST.md` (UI + game-load acceptance).
-4. Tag: `git tag vX.Y.Z && git push origin vX.Y.Z` (human only).
-5. `pwsh -File scripts/publish-release.ps1` produces the self-contained single-file
-   `IUUT.exe` (~15–25 MB) plus a portable zip. *(Script is a stub until first code release.)*
-6. Create the GitHub Release; attach `IUUT.exe` + portable zip; paste the generated
-   release notes (commit log since the previous tag, grouped by `<type>`).
+3. Run the relevant items in `tests/MANUAL_CHECKLIST.md` (UI + game-load + integrity/footprint).
+4. *(Optional)* Local dry-run: `pwsh -File scripts/publish-release.ps1` to inspect the
+   artifacts + checksums before tagging. *(Stub until first code release.)*
+5. **Tag (human only):** `git tag vX.Y.Z && git push origin vX.Y.Z`.
+6. **`release.yml` runs automatically** and produces, on the GitHub Release:
+   `IUUT.exe`, `IUUT-portable.zip`, `SHA256SUMS.txt`, generated release notes, and a
+   Sigstore build-provenance attestation.
 7. Update `CHANGELOG.md` (move `Unreleased` items under the new version heading).
 
-### Code signing (future)
+The artifacts are **verifiable by anyone** (no certificate needed): a checksum match
+plus `gh attestation verify IUUT.exe --repo ImPanick/IUUT` proves the binary is exactly
+what public CI built from the tagged commit. See master doc §19.2 and `docs/INSTALL.md` §4.
 
-Optional, reduces SmartScreen friction (master doc §19). When a cert is available,
-`publish-release.ps1` signs `IUUT.exe`. Not required for early releases.
+### Integrity model — "verified signed hashes"
+
+| Layer | Mechanism | Cost | Status |
+| --- | --- | --- | --- |
+| **Tamper detection** | `SHA256SUMS.txt` per release | free | active in `release.yml` |
+| **Provenance** | Sigstore attestation via `actions/attest-build-provenance` | free | active in `release.yml` |
+| **Reproducibility** | Acquisition Path B — build from source (master doc §6.4) | free | active |
+| **Publisher identity** | Authenticode code-signing of `IUUT.exe` | needs a code-signing cert | **future upgrade** |
+
+The first three ship now and fully satisfy "verified signed hashes from the repo."
+Authenticode (which removes most SmartScreen prompts) is added when a certificate is
+obtained — a `chore(ci)` change to `release.yml` plus a CI signing secret.
 
 ---
 

docs/DEVELOPMENT.md

@@ -73,13 +73,33 @@ when CI runs the equivalent trailer check. Don't skip it.
 | Test (filter) | `dotnet test --filter "FullyQualifiedName~ProfileParser"` |
 | Run the WPF app | `dotnet run --project src/IUUT.App` |
 | Run the CLI | `dotnet run --project src/IUUT.Cli -- check` |
+| Build your own release `IUUT.exe` | see below |
 | Format (apply) | `dotnet format IcarusUltimateUtilityTool.sln` |
 | Format (verify, CI-style) | `dotnet format IcarusUltimateUtilityTool.sln --verify-no-changes` |
 | Governance lint | `pwsh -File scripts/governance-lint.ps1 -StagedOnly` |
 
 The four gates CI enforces (mirror them locally before pushing): **build with no
 warnings**, **tests pass**, **format verifies clean**, **governance lint clean**.
 
+### Build your own self-contained `IUUT.exe`
+
+This is acquisition **Path B** for end users (master doc §6.4) and how you produce a
+local release artifact:
+
+```powershell
+dotnet publish src/IUUT.App/IUUT.App.csproj `
+  -c Release -r win-x64 `
+  --self-contained true `
+  -p:PublishSingleFile=true `
+  -p:IncludeNativeLibrariesForSelfExtract=true
+```
+
+Output: `src/IUUT.App/bin/Release/net8.0-windows/win-x64/publish/IUUT.exe` — a single
+~15–25 MB file with the .NET 8 runtime bundled; no install needed to run it. The
+canonical, attested release is built by `.github/workflows/release.yml` on a `vX.Y.Z`
+tag; `scripts/publish-release.ps1` is the local dry-run. See `docs/CICD.md` §5 and
+`docs/INSTALL.md`.
+
 ---
 
 ## 4. Project map

docs/INSTALL.md

@@ -0,0 +1,155 @@
+# Get & Run IUUT — Operator Guide
+
+How to obtain, verify, and run **Icarus Ultimate Utility Tool (IUUT)**. No
+programming required for the download path.
+
+> **The promise:** IUUT is a single `.exe`. You don't install anything, it doesn't
+> need administrator rights, it makes no system-wide changes, and removing it is
+> deleting one file and one folder. See the [footprint](#5-what-iuut-leaves-on-your-pc)
+> section for the exact list of what it touches.
+
+---
+
+## 1. Pick how you get it
+
+| You want… | Use |
+| --- | --- |
+| The easy way — just download and run | **Path A: pre-built download** (§2) |
+| To compile it yourself and trust nothing but your own build | **Path B: build from source** (§3) |
+
+Both give you the **identical** self-contained `IUUT.exe`.
+
+---
+
+## 2. Path A — download the pre-built `IUUT.exe` (recommended)
+
+1. Go to the repository's **Releases** page:
+   <https://github.com/ImPanick/IUUT/releases>
+2. From the latest release, download:
+   - **`IUUT.exe`** (or **`IUUT-portable.zip`** if you want portable mode — see §6), and
+   - **`SHA256SUMS.txt`**
+3. **Verify it** (strongly recommended — see §4). It takes ten seconds.
+4. **Double-click `IUUT.exe`.** That's it. No setup, no install, no admin prompt.
+
+> Windows SmartScreen may show "Windows protected your PC" the first time, because
+> IUUT is not yet Authenticode-signed (a paid certificate is a future upgrade). Click
+> **More info → Run anyway**. Verifying the file first (§4) is exactly how you confirm
+> it's safe despite that warning.
+
+---
+
+## 3. Path B — build your own `IUUT.exe` from source
+
+Requires the **.NET 8 SDK** (or newer — see `docs/DEVELOPMENT.md` §1). Then:
+
+```powershell
+git clone https://github.com/ImPanick/IUUT.git
+cd IUUT
+
+dotnet publish src/IUUT.App/IUUT.App.csproj `
+  -c Release -r win-x64 `
+  --self-contained true `
+  -p:PublishSingleFile=true `
+  -p:IncludeNativeLibrariesForSelfExtract=true
+```
+
+Your `IUUT.exe` is written to
+`src/IUUT.App/bin/Release/net8.0-windows/win-x64/publish/IUUT.exe`.
+Copy it anywhere and double-click. This is a binary **you** produced from source —
+no need to trust our release at all.
+
+---
+
+## 4. Verify the download ("verified signed hashes")
+
+Two independent checks. Do at least the first.
+
+### 4a. Checksum (no tools needed beyond PowerShell)
+
+```powershell
+(Get-FileHash .\IUUT.exe -Algorithm SHA256).Hash
+```
+
+Compare the printed hash against the `IUUT.exe` line in `SHA256SUMS.txt`. They must
+match exactly (case-insensitive). A mismatch means the file is corrupted or tampered —
+do not run it.
+
+### 4b. Build provenance (recommended; needs the free GitHub CLI)
+
+```powershell
+gh attestation verify .\IUUT.exe --repo ImPanick/IUUT
+```
+
+This cryptographically proves the `.exe` was built by IUUT's public CI from a specific
+tagged commit (Sigstore attestation) — not swapped out by someone else. A green result
+is the strongest assurance short of building it yourself.
+
+---
+
+## 5. What IUUT leaves on your PC
+
+IUUT is deliberately tidy. The complete footprint:
+
+| Item | Where | What it is |
+| --- | --- | --- |
+| The program | wherever you put `IUUT.exe` | The single executable. |
+| App state | `%AppData%\IUUT\` | Steam-name cache, your (encrypted) Steam Web API key if you set one, logs, and settings. The **only** folder IUUT creates. |
+| Save backups | inside your `…\Icarus\Saved\PlayerData\<SteamID>\` | Timestamped `.iuut-backup-…` copies made **before** every edit, next to the files they protect. Part of your save folder, not scattered. |
+
+IUUT does **not**: run an installer, require admin, write to the Windows registry,
+install into Program Files, create Start-Menu entries or shortcuts, run a background
+service, auto-start with Windows, or phone home.
+
+---
+
+## 6. Portable mode (true fire-and-forget)
+
+Want **nothing** in `%AppData%`? Run portable:
+
+- Use the `IUUT-portable.zip` release (it includes the marker), **or**
+- Create an empty file named **`IUUT.portable`** next to `IUUT.exe`.
+
+In portable mode, all app state goes in a **`IUUT-Data\`** folder beside the `.exe`.
+Put the exe + that folder on a USB stick and it travels with you, leaving the host PC
+completely untouched.
+
+---
+
+## 7. First run
+
+1. **Read & accept the one-time disclaimer** (IUUT is unofficial; back up your saves;
+   you're responsible for your edits).
+2. **Save folder auto-links.** IUUT looks for `%LOCALAPPDATA%\Icarus\Saved\`
+   automatically. If found, you go straight to the profile picker.
+3. **If it can't find your saves** (game installed somewhere unusual), IUUT asks you to
+   **Browse…** to your `Saved\` (or `PlayerData\`) folder once. It remembers your choice.
+4. **Pick your profile** by Steam display name and start with **Broken Save Recovery**,
+   **Lazy Max**, or **Custom**.
+
+---
+
+## 8. Remove IUUT completely
+
+There's nothing to uninstall:
+
+1. Delete `IUUT.exe`.
+2. Delete `%AppData%\IUUT\` (or, in portable mode, the `IUUT-Data\` folder next to the exe).
+
+Your Icarus saves and their backups are left untouched. (If you also want to discard
+the backups IUUT made, delete the `*.iuut-backup-*` files in your `PlayerData\<SteamID>\`
+folder — but you may want to keep them.)
+
+---
+
+## 9. Safety reminders
+
+- **Back up your save folder** before big edits (IUUT also auto-backs-up each file).
+- **Close Icarus, or stay on the Main Menu**, while editing (see the in-app banner).
+- If you use **Steam Cloud**, verify sync direction after editing so an older cloud
+  copy doesn't overwrite your edits.
+
+---
+
+*Operator runbook. The binding guarantees behind it live in
+`docs/IUUT-PROJECT-DOCUMENTATION.md` §6.4 and §19. Maintained per
+`.agent/AMENDMENT_PROCESS.md` §4. Last updated: 2026-05-25.*