From 603f350879f3b78fa81db2b98e10df55d82abffd Mon Sep 17 00:00:00 2001
From: "chenglun.hu" <chenglun.hu@zoom.us>
Date: Wed, 28 Jan 2026 14:08:50 +0800
Subject: [PATCH] docs: clarify moltbot/clawdbot CLI naming fallback
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Fixes #3038

Users hit "command not found: moltbot" after install because docs only
reference `moltbot`, but package.json defines both `moltbot` and `clawdbot`
bins. Some install methods may expose only `clawdbot`.

Changes:
- Add "try clawdbot (compatibility shim)" fallback in 7 key docs
- README, install docs, getting started, troubleshooting
- Consistent messaging: try clawdbot first → then check PATH
- All links follow Mintlify root-relative convention

Reviewed-by: Codex (threadId: 019c0332-8694-7531-b987-a6f795e1a668)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 README.md                     | 9 ++++++++-
 docs/help/troubleshooting.md  | 2 +-
 docs/index.md                 | 1 +
 docs/install/index.md         | 2 ++
 docs/install/installer.md     | 2 +-
 docs/install/node.md          | 2 +-
 docs/start/getting-started.md | 2 ++
 7 files changed, 16 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 7e884be33..c2d15e438 100644
--- a/README.md
+++ b/README.md
@@ -50,7 +50,14 @@ moltbot onboard --install-daemon
 ```
 
 The wizard installs the Gateway daemon (launchd/systemd user service) so it stays running.
-Legacy note: `clawdbot` remains available as a compatibility shim.
+
+Both `moltbot` and `clawdbot` should be available after a correct install. If `moltbot: command not found`, try:
+
+```bash
+clawdbot --version  # fallback compatibility shim
+```
+
+If neither works, see [PATH troubleshooting](https://docs.molt.bot/install/node).
 
 ## Quick start (TL;DR)
 
diff --git a/docs/help/troubleshooting.md b/docs/help/troubleshooting.md
index e681edd9d..07d3e71a1 100644
--- a/docs/help/troubleshooting.md
+++ b/docs/help/troubleshooting.md
@@ -29,7 +29,7 @@ moltbot status --deep
 
 ### `moltbot: command not found`
 
-Almost always a Node/npm PATH issue. Start here:
+First try `clawdbot` (compatibility shim). If that also fails, it's almost always a Node/npm PATH issue. Start here:
 
 - [Install (Node/npm PATH sanity)](/install#nodejs--npm-path-sanity)
 
diff --git a/docs/index.md b/docs/index.md
index 3d85e0eb0..93cce701a 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -106,6 +106,7 @@ npm install -g moltbot@latest
 # or: pnpm add -g moltbot@latest
 
 # Onboard + install the service (launchd/systemd user service)
+# If "moltbot: command not found", try clawdbot (compatibility shim)
 moltbot onboard --install-daemon
 
 # Pair WhatsApp Web (shows QR)
diff --git a/docs/install/index.md b/docs/install/index.md
index 8c6943589..e57ef18ba 100644
--- a/docs/install/index.md
+++ b/docs/install/index.md
@@ -27,6 +27,8 @@ Next step (if you skipped onboarding):
 moltbot onboard --install-daemon
 ```
 
+**Troubleshooting**: If `moltbot` is not found, try `clawdbot` (compatibility shim) or see [PATH troubleshooting](/install/node).
+
 ## System requirements
 
 - **Node >=22**
diff --git a/docs/install/installer.md b/docs/install/installer.md
index c4139de6a..dc7959513 100644
--- a/docs/install/installer.md
+++ b/docs/install/installer.md
@@ -26,7 +26,7 @@ Windows (PowerShell) help:
 & ([scriptblock]::Create((iwr -useb https://molt.bot/install.ps1))) -?
 ```
 
-If the installer completes but `moltbot` is not found in a new terminal, it’s usually a Node/npm PATH issue. See: [Install](/install#nodejs--npm-path-sanity).
+If the installer completes but `moltbot` is not found in a new terminal, try `clawdbot` (compatibility shim). If neither works, it's usually a Node/npm PATH issue. See: [Install](/install#nodejs--npm-path-sanity).
 
 ## install.sh (recommended)
 
diff --git a/docs/install/node.md b/docs/install/node.md
index 801864424..186ef6f65 100644
--- a/docs/install/node.md
+++ b/docs/install/node.md
@@ -11,7 +11,7 @@ read_when:
 
 Moltbot’s runtime baseline is **Node 22+**.
 
-If you can run `npm install -g moltbot@latest` but later see `moltbot: command not found`, it’s almost always a **PATH** issue: the directory where npm puts global binaries isn’t on your shell’s PATH.
+If you can run `npm install -g moltbot@latest` but later see `moltbot: command not found`, first try `clawdbot` (compatibility shim). If that also fails, it's almost always a **PATH** issue: the directory where npm puts global binaries isn't on your shell's PATH.
 
 ## Quick diagnosis
 
diff --git a/docs/start/getting-started.md b/docs/start/getting-started.md
index 239b29966..d212b8596 100644
--- a/docs/start/getting-started.md
+++ b/docs/start/getting-started.md
@@ -75,6 +75,8 @@ npm install -g moltbot@latest
 pnpm add -g moltbot@latest
 ```
 
+If `moltbot: command not found`, try `clawdbot` (compatibility shim) or see [PATH troubleshooting](/install/node).
+
 ## 2) Run the onboarding wizard (and install the service)
 
 ```bash