docs: add quick setup blocks to chat providers

docs/providers/discord.md

@@ -8,6 +8,25 @@ read_when:
 
 Status: ready for DM and guild text channels via the official Discord bot gateway.
 
+## Quick setup (beginner)
+1) Create a Discord bot and copy the bot token.
+2) Set the token for Clawdbot:
+   - Env: `DISCORD_BOT_TOKEN=...`
+   - Or config: `discord.token: "..."`.
+3) Invite the bot to your server with message permissions.
+4) Start the gateway.
+5) DM access is pairing by default; approve the pairing code on first contact.
+
+Minimal config:
+```json5
+{
+  discord: {
+    enabled: true,
+    token: "YOUR_BOT_TOKEN"
+  }
+}
+```
+
 ## Goals
 - Talk to Clawdbot via Discord DMs or guild channels.
 - Direct chats collapse into the agent's main session (default `agent:main:main`); guild channels stay isolated as `agent:<agentId>:discord:channel:<channelId>` (display names use `discord:<guildSlug>#<channelSlug>`).
@@ -18,8 +37,8 @@ Status: ready for DM and guild text channels via the official Discord bot gatewa
 1. Create a Discord application → Bot, enable the intents you need (DMs + guild messages + message content), and grab the bot token.
 2. Invite the bot to your server with the permissions required to read/send messages where you want to use it.
 3. Configure Clawdbot with `DISCORD_BOT_TOKEN` (or `discord.token` in `~/.clawdbot/clawdbot.json`).
-4. Run the gateway; it auto-starts the Discord provider only when a `discord` config section exists **and** the token is set (unless `discord.enabled = false`).
+4. Run the gateway; it auto-starts the Discord provider when a token is available (env or config) and `discord.enabled` is not `false`.
-   - If you prefer env vars, still add `discord: { enabled: true }` to `~/.clawdbot/clawdbot.json` and set `DISCORD_BOT_TOKEN`.
+   - If you prefer env vars, set `DISCORD_BOT_TOKEN` (a config block is optional).
 5. Direct chats: use `user:<id>` (or a `<@id>` mention) when delivering; all turns land in the shared `main` session. Bare numeric IDs are ambiguous and rejected.
 6. Guild channels: use `channel:<channelId>` for delivery. Mentions are required by default and can be set per guild or per channel.
 7. Direct chats: secure by default via `discord.dm.policy` (default: `"pairing"`). Unknown senders get a pairing code (expires after 1 hour); approve via `clawdbot pairing approve discord <code>`.

docs/providers/imessage.md

@@ -9,6 +9,24 @@ read_when:
 
 Status: external CLI integration. Gateway spawns `imsg rpc` (JSON-RPC over stdio).
 
+## Quick setup (beginner)
+1) Ensure Messages is signed in on this Mac.
+2) Install `imsg`:
+   - `brew install steipete/tap/imsg`
+3) Configure Clawdbot with `imessage.cliPath` and `imessage.dbPath`.
+4) Start the gateway and approve any macOS prompts (Automation + Full Disk Access).
+
+Minimal config:
+```json5
+{
+  imessage: {
+    enabled: true,
+    cliPath: "/usr/local/bin/imsg",
+    dbPath: "/Users/<you>/Library/Messages/chat.db"
+  }
+}
+```
+
 ## What it is
 - iMessage provider backed by `imsg` on macOS.
 - Deterministic routing: replies always go back to iMessage.

docs/providers/index.md

@@ -1,40 +1,28 @@
 ---
-summary: "All supported providers (models + messaging) in one place"
+summary: "Messaging platforms Clawdbot can connect to"
 read_when:
-  - You want a single hub for every provider we document
+  - You want to choose a chat provider for Clawdbot
-  - You want model providers vs chat providers split clearly
+  - You need a quick overview of supported messaging platforms
 ---
-# Providers hub
+# Chat Providers
 
-This hub covers **model providers** (LLMs) and **messaging/chat providers** (WhatsApp, Telegram, etc).
+Clawdbot can talk to you on any chat app you already use. Each provider connects via the Gateway.
-For model selection rules, see [/concepts/models](/concepts/models). For the full provider catalog, see
+Text is supported everywhere; media and reactions vary by provider.
-[/concepts/model-providers](/concepts/model-providers).
 
-## Model providers
+## Supported providers
 
-- [OpenAI (API + Codex)](/providers/openai)
+- [WhatsApp](/providers/whatsapp) — Most popular; uses Baileys and requires QR pairing.
-- [Anthropic (API + Claude CLI)](/providers/anthropic)
+- [Telegram](/providers/telegram) — Bot API via grammY; supports groups.
-- [OpenRouter](/providers/openrouter)
+- [Discord](/providers/discord) — Discord Bot API + Gateway; supports servers, channels, and DMs.
-- [OpenCode Zen](/providers/opencode)
+- [Slack](/providers/slack) — Bolt SDK; workspace apps.
-- [Z.AI](/providers/zai)
+- [Signal](/providers/signal) — signal-cli; privacy-focused.
-- [GLM models](/providers/glm)
+- [iMessage](/providers/imessage) — macOS only; native integration.
+- [Microsoft Teams](/providers/msteams) — Bot Framework; enterprise support.
+- [WebChat](/web/webchat) — Gateway WebChat UI over WebSocket.
 
