@quantumclaw/quantumclaw 2026.3.22

package/docs/install/development-channels.md

@@ -0,0 +1,120 @@
+---
+summary: "Stable, beta, and dev channels: semantics, switching, pinning, and tagging"
+read_when:
+  - You want to switch between stable/beta/dev
+  - You want to pin a specific version, tag, or SHA
+  - You are tagging or publishing prereleases
+title: "Release Channels"
+sidebarTitle: "Release Channels"
+---
+
+# Development channels
+
+QuantumClaw ships three update channels:
+
+- **stable**: npm dist-tag `latest`. Recommended for most users.
+- **beta**: npm dist-tag `beta` (builds under test).
+- **dev**: moving head of `main` (git). npm dist-tag: `dev` (when published).
+  The `main` branch is for experimentation and active development. It may contain
+  incomplete features or breaking changes. Do not use it for production gateways.
+
+We ship builds to **beta**, test them, then **promote a vetted build to `latest`**
+without changing the version number -- dist-tags are the source of truth for npm installs.
+
+## Switching channels
+
+```bash
+quantumclaw update --channel stable
+quantumclaw update --channel beta
+quantumclaw update --channel dev
+```
+
+`--channel` persists your choice in config (`update.channel`) and aligns the
+install method:
+
+- **`stable`/`beta`** (package installs): updates via the matching npm dist-tag.
+- **`stable`/`beta`** (git installs): checks out the latest matching git tag.
+- **`dev`**: ensures a git checkout (default `~/quantumclaw`, override with
+  `QUANTUMCLAW_GIT_DIR`), switches to `main`, rebases on upstream, builds, and
+  installs the global CLI from that checkout.
+
+Tip: if you want stable + dev in parallel, keep two clones and point your
+gateway at the stable one.
+
+## One-off version or tag targeting
+
+Use `--tag` to target a specific dist-tag, version, or package spec for a single
+update **without** changing your persisted channel:
+
+```bash
+# Install a specific version
+quantumclaw update --tag 2026.3.22
+
+# Install from the beta dist-tag (one-off, does not persist)
+quantumclaw update --tag beta
+
+# Install from GitHub main branch (npm tarball)
+quantumclaw update --tag main
+
+# Install a specific npm package spec
+quantumclaw update --tag quantumclaw@2026.3.22
+```
+
+Notes:
+
+- `--tag` applies to **package (npm) installs only**. Git installs ignore it.
+- The tag is not persisted. Your next `quantumclaw update` uses your configured
+  channel as usual.
+- Downgrade protection: if the target version is older than your current version,
+  QuantumClaw prompts for confirmation (skip with `--yes`).
+
+## Dry run
+
+Preview what `quantumclaw update` would do without making changes:
+
+```bash
+quantumclaw update --dry-run
+quantumclaw update --channel beta --dry-run
+quantumclaw update --tag 2026.3.22 --dry-run
+quantumclaw update --dry-run --json
+```
+
+The dry run shows the effective channel, target version, planned actions, and
+whether a downgrade confirmation would be required.
+
+## Plugins and channels
+
+When you switch channels with `quantumclaw update`, QuantumClaw also syncs plugin
+sources:
+
+- `dev` prefers bundled plugins from the git checkout.
+- `stable` and `beta` restore npm-installed plugin packages.
+- npm-installed plugins are updated after the core update completes.
+
+## Checking current status
+
+```bash
+quantumclaw update status
+```
+
+Shows the active channel, install kind (git or package), current version, and
+source (config, git tag, git branch, or default).
+
+## Tagging best practices
+
+- Tag releases you want git checkouts to land on (`vYYYY.M.D` for stable,
+  `vYYYY.M.D-beta.N` for beta).
+- `vYYYY.M.D.beta.N` is also recognized for compatibility, but prefer `-beta.N`.
+- Legacy `vYYYY.M.D-<patch>` tags are still recognized as stable (non-beta).
+- Keep tags immutable: never move or reuse a tag.
+- npm dist-tags remain the source of truth for npm installs:
+  - `latest` -> stable
+  - `beta` -> candidate build
+  - `dev` -> main snapshot (optional)
+
+## macOS app availability
+
+Beta and dev builds may **not** include a macOS app release. That is OK:
+
+- The git tag and npm dist-tag can still be published.
+- Call out "no macOS build for this beta" in release notes or changelog.

package/docs/install/digitalocean.md

