@quantumclaw/quantumclaw 2026.3.22

package/docs/cli/configure.md

@@ -0,0 +1,36 @@
+---
+summary: "CLI reference for `quantumclaw configure` (interactive configuration prompts)"
+read_when:
+  - You want to tweak credentials, devices, or agent defaults interactively
+title: "configure"
+---
+
+# `quantumclaw configure`
+
+Interactive prompt to set up credentials, devices, and agent defaults.
+
+Note: The **Model** section now includes a multi-select for the
+`agents.defaults.models` allowlist (what shows up in `/model` and the model picker).
+
+Tip: `quantumclaw config` without a subcommand opens the same wizard. Use
+`quantumclaw config get|set|unset` for non-interactive edits.
+
+Related:
+
+- Gateway configuration reference: [Configuration](/gateway/configuration)
+- Config CLI: [Config](/cli/config)
+
+Notes:
+
+- Choosing where the Gateway runs always updates `gateway.mode`. You can select "Continue" without other sections if that is all you need.
+- Channel-oriented services (Slack/Discord/Matrix/Microsoft Teams) prompt for channel/room allowlists during setup. You can enter names or IDs; the wizard resolves names to IDs when possible.
+- If you run the daemon install step, token auth requires a token, and `gateway.auth.token` is SecretRef-managed, configure validates the SecretRef but does not persist resolved plaintext token values into supervisor service environment metadata.
+- If token auth requires a token and the configured token SecretRef is unresolved, configure blocks daemon install with actionable remediation guidance.
+- If both `gateway.auth.token` and `gateway.auth.password` are configured and `gateway.auth.mode` is unset, configure blocks daemon install until mode is set explicitly.
+
+## Examples
+
+```bash
+quantumclaw configure
+quantumclaw configure --section model --section channels
+```

package/docs/cli/cron.md

@@ -0,0 +1,77 @@
+---
+summary: "CLI reference for `quantumclaw cron` (schedule and run background jobs)"
+read_when:
+  - You want scheduled jobs and wakeups
+  - You’re debugging cron execution and logs
+title: "cron"
+---
+
+# `quantumclaw cron`
+
+Manage cron jobs for the Gateway scheduler.
+
+Related:
+
+- Cron jobs: [Cron jobs](/automation/cron-jobs)
+
+Tip: run `quantumclaw cron --help` for the full command surface.
+
+Note: isolated `cron add` jobs default to `--announce` delivery. Use `--no-deliver` to keep
+output internal. `--deliver` remains as a deprecated alias for `--announce`.
+
+Note: one-shot (`--at`) jobs delete after success by default. Use `--keep-after-run` to keep them.
+
+Note: recurring jobs now use exponential retry backoff after consecutive errors (30s → 1m → 5m → 15m → 60m), then return to normal schedule after the next successful run.
+
+Note: `quantumclaw cron run` now returns as soon as the manual run is queued for execution. Successful responses include `{ ok: true, enqueued: true, runId }`; use `quantumclaw cron runs --id <job-id>` to follow the eventual outcome.
+
+Note: retention/pruning is controlled in config:
+
+- `cron.sessionRetention` (default `24h`) prunes completed isolated run sessions.
+- `cron.runLog.maxBytes` + `cron.runLog.keepLines` prune `~/.quantumclaw/cron/runs/<jobId>.jsonl`.
+
+Upgrade note: if you have older cron jobs from before the current delivery/store format, run
+`quantumclaw doctor --fix`. Doctor now normalizes legacy cron fields (`jobId`, `schedule.cron`,
+top-level delivery fields, payload `provider` delivery aliases) and migrates simple
+`notify: true` webhook fallback jobs to explicit webhook delivery when `cron.webhook` is
+configured.
+
+## Common edits
+
+Update delivery settings without changing the message:
+
+```bash
+quantumclaw cron edit <job-id> --announce --channel telegram --to "123456789"
+```
+
+Disable delivery for an isolated job:
+
+```bash
+quantumclaw cron edit <job-id> --no-deliver
+```
+
+Enable lightweight bootstrap context for an isolated job:
+
+```bash
+quantumclaw cron edit <job-id> --light-context
+```
+
+Announce to a specific channel:
+
+```bash
+quantumclaw cron edit <job-id> --announce --channel slack --to "channel:C1234567890"
+```
+
+Create an isolated job with lightweight bootstrap context:
+
+```bash
+quantumclaw cron add \
+  --name "Lightweight morning brief" \
+  --cron "0 7 * * *" \
+  --session isolated \
+  --message "Summarize overnight updates." \
+  --light-context \
+  --no-deliver
+```
+
+`--light-context` applies to isolated agent-turn jobs only. For cron runs, lightweight mode keeps bootstrap context empty instead of injecting the full workspace bootstrap set.

