release: 0.0.38 with accurate Windows first-run documentation (#57)

Cuts 0.0.38 and corrects the public documentation for the Windows
first-run experience that 0.0.37 and 0.0.38 actually fixed.

A typical new Windows 11 PC has WSL and VirtualMachinePlatform
disabled. 1Helm enables both itself, which requires one Windows restart
partway through setup. The README, website manual, getting-started
guide, and user guide now state that plainly: WSL is not a
prerequisite, the single UAC prompt, the PowerShell progress window
that must stay open, the restart as a normal step rather than an error,
and resuming by reopening 1Helm as the same Windows user. SmartScreen
on the unsigned Setup executable is disclosed honestly.

Also adds the per-platform install and removal paths the repository
front page never documented, first-run troubleshooting for all three
platforms, and the two Settings sections (Notifications, Feedback) the
user guide omitted.

The website's disclosed Authenticode version is release-coupled, so
test/site.mjs now derives it from package.json instead of pinning a
literal that goes stale on every patch bump.

Release pins: version, changelog, and local/1helm-channel-machine:0.0.38.

Co-authored-by: Joseph Yaksich <gitcommit90@users.noreply.github.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: gitcommit90

CHANGELOG.md

@@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.0.38] - 2026-08-02
+
 ### Fixed
 
 - Windows first-run no longer reports "Shared runtime setup failed" when all
@@ -1036,6 +1038,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   Application Support, and isolated Apple container machines.
 
 [Unreleased]: https://github.com/gitcommit90/1Helm/compare/v0.0.36...HEAD
+[0.0.38]: https://github.com/gitcommit90/1Helm/compare/v0.0.30...v0.0.38
 [0.0.37]: https://github.com/gitcommit90/1Helm/compare/v0.0.30...v0.0.37
 [0.0.36]: https://github.com/gitcommit90/1Helm/compare/v0.0.35...v0.0.36
 [0.0.35]: https://github.com/gitcommit90/1Helm/compare/v0.0.34...v0.0.35

README.md

@@ -110,7 +110,10 @@ Skipper ─── crosses the boundary ─────────┘
 
 ## Install
 
