@quantumclaw/quantumclaw 2026.3.22

package/docs/cli/logs.md

@@ -0,0 +1,28 @@
+---
+summary: "CLI reference for `quantumclaw logs` (tail gateway logs via RPC)"
+read_when:
+  - You need to tail Gateway logs remotely (without SSH)
+  - You want JSON log lines for tooling
+title: "logs"
+---
+
+# `quantumclaw logs`
+
+Tail Gateway file logs over RPC (works in remote mode).
+
+Related:
+
+- Logging overview: [Logging](/logging)
+
+## Examples
+
+```bash
+quantumclaw logs
+quantumclaw logs --follow
+quantumclaw logs --json
+quantumclaw logs --limit 500
+quantumclaw logs --local-time
+quantumclaw logs --follow --local-time
+```
+
+Use `--local-time` to render timestamps in your local timezone.

package/docs/cli/memory.md

@@ -0,0 +1,66 @@
+---
+summary: "CLI reference for `quantumclaw memory` (status/index/search)"
+read_when:
+  - You want to index or search semantic memory
+  - You’re debugging memory availability or indexing
+title: "memory"
+---
+
+# `quantumclaw memory`
+
+Manage semantic memory indexing and search.
+Provided by the active memory plugin (default: `memory-core`; set `plugins.slots.memory = "none"` to disable).
+
+Related:
+
+- Memory concept: [Memory](/concepts/memory)
+- Plugins: [Plugins](/tools/plugin)
+
+## Examples
+
+```bash
+quantumclaw memory status
+quantumclaw memory status --deep
+quantumclaw memory index --force
+quantumclaw memory search "meeting notes"
+quantumclaw memory search --query "deployment" --max-results 20
+quantumclaw memory status --json
+quantumclaw memory status --deep --index
+quantumclaw memory status --deep --index --verbose
+quantumclaw memory status --agent main
+quantumclaw memory index --agent main --verbose
+```
+
+## Options
+
+`memory status` and `memory index`:
+
+- `--agent <id>`: scope to a single agent. Without it, these commands run for each configured agent; if no agent list is configured, they fall back to the default agent.
+- `--verbose`: emit detailed logs during probes and indexing.
+
+`memory status`:
+
+- `--deep`: probe vector + embedding availability.
+- `--index`: run a reindex if the store is dirty (implies `--deep`).
+- `--json`: print JSON output.
+
+`memory index`:
+
+- `--force`: force a full reindex.
+
+`memory search`:
+
+- Query input: pass either positional `[query]` or `--query <text>`.
+- If both are provided, `--query` wins.
+- If neither is provided, the command exits with an error.
+- `--agent <id>`: scope to a single agent (default: the default agent).
+- `--max-results <n>`: limit the number of results returned.
+- `--min-score <n>`: filter out low-score matches.
+- `--json`: print JSON results.
+
+Notes:
+
+- `memory index --verbose` prints per-phase details (provider, model, sources, batch activity).
+- `memory status` includes any extra paths configured via `memorySearch.extraPaths`.
+- If effectively active memory remote API key fields are configured as SecretRefs, the command resolves those values from the active gateway snapshot. If gateway is unavailable, the command fails fast.
+- Gateway version skew note: this command path requires a gateway that supports `secrets.resolve`; older gateways return an unknown-method error.

package/docs/cli/message.md

