fix: add gateway stop/restart commands

docs/faq.md

@@ -492,6 +492,9 @@ The gateway runs under a supervisor that auto-restarts it. You need to stop the
 # Check if running
 launchctl list | grep clawdbot
 
+# Stop (disable does NOT stop a running job)
+clawdbot gateway stop
+
 # Stop and disable
 launchctl disable gui/$UID/com.clawdbot.gateway
 launchctl bootout gui/$UID/com.clawdbot.gateway
@@ -499,6 +502,9 @@ launchctl bootout gui/$UID/com.clawdbot.gateway
 # Re-enable later
 launchctl enable gui/$UID/com.clawdbot.gateway
 launchctl bootstrap gui/$UID ~/Library/LaunchAgents/com.clawdbot.gateway.plist
+
+# Or just restart
+clawdbot gateway restart
 ```
 
 **Linux (systemd)**
@@ -508,7 +514,11 @@ launchctl bootstrap gui/$UID ~/Library/LaunchAgents/com.clawdbot.gateway.plist
 systemctl list-units | grep -i clawdbot
 
 # Stop and disable
-sudo systemctl disable --now clawdbot
+clawdbot gateway stop
+systemctl --user disable --now clawdbot-gateway.service
+
+# Or just restart
+clawdbot gateway restart
 ```
 
 **pm2 (if used)**

docs/gateway.md

@@ -159,6 +159,8 @@ See also: `docs/presence.md` for how presence is produced/deduped and why `insta
 
 Bundled mac app:
 - Clawdbot.app can bundle a bun-compiled gateway binary and install a per-user LaunchAgent labeled `com.clawdbot.gateway`.
+- To stop it cleanly, use `clawdbot gateway stop` (or `launchctl bootout gui/$UID/com.clawdbot.gateway`).
+- To restart, use `clawdbot gateway restart` (or `launchctl kickstart -k gui/$UID/com.clawdbot.gateway`).
 
 ## Supervision (systemd user unit)
 Create `~/.config/systemd/user/clawdbot-gateway.service`:
@@ -217,6 +219,7 @@ sudo systemctl enable --now clawdbot-gateway.service
 - `clawdbot gateway send --to <num> --message "hi" [--media-url ...]` — send via Gateway (idempotent).
 - `clawdbot gateway agent --message "hi" [--to ...]` — run an agent turn (waits for final by default).
 - `clawdbot gateway call <method> --params '{"k":"v"}'` — raw method invoker for debugging.
+- `clawdbot gateway stop|restart` — stop/restart the supervised gateway service (launchd/systemd/schtasks).
 - Gateway helper subcommands assume a running gateway on `--url`; they no longer auto-spawn one.
 
 ## Migration guidance

docs/troubleshooting.md

@@ -160,6 +160,13 @@ lsof -nP -i :18789
 kill -9 <PID>
 ```
 
+If the gateway is supervised by launchd, killing the PID will just respawn it.
+Stop the supervisor instead:
+```bash
+clawdbot gateway stop
+# Or: launchctl bootout gui/$UID/com.clawdbot.gateway
+```
+
 **Fix 2: Check embedded gateway**
 Ensure the gateway relay was properly bundled. Run `./scripts/package-mac-app.sh` and ensure `bun` is installed.