package/docs/cli/daemon.md

@@ -0,0 +1,53 @@
+---
+summary: "CLI reference for `quantumclaw daemon` (legacy alias for gateway service management)"
+read_when:
+  - You still use `quantumclaw daemon ...` in scripts
+  - You need service lifecycle commands (install/start/stop/restart/status)
+title: "daemon"
+---
+
+# `quantumclaw daemon`
+
+Legacy alias for Gateway service management commands.
+
+`quantumclaw daemon ...` maps to the same service control surface as `quantumclaw gateway ...` service commands.
+
+## Usage
+
+```bash
+quantumclaw daemon status
+quantumclaw daemon install
+quantumclaw daemon start
+quantumclaw daemon stop
+quantumclaw daemon restart
+quantumclaw daemon uninstall
+```
+
+## Subcommands
+
+- `status`: show service install state and probe Gateway health
+- `install`: install service (`launchd`/`systemd`/`schtasks`)
+- `uninstall`: remove service
+- `start`: start service
+- `stop`: stop service
+- `restart`: restart service
+
+## Common options
+
+- `status`: `--url`, `--token`, `--password`, `--timeout`, `--no-probe`, `--require-rpc`, `--deep`, `--json`
+- `install`: `--port`, `--runtime <node|bun>`, `--token`, `--force`, `--json`
+- lifecycle (`uninstall|start|stop|restart`): `--json`
+
+Notes:
+
+- `status` resolves configured auth SecretRefs for probe auth when possible.
+- If a required auth SecretRef is unresolved in this command path, `daemon status --json` reports `rpc.authWarning` when probe connectivity/auth fails; pass `--token`/`--password` explicitly or resolve the secret source first.
+- If the probe succeeds, unresolved auth-ref warnings are suppressed to avoid false positives.
+- On Linux systemd installs, `status` token-drift checks include both `Environment=` and `EnvironmentFile=` unit sources.
+- When token auth requires a token and `gateway.auth.token` is SecretRef-managed, `install` validates that the SecretRef is resolvable but does not persist the resolved token into service environment metadata.
+- If token auth requires a token and the configured token SecretRef is unresolved, install fails closed.
+- If both `gateway.auth.token` and `gateway.auth.password` are configured and `gateway.auth.mode` is unset, install is blocked until mode is set explicitly.
+
+## Prefer
+
+Use [`quantumclaw gateway`](/cli/gateway) for current docs and examples.

package/docs/cli/dashboard.md

@@ -0,0 +1,22 @@
+---
+summary: "CLI reference for `quantumclaw dashboard` (open the Control UI)"
+read_when:
+  - You want to open the Control UI with your current token
+  - You want to print the URL without launching a browser
+title: "dashboard"
+---
+
+# `quantumclaw dashboard`
+
+Open the Control UI using your current auth.
+
+```bash
+quantumclaw dashboard
+quantumclaw dashboard --no-open
+```
+
+Notes:
+
+- `dashboard` resolves configured `gateway.auth.token` SecretRefs when possible.
+- For SecretRef-managed tokens (resolved or unresolved), `dashboard` prints/copies/opens a non-tokenized URL to avoid exposing external secrets in terminal output, clipboard history, or browser-launch arguments.
+- If `gateway.auth.token` is SecretRef-managed but unresolved in this command path, the command prints a non-tokenized URL and explicit remediation guidance instead of embedding an invalid token placeholder.

package/docs/cli/devices.md