@@ -0,0 +1,278 @@
+---
+summary: "CLI reference for `quantumclaw message` (send + channel actions)"
+read_when:
+  - Adding or modifying message CLI actions
+  - Changing outbound channel behavior
+title: "message"
+---
+
+# `quantumclaw message`
+
+Single outbound command for sending messages and channel actions
+(Discord/Google Chat/Slack/Mattermost (plugin)/Telegram/WhatsApp/Signal/iMessage/Microsoft Teams).
+
+## Usage
+
+```
+quantumclaw message <subcommand> [flags]
+```
+
+Channel selection:
+
+- `--channel` required if more than one channel is configured.
+- If exactly one channel is configured, it becomes the default.
+- Values: `whatsapp|telegram|discord|googlechat|slack|mattermost|signal|imessage|msteams` (Mattermost requires plugin)
+
+Target formats (`--target`):
+
+- WhatsApp: E.164 or group JID
+- Telegram: chat id or `@username`
+- Discord: `channel:<id>` or `user:<id>` (or `<@id>` mention; raw numeric ids are treated as channels)
+- Google Chat: `spaces/<spaceId>` or `users/<userId>`
+- Slack: `channel:<id>` or `user:<id>` (raw channel id is accepted)
+- Mattermost (plugin): `channel:<id>`, `user:<id>`, or `@username` (bare ids are treated as channels)
+- Signal: `+E.164`, `group:<id>`, `signal:+E.164`, `signal:group:<id>`, or `username:<name>`/`u:<name>`
+- iMessage: handle, `chat_id:<id>`, `chat_guid:<guid>`, or `chat_identifier:<id>`
+- Microsoft Teams: conversation id (`19:...@thread.tacv2`) or `conversation:<id>` or `user:<aad-object-id>`
+
+Name lookup:
+
+- For supported providers (Discord/Slack/etc), channel names like `Help` or `#help` are resolved via the directory cache.
+- On cache miss, QuantumClaw will attempt a live directory lookup when the provider supports it.
+
+## Common flags
+
+- `--channel <name>`
+- `--account <id>`
+- `--target <dest>` (target channel or user for send/poll/read/etc)
+- `--targets <name>` (repeat; broadcast only)
+- `--json`
+- `--dry-run`
+- `--verbose`
+
+## SecretRef behavior
+
+- `quantumclaw message` resolves supported channel SecretRefs before running the selected action.
+- Resolution is scoped to the active action target when possible:
+  - channel-scoped when `--channel` is set (or inferred from prefixed targets like `discord:...`)
+  - account-scoped when `--account` is set (channel globals + selected account surfaces)
+  - when `--account` is omitted, QuantumClaw does not force a `default` account SecretRef scope
+- Unresolved SecretRefs on unrelated channels do not block a targeted message action.
+- If the selected channel/account SecretRef is unresolved, the command fails closed for that action.
+
+## Actions
+
+### Core
+
+- `send`
+  - Channels: WhatsApp/Telegram/Discord/Google Chat/Slack/Mattermost (plugin)/Signal/iMessage/Microsoft Teams
+  - Required: `--target`, plus `--message` or `--media`
+  - Optional: `--media`, `--reply-to`, `--thread-id`, `--gif-playback`
+  - Telegram only: `--buttons` (requires `channels.telegram.capabilities.inlineButtons` to allow it)
+  - Telegram only: `--force-document` (send images and GIFs as documents to avoid Telegram compression)
+  - Telegram only: `--thread-id` (forum topic id)
+  - Slack only: `--thread-id` (thread timestamp; `--reply-to` uses the same field)
+  - WhatsApp only: `--gif-playback`
+
+- `poll`
+  - Channels: WhatsApp/Telegram/Discord/Matrix/Microsoft Teams
+  - Required: `--target`, `--poll-question`, `--poll-option` (repeat)
+  - Optional: `--poll-multi`
+  - Discord only: `--poll-duration-hours`, `--silent`, `--message`
+  - Telegram only: `--poll-duration-seconds` (5-600), `--silent`, `--poll-anonymous` / `--poll-public`, `--thread-id`
+
+- `react`
+  - Channels: Discord/Google Chat/Slack/Telegram/WhatsApp/Signal
+  - Required: `--message-id`, `--target`
+  - Optional: `--emoji`, `--remove`, `--participant`, `--from-me`, `--target-author`, `--target-author-uuid`
+  - Note: `--remove` requires `--emoji` (omit `--emoji` to clear own reactions where supported; see /tools/reactions)
+  - WhatsApp only: `--participant`, `--from-me`
+  - Signal group reactions: `--target-author` or `--target-author-uuid` required
+
+- `reactions`
+  - Channels: Discord/Google Chat/Slack
+  - Required: `--message-id`, `--target`
+  - Optional: `--limit`
+
+- `read`
+  - Channels: Discord/Slack
+  - Required: `--target`
+  - Optional: `--limit`, `--before`, `--after`
+  - Discord only: `--around`
+
+- `edit`
+  - Channels: Discord/Slack
+  - Required: `--message-id`, `--message`, `--target`
+
+- `delete`
+  - Channels: Discord/Slack/Telegram
+  - Required: `--message-id`, `--target`
+
+- `pin` / `unpin`
+  - Channels: Discord/Slack
+  - Required: `--message-id`, `--target`
+
+- `pins` (list)
+  - Channels: Discord/Slack
+  - Required: `--target`
+
+- `permissions`
+  - Channels: Discord
+  - Required: `--target`
+
+- `search`
+  - Channels: Discord
+  - Required: `--guild-id`, `--query`
+  - Optional: `--channel-id`, `--channel-ids` (repeat), `--author-id`, `--author-ids` (repeat), `--limit`
+
+### Threads
+
+- `thread create`
+  - Channels: Discord
+  - Required: `--thread-name`, `--target` (channel id)
+  - Optional: `--message-id`, `--message`, `--auto-archive-min`
+
+- `thread list`
+  - Channels: Discord
+  - Required: `--guild-id`
+  - Optional: `--channel-id`, `--include-archived`, `--before`, `--limit`
+
+- `thread reply`
+  - Channels: Discord
+  - Required: `--target` (thread id), `--message`
+  - Optional: `--media`, `--reply-to`
+
+### Emojis
+
+- `emoji list`
+  - Discord: `--guild-id`
+  - Slack: no extra flags
+
+- `emoji upload`
+  - Channels: Discord
+  - Required: `--guild-id`, `--emoji-name`, `--media`
+  - Optional: `--role-ids` (repeat)
+
+### Stickers
+
+- `sticker send`
+  - Channels: Discord
+  - Required: `--target`, `--sticker-id` (repeat)
+  - Optional: `--message`
+
+- `sticker upload`
+  - Channels: Discord
+  - Required: `--guild-id`, `--sticker-name`, `--sticker-desc`, `--sticker-tags`, `--media`
+
+### Roles / Channels / Members / Voice
+
+- `role info` (Discord): `--guild-id`
+- `role add` / `role remove` (Discord): `--guild-id`, `--user-id`, `--role-id`
+- `channel info` (Discord): `--target`
+- `channel list` (Discord): `--guild-id`
+- `member info` (Discord/Slack): `--user-id` (+ `--guild-id` for Discord)
+- `voice status` (Discord): `--guild-id`, `--user-id`
+
+### Events
+
+- `event list` (Discord): `--guild-id`
+- `event create` (Discord): `--guild-id`, `--event-name`, `--start-time`
+  - Optional: `--end-time`, `--desc`, `--channel-id`, `--location`, `--event-type`
+
+### Moderation (Discord)
+
+- `timeout`: `--guild-id`, `--user-id` (optional `--duration-min` or `--until`; omit both to clear timeout)
+- `kick`: `--guild-id`, `--user-id` (+ `--reason`)
+- `ban`: `--guild-id`, `--user-id` (+ `--delete-days`, `--reason`)
+  - `timeout` also supports `--reason`
+
+### Broadcast
+
+- `broadcast`
+  - Channels: any configured channel; use `--channel all` to target all providers
+  - Required: `--targets` (repeat)
+  - Optional: `--message`, `--media`, `--dry-run`
+
+## Examples
+
+Send a Discord reply:
+
+```
+quantumclaw message send --channel discord \
+  --target channel:123 --message "hi" --reply-to 456
+```
+
+Send a Discord message with components:
+
+```
+quantumclaw message send --channel discord \
+  --target channel:123 --message "Choose:" \
+  --components '{"text":"Choose a path","blocks":[{"type":"actions","buttons":[{"label":"Approve","style":"success"},{"label":"Decline","style":"danger"}]}]}'
+```
+
+See [Discord components](/channels/discord#interactive-components) for the full schema.
+
+Create a Discord poll:
+
+```
+quantumclaw message poll --channel discord \
+  --target channel:123 \
+  --poll-question "Snack?" \
+  --poll-option Pizza --poll-option Sushi \
+  --poll-multi --poll-duration-hours 48
+```
+
+Create a Telegram poll (auto-close in 2 minutes):
+
+```
+quantumclaw message poll --channel telegram \
+  --target @mychat \
+  --poll-question "Lunch?" \
+  --poll-option Pizza --poll-option Sushi \
+  --poll-duration-seconds 120 --silent
+```
+
+Send a Teams proactive message:
+
+```
+quantumclaw message send --channel msteams \
+  --target conversation:19:abc@thread.tacv2 --message "hi"
+```
+
+Create a Teams poll:
+
+```
+quantumclaw message poll --channel msteams \
+  --target conversation:19:abc@thread.tacv2 \
+  --poll-question "Lunch?" \
+  --poll-option Pizza --poll-option Sushi
+```
+
+React in Slack:
+
+```
+quantumclaw message react --channel slack \
+  --target C123 --message-id 456 --emoji "✅"
+```
+
+React in a Signal group:
+
+```
+quantumclaw message react --channel signal \
+  --target signal:group:abc123 --message-id 1737630212345 \
+  --emoji "✅" --target-author-uuid 123e4567-e89b-12d3-a456-426614174000
+```
+
+Send Telegram inline buttons:
+
+```
+quantumclaw message send --channel telegram --target @mychat --message "Choose:" \
+  --buttons '[ [{"text":"Yes","callback_data":"cmd:yes"}], [{"text":"No","callback_data":"cmd:no"}] ]'
+```
+
+Send a Telegram image as a document to avoid compression:
+
+```bash
+quantumclaw message send --channel telegram --target @mychat \
+  --media ./diagram.png --force-document
+```

package/docs/cli/models.md

@@ -0,0 +1,81 @@
+---
+summary: "CLI reference for `quantumclaw models` (status/list/set/scan, aliases, fallbacks, auth)"
+read_when:
+  - You want to change default models or view provider auth status
+  - You want to scan available models/providers and debug auth profiles
+title: "models"
+---
+
+# `quantumclaw models`
+
+Model discovery, scanning, and configuration (default model, fallbacks, auth profiles).
+
+Related:
+
+- Providers + models: [Models](/providers/models)
+- Provider auth setup: [Getting started](/start/getting-started)
+
+## Common commands
+
+```bash
+quantumclaw models status
+quantumclaw models list
+quantumclaw models set <model-or-alias>
+quantumclaw models scan
+```
+
+`quantumclaw models status` shows the resolved default/fallbacks plus an auth overview.
+When provider usage snapshots are available, the OAuth/token status section includes
+provider usage headers.
+Add `--probe` to run live auth probes against each configured provider profile.
+Probes are real requests (may consume tokens and trigger rate limits).
+Use `--agent <id>` to inspect a configured agent’s model/auth state. When omitted,
+the command uses `QUANTUMCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR` if set, otherwise the
+configured default agent.
+
+Notes:
+
+- `models set <model-or-alias>` accepts `provider/model` or an alias.
+- Model refs are parsed by splitting on the **first** `/`. If the model ID includes `/` (OpenRouter-style), include the provider prefix (example: `openrouter/moonshotai/kimi-k2`).
+- If you omit the provider, QuantumClaw treats the input as an alias or a model for the **default provider** (only works when there is no `/` in the model ID).
+- `models status` may show `marker(<value>)` in auth output for non-secret placeholders (for example `OPENAI_API_KEY`, `secretref-managed`, `minimax-oauth`, `qwen-oauth`, `ollama-local`) instead of masking them as secrets.
+
+### `models status`
+
+Options:
+
+- `--json`
+- `--plain`
+- `--check` (exit 1=expired/missing, 2=expiring)
+- `--probe` (live probe of configured auth profiles)
+- `--probe-provider <name>` (probe one provider)
+- `--probe-profile <id>` (repeat or comma-separated profile ids)
+- `--probe-timeout <ms>`
+- `--probe-concurrency <n>`
+- `--probe-max-tokens <n>`
+- `--agent <id>` (configured agent id; overrides `QUANTUMCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR`)
+
+## Aliases + fallbacks
+
+```bash
+quantumclaw models aliases list
+quantumclaw models fallbacks list
+```
+
+## Auth profiles
+
+```bash
+quantumclaw models auth add
+quantumclaw models auth login --provider <id>
+quantumclaw models auth setup-token
+quantumclaw models auth paste-token
+```
+
+`models auth login` runs a provider plugin’s auth flow (OAuth/API key). Use
+`quantumclaw plugins list` to see which providers are installed.
+
+Notes:
+
+- `setup-token` prompts for a setup-token value (generate it with `claude setup-token` on any machine).
+- `paste-token` accepts a token string generated elsewhere or from automation.
+- Anthropic policy note: setup-token support is technical compatibility. Anthropic has blocked some subscription usage outside Claude Code in the past, so verify current terms before using it broadly.

package/docs/cli/node.md

@@ -0,0 +1,127 @@
+---
+summary: "CLI reference for `quantumclaw node` (headless node host)"
+read_when:
+  - Running the headless node host
+  - Pairing a non-macOS node for system.run
+title: "node"
+---
+
+# `quantumclaw node`
+
+Run a **headless node host** that connects to the Gateway WebSocket and exposes
+`system.run` / `system.which` on this machine.
+
+## Why use a node host?
+
+Use a node host when you want agents to **run commands on other machines** in your
+network without installing a full macOS companion app there.
+
+Common use cases:
+
+- Run commands on remote Linux/Windows boxes (build servers, lab machines, NAS).
+- Keep exec **sandboxed** on the gateway, but delegate approved runs to other hosts.
+- Provide a lightweight, headless execution target for automation or CI nodes.
+
+Execution is still guarded by **exec approvals** and per‑agent allowlists on the
+node host, so you can keep command access scoped and explicit.
+
+## Browser proxy (zero-config)
+
+Node hosts automatically advertise a browser proxy if `browser.enabled` is not
+disabled on the node. This lets the agent use browser automation on that node
+without extra configuration.
+
+Disable it on the node if needed:
+
+```json5
+{
+  nodeHost: {
+    browserProxy: {
+      enabled: false,
+    },
+  },
+}
+```
+
+## Run (foreground)
+
+```bash
+quantumclaw node run --host <gateway-host> --port 18789
+```
+
+Options:
+
+- `--host <host>`: Gateway WebSocket host (default: `127.0.0.1`)
+- `--port <port>`: Gateway WebSocket port (default: `18789`)
+- `--tls`: Use TLS for the gateway connection
+- `--tls-fingerprint <sha256>`: Expected TLS certificate fingerprint (sha256)
+- `--node-id <id>`: Override node id (clears pairing token)
+- `--display-name <name>`: Override the node display name
+
+## Gateway auth for node host
+
+`quantumclaw node run` and `quantumclaw node install` resolve gateway auth from config/env (no `--token`/`--password` flags on node commands):
+
+- `QUANTUMCLAW_GATEWAY_TOKEN` / `QUANTUMCLAW_GATEWAY_PASSWORD` are checked first.
+- Then local config fallback: `gateway.auth.token` / `gateway.auth.password`.
+- In local mode, node host intentionally does not inherit `gateway.remote.token` / `gateway.remote.password`.
+- If `gateway.auth.token` / `gateway.auth.password` is explicitly configured via SecretRef and unresolved, node auth resolution fails closed (no remote fallback masking).
+- In `gateway.mode=remote`, remote client fields (`gateway.remote.token` / `gateway.remote.password`) are also eligible per remote precedence rules.
+- Legacy `CLAWDBOT_GATEWAY_*` env vars are ignored for node host auth resolution.
+
+## Service (background)
+
+Install a headless node host as a user service.
+
+```bash
+quantumclaw node install --host <gateway-host> --port 18789
+```
+
+Options:
+
+- `--host <host>`: Gateway WebSocket host (default: `127.0.0.1`)
+- `--port <port>`: Gateway WebSocket port (default: `18789`)
+- `--tls`: Use TLS for the gateway connection
+- `--tls-fingerprint <sha256>`: Expected TLS certificate fingerprint (sha256)
+- `--node-id <id>`: Override node id (clears pairing token)
+- `--display-name <name>`: Override the node display name
+- `--runtime <runtime>`: Service runtime (`node` or `bun`)
+- `--force`: Reinstall/overwrite if already installed
+
+Manage the service:
+
+```bash
+quantumclaw node status
+quantumclaw node stop
+quantumclaw node restart
+quantumclaw node uninstall
+```
+
+Use `quantumclaw node run` for a foreground node host (no service).
+
+Service commands accept `--json` for machine-readable output.
+
+## Pairing
+
+The first connection creates a pending device pairing request (`role: node`) on the Gateway.
+Approve it via:
+
+```bash
+quantumclaw devices list
+quantumclaw devices approve <requestId>
+```
+
+If the node retries pairing with changed auth details (role/scopes/public key),
+the previous pending request is superseded and a new `requestId` is created.
+Run `quantumclaw devices list` again before approval.
+
+The node host stores its node id, token, display name, and gateway connection info in
+`~/.quantumclaw/node.json`.
+
+## Exec approvals
+
+`system.run` is gated by local exec approvals:
+
+- `~/.quantumclaw/exec-approvals.json`
+- [Exec approvals](/tools/exec-approvals)
+- `quantumclaw approvals --node <id|name|ip>` (edit from the Gateway)

package/docs/cli/nodes.md

@@ -0,0 +1,75 @@
+---
+summary: "CLI reference for `quantumclaw nodes` (list/status/approve/invoke, camera/canvas/screen)"
+read_when:
+  - You’re managing paired nodes (cameras, screen, canvas)
+  - You need to approve requests or invoke node commands
+title: "nodes"
+---
+
+# `quantumclaw nodes`
+
+Manage paired nodes (devices) and invoke node capabilities.
+
+Related:
+
+- Nodes overview: [Nodes](/nodes)
+- Camera: [Camera nodes](/nodes/camera)
+- Images: [Image nodes](/nodes/images)
+
+Common options:
+
+- `--url`, `--token`, `--timeout`, `--json`
+
+## Common commands
+
+```bash
+quantumclaw nodes list
+quantumclaw nodes list --connected
+quantumclaw nodes list --last-connected 24h
+quantumclaw nodes pending
+quantumclaw nodes approve <requestId>
+quantumclaw nodes status
+quantumclaw nodes status --connected
+quantumclaw nodes status --last-connected 24h
+```
+
+`nodes list` prints pending/paired tables. Paired rows include the most recent connect age (Last Connect).
+Use `--connected` to only show currently-connected nodes. Use `--last-connected <duration>` to
+filter to nodes that connected within a duration (e.g. `24h`, `7d`).
+
+## Invoke / run
+
+```bash
+quantumclaw nodes invoke --node <id|name|ip> --command <command> --params <json>
+quantumclaw nodes run --node <id|name|ip> <command...>
+quantumclaw nodes run --raw "git status"
+quantumclaw nodes run --agent main --node <id|name|ip> --raw "git status"
+```
+
+Invoke flags:
+
+- `--params <json>`: JSON object string (default `{}`).
+- `--invoke-timeout <ms>`: node invoke timeout (default `15000`).
+- `--idempotency-key <key>`: optional idempotency key.
+
+### Exec-style defaults
+
+`nodes run` mirrors the model’s exec behavior (defaults + approvals):
+
+- Reads `tools.exec.*` (plus `agents.list[].tools.exec.*` overrides).
+- Uses exec approvals (`exec.approval.request`) before invoking `system.run`.
+- `--node` can be omitted when `tools.exec.node` is set.
+- Requires a node that advertises `system.run` (macOS companion app or headless node host).
+
+Flags:
+
+- `--cwd <path>`: working directory.
+- `--env <key=val>`: env override (repeatable). Note: node hosts ignore `PATH` overrides (and `tools.exec.pathPrepend` is not applied to node hosts).
+- `--command-timeout <ms>`: command timeout.
+- `--invoke-timeout <ms>`: node invoke timeout (default `30000`).
+- `--needs-screen-recording`: require screen recording permission.
+- `--raw <command>`: run a shell string (`/bin/sh -lc` or `cmd.exe /c`).
+  In allowlist mode on Windows node hosts, `cmd.exe /c` shell-wrapper runs require approval
+  (allowlist entry alone does not auto-allow the wrapper form).
+- `--agent <id>`: agent-scoped approvals/allowlists (defaults to configured agent).
+- `--ask <off|on-miss|always>`, `--security <deny|allowlist|full>`: overrides.