docs: improve windows preview release guide

vavo · vavo · commit 07f25798d1a9 · 2026-04-07T00:42:15.000+02:00
diff --git a/docs/deployment/windows-preview-release-template.md b/docs/deployment/windows-preview-release-template.md
@@ -43,10 +43,10 @@ This is a Windows preview build of LoRA Pilot delivered through a WSL-backed ins
 ### Install Notes
 
 - Run `LoRAPilotSetup.exe` as Administrator.
-- Tagged releases are intended to work as a single-download web installer: users run `LoRAPilotSetup.exe` and the runtime bundles are fetched automatically.
-- If Windows asks for a reboot during WSL setup, reboot and sign back in. Setup should resume automatically.
-- The installer downloads runtime bundles from the public URLs referenced by `windows-runtime-manifest.json`, not from GitHub release attachments.
-- If you downloaded both `windows-installer` and `windows-runtime-artifacts` preview artifacts instead of using a tagged release, run `Install-LoRAPilotPreview.ps1` from an elevated PowerShell after installing.
+- This tagged preview is intended to work as a single-download web installer. The runtime bundles are fetched automatically from the public URLs embedded in `windows-runtime-manifest.json`.
+- If WSL setup requires a reboot, reboot and sign back in. If setup does not resume automatically, run the installer again as Administrator.
+- The bundled `PREVIEW-INSTALL.md` file contains the real install flow, troubleshooting steps, and launcher commands. Users should read that first instead of improvising.
+- CI artifact smoke builds are a different path. If someone is testing raw workflow artifacts instead of the tagged release, `Install-LoRAPilotPreview.ps1` is the fallback helper.
 
 ### Known Limitations
 
@@ -70,6 +70,7 @@ This is a Windows preview build of LoRA Pilot delivered through a WSL-backed ins
 - WSL setup / reboot edge cases
 - Port conflicts
 - SmartScreen / Defender behavior
+- R2 / CDN download behavior on real Windows machines
 - General launcher reliability
 ```
 
diff --git a/packaging/windows/PREVIEW-INSTALL.md b/packaging/windows/PREVIEW-INSTALL.md
@@ -1,23 +1,162 @@
-# Windows Preview Installer
+# LoRA Pilot Windows Preview
 
-This preview build ships the installer and launcher, but the runtime payload still lives in the separate `windows-runtime-artifacts` download because GitHub Actions prefers absurdity over convenience.
+This is a preview Windows release of LoRA Pilot delivered through a WSL2-backed installer.
 
-## Preview install flow
+It is meant to be testable, not invisible. Expect a few rough edges, especially around first-time WSL setup, SmartScreen, and GPU-specific behavior. The basic install/start path works. That is already more than many preview installers can say with a straight face.
 
-1. Download and extract both artifacts into the same folder:
-   - `windows-installer`
-   - `windows-runtime-artifacts`
-2. Run `LoRAPilotSetup.exe` as Administrator.
-3. Open an elevated PowerShell in that folder and run:
+## What This Release Includes
+
+- `LoRAPilotSetup.exe`
+- `windows-runtime-manifest.json`
+- runtime checksum files
+- public runtime bundles hosted on Cloudflare R2 and downloaded during setup
+
+You do not need to manually download the large runtime bundles when using a tagged preview release. The installer fetches them for you.
+
+## Requirements
+
+- Windows 11 or Windows 10 22H2+
+- Administrator rights
+- WSL2 support enabled or installable on the machine
+- roughly 100 GB free disk space if you want enough room for the runtime, models, and workspace data
+- a decent internet connection, because the runtime bundle is not small and pretending otherwise would be unserious
+- NVIDIA Windows drivers with WSL GPU support if you want GPU acceleration
+
+## Quick Start
+
+1. Download `LoRAPilotSetup.exe` from the GitHub pre-release.
+2. Run it as Administrator.
+3. Let the installer:
+   - check Windows support
+   - enable or reuse WSL
+   - download the runtime manifest and runtime bundle
+   - import the managed `LoRAPilot` WSL distro
+   - create Start Menu shortcuts
+4. If Windows requires a reboot for WSL setup, reboot and sign in again.
+5. Start `LoRA Pilot` from the Start Menu.
+
+ControlPilot should open on `http://127.0.0.1:7878` once the runtime becomes healthy.
+
+## What Gets Installed
+
+- Windows launcher:
+  `%LOCALAPPDATA%\Programs\LoRAPilot\LoRAPilotLauncher.exe`
+- State, logs, downloads, and managed WSL files:
+  `%LOCALAPPDATA%\LoRAPilot`
+- Managed WSL distro name:
+  `LoRAPilot`
+- Distro storage location:
+  `%LOCALAPPDATA%\LoRAPilot\wsl\LoRAPilot`
+
+Persistent app data remains inside the distro under `/workspace`.
+
+## Start Menu Entries
+
+- `LoRA Pilot`: starts the runtime and opens ControlPilot
+- `Open ControlPilot`: opens the browser if ControlPilot is already running
+- `Stop LoRA Pilot`: stops the managed runtime
+- `Uninstall LoRA Pilot`: removes the Windows launcher and optionally the managed distro
+
+## Useful Commands
+
+Open an elevated PowerShell and use:
+
+```powershell
+$exe = "$env:LOCALAPPDATA\Programs\LoRAPilot\LoRAPilotLauncher.exe"
+
+& $exe status --json
+& $exe start
+& $exe stop
+& $exe open
+```
+
+That is much more informative than angrily clicking the same shortcut five times and expecting Windows to develop empathy.
+
+## Troubleshooting
+
+### Installer says WSL needs a reboot
+
+- Reboot Windows.
+- Sign back in.
+- If setup does not resume automatically, run the installer again as Administrator.
+
+### Installer fails during the WSL import step
+
+Clean stale state and retry:
+
+```powershell
+wsl --unregister LoRAPilot
+Remove-Item -Recurse -Force "$env:LOCALAPPDATA\LoRAPilot\wsl\LoRAPilot" -ErrorAction SilentlyContinue
+Remove-Item -Force "$env:LOCALAPPDATA\LoRAPilot\state.json" -ErrorAction SilentlyContinue
+```
+
+Then rerun `LoRAPilotSetup.exe`.
+
+### ControlPilot does not open
+
+Check launcher status:
 
 ```powershell
-.\Install-LoRAPilotPreview.ps1
+$exe = "$env:LOCALAPPDATA\Programs\LoRAPilot\LoRAPilotLauncher.exe"
+& $exe status --json
 ```
 
