durar-ai 2026.4.4

package/docs/tools/creating-skills.md

@@ -0,0 +1,119 @@
+---
+title: "Creating Skills"
+summary: "Build and test custom workspace skills with SKILL.md"
+read_when:
+  - You are creating a new custom skill in your workspace
+  - You need a quick starter workflow for SKILL.md-based skills
+---
+
+# Creating Skills
+
+Skills teach the agent how and when to use tools. Each skill is a directory
+containing a `SKILL.md` file with YAML frontmatter and markdown instructions.
+
+For how skills are loaded and prioritized, see [Skills](/tools/skills).
+
+## Create your first skill
+
+<Steps>
+  <Step title="Create the skill directory">
+    Skills live in your workspace. Create a new folder:
+
+    ```bash
+    mkdir -p ~/.Durar/workspace/skills/hello-world
+    ```
+
+  </Step>
+
+  <Step title="Write SKILL.md">
+    Create `SKILL.md` inside that directory. The frontmatter defines metadata,
+    and the markdown body contains instructions for the agent.
+
+    ```markdown
+    ---
+    name: hello_world
+    description: A simple skill that says hello.
+    ---
+
+    # Hello World Skill
+
+    When the user asks for a greeting, use the `echo` tool to say
+    "Hello from your custom skill!".
+    ```
+
+  </Step>
+
+  <Step title="Add tools (optional)">
+    You can define custom tool schemas in the frontmatter or instruct the agent
+    to use existing system tools (like `exec` or `browser`). Skills can also
+    ship inside plugins alongside the tools they document.
+
+  </Step>
+
+  <Step title="Load the skill">
+    Start a new session so Durar picks up the skill:
+
+    ```bash
+    # From chat
+    /new
+
+    # Or restart the gateway
+    Durar gateway restart
+    ```
+
+    Verify the skill loaded:
+
+    ```bash
+    Durar skills list
+    ```
+
+  </Step>
+
+  <Step title="Test it">
+    Send a message that should trigger the skill:
+
+    ```bash
+    Durar agent --message "give me a greeting"
+    ```
+
+    Or just chat with the agent and ask for a greeting.
+
+  </Step>
+</Steps>
+
+## Skill metadata reference
+
+The YAML frontmatter supports these fields:
+
+| Field                               | Required | Description                                 |
+| ----------------------------------- | -------- | ------------------------------------------- |
+| `name`                              | Yes      | Unique identifier (snake_case)              |
+| `description`                       | Yes      | One-line description shown to the agent     |
+| `metadata.Durar.os`              | No       | OS filter (`["darwin"]`, `["linux"]`, etc.) |
+| `metadata.Durar.requires.bins`   | No       | Required binaries on PATH                   |
+| `metadata.Durar.requires.config` | No       | Required config keys                        |
+
+## Best practices
+
+- **Be concise** — instruct the model on _what_ to do, not how to be an AI
+- **Safety first** — if your skill uses `exec`, ensure prompts don't allow arbitrary command injection from untrusted input
+- **Test locally** — use `Durar agent --message "..."` to test before sharing
+- **Use Durar Gateway** — browse and contribute skills at [Durar Gateway](https://Durar Gateway.ai)
+
+## Where skills live
+
+| Location                        | Precedence | Scope                 |
+| ------------------------------- | ---------- | --------------------- |
+| `\<workspace\>/skills/`         | Highest    | Per-agent             |
+| `\<workspace\>/.agents/skills/` | High       | Per-workspace agent   |
+| `~/.agents/skills/`             | Medium     | Shared agent profile  |
+| `~/.Durar/skills/`           | Medium     | Shared (all agents)   |
+| Bundled (shipped with Durar) | Low        | Global                |
+| `skills.load.extraDirs`         | Lowest     | Custom shared folders |
+
+## Related
+
+- [Skills reference](/tools/skills) — loading, precedence, and gating rules
+- [Skills config](/tools/skills-config) — `skills.*` config schema
+- [Durar Gateway](/tools/Durar Gateway) — public skill registry
+- [Building Plugins](/plugins/building-plugins) — plugins can ship skills

package/docs/tools/diffs.md

@@ -0,0 +1,434 @@
+---
+title: "Diffs"
+summary: "Read-only diff viewer and file renderer for agents (optional plugin tool)"
+read_when:
+  - You want agents to show code or markdown edits as diffs
+  - You want a canvas-ready viewer URL or a rendered diff file
+  - You need controlled, temporary diff artifacts with secure defaults
+---
+
+# Diffs
+
+`diffs` is an optional plugin tool with short built-in system guidance and a companion skill that turns change content into a read-only diff artifact for agents.
+
+It accepts either:
+
+- `before` and `after` text
+- a unified `patch`
+
+It can return:
+
+- a gateway viewer URL for canvas presentation
+- a rendered file path (PNG or PDF) for message delivery
+- both outputs in one call
+
+When enabled, the plugin prepends concise usage guidance into system-prompt space and also exposes a detailed skill for cases where the agent needs fuller instructions.
+
+## Quick start
+
+1. Enable the plugin.
+2. Call `diffs` with `mode: "view"` for canvas-first flows.
+3. Call `diffs` with `mode: "file"` for chat file delivery flows.
+4. Call `diffs` with `mode: "both"` when you need both artifacts.
+
+## Enable the plugin
+
+```json5
+{
+  plugins: {
+    entries: {
+      diffs: {
+        enabled: true,
+      },
+    },
+  },
+}
+```
+
+## Disable built-in system guidance
+
+If you want to keep the `diffs` tool enabled but disable its built-in system-prompt guidance, set `plugins.entries.diffs.hooks.allowPromptInjection` to `false`:
+
+```json5
+{
+  plugins: {
+    entries: {
+      diffs: {
+        enabled: true,
+        hooks: {
+          allowPromptInjection: false,
+        },
+      },
+    },
+  },
+}
+```
+
+This blocks the diffs plugin's `before_prompt_build` hook while keeping the plugin, tool, and companion skill available.
+
+If you want to disable both the guidance and the tool, disable the plugin instead.
+
+## Typical agent workflow
+
+1. Agent calls `diffs`.
+2. Agent reads `details` fields.
+3. Agent either:
+   - opens `details.viewerUrl` with `canvas present`
+   - sends `details.filePath` with `message` using `path` or `filePath`
+   - does both
+
+## Input examples
+
+Before and after:
+
+```json
+{
+  "before": "# Hello\n\nOne",
+  "after": "# Hello\n\nTwo",
+  "path": "docs/example.md",
+  "mode": "view"
+}
+```
+
+Patch:
+
+```json
+{
+  "patch": "diff --git a/src/example.ts b/src/example.ts\n--- a/src/example.ts\n+++ b/src/example.ts\n@@ -1 +1 @@\n-const x = 1;\n+const x = 2;\n",
+  "mode": "both"
+}
+```
+
+## Tool input reference
+
+All fields are optional unless noted:
+
+- `before` (`string`): original text. Required with `after` when `patch` is omitted.
+- `after` (`string`): updated text. Required with `before` when `patch` is omitted.
+- `patch` (`string`): unified diff text. Mutually exclusive with `before` and `after`.
+- `path` (`string`): display filename for before and after mode.
+- `lang` (`string`): language override hint for before and after mode. Unknown values fall back to plain text.
+- `title` (`string`): viewer title override.
+- `mode` (`"view" | "file" | "both"`): output mode. Defaults to plugin default `defaults.mode`.
+  Deprecated alias: `"image"` behaves like `"file"` and is still accepted for backward compatibility.
+- `theme` (`"light" | "dark"`): viewer theme. Defaults to plugin default `defaults.theme`.
+- `layout` (`"unified" | "split"`): diff layout. Defaults to plugin default `defaults.layout`.
+- `expandUnchanged` (`boolean`): expand unchanged sections when full context is available. Per-call option only (not a plugin default key).
+- `fileFormat` (`"png" | "pdf"`): rendered file format. Defaults to plugin default `defaults.fileFormat`.
+- `fileQuality` (`"standard" | "hq" | "print"`): quality preset for PNG or PDF rendering.
+- `fileScale` (`number`): device scale override (`1`-`4`).
+- `fileMaxWidth` (`number`): max render width in CSS pixels (`640`-`2400`).
+- `ttlSeconds` (`number`): artifact TTL in seconds for viewer and standalone file outputs. Default 1800, max 21600.
+- `baseUrl` (`string`): viewer URL origin override. Overrides plugin `viewerBaseUrl`. Must be `http` or `https`, no query/hash.
+
+Legacy input aliases still accepted for backward compatibility:
+
+- `format` -> `fileFormat`
+- `imageFormat` -> `fileFormat`
+- `imageQuality` -> `fileQuality`
+- `imageScale` -> `fileScale`
+- `imageMaxWidth` -> `fileMaxWidth`
+
+Validation and limits:
+
+- `before` and `after` each max 512 KiB.
+- `patch` max 2 MiB.
+- `path` max 2048 bytes.
+- `lang` max 128 bytes.
+- `title` max 1024 bytes.
+- Patch complexity cap: max 128 files and 120000 total lines.
+- `patch` and `before` or `after` together are rejected.
+- Rendered file safety limits (apply to PNG and PDF):
+  - `fileQuality: "standard"`: max 8 MP (8,000,000 rendered pixels).
+  - `fileQuality: "hq"`: max 14 MP (14,000,000 rendered pixels).
+  - `fileQuality: "print"`: max 24 MP (24,000,000 rendered pixels).
+  - PDF also has a max of 50 pages.
+
+## Output details contract
+
+The tool returns structured metadata under `details`.
+
+Shared fields for modes that create a viewer:
+
+- `artifactId`
+- `viewerUrl`
+- `viewerPath`
+- `title`
+- `expiresAt`
+- `inputKind`
+- `fileCount`
+- `mode`
+- `context` (`agentId`, `sessionId`, `messageChannel`, `agentAccountId` when available)
+
+File fields when PNG or PDF is rendered:
+
+- `artifactId`
+- `expiresAt`
+- `filePath`
+- `path` (same value as `filePath`, for message tool compatibility)
+- `fileBytes`
+- `fileFormat`
+- `fileQuality`
+- `fileScale`
+- `fileMaxWidth`
+
+Compatibility aliases also returned for existing callers:
+
+- `format` (same value as `fileFormat`)
+- `imagePath` (same value as `filePath`)
+- `imageBytes` (same value as `fileBytes`)
+- `imageQuality` (same value as `fileQuality`)
+- `imageScale` (same value as `fileScale`)
+- `imageMaxWidth` (same value as `fileMaxWidth`)
+
+Mode behavior summary:
+
+- `mode: "view"`: viewer fields only.
+- `mode: "file"`: file fields only, no viewer artifact.
+- `mode: "both"`: viewer fields plus file fields. If file rendering fails, viewer still returns with `fileError` and compatibility alias `imageError`.
+
+## Collapsed unchanged sections
+
+- The viewer can show rows like `N unmodified lines`.
+- Expand controls on those rows are conditional and not guaranteed for every input kind.
+- Expand controls appear when the rendered diff has expandable context data, which is typical for before and after input.
+- For many unified patch inputs, omitted context bodies are not available in the parsed patch hunks, so the row can appear without expand controls. This is expected behavior.
+- `expandUnchanged` applies only when expandable context exists.
+
+## Plugin defaults
+
+Set plugin-wide defaults in `~/.Durar/Durar.json`:
+
+```json5
+{
+  plugins: {
+    entries: {
+      diffs: {
+        enabled: true,
+        config: {
+          defaults: {
+            fontFamily: "Fira Code",
+            fontSize: 15,
+            lineSpacing: 1.6,
+            layout: "unified",
+            showLineNumbers: true,
+            diffIndicators: "bars",
+            wordWrap: true,
+            background: true,
+            theme: "dark",
+            fileFormat: "png",
+            fileQuality: "standard",
+            fileScale: 2,
+            fileMaxWidth: 960,
+            mode: "both",
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+Supported defaults:
+
+- `fontFamily`
+- `fontSize`
+- `lineSpacing`
+- `layout`
+- `showLineNumbers`
+- `diffIndicators`
+- `wordWrap`
+- `background`
+- `theme`
+- `fileFormat`
+- `fileQuality`
+- `fileScale`
+- `fileMaxWidth`
+- `mode`
+
+Explicit tool parameters override these defaults.
+
+Persistent viewer URL config:
+
+- `viewerBaseUrl` (`string`, optional)
+  - Plugin-owned fallback for returned viewer links when a tool call does not pass `baseUrl`.
+  - Must be `http` or `https`, no query/hash.
+
+Example:
+
+```json5
+{
+  plugins: {
+    entries: {
+      diffs: {
+        enabled: true,
+        config: {
+          viewerBaseUrl: "https://gateway.example.com/Durar",
+        },
+      },
+    },
+  },
+}
+```
+
+## Security config
+
+- `security.allowRemoteViewer` (`boolean`, default `false`)
+  - `false`: non-loopback requests to viewer routes are denied.
+  - `true`: remote viewers are allowed if tokenized path is valid.
+
+Example:
+
+```json5
+{
+  plugins: {
+    entries: {
+      diffs: {
+        enabled: true,
+        config: {
+          security: {
+            allowRemoteViewer: false,
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+## Artifact lifecycle and storage
+
+- Artifacts are stored under the temp subfolder: `$TMPDIR/Durar-diffs`.
+- Viewer artifact metadata contains:
+  - random artifact ID (20 hex chars)
+  - random token (48 hex chars)
+  - `createdAt` and `expiresAt`
+  - stored `viewer.html` path
+- Default artifact TTL is 30 minutes when not specified.
+- Maximum accepted viewer TTL is 6 hours.
+- Cleanup runs opportunistically after artifact creation.
+- Expired artifacts are deleted.
+- Fallback cleanup removes stale folders older than 24 hours when metadata is missing.
+
+## Viewer URL and network behavior
+
+Viewer route:
+
+- `/plugins/diffs/view/{artifactId}/{token}`
+
+Viewer assets:
+
+- `/plugins/diffs/assets/viewer.js`
+- `/plugins/diffs/assets/viewer-runtime.js`
+
+The viewer document resolves those assets relative to the viewer URL, so an optional `baseUrl` path prefix is preserved for both asset requests too.
+
+URL construction behavior:
+
+- If tool-call `baseUrl` is provided, it is used after strict validation.
+- Else if plugin `viewerBaseUrl` is configured, it is used.
+- Without either override, viewer URL defaults to loopback `127.0.0.1`.
+- If gateway bind mode is `custom` and `gateway.customBindHost` is set, that host is used.
+
+`baseUrl` rules:
+
+- Must be `http://` or `https://`.
+- Query and hash are rejected.
+- Origin plus optional base path is allowed.
+
+## Security model
+
+Viewer hardening:
+
+- Loopback-only by default.
+- Tokenized viewer paths with strict ID and token validation.
+- Viewer response CSP:
+  - `default-src 'none'`
+  - scripts and assets only from self
+  - no outbound `connect-src`
+- Remote miss throttling when remote access is enabled:
+  - 40 failures per 60 seconds
+  - 60 second lockout (`429 Too Many Requests`)
+
+File rendering hardening:
+
+- Screenshot browser request routing is deny-by-default.
+- Only local viewer assets from `http://127.0.0.1/plugins/diffs/assets/*` are allowed.
+- External network requests are blocked.
+
+## Browser requirements for file mode
+
+`mode: "file"` and `mode: "both"` need a Chromium-compatible browser.
+
+Resolution order:
+
+1. `browser.executablePath` in Durar config.
+2. Environment variables:
+   - `Durar_BROWSER_EXECUTABLE_PATH`
+   - `BROWSER_EXECUTABLE_PATH`
+   - `PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH`
+3. Platform command/path discovery fallback.
+
+Common failure text:
+
+- `Diff PNG/PDF rendering requires a Chromium-compatible browser...`
+
+Fix by installing Chrome, Chromium, Edge, or Brave, or setting one of the executable path options above.
+
+## Troubleshooting
+
+Input validation errors:
+
+- `Provide patch or both before and after text.`
+  - Include both `before` and `after`, or provide `patch`.
+- `Provide either patch or before/after input, not both.`
+  - Do not mix input modes.
+- `Invalid baseUrl: ...`
+  - Use `http(s)` origin with optional path, no query/hash.
+- `{field} exceeds maximum size (...)`
+  - Reduce payload size.
+- Large patch rejection
+  - Reduce patch file count or total lines.
+
+Viewer accessibility issues:
+
+- Viewer URL resolves to `127.0.0.1` by default.
+- For remote access scenarios, either:
+  - set plugin `viewerBaseUrl`, or
+  - pass `baseUrl` per tool call, or
+  - use `gateway.bind=custom` and `gateway.customBindHost`
+- If `gateway.trustedProxies` includes loopback for a same-host proxy (for example Tailscale Serve), raw loopback viewer requests without forwarded client-IP headers fail closed by design.
+- For that proxy topology:
+  - prefer `mode: "file"` or `mode: "both"` when you only need an attachment, or
+  - intentionally enable `security.allowRemoteViewer` and set plugin `viewerBaseUrl` or pass a proxy/public `baseUrl` when you need a shareable viewer URL
+- Enable `security.allowRemoteViewer` only when you intend external viewer access.
+
+Unmodified-lines row has no expand button:
+
+- This can happen for patch input when the patch does not carry expandable context.
+- This is expected and does not indicate a viewer failure.
+
+Artifact not found:
+
+- Artifact expired due TTL.
+- Token or path changed.
+- Cleanup removed stale data.
+
+## Operational guidance
+
+- Prefer `mode: "view"` for local interactive reviews in canvas.
+- Prefer `mode: "file"` for outbound chat channels that need an attachment.
+- Keep `allowRemoteViewer` disabled unless your deployment requires remote viewer URLs.
+- Set explicit short `ttlSeconds` for sensitive diffs.
+- Avoid sending secrets in diff input when not required.
+- If your channel compresses images aggressively (for example Telegram or WhatsApp), prefer PDF output (`fileFormat: "pdf"`).
+
+Diff rendering engine:
+
+- Powered by [Diffs](https://diffs.com).
+
+## Related docs
+
+- [Tools overview](/tools)
+- [Plugins](/tools/plugin)
+- [Browser](/tools/browser)

package/docs/tools/duckduckgo-search.md

@@ -0,0 +1,102 @@
+---
+summary: "DuckDuckGo web search -- key-free fallback provider (experimental, HTML-based)"
+read_when:
+  - You want a web search provider that requires no API key
+  - You want to use DuckDuckGo for web_search
+  - You need a zero-config search fallback
+title: "DuckDuckGo Search"
+---
+
+# DuckDuckGo Search
+
+Durar supports DuckDuckGo as a **key-free** `web_search` provider. No API
+key or account is required.
+
+<Warning>
+  DuckDuckGo is an **experimental, unofficial** integration that pulls results
+  from DuckDuckGo's non-JavaScript search pages — not an official API. Expect
+  occasional breakage from bot-challenge pages or HTML changes.
+</Warning>
+
+## Setup
+
+No API key needed — just set DuckDuckGo as your provider:
+
+<Steps>
+  <Step title="Configure">
+    ```bash
+    Durar configure --section web
+    # Select "duckduckgo" as the provider
+    ```
+  </Step>
+</Steps>
+
+## Config
+
+```json5
+{
+  tools: {
+    web: {
+      search: {
+        provider: "duckduckgo",
+      },
+    },
+  },
+}
+```
+
+Optional plugin-level settings for region and SafeSearch:
+
+```json5
+{
+  plugins: {
+    entries: {
+      duckduckgo: {
+        config: {
+          webSearch: {
+            region: "us-en", // DuckDuckGo region code
+            safeSearch: "moderate", // "strict", "moderate", or "off"
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+## Tool parameters
+
+| Parameter    | Description                                                |
+| ------------ | ---------------------------------------------------------- |
+| `query`      | Search query (required)                                    |
+| `count`      | Results to return (1-10, default: 5)                       |
+| `region`     | DuckDuckGo region code (e.g. `us-en`, `uk-en`, `de-de`)    |
+| `safeSearch` | SafeSearch level: `strict`, `moderate` (default), or `off` |
+
+Region and SafeSearch can also be set in plugin config (see above) — tool
+parameters override config values per-query.
+
+## Notes
+
+- **No API key** — works out of the box, zero configuration
+- **Experimental** — gathers results from DuckDuckGo's non-JavaScript HTML
+  search pages, not an official API or SDK
+- **Bot-challenge risk** — DuckDuckGo may serve CAPTCHAs or block requests
+  under heavy or automated use
+- **HTML parsing** — results depend on page structure, which can change without
+  notice
+- **Auto-detection order** — DuckDuckGo is the first key-free fallback
+  (order 100) in auto-detection. API-backed providers with configured keys run
+  first, then Ollama Web Search (order 110), then SearXNG (order 200)
+- **SafeSearch defaults to moderate** when not configured
+
+<Tip>
+  For production use, consider [Brave Search](/tools/brave-search) (free tier
+  available) or another API-backed provider.
+</Tip>
+
+## Related
+
+- [Web Search overview](/tools/web) -- all providers and auto-detection
+- [Brave Search](/tools/brave-search) -- structured results with free tier
+- [Exa Search](/tools/exa-search) -- neural search with content extraction