docs(lan): document ssh-lan.conf for naming LAN peers

The host-owned, bind-mounted ~/.config/devbox-shell/ssh-lan.conf is the
intended place to add `ProxyJump host` overrides for named LAN peers (so
`pi --ssh <peer>` / `dssh <peer>` route through the host), but it was only
documented in .env.example and the setup-lan-access.sh header — never in the
README, where someone hitting "can't reach LAN peers" actually looks.

- README: add a "Naming LAN peers" subsection under the macOS LAN-peers
  troubleshooting block, with a ProxyJump example and the read-only ~/.ssh
  caveat; add a pointer to it from the SSH and ControlMaster section.
- setup-lan-access.sh: correct the INCLUDE_BLOCK comment that suggested adding
  ProxyJump to the read-only ~/.ssh/config; point at ssh-lan.conf instead.
- CHANGELOG: note under Unreleased.

Docs/comment only — no behavior change.

CHANGELOG.md

@@ -13,6 +13,17 @@ Pre-v1.0.0 tags followed the pi npm version (`v{pi_version}[letter]`).
 
 ## Unreleased
 
+### Docs: document `~/.config/devbox-shell/ssh-lan.conf` for naming LAN peers
+
+The host-owned, bind-mounted `~/.config/devbox-shell/ssh-lan.conf` is the
+intended place to add `ProxyJump host` overrides for **named** LAN peers (so
+`pi --ssh <peer>` / `dssh <peer>` route through the host), but it was only
+mentioned in `.env.example` and the `setup-lan-access.sh` header — never in the
+README. Added a "Naming LAN peers" subsection to the README troubleshooting
+block (plus a pointer from the SSH/ControlMaster section), and corrected the
+stale `setup-lan-access.sh` comment that suggested editing the read-only
+`~/.ssh/config` instead of `ssh-lan.conf`.
+
 ## v1.1.6 — 2026-06-19
 
 Build provenance + reproducibility hardening, plus pi `0.79.7` → `0.79.8`

README.md

@@ -479,7 +479,11 @@ this without editing the read-only config:
   cannot fail on the read-only socket dir.
 - **`ssh -F ~/.ssh-local/config` / `dssh` / `dscp`** — `setup-lan-access.sh`
   redirects `ControlPath` into the writable `~/.ssh-local/cm` for every host
-  (the sidecar is rendered on all host OSes).
+  (the sidecar is rendered on all host OSes). To name LAN peers that should
+  jump via the host, add `ProxyJump host` overrides in the host-owned
+  `~/.config/devbox-shell/ssh-lan.conf` (see
+  [Naming LAN peers](#naming-lan-peers)) rather than the read-only
+  `~/.ssh/config`.
 
 ## tmux and 0-indexed sessions
 
@@ -615,6 +619,28 @@ auto-runs on container start and writes `~/.ssh-local/config` with a
 ssh-jump-via-host configuration. Set `DEVBOX_LAN_ACCESS=jump` and
 `HOST_SSH_USER=<your-mac-user>` in `.env` if auto-detection fails.
 
+#### Naming LAN peers
+
+`DEVBOX_LAN_ACCESS` / `HOST_SSH_USER` only set up the *jump* to the host. To
+make a **named** peer route through it — so `pi --ssh alpserv-2`,
+`dssh alpserv-2`, etc. resolve the ProxyJump — add a `ProxyJump host` override
+for it in the host-owned, bind-mounted `~/.config/devbox-shell/ssh-lan.conf`
+(**not** `~/.ssh/config`, which is mounted read-only):
+
+```
+Host pve pve-2 alpserv-2 lagret
+    ProxyJump host
+```
+
+`HostName` / `User` / `IdentityFile` are inherited from the matching block in
+your real `~/.ssh/config` (first-value-wins, so only `ProxyJump` is taken from
+here). This file is `Include`d *before* `~/.ssh/config` and read fresh on every
+connection — newly added peers work immediately, no container or session
+restart needed — and the peer names stay out of the published image (they're a
+fact about your specific LAN, not the image). Alternatively, set
+`DEVBOX_LAN_AUTOJUMP_PRIVATE=1` to ProxyJump *any* RFC1918 address through the
+host without naming peers (see `.env.example`).
+
 ### Smoke-testing a local build
 
 ```bash

rootfs/usr/local/lib/pi-devbox/setup-lan-access.sh

@@ -188,7 +188,9 @@ if [ -r "${HOME}/.ssh/config" ]; then
 
 # Your own target hosts. Scope reset to match-all so this Include applies to
 # every target (an Include is otherwise scoped to the enclosing Host block).
-# Add 'ProxyJump host' to LAN entries here (or in ssh-lan.conf above).
+# To make a LAN peer jump via the host, add 'ProxyJump host' to its entry in
+# the host-owned ~/.config/devbox-shell/ssh-lan.conf (Included above) — NOT
+# here in ~/.ssh/config, which is typically bind-mounted read-only.
 Host *
 Include ~/.ssh/config
 EOF