From 8624feb36ac70dea20bb9850290d4223dd749862 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 9 Jan 2026 23:10:09 +0100
Subject: [PATCH] docs: clarify npm vs git install switching

---
 docs/index.md            |  2 ++
 docs/install/updating.md |  1 +
 docs/start/faq.md        | 25 +++++++++++++++++++++++++
 3 files changed, 28 insertions(+)

diff --git a/docs/index.md b/docs/index.md
index 35332ecf11..5d96b746f3 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -112,6 +112,8 @@ clawdbot providers login
 clawdbot gateway --port 18789
 ```
 
+Switching between npm and git installs later is easy: install the other flavor and run `clawdbot doctor` to update the gateway service entrypoint.
+
 From source (development):
 
 ```bash
diff --git a/docs/install/updating.md b/docs/install/updating.md
index 46e5632cfb..c387a75ffc 100644
--- a/docs/install/updating.md
+++ b/docs/install/updating.md
@@ -67,6 +67,7 @@ pnpm 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 directly from TypeScript (`pnpm clawdbot ...` / `bun run clawdbot ...`), a rebuild is usually unnecessary, but **config migrations still apply** → run doctor.
+- Switching between npm and git installs is easy: install the other flavor, then run `clawdbot doctor` so the gateway service entrypoint is rewritten to the current install.
 
 ## Always run: `clawdbot doctor`
 
diff --git a/docs/start/faq.md b/docs/start/faq.md
index 327713c109..2fc0c29e99 100644
--- a/docs/start/faq.md
+++ b/docs/start/faq.md
@@ -92,6 +92,31 @@ It also warns if your configured model is unknown or missing auth.
 
 Bun is supported for faster TypeScript execution, but **WhatsApp requires Node** in this ecosystem. The wizard lets you pick the runtime; choose **Node** if you use WhatsApp.
 
+### Can I switch between npm and git installs later?
+
+Yes. Install the other flavor, then run Doctor so the gateway service points at the new entrypoint.
+
+From npm → git:
+
+```bash
+git clone https://github.com/clawdbot/clawdbot.git
+cd clawdbot
+pnpm install
+pnpm build
+pnpm clawdbot doctor
+clawdbot daemon restart
+```
+
+From git → npm:
+
+```bash
+npm install -g clawdbot@latest
+clawdbot doctor
+clawdbot daemon restart
+```
+
+Doctor detects a gateway service entrypoint mismatch and offers to rewrite the service config to match the current install (use `--repair` in automation).
+
 ### Is there a dedicated sandboxing doc?
 
 Yes. See [Sandboxing](/gateway/sandboxing). For Docker-specific setup (full gateway in Docker or sandbox images), see [Docker](/install/docker).