diff --git a/README.md b/README.md
index ec970bb5b..4a40587f8 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