From f57f6e0ca64ecd1241c5860c8afaf11f56d11708 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Mon, 12 Jan 2026 02:00:09 +0000
Subject: [PATCH] docs: add installer internals

---
 CHANGELOG.md              |  1 +
 docs/docs.json            |  1 +
 docs/install/index.md     |  9 ++++-
 docs/install/installer.md | 72 +++++++++++++++++++++++++++++++++++++++
 4 files changed, 82 insertions(+), 1 deletion(-)
 create mode 100644 docs/install/installer.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8c694d3b1..d3baa9cfa 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -23,6 +23,7 @@
 - Postinstall: replace `git apply` with builtin JS patcher (works npm/pnpm/bun; no git dependency) plus regression tests.
 - Installer tests: add root+non-root docker smokes, CI workflow to fetch clawd.bot scripts and run install sh/cli with onboarding skipped.
 - Installer UX: support `CLAWDBOT_NO_ONBOARD=1` for non-interactive installs; fix npm prefix on Linux and auto-install git.
+- Installer UX: add `install.sh --help` with flags/env and git install hint.
 - Installer UX: add `--install-method git|npm` and auto-detect source checkouts (prompt to update git checkout vs migrate to npm).
 
 ### Fixes
diff --git a/docs/docs.json b/docs/docs.json
index 6b36fbff7..1ef5e197c 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -576,6 +576,7 @@
         "group": "Install & Updates",
         "pages": [
           "install/index",
+          "install/installer",
           "install/updating",
           "install/ansible",
           "install/nix",
diff --git a/docs/install/index.md b/docs/install/index.md
index abef2483d..b7e56c92a 100644
--- a/docs/install/index.md
+++ b/docs/install/index.md
@@ -17,6 +17,14 @@ curl -fsSL https://clawd.bot/install.sh | bash
 
 This installs the `clawdbot` CLI globally via npm and then starts onboarding.
 
+See installer flags:
+
+```bash
+curl -fsSL https://clawd.bot/install.sh | bash -s -- --help
+```
+
+Details: [Installer internals](/install/installer).
+
 Non-interactive (skip onboarding):
 
 ```bash
@@ -99,4 +107,3 @@ Then:
 ```bash
 clawdbot onboard --install-daemon
 ```
-
diff --git a/docs/install/installer.md b/docs/install/installer.md
new file mode 100644
index 000000000..3e3b88e21
--- /dev/null
+++ b/docs/install/installer.md
@@ -0,0 +1,72 @@
+---
+summary: "How the installer scripts work (install.sh + install-cli.sh), flags, and automation"
+read_when:
+  - You want to understand `clawd.bot/install.sh`
+  - You want to automate installs (CI / headless)
+  - You want to install from a GitHub checkout
+---
+
+# Installer internals
+
+Clawdbot ships two installer scripts (served from `clawd.bot`):
+
+- `https://clawd.bot/install.sh` — “recommended” installer (global npm install by default; can also install from a GitHub checkout)
+- `https://clawd.bot/install-cli.sh` — non-root-friendly CLI installer (installs into a prefix with its own Node)
+
+To see the current flags/behavior, run:
+
+```bash
+curl -fsSL https://clawd.bot/install.sh | bash -s -- --help
+```
+
+## install.sh (recommended)
+
+What it does (high level):
+
+- Detect OS (macOS / Linux / WSL).
+- Ensure Node.js **22+** (macOS via Homebrew; Linux via NodeSource).
+- Choose install method:
+  - `npm` (default): `npm install -g clawdbot@latest`
+  - `git`: clone/build a source checkout and install a wrapper script
+- On Linux: avoid global npm permission errors by switching npm’s prefix to `~/.npm-global` when needed.
+- If upgrading an existing install: runs `clawdbot doctor --non-interactive` (best effort).
+
+### Discoverability / “git install” prompt
+
+If you run the installer while **already inside a Clawdbot source checkout** (detected via `package.json` + `pnpm-workspace.yaml`), it prompts:
+
+- update and use this checkout (`git`)
+- or migrate to the global npm install (`npm`)
+
+In non-interactive contexts (no TTY / `--no-prompt`), you must pass `--install-method git|npm` (or set `CLAWDBOT_INSTALL_METHOD`), otherwise the script exits with code `2`.
+
+### Why Git is needed
+
+Git is required for the `--install-method git` path (clone / pull).
+
+For `npm` installs, Git is *usually* not required, but some environments still end up needing it (e.g. when a package or dependency is fetched via a git URL). The installer currently ensures Git is present to avoid `spawn git ENOENT` surprises on fresh distros.
+
+### Why npm hits `EACCES` on fresh Linux
+
+On some Linux setups (especially after installing Node via the system package manager or NodeSource), npm’s global prefix points at a root-owned location. Then `npm install -g ...` fails with `EACCES` / `mkdir` permission errors.
+
+`install.sh` mitigates this by switching the prefix to:
+
+- `~/.npm-global` (and adding it to `PATH` in `~/.bashrc` / `~/.zshrc` when present)
+
+## install-cli.sh (non-root CLI installer)
+
+This script installs `clawdbot` into a prefix (default: `~/.clawdbot`) and also installs a dedicated Node runtime under that prefix, so it can work on machines where you don’t want to touch the system Node/npm.
+
+Help:
+
+```bash
+curl -fsSL https://clawd.bot/install-cli.sh | bash -s -- --help
+```
+
+## Patches (npm / pnpm / bun)
+
+Clawdbot’s `postinstall` script includes a builtin JS patcher that can apply `pnpm.patchedDependencies` patches even when the package manager doesn’t support them (notably Bun). pnpm itself already applies `pnpm.patchedDependencies`, so the fallback skips pnpm installs to avoid double-applying.
+
+See: [Bun notes](/install/bun).
+