diff --git a/docs/cli/index.md b/docs/cli/index.md
new file mode 100644
index 000000000..8e1bf6e22
--- /dev/null
+++ b/docs/cli/index.md
@@ -0,0 +1,533 @@
+---
+summary: "CLI reference for clawdbot commands, subcommands, and options"
+read_when:
+  - Adding or modifying CLI commands or options
+  - Documenting new command surfaces
+---
+
+# CLI reference
+
+This page mirrors `src/cli/*` and is the source of truth for CLI behavior.
+If you change the CLI code, update this doc.
+
+## Global flags
+
+- `--dev`: isolate state under `~/.clawdbot-dev` and shift default ports.
+- `--profile <name>`: isolate state under `~/.clawdbot-<name>`.
+- `-V`, `--version`, `-v`: print version and exit.
+
+## Command tree
+
+```
+clawdbot [--dev] [--profile <name>] <command>
+  setup
+  onboard
+  configure (alias: config)
+  update
+  doctor
+  login
+  logout
+  send
+  poll
+  agent
+  status
+  health
+  sessions
+  gateway
+    call
+    health
+    status
+    wake
+    send
+    agent
+    stop
+    restart
+  gateway-daemon
+  models
+    list
+    status
+    set
+    set-image
+    aliases list|add|remove
+    fallbacks list|add|remove|clear
+    image-fallbacks list|add|remove|clear
+    scan
+  wake
+  cron
+    status
+    list
+    add
+    edit
+    rm
+    enable
+    disable
+    runs
+    run
+  nodes
+    status
+    describe
+    list
+    pending
+    approve
+    reject
+    rename
+    invoke
+    run
+    notify
+    camera list|snap|clip
+    canvas snapshot
+    screen record
+    location get
+  canvas
+    snapshot
+    present
+    hide
+    navigate
+    eval
+    a2ui push|reset
+  browser
+    status
+    start
+    stop
+    reset-profile
+    tabs
+    open
+    focus
+    close
+    profiles
+    create-profile
+    delete-profile
+    screenshot
+    snapshot
+    navigate
+    resize
+    click
+    type
+    press
+    hover
+    drag
+    select
+    upload
+    fill
+    dialog
+    wait
+    evaluate
+    console
+    pdf
+  hooks
+    gmail setup|run
+  pairing
+    list
+    approve
+  telegram
+    pairing list|approve
+  docs
+  dns
+    setup
+  tui
+```
+
+## Setup + onboarding
+
+### `setup`
+Initialize config + workspace.
+
+Options:
+- `--workspace <dir>`: agent workspace path (default `~/clawd`).
+- `--wizard`: run the onboarding wizard.
+- `--non-interactive`: run wizard without prompts.
+- `--mode <local|remote>`: wizard mode.
+- `--remote-url <url>`: remote Gateway URL.
+- `--remote-token <token>`: remote Gateway token.
+
+### `onboard`
+Interactive wizard to set up gateway, workspace, and skills.
+
+Options:
+- `--workspace <dir>`
+- `--non-interactive`
+- `--mode <local|remote>`
+- `--auth-choice <oauth|apiKey|minimax|skip>`
+- `--anthropic-api-key <key>`
+- `--gateway-port <port>`
+- `--gateway-bind <loopback|lan|tailnet|auto>`
+- `--gateway-auth <off|token|password>`
+- `--gateway-token <token>`
+- `--gateway-password <password>`
+- `--remote-url <url>`
+- `--remote-token <token>`
+- `--tailscale <off|serve|funnel>`
+- `--tailscale-reset-on-exit`
+- `--install-daemon`
+- `--daemon-runtime <node|bun>`
+- `--skip-skills`
+- `--skip-health`
+- `--node-manager <npm|pnpm|bun>`
+- `--json`
+
+### `configure` / `config`
+Interactive configuration wizard (models, providers, skills, gateway).
+
+### `update`
+Audit and modernize the local configuration.
+
+### `doctor`
+Health checks + quick fixes.
+
+Options:
+- `--no-workspace-suggestions`: disable workspace memory hints.
+
+## Auth + provider helpers
+
+### `login`
+Link a WhatsApp Web account via QR.
+
+Options:
+- `--verbose`
+- `--provider <provider>` (default `whatsapp`)
+- `--account <id>`
+
+### `logout`
+Clear cached WhatsApp Web credentials.
+
+Options:
+- `--provider <provider>`
+- `--account <id>`
+
+### `pairing`
+Approve DM pairing requests across providers.
+
+Subcommands:
+- `pairing list --provider <telegram|signal|imessage|discord|slack|whatsapp> [--json]`
+- `pairing approve --provider <...> <code> [--notify]`
+
+### `telegram pairing`
+Telegram-only pairing helper.
+
+Subcommands:
+- `telegram pairing list [--json]`
+- `telegram pairing approve <code> [--no-notify]`
+
+### `hooks gmail`
+Gmail Pub/Sub hook setup + runner. See [/automation/gmail-pubsub](/automation/gmail-pubsub).
+
+Subcommands:
+- `hooks gmail setup` (requires `--account <email>`; supports `--project`, `--topic`, `--subscription`, `--label`, `--hook-url`, `--hook-token`, `--push-token`, `--bind`, `--port`, `--path`, `--include-body`, `--max-bytes`, `--renew-minutes`, `--tailscale`, `--tailscale-path`, `--push-endpoint`, `--json`)
+- `hooks gmail run` (runtime overrides for the same flags)
+
+### `dns setup`
+Wide-area discovery DNS helper (CoreDNS + Tailscale). See [/gateway/discovery](/gateway/discovery).
+
+Options:
+- `--apply`: install/update CoreDNS config (requires sudo; macOS only).
+
+## Messaging + agent
+
+### `send`
+Send a message through a provider.
+
+Required:
+- `--to <dest>`
+- `--message <text>`
+
+Options:
+- `--media <path-or-url>`
+- `--gif-playback`
+- `--provider <whatsapp|telegram|discord|slack|signal|imessage>`
+- `--account <id>` (WhatsApp)
+- `--dry-run`
+- `--json`
+- `--verbose`
+
+### `poll`
+Create a poll (WhatsApp or Discord).
+
+Required:
+- `--to <id>`
+- `--question <text>`
+- `--option <choice>` (repeat 2-12 times)
+
+Options:
+- `--max-selections <n>`
+- `--duration-hours <n>` (Discord)
+- `--provider <whatsapp|discord>`
+- `--dry-run`
+- `--json`
+- `--verbose`
+
+### `agent`
+Run one agent turn via the Gateway (or `--local` embedded).
+
+Required:
+- `--message <text>`
+
+Options:
+- `--to <dest>` (for session key and optional delivery)
+- `--session-id <id>`
+- `--thinking <off|minimal|low|medium|high>`
+- `--verbose <on|off>`
+- `--provider <whatsapp|telegram|discord|slack|signal|imessage>`
+- `--local`
+- `--deliver`
+- `--json`
+- `--timeout <seconds>`
+
+### `status`
+Show linked session health and recent recipients.
+
+Options:
+- `--json`
+- `--deep` (probe providers)
+- `--timeout <ms>`
+- `--verbose`
+
+### `health`
+Fetch health from the running Gateway.
+
+Options:
+- `--json`
+- `--timeout <ms>`
+- `--verbose`
+
+### `sessions`
+List stored conversation sessions.
+
+Options:
+- `--json`
+- `--verbose`
+- `--store <path>`
+- `--active <minutes>`
+
+## Gateway
+
+### `gateway`
+Run the WebSocket Gateway.
+
+Options:
+- `--port <port>`
+- `--bind <loopback|tailnet|lan|auto>`
+- `--token <token>`
+- `--auth <token|password>`
+- `--password <password>`
+- `--tailscale <off|serve|funnel>`
+- `--tailscale-reset-on-exit`
+- `--allow-unconfigured`
+- `--force` (kill existing listener on port)
+- `--verbose`
+- `--ws-log <auto|full|compact>`
+- `--compact` (alias for `--ws-log compact`)
+
+### `gateway-daemon`
+Run the Gateway as a long-lived daemon (same options as `gateway`, minus `--allow-unconfigured` and `--force`).
+
+### `gateway <subcommand>`
+Gateway RPC helpers (use `--url`, `--token`, `--password`, `--timeout`, `--expect-final` for each).
+
+Subcommands:
+- `gateway call <method> [--params <json>]`
+- `gateway health`
+- `gateway status`
+- `gateway wake --text <text> [--mode now|next-heartbeat]`
+- `gateway send --to <jidOrPhone> --message <text> [--media-url <url>] [--gif-playback] [--idempotency-key <key>]`
+- `gateway agent --message <text> [--to <jidOrPhone>] [--session-id <id>] [--thinking <level>] [--deliver] [--timeout-seconds <n>] [--idempotency-key <key>]`
+- `gateway stop`
+- `gateway restart`
+
+## Models
+
+See [/concepts/models](/concepts/models) for fallback behavior and scanning strategy.
+
+### `models` (root)
+`clawdbot models` is an alias for `models status`.
+
+### `models list`
+Options:
+- `--all`
+- `--local`
+- `--provider <name>`
+- `--json`
+- `--plain`
+
+### `models status`
+Options:
+- `--json`
+- `--plain`
+
+### `models set <model>`
+Set `agent.model.primary`.
+
+### `models set-image <model>`
+Set `agent.imageModel.primary`.
+
+### `models aliases list|add|remove`
+Options:
+- `list`: `--json`, `--plain`
+- `add <alias> <model>`
+- `remove <alias>`
+
+### `models fallbacks list|add|remove|clear`
+Options:
+- `list`: `--json`, `--plain`
+- `add <model>`
+- `remove <model>`
+- `clear`
+
+### `models image-fallbacks list|add|remove|clear`
+Options:
+- `list`: `--json`, `--plain`
+- `add <model>`
+- `remove <model>`
+- `clear`
+
+### `models scan`
+Options:
+- `--min-params <b>`
+- `--max-age-days <days>`
+- `--provider <name>`
+- `--max-candidates <n>`
+- `--timeout <ms>`
+- `--concurrency <n>`
+- `--yes`
+- `--no-input`
+- `--set-default`
+- `--set-image`
+- `--json`
+
+## Cron + wake
+
+### `wake`
+Enqueue a system event and optionally trigger a heartbeat (Gateway RPC).
+
+Required:
+- `--text <text>`
+
+Options:
+- `--mode <now|next-heartbeat>`
+- `--json`
+- `--url`, `--token`, `--timeout`, `--expect-final`
+
+### `cron`
+Manage scheduled jobs (Gateway RPC). See [/automation/cron-jobs](/automation/cron-jobs).
+
+Subcommands:
+- `cron status [--json]`
+- `cron list [--all] [--json]`
+- `cron add` (requires `--name` and exactly one of `--at` | `--every` | `--cron`, and exactly one payload of `--system-event` | `--message`)
+- `cron edit <id>` (patch fields)
+- `cron rm <id>`
+- `cron enable <id>`
+- `cron disable <id>`
+- `cron runs --id <id> [--limit <n>]`
+- `cron run <id> [--force]`
+
+All `cron` commands accept `--url`, `--token`, `--timeout`, `--expect-final`.
+
+## Nodes
+
+`nodes` talks to the Gateway and targets paired nodes. See [/nodes](/nodes).
+
+Common options:
+- `--url`, `--token`, `--timeout`, `--json`
+
+Subcommands:
+- `nodes status`
+- `nodes describe --node <id|name|ip>`
+- `nodes list`
+- `nodes pending`
+- `nodes approve <requestId>`
+- `nodes reject <requestId>`
+- `nodes rename --node <id|name|ip> --name <displayName>`
+- `nodes invoke --node <id|name|ip> --command <command> [--params <json>] [--invoke-timeout <ms>] [--idempotency-key <key>]`
+- `nodes run --node <id|name|ip> [--cwd <path>] [--env KEY=VAL] [--command-timeout <ms>] [--needs-screen-recording] [--invoke-timeout <ms>] <command...>` (mac only)
+- `nodes notify --node <id|name|ip> [--title <text>] [--body <text>] [--sound <name>] [--priority <passive|active|timeSensitive>] [--delivery <system|overlay|auto>] [--invoke-timeout <ms>]` (mac only)
+
+Camera:
+- `nodes camera list --node <id|name|ip>`
+- `nodes camera snap --node <id|name|ip> [--facing front|back|both] [--device-id <id>] [--max-width <px>] [--quality <0-1>] [--delay-ms <ms>] [--invoke-timeout <ms>]`
+- `nodes camera clip --node <id|name|ip> [--facing front|back] [--device-id <id>] [--duration <ms|10s|1m>] [--no-audio] [--invoke-timeout <ms>]`
+
+Canvas + screen:
+- `nodes canvas snapshot --node <id|name|ip> [--format png|jpg|jpeg] [--max-width <px>] [--quality <0-1>] [--invoke-timeout <ms>]`
+- `nodes screen record --node <id|name|ip> [--screen <index>] [--duration <ms|10s>] [--fps <n>] [--no-audio] [--out <path>] [--invoke-timeout <ms>]`
+
+Location:
+- `nodes location get --node <id|name|ip> [--max-age <ms>] [--accuracy <coarse|balanced|precise>] [--location-timeout <ms>] [--invoke-timeout <ms>]`
+
+## Canvas
+
+Canvas RPC helper (top-level wrapper for `node.invoke`). See [/platforms/mac/canvas](/platforms/mac/canvas).
+
+Common options:
+- `--url`, `--token`, `--timeout`, `--json`
+
+Subcommands:
+- `canvas snapshot [--node <id|name|ip>] [--format png|jpg] [--max-width <px>] [--quality <0-1>]`
+- `canvas present [--node <id|name|ip>] [--target <urlOrPath>] [--x <px>] [--y <px>] [--width <px>] [--height <px>]`
+- `canvas hide [--node <id|name|ip>]`
+- `canvas navigate <url> [--node <id|name|ip>]`
+- `canvas eval [<js>] [--js <code>] [--node <id|name|ip>]`
+- `canvas a2ui push (--jsonl <path> | --text <text>) [--node <id|name|ip>]`
+- `canvas a2ui reset [--node <id|name|ip>]`
+
+## Browser
+
+Browser control CLI (dedicated Chrome/Chromium). See [/tools/browser](/tools/browser).
+
+Common options:
+- `--url <controlUrl>`
+- `--browser-profile <name>`
+- `--json`
+
+Manage:
+- `browser status`
+- `browser start`
+- `browser stop`
+- `browser reset-profile`
+- `browser tabs`
+- `browser open <url>`
+- `browser focus <targetId>`
+- `browser close [targetId]`
+- `browser profiles`
+- `browser create-profile --name <name> [--color <hex>] [--cdp-url <url>]`
+- `browser delete-profile --name <name>`
+
+Inspect:
+- `browser screenshot [targetId] [--full-page] [--ref <ref>] [--element <selector>] [--type png|jpeg]`
+- `browser snapshot [--format aria|ai] [--target-id <id>] [--limit <n>] [--out <path>]`
+
+Actions:
+- `browser navigate <url> [--target-id <id>]`
+- `browser resize <width> <height> [--target-id <id>]`
+- `browser click <ref> [--double] [--button <left|right|middle>] [--modifiers <csv>] [--target-id <id>]`
+- `browser type <ref> <text> [--submit] [--slowly] [--target-id <id>]`
+- `browser press <key> [--target-id <id>]`
+- `browser hover <ref> [--target-id <id>]`
+- `browser drag <startRef> <endRef> [--target-id <id>]`
+- `browser select <ref> <values...> [--target-id <id>]`
+- `browser upload <paths...> [--ref <ref>] [--input-ref <ref>] [--element <selector>] [--target-id <id>] [--timeout-ms <ms>]`
+- `browser fill [--fields <json>] [--fields-file <path>] [--target-id <id>]`
+- `browser dialog --accept|--dismiss [--prompt <text>] [--target-id <id>] [--timeout-ms <ms>]`
+- `browser wait [--time <ms>] [--text <value>] [--text-gone <value>] [--target-id <id>]`
+- `browser evaluate --fn <code> [--ref <ref>] [--target-id <id>]`
+- `browser console [--level <error|warn|info>] [--target-id <id>]`
+- `browser pdf [--target-id <id>]`
+
+## Docs search
+
+### `docs [query...]`
+Search the live docs index.
+
+## TUI
+
+### `tui`
+Open the terminal UI connected to the Gateway.
+
+Options:
+- `--url <url>`
+- `--token <token>`
+- `--password <password>`
+- `--session <key>`
+- `--deliver`
+- `--thinking <level>`
+- `--timeout-ms <ms>`
+- `--history-limit <n>`
diff --git a/docs/concepts/models.md b/docs/concepts/models.md
index c8b720841..64db76e05 100644
--- a/docs/concepts/models.md
+++ b/docs/concepts/models.md
@@ -14,27 +14,35 @@ that prefers tool-call + image-capable models and maintains ordered fallbacks.
 
 ## Model recommendations
 
