From ad8b7c739b8887416e72bcfaaa43b52c542dcd04 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Thu, 8 Jan 2026 00:13:10 +0000
Subject: [PATCH] docs: tighten onboarding pairing + UI fallback

---
 docs/start/faq.md             | 9 +++++++++
 docs/start/getting-started.md | 9 ++++++---
 docs/start/wizard.md          | 5 +++--
 3 files changed, 18 insertions(+), 5 deletions(-)

diff --git a/docs/start/faq.md b/docs/start/faq.md
index e2849ad02..8ea19e7de 100644
--- a/docs/start/faq.md
+++ b/docs/start/faq.md
@@ -87,6 +87,15 @@ 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
diff --git a/docs/start/getting-started.md b/docs/start/getting-started.md
index c9b96b0c7..947ad135d 100644
--- a/docs/start/getting-started.md
+++ b/docs/start/getting-started.md
@@ -42,14 +42,14 @@ Note: Bun is optional if you prefer running TypeScript directly:
 bun install
 ```
 
-## 2) Build the Control UI (recommended)
+## 2) Control UI (auto + fallback)
 
 The Gateway serves the browser dashboard (Control UI) when assets exist.
+The wizard tries to build these for you. If it fails, run:
 
 ```bash
 pnpm ui:install
 pnpm ui:build
-pnpm build
 ```
 
 If you skip UI build, the gateway still works — you just won’t get the dashboard.
@@ -63,7 +63,7 @@ pnpm clawdbot onboard
 What you’ll choose:
 - **Local vs Remote** gateway
 - **Auth**: Anthropic OAuth or OpenAI OAuth (recommended), API key (optional), or skip for now
-- **Providers**: WhatsApp QR login, bot tokens, etc.
+- **Providers**: WhatsApp QR login, Telegram/Discord bot tokens, etc.
 - **Daemon**: optional background install (launchd/systemd; WSL2 uses systemd)
   - **Runtime**: Node (recommended; required for WhatsApp) or Bun (faster, but incompatible with WhatsApp)
 
@@ -112,9 +112,12 @@ The wizard can write tokens/config for you. If you prefer manual config, start w
 - Telegram: [Telegram](/providers/telegram)
 - Discord: [Discord](/providers/discord)
 
+**Telegram DM tip:** your first DM returns a pairing code. Approve it (see next step) or the bot won’t respond.
+
 ## 6) DM safety (pairing approvals)
 
 Default posture: unknown DMs get a short code and messages are not processed until approved.
+If your first DM gets no reply, approve the pairing:
 
 Approve:
 
diff --git a/docs/start/wizard.md b/docs/start/wizard.md
index 66eb8f190..0a558e9f6 100644
--- a/docs/start/wizard.md
+++ b/docs/start/wizard.md
@@ -79,7 +79,7 @@ clawdbot agents add <name>
    - Discord: bot token.
    - Signal: optional `signal-cli` install + account config.
    - iMessage: local `imsg` CLI path + DB access.
-   - DM security: default is pairing (unknown DMs get a pairing code). Approve via `clawdbot pairing approve --provider <provider> <code>`.
+  - DM security: default is pairing. First DM sends a code; approve via `clawdbot pairing approve --provider <provider> <code>` or use allowlists.
 
 6) **Daemon install**
    - macOS: LaunchAgent
@@ -99,7 +99,8 @@ clawdbot agents add <name>
 
 9) **Finish**
    - Summary + next steps, including iOS/Android/macOS apps for extra features.
-   - If no GUI is detected, the wizard prints SSH port-forward instructions for the Control UI instead of opening a browser.
+  - If no GUI is detected, the wizard prints SSH port-forward instructions for the Control UI instead of opening a browser.
+  - If the Control UI assets are missing, the wizard attempts to build them; fallback is `pnpm ui:install && pnpm ui:build`.
 
 ## Remote mode