@@ -0,0 +1,129 @@
+---
+summary: "Host QuantumClaw on a DigitalOcean Droplet"
+read_when:
+  - Setting up QuantumClaw on DigitalOcean
+  - Looking for a simple paid VPS for QuantumClaw
+title: "DigitalOcean"
+---
+
+# DigitalOcean
+
+Run a persistent QuantumClaw Gateway on a DigitalOcean Droplet.
+
+## Prerequisites
+
+- DigitalOcean account ([signup](https://cloud.digitalocean.com/registrations/new))
+- SSH key pair (or willingness to use password auth)
+- About 20 minutes
+
+## Setup
+
+<Steps>
+  <Step title="Create a Droplet">
+    <Warning>
+    Use a clean base image (Ubuntu 24.04 LTS). Avoid third-party Marketplace 1-click images unless you have reviewed their startup scripts and firewall defaults.
+    </Warning>
+
+    1. Log into [DigitalOcean](https://cloud.digitalocean.com/).
+    2. Click **Create > Droplets**.
+    3. Choose:
+       - **Region:** Closest to you
+       - **Image:** Ubuntu 24.04 LTS
+       - **Size:** Basic, Regular, 1 vCPU / 1 GB RAM / 25 GB SSD
+       - **Authentication:** SSH key (recommended) or password
+    4. Click **Create Droplet** and note the IP address.
+
+  </Step>
+
+  <Step title="Connect and install">
+    ```bash
+    ssh root@YOUR_DROPLET_IP
+
+    apt update && apt upgrade -y
+
+    # Install Node.js 24
+    curl -fsSL https://deb.nodesource.com/setup_24.x | bash -
+    apt install -y nodejs
+
+    # Install QuantumClaw
+    curl -fsSL https://quantumclaw.ai/install.sh | bash
+    quantumclaw --version
+    ```
+
+  </Step>
+
+  <Step title="Run onboarding">
+    ```bash
+    quantumclaw onboard --install-daemon
+    ```
+
+    The wizard walks you through model auth, channel setup, gateway token generation, and daemon installation (systemd).
+
+  </Step>
+
+  <Step title="Add swap (recommended for 1 GB Droplets)">
+    ```bash
+    fallocate -l 2G /swapfile
+    chmod 600 /swapfile
+    mkswap /swapfile
+    swapon /swapfile
+    echo '/swapfile none swap sw 0 0' >> /etc/fstab
+    ```
+  </Step>
+
+  <Step title="Verify the gateway">
+    ```bash
+    quantumclaw status
+    systemctl --user status quantumclaw-gateway.service
+    journalctl --user -u quantumclaw-gateway.service -f
+    ```
+  </Step>
+
+  <Step title="Access the Control UI">
+    The gateway binds to loopback by default. Pick one of these options.
+
+    **Option A: SSH tunnel (simplest)**
+
+    ```bash
+    # From your local machine
+    ssh -L 18789:localhost:18789 root@YOUR_DROPLET_IP
+    ```
+
+    Then open `http://localhost:18789`.
+
+    **Option B: Tailscale Serve**
+
+    ```bash
+    curl -fsSL https://tailscale.com/install.sh | sh
+    tailscale up
+    quantumclaw config set gateway.tailscale.mode serve
+    quantumclaw gateway restart
+    ```
+
+    Then open `https://<magicdns>/` from any device on your tailnet.
+
+    **Option C: Tailnet bind (no Serve)**
+
+    ```bash
+    quantumclaw config set gateway.bind tailnet
+    quantumclaw gateway restart
+    ```
+
+    Then open `http://<tailscale-ip>:18789` (token required).
+
+  </Step>
+</Steps>
+
+## Troubleshooting
+
+**Gateway will not start** -- Run `quantumclaw doctor --non-interactive` and check logs with `journalctl --user -u quantumclaw-gateway.service -n 50`.
+
+**Port already in use** -- Run `lsof -i :18789` to find the process, then stop it.
+
+**Out of memory** -- Verify swap is active with `free -h`. If still hitting OOM, use API-based models (Claude, GPT) rather than local models, or upgrade to a 2 GB Droplet.
+
+## Next steps
+
+- [Channels](/channels) -- connect Telegram, WhatsApp, Discord, and more
+- [Gateway configuration](/gateway/configuration) -- all config options
+- [Updating](/install/updating) -- keep QuantumClaw up to date

package/docs/install/docker-vm-runtime.md

@@ -0,0 +1,142 @@
+---
+summary: "Shared Docker VM runtime steps for long-lived QuantumClaw Gateway hosts"
+read_when:
+  - You are deploying QuantumClaw on a cloud VM with Docker
+  - You need the shared binary bake, persistence, and update flow
+title: "Docker VM Runtime"
+---
+
+# Docker VM Runtime
+
+Shared runtime steps for VM-based Docker installs such as GCP, Hetzner, and similar VPS providers.
+
+## Bake required binaries into the image
+
+Installing binaries inside a running container is a trap.
+Anything installed at runtime will be lost on restart.
+
+All external binaries required by skills must be installed at image build time.
+
+The examples below show three common binaries only:
+
+- `gog` for Gmail access
+- `goplaces` for Google Places
+- `wacli` for WhatsApp
+
+These are examples, not a complete list.
+You may install as many binaries as needed using the same pattern.
+
+If you add new skills later that depend on additional binaries, you must:
+
+1. Update the Dockerfile
+2. Rebuild the image
+3. Restart the containers
+
+**Example Dockerfile**
+
+```dockerfile
+FROM node:24-bookworm
+
+RUN apt-get update && apt-get install -y socat && rm -rf /var/lib/apt/lists/*
+
+# Example binary 1: Gmail CLI
+RUN curl -L https://github.com/steipete/gog/releases/latest/download/gog_Linux_x86_64.tar.gz \
+  | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/gog
+
+# Example binary 2: Google Places CLI
+RUN curl -L https://github.com/steipete/goplaces/releases/latest/download/goplaces_Linux_x86_64.tar.gz \
+  | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/goplaces
+
+# Example binary 3: WhatsApp CLI
+RUN curl -L https://github.com/steipete/wacli/releases/latest/download/wacli_Linux_x86_64.tar.gz \
+  | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/wacli
+
+# Add more binaries below using the same pattern
+
+WORKDIR /app
+COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
+COPY ui/package.json ./ui/package.json
+COPY scripts ./scripts
+
+RUN corepack enable
+RUN pnpm install --frozen-lockfile
+
+COPY . .
+RUN pnpm build
+RUN pnpm ui:install
+RUN pnpm ui:build
+
+ENV NODE_ENV=production
+
+CMD ["node","dist/index.js"]
+```
+
+<Note>
+The download URLs above are for x86_64 (amd64). For ARM-based VMs (e.g. Hetzner ARM, GCP Tau T2A), replace the download URLs with the appropriate ARM64 variants from each tool's release page.
+</Note>
+
+## Build and launch
+
+```bash
+docker compose build
+docker compose up -d quantumclaw-gateway
+```
+
+If build fails with `Killed` or `exit code 137` during `pnpm install --frozen-lockfile`, the VM is out of memory.
+Use a larger machine class before retrying.
+
+Verify binaries:
+
+```bash
+docker compose exec quantumclaw-gateway which gog
+docker compose exec quantumclaw-gateway which goplaces
+docker compose exec quantumclaw-gateway which wacli
+```
+
+Expected output:
+
+```
+/usr/local/bin/gog
+/usr/local/bin/goplaces
+/usr/local/bin/wacli
+```
+
+Verify Gateway:
+
+```bash
+docker compose logs -f quantumclaw-gateway
+```
+
+Expected output:
+
+```
+[gateway] listening on ws://0.0.0.0:18789
+```
+
+## What persists where
+
+QuantumClaw runs in Docker, but Docker is not the source of truth.
+All long-lived state must survive restarts, rebuilds, and reboots.
+
+| Component           | Location                          | Persistence mechanism  | Notes                            |
+| ------------------- | --------------------------------- | ---------------------- | -------------------------------- |
+| Gateway config      | `/home/node/.quantumclaw/`           | Host volume mount      | Includes `quantumclaw.json`, tokens |
+| Model auth profiles | `/home/node/.quantumclaw/`           | Host volume mount      | OAuth tokens, API keys           |
+| Skill configs       | `/home/node/.quantumclaw/skills/`    | Host volume mount      | Skill-level state                |
+| Agent workspace     | `/home/node/.quantumclaw/workspace/` | Host volume mount      | Code and agent artifacts         |
+| WhatsApp session    | `/home/node/.quantumclaw/`           | Host volume mount      | Preserves QR login               |
+| Gmail keyring       | `/home/node/.quantumclaw/`           | Host volume + password | Requires `GOG_KEYRING_PASSWORD`  |
+| External binaries   | `/usr/local/bin/`                 | Docker image           | Must be baked at build time      |
+| Node runtime        | Container filesystem              | Docker image           | Rebuilt every image build        |
+| OS packages         | Container filesystem              | Docker image           | Do not install at runtime        |
+| Docker container    | Ephemeral                         | Restartable            | Safe to destroy                  |
+
+## Updates
+
+To update QuantumClaw on the VM:
+
+```bash
+git pull
+docker compose build
+docker compose up -d
+```