@quantumclaw/quantumclaw 2026.3.22

package/docs/gateway/discovery.md

@@ -0,0 +1,123 @@
+---
+summary: "Node discovery and transports (Bonjour, Tailscale, SSH) for finding the gateway"
+read_when:
+  - Implementing or changing Bonjour discovery/advertising
+  - Adjusting remote connection modes (direct vs SSH)
+  - Designing node discovery + pairing for remote nodes
+title: "Discovery and Transports"
+---
+
+# Discovery & transports
+
+QuantumClaw has two distinct problems that look similar on the surface:
+
+1. **Operator remote control**: the macOS menu bar app controlling a gateway running elsewhere.
+2. **Node pairing**: iOS/Android (and future nodes) finding a gateway and pairing securely.
+
+The design goal is to keep all network discovery/advertising in the **Node Gateway** (`quantumclaw gateway`) and keep clients (mac app, iOS) as consumers.
+
+## Terms
+
+- **Gateway**: a single long-running gateway process that owns state (sessions, pairing, node registry) and runs channels. Most setups use one per host; isolated multi-gateway setups are possible.
+- **Gateway WS (control plane)**: the WebSocket endpoint on `127.0.0.1:18789` by default; can be bound to LAN/tailnet via `gateway.bind`.
+- **Direct WS transport**: a LAN/tailnet-facing Gateway WS endpoint (no SSH).
+- **SSH transport (fallback)**: remote control by forwarding `127.0.0.1:18789` over SSH.
+- **Legacy TCP bridge (deprecated/removed)**: older node transport (see [Bridge protocol](/gateway/bridge-protocol)); no longer advertised for discovery.
+
+Protocol details:
+
+- [Gateway protocol](/gateway/protocol)
+- [Bridge protocol (legacy)](/gateway/bridge-protocol)
+
+## Why we keep both "direct" and SSH
+
+- **Direct WS** is the best UX on the same network and within a tailnet:
+  - auto-discovery on LAN via Bonjour
+  - pairing tokens + ACLs owned by the gateway
+  - no shell access required; protocol surface can stay tight and auditable
+- **SSH** remains the universal fallback:
+  - works anywhere you have SSH access (even across unrelated networks)
+  - survives multicast/mDNS issues
+  - requires no new inbound ports besides SSH
+
+## Discovery inputs (how clients learn where the gateway is)
+
+### 1) Bonjour / mDNS (LAN only)
+
+Bonjour is best-effort and does not cross networks. It is only used for “same LAN” convenience.
+
+Target direction:
+
+- The **gateway** advertises its WS endpoint via Bonjour.
+- Clients browse and show a “pick a gateway” list, then store the chosen endpoint.
+
+Troubleshooting and beacon details: [Bonjour](/gateway/bonjour).
+
+#### Service beacon details
+
+- Service types:
+  - `_quantumclaw-gw._tcp` (gateway transport beacon)
+- TXT keys (non-secret):
+  - `role=gateway`
+  - `lanHost=<hostname>.local`
+  - `sshPort=22` (or whatever is advertised)
+  - `gatewayPort=18789` (Gateway WS + HTTP)
+  - `gatewayTls=1` (only when TLS is enabled)
+  - `gatewayTlsSha256=<sha256>` (only when TLS is enabled and fingerprint is available)
+  - `canvasPort=<port>` (canvas host port; currently the same as `gatewayPort` when the canvas host is enabled)
+  - `cliPath=<path>` (optional; absolute path to a runnable `quantumclaw` entrypoint or binary)
+  - `tailnetDns=<magicdns>` (optional hint; auto-detected when Tailscale is available)
+
+Security notes:
+
+- Bonjour/mDNS TXT records are **unauthenticated**. Clients must treat TXT values as UX hints only.
+- Routing (host/port) should prefer the **resolved service endpoint** (SRV + A/AAAA) over TXT-provided `lanHost`, `tailnetDns`, or `gatewayPort`.
+- TLS pinning must never allow an advertised `gatewayTlsSha256` to override a previously stored pin.
+- iOS/Android nodes should treat discovery-based direct connects as **TLS-only** and require an explicit “trust this fingerprint” confirmation before storing a first-time pin (out-of-band verification).
+
+Disable/override:
+
+- `QUANTUMCLAW_DISABLE_BONJOUR=1` disables advertising.
+- `gateway.bind` in `~/.quantumclaw/quantumclaw.json` controls the Gateway bind mode.
+- `QUANTUMCLAW_SSH_PORT` overrides the SSH port advertised in TXT (defaults to 22).
+- `QUANTUMCLAW_TAILNET_DNS` publishes a `tailnetDns` hint (MagicDNS).
+- `QUANTUMCLAW_CLI_PATH` overrides the advertised CLI path.
+
+### 2) Tailnet (cross-network)
+
+For London/Vienna style setups, Bonjour won’t help. The recommended “direct” target is:
+
+- Tailscale MagicDNS name (preferred) or a stable tailnet IP.
+
+If the gateway can detect it is running under Tailscale, it publishes `tailnetDns` as an optional hint for clients (including wide-area beacons).
+
+### 3) Manual / SSH target
+
+When there is no direct route (or direct is disabled), clients can always connect via SSH by forwarding the loopback gateway port.
+
+See [Remote access](/gateway/remote).
+
+## Transport selection (client policy)
+
+Recommended client behavior:
+
+1. If a paired direct endpoint is configured and reachable, use it.
+2. Else, if Bonjour finds a gateway on LAN, offer a one-tap “Use this gateway” choice and save it as the direct endpoint.
+3. Else, if a tailnet DNS/IP is configured, try direct.
+4. Else, fall back to SSH.
+
+## Pairing + auth (direct transport)
+
+The gateway is the source of truth for node/client admission.
+
+- Pairing requests are created/approved/rejected in the gateway (see [Gateway pairing](/gateway/pairing)).
+- The gateway enforces:
+  - auth (token / keypair)
+  - scopes/ACLs (the gateway is not a raw proxy to every method)
+  - rate limits
+
+## Responsibilities by component
+
+- **Gateway**: advertises discovery beacons, owns pairing decisions, and hosts the WS endpoint.
+- **macOS app**: helps you pick a gateway, shows pairing prompts, and uses SSH only as a fallback.
+- **iOS/Android nodes**: browse Bonjour as a convenience and connect to the paired Gateway WS.