-On Apple Silicon:
+Whichever platform, it works best on a dedicated machine: your crew works
+around the clock, and your everyday computer takes naps.
+
+### macOS (Apple Silicon)
 
 1. [Download the current signed DMG](https://1helm.com/download/macos).
 2. Open it and drag **1Helm** to Applications.
@@ -125,21 +128,70 @@ update preserves it — credentials, databases, resident state, files, and
 workspaces. Profile → Check for updates asks the Mac running 1Helm—not the
 device displaying the web UI—to download and verify the signed update.
 
-Windows 11 x64 gets a [Setup executable](https://1helm.com/download/windows)
-that provisions one installation-scoped WSL 2 runtime and one durable OCI
-container per ordinary channel. Linux hosts run the same channel containers
-natively under Podman. The verified installer provisions a durable systemd
-service with an atomic,
-digest-verified, health-checked updater — see the
-[Linux install guide](https://1helm.com/manual/install-linux). Whichever platform,
-it works best on a dedicated machine: your crew works around the clock, and
-your everyday computer takes naps.
+### Windows 11 x64
+
+1. [Download the current Setup executable](https://1helm.com/download/windows).
+2. Windows Setup is **not yet Authenticode signed**, so SmartScreen shows
+   "Windows protected your PC". Choose **More info** → **Run anyway**.
+3. Open 1Helm and complete Captain → Providers → Workspace.
+4. At the Workspace step, 1Helm builds its WSL 2 runtime. **You do not need WSL
+   installed beforehand.** A stock Windows 11 ships with WSL and
+   VirtualMachinePlatform turned off, and 1Helm enables both itself:
+   - Approve the one administrator (UAC) prompt.
+   - A PowerShell window opens and reports progress. **Leave it open** until it
+     finishes.
+   - Because those Windows features were just turned on, **Windows has to
+     restart once.** 1Helm says so in plain language. This is the normal path
+     on a new PC — it is not an error, and nothing is lost.
+   - Restart, sign back in as the **same** Windows user, then open 1Helm and
+     continue setup. It picks up where it left off; already-completed steps are
+     skipped.
+
+Setup downloads Microsoft's pinned WSL 2 package and a pinned Ubuntu 24.04 root
+filesystem, both SHA-256 verified, and the WSL package is additionally checked
+for a valid Microsoft Authenticode signature. The result is one
+installation-scoped WSL 2 runtime hosting one durable OCI container per ordinary
+channel, with Windows-drive mounts and process interop disabled. App state lives
+in `%APPDATA%\1Helm-OCI-v1`; the shared runtime disk lives in
+`%LOCALAPPDATA%\1Helm-Runtime`.
+
+### Linux (Ubuntu/Debian, systemd)
+
+Linux hosts run the same channel containers natively under Podman. The verified
+installer provisions a durable systemd service with an atomic, digest-verified,
+health-checked updater:
+
+```bash
+curl -fsSLo /tmp/1helm-install.sh https://1helm.com/install.sh
+less /tmp/1helm-install.sh
+sudo bash /tmp/1helm-install.sh
+```
+
+It requires root, systemd, apt, cgroup v2, and x86-64 or arm64 — see the
+[Linux install guide](https://1helm.com/manual/install-linux).
+
+### Removing 1Helm
+
+Use **Settings → Admin → Prepare to remove 1Helm** first on any platform. It is
+Captain-only, requires typed confirmation, and prepares backend-owned resident
+machines for safe deletion. Export irreplaceable channel files before you start.
+
+- **macOS** — drag 1Helm to the Trash. `~/Library/Application Support/1Helm-OCI-v1`
+  is preserved unless you delete it yourself.
+- **Windows** — uninstall from Settings → Apps → Installed apps. The uninstaller
+  removes 1Helm's own containers, unregisters its WSL runtime, and deletes
+  `%LOCALAPPDATA%\1Helm-Runtime`.
+- **Linux** — `sudo /opt/1helm/uninstall-host.sh` removes the services, helper,
+  and 1Helm-owned containers while preserving `/var/lib/1helm-oci-v1` for
+  recovery.
+
+### Release discipline
 
 Mac, Linux, and Windows use one synchronized desktop release version. A release
 is held in full until the signed/notarized Mac DMG and updater ZIP, verified
 Linux host archive, and Windows Setup/Squirrel feed have all passed native
 install and update acceptance from the same source commit. Windows
-Authenticode status is disclosed in every release; v0.0.31 is `NotSigned`.
+Authenticode status is disclosed in every release; v0.0.38 is `NotSigned`.
 
 ### Connect from a phone or tablet
 
@@ -152,10 +204,10 @@ frontend; the password is never retained and the resulting session is stored
 in the iOS Keychain or encrypted with a key held by Android Keystore.
 
 - The native iOS and Android gateway source is included in this repository,
-  but neither mobile platform has a current v0.0.31 public build. The most
+  but neither mobile platform has a current v0.0.38 public build. The most
   recent signed Android APK is the older v0.0.23 gateway, and 1Helm is not
   currently listed in the public iOS App Store. Use the HTTPS browser interface
-  for the current v0.0.31 experience.
+  for the current v0.0.38 experience.
 - The native clients require HTTPS, do not contain or initialize the 1Helm
   server or a frozen copy of its product frontend, and do not retain host data
   or provider credentials beyond the selected server address and secure
@@ -277,7 +329,7 @@ and an audit trail. A prompt saying “use this service” is not a connector.
   service with health-check rollback.
 - Signed, Apple-notarized, stapled Apple Silicon DMG releases.
 - Browser access from phones and tablets to an already configured HTTPS 1Helm
-  host; native mobile gateway source is present but has no v0.0.31 public build.
+  host; native mobile gateway source is present but has no v0.0.38 public build.
 
 ### Platform truth
 
@@ -286,7 +338,7 @@ and an audit trail. A prompt saying “use this service” is not a connector.
 | **Apple Silicon macOS 26** | Native desktop product and real isolated Linux computer per resident (Apple `container machine`, `home-mount=none`). |
 | **Linux / CI** | Supported headless systemd host with one durable Podman OCI container per resident, runtime-owned storage, and exact ownership checks; CI may select an explicit test backend. |
 | **Windows 11 x64** | Native desktop product with one installation-scoped WSL 2 OCI runtime and one durable container per resident; Windows-drive mounts and interop are disabled. |
-| **iPhone, iPad, and Android** | Use the current HTTPS browser interface. Native gateway source exists, but v0.0.31 has no public mobile artifact and the iOS app is not publicly listed. |
+| **iPhone, iPad, and Android** | Use the current HTTPS browser interface. Native gateway source exists, but v0.0.38 has no public mobile artifact and the iOS app is not publicly listed. |
 
 Not yet shipped: current public mobile builds, a native Linux desktop shell, a
 hosted control plane, rich Photon attachment fidelity, or blind execution of
@@ -313,7 +365,7 @@ A fresh data directory opens first-run setup. The source runtime defaults to
 | `PORT` | `8123` | HTTP/WebSocket control-plane port. |
 | `CTRL_DATA_DIR` | `./data` | Databases, routing state, uploads, and non-OCI development/Apple workspace mirrors. |
 | `HELM_CHANNEL_COMPUTER_BACKEND` | `apple` on macOS, `oci` on Linux and Windows | Host isolation backend; `native` and `mock` are explicit development/test overrides. |
-| `HELM_CHANNEL_MACHINE_IMAGE` | `local/1helm-channel-machine:0.0.37` | Versioned channel-machine image contract. |
+| `HELM_CHANNEL_MACHINE_IMAGE` | `local/1helm-channel-machine:0.0.38` | Versioned channel-machine image contract. |
 
 ### Agent-first JSON CLI
 

docs/GOVERNANCE.md

@@ -86,7 +86,10 @@ contract as the slice hardens.
   `/var/lib/1helm-oci-v1`.
 - Windows verification must prove the Setup/Squirrel signature status, clean
   install, old-to-new update, loopback health, WSL lifecycle, and retained
-  application data on Windows 11 x64. Do not substitute a self-signed
+  application data on Windows 11 x64. Clean install must be exercised on a host
+  where WSL and VirtualMachinePlatform start disabled, covering the elevation
+  prompt, the required Windows restart, and resumed setup after that restart.
+  Do not substitute a self-signed
   certificate or block an otherwise accepted release solely because the
   artifacts are honestly disclosed as unsigned.
 

docs/USER_GUIDE.md

@@ -204,13 +204,19 @@ not consume half of the visible screen.
 - **Workflows** — recurring resident work, next run, pause/resume, run counts,
   and failures.
 - **Connections** — native host-brokered Gmail and Photon configuration.
+- **Notifications** — per-account global mute and mobile notification opt-in.
+- **Feedback** — send a comment and optional attachments to the 1Helm team,
+  with privacy-bounded diagnostics included only if you check that option.
 - **Audit** — retained events and hash-chain verification.
 - **Domains** — local-first collaboration and optional Cloudflare domain.
 - **Providers** — accounts, keys, models, routes, quotas, logs, and endpoint.
 - **Skipper computers** — optional Captain-owned computers for authorized
   Skipper work; these never replace resident Linux computers.
 - **Members** — coworkers, access requests, and invitations.
 
+Those sections are the Captain/admin view. A signed-in member who is not an
+administrator sees only **Providers** and **Notifications**.
+
 ## Providers, models, and routes
 
 Accounts and keys form one fabric. Connect multiple ChatGPT, Claude,
@@ -377,14 +383,17 @@ Source/developer deployments report that their host operator owns updates.
 Every host update preserves:
 
 ```text
-~/Library/Application Support/1Helm-OCI-v1
+macOS:    ~/Library/Application Support/1Helm-OCI-v1
+Linux:    /var/lib/1helm-oci-v1
+Windows:  %APPDATA%\1Helm-OCI-v1  (plus %LOCALAPPDATA%\1Helm-Runtime)
 ```
 
 On macOS that directory contains databases, credentials, workspaces, resident
-state, and Apple mirrors. Linux preserves the equivalent OCI-generation state
-under `/var/lib/1helm-oci-v1`. The retired data roots remain untouched and are
-not imported by this generation. Do not delete either current data root during
-replacement.
+state, and Apple mirrors. Linux and Windows preserve the equivalent
+OCI-generation state; on Windows the shared WSL runtime disk lives separately
+under `%LOCALAPPDATA%\1Helm-Runtime`. The retired data roots remain untouched
+and are not imported by this generation. Do not delete a current data root
+during replacement.
 
 Before removing 1Helm, use its removal preparation flow. It is Captain-only,
 requires typed confirmation, reports backend-owned resident machines, and
@@ -403,6 +412,47 @@ Recovery principles:
 
 ## Troubleshooting
 
+### First run and installation
+
+**Windows asks me to restart in the middle of setup.** That is the expected
+path on a normal Windows 11 PC. WSL and VirtualMachinePlatform ship disabled;
+1Helm turns them on for you, and Windows cannot use them until it restarts.
+Restart, sign back in as the same Windows user, open 1Helm, and continue —
+completed steps are skipped. Nothing is lost and nothing else is required.
+
+**Windows says "Windows protected your PC" when I run Setup.** Windows Setup is
+not yet Authenticode signed, so SmartScreen warns about it. Choose **More info**
+→ **Run anyway**. Every release discloses its Authenticode status; v0.0.38 is
+`NotSigned`. Only run an installer you downloaded from
+[1helm.com](https://1helm.com/download/windows) or the project's GitHub
+releases.
+
+**A PowerShell window opened during Windows setup.** That window is the setup
+itself and shows live progress. Leave it open until it finishes; closing it
+early aborts the step. 1Helm mirrors the same progress in the app and writes a
+log to `%APPDATA%\1Helm-OCI-v1\windows-wsl-setup.log`.
+
+**Windows setup failed or stalled.** Check the PowerShell window for the error,
+then use **Retry shared runtime setup** in onboarding or Settings → Channel
+computers. Setup is idempotent — retrying resumes rather than starting over.
+The runtime requires Windows 11 **x64**; arm64 Windows is not supported by this
+build.
+
+**macOS blocks the app or reports it is damaged.** The Mac release is Developer
+ID signed, notarized, and stapled, so Gatekeeper should accept it after you
+drag it to Applications. If it does not, you are almost certainly running a
+partially downloaded or re-hosted copy — download the DMG again from
+[1helm.com](https://1helm.com/download/macos). Do not strip quarantine
+attributes or re-sign an ad-hoc build to work around a failed verification.
+
+**The Linux installer refuses to run.** It requires root, a running systemd
+host, `apt`, cgroup v2, and an x86-64 or arm64 CPU, and it installs Podman
+rather than Docker. The error names the missing prerequisite. Follow the
+[Linux install guide](https://1helm.com/manual/install-linux); check progress
+with `sudo systemctl status 1helm` and `sudo journalctl -u 1helm -f`.
+
+### In the app
+
 **A button highlights but Continue does nothing.** Ensure every visible question
 has one selected option or typed answer. If it still fails, capture the thread
 and app version; selection and the submitted answer should survive live repaints.
@@ -445,7 +495,7 @@ fallback.
 - Operational history is locally tamper-evident.
 - Mac artifacts are Developer ID signed, notarized, stapled, and Gatekeeper
   verified. Linux assets are digest-verified, and Windows Authenticode status
-  is disclosed for every release (`NotSigned` for v0.0.31).
+  is disclosed for every release (`NotSigned` for v0.0.38).
 
 For the detailed boundary, see [SECURITY.md](../SECURITY.md). For product intent,
 see [VISION.md](VISION.md).

docs/VISION.md

@@ -87,7 +87,7 @@ verification.
   synchronized public desktop-host product. Every named desktop release must
   publish all three from one version and exact source commit.
 - 1Helm is self-hosted and open source. Native mobile gateway source is present,
-  but v0.0.31 has no public Android/iOS build and 1Helm is not listed in the
+  but v0.0.38 has no public Android/iOS build and 1Helm is not listed in the
   public iOS App Store. A hosted control plane, blind community-skill execution,
   and a native Linux desktop shell are not shipped.
 

package-lock.json

@@ -1,7 +1,7 @@
 {
   "name": "1helm",
   "productName": "1Helm",
-  "version": "0.0.37",
+  "version": "0.0.38",
   "private": true,
   "type": "module",
   "license": "AGPL-3.0-only",