@quantumclaw/quantumclaw 2026.3.22

package/docs/reference/transcript-hygiene.md

@@ -0,0 +1,151 @@
+---
+summary: "Reference: provider-specific transcript sanitization and repair rules"
+read_when:
+  - You are debugging provider request rejections tied to transcript shape
+  - You are changing transcript sanitization or tool-call repair logic
+  - You are investigating tool-call id mismatches across providers
+title: "Transcript Hygiene"
+---
+
+# Transcript Hygiene (Provider Fixups)
+
+This document describes **provider-specific fixes** applied to transcripts before a run
+(building model context). These are **in-memory** adjustments used to satisfy strict
+provider requirements. These hygiene steps do **not** rewrite the stored JSONL transcript
+on disk; however, a separate session-file repair pass may rewrite malformed JSONL files
+by dropping invalid lines before the session is loaded. When a repair occurs, the original
+file is backed up alongside the session file.
+
+Scope includes:
+
+- Tool call id sanitization
+- Tool call input validation
+- Tool result pairing repair
+- Turn validation / ordering
+- Thought signature cleanup
+- Image payload sanitization
+- User-input provenance tagging (for inter-session routed prompts)
+
+If you need transcript storage details, see:
+
+- [/reference/session-management-compaction](/reference/session-management-compaction)
+
+---
+
+## Where this runs
+
+All transcript hygiene is centralized in the embedded runner:
+
+- Policy selection: `src/agents/transcript-policy.ts`
+- Sanitization/repair application: `sanitizeSessionHistory` in `src/agents/pi-embedded-runner/google.ts`
+
+The policy uses `provider`, `modelApi`, and `modelId` to decide what to apply.
+
+Separate from transcript hygiene, session files are repaired (if needed) before load:
+
+- `repairSessionFileIfNeeded` in `src/agents/session-file-repair.ts`
+- Called from `run/attempt.ts` and `compact.ts` (embedded runner)
+
+---
+
+## Global rule: image sanitization
+
+Image payloads are always sanitized to prevent provider-side rejection due to size
+limits (downscale/recompress oversized base64 images).
+
+This also helps control image-driven token pressure for vision-capable models.
+Lower max dimensions generally reduce token usage; higher dimensions preserve detail.
+
+Implementation:
+
+- `sanitizeSessionMessagesImages` in `src/agents/pi-embedded-helpers/images.ts`
+- `sanitizeContentBlocksImages` in `src/agents/tool-images.ts`
+- Max image side is configurable via `agents.defaults.imageMaxDimensionPx` (default: `1200`).
+
+---
+
+## Global rule: malformed tool calls
+
+Assistant tool-call blocks that are missing both `input` and `arguments` are dropped
+before model context is built. This prevents provider rejections from partially
+persisted tool calls (for example, after a rate limit failure).
+
+Implementation:
+
+- `sanitizeToolCallInputs` in `src/agents/session-transcript-repair.ts`
+- Applied in `sanitizeSessionHistory` in `src/agents/pi-embedded-runner/google.ts`
+
+---
+
+## Global rule: inter-session input provenance
+
+When an agent sends a prompt into another session via `sessions_send` (including
+agent-to-agent reply/announce steps), QuantumClaw persists the created user turn with:
+
+- `message.provenance.kind = "inter_session"`
+
+This metadata is written at transcript append time and does not change role
+(`role: "user"` remains for provider compatibility). Transcript readers can use
+this to avoid treating routed internal prompts as end-user-authored instructions.
+
+During context rebuild, QuantumClaw also prepends a short `[Inter-session message]`
+marker to those user turns in-memory so the model can distinguish them from
+external end-user instructions.
+
+---
+
+## Provider matrix (current behavior)
+
+**OpenAI / OpenAI Codex**
+
+- Image sanitization only.
+- Drop orphaned reasoning signatures (standalone reasoning items without a following content block) for OpenAI Responses/Codex transcripts.
+- No tool call id sanitization.
+- No tool result pairing repair.
+- No turn validation or reordering.
+- No synthetic tool results.
+- No thought signature stripping.
+
+**Google (Generative AI / Gemini CLI / Antigravity)**
+
+- Tool call id sanitization: strict alphanumeric.
+- Tool result pairing repair and synthetic tool results.
+- Turn validation (Gemini-style turn alternation).
+- Google turn ordering fixup (prepend a tiny user bootstrap if history starts with assistant).
+- Antigravity Claude: normalize thinking signatures; drop unsigned thinking blocks.
+
+**Anthropic / Minimax (Anthropic-compatible)**
+
+- Tool result pairing repair and synthetic tool results.
+- Turn validation (merge consecutive user turns to satisfy strict alternation).
+
+**Mistral (including model-id based detection)**
+
+- Tool call id sanitization: strict9 (alphanumeric length 9).
+
+**OpenRouter Gemini**
+
+- Thought signature cleanup: strip non-base64 `thought_signature` values (keep base64).
+
+**Everything else**
+
+- Image sanitization only.
+
+---
+
+## Historical behavior (pre-2026.1.22)
+
+Before the 2026.1.22 release, QuantumClaw applied multiple layers of transcript hygiene:
+
+- A **transcript-sanitize extension** ran on every context build and could:
+  - Repair tool use/result pairing.
+  - Sanitize tool call ids (including a non-strict mode that preserved `_`/`-`).
+- The runner also performed provider-specific sanitization, which duplicated work.
+- Additional mutations occurred outside the provider policy, including:
+  - Stripping `<final>` tags from assistant text before persistence.
+  - Dropping empty assistant error turns.
+  - Trimming assistant content after tool calls.
+
+This complexity caused cross-provider regressions (notably `openai-responses`
+`call_id|fc_id` pairing). The 2026.1.22 cleanup removed the extension, centralized
+logic in the runner, and made OpenAI **no-touch** beyond image sanitization.

