loudmouth-ai 0.1.0

package/docs/install/installer.md

@@ -0,0 +1,122 @@
+---
+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)
+ - `https://clawd.bot/install.ps1` — Windows PowerShell installer (npm by default; optional git install)
+
+To see the current flags/behavior, run:
+
+```bash
+curl -fsSL https://clawd.bot/install.sh | bash -s -- --help
+```
+
+Windows (PowerShell) help:
+
+```powershell
+& ([scriptblock]::Create((iwr -useb https://clawd.bot/install.ps1))) -?
+```
+
+If the installer completes but `clawdbot` is not found in a new terminal, it’s usually a Node/npm PATH issue. See: [Install](/install#nodejs--npm-path-sanity).
+
+## 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).
+- For git installs: runs `clawdbot doctor --non-interactive` after install/update (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
+
+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
+```
+
+## install.ps1 (Windows PowerShell)
+
+What it does (high level):
+
+- Ensure Node.js **22+** (winget/Chocolatey/Scoop or manual).
+- Choose install method:
+  - `npm` (default): `npm install -g clawdbot@latest`
+  - `git`: clone/build a source checkout and install a wrapper script
+- Runs `clawdbot doctor --non-interactive` on upgrades and git installs (best effort).
+
+Examples:
+
+```powershell
+iwr -useb https://clawd.bot/install.ps1 | iex
+```
+
+```powershell
+iwr -useb https://clawd.bot/install.ps1 | iex -InstallMethod git
+```
+
+```powershell
+iwr -useb https://clawd.bot/install.ps1 | iex -InstallMethod git -GitDir "C:\\clawdbot"
+```
+
+Environment variables:
+
+- `CLAWDBOT_INSTALL_METHOD=git|npm`
+- `CLAWDBOT_GIT_DIR=...`
+
+Git requirement:
+
+If you choose `-InstallMethod git` and Git is missing, the installer will print the
+Git for Windows link (`https://git-scm.com/download/win`) and exit.
+
+Common Windows issues:
+
+- **npm error spawn git / ENOENT**: install Git for Windows and reopen PowerShell, then rerun the installer.
+- **"clawdbot" is not recognized**: your npm global bin folder is not on PATH. Most systems use
+  `%AppData%\\npm`. You can also run `npm config get prefix` and add `\\bin` to PATH, then reopen PowerShell.

package/docs/install/nix.md

@@ -0,0 +1,95 @@
+---
+summary: "Install Clawdbot declaratively with Nix"
+read_when:
+  - You want reproducible, rollback-able installs
+  - You're already using Nix/NixOS/Home Manager
+  - You want everything pinned and managed declaratively
+---
+
+# Nix Installation
+
+The recommended way to run Clawdbot with Nix is via **[nix-clawdbot](https://github.com/clawdbot/nix-clawdbot)** — a batteries-included Home Manager module.
+
+## Quick Start
+
+Paste this to your AI agent (Claude, Cursor, etc.):
+
+```text
+I want to set up nix-clawdbot on my Mac.
+Repository: github:clawdbot/nix-clawdbot
+
+What I need you to do:
+1. Check if Determinate Nix is installed (if not, install it)
+2. Create a local flake at ~/code/clawdbot-local using templates/agent-first/flake.nix
+3. Help me create a Telegram bot (@BotFather) and get my chat ID (@userinfobot)
+4. Set up secrets (bot token, Anthropic key) - plain files at ~/.secrets/ is fine
+5. Fill in the template placeholders and run home-manager switch
+6. Verify: launchd running, bot responds to messages
+
+Reference the nix-clawdbot README for module options.
+```
+
+> **📦 Full guide: [github.com/clawdbot/nix-clawdbot](https://github.com/clawdbot/nix-clawdbot)**
+>
+> The nix-clawdbot repo is the source of truth for Nix installation. This page is just a quick overview.
+
+## What you get
+
+- Gateway + macOS app + tools (whisper, spotify, cameras) — all pinned
+- Launchd service that survives reboots
+- Plugin system with declarative config
+- Instant rollback: `home-manager switch --rollback`
+
+---
+
+## Nix Mode Runtime Behavior
+
+When `CLAWDBOT_NIX_MODE=1` is set (automatic with nix-clawdbot):
+
+Clawdbot supports a **Nix mode** that makes configuration deterministic and disables auto-install flows.
+Enable it by exporting:
+
+```bash
+CLAWDBOT_NIX_MODE=1
+```
+
+On macOS, the GUI app does not automatically inherit shell env vars. You can
+also enable Nix mode via defaults:
+
+```bash
+defaults write com.clawdbot.mac clawdbot.nixMode -bool true
+```
+
+### Config + state paths
+
+Clawdbot reads JSON5 config from `CLAWDBOT_CONFIG_PATH` and stores mutable data in `CLAWDBOT_STATE_DIR`.
+
+- `CLAWDBOT_STATE_DIR` (default: `~/.clawdbot`)
+- `CLAWDBOT_CONFIG_PATH` (default: `$CLAWDBOT_STATE_DIR/clawdbot.json`)
+
+When running under Nix, set these explicitly to Nix-managed locations so runtime state and config
+stay out of the immutable store.
+
+### Runtime behavior in Nix mode
+
+- Auto-install and self-mutation flows are disabled
+- Missing dependencies surface Nix-specific remediation messages
+- UI surfaces a read-only Nix mode banner when present
+
+## Packaging note (macOS)
+
+The macOS packaging flow expects a stable Info.plist template at:
+
+```
+apps/macos/Sources/Clawdbot/Resources/Info.plist
+```
+
+[`scripts/package-mac-app.sh`](https://github.com/clawdbot/clawdbot/blob/main/scripts/package-mac-app.sh) copies this template into the app bundle and patches dynamic fields
+(bundle ID, version/build, Git SHA, Sparkle keys). This keeps the plist deterministic for SwiftPM
+packaging and Nix builds (which do not rely on a full Xcode toolchain).
+
+## Related
+
+- [nix-clawdbot](https://github.com/clawdbot/nix-clawdbot) — full setup guide
+- [Wizard](/start/wizard) — non-Nix CLI setup
+- [Docker](/install/docker) — containerized setup

package/docs/install/node.md

@@ -0,0 +1,77 @@
+---
+summary: "Node.js + npm install sanity: versions, PATH, and global installs"
+read_when:
+  - You installed Clawdbot but `clawdbot` is “command not found”
+  - You’re setting up Node.js/npm on a new machine
+  - `npm install -g ...` fails with permissions or PATH issues
+---
+
+# Node.js + npm (PATH sanity)
+
+Clawdbot’s runtime baseline is **Node 22+**.
+
+If you can run `npm install -g clawdbot@latest` but later see `clawdbot: command not found`, it’s almost always a **PATH** issue: the directory where npm puts global binaries isn’t on your shell’s PATH.
+
+## Quick diagnosis
+
+Run:
+
+```bash
+node -v
+npm -v
+npm prefix -g
+echo "$PATH"
+```
+
+If `$(npm prefix -g)/bin` (macOS/Linux) or `$(npm prefix -g)` (Windows) is **not** present inside `echo "$PATH"`, your shell can’t find global npm binaries (including `clawdbot`).
+
+## Fix: put npm’s global bin dir on PATH
+
+1) Find your global npm prefix:
+
+```bash
+npm prefix -g
+```
+
+2) Add the global npm bin directory to your shell startup file:
+
+- zsh: `~/.zshrc`
+- bash: `~/.bashrc`
+
+Example (replace the path with your `npm prefix -g` output):
+
+```bash
+# macOS / Linux
+export PATH="/path/from/npm/prefix/bin:$PATH"
+```
+
+Then open a **new terminal** (or run `rehash` in zsh / `hash -r` in bash).
+
+On Windows, add the output of `npm prefix -g` to your PATH.
+
+## Fix: avoid `sudo npm install -g` / permission errors (Linux)
+
+If `npm install -g ...` fails with `EACCES`, switch npm’s global prefix to a user-writable directory:
+
+```bash
+mkdir -p "$HOME/.npm-global"
+npm config set prefix "$HOME/.npm-global"
+export PATH="$HOME/.npm-global/bin:$PATH"
+```
+
+Persist the `export PATH=...` line in your shell startup file.
+
+## Recommended Node install options
+
+You’ll have the fewest surprises if Node/npm are installed in a way that:
+
+- keeps Node updated (22+)
+- makes the global npm bin dir stable and on PATH in new shells
+
+Common choices:
+
+- macOS: Homebrew (`brew install node`) or a version manager
+- Linux: your preferred version manager, or a distro-supported install that provides Node 22+
+- Windows: official Node installer, `winget`, or a Windows Node version manager
+
+If you use a version manager (nvm/fnm/asdf/etc), ensure it’s initialized in the shell you use day-to-day (zsh vs bash) so the PATH it sets is present when you run installers.

package/docs/install/uninstall.md

@@ -0,0 +1,125 @@
+---
+summary: "Uninstall Clawdbot completely (CLI, service, state, workspace)"
+read_when:
+  - You want to remove Clawdbot from a machine
+  - The gateway service is still running after uninstall
+---
+
+# Uninstall
+
+Two paths:
+- **Easy path** if `clawdbot` is still installed.
+- **Manual service removal** if the CLI is gone but the service is still running.
+
+## Easy path (CLI still installed)
+
+Recommended: use the built-in uninstaller:
+
+```bash
+clawdbot uninstall
+```
+
+Non-interactive (automation / npx):
+
+```bash
+clawdbot uninstall --all --yes --non-interactive
+npx -y clawdbot uninstall --all --yes --non-interactive
+```
+
+Manual steps (same result):
+
+1) Stop the gateway service:
+
+```bash
+clawdbot gateway stop
+```
+
+2) Uninstall the gateway service (launchd/systemd/schtasks):
+
+```bash
+clawdbot gateway uninstall
+```
+
+3) Delete state + config:
+
+```bash
+rm -rf "${CLAWDBOT_STATE_DIR:-$HOME/.clawdbot}"
+```
+
+If you set `CLAWDBOT_CONFIG_PATH` to a custom location outside the state dir, delete that file too.
+
+4) Delete your workspace (optional, removes agent files):
+
+```bash
+rm -rf ~/clawd
+```
+
+5) Remove the CLI install (pick the one you used):
+
+```bash
+npm rm -g clawdbot
+pnpm remove -g clawdbot
+bun remove -g clawdbot
+```
+
+6) If you installed the macOS app:
+
+```bash
+rm -rf /Applications/Clawdbot.app
+```
+
+Notes:
+- If you used profiles (`--profile` / `CLAWDBOT_PROFILE`), repeat step 3 for each state dir (defaults are `~/.clawdbot-<profile>`).
+- In remote mode, the state dir lives on the **gateway host**, so run steps 1-4 there too.
+
+## Manual service removal (CLI not installed)
+
+Use this if the gateway service keeps running but `clawdbot` is missing.
+
+### macOS (launchd)
+
+Default label is `com.clawdbot.gateway` (or `com.clawdbot.<profile>`):
+
+```bash
+launchctl bootout gui/$UID/com.clawdbot.gateway
+rm -f ~/Library/LaunchAgents/com.clawdbot.gateway.plist
+```
+
+If you used a profile, replace the label and plist name with `com.clawdbot.<profile>`.
+
+### Linux (systemd user unit)
+
+Default unit name is `clawdbot-gateway.service` (or `clawdbot-gateway-<profile>.service`):
+
+```bash
+systemctl --user disable --now clawdbot-gateway.service
+rm -f ~/.config/systemd/user/clawdbot-gateway.service
+systemctl --user daemon-reload
+```
+
+### Windows (Scheduled Task)
+
+Default task name is `Clawdbot Gateway` (or `Clawdbot Gateway (<profile>)`).
+The task script lives under your state dir.
+
+```powershell
+schtasks /Delete /F /TN "Clawdbot Gateway"
+Remove-Item -Force "$env:USERPROFILE\.clawdbot\gateway.cmd"
+```
+
+If you used a profile, delete the matching task name and `~\.clawdbot-<profile>\gateway.cmd`.
+
+## Normal install vs source checkout
+
+### Normal install (install.sh / npm / pnpm / bun)
+
+If you used `https://clawd.bot/install.sh` or `install.ps1`, the CLI was installed with `npm install -g clawdbot@latest`.
+Remove it with `npm rm -g clawdbot` (or `pnpm remove -g` / `bun remove -g` if you installed that way).
+
+### Source checkout (git clone)
+
+If you run from a repo checkout (`git clone` + `clawdbot ...` / `bun run clawdbot ...`):
+
+1) Uninstall the gateway service **before** deleting the repo (use the easy path above or manual service removal).
+2) Delete the repo directory.
+3) Remove state + workspace as shown above.

