@quantumclaw/quantumclaw 2026.3.22

package/docs/start/setup.md

@@ -0,0 +1,164 @@
+---
+summary: "Advanced setup and development workflows for QuantumClaw"
+read_when:
+  - Setting up a new machine
+  - You want “latest + greatest” without breaking your personal setup
+title: "Setup"
+---
+
+# Setup
+
+<Note>
+If you are setting up for the first time, start with [Getting Started](/start/getting-started).
+For onboarding details, see [Onboarding (CLI)](/start/wizard).
+</Note>
+
+## TL;DR
+
+- **Tailoring lives outside the repo:** `~/.quantumclaw/workspace` (workspace) + `~/.quantumclaw/quantumclaw.json` (config).
+- **Stable workflow:** install the macOS app; let it run the bundled Gateway.
+- **Bleeding edge workflow:** run the Gateway yourself via `pnpm gateway:watch`, then let the macOS app attach in Local mode.
+
+## Prereqs (from source)
+
+- Node 24 recommended (Node 22 LTS, currently `22.16+`, still supported)
+- `pnpm`
+- Docker (optional; only for containerized setup/e2e — see [Docker](/install/docker))
+
+## Tailoring strategy (so updates do not hurt)
+
+If you want “100% tailored to me” _and_ easy updates, keep your customization in:
+
+- **Config:** `~/.quantumclaw/quantumclaw.json` (JSON/JSON5-ish)
+- **Workspace:** `~/.quantumclaw/workspace` (skills, prompts, memories; make it a private git repo)
+
+Bootstrap once:
+
+```bash
+quantumclaw setup
+```
+
+From inside this repo, use the local CLI entry:
+
+```bash
+quantumclaw setup
+```
+
+If you don’t have a global install yet, run it via `pnpm quantumclaw setup`.
+
+## Run the Gateway from this repo
+
+After `pnpm build`, you can run the packaged CLI directly:
+
+```bash
+node quantumclaw.mjs gateway --port 18789 --verbose
+```
+
+## Stable workflow (macOS app first)
+
+1. Install + launch **QuantumClaw.app** (menu bar).
+2. Complete the onboarding/permissions checklist (TCC prompts).
+3. Ensure Gateway is **Local** and running (the app manages it).
+4. Link surfaces (example: WhatsApp):
+
+```bash
+quantumclaw channels login
+```
+
+5. Sanity check:
+
+```bash
+quantumclaw health
+```
+
+If onboarding is not available in your build:
+
+- Run `quantumclaw setup`, then `quantumclaw channels login`, then start the Gateway manually (`quantumclaw gateway`).
+
+## Bleeding edge workflow (Gateway in a terminal)
+
+Goal: work on the TypeScript Gateway, get hot reload, keep the macOS app UI attached.
+
+### 0) (Optional) Run the macOS app from source too
+
+If you also want the macOS app on the bleeding edge:
+
+```bash
+./scripts/restart-mac.sh
+```
+
+### 1) Start the dev Gateway
+
+```bash
+pnpm install
+pnpm gateway:watch
+```
+
+`gateway:watch` runs the gateway in watch mode and reloads on relevant source,
+config, and bundled-plugin metadata changes.
+
+### 2) Point the macOS app at your running Gateway
+
+In **QuantumClaw.app**:
+
+- Connection Mode: **Local**
+  The app will attach to the running gateway on the configured port.
+
+### 3) Verify
+
+- In-app Gateway status should read **“Using existing gateway …”**
+- Or via CLI:
+
+```bash
+quantumclaw health
+```
+
+### Common footguns
+
+- **Wrong port:** Gateway WS defaults to `ws://127.0.0.1:18789`; keep app + CLI on the same port.
+- **Where state lives:**
+  - Credentials: `~/.quantumclaw/credentials/`
+  - Sessions: `~/.quantumclaw/agents/<agentId>/sessions/`
+  - Logs: `/tmp/quantumclaw/`
+
+## Credential storage map
+
+Use this when debugging auth or deciding what to back up:
+
+- **WhatsApp**: `~/.quantumclaw/credentials/whatsapp/<accountId>/creds.json`
+- **Telegram bot token**: config/env or `channels.telegram.tokenFile` (regular file only; symlinks rejected)
+- **Discord bot token**: config/env or SecretRef (env/file/exec providers)
+- **Slack tokens**: config/env (`channels.slack.*`)
+- **Pairing allowlists**:
+  - `~/.quantumclaw/credentials/<channel>-allowFrom.json` (default account)
+  - `~/.quantumclaw/credentials/<channel>-<accountId>-allowFrom.json` (non-default accounts)
+- **Model auth profiles**: `~/.quantumclaw/agents/<agentId>/agent/auth-profiles.json`
+- **File-backed secrets payload (optional)**: `~/.quantumclaw/secrets.json`
+- **Legacy OAuth import**: `~/.quantumclaw/credentials/oauth.json`
+  More detail: [Security](/gateway/security#credential-storage-map).
+
+## Updating (without wrecking your setup)
+
+- Keep `~/.quantumclaw/workspace` and `~/.quantumclaw/` as “your stuff”; don’t put personal prompts/config into the `quantumclaw` repo.
+- Updating source: `git pull` + `pnpm install` (when lockfile changed) + keep using `pnpm gateway:watch`.
+
+## Linux (systemd user service)
+
+Linux installs use a systemd **user** service. By default, systemd stops user
+services on logout/idle, which kills the Gateway. Onboarding attempts to enable
+lingering for you (may prompt for sudo). If it’s still off, run:
+
+```bash
+sudo loginctl enable-linger $USER
+```
+
+For always-on or multi-user servers, consider a **system** service instead of a
+user service (no lingering needed). See [Gateway runbook](/gateway) for the systemd notes.
+
+## Related docs
+
+- [Gateway runbook](/gateway) (flags, supervision, ports)
+- [Gateway configuration](/gateway/configuration) (config schema + examples)
+- [Discord](/channels/discord) and [Telegram](/channels/telegram) (reply tags + replyToMode settings)
+- [QuantumClaw assistant setup](/start/quantumclaw)
+- [macOS app](/platforms/macos) (gateway lifecycle)

package/docs/start/showcase.md

@@ -0,0 +1,418 @@
+---
+title: "Showcase"
+summary: "Community-built projects and integrations powered by QuantumClaw"
+read_when:
+  - Looking for real QuantumClaw usage examples
+  - Updating community project highlights
+---
+
+# Showcase
+
+Real projects from the community. See what people are building with QuantumClaw.
+
+<Info>
+**Want to be featured?** Share your project in [#showcase on Discord](https://discord.gg/clawd) or [tag @quantumclaw on X](https://x.com/quantumclaw).
+</Info>
+
+## 🎥 QuantumClaw in Action
+
+Full setup walkthrough (28m) by VelvetShark.
+
+<div
+  style={{
+    position: "relative",
+    paddingBottom: "56.25%",
+    height: 0,
+    overflow: "hidden",
+    borderRadius: 16,
+  }}
+>
+  <iframe
+    src="https://www.youtube-nocookie.com/embed/SaWSPZoPX34"
+    title="QuantumClaw: The self-hosted AI that Siri should have been (Full setup)"
+    style={{ position: "absolute", top: 0, left: 0, width: "100%", height: "100%" }}
+    frameBorder="0"
+    loading="lazy"
+    allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
+    allowFullScreen
+  />
+</div>
+
+[Watch on YouTube](https://www.youtube.com/watch?v=SaWSPZoPX34)
+
+<div
+  style={{
+    position: "relative",
+    paddingBottom: "56.25%",
+    height: 0,
+    overflow: "hidden",
+    borderRadius: 16,
+  }}
+>
+  <iframe
+    src="https://www.youtube-nocookie.com/embed/mMSKQvlmFuQ"
+    title="QuantumClaw showcase video"
+    style={{ position: "absolute", top: 0, left: 0, width: "100%", height: "100%" }}
+    frameBorder="0"
+    loading="lazy"
+    allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
+    allowFullScreen
+  />
+</div>
+
+[Watch on YouTube](https://www.youtube.com/watch?v=mMSKQvlmFuQ)
+
+<div
+  style={{
+    position: "relative",
+    paddingBottom: "56.25%",
+    height: 0,
+    overflow: "hidden",
+    borderRadius: 16,
+  }}
+>
+  <iframe
+    src="https://www.youtube-nocookie.com/embed/5kkIJNUGFho"
+    title="QuantumClaw community showcase"
+    style={{ position: "absolute", top: 0, left: 0, width: "100%", height: "100%" }}
+    frameBorder="0"
+    loading="lazy"
+    allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
+    allowFullScreen
+  />
+</div>
+
+[Watch on YouTube](https://www.youtube.com/watch?v=5kkIJNUGFho)
+
+## 🆕 Fresh from Discord
+
+<CardGroup cols={2}>
+
+<Card title="PR Review → Telegram Feedback" icon="code-pull-request" href="https://x.com/i/status/2010878524543131691">
+  **@bangnokia** • `review` `github` `telegram`
+
+OpenCode finishes the change → opens a PR → QuantumClaw reviews the diff and replies in Telegram with “minor suggestions” plus a clear merge verdict (including critical fixes to apply first).
+
+  <img src="/assets/showcase/pr-review-telegram.jpg" alt="QuantumClaw PR review feedback delivered in Telegram" />
+</Card>
+
+<Card title="Wine Cellar Skill in Minutes" icon="wine-glass" href="https://x.com/i/status/2010916352454791216">
+  **@prades_maxime** • `skills` `local` `csv`
+
+Asked “Robby” (@quantumclaw) for a local wine cellar skill. It requests a sample CSV export + where to store it, then builds/tests the skill fast (962 bottles in the example).
+
+  <img src="/assets/showcase/wine-cellar-skill.jpg" alt="QuantumClaw building a local wine cellar skill from CSV" />
+</Card>
+
+<Card title="Tesco Shop Autopilot" icon="cart-shopping" href="https://x.com/i/status/2009724862470689131">
+  **@marchattonhere** • `automation` `browser` `shopping`
+
+Weekly meal plan → regulars → book delivery slot → confirm order. No APIs, just browser control.
+
+  <img src="/assets/showcase/tesco-shop.jpg" alt="Tesco shop automation via chat" />
+</Card>
+
+<Card title="SNAG Screenshot-to-Markdown" icon="scissors" href="https://github.com/am-will/snag">
+  **@am-will** • `devtools` `screenshots` `markdown`
+
+Hotkey a screen region → Gemini vision → instant Markdown in your clipboard.
+
+  <img src="/assets/showcase/snag.png" alt="SNAG screenshot-to-markdown tool" />
+</Card>
+
+<Card title="Agents UI" icon="window-maximize" href="https://releaseflow.net/kitze/agents-ui">
+  **@kitze** • `ui` `skills` `sync`
+
+Desktop app to manage skills/commands across Agents, Claude, Codex, and QuantumClaw.
+
+  <img src="/assets/showcase/agents-ui.jpg" alt="Agents UI app" />
+</Card>
+
+<Card title="Telegram Voice Notes (papla.media)" icon="microphone" href="https://papla.media/docs">
+  **Community** • `voice` `tts` `telegram`
+
+Wraps papla.media TTS and sends results as Telegram voice notes (no annoying autoplay).
+
+  <img src="/assets/showcase/papla-tts.jpg" alt="Telegram voice note output from TTS" />
+</Card>
+
+<Card title="CodexMonitor" icon="eye" href="https://clawhub.com/odrobnik/codexmonitor">
+  **@odrobnik** • `devtools` `codex` `brew`
+
+Homebrew-installed helper to list/inspect/watch local OpenAI Codex sessions (CLI + VS Code).
+
+  <img src="/assets/showcase/codexmonitor.png" alt="CodexMonitor on ClawHub" />
+</Card>
+
+<Card title="Bambu 3D Printer Control" icon="print" href="https://clawhub.com/tobiasbischoff/bambu-cli">
+  **@tobiasbischoff** • `hardware` `3d-printing` `skill`
+
+Control and troubleshoot BambuLab printers: status, jobs, camera, AMS, calibration, and more.
+
+  <img src="/assets/showcase/bambu-cli.png" alt="Bambu CLI skill on ClawHub" />
+</Card>
+
+<Card title="Vienna Transport (Wiener Linien)" icon="train" href="https://clawhub.com/hjanuschka/wienerlinien">
+  **@hjanuschka** • `travel` `transport` `skill`
+
+Real-time departures, disruptions, elevator status, and routing for Vienna's public transport.
+
+  <img src="/assets/showcase/wienerlinien.png" alt="Wiener Linien skill on ClawHub" />
+</Card>
+
+<Card title="ParentPay School Meals" icon="utensils" href="#">
+  **@George5562** • `automation` `browser` `parenting`
+
+Automated UK school meal booking via ParentPay. Uses mouse coordinates for reliable table cell clicking.
+</Card>
+
+<Card title="R2 Upload (Send Me My Files)" icon="cloud-arrow-up" href="https://clawhub.com/skills/r2-upload">
+  **@julianengel** • `files` `r2` `presigned-urls`
+
+Upload to Cloudflare R2/S3 and generate secure presigned download links. Perfect for remote QuantumClaw instances.
+</Card>
+
+<Card title="iOS App via Telegram" icon="mobile" href="#">
+  **@coard** • `ios` `xcode` `testflight`
+
+Built a complete iOS app with maps and voice recording, deployed to TestFlight entirely via Telegram chat.
+
+  <img src="/assets/showcase/ios-testflight.jpg" alt="iOS app on TestFlight" />
+</Card>
+
+<Card title="Oura Ring Health Assistant" icon="heart-pulse" href="#">
+  **@AS** • `health` `oura` `calendar`
+
+Personal AI health assistant integrating Oura ring data with calendar, appointments, and gym schedule.
+
+  <img src="/assets/showcase/oura-health.png" alt="Oura ring health assistant" />
+</Card>
+<Card title="Kev's Dream Team (14+ Agents)" icon="robot" href="https://github.com/adam91holt/orchestrated-ai-articles">
+  **@adam91holt** • `multi-agent` `orchestration` `architecture` `manifesto`
+
+14+ agents under one gateway with Opus 4.5 orchestrator delegating to Codex workers. Comprehensive [technical write-up](https://github.com/adam91holt/orchestrated-ai-articles) covering the Dream Team roster, model selection, sandboxing, webhooks, heartbeats, and delegation flows. [Clawdspace](https://github.com/adam91holt/clawdspace) for agent sandboxing. [Blog post](https://adams-ai-journey.ghost.io/2026-the-year-of-the-orchestrator/).
+</Card>
+
+<Card title="Linear CLI" icon="terminal" href="https://github.com/Finesssee/linear-cli">
+  **@NessZerra** • `devtools` `linear` `cli` `issues`
+
+CLI for Linear that integrates with agentic workflows (Claude Code, QuantumClaw). Manage issues, projects, and workflows from the terminal. First external PR merged!
+</Card>
+
+<Card title="Beeper CLI" icon="message" href="https://github.com/blqke/beepcli">
+  **@jules** • `messaging` `beeper` `cli` `automation`
+
+Read, send, and archive messages via Beeper Desktop. Uses Beeper local MCP API so agents can manage all your chats (iMessage, WhatsApp, etc.) in one place.
+</Card>
+
+</CardGroup>
+
+## 🤖 Automation & Workflows
+
+<CardGroup cols={2}>
+
+<Card title="Winix Air Purifier Control" icon="wind" href="https://x.com/antonplex/status/2010518442471006253">
+  **@antonplex** • `automation` `hardware` `air-quality`
+
+Claude Code discovered and confirmed the purifier controls, then QuantumClaw takes over to manage room air quality.
+
+  <img src="/assets/showcase/winix-air-purifier.jpg" alt="Winix air purifier control via QuantumClaw" />
+</Card>
+
+<Card title="Pretty Sky Camera Shots" icon="camera" href="https://x.com/signalgaining/status/2010523120604746151">
+  **@signalgaining** • `automation` `camera` `skill` `images`
+
+Triggered by a roof camera: ask QuantumClaw to snap a sky photo whenever it looks pretty — it designed a skill and took the shot.
+
+  <img src="/assets/showcase/roof-camera-sky.jpg" alt="Roof camera sky snapshot captured by QuantumClaw" />
+</Card>
+
+<Card title="Visual Morning Briefing Scene" icon="robot" href="https://x.com/buddyhadry/status/2010005331925954739">
+  **@buddyhadry** • `automation` `briefing` `images` `telegram`
+
+A scheduled prompt generates a single "scene" image each morning (weather, tasks, date, favorite post/quote) via an QuantumClaw persona.
+</Card>
+
+<Card title="Padel Court Booking" icon="calendar-check" href="https://github.com/joshp123/padel-cli">
+  **@joshp123** • `automation` `booking` `cli`
+  
+  Playtomic availability checker + booking CLI. Never miss an open court again.
+  
+  <img src="/assets/showcase/padel-screenshot.jpg" alt="padel-cli screenshot" />
+</Card>
+
+<Card title="Accounting Intake" icon="file-invoice-dollar">
+  **Community** • `automation` `email` `pdf`
+  
+  Collects PDFs from email, preps documents for tax consultant. Monthly accounting on autopilot.
+</Card>
+
+<Card title="Couch Potato Dev Mode" icon="couch" href="https://davekiss.com">
+  **@davekiss** • `telegram` `website` `migration` `astro`
+
+Rebuilt entire personal site via Telegram while watching Netflix — Notion → Astro, 18 posts migrated, DNS to Cloudflare. Never opened a laptop.
+</Card>
+
+<Card title="Job Search Agent" icon="briefcase">
+  **@attol8** • `automation` `api` `skill`
+
+Searches job listings, matches against CV keywords, and returns relevant opportunities with links. Built in 30 minutes using JSearch API.
+</Card>
+
+<Card title="Jira Skill Builder" icon="diagram-project" href="https://x.com/jdrhyne/status/2008336434827002232">
+  **@jdrhyne** • `automation` `jira` `skill` `devtools`
+
+QuantumClaw connected to Jira, then generated a new skill on the fly (before it existed on ClawHub).
+</Card>
+
+<Card title="Todoist Skill via Telegram" icon="list-check" href="https://x.com/iamsubhrajyoti/status/2009949389884920153">
+  **@iamsubhrajyoti** • `automation` `todoist` `skill` `telegram`
+
+Automated Todoist tasks and had QuantumClaw generate the skill directly in Telegram chat.
+</Card>
+
+<Card title="TradingView Analysis" icon="chart-line">
+  **@bheem1798** • `finance` `browser` `automation`
+
+Logs into TradingView via browser automation, screenshots charts, and performs technical analysis on demand. No API needed—just browser control.
+</Card>
+
+<Card title="Slack Auto-Support" icon="slack">
+  **@henrymascot** • `slack` `automation` `support`
+
+Watches company Slack channel, responds helpfully, and forwards notifications to Telegram. Autonomously fixed a production bug in a deployed app without being asked.
+</Card>
+
+</CardGroup>
+
+## 🧠 Knowledge & Memory
+
+<CardGroup cols={2}>
+
+<Card title="xuezh Chinese Learning" icon="language" href="https://github.com/joshp123/xuezh">
+  **@joshp123** • `learning` `voice` `skill`
+  
+  Chinese learning engine with pronunciation feedback and study flows via QuantumClaw.
+  
+  <img src="/assets/showcase/xuezh-pronunciation.jpeg" alt="xuezh pronunciation feedback" />
+</Card>
+
+<Card title="WhatsApp Memory Vault" icon="vault">
+  **Community** • `memory` `transcription` `indexing`
+  
+  Ingests full WhatsApp exports, transcribes 1k+ voice notes, cross-checks with git logs, outputs linked markdown reports.
+</Card>
+
+<Card title="Karakeep Semantic Search" icon="magnifying-glass" href="https://github.com/jamesbrooksco/karakeep-semantic-search">
+  **@jamesbrooksco** • `search` `vector` `bookmarks`
+  
+  Adds vector search to Karakeep bookmarks using Qdrant + OpenAI/Ollama embeddings.
+</Card>
+
+<Card title="Inside-Out-2 Memory" icon="brain">
+  **Community** • `memory` `beliefs` `self-model`
+  
+  Separate memory manager that turns session files into memories → beliefs → evolving self model.
+</Card>
+
+</CardGroup>
+
+## 🎙️ Voice & Phone
+
+<CardGroup cols={2}>
+
+<Card title="Clawdia Phone Bridge" icon="phone" href="https://github.com/alejandroOPI/clawdia-bridge">
+  **@alejandroOPI** • `voice` `vapi` `bridge`
+  
+  Vapi voice assistant ↔ QuantumClaw HTTP bridge. Near real-time phone calls with your agent.
+</Card>
+
+<Card title="OpenRouter Transcription" icon="microphone" href="https://clawhub.com/obviyus/openrouter-transcribe">
+  **@obviyus** • `transcription` `multilingual` `skill`
+
+Multi-lingual audio transcription via OpenRouter (Gemini, etc). Available on ClawHub.
+</Card>
+
+</CardGroup>
+
+## 🏗️ Infrastructure & Deployment
+
+<CardGroup cols={2}>
+
+<Card title="Home Assistant Add-on" icon="home" href="https://github.com/ngutman/quantumclaw-ha-addon">
+  **@ngutman** • `homeassistant` `docker` `raspberry-pi`
+  
+  QuantumClaw gateway running on Home Assistant OS with SSH tunnel support and persistent state.
+</Card>
+
+<Card title="Home Assistant Skill" icon="toggle-on" href="https://clawhub.com/skills/homeassistant">
+  **ClawHub** • `homeassistant` `skill` `automation`
+  
+  Control and automate Home Assistant devices via natural language.
+</Card>
+
+<Card title="Nix Packaging" icon="snowflake" href="https://github.com/quantumclaw/nix-quantumclaw">
+  **@quantumclaw** • `nix` `packaging` `deployment`
+  
+  Batteries-included nixified QuantumClaw configuration for reproducible deployments.
+</Card>
+
+<Card title="CalDAV Calendar" icon="calendar" href="https://clawhub.com/skills/caldav-calendar">
+  **ClawHub** • `calendar` `caldav` `skill`
+  
+  Calendar skill using khal/vdirsyncer. Self-hosted calendar integration.
+</Card>
+
+</CardGroup>
+
+## 🏠 Home & Hardware
+
+<CardGroup cols={2}>
+
+<Card title="GoHome Automation" icon="house-signal" href="https://github.com/joshp123/gohome">
+  **@joshp123** • `home` `nix` `grafana`
+  
+  Nix-native home automation with QuantumClaw as the interface, plus beautiful Grafana dashboards.
+  
+  <img src="/assets/showcase/gohome-grafana.png" alt="GoHome Grafana dashboard" />
+</Card>
+
+<Card title="Roborock Vacuum" icon="robot" href="https://github.com/joshp123/gohome/tree/main/plugins/roborock">
+  **@joshp123** • `vacuum` `iot` `plugin`
+  
+  Control your Roborock robot vacuum through natural conversation.
+  
+  <img src="/assets/showcase/roborock-screenshot.jpg" alt="Roborock status" />
+</Card>
+
+</CardGroup>
+
+## 🌟 Community Projects
+
+<CardGroup cols={2}>
+
+<Card title="StarSwap Marketplace" icon="star" href="https://star-swap.com/">
+  **Community** • `marketplace` `astronomy` `webapp`
+  
+  Full astronomy gear marketplace. Built with/around the QuantumClaw ecosystem.
+</Card>
+
+</CardGroup>
+
+---
+
+## Submit Your Project
+
+Have something to share? We'd love to feature it!
+
+<Steps>
+  <Step title="Share It">
+    Post in [#showcase on Discord](https://discord.gg/clawd) or [tweet @quantumclaw](https://x.com/quantumclaw)
+  </Step>
+  <Step title="Include Details">
+    Tell us what it does, link to the repo/demo, share a screenshot if you have one
+  </Step>
+  <Step title="Get Featured">
+    We'll add standout projects to this page
+  </Step>
+</Steps>