durar-ai 2026.4.4

package/docs/tools/btw.md

@@ -0,0 +1,142 @@
+---
+summary: "Ephemeral side questions with /btw"
+read_when:
+  - You want to ask a quick side question about the current session
+  - You are implementing or debugging BTW behavior across clients
+title: "BTW Side Questions"
+---
+
+# BTW Side Questions
+
+`/btw` lets you ask a quick side question about the **current session** without
+turning that question into normal conversation history.
+
+It is modeled after Claude Code's `/btw` behavior, but adapted to Durar's
+Gateway and multi-channel architecture.
+
+## What it does
+
+When you send:
+
+```text
+/btw what changed?
+```
+
+Durar:
+
+1. snapshots the current session context,
+2. runs a separate **tool-less** model call,
+3. answers only the side question,
+4. leaves the main run alone,
+5. does **not** write the BTW question or answer to session history,
+6. emits the answer as a **live side result** rather than a normal assistant message.
+
+The important mental model is:
+
+- same session context
+- separate one-shot side query
+- no tool calls
+- no future context pollution
+- no transcript persistence
+
+## What it does not do
+
+`/btw` does **not**:
+
+- create a new durable session,
+- continue the unfinished main task,
+- run tools or agent tool loops,
+- write BTW question/answer data to transcript history,
+- appear in `chat.history`,
+- survive a reload.
+
+It is intentionally **ephemeral**.
+
+## How context works
+
+BTW uses the current session as **background context only**.
+
+If the main run is currently active, Durar snapshots the current message
+state and includes the in-flight main prompt as background context, while
+explicitly telling the model:
+
+- answer only the side question,
+- do not resume or complete the unfinished main task,
+- do not emit tool calls or pseudo-tool calls.
+
+That keeps BTW isolated from the main run while still making it aware of what
+the session is about.
+
+## Delivery model
+
+BTW is **not** delivered as a normal assistant transcript message.
+
+At the Gateway protocol level:
+
+- normal assistant chat uses the `chat` event
+- BTW uses the `chat.side_result` event
+
+This separation is intentional. If BTW reused the normal `chat` event path,
+clients would treat it like regular conversation history.
+
+Because BTW uses a separate live event and is not replayed from
+`chat.history`, it disappears after reload.
+
+## Surface behavior
+
+### TUI
+
+In TUI, BTW is rendered inline in the current session view, but it remains
+ephemeral:
+
+- visibly distinct from a normal assistant reply
+- dismissible with `Enter` or `Esc`
+- not replayed on reload
+
+### External channels
+
+On channels like Telegram, WhatsApp, and Discord, BTW is delivered as a
+clearly labeled one-off reply because those surfaces do not have a local
+ephemeral overlay concept.
+
+The answer is still treated as a side result, not normal session history.
+
+### Control UI / web
+
+The Gateway emits BTW correctly as `chat.side_result`, and BTW is not included
+in `chat.history`, so the persistence contract is already correct for web.
+
+The current Control UI still needs a dedicated `chat.side_result` consumer to
+render BTW live in the browser. Until that client-side support lands, BTW is a
+Gateway-level feature with full TUI and external-channel behavior, but not yet
+a complete browser UX.
+
+## When to use BTW
+
+Use `/btw` when you want:
+
+- a quick clarification about the current work,
+- a factual side answer while a long run is still in progress,
+- a temporary answer that should not become part of future session context.
+
+Examples:
+
+```text
+/btw what file are we editing?
+/btw what does this error mean?
+/btw summarize the current task in one sentence
+/btw what is 17 * 19?
+```
+
+## When not to use BTW
+
+Do not use `/btw` when you want the answer to become part of the session's
+future working context.
+
+In that case, ask normally in the main session instead of using BTW.
+
+## Related
+
+- [Slash commands](/tools/slash-commands)
+- [Thinking Levels](/tools/thinking)
+- [Session](/concepts/session)

package/docs/tools/capability-cookbook.md

