fix: enable systemd lingering for gateway

docs/doctor.md

@@ -15,6 +15,7 @@ read_when:
 - Migrates legacy `~/.clawdis/clawdis.json` when no Clawdbot config exists.
 - Checks sandbox Docker images when sandboxing is enabled (offers to build or switch to legacy names).
 - Detects legacy Clawdis services (launchd/systemd/schtasks) and offers to migrate them.
+- On Linux, checks if systemd user lingering is enabled and can enable it (required to keep the Gateway alive after logout).
 
 ## Legacy config file migration
 If `~/.clawdis/clawdis.json` exists and `~/.clawdbot/clawdbot.json` does not, doctor will migrate the file and normalize old paths/image names.

docs/faq.md

@@ -466,6 +466,21 @@ cd ~/path/to/clawdbot
 codex --full-auto "debug why clawdbot gateway won't start"
 ```
 
+### Gateway stops after I log out (Linux)
+
+Linux installs use a systemd **user** service. By default, systemd stops user
+services on logout/idle, which kills the Gateway.
+
+Fix:
+```bash
+sudo loginctl enable-linger $USER
+```
+
+**macOS/Windows**
+
+Gateway daemons run in the user session by default. Keep the user logged in.
+Headless/system services are not configured out of the box.
+
 ### Processes keep restarting after I kill them
 
 The gateway runs under a supervisor that auto-restarts it. You need to stop the supervisor, not just kill the process.

docs/gateway.md

@@ -155,11 +155,13 @@ See also: `docs/presence.md` for how presence is produced/deduped and why `insta
   - KeepAlive: true
   - 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).
 
 Bundled mac app:
 - Clawdbot.app can bundle a bun-compiled gateway binary and install a per-user LaunchAgent labeled `com.clawdbot.gateway`.
 
-## Supervision (systemd example)
+## Supervision (systemd user unit)
+Create `~/.config/systemd/user/clawdbot-gateway.service`:
 ```
 [Unit]
 Description=Clawdbot Gateway
@@ -168,16 +170,27 @@ Wants=network-online.target
 
 [Service]
 ExecStart=/usr/local/bin/clawdbot gateway --port 18789
-Restart=on-failure
+Restart=always
 RestartSec=5
-User=clawdbot
 Environment=CLAWDBOT_GATEWAY_TOKEN=
-WorkingDirectory=/home/clawdbot
+WorkingDirectory=/home/youruser
 
 [Install]
-WantedBy=multi-user.target
+WantedBy=default.target
 ```
-Enable with `systemctl enable --now clawdbot-gateway.service`.
+Enable lingering (required so the user service survives logout/idle):
+```
+sudo loginctl enable-linger youruser
+```
+Requires sudo (writes `/var/lib/systemd/linger`).
+Then enable the service:
+```
+systemctl --user enable --now clawdbot-gateway.service
+```
+
+## Supervision (Windows scheduled task)
+- Onboarding installs a Scheduled Task named `Clawdbot Gateway` (runs on user logon).
+- Requires a logged-in user session; for headless setups use a system service or a task configured to run without a logged-in user (not shipped).
 
 ## Operational checks
 - Liveness: open WS and send `req:connect` → expect `res` with `payload.type="hello-ok"` (with snapshot).

docs/wizard.md

@@ -72,8 +72,12 @@ It does **not** install or change anything on the remote host.
 
 6) **Daemon install**
    - macOS: LaunchAgent
+     - Requires a logged-in user session; for headless, use a custom LaunchDaemon (not shipped).
    - Linux: systemd user unit
+     - Wizard enables lingering via `loginctl enable-linger <user>` so the Gateway stays up after logout.
+     - Requires sudo (writes `/var/lib/systemd/linger`).
    - Windows: Scheduled Task
+     - Runs on user logon; headless/system services are not configured by default.
 
 7) **Health check**
    - Starts the Gateway (if needed) and runs `clawdbot health`.