docs: add macvlan LAN-only warning for runners outside the network

Macvlan container IPs are only reachable on the LAN. Runners working
remotely (coffee shop, VPN) must use the public GITEA_DOMAIN instead
of the LAN IP in their .runner file. Added inline comments to
.env.example and troubleshooting entries to README.md and USAGE_GUIDE.md.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.env.example

@@ -34,14 +34,14 @@ UNRAID_MACVLAN_PARENT=            # Host network interface (e.g. br0, eth0)
 UNRAID_MACVLAN_SUBNET=            # LAN subnet in CIDR (e.g. 192.168.1.0/24)
 UNRAID_MACVLAN_GATEWAY=           # LAN gateway (e.g. 192.168.1.1)
 UNRAID_MACVLAN_IP_RANGE=          # IP range for containers (e.g. 192.168.1.192/28 — 16 IPs)
-UNRAID_GITEA_IP=                  # Static LAN IP for Gitea container
+UNRAID_GITEA_IP=                  # Static LAN IP for Gitea container (macvlan — only reachable on the LAN; runners outside the LAN must use GITEA_DOMAIN instead)
 UNRAID_CADDY_IP=                  # Static LAN IP for Caddy container
 
 FEDORA_MACVLAN_PARENT=            # Host network interface (e.g. eth0)
 FEDORA_MACVLAN_SUBNET=            # LAN subnet in CIDR (e.g. 192.168.1.0/24)
 FEDORA_MACVLAN_GATEWAY=           # LAN gateway (e.g. 192.168.1.1)
 FEDORA_MACVLAN_IP_RANGE=          # IP range for containers (e.g. 192.168.1.208/28 — 16 IPs)
-FEDORA_GITEA_IP=                  # Static LAN IP for Gitea container
+FEDORA_GITEA_IP=                  # Static LAN IP for Gitea container (macvlan — only reachable on the LAN)
 
 
 # -----------------------------------------------------------------------------

README.md

@@ -195,6 +195,12 @@ Phases run strictly sequentially. Phase 4 could potentially import repos in para
 - The total migration time is dominated by network transfers, not script execution
 - Sequential execution produces readable, linear logs
 
+### Macvlan IPs are LAN-only — runners outside the network must use the public domain
+
+Gitea containers run on macvlan IPs (e.g., `UNRAID_GITEA_IP=192.168.1.177`). These IPs are only reachable from machines on the same LAN. If a runner (e.g., a MacBook) is outside the local network (coffee shop, VPN, mobile hotspot), it cannot reach the macvlan IP and will fail to poll for jobs or report results.
+
+**Fix**: Edit the runner's `.runner` file and change the `address` field from the LAN IP (`http://192.168.1.177:3000`) to the public domain (`https://YOUR_DOMAIN`). The public domain routes through Caddy (Phase 8) and works from anywhere. Restart the runner after changing the address.
+
 ### Docker socket mounted in runner containers
 
 Runner containers get `/var/run/docker.sock` mounted, giving them root-equivalent access to the host's Docker daemon. This is required for runners to spawn job containers but is a security concern for untrusted code. For a private instance with trusted users, this is the standard Gitea runner deployment.

USAGE_GUIDE.md

@@ -364,6 +364,20 @@ This generates ed25519 keys on each host and distributes public keys to the othe
 
 **Fix**: Log out and back in to the Fedora machine (SSH session), then re-run the failed script. Adding a user to the `docker` group requires a new login session to take effect.
 
+### Runner cannot connect from outside the LAN
+
+**Symptom**: A runner (typically a MacBook) shows as offline or fails to connect when working outside the local network (e.g., coffee shop, VPN, mobile hotspot).
+
+**Cause**: Gitea containers use macvlan IPs (e.g., `192.168.1.177`) which are only reachable from machines on the same LAN. The runner's `.runner` file contains `"address": "http://192.168.1.177:3000"` which is unreachable from outside.
+
+**Fix**: Edit the runner's `.runner` file and change the `address` to the public domain:
+
+```json
+"address": "https://YOUR_DOMAIN"
+```
+
+Then restart the runner. The public domain routes through Caddy (Phase 8) and works from anywhere. No SSH tunnel needed.
+
 ### Runner shows as offline after deployment
 
 **Symptom**: Phase 3 post-check reports a runner as offline.