docs: add /help hub and Node/npm PATH guide

CHANGELOG.md

@@ -32,6 +32,7 @@
 - Cron: isolated cron jobs now start a fresh session id on every run to prevent context buildup.
 - Daemon: share profile/state-dir resolution across service helpers and honor `CLAWDBOT_STATE_DIR` for Windows task scripts.
 - Docs: clarify multi-gateway rescue bot guidance. (#969) — thanks @bjesuiter.
+- Docs: add `/help` hub, Node/npm PATH sanity guide, and installer PATH warnings (for “installed but command not found” setups). (#861)
 - Agents: add Current Date & Time system prompt section with configurable time format (auto/12/24).
 - Agents: default to no narration for routine tool calls. (#1008) — thanks @cpojer.
 - Tools: normalize Slack/Discord message timestamps with `timestampMs`/`timestampUtc` while keeping raw provider fields.

docs/docs.json

@@ -733,6 +733,14 @@
       "source": "/wizard",
       "destination": "/start/wizard"
     },
+    {
+      "source": "/start/faq",
+      "destination": "/help"
+    },
+    {
+      "source": "/start/faq/",
+      "destination": "/help"
+    },
     {
       "source": "/oauth",
       "destination": "/concepts/oauth"
@@ -752,7 +760,6 @@
           "start/wizard",
           "start/setup",
           "start/pairing",
-          "start/faq",
           "start/clawd",
           "start/showcase",
           "start/hubs",
@@ -760,10 +767,19 @@
           "start/lore"
         ]
       },
+      {
+        "group": "Help",
+        "pages": [
+          "help/index",
+          "help/troubleshooting",
+          "help/faq"
+        ]
+      },
       {
         "group": "Install & Updates",
         "pages": [
           "install/index",
+          "install/node",
           "install/installer",
           "install/updating",
           "install/uninstall",

docs/gateway/authentication.md

@@ -44,7 +44,7 @@ clawdbot doctor
 If you’d rather not manage env vars yourself, the onboarding wizard can store
 API keys for daemon use: `clawdbot onboard`.
 
-See [/start/faq](/start/faq) for details on env inheritance (`env.shellEnv`,
+See [Help](/help) for details on env inheritance (`env.shellEnv`,
 `~/.clawdbot/.env`, systemd/launchd).
 
 ## Anthropic: Claude Code CLI setup-token (supported)

docs/help/faq.md

@@ -0,0 +1,32 @@
+---
+summary: "FAQ (concepts): what Clawdbot is and how it fits together"
+read_when:
+  - You’re new and want the mental model
+  - You’re not debugging a specific error
+---
+
+# FAQ (concepts)
+
+If you’re here because something’s broken, start with: [Troubleshooting](/help/troubleshooting).
+
+## What is Clawdbot?
+
+Clawdbot is a personal AI assistant you run on your own devices. It replies on the messaging surfaces you already use (WhatsApp, Telegram, Slack, Discord, Signal, iMessage, WebChat) and can also do voice + a live Canvas on supported platforms. The **Gateway** is the always‑on control plane; the assistant is the product.
+
+## What runtime do I need?
+
+Node **>= 22** is required. `pnpm` is recommended. Bun is **not recommended** for the Gateway.
+
+## What’s the recommended setup flow?
+
+Use the onboarding wizard:
+
+```bash
+clawdbot onboard --install-daemon
+```
+
+Then use:
+
+```bash
+clawdbot dashboard
+```

docs/help/index.md

@@ -0,0 +1,20 @@
+---
+summary: "Help hub: common fixes, install sanity, and where to look when something breaks"
+read_when:
+  - You’re new and want the “what do I click/run” guide
+  - Something broke and you want the fastest path to a fix
+---
+
+# Help
+
+If you want a quick “get unstuck” flow, start here:
+
+- **Troubleshooting:** [Start here](/help/troubleshooting)
+- **Install sanity (Node/npm/PATH):** [Node.js + npm (PATH sanity)](/install/node)
+- **Gateway issues:** [Gateway troubleshooting](/gateway/troubleshooting)
+- **Logs:** [Logging](/logging) and [Gateway logging](/gateway/logging)
+- **Repairs:** [Doctor](/gateway/doctor)
+
+If you’re looking for conceptual questions (not “something broke”):
+
+- [FAQ (concepts)](/help/faq)

docs/help/troubleshooting.md

@@ -0,0 +1,59 @@
+---
+summary: "Troubleshooting hub: symptoms → checks → fixes"
+read_when:
+  - You see an error and want the fix path
+  - The installer says “success” but the CLI doesn’t work
+---
+
+# Troubleshooting
+
+## First 60 seconds
+
+Run these in order:
+
+```bash
+clawdbot status
+clawdbot status --all
+clawdbot daemon status
+clawdbot logs --follow
+clawdbot doctor
+```
+
+If the gateway is reachable, deep probes:
+
+```bash
+clawdbot status --deep
+```
+
+## Common “it broke” cases
+
+### `clawdbot: command not found`
+
+Almost always a Node/npm PATH issue. Start here:
+
+- [Node.js + npm (PATH sanity)](/install/node)
+
+### Gateway “unauthorized”, can’t connect, or keeps reconnecting
+
+- [Gateway troubleshooting](/gateway/troubleshooting)
+- [Gateway authentication](/gateway/authentication)
+
+### Daemon says running, but RPC probe fails
+
+- [Gateway troubleshooting](/gateway/troubleshooting)
+- [Background process / daemon](/gateway/background-process)
+
+### Model/auth failures (rate limit, billing, “all models failed”)
+
+- [Models](/cli/models)
+- [OAuth / auth concepts](/concepts/oauth)
+
+### When filing an issue
+
+Paste a safe report:
+
+```bash
+clawdbot status --all
+```
+
+If you can, include the relevant log tail from `clawdbot logs --follow`.

docs/index.md

@@ -165,7 +165,7 @@ Example:
 
 - Start here:
   - [Docs hubs (all pages linked)](/start/hubs)
-  - [FAQ](/start/faq) ← *common questions answered*
+  - [Help](/help) ← *common fixes + troubleshooting*
   - [Configuration](/gateway/configuration)
   - [Configuration examples](/gateway/configuration-examples)
   - [Slash commands](/tools/slash-commands)

docs/install/index.md

@@ -9,6 +9,8 @@ read_when:
 
 Runtime baseline: **Node >=22**.
 
+If the installer says it succeeded but you later see `clawdbot: command not found`, it’s usually a Node/npm PATH issue. See: [Node.js + npm (PATH sanity)](/install/node).
+
 ## Recommended (installer script)
 
 ```bash

docs/install/installer.md

@@ -19,6 +19,8 @@ To see the current flags/behavior, run:
 curl -fsSL https://clawd.bot/install.sh | bash -s -- --help
 ```
 
+If the installer completes but `clawdbot` is not found in a new terminal, it’s usually a Node/npm PATH issue. See: [Node.js + npm (PATH sanity)](/install/node).
+
 ## install.sh (recommended)
 
 What it does (high level):

docs/install/node.md

@@ -0,0 +1,74 @@
+---
+summary: "Node.js + npm install sanity: versions, PATH, and global installs"
+read_when:
+  - You installed Clawdbot but `clawdbot` is “command not found”
+  - You’re setting up Node.js/npm on a new machine
+  - `npm install -g ...` fails with permissions or PATH issues
+---
+
+# Node.js + npm (PATH sanity)
+
+Clawdbot’s runtime baseline is **Node 22+**.
+
+If you can run `npm install -g clawdbot@latest` but later see `clawdbot: command not found`, it’s almost always a **PATH** issue: the directory where npm puts global binaries isn’t on your shell’s PATH.
+
+## Quick diagnosis
+
+Run:
+
+```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: put npm’s global bin dir on PATH
+
+1) Find your global bin directory:
+
+```bash
+npm bin -g
+```
+
+2) Add it to your shell startup file:
+
+- zsh: `~/.zshrc`
+- bash: `~/.bashrc`
+
+Example (replace the path with your `npm bin -g` output):
+
+```bash
+export PATH="/path/from/npm/bin/-g:$PATH"
+```
+
+Then open a **new terminal** (or run `rehash` in zsh / `hash -r` in bash).
+
+## Fix: avoid `sudo npm install -g` / permission errors (Linux)
+
+If `npm install -g ...` fails with `EACCES`, switch npm’s global prefix to a user-writable directory:
+
+```bash
+mkdir -p "$HOME/.npm-global"
+npm config set prefix "$HOME/.npm-global"
+export PATH="$HOME/.npm-global/bin:$PATH"
+```
+
+Persist the `export PATH=...` line in your shell startup file.
+
+## Recommended Node install options
+
+You’ll have the fewest surprises if Node/npm are installed in a way that:
+
+- keeps Node updated (22+)
+- makes `npm bin -g` stable and on PATH in new shells
+
+Common choices:
+
+- macOS: Homebrew (`brew install node`) or a version manager
+- Linux: your preferred version manager, or a distro-supported install that provides Node 22+
+- Windows: official Node installer, `winget`, or a Windows Node version manager
+
+If you use a version manager (nvm/fnm/asdf/etc), ensure it’s initialized in the shell you use day-to-day (zsh vs bash) so the PATH it sets is present when you run installers.

docs/platforms/exe-dev.md

@@ -99,7 +99,7 @@ It can set up:
 - model provider config/login
 - Linux systemd **user** service (daemon)
 
-If you’re doing OAuth on a headless VM: do OAuth on a normal machine first, then copy the auth profile to the VM (see [FAQ](/start/faq)).
+If you’re doing OAuth on a headless VM: do OAuth on a normal machine first, then copy the auth profile to the VM (see [Help](/help)).
 
 ## 5) Remote access options
 

docs/start/hubs.md

@@ -15,7 +15,7 @@ Use these hubs to discover every page, including deep dives and reference docs t
 - [Wizard](/start/wizard)
 - [Setup](/start/setup)
 - [Dashboard (local Gateway)](http://127.0.0.1:18789/)
-- [FAQ](/start/faq)
+- [Help](/help)
 - [Configuration](/gateway/configuration)
 - [Configuration examples](/gateway/configuration-examples)
 - [Clawdbot assistant (Clawd)](/start/clawd)