@quantumclaw/quantumclaw 2026.3.22

package/docs/platforms/raspberry-pi.md

@@ -0,0 +1,412 @@
+---
+summary: "QuantumClaw on Raspberry Pi (budget self-hosted setup)"
+read_when:
+  - Setting up QuantumClaw on a Raspberry Pi
+  - Running QuantumClaw on ARM devices
+  - Building a cheap always-on personal AI
+title: "Raspberry Pi"
+---
+
+# QuantumClaw on Raspberry Pi
+
+## Goal
+
+Run a persistent, always-on QuantumClaw Gateway on a Raspberry Pi for **~$35-80** one-time cost (no monthly fees).
+
+Perfect for:
+
+- 24/7 personal AI assistant
+- Home automation hub
+- Low-power, always-available Telegram/WhatsApp bot
+
+## Hardware Requirements
+
+| Pi Model        | RAM     | Works?   | Notes                              |
+| --------------- | ------- | -------- | ---------------------------------- |
+| **Pi 5**        | 4GB/8GB | ✅ Best  | Fastest, recommended               |
+| **Pi 4**        | 4GB     | ✅ Good  | Sweet spot for most users          |
+| **Pi 4**        | 2GB     | ✅ OK    | Works, add swap                    |
+| **Pi 4**        | 1GB     | ⚠️ Tight | Possible with swap, minimal config |
+| **Pi 3B+**      | 1GB     | ⚠️ Slow  | Works but sluggish                 |
+| **Pi Zero 2 W** | 512MB   | ❌       | Not recommended                    |
+
+**Minimum specs:** 1GB RAM, 1 core, 500MB disk  
+**Recommended:** 2GB+ RAM, 64-bit OS, 16GB+ SD card (or USB SSD)
+
+## What you need
+
+- Raspberry Pi 4 or 5 (2GB+ recommended)
+- MicroSD card (16GB+) or USB SSD (better performance)
+- Power supply (official Pi PSU recommended)
+- Network connection (Ethernet or WiFi)
+- ~30 minutes
+
+## 1) Flash the OS
+
+Use **Raspberry Pi OS Lite (64-bit)** — no desktop needed for a headless server.
+
+1. Download [Raspberry Pi Imager](https://www.raspberrypi.com/software/)
+2. Choose OS: **Raspberry Pi OS Lite (64-bit)**
+3. Click the gear icon (⚙️) to pre-configure:
+   - Set hostname: `gateway-host`
+   - Enable SSH
+   - Set username/password
+   - Configure WiFi (if not using Ethernet)
+4. Flash to your SD card / USB drive
+5. Insert and boot the Pi
+
+## 2) Connect via SSH
+
+```bash
+ssh user@gateway-host
+# or use the IP address
+ssh user@192.168.x.x
+```
+
+## 3) System Setup
+
+```bash
+# Update system
+sudo apt update && sudo apt upgrade -y
+
+# Install essential packages
+sudo apt install -y git curl build-essential
+
+# Set timezone (important for cron/reminders)
+sudo timedatectl set-timezone America/Chicago  # Change to your timezone
+```
+
+## 4) Install Node.js 24 (ARM64)
+
+```bash
+# Install Node.js via NodeSource
+curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
+sudo apt install -y nodejs
+
+# Verify
+node --version  # Should show v24.x.x
+npm --version
+```
+
+## 5) Add Swap (Important for 2GB or less)
+
+Swap prevents out-of-memory crashes:
+
+```bash
+# Create 2GB swap file
+sudo fallocate -l 2G /swapfile
+sudo chmod 600 /swapfile
+sudo mkswap /swapfile
+sudo swapon /swapfile
+
+# Make permanent
+echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
+
+# Optimize for low RAM (reduce swappiness)
+echo 'vm.swappiness=10' | sudo tee -a /etc/sysctl.conf
+sudo sysctl -p
+```
+
+## 6) Install QuantumClaw
+
+### Option A: Standard Install (Recommended)
+
+```bash
+curl -fsSL https://quantumclaw.ai/install.sh | bash
+```
+
+### Option B: Hackable Install (For tinkering)
+
+```bash
+git clone https://github.com/quantumclaw/quantumclaw.git
+cd quantumclaw
+npm install
+npm run build
+npm link
+```
+
+The hackable install gives you direct access to logs and code — useful for debugging ARM-specific issues.
+
+## 7) Run Onboarding
+
+```bash
+quantumclaw onboard --install-daemon
+```
+
+Follow the wizard:
+
+1. **Gateway mode:** Local
+2. **Auth:** API keys recommended (OAuth can be finicky on headless Pi)
+3. **Channels:** Telegram is easiest to start with
+4. **Daemon:** Yes (systemd)
+
+## 8) Verify Installation
+
+```bash
+# Check status
+quantumclaw status
+
+# Check service
+sudo systemctl status quantumclaw
+
+# View logs
+journalctl -u quantumclaw -f
+```
+
+## 9) Access the QuantumClaw Dashboard
+
+Replace `user@gateway-host` with your Pi username and hostname or IP address.
+
+On your computer, ask the Pi to print a fresh dashboard URL:
+
+```bash
+ssh user@gateway-host 'quantumclaw dashboard --no-open'
+```
+
+The command prints `Dashboard URL:`. Depending on how `gateway.auth.token`
+is configured, the URL may be a plain `http://127.0.0.1:18789/` link or one
+that includes `#token=...`.
+
+In another terminal on your computer, create the SSH tunnel:
+
+```bash
+ssh -N -L 18789:127.0.0.1:18789 user@gateway-host
+```
+
+Then open the printed Dashboard URL in your local browser.
+
+If the UI asks for auth, paste the token from `gateway.auth.token`
+(or `QUANTUMCLAW_GATEWAY_TOKEN`) into Control UI settings.
+
+For always-on remote access, see [Tailscale](/gateway/tailscale).
+
+---
+
+## Performance Optimizations
+
+### Use a USB SSD (Huge Improvement)
+
+SD cards are slow and wear out. A USB SSD dramatically improves performance:
+
+```bash
+# Check if booting from USB
+lsblk
+```
+
+See [Pi USB boot guide](https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#usb-mass-storage-boot) for setup.
+
+### Speed up CLI startup (module compile cache)
+
+On lower-power Pi hosts, enable Node's module compile cache so repeated CLI runs are faster:
+
+```bash
+grep -q 'NODE_COMPILE_CACHE=/var/tmp/quantumclaw-compile-cache' ~/.bashrc || cat >> ~/.bashrc <<'EOF' # pragma: allowlist secret
+export NODE_COMPILE_CACHE=/var/tmp/quantumclaw-compile-cache
+mkdir -p /var/tmp/quantumclaw-compile-cache
+export QUANTUMCLAW_NO_RESPAWN=1
+EOF
+source ~/.bashrc
+```
+
+Notes:
+
+- `NODE_COMPILE_CACHE` speeds up subsequent runs (`status`, `health`, `--help`).
+- `/var/tmp` survives reboots better than `/tmp`.
+- `QUANTUMCLAW_NO_RESPAWN=1` avoids extra startup cost from CLI self-respawn.
+- First run warms the cache; later runs benefit most.
+
+### systemd startup tuning (optional)
+
+If this Pi is mostly running QuantumClaw, add a service drop-in to reduce restart
+jitter and keep startup env stable:
+
+```bash
+sudo systemctl edit quantumclaw
+```
+
+```ini
+[Service]
+Environment=QUANTUMCLAW_NO_RESPAWN=1
+Environment=NODE_COMPILE_CACHE=/var/tmp/quantumclaw-compile-cache
+Restart=always
+RestartSec=2
+TimeoutStartSec=90
+```
+
+Then apply:
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl restart quantumclaw
+```
+
+If possible, keep QuantumClaw state/cache on SSD-backed storage to avoid SD-card
+random-I/O bottlenecks during cold starts.
+
+How `Restart=` policies help automated recovery:
+[systemd can automate service recovery](https://www.redhat.com/en/blog/systemd-automate-recovery).
+
+### Reduce Memory Usage
+
+```bash
+# Disable GPU memory allocation (headless)
+echo 'gpu_mem=16' | sudo tee -a /boot/config.txt
+
+# Disable Bluetooth if not needed
+sudo systemctl disable bluetooth
+```
+
+### Monitor Resources
+
+```bash
+# Check memory
+free -h
+
+# Check CPU temperature
+vcgencmd measure_temp
+
+# Live monitoring
+htop
+```
+
+---
+
+## ARM-Specific Notes
+
+### Binary Compatibility
+
+Most QuantumClaw features work on ARM64, but some external binaries may need ARM builds:
+
+| Tool               | ARM64 Status | Notes                               |
+| ------------------ | ------------ | ----------------------------------- |
+| Node.js            | ✅           | Works great                         |
+| WhatsApp (Baileys) | ✅           | Pure JS, no issues                  |
+| Telegram           | ✅           | Pure JS, no issues                  |
+| gog (Gmail CLI)    | ⚠️           | Check for ARM release               |
+| Chromium (browser) | ✅           | `sudo apt install chromium-browser` |
+
+If a skill fails, check if its binary has an ARM build. Many Go/Rust tools do; some don't.
+
+### 32-bit vs 64-bit
+
+**Always use 64-bit OS.** Node.js and many modern tools require it. Check with:
+
+```bash
+uname -m
+# Should show: aarch64 (64-bit) not armv7l (32-bit)
+```
+
+---
+
+## Recommended Model Setup
+
+Since the Pi is just the Gateway (models run in the cloud), use API-based models:
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "model": {
+        "primary": "anthropic/claude-sonnet-4-20250514",
+        "fallbacks": ["openai/gpt-4o-mini"]
+      }
+    }
+  }
+}
+```
+
+**Don't try to run local LLMs on a Pi** — even small models are too slow. Let Claude/GPT do the heavy lifting.
+
+---
+
+## Auto-Start on Boot
+
+Onboarding sets this up, but to verify:
+
+```bash
+# Check service is enabled
+sudo systemctl is-enabled quantumclaw
+
+# Enable if not
+sudo systemctl enable quantumclaw
+
+# Start on boot
+sudo systemctl start quantumclaw
+```
+
+---
+
+## Troubleshooting
+
+### Out of Memory (OOM)
+
+```bash
+# Check memory
+free -h
+
+# Add more swap (see Step 5)
+# Or reduce services running on the Pi
+```
+
+### Slow Performance
+
+- Use USB SSD instead of SD card
+- Disable unused services: `sudo systemctl disable cups bluetooth avahi-daemon`
+- Check CPU throttling: `vcgencmd get_throttled` (should return `0x0`)
+
+### Service will not start
+
+```bash
+# Check logs
+journalctl -u quantumclaw --no-pager -n 100
+
+# Common fix: rebuild
+cd ~/quantumclaw  # if using hackable install
+npm run build
+sudo systemctl restart quantumclaw
+```
+
+### ARM Binary Issues
+
+If a skill fails with "exec format error":
+
+1. Check if the binary has an ARM64 build
+2. Try building from source
+3. Or use a Docker container with ARM support
+
+### WiFi Drops
+
+For headless Pis on WiFi:
+
+```bash
+# Disable WiFi power management
+sudo iwconfig wlan0 power off
+
+# Make permanent
+echo 'wireless-power off' | sudo tee -a /etc/network/interfaces
+```
+
+---
+
+## Cost Comparison
+
+| Setup          | One-Time Cost | Monthly Cost | Notes                     |
+| -------------- | ------------- | ------------ | ------------------------- |
+| **Pi 4 (2GB)** | ~$45          | $0           | + power (~$5/yr)          |
+| **Pi 4 (4GB)** | ~$55          | $0           | Recommended               |
+| **Pi 5 (4GB)** | ~$60          | $0           | Best performance          |
+| **Pi 5 (8GB)** | ~$80          | $0           | Overkill but future-proof |
+| DigitalOcean   | $0            | $6/mo        | $72/year                  |
+| Hetzner        | $0            | €3.79/mo     | ~$50/year                 |
+
+**Break-even:** A Pi pays for itself in ~6-12 months vs cloud VPS.
+
+---
+
+## See Also
+
+- [Linux guide](/platforms/linux) — general Linux setup
+- [DigitalOcean guide](/platforms/digitalocean) — cloud alternative
+- [Hetzner guide](/install/hetzner) — Docker setup
+- [Tailscale](/gateway/tailscale) — remote access
+- [Nodes](/nodes) — pair your laptop/phone with the Pi gateway

package/docs/platforms/windows.md

@@ -0,0 +1,241 @@
+---
+summary: "Windows support: native and WSL2 install paths, daemon, and current caveats"
+read_when:
+  - Installing QuantumClaw on Windows
+  - Choosing between native Windows and WSL2
+  - Looking for Windows companion app status
+title: "Windows"
+---
+
+# Windows
+
+QuantumClaw supports both **native Windows** and **WSL2**. WSL2 is the more
+stable path and recommended for the full experience — the CLI, Gateway, and
+tooling run inside Linux with full compatibility. Native Windows works for
+core CLI and Gateway use, with some caveats noted below.
+
+Native Windows companion apps are planned.
+
+## WSL2 (recommended)
+
+- [Getting Started](/start/getting-started) (use inside WSL)
+- [Install & updates](/install/updating)
+- Official WSL2 guide (Microsoft): [https://learn.microsoft.com/windows/wsl/install](https://learn.microsoft.com/windows/wsl/install)
+
+## Native Windows status
+
+Native Windows CLI flows are improving, but WSL2 is still the recommended path.
+
+What works well on native Windows today:
+
+- website installer via `install.ps1`
+- local CLI use such as `quantumclaw --version`, `quantumclaw doctor`, and `quantumclaw plugins list --json`
+- embedded local-agent/provider smoke such as:
+
+```powershell
+quantumclaw agent --local --agent main --thinking low -m "Reply with exactly WINDOWS-HATCH-OK."
+```
+
+Current caveats:
+
+- `quantumclaw onboard --non-interactive` still expects a reachable local gateway unless you pass `--skip-health`
+- `quantumclaw onboard --non-interactive --install-daemon` and `quantumclaw gateway install` try Windows Scheduled Tasks first
+- if Scheduled Task creation is denied, QuantumClaw falls back to a per-user Startup-folder login item and starts the gateway immediately
+- if `schtasks` itself wedges or stops responding, QuantumClaw now aborts that path quickly and falls back instead of hanging forever
+- Scheduled Tasks are still preferred when available because they provide better supervisor status
+
+If you want the native CLI only, without gateway service install, use one of these:
+
+```powershell
+quantumclaw onboard --non-interactive --skip-health
+quantumclaw gateway run
+```
+
+If you do want managed startup on native Windows:
+
+```powershell
+quantumclaw gateway install
+quantumclaw gateway status --json
+```
+
+If Scheduled Task creation is blocked, the fallback service mode still auto-starts after login through the current user's Startup folder.
+
+## Gateway
+
+- [Gateway runbook](/gateway)
+- [Configuration](/gateway/configuration)
+
+## Gateway service install (CLI)
+
+Inside WSL2:
+
+```
+quantumclaw onboard --install-daemon
+```
+
+Or:
+
+```
+quantumclaw gateway install
+```
+
+Or:
+
+```
+quantumclaw configure
+```
+
+Select **Gateway service** when prompted.
+
+Repair/migrate:
+
+```
+quantumclaw doctor
+```
+
+## Gateway auto-start before Windows login
+
+For headless setups, ensure the full boot chain runs even when no one logs into
+Windows.
+
+### 1) Keep user services running without login
+
+Inside WSL:
+
+```bash
+sudo loginctl enable-linger "$(whoami)"
+```
+
+### 2) Install the QuantumClaw gateway user service
+
+Inside WSL:
+
+```bash
+quantumclaw gateway install
+```
+
+### 3) Start WSL automatically at Windows boot
+
+In PowerShell as Administrator:
+
+```powershell
+schtasks /create /tn "WSL Boot" /tr "wsl.exe -d Ubuntu --exec /bin/true" /sc onstart /ru SYSTEM
+```
+
+Replace `Ubuntu` with your distro name from:
+
+```powershell
+wsl --list --verbose
+```
+
+### Verify startup chain
+
+After a reboot (before Windows sign-in), check from WSL:
+
+```bash
+systemctl --user is-enabled quantumclaw-gateway
+systemctl --user status quantumclaw-gateway --no-pager
+```
+
+## Advanced: expose WSL services over LAN (portproxy)
+
+WSL has its own virtual network. If another machine needs to reach a service
+running **inside WSL** (SSH, a local TTS server, or the Gateway), you must
+forward a Windows port to the current WSL IP. The WSL IP changes after restarts,
+so you may need to refresh the forwarding rule.
+
+Example (PowerShell **as Administrator**):
+
+```powershell
+$Distro = "Ubuntu-24.04"
+$ListenPort = 2222
+$TargetPort = 22
+
+$WslIp = (wsl -d $Distro -- hostname -I).Trim().Split(" ")[0]
+if (-not $WslIp) { throw "WSL IP not found." }
+
+netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=$ListenPort `
+  connectaddress=$WslIp connectport=$TargetPort
+```
+
+Allow the port through Windows Firewall (one-time):
+
+```powershell
+New-NetFirewallRule -DisplayName "WSL SSH $ListenPort" -Direction Inbound `
+  -Protocol TCP -LocalPort $ListenPort -Action Allow
+```
+
+Refresh the portproxy after WSL restarts:
+
+```powershell
+netsh interface portproxy delete v4tov4 listenport=$ListenPort listenaddress=0.0.0.0 | Out-Null
+netsh interface portproxy add v4tov4 listenport=$ListenPort listenaddress=0.0.0.0 `
+  connectaddress=$WslIp connectport=$TargetPort | Out-Null
+```
+
+Notes:
+
+- SSH from another machine targets the **Windows host IP** (example: `ssh user@windows-host -p 2222`).
+- Remote nodes must point at a **reachable** Gateway URL (not `127.0.0.1`); use
+  `quantumclaw status --all` to confirm.
+- Use `listenaddress=0.0.0.0` for LAN access; `127.0.0.1` keeps it local only.
+- If you want this automatic, register a Scheduled Task to run the refresh
+  step at login.
+
+## Step-by-step WSL2 install
+
+### 1) Install WSL2 + Ubuntu
+
+Open PowerShell (Admin):
+
+```powershell
+wsl --install
+# Or pick a distro explicitly:
+wsl --list --online
+wsl --install -d Ubuntu-24.04
+```
+
+Reboot if Windows asks.
+
+### 2) Enable systemd (required for gateway install)
+
+In your WSL terminal:
+
+```bash
+sudo tee /etc/wsl.conf >/dev/null <<'EOF'
+[boot]
+systemd=true
+EOF
+```
+
+Then from PowerShell:
+
+```powershell
+wsl --shutdown
+```
+
+Re-open Ubuntu, then verify:
+
+```bash
+systemctl --user status
+```
+
+### 3) Install QuantumClaw (inside WSL)
+
+Follow the Linux Getting Started flow inside WSL:
+
+```bash
+git clone https://github.com/quantumclaw/quantumclaw.git
+cd quantumclaw
+pnpm install
+pnpm ui:build # auto-installs UI deps on first run
+pnpm build
+quantumclaw onboard
+```
+
+Full guide: [Getting Started](/start/getting-started)
+
+## Windows companion app
+
+We do not have a Windows companion app yet. Contributions are welcome if you want
+contributions to make it happen.

package/docs/plugins/agent-tools.md

@@ -0,0 +1,10 @@
+---
+summary: "Redirects to Building Plugins (registering tools section)"
+read_when:
+  - Legacy link to agent-tools
+title: "Registering Tools"
+---
+
+# Registering Tools in Plugins
+
+This page has moved. See [Building Plugins: Registering agent tools](/plugins/building-plugins#registering-agent-tools).