@quantumclaw/quantumclaw 2026.3.22

package/docs/tools/plugin.md

@@ -0,0 +1,255 @@
+---
+summary: "Install, configure, and manage QuantumClaw plugins"
+read_when:
+  - Installing or configuring plugins
+  - Understanding plugin discovery and load rules
+  - Working with Codex/Claude-compatible plugin bundles
+title: "Plugins"
+sidebarTitle: "Install and Configure"
+---
+
+# Plugins
+
+Plugins extend QuantumClaw with new capabilities: channels, model providers, tools,
+skills, speech, image generation, and more. Some plugins are **core** (shipped
+with QuantumClaw), others are **external** (published on npm by the community).
+
+## Quick start
+
+<Steps>
+  <Step title="See what is loaded">
+    ```bash
+    quantumclaw plugins list
+    ```
+  </Step>
+
+  <Step title="Install a plugin">
+    ```bash
+    # From npm
+    quantumclaw plugins install @quantumclaw/voice-call
+
+    # From a local directory or archive
+    quantumclaw plugins install ./my-plugin
+    quantumclaw plugins install ./my-plugin.tgz
+    ```
+
+  </Step>
+
+  <Step title="Restart the Gateway">
+    ```bash
+    quantumclaw gateway restart
+    ```
+
+    Then configure under `plugins.entries.\<id\>.config` in your config file.
+
+  </Step>
+</Steps>
+
+## Plugin types
+
+QuantumClaw recognizes two plugin formats:
+
+| Format     | How it works                                                       | Examples                                               |
+| ---------- | ------------------------------------------------------------------ | ------------------------------------------------------ |
+| **Native** | `quantumclaw.plugin.json` + runtime module; executes in-process       | Official plugins, community npm packages               |
+| **Bundle** | Codex/Claude/Cursor-compatible layout; mapped to QuantumClaw features | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` |
+
+Both show up under `quantumclaw plugins list`. See [Plugin Bundles](/plugins/bundles) for bundle details.
+
+If you are writing a native plugin, start with [Building Plugins](/plugins/building-plugins)
+and the [Plugin SDK Overview](/plugins/sdk-overview).
+
+## Official plugins
+
+### Installable (npm)
+
+| Plugin          | Package                | Docs                                 |
+| --------------- | ---------------------- | ------------------------------------ |
+| Matrix          | `@quantumclaw/matrix`     | [Matrix](/channels/matrix)           |
+| Microsoft Teams | `@quantumclaw/msteams`    | [Microsoft Teams](/channels/msteams) |
+| Nostr           | `@quantumclaw/nostr`      | [Nostr](/channels/nostr)             |
+| Voice Call      | `@quantumclaw/voice-call` | [Voice Call](/plugins/voice-call)    |
+| Zalo            | `@quantumclaw/zalo`       | [Zalo](/channels/zalo)               |
+| Zalo Personal   | `@quantumclaw/zalouser`   | [Zalo Personal](/plugins/zalouser)   |
+
+### Core (shipped with QuantumClaw)
+
+<AccordionGroup>
+  <Accordion title="Model providers (enabled by default)">
+    `anthropic`, `byteplus`, `cloudflare-ai-gateway`, `github-copilot`, `google`,
+    `huggingface`, `kilocode`, `kimi-coding`, `minimax`, `mistral`, `modelstudio`,
+    `moonshot`, `nvidia`, `openai`, `opencode`, `opencode-go`, `openrouter`,
+    `qianfan`, `qwen-portal-auth`, `synthetic`, `together`, `venice`,
+    `vercel-ai-gateway`, `volcengine`, `xiaomi`, `zai`
+  </Accordion>
+
+  <Accordion title="Memory plugins">
+    - `memory-core` — bundled memory search (default via `plugins.slots.memory`)
+    - `memory-lancedb` — install-on-demand long-term memory with auto-recall/capture (set `plugins.slots.memory = "memory-lancedb"`)
+  </Accordion>
+
+  <Accordion title="Speech providers (enabled by default)">
+    `elevenlabs`, `microsoft`
+  </Accordion>
+
+  <Accordion title="Other">
+    - `copilot-proxy` — VS Code Copilot Proxy bridge (disabled by default)
+  </Accordion>
+</AccordionGroup>
+
+Looking for third-party plugins? See [Community Plugins](/plugins/community).
+
+## Configuration
+
+```json5
+{
+  plugins: {
+    enabled: true,
+    allow: ["voice-call"],
+    deny: ["untrusted-plugin"],
+    load: { paths: ["~/Projects/oss/voice-call-extension"] },
+    entries: {
+      "voice-call": { enabled: true, config: { provider: "twilio" } },
+    },
+  },
+}
+```
+
+| Field            | Description                                               |
+| ---------------- | --------------------------------------------------------- |
+| `enabled`        | Master toggle (default: `true`)                           |
+| `allow`          | Plugin allowlist (optional)                               |
+| `deny`           | Plugin denylist (optional; deny wins)                     |
+| `load.paths`     | Extra plugin files/directories                            |
+| `slots`          | Exclusive slot selectors (e.g. `memory`, `contextEngine`) |
+| `entries.\<id\>` | Per-plugin toggles + config                               |
+
+Config changes **require a gateway restart**.
+
+<Accordion title="Plugin states: disabled vs missing vs invalid">
+  - **Disabled**: plugin exists but enablement rules turned it off. Config is preserved.
+  - **Missing**: config references a plugin id that discovery did not find.
+  - **Invalid**: plugin exists but its config does not match the declared schema.
+</Accordion>
+
+## Discovery and precedence
+
+QuantumClaw scans for plugins in this order (first match wins):
+
+<Steps>
+  <Step title="Config paths">
+    `plugins.load.paths` — explicit file or directory paths.
+  </Step>
+
+  <Step title="Workspace extensions">
+    `\<workspace\>/.quantumclaw/extensions/*.ts` and `\<workspace\>/.quantumclaw/extensions/*/index.ts`.
+  </Step>
+
+  <Step title="Global extensions">
+    `~/.quantumclaw/extensions/*.ts` and `~/.quantumclaw/extensions/*/index.ts`.
+  </Step>
+
+  <Step title="Bundled plugins">
+    Shipped with QuantumClaw. Many are enabled by default (model providers, speech).
+    Others require explicit enablement.
+  </Step>
+</Steps>
+
+### Enablement rules
+
+- `plugins.enabled: false` disables all plugins
+- `plugins.deny` always wins over allow
+- `plugins.entries.\<id\>.enabled: false` disables that plugin
+- Workspace-origin plugins are **disabled by default** (must be explicitly enabled)
+- Bundled plugins follow the built-in default-on set unless overridden
+- Exclusive slots can force-enable the selected plugin for that slot
+
+## Plugin slots (exclusive categories)
+
+Some categories are exclusive (only one active at a time):
+
+```json5
+{
+  plugins: {
+    slots: {
+      memory: "memory-core", // or "none" to disable
+      contextEngine: "legacy", // or a plugin id
+    },
+  },
+}
+```
+
+| Slot            | What it controls      | Default             |
+| --------------- | --------------------- | ------------------- |
+| `memory`        | Active memory plugin  | `memory-core`       |
+| `contextEngine` | Active context engine | `legacy` (built-in) |
+
+## CLI reference
+
+```bash
+quantumclaw plugins list                    # compact inventory
+quantumclaw plugins inspect <id>            # deep detail
+quantumclaw plugins inspect <id> --json     # machine-readable
+quantumclaw plugins status                  # operational summary
+quantumclaw plugins doctor                  # diagnostics
+
+quantumclaw plugins install <package>        # install (ClawHub first, then npm)
+quantumclaw plugins install clawhub:<pkg>   # install from ClawHub only
+quantumclaw plugins install <path>          # install from local path
+quantumclaw plugins install -l <path>       # link (no copy) for dev
+quantumclaw plugins update <id>             # update one plugin
+quantumclaw plugins update --all            # update all
+
+quantumclaw plugins enable <id>
+quantumclaw plugins disable <id>
+```
+
+See [`quantumclaw plugins` CLI reference](/cli/plugins) for full details.
+
+## Plugin API overview
+
+Plugins export either a function or an object with `register(api)`:
+
+```typescript
+export default definePluginEntry({
+  id: "my-plugin",
+  name: "My Plugin",
+  register(api) {
+    api.registerProvider({
+      /* ... */
+    });
+    api.registerTool({
+      /* ... */
+    });
+    api.registerChannel({
+      /* ... */
+    });
+  },
+});
+```
+
+Common registration methods:
+
+| Method                               | What it registers    |
+| ------------------------------------ | -------------------- |
+| `registerProvider`                   | Model provider (LLM) |
+| `registerChannel`                    | Chat channel         |
+| `registerTool`                       | Agent tool           |
+| `registerHook` / `on(...)`           | Lifecycle hooks      |
+| `registerSpeechProvider`             | Text-to-speech / STT |
+| `registerMediaUnderstandingProvider` | Image/audio analysis |
+| `registerImageGenerationProvider`    | Image generation     |
+| `registerWebSearchProvider`          | Web search           |
+| `registerHttpRoute`                  | HTTP endpoint        |
+| `registerCommand` / `registerCli`    | CLI commands         |
+| `registerContextEngine`              | Context engine       |
+| `registerService`                    | Background service   |
+
+## Related
+
+- [Building Plugins](/plugins/building-plugins) — create your own plugin
+- [Plugin Bundles](/plugins/bundles) — Codex/Claude/Cursor bundle compatibility
+- [Plugin Manifest](/plugins/manifest) — manifest schema
+- [Registering Tools](/plugins/building-plugins#registering-agent-tools) — add agent tools in a plugin
+- [Plugin Internals](/plugins/architecture) — capability model and load pipeline
+- [Community Plugins](/plugins/community) — third-party listings

package/docs/tools/reactions.md

@@ -0,0 +1,64 @@
+---
+summary: "Reaction tool semantics across all supported channels"
+read_when:
+  - Working on reactions in any channel
+  - Understanding how emoji reactions differ across platforms
+title: "Reactions"
+---
+
+# Reactions
+
+The agent can add and remove emoji reactions on messages using the `message`
+tool with the `react` action. Reaction behavior varies by channel.
+
+## How it works
+
+```json
+{
+  "action": "react",
+  "messageId": "msg-123",
+  "emoji": "thumbsup"
+}
+```
+
+- `emoji` is required when adding a reaction.
+- Set `emoji` to an empty string (`""`) to remove the bot's reaction(s).
+- Set `remove: true` to remove a specific emoji (requires non-empty `emoji`).
+
+## Channel behavior
+
+<AccordionGroup>
+  <Accordion title="Discord and Slack">
+    - Empty `emoji` removes all of the bot's reactions on the message.
+    - `remove: true` removes just the specified emoji.
+  </Accordion>
+
+  <Accordion title="Google Chat">
+    - Empty `emoji` removes the app's reactions on the message.
+    - `remove: true` removes just the specified emoji.
+  </Accordion>
+
+  <Accordion title="Telegram">
+    - Empty `emoji` removes the bot's reactions.
+    - `remove: true` also removes reactions but still requires a non-empty `emoji` for tool validation.
+  </Accordion>
+
+  <Accordion title="WhatsApp">
+    - Empty `emoji` removes the bot reaction.
+    - `remove: true` maps to empty emoji internally (still requires `emoji` in the tool call).
+  </Accordion>
+
+  <Accordion title="Zalo Personal (zalouser)">
+    - Requires non-empty `emoji`.
+    - `remove: true` removes that specific emoji reaction.
+  </Accordion>
+
+  <Accordion title="Signal">
+    - Inbound reaction notifications emit system events when `channels.signal.reactionNotifications` is enabled.
+  </Accordion>
+</AccordionGroup>
+
+## Related
+
+- [Agent Send](/tools/agent-send) — the `message` tool that includes `react`
+- [Channels](/channels) — channel-specific configuration

package/docs/tools/skills-config.md

@@ -0,0 +1,86 @@
+---
+summary: "Skills config schema and examples"
+read_when:
+  - Adding or modifying skills config
+  - Adjusting bundled allowlist or install behavior
+title: "Skills Config"
+---
+
+# Skills Config
+
+All skills-related configuration lives under `skills` in `~/.quantumclaw/quantumclaw.json`.
+
+```json5
+{
+  skills: {
+    allowBundled: ["gemini", "peekaboo"],
+    load: {
+      extraDirs: ["~/Projects/agent-scripts/skills", "~/Projects/oss/some-skill-pack/skills"],
+      watch: true,
+      watchDebounceMs: 250,
+    },
+    install: {
+      preferBrew: true,
+      nodeManager: "npm", // npm | pnpm | yarn | bun (Gateway runtime still Node; bun not recommended)
+    },
+    entries: {
+      "image-lab": {
+        enabled: true,
+        apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string
+        env: {
+          GEMINI_API_KEY: "GEMINI_KEY_HERE",
+        },
+      },
+      peekaboo: { enabled: true },
+      sag: { enabled: false },
+    },
+  },
+}
+```
+
+For built-in image generation/editing, prefer `agents.defaults.imageGenerationModel`
+plus the core `image_generate` tool. `skills.entries.*` is only for custom or
+third-party skill workflows.
+
+Examples:
+
+- Native Nano Banana-style setup: `agents.defaults.imageGenerationModel.primary: "google/gemini-3-pro-image-preview"`
+- Native fal setup: `agents.defaults.imageGenerationModel.primary: "fal/fal-ai/flux/dev"`
+
+## Fields
+
+- `allowBundled`: optional allowlist for **bundled** skills only. When set, only
+  bundled skills in the list are eligible (managed/workspace skills unaffected).
+- `load.extraDirs`: additional skill directories to scan (lowest precedence).
+- `load.watch`: watch skill folders and refresh the skills snapshot (default: true).
+- `load.watchDebounceMs`: debounce for skill watcher events in milliseconds (default: 250).
+- `install.preferBrew`: prefer brew installers when available (default: true).
+- `install.nodeManager`: node installer preference (`npm` | `pnpm` | `yarn` | `bun`, default: npm).
+  This only affects **skill installs**; the Gateway runtime should still be Node
+  (Bun not recommended for WhatsApp/Telegram).
+- `entries.<skillKey>`: per-skill overrides.
+
+Per-skill fields:
+
+- `enabled`: set `false` to disable a skill even if it’s bundled/installed.
+- `env`: environment variables injected for the agent run (only if not already set).
+- `apiKey`: optional convenience for skills that declare a primary env var.
+  Supports plaintext string or SecretRef object (`{ source, provider, id }`).
+
+## Notes
+
+- Keys under `entries` map to the skill name by default. If a skill defines
+  `metadata.quantumclaw.skillKey`, use that key instead.
+- Changes to skills are picked up on the next agent turn when the watcher is enabled.
+
+### Sandboxed skills + env vars
+
+When a session is **sandboxed**, skill processes run inside Docker. The sandbox
+does **not** inherit the host `process.env`.
+
+Use one of:
+
+- `agents.defaults.sandbox.docker.env` (or per-agent `agents.list[].sandbox.docker.env`)
+- bake the env into your custom sandbox image
+
+Global `env` and `skills.entries.<skill>.env/apiKey` apply to **host** runs only.