@quantumclaw/quantumclaw 2026.3.22

package/docs/gateway/authentication.md

@@ -0,0 +1,179 @@
+---
+summary: "Model authentication: OAuth, API keys, and setup-token"
+read_when:
+  - Debugging model auth or OAuth expiry
+  - Documenting authentication or credential storage
+title: "Authentication"
+---
+
+# Authentication
+
+QuantumClaw supports OAuth and API keys for model providers. For always-on gateway
+hosts, API keys are usually the most predictable option. Subscription/OAuth
+flows are also supported when they match your provider account model.
+
+See [/concepts/oauth](/concepts/oauth) for the full OAuth flow and storage
+layout.
+For SecretRef-based auth (`env`/`file`/`exec` providers), see [Secrets Management](/gateway/secrets).
+For credential eligibility/reason-code rules used by `models status --probe`, see
+[Auth Credential Semantics](/auth-credential-semantics).
+
+## Recommended setup (API key, any provider)
+
+If you’re running a long-lived gateway, start with an API key for your chosen
+provider.
+For Anthropic specifically, API key auth is the safe path and is recommended
+over subscription setup-token auth.
+
+1. Create an API key in your provider console.
+2. Put it on the **gateway host** (the machine running `quantumclaw gateway`).
+
+```bash
+export <PROVIDER>_API_KEY="..."
+quantumclaw models status
+```
+
+3. If the Gateway runs under systemd/launchd, prefer putting the key in
+   `~/.quantumclaw/.env` so the daemon can read it:
+
+```bash
+cat >> ~/.quantumclaw/.env <<'EOF'
+<PROVIDER>_API_KEY=...
+EOF
+```
+
+Then restart the daemon (or restart your Gateway process) and re-check:
+
+```bash
+quantumclaw models status
+quantumclaw doctor
+```
+
+If you’d rather not manage env vars yourself, onboarding can store
+API keys for daemon use: `quantumclaw onboard`.
+
+See [Help](/help) for details on env inheritance (`env.shellEnv`,
+`~/.quantumclaw/.env`, systemd/launchd).
+
+## Anthropic: setup-token (subscription auth)
+
+If you’re using a Claude subscription, the setup-token flow is supported. Run
+it on the **gateway host**:
+
+```bash
+claude setup-token
+```
+
+Then paste it into QuantumClaw:
+
+```bash
+quantumclaw models auth setup-token --provider anthropic
+```
+
+If the token was created on another machine, paste it manually:
+
+```bash
+quantumclaw models auth paste-token --provider anthropic
+```
+
+If you see an Anthropic error like:
+
+```
+This credential is only authorized for use with Claude Code and cannot be used for other API requests.
+```
+
+…use an Anthropic API key instead.
+
+<Warning>
+Anthropic setup-token support is technical compatibility only. Anthropic has blocked
+some subscription usage outside Claude Code in the past. Use it only if you decide
+the policy risk is acceptable, and verify Anthropic's current terms yourself.
+</Warning>
+
+Manual token entry (any provider; writes `auth-profiles.json` + updates config):
+
+```bash
+quantumclaw models auth paste-token --provider anthropic
+quantumclaw models auth paste-token --provider openrouter
+```
+
+Auth profile refs are also supported for static credentials:
+
+- `api_key` credentials can use `keyRef: { source, provider, id }`
+- `token` credentials can use `tokenRef: { source, provider, id }`
+
+Automation-friendly check (exit `1` when expired/missing, `2` when expiring):
+
+```bash
+quantumclaw models status --check
+```
+
+Optional ops scripts (systemd/Termux) are documented here:
+[/automation/auth-monitoring](/automation/auth-monitoring)
+
+> `claude setup-token` requires an interactive TTY.
+
+## Checking model auth status
+
+```bash
+quantumclaw models status
+quantumclaw doctor
+```
+
+## API key rotation behavior (gateway)
+
+Some providers support retrying a request with alternative keys when an API call
+hits a provider rate limit.
+
+- Priority order:
+  - `QUANTUMCLAW_LIVE_<PROVIDER>_KEY` (single override)
+  - `<PROVIDER>_API_KEYS`
+  - `<PROVIDER>_API_KEY`
+  - `<PROVIDER>_API_KEY_*`
+- Google providers also include `GOOGLE_API_KEY` as an additional fallback.
+- The same key list is deduplicated before use.
+- QuantumClaw retries with the next key only for rate-limit errors (for example
+  `429`, `rate_limit`, `quota`, `resource exhausted`).
+- Non-rate-limit errors are not retried with alternate keys.
+- If all keys fail, the final error from the last attempt is returned.
+
+## Controlling which credential is used
+
+### Per-session (chat command)
+
+Use `/model <alias-or-id>@<profileId>` to pin a specific provider credential for the current session (example profile ids: `anthropic:default`, `anthropic:work`).
+
+Use `/model` (or `/model list`) for a compact picker; use `/model status` for the full view (candidates + next auth profile, plus provider endpoint details when configured).
+
+### Per-agent (CLI override)
+
+Set an explicit auth profile order override for an agent (stored in that agent’s `auth-profiles.json`):
+
+```bash
+quantumclaw models auth order get --provider anthropic
+quantumclaw models auth order set --provider anthropic anthropic:default
+quantumclaw models auth order clear --provider anthropic
+```
+
+Use `--agent <id>` to target a specific agent; omit it to use the configured default agent.
+
+## Troubleshooting
+
+### "No credentials found"
+
+If the Anthropic token profile is missing, run `claude setup-token` on the
+**gateway host**, then re-check:
+
+```bash
+quantumclaw models status
+```
+
+### Token expiring/expired
+
+Run `quantumclaw models status` to confirm which profile is expiring. If the profile
+is missing, rerun `claude setup-token` and paste the token again.
+
+## Requirements
+
+- Anthropic subscription account (for `claude setup-token`)
+- Claude Code CLI installed (`claude` command available)

