refactor: normalize cli command hints

docs/concepts/session.md

@@ -117,8 +117,8 @@ Send these as standalone messages so they register.
 ```
 
 ## Inspecting
-- `pnpm clawdbot status` — shows store path and recent sessions.
-- `pnpm clawdbot sessions --json` — dumps every entry (filter with `--active <minutes>`).
+- `clawdbot status` — shows store path and recent sessions.
+- `clawdbot sessions --json` — dumps every entry (filter with `--active <minutes>`).
 - `clawdbot gateway call sessions.list --params '{}'` — fetch sessions from the running gateway (use `--url`/`--token` for remote gateway access).
 - Send `/status` as a standalone message in chat to see whether the agent is reachable, how much of the session context is used, current thinking/verbose toggles, and when your WhatsApp web creds were last refreshed (helps spot relink needs).
 - Send `/context list` or `/context detail` to see what’s in the system prompt and injected workspace files (and the biggest context contributors).

docs/debug/node-issue.md

@@ -48,7 +48,7 @@ node --import tsx scripts/repro/tsx-name-repro.ts
 
 ## Regression history
 - `2871657e` (2026-01-06): scripts changed from Bun to tsx to make Bun optional.
-- Before that (Bun path), `pnpm clawdbot status` and `gateway:watch` worked.
+- Before that (Bun path), `clawdbot status` and `gateway:watch` worked.
 
 ## Workarounds
 - Use Bun for dev scripts (current temporary revert).

docs/debugging.md

@@ -59,9 +59,11 @@ Recommended flow (dev profile + dev bootstrap):
 
 ```bash
 pnpm gateway:dev
-CLAWDBOT_PROFILE=dev pnpm clawdbot tui
+CLAWDBOT_PROFILE=dev clawdbot tui
 ```
 
+If you don’t have a global install yet, run the CLI via `pnpm clawdbot ...`.
+
 What this does:
 
 1) **Profile isolation** (global `--dev`)
@@ -89,7 +91,7 @@ Note: `--dev` is a **global** profile flag and gets eaten by some runners.
 If you need to spell it out, use the env var form:
 
 ```bash
-CLAWDBOT_PROFILE=dev pnpm clawdbot gateway --dev --reset
+CLAWDBOT_PROFILE=dev clawdbot gateway --dev --reset
 ```
 
 `--reset` wipes config, credentials, sessions, and the dev workspace (using

docs/gateway/troubleshooting.md

@@ -378,7 +378,7 @@ clawdbot channels login
 ### Build errors on `main` — what’s the standard fix path?
 
 1) `git pull origin main && pnpm install`
-2) `pnpm clawdbot doctor`
+2) `clawdbot doctor`
 3) Check GitHub issues or Discord
 4) Temporary workaround: check out an older commit
 
@@ -392,7 +392,7 @@ Typical recovery:
 git status   # ensure you’re in the repo root
 pnpm install
 pnpm build
-pnpm clawdbot doctor
+clawdbot doctor
 clawdbot daemon restart
 ```
 

docs/index.md

@@ -123,9 +123,11 @@ cd clawdbot
 pnpm install
 pnpm ui:build # auto-installs UI deps on first run
 pnpm build
-pnpm clawdbot onboard --install-daemon
+clawdbot onboard --install-daemon
 ```
 
+If you don’t have a global install yet, run the onboarding step via `pnpm clawdbot ...` from the repo.
+
 Multi-instance quickstart (optional):
 
 ```bash

docs/install/index.md

@@ -7,40 +7,43 @@ read_when:
 
 # Install
 
-Runtime baseline: **Node >=22**.
+Use the installer unless you have a reason not to. It sets up the CLI and runs onboarding.
 
-If the installer says it succeeded but you later see `clawdbot: command not found`, it’s usually a Node/npm PATH issue (global npm bin dir not on PATH). See the section below.
-
-## Node.js + npm (PATH sanity)
-
-Quick diagnosis:
-
-```bash
-node -v
-npm -v
-npm bin -g
-echo "$PATH"
-```
-
-If the output of `npm bin -g` is **not** present inside `echo "$PATH"`, your shell can’t find global npm binaries (including `clawdbot`).
-
-Fix: add it to your shell startup file (zsh: `~/.zshrc`, bash: `~/.bashrc`):
-
-```bash
-export PATH="/path/from/npm/bin/-g:$PATH"
-```
-
-Then open a new terminal (or `rehash` in zsh / `hash -r` in bash).
-
-## Recommended (installer script)
+## Quick install (recommended)
 
 ```bash
 curl -fsSL https://clawd.bot/install.sh | bash
 ```
 
-This installs the `clawdbot` CLI globally via npm and then starts onboarding.
+Windows (PowerShell):
 
