@quantumclaw/quantumclaw 2026.3.22

package/docs/cli/secrets.md

@@ -0,0 +1,188 @@
+---
+summary: "CLI reference for `quantumclaw secrets` (reload, audit, configure, apply)"
+read_when:
+  - Re-resolving secret refs at runtime
+  - Auditing plaintext residues and unresolved refs
+  - Configuring SecretRefs and applying one-way scrub changes
+title: "secrets"
+---
+
+# `quantumclaw secrets`
+
+Use `quantumclaw secrets` to manage SecretRefs and keep the active runtime snapshot healthy.
+
+Command roles:
+
+- `reload`: gateway RPC (`secrets.reload`) that re-resolves refs and swaps runtime snapshot only on full success (no config writes).
+- `audit`: read-only scan of configuration/auth/generated-model stores and legacy residues for plaintext, unresolved refs, and precedence drift (exec refs are skipped unless `--allow-exec` is set).
+- `configure`: interactive planner for provider setup, target mapping, and preflight (TTY required).
+- `apply`: execute a saved plan (`--dry-run` for validation only; dry-run skips exec checks by default, and write mode rejects exec-containing plans unless `--allow-exec` is set), then scrub targeted plaintext residues.
+
+Recommended operator loop:
+
+```bash
+quantumclaw secrets audit --check
+quantumclaw secrets configure
+quantumclaw secrets apply --from /tmp/quantumclaw-secrets-plan.json --dry-run
+quantumclaw secrets apply --from /tmp/quantumclaw-secrets-plan.json
+quantumclaw secrets audit --check
+quantumclaw secrets reload
+```
+
+If your plan includes `exec` SecretRefs/providers, pass `--allow-exec` on both dry-run and write apply commands.
+
+Exit code note for CI/gates:
+
+- `audit --check` returns `1` on findings.
+- unresolved refs return `2`.
+
+Related:
+
+- Secrets guide: [Secrets Management](/gateway/secrets)
+- Credential surface: [SecretRef Credential Surface](/reference/secretref-credential-surface)
+- Security guide: [Security](/gateway/security)
+
+## Reload runtime snapshot
+
+Re-resolve secret refs and atomically swap runtime snapshot.
+
+```bash
+quantumclaw secrets reload
+quantumclaw secrets reload --json
+```
+
+Notes:
+
+- Uses gateway RPC method `secrets.reload`.
+- If resolution fails, gateway keeps last-known-good snapshot and returns an error (no partial activation).
+- JSON response includes `warningCount`.
+
+## Audit
+
+Scan QuantumClaw state for:
+
+- plaintext secret storage
+- unresolved refs
+- precedence drift (`auth-profiles.json` credentials shadowing `quantumclaw.json` refs)
+- generated `agents/*/agent/models.json` residues (provider `apiKey` values and sensitive provider headers)
+- legacy residues (legacy auth store entries, OAuth reminders)
+
+Header residue note:
+
+- Sensitive provider header detection is name-heuristic based (common auth/credential header names and fragments such as `authorization`, `x-api-key`, `token`, `secret`, `password`, and `credential`).
+
+```bash
+quantumclaw secrets audit
+quantumclaw secrets audit --check
+quantumclaw secrets audit --json
+quantumclaw secrets audit --allow-exec
+```
+
+Exit behavior:
+
+- `--check` exits non-zero on findings.
+- unresolved refs exit with higher-priority non-zero code.
+
+Report shape highlights:
+
+- `status`: `clean | findings | unresolved`
+- `resolution`: `refsChecked`, `skippedExecRefs`, `resolvabilityComplete`
+- `summary`: `plaintextCount`, `unresolvedRefCount`, `shadowedRefCount`, `legacyResidueCount`
+- finding codes:
+  - `PLAINTEXT_FOUND`
+  - `REF_UNRESOLVED`
+  - `REF_SHADOWED`
+  - `LEGACY_RESIDUE`
+
+## Configure (interactive helper)
+
+Build provider and SecretRef changes interactively, run preflight, and optionally apply:
+
+```bash
+quantumclaw secrets configure
+quantumclaw secrets configure --plan-out /tmp/quantumclaw-secrets-plan.json
+quantumclaw secrets configure --apply --yes
+quantumclaw secrets configure --providers-only
+quantumclaw secrets configure --skip-provider-setup
+quantumclaw secrets configure --agent ops
+quantumclaw secrets configure --json
+```
+
+Flow:
+
+- Provider setup first (`add/edit/remove` for `secrets.providers` aliases).
+- Credential mapping second (select fields and assign `{source, provider, id}` refs).
+- Preflight and optional apply last.
+
+Flags:
+
+- `--providers-only`: configure `secrets.providers` only, skip credential mapping.
+- `--skip-provider-setup`: skip provider setup and map credentials to existing providers.
+- `--agent <id>`: scope `auth-profiles.json` target discovery and writes to one agent store.
+- `--allow-exec`: allow exec SecretRef checks during preflight/apply (may execute provider commands).
+
+Notes:
+
+- Requires an interactive TTY.
+- You cannot combine `--providers-only` with `--skip-provider-setup`.
+- `configure` targets secret-bearing fields in `quantumclaw.json` plus `auth-profiles.json` for the selected agent scope.
+- `configure` supports creating new `auth-profiles.json` mappings directly in the picker flow.
+- Canonical supported surface: [SecretRef Credential Surface](/reference/secretref-credential-surface).
+- It performs preflight resolution before apply.
+- If preflight/apply includes exec refs, keep `--allow-exec` set for both steps.
+- Generated plans default to scrub options (`scrubEnv`, `scrubAuthProfilesForProviderTargets`, `scrubLegacyAuthJson` all enabled).
+- Apply path is one-way for scrubbed plaintext values.
+- Without `--apply`, CLI still prompts `Apply this plan now?` after preflight.
+- With `--apply` (and no `--yes`), CLI prompts an extra irreversible confirmation.
+
+Exec provider safety note:
+
+- Homebrew installs often expose symlinked binaries under `/opt/homebrew/bin/*`.
+- Set `allowSymlinkCommand: true` only when needed for trusted package-manager paths, and pair it with `trustedDirs` (for example `["/opt/homebrew"]`).
+- On Windows, if ACL verification is unavailable for a provider path, QuantumClaw fails closed. For trusted paths only, set `allowInsecurePath: true` on that provider to bypass path security checks.
+
+## Apply a saved plan
+
+Apply or preflight a plan generated previously:
+
+```bash
+quantumclaw secrets apply --from /tmp/quantumclaw-secrets-plan.json
+quantumclaw secrets apply --from /tmp/quantumclaw-secrets-plan.json --allow-exec
+quantumclaw secrets apply --from /tmp/quantumclaw-secrets-plan.json --dry-run
+quantumclaw secrets apply --from /tmp/quantumclaw-secrets-plan.json --dry-run --allow-exec
+quantumclaw secrets apply --from /tmp/quantumclaw-secrets-plan.json --json
+```
+
+Exec behavior:
+
+- `--dry-run` validates preflight without writing files.
+- exec SecretRef checks are skipped by default in dry-run.
+- write mode rejects plans that contain exec SecretRefs/providers unless `--allow-exec` is set.
+- Use `--allow-exec` to opt in to exec provider checks/execution in either mode.
+
+Plan contract details (allowed target paths, validation rules, and failure semantics):
+
+- [Secrets Apply Plan Contract](/gateway/secrets-plan-contract)
+
+What `apply` may update:
+
+- `quantumclaw.json` (SecretRef targets + provider upserts/deletes)
+- `auth-profiles.json` (provider-target scrubbing)
+- legacy `auth.json` residues
+- `~/.quantumclaw/.env` known secret keys whose values were migrated
+
+## Why no rollback backups
+
+`secrets apply` intentionally does not write rollback backups containing old plaintext values.
+
+Safety comes from strict preflight + atomic-ish apply with best-effort in-memory restore on failure.
+
+## Example
+
+```bash
+quantumclaw secrets audit --check
+quantumclaw secrets configure
+quantumclaw secrets audit --check
+```
+
+If `audit --check` still reports plaintext findings, update the remaining reported target paths and rerun audit.

