docs: update faq and install guidance

docs/cli/index.md

@@ -257,12 +257,12 @@ Options:
 - `--tailscale-reset-on-exit`
 - `--install-daemon`
 - `--no-install-daemon` (alias: `--skip-daemon`)
-- `--daemon-runtime <node|bun>`
+- `--daemon-runtime <node|bun>` (bun not recommended for WhatsApp/Telegram)
 - `--skip-providers`
 - `--skip-skills`
 - `--skip-health`
 - `--skip-ui`
-- `--node-manager <npm|pnpm|bun>`
+- `--node-manager <npm|pnpm|bun>` (pnpm recommended; bun not recommended for Gateway runtime)
 - `--json`
 
 ### `configure` / `config`
@@ -549,7 +549,7 @@ Notes:
 - `daemon status` supports `--no-probe`, `--deep`, and `--json` for scripting.
 - `daemon status` also surfaces legacy or extra gateway services when it can detect them (`--deep` adds system-level scans). Profile-named Clawdbot services are treated as first-class and aren't flagged as "extra".
 - `daemon status` prints which config path the CLI uses vs which config the daemon likely uses (service env), plus the resolved probe target URL.
-- `daemon install` defaults to Node runtime; use `--runtime bun` only when WhatsApp is disabled.
+- `daemon install` defaults to Node runtime; bun is **not recommended** (WhatsApp/Telegram bugs).
 - `daemon install` options: `--port`, `--runtime`, `--token`, `--force`.
 
 ### `logs`

docs/cli/update.md

@@ -9,7 +9,7 @@ read_when:
 
 Safely update a **source checkout** (git install) of Clawdbot.
 
-If you installed via **npm/pnpm/bun** (global install, no git metadata), use the package manager flow in [Updating](/install/updating).
+If you installed via **npm/pnpm** (global install, no git metadata), use the package manager flow in [Updating](/install/updating).
 
 ## Usage
 
@@ -32,7 +32,7 @@ High-level:
 
 1. Requires a clean worktree (no uncommitted changes).
 2. Fetches and rebases against `@{upstream}`.
-3. Installs deps (pnpm/bun/npm depending on the checkout).
+3. Installs deps (pnpm preferred; npm fallback).
 4. Builds + builds the Control UI.
 5. Runs `clawdbot doctor` as the final “safe update” check.
 

docs/concepts/streaming.md

@@ -92,6 +92,9 @@ This maps to:
 `*.blockStreaming` is explicitly set to `true`. Telegram can stream drafts
 (`telegram.streamMode`) without block replies.
 
+Config location reminder: the `blockStreaming*` defaults live under
+`agents.defaults`, not the root config.
+
 ## Telegram draft streaming (token-ish)
 
 Telegram is the only provider with draft streaming:

docs/gateway/tailscale.md

@@ -73,6 +73,8 @@ clawdbot gateway --tailscale funnel --auth password
 - `tailscale.mode: "funnel"` refuses to start unless auth mode is `password` to avoid public exposure.
 - Set `gateway.tailscale.resetOnExit` if you want Clawdbot to undo `tailscale serve`
   or `tailscale funnel` configuration on shutdown.
+- Serve/Funnel only expose the **Gateway control UI + WS**. Node **bridge** traffic
+  uses the separate bridge port (default `18790`) and is **not** proxied by Serve.
 
 ## Tailscale prerequisites + limits
 

docs/install/bun.md

@@ -1,13 +1,16 @@
 ---
-summary: "Bun workflow (preferred): installs, patches, and gotchas vs pnpm"
+summary: "Bun workflow (experimental): installs, patches, and gotchas vs pnpm"
 read_when:
   - You want the fastest local dev loop (bun + watch)
   - You hit Bun install/patch/lifecycle script issues
 ---
 
-# Bun
+# Bun (experimental)
 
-Goal: run this repo with **Bun** (optional) without losing pnpm patch behavior.
+Goal: run this repo with **Bun** (optional, not recommended for WhatsApp/Telegram)
+without losing pnpm patch behavior.
+
+⚠️ **Not recommended for Gateway runtime** (WhatsApp/Telegram bugs). Use Node for production.
 
 ## Status
 

docs/install/updating.md

@@ -9,9 +9,28 @@ read_when:
 
 Clawdbot is moving fast (pre “1.0”). Treat updates like shipping infra: update → run checks → restart → verify.
 
+## Recommended: re-run the website installer (upgrade in place)
+
+The **preferred** update path is to re-run the installer from the website. It
+detects existing installs, upgrades in place, and runs `clawdbot doctor` when
+needed.
+
+```bash
+curl -fsSL https://clawd.bot/install.sh | bash
+```
+
+Notes:
+- Add `--no-onboard` if you don’t want the onboarding wizard to run again.
+- For **source installs**, use:
+  ```bash
+  curl -fsSL https://clawd.bot/install.sh | bash -s -- --install-method git --no-onboard
+  ```
+  The installer will `git pull --rebase` **only** if the repo is clean.
+- For **global installs**, the script uses `npm install -g clawdbot@latest` under the hood.
+
 ## Before you update
 
-- Know how you installed: **global** (npm/pnpm/bun) vs **from source** (git clone).
+- Know how you installed: **global** (npm/pnpm) vs **from source** (git clone).
 - Know how your Gateway is running: **foreground terminal** vs **supervised service** (launchd/systemd).
 - Snapshot your tailoring:
   - Config: `~/.clawdbot/clawdbot.json`
@@ -29,10 +48,7 @@ npm i -g clawdbot@latest
 ```bash
 pnpm add -g clawdbot@latest
 ```
-
+We do **not** recommend Bun for the Gateway runtime (WhatsApp/Telegram bugs).
-```bash
-bun add -g clawdbot@latest
-```
 
 Then:
 
