@quantumclaw/quantumclaw 2026.3.22

package/docs/plugins/building-extensions.md

@@ -0,0 +1,10 @@
+---
+title: "Building Plugins"
+summary: "Redirects to the current Building Plugins guide"
+read_when:
+  - Legacy link to building-extensions
+---
+
+# Building Plugins
+
+This page has moved to [Building Plugins](/plugins/building-plugins).

package/docs/plugins/building-plugins.md

@@ -0,0 +1,239 @@
+---
+title: "Building Plugins"
+sidebarTitle: "Getting Started"
+summary: "Create your first QuantumClaw plugin in minutes"
+read_when:
+  - You want to create a new QuantumClaw plugin
+  - You need a quick-start for plugin development
+  - You are adding a new channel, provider, tool, or other capability to QuantumClaw
+---
+
+# Building Plugins
+
+Plugins extend QuantumClaw with new capabilities: channels, model providers, speech,
+image generation, web search, agent tools, or any combination.
+
+You do not need to add your plugin to the QuantumClaw repository. Publish to
+[ClawHub](/tools/clawhub) or npm and users install with
+`quantumclaw plugins install <package-name>`. QuantumClaw tries ClawHub first and
+falls back to npm automatically.
+
+## Prerequisites
+
+- Node >= 22 and a package manager (npm or pnpm)
+- Familiarity with TypeScript (ESM)
+- For in-repo plugins: repository cloned and `pnpm install` done
+
+## What kind of plugin?
+
+<CardGroup cols={3}>
+  <Card title="Channel plugin" icon="messages-square" href="/plugins/sdk-channel-plugins">
+    Connect QuantumClaw to a messaging platform (Discord, IRC, etc.)
+  </Card>
+  <Card title="Provider plugin" icon="cpu" href="/plugins/sdk-provider-plugins">
+    Add a model provider (LLM, proxy, or custom endpoint)
+  </Card>
+  <Card title="Tool / hook plugin" icon="wrench">
+    Register agent tools, event hooks, or services — continue below
+  </Card>
+</CardGroup>
+
+## Quick start: tool plugin
+
+This walkthrough creates a minimal plugin that registers an agent tool. Channel
+and provider plugins have dedicated guides linked above.
+
+<Steps>
+  <Step title="Create the package and manifest">
+    <CodeGroup>
+    ```json package.json
+    {
+      "name": "@myorg/quantumclaw-my-plugin",
+      "version": "1.0.0",
+      "type": "module",
+      "quantumclaw": {
+        "extensions": ["./index.ts"]
+      }
+    }
+    ```
+
+    ```json quantumclaw.plugin.json
+    {
+      "id": "my-plugin",
+      "name": "My Plugin",
+      "description": "Adds a custom tool to QuantumClaw",
+      "configSchema": {
+        "type": "object",
+        "additionalProperties": false
+      }
+    }
+    ```
+    </CodeGroup>
+
+    Every plugin needs a manifest, even with no config. See
+    [Manifest](/plugins/manifest) for the full schema.
+
+  </Step>
+
+  <Step title="Write the entry point">
+
+    ```typescript
+    // index.ts
+    import { definePluginEntry } from "quantumclaw/plugin-sdk/plugin-entry";
+    import { Type } from "@sinclair/typebox";
+
+    export default definePluginEntry({
+      id: "my-plugin",
+      name: "My Plugin",
+      description: "Adds a custom tool to QuantumClaw",
+      register(api) {
+        api.registerTool({
+          name: "my_tool",
+          description: "Do a thing",
+          parameters: Type.Object({ input: Type.String() }),
+          async execute(_id, params) {
+            return { content: [{ type: "text", text: `Got: ${params.input}` }] };
+          },
+        });
+      },
+    });
+    ```
+
+    `definePluginEntry` is for non-channel plugins. For channels, use
+    `defineChannelPluginEntry` — see [Channel Plugins](/plugins/sdk-channel-plugins).
+    For full entry point options, see [Entry Points](/plugins/sdk-entrypoints).
+
+  </Step>
+
+  <Step title="Test and publish">
+
+    **External plugins:** publish to [ClawHub](/tools/clawhub) or npm, then install:
+
+    ```bash
+    quantumclaw plugins install @myorg/quantumclaw-my-plugin
+    ```
+
+    QuantumClaw checks ClawHub first, then falls back to npm.
+
+    **In-repo plugins:** place under `extensions/` — automatically discovered.
+
+    ```bash
+    pnpm test -- extensions/my-plugin/
+    ```
+
+  </Step>
+</Steps>
+
+## Plugin capabilities
+
+A single plugin can register any number of capabilities via the `api` object:
+
+| Capability           | Registration method                           | Detailed guide                                                                  |
+| -------------------- | --------------------------------------------- | ------------------------------------------------------------------------------- |
+| Text inference (LLM) | `api.registerProvider(...)`                   | [Provider Plugins](/plugins/sdk-provider-plugins)                               |
+| Channel / messaging  | `api.registerChannel(...)`                    | [Channel Plugins](/plugins/sdk-channel-plugins)                                 |
+| Speech (TTS/STT)     | `api.registerSpeechProvider(...)`             | [Provider Plugins](/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
+| Media understanding  | `api.registerMediaUnderstandingProvider(...)` | [Provider Plugins](/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
+| Image generation     | `api.registerImageGenerationProvider(...)`    | [Provider Plugins](/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
+| Web search           | `api.registerWebSearchProvider(...)`          | [Provider Plugins](/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
+| Agent tools          | `api.registerTool(...)`                       | Below                                                                           |
+| Custom commands      | `api.registerCommand(...)`                    | [Entry Points](/plugins/sdk-entrypoints)                                        |
+| Event hooks          | `api.registerHook(...)`                       | [Entry Points](/plugins/sdk-entrypoints)                                        |
+| HTTP routes          | `api.registerHttpRoute(...)`                  | [Internals](/plugins/architecture#gateway-http-routes)                          |
+| CLI subcommands      | `api.registerCli(...)`                        | [Entry Points](/plugins/sdk-entrypoints)                                        |
+
+For the full registration API, see [SDK Overview](/plugins/sdk-overview#registration-api).
+
+## Registering agent tools
+
+Tools are typed functions the LLM can call. They can be required (always
+available) or optional (user opt-in):
+
+```typescript
+register(api) {
+  // Required tool — always available
+  api.registerTool({
+    name: "my_tool",
+    description: "Do a thing",
+    parameters: Type.Object({ input: Type.String() }),
+    async execute(_id, params) {
+      return { content: [{ type: "text", text: params.input }] };
+    },
+  });
+
+  // Optional tool — user must add to allowlist
+  api.registerTool(
+    {
+      name: "workflow_tool",
+      description: "Run a workflow",
+      parameters: Type.Object({ pipeline: Type.String() }),
+      async execute(_id, params) {
+        return { content: [{ type: "text", text: params.pipeline }] };
+      },
+    },
+    { optional: true },
+  );
+}
+```
+
+Users enable optional tools in config:
+
+```json5
+{
+  tools: { allow: ["workflow_tool"] },
+}
+```
+
+- Tool names must not clash with core tools (conflicts are skipped)
+- Use `optional: true` for tools with side effects or extra binary requirements
+- Users can enable all tools from a plugin by adding the plugin id to `tools.allow`
+
+## Import conventions
+
+Always import from focused `quantumclaw/plugin-sdk/<subpath>` paths:
+
+```typescript
+import { definePluginEntry } from "quantumclaw/plugin-sdk/plugin-entry";
+import { createPluginRuntimeStore } from "quantumclaw/plugin-sdk/runtime-store";
+
+// Wrong: monolithic root (deprecated, will be removed)
+import { ... } from "quantumclaw/plugin-sdk";
+```
+
+For the full subpath reference, see [SDK Overview](/plugins/sdk-overview).
+
+Within your plugin, use local barrel files (`api.ts`, `runtime-api.ts`) for
+internal imports — never import your own plugin through its SDK path.
+
+## Pre-submission checklist
+
+<Check>**package.json** has correct `quantumclaw` metadata</Check>
+<Check>**quantumclaw.plugin.json** manifest is present and valid</Check>
+<Check>Entry point uses `defineChannelPluginEntry` or `definePluginEntry`</Check>
+<Check>All imports use focused `plugin-sdk/<subpath>` paths</Check>
+<Check>Internal imports use local modules, not SDK self-imports</Check>
+<Check>Tests pass (`pnpm test -- extensions/my-plugin/`)</Check>
+<Check>`pnpm check` passes (in-repo plugins)</Check>
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Channel Plugins" icon="messages-square" href="/plugins/sdk-channel-plugins">
+    Build a messaging channel plugin
+  </Card>
+  <Card title="Provider Plugins" icon="cpu" href="/plugins/sdk-provider-plugins">
+    Build a model provider plugin
+  </Card>
+  <Card title="SDK Overview" icon="book-open" href="/plugins/sdk-overview">
+    Import map and registration API reference
+  </Card>
+  <Card title="Runtime Helpers" icon="settings" href="/plugins/sdk-runtime">
+    TTS, search, subagent via api.runtime
+  </Card>
+  <Card title="Testing" icon="test-tubes" href="/plugins/sdk-testing">
+    Test utilities and patterns
+  </Card>
+  <Card title="Plugin Manifest" icon="file-json" href="/plugins/manifest">
+    Full manifest schema reference
+  </Card>
+</CardGroup>

package/docs/plugins/bundles.md

@@ -0,0 +1,181 @@
+---
+summary: "Install and use Codex, Claude, and Cursor bundles as QuantumClaw plugins"
+read_when:
+  - You want to install a Codex, Claude, or Cursor-compatible bundle
+  - You need to understand how QuantumClaw maps bundle content into native features
+  - You are debugging bundle detection or missing capabilities
+title: "Plugin Bundles"
+---
+
+# Plugin Bundles
+
+QuantumClaw can install plugins from three external ecosystems: **Codex**, **Claude**,
+and **Cursor**. These are called **bundles** — content and metadata packs that
+QuantumClaw maps into native features like skills, hooks, and MCP tools.
+
+<Info>
+  Bundles are **not** the same as native QuantumClaw plugins. Native plugins run
+  in-process and can register any capability. Bundles are content packs with
+  selective feature mapping and a narrower trust boundary.
+</Info>
+
+## Why bundles exist
+
+Many useful plugins are published in Codex, Claude, or Cursor format. Instead
+of requiring authors to rewrite them as native QuantumClaw plugins, QuantumClaw
+detects these formats and maps their supported content into the native feature
+set. This means you can install a Claude command pack or a Codex skill bundle
+and use it immediately.
+
+## Install a bundle
+
+<Steps>
+  <Step title="Install from a directory, archive, or marketplace">
+    ```bash
+    # Local directory
+    quantumclaw plugins install ./my-bundle
+
+    # Archive
+    quantumclaw plugins install ./my-bundle.tgz
+
+    # Claude marketplace
+    quantumclaw plugins marketplace list <marketplace-name>
+    quantumclaw plugins install <plugin-name>@<marketplace-name>
+    ```
+
+  </Step>
+
+  <Step title="Verify detection">
+    ```bash
+    quantumclaw plugins list
+    quantumclaw plugins inspect <id>
+    ```
+
+    Bundles show as `Format: bundle` with a subtype of `codex`, `claude`, or `cursor`.
+
+  </Step>
+
+  <Step title="Restart and use">
+    ```bash
+    quantumclaw gateway restart
+    ```
+
+    Mapped features (skills, hooks, MCP tools) are available in the next session.
+
+  </Step>
+</Steps>
+
+## What QuantumClaw maps from bundles
+
+Not every bundle feature runs in QuantumClaw today. Here is what works and what
+is detected but not yet wired.
+
+### Supported now
+
+| Feature       | How it maps                                                                                          | Applies to     |
+| ------------- | ---------------------------------------------------------------------------------------------------- | -------------- |
+| Skill content | Bundle skill roots load as normal QuantumClaw skills                                                    | All formats    |
+| Commands      | `commands/` and `.cursor/commands/` treated as skill roots                                           | Claude, Cursor |
+| Hook packs    | QuantumClaw-style `HOOK.md` + `handler.ts` layouts                                                      | Codex          |
+| MCP tools     | Bundle MCP config merged into embedded Pi settings; supported stdio servers launched as subprocesses | All formats    |
+| Settings      | Claude `settings.json` imported as embedded Pi defaults                                              | Claude         |
+
+### Detected but not executed
+
+These are recognized and shown in diagnostics, but QuantumClaw does not run them:
+
+- Claude `agents`, `hooks.json` automation, `lspServers`, `outputStyles`
+- Cursor `.cursor/agents`, `.cursor/hooks.json`, `.cursor/rules`
+- Codex inline/app metadata beyond capability reporting
+
+## Bundle formats
+
+<AccordionGroup>
+  <Accordion title="Codex bundles">
+    Markers: `.codex-plugin/plugin.json`
+
+    Optional content: `skills/`, `hooks/`, `.mcp.json`, `.app.json`
+
+    Codex bundles fit QuantumClaw best when they use skill roots and QuantumClaw-style
+    hook-pack directories (`HOOK.md` + `handler.ts`).
+
+  </Accordion>
+
+  <Accordion title="Claude bundles">
+    Two detection modes:
+
+    - **Manifest-based:** `.claude-plugin/plugin.json`
+    - **Manifestless:** default Claude layout (`skills/`, `commands/`, `agents/`, `hooks/`, `.mcp.json`, `settings.json`)
+
+    Claude-specific behavior:
+
+    - `commands/` is treated as skill content
+    - `settings.json` is imported into embedded Pi settings (shell override keys are sanitized)
+    - `.mcp.json` exposes supported stdio tools to embedded Pi
+    - `hooks/hooks.json` is detected but not executed
+    - Custom component paths in the manifest are additive (they extend defaults, not replace them)
+
+  </Accordion>
+
+  <Accordion title="Cursor bundles">
+    Markers: `.cursor-plugin/plugin.json`
+
+    Optional content: `skills/`, `.cursor/commands/`, `.cursor/agents/`, `.cursor/rules/`, `.cursor/hooks.json`, `.mcp.json`
+
+    - `.cursor/commands/` is treated as skill content
+    - `.cursor/rules/`, `.cursor/agents/`, and `.cursor/hooks.json` are detect-only
+
+  </Accordion>
+</AccordionGroup>
+
+## Detection precedence
+
+QuantumClaw checks for native plugin format first:
+
+1. `quantumclaw.plugin.json` or valid `package.json` with `quantumclaw.extensions` — treated as **native plugin**
+2. Bundle markers (`.codex-plugin/`, `.claude-plugin/`, or default Claude/Cursor layout) — treated as **bundle**
+
+If a directory contains both, QuantumClaw uses the native path. This prevents
+dual-format packages from being partially installed as bundles.
+
+## Security
+
+Bundles have a narrower trust boundary than native plugins:
+
+- QuantumClaw does **not** load arbitrary bundle runtime modules in-process
+- Skills and hook-pack paths must stay inside the plugin root (boundary-checked)
+- Settings files are read with the same boundary checks
+- Supported stdio MCP servers may be launched as subprocesses
+
+This makes bundles safer by default, but you should still treat third-party
+bundles as trusted content for the features they do expose.
+
+## Troubleshooting
+
+<AccordionGroup>
+  <Accordion title="Bundle is detected but capabilities do not run">
+    Run `quantumclaw plugins inspect <id>`. If a capability is listed but marked as
+    not wired, that is a product limit — not a broken install.
+  </Accordion>
+
+  <Accordion title="Claude command files do not appear">
+    Make sure the bundle is enabled and the markdown files are inside a detected
+    `commands/` or `skills/` root.
+  </Accordion>
+
+  <Accordion title="Claude settings do not apply">
+    Only embedded Pi settings from `settings.json` are supported. QuantumClaw does
+    not treat bundle settings as raw config patches.
+  </Accordion>
+
+  <Accordion title="Claude hooks do not execute">
+    `hooks/hooks.json` is detect-only. If you need runnable hooks, use the
+    QuantumClaw hook-pack layout or ship a native plugin.
+  </Accordion>
+</AccordionGroup>
+
+## Related
+
+- [Install and Configure Plugins](/tools/plugin)
+- [Building Plugins](/plugins/building-plugins) — create a native plugin
+- [Plugin Manifest](/plugins/manifest) — native manifest schema

package/docs/plugins/community.md

@@ -0,0 +1,145 @@
+---
+summary: "Community-maintained QuantumClaw plugins: browse, install, and submit your own"
+read_when:
+  - You want to find third-party QuantumClaw plugins
+  - You want to publish or list your own plugin
+title: "Community Plugins"
+---
+
+# Community Plugins
+
+Community plugins are third-party packages that extend QuantumClaw with new
+channels, tools, providers, or other capabilities. They are built and maintained
+by the community, published on [ClawHub](/tools/clawhub) or npm, and
+installable with a single command.
+
+```bash
+quantumclaw plugins install <package-name>
+```
+
+QuantumClaw checks ClawHub first and falls back to npm automatically.
+
+## Listed plugins
+
+### Codex App Server Bridge
+
+Independent QuantumClaw bridge for Codex App Server conversations. Bind a chat to
+a Codex thread, talk to it with plain text, and control it with chat-native
+commands for resume, planning, review, model selection, compaction, and more.
+
+- **npm:** `quantumclaw-codex-app-server`
+- **repo:** [github.com/pwrdrvr/quantumclaw-codex-app-server](https://github.com/pwrdrvr/quantumclaw-codex-app-server)
+
+```bash
+quantumclaw plugins install quantumclaw-codex-app-server
+```
+
+### DingTalk
+
+Enterprise robot integration using Stream mode. Supports text, images, and
+file messages via any DingTalk client.
+
+- **npm:** `@largezhou/ddingtalk`
+- **repo:** [github.com/largezhou/quantumclaw-dingtalk](https://github.com/largezhou/quantumclaw-dingtalk)
+
+```bash
+quantumclaw plugins install @largezhou/ddingtalk
+```
+
+### Lossless Claw (LCM)
+
+Lossless Context Management plugin for QuantumClaw. DAG-based conversation
+summarization with incremental compaction — preserves full context fidelity
+while reducing token usage.
+
+- **npm:** `@martian-engineering/lossless-claw`
+- **repo:** [github.com/Martian-Engineering/lossless-claw](https://github.com/Martian-Engineering/lossless-claw)
+
+```bash
+quantumclaw plugins install @martian-engineering/lossless-claw
+```
+
+### Opik
+
+Official plugin that exports agent traces to Opik. Monitor agent behavior,
+cost, tokens, errors, and more.
+
+- **npm:** `@opik/opik-quantumclaw`
+- **repo:** [github.com/comet-ml/opik-quantumclaw](https://github.com/comet-ml/opik-quantumclaw)
+
+```bash
+quantumclaw plugins install @opik/opik-quantumclaw
+```
+
+### QQbot
+
+Connect QuantumClaw to QQ via the QQ Bot API. Supports private chats, group
+mentions, channel messages, and rich media including voice, images, videos,
+and files.
+
+- **npm:** `@sliverp/qqbot`
+- **repo:** [github.com/sliverp/qqbot](https://github.com/sliverp/qqbot)
+
+```bash
+quantumclaw plugins install @sliverp/qqbot
+```
+
+### wecom
+
+QuantumClaw Enterprise WeCom Channel Plugin.
+A bot plugin powered by WeCom AI Bot WebSocket persistent connections,
+supports direct messages & group chats, streaming replies, and proactive messaging.
+
+- **npm:** `@wecom/wecom-quantumclaw-plugin`
+- **repo:** [github.com/WecomTeam/wecom-quantumclaw-plugin](https://github.com/WecomTeam/wecom-quantumclaw-plugin)
+
+```bash
+quantumclaw plugins install @wecom/wecom-quantumclaw-plugin
+```
+
+## Submit your plugin
+
+We welcome community plugins that are useful, documented, and safe to operate.
+
+<Steps>
+  <Step title="Publish to ClawHub or npm">
+    Your plugin must be installable via `quantumclaw plugins install \<package-name\>`.
+    Publish to [ClawHub](/tools/clawhub) (preferred) or npm.
+    See [Building Plugins](/plugins/building-plugins) for the full guide.
+
+  </Step>
+
+  <Step title="Host on GitHub">
+    Source code must be in a public repository with setup docs and an issue
+    tracker.
+
+  </Step>
+
+  <Step title="Open a PR">
+    Add your plugin to this page with:
+
+    - Plugin name
+    - npm package name
+    - GitHub repository URL
+    - One-line description
+    - Install command
+
+  </Step>
+</Steps>
+
+## Quality bar
+
+| Requirement                 | Why                                           |
+| --------------------------- | --------------------------------------------- |
+| Published on ClawHub or npm | Users need `quantumclaw plugins install` to work |
+| Public GitHub repo          | Source review, issue tracking, transparency   |
+| Setup and usage docs        | Users need to know how to configure it        |
+| Active maintenance          | Recent updates or responsive issue handling   |
+
+Low-effort wrappers, unclear ownership, or unmaintained packages may be declined.
+
+## Related
+
+- [Install and Configure Plugins](/tools/plugin) — how to install any plugin
+- [Building Plugins](/plugins/building-plugins) — create your own
+- [Plugin Manifest](/plugins/manifest) — manifest schema