@quantumclaw/quantumclaw 2026.3.22

package/docs/security/formal-verification.md

@@ -0,0 +1,167 @@
+---
+title: Formal Verification (Security Models)
+summary: Machine-checked security models for QuantumClaw’s highest-risk paths.
+read_when:
+  - Reviewing formal security model guarantees or limits
+  - Reproducing or updating TLA+/TLC security model checks
+permalink: /security/formal-verification/
+---
+
+# Formal Verification (Security Models)
+
+This page tracks QuantumClaw’s **formal security models** (TLA+/TLC today; more as needed).
+
+> Note: some older links may refer to the previous project name.
+
+**Goal (north star):** provide a machine-checked argument that QuantumClaw enforces its
+intended security policy (authorization, session isolation, tool gating, and
+misconfiguration safety), under explicit assumptions.
+
+**What this is (today):** an executable, attacker-driven **security regression suite**:
+
+- Each claim has a runnable model-check over a finite state space.
+- Many claims have a paired **negative model** that produces a counterexample trace for a realistic bug class.
+
+**What this is not (yet):** a proof that “QuantumClaw is secure in all respects” or that the full TypeScript implementation is correct.
+
+## Where the models live
+
+Models are maintained in a separate repo: [vignesh07/quantumclaw-formal-models](https://github.com/vignesh07/quantumclaw-formal-models).
+
+## Important caveats
+
+- These are **models**, not the full TypeScript implementation. Drift between model and code is possible.
+- Results are bounded by the state space explored by TLC; “green” does not imply security beyond the modeled assumptions and bounds.
+- Some claims rely on explicit environmental assumptions (e.g., correct deployment, correct configuration inputs).
+
+## Reproducing results
+
+Today, results are reproduced by cloning the models repo locally and running TLC (see below). A future iteration could offer:
+
+- CI-run models with public artifacts (counterexample traces, run logs)
+- a hosted “run this model” workflow for small, bounded checks
+
+Getting started:
+
+```bash
+git clone https://github.com/vignesh07/quantumclaw-formal-models
+cd quantumclaw-formal-models
+
+# Java 11+ required (TLC runs on the JVM).
+# The repo vendors a pinned `tla2tools.jar` (TLA+ tools) and provides `bin/tlc` + Make targets.
+
+make <target>
+```
+
+### Gateway exposure and open gateway misconfiguration
+
+**Claim:** binding beyond loopback without auth can make remote compromise possible / increases exposure; token/password blocks unauth attackers (per the model assumptions).
+
+- Green runs:
+  - `make gateway-exposure-v2`
+  - `make gateway-exposure-v2-protected`
+- Red (expected):
+  - `make gateway-exposure-v2-negative`
+
+See also: `docs/gateway-exposure-matrix.md` in the models repo.
+
+### Nodes.run pipeline (highest-risk capability)
+
+**Claim:** `nodes.run` requires (a) node command allowlist plus declared commands and (b) live approval when configured; approvals are tokenized to prevent replay (in the model).
+
+- Green runs:
+  - `make nodes-pipeline`
+  - `make approvals-token`
+- Red (expected):
+  - `make nodes-pipeline-negative`
+  - `make approvals-token-negative`
+
+### Pairing store (DM gating)
+
+**Claim:** pairing requests respect TTL and pending-request caps.
+
+- Green runs:
+  - `make pairing`
+  - `make pairing-cap`
+- Red (expected):
+  - `make pairing-negative`
+  - `make pairing-cap-negative`
+
+### Ingress gating (mentions + control-command bypass)
+
+**Claim:** in group contexts requiring mention, an unauthorized “control command” cannot bypass mention gating.
+
+- Green:
+  - `make ingress-gating`
+- Red (expected):
+  - `make ingress-gating-negative`
+
+### Routing/session-key isolation
+
+**Claim:** DMs from distinct peers do not collapse into the same session unless explicitly linked/configured.
+
+- Green:
+  - `make routing-isolation`
+- Red (expected):
+  - `make routing-isolation-negative`
+
+## v1++: additional bounded models (concurrency, retries, trace correctness)
+
+These are follow-on models that tighten fidelity around real-world failure modes (non-atomic updates, retries, and message fan-out).
+
+### Pairing store concurrency / idempotency
+
+**Claim:** a pairing store should enforce `MaxPending` and idempotency even under interleavings (i.e., “check-then-write” must be atomic / locked; refresh shouldn’t create duplicates).
+
+What it means:
+
+- Under concurrent requests, you can’t exceed `MaxPending` for a channel.
+- Repeated requests/refreshes for the same `(channel, sender)` should not create duplicate live pending rows.
+
+- Green runs:
+  - `make pairing-race` (atomic/locked cap check)
+  - `make pairing-idempotency`
+  - `make pairing-refresh`
+  - `make pairing-refresh-race`
+- Red (expected):
+  - `make pairing-race-negative` (non-atomic begin/commit cap race)
+  - `make pairing-idempotency-negative`
+  - `make pairing-refresh-negative`
+  - `make pairing-refresh-race-negative`
+
+### Ingress trace correlation / idempotency
+
+**Claim:** ingestion should preserve trace correlation across fan-out and be idempotent under provider retries.
+
+What it means:
+
+- When one external event becomes multiple internal messages, every part keeps the same trace/event identity.
+- Retries do not result in double-processing.
+- If provider event IDs are missing, dedupe falls back to a safe key (e.g., trace ID) to avoid dropping distinct events.
+
+- Green:
+  - `make ingress-trace`
+  - `make ingress-trace2`
+  - `make ingress-idempotency`
+  - `make ingress-dedupe-fallback`
+- Red (expected):
+  - `make ingress-trace-negative`
+  - `make ingress-trace2-negative`
+  - `make ingress-idempotency-negative`
+  - `make ingress-dedupe-fallback-negative`
+
+### Routing dmScope precedence + identityLinks
+
+**Claim:** routing must keep DM sessions isolated by default, and only collapse sessions when explicitly configured (channel precedence + identity links).
+
+What it means:
+
+- Channel-specific dmScope overrides must win over global defaults.
+- identityLinks should collapse only within explicit linked groups, not across unrelated peers.
+
+- Green:
+  - `make routing-precedence`
+  - `make routing-identitylinks`
+- Red (expected):
+  - `make routing-precedence-negative`
+  - `make routing-identitylinks-negative`

package/docs/start/bootstrapping.md

@@ -0,0 +1,41 @@
+---
+summary: "Agent bootstrapping ritual that seeds the workspace and identity files"
+read_when:
+  - Understanding what happens on the first agent run
+  - Explaining where bootstrapping files live
+  - Debugging onboarding identity setup
+title: "Agent Bootstrapping"
+sidebarTitle: "Bootstrapping"
+---
+
+# Agent Bootstrapping
+
+Bootstrapping is the **first‑run** ritual that prepares an agent workspace and
+collects identity details. It happens after onboarding, when the agent starts
+for the first time.
+
+## What bootstrapping does
+
+On the first agent run, QuantumClaw bootstraps the workspace (default
+`~/.quantumclaw/workspace`):
+
+- Seeds `AGENTS.md`, `BOOTSTRAP.md`, `IDENTITY.md`, `USER.md`.
+- Runs a short Q&A ritual (one question at a time).
+- Writes identity + preferences to `IDENTITY.md`, `USER.md`, `SOUL.md`.
+- Removes `BOOTSTRAP.md` when finished so it only runs once.
+
+## Where it runs
+
+Bootstrapping always runs on the **gateway host**. If the macOS app connects to
+a remote Gateway, the workspace and bootstrapping files live on that remote
+machine.
+
+<Note>
+When the Gateway runs on another machine, edit workspace files on the gateway
+host (for example, `user@gateway-host:~/.quantumclaw/workspace`).
+</Note>
+
+## Related docs
+
+- macOS app onboarding: [Onboarding](/start/onboarding)
+- Workspace layout: [Agent workspace](/concepts/agent-workspace)

package/docs/start/docs-directory.md

@@ -0,0 +1,66 @@
+---
+summary: "Curated links to the most used QuantumClaw docs."
+read_when:
+  - You want quick access to key docs pages
+title: "Docs directory"
+---
+
+# Docs Directory
+
+<Note>
+This page is a curated index. If you are new, start with [Getting Started](/start/getting-started).
+For a complete map of the docs, see [Docs hubs](/start/hubs).
+</Note>
+
+## Start here
+
+- [Docs hubs (all pages linked)](/start/hubs)
+- [Help](/help)
+- [Configuration](/gateway/configuration)
+- [Configuration examples](/gateway/configuration-examples)
+- [Slash commands](/tools/slash-commands)
+- [Multi-agent routing](/concepts/multi-agent)
+- [Updating and rollback](/install/updating)
+- [Pairing (DM and nodes)](/channels/pairing)
+- [Nix mode](/install/nix)
+- [QuantumClaw assistant setup](/start/quantumclaw)
+- [Skills](/tools/skills)
+- [Skills config](/tools/skills-config)
+- [Workspace templates](/reference/templates/AGENTS)
+- [RPC adapters](/reference/rpc)
+- [Gateway runbook](/gateway)
+- [Nodes (iOS and Android)](/nodes)
+- [Web surfaces (Control UI)](/web)
+- [Discovery and transports](/gateway/discovery)
+- [Remote access](/gateway/remote)
+
+## Providers and UX
+
+- [WebChat](/web/webchat)
+- [Control UI (browser)](/web/control-ui)
+- [Telegram](/channels/telegram)
+- [Discord](/channels/discord)
+- [Mattermost (plugin)](/channels/mattermost)
+- [BlueBubbles (iMessage)](/channels/bluebubbles)
+- [iMessage (legacy)](/channels/imessage)
+- [Groups](/channels/groups)
+- [WhatsApp group messages](/channels/group-messages)
+- [Media images](/nodes/images)
+- [Media audio](/nodes/audio)
+
+## Companion apps
+
+- [macOS app](/platforms/macos)
+- [iOS app](/platforms/ios)
+- [Android app](/platforms/android)
+- [Windows (WSL2)](/platforms/windows)
+- [Linux app](/platforms/linux)
+
+## Operations and safety
+
+- [Sessions](/concepts/session)
+- [Cron jobs](/automation/cron-jobs)
+- [Webhooks](/automation/webhook)
+- [Gmail hooks (Pub/Sub)](/automation/gmail-pubsub)
+- [Security](/gateway/security)
+- [Troubleshooting](/gateway/troubleshooting)

package/docs/start/getting-started.md

@@ -0,0 +1,116 @@
+---
+summary: "Get QuantumClaw installed and run your first chat in minutes."
+read_when:
+  - First time setup from zero
+  - You want the fastest path to a working chat
+title: "Getting Started"
+---
+
+# Getting Started
+
+Install QuantumClaw, run onboarding, and chat with your AI assistant — all in
+about 5 minutes. By the end you will have a running Gateway, configured auth,
+and a working chat session.
+
+## What you need
+
+- **Node.js** — Node 24 recommended (Node 22.16+ also supported)
+- **An API key** from a model provider (Anthropic, OpenAI, Google, etc.) — onboarding will prompt you
+
+<Tip>
+Check your Node version with `node --version`.
+**Windows users:** both native Windows and WSL2 are supported. WSL2 is more
+stable and recommended for the full experience. See [Windows](/platforms/windows).
+Need to install Node? See [Node setup](/install/node).
+</Tip>
+
+## Quick setup
+
+<Steps>
+  <Step title="Install QuantumClaw">
+    <Tabs>
+      <Tab title="macOS / Linux">
+        ```bash
+        curl -fsSL https://quantumclaw.ai/install.sh | bash
+        ```
+        <img
+  src="/assets/install-script.svg"
+  alt="Install Script Process"
+  className="rounded-lg"
+/>
+      </Tab>
+      <Tab title="Windows (PowerShell)">
+        ```powershell
+        iwr -useb https://quantumclaw.ai/install.ps1 | iex
+        ```
+      </Tab>
+    </Tabs>
+
+    <Note>
+    Other install methods (Docker, Nix, npm): [Install](/install).
+    </Note>
+
+  </Step>
+  <Step title="Run onboarding">
+    ```bash
+    quantumclaw onboard --install-daemon
+    ```
+
+    The wizard walks you through choosing a model provider, setting an API key,
+    and configuring the Gateway. It takes about 2 minutes.
+
+    See [Onboarding (CLI)](/start/wizard) for the full reference.
+
+  </Step>
+  <Step title="Verify the Gateway is running">
+    ```bash
+    quantumclaw gateway status
+    ```
+
+    You should see the Gateway listening on port 18789.
+
+  </Step>
+  <Step title="Open the dashboard">
+    ```bash
+    quantumclaw dashboard
+    ```
+
+    This opens the Control UI in your browser. If it loads, everything is working.
+
+  </Step>
+  <Step title="Send your first message">
+    Type a message in the Control UI chat and you should get an AI reply.
+
+    Want to chat from your phone instead? The fastest channel to set up is
+    [Telegram](/channels/telegram) (just a bot token). See [Channels](/channels)
+    for all options.
+
+  </Step>
+</Steps>
+
+## What to do next
+
+<Columns>
+  <Card title="Connect a channel" href="/channels" icon="message-square">
+    WhatsApp, Telegram, Discord, iMessage, and more.
+  </Card>
+  <Card title="Pairing and safety" href="/channels/pairing" icon="shield">
+    Control who can message your agent.
+  </Card>
+  <Card title="Configure the Gateway" href="/gateway/configuration" icon="settings">
+    Models, tools, sandbox, and advanced settings.
+  </Card>
+  <Card title="Browse tools" href="/tools" icon="wrench">
+    Browser, exec, web search, skills, and plugins.
+  </Card>
+</Columns>
+
+<Accordion title="Advanced: environment variables">
+  If you run QuantumClaw as a service account or want custom paths:
+
+- `QUANTUMCLAW_HOME` — home directory for internal path resolution
+- `QUANTUMCLAW_STATE_DIR` — override the state directory
+- `QUANTUMCLAW_CONFIG_PATH` — override the config file path
+
+Full reference: [Environment variables](/help/environment).
+</Accordion>

package/docs/start/hubs.md

@@ -0,0 +1,198 @@
+---
+summary: "Hubs that link to every QuantumClaw doc"
+read_when:
+  - You want a complete map of the documentation
+title: "Docs Hubs"
+---
+
+# Docs hubs
+
+<Note>
+If you are new to QuantumClaw, start with [Getting Started](/start/getting-started).
+</Note>
+
+Use these hubs to discover every page, including deep dives and reference docs that don’t appear in the left nav.
+
+## Start here
+
+- [Index](/)
+- [Getting Started](/start/getting-started)
+- [Onboarding](/start/onboarding)
+- [Onboarding (CLI)](/start/wizard)
+- [Setup](/start/setup)
+- [Dashboard (local Gateway)](http://127.0.0.1:18789/)
+- [Help](/help)
+- [Docs directory](/start/docs-directory)
+- [Configuration](/gateway/configuration)
+- [Configuration examples](/gateway/configuration-examples)
+- [QuantumClaw assistant](/start/quantumclaw)
+- [Showcase](/start/showcase)
+- [Lore](/start/lore)
+
+## Installation + updates
+
+- [Docker](/install/docker)
+- [Nix](/install/nix)
+- [Updating / rollback](/install/updating)
+- [Bun workflow (experimental)](/install/bun)
+
+## Core concepts
+
+- [Architecture](/concepts/architecture)
+- [Features](/concepts/features)
+- [Network hub](/network)
+- [Agent runtime](/concepts/agent)
+- [Agent workspace](/concepts/agent-workspace)
+- [Memory](/concepts/memory)
+- [Agent loop](/concepts/agent-loop)
+- [Streaming + chunking](/concepts/streaming)
+- [Multi-agent routing](/concepts/multi-agent)
+- [Compaction](/concepts/compaction)
+- [Sessions](/concepts/session)
+- [Session pruning](/concepts/session-pruning)
+- [Session tools](/concepts/session-tool)
+- [Queue](/concepts/queue)
+- [Slash commands](/tools/slash-commands)
+- [RPC adapters](/reference/rpc)
+- [TypeBox schemas](/concepts/typebox)
+- [Timezone handling](/concepts/timezone)
+- [Presence](/concepts/presence)
+- [Discovery + transports](/gateway/discovery)
+- [Bonjour](/gateway/bonjour)
+- [Channel routing](/channels/channel-routing)
+- [Groups](/channels/groups)
+- [Group messages](/channels/group-messages)
+- [Model failover](/concepts/model-failover)
+- [OAuth](/concepts/oauth)
+
+## Providers + ingress
+
+- [Chat channels hub](/channels)
+- [Model providers hub](/providers/models)
+- [WhatsApp](/channels/whatsapp)
+- [Telegram](/channels/telegram)
+- [Slack](/channels/slack)
+- [Discord](/channels/discord)
+- [Mattermost](/channels/mattermost) (plugin)
+- [Signal](/channels/signal)
+- [BlueBubbles (iMessage)](/channels/bluebubbles)
+- [iMessage (legacy)](/channels/imessage)
+- [Location parsing](/channels/location)
+- [WebChat](/web/webchat)
+- [Webhooks](/automation/webhook)
+- [Gmail Pub/Sub](/automation/gmail-pubsub)
+
+## Gateway + operations
+
+- [Gateway runbook](/gateway)
+- [Network model](/gateway/network-model)
+- [Gateway pairing](/gateway/pairing)
+- [Gateway lock](/gateway/gateway-lock)
+- [Background process](/gateway/background-process)
+- [Health](/gateway/health)
+- [Heartbeat](/gateway/heartbeat)
+- [Doctor](/gateway/doctor)
+- [Logging](/gateway/logging)
+- [Sandboxing](/gateway/sandboxing)
+- [Dashboard](/web/dashboard)
+- [Control UI](/web/control-ui)
+- [Remote access](/gateway/remote)
+- [Remote gateway README](/gateway/remote-gateway-readme)
+- [Tailscale](/gateway/tailscale)
+- [Security](/gateway/security)
+- [Troubleshooting](/gateway/troubleshooting)
+
+## Tools + automation
+
+- [Tools surface](/tools)
+- [OpenProse](/prose)
+- [CLI reference](/cli)
+- [Exec tool](/tools/exec)
+- [PDF tool](/tools/pdf)
+- [Elevated mode](/tools/elevated)
+- [Cron jobs](/automation/cron-jobs)
+- [Cron vs Heartbeat](/automation/cron-vs-heartbeat)
+- [Thinking + verbose](/tools/thinking)
+- [Models](/concepts/models)
+- [Sub-agents](/tools/subagents)
+- [Agent send CLI](/tools/agent-send)
+- [Terminal UI](/web/tui)
+- [Browser control](/tools/browser)
+- [Browser (Linux troubleshooting)](/tools/browser-linux-troubleshooting)
+- [Polls](/automation/poll)
+
+## Nodes, media, voice
+
+- [Nodes overview](/nodes)
+- [Camera](/nodes/camera)
+- [Images](/nodes/images)
+- [Audio](/nodes/audio)
+- [Location command](/nodes/location-command)
+- [Voice wake](/nodes/voicewake)
+- [Talk mode](/nodes/talk)
+
+## Platforms
+
+- [Platforms overview](/platforms)
+- [macOS](/platforms/macos)
+- [iOS](/platforms/ios)
+- [Android](/platforms/android)
+- [Windows (WSL2)](/platforms/windows)
+- [Linux](/platforms/linux)
+- [Web surfaces](/web)
+
+## macOS companion app (advanced)
+
+- [macOS dev setup](/platforms/mac/dev-setup)
+- [macOS menu bar](/platforms/mac/menu-bar)
+- [macOS voice wake](/platforms/mac/voicewake)
+- [macOS voice overlay](/platforms/mac/voice-overlay)
+- [macOS WebChat](/platforms/mac/webchat)
+- [macOS Canvas](/platforms/mac/canvas)
+- [macOS child process](/platforms/mac/child-process)
+- [macOS health](/platforms/mac/health)
+- [macOS icon](/platforms/mac/icon)
+- [macOS logging](/platforms/mac/logging)
+- [macOS permissions](/platforms/mac/permissions)
+- [macOS remote](/platforms/mac/remote)
+- [macOS signing](/platforms/mac/signing)
+- [macOS gateway (launchd)](/platforms/mac/bundled-gateway)
+- [macOS XPC](/platforms/mac/xpc)
+- [macOS skills](/platforms/mac/skills)
+- [macOS Peekaboo](/platforms/mac/peekaboo)
+
+## Extensions + plugins
+
+- [Plugins overview](/tools/plugin)
+- [Building plugins](/plugins/building-plugins)
+- [Plugin manifest](/plugins/manifest)
+- [Agent tools](/plugins/building-plugins#registering-agent-tools)
+- [Plugin bundles](/plugins/bundles)
+- [Community plugins](/plugins/community)
+- [Capability cookbook](/tools/capability-cookbook)
+- [Voice call plugin](/plugins/voice-call)
+- [Zalo user plugin](/plugins/zalouser)
+
+## Workspace + templates
+
+- [Skills](/tools/skills)
+- [ClawHub](/tools/clawhub)
+- [Skills config](/tools/skills-config)
+- [Default AGENTS](/reference/AGENTS.default)
+- [Templates: AGENTS](/reference/templates/AGENTS)
+- [Templates: BOOTSTRAP](/reference/templates/BOOTSTRAP)
+- [Templates: HEARTBEAT](/reference/templates/HEARTBEAT)
+- [Templates: IDENTITY](/reference/templates/IDENTITY)
+- [Templates: SOUL](/reference/templates/SOUL)
+- [Templates: TOOLS](/reference/templates/TOOLS)
+- [Templates: USER](/reference/templates/USER)
+
+## Project
+
+- [Credits](/reference/credits)
+
+## Testing + release
+
+- [Testing](/reference/test)
+- [Release policy](/reference/RELEASING)
+- [Device models](/reference/device-models)