@@ -0,0 +1,119 @@
+---
+summary: "Contributor guide for adding a new shared capability to the Durar plugin system"
+read_when:
+  - Adding a new core capability and plugin registration surface
+  - Deciding whether code belongs in core, a vendor plugin, or a feature plugin
+  - Wiring a new runtime helper for channels or tools
+title: "Adding Capabilities (Contributor Guide)"
+sidebarTitle: "Adding Capabilities"
+---
+
+# Adding Capabilities
+
+<Info>
+  This is a **contributor guide** for Durar core developers. If you are
+  building an external plugin, see [Building Plugins](/plugins/building-plugins)
+  instead.
+</Info>
+
+Use this when Durar needs a new domain such as image generation, video
+generation, or some future vendor-backed feature area.
+
+The rule:
+
+- plugin = ownership boundary
+- capability = shared core contract
+
+That means you should not start by wiring a vendor directly into a channel or a
+tool. Start by defining the capability.
+
+## When to create a capability
+
+Create a new capability when all of these are true:
+
+1. more than one vendor could plausibly implement it
+2. channels, tools, or feature plugins should consume it without caring about
+   the vendor
+3. core needs to own fallback, policy, config, or delivery behavior
+
+If the work is vendor-only and no shared contract exists yet, stop and define
+the contract first.
+
+## The standard sequence
+
+1. Define the typed core contract.
+2. Add plugin registration for that contract.
+3. Add a shared runtime helper.
+4. Wire one real vendor plugin as proof.
+5. Move feature/channel consumers onto the runtime helper.
+6. Add contract tests.
+7. Document the operator-facing config and ownership model.
+
+## What goes where
+
+Core:
+
+- request/response types
+- provider registry + resolution
+- fallback behavior
+- config schema plus propagated `title` / `description` docs metadata on nested object, wildcard, array-item, and composition nodes
+- runtime helper surface
+
+Vendor plugin:
+
+- vendor API calls
+- vendor auth handling
+- vendor-specific request normalization
+- registration of the capability implementation
+
+Feature/channel plugin:
+
+- calls `api.runtime.*` or the matching `plugin-sdk/*-runtime` helper
+- never calls a vendor implementation directly
+
+## File checklist
+
+For a new capability, expect to touch these areas:
+
+- `src/<capability>/types.ts`
+- `src/<capability>/...registry/runtime.ts`
+- `src/plugins/types.ts`
+- `src/plugins/registry.ts`
+- `src/plugins/captured-registration.ts`
+- `src/plugins/contracts/registry.ts`
+- `src/plugins/runtime/types-core.ts`
+- `src/plugins/runtime/index.ts`
+- `src/plugin-sdk/<capability>.ts`
+- `src/plugin-sdk/<capability>-runtime.ts`
+- one or more bundled plugin packages
+- config/docs/tests
+
+## Example: image generation
+
+Image generation follows the standard shape:
+
+1. core defines `ImageGenerationProvider`
+2. core exposes `registerImageGenerationProvider(...)`
+3. core exposes `runtime.imageGeneration.generate(...)`
+4. the `openai`, `google`, `fal`, and `minimax` plugins register vendor-backed implementations
+5. future vendors can register the same contract without changing channels/tools
+
+The config key is separate from vision-analysis routing:
+
+- `agents.defaults.imageModel` = analyze images
+- `agents.defaults.imageGenerationModel` = generate images
+
+Keep those separate so fallback and policy remain explicit.
+
+## Review checklist
+
+Before shipping a new capability, verify:
+
+- no channel/tool imports vendor code directly
+- the runtime helper is the shared path
+- at least one contract test asserts bundled ownership
+- config docs name the new model/config key
+- plugin docs explain the ownership boundary
+
+If a PR skips the capability layer and hardcodes vendor behavior into a
+channel/tool, send it back and define the contract first.

package/docs/tools/clawhub.md