package/docs/cli/security.md

@@ -0,0 +1,79 @@
+---
+summary: "CLI reference for `quantumclaw security` (audit and fix common security footguns)"
+read_when:
+  - You want to run a quick security audit on config/state
+  - You want to apply safe “fix” suggestions (chmod, tighten defaults)
+title: "security"
+---
+
+# `quantumclaw security`
+
+Security tools (audit + optional fixes).
+
+Related:
+
+- Security guide: [Security](/gateway/security)
+
+## Audit
+
+```bash
+quantumclaw security audit
+quantumclaw security audit --deep
+quantumclaw security audit --deep --password <password>
+quantumclaw security audit --deep --token <token>
+quantumclaw security audit --fix
+quantumclaw security audit --json
+```
+
+The audit warns when multiple DM senders share the main session and recommends **secure DM mode**: `session.dmScope="per-channel-peer"` (or `per-account-channel-peer` for multi-account channels) for shared inboxes.
+This is for cooperative/shared inbox hardening. A single Gateway shared by mutually untrusted/adversarial operators is not a recommended setup; split trust boundaries with separate gateways (or separate OS users/hosts).
+It also emits `security.trust_model.multi_user_heuristic` when config suggests likely shared-user ingress (for example open DM/group policy, configured group targets, or wildcard sender rules), and reminds you that QuantumClaw is a personal-assistant trust model by default.
+For intentional shared-user setups, the audit guidance is to sandbox all sessions, keep filesystem access workspace-scoped, and keep personal/private identities or credentials off that runtime.
+It also warns when small models (`<=300B`) are used without sandboxing and with web/browser tools enabled.
+For webhook ingress, it warns when `hooks.token` reuses the Gateway token, when `hooks.defaultSessionKey` is unset, when `hooks.allowedAgentIds` is unrestricted, when request `sessionKey` overrides are enabled, and when overrides are enabled without `hooks.allowedSessionKeyPrefixes`.
+It also warns when sandbox Docker settings are configured while sandbox mode is off, when `gateway.nodes.denyCommands` uses ineffective pattern-like/unknown entries (exact node command-name matching only, not shell-text filtering), when `gateway.nodes.allowCommands` explicitly enables dangerous node commands, when global `tools.profile="minimal"` is overridden by agent tool profiles, when open groups expose runtime/filesystem tools without sandbox/workspace guards, and when installed extension plugin tools may be reachable under permissive tool policy.
+It also flags `gateway.allowRealIpFallback=true` (header-spoofing risk if proxies are misconfigured) and `discovery.mdns.mode="full"` (metadata leakage via mDNS TXT records).
+It also warns when sandbox browser uses Docker `bridge` network without `sandbox.browser.cdpSourceRange`.
+It also flags dangerous sandbox Docker network modes (including `host` and `container:*` namespace joins).
+It also warns when existing sandbox browser Docker containers have missing/stale hash labels (for example pre-migration containers missing `quantumclaw.browserConfigEpoch`) and recommends `quantumclaw sandbox recreate --browser --all`.
+It also warns when npm-based plugin/hook install records are unpinned, missing integrity metadata, or drift from currently installed package versions.
+It warns when channel allowlists rely on mutable names/emails/tags instead of stable IDs (Discord, Slack, Google Chat, Microsoft Teams, Mattermost, IRC scopes where applicable).
+It warns when `gateway.auth.mode="none"` leaves Gateway HTTP APIs reachable without a shared secret (`/tools/invoke` plus any enabled `/v1/*` endpoint).
+Settings prefixed with `dangerous`/`dangerously` are explicit break-glass operator overrides; enabling one is not, by itself, a security vulnerability report.
+For the complete dangerous-parameter inventory, see the "Insecure or dangerous flags summary" section in [Security](/gateway/security).
+
+SecretRef behavior:
+
+- `security audit` resolves supported SecretRefs in read-only mode for its targeted paths.
+- If a SecretRef is unavailable in the current command path, audit continues and reports `secretDiagnostics` (instead of crashing).
+- `--token` and `--password` only override deep-probe auth for that command invocation; they do not rewrite config or SecretRef mappings.
+
+## JSON output
+
+Use `--json` for CI/policy checks:
+
+```bash
+quantumclaw security audit --json | jq '.summary'
+quantumclaw security audit --deep --json | jq '.findings[] | select(.severity=="critical") | .checkId'
+```
+
+If `--fix` and `--json` are combined, output includes both fix actions and final report:
+
+```bash
+quantumclaw security audit --fix --json | jq '{fix: .fix.ok, summary: .report.summary}'
+```
+
+## What `--fix` changes
+
+`--fix` applies safe, deterministic remediations:
+
+- flips common `groupPolicy="open"` to `groupPolicy="allowlist"` (including account variants in supported channels)
+- sets `logging.redactSensitive` from `"off"` to `"tools"`
+- tightens permissions for state/config and common sensitive files (`credentials/*.json`, `auth-profiles.json`, `sessions.json`, session `*.jsonl`)
+
+`--fix` does **not**:
+
+- rotate tokens/passwords/API keys
+- disable tools (`gateway`, `cron`, `exec`, etc.)
+- change gateway bind/auth/network exposure choices
+- remove or rewrite plugins/skills