-Full list (xAI, Groq, Mistral, etc.): [/concepts/model-providers](/concepts/model-providers)
+## Notes
 
-## Messaging + chat providers
+- Providers can run simultaneously; configure multiple and Clawdbot will route per chat.
-
+- Group behavior varies by provider; see [Groups](/concepts/groups).
-- [WhatsApp](/providers/whatsapp)
+- DM pairing and allowlists are enforced for safety; see [Security](/gateway/security).
-- [Telegram](/providers/telegram)
+- Model providers are documented separately; see [Model Providers](/providers/models).
-- [Telegram (grammY notes)](/providers/grammy)
-- [Slack](/providers/slack)
-- [Discord](/providers/discord)
-- [Signal](/providers/signal)
-- [iMessage](/providers/imessage)
-- [Location parsing](/providers/location)
-- [Provider troubleshooting](/providers/troubleshooting)
-
-## Ingress + web
-
-- [WebChat](/web/webchat)
-- [Webhooks](/automation/webhook)
-- [Gmail Pub/Sub](/automation/gmail-pubsub)

docs/providers/models.md

@@ -0,0 +1,33 @@
+---
+summary: "Model providers (LLMs) supported by Clawdbot"
+read_when:
+  - You want to choose a model provider
+  - You want quick setup examples for LLM auth + model selection
+---
+# Model Providers
+
+Clawdbot can use many LLM providers. Pick one, authenticate, then set the default
+model as `provider/model`.
+
+## Quick start (two steps)
+
+1) Authenticate with the provider (usually via `clawdbot onboard`).
+2) Set the default model:
+
+```json5
+{
+  agents: { defaults: { model: { primary: "anthropic/claude-opus-4-5" } } }
+}
+```
+
+## Supported providers (starter set)
+
+- [OpenAI (API + Codex)](/providers/openai)
+- [Anthropic (API + Claude CLI)](/providers/anthropic)
+- [OpenRouter](/providers/openrouter)
+- [OpenCode Zen](/providers/opencode)
+- [Z.AI](/providers/zai)
+- [GLM models](/providers/glm)
+
+For the full provider catalog (xAI, Groq, Mistral, etc.) and advanced configuration,
+see [Model providers](/concepts/model-providers).

docs/providers/msteams.md

@@ -12,6 +12,25 @@ Updated: 2026-01-08
 
 Status: text + DM attachments are supported; channel/group attachments require Microsoft Graph permissions. Polls are sent via Adaptive Cards.
 
+## Quick setup (beginner)
+1) Create an **Azure Bot** (App ID + client secret + tenant ID).
+2) Configure Clawdbot with those credentials.
+3) Expose `/api/messages` (port 3978 by default) via a public URL or tunnel.
+4) Install the Teams app package and start the gateway.
+
+Minimal config:
+```json5
+{
+  msteams: {
+    enabled: true,
+    appId: "<APP_ID>",
+    appPassword: "<APP_PASSWORD>",
+    tenantId: "<TENANT_ID>",
+    webhook: { port: 3978, path: "/api/messages" }
+  }
+}
+```
+
 ## Goals
 - Talk to Clawdbot via Teams DMs, group chats, or channels.
 - Keep routing deterministic: replies always go back to the provider they arrived on.

docs/providers/openai.md

@@ -7,7 +7,8 @@ read_when:
 # OpenAI
 
 OpenAI provides developer APIs for GPT models. Codex supports **ChatGPT sign-in** for subscription
-access or **API key** sign-in for usage-based access. The Codex CLI caches login details in
+access or **API key** sign-in for usage-based access. Codex cloud requires ChatGPT sign-in, while
+the Codex CLI supports either sign-in method. The Codex CLI caches login details in
 `~/.codex/auth.json` (or your OS credential store), which Clawdbot can reuse.
 
 ## Option A: OpenAI API key (OpenAI Platform)

docs/providers/signal.md

@@ -9,6 +9,26 @@ read_when:
 
 Status: external CLI integration. Gateway talks to `signal-cli` over HTTP JSON-RPC + SSE.
 
+## Quick setup (beginner)
+1) Use a **separate Signal number** for the bot (recommended).
+2) Install `signal-cli` (Java required).
+3) Link the bot device and start the daemon:
+   - `signal-cli link -n "Clawdbot"`
+4) Configure Clawdbot and start the gateway.
+
+Minimal config:
+```json5
+{
+  signal: {
+    enabled: true,
+    account: "+15551234567",
+    cliPath: "signal-cli",
+    dmPolicy: "pairing",
+    allowFrom: ["+15557654321"]
+  }
+}
+```
+
 ## What it is
 - Signal provider via `signal-cli` (not embedded libsignal).
 - Deterministic routing: replies always go back to Signal.

docs/providers/slack.md

@@ -5,6 +5,22 @@ read_when: "Setting up Slack or debugging Slack socket mode"
 
 # Slack (socket mode)
 