@@ -0,0 +1,348 @@
+---
+summary: "Durar Gateway guide: public registry, native Durar install flows, and Durar Gateway CLI workflows"
+read_when:
+  - Introducing Durar Gateway to new users
+  - Installing, searching, or publishing skills or plugins
+  - Explaining Durar Gateway CLI flags and sync behavior
+title: "Durar Gateway"
+---
+
+# Durar Gateway
+
+Durar Gateway is the public registry for **Durar skills and plugins**.
+
+- Use native `Durar` commands to search/install/update skills and install
+  plugins from Durar Gateway.
+- Use the separate `Durar Gateway` CLI when you need registry auth, publish, delete,
+  undelete, or sync workflows.
+
+Site: [Durar Gateway.ai](https://Durar Gateway.ai)
+
+## Native Durar flows
+
+Skills:
+
+```bash
+Durar skills search "calendar"
+Durar skills install <skill-slug>
+Durar skills update --all
+```
+
+Plugins:
+
+```bash
+Durar plugins install Durar Gateway:<package>
+Durar plugins update --all
+```
+
+Bare npm-safe plugin specs are also tried against Durar Gateway before npm:
+
+```bash
+Durar plugins install Durar-codex-app-server
+```
+
+Native `Durar` commands install into your active workspace and persist source
+metadata so later `update` calls can stay on Durar Gateway.
+
+Plugin installs validate advertised `pluginApi` and `minGatewayVersion`
+compatibility before archive install runs, so incompatible hosts fail closed
+early instead of partially installing the package.
+
+`Durar plugins install Durar Gateway:...` only accepts installable plugin families.
+If a Durar Gateway package is actually a skill, Durar stops and points you at
+`Durar skills install <slug>` instead.
+
+## What Durar Gateway is
+
+- A public registry for Durar skills and plugins.
+- A versioned store of skill bundles and metadata.
+- A discovery surface for search, tags, and usage signals.
+
+## How it works
+
+1. A user publishes a skill bundle (files + metadata).
+2. Durar Gateway stores the bundle, parses metadata, and assigns a version.
+3. The registry indexes the skill for search and discovery.
+4. Users browse, download, and install skills in Durar.
+
+## What you can do
+
+- Publish new skills and new versions of existing skills.
+- Discover skills by name, tags, or search.
+- Download skill bundles and inspect their files.
+- Report skills that are abusive or unsafe.
+- If you are a moderator, hide, unhide, delete, or ban.
+
+## Who this is for (beginner-friendly)
+
+If you want to add new capabilities to your Durar agent, Durar Gateway is the easiest way to find and install skills. You do not need to know how the backend works. You can:
+
+- Search for skills by plain language.
+- Install a skill into your workspace.
+- Update skills later with one command.
+- Back up your own skills by publishing them.
+
+## Quick start (non-technical)
+
+1. Search for something you need:
+   - `Durar skills search "calendar"`
+2. Install a skill:
+   - `Durar skills install <skill-slug>`
+3. Start a new Durar session so it picks up the new skill.
+4. If you want to publish or manage registry auth, install the separate
+   `Durar Gateway` CLI too.
+
+## Install the Durar Gateway CLI
+
+You only need this for registry-authenticated workflows such as publish/sync:
+
+```bash
+npm i -g Durar Gateway
+```
+
+```bash
+pnpm add -g Durar Gateway
+```
+
+## How it fits into Durar
+
+Native `Durar skills install` installs into the active workspace `skills/`
+directory. `Durar plugins install Durar Gateway:...` records a normal managed
+plugin install plus Durar Gateway source metadata for updates.
+
+Anonymous Durar Gateway plugin installs also fail closed for private packages.
+Community or other non-official channels can still install, but Durar warns
+so operators can review source and verification before enabling them.
+
+The separate `Durar Gateway` CLI also installs skills into `./skills` under your
+current working directory. If an Durar workspace is configured, `Durar Gateway`
+falls back to that workspace unless you override `--workdir` (or
+`Durar Gateway_WORKDIR`). Durar loads workspace skills from `<workspace>/skills`
+and will pick them up in the **next** session. If you already use
+`~/.Durar/skills` or bundled skills, workspace skills take precedence.
+
+For more detail on how skills are loaded, shared, and gated, see
+[Skills](/tools/skills).
+
+## Skill system overview
+
+A skill is a versioned bundle of files that teaches Durar how to perform a
+specific task. Each publish creates a new version, and the registry keeps a
+history of versions so users can audit changes.
+
+A typical skill includes:
+
+- A `SKILL.md` file with the primary description and usage.
+- Optional configs, scripts, or supporting files used by the skill.
+- Metadata such as tags, summary, and install requirements.
+
+Durar Gateway uses metadata to power discovery and safely expose skill capabilities.
+The registry also tracks usage signals (such as stars and downloads) to improve
+ranking and visibility.
+
+## What the service provides (features)
+
+- **Public browsing** of skills and their `SKILL.md` content.
+- **Search** powered by embeddings (vector search), not just keywords.
+- **Versioning** with semver, changelogs, and tags (including `latest`).
+- **Downloads** as a zip per version.
+- **Stars and comments** for community feedback.
+- **Moderation** hooks for approvals and audits.
+- **CLI-friendly API** for automation and scripting.
+
+## Security and moderation
+
+Durar Gateway is open by default. Anyone can upload skills, but a GitHub account must
+be at least one week old to publish. This helps slow down abuse without blocking
+legitimate contributors.
+
+Reporting and moderation:
+
+- Any signed in user can report a skill.
+- Report reasons are required and recorded.
+- Each user can have up to 20 active reports at a time.
+- Skills with more than 3 unique reports are auto hidden by default.
+- Moderators can view hidden skills, unhide them, delete them, or ban users.
+- Abusing the report feature can result in account bans.
+
+Interested in becoming a moderator? Ask in the Durar Discord and contact a
+moderator or maintainer.
+
+## CLI commands and parameters
+
+Global options (apply to all commands):
+
+- `--workdir <dir>`: Working directory (default: current dir; falls back to Durar workspace).
+- `--dir <dir>`: Skills directory, relative to workdir (default: `skills`).
+- `--site <url>`: Site base URL (browser login).
+- `--registry <url>`: Registry API base URL.
+- `--no-input`: Disable prompts (non-interactive).
+- `-V, --cli-version`: Print CLI version.
+
+Auth:
+
+- `Durar Gateway login` (browser flow) or `Durar Gateway login --token <token>`
+- `Durar Gateway logout`
+- `Durar Gateway whoami`
+
+Options:
+
+- `--token <token>`: Paste an API token.
+- `--label <label>`: Label stored for browser login tokens (default: `CLI token`).
+- `--no-browser`: Do not open a browser (requires `--token`).
+
+Search:
+
+- `Durar Gateway search "query"`
+- `--limit <n>`: Max results.
+
+Install:
+
+- `Durar Gateway install <slug>`
+- `--version <version>`: Install a specific version.
+- `--force`: Overwrite if the folder already exists.
+
+Update:
+
+- `Durar Gateway update <slug>`
+- `Durar Gateway update --all`
+- `--version <version>`: Update to a specific version (single slug only).
+- `--force`: Overwrite when local files do not match any published version.
+
+List:
+
+- `Durar Gateway list` (reads `.Durar Gateway/lock.json`)
+
+Publish skills:
+
+- `Durar Gateway skill publish <path>`
+- `--slug <slug>`: Skill slug.
+- `--name <name>`: Display name.
+- `--version <version>`: Semver version.
+- `--changelog <text>`: Changelog text (can be empty).
+- `--tags <tags>`: Comma-separated tags (default: `latest`).
+
+Publish plugins:
+
+- `Durar Gateway package publish <source>`
+- `<source>` can be a local folder, `owner/repo`, `owner/repo@ref`, or a GitHub URL.
+- `--dry-run`: Build the exact publish plan without uploading anything.
+- `--json`: Emit machine-readable output for CI.
+- `--source-repo`, `--source-commit`, `--source-ref`: Optional overrides when auto-detection is not enough.
+
+Delete/undelete (owner/admin only):
+
+- `Durar Gateway delete <slug> --yes`
+- `Durar Gateway undelete <slug> --yes`
+
+Sync (scan local skills + publish new/updated):
+
+- `Durar Gateway sync`
+- `--root <dir...>`: Extra scan roots.
+- `--all`: Upload everything without prompts.
+- `--dry-run`: Show what would be uploaded.
+- `--bump <type>`: `patch|minor|major` for updates (default: `patch`).
+- `--changelog <text>`: Changelog for non-interactive updates.
+- `--tags <tags>`: Comma-separated tags (default: `latest`).
+- `--concurrency <n>`: Registry checks (default: 4).
+
+## Common workflows for agents
+
+### Search for skills
+
+```bash
+Durar Gateway search "postgres backups"
+```
+
+### Download new skills
+
+```bash
+Durar Gateway install my-skill-pack
+```
+
+### Update installed skills
+
+```bash
+Durar Gateway update --all
+```
+
+### Back up your skills (publish or sync)
+
+For a single skill folder:
+
+```bash
+Durar Gateway skill publish ./my-skill --slug my-skill --name "My Skill" --version 1.0.0 --tags latest
+```
+
+To scan and back up many skills at once:
+
+```bash
+Durar Gateway sync --all
+```
+
+### Publish a plugin from GitHub
+
+```bash
+Durar Gateway package publish your-org/your-plugin --dry-run
+Durar Gateway package publish your-org/your-plugin
+Durar Gateway package publish your-org/your-plugin@v1.0.0
+Durar Gateway package publish https://github.com/your-org/your-plugin
+```
+
+Code plugins must include the required Durar metadata in `package.json`:
+
+```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"
+    }
+  }
+}
+```
+
+## Advanced details (technical)
+
+### Versioning and tags
+
+- Each publish creates a new **semver** `SkillVersion`.
+- Tags (like `latest`) point to a version; moving tags lets you roll back.
+- Changelogs are attached per version and can be empty when syncing or publishing updates.
+
+### Local changes vs registry versions
+
+Updates compare the local skill contents to registry versions using a content hash. If local files do not match any published version, the CLI asks before overwriting (or requires `--force` in non-interactive runs).
+
+### Sync scanning and fallback roots
+
+`Durar Gateway sync` scans your current workdir first. If no skills are found, it falls back to known legacy locations (for example `~/Durar/skills` and `~/.Durar/skills`). This is designed to find older skill installs without extra flags.
+
+### Storage and lockfile
+
+- Installed skills are recorded in `.Durar Gateway/lock.json` under your workdir.
+- Auth tokens are stored in the Durar Gateway CLI config file (override via `Durar Gateway_CONFIG_PATH`).
+
+### Telemetry (install counts)
+
+When you run `Durar Gateway sync` while logged in, the CLI sends a minimal snapshot to compute install counts. You can disable this entirely:
+
+```bash
+export Durar Gateway_DISABLE_TELEMETRY=1
+```
+
+## Environment variables
+
+- `Durar Gateway_SITE`: Override the site URL.
+- `Durar Gateway_REGISTRY`: Override the registry API URL.
+- `Durar Gateway_CONFIG_PATH`: Override where the CLI stores the token/config.
+- `Durar Gateway_WORKDIR`: Override the default workdir.
+- `Durar Gateway_DISABLE_TELEMETRY=1`: Disable telemetry on `sync`.

package/docs/tools/code-execution.md

@@ -0,0 +1,90 @@
+---
+summary: "code_execution -- run sandboxed remote Python analysis with xAI"
+read_when:
+  - You want to enable or configure code_execution
+  - You want remote analysis without local shell access
+  - You want to combine x_search or web_search with remote Python analysis
+title: "Code Execution"
+---
+
+# Code Execution
+
+`code_execution` runs sandboxed remote Python analysis on xAI's Responses API.
+This is different from local [`exec`](/tools/exec):
+
+- `exec` runs shell commands on your machine or node
+- `code_execution` runs Python in xAI's remote sandbox
+
+Use `code_execution` for:
+
+- calculations
+- tabulation
+- quick statistics
+- chart-style analysis
+- analyzing data returned by `x_search` or `web_search`
+
+Do **not** use it when you need local files, your shell, your repo, or paired
+devices. Use [`exec`](/tools/exec) for that.
+
+## Setup
+
+You need an xAI API key. Any of these work:
+
+- `XAI_API_KEY`
+- `plugins.entries.xai.config.webSearch.apiKey`
+
+Example:
+
+```json5
+{
+  plugins: {
+    entries: {
+      xai: {
+        config: {
+          webSearch: {
+            apiKey: "xai-...",
+          },
+          codeExecution: {
+            enabled: true,
+            model: "grok-4-1-fast",
+            maxTurns: 2,
+            timeoutSeconds: 30,
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+## How To Use It
+
+Ask naturally and make the analysis intent explicit:
+
+```text
+Use code_execution to calculate the 7-day moving average for these numbers: ...
+```
+
+```text
+Use x_search to find posts mentioning Durar this week, then use code_execution to count them by day.
+```
+
+```text
+Use web_search to gather the latest AI benchmark numbers, then use code_execution to compare percent changes.
+```
+
+The tool takes a single `task` parameter internally, so the agent should send
+the full analysis request and any inline data in one prompt.
+
+## Limits
+
+- This is remote xAI execution, not local process execution.
+- It should be treated as ephemeral analysis, not a persistent notebook.
+- Do not assume access to local files or your workspace.
+- For fresh X data, use [`x_search`](/tools/web#x_search) first.
+
+## See Also
+
+- [Web tools](/tools/web)
+- [Exec](/tools/exec)
+- [xAI](/providers/xai)