-See installer flags:
+```powershell
+iwr -useb https://clawd.bot/install.ps1 | iex
+```
+
+Next step (if you skipped onboarding):
+
+```bash
+clawdbot onboard --install-daemon
+```
+
+## System requirements
+
+- **Node >=22**
+- macOS, Linux, or Windows via WSL2
+- `pnpm` only if you build from source
+
+## Choose your install path
+
+### 1) Installer script (recommended)
+
+Installs `clawdbot` globally via npm and runs onboarding.
+
+```bash
+curl -fsSL https://clawd.bot/install.sh | bash
+```
+
+Installer flags:
 
 ```bash
 curl -fsSL https://clawd.bot/install.sh | bash -s -- --help
@@ -54,7 +57,60 @@ Non-interactive (skip onboarding):
 curl -fsSL https://clawd.bot/install.sh | bash -s -- --no-onboard
 ```
 
-## Install method: npm vs git
+### 2) Global install (manual)
+
+If you already have Node:
+
+```bash
+npm install -g clawdbot@latest
+```
+
+If you have libvips installed globally (common on macOS via Homebrew) and `sharp` fails to install, force prebuilt binaries:
+
+```bash
+SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g clawdbot@latest
+```
+
+Or:
+
+```bash
+pnpm add -g clawdbot@latest
+```
+
+Then:
+
+```bash
+clawdbot onboard --install-daemon
+```
+
+### 3) From source (contributors/dev)
+
+```bash
+git clone https://github.com/clawdbot/clawdbot.git
+cd clawdbot
+pnpm install
+pnpm ui:build # auto-installs UI deps on first run
+pnpm build
+clawdbot onboard --install-daemon
+```
+
+Tip: if you don’t have a global install yet, run repo commands via `pnpm clawdbot ...`.
+
+### 4) Other install options
+
+- Docker: [Docker](/install/docker)
+- Nix: [Nix](/install/nix)
+- Ansible: [Ansible](/install/ansible)
+- Bun (CLI only): [Bun](/install/bun)
+
+## After install
+
+- Run onboarding: `clawdbot onboard --install-daemon`
+- Quick check: `clawdbot doctor`
+- Check gateway health: `clawdbot status` + `clawdbot health`
+- Open the dashboard: `clawdbot dashboard`
+
+## Install method: npm vs git (installer)
 
 The installer supports two methods:
 
@@ -92,28 +148,28 @@ Equivalent env vars (useful for automation):
 - `CLAWDBOT_NO_ONBOARD=1`
 - `SHARP_IGNORE_GLOBAL_LIBVIPS=0|1` (default: `1`; avoids `sharp` building against system libvips)
 
-## Global install (manual)
+## Troubleshooting: `clawdbot` not found (PATH)
 
-If you already have Node:
+Quick diagnosis:
 
 ```bash
-npm install -g clawdbot@latest
+node -v
+npm -v
+npm bin -g
+echo "$PATH"
 ```
 
-If you have libvips installed globally (common on macOS via Homebrew) and `sharp` fails to install, force prebuilt binaries:
+If the output of `npm bin -g` is **not** present inside `echo "$PATH"`, your shell can’t find global npm binaries (including `clawdbot`).
+
+Fix: add it to your shell startup file (zsh: `~/.zshrc`, bash: `~/.bashrc`):
 
 ```bash
-SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g clawdbot@latest
+export PATH="/path/from/npm/bin/-g:$PATH"
 ```
 
-Or:
+Then open a new terminal (or `rehash` in zsh / `hash -r` in bash).
 
-```bash
-pnpm add -g clawdbot@latest
-```
+## Update / uninstall
 
-Then:
-
-```bash
-clawdbot onboard --install-daemon
-```
+- Updates: [Updating](/install/updating)
+- Uninstall: [Uninstall](/install/uninstall)

docs/install/uninstall.md

@@ -118,7 +118,7 @@ Remove it with `npm rm -g clawdbot` (or `pnpm remove -g` / `bun remove -g` if yo
 
 ### Source checkout (git clone)
 
-If you run from a repo checkout (`git clone` + `pnpm clawdbot ...` / `bun run clawdbot ...`):
+If you run from a repo checkout (`git clone` + `clawdbot ...` / `bun run clawdbot ...`):
 
 1) Uninstall the gateway service **before** deleting the repo (use the easy path above or manual service removal).
 2) Delete the repo directory.

docs/install/updating.md

@@ -119,12 +119,13 @@ git pull
 pnpm install
 pnpm build
 pnpm ui:build # auto-installs UI deps on first run
-pnpm clawdbot doctor
-pnpm clawdbot health
+clawdbot doctor
+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 from a repo checkout without a global install, use `pnpm clawdbot ...` for CLI commands.
 - 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.
 

docs/platforms/macos.md

@@ -155,7 +155,7 @@ Options:
 - `--timeout <ms>`: overall discovery window (default `2000`)
 - `--json`: structured output for diffing
 