package/docs/gateway/background-process.md

@@ -0,0 +1,97 @@
+---
+summary: "Background exec execution and process management"
+read_when:
+  - Adding or modifying background exec behavior
+  - Debugging long-running exec tasks
+title: "Background Exec and Process Tool"
+---
+
+# Background Exec + Process Tool
+
+QuantumClaw runs shell commands through the `exec` tool and keeps long‑running tasks in memory. The `process` tool manages those background sessions.
+
+## exec tool
+
+Key parameters:
+
+- `command` (required)
+- `yieldMs` (default 10000): auto‑background after this delay
+- `background` (bool): background immediately
+- `timeout` (seconds, default 1800): kill the process after this timeout
+- `elevated` (bool): run on host if elevated mode is enabled/allowed
+- Need a real TTY? Set `pty: true`.
+- `workdir`, `env`
+
+Behavior:
+
+- Foreground runs return output directly.
+- When backgrounded (explicit or timeout), the tool returns `status: "running"` + `sessionId` and a short tail.
+- Output is kept in memory until the session is polled or cleared.
+- If the `process` tool is disallowed, `exec` runs synchronously and ignores `yieldMs`/`background`.
+- Spawned exec commands receive `QUANTUMCLAW_SHELL=exec` for context-aware shell/profile rules.
+
+## Child process bridging
+
+When spawning long-running child processes outside the exec/process tools (for example, CLI respawns or gateway helpers), attach the child-process bridge helper so termination signals are forwarded and listeners are detached on exit/error. This avoids orphaned processes on systemd and keeps shutdown behavior consistent across platforms.
+
+Environment overrides:
+
+- `PI_BASH_YIELD_MS`: default yield (ms)
+- `PI_BASH_MAX_OUTPUT_CHARS`: in‑memory output cap (chars)
+- `QUANTUMCLAW_BASH_PENDING_MAX_OUTPUT_CHARS`: pending stdout/stderr cap per stream (chars)
+- `PI_BASH_JOB_TTL_MS`: TTL for finished sessions (ms, bounded to 1m–3h)
+
+Config (preferred):
+
+- `tools.exec.backgroundMs` (default 10000)
+- `tools.exec.timeoutSec` (default 1800)
+- `tools.exec.cleanupMs` (default 1800000)
+- `tools.exec.notifyOnExit` (default true): enqueue a system event + request heartbeat when a backgrounded exec exits.
+- `tools.exec.notifyOnExitEmptySuccess` (default false): when true, also enqueue completion events for successful backgrounded runs that produced no output.
+
+## process tool
+
+Actions:
+
+- `list`: running + finished sessions
+- `poll`: drain new output for a session (also reports exit status)
+- `log`: read the aggregated output (supports `offset` + `limit`)
+- `write`: send stdin (`data`, optional `eof`)
+- `kill`: terminate a background session
+- `clear`: remove a finished session from memory
+- `remove`: kill if running, otherwise clear if finished
+
+Notes:
+
+- Only backgrounded sessions are listed/persisted in memory.
+- Sessions are lost on process restart (no disk persistence).
+- Session logs are only saved to chat history if you run `process poll/log` and the tool result is recorded.
+- `process` is scoped per agent; it only sees sessions started by that agent.
+- `process list` includes a derived `name` (command verb + target) for quick scans.
+- `process log` uses line-based `offset`/`limit`.
+- When both `offset` and `limit` are omitted, it returns the last 200 lines and includes a paging hint.
+- When `offset` is provided and `limit` is omitted, it returns from `offset` to the end (not capped to 200).
+
+## Examples
+
+Run a long task and poll later:
+
+```json
+{ "tool": "exec", "command": "sleep 5 && echo done", "yieldMs": 1000 }
+```
+
+```json
+{ "tool": "process", "action": "poll", "sessionId": "<id>" }
+```
+
+Start immediately in background:
+
+```json
+{ "tool": "exec", "command": "npm run build", "background": true }
+```
+
+Send stdin:
+
+```json
+{ "tool": "process", "action": "write", "sessionId": "<id>", "data": "y\n" }
+```

