diff --git a/docs/start/faq.md b/docs/start/faq.md
index 8ea19e7de..30ea52816 100644
--- a/docs/start/faq.md
+++ b/docs/start/faq.md
@@ -1,15 +1,66 @@
 ---
 summary: "Frequently asked questions about Clawdbot setup, configuration, and usage"
 ---
-# FAQ 🦞
+# FAQ
 
-Common questions from the community. For detailed configuration, see [Configuration](/gateway/configuration).
+Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, multi-agent, OAuth/API keys, model failover). For the full config reference, see [Configuration](/gateway/configuration).
 
-## Installation & Setup
+## What is Clawdbot?
+
+### What is Clawdbot, in one paragraph?
+
+Clawdbot is a personal AI assistant you run on your own devices. It replies on the messaging surfaces you already use (WhatsApp, Telegram, Slack, Discord, Signal, iMessage, WebChat) and can also do voice + a live Canvas on supported platforms. The **Gateway** is the always‑on control plane; the assistant is the product.
+
+## Quick start and first‑run setup
+
+### What’s the recommended way to install and set up Clawdbot?
+
+The repo recommends running from source and using the onboarding wizard:
+
+```bash
+git clone https://github.com/clawdbot/clawdbot.git
+cd clawdbot
+
+pnpm install
+
+# Optional if you want built output / global linking:
+pnpm build
+
+# If the Control UI assets are missing or you want the dashboard:
+pnpm ui:install
+pnpm ui:build
+
+pnpm clawdbot onboard
+```
+
+The wizard can also build UI assets automatically. After onboarding, you typically run the Gateway on port **18789**.
+
+### What runtime do I need?
+
+Node **>= 22** is required. `pnpm` is recommended; `bun` is optional.
+
+### What does the onboarding wizard actually do?
+
+`clawdbot onboard` is the recommended setup path. In **local mode** it walks you through:
+
+- **Model/auth setup** (Anthropic OAuth recommended, OpenAI Codex OAuth supported, API keys optional, LM Studio local models supported)
+- **Workspace** location + bootstrap files
+- **Gateway settings** (bind/port/auth/tailscale)
+- **Providers** (WhatsApp, Telegram, Discord, Signal, iMessage)
+- **Daemon install** (LaunchAgent on macOS; systemd user unit on Linux/WSL2)
+- **Health checks** and **skills** selection
+
+It also warns if your configured model is unknown or missing auth.
+
+### Can I use Bun?
+
+Bun is supported for faster TypeScript execution, but **WhatsApp requires Node** in this ecosystem. The wizard lets you pick the runtime; choose **Node** if you use WhatsApp.
+
+## Where things live on disk
 
 ### Where does Clawdbot store its data?
 
-Everything lives under `~/.clawdbot/`:
+Everything lives under `~/.clawdbot/` (or `$CLAWDBOT_STATE_DIR` if you override the state dir):
 
 | Path | Purpose |
 |------|---------|
@@ -17,613 +68,98 @@ Everything lives under `~/.clawdbot/`:
 | `~/.clawdbot/credentials/oauth.json` | Legacy OAuth import (copied into auth profiles on first use) |
 | `~/.clawdbot/agents/<agentId>/agent/auth-profiles.json` | Auth profiles (OAuth + API keys) |
 | `~/.clawdbot/agents/<agentId>/agent/auth.json` | Runtime auth cache (managed automatically) |
-| `~/.clawdbot/credentials/` | Provider auth state (e.g. `whatsapp/<accountId>/creds.json`) |
-| `~/.clawdbot/agents/` | Per-agent state (agentDir + sessions) |
+| `~/.clawdbot/credentials/` | Provider state (e.g. `whatsapp/<accountId>/creds.json`) |
+| `~/.clawdbot/agents/` | Per‑agent state (agentDir + sessions) |
 | `~/.clawdbot/agents/<agentId>/sessions/` | Conversation history & state (per agent) |
 | `~/.clawdbot/agents/<agentId>/sessions/sessions.json` | Session metadata (per agent) |
 
-Legacy single-agent path: `~/.clawdbot/agent/*` (migrated by `clawdbot doctor`).
+Legacy single‑agent path: `~/.clawdbot/agent/*` (migrated by `clawdbot doctor`).
 
-Your **workspace** (AGENTS.md, memory files, skills) is separate — configured via `agent.workspace` in your config (default: `~/clawd`).
+Your **workspace** (AGENTS.md, memory files, skills, etc.) is separate and configured via `agent.workspace` (default: `~/clawd`).
 
-### What platforms does Clawdbot run on?
+## Config basics
 
-**macOS and Linux** are the primary targets. On Windows, use **WSL2** (Ubuntu recommended).
+### What format is the config? Where is it?
 
-- **macOS** — Fully supported, most tested
-- **Linux** — Works great, common for VPS/server deployments
-- **Windows (WSL2)** — WSL2 is strongly recommended; native Windows installs are untested and more problematic
+Clawdbot reads an optional **JSON5** config from:
 
