From b067288494650a5aef749961632e376621ba8a9f Mon Sep 17 00:00:00 2001
From: Robert M1 <50460704+githubrobbi@users.noreply.github.com>
Date: Fri, 19 Jun 2026 17:18:07 -0700
Subject: [PATCH] docs: steer Windows/WinGet users to `uffs --update`, not
 `winget upgrade`
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Real-device testing showed `winget upgrade SkyLLC.UFFS` fails with
`remove_all: Access is denied` — the running daemon/broker hold the binaries
open, so WinGet can't replace in-use files. And the old note's claim that UFFS
"defers to WinGet for WinGet-managed installs" is inaccurate: the WinGet
binaries live in a per-user `…\WinGet\Links` path UFFS treats as an ordinary
unmanaged install, and `uffs --update` swaps them directly (it stops the
services first, then swaps).

Update both the README and the full update guide to recommend `uffs --update`
for WinGet installs, with the `winget upgrade` lock caveat (and the
stop-services-first workaround if someone insists on WinGet).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 README.md                    |  8 ++++++--
 docs/user-manual/updating.md | 11 ++++++++---
 2 files changed, 14 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 05802e71c..dcb1b08c8 100644
--- a/README.md
+++ b/README.md
@@ -183,8 +183,12 @@ uffs --update repair                    # diagnose + self-heal
 uffs --update apply --version v0.6.5    # pin / roll back to a specific release
 ```
 
-> **WinGet installs** update with `winget upgrade SkyLLC.UFFS` instead — UFFS
-> defers to WinGet for WinGet-managed installs.
+> **WinGet installs:** prefer `uffs --update` here too. `winget upgrade
+> SkyLLC.UFFS` can fail with `remove_all: Access is denied` — the running
+> daemon and broker hold open the very binaries WinGet tries to replace.
+> `uffs --update` stops those services first, then swaps, so it's the reliable
+> path. (If you do run `winget upgrade`, stop UFFS first — elevated
+> `uffs --daemon stop` + `uffs-broker --stop`.)
 
 > 📖 **[Full update guide](docs/user-manual/updating.md)** — every action, version pinning/rollback, the health check, and edge cases.
 
diff --git a/docs/user-manual/updating.md b/docs/user-manual/updating.md
index 4e6d82f97..de5f10d4e 100644
--- a/docs/user-manual/updating.md
+++ b/docs/user-manual/updating.md
@@ -11,9 +11,14 @@ inconsistent — it downloads, SHA-256-verifies, and atomically swaps every core
 binary in place (journaled, with automatic rollback on failure). If you're
 already current, it does nothing and touches no services.
 
-> **WinGet installs:** if you installed via `winget install SkyLLC.UFFS`, update
-> with `winget upgrade SkyLLC.UFFS` instead — UFFS detects a WinGet-managed
-> install and defers to WinGet rather than swapping those files itself.
+> **WinGet installs:** use `uffs --update` here too — it updates the WinGet
+> install in place (the binaries live in a per-user `…\WinGet\Links` location
+> UFFS treats as an ordinary unmanaged install). Prefer it over `winget upgrade
+> SkyLLC.UFFS`, which can fail with `remove_all: Access is denied` because the
+> running daemon and broker hold the binaries open while WinGet tries to replace
+> them. `uffs --update` stops those services first, then swaps. If you do want
+> `winget upgrade`, stop UFFS first: elevated `uffs --daemon stop` +
+> `uffs-broker --stop`.
 
 ---