@quantumclaw/quantumclaw 2026.3.22

package/docs/install/migrating-matrix.md

@@ -0,0 +1,346 @@
+---
+summary: "How QuantumClaw upgrades the previous Matrix plugin in place, including encrypted-state recovery limits and manual recovery steps."
+read_when:
+  - Upgrading an existing Matrix installation
+  - Migrating encrypted Matrix history and device state
+title: "Matrix migration"
+---
+
+# Matrix migration
+
+This page covers upgrades from the previous public `matrix` plugin to the current implementation.
+
+For most users, the upgrade is in place:
+
+- the plugin stays `@quantumclaw/matrix`
+- the channel stays `matrix`
+- your config stays under `channels.matrix`
+- cached credentials stay under `~/.quantumclaw/credentials/matrix/`
+- runtime state stays under `~/.quantumclaw/matrix/`
+
+You do not need to rename config keys or reinstall the plugin under a new name.
+
+## What the migration does automatically
+
+When the gateway starts, and when you run [`quantumclaw doctor --fix`](/gateway/doctor), QuantumClaw tries to repair old Matrix state automatically.
+Before any actionable Matrix migration step mutates on-disk state, QuantumClaw creates or reuses a focused recovery snapshot.
+
+When you use `quantumclaw update`, the exact trigger depends on how QuantumClaw is installed:
+
+- source installs run `quantumclaw doctor --fix` during the update flow, then restart the gateway by default
+- package-manager installs update the package, run a non-interactive doctor pass, then rely on the default gateway restart so startup can finish Matrix migration
+- if you use `quantumclaw update --no-restart`, startup-backed Matrix migration is deferred until you later run `quantumclaw doctor --fix` and restart the gateway
+
+Automatic migration covers:
+
+- creating or reusing a pre-migration snapshot under `~/Backups/quantumclaw-migrations/`
+- reusing your cached Matrix credentials
+- keeping the same account selection and `channels.matrix` config
+- moving the oldest flat Matrix sync store into the current account-scoped location
+- moving the oldest flat Matrix crypto store into the current account-scoped location when the target account can be resolved safely
+- extracting a previously saved Matrix room-key backup decryption key from the old rust crypto store, when that key exists locally
+- reusing the most complete existing token-hash storage root for the same Matrix account, homeserver, and user when the access token changes later
+- scanning sibling token-hash storage roots for pending encrypted-state restore metadata when the Matrix access token changed but the account/device identity stayed the same
+- restoring backed-up room keys into the new crypto store on the next Matrix startup
+
+Snapshot details:
+
+- QuantumClaw writes a marker file at `~/.quantumclaw/matrix/migration-snapshot.json` after a successful snapshot so later startup and repair passes can reuse the same archive.
+- These automatic Matrix migration snapshots back up config + state only (`includeWorkspace: false`).
+- If Matrix only has warning-only migration state, for example because `userId` or `accessToken` is still missing, QuantumClaw does not create the snapshot yet because no Matrix mutation is actionable.
+- If the snapshot step fails, QuantumClaw skips Matrix migration for that run instead of mutating state without a recovery point.
+
+About multi-account upgrades:
+
+- the oldest flat Matrix store (`~/.quantumclaw/matrix/bot-storage.json` and `~/.quantumclaw/matrix/crypto/`) came from a single-store layout, so QuantumClaw can only migrate it into one resolved Matrix account target
+- already account-scoped legacy Matrix stores are detected and prepared per configured Matrix account
+
+## What the migration cannot do automatically
+
+The previous public Matrix plugin did **not** automatically create Matrix room-key backups. It persisted local crypto state and requested device verification, but it did not guarantee that your room keys were backed up to the homeserver.
+
+That means some encrypted installs can only be migrated partially.
+
+QuantumClaw cannot automatically recover:
+
+- local-only room keys that were never backed up
+- encrypted state when the target Matrix account cannot be resolved yet because `homeserver`, `userId`, or `accessToken` are still unavailable
+- automatic migration of one shared flat Matrix store when multiple Matrix accounts are configured but `channels.matrix.defaultAccount` is not set
+- custom plugin path installs that are pinned to a repo path instead of the standard Matrix package
+- a missing recovery key when the old store had backed-up keys but did not keep the decryption key locally
+
+Current warning scope:
+
+- custom Matrix plugin path installs are surfaced by both gateway startup and `quantumclaw doctor`
+
+If your old installation had local-only encrypted history that was never backed up, some older encrypted messages may remain unreadable after the upgrade.
+
+## Recommended upgrade flow
+
+1. Update QuantumClaw and the Matrix plugin normally.
+   Prefer plain `quantumclaw update` without `--no-restart` so startup can finish the Matrix migration immediately.
+2. Run:
+
+   ```bash
+   quantumclaw doctor --fix
+   ```
+
+   If Matrix has actionable migration work, doctor will create or reuse the pre-migration snapshot first and print the archive path.
+
+3. Start or restart the gateway.
+4. Check current verification and backup state:
+
+   ```bash
+   quantumclaw matrix verify status
+   quantumclaw matrix verify backup status
+   ```
+
+5. If QuantumClaw tells you a recovery key is needed, run:
+
+   ```bash
+   quantumclaw matrix verify backup restore --recovery-key "<your-recovery-key>"
+   ```
+
+6. If this device is still unverified, run:
+
+   ```bash
+   quantumclaw matrix verify device "<your-recovery-key>"
+   ```
+
+7. If you are intentionally abandoning unrecoverable old history and want a fresh backup baseline for future messages, run:
+
+   ```bash
+   quantumclaw matrix verify backup reset --yes
+   ```
+
+8. If no server-side key backup exists yet, create one for future recoveries:
+
+   ```bash
+   quantumclaw matrix verify bootstrap
+   ```
+
+## How encrypted migration works
+
+Encrypted migration is a two-stage process:
+
+1. Startup or `quantumclaw doctor --fix` creates or reuses the pre-migration snapshot if encrypted migration is actionable.
+2. Startup or `quantumclaw doctor --fix` inspects the old Matrix crypto store through the active Matrix plugin install.
+3. If a backup decryption key is found, QuantumClaw writes it into the new recovery-key flow and marks room-key restore as pending.
+4. On the next Matrix startup, QuantumClaw restores backed-up room keys into the new crypto store automatically.
+
+If the old store reports room keys that were never backed up, QuantumClaw warns instead of pretending recovery succeeded.
+
+## Common messages and what they mean
+
+### Upgrade and detection messages
+
+`Matrix plugin upgraded in place.`
+
+- Meaning: the old on-disk Matrix state was detected and migrated into the current layout.
+- What to do: nothing unless the same output also includes warnings.
+
+`Matrix migration snapshot created before applying Matrix upgrades.`
+
+- Meaning: QuantumClaw created a recovery archive before mutating Matrix state.
+- What to do: keep the printed archive path until you confirm migration succeeded.
+
+`Matrix migration snapshot reused before applying Matrix upgrades.`
+
+- Meaning: QuantumClaw found an existing Matrix migration snapshot marker and reused that archive instead of creating a duplicate backup.
+- What to do: keep the printed archive path until you confirm migration succeeded.
+
+`Legacy Matrix state detected at ... but channels.matrix is not configured yet.`
+
+- Meaning: old Matrix state exists, but QuantumClaw cannot map it to a current Matrix account because Matrix is not configured.
+- What to do: configure `channels.matrix`, then rerun `quantumclaw doctor --fix` or restart the gateway.
+
+`Legacy Matrix state detected at ... but the new account-scoped target could not be resolved yet (need homeserver, userId, and access token for channels.matrix...).`
+
+- Meaning: QuantumClaw found old state, but it still cannot determine the exact current account/device root.
+- What to do: start the gateway once with a working Matrix login, or rerun `quantumclaw doctor --fix` after cached credentials exist.
+
+`Legacy Matrix state detected at ... but multiple Matrix accounts are configured and channels.matrix.defaultAccount is not set.`
+
+- Meaning: QuantumClaw found one shared flat Matrix store, but it refuses to guess which named Matrix account should receive it.
+- What to do: set `channels.matrix.defaultAccount` to the intended account, then rerun `quantumclaw doctor --fix` or restart the gateway.
+
+`Matrix legacy sync store not migrated because the target already exists (...)`
+
+- Meaning: the new account-scoped location already has a sync or crypto store, so QuantumClaw did not overwrite it automatically.
+- What to do: verify that the current account is the correct one before manually removing or moving the conflicting target.
+
+`Failed migrating Matrix legacy sync store (...)` or `Failed migrating Matrix legacy crypto store (...)`
+
+- Meaning: QuantumClaw tried to move old Matrix state but the filesystem operation failed.
+- What to do: inspect filesystem permissions and disk state, then rerun `quantumclaw doctor --fix`.
+
+`Legacy Matrix encrypted state detected at ... but channels.matrix is not configured yet.`
+
+- Meaning: QuantumClaw found an old encrypted Matrix store, but there is no current Matrix config to attach it to.
+- What to do: configure `channels.matrix`, then rerun `quantumclaw doctor --fix` or restart the gateway.
+
+`Legacy Matrix encrypted state detected at ... but the account-scoped target could not be resolved yet (need homeserver, userId, and access token for channels.matrix...).`
+
+- Meaning: the encrypted store exists, but QuantumClaw cannot safely decide which current account/device it belongs to.
+- What to do: start the gateway once with a working Matrix login, or rerun `quantumclaw doctor --fix` after cached credentials are available.
+
+`Legacy Matrix encrypted state detected at ... but multiple Matrix accounts are configured and channels.matrix.defaultAccount is not set.`
+
+- Meaning: QuantumClaw found one shared flat legacy crypto store, but it refuses to guess which named Matrix account should receive it.
+- What to do: set `channels.matrix.defaultAccount` to the intended account, then rerun `quantumclaw doctor --fix` or restart the gateway.
+
+`Matrix migration warnings are present, but no on-disk Matrix mutation is actionable yet. No pre-migration snapshot was needed.`
+
+- Meaning: QuantumClaw detected old Matrix state, but the migration is still blocked on missing identity or credential data.
+- What to do: finish Matrix login or config setup, then rerun `quantumclaw doctor --fix` or restart the gateway.
+
+`Legacy Matrix encrypted state was detected, but the Matrix plugin helper is unavailable. Install or repair @quantumclaw/matrix so QuantumClaw can inspect the old rust crypto store before upgrading.`
+
+- Meaning: QuantumClaw found old encrypted Matrix state, but it could not load the helper entrypoint from the Matrix plugin that normally inspects that store.
+- What to do: reinstall or repair the Matrix plugin (`quantumclaw plugins install @quantumclaw/matrix`, or `quantumclaw plugins install ./extensions/matrix` for a repo checkout), then rerun `quantumclaw doctor --fix` or restart the gateway.
+
+`Matrix plugin helper path is unsafe: ... Reinstall @quantumclaw/matrix and try again.`
+
+- Meaning: QuantumClaw found a helper file path that escapes the plugin root or fails plugin boundary checks, so it refused to import it.
+- What to do: reinstall the Matrix plugin from a trusted path, then rerun `quantumclaw doctor --fix` or restart the gateway.
+
+`- Failed creating a Matrix migration snapshot before repair: ...`
+
+`- Skipping Matrix migration changes for now. Resolve the snapshot failure, then rerun "quantumclaw doctor --fix".`
+
+- Meaning: QuantumClaw refused to mutate Matrix state because it could not create the recovery snapshot first.
+- What to do: resolve the backup error, then rerun `quantumclaw doctor --fix` or restart the gateway.
+
+`Failed migrating legacy Matrix client storage: ...`
+
+- Meaning: the Matrix client-side fallback found old flat storage, but the move failed. QuantumClaw now aborts that fallback instead of silently starting with a fresh store.
+- What to do: inspect filesystem permissions or conflicts, keep the old state intact, and retry after fixing the error.
+
+`Matrix is installed from a custom path: ...`
+
+- Meaning: Matrix is pinned to a path install, so mainline updates do not automatically replace it with the repo's standard Matrix package.
+- What to do: reinstall with `quantumclaw plugins install @quantumclaw/matrix` when you want to return to the default Matrix plugin.
+
+### Encrypted-state recovery messages
+
+`matrix: restored X/Y room key(s) from legacy encrypted-state backup`
+
+- Meaning: backed-up room keys were restored successfully into the new crypto store.
+- What to do: usually nothing.
+
+`matrix: N legacy local-only room key(s) were never backed up and could not be restored automatically`
+
+- Meaning: some old room keys existed only in the old local store and had never been uploaded to Matrix backup.
+- What to do: expect some old encrypted history to remain unavailable unless you can recover those keys manually from another verified client.
+
+`Legacy Matrix encrypted state for account "..." has backed-up room keys, but no local backup decryption key was found. Ask the operator to run "quantumclaw matrix verify backup restore --recovery-key <key>" after upgrade if they have the recovery key.`
+
+- Meaning: backup exists, but QuantumClaw could not recover the recovery key automatically.
+- What to do: run `quantumclaw matrix verify backup restore --recovery-key "<your-recovery-key>"`.
+
+`Failed inspecting legacy Matrix encrypted state for account "..." (...): ...`
+
+- Meaning: QuantumClaw found the old encrypted store, but it could not inspect it safely enough to prepare recovery.
+- What to do: rerun `quantumclaw doctor --fix`. If it repeats, keep the old state directory intact and recover using another verified Matrix client plus `quantumclaw matrix verify backup restore --recovery-key "<your-recovery-key>"`.
+
+`Legacy Matrix backup key was found for account "...", but .../recovery-key.json already contains a different recovery key. Leaving the existing file unchanged.`
+
+- Meaning: QuantumClaw detected a backup key conflict and refused to overwrite the current recovery-key file automatically.
+- What to do: verify which recovery key is correct before retrying any restore command.
+
+`Legacy Matrix encrypted state for account "..." cannot be fully converted automatically because the old rust crypto store does not expose all local room keys for export.`
+
+- Meaning: this is the hard limit of the old storage format.
+- What to do: backed-up keys can still be restored, but local-only encrypted history may remain unavailable.
+
+`matrix: failed restoring room keys from legacy encrypted-state backup: ...`
+
+- Meaning: the new plugin attempted restore but Matrix returned an error.
+- What to do: run `quantumclaw matrix verify backup status`, then retry with `quantumclaw matrix verify backup restore --recovery-key "<your-recovery-key>"` if needed.
+
+### Manual recovery messages
+
+`Backup key is not loaded on this device. Run 'quantumclaw matrix verify backup restore' to load it and restore old room keys.`
+
+- Meaning: QuantumClaw knows you should have a backup key, but it is not active on this device.
+- What to do: run `quantumclaw matrix verify backup restore`, or pass `--recovery-key` if needed.
+
+`Store a recovery key with 'quantumclaw matrix verify device <key>', then run 'quantumclaw matrix verify backup restore'.`
+
+- Meaning: this device does not currently have the recovery key stored.
+- What to do: verify the device with your recovery key first, then restore the backup.
+
+`Backup key mismatch on this device. Re-run 'quantumclaw matrix verify device <key>' with the matching recovery key.`
+
+- Meaning: the stored key does not match the active Matrix backup.
+- What to do: rerun `quantumclaw matrix verify device "<your-recovery-key>"` with the correct key.
+
+If you accept losing unrecoverable old encrypted history, you can instead reset the current backup baseline with `quantumclaw matrix verify backup reset --yes`.
+
+`Backup trust chain is not verified on this device. Re-run 'quantumclaw matrix verify device <key>'.`
+
+- Meaning: the backup exists, but this device does not trust the cross-signing chain strongly enough yet.
+- What to do: rerun `quantumclaw matrix verify device "<your-recovery-key>"`.
+
+`Matrix recovery key is required`
+
+- Meaning: you tried a recovery step without supplying a recovery key when one was required.
+- What to do: rerun the command with your recovery key.
+
+`Invalid Matrix recovery key: ...`
+
+- Meaning: the provided key could not be parsed or did not match the expected format.
+- What to do: retry with the exact recovery key from your Matrix client or recovery-key file.
+
+`Matrix device is still unverified after applying recovery key. Verify your recovery key and ensure cross-signing is available.`
+
+- Meaning: the key was applied, but the device still could not complete verification.
+- What to do: confirm you used the correct key and that cross-signing is available on the account, then retry.
+
+`Matrix key backup is not active on this device after loading from secret storage.`
+
+- Meaning: secret storage did not produce an active backup session on this device.
+- What to do: verify the device first, then recheck with `quantumclaw matrix verify backup status`.
+
+`Matrix crypto backend cannot load backup keys from secret storage. Verify this device with 'quantumclaw matrix verify device <key>' first.`
+
+- Meaning: this device cannot restore from secret storage until device verification is complete.
+- What to do: run `quantumclaw matrix verify device "<your-recovery-key>"` first.
+
+### Custom plugin install messages
+
+`Matrix is installed from a custom path that no longer exists: ...`
+
+- Meaning: your plugin install record points at a local path that is gone.
+- What to do: reinstall with `quantumclaw plugins install @quantumclaw/matrix`, or if you are running from a repo checkout, `quantumclaw plugins install ./extensions/matrix`.
+
+## If encrypted history still does not come back
+
+Run these checks in order:
+
+```bash
+quantumclaw matrix verify status --verbose
+quantumclaw matrix verify backup status --verbose
+quantumclaw matrix verify backup restore --recovery-key "<your-recovery-key>" --verbose
+```
+
+If the backup restores successfully but some old rooms are still missing history, those missing keys were probably never backed up by the previous plugin.
+
+## If you want to start fresh for future messages
+
+If you accept losing unrecoverable old encrypted history and only want a clean backup baseline going forward, run these commands in order:
+
+```bash
+quantumclaw matrix verify backup reset --yes
+quantumclaw matrix verify backup status --verbose
+quantumclaw matrix verify status
+```
+
+If the device is still unverified after that, finish verification from your Matrix client by comparing the SAS emoji or decimal codes and confirming that they match.
+
+## Related pages
+
+- [Matrix](/channels/matrix)
+- [Doctor](/gateway/doctor)
+- [Migrating](/install/migrating)
+- [Plugins](/tools/plugin)