-Some features are platform-specific:
-- **iMessage** — macOS only (uses `imsg` CLI)
-- **Clawdbot.app** — macOS native app (optional, gateway works without it)
-
-### What are the minimum system requirements?
-
-**Basically nothing!** The gateway is very lightweight — heavy compute happens on your model provider’s servers (Anthropic/OpenAI/etc.).
-
-- **RAM:** 512MB-1GB is enough (community member runs on 1GB VPS!)
-- **CPU:** 1 core is fine for personal use
-- **Disk:** ~500MB for Clawdbot + deps, plus space for logs/media
-
-The gateway is just shuffling messages around. A Raspberry Pi 4 can run it. For the CLI, prefer the Node runtime (most stable):
-
-```bash
-clawdbot gateway
+```
+~/.clawdbot/clawdbot.json
 ```
 
-### How do I install on Windows?
+If the file is missing, it uses safe‑ish defaults (including a default workspace of `~/clawd`).
 
-Use **WSL2** (Ubuntu recommended) and follow the Linux flow inside WSL. Quick start:
+### Do I have to restart after changing config?
 
-```powershell
-wsl --install
-```
+The Gateway watches the config and supports hot‑reload:
 
-Then open Ubuntu and run the normal Getting Started steps.
+- `gateway.reload.mode: "hybrid"` (default): hot‑apply safe changes, restart for critical ones
+- `hot`, `restart`, `off` are also supported
 
-Full guide: [Windows (WSL2)](/platforms/windows)
+A full restart is required for `gateway`, `bridge`, `discovery`, and `canvasHost` changes.
 
-### How do I install on Linux without Homebrew?
+### Is there an API / RPC way to apply config?
 
-Build CLIs from source! Example for `gogcli`:
+Yes. `config.apply` validates + writes the full config and restarts the Gateway as part of the operation.
 
-```bash
-git clone https://github.com/steipete/gogcli.git
-cd gogcli
-make
-sudo mv bin/gog /usr/local/bin/
-```
-
-Most of Peter's tools are Go binaries — clone, build, move to PATH. No brew needed.
-
-### I'm getting "unauthorized" errors on health check
-
-You need a config file. Run the onboarding wizard:
-
-```bash
-pnpm clawdbot onboard
-```
-
-This creates `~/.clawdbot/clawdbot.json` with your API keys, workspace path, and owner phone number.
-
-### My bot doesn’t respond after I DM it
-
-Clawdbot defaults to **pairing** for DMs. Your first DM sends a pairing code; messages are ignored until you approve it.
-
-```bash
-clawdbot pairing list --provider telegram
-clawdbot pairing approve --provider telegram <CODE>
-```
-
-### How do I start fresh?
-
-```bash
-# Backup first (optional)
-cp -r ~/.clawdbot ~/.clawdbot-backup
-
-# Remove config and credentials
-trash ~/.clawdbot
-
-# Re-run onboarding
-pnpm clawdbot onboard
-pnpm clawdbot login
-```
-
-### Something's broken — how do I diagnose?
-
-Run the doctor:
-
-```bash
-pnpm clawdbot doctor
-```
-
-It checks your config, skills status, and gateway health. It can also restart the gateway daemon if needed.
-
-### How do I search the docs quickly?
-
-Use the CLI docs search (live docs):
-
-```bash
-clawdbot docs "gateway lock"
-```
-
-The first run will fetch the helper CLIs if they are missing.
-
-### Terminal onboarding vs macOS app?
-
-**Use terminal onboarding** (`pnpm clawdbot onboard`) — it's more stable right now.
-
-The macOS app onboarding is still being polished and can have quirks (e.g., WhatsApp 515 errors, OAuth issues).
-
----
-
-## Authentication
-
-### OAuth vs API key — what's the difference?
-
-- **OAuth** — Uses your **subscription** (Anthropic Claude Pro/Max or OpenAI ChatGPT/Codex). No per‑token charges. ✅ Recommended!
-- **API key** — Pay‑per‑token via the provider’s API billing. Can get expensive fast.
-
-They're **separate billing**! An API key does NOT use your subscription.
-
-**For OAuth:** During onboarding, pick **Anthropic OAuth** or **OpenAI Codex OAuth**, log in, paste the code/URL when prompted. Or just run:
-
-```bash
-pnpm clawdbot login
-```
-
-**If OAuth fails** (headless/container): Do OAuth on a normal machine, then copy `~/.clawdbot/agents/<agentId>/agent/auth-profiles.json` (and `auth.json` if present) to your server. Legacy installs can still import `~/.clawdbot/credentials/oauth.json` on first use.
-
-### How are env vars loaded?
-
-CLAWDBOT reads env vars from the parent process (shell, launchd/systemd, CI, etc.). It also loads `.env` files:
-- `.env` in the current working directory
-- global fallback: `~/.clawdbot/.env` (aka `$CLAWDBOT_STATE_DIR/.env`)
-
-Neither `.env` file overrides existing env vars.
-
-Optional convenience: import missing expected keys from your login shell env (sources your shell profile):
+### What’s a minimal “sane” config for a first install?
 
 ```json5
 {
-  env: { shellEnv: { enabled: true, timeoutMs: 15000 } }
+  agent: { workspace: "~/clawd" },
+  whatsapp: { allowFrom: ["+15555550123"] }
 }
 ```
 
-Or set `CLAWDBOT_LOAD_SHELL_ENV=1` (timeout: `CLAWDBOT_SHELL_ENV_TIMEOUT_MS=15000`).
+This sets your workspace and restricts who can trigger the bot.
 
-### Does enterprise OAuth work?
+## Env vars and .env loading
 
-**Not currently.** Enterprise accounts use SSO which requires a different auth flow that Clawdbot’s OAuth login doesn’t support yet.
+### How does Clawdbot load environment variables?
 
-**Workaround:** Ask your enterprise admin to provision an API key (Anthropic or OpenAI) and use it via `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`.
+Clawdbot reads env vars from the parent process (shell, launchd/systemd, CI, etc.) and additionally loads:
 
-### OAuth callback not working (containers/headless)?
+- `.env` from the current working directory
+- a global fallback `.env` from `~/.clawdbot/.env` (aka `$CLAWDBOT_STATE_DIR/.env`)
 
-OAuth needs the callback to reach the machine running the CLI. Options:
+Neither `.env` file overrides existing env vars.
 
-1. **Copy auth manually** — Run OAuth on your laptop, copy `~/.clawdbot/agents/<agentId>/agent/auth-profiles.json` (and `auth.json` if present) to the container. Legacy flow: copy `~/.clawdbot/credentials/oauth.json` to trigger import.
-2. **SSH tunnel** — `ssh -L 18789:localhost:18789 user@server`
-3. **Tailscale** — Put both machines on your tailnet.
+### “I started the Gateway via a daemon and my env vars disappeared.” What now?
 
----
+Two common fixes:
 
-## Migration & Deployment
+1) Put the missing keys in `~/.clawdbot/.env` so they’re picked up even when the daemon doesn’t inherit your shell env.
+2) Enable shell import (opt‑in convenience):
 
-### How do I migrate Clawdbot to a new machine (or VPS)?
-
-1. **Backup on old machine:**
-   ```bash
-   # Config + credentials + sessions
-   tar -czvf clawdbot-backup.tar.gz ~/.clawdbot
-   
-   # Your workspace (memories, AGENTS.md, etc.)
-   tar -czvf workspace-backup.tar.gz ~/path/to/workspace
-   ```
-
-2. **Copy to new machine:**
-   ```bash
-   scp clawdbot-backup.tar.gz workspace-backup.tar.gz user@new-machine:~/
-   ```
-
-3. **Restore on new machine:**
-   ```bash
-   cd ~
-   tar -xzvf clawdbot-backup.tar.gz
-   tar -xzvf workspace-backup.tar.gz
-   ```
-
-4. **Install Clawdbot** (Node 22+, pnpm, clone repo, `pnpm install && pnpm build`)
-
-5. **Start gateway:**
-   ```bash
-   clawdbot gateway
-   ```
-
-**Note:** WhatsApp may notice the IP change and require re-authentication. If so, run `pnpm clawdbot login` again. Stop the old instance before starting the new one to avoid conflicts.
-
-### Can I run Clawdbot in Docker?
-
-Yes — Docker is optional but supported. Recommended: run the setup script:
-
-```bash
-./docker-setup.sh
-```
-
-It builds the image, runs onboarding + login, and starts Docker Compose. For manual steps and sandbox notes, see `docs/docker.md`.
-
-Key considerations:
-
-- **WhatsApp login:** QR code works in terminal — no display needed.
-- **Persistence:** Mount `~/.clawdbot/` and your workspace as volumes.
-- **pnpm doesn't persist:** Global npm installs don't survive container restarts. Install pnpm in your startup script.
-- **Browser automation:** Optional. If needed, install headless Chrome + Playwright deps, or connect to a remote browser via `--remote-debugging-port`.
-
-**Volume mappings (e.g., Unraid):**
-```
-/mnt/user/appdata/clawdbot/config    → /root/.clawdbot
-/mnt/user/appdata/clawdbot/workspace → /root/clawd
-/mnt/user/appdata/clawdbot/app       → /app
-```
-
-**Startup script (`start.sh`):**
-```bash
-#!/bin/bash
-npm install -g pnpm
-cd /app
-clawdbot gateway
-```
-
-**Container command:**
-```
-bash /app/start.sh
-```
-
-For more detail, see `docs/docker.md`.
-
-### Can I run Clawdbot headless on a VPS?
-
-Yes! The terminal QR code login works fine over SSH. For long-running operation:
-
-- Use `pm2`, `systemd`, or a `launchd` plist to keep the gateway running.
-- Consider Tailscale for secure remote access.
-
-### I'm seeing `InvalidPnpmLockfile: failed to migrate lockfile: 'pnpm-lock.yaml'`
-
-This can be ignored. This is simply a package manager warning when using PNPM and BUN.
-
-It often shows up when switching between `pnpm install` and `bun install`. If installs/build/tests work, you can safely ignore it.
-
-### bun binary vs Node runtime?
-
-Clawdbot can run as:
-- **bun binary (macOS app)** — Single executable, easy distribution, auto-restarts via launchd
-- **Node runtime** (`clawdbot gateway`) — More stable for WhatsApp
-
-If you see WebSocket errors like `ws.WebSocket 'upgrade' event is not implemented`, use Node instead of the bun binary. Bun's WebSocket implementation has edge cases that can break WhatsApp (Baileys) and can corrupt memory on reconnect. Baileys: https://github.com/WhiskeySockets/Baileys · Bun issue: https://github.com/oven-sh/bun/issues/5951
-
-**For stability:** Use launchd (macOS) or the Clawdbot.app — they handle process supervision (auto-restart on crash).
-
-**For debugging:** Use `pnpm gateway:watch` for live reload during development.
-
-### WhatsApp keeps disconnecting / crashing (macOS app)
-
-This is often the bun WebSocket issue. Workaround:
-
-1. Run gateway with Node instead:
-   ```bash
-   pnpm gateway:watch
-   ```
-2. In **Clawdbot.app → Settings → Debug**, check **"External gateway"**
-3. The app now connects to your Node gateway instead of spawning bun
-
-This is the most stable setup until bun's WebSocket handling improves.
-
----
-
-## Multi-Instance & Contexts
-
-### Can I run multiple Clawds (separate instances)?
-
-The intended design is **one Clawd, one identity**. Rather than running separate instances:
-
-- **Add skills** — Give your Clawd multiple capabilities (business + fitness + personal).
-- **Use context switching** — "Hey Clawd, let's talk about fitness" within the same conversation.
-- **Use groups for separation** — Create Telegram/Discord groups for different contexts; each group gets its own session.
-
-Why? A unified assistant knows your whole context. Your fitness coach knows when you've had a stressful work week.
-
-If you truly need full separation (different users, privacy boundaries), you'd need:
-- Separate config + state directories (`CLAWDBOT_CONFIG_PATH`, `CLAWDBOT_STATE_DIR`)
-- Separate agent workspaces (`agent.workspace`)
-- Separate gateway ports (`gateway.port` / `--port`)
-- Separate phone numbers for WhatsApp (one number = one account)
-
-### Can I have separate "threads" for different topics?
-
-Currently, sessions are per-chat:
-- Each WhatsApp/Telegram DM = one session
-- Each group = separate session
-
-**Workaround:** Create multiple groups (even just you + the bot) for different contexts. Each group maintains its own session.
-
-Feature request? Open a [GitHub discussion](https://github.com/clawdbot/clawdbot/discussions)!
-
-### How do groups work?
-
-Groups get separate sessions automatically. By default, the bot requires a **mention** to respond in groups.
-
-Per-group activation can be changed by the owner:
-- `/activation mention` — respond only when mentioned (default)
-- `/activation always` — respond to all messages
-
-See [Groups](/concepts/groups) for details.
-
----
-
-## Context & Memory
-
-### How much context can Clawdbot handle?
-
-Context window depends on the model. Clawdbot uses **autocompaction** — older conversation gets summarized to stay under the limit. See [/concepts/compaction](/concepts/compaction).
-
-Practical tips:
-- Keep `AGENTS.md` focused, not bloated.
-- Use `/compact` to shrink older context or `/new` to reset when it gets stale.
-- For large memory/notes collections, use search tools like `qmd` rather than loading everything.
-
-### Where are my memory files?
-
-In your workspace directory (configured in `agent.workspace`, default `~/clawd`). Look for:
-- `memory/` — daily memory files
-- `AGENTS.md` — agent instructions
-- `TOOLS.md` — tool-specific notes
-
-Check your config:
-```bash
-cat ~/.clawdbot/clawdbot.json | grep workspace
-```
-
----
-
-## Platforms
-
-### Which platforms does Clawdbot support?
-
-- **WhatsApp** — Primary. Uses WhatsApp Web protocol.
-- **Telegram** — Via Bot API (grammY).
-- **Discord** — Bot integration.
-- **iMessage** — Via `imsg` CLI (macOS only).
-- **Signal** — Via `signal-cli` (see [Signal](/providers/signal)).
-- **WebChat** — Browser-based chat UI.
-
-### Discord: Bot works in channels but not DMs?
-
-Discord has **separate allowlists** for channels vs DMs:
-
-- `discord.guilds.*.users` — controls who can talk in server channels
-- `discord.dm.allowFrom` — controls who can DM the bot
-
-If channels work but DMs don't, add `discord.dm.allowFrom` to your config:
-
-```json
+```json5
 {
-  "discord": {
-    "dm": {
-      "enabled": true,
-      "allowFrom": ["YOUR_DISCORD_USER_ID"]
-    },
-    "guilds": {
-      "your-server": {
-        "users": ["YOUR_DISCORD_USER_ID"]
-      }
+  env: {
+    shellEnv: {
+      enabled: true,
+      timeoutMs: 15000
     }
   }
 }
 ```
 