package/docs/gateway/doctor.md

@@ -0,0 +1,362 @@
+---
+summary: "Doctor command: health checks, config migrations, and repair steps"
+read_when:
+  - Adding or modifying doctor migrations
+  - Introducing breaking config changes
+title: "Doctor"
+---
+
+# Doctor
+
+`quantumclaw doctor` is the repair + migration tool for QuantumClaw. It fixes stale
+config/state, checks health, and provides actionable repair steps.
+
+## Quick start
+
+```bash
+quantumclaw doctor
+```
+
+### Headless / automation
+
+```bash
+quantumclaw doctor --yes
+```
+
+Accept defaults without prompting (including restart/service/sandbox repair steps when applicable).
+
+```bash
+quantumclaw doctor --repair
+```
+
+Apply recommended repairs without prompting (repairs + restarts where safe).
+
+```bash
+quantumclaw doctor --repair --force
+```
+
+Apply aggressive repairs too (overwrites custom supervisor configs).
+
+```bash
+quantumclaw doctor --non-interactive
+```
+
+Run without prompts and only apply safe migrations (config normalization + on-disk state moves). Skips restart/service/sandbox actions that require human confirmation.
+Legacy state migrations run automatically when detected.
+
+```bash
+quantumclaw doctor --deep
+```
+
+Scan system services for extra gateway installs (launchd/systemd/schtasks).
+
+If you want to review changes before writing, open the config file first:
+
+```bash
+cat ~/.quantumclaw/quantumclaw.json
+```
+
+## What it does (summary)
+
+- Optional pre-flight update for git installs (interactive only).
+- UI protocol freshness check (rebuilds Control UI when the protocol schema is newer).
+- Health check + restart prompt.
+- Skills status summary (eligible/missing/blocked).
+- Config normalization for legacy values.
+- Browser migration checks for legacy Chrome extension configs and Chrome MCP readiness.
+- OpenCode provider override warnings (`models.providers.opencode` / `models.providers.opencode-go`).
+- Legacy on-disk state migration (sessions/agent dir/WhatsApp auth).
+- Legacy cron store migration (`jobId`, `schedule.cron`, top-level delivery/payload fields, payload `provider`, simple `notify: true` webhook fallback jobs).
+- State integrity and permissions checks (sessions, transcripts, state dir).
+- Config file permission checks (chmod 600) when running locally.
+- Model auth health: checks OAuth expiry, can refresh expiring tokens, and reports auth-profile cooldown/disabled states.
+- Extra workspace dir detection (`~/quantumclaw`).
+- Sandbox image repair when sandboxing is enabled.
+- Legacy service migration and extra gateway detection.
+- Gateway runtime checks (service installed but not running; cached launchd label).
+- Channel status warnings (probed from the running gateway).
+- Supervisor config audit (launchd/systemd/schtasks) with optional repair.
+- Gateway runtime best-practice checks (Node vs Bun, version-manager paths).
+- Gateway port collision diagnostics (default `18789`).
+- Security warnings for open DM policies.
+- Gateway auth checks for local token mode (offers token generation when no token source exists; does not overwrite token SecretRef configs).
+- systemd linger check on Linux.
+- Source install checks (pnpm workspace mismatch, missing UI assets, missing tsx binary).
+- Writes updated config + wizard metadata.
+
+## Detailed behavior and rationale
+
+### 0) Optional update (git installs)
+
+If this is a git checkout and doctor is running interactively, it offers to
+update (fetch/rebase/build) before running doctor.
+
+### 1) Config normalization
+
+If the config contains legacy value shapes (for example `messages.ackReaction`
+without a channel-specific override), doctor normalizes them into the current
+schema.
+
+### 2) Legacy config key migrations
+
+When the config contains deprecated keys, other commands refuse to run and ask
+you to run `quantumclaw doctor`.
+
+Doctor will:
+
+- Explain which legacy keys were found.
+- Show the migration it applied.
+- Rewrite `~/.quantumclaw/quantumclaw.json` with the updated schema.
+
+The Gateway also auto-runs doctor migrations on startup when it detects a
+legacy config format, so stale configs are repaired without manual intervention.
+
+Current migrations:
+
+- `routing.allowFrom` → `channels.whatsapp.allowFrom`
+- `routing.groupChat.requireMention` → `channels.whatsapp/telegram/imessage.groups."*".requireMention`
+- `routing.groupChat.historyLimit` → `messages.groupChat.historyLimit`
+- `routing.groupChat.mentionPatterns` → `messages.groupChat.mentionPatterns`
+- `routing.queue` → `messages.queue`
+- `routing.bindings` → top-level `bindings`
+- `routing.agents`/`routing.defaultAgentId` → `agents.list` + `agents.list[].default`
+- `routing.agentToAgent` → `tools.agentToAgent`
+- `routing.transcribeAudio` → `tools.media.audio.models`
+- `bindings[].match.accountID` → `bindings[].match.accountId`
+- For channels with named `accounts` but missing `accounts.default`, move account-scoped top-level single-account channel values into `channels.<channel>.accounts.default` when present
+- `identity` → `agents.list[].identity`
+- `agent.*` → `agents.defaults` + `tools.*` (tools/elevated/exec/sandbox/subagents)
+- `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks`
+  → `agents.defaults.models` + `agents.defaults.model.primary/fallbacks` + `agents.defaults.imageModel.primary/fallbacks`
+- `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`
+- `browser.profiles.*.driver: "extension"` → `"existing-session"`
+- remove `browser.relayBindHost` (legacy extension relay setting)
+
+Doctor warnings also include account-default guidance for multi-account channels:
+
+- If two or more `channels.<channel>.accounts` entries are configured without `channels.<channel>.defaultAccount` or `accounts.default`, doctor warns that fallback routing can pick an unexpected account.
+- If `channels.<channel>.defaultAccount` is set to an unknown account ID, doctor warns and lists configured account IDs.
+
+### 2b) OpenCode provider overrides
+
+If you’ve added `models.providers.opencode`, `opencode-zen`, or `opencode-go`
+manually, it overrides the built-in OpenCode catalog from `@mariozechner/pi-ai`.
+That can force models onto the wrong API or zero out costs. Doctor warns so you
+can remove the override and restore per-model API routing + costs.
+
+### 2c) Browser migration and Chrome MCP readiness
+
+If your browser config still points at the removed Chrome extension path, doctor
+normalizes it to the current host-local Chrome MCP attach model:
+
+- `browser.profiles.*.driver: "extension"` becomes `"existing-session"`
+- `browser.relayBindHost` is removed
+
+Doctor also audits the host-local Chrome MCP path when you use `defaultProfile:
+"user"` or a configured `existing-session` profile:
+
+- checks whether Google Chrome is installed on the same host for default
+  auto-connect profiles
+- checks the detected Chrome version and warns when it is below Chrome 144
+- reminds you to enable remote debugging in the browser inspect page (for
+  example `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging`,
+  or `edge://inspect/#remote-debugging`)
+
+Doctor cannot enable the Chrome-side setting for you. Host-local Chrome MCP
+still requires:
+
+- a Chromium-based browser 144+ on the gateway/node host
+- the browser running locally
+- remote debugging enabled in that browser
+- approving the first attach consent prompt in the browser
+
+This check does **not** apply to Docker, sandbox, remote-browser, or other
+headless flows. Those continue to use raw CDP.
+
+### 3) Legacy state migrations (disk layout)
+
+Doctor can migrate older on-disk layouts into the current structure:
+
+- Sessions store + transcripts:
+  - from `~/.quantumclaw/sessions/` to `~/.quantumclaw/agents/<agentId>/sessions/`
+- Agent dir:
+  - from `~/.quantumclaw/agent/` to `~/.quantumclaw/agents/<agentId>/agent/`
+- WhatsApp auth state (Baileys):
+  - from legacy `~/.quantumclaw/credentials/*.json` (except `oauth.json`)
+  - to `~/.quantumclaw/credentials/whatsapp/<accountId>/...` (default account id: `default`)
+
+These migrations are best-effort and idempotent; doctor will emit warnings when
+it leaves any legacy folders behind as backups. The Gateway/CLI also auto-migrates
+the legacy sessions + agent dir on startup so history/auth/models land in the
+per-agent path without a manual doctor run. WhatsApp auth is intentionally only
+migrated via `quantumclaw doctor`.
+
+### 3b) Legacy cron store migrations
+
+Doctor also checks the cron job store (`~/.quantumclaw/cron/jobs.json` by default,
+or `cron.store` when overridden) for old job shapes that the scheduler still
+accepts for compatibility.
+
+Current cron cleanups include:
+
+- `jobId` → `id`
+- `schedule.cron` → `schedule.expr`
+- top-level payload fields (`message`, `model`, `thinking`, ...) → `payload`
+- top-level delivery fields (`deliver`, `channel`, `to`, `provider`, ...) → `delivery`
+- payload `provider` delivery aliases → explicit `delivery.channel`
+- simple legacy `notify: true` webhook fallback jobs → explicit `delivery.mode="webhook"` with `delivery.to=cron.webhook`
+
+Doctor only auto-migrates `notify: true` jobs when it can do so without
+changing behavior. If a job combines legacy notify fallback with an existing
+non-webhook delivery mode, doctor warns and leaves that job for manual review.
+
+### 4) State integrity checks (session persistence, routing, and safety)
+
+The state directory is the operational brainstem. If it vanishes, you lose
+sessions, credentials, logs, and config (unless you have backups elsewhere).
+
+Doctor checks:
+
+- **State dir missing**: warns about catastrophic state loss, prompts to recreate
+  the directory, and reminds you that it cannot recover missing data.
+- **State dir permissions**: verifies writability; offers to repair permissions
+  (and emits a `chown` hint when owner/group mismatch is detected).
+- **macOS cloud-synced state dir**: warns when state resolves under iCloud Drive
+  (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) or
+  `~/Library/CloudStorage/...` because sync-backed paths can cause slower I/O
+  and lock/sync races.
+- **Linux SD or eMMC state dir**: warns when state resolves to an `mmcblk*`
+  mount source, because SD or eMMC-backed random I/O can be slower and wear
+  faster under session and credential writes.
+- **Session dirs missing**: `sessions/` and the session store directory are
+  required to persist history and avoid `ENOENT` crashes.
+- **Transcript mismatch**: warns when recent session entries have missing
+  transcript files.
+- **Main session “1-line JSONL”**: flags when the main transcript has only one
+  line (history is not accumulating).
+- **Multiple state dirs**: warns when multiple `~/.quantumclaw` folders exist across
+  home directories or when `QUANTUMCLAW_STATE_DIR` points elsewhere (history can
+  split between installs).
+- **Remote mode reminder**: if `gateway.mode=remote`, doctor reminds you to run
+  it on the remote host (the state lives there).
+- **Config file permissions**: warns if `~/.quantumclaw/quantumclaw.json` is
+  group/world readable and offers to tighten to `600`.
+
+### 5) Model auth health (OAuth expiry)
+
+Doctor inspects OAuth profiles in the auth store, warns when tokens are
+expiring/expired, and can refresh them when safe. If the Anthropic Claude Code
+profile is stale, it suggests running `claude setup-token` (or pasting a setup-token).
+Refresh prompts only appear when running interactively (TTY); `--non-interactive`
+skips refresh attempts.
+
+Doctor also reports auth profiles that are temporarily unusable due to:
+
+- short cooldowns (rate limits/timeouts/auth failures)
+- longer disables (billing/credit failures)
+
+### 6) Hooks model validation
+
+If `hooks.gmail.model` is set, doctor validates the model reference against the
+catalog and allowlist and warns when it won’t resolve or is disallowed.
+
+### 7) Sandbox image repair
+
+When sandboxing is enabled, doctor checks Docker images and offers to build or
+switch to legacy names if the current image is missing.
+
+### 8) Gateway service migrations and cleanup hints
+
+Doctor detects legacy gateway services (launchd/systemd/schtasks) and
+offers to remove them and install the QuantumClaw service using the current gateway
+port. It can also scan for extra gateway-like services and print cleanup hints.
+Profile-named QuantumClaw gateway services are considered first-class and are not
+flagged as "extra."
+
+### 9) Security warnings
+
+Doctor emits warnings when a provider is open to DMs without an allowlist, or
+when a policy is configured in a dangerous way.
+
+### 10) systemd linger (Linux)
+
+If running as a systemd user service, doctor ensures lingering is enabled so the
+gateway stays alive after logout.
+
+### 11) Skills status
+
+Doctor prints a quick summary of eligible/missing/blocked skills for the current
+workspace.
+
+### 12) Gateway auth checks (local token)
+
+Doctor checks local gateway token auth readiness.
+
+- If token mode needs a token and no token source exists, doctor offers to generate one.
+- If `gateway.auth.token` is SecretRef-managed but unavailable, doctor warns and does not overwrite it with plaintext.
+- `quantumclaw doctor --generate-gateway-token` forces generation only when no token SecretRef is configured.
+
+### 12b) Read-only SecretRef-aware repairs
+
+Some repair flows need to inspect configured credentials without weakening runtime fail-fast behavior.
+
+- `quantumclaw doctor --fix` now uses the same read-only SecretRef summary model as status-family commands for targeted config repairs.
+- Example: Telegram `allowFrom` / `groupAllowFrom` `@username` repair tries to use configured bot credentials when available.
+- If the Telegram bot token is configured via SecretRef but unavailable in the current command path, doctor reports that the credential is configured-but-unavailable and skips auto-resolution instead of crashing or misreporting the token as missing.
+
+### 13) Gateway health check + restart
+
+Doctor runs a health check and offers to restart the gateway when it looks
+unhealthy.
+
+### 14) Channel status warnings
+
+If the gateway is healthy, doctor runs a channel status probe and reports
+warnings with suggested fixes.
+
+### 15) Supervisor config audit + repair
+
+Doctor checks the installed supervisor config (launchd/systemd/schtasks) for
+missing or outdated defaults (e.g., systemd network-online dependencies and
+restart delay). When it finds a mismatch, it recommends an update and can
+rewrite the service file/task to the current defaults.
+
+Notes:
+
+- `quantumclaw doctor` prompts before rewriting supervisor config.
+- `quantumclaw doctor --yes` accepts the default repair prompts.
+- `quantumclaw doctor --repair` applies recommended fixes without prompts.
+- `quantumclaw doctor --repair --force` overwrites custom supervisor configs.
+- If token auth requires a token and `gateway.auth.token` is SecretRef-managed, doctor service install/repair 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, doctor blocks the install/repair path with actionable guidance.
+- If both `gateway.auth.token` and `gateway.auth.password` are configured and `gateway.auth.mode` is unset, doctor blocks install/repair until mode is set explicitly.
+- For Linux user-systemd units, doctor token drift checks now include both `Environment=` and `EnvironmentFile=` sources when comparing service auth metadata.
+- You can always force a full rewrite via `quantumclaw gateway install --force`.
+
+### 16) Gateway runtime + port diagnostics
+
+Doctor inspects the service runtime (PID, last exit status) and warns when the
+service is installed but not actually running. It also checks for port collisions
+on the gateway port (default `18789`) and reports likely causes (gateway already
+running, SSH tunnel).
+
+### 17) Gateway runtime best practices
+
+Doctor warns when the gateway service runs on Bun or a version-managed Node path
+(`nvm`, `fnm`, `volta`, `asdf`, etc.). WhatsApp + Telegram channels require Node,
+and version-manager paths can break after upgrades because the service does not
+load your shell init. Doctor offers to migrate to a system Node install when
+available (Homebrew/apt/choco).
+
+### 18) Config write + wizard metadata
+
+Doctor persists any config changes and stamps wizard metadata to record the
+doctor run.
+
+### 19) Workspace tips (backup + memory system)
+
+Doctor suggests a workspace memory system when missing and prints a backup tip
+if the workspace is not already under git.
+
+See [/concepts/agent-workspace](/concepts/agent-workspace) for a full guide to
+workspace structure and git backup (recommended private GitHub or GitLab).