@@ -0,0 +1,139 @@
+---
+summary: "CLI reference for `quantumclaw devices` (device pairing + token rotation/revocation)"
+read_when:
+  - You are approving device pairing requests
+  - You need to rotate or revoke device tokens
+title: "devices"
+---
+
+# `quantumclaw devices`
+
+Manage device pairing requests and device-scoped tokens.
+
+## Commands
+
+### `quantumclaw devices list`
+
+List pending pairing requests and paired devices.
+
+```
+quantumclaw devices list
+quantumclaw devices list --json
+```
+
+Pending request output includes the requested role and scopes so approvals can
+be reviewed before you approve.
+
+### `quantumclaw devices remove <deviceId>`
+
+Remove one paired device entry.
+
+```
+quantumclaw devices remove <deviceId>
+quantumclaw devices remove <deviceId> --json
+```
+
+### `quantumclaw devices clear --yes [--pending]`
+
+Clear paired devices in bulk.
+
+```
+quantumclaw devices clear --yes
+quantumclaw devices clear --yes --pending
+quantumclaw devices clear --yes --pending --json
+```
+
+### `quantumclaw devices approve [requestId] [--latest]`
+
+Approve a pending device pairing request. If `requestId` is omitted, QuantumClaw
+automatically approves the most recent pending request.
+
+Note: if a device retries pairing with changed auth details (role/scopes/public
+key), QuantumClaw supersedes the previous pending entry and issues a new
+`requestId`. Run `quantumclaw devices list` right before approval to use the
+current ID.
+
+```
+quantumclaw devices approve
+quantumclaw devices approve <requestId>
+quantumclaw devices approve --latest
+```
+
+### `quantumclaw devices reject <requestId>`
+
+Reject a pending device pairing request.
+
+```
+quantumclaw devices reject <requestId>
+```
+
+### `quantumclaw devices rotate --device <id> --role <role> [--scope <scope...>]`
+
+Rotate a device token for a specific role (optionally updating scopes).
+
+```
+quantumclaw devices rotate --device <deviceId> --role operator --scope operator.read --scope operator.write
+```
+
+### `quantumclaw devices revoke --device <id> --role <role>`
+
+Revoke a device token for a specific role.
+
+```
+quantumclaw devices revoke --device <deviceId> --role node
+```
+
+## Common options
+
+- `--url <url>`: Gateway WebSocket URL (defaults to `gateway.remote.url` when configured).
+- `--token <token>`: Gateway token (if required).
+- `--password <password>`: Gateway password (password auth).
+- `--timeout <ms>`: RPC timeout.
+- `--json`: JSON output (recommended for scripting).
+
+Note: when you set `--url`, the CLI does not fall back to config or environment credentials.
+Pass `--token` or `--password` explicitly. Missing explicit credentials is an error.
+
+## Notes
+
+- Token rotation returns a new token (sensitive). Treat it like a secret.
+- These commands require `operator.pairing` (or `operator.admin`) scope.
+- `devices clear` is intentionally gated by `--yes`.
+- If pairing scope is unavailable on local loopback (and no explicit `--url` is passed), list/approve can use a local pairing fallback.
+
+## Token drift recovery checklist
+
+Use this when Control UI or other clients keep failing with `AUTH_TOKEN_MISMATCH` or `AUTH_DEVICE_TOKEN_MISMATCH`.
+
+1. Confirm current gateway token source:
+
+```bash
+quantumclaw config get gateway.auth.token
+```
+
+2. List paired devices and identify the affected device id:
+
+```bash
+quantumclaw devices list
+```
+
+3. Rotate operator token for the affected device:
+
+```bash
+quantumclaw devices rotate --device <deviceId> --role operator
+```
+
+4. If rotation is not enough, remove stale pairing and approve again:
+
+```bash
+quantumclaw devices remove <deviceId>
+quantumclaw devices list
+quantumclaw devices approve <requestId>
+```
+
+5. Retry client connection with the current shared token/password.
+
+Related:
+
+- [Dashboard auth troubleshooting](/web/dashboard#if-you-see-unauthorized-1008)
+- [Gateway troubleshooting](/gateway/troubleshooting#dashboard-control-ui-connectivity)

package/docs/cli/directory.md

@@ -0,0 +1,63 @@
+---
+summary: "CLI reference for `quantumclaw directory` (self, peers, groups)"
+read_when:
+  - You want to look up contacts/groups/self ids for a channel
+  - You are developing a channel directory adapter
+title: "directory"
+---
+
+# `quantumclaw directory`
+
+Directory lookups for channels that support it (contacts/peers, groups, and “me”).
+
+## Common flags
+
+- `--channel <name>`: channel id/alias (required when multiple channels are configured; auto when only one is configured)
+- `--account <id>`: account id (default: channel default)
+- `--json`: output JSON
+
+## Notes
+
+- `directory` is meant to help you find IDs you can paste into other commands (especially `quantumclaw message send --target ...`).
+- For many channels, results are config-backed (allowlists / configured groups) rather than a live provider directory.
+- Default output is `id` (and sometimes `name`) separated by a tab; use `--json` for scripting.
+
+## Using results with `message send`
+
+```bash
+quantumclaw directory peers list --channel slack --query "U0"
+quantumclaw message send --channel slack --target user:U012ABCDEF --message "hello"
+```
+
+## ID formats (by channel)
+
+- WhatsApp: `+15551234567` (DM), `1234567890-1234567890@g.us` (group)
+- Telegram: `@username` or numeric chat id; groups are numeric ids
+- Slack: `user:U…` and `channel:C…`
+- Discord: `user:<id>` and `channel:<id>`
+- Matrix (plugin): `user:@user:server`, `room:!roomId:server`, or `#alias:server`
+- Microsoft Teams (plugin): `user:<id>` and `conversation:<id>`
+- Zalo (plugin): user id (Bot API)
+- Zalo Personal / `zalouser` (plugin): thread id (DM/group) from `zca` (`me`, `friend list`, `group list`)
+
+## Self ("me")
+
+```bash
+quantumclaw directory self --channel zalouser
+```
+
+## Peers (contacts/users)
+
+```bash
+quantumclaw directory peers list --channel zalouser
+quantumclaw directory peers list --channel zalouser --query "name"
+quantumclaw directory peers list --channel zalouser --limit 50
+```
+
+## Groups
+
+```bash
+quantumclaw directory groups list --channel zalouser
+quantumclaw directory groups list --channel zalouser --query "work"
+quantumclaw directory groups members --channel zalouser --group-id <id>
+```

package/docs/cli/dns.md

@@ -0,0 +1,23 @@
+---
+summary: "CLI reference for `quantumclaw dns` (wide-area discovery helpers)"
+read_when:
+  - You want wide-area discovery (DNS-SD) via Tailscale + CoreDNS
+  - You’re setting up split DNS for a custom discovery domain (example: quantumclaw.internal)
+title: "dns"
+---
+
+# `quantumclaw dns`
+
+DNS helpers for wide-area discovery (Tailscale + CoreDNS). Currently focused on macOS + Homebrew CoreDNS.
+
+Related:
+
+- Gateway discovery: [Discovery](/gateway/discovery)
+- Wide-area discovery config: [Configuration](/gateway/configuration)
+
+## Setup
+
+```bash
+quantumclaw dns setup
+quantumclaw dns setup --apply
+```

package/docs/cli/docs.md

@@ -0,0 +1,15 @@
+---
+summary: "CLI reference for `quantumclaw docs` (search the live docs index)"
+read_when:
+  - You want to search the live QuantumClaw docs from the terminal
+title: "docs"
+---
+
+# `quantumclaw docs`
+
+Search the live docs index.
+
+```bash
+quantumclaw docs browser existing-session
+quantumclaw docs sandbox allowHostControl
+```

package/docs/cli/doctor.md

@@ -0,0 +1,48 @@
+---
+summary: "CLI reference for `quantumclaw doctor` (health checks + guided repairs)"
+read_when:
+  - You have connectivity/auth issues and want guided fixes
+  - You updated and want a sanity check
+title: "doctor"
+---
+
+# `quantumclaw doctor`
+
+Health checks + quick fixes for the gateway and channels.
+
+Related:
+
+- Troubleshooting: [Troubleshooting](/gateway/troubleshooting)
+- Security audit: [Security](/gateway/security)
+
+## Examples
+
+```bash
+quantumclaw doctor
+quantumclaw doctor --repair
+quantumclaw doctor --deep
+```
+
+Notes:
+
+- Interactive prompts (like keychain/OAuth fixes) only run when stdin is a TTY and `--non-interactive` is **not** set. Headless runs (cron, Telegram, no terminal) will skip prompts.
+- `--fix` (alias for `--repair`) writes a backup to `~/.quantumclaw/quantumclaw.json.bak` and drops unknown config keys, listing each removal.
+- State integrity checks now detect orphan transcript files in the sessions directory and can archive them as `.deleted.<timestamp>` to reclaim space safely.
+- Doctor also scans `~/.quantumclaw/cron/jobs.json` (or `cron.store`) for legacy cron job shapes and can rewrite them in place before the scheduler has to auto-normalize them at runtime.
+- Doctor includes a memory-search readiness check and can recommend `quantumclaw configure --section model` when embedding credentials are missing.
+- If sandbox mode is enabled but Docker is unavailable, doctor reports a high-signal warning with remediation (`install Docker` or `quantumclaw config set agents.defaults.sandbox.mode off`).
+- If `gateway.auth.token`/`gateway.auth.password` are SecretRef-managed and unavailable in the current command path, doctor reports a read-only warning and does not write plaintext fallback credentials.
+- If channel SecretRef inspection fails in a fix path, doctor continues and reports a warning instead of exiting early.
+- Telegram `allowFrom` username auto-resolution (`doctor --fix`) requires a resolvable Telegram token in the current command path. If token inspection is unavailable, doctor reports a warning and skips auto-resolution for that pass.
+
+## macOS: `launchctl` env overrides
+
+If you previously ran `launchctl setenv QUANTUMCLAW_GATEWAY_TOKEN ...` (or `...PASSWORD`), that value overrides your config file and can cause persistent “unauthorized” errors.
+
+```bash
+launchctl getenv QUANTUMCLAW_GATEWAY_TOKEN
+launchctl getenv QUANTUMCLAW_GATEWAY_PASSWORD
+
+launchctl unsetenv QUANTUMCLAW_GATEWAY_TOKEN
+launchctl unsetenv QUANTUMCLAW_GATEWAY_PASSWORD
+```