-Find your user ID: Discord Settings → Advanced → Developer Mode → right-click yourself → Copy User ID.
+This runs your login shell and imports only missing expected keys (never overrides). Env var equivalents:
+`CLAWDBOT_LOAD_SHELL_ENV=1`, `CLAWDBOT_SHELL_ENV_TIMEOUT_MS=15000`.
 
-### Images/media not being understood by the agent?
+## Models: defaults, selection, aliases, switching
 
-If you send an image but your Clawd doesn't "see" it, check these:
+### What is the “default model”?
 
-**1. Is your model vision-capable?**
+Clawdbot’s default model is whatever you set as:
 
-Not all models support images! Check `agent.model` in your config:
-
-- ✅ Vision (examples): `anthropic/claude-opus-4-5`, `anthropic/claude-sonnet-4-5`, `anthropic/claude-haiku-4-5`, `openai/gpt-5.2`, `openai/gpt-4o`, `google/gemini-3-pro-preview`, `google/gemini-3-flash-preview`
-- ❌ No vision: Most local LLMs (Llama, Mistral), older models, text-only configs
-
-**2. Is media being downloaded?**
-
-```bash
-ls -la ~/.clawdbot/media/inbound/
-grep -i "media\|download" /tmp/clawdbot/clawdbot-*.log | tail -20
+```
+agent.model.primary
 ```
 
-**3. Is `agent.mediaMaxMb` too low?**
+Models are referenced as `provider/model` (example: `anthropic/claude-opus-4-5`). If you omit the provider, Clawdbot currently assumes `anthropic` as a temporary deprecation fallback — but you should still **explicitly** set `provider/model`.
 
-Default is 5MB. Large images get resized, but if the limit is set very low, media might be skipped.
+### How do I switch models on the fly (without restarting)?
 
-**4. Does the agent see `[media attached: ...]`?**
-
-If this line isn't in the agent's input, the gateway didn't pass the media. Check logs for errors.
-
-**5. For PDFs, audio, video, and exotic files:**
-
-Use the [summarize](https://summarize.sh) skill to extract and condense content from files that can't be passed directly to vision.
-
-### Can I use multiple platforms at once?
-
-Yes! One Clawdbot gateway can connect to WhatsApp, Telegram, Discord, and more simultaneously. Each platform maintains its own sessions.
-
-### WhatsApp: Can I use two numbers?
-
-One WhatsApp account = one phone number = one gateway connection. For a second number, you'd need a second gateway instance with a separate config directory.
-
----
-
-## Skills & Tools
-
-### How do I add new skills?
-
-Skills are auto-discovered from your workspace's `skills/` folder. After adding new skills:
-
-1. Send `/reset` (or `/new`) in chat to start a new session
-2. The new skills will be available
-
-No gateway restart needed!
-
-### How do I run commands on other machines?
-
-Use **[Tailscale](https://tailscale.com/)** to create a secure network between your machines:
-
-1. Install Tailscale on all machines (it's separate from Clawdbot — set it up yourself)
-2. Each gets a stable IP (like `100.x.x.x`)
-3. SSH just works: `ssh user@100.x.x.x "command"`
-
-Clawdbot can use Tailscale when you set `bridge.bind: "tailnet"` in your config — it auto-detects your Tailscale IP.
-
-For deeper integration, look into **Clawdbot nodes** — pair remote machines with your gateway for camera/screen/automation access.
-
----
-
-## Troubleshooting
-
-### Build errors (TypeScript)
-
-If you hit build errors on `main`:
-
-1. Pull latest: `git pull origin main && pnpm install`
-2. Try `pnpm clawdbot doctor`
-3. Check [GitHub issues](https://github.com/clawdbot/clawdbot/issues) or Discord
-4. Temporary workaround: checkout an older commit
-
-### WhatsApp logged me out
-
-WhatsApp sometimes disconnects on IP changes or after updates. Re-authenticate:
-
-```bash
-pnpm clawdbot login
-```
-
-Scan the QR code and you're back.
-
-### Gateway won't start
-
-Check logs:
-```bash
-cat /tmp/clawdbot/clawdbot-$(date +%Y-%m-%d).log
-```
-
-Common issues:
-- Port already in use (change with `--port`)
-- Missing API keys in config
-- Invalid config syntax (remember it's JSON5, but still check for errors)
-- **Tailscale serve + bind conflict:** If using `tailscale.mode: "serve"`, you must set `gateway.bind: "loopback"` (not `"lan"`). Tailscale serve proxies traffic itself.
-
-**Debug mode** — use watch for live reload:
-```bash
-pnpm gateway:watch
-```
-
-**Pro tip:** Use Codex to debug:
-```bash
-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.
-
-Onboarding attempts to enable lingering; if it’s still off, run:
-```bash
-sudo loginctl enable-linger $USER
-```
-
-**macOS/WSL2**
-
-Gateway daemons run in the user session by default. Keep the user logged in
-(WSL2 services stop when the WSL VM shuts down).
-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.
-
-**macOS (Clawdbot.app)**
-
-- Quit the menu bar app to stop the gateway.
-- For debugging, restart via the app (or `scripts/restart-mac.sh` when working in the repo).
-- To inspect launchd state: `launchctl print gui/$UID | grep clawdbot`
-
-**macOS (CLI launchd service, if installed)**
-
-```bash
-clawdbot gateway stop
-clawdbot gateway restart
-```
-
-**Linux (systemd)**
-
-```bash
-# Check if running
-systemctl list-units | grep -i clawdbot
-
-# Stop and disable
-clawdbot gateway stop
-systemctl --user disable --now clawdbot-gateway.service
-
-# Or just restart
-clawdbot gateway restart
-```
-
-**pm2 (if used)**
-
-```bash
-pm2 list
-pm2 delete clawdbot
-```
-
-### Clean uninstall (start fresh)
-
-```bash
-# macOS: stop launchd service
-launchctl disable gui/$UID/com.clawdbot.gateway
-launchctl bootout gui/$UID/com.clawdbot.gateway 2>/dev/null
-
-# Linux: stop systemd user service
-systemctl --user disable --now clawdbot-gateway.service
-
-# Linux (system-wide unit, if installed)
-sudo systemctl disable --now clawdbot-gateway.service
-
-# Kill any remaining processes
-pkill -f "clawdbot"
-
-# Remove data
-trash ~/.clawdbot
-
-# Remove repo and re-clone (adjust path if you cloned elsewhere)
-trash ~/Projects/clawdbot
-git clone https://github.com/clawdbot/clawdbot.git ~/Projects/clawdbot
-cd ~/Projects/clawdbot && pnpm install && pnpm build
-pnpm clawdbot onboard
-```
-
----
-
-## Chat Commands
-
-Quick reference (send these in chat):
-
-| Command | Action |
-|---------|--------|
-| `/help` | Show available commands |
-| `/status` | Health + session info |
-| `/stop` | Abort the current run |
-| `/new` or `/reset` | Reset the session |
-| `/compact [notes]` | Compact session context |
-| `/restart` | Restart Clawdbot |
-| `/activation mention\|always` | Group activation (owner-only) |
-| `/think <level>` | Set thinking level (off\|minimal\|low\|medium\|high) |
-| `/verbose on\|off` | Toggle verbose mode |
-| `/reasoning on\|off\|stream` | Toggle reasoning visibility (stream = Telegram draft only) |
-| `/elevated on\|off` | Toggle elevated bash mode (approved senders only) |
-| `/model <name>` | Switch AI model (see below) |
-| `/queue <mode>` | Queue mode (see below) |
-
-Slash commands are owner-only (gated by `whatsapp.allowFrom` and command authorization on other surfaces).
-Commands are only recognized when the entire message is the command (slash required; no plain-text aliases).
-Full list + config: [Slash commands](/tools/slash-commands)
-
-### How do I switch models on the fly?
-
-Use `/model` to switch without restarting:
+Use the `/model` command as a standalone message:
 
 ```
 /model sonnet
@@ -635,112 +171,281 @@ Use `/model` to switch without restarting:
 /model gemini-flash
 ```
 
