durar-ai 2026.4.4

package/docs/plugins/building-extensions.md

@@ -0,0 +1,10 @@
+---
+title: "Building Plugins (redirect)"
+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,319 @@
+---
+title: "Building Plugins"
+sidebarTitle: "Getting Started"
+summary: "Create your first Durar plugin in minutes"
+read_when:
+  - You want to create a new Durar plugin
+  - You need a quick-start for plugin development
+  - You are adding a new channel, provider, tool, or other capability to Durar
+---
+
+# Building Plugins
+
+Plugins extend Durar with new capabilities: channels, model providers,
+speech, realtime transcription, realtime voice, media understanding, image
+generation, video generation, web fetch, web search, agent tools, or any
+combination.
+
+You do not need to add your plugin to the Durar repository. Publish to
+[Durar Gateway](/tools/Durar Gateway) or npm and users install with
+`Durar plugins install <package-name>`. Durar tries Durar Gateway 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 Durar 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>
+
+If a channel plugin is optional and may not be installed when onboarding/setup
+runs, use `createOptionalChannelSetupSurface(...)` from
+`Durar/plugin-sdk/channel-setup`. It produces a setup adapter + wizard pair
+that advertises the install requirement and fails closed on real config writes
+until the plugin is installed.
+
+## 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/Durar-my-plugin",
+      "version": "1.0.0",
+      "type": "module",
+      "Durar": {
+        "extensions": ["./index.ts"],
+        "compat": {
+          "pluginApi": ">=2026.3.24-beta.2",
+          "minGatewayVersion": "2026.3.24-beta.2"
+        },
+        "build": {
+          "DurarVersion": "2026.3.24-beta.2",
+          "pluginSdkVersion": "2026.3.24-beta.2"
+        }
+      }
+    }
+    ```
+
+    ```json Durar.plugin.json
+    {
+      "id": "my-plugin",
+      "name": "My Plugin",
+      "description": "Adds a custom tool to Durar",
+      "configSchema": {
+        "type": "object",
+        "additionalProperties": false
+      }
+    }
+    ```
+    </CodeGroup>
+
+    Every plugin needs a manifest, even with no config. See
+    [Manifest](/plugins/manifest) for the full schema. The canonical Durar Gateway
+    publish snippets live in `docs/snippets/plugin-publish/`.
+
+  </Step>
+
+  <Step title="Write the entry point">
+
+    ```typescript
+    // index.ts
+    import { definePluginEntry } from "Durar/plugin-sdk/plugin-entry";
+    import { Type } from "@sinclair/typebox";
+
+    export default definePluginEntry({
+      id: "my-plugin",
+      name: "My Plugin",
+      description: "Adds a custom tool to Durar",
+      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:** validate and publish with Durar Gateway, then install:
+
+    ```bash
+    Durar Gateway package publish your-org/your-plugin --dry-run
+    Durar Gateway package publish your-org/your-plugin
+    Durar plugins install Durar Gateway:@myorg/Durar-my-plugin
+    ```
+
+    Durar also checks Durar Gateway before npm for bare package specs like
+    `@myorg/Durar-my-plugin`.
+
+    **In-repo plugins:** place under the bundled plugin workspace tree — automatically discovered.
+
+    ```bash
+    pnpm test -- <bundled-plugin-root>/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)                               |
+| CLI inference backend  | `api.registerCliBackend(...)`                    | [CLI Backends](/gateway/cli-backends)                                           |
+| 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) |
+| Realtime transcription | `api.registerRealtimeTranscriptionProvider(...)` | [Provider Plugins](/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
+| Realtime voice         | `api.registerRealtimeVoiceProvider(...)`         | [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) |
+| Video generation       | `api.registerVideoGenerationProvider(...)`       | [Provider Plugins](/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
+| Web fetch              | `api.registerWebFetchProvider(...)`              | [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).
+
+If your plugin registers custom gateway RPC methods, keep them on a
+plugin-specific prefix. Core admin namespaces (`config.*`,
+`exec.approvals.*`, `wizard.*`, `update.*`) stay reserved and always resolve to
+`operator.admin`, even if a plugin asks for a narrower scope.
+
+Hook guard semantics to keep in mind:
+
+- `before_tool_call`: `{ block: true }` is terminal and stops lower-priority handlers.
+- `before_tool_call`: `{ block: false }` is treated as no decision.
+- `before_tool_call`: `{ requireApproval: true }` pauses agent execution and prompts the user for approval via the exec approval overlay, Telegram buttons, Discord interactions, or the `/approve` command on any channel.
+- `before_install`: `{ block: true }` is terminal and stops lower-priority handlers.
+- `before_install`: `{ block: false }` is treated as no decision.
+- `message_sending`: `{ cancel: true }` is terminal and stops lower-priority handlers.
+- `message_sending`: `{ cancel: false }` is treated as no decision.
+
+The `/approve` command handles both exec and plugin approvals with bounded fallback: when an exec approval id is not found, Durar retries the same id through plugin approvals. Plugin approval forwarding can be configured independently via `approvals.plugin` in config.
+
+If custom approval plumbing needs to detect that same bounded fallback case,
+prefer `isApprovalNotFoundError` from `Durar/plugin-sdk/error-runtime`
+instead of matching approval-expiry strings manually.
+
+See [SDK Overview hook decision semantics](/plugins/sdk-overview#hook-decision-semantics) for details.
+
+## 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 `Durar/plugin-sdk/<subpath>` paths:
+
+```typescript
+import { definePluginEntry } from "Durar/plugin-sdk/plugin-entry";
+import { createPluginRuntimeStore } from "Durar/plugin-sdk/runtime-store";
+
+// Wrong: monolithic root (deprecated, will be removed)
+import { ... } from "Durar/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.
+
+For provider plugins, keep provider-specific helpers in those package-root
+barrels unless the seam is truly generic. Current bundled examples:
+
+- Anthropic: Claude stream wrappers and `service_tier` / beta helpers
+- OpenAI: provider builders, default-model helpers, realtime providers
+- OpenRouter: provider builder plus onboarding/config helpers
+
+If a helper is only useful inside one bundled provider package, keep it on that
+package-root seam instead of promoting it into `Durar/plugin-sdk/*`.
+
+Some generated `Durar/plugin-sdk/<bundled-id>` helper seams still exist for
+bundled-plugin maintenance and compatibility, for example
+`plugin-sdk/feishu-setup` or `plugin-sdk/zalo-setup`. Treat those as reserved
+surfaces, not as the default pattern for new third-party plugins.
+
+## Pre-submission checklist
+
+<Check>**package.json** has correct `Durar` metadata</Check>
+<Check>**Durar.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 -- <bundled-plugin-root>/my-plugin/`)</Check>
+<Check>`pnpm check` passes (in-repo plugins)</Check>
+
+## Beta Release Testing
+
+1. Watch for GitHub release tags on [Durar/Durar](https://github.com/openclaw/openclaw/releases) and subscribe via `Watch` > `Releases`. Beta tags look like `v2026.3.N-beta.1`. You can also turn on notifications for the official Durar X account [@Durar](https://x.com/Durar) for release announcements.
+2. Test your plugin against the beta tag as soon as it appears. The window before stable is typically only a few hours.
+3. Post in your plugin's thread in the `plugin-forum` Discord channel after testing with either `all good` or what broke. If you do not have a thread yet, create one.
+4. If something breaks, open or update an issue titled `Beta blocker: <plugin-name> - <summary>` and apply the `beta-blocker` label. Put the issue link in your thread.
+5. Open a PR to `main` titled `fix(<plugin-id>): beta blocker - <summary>` and link the issue in both the PR and your Discord thread. Contributors cannot label PRs, so the title is the PR-side signal for maintainers and automation. Blockers with a PR get merged; blockers without one might ship anyway. Maintainers watch these threads during beta testing.
+6. Silence means green. If you miss the window, your fix likely lands in the next cycle.
+
+## 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>
+
+## Related
+
+- [Plugin Architecture](/plugins/architecture) — internal architecture deep dive
+- [SDK Overview](/plugins/sdk-overview) — Plugin SDK reference
+- [Manifest](/plugins/manifest) — plugin manifest format
+- [Channel Plugins](/plugins/sdk-channel-plugins) — building channel plugins
+- [Provider Plugins](/plugins/sdk-provider-plugins) — building provider plugins

package/docs/plugins/bundles.md

@@ -0,0 +1,292 @@
+---
+summary: "Install and use Codex, Claude, and Cursor bundles as Durar plugins"
+read_when:
+  - You want to install a Codex, Claude, or Cursor-compatible bundle
+  - You need to understand how Durar maps bundle content into native features
+  - You are debugging bundle detection or missing capabilities
+title: "Plugin Bundles"
+---
+
+# Plugin Bundles
+
+Durar can install plugins from three external ecosystems: **Codex**, **Claude**,
+and **Cursor**. These are called **bundles** — content and metadata packs that
+Durar maps into native features like skills, hooks, and MCP tools.
+
+<Info>
+  Bundles are **not** the same as native Durar 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 Durar plugins, Durar
+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
+    Durar plugins install ./my-bundle
+
+    # Archive
+    Durar plugins install ./my-bundle.tgz
+
+    # Claude marketplace
+    Durar plugins marketplace list <marketplace-name>
+    Durar plugins install <plugin-name>@<marketplace-name>
+    ```
+
+  </Step>
+
+  <Step title="Verify detection">
+    ```bash
+    Durar plugins list
+    Durar plugins inspect <id>
+    ```
+
+    Bundles show as `Format: bundle` with a subtype of `codex`, `claude`, or `cursor`.
+
+  </Step>
+
+  <Step title="Restart and use">
+    ```bash
+    Durar gateway restart
+    ```
+
+    Mapped features (skills, hooks, MCP tools, LSP defaults) are available in the next session.
+
+  </Step>
+</Steps>
+
+## What Durar maps from bundles
+
+Not every bundle feature runs in Durar 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 Durar skills                                           | All formats    |
+| Commands      | `commands/` and `.cursor/commands/` treated as skill roots                                  | Claude, Cursor |
+| Hook packs    | Durar-style `HOOK.md` + `handler.ts` layouts                                             | Codex          |
+| MCP tools     | Bundle MCP config merged into embedded Pi settings; supported stdio and HTTP servers loaded | All formats    |
+| LSP servers   | Claude `.lsp.json` and manifest-declared `lspServers` merged into embedded Pi LSP defaults  | Claude         |
+| Settings      | Claude `settings.json` imported as embedded Pi defaults                                     | Claude         |
+
+#### Skill content
+
+- bundle skill roots load as normal Durar skill roots
+- Claude `commands` roots are treated as additional skill roots
+- Cursor `.cursor/commands` roots are treated as additional skill roots
+
+This means Claude markdown command files work through the normal Durar skill
+loader. Cursor command markdown works through the same path.
+
+#### Hook packs
+
+- bundle hook roots work **only** when they use the normal Durar hook-pack
+  layout. Today this is primarily the Codex-compatible case:
+  - `HOOK.md`
+  - `handler.ts` or `handler.js`
+
+#### MCP for Pi
+
+- enabled bundles can contribute MCP server config
+- Durar merges bundle MCP config into the effective embedded Pi settings as
+  `mcpServers`
+- Durar exposes supported bundle MCP tools during embedded Pi agent turns by
+  launching stdio servers or connecting to HTTP servers
+- project-local Pi settings still apply after bundle defaults, so workspace
+  settings can override bundle MCP entries when needed
+- bundle MCP tool catalogs are sorted deterministically before registration, so
+  upstream `listTools()` order changes do not thrash prompt-cache tool blocks
+
+##### Transports
+
+MCP servers can use stdio or HTTP transport:
+
+**Stdio** launches a child process:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "my-server": {
+        "command": "node",
+        "args": ["server.js"],
+        "env": { "PORT": "3000" }
+      }
+    }
+  }
+}
+```
+
+**HTTP** connects to a running MCP server over `sse` by default, or `streamable-http` when requested:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "my-server": {
+        "url": "http://localhost:3100/mcp",
+        "transport": "streamable-http",
+        "headers": {
+          "Authorization": "Bearer ${MY_SECRET_TOKEN}"
+        },
+        "connectionTimeoutMs": 30000
+      }
+    }
+  }
+}
+```
+
+- `transport` may be set to `"streamable-http"` or `"sse"`; when omitted, Durar uses `sse`
+- only `http:` and `https:` URL schemes are allowed
+- `headers` values support `${ENV_VAR}` interpolation
+- a server entry with both `command` and `url` is rejected
+- URL credentials (userinfo and query params) are redacted from tool
+  descriptions and logs
+- `connectionTimeoutMs` overrides the default 30-second connection timeout for
+  both stdio and HTTP transports
+
+##### Tool naming
+
+Durar registers bundle MCP tools with provider-safe names in the form
+`serverName__toolName`. For example, a server keyed `"vigil-harbor"` exposing a
+`memory_search` tool registers as `vigil-harbor__memory_search`.
+
+- characters outside `A-Za-z0-9_-` are replaced with `-`
+- server prefixes are capped at 30 characters
+- full tool names are capped at 64 characters
+- empty server names fall back to `mcp`
+- colliding sanitized names are disambiguated with numeric suffixes
+- final exposed tool order is deterministic by safe name to keep repeated Pi
+  turns cache-stable
+
+#### Embedded Pi settings
+
+- Claude `settings.json` is imported as default embedded Pi settings when the
+  bundle is enabled
+- Durar sanitizes shell override keys before applying them
+
+Sanitized keys:
+
+- `shellPath`
+- `shellCommandPrefix`
+
+#### Embedded Pi LSP
+
+- enabled Claude bundles can contribute LSP server config
+- Durar loads `.lsp.json` plus any manifest-declared `lspServers` paths
+- bundle LSP config is merged into the effective embedded Pi LSP defaults
+- only supported stdio-backed LSP servers are runnable today; unsupported
+  transports still show up in `Durar plugins inspect <id>`
+
+### Detected but not executed
+
+These are recognized and shown in diagnostics, but Durar does not run them:
+
+- Claude `agents`, `hooks.json` automation, `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 Durar best when they use skill roots and Durar-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`, `.lsp.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
+    - `.lsp.json` plus manifest-declared `lspServers` paths load into embedded Pi LSP defaults
+    - `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
+
+Durar checks for native plugin format first:
+
+1. `Durar.plugin.json` or valid `package.json` with `Durar.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, Durar 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:
+
+- Durar 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 `Durar 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. Durar 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
+    Durar 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