package/docs/install/updating.md

@@ -0,0 +1,218 @@
+---
+summary: "Updating Clawdbot safely (global install or source), plus rollback strategy"
+read_when:
+  - Updating Clawdbot
+  - Something breaks after an update
+---
+
+# Updating
+
+Clawdbot is moving fast (pre “1.0”). Treat updates like shipping infra: update → run checks → restart (or use `clawdbot update`, which restarts) → verify.
+
+## Recommended: re-run the website installer (upgrade in place)
+
+The **preferred** update path is to re-run the installer from the website. It
+detects existing installs, upgrades in place, and runs `clawdbot doctor` when
+needed.
+
+```bash
+curl -fsSL https://clawd.bot/install.sh | bash
+```
+
+Notes:
+- Add `--no-onboard` if you don’t want the onboarding wizard to run again.
+- For **source installs**, use:
+  ```bash
+  curl -fsSL https://clawd.bot/install.sh | bash -s -- --install-method git --no-onboard
+  ```
+  The installer will `git pull --rebase` **only** if the repo is clean.
+- For **global installs**, the script uses `npm install -g clawdbot@latest` under the hood.
+
+## Before you update
+
+- Know how you installed: **global** (npm/pnpm) vs **from source** (git clone).
+- Know how your Gateway is running: **foreground terminal** vs **supervised service** (launchd/systemd).
+- Snapshot your tailoring:
+  - Config: `~/.clawdbot/clawdbot.json`
+  - Credentials: `~/.clawdbot/credentials/`
+  - Workspace: `~/clawd`
+
+## Update (global install)
+
+Global install (pick one):
+
+```bash
+npm i -g clawdbot@latest
+```
+
+```bash
+pnpm add -g clawdbot@latest
+```
+We do **not** recommend Bun for the Gateway runtime (WhatsApp/Telegram bugs).
+
+To switch update channels (git + npm installs):
+
+```bash
+clawdbot update --channel beta
+clawdbot update --channel dev
+clawdbot update --channel stable
+```
+
+Use `--tag <dist-tag|version>` for a one-off install tag/version.
+
+See [Development channels](/install/development-channels) for channel semantics and release notes.
+
+Note: on npm installs, the gateway logs an update hint on startup (checks the current channel tag). Disable via `update.checkOnStart: false`.
+
+Then:
+
+```bash
+clawdbot doctor
+clawdbot gateway restart
+clawdbot health
+```
+
+Notes:
+- If your Gateway runs as a service, `clawdbot gateway restart` is preferred over killing PIDs.
+- If you’re pinned to a specific version, see “Rollback / pinning” below.
+
+## Update (`clawdbot update`)
+
+For **source installs** (git checkout), prefer:
+
+```bash
+clawdbot update
+```
+
+It runs a safe-ish update flow:
+- Requires a clean worktree.
+- Switches to the selected channel (tag or branch).
+- Fetches + rebases against the configured upstream (dev channel).
+- Installs deps, builds, builds the Control UI, and runs `clawdbot doctor`.
+- Restarts the gateway by default (use `--no-restart` to skip).
+
+If you installed via **npm/pnpm** (no git metadata), `clawdbot update` will try to update via your package manager. If it can’t detect the install, use “Update (global install)” instead.
+
+## Update (Control UI / RPC)
+
+The Control UI has **Update & Restart** (RPC: `update.run`). It:
+1) Runs the same source-update flow as `clawdbot update` (git checkout only).
+2) Writes a restart sentinel with a structured report (stdout/stderr tail).
+3) Restarts the gateway and pings the last active session with the report.
+
+If the rebase fails, the gateway aborts and restarts without applying the update.
+
+## Update (from source)
+
+From the repo checkout:
+
+Preferred:
+
+```bash
+clawdbot update
+```
+
+Manual (equivalent-ish):
+
+```bash
+git pull
+pnpm install
+pnpm build
+pnpm ui:build # auto-installs UI deps on first run
+clawdbot doctor
+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 from a repo checkout without a global install, use `pnpm clawdbot ...` for CLI commands.
+- If you run directly from TypeScript (`pnpm clawdbot ...`), a rebuild is usually unnecessary, but **config migrations still apply** → run doctor.
+- Switching between global 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`
+
+Doctor is the “safe update” command. It’s intentionally boring: repair + migrate + warn.
+
+Note: if you’re on a **source install** (git checkout), `clawdbot doctor` will offer to run `clawdbot update` first.
+
+Typical things it does:
+- Migrate deprecated config keys / legacy config file locations.
+- Audit DM policies and warn on risky “open” settings.
+- Check Gateway health and can offer to restart.
+- Detect and migrate older gateway services (launchd/systemd; legacy schtasks) to current Clawdbot services.
+- On Linux, ensure systemd user lingering (so the Gateway survives logout).
+
+Details: [Doctor](/gateway/doctor)
+
+## Start / stop / restart the Gateway
+
+CLI (works regardless of OS):
+
+```bash
+clawdbot gateway status
+clawdbot gateway stop
+clawdbot gateway restart
+clawdbot gateway --port 18789
+clawdbot logs --follow
+```
+
+If you’re supervised:
+- macOS launchd (app-bundled LaunchAgent): `launchctl kickstart -k gui/$UID/com.clawdbot.gateway` (use `com.clawdbot.<profile>` if set)
+- Linux systemd user service: `systemctl --user restart clawdbot-gateway[-<profile>].service`
+- Windows (WSL2): `systemctl --user restart clawdbot-gateway[-<profile>].service`
+  - `launchctl`/`systemctl` only work if the service is installed; otherwise run `clawdbot gateway install`.
+
+Runbook + exact service labels: [Gateway runbook](/gateway)
+
+## Rollback / pinning (when something breaks)
+
+### Pin (global install)
+
+Install a known-good version (replace `<version>` with the last working one):
+
+```bash
+npm i -g clawdbot@<version>
+```
+
+```bash
+pnpm add -g clawdbot@<version>
+```
+
+Tip: to see the current published version, run `npm view clawdbot version`.
+
+Then restart + re-run doctor:
+
+```bash
+clawdbot doctor
+clawdbot gateway restart
+```
+
+### Pin (source) by date
+
+Pick a commit from a date (example: “state of main as of 2026-01-01”):
+
+```bash
+git fetch origin
+git checkout "$(git rev-list -n 1 --before=\"2026-01-01\" origin/main)"
+```
+
+Then reinstall deps + restart:
+
+```bash
+pnpm install
+pnpm build
+clawdbot gateway restart
+```
+
+If you want to go back to latest later:
+
+```bash
+git checkout main
+git pull
+```
+
+## If you’re stuck
+
+- Run `clawdbot doctor` again and read the output carefully (it often tells you the fix).
+- Check: [Troubleshooting](/gateway/troubleshooting)
+- Ask in Discord: https://channels.discord.gg/clawd