docs: clarify doctor + launchd service guidance

docs/gateway/doctor.md

@@ -150,6 +150,11 @@ missing or outdated defaults (e.g., systemd network-online dependencies and
 restart delay). When it finds a mismatch, it recommends an update and can
 rewrite the service file/task to the current defaults.
 
+Notes:
+- `clawdbot doctor` prompts before rewriting supervisor config.
+- `clawdbot doctor --yes` accepts the default repair prompts.
+- You can always force a full rewrite via `clawdbot daemon install --force`.
+
 ### 12) Gateway runtime + port diagnostics
 Doctor inspects the daemon runtime (PID, last exit status) and warns when the
 service is installed but not actually running. It also checks for port collisions

docs/gateway/index.md

@@ -156,6 +156,8 @@ See also: [`docs/presence.md`](/concepts/presence) for how presence is produced/
   - StandardOut/Err: file paths or `syslog`
 - On failure, launchd restarts; fatal misconfig should keep exiting so the operator notices.
 - LaunchAgents are per-user and require a logged-in session; for headless setups use a custom LaunchDaemon (not shipped).
+  - `clawdbot daemon install` writes `~/Library/LaunchAgents/com.clawdbot.gateway.plist`.
+  - `clawdbot doctor` audits the LaunchAgent config and can update it to current defaults.
 
 ## Daemon management (CLI)
 

docs/gateway/troubleshooting.md

@@ -55,6 +55,10 @@ the Gateway likely refused to bind.
 - If they don’t, you’re almost certainly editing one config while the daemon is running another.
 - Fix: rerun `clawdbot daemon install --force` from the same `--profile` / `CLAWDBOT_STATE_DIR` you want the daemon to use.
 
+**If `clawdbot daemon status` reports service config issues**
+- The supervisor config (launchd/systemd/schtasks) is missing current defaults.
+- Fix: run `clawdbot doctor` to update it (or `clawdbot daemon install --force` for a full rewrite).
+
 **If `Last gateway error:` mentions “refusing to bind … without auth”**
 - You set `gateway.bind` to a non-loopback mode (`lan`/`tailnet`/`auto`) but left auth off.
 - Fix: set `gateway.auth.mode` + `gateway.auth.token` (or export `CLAWDBOT_GATEWAY_TOKEN`) and restart the daemon.

docs/platforms/linux.md

@@ -35,12 +35,6 @@ clawdbot daemon install
 
 Or:
 
-```
-clawdbot daemon install
-```
-
-Or:
-
 ```
 clawdbot configure
 ```

docs/platforms/mac/bun.md

@@ -63,6 +63,8 @@ Manager:
 Behavior:
 - “Clawdbot Active” enables/disables the LaunchAgent.
 - App quit does **not** stop the gateway (launchd keeps it alive).
+ - CLI install (`clawdbot daemon install`) writes the same LaunchAgent; `clawdbot daemon install --force` rewrites it.
+ - `clawdbot doctor` audits the LaunchAgent config and can update it to current defaults.
 
 Logging:
 - launchd stdout/err: `/tmp/clawdbot/clawdbot-gateway.log`

docs/platforms/windows.md

@@ -36,12 +36,6 @@ clawdbot daemon install
 
 Or:
 
-```
-clawdbot daemon install
-```
-
-Or:
-
 ```
 clawdbot configure
 ```