feat: refine providers onboarding and cli

docs/docs.json

@@ -654,7 +654,8 @@
           "platforms/ios",
           "platforms/android",
           "platforms/windows",
-          "platforms/linux"
+          "platforms/linux",
+          "platforms/exe-dev"
         ]
       },
       {

docs/platforms/exe-dev.md

@@ -0,0 +1,174 @@
+---
+summary: "Run Clawdbot Gateway on exe.dev (VM + HTTPS proxy) for remote access"
+read_when:
+  - You want a cheap always-on Linux host for the Gateway
+  - You want remote Control UI access without running your own VPS
+---
+
+# exe.dev
+
+Goal: Clawdbot Gateway running on an exe.dev VM, reachable from your laptop via:
+- **exe.dev HTTPS proxy** (easy, no tunnel) or
+- **SSH tunnel** (most secure; loopback-only Gateway)
+
+This page assumes **Ubuntu/Debian**. If you picked a different distro, map packages accordingly.
+
+## What you need
+
+- exe.dev account + `ssh exe.dev` working on your laptop
+- SSH keys set up (your laptop → exe.dev)
+- Model auth (OAuth or API key) you want to use
+- Provider credentials (optional): WhatsApp QR scan, Telegram bot token, Discord bot token, …
+
+## 1) Create the VM
+
+From your laptop:
+
+```bash
+ssh exe.dev new --name=clawdbot
+```
+
+Then connect:
+
+```bash
+ssh clawdbot.exe.xyz
+```
+
+Tip: keep this VM **stateful**. Clawdbot stores state under `~/.clawdbot/` and `~/clawd/`.
+
+## 2) Install prerequisites (on the VM)
+
+```bash
+sudo apt-get update
+sudo apt-get install -y git curl jq ca-certificates openssl
+```
+
+### Node 22
+
+Install Node **>= 22.12** (any method is fine). Quick check:
+
+```bash
+node -v
+```
+
+If you don’t already have Node 22 on the VM, use your preferred Node manager (nvm/mise/asdf) or a distro package source that provides Node 22+.
+
+Common Ubuntu/Debian option (NodeSource):
+
+```bash
+curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
+sudo apt-get install -y nodejs
+```
+
+## 3) Install Clawdbot
+
+Recommended on servers: npm global install.
+
+```bash
+npm i -g clawdbot@latest
+clawdbot --version
+```
+
+If native deps fail to install (rare; usually `sharp`), add build tools:
+
+```bash
+sudo apt-get install -y build-essential python3
+```
+
+## 4) First-time setup (wizard)
+
+Run the onboarding wizard on the VM:
+
+```bash
+clawdbot onboard --install-daemon
+```
+
+It can set up:
+- `~/clawd` workspace bootstrap
+- `~/.clawdbot/clawdbot.json` config
+- model auth profiles
+- provider config/login
+- Linux systemd **user** service (daemon)
+
+If you’re doing OAuth on a headless VM: do OAuth on a normal machine first, then copy the auth profile to the VM (see [FAQ](/start/faq)).
+
+## 5) Remote access options
+
+### Option A (recommended): SSH tunnel (loopback-only)
+
+Keep Gateway on loopback (default) and tunnel it from your laptop:
+
+```bash
+ssh -N -L 18789:127.0.0.1:18789 clawdbot.exe.xyz
+```
+
+Open locally:
+- `http://127.0.0.1:18789/` (Control UI)
+
+Runbook: [Remote access](/gateway/remote)
+
+### Option B: exe.dev HTTPS proxy (no tunnel)
+
+To let exe.dev proxy traffic to the VM, bind the Gateway to the LAN interface and set a token:
+
+```bash
+export CLAWDBOT_GATEWAY_TOKEN="$(openssl rand -hex 32)"
+clawdbot gateway --bind lan --port 8080 --token "$CLAWDBOT_GATEWAY_TOKEN"
+```
+
+For daemon runs, persist it in `~/.clawdbot/clawdbot.json`:
+
+```json5
+{
+  gateway: {
+    mode: "local",
+    port: 8080,
+    bind: "lan",
+    auth: { mode: "token", token: "YOUR_TOKEN" }
+  }
+}
+```
+
+Then point exe.dev’s proxy at `8080` (or whatever port you chose) and open your VM’s HTTPS URL:
+
+```bash
+ssh exe.dev share port clawdbot 8080
+```
+
+Open:
+- `https://clawdbot.exe.xyz/`
+
+In the Control UI, paste the token (UI → Settings → token). The UI sends it as `connect.params.auth.token`.
+
+Notes:
+- Prefer a **non-default** port (like `8080`) if your proxy expects an app port.
+- Treat the token like a password.
+
+Control UI details: [Control UI](/web/control-ui)
+
+## 6) Keep it running (daemon)
+
+On Linux, Clawdbot uses a systemd **user** service. After `--install-daemon`, verify:
+
+```bash
+systemctl --user status clawdbot-gateway.service
+```
+
+If the service dies after logout, enable lingering:
+
+```bash
+sudo loginctl enable-linger "$USER"
+```
+
+More: [Linux](/platforms/linux)
+
+## 7) Updates
+
+```bash
+npm i -g clawdbot@latest
+clawdbot doctor
+clawdbot gateway restart
+clawdbot health
+```
+
+Guide: [Updating](/install/updating)

docs/providers/imessage.md

@@ -19,7 +19,7 @@ Status: external CLI integration. Gateway spawns `imsg rpc` (JSON-RPC over stdio
 - macOS with Messages signed in.
 - Full Disk Access for Clawdbot + `imsg` (Messages DB access).
 - Automation permission when sending.
-- `imessage.cliPath` can point to a wrapper script (for example, an SSH hop to another Mac that runs `imsg rpc`).
+- `imessage.cliPath` can point to any command that proxies stdin/stdout (for example, a wrapper script that SSHes to another Mac and runs `imsg rpc`).
 
 ## Setup (fast path)
 1) Ensure Messages is signed in on this Mac.
@@ -46,7 +46,7 @@ Example:
 {
   imessage: {
     enabled: true,
-    cliPath: "imsg",
+    cliPath: "/usr/local/bin/imessage-remote",
     dmPolicy: "pairing",
     allowFrom: ["+15555550123"]
   }

docs/start/getting-started.md

@@ -140,6 +140,7 @@ pnpm clawdbot send --to +15555550123 --message "Hello from Clawdbot"
 If `health` shows “no auth configured”, go back to the wizard and set OAuth/key auth — the agent won’t be able to respond without it.
 
 Local probe tip: `pnpm clawdbot status --deep` runs provider checks without needing a gateway connection.
+Gateway snapshot: `pnpm clawdbot providers status` shows what the gateway reports (use `status --deep` for local-only probes).
 
 ## Next steps (optional, but great)
 

docs/start/onboarding.md

@@ -80,7 +80,7 @@ The onboarding flow now embeds the SwiftUI chat view directly. It uses a **speci
 This onboarding chat is where the agent:
 - does the BOOTSTRAP.md identity ritual (one question at a time)
 - visits **soul.md** with the user and writes `SOUL.md` (values, tone, boundaries)
-- asks how the user wants to talk (web-only / WhatsApp / Telegram)
+- asks how the user wants to talk (web-only / Telegram / WhatsApp)
 - guides linking steps (including showing a QR inline for WhatsApp via the `whatsapp_login` tool)
 
 If the workspace bootstrap is already complete (BOOTSTRAP.md removed), the onboarding chat step is skipped.

docs/start/wizard.md

@@ -30,7 +30,7 @@ clawdbot configure
 - Model/auth (Anthropic or OpenAI Codex OAuth recommended, API key optional, Minimax M2.1 via LM Studio)
 - Workspace location + bootstrap files
 - Gateway settings (port/bind/auth/tailscale)
-- Providers (WhatsApp, Telegram, Discord, Signal)
+- Providers (Telegram, WhatsApp, Discord, Signal)
 - Daemon install (LaunchAgent / systemd user unit)
 - Health check
 - Skills (recommended)