package/docs/gateway/bonjour.md

@@ -0,0 +1,177 @@
+---
+summary: "Bonjour/mDNS discovery + debugging (Gateway beacons, clients, and common failure modes)"
+read_when:
+  - Debugging Bonjour discovery issues on macOS/iOS
+  - Changing mDNS service types, TXT records, or discovery UX
+title: "Bonjour Discovery"
+---
+
+# Bonjour / mDNS discovery
+
+QuantumClaw uses Bonjour (mDNS / DNS‑SD) as a **LAN‑only convenience** to discover
+an active Gateway (WebSocket endpoint). It is best‑effort and does **not** replace SSH or
+Tailnet-based connectivity.
+
+## Wide-area Bonjour (Unicast DNS-SD) over Tailscale
+
+If the node and gateway are on different networks, multicast mDNS won’t cross the
+boundary. You can keep the same discovery UX by switching to **unicast DNS‑SD**
+("Wide‑Area Bonjour") over Tailscale.
+
+High‑level steps:
+
+1. Run a DNS server on the gateway host (reachable over Tailnet).
+2. Publish DNS‑SD records for `_quantumclaw-gw._tcp` under a dedicated zone
+   (example: `quantumclaw.internal.`).
+3. Configure Tailscale **split DNS** so your chosen domain resolves via that
+   DNS server for clients (including iOS).
+
+QuantumClaw supports any discovery domain; `quantumclaw.internal.` is just an example.
+iOS/Android nodes browse both `local.` and your configured wide‑area domain.
+
+### Gateway config (recommended)
+
+```json5
+{
+  gateway: { bind: "tailnet" }, // tailnet-only (recommended)
+  discovery: { wideArea: { enabled: true } }, // enables wide-area DNS-SD publishing
+}
+```
+
+### One-time DNS server setup (gateway host)
+
+```bash
+quantumclaw dns setup --apply
+```
+
+This installs CoreDNS and configures it to:
+
+- listen on port 53 only on the gateway’s Tailscale interfaces
+- serve your chosen domain (example: `quantumclaw.internal.`) from `~/.quantumclaw/dns/<domain>.db`
+
+Validate from a tailnet‑connected machine:
+
+```bash
+dns-sd -B _quantumclaw-gw._tcp quantumclaw.internal.
+dig @<TAILNET_IPV4> -p 53 _quantumclaw-gw._tcp.quantumclaw.internal PTR +short
+```
+
+### Tailscale DNS settings
+
+In the Tailscale admin console:
+
+- Add a nameserver pointing at the gateway’s tailnet IP (UDP/TCP 53).
+- Add split DNS so your discovery domain uses that nameserver.
+
+Once clients accept tailnet DNS, iOS nodes can browse
+`_quantumclaw-gw._tcp` in your discovery domain without multicast.
+
+### Gateway listener security (recommended)
+
+The Gateway WS port (default `18789`) binds to loopback by default. For LAN/tailnet
+access, bind explicitly and keep auth enabled.
+
+For tailnet‑only setups:
+
+- Set `gateway.bind: "tailnet"` in `~/.quantumclaw/quantumclaw.json`.
+- Restart the Gateway (or restart the macOS menubar app).
+
+## What advertises
+
+Only the Gateway advertises `_quantumclaw-gw._tcp`.
+
+## Service types
+
+- `_quantumclaw-gw._tcp` — gateway transport beacon (used by macOS/iOS/Android nodes).
+
+## TXT keys (non-secret hints)
+
+The Gateway advertises small non‑secret hints to make UI flows convenient:
+
+- `role=gateway`
+- `displayName=<friendly name>`
+- `lanHost=<hostname>.local`
+- `gatewayPort=<port>` (Gateway WS + HTTP)
+- `gatewayTls=1` (only when TLS is enabled)
+- `gatewayTlsSha256=<sha256>` (only when TLS is enabled and fingerprint is available)
+- `canvasPort=<port>` (only when the canvas host is enabled; currently the same as `gatewayPort`)
+- `sshPort=<port>` (defaults to 22 when not overridden)
+- `transport=gateway`
+- `cliPath=<path>` (optional; absolute path to a runnable `quantumclaw` entrypoint)
+- `tailnetDns=<magicdns>` (optional hint when Tailnet is available)
+
+Security notes:
+
+- Bonjour/mDNS TXT records are **unauthenticated**. Clients must not treat TXT as authoritative routing.
+- Clients should route using the resolved service endpoint (SRV + A/AAAA). Treat `lanHost`, `tailnetDns`, `gatewayPort`, and `gatewayTlsSha256` as hints only.
+- 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 explicit user confirmation before trusting a first-time fingerprint.
+
+## Debugging on macOS
+
+Useful built‑in tools:
+
+- Browse instances:
+
+  ```bash
+  dns-sd -B _quantumclaw-gw._tcp local.
+  ```
+
+- Resolve one instance (replace `<instance>`):
+
+  ```bash
+  dns-sd -L "<instance>" _quantumclaw-gw._tcp local.
+  ```
+
+If browsing works but resolving fails, you’re usually hitting a LAN policy or
+mDNS resolver issue.
+
+## Debugging in Gateway logs
+
+The Gateway writes a rolling log file (printed on startup as
+`gateway log file: ...`). Look for `bonjour:` lines, especially:
+
+- `bonjour: advertise failed ...`
+- `bonjour: ... name conflict resolved` / `hostname conflict resolved`
+- `bonjour: watchdog detected non-announced service ...`
+
+## Debugging on iOS node
+
+The iOS node uses `NWBrowser` to discover `_quantumclaw-gw._tcp`.
+
+To capture logs:
+
+- Settings → Gateway → Advanced → **Discovery Debug Logs**
+- Settings → Gateway → Advanced → **Discovery Logs** → reproduce → **Copy**
+
+The log includes browser state transitions and result‑set changes.
+
+## Common failure modes
+
+- **Bonjour doesn’t cross networks**: use Tailnet or SSH.
+- **Multicast blocked**: some Wi‑Fi networks disable mDNS.
+- **Sleep / interface churn**: macOS may temporarily drop mDNS results; retry.
+- **Browse works but resolve fails**: keep machine names simple (avoid emojis or
+  punctuation), then restart the Gateway. The service instance name derives from
+  the host name, so overly complex names can confuse some resolvers.
+
+## Escaped instance names (`\032`)
+
+Bonjour/DNS‑SD often escapes bytes in service instance names as decimal `\DDD`
+sequences (e.g. spaces become `\032`).
+
+- This is normal at the protocol level.
+- UIs should decode for display (iOS uses `BonjourEscapes.decode`).
+
+## Disabling / configuration
+
+- `QUANTUMCLAW_DISABLE_BONJOUR=1` disables advertising (legacy: `QUANTUMCLAW_DISABLE_BONJOUR`).
+- `gateway.bind` in `~/.quantumclaw/quantumclaw.json` controls the Gateway bind mode.
+- `QUANTUMCLAW_SSH_PORT` overrides the SSH port advertised in TXT (legacy: `QUANTUMCLAW_SSH_PORT`).
+- `QUANTUMCLAW_TAILNET_DNS` publishes a MagicDNS hint in TXT (legacy: `QUANTUMCLAW_TAILNET_DNS`).
+- `QUANTUMCLAW_CLI_PATH` overrides the advertised CLI path (legacy: `QUANTUMCLAW_CLI_PATH`).
+
+## Related docs
+
+- Discovery policy and transport selection: [Discovery](/gateway/discovery)
+- Node pairing + approvals: [Gateway pairing](/gateway/pairing)

