diff --git a/docs/content/docs/guides/EXTERNAL-HOST-WALKTHROUGH.md b/docs/content/docs/guides/EXTERNAL-HOST-WALKTHROUGH.md
index 014231d..38a592b 100644
--- a/docs/content/docs/guides/EXTERNAL-HOST-WALKTHROUGH.md
+++ b/docs/content/docs/guides/EXTERNAL-HOST-WALKTHROUGH.md
@@ -170,14 +170,35 @@ curl -s http://192.0.2.1:8090/sources
 ### Via soundtouch-web
 
 The Radio Browser, TuneIn tabs, and preset saving live in
-**soundtouch-web**, a separate binary from the service. Run it on your
-host and open **`http://<host-ip>:8080`** in your browser (default port
-8080).
+**soundtouch-web**, a separate binary from the service. Once running,
+open **`http://<host-ip>:8080`** in your browser (default port 8080).
 
-> **Raspberry Pi note:** The Raspberry Pi installer (`install.sh`) only
-> installs `soundtouch-service`. Download `soundtouch-web` separately from
-> the [Releases page](https://github.com/gesellix/Bose-SoundTouch/releases)
-> and start it alongside the service.
+### Installing soundtouch-web on a Raspberry Pi
+
+`install.sh` only installs `soundtouch-service`. Use the dedicated
+`install-web.sh` script to add soundtouch-web:
+
+```bash
+curl -fsSL -o install-web.sh \
+  https://raw.githubusercontent.com/gesellix/Bose-SoundTouch/main/scripts/raspberry-pi/install-web.sh
+sudo bash install-web.sh
+```
+
+For configuration, service management, updates, and removal see the
+[Raspberry Pi guide → soundtouch-web](RASPBERRY-PI.md#soundtouch-web).
+
+### Installing soundtouch-web on other hosts
+
+Download the binary for your OS and architecture from the
+[Releases page](https://github.com/gesellix/Bose-SoundTouch/releases)
+and run it directly:
+
+```bash
+./soundtouch-web --port 8080
+```
+
+Or install it as a systemd service following the same unit-file pattern
+described in [DEPLOYMENT.md](DEPLOYMENT.md).
 
 soundtouch-web provides two ways to save what's currently playing to a
 preset slot:
diff --git a/docs/content/docs/guides/ON-DEVICE-INSTALL-WALKTHROUGH.md b/docs/content/docs/guides/ON-DEVICE-INSTALL-WALKTHROUGH.md
index 34a1864..74f2ab2 100644
--- a/docs/content/docs/guides/ON-DEVICE-INSTALL-WALKTHROUGH.md
+++ b/docs/content/docs/guides/ON-DEVICE-INSTALL-WALKTHROUGH.md
@@ -10,9 +10,6 @@ by [weissigera](https://github.com/weissigera) in
 [issue #329](https://github.com/gesellix/Bose-SoundTouch/issues/329#issuecomment-4521280831),
 documenting a successful fresh installation on a SoundTouch 20 Series I.
 
-For the installer reference and troubleshooting tips see
-[scripts/on-device-install/README.md](https://github.com/gesellix/Bose-SoundTouch/blob/main/scripts/on-device-install/README.md).
-
 ---
 
 ## Prerequisites
@@ -292,6 +289,72 @@ should start playing the corresponding stream.
 | `http://localhost:8000` not responding after install | `logread \| grep aftertouch \| tail -20`            |
 | No space left on device during install               | Run the cleanup in Step 2; check `df -h /mnt/nv`    |
 
-For more detail on any of these, see
-[TROUBLESHOOTING.md](./TROUBLESHOOTING.md) and the
-[on-device installer README](https://github.com/gesellix/Bose-SoundTouch/blob/main/scripts/on-device-install/README.md).
+For more detail see [TROUBLESHOOTING.md](TROUBLESHOOTING.md).
+
+---
+
+## Updating AfterTouch
+
+Re-run the installer with the version you want. The script backs up the
+running binary (named after its version), installs the new one, and prunes
+older artefacts to keep `/mnt/nv` free:
+
+```bash
+# Update to latest release
+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.99.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 | sh -s -- --version 0.99.0
+
+curl -sSLo install.sh https://raw.githubusercontent.com/gesellix/Bose-SoundTouch/main/scripts/on-device-install/install.sh
+sh install.sh --version 0.99.0
+```
+
+**Rollback:** the installer keeps a `.backup` file alongside the binary:
+
+```bash
+ls /mnt/nv/aftertouch/aftertouch-service*.backup
+cp /mnt/nv/aftertouch/aftertouch-service.<old-version>.backup \
+   /mnt/nv/aftertouch/aftertouch-service
+/etc/init.d/aftertouch restart
+```
+
+---
+
+## Service management
+
+```bash
+/etc/init.d/aftertouch start
+/etc/init.d/aftertouch stop
+/etc/init.d/aftertouch restart
+/etc/init.d/aftertouch status   # distinguishes "running + listener up" from "PID alive but listener down"
+```
+
+---
+
+## Logs
+
+The daemon writes to BusyBox syslog (tagged `aftertouch`). Disk usage stays
+bounded — the syslog ring buffer is in memory:
+
+```bash
+logread        | grep aftertouch | tail -20   # recent entries
+logread -f     | grep aftertouch              # live tail
+```
+
+If the service is running but port 8000 isn't responding, check the syslog
+tail first — panics and startup errors appear there.
+
+---
+
+## Uninstalling
+
+Before uninstalling, consider reverting the speaker migration from the
+AfterTouch Admin UI so the speaker URL is set back to the Bose cloud (though
+neither Bose nor AfterTouch will be reachable once both are removed).
+
+```bash
+curl -sSL https://raw.githubusercontent.com/gesellix/Bose-SoundTouch/main/scripts/on-device-install/uninstall.sh | sh
+```
diff --git a/docs/content/docs/guides/RASPBERRY-PI.md b/docs/content/docs/guides/RASPBERRY-PI.md
index 9f21941..53262e5 100644
--- a/docs/content/docs/guides/RASPBERRY-PI.md
+++ b/docs/content/docs/guides/RASPBERRY-PI.md
@@ -1,38 +1,43 @@
 ---
 title: "Raspberry Pi Installation Guide"
 ---
-This guide explains how to install the `soundtouch-service` as a persistent systemd service on a Raspberry Pi (tested on Raspberry Pi Zero 2W, 3, and 4).
+How to install and manage AfterTouch on a Raspberry Pi (or any always-on Linux
+host) using the provided installer scripts.
 
-For a complete walkthrough — from install through speaker migration and preset setup — see
+Two scripts are available, one per binary:
+
+| Script           | Binary               | Role                               | Default port |
+|------------------|----------------------|------------------------------------|--------------|
+| `install.sh`     | `soundtouch-service` | Cloud-replacement relay — always-on | 80 / 443     |
+| `install-web.sh` | `soundtouch-web`     | Browser control panel              | 8080         |
+
+Both auto-detect CPU architecture (armv7 / arm64 / amd64), create a `soundtouch`
+system user, and install a systemd unit. They are safe to re-run for updates.
+
+For a complete install-through-migration walkthrough see
 [EXTERNAL-HOST-WALKTHROUGH.md](EXTERNAL-HOST-WALKTHROUGH.md).
 Not sure whether to use a Pi or run AfterTouch on the speaker itself? See
 [DEPLOYMENT-OVERVIEW.md](DEPLOYMENT-OVERVIEW.md).
 
-## Automated Installer
+---
 
-We provide a specialized installer script located in the `scripts/raspberry-pi/` directory of the repository.
+## soundtouch-service
 
-### Features
-*   **Automatic start on boot**: Installs a systemd unit.
-*   **Non-root operation**: Uses `AmbientCapabilities` to bind to ports 80/443 without root privileges.
-*   **Arch Detection**: Automatically selects the correct binary for `armv7`, `arm64`, or `amd64`.
-*   **Easy Updates**: Re-running the script updates the binary to the latest version.
+### Installation
 
-### Installation Steps
+```bash
+curl -fsSL -o install.sh \
+  https://raw.githubusercontent.com/gesellix/Bose-SoundTouch/main/scripts/raspberry-pi/install.sh
+sudo bash install.sh
+```
 
-1.  **Download the installer**:
-    ```bash
-    curl -fsSL -o install.sh https://raw.githubusercontent.com/gesellix/bose-soundtouch/main/scripts/raspberry-pi/install.sh
-    ```
+Install a specific version:
 
-2.  **Run with sudo**:
-    ```bash
-    sudo bash install.sh
-    ```
+```bash
+sudo bash install.sh v0.99.0
+```
 
-### Overriding Defaults
-
-You can customize the installation using environment variables:
+Override defaults at install time:
 
 ```bash
 sudo \
@@ -43,33 +48,205 @@ sudo \
   bash install.sh
 ```
 
-### Updating the Service
+### Configuration
 
-To update the service to a specific version, run the installer with the version as an argument:
-
-```bash
-sudo bash install.sh v0.99.0
+```
+/etc/soundtouch-service/soundtouch-service.env
 ```
 
-The installer will automatically fetch the latest version of itself for that release and then update the service binary and restart it.
-
-## Management
-
-Once installed, use standard `systemctl` commands to manage the service:
+Example:
 
 ```bash
-# Check status
-systemctl status soundtouch-service
+PORT=80
+HTTPS_PORT=443
+DATA_DIR=/var/lib/soundtouch-service
 
-# Follow logs
-journalctl -u soundtouch-service -f
+LOG_PROXY_BODY=false
+REDACT_PROXY_LOGS=true
+RECORD_INTERACTIONS=true
+DISCOVERY_INTERVAL=5m
 
-# Restart
+SERVER_URL=http://soundtouch.local
+HTTPS_SERVER_URL=https://soundtouch.local
+```
+
+After editing the env file:
+
+```bash
 sudo systemctl restart soundtouch-service
 ```
 
-## Configuration
+### Service management
 
-Configuration is stored in `/etc/soundtouch-service/soundtouch-service.env`. Note that settings saved via the Web UI (in `settings.json`) will take precedence over these environment variables once the service is running.
+```bash
+systemctl status soundtouch-service
+sudo systemctl enable soundtouch-service   # start on boot
+sudo systemctl disable soundtouch-service
+sudo systemctl stop soundtouch-service
+sudo systemctl start soundtouch-service
+sudo systemctl restart soundtouch-service
+```
 
-For more details, see the [scripts/raspberry-pi/README.md](https://github.com/gesellix/Bose-SoundTouch/blob/main/scripts/raspberry-pi/README.md) in the repository.
+### Logs
+
+```bash
+journalctl -u soundtouch-service -e --no-pager   # recent
+journalctl -u soundtouch-service -f               # follow live
+journalctl -u soundtouch-service -b               # this boot only
+```
+
+### Updates
+
+```bash
+sudo bash install.sh              # update to latest release
+sudo bash install.sh v0.99.0     # update to a specific version
+```
+
+The script stops the service, downloads the new binary (backs up the old one to
+`.old`), and restarts automatically. Your env file and data directory are preserved.
+
+### Removal
+
+```bash
+sudo systemctl disable --now soundtouch-service
+sudo rm /etc/systemd/system/soundtouch-service.service
+sudo rm -rf /etc/soundtouch-service
+sudo rm -rf /var/lib/soundtouch-service
+sudo rm /usr/local/bin/soundtouch-service
+sudo systemctl daemon-reload
+```
+
+---
+
+## soundtouch-web
+
+`soundtouch-web` is a stateless browser control panel — it holds no persistent
+data and can be stopped or restarted at any time without data loss.
+
+### Installation
+
+```bash
+curl -fsSL -o install-web.sh \
+  https://raw.githubusercontent.com/gesellix/Bose-SoundTouch/main/scripts/raspberry-pi/install-web.sh
+sudo bash install-web.sh
+```
+
+Install a specific version:
+
+```bash
+sudo bash install-web.sh v0.99.0
+```
+
+Override defaults at install time:
+
+```bash
+sudo \
+  VERSION=v0.99.0 \
+  HTTP_PORT=8081 \
+  bash install-web.sh
+```
+
+Once running, open **`http://<pi-ip>:8080`** in a browser.
+
+### Configuration
+
+```
+/etc/soundtouch-web/soundtouch-web.env
+```
+
+Example:
+
+```bash
+PORT=8080
+BIND_ADDR=
+DISCOVERY_INTERFACE=
+SOUNDTOUCH_DEVICES=
+```
+
+`SOUNDTOUCH_DEVICES` accepts a comma-separated list of IP addresses for manual
+device registration — useful when mDNS auto-discovery is unreliable on your
+network:
+
+```bash
+SOUNDTOUCH_DEVICES=192.0.2.1,192.0.2.2
+```
+
+After editing the env file:
+
+```bash
+sudo systemctl restart soundtouch-web
+```
+
+### Port conflicts
+
+Port 8080 is a common default for other services. To check what is already
+using it:
+
+```bash
+sudo ss -tulpn | grep :8080
+```
+
+To use a different port, pass `HTTP_PORT=<port>` to the installer, or edit
+the env file after installation and restart the service.
+
+### Service management
+
+```bash
+systemctl status soundtouch-web
+sudo systemctl enable soundtouch-web    # start on boot
+sudo systemctl disable soundtouch-web
+sudo systemctl stop soundtouch-web
+sudo systemctl start soundtouch-web
+sudo systemctl restart soundtouch-web
+```
+
+### Logs
+
+```bash
+journalctl -u soundtouch-web -e --no-pager
+journalctl -u soundtouch-web -f
+```
+
+### Updates
+
+```bash
+sudo bash install-web.sh              # update to latest release
+sudo bash install-web.sh v0.99.0     # update to a specific version
+```
+
+### Removal
+
+```bash
+sudo systemctl disable --now soundtouch-web
+sudo rm /etc/systemd/system/soundtouch-web.service
+sudo rm -rf /etc/soundtouch-web
+sudo rm /usr/local/bin/soundtouch-web
+sudo systemctl daemon-reload
+```
+
+---
+
+## Architecture auto-detection
+
+Both installers detect the CPU and pick the matching release asset automatically:
+
+| `uname -m`          | asset suffix  |
+|---------------------|---------------|
+| `aarch64`           | `linux-arm64` |
+| `armv7l` / `armv6l` | `linux-armv7` |
+| `x86_64`            | `linux-amd64` |
+
+Override if needed:
+
+```bash
+sudo ARCH_ASSET=linux-arm64 bash install.sh
+sudo ARCH_ASSET=linux-arm64 bash install-web.sh
+```
+
+---
+
+## Security
+
+Both services run as the `soundtouch` system user (no login shell, no home
+directory). `soundtouch-service` additionally uses
+`AmbientCapabilities=CAP_NET_BIND_SERVICE` to bind ports 80 / 443 without root.
diff --git a/scripts/raspberry-pi/README.md b/scripts/raspberry-pi/README.md
index 9bcd706..08e8688 100644
--- a/scripts/raspberry-pi/README.md
+++ b/scripts/raspberry-pi/README.md
@@ -1,20 +1,16 @@
 # Raspberry Pi installers
 
-Two installer scripts are available, one for each binary:
+Full documentation — installation, configuration, service management, updates,
+and removal for both `soundtouch-service` and `soundtouch-web` — lives in the
+project docs:
 
-| Script           | Binary               | Role                                    | Default port |
-|------------------|----------------------|-----------------------------------------|--------------|
-| `install.sh`     | `soundtouch-service` | Cloud-replacement relay — must run 24/7 | 80 / 443     |
-| `install-web.sh` | `soundtouch-web`     | Browser control panel — run on demand   | 8080         |
-
-Both scripts auto-detect CPU architecture (armv7 / arm64 / amd64), create a systemd unit,
-and are safe to re-run for updates.
+**[docs/content/docs/guides/RASPBERRY-PI.md](../../docs/content/docs/guides/RASPBERRY-PI.md)**
 
 ---
 
-# soundtouch-service
+## Quick start
 
-## Installation
+**soundtouch-service** (cloud-replacement relay):
 
 ```bash
 curl -fsSL -o install.sh \
@@ -22,89 +18,7 @@ curl -fsSL -o install.sh \
 sudo bash install.sh
 ```
 
-Override defaults at install time:
-
-```bash
-sudo \
-  VERSION=v0.99.0 \
-  HOSTNAME_FQDN=soundtouch.local \
-  HTTP_PORT=80 \
-  HTTPS_PORT=443 \
-  bash install.sh
-```
-
-## Configuration
-
-```
-/etc/soundtouch-service/soundtouch-service.env
-```
-
-Example:
-
-```bash
-PORT=80
-HTTPS_PORT=443
-DATA_DIR=/var/lib/soundtouch-service
-
-LOG_PROXY_BODY=false
-REDACT_PROXY_LOGS=true
-RECORD_INTERACTIONS=true
-DISCOVERY_INTERVAL=5m
-
-SERVER_URL=http://soundtouch.local
-HTTPS_SERVER_URL=https://soundtouch.local
-```
-
-After editing the env file:
-
-```bash
-sudo systemctl restart soundtouch-service
-```
-
-## Service management
-
-```bash
-systemctl status soundtouch-service
-sudo systemctl enable soundtouch-service   # start on boot
-sudo systemctl disable soundtouch-service
-sudo systemctl stop soundtouch-service
-sudo systemctl start soundtouch-service
-sudo systemctl restart soundtouch-service
-```
-
-## Logs
-
-```bash
-journalctl -u soundtouch-service -e --no-pager   # recent
-journalctl -u soundtouch-service -f               # follow
-journalctl -u soundtouch-service -b               # this boot
-```
-
-## Updates
-
-```bash
-sudo bash install.sh vX.Y.Z
-```
-
-The script self-updates, downloads the new binary, backs up the old one to `.old`, and
-restarts the service. Your env file and data are preserved.
-
-## Removal
-
-```bash
-sudo systemctl disable --now soundtouch-service
-sudo rm /etc/systemd/system/soundtouch-service.service
-sudo rm -rf /etc/soundtouch-service
-sudo rm -rf /var/lib/soundtouch-service
-sudo rm /usr/local/bin/soundtouch-service
-sudo systemctl daemon-reload
-```
-
----
-
-# soundtouch-web
-
-## Installation
+**soundtouch-web** (browser control panel):
 
 ```bash
 curl -fsSL -o install-web.sh \
@@ -112,108 +26,9 @@ curl -fsSL -o install-web.sh \
 sudo bash install-web.sh
 ```
 
-Override defaults at install time:
+Pass a version tag as the first argument to pin a specific release:
 
 ```bash
-sudo \
-  VERSION=v0.99.0 \
-  HTTP_PORT=8081 \
-  bash install-web.sh
+sudo bash install.sh v0.99.0
+sudo bash install-web.sh v0.99.0
 ```
-
-`soundtouch-web` is **stateless** — it holds no persistent data and can be stopped or
-restarted at any time without data loss.
-
-## Configuration
-
-```
-/etc/soundtouch-web/soundtouch-web.env
-```
-
-Example:
-
-```bash
-PORT=8080
-BIND_ADDR=
-DISCOVERY_INTERFACE=
-SOUNDTOUCH_DEVICES=
-```
-
-`SOUNDTOUCH_DEVICES` accepts a comma-separated list of IP addresses for manual device
-registration (useful when mDNS auto-discovery is unreliable on your network).
-
-After editing the env file:
-
-```bash
-sudo systemctl restart soundtouch-web
-```
-
-## Port conflicts
-
-Port 8080 is a common default for other services. To use a different port, either pass
-`HTTP_PORT=<port>` to the installer, or edit the env file after installation:
-
-```bash
-sudo ss -tulpn | grep :8080   # check what's using the port
-```
-
-## Service management
-
-```bash
-systemctl status soundtouch-web
-sudo systemctl enable soundtouch-web    # start on boot
-sudo systemctl disable soundtouch-web
-sudo systemctl stop soundtouch-web
-sudo systemctl start soundtouch-web
-sudo systemctl restart soundtouch-web
-```
-
-## Logs
-
-```bash
-journalctl -u soundtouch-web -e --no-pager
-journalctl -u soundtouch-web -f
-```
-
-## Updates
-
-```bash
-sudo bash install-web.sh vX.Y.Z
-```
-
-## Removal
-
-```bash
-sudo systemctl disable --now soundtouch-web
-sudo rm /etc/systemd/system/soundtouch-web.service
-sudo rm -rf /etc/soundtouch-web
-sudo rm /usr/local/bin/soundtouch-web
-sudo systemctl daemon-reload
-```
-
----
-
-# Architecture auto-detection
-
-Both installers detect the CPU and pick the matching release asset automatically:
-
-| `uname -m`          | asset suffix  |
-|---------------------|---------------|
-| `aarch64`           | `linux-arm64` |
-| `armv7l` / `armv6l` | `linux-armv7` |
-| `x86_64`            | `linux-amd64` |
-
-Override if needed:
-
-```bash
-sudo ARCH_ASSET=linux-arm64 bash install.sh
-sudo ARCH_ASSET=linux-arm64 bash install-web.sh
-```
-
----
-
-# Security
-
-Both services run as the `soundtouch` system user (no login shell, no home directory
-ownership required for `soundtouch-web`). `soundtouch-service` additionally uses
-`AmbientCapabilities=CAP_NET_BIND_SERVICE` to bind ports 80/443 without root.