diff --git a/README.md b/README.md
index af056f1be..4bcdb32e6 100644
--- a/README.md
+++ b/README.md
@@ -125,7 +125,7 @@ CLAWDIS was built for **Clawd**, a space lobster AI assistant. See the full setu
 ### WhatsApp Web
 ```bash
 clawdis login      # Scan QR code
-clawdis gateway    # Start listening
+clawdis gateway    # Start listening (WS on 127.0.0.1:18789)
 ```
 
 ### Telegram (Bot API)
@@ -133,15 +133,35 @@ Bot-mode support (grammY only) shares the same `main` session as WhatsApp/WebCha
 
 ## Commands
 
+| Command | Description |
+|---------|-------------|
 | Command | Description |
 |---------|-------------|
 | `clawdis login` | Link WhatsApp Web via QR |
-| `clawdis send` | Send a message (WhatsApp default; `--provider telegram` for bot mode, text + media) |
+| `clawdis send` | Send a message (WhatsApp default; `--provider telegram` for bot mode). Always uses the Gateway WS; `--spawn-gateway` may start it if the port is free. |
 | `clawdis agent` | Talk directly to the agent (no WhatsApp send) |
-| `clawdis gateway` | Start auto-reply loop (WhatsApp + Telegram when configured) |
+| `clawdis gateway` | Start the Gateway server (WS control plane). Params: `--port`, `--token`, `--force`, `--verbose`. |
+| `clawdis gateway health|status|send|agent|call` | Gateway WS clients; never start the server unless you pass `--spawn-gateway` (and only if no listener exists). |
 | `clawdis status` | Web session health + session store summary |
+| `clawdis health` | Reports cached provider state; add `--probe` to force a fresh Baileys connect (may conflict if already connected). |
 | `clawdis heartbeat` | Trigger a heartbeat |
 
+#### Gateway client params (WS only)
+- `--url` (default `ws://127.0.0.1:18789`)
+- `--token` (shared secret if set on the gateway)
+- `--timeout <ms>` (WS call timeout)
+- `--spawn-gateway` (only if no listener is present; explicit opt-in)
+
+#### Send
+- `--provider whatsapp|telegram` (default whatsapp)
+- `--media <path-or-url>`
+- `--json` for machine-readable output
+- `--spawn-gateway` to start a local gateway if the port is free and nothing is listening.
+
+#### Health
+- Default: reads gateway/provider state (no extra Baileys socket).
+- `--probe` will open a transient Baileys connection; use only when diagnosing login issues (can be rejected if the main session is already connected).
+
 In chat, send `/status` to see if the agent is reachable, how much context the session has used, and the current thinking/verbose toggles—no agent call required.
 `/status` also shows whether your WhatsApp web session is linked and how long ago the creds were refreshed so you know when to re-scan the QR.