package/docs/cli/sessions.md

@@ -0,0 +1,110 @@
+---
+summary: "CLI reference for `quantumclaw sessions` (list stored sessions + usage)"
+read_when:
+  - You want to list stored sessions and see recent activity
+title: "sessions"
+---
+
+# `quantumclaw sessions`
+
+List stored conversation sessions.
+
+```bash
+quantumclaw sessions
+quantumclaw sessions --agent work
+quantumclaw sessions --all-agents
+quantumclaw sessions --active 120
+quantumclaw sessions --json
+```
+
+Scope selection:
+
+- default: configured default agent store
+- `--agent <id>`: one configured agent store
+- `--all-agents`: aggregate all configured agent stores
+- `--store <path>`: explicit store path (cannot be combined with `--agent` or `--all-agents`)
+
+`quantumclaw sessions --all-agents` reads configured agent stores. Gateway and ACP
+session discovery are broader: they also include disk-only stores found under
+the default `agents/` root or a templated `session.store` root. Those
+discovered stores must resolve to regular `sessions.json` files inside the
+agent root; symlinks and out-of-root paths are skipped.
+
+JSON examples:
+
+`quantumclaw sessions --all-agents --json`:
+
+```json
+{
+  "path": null,
+  "stores": [
+    { "agentId": "main", "path": "/home/user/.quantumclaw/agents/main/sessions/sessions.json" },
+    { "agentId": "work", "path": "/home/user/.quantumclaw/agents/work/sessions/sessions.json" }
+  ],
+  "allAgents": true,
+  "count": 2,
+  "activeMinutes": null,
+  "sessions": [
+    { "agentId": "main", "key": "agent:main:main", "model": "gpt-5" },
+    { "agentId": "work", "key": "agent:work:main", "model": "claude-opus-4-6" }
+  ]
+}
+```
+
+## Cleanup maintenance
+
+Run maintenance now (instead of waiting for the next write cycle):
+
+```bash
+quantumclaw sessions cleanup --dry-run
+quantumclaw sessions cleanup --agent work --dry-run
+quantumclaw sessions cleanup --all-agents --dry-run
+quantumclaw sessions cleanup --enforce
+quantumclaw sessions cleanup --enforce --active-key "agent:main:telegram:direct:123"
+quantumclaw sessions cleanup --json
+```
+
+`quantumclaw sessions cleanup` uses `session.maintenance` settings from config:
+
+- Scope note: `quantumclaw sessions cleanup` maintains session stores/transcripts only. It does not prune cron run logs (`cron/runs/<jobId>.jsonl`), which are managed by `cron.runLog.maxBytes` and `cron.runLog.keepLines` in [Cron configuration](/automation/cron-jobs#configuration) and explained in [Cron maintenance](/automation/cron-jobs#maintenance).
+
+- `--dry-run`: preview how many entries would be pruned/capped without writing.
+  - In text mode, dry-run prints a per-session action table (`Action`, `Key`, `Age`, `Model`, `Flags`) so you can see what would be kept vs removed.
+- `--enforce`: apply maintenance even when `session.maintenance.mode` is `warn`.
+- `--active-key <key>`: protect a specific active key from disk-budget eviction.
+- `--agent <id>`: run cleanup for one configured agent store.
+- `--all-agents`: run cleanup for all configured agent stores.
+- `--store <path>`: run against a specific `sessions.json` file.
+- `--json`: print a JSON summary. With `--all-agents`, output includes one summary per store.
+
+`quantumclaw sessions cleanup --all-agents --dry-run --json`:
+
+```json
+{
+  "allAgents": true,
+  "mode": "warn",
+  "dryRun": true,
+  "stores": [
+    {
+      "agentId": "main",
+      "storePath": "/home/user/.quantumclaw/agents/main/sessions/sessions.json",
+      "beforeCount": 120,
+      "afterCount": 80,
+      "pruned": 40,
+      "capped": 0
+    },
+    {
+      "agentId": "work",
+      "storePath": "/home/user/.quantumclaw/agents/work/sessions/sessions.json",
+      "beforeCount": 18,
+      "afterCount": 18,
+      "pruned": 0,
+      "capped": 0
+    }
+  ]
+}
+```
+
+Related:
+
+- Session config: [Configuration reference](/gateway/configuration-reference#session)

package/docs/cli/setup.md

@@ -0,0 +1,29 @@
+---
+summary: "CLI reference for `quantumclaw setup` (initialize config + workspace)"
+read_when:
+  - You’re doing first-run setup without full CLI onboarding
+  - You want to set the default workspace path
+title: "setup"
+---
+
+# `quantumclaw setup`
+
+Initialize `~/.quantumclaw/quantumclaw.json` and the agent workspace.
+
+Related:
+
+- Getting started: [Getting started](/start/getting-started)
+- CLI onboarding: [Onboarding (CLI)](/start/wizard)
+
+## Examples
+
+```bash
+quantumclaw setup
+quantumclaw setup --workspace ~/.quantumclaw/workspace
+```
+
+To run onboarding via setup:
+
+```bash
+quantumclaw setup --wizard
+```

package/docs/cli/skills.md

@@ -0,0 +1,36 @@
+---
+summary: "CLI reference for `quantumclaw skills` (search/install/update/list/info/check)"
+read_when:
+  - You want to see which skills are available and ready to run
+  - You want to search, install, or update skills from ClawHub
+  - You want to debug missing binaries/env/config for skills
+title: "skills"
+---
+
+# `quantumclaw skills`
+
+Inspect local skills and install/update skills from ClawHub.
+
+Related:
+
+- Skills system: [Skills](/tools/skills)
+- Skills config: [Skills config](/tools/skills-config)
+- ClawHub installs: [ClawHub](/tools/clawhub)
+
+## Commands
+
+```bash
+quantumclaw skills search "calendar"
+quantumclaw skills install <slug>
+quantumclaw skills install <slug> --version <version>
+quantumclaw skills update <slug>
+quantumclaw skills update --all
+quantumclaw skills list
+quantumclaw skills list --eligible
+quantumclaw skills info <name>
+quantumclaw skills check
+```
+
+`search`/`install`/`update` use ClawHub directly and install into the active
+workspace `skills/` directory. `list`/`info`/`check` still inspect the local
+skills visible to the current workspace and config.

package/docs/cli/status.md

@@ -0,0 +1,30 @@
+---
+summary: "CLI reference for `quantumclaw status` (diagnostics, probes, usage snapshots)"
+read_when:
+  - You want a quick diagnosis of channel health + recent session recipients
+  - You want a pasteable “all” status for debugging
+title: "status"
+---
+
+# `quantumclaw status`
+
+Diagnostics for channels + sessions.
+
+```bash
+quantumclaw status
+quantumclaw status --all
+quantumclaw status --deep
+quantumclaw status --usage
+```
+
+Notes:
+
+- `--deep` runs live probes (WhatsApp Web + Telegram + Discord + Google Chat + Slack + Signal).
+- Output includes per-agent session stores when multiple agents are configured.
+- Overview includes Gateway + node host service install/runtime status when available.
+- Overview includes update channel + git SHA (for source checkouts).
+- Update info surfaces in the Overview; if an update is available, status prints a hint to run `quantumclaw update` (see [Updating](/install/updating)).
+- Read-only status surfaces (`status`, `status --json`, `status --all`) resolve supported SecretRefs for their targeted config paths when possible.
+- If a supported channel SecretRef is configured but unavailable in the current command path, status stays read-only and reports degraded output instead of crashing. Human output shows warnings such as “configured token unavailable in this command path”, and JSON output includes `secretDiagnostics`.
+- When command-local SecretRef resolution succeeds, status prefers the resolved snapshot and clears transient “secret unavailable” channel markers from the final output.
+- `status --all` includes a Secrets overview row and a diagnosis section that summarizes secret diagnostics (truncated for readability) without stopping report generation.

package/docs/cli/system.md

@@ -0,0 +1,60 @@
+---
+summary: "CLI reference for `quantumclaw system` (system events, heartbeat, presence)"
+read_when:
+  - You want to enqueue a system event without creating a cron job
+  - You need to enable or disable heartbeats
+  - You want to inspect system presence entries
+title: "system"
+---
+
+# `quantumclaw system`
+
+System-level helpers for the Gateway: enqueue system events, control heartbeats,
+and view presence.
+
+## Common commands
+
+```bash
+quantumclaw system event --text "Check for urgent follow-ups" --mode now
+quantumclaw system heartbeat enable
+quantumclaw system heartbeat last
+quantumclaw system presence
+```
+
+## `system event`
+
+Enqueue a system event on the **main** session. The next heartbeat will inject
+it as a `System:` line in the prompt. Use `--mode now` to trigger the heartbeat
+immediately; `next-heartbeat` waits for the next scheduled tick.
+
+Flags:
+
+- `--text <text>`: required system event text.
+- `--mode <mode>`: `now` or `next-heartbeat` (default).
+- `--json`: machine-readable output.
+
+## `system heartbeat last|enable|disable`
+
+Heartbeat controls:
+
+- `last`: show the last heartbeat event.
+- `enable`: turn heartbeats back on (use this if they were disabled).
+- `disable`: pause heartbeats.
+
+Flags:
+
+- `--json`: machine-readable output.
+
+## `system presence`
+
+List the current system presence entries the Gateway knows about (nodes,
+instances, and similar status lines).
+
+Flags:
+
+- `--json`: machine-readable output.
+
+## Notes
+
+- Requires a running Gateway reachable by your current config (local or remote).
+- System events are ephemeral and not persisted across restarts.

package/docs/cli/tui.md

@@ -0,0 +1,30 @@
+---
+summary: "CLI reference for `quantumclaw tui` (terminal UI connected to the Gateway)"
+read_when:
+  - You want a terminal UI for the Gateway (remote-friendly)
+  - You want to pass url/token/session from scripts
+title: "tui"
+---
+
+# `quantumclaw tui`
+
+Open the terminal UI connected to the Gateway.
+
+Related:
+
+- TUI guide: [TUI](/web/tui)
+
+Notes:
+
+- `tui` resolves configured gateway auth SecretRefs for token/password auth when possible (`env`/`file`/`exec` providers).
+- When launched from inside a configured agent workspace directory, TUI auto-selects that agent for the session key default (unless `--session` is explicitly `agent:<id>:...`).
+
+## Examples
+
+```bash
+quantumclaw tui
+quantumclaw tui --url ws://127.0.0.1:18789 --token <token>
+quantumclaw tui --session main --deliver
+# when run inside an agent workspace, infers that agent automatically
+quantumclaw tui --session bugfix
+```

package/docs/cli/uninstall.md

@@ -0,0 +1,20 @@
+---
+summary: "CLI reference for `quantumclaw uninstall` (remove gateway service + local data)"
+read_when:
+  - You want to remove the gateway service and/or local state
+  - You want a dry-run first
+title: "uninstall"
+---
+
+# `quantumclaw uninstall`
+
+Uninstall the gateway service + local data (CLI remains).
+
+```bash
+quantumclaw backup create
+quantumclaw uninstall
+quantumclaw uninstall --all --yes
+quantumclaw uninstall --dry-run
+```
+
+Run `quantumclaw backup create` first if you want a restorable snapshot before removing state or workspaces.