-List available models with `/model`, `/model list`, or `/model status`.
+You can list available models with `/model`, `/model list`, or `/model status`.
 
-Clawdbot ships a few default model shorthands (you can override them in config):
-`opus`, `sonnet`, `gpt`, `gpt-mini`, `gemini`, `gemini-flash`.
+### Are opus / sonnet / gpt built‑in shortcuts?
 
-**Setup:** Configure models and aliases in `clawdbot.json`:
+Yes. Clawdbot ships a few default shorthands (only applied when the model exists in `agent.models`):
 
-```json
+- `opus` → `anthropic/claude-opus-4-5`
+- `sonnet` → `anthropic/claude-sonnet-4-5`
+- `gpt` → `openai/gpt-5.2`
+- `gpt-mini` → `openai/gpt-5-mini`
+- `gemini` → `google/gemini-3-pro-preview`
+- `gemini-flash` → `google/gemini-3-flash-preview`
+
+If you set your own alias with the same name, your value wins.
+
+### How do I define/override model shortcuts (aliases)?
+
+Aliases come from `agent.models.<modelId>.alias`. Example:
+
+```json5
 {
-  "agent": {
-    "model": { "primary": "anthropic/claude-opus-4-5" },
-    "models": {
-      "anthropic/claude-opus-4-5": { "alias": "opus" },
-      "anthropic/claude-sonnet-4-5": { "alias": "sonnet" },
-      "anthropic/claude-haiku-4-5": { "alias": "haiku" }
+  agent: {
+    model: { primary: "anthropic/claude-opus-4-5" },
+    models: {
+      "anthropic/claude-opus-4-5": { alias: "opus" },
+      "anthropic/claude-sonnet-4-5": { alias: "sonnet" },
+      "anthropic/claude-haiku-4-5": { alias: "haiku" }
     }
   }
 }
 ```
 
-**Tip:** `/model` is processed at the gateway level — it works even if you're rate-limited (429) on the current model!
+Then `/model sonnet` (or `/<alias>` when supported) resolves to that model ID.
 
-### Alternative providers (OpenRouter, Z.AI)?
+### How do I add models from other providers like OpenRouter or Z.AI?
 
-If you don't want to use Anthropic directly, you can use alternative providers:
+OpenRouter (pay‑per‑token; many models):
 
-**OpenRouter** (pay-per-token, many models):
 ```json5
 {
   agent: {
     model: { primary: "openrouter/anthropic/claude-sonnet-4-5" },
-    models: { "openrouter/anthropic/claude-sonnet-4-5": {} },
-    env: { OPENROUTER_API_KEY: "sk-or-..." }
-  }
+    models: { "openrouter/anthropic/claude-sonnet-4-5": {} }
+  },
+  env: { OPENROUTER_API_KEY: "sk-or-..." }
 }
 ```
 
-**Z.AI** (flat-rate plans, GLM models):
+Z.AI (GLM models):
+
 ```json5
 {
   agent: {
     model: { primary: "zai/glm-4.7" },
-    models: { "zai/glm-4.7": {} },
-    env: { ZAI_API_KEY: "..." }
+    models: { "zai/glm-4.7": {} }
+  },
+  env: { ZAI_API_KEY: "..." }
+}
+```
+
+If you reference a provider/model but the required provider key is missing, you’ll get a runtime auth error (e.g. `No API key found for provider "zai"`).
+
+## Model failover and “All models failed”
+
+### How does failover work?
+
+Failover happens in two stages:
+
+1) **Auth profile rotation** within the same provider.
+2) **Model fallback** to the next model in `agent.model.fallbacks`.
+
+Cooldowns apply to failing profiles (exponential backoff), so Clawdbot can keep responding even when a provider is rate‑limited or temporarily failing.
+
+### What does this error mean?
+
+```
+No credentials found for profile "anthropic:default"
+```
+
+It means the system attempted to use the auth profile ID `anthropic:default`, but could not find credentials for it in the expected auth store.
+
+### Fix checklist for `No credentials found for profile "anthropic:default"`
+
+- **Confirm where auth profiles live** (new vs legacy paths)
+  - Current: `~/.clawdbot/agents/<agentId>/agent/auth-profiles.json`
+  - Legacy: `~/.clawdbot/agent/*` (migrated by `clawdbot doctor`)
+- **Confirm your env var is loaded by the Gateway**
+  - If you set `ANTHROPIC_API_KEY` in your shell but run the Gateway via systemd/launchd, it may not inherit it. Put it in `~/.clawdbot/.env` or enable `env.shellEnv`.
+- **Make sure you’re editing the correct agent**
+  - Multi‑agent setups mean there can be multiple `auth-profiles.json` files.
+- **Sanity‑check model/auth status**
+  - Use `/model status` to see configured models and whether providers are authenticated.
+
+### Why did it also try Google Gemini and fail?
+
+If your model config includes Google Gemini as a fallback (or you switched to a Gemini shorthand), Clawdbot will try it during model fallback. If you haven’t configured Google credentials, you’ll see `No API key found for provider "google"`.
+
+Fix: either provide Google auth, or remove/avoid Google models in `agent.model.fallbacks` / aliases so fallback doesn’t route there.
+
+## Auth profiles: what they are and how to manage them
+
+### What is an auth profile?
+
+An auth profile is a named credential record (OAuth or API key) tied to a provider. Profiles live in:
+
+```
+~/.clawdbot/agents/<agentId>/agent/auth-profiles.json
+```
+
+### What are typical profile IDs?
+
+Clawdbot uses provider‑prefixed IDs like:
+
+- `anthropic:default` (common when no email identity exists)
+- `anthropic:<email>` for OAuth identities
+- custom IDs you choose (e.g. `anthropic:work`)
+
+### Can I control which auth profile is tried first?
+
+Yes. Config supports optional metadata for profiles and an ordering per provider (`auth.order.<provider>`). This does **not** store secrets; it maps IDs to provider/mode and sets rotation order.
+
+### OAuth vs API key: what’s the difference?
+
+Clawdbot supports both:
+
+- **OAuth** often leverages subscription access (where applicable).
+- **API keys** use pay‑per‑token billing.
+
+The wizard explicitly supports Anthropic OAuth and OpenAI Codex OAuth and can store API keys for you.
+
+## Gateway: ports, “already running”, and remote mode
+
+### What port does the Gateway use?
+
+`gateway.port` controls the single multiplexed port for WebSocket + HTTP (Control UI, hooks, etc.).
+
+Precedence:
+
+```
+--port > CLAWDBOT_GATEWAY_PORT > gateway.port > default 18789
+```
+
+### What does “another gateway instance is already listening” mean?
+
+Clawdbot enforces a runtime lock by binding the WebSocket listener immediately on startup (default `ws://127.0.0.1:18789`). If the bind fails with `EADDRINUSE`, it throws `GatewayLockError` indicating another instance is already listening.
+
+Fix: stop the other instance, free the port, or run with `clawdbot gateway --port <port>`.
+
+### How do I run Clawdbot in remote mode (client connects to a Gateway elsewhere)?
+
+Set `gateway.mode: "remote"` and point to a remote WebSocket URL, optionally with a token/password:
+
+```json5
+{
+  gateway: {
+    mode: "remote",
+    remote: {
+      url: "ws://gateway.tailnet:18789",
+      token: "your-token",
+      password: "your-password"
+    }
   }
 }
 ```
 
-**Important:** Always use the latest Claude models (4.5 series). Don't use older 3.x models — they're deprecated and less capable. Check [OpenRouter models](https://openrouter.ai/models?q=claude) for exact IDs.
+Notes:
+- `clawdbot gateway` only starts when `gateway.mode` is `local` (or you pass the override flag).
+- The macOS app watches the config file and switches modes live when these values change.
 
-### Model + thinking mode issues?
+### Can I run multiple Gateways on the same host?
 
-Some models don't support extended thinking well:
+Yes, but you must isolate:
 
-- **Gemini Flash + thinking:** Can cause "Corrupted thought signature" errors. Fix: `/think off`
-- **Claude Opus + thinking off:** Opus may "think out loud" anyway. Better to use `/think low` than `off`.
-- **Local LLMs:** Most don't support the thinking/reasoning separation. Set `reasoning: false` in your model config.
+- `CLAWDBOT_CONFIG_PATH` (per‑instance config)
+- `CLAWDBOT_STATE_DIR` (per‑instance state)
+- `agent.workspace` (workspace isolation)
+- `gateway.port` (unique ports)
 
-If you get weird errors after switching models, try `/think off` and `/new` to reset.
+There are convenience CLI flags like `--dev` and `--profile <name>` that shift state dirs and ports.
+
+## Logging and debugging
+
+### Where are logs?
+
+Default log file:
+
+```
+/tmp/clawdbot/clawdbot-YYYY-MM-DD.log
+```
+
+You can set a stable path via `logging.file`. File log level is controlled by `logging.level`. Console verbosity is controlled by `--verbose` and `logging.consoleLevel`.
+
+### What’s the fastest way to get more details when something fails?
+
+Start the Gateway with `--verbose` to get more console detail. Then inspect the log file for provider auth, model routing, and RPC errors.
+
+## Security and access control
+
+### Is it safe to expose Clawdbot to inbound DMs?
+
+Treat inbound DMs as untrusted input. Defaults are designed to reduce risk:
+
+- Default behavior on DM‑capable providers is **pairing**:
+  - Unknown senders receive a pairing code; the bot does not process their message.
+  - Approve with: `clawdbot pairing approve --provider <provider> <code>`
+- Opening DMs publicly requires explicit opt‑in (`dmPolicy: "open"` and allowlist `"*"`).
+
+Run `clawdbot doctor` to surface risky DM policies.
+
+## Chat commands, aborting tasks, and “it won’t stop”
 
 ### How do I stop/cancel a running task?
 
-Send one of these **as a standalone message** (no slash): `stop`, `abort`, `esc`, `wait`, `exit`.
-These are abort triggers, not slash commands.
+Send any of these **as a standalone message** (no slash):
+
+```
+stop
+abort
+esc
+wait
+exit
+```
+
+These are abort triggers (not slash commands).
+
+For background processes (from the bash tool), you can ask the agent to run:
 
-For background processes (like Codex), use:
 ```
 process action:kill sessionId:XXX
 ```
 
-You can also configure `routing.queue.mode` to control how new messages interact with running tasks:
-- `steer` — New messages redirect the current task
-- `followup` — Run messages one at a time
-- `collect` — Batch messages, reply once after things settle
-- `steer-backlog` — Steer now, process backlog afterward
-- `interrupt` — Abort current run, start fresh
+Slash commands only run when the **entire** message is the command (must start with `/`). Inline text like `hello /status` is ignored.
 
-### Does Codex CLI use my ChatGPT Pro subscription or API credits?
+### Why does it feel like the bot “ignores” rapid‑fire messages?
 
-**Both are supported!** Codex CLI can auth via:
+Queue mode controls how new messages interact with an in‑flight run. Use `/queue` to change modes:
 
-1. **Browser/Device OAuth** → Uses your ChatGPT Pro/Plus subscription (no per-token cost)
-   ```bash
-   codex login --device-auth
-   # Opens browser, log in with your ChatGPT account
-   ```
+- `steer` — new messages redirect the current task
+- `followup` — run messages one at a time
+- `collect` — batch messages and reply once (default)
+- `steer-backlog` — steer now, then process backlog
+- `interrupt` — abort current run and start fresh
 
-2. **API key** → Pay-per-token via OpenAI API billing
-   ```bash
-   export OPENAI_API_KEY="sk-..."
-   ```
+You can add options like `debounce:2s cap:25 drop:summarize` for followup modes.
 
-If you have a ChatGPT subscription, use browser auth to avoid API charges!
+## Common troubleshooting
 
-### How do rapid-fire messages work?
+### “All models failed” — what should I check first?
 
-Use `/queue` to control how messages sent in quick succession are handled:
+- **Credentials** present for the provider(s) being tried (auth profiles + env vars).
+- **Model routing**: confirm `agent.model.primary` and fallbacks are models you can access.
+- **Gateway logs** in `/tmp/clawdbot/…` for the exact provider error.
+- **`/model status`** to see current configured models + shorthands.
 
-- **`/queue steer`** — New messages steer the current response
-- **`/queue collect`** — Batch messages, reply once after things settle
-- **`/queue followup`** — One at a time, in order
-- **`/queue steer-backlog`** — Steer now, process backlog afterward
-- **`/queue interrupt`** — Abort current run, start fresh
+### WhatsApp logged me out. How do I re‑auth?
 
-If you tend to send multiple short messages, `/queue steer` feels most natural.
+Run the login command again and scan the QR code:
+
+```bash
+clawdbot login
+```
+
+### Build errors on `main` — what’s the standard fix path?
+
+1) `git pull origin main && pnpm install`
+2) `pnpm clawdbot doctor`
+3) Check GitHub issues or Discord
+4) Temporary workaround: check out an older commit
+
+## Answer the exact question from the screenshot/chat log
+
+**Q: “What’s the default model for Anthropic with an API key?”**
+
+**A:** In Clawdbot, credentials and model selection are separate. Setting `ANTHROPIC_API_KEY` (or storing an Anthropic API key in auth profiles) enables authentication, but the actual default model is whatever you configure in `agent.model.primary` (for example, `anthropic/claude-sonnet-4-5` or `anthropic/claude-opus-4-5`). If you see `No credentials found for profile "anthropic:default"`, it means the Gateway couldn’t find Anthropic credentials in the expected `auth-profiles.json` for the agent that’s running.
 
 ---
 
-*Still stuck? Ask in [Discord](https://discord.gg/qkhbAGHRBT) or open a [GitHub discussion](https://github.com/clawdbot/clawdbot/discussions).* 🦞
+Still stuck? Ask in Discord or open a GitHub discussion.