package/docs/reference/wizard.md

@@ -0,0 +1,235 @@
+---
+summary: "Full reference for CLI onboarding: every step, flag, and config field"
+read_when:
+  - Looking up a specific onboarding step or flag
+  - Automating onboarding with non-interactive mode
+  - Debugging onboarding behavior
+title: "Onboarding Reference"
+sidebarTitle: "Onboarding Reference"
+---
+
+# Onboarding Reference
+
+This is the full reference for `quantumclaw onboard`.
+For a high-level overview, see [Onboarding (CLI)](/start/wizard).
+
+## Flow details (local mode)
+
+<Steps>
+  <Step title="Existing config detection">
+    - If `~/.quantumclaw/quantumclaw.json` exists, choose **Keep / Modify / Reset**.
+    - Re-running onboarding does **not** wipe anything unless you explicitly choose **Reset**
+      (or pass `--reset`).
+    - CLI `--reset` defaults to `config+creds+sessions`; use `--reset-scope full`
+      to also remove workspace.
+    - If the config is invalid or contains legacy keys, the wizard stops and asks
+      you to run `quantumclaw doctor` before continuing.
+    - Reset uses `trash` (never `rm`) and offers scopes:
+      - Config only
+      - Config + credentials + sessions
+      - Full reset (also removes workspace)
+  </Step>
+  <Step title="Model/Auth">
+    - **Anthropic API key**: uses `ANTHROPIC_API_KEY` if present or prompts for a key, then saves it for daemon use.
+    - **Anthropic OAuth (Claude Code CLI)**: on macOS onboarding checks Keychain item "Claude Code-credentials" (choose "Always Allow" so launchd starts don't block); on Linux/Windows it reuses `~/.claude/.credentials.json` if present.
+    - **Anthropic token (paste setup-token)**: run `claude setup-token` on any machine, then paste the token (you can name it; blank = default).
+    - **OpenAI Code (Codex) subscription (Codex CLI)**: if `~/.codex/auth.json` exists, onboarding can reuse it.
+    - **OpenAI Code (Codex) subscription (OAuth)**: browser flow; paste the `code#state`.
+      - Sets `agents.defaults.model` to `openai-codex/gpt-5.2` when model is unset or `openai/*`.
+    - **OpenAI API key**: uses `OPENAI_API_KEY` if present or prompts for a key, then stores it in auth profiles.
+    - **xAI (Grok) API key**: prompts for `XAI_API_KEY` and configures xAI as a model provider.
+    - **OpenCode**: prompts for `OPENCODE_API_KEY` (or `OPENCODE_ZEN_API_KEY`, get it at https://opencode.ai/auth) and lets you pick the Zen or Go catalog.
+    - **Ollama**: prompts for the Ollama base URL, offers **Cloud + Local** or **Local** mode, discovers available models, and auto-pulls the selected local model when needed.
+    - More detail: [Ollama](/providers/ollama)
+    - **API key**: stores the key for you.
+    - **Vercel AI Gateway (multi-model proxy)**: prompts for `AI_GATEWAY_API_KEY`.
+    - More detail: [Vercel AI Gateway](/providers/vercel-ai-gateway)
+    - **Cloudflare AI Gateway**: prompts for Account ID, Gateway ID, and `CLOUDFLARE_AI_GATEWAY_API_KEY`.
+    - More detail: [Cloudflare AI Gateway](/providers/cloudflare-ai-gateway)
+    - **MiniMax**: config is auto-written; hosted default is `MiniMax-M2.7` and `MiniMax-M2.5` stays available.
+    - More detail: [MiniMax](/providers/minimax)
+    - **Synthetic (Anthropic-compatible)**: prompts for `SYNTHETIC_API_KEY`.
+    - More detail: [Synthetic](/providers/synthetic)
+    - **Moonshot (Kimi K2)**: config is auto-written.
+    - **Kimi Coding**: config is auto-written.
+    - More detail: [Moonshot AI (Kimi + Kimi Coding)](/providers/moonshot)
+    - **Skip**: no auth configured yet.
+    - Pick a default model from detected options (or enter provider/model manually). For best quality and lower prompt-injection risk, choose the strongest latest-generation model available in your provider stack.
+    - Onboarding runs a model check and warns if the configured model is unknown or missing auth.
+    - API key storage mode defaults to plaintext auth-profile values. Use `--secret-input-mode ref` to store env-backed refs instead (for example `keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }`).
+    - OAuth credentials live in `~/.quantumclaw/credentials/oauth.json`; auth profiles live in `~/.quantumclaw/agents/<agentId>/agent/auth-profiles.json` (API keys + OAuth).
+    - More detail: [/concepts/oauth](/concepts/oauth)
+    <Note>
+    Headless/server tip: complete OAuth on a machine with a browser, then copy
+    `~/.quantumclaw/credentials/oauth.json` (or `$QUANTUMCLAW_STATE_DIR/credentials/oauth.json`) to the
+    gateway host.
+    </Note>
+  </Step>
+  <Step title="Workspace">
+    - Default `~/.quantumclaw/workspace` (configurable).
+    - Seeds the workspace files needed for the agent bootstrap ritual.
+    - Full workspace layout + backup guide: [Agent workspace](/concepts/agent-workspace)
+  </Step>
+  <Step title="Gateway">
+    - Port, bind, auth mode, tailscale exposure.
+    - Auth recommendation: keep **Token** even for loopback so local WS clients must authenticate.
+    - In token mode, interactive setup offers:
+      - **Generate/store plaintext token** (default)
+      - **Use SecretRef** (opt-in)
+      - Quickstart reuses existing `gateway.auth.token` SecretRefs across `env`, `file`, and `exec` providers for onboarding probe/dashboard bootstrap.
+      - If that SecretRef is configured but cannot be resolved, onboarding fails early with a clear fix message instead of silently degrading runtime auth.
+    - In password mode, interactive setup also supports plaintext or SecretRef storage.
+    - Non-interactive token SecretRef path: `--gateway-token-ref-env <ENV_VAR>`.
+      - Requires a non-empty env var in the onboarding process environment.
+      - Cannot be combined with `--gateway-token`.
+    - Disable auth only if you fully trust every local process.
+    - Non‑loopback binds still require auth.
+  </Step>
+  <Step title="Channels">
+    - [WhatsApp](/channels/whatsapp): optional QR login.
+    - [Telegram](/channels/telegram): bot token.
+    - [Discord](/channels/discord): bot token.
+    - [Google Chat](/channels/googlechat): service account JSON + webhook audience.
+    - [Mattermost](/channels/mattermost) (plugin): bot token + base URL.
+    - [Signal](/channels/signal): optional `signal-cli` install + account config.
+    - [BlueBubbles](/channels/bluebubbles): **recommended for iMessage**; server URL + password + webhook.
+    - [iMessage](/channels/imessage): legacy `imsg` CLI path + DB access.
+    - DM security: default is pairing. First DM sends a code; approve via `quantumclaw pairing approve <channel> <code>` or use allowlists.
+  </Step>
+  <Step title="Web search">
+    - Pick a provider: Perplexity, Brave, Gemini, Grok, or Kimi (or skip).
+    - Paste your API key (QuickStart auto-detects keys from env vars or existing config).
+    - Skip with `--skip-search`.
+    - Configure later: `quantumclaw configure --section web`.
+  </Step>
+  <Step title="Daemon install">
+    - macOS: LaunchAgent
+      - Requires a logged-in user session; for headless, use a custom LaunchDaemon (not shipped).
+    - Linux (and Windows via WSL2): systemd user unit
+      - Onboarding attempts to enable lingering via `loginctl enable-linger <user>` so the Gateway stays up after logout.
+      - May prompt for sudo (writes `/var/lib/systemd/linger`); it tries without sudo first.
+    - **Runtime selection:** Node (recommended; required for WhatsApp/Telegram). Bun is **not recommended**.
+    - If token auth requires a token and `gateway.auth.token` is SecretRef-managed, daemon install validates it 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, daemon install is blocked with actionable guidance.
+    - If both `gateway.auth.token` and `gateway.auth.password` are configured and `gateway.auth.mode` is unset, daemon install is blocked until mode is set explicitly.
+  </Step>
+  <Step title="Health check">
+    - Starts the Gateway (if needed) and runs `quantumclaw health`.
+    - Tip: `quantumclaw status --deep` adds gateway health probes to status output (requires a reachable gateway).
+  </Step>
+  <Step title="Skills (recommended)">
+    - Reads the available skills and checks requirements.
+    - Lets you choose a node manager: **npm / pnpm** (bun not recommended).
+    - Installs optional dependencies (some use Homebrew on macOS).
+  </Step>
+  <Step title="Finish">
+    - Summary + next steps, including iOS/Android/macOS apps for extra features.
+  </Step>
+</Steps>
+
+<Note>
+If no GUI is detected, onboarding prints SSH port-forward instructions for the Control UI instead of opening a browser.
+If the Control UI assets are missing, onboarding attempts to build them; fallback is `pnpm ui:build` (auto-installs UI deps).
+</Note>
+
+## Non-interactive mode
+
+Use `--non-interactive` to automate or script onboarding:
+
+```bash
+quantumclaw onboard --non-interactive \
+  --mode local \
+  --auth-choice apiKey \
+  --anthropic-api-key "$ANTHROPIC_API_KEY" \
+  --gateway-port 18789 \
+  --gateway-bind loopback \
+  --install-daemon \
+  --daemon-runtime node \
+  --skip-skills
+```
+
+Add `--json` for a machine‑readable summary.
+
+Gateway token SecretRef in non-interactive mode:
+
+```bash
+export QUANTUMCLAW_GATEWAY_TOKEN="your-token"
+quantumclaw onboard --non-interactive \
+  --mode local \
+  --auth-choice skip \
+  --gateway-auth token \
+  --gateway-token-ref-env QUANTUMCLAW_GATEWAY_TOKEN
+```
+
+`--gateway-token` and `--gateway-token-ref-env` are mutually exclusive.
+
+<Note>
+`--json` does **not** imply non-interactive mode. Use `--non-interactive` (and `--workspace`) for scripts.
+</Note>
+
+Provider-specific command examples live in [CLI Automation](/start/wizard-cli-automation#provider-specific-examples).
+Use this reference page for flag semantics and step ordering.
+
+### Add agent (non-interactive)
+
+```bash
+quantumclaw agents add work \
+  --workspace ~/.quantumclaw/workspace-work \
+  --model openai/gpt-5.2 \
+  --bind whatsapp:biz \
+  --non-interactive \
+  --json
+```
+
+## Gateway wizard RPC
+
+The Gateway exposes the onboarding flow over RPC (`wizard.start`, `wizard.next`, `wizard.cancel`, `wizard.status`).
+Clients (macOS app, Control UI) can render steps without re‑implementing onboarding logic.
+
+## Signal setup (signal-cli)
+
+Onboarding can install `signal-cli` from GitHub releases:
+
+- Downloads the appropriate release asset.
+- Stores it under `~/.quantumclaw/tools/signal-cli/<version>/`.
+- Writes `channels.signal.cliPath` to your config.
+
+Notes:
+
+- JVM builds require **Java 21**.
+- Native builds are used when available.
+- Windows uses WSL2; signal-cli install follows the Linux flow inside WSL.
+
+## What the wizard writes
+
+Typical fields in `~/.quantumclaw/quantumclaw.json`:
+
+- `agents.defaults.workspace`
+- `agents.defaults.model` / `models.providers` (if Minimax chosen)
+- `tools.profile` (local onboarding defaults to `"coding"` when unset; existing explicit values are preserved)
+- `gateway.*` (mode, bind, auth, tailscale)
+- `session.dmScope` (behavior details: [CLI Setup Reference](/start/wizard-cli-reference#outputs-and-internals))
+- `channels.telegram.botToken`, `channels.discord.token`, `channels.signal.*`, `channels.imessage.*`
+- Channel allowlists (Slack/Discord/Matrix/Microsoft Teams) when you opt in during the prompts (names resolve to IDs when possible).
+- `skills.install.nodeManager`
+- `wizard.lastRunAt`
+- `wizard.lastRunVersion`
+- `wizard.lastRunCommit`
+- `wizard.lastRunCommand`
+- `wizard.lastRunMode`
+
+`quantumclaw agents add` writes `agents.list[]` and optional `bindings`.
+
+WhatsApp credentials go under `~/.quantumclaw/credentials/whatsapp/<accountId>/`.
+Sessions are stored under `~/.quantumclaw/agents/<agentId>/sessions/`.
+
+Some channels are delivered as plugins. When you pick one during setup, onboarding
+will prompt to install it (npm or a local path) before it can be configured.
+
+## Related docs
+
+- Onboarding overview: [Onboarding (CLI)](/start/wizard)
+- macOS app onboarding: [Onboarding](/start/onboarding)
+- Config reference: [Gateway configuration](/gateway/configuration)
+- Providers: [WhatsApp](/channels/whatsapp), [Telegram](/channels/telegram), [Discord](/channels/discord), [Google Chat](/channels/googlechat), [Signal](/channels/signal), [BlueBubbles](/channels/bluebubbles) (iMessage), [iMessage](/channels/imessage) (legacy)
+- Skills: [Skills](/tools/skills), [Skills config](/tools/skills-config)

package/docs/security/CONTRIBUTING-THREAT-MODEL.md

@@ -0,0 +1,98 @@
+---
+title: "Contributing to the Threat Model"
+summary: "How to contribute to the QuantumClaw threat model"
+read_when:
+  - You want to contribute security findings or threat scenarios
+  - Reviewing or updating the threat model
+---
+
+# Contributing to the QuantumClaw Threat Model
+
+Thanks for helping make QuantumClaw more secure. This threat model is a living document and we welcome contributions from anyone - you don't need to be a security expert.
+
+## Ways to Contribute
+
+### Add a Threat
+
+Spotted an attack vector or risk we haven't covered? Open an issue on [quantumclaw/trust](https://github.com/quantumclaw/trust/issues) and describe it in your own words. You don't need to know any frameworks or fill in every field - just describe the scenario.
+
+**Helpful to include (but not required):**
+
+- The attack scenario and how it could be exploited
+- Which parts of QuantumClaw are affected (CLI, gateway, channels, ClawHub, MCP servers, etc.)
+- How severe you think it is (low / medium / high / critical)
+- Any links to related research, CVEs, or real-world examples
+
+We'll handle the ATLAS mapping, threat IDs, and risk assessment during review. If you want to include those details, great - but it's not expected.
+
+> **This is for adding to the threat model, not reporting live vulnerabilities.** If you've found an exploitable vulnerability, see our [Trust page](https://trust.quantumclaw.ai) for responsible disclosure instructions.
+
+### Suggest a Mitigation
+
+Have an idea for how to address an existing threat? Open an issue or PR referencing the threat. Useful mitigations are specific and actionable - for example, "per-sender rate limiting of 10 messages/minute at the gateway" is better than "implement rate limiting."
+
+### Propose an Attack Chain
+
+Attack chains show how multiple threats combine into a realistic attack scenario. If you see a dangerous combination, describe the steps and how an attacker would chain them together. A short narrative of how the attack unfolds in practice is more valuable than a formal template.
+
+### Fix or Improve Existing Content
+
+Typos, clarifications, outdated info, better examples - PRs welcome, no issue needed.
+
+## What We Use
+
+### MITRE ATLAS
+
+This threat model is built on [MITRE ATLAS](https://atlas.mitre.org/) (Adversarial Threat Landscape for AI Systems), a framework designed specifically for AI/ML threats like prompt injection, tool misuse, and agent exploitation. You don't need to know ATLAS to contribute - we map submissions to the framework during review.
+
+### Threat IDs
+
+Each threat gets an ID like `T-EXEC-003`. The categories are:
+
+| Code    | Category                                   |
+| ------- | ------------------------------------------ |
+| RECON   | Reconnaissance - information gathering     |
+| ACCESS  | Initial access - gaining entry             |
+| EXEC    | Execution - running malicious actions      |
+| PERSIST | Persistence - maintaining access           |
+| EVADE   | Defense evasion - avoiding detection       |
+| DISC    | Discovery - learning about the environment |
+| EXFIL   | Exfiltration - stealing data               |
+| IMPACT  | Impact - damage or disruption              |
+
+IDs are assigned by maintainers during review. You don't need to pick one.
+
+### Risk Levels
+
+| Level        | Meaning                                                           |
+| ------------ | ----------------------------------------------------------------- |
+| **Critical** | Full system compromise, or high likelihood + critical impact      |
+| **High**     | Significant damage likely, or medium likelihood + critical impact |
+| **Medium**   | Moderate risk, or low likelihood + high impact                    |
+| **Low**      | Unlikely and limited impact                                       |
+
+If you're unsure about the risk level, just describe the impact and we'll assess it.
+
+## Review Process
+
+1. **Triage** - We review new submissions within 48 hours
+2. **Assessment** - We verify feasibility, assign ATLAS mapping and threat ID, validate risk level
+3. **Documentation** - We ensure everything is formatted and complete
+4. **Merge** - Added to the threat model and visualization
+
+## Resources
+
+- [ATLAS Website](https://atlas.mitre.org/)
+- [ATLAS Techniques](https://atlas.mitre.org/techniques/)
+- [ATLAS Case Studies](https://atlas.mitre.org/studies/)
+- [QuantumClaw Threat Model](/security/THREAT-MODEL-ATLAS)
+
+## Contact
+
+- **Security vulnerabilities:** See our [Trust page](https://trust.quantumclaw.ai) for reporting instructions
+- **Threat model questions:** Open an issue on [quantumclaw/trust](https://github.com/quantumclaw/trust/issues)
+- **General chat:** Discord #security channel
+
+## Recognition
+
+Contributors to the threat model are recognized in the threat model acknowledgments, release notes, and the QuantumClaw security hall of fame for significant contributions.