-Tip: compare against `pnpm clawdbot gateway discover --json` to see whether the
+Tip: compare against `clawdbot gateway discover --json` to see whether the
 macOS app’s discovery pipeline (NWBrowser + tailnet DNS‑SD fallback) differs from
 the Node CLI’s `dns-sd` based discovery.
 

docs/platforms/windows.md

@@ -97,7 +97,7 @@ cd clawdbot
 pnpm install
 pnpm ui:build # auto-installs UI deps on first run
 pnpm build
-pnpm clawdbot onboard
+clawdbot onboard
 ```
 
 Full guide: [Getting Started](/start/getting-started)

docs/start/faq.md

@@ -184,22 +184,25 @@ Clawdbot is a personal AI assistant you run on your own devices. It replies on t
 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:build # auto-installs UI deps on first run
-
-pnpm clawdbot onboard
+curl -fsSL https://clawd.bot/install.sh | bash
+clawdbot onboard --install-daemon
 ```
 
 The wizard can also build UI assets automatically. After onboarding, you typically run the Gateway on port **18789**.
 
+From source (contributors/dev):
+
+```bash
+git clone https://github.com/clawdbot/clawdbot.git
+cd clawdbot
+pnpm install
+pnpm build
+pnpm ui:build # auto-installs UI deps on first run
+clawdbot onboard
+```
+
+If you don’t have a global install yet, run it via `pnpm clawdbot onboard`.
+
 ### How do I open the dashboard after onboarding?
 
 The wizard now opens your browser with a tokenized dashboard URL right after onboarding and also prints the full link (with token) in the summary. Keep that tab open; if it didn’t launch, copy/paste the printed URL on the same machine. Tokens stay local to your host—nothing is fetched from the browser.
@@ -330,7 +333,7 @@ git clone https://github.com/clawdbot/clawdbot.git
 cd clawdbot
 pnpm install
 pnpm build
-pnpm clawdbot doctor
+clawdbot doctor
 clawdbot daemon restart
 ```
 

docs/start/getting-started.md

@@ -116,6 +116,13 @@ If a token is configured, paste it into the Control UI settings (stored as `conn
 ⚠️ **Bun warning (WhatsApp + Telegram):** Bun has known issues with these
 channels. If you use WhatsApp or Telegram, run the Gateway with **Node**.
 
+## 3.5) Quick verify (2 min)
+
+```bash
+clawdbot status
+clawdbot health
+```
+
 ## 4) Pair + connect your first chat surface
 
 ### WhatsApp (QR login)
@@ -158,9 +165,11 @@ cd clawdbot
 pnpm install
 pnpm ui:build # auto-installs UI deps on first run
 pnpm build
-pnpm clawdbot onboard --install-daemon
+clawdbot onboard --install-daemon
 ```
 
+If you don’t have a global install yet, run the onboarding step via `pnpm clawdbot ...` from the repo.
+
 Gateway (from this repo):
 
 ```bash
@@ -169,15 +178,13 @@ node dist/entry.js gateway --port 18789 --verbose
 
 ## 7) Verify end-to-end
 
-In a new terminal:
+In a new terminal, send a test message:
 
 ```bash
-clawdbot status
-clawdbot health
 clawdbot message send --target +15555550123 --message "Hello from Clawdbot"
 ```
 
-If `health` shows “no auth configured”, go back to the wizard and set OAuth/key auth — the agent won’t be able to respond without it.
+If `clawdbot health` shows “no auth configured”, go back to the wizard and set OAuth/key auth — the agent won’t be able to respond without it.
 
 Tip: `clawdbot status --all` is the best pasteable, read-only debug report.
 Health probes: `clawdbot health` (or `clawdbot status --deep`) asks the running gateway for a health snapshot.

docs/start/setup.md

@@ -35,9 +35,11 @@ clawdbot setup
 From inside this repo, use the local CLI entry:
 
 ```bash
-pnpm clawdbot setup
+clawdbot setup
 ```
 
+If you don’t have a global install yet, run it via `pnpm clawdbot setup`.
+
 ## Stable workflow (macOS app first)
 
 1) Install + launch **Clawdbot.app** (menu bar).
@@ -92,7 +94,7 @@ The app will attach to the running gateway on the configured port.
 - Or via CLI:
 
 ```bash
-pnpm clawdbot health
+clawdbot health
 ```
 
 ### Common footguns

docs/testing.md

@@ -150,8 +150,8 @@ Live tests are split into two layers so we can isolate failures:
 Tip: to see what you can test on your machine (and the exact `provider/model` ids), run:
 
 ```bash
-pnpm clawdbot models list
-pnpm clawdbot models list --json
+clawdbot models list
+clawdbot models list --json
 ```
 
 ## Live: Anthropic setup-token smoke