From af31e0d969ff4aa5b67436894a4c0133c314454b Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 16 Jan 2026 23:18:44 +0000
Subject: [PATCH] docs: redirect /install/node to install section

---
 docs/docs.json               |  9 ++++++++-
 docs/help/index.md           |  2 +-
 docs/help/troubleshooting.md |  2 +-
 docs/install/index.md        | 23 ++++++++++++++++++++++-
 docs/install/installer.md    |  2 +-
 5 files changed, 33 insertions(+), 5 deletions(-)

diff --git a/docs/docs.json b/docs/docs.json
index 72b776b0a..871d76b90 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -733,6 +733,14 @@
       "source": "/wizard",
       "destination": "/start/wizard"
     },
+    {
+      "source": "/install/node",
+      "destination": "/install#nodejs--npm-path-sanity"
+    },
+    {
+      "source": "/install/node/",
+      "destination": "/install#nodejs--npm-path-sanity"
+    },
     {
       "source": "/start/faq",
       "destination": "/help"
@@ -779,7 +787,6 @@
         "group": "Install & Updates",
         "pages": [
           "install/index",
-          "install/node",
           "install/installer",
           "install/updating",
           "install/uninstall",
diff --git a/docs/help/index.md b/docs/help/index.md
index 5a4193c40..8e386c82d 100644
--- a/docs/help/index.md
+++ b/docs/help/index.md
@@ -10,7 +10,7 @@ read_when:
 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)
+- **Install sanity (Node/npm/PATH):** [Install](/install#nodejs--npm-path-sanity)
 - **Gateway issues:** [Gateway troubleshooting](/gateway/troubleshooting)
 - **Logs:** [Logging](/logging) and [Gateway logging](/gateway/logging)
 - **Repairs:** [Doctor](/gateway/doctor)
diff --git a/docs/help/troubleshooting.md b/docs/help/troubleshooting.md
index 0b4b35789..6d28b7294 100644
--- a/docs/help/troubleshooting.md
+++ b/docs/help/troubleshooting.md
@@ -31,7 +31,7 @@ clawdbot status --deep
 
 Almost always a Node/npm PATH issue. Start here:
 
-- [Node.js + npm (PATH sanity)](/install/node)
+- [Install (Node/npm PATH sanity)](/install#nodejs--npm-path-sanity)
 
 ### Gateway “unauthorized”, can’t connect, or keeps reconnecting
 
diff --git a/docs/install/index.md b/docs/install/index.md
index f2eb6083d..4d90de418 100644
--- a/docs/install/index.md
+++ b/docs/install/index.md
@@ -9,7 +9,28 @@ 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).
+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)
 
diff --git a/docs/install/installer.md b/docs/install/installer.md
index 578a96d67..1778fe464 100644
--- a/docs/install/installer.md
+++ b/docs/install/installer.md
@@ -19,7 +19,7 @@ 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).
+If the installer completes but `clawdbot` is not found in a new terminal, it’s usually a Node/npm PATH issue. See: [Install](/install#nodejs--npm-path-sanity).
 
 ## install.sh (recommended)