package/docs/install/migrating.md

@@ -0,0 +1,110 @@
+---
+summary: "Move (migrate) an QuantumClaw install from one machine to another"
+read_when:
+  - You are moving QuantumClaw to a new laptop/server
+  - You want to preserve sessions, auth, and channel logins (WhatsApp, etc.)
+title: "Migration Guide"
+---
+
+# Migrating QuantumClaw to a New Machine
+
+This guide moves an QuantumClaw gateway to a new machine without redoing onboarding.
+
+## What Gets Migrated
+
+When you copy the **state directory** (`~/.quantumclaw/` by default) and your **workspace**, you preserve:
+
+- **Config** -- `quantumclaw.json` and all gateway settings
+- **Auth** -- API keys, OAuth tokens, credential profiles
+- **Sessions** -- conversation history and agent state
+- **Channel state** -- WhatsApp login, Telegram session, etc.
+- **Workspace files** -- `MEMORY.md`, `USER.md`, skills, and prompts
+
+<Tip>
+Run `quantumclaw status` on the old machine to confirm your state directory path.
+Custom profiles use `~/.quantumclaw-<profile>/` or a path set via `QUANTUMCLAW_STATE_DIR`.
+</Tip>
+
+## Migration Steps
+
+<Steps>
+  <Step title="Stop the gateway and back up">
+    On the **old** machine, stop the gateway so files are not changing mid-copy, then archive:
+
+    ```bash
+    quantumclaw gateway stop
+    cd ~
+    tar -czf quantumclaw-state.tgz .quantumclaw
+    ```
+
+    If you use multiple profiles (e.g. `~/.quantumclaw-work`), archive each separately.
+
+  </Step>
+
+  <Step title="Install QuantumClaw on the new machine">
+    [Install](/install) the CLI (and Node if needed) on the new machine.
+    It is fine if onboarding creates a fresh `~/.quantumclaw/` -- you will overwrite it next.
+  </Step>
+
+  <Step title="Copy state directory and workspace">
+    Transfer the archive via `scp`, `rsync -a`, or an external drive, then extract:
+
+    ```bash
+    cd ~
+    tar -xzf quantumclaw-state.tgz
+    ```
+
+    Ensure hidden directories were included and file ownership matches the user that will run the gateway.
+
+  </Step>
+
+  <Step title="Run doctor and verify">
+    On the new machine, run [Doctor](/gateway/doctor) to apply config migrations and repair services:
+
+    ```bash
+    quantumclaw doctor
+    quantumclaw gateway restart
+    quantumclaw status
+    ```
+
+  </Step>
+</Steps>
+
+## Common Pitfalls
+
+<AccordionGroup>
+  <Accordion title="Profile or state-dir mismatch">
+    If the old gateway used `--profile` or `QUANTUMCLAW_STATE_DIR` and the new one does not,
+    channels will appear logged out and sessions will be empty.
+    Launch the gateway with the **same** profile or state-dir you migrated, then rerun `quantumclaw doctor`.
+  </Accordion>
+
+  <Accordion title="Copying only quantumclaw.json">
+    The config file alone is not enough. Credentials live under `credentials/`, and agent
+    state lives under `agents/`. Always migrate the **entire** state directory.
+  </Accordion>
+
+  <Accordion title="Permissions and ownership">
+    If you copied as root or switched users, the gateway may fail to read credentials.
+    Ensure the state directory and workspace are owned by the user running the gateway.
+  </Accordion>
+
+  <Accordion title="Remote mode">
+    If your UI points at a **remote** gateway, the remote host owns sessions and workspace.
+    Migrate the gateway host itself, not your local laptop. See [FAQ](/help/faq#where-does-quantumclaw-store-its-data).
+  </Accordion>
+
+  <Accordion title="Secrets in backups">
+    The state directory contains API keys, OAuth tokens, and channel credentials.
+    Store backups encrypted, avoid insecure transfer channels, and rotate keys if you suspect exposure.
+  </Accordion>
+</AccordionGroup>
+
+## Verification Checklist
+
+On the new machine, confirm:
+
+- [ ] `quantumclaw status` shows the gateway running
+- [ ] Channels are still connected (no re-pairing needed)
+- [ ] The dashboard opens and shows existing sessions
+- [ ] Workspace files (memory, configs) are present

package/docs/install/nix.md

@@ -0,0 +1,89 @@
+---
+summary: "Install QuantumClaw 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
+title: "Nix"
+---
+
+# Nix Installation
+
+Install QuantumClaw declaratively with **[nix-quantumclaw](https://github.com/quantumclaw/nix-quantumclaw)** -- a batteries-included Home Manager module.
+
+<Info>
+The [nix-quantumclaw](https://github.com/quantumclaw/nix-quantumclaw) repo is the source of truth for Nix installation. This page is a quick overview.
+</Info>
+
+## 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`
+
+## Quick Start
+
+<Steps>
+  <Step title="Install Determinate Nix">
+    If Nix is not already installed, follow the [Determinate Nix installer](https://github.com/DeterminateSystems/nix-installer) instructions.
+  </Step>
+  <Step title="Create a local flake">
+    Use the agent-first template from the nix-quantumclaw repo:
+    ```bash
+    mkdir -p ~/code/quantumclaw-local
+    # Copy templates/agent-first/flake.nix from the nix-quantumclaw repo
+    ```
+  </Step>
+  <Step title="Configure secrets">
+    Set up your messaging bot token and model provider API key. Plain files at `~/.secrets/` work fine.
+  </Step>
+  <Step title="Fill in template placeholders and switch">
+    ```bash
+    home-manager switch
+    ```
+  </Step>
+  <Step title="Verify">
+    Confirm the launchd service is running and your bot responds to messages.
+  </Step>
+</Steps>
+
+See the [nix-quantumclaw README](https://github.com/quantumclaw/nix-quantumclaw) for full module options and examples.
+
+## Nix Mode Runtime Behavior
+
+When `QUANTUMCLAW_NIX_MODE=1` is set (automatic with nix-quantumclaw), QuantumClaw enters a deterministic mode that disables auto-install flows.
+
+You can also set it manually:
+
+```bash
+export QUANTUMCLAW_NIX_MODE=1
+```
+
+On macOS, the GUI app does not automatically inherit shell environment variables. Enable Nix mode via defaults instead:
+
+```bash
+defaults write ai.quantumclaw.mac quantumclaw.nixMode -bool true
+```
+
+### What changes 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
+
+### Config and state paths
+
+QuantumClaw reads JSON5 config from `QUANTUMCLAW_CONFIG_PATH` and stores mutable data in `QUANTUMCLAW_STATE_DIR`. When running under Nix, set these explicitly to Nix-managed locations so runtime state and config stay out of the immutable store.
+
+| Variable               | Default                                 |
+| ---------------------- | --------------------------------------- |
+| `QUANTUMCLAW_HOME`        | `HOME` / `USERPROFILE` / `os.homedir()` |
+| `QUANTUMCLAW_STATE_DIR`   | `~/.quantumclaw`                           |
+| `QUANTUMCLAW_CONFIG_PATH` | `$QUANTUMCLAW_STATE_DIR/quantumclaw.json`     |
+
+## Related
+
+- [nix-quantumclaw](https://github.com/quantumclaw/nix-quantumclaw) -- full setup guide
+- [Wizard](/start/wizard) -- non-Nix CLI setup
+- [Docker](/install/docker) -- containerized setup

package/docs/install/node.md

@@ -0,0 +1,138 @@
+---
+title: "Node.js"
+summary: "Install and configure Node.js for QuantumClaw — version requirements, install options, and PATH troubleshooting"
+read_when:
+  - "You need to install Node.js before installing QuantumClaw"
+  - "You installed QuantumClaw but `quantumclaw` is command not found"
+  - "npm install -g fails with permissions or PATH issues"
+---
+
+# Node.js
+
+QuantumClaw requires **Node 22.16 or newer**. **Node 24 is the default and recommended runtime** for installs, CI, and release workflows. Node 22 remains supported via the active LTS line. The [installer script](/install#alternative-install-methods) will detect and install Node automatically — this page is for when you want to set up Node yourself and make sure everything is wired up correctly (versions, PATH, global installs).
+
+## Check your version
+
+```bash
+node -v
+```
+
+If this prints `v24.x.x` or higher, you're on the recommended default. If it prints `v22.16.x` or higher, you're on the supported Node 22 LTS path, but we still recommend upgrading to Node 24 when convenient. If Node isn't installed or the version is too old, pick an install method below.
+
+## Install Node
+
+<Tabs>
+  <Tab title="macOS">
+    **Homebrew** (recommended):
+
+    ```bash
+    brew install node
+    ```
+
+    Or download the macOS installer from [nodejs.org](https://nodejs.org/).
+
+  </Tab>
+  <Tab title="Linux">
+    **Ubuntu / Debian:**
+
+    ```bash
+    curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
+    sudo apt-get install -y nodejs
+    ```
+
+    **Fedora / RHEL:**
+
+    ```bash
+    sudo dnf install nodejs
+    ```
+
+    Or use a version manager (see below).
+
+  </Tab>
+  <Tab title="Windows">
+    **winget** (recommended):
+
+    ```powershell
+    winget install OpenJS.NodeJS.LTS
+    ```
+
+    **Chocolatey:**
+
+    ```powershell
+    choco install nodejs-lts
+    ```
+
+    Or download the Windows installer from [nodejs.org](https://nodejs.org/).
+
+  </Tab>
+</Tabs>
+
+<Accordion title="Using a version manager (nvm, fnm, mise, asdf)">
+  Version managers let you switch between Node versions easily. Popular options:
+
+- [**fnm**](https://github.com/Schniz/fnm) — fast, cross-platform
+- [**nvm**](https://github.com/nvm-sh/nvm) — widely used on macOS/Linux
+- [**mise**](https://mise.jdx.dev/) — polyglot (Node, Python, Ruby, etc.)
+
+Example with fnm:
+
+```bash
+fnm install 24
+fnm use 24
+```
+
+  <Warning>
+  Make sure your version manager is initialized in your shell startup file (`~/.zshrc` or `~/.bashrc`). If it isn't, `quantumclaw` may not be found in new terminal sessions because the PATH won't include Node's bin directory.
+  </Warning>
+</Accordion>
+
+## Troubleshooting
+
+### `quantumclaw: command not found`
+
+This almost always means npm's global bin directory isn't on your PATH.
+
+<Steps>
+  <Step title="Find your global npm prefix">
+    ```bash
+    npm prefix -g
+    ```
+  </Step>
+  <Step title="Check if it's on your PATH">
+    ```bash
+    echo "$PATH"
+    ```
+
+    Look for `<npm-prefix>/bin` (macOS/Linux) or `<npm-prefix>` (Windows) in the output.
+
+  </Step>
+  <Step title="Add it to your shell startup file">
+    <Tabs>
+      <Tab title="macOS / Linux">
+        Add to `~/.zshrc` or `~/.bashrc`:
+
+        ```bash
+        export PATH="$(npm prefix -g)/bin:$PATH"
+        ```
+
+        Then open a new terminal (or run `rehash` in zsh / `hash -r` in bash).
+      </Tab>
+      <Tab title="Windows">
+        Add the output of `npm prefix -g` to your system PATH via Settings → System → Environment Variables.
+      </Tab>
+    </Tabs>
+
+  </Step>
+</Steps>
+
+### Permission errors on `npm install -g` (Linux)
+
+If you see `EACCES` errors, 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"
+```
+
+Add the `export PATH=...` line to your `~/.bashrc` or `~/.zshrc` to make it permanent.