package/docs/gateway/bridge-protocol.md

@@ -0,0 +1,91 @@
+---
+summary: "Bridge protocol (legacy nodes): TCP JSONL, pairing, scoped RPC"
+read_when:
+  - Building or debugging node clients (iOS/Android/macOS node mode)
+  - Investigating pairing or bridge auth failures
+  - Auditing the node surface exposed by the gateway
+title: "Bridge Protocol"
+---
+
+# Bridge protocol (legacy node transport)
+
+The Bridge protocol is a **legacy** node transport (TCP JSONL). New node clients
+should use the unified Gateway WebSocket protocol instead.
+
+If you are building an operator or node client, use the
+[Gateway protocol](/gateway/protocol).
+
+**Note:** Current QuantumClaw builds no longer ship the TCP bridge listener; this document is kept for historical reference.
+Legacy `bridge.*` config keys are no longer part of the config schema.
+
+## Why we have both
+
+- **Security boundary**: the bridge exposes a small allowlist instead of the
+  full gateway API surface.
+- **Pairing + node identity**: node admission is owned by the gateway and tied
+  to a per-node token.
+- **Discovery UX**: nodes can discover gateways via Bonjour on LAN, or connect
+  directly over a tailnet.
+- **Loopback WS**: the full WS control plane stays local unless tunneled via SSH.
+
+## Transport
+
+- TCP, one JSON object per line (JSONL).
+- Optional TLS (when `bridge.tls.enabled` is true).
+- Legacy default listener port was `18790` (current builds do not start a TCP bridge).
+
+When TLS is enabled, discovery TXT records include `bridgeTls=1` plus
+`bridgeTlsSha256` as a non-secret hint. Note that Bonjour/mDNS TXT records are
+unauthenticated; clients must not treat the advertised fingerprint as an
+authoritative pin without explicit user intent or other out-of-band verification.
+
+## Handshake + pairing
+
+1. Client sends `hello` with node metadata + token (if already paired).
+2. If not paired, gateway replies `error` (`NOT_PAIRED`/`UNAUTHORIZED`).
+3. Client sends `pair-request`.
+4. Gateway waits for approval, then sends `pair-ok` and `hello-ok`.
+
+`hello-ok` returns `serverName` and may include `canvasHostUrl`.
+
+## Frames
+
+Client → Gateway:
+
+- `req` / `res`: scoped gateway RPC (chat, sessions, config, health, voicewake, skills.bins)
+- `event`: node signals (voice transcript, agent request, chat subscribe, exec lifecycle)
+
+Gateway → Client:
+
+- `invoke` / `invoke-res`: node commands (`canvas.*`, `camera.*`, `screen.record`,
+  `location.get`, `sms.send`)
+- `event`: chat updates for subscribed sessions
+- `ping` / `pong`: keepalive
+
+Legacy allowlist enforcement lived in `src/gateway/server-bridge.ts` (removed).
+
+## Exec lifecycle events
+
+Nodes can emit `exec.finished` or `exec.denied` events to surface system.run activity.
+These are mapped to system events in the gateway. (Legacy nodes may still emit `exec.started`.)
+
+Payload fields (all optional unless noted):
+
+- `sessionKey` (required): agent session to receive the system event.
+- `runId`: unique exec id for grouping.
+- `command`: raw or formatted command string.
+- `exitCode`, `timedOut`, `success`, `output`: completion details (finished only).
+- `reason`: denial reason (denied only).
+
+## Tailnet usage
+
+- Bind the bridge to a tailnet IP: `bridge.bind: "tailnet"` in
+  `~/.quantumclaw/quantumclaw.json`.
+- Clients connect via MagicDNS name or tailnet IP.
+- Bonjour does **not** cross networks; use manual host/port or wide-area DNS‑SD
+  when needed.
+
+## Versioning
+
+Bridge is currently **implicit v1** (no min/max negotiation). Backward‑compat
+is expected; add a bridge protocol version field before any breaking changes.