+## Quick setup (beginner)
+1) Create a Slack app and enable **Socket Mode**.
+2) Create an **App Token** (`xapp-...`) and **Bot Token** (`xoxb-...`).
+3) Set tokens for Clawdbot and start the gateway.
+
+Minimal config:
+```json5
+{
+  slack: {
+    enabled: true,
+    appToken: "xapp-...",
+    botToken: "xoxb-..."
+  }
+}
+```
+
 ## Setup
 1) Create a Slack app (From scratch) in https://api.slack.com/apps.
 2) **Socket Mode** → toggle on. Then go to **Basic Information** → **App-Level Tokens** → **Generate Token and Scopes** with scope `connections:write`. Copy the **App Token** (`xapp-...`).
@@ -24,6 +40,24 @@ Use the manifest below so scopes and events stay in sync.
 
 Multi-account support: use `slack.accounts` with per-account tokens and optional `name`. See [`gateway/configuration`](/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts) for the shared pattern.
 
+## Clawdbot config (minimal)
+
+Set tokens via env vars (recommended):
+- `SLACK_APP_TOKEN=xapp-...`
+- `SLACK_BOT_TOKEN=xoxb-...`
+
+Or via config:
+
+```json5
+{
+  slack: {
+    enabled: true,
+    appToken: "xapp-...",
+    botToken: "xoxb-..."
+  }
+}
+```
+
 ## History context
 - `slack.historyLimit` (or `slack.accounts.*.historyLimit`) controls how many recent channel/group messages are wrapped into the prompt.
 - Falls back to `messages.groupChat.historyLimit`. Set `0` to disable (default 50).

docs/providers/telegram.md

@@ -8,6 +8,25 @@ read_when:
 
 Status: production-ready for bot DMs + groups via grammY. Long-polling by default; webhook optional.
 
+## Quick setup (beginner)
+1) Create a bot with **@BotFather** and copy the token.
+2) Set the token:
+   - Env: `TELEGRAM_BOT_TOKEN=...`
+   - Or config: `telegram.botToken: "..."`.
+3) Start the gateway.
+4) DM access is pairing by default; approve the pairing code on first contact.
+
+Minimal config:
+```json5
+{
+  telegram: {
+    enabled: true,
+    botToken: "123:abc",
+    dmPolicy: "pairing"
+  }
+}
+```
+
 ## What it is
 - A Telegram Bot API provider owned by the Gateway.
 - Deterministic routing: replies go back to Telegram; the model never chooses providers.
@@ -37,9 +56,11 @@ Example:
 }
 ```
 
+Env option: `TELEGRAM_BOT_TOKEN=...` (works for the default account).
+
 Multi-account support: use `telegram.accounts` with per-account tokens and optional `name`. See [`gateway/configuration`](/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts) for the shared pattern.
 
-3) Start the gateway. Telegram starts when a `telegram` config section exists and a token is resolved.
+3) Start the gateway. Telegram starts when a token is resolved (env or config).
 4) DM access defaults to pairing. Approve the code when the bot is first contacted.
 5) For groups: add the bot, decide privacy/admin behavior (below), then set `telegram.groups` to control mention gating + allowlists.
 

docs/providers/whatsapp.md

@@ -8,6 +8,22 @@ read_when:
 
 Status: WhatsApp Web via Baileys only. Gateway owns the session(s).
 
+## Quick setup (beginner)
+1) Use a **separate phone number** if possible (recommended).
+2) Configure WhatsApp in `~/.clawdbot/clawdbot.json`.
+3) Run `clawdbot providers login` to scan the QR code (Linked Devices).
+4) Start the gateway.
+
+Minimal config:
+```json5
+{
+  whatsapp: {
+    dmPolicy: "allowlist",
+    allowFrom: ["+15551234567"]
+  }
+}
+```
+
 ## Goals
 - Multiple WhatsApp accounts (multi-account) in one Gateway process.
 - Deterministic routing: replies return to WhatsApp, no model routing.

docs/start/hubs.md

@@ -58,7 +58,8 @@ Use these hubs to discover every page, including deep dives and reference docs t
 
 ## Providers + ingress
 
-- [Model providers hub](/providers)
+- [Chat providers hub](/providers)
+- [Model providers hub](/providers/models)
 - [WhatsApp](/providers/whatsapp)
 - [Telegram](/providers/telegram)
 - [Telegram (grammY notes)](/providers/grammy)

docs/web/webchat.md

@@ -13,6 +13,11 @@ Status: the macOS/iOS SwiftUI chat UI talks directly to the Gateway WebSocket.
 - Uses the same sessions and routing rules as other providers.
 - Deterministic routing: replies always go back to WebChat.
 
+## Quick start
+1) Start the gateway.
+2) Open the WebChat UI (macOS/iOS app) or the Control UI chat tab.
+3) Ensure gateway auth is configured if you are not on loopback.
+
 ## How it works (behavior)
 - The UI connects to the Gateway WebSocket and uses `chat.history` + `chat.send`.
 - History is always fetched from the gateway (no local file watching).