@@ -59,7 +75,7 @@ It runs a safe-ish update flow:
 - Fetches + rebases against the configured upstream.
 - Installs deps, builds, builds the Control UI, and runs `clawdbot doctor`.
 
-If you installed via **npm/pnpm/bun** (no git metadata), `clawdbot update` will skip. Use “Update (global install)” instead.
+If you installed via **npm/pnpm** (no git metadata), `clawdbot update` will skip. Use “Update (global install)” instead.
 
 ## Update (Control UI / RPC)
 
@@ -93,7 +109,7 @@ pnpm clawdbot health
 
 Notes:
 - `pnpm build` matters when you run the packaged `clawdbot` binary ([`dist/entry.js`](https://github.com/clawdbot/clawdbot/blob/main/dist/entry.js)) or use Node to run `dist/`.
-- If you run directly from TypeScript (`pnpm clawdbot ...` / `bun run clawdbot ...`), a rebuild is usually unnecessary, but **config migrations still apply** → run doctor.
+- If you run directly from TypeScript (`pnpm clawdbot ...`), a rebuild is usually unnecessary, but **config migrations still apply** → run doctor.
 - Switching between global and git installs is easy: install the other flavor, then run `clawdbot doctor` so the gateway service entrypoint is rewritten to the current install.
 
 ## Always run: `clawdbot doctor`
@@ -145,10 +161,6 @@ npm i -g clawdbot@<version>
 pnpm add -g clawdbot@<version>
 ```
 
-```bash
-bun add -g clawdbot@<version>
-```
-
 Tip: to see the current published version, run `npm view clawdbot version`.
 
 Then restart + re-run doctor:

docs/platforms/index.md

@@ -6,7 +6,8 @@ read_when:
 ---
 # Platforms
 
-Clawdbot core is written in TypeScript, so the CLI + Gateway run anywhere Node or Bun runs.
+Clawdbot core is written in TypeScript. **Node is the recommended runtime**.
+Bun is not recommended for the Gateway (WhatsApp/Telegram bugs).
 
 Companion apps exist for macOS (menu bar app) and mobile nodes (iOS/Android). Windows and
 Linux companion apps are planned, but the Gateway is fully supported today.

docs/platforms/linux.md

@@ -6,7 +6,8 @@ read_when:
 ---
 # Linux App
 
-The Gateway is fully supported on Linux. The core is written in TypeScript, so it runs anywhere Node or Bun runs.
+The Gateway is fully supported on Linux. **Node is the recommended runtime**.
+Bun is not recommended for the Gateway (WhatsApp/Telegram bugs).
 
 Native Linux companion apps are planned. Contributions are welcome if you want to help build one.
 
@@ -23,7 +24,7 @@ Step-by-step VPS guide: [exe.dev](/platforms/exe-dev)
 ## Install
 - [Getting Started](/start/getting-started)
 - [Install & updates](/install/updating)
-- Optional flows: [Bun](/install/bun), [Nix](/install/nix), [Docker](/install/docker)
+- Optional flows: [Bun (experimental)](/install/bun), [Nix](/install/nix), [Docker](/install/docker)
 
 ## Gateway
 - [Gateway runbook](/gateway)

docs/platforms/mac/bundled-gateway.md

@@ -20,7 +20,7 @@ You need Node 22+ on the Mac, then install `clawdbot` globally:
 npm install -g clawdbot@<version>
 ```
 
-The macOS app’s **Install CLI** button runs the same flow via npm/pnpm/bun.
+The macOS app’s **Install CLI** button runs the same flow via npm/pnpm (bun not recommended for Gateway runtime).
 
 ## Launchd (Gateway as LaunchAgent)
 

docs/platforms/macos.md

@@ -18,7 +18,7 @@ node.
 - Runs or connects to the Gateway (local or remote).
 - Exposes macOS‑only tools (Canvas, Camera, Screen Recording, `system.run`).
 - Optionally hosts **PeekabooBridge** for UI automation.
-- Installs the global CLI (`clawdbot`) via npm/pnpm/bun on request.
+- Installs the global CLI (`clawdbot`) via npm/pnpm on request (bun not recommended for the Gateway runtime).
 
 ## Local vs remote mode
 

docs/providers/discord.md

@@ -174,6 +174,8 @@ Notes:
   - The bot lacks channel permissions (View/Send/Read History), or
   - Your config requires mentions and you didn’t mention it, or
   - Your guild/channel allowlist denies the channel/user.
+- **`requireMention: false` but still no replies**:
+  - `discord.groupPolicy` defaults to **allowlist**; you must either set it to `"open"` or explicitly list the channel under `discord.guilds.<id>.channels`.
 - **Permission audits** (`providers status --probe`) only check numeric channel IDs. If you use slugs/names as `discord.guilds.*.channels` keys, the audit can’t verify permissions.
 - **DMs don’t work**: `discord.dm.enabled=false`, `discord.dm.policy="disabled"`, or you haven’t been approved yet (`discord.dm.policy="pairing"`).
 

docs/providers/minimax.md

@@ -158,3 +158,24 @@ Use the interactive config wizard to set MiniMax without editing JSON:
 - Update pricing values in `models.json` if you need exact cost tracking.
 - See [/concepts/model-providers](/concepts/model-providers) for provider rules.
 - Use `clawdbot models list` and `clawdbot models set minimax/MiniMax-M2.1` to switch.
+
+## Troubleshooting
+
+### “Unknown model: minimax/MiniMax-M2.1”
+
+This usually means the **MiniMax provider isn’t configured** (no provider entry
+and no MiniMax auth profile/env key found). A fix for this detection is in
+**2026.1.12** (unreleased at the time of writing). Fix by:
+- Upgrading to **2026.1.12** (or run from source `main`), then restarting the gateway.
+- Running `clawdbot configure` and selecting **MiniMax M2.1**, or
+- Adding the `models.providers.minimax` block manually, or
+- Setting `MINIMAX_API_KEY` (or a MiniMax auth profile) so the provider can be injected.
+
+Make sure the model id is **case‑sensitive**:
+- `minimax/MiniMax-M2.1`
+- `minimax/MiniMax-M2.1-lightning`
+
+Then recheck with:
+```bash
+clawdbot models list
+```

docs/providers/whatsapp.md

@@ -310,4 +310,5 @@ WhatsApp can automatically send emoji reactions to incoming messages immediately
 - Fix: `clawdbot doctor` (or restart the gateway). If it persists, relink via `providers login` and inspect `clawdbot logs --follow`.
 
 **Bun runtime**
-- WhatsApp uses Baileys; run the gateway with **Node** for WhatsApp. (See Getting Started runtime note.)
+- Bun is **not recommended**. WhatsApp (Baileys) and Telegram are unreliable on Bun.
+  Run the gateway with **Node**. (See Getting Started runtime note.)

docs/start/faq.md

@@ -27,11 +27,13 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
   - [Can I run a "fast chat" agent and an "Opus for coding" agent?](#can-i-run-a-fast-chat-agent-and-an-opus-for-coding-agent)
   - [Does Homebrew work on Linux?](#does-homebrew-work-on-linux)
   - [Can I switch between npm and git installs later?](#can-i-switch-between-npm-and-git-installs-later)
+  - [Should I run the Gateway on my laptop or a VPS?](#should-i-run-the-gateway-on-my-laptop-or-a-vps)
 - [Skills and automation](#skills-and-automation)
   - [How do I customize skills without keeping the repo dirty?](#how-do-i-customize-skills-without-keeping-the-repo-dirty)
   - [Can I load skills from a custom folder?](#can-i-load-skills-from-a-custom-folder)
   - [How can I use different models for different tasks?](#how-can-i-use-different-models-for-different-tasks)
   - [How do I install skills on Linux?](#how-do-i-install-skills-on-linux)
+  - [Do you have a Notion or HeyGen integration?](#do-you-have-a-notion-or-heygen-integration)
 - [Sandboxing and memory](#sandboxing-and-memory)
   - [Is there a dedicated sandboxing doc?](#is-there-a-dedicated-sandboxing-doc)
   - [How do I bind a host folder into the sandbox?](#how-do-i-bind-a-host-folder-into-the-sandbox)
@@ -39,6 +41,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
   - [Does semantic memory search require an OpenAI API key?](#does-semantic-memory-search-require-an-openai-api-key)
 - [Where things live on disk](#where-things-live-on-disk)
   - [Where does Clawdbot store its data?](#where-does-clawdbot-store-its-data)
+  - [Where should AGENTS.md / SOUL.md / USER.md / MEMORY.md live?](#where-should-agentsmd--soulmd--usermd--memorymd-live)
   - [How do I completely uninstall Clawdbot?](#how-do-i-completely-uninstall-clawdbot)
   - [Can agents work outside the workspace?](#can-agents-work-outside-the-workspace)
   - [I’m in remote mode — where is the session store?](#im-in-remote-mode-where-is-the-session-store)
@@ -54,12 +57,16 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
   - [Do nodes run a gateway daemon?](#do-nodes-run-a-gateway-daemon)
   - [Is there an API / RPC way to apply config?](#is-there-an-api-rpc-way-to-apply-config)
   - [What’s a minimal “sane” config for a first install?](#whats-a-minimal-sane-config-for-a-first-install)
+  - [How do I set up Tailscale on a VPS and connect from my Mac?](#how-do-i-set-up-tailscale-on-a-vps-and-connect-from-my-mac)
+  - [How do I connect a Mac node to a remote Gateway (Tailscale Serve)?](#how-do-i-connect-a-mac-node-to-a-remote-gateway-tailscale-serve)
 - [Env vars and .env loading](#env-vars-and-env-loading)
   - [How does Clawdbot load environment variables?](#how-does-clawdbot-load-environment-variables)
   - [“I started the Gateway via a daemon and my env vars disappeared.” What now?](#i-started-the-gateway-via-a-daemon-and-my-env-vars-disappeared-what-now)
+  - [I set `COPILOT_GITHUB_TOKEN`, but models status shows “Shell env: off.” Why?](#i-set-copilot_github_token-but-models-status-shows-shell-env-off-why)
 - [Sessions & multiple chats](#sessions-multiple-chats)
   - [How do I start a fresh conversation?](#how-do-i-start-a-fresh-conversation)
   - [How do I completely reset Clawdbot (but keep it installed)?](#how-do-i-completely-reset-clawdbot-but-keep-it-installed)
+  - [I’m getting “context too large” errors — how do I reset or compact?](#im-getting-context-too-large-errors-how-do-i-reset-or-compact)
   - [Do I need to add a “bot account” to a WhatsApp group?](#do-i-need-to-add-a-bot-account-to-a-whatsapp-group)
   - [Why doesn’t Clawdbot reply in a group?](#why-doesnt-clawdbot-reply-in-a-group)
   - [Do groups/threads share context with DMs?](#do-groupsthreads-share-context-with-dms)
@@ -67,6 +74,8 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
   - [What is the “default model”?](#what-is-the-default-model)
   - [How do I switch models on the fly (without restarting)?](#how-do-i-switch-models-on-the-fly-without-restarting)
   - [Why do I see “Model … is not allowed” and then no reply?](#why-do-i-see-model-is-not-allowed-and-then-no-reply)
+  - [Why do I see “Unknown model: minimax/MiniMax-M2.1”?](#why-do-i-see-unknown-model-minimaxminimax-m21)
+  - [Can I use MiniMax as my default and OpenAI for complex tasks?](#can-i-use-minimax-as-my-default-and-openai-for-complex-tasks)
   - [Are opus / sonnet / gpt built‑in shortcuts?](#are-opus-sonnet-gpt-builtin-shortcuts)
   - [How do I define/override model shortcuts (aliases)?](#how-do-i-defineoverride-model-shortcuts-aliases)
   - [How do I add models from other providers like OpenRouter or Z.AI?](#how-do-i-add-models-from-other-providers-like-openrouter-or-zai)
@@ -89,6 +98,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
   - [The Control UI says “unauthorized” (or keeps reconnecting). What now?](#the-control-ui-says-unauthorized-or-keeps-reconnecting-what-now)
   - [I set `gateway.bind: "tailnet"` but it can’t bind / nothing listens](#i-set-gatewaybind-tailnet-but-it-cant-bind-nothing-listens)
   - [Can I run multiple Gateways on the same host?](#can-i-run-multiple-gateways-on-the-same-host)
+  - [What does “invalid handshake” / code 1008 mean?](#what-does-invalid-handshake--code-1008-mean)
 - [Logging and debugging](#logging-and-debugging)
   - [Where are logs?](#where-are-logs)
   - [How do I start/stop/restart the Gateway daemon?](#how-do-i-startstoprestart-the-gateway-daemon)
@@ -106,6 +116,11 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
   - [I’m running on my personal WhatsApp number — why is self-chat weird?](#im-running-on-my-personal-whatsapp-number-why-is-self-chat-weird)
   - [WhatsApp logged me out. How do I re‑auth?](#whatsapp-logged-me-out-how-do-i-reauth)
   - [Build errors on `main` — what’s the standard fix path?](#build-errors-on-main-whats-the-standard-fix-path)
+  - [npm install fails (allow-build-scripts / missing tar or yargs). What now?](#npm-install-fails-allow-build-scripts--missing-tar-or-yargs-what-now)
+  - [How do I switch between git installs and npm installs?](#how-do-i-switch-between-git-installs-and-npm-installs)
+  - [Telegram block streaming isn’t splitting text between tool calls. Why?](#telegram-block-streaming-isnt-splitting-text-between-tool-calls-why)
+  - [Discord doesn’t reply in my server even with `requireMention: false`. Why?](#discord-doesnt-reply-in-my-server-even-with-requiremention-false-why)
+  - [Cloud Code Assist API error: invalid tool schema (400). What now?](#cloud-code-assist-api-error-invalid-tool-schema-400-what-now)
 
 ## First 60 seconds if something's broken
 
@@ -205,7 +220,7 @@ See [Dashboard](/web/dashboard) and [Web surfaces](/web) for bind modes and auth
 
 ### What runtime do I need?
 
-Node **>= 22** is required. `pnpm` is recommended; `bun` is optional.
+Node **>= 22** is required. `pnpm` is recommended. Bun is **not recommended** for the Gateway.
 
 ### What does the onboarding wizard actually do?
 
@@ -228,6 +243,8 @@ The wizard can run `claude setup-token` on the gateway host (or you run it yours
 
 Yes. Clawdbot can **reuse Claude Code CLI credentials** (OAuth) and also supports **setup-token**. If you have a Claude subscription, we recommend **setup-token** on the gateway host for the most reliable long‑running setup (requires Claude Pro/Max + the `claude` CLI). OAuth reuse is supported, but avoid logging in separately via Clawdbot and Claude Code to prevent token conflicts. See [Anthropic](/providers/anthropic) and [OAuth](/concepts/oauth).
 
+Note: Claude subscription access is governed by Anthropic’s terms. For production or multi‑user workloads, API keys are usually the safer choice.
+
 ### Is AWS Bedrock supported?
 
 Yes — via pi‑ai’s **Amazon Bedrock (Converse)** provider with **manual config**. You must supply AWS credentials/region on the gateway host and add a Bedrock provider entry in your models config. See [Amazon Bedrock](/bedrock) and [Model providers](/providers/models). If you prefer a managed key flow, an OpenAI‑compatible proxy in front of Bedrock is still a valid option.
@@ -246,7 +263,11 @@ Pick region-pinned endpoints. OpenRouter exposes US-hosted options for MiniMax,
 
 ### 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.
+Bun is **not recommended**. We see runtime bugs, especially with WhatsApp and Telegram.
+Use **Node** for stable gateways.
+
+If you still want to experiment with Bun, do it on a non‑production gateway
+without WhatsApp/Telegram.
 
 ### Telegram: what goes in `allowFrom`?
 
@@ -298,6 +319,23 @@ clawdbot daemon restart
 
 Doctor detects a gateway service entrypoint mismatch and offers to rewrite the service config to match the current install (use `--repair` in automation).
 
+### Should I run the Gateway on my laptop or a VPS?
+
+Short answer: **if you want 24/7 reliability, use a VPS**. If you want the
+lowest friction and you’re okay with sleep/restarts, run it locally.
+
+**Laptop (local Gateway)**
+- **Pros:** no server cost, direct access to local files, live browser window.
+- **Cons:** sleep/network drops = disconnects, OS updates/reboots interrupt, must stay awake.
+
+**VPS / cloud**
+- **Pros:** always‑on, stable network, no laptop sleep issues, easier to keep running.
+- **Cons:** often run headless (use screenshots), remote file access only, you must SSH for updates.
+
+**Clawdbot‑specific note:** WhatsApp/Telegram/Slack/Discord all work fine from a VPS. The only real trade‑off is **headless browser** vs a visible window. See [Browser](/tools/browser).
+
+**Recommended default:** VPS if you had gateway disconnects before. Local is great when you’re actively using the Mac and want local file access or UI automation with a visible browser.
+
 ## Skills and automation
 
 ### How do I customize skills without keeping the repo dirty?
@@ -320,6 +358,7 @@ See [Cron jobs](/automation/cron-jobs), [Multi-Agent Routing](/concepts/multi-ag
 ### How do I install skills on Linux?
 
 Use **ClawdHub** (CLI) or drop skills into your workspace. The macOS Skills UI isn’t available on Linux.
+Browse skills at https://clawdhub.com.
 
 Install the ClawdHub CLI (pick one package manager):
 
@@ -331,9 +370,20 @@ npm i -g clawdhub
 pnpm add -g clawdhub
 ```
 
-```bash
+### Do you have a Notion or HeyGen integration?
-bun add -g clawdhub
+
-```
+Not built‑in today.
+
+Options:
+- **Custom skill / plugin:** best for reliable API access (Notion/HeyGen both have APIs).
+- **Browser automation:** works without code but is slower and more fragile.
+
+If you want to keep context per client (agency workflows), a simple pattern is:
+- One Notion page per client (context + preferences + active work).
+- Ask the agent to fetch that page at the start of a session.
+
+If you want a native integration, open a feature request or build a skill
+targeting those APIs.
 
 Install skills:
 
@@ -396,6 +446,29 @@ Legacy single‑agent path: `~/.clawdbot/agent/*` (migrated by `clawdbot doctor`
 
 Your **workspace** (AGENTS.md, memory files, skills, etc.) is separate and configured via `agents.defaults.workspace` (default: `~/clawd`).
 
+### Where should AGENTS.md / SOUL.md / USER.md / MEMORY.md live?
+
+These files live in the **agent workspace**, not `~/.clawdbot`.
+
+- **Workspace (per agent)**: `AGENTS.md`, `SOUL.md`, `IDENTITY.md`, `USER.md`,
+  `MEMORY.md` (or `memory.md`), `memory/YYYY-MM-DD.md`, optional `HEARTBEAT.md`.
+- **State dir (`~/.clawdbot`)**: config, credentials, auth profiles, sessions, logs,
+  and shared skills (`~/.clawdbot/skills`).
+
+Default workspace is `~/clawd`, configurable via:
+
+```json5
+{
+  agents: { defaults: { workspace: "~/clawd" } }
+}
+```
+
+If the bot “forgets” after a restart, confirm the Gateway is using the same
+workspace on every launch (and remember: remote mode uses the **gateway host’s**
+workspace, not your local laptop).
+
+See [Agent workspace](/concepts/agent-workspace) and [Memory](/concepts/memory).
+
 ### How do I completely uninstall Clawdbot?
 
 See the dedicated guide: [Uninstall](/install/uninstall).
@@ -500,6 +573,11 @@ Yes. It’s a config option:
 
 Default is `false` (headful). Headless is more likely to trigger anti‑bot checks on some sites. See [Browser](/tools/browser).
 
+Headless uses the **same Chromium engine** and works for most automation (forms, clicks, scraping, logins). The main differences:
+- No visible browser window (use screenshots if you need visuals).
+- Some sites are stricter about automation in headless mode (CAPTCHAs, anti‑bot).
+  For example, X/Twitter often blocks headless sessions.
+
 ## Remote gateways + nodes
 
 ### How do commands propagate between Telegram, the gateway, and nodes?
@@ -533,6 +611,52 @@ Yes. `config.apply` validates + writes the full config and restarts the Gateway
 
 This sets your workspace and restricts who can trigger the bot.
 
+### How do I set up Tailscale on a VPS and connect from my Mac?
+
+Minimal steps:
+
+1) **Install + login on the VPS**
+   ```bash
+   curl -fsSL https://tailscale.com/install.sh | sh
+   sudo tailscale up
+   ```
+2) **Install + login on your Mac**
+   - Use the Tailscale app and sign in to the same tailnet.
+3) **Enable MagicDNS (recommended)**
+   - In the Tailscale admin console, enable MagicDNS so the VPS has a stable name.
+4) **Use the tailnet hostname**
+   - SSH: `ssh user@your-vps.tailnet-xxxx.ts.net`
+   - Gateway WS: `ws://your-vps.tailnet-xxxx.ts.net:18789`
+
+If you want the Control UI without SSH, use Tailscale Serve on the VPS:
+```bash
+clawdbot gateway --tailscale serve
+```
+This keeps the gateway bound to loopback and exposes HTTPS via Tailscale. See [Tailscale](/gateway/tailscale).
+
+### How do I connect a Mac node to a remote Gateway (Tailscale Serve)?
+
+Serve only exposes the **Gateway Control UI**. Nodes use the **bridge port**.
+
+Recommended setup:
+1) **Enable the bridge on the gateway host**:
+   ```json5
+   {
+     bridge: { enabled: true, bind: "auto" }
+   }
+   ```
+   `auto` prefers a tailnet IP when Tailscale is present.
+2) **Make sure the VPS + Mac are on the same tailnet**.
+3) **Use the macOS app in Remote mode** (SSH target can be the tailnet hostname).
+   The app will tunnel the bridge port and connect as a node.
+4) **Approve the node** on the gateway:
+   ```bash
+   clawdbot nodes pending
+   clawdbot nodes approve <requestId>
+   ```
+
+Docs: [Bridge protocol](/gateway/bridge-protocol), [Discovery](/gateway/discovery), [macOS remote mode](/platforms/mac/remote).
+
 ## Env vars and .env loading
 
 ### How does Clawdbot load environment variables?
@@ -578,6 +702,30 @@ Two common fixes:
 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`.
 
+### I set `COPILOT_GITHUB_TOKEN`, but models status shows “Shell env: off.” Why?
+
+`clawdbot models status` reports whether **shell env import** is enabled. “Shell env: off”
+does **not** mean your env vars are missing — it just means Clawdbot won’t load
+your login shell automatically.
+
+If the Gateway runs as a daemon (launchd/systemd), it won’t inherit your shell
+environment. Fix by doing one of these:
+
+1) Put the token in `~/.clawdbot/.env`:
+   ```
+   COPILOT_GITHUB_TOKEN=...
+   ```
+2) Or enable shell import (`env.shellEnv.enabled: true`).
+3) Or add it to your config `env` block (applies only if missing).
+
+Then restart the gateway and recheck:
+```bash
+clawdbot models status
+```
+
+Copilot tokens are read from `COPILOT_GITHUB_TOKEN` (also `GH_TOKEN` / `GITHUB_TOKEN`).
+See [/concepts/model-providers](/concepts/model-providers) and [/environment](/environment).
+
 ## Sessions & multiple chats
 
 ### How do I start a fresh conversation?
@@ -609,6 +757,28 @@ Notes:
 - If you used profiles (`--profile` / `CLAWDBOT_PROFILE`), reset each state dir (defaults are `~/.clawdbot-<profile>`).
 - Dev reset: `clawdbot gateway --dev --reset` (dev-only; wipes dev config + credentials + sessions + workspace).
 
+### I’m getting “context too large” errors — how do I reset or compact?
+
+Use one of these:
+
+- **Compact** (keeps the conversation but summarizes older turns):
+  ```
+  /compact
+  ```
+  or `/compact <instructions>` to guide the summary.
+
+- **Reset** (fresh session ID for the same chat key):
+  ```
+  /new
+  /reset
+  ```
+
+If it keeps happening:
+- Enable or tune **session pruning** (`agents.defaults.contextPruning`) to trim old tool output.
+- Use a model with a larger context window.
+
+Docs: [Compaction](/concepts/compaction), [Session pruning](/concepts/session-pruning), [Session management](/concepts/session).
+
 ### Do I need to add a “bot account” to a WhatsApp group?
 
 No. Clawdbot runs on **your own account**, so if you’re in the group, Clawdbot can see it.
@@ -693,6 +863,59 @@ Model "provider/model" is not allowed. Use /model to list available models.
 That error is returned **instead of** a normal reply. Fix: add the model to
 `agents.defaults.models`, remove the allowlist, or pick a model from `/model list`.
 
+### Why do I see “Unknown model: minimax/MiniMax-M2.1”?
+
+This means the **provider isn’t configured** (no MiniMax provider config or auth
+profile was found), so the model can’t be resolved. A fix for this detection is
+in **2026.1.12** (unreleased at the time of writing).
+
+Fix checklist:
+1) Upgrade to **2026.1.12** (or run from source `main`), then restart the gateway.
+2) Make sure MiniMax is configured (wizard or JSON), or that a MiniMax API key
+   exists in env/auth profiles so the provider can be injected.
+3) Use the exact model id (case‑sensitive): `minimax/MiniMax-M2.1` or
+   `minimax/MiniMax-M2.1-lightning`.
+4) Run:
+   ```bash
+   clawdbot models list
+   ```
+   and pick from the list (or `/model list` in chat).
+
+See [MiniMax](/providers/minimax) and [Models](/concepts/models).
+
+### Can I use MiniMax as my default and OpenAI for complex tasks?
+
+Yes. Use **MiniMax as the default** and switch models **per session** when needed.
+Fallbacks are for **errors**, not “hard tasks,” so use `/model` or a separate agent.
+
+**Option A: switch per session**
+```json5
+{
+  env: { MINIMAX_API_KEY: "sk-...", OPENAI_API_KEY: "sk-..." },
+  agents: {
+    defaults: {
+      model: { primary: "minimax/MiniMax-M2.1" },
+      models: {
+        "minimax/MiniMax-M2.1": { alias: "minimax" },
+        "openai/gpt-5.2": { alias: "gpt" }
+      }
+    }
+  }
+}
+```
+
+Then:
+```
+/model gpt
+```
+
+**Option B: separate agents**
+- Agent A default: MiniMax
+- Agent B default: OpenAI
+- Route by agent or use `/agent` to switch
+
+Docs: [Models](/concepts/models), [Multi-Agent Routing](/concepts/multi-agent), [MiniMax](/providers/minimax), [OpenAI](/providers/openai).
+
 ### Are opus / sonnet / gpt built‑in shortcuts?
 
 Yes. Clawdbot ships a few default shorthands (only applied when the model exists in `agents.defaults.models`):
@@ -932,6 +1155,8 @@ Fix:
 Fix:
 - Start Tailscale on that host (so it has a 100.x address), or
 - Switch to `gateway.bind: "loopback"` / `"lan"`.
+  
+Note: `tailnet` is legacy and is migrated to `auto` by Doctor. Prefer `gateway.bind: "auto"` when using Tailscale.
 
 ### Can I run multiple Gateways on the same host?
 
@@ -951,6 +1176,29 @@ Quick setup (recommended):
 
 Profiles also suffix service names (`com.clawdbot.<profile>`, `clawdbot-gateway-<profile>.service`, `Clawdbot Gateway (<profile>)`).
 
+### What does “invalid handshake” / code 1008 mean?
+
+The Gateway is a **WebSocket server**, and it expects the very first message to
+be a `connect` frame. If it receives anything else, it closes the connection
+with **code 1008** (policy violation).
+
+Common causes:
+- You opened the **HTTP** URL in a browser (`http://...`) instead of a WS client.
+- You used the wrong port or path.
+- A proxy or tunnel stripped auth headers or sent a non‑Gateway request.
+
+Quick fixes:
+1) Use the WS URL: `ws://<host>:18789` (or `wss://...` if HTTPS).
+2) Don’t open the WS port in a normal browser tab.
+3) If auth is on, include the token/password in the `connect` frame.
+
+If you’re using the CLI or TUI, the URL should look like:
+```
+clawdbot tui --url ws://<host>:18789 --token <token>
+```
+
+Protocol details: [Gateway protocol](/gateway/protocol).
+
 ## Logging and debugging
 
 ### Where are logs?
@@ -1115,6 +1363,94 @@ clawdbot providers login
 3) Check GitHub issues or Discord
 4) Temporary workaround: check out an older commit
 
+### npm install fails (allow-build-scripts / missing tar or yargs). What now?
+
+If you’re running from source, use the repo’s package manager: **pnpm** (preferred).
+The repo declares `packageManager: "pnpm@…"`, and pnpm patches are tracked in `pnpm.patchedDependencies`.
+
+Typical recovery:
+```bash
+git status   # ensure you’re in the repo root
+pnpm install
+pnpm build
+pnpm clawdbot doctor
+clawdbot daemon restart
+```
+
+Why: pnpm is the configured package manager for this repo, and the dependency
+patching workflow relies on it.
+
+### How do I switch between git installs and npm installs?
+
+Use the **website installer** and select the install method with a flag. It
+upgrades in place and rewrites the gateway service to point at the new install.
+
+Switch **to git install**:
+```bash
+curl -fsSL https://clawd.bot/install.sh | bash -s -- --install-method git --no-onboard
+```
+
+Switch **to npm global**:
+```bash
+curl -fsSL https://clawd.bot/install.sh | bash
+```
+
+Notes:
+- The git flow only rebases if the repo is clean. Commit or stash changes first.
+- After switching, run:
+  ```bash
+  clawdbot doctor
+  clawdbot daemon restart
+  ```
+
+### Telegram block streaming isn’t splitting text between tool calls. Why?
+
+Block streaming only sends **completed text blocks**. Common reasons you see a single message:
+- `agents.defaults.blockStreamingDefault` is still `"off"`.
+- `telegram.blockStreaming` is set to `false`.
+- `telegram.streamMode` is `partial` or `block` **and draft streaming is active**
+  (private chat + topics). Draft streaming disables block streaming in that case.
+- Your `minChars` / coalesce settings are too high, so chunks get merged.
+- The model emits one large text block (no mid‑reply flush points).
+
+Fix checklist:
+1) Put block streaming settings under `agents.defaults`, not the root.
+2) Set `telegram.streamMode: "off"` if you want real multi‑message block replies.
+3) Use smaller chunk/coalesce thresholds while debugging.
+
+See [Streaming](/concepts/streaming).
+
+### Discord doesn’t reply in my server even with `requireMention: false`. Why?
+
+`requireMention` only controls mention‑gating **after** the channel passes allowlists.
+By default `discord.groupPolicy` is **allowlist**, so guild channels must be explicitly enabled.
+
+Fix checklist:
+1) Set `discord.groupPolicy: "open"` **or** add the guild/channel allowlist.
+2) Use **numeric channel IDs** in `discord.guilds.<guildId>.channels`.
+3) Ensure the bot has **Message Content Intent** and channel permissions.
+4) Run `clawdbot providers status --probe` for audit hints.
+
+Docs: [Discord](/providers/discord), [Providers troubleshooting](/providers/troubleshooting).
+
+### Cloud Code Assist API error: invalid tool schema (400). What now?
+
+This is almost always a **tool schema compatibility** issue. The Cloud Code Assist
+endpoint accepts a strict subset of JSON Schema. Clawdbot scrubs/normalizes tool
+schemas in current `main`, but the fix is not in the last release yet (as of
+January 13, 2026).
+
+Fix checklist:
+1) **Update Clawdbot**:
+   - If you can run from source, pull `main` and restart the gateway.
+   - Otherwise, wait for the next release that includes the schema scrubber.
+2) Avoid unsupported keywords like `anyOf/oneOf/allOf`, `patternProperties`,
+   `additionalProperties`, `minLength`, `maxLength`, `format`, etc.
+3) If you define custom tools, keep the top‑level schema as `type: "object"` with
+   `properties` and simple enums.
+
+See [Tools](/tools) and [TypeBox schemas](/concepts/typebox).
+
 ## Answer the exact question from the screenshot/chat log
 
 **Q: “What’s the default model for Anthropic with an API key?”**

docs/start/getting-started.md

@@ -79,7 +79,7 @@ What you’ll choose:
 - **Auth**: OpenAI Code (Codex) subscription (OAuth) or API keys. For Anthropic we recommend an API key; `claude setup-token` is also supported.
 - **Providers**: WhatsApp QR login, Telegram/Discord bot tokens, etc.
 - **Daemon**: background install (launchd/systemd; WSL2 uses systemd)
-  - **Runtime**: Node (recommended; required for WhatsApp) or Bun (faster, but incompatible with WhatsApp)
+  - **Runtime**: Node (recommended; required for WhatsApp/Telegram). Bun is **not recommended**.
 - **Gateway token**: the wizard generates one by default (even on loopback) and stores it in `gateway.auth.token`.
 
 Wizard doc: [Wizard](/start/wizard)
@@ -110,11 +110,8 @@ clawdbot gateway --port 18789 --verbose
 Dashboard (local loopback): `http://127.0.0.1:18789/`
 If a token is configured, paste it into the Control UI settings (stored as `connect.params.auth.token`).
 
-⚠️ **WhatsApp + Bun warning:** Baileys (WhatsApp Web library) uses a WebSocket
+⚠️ **Bun warning (WhatsApp + Telegram):** Bun has known issues with these
-path that is currently incompatible with Bun and can cause memory corruption on
+providers. If you use WhatsApp or Telegram, run the Gateway with **Node**.
-reconnect. If you use WhatsApp, run the Gateway with **Node** until this is
-resolved. Baileys: https://github.com/WhiskeySockets/Baileys · Bun issue:
-https://github.com/oven-sh/bun/issues/5951
 
 ## 4) Pair + connect your first chat surface
 

docs/start/hubs.md

@@ -27,7 +27,7 @@ Use these hubs to discover every page, including deep dives and reference docs t
 - [Docker](/install/docker)
 - [Nix](/install/nix)
 - [Updating / rollback](/install/updating)
-- [Bun workflow](/install/bun)
+- [Bun workflow (experimental)](/install/bun)
 
 ## Core concepts
 

docs/start/onboarding.md

@@ -64,7 +64,7 @@ Onboarding requests TCC permissions needed for:
 
 ## 5) CLI (optional)
 
-The app can install the global `clawdbot` CLI via npm/pnpm/bun so terminal
+The app can install the global `clawdbot` CLI via npm/pnpm so terminal
 workflows and launchd tasks work out of the box.
 
 ## 6) Onboarding chat (dedicated session)

docs/start/wizard.md

@@ -119,7 +119,7 @@ Tip: `--json` does **not** imply non-interactive mode. Use `--non-interactive` (
    - Linux (and Windows via WSL2): systemd user unit
      - Wizard attempts to enable lingering via `loginctl enable-linger <user>` so the Gateway stays up after logout.
      - May prompt for sudo (writes `/var/lib/systemd/linger`); it tries without sudo first.
-   - **Runtime selection:** Node (recommended; required for WhatsApp) or Bun (faster, but incompatible with WhatsApp).
+   - **Runtime selection:** Node (recommended; required for WhatsApp/Telegram). Bun is **not recommended**.
 
 7) **Health check**
    - Starts the Gateway (if needed) and runs `clawdbot health`.
@@ -127,7 +127,7 @@ Tip: `--json` does **not** imply non-interactive mode. Use `--non-interactive` (
 
 8) **Skills (recommended)**
    - Reads the available skills and checks requirements.
-   - Lets you choose a node manager: **npm / pnpm / bun**.
+   - Lets you choose a node manager: **npm / pnpm** (bun not recommended).
    - Installs optional dependencies (some use Homebrew on macOS).
 
 9) **Finish**

docs/tools/clawdhub.md

@@ -42,10 +42,6 @@ npm i -g clawdhub
 pnpm add -g clawdhub
 ```
 
-```bash
-bun add -g clawdhub
-```
-
 ## How it fits into Clawdbot
 
 By default, the CLI installs skills into `./skills` under your current working directory. If a Clawdbot workspace is configured, `clawdhub` falls back to that workspace unless you override `--workdir` (or `CLAWDHUB_WORKDIR`). Clawdbot loads workspace skills from `<workspace>/skills` and will pick them up in the **next** session. If you already use `~/.clawdbot/skills` or bundled skills, workspace skills take precedence.

docs/tools/skills-config.md

@@ -20,7 +20,7 @@ All skills-related configuration lives under `skills` in `~/.clawdbot/clawdbot.j
     },
     install: {
       preferBrew: true,
-      nodeManager: "npm" // npm | pnpm | yarn | bun
+      nodeManager: "npm" // npm | pnpm | yarn | bun (Gateway runtime still Node; bun not recommended)
     },
     entries: {
       "nano-banana-pro": {
@@ -44,6 +44,8 @@ All skills-related configuration lives under `skills` in `~/.clawdbot/clawdbot.j
 - `load.extraDirs`: additional skill directories to scan (lowest precedence).
 - `install.preferBrew`: prefer brew installers when available (default: true).
 - `install.nodeManager`: node installer preference (`npm` | `pnpm` | `yarn` | `bun`, default: npm).
+  This only affects **skill installs**; the Gateway runtime should still be Node
+  (Bun not recommended for WhatsApp/Telegram).
 - `entries.<skillKey>`: per-skill overrides.
 
 Per-skill fields:

docs/tools/skills.md

@@ -45,8 +45,9 @@ surface those skills teach.
 
 ## ClawdHub (install + sync)
 
-ClawdHub is the public skills registry for Clawdbot. Use it to discover,
+ClawdHub is the public skills registry for Clawdbot. Browse at
-install, update, and back up skills. Full guide: [ClawdHub](/tools/clawdhub).
+https://clawdhub.com. Use it to discover, install, update, and back up skills.
+Full guide: [ClawdHub](/tools/clawdhub).
 
 Common flows:
 
@@ -117,6 +118,8 @@ metadata: {"clawdbot":{"emoji":"♊️","requires":{"bins":["gemini"]},"install"
 Notes:
 - If multiple installers are listed, the gateway picks a **single** preferred option (brew when available, otherwise node).
 - Node installs honor `skills.install.nodeManager` in `clawdbot.json` (default: npm; options: npm/pnpm/yarn/bun).
+  This only affects **skill installs**; the Gateway runtime should still be Node
+  (Bun is not recommended for WhatsApp/Telegram).
 - Go installs: if `go` is missing and `brew` is available, the gateway installs Go via Homebrew first and sets `GOBIN` to Homebrew’s `bin` when possible.
 
 If no `metadata.clawdbot` is present, the skill is always eligible (unless
@@ -201,6 +204,6 @@ See [Skills config](/tools/skills-config) for the full configuration schema.
 
 ## Looking for more skills?
 
-Browse [ClawdHub](/tools/clawdhub).
+Browse https://clawdhub.com.
 
 ---

docs/web/tui.md

@@ -67,3 +67,6 @@ Use SSH tunneling or Tailscale to reach the Gateway WS.
 ## Notes
 - The TUI shows Gateway chat deltas (`event: chat`) and agent tool events.
 - It registers as a Gateway client with `mode: "tui"` for presence and debugging.
+- The TUI uses the **Gateway’s** model/auth config and environment. If a model
+  token works in your shell but not in TUI, put it in `~/.clawdbot/.env` or
+  enable `env.shellEnv.enabled`, then restart the Gateway.