diff --git a/docs/content/docs/guides/ON-DEVICE-INSTALL-WALKTHROUGH.md b/docs/content/docs/guides/ON-DEVICE-INSTALL-WALKTHROUGH.md
index b0ce938..0a94017 100644
--- a/docs/content/docs/guides/ON-DEVICE-INSTALL-WALKTHROUGH.md
+++ b/docs/content/docs/guides/ON-DEVICE-INSTALL-WALKTHROUGH.md
@@ -104,8 +104,11 @@ By default this installs the **latest release** — the script resolves it from
 GitHub's `releases/latest` redirect. To target a specific version instead:
 
 ```bash
-# Via environment variable (works with pipe-to-sh)
-VERSION=0.123.0 rw && curl -sSL https://raw.githubusercontent.com/gesellix/Bose-SoundTouch/main/scripts/on-device-install/install.sh | sh
+# Via environment variable — note it goes on `sh`, not `curl`: shell
+# variable-assignment prefixes only apply to the one command they're
+# attached to, and in a pipe each command is a separate process.
+# `VERSION=0.123.0 curl ... | sh` silently does NOT set it for `sh`.
+rw && curl -sSL https://raw.githubusercontent.com/gesellix/Bose-SoundTouch/main/scripts/on-device-install/install.sh | VERSION=0.123.0 sh
 
 # Via command-line flag (pass args after sh -s --)
 curl -sSL https://raw.githubusercontent.com/gesellix/Bose-SoundTouch/main/scripts/on-device-install/install.sh | sh -s -- --version 0.123.0
@@ -372,7 +375,7 @@ older artefacts to keep `/mnt/nv` free:
 rw && curl -sSL https://raw.githubusercontent.com/gesellix/Bose-SoundTouch/main/scripts/on-device-install/install.sh | sh
 
 # Update to a specific version — three equivalent forms
-VERSION=0.123.0 rw && curl -sSL https://raw.githubusercontent.com/gesellix/Bose-SoundTouch/main/scripts/on-device-install/install.sh | sh
+rw && curl -sSL https://raw.githubusercontent.com/gesellix/Bose-SoundTouch/main/scripts/on-device-install/install.sh | VERSION=0.123.0 sh
 
 rw && curl -sSL https://raw.githubusercontent.com/gesellix/Bose-SoundTouch/main/scripts/on-device-install/install.sh | sh -s -- --version 0.123.0
 
diff --git a/scripts/on-device-install/README.md b/scripts/on-device-install/README.md
index 3fc5c4a..f633f28 100644
--- a/scripts/on-device-install/README.md
+++ b/scripts/on-device-install/README.md
@@ -94,8 +94,10 @@ Run the installer again with the version you want to install. The script backs u
 **Install (or upgrade to) a specific version** — three equivalent ways:
 
 ```bash
-# 1. Environment variable (works when piping into sh)
-VERSION=0.123.0 rw && curl -sSL https://raw.githubusercontent.com/gesellix/Bose-SoundTouch/main/scripts/on-device-install/install.sh | sh
+# 1. Environment variable — goes on `sh`, not `curl`: in a pipe, each
+#    command is a separate process, so `VERSION=X curl ... | sh` silently
+#    does NOT set it for `sh` (the one that actually reads $VERSION).
+rw && curl -sSL https://raw.githubusercontent.com/gesellix/Bose-SoundTouch/main/scripts/on-device-install/install.sh | VERSION=0.123.0 sh
 
 # 2. Command-line flag (pass args after `sh -s --`)
 rw && curl -sSL https://raw.githubusercontent.com/gesellix/Bose-SoundTouch/main/scripts/on-device-install/install.sh | sh -s -- --version 0.123.0
diff --git a/scripts/on-device-install/install.sh b/scripts/on-device-install/install.sh
index 0c9fd97..1fad690 100644
--- a/scripts/on-device-install/install.sh
+++ b/scripts/on-device-install/install.sh
@@ -5,8 +5,10 @@ set -eo pipefail
 #   curl -sSL .../install.sh | sh
 # resolves and installs the latest release automatically (see below).
 #
-# Pin a specific version via environment variable or the --version/-v flag:
-#   VERSION=0.123.0 curl -sSL .../install.sh | sh
+# Pin a specific version via environment variable or the --version/-v flag.
+# The env var goes on `sh`, not `curl`: in a pipe, each command is its own
+# process, so `VERSION=X curl ... | sh` silently does NOT set it for `sh`.
+#   curl -sSL .../install.sh | VERSION=0.123.0 sh
 #   curl -sSL .../install.sh | sh -s -- --version 0.123.0
 VERSION=${VERSION:-}