package/docs/gateway/gateway-lock.md

@@ -0,0 +1,34 @@
+---
+summary: "Gateway singleton guard using the WebSocket listener bind"
+read_when:
+  - Running or debugging the gateway process
+  - Investigating single-instance enforcement
+title: "Gateway Lock"
+---
+
+# Gateway lock
+
+Last updated: 2025-12-11
+
+## Why
+
+- Ensure only one gateway instance runs per base port on the same host; additional gateways must use isolated profiles and unique ports.
+- Survive crashes/SIGKILL without leaving stale lock files.
+- Fail fast with a clear error when the control port is already occupied.
+
+## Mechanism
+
+- The gateway binds the WebSocket listener (default `ws://127.0.0.1:18789`) immediately on startup using an exclusive TCP listener.
+- If the bind fails with `EADDRINUSE`, startup throws `GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>")`.
+- The OS releases the listener automatically on any process exit, including crashes and SIGKILL—no separate lock file or cleanup step is needed.
+- On shutdown the gateway closes the WebSocket server and underlying HTTP server to free the port promptly.
+
+## Error surface
+
+- If another process holds the port, startup throws `GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>")`.
+- Other bind failures surface as `GatewayLockError("failed to bind gateway socket on ws://127.0.0.1:<port>: …")`.
+
+## Operational notes
+
+- If the port is occupied by _another_ process, the error is the same; free the port or choose another with `quantumclaw gateway --port <port>`.
+- The macOS app still maintains its own lightweight PID guard before spawning the gateway; the runtime lock is enforced by the WebSocket bind.

