docs: document sharp/libvips install workaround

AGENTS.md

@@ -4,6 +4,7 @@
 - Source code: `src/` (CLI wiring in `src/cli`, commands in `src/commands`, web provider in `src/provider-web.ts`, infra in `src/infra`, media pipeline in `src/media`).
 - Tests: colocated `*.test.ts`.
 - Docs: `docs/` (images, queue, Pi config). Built output lives in `dist/`.
+- Installers served from `https://clawd.bot/*`: live in the sibling repo `../clawd.bot` (`public/install.sh`, `public/install-cli.sh`, `public/install.ps1`).
 
 ## Docs Linking (Mintlify)
 - Docs are hosted on Mintlify (docs.clawd.bot).

docs/install/index.md

@@ -67,6 +67,7 @@ Equivalent env vars (useful for automation):
 - `CLAWDBOT_NO_PROMPT=1`
 - `CLAWDBOT_DRY_RUN=1`
 - `CLAWDBOT_NO_ONBOARD=1`
+- `SHARP_IGNORE_GLOBAL_LIBVIPS=0|1` (default: `1`; avoids `sharp` building against system libvips)
 
 ## Install from GitHub (from source)
 
@@ -96,6 +97,12 @@ If you already have Node:
 npm install -g clawdbot@latest
 ```
 
+If you have libvips installed globally (common on macOS via Homebrew) and `sharp` fails to install, force prebuilt binaries:
+
+```bash
+SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g clawdbot@latest
+```
+
 Or:
 
 ```bash

docs/install/installer.md

@@ -30,6 +30,13 @@ What it does (high level):
   - `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).
+- Mitigates `sharp` native install gotchas by defaulting `SHARP_IGNORE_GLOBAL_LIBVIPS=1` (avoids building against system libvips).
+
+If you *want* `sharp` to link against a globally-installed libvips (or you’re debugging), set:
+
+```bash
+SHARP_IGNORE_GLOBAL_LIBVIPS=0 curl -fsSL https://clawd.bot/install.sh | bash
+```
 
 ### Discoverability / “git install” prompt
 
@@ -69,4 +76,3 @@ curl -fsSL https://clawd.bot/install-cli.sh | bash -s -- --help
 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).
-