diff --git a/deploy/README.md b/deploy/README.md
index fac67b5..84ccbe7 100644
--- a/deploy/README.md
+++ b/deploy/README.md
@@ -127,6 +127,25 @@ re-initdb the cluster, use `--encoding=UTF8 --locale=C.UTF-8`.
   mkdir -p /var/lib/void/icons
   chown void: /var/lib/void/icons
   ```
+
+## LAN device discovery (2.1.0)
+
+The hourly device scan (`lib/cron` → `runDeviceScanCycle`) shells `arp-scan`. The
+service runs as the non-root `void` user, so `arp-scan` needs a raw-socket
+capability:
+
+```bash
+apt-get install -y arp-scan
+setcap cap_net_raw,cap_net_admin+eip "$(readlink -f "$(command -v arp-scan)")"
+# verify as the service user (run from the service WorkingDirectory so the
+# OUI vendor files resolve):
+runuser -u void -- sh -c 'cd /opt/void-server && arp-scan --localnet --plain | head'
+```
+
+**⚠ Re-apply the `setcap` after any `arp-scan` package upgrade** — the upgrade
+replaces the binary and drops the capability, after which scans silently find
+nothing. `migration 024` creates `lan_devices` and seeds it from the old
+`devices.json`, so the band still renders even before the first scan runs.
 - **Service registry** — edit `config/services.json` to the real homelab service URLs and CT numbers. The committed seed values are best-guess placeholders and should be updated before the health band is meaningful.
 
 ## Deploy safety (push.sh, hardened)