docs: reorganize documentation structure

docs/gateway/remote.md

@@ -0,0 +1,61 @@
+---
+summary: "Remote access using SSH tunnels (Gateway WS) and tailnets"
+read_when:
+  - Running or troubleshooting remote gateway setups
+---
+# Remote access (SSH, tunnels, and tailnets)
+
+This repo supports “remote over SSH” by keeping a single Gateway (the master) running on a host (e.g., your Mac Studio) and connecting clients to it.
+
+- For **operators (you / the macOS app)**: SSH tunneling is the universal fallback.
+- For **nodes (iOS/Android and future devices)**: prefer the Gateway **Bridge** when on the same LAN/tailnet (see [`docs/discovery.md`](/discovery)).
+
+## The core idea
+
+- The Gateway WebSocket binds to **loopback** on your configured port (defaults to 18789).
+- For remote use, you forward that loopback port over SSH (or use a tailnet/VPN and tunnel less).
+
+## SSH tunnel (CLI + tools)
+
+Create a local tunnel to the remote Gateway WS:
+
+```bash
+ssh -N -L 18789:127.0.0.1:18789 user@host
+```
+
+With the tunnel up:
+- `clawdbot health` and `clawdbot status --deep` now reach the remote gateway via `ws://127.0.0.1:18789`.
+- `clawdbot gateway {status,health,send,agent,call}` can also target the forwarded URL via `--url` when needed.
+
+Note: replace `18789` with your configured `gateway.port` (or `--port`/`CLAWDBOT_GATEWAY_PORT`).
+
+## CLI remote defaults
+
+You can persist a remote target so CLI commands use it by default:
+
+```json5
+{
+  gateway: {
+    mode: "remote",
+    remote: {
+      url: "ws://127.0.0.1:18789",
+      token: "your-token"
+    }
+  }
+}
+```
+
+When the gateway is loopback-only, keep the URL at `ws://127.0.0.1:18789` and open the SSH tunnel first.
+
+## Chat UI over SSH
+
+WebChat no longer uses a separate HTTP port. The SwiftUI chat UI connects directly to the Gateway WebSocket.
+
+- Forward `18789` over SSH (see above), then connect clients to `ws://127.0.0.1:18789`.
+- On macOS, prefer the app’s “Remote over SSH” mode, which manages the tunnel automatically.
+
+## macOS app “Remote over SSH”
+
+The macOS menu bar app can drive the same setup end-to-end (remote status checks, WebChat, and Voice Wake forwarding).
+
+Runbook: [`docs/mac/remote.md`](/mac/remote).