-Through testing, we’ve found Anthropic Opus 4.5 is the most useful general-purpose model for anything coding-related. We suggest GPT 5.2 Codex for coding and sub-agents. For personal assistant work, nothing comes close to Opus. If you’re going all-in on Claude, we recommend the Max $200 subscription: https://claude.com/pricing
+Through testing, we’ve found [Claude Opus 4.5](https://www.anthropic.com/claude/opus) is the most useful general-purpose model for anything coding-related. We suggest [GPT-5.2-Codex](https://developers.openai.com/codex/models) for coding and sub-agents. For personal assistant work, nothing comes close to Opus. If you’re going all-in on Claude, we recommend the [Claude Max $200 subscription](https://www.anthropic.com/pricing/).
 
-## Command tree (draft)
+## Model discussions (community notes)
 
-- `clawdbot models list`
-  - default: configured models only
-  - flags: `--all` (full catalog), `--local`, `--provider <name>`, `--json`, `--plain`
-- `clawdbot models status`
-  - show default model + aliases + fallbacks + configured models
-- `clawdbot models set <modelOrAlias>`
-  - writes `agent.model.primary` and ensures `agent.models` entry
-- `clawdbot models set-image <modelOrAlias>`
-  - writes `agent.imageModel.primary` and ensures `agent.models` entry
-- `clawdbot models aliases list|add|remove`
-  - writes `agent.models.*.alias`
-- `clawdbot models fallbacks list|add|remove|clear`
-  - writes `agent.model.fallbacks`
-- `clawdbot models image-fallbacks list|add|remove|clear`
-  - writes `agent.imageModel.fallbacks`
-- `clawdbot models scan`
-  - OpenRouter :free scan; probe tool-call + image; interactive selection
+Anecdotal notes from the Discord thread on January 4–5, 2026. Treat as “what people reported,” not guarantees.
+
+**Reported working well**
+- [Claude Opus 4.5](https://www.anthropic.com/claude/opus): best quality, but expensive and easy to hit limits.
+- [Claude Sonnet 4.5](https://www.anthropic.com/claude/sonnet): solid fallback when Opus caps out.
+- [GLM](https://www.zhipuai.cn/en/): used as a worker model under orchestration.
+- [MiniMax M2.1](https://platform.minimax.io/docs/guides/models-intro): “good enough” fallback for grunt tasks.
+- [Gemini 3 Pro](https://deepmind.google/en/models/gemini/pro/): some users said it maps Clawdbot structure well.
+
+**Mixed / unclear**
+- [Antigravity](https://blog.google/technology/ai/google-ai-updates-november-2025/) (Claude Opus access): some reported extra Opus quota, pricing/limits unclear.
+
+**Reported weak in Clawdbot**
+- [GPT-5.2-Codex](https://developers.openai.com/codex/models) inside Clawdbot: considered rough for conversation or assistant tasks.
+- [Grok](https://docs.x.ai/docs/models/grok-4): tried, abandoned.
+
+**Tooling note**
+- [Codex CLI](https://developers.openai.com/codex/cli) felt stronger than embedded use.
+
+**Theme**
+- Token burn feels higher than expected in long sessions; people suspect context buildup + tool outputs. Pruning/compaction helps. Check session logs before blaming providers. See [/concepts/session](/concepts/session) and [/concepts/model-failover](/concepts/model-failover).
+
+## Models CLI
+
+See [/cli](/cli) for the full command tree and CLI flags.
 
 ## Config changes
 
diff --git a/docs/start/hubs.md b/docs/start/hubs.md
index 8a4b073c6..bddfaea85 100644
--- a/docs/start/hubs.md
+++ b/docs/start/hubs.md
@@ -86,6 +86,7 @@ Use these hubs to discover every page, including deep dives and reference docs t
 ## Tools + automation
 
 - [Tools surface](https://docs.clawd.bot/tools)
+- [CLI reference](https://docs.clawd.bot/cli)
 - [Bash tool](https://docs.clawd.bot/tools/bash)
 - [Elevated mode](https://docs.clawd.bot/tools/elevated)
 - [Cron jobs](https://docs.clawd.bot/automation/cron-jobs)