package/docs/gateway/health.md

@@ -0,0 +1,44 @@
+---
+summary: "Health check steps for channel connectivity"
+read_when:
+  - Diagnosing WhatsApp channel health
+title: "Health Checks"
+---
+
+# Health Checks (CLI)
+
+Short guide to verify channel connectivity without guessing.
+
+## Quick checks
+
+- `quantumclaw status` — local summary: gateway reachability/mode, update hint, linked channel auth age, sessions + recent activity.
+- `quantumclaw status --all` — full local diagnosis (read-only, color, safe to paste for debugging).
+- `quantumclaw status --deep` — also probes the running Gateway (per-channel probes when supported).
+- `quantumclaw health --json` — asks the running Gateway for a full health snapshot (WS-only; no direct Baileys socket).
+- Send `/status` as a standalone message in WhatsApp/WebChat to get a status reply without invoking the agent.
+- Logs: tail `/tmp/quantumclaw/quantumclaw-*.log` and filter for `web-heartbeat`, `web-reconnect`, `web-auto-reply`, `web-inbound`.
+
+## Deep diagnostics
+
+- Creds on disk: `ls -l ~/.quantumclaw/credentials/whatsapp/<accountId>/creds.json` (mtime should be recent).
+- Session store: `ls -l ~/.quantumclaw/agents/<agentId>/sessions/sessions.json` (path can be overridden in config). Count and recent recipients are surfaced via `status`.
+- Relink flow: `quantumclaw channels logout && quantumclaw channels login --verbose` when status codes 409–515 or `loggedOut` appear in logs. (Note: the QR login flow auto-restarts once for status 515 after pairing.)
+
+## Health monitor config
+
+- `gateway.channelHealthCheckMinutes`: how often the gateway checks channel health. Default: `5`. Set `0` to disable health-monitor restarts globally.
+- `gateway.channelStaleEventThresholdMinutes`: how long a connected channel can stay idle before the health monitor treats it as stale and restarts it. Default: `30`. Keep this greater than or equal to `gateway.channelHealthCheckMinutes`.
+- `gateway.channelMaxRestartsPerHour`: rolling one-hour cap for health-monitor restarts per channel/account. Default: `10`.
+- `channels.<provider>.healthMonitor.enabled`: disable health-monitor restarts for a specific channel while leaving global monitoring enabled.
+- `channels.<provider>.accounts.<accountId>.healthMonitor.enabled`: multi-account override that wins over the channel-level setting.
+- These per-channel overrides apply to the built-in channel monitors that expose them today: Discord, Google Chat, iMessage, Microsoft Teams, Signal, Slack, Telegram, and WhatsApp.
+
+## When something fails
+
+- `logged out` or status 409–515 → relink with `quantumclaw channels logout` then `quantumclaw channels login`.
+- Gateway unreachable → start it: `quantumclaw gateway --port 18789` (use `--force` if the port is busy).
+- No inbound messages → confirm linked phone is online and the sender is allowed (`channels.whatsapp.allowFrom`); for group chats, ensure allowlist + mention rules match (`channels.whatsapp.groups`, `agents.list[].groupChat.mentionPatterns`).
+
+## Dedicated "health" command
+
+`quantumclaw health --json` asks the running Gateway for its health snapshot (no direct channel sockets from the CLI). It reports linked creds/auth age when available, per-channel probe summaries, session-store summary, and a probe duration. It exits non-zero if the Gateway is unreachable or the probe fails/timeouts. Use `--timeout <ms>` to override the 10s default.