-4. If WSL setup required a reboot, rerun:
+Check launcher logs:
+
+- `%LOCALAPPDATA%\LoRAPilot\logs\launcher.log`
+
+### Windows warns that the installer is suspicious
+
+That is still possible on preview builds, especially before signing and reputation are fully in place. If Windows blocks execution, use the usual SmartScreen “More info” path only if you trust the source of the release.
+
+### Port conflicts
+
+LoRA Pilot expects these localhost ports:
+
+- `7878`
+- `8888`
+- `8443`
+- `5555`
+- `6666`
+- `4444`
+- `9090`
+- `8675`
+- `7879`
+
+If `7878` is taken, for example:
 
 ```powershell
-.\Install-LoRAPilotPreview.ps1 -Resume
+netstat -ano | findstr :7878
 ```
 
-The helper patches `windows-runtime-manifest.json` to local file paths, writes a BOM-free `windows-runtime-manifest.local.json`, and calls `LoRAPilotLauncher.exe install --manifest-url ...` for you.
+Stop the conflicting process, then start LoRA Pilot again.
+
+### GPU is missing inside WSL
+
+Run:
+
+```powershell
+nvidia-smi
+wsl --status
+wsl --update
+```
+
+If the Windows NVIDIA driver is wrong, LoRA Pilot cannot compensate with optimism.
+
+## Current Limitations
+
+- Preview quality, not GA
+- No offline single-file installer
+- Windows GPU validation is still thinner than it should be
+- Some install/retry edge cases are still being tightened
+
+## If You Are Testing CI Artifacts Instead of a Tagged Preview Release
+
+That is a separate, more annoying path.
+
+Use:
+
+- `LoRAPilotSetup.exe`
+- `Install-LoRAPilotPreview.ps1`
+
+The helper script exists for artifact-based smoke tests where the runtime is not published like a normal release yet. If you are using a tagged GitHub pre-release, you should not need it.
