durar-ai 2026.4.4

package/docs/cli/approvals.md

@@ -0,0 +1,136 @@
+---
+summary: "CLI reference for `Durar approvals` (exec approvals for gateway or node hosts)"
+read_when:
+  - You want to edit exec approvals from the CLI
+  - You need to manage allowlists on gateway or node hosts
+title: "approvals"
+---
+
+# `Durar approvals`
+
+Manage exec approvals for the **local host**, **gateway host**, or a **node host**.
+By default, commands target the local approvals file on disk. Use `--gateway` to target the gateway, or `--node` to target a specific node.
+
+Alias: `Durar exec-approvals`
+
+Related:
+
+- Exec approvals: [Exec approvals](/tools/exec-approvals)
+- Nodes: [Nodes](/nodes)
+
+## Common commands
+
+```bash
+Durar approvals get
+Durar approvals get --node <id|name|ip>
+Durar approvals get --gateway
+```
+
+`Durar approvals get` now shows the effective exec policy for local, gateway, and node targets:
+
+- requested `tools.exec` policy
+- host approvals-file policy
+- effective result after precedence rules are applied
+
+Precedence is intentional:
+
+- the host approvals file is the enforceable source of truth
+- requested `tools.exec` policy can narrow or broaden intent, but the effective result is still derived from the host rules
+- `--node` combines the node host approvals file with gateway `tools.exec` policy, because both still apply at runtime
+- if gateway config is unavailable, the CLI falls back to the node approvals snapshot and notes that the final runtime policy could not be computed
+
+## Replace approvals from a file
+
+```bash
+Durar approvals set --file ./exec-approvals.json
+Durar approvals set --stdin <<'EOF'
+{ version: 1, defaults: { security: "full", ask: "off" } }
+EOF
+Durar approvals set --node <id|name|ip> --file ./exec-approvals.json
+Durar approvals set --gateway --file ./exec-approvals.json
+```
+
+`set` accepts JSON5, not only strict JSON. Use either `--file` or `--stdin`, not both.
+
+## "Never prompt" / YOLO example
+
+For a host that should never stop on exec approvals, set the host approvals defaults to `full` + `off`:
+
+```bash
+Durar approvals set --stdin <<'EOF'
+{
+  version: 1,
+  defaults: {
+    security: "full",
+    ask: "off",
+    askFallback: "full"
+  }
+}
+EOF
+```
+
+Node variant:
+
+```bash
+Durar approvals set --node <id|name|ip> --stdin <<'EOF'
+{
+  version: 1,
+  defaults: {
+    security: "full",
+    ask: "off",
+    askFallback: "full"
+  }
+}
+EOF
+```
+
+This changes the **host approvals file** only. To keep the requested Durar policy aligned, also set:
+
+```bash
+Durar config set tools.exec.host gateway
+Durar config set tools.exec.security full
+Durar config set tools.exec.ask off
+```
+
+Why `tools.exec.host=gateway` in this example:
+
+- `host=auto` still means "sandbox when available, otherwise gateway".
+- YOLO is about approvals, not routing.
+- If you want host exec even when a sandbox is configured, make the host choice explicit with `gateway` or `/exec host=gateway`.
+
+This matches the current host-default YOLO behavior. Tighten it if you want approvals.
+
+## Allowlist helpers
+
+```bash
+Durar approvals allowlist add "~/Projects/**/bin/rg"
+Durar approvals allowlist add --agent main --node <id|name|ip> "/usr/bin/uptime"
+Durar approvals allowlist add --agent "*" "/usr/bin/uname"
+
+Durar approvals allowlist remove "~/Projects/**/bin/rg"
+```
+
+## Common options
+
+`get`, `set`, and `allowlist add|remove` all support:
+
+- `--node <id|name|ip>`
+- `--gateway`
+- shared node RPC options: `--url`, `--token`, `--timeout`, `--json`
+
+Targeting notes:
+
+- no target flags means the local approvals file on disk
+- `--gateway` targets the gateway host approvals file
+- `--node` targets one node host after resolving id, name, IP, or id prefix
+
+`allowlist add|remove` also supports:
+
+- `--agent <id>` (defaults to `*`)
+
+## Notes
+
+- `--node` uses the same resolver as `Durar nodes` (id, name, ip, or id prefix).
+- `--agent` defaults to `"*"`, which applies to all agents.
+- The node host must advertise `system.execApprovals.get/set` (macOS app or headless node host).
+- Approvals files are stored per host at `~/.Durar/exec-approvals.json`.

package/docs/cli/backup.md

@@ -0,0 +1,84 @@
+---
+summary: "CLI reference for `Durar backup` (create local backup archives)"
+read_when:
+  - You want a first-class backup archive for local Durar state
+  - You want to preview which paths would be included before reset or uninstall
+title: "backup"
+---
+
+# `Durar backup`
+
+Create a local backup archive for Durar state, config, auth profiles, channel/provider credentials, sessions, and optionally workspaces.
+
+```bash
+Durar backup create
+Durar backup create --output ~/Backups
+Durar backup create --dry-run --json
+Durar backup create --verify
+Durar backup create --no-include-workspace
+Durar backup create --only-config
+Durar backup verify ./2026-03-09T00-00-00.000Z-Durar-backup.tar.gz
+```
+
+## Notes
+
+- The archive includes a `manifest.json` file with the resolved source paths and archive layout.
+- Default output is a timestamped `.tar.gz` archive in the current working directory.
+- If the current working directory is inside a backed-up source tree, Durar falls back to your home directory for the default archive location.
+- Existing archive files are never overwritten.
+- Output paths inside the source state/workspace trees are rejected to avoid self-inclusion.
+- `Durar backup verify <archive>` validates that the archive contains exactly one root manifest, rejects traversal-style archive paths, and checks that every manifest-declared payload exists in the tarball.
+- `Durar backup create --verify` runs that validation immediately after writing the archive.
+- `Durar backup create --only-config` backs up just the active JSON config file.
+
+## What gets backed up
+
+`Durar backup create` plans backup sources from your local Durar install:
+
+- The state directory returned by Durar's local state resolver, usually `~/.Durar`
+- The active config file path
+- The resolved `credentials/` directory when it exists outside the state directory
+- Workspace directories discovered from the current config, unless you pass `--no-include-workspace`
+
+Model auth profiles are already part of the state directory under
+`agents/<agentId>/agent/auth-profiles.json`, so they are normally covered by the
+state backup entry.
+
+If you use `--only-config`, Durar skips state, credentials-directory, and workspace discovery and archives only the active config file path.
+
+Durar canonicalizes paths before building the archive. If config, the
+credentials directory, or a workspace already live inside the state directory,
+they are not duplicated as separate top-level backup sources. Missing paths are
+skipped.
+
+The archive payload stores file contents from those source trees, and the embedded `manifest.json` records the resolved absolute source paths plus the archive layout used for each asset.
+
+## Invalid config behavior
+
+`Durar backup` intentionally bypasses the normal config preflight so it can still help during recovery. Because workspace discovery depends on a valid config, `Durar backup create` now fails fast when the config file exists but is invalid and workspace backup is still enabled.
+
+If you still want a partial backup in that situation, rerun:
+
+```bash
+Durar backup create --no-include-workspace
+```
+
+That keeps state, config, and the external credentials directory in scope while
+skipping workspace discovery entirely.
+
+If you only need a copy of the config file itself, `--only-config` also works when the config is malformed because it does not rely on parsing the config for workspace discovery.
+
+## Size and performance
+
+Durar does not enforce a built-in maximum backup size or per-file size limit.
+
+Practical limits come from the local machine and destination filesystem:
+
+- Available space for the temporary archive write plus the final archive
+- Time to walk large workspace trees and compress them into a `.tar.gz`
+- Time to rescan the archive if you use `Durar backup create --verify` or run `Durar backup verify`
+- Filesystem behavior at the destination path. Durar prefers a no-overwrite hard-link publish step and falls back to exclusive copy when hard links are unsupported
+
+Large workspaces are usually the main driver of archive size. If you want a smaller or faster backup, use `--no-include-workspace`.
+
+For the smallest archive, use `--only-config`.

package/docs/cli/browser.md

@@ -0,0 +1,233 @@
+---
+summary: "CLI reference for `Durar browser` (lifecycle, profiles, tabs, actions, state, and debugging)"
+read_when:
+  - You use `Durar browser` and want examples for common tasks
+  - You want to control a browser running on another machine via a node host
+  - You want to attach to your local signed-in Chrome via Chrome MCP
+title: "browser"
+---
+
+# `Durar browser`
+
+Manage Durar's browser control surface and run browser actions (lifecycle, profiles, tabs, snapshots, screenshots, navigation, input, state emulation, and debugging).
+
+Related:
+
+- Browser tool + API: [Browser tool](/tools/browser)
+
+## Common flags
+
+- `--url <gatewayWsUrl>`: Gateway WebSocket URL (defaults to config).
+- `--token <token>`: Gateway token (if required).
+- `--timeout <ms>`: request timeout (ms).
+- `--expect-final`: wait for a final Gateway response.
+- `--browser-profile <name>`: choose a browser profile (default from config).
+- `--json`: machine-readable output (where supported).
+
+## Quick start (local)
+
+```bash
+Durar browser profiles
+Durar browser --browser-profile Durar start
+Durar browser --browser-profile Durar open https://example.com
+Durar browser --browser-profile Durar snapshot
+```
+
+## Lifecycle
+
+```bash
+Durar browser status
+Durar browser start
+Durar browser stop
+Durar browser --browser-profile Durar reset-profile
+```
+
+Notes:
+
+- For `attachOnly` and remote CDP profiles, `Durar browser stop` closes the
+  active control session and clears temporary emulation overrides even when
+  Durar did not launch the browser process itself.
+- For local managed profiles, `Durar browser stop` stops the spawned browser
+  process.
+
+## If the command is missing
+
+If `Durar browser` is an unknown command, check `plugins.allow` in
+`~/.Durar/Durar.json`.
+
+When `plugins.allow` is present, the bundled browser plugin must be listed
+explicitly:
+
+```json5
+{
+  plugins: {
+    allow: ["telegram", "browser"],
+  },
+}
+```
+
+`browser.enabled=true` does not restore the CLI subcommand when the plugin
+allowlist excludes `browser`.
+
+Related: [Browser tool](/tools/browser#missing-browser-command-or-tool)
+
+## Profiles
+
+Profiles are named browser routing configs. In practice:
+
+- `Durar`: launches or attaches to a dedicated Durar-managed Chrome instance (isolated user data dir).
+- `user`: controls your existing signed-in Chrome session via Chrome DevTools MCP.
+- custom CDP profiles: point at a local or remote CDP endpoint.
+
+```bash
+Durar browser profiles
+Durar browser create-profile --name work --color "#FF5A36"
+Durar browser create-profile --name chrome-live --driver existing-session
+Durar browser create-profile --name remote --cdp-url https://browser-host.example.com
+Durar browser delete-profile --name work
+```
+
+Use a specific profile:
+
+```bash
+Durar browser --browser-profile work tabs
+```
+
+## Tabs
+
+```bash
+Durar browser tabs
+Durar browser tab new
+Durar browser tab select 2
+Durar browser tab close 2
+Durar browser open https://docs.Durar.ai
+Durar browser focus <targetId>
+Durar browser close <targetId>
+```
+
+## Snapshot / screenshot / actions
+
+Snapshot:
+
+```bash
+Durar browser snapshot
+```
+
+Screenshot:
+
+```bash
+Durar browser screenshot
+Durar browser screenshot --full-page
+Durar browser screenshot --ref e12
+```
+
+Notes:
+
+- `--full-page` is for page captures only; it cannot be combined with `--ref`
+  or `--element`.
+- `existing-session` / `user` profiles support page screenshots and `--ref`
+  screenshots from snapshot output, but not CSS `--element` screenshots.
+
+Navigate/click/type (ref-based UI automation):
+
+```bash
+Durar browser navigate https://example.com
+Durar browser click <ref>
+Durar browser type <ref> "hello"
+Durar browser press Enter
+Durar browser hover <ref>
+Durar browser scrollintoview <ref>
+Durar browser drag <startRef> <endRef>
+Durar browser select <ref> OptionA OptionB
+Durar browser fill --fields '[{"ref":"1","value":"Ada"}]'
+Durar browser wait --text "Done"
+Durar browser evaluate --fn '(el) => el.textContent' --ref <ref>
+```
+
+File + dialog helpers:
+
+```bash
+Durar browser upload /tmp/Durar/uploads/file.pdf --ref <ref>
+Durar browser waitfordownload
+Durar browser download <ref> report.pdf
+Durar browser dialog --accept
+```
+
+## State and storage
+
+Viewport + emulation:
+
+```bash
+Durar browser resize 1280 720
+Durar browser set viewport 1280 720
+Durar browser set offline on
+Durar browser set media dark
+Durar browser set timezone Europe/London
+Durar browser set locale en-GB
+Durar browser set geo 51.5074 -0.1278 --accuracy 25
+Durar browser set device "iPhone 14"
+Durar browser set headers '{"x-test":"1"}'
+Durar browser set credentials myuser mypass
+```
+
+Cookies + storage:
+
+```bash
+Durar browser cookies
+Durar browser cookies set session abc123 --url https://example.com
+Durar browser cookies clear
+Durar browser storage local get
+Durar browser storage local set token abc123
+Durar browser storage session clear
+```
+
+## Debugging
+
+```bash
+Durar browser console --level error
+Durar browser pdf
+Durar browser responsebody "**/api"
+Durar browser highlight <ref>
+Durar browser errors --clear
+Durar browser requests --filter api
+Durar browser trace start
+Durar browser trace stop --out trace.zip
+```
+
+## Existing Chrome via MCP
+
+Use the built-in `user` profile, or create your own `existing-session` profile:
+
+```bash
+Durar browser --browser-profile user tabs
+Durar browser create-profile --name chrome-live --driver existing-session
+Durar browser create-profile --name brave-live --driver existing-session --user-data-dir "~/Library/Application Support/BraveSoftware/Brave-Browser"
+Durar browser --browser-profile chrome-live tabs
+```
+
+This path is host-only. For Docker, headless servers, Browserless, or other remote setups, use a CDP profile instead.
+
+Current existing-session limits:
+
+- snapshot-driven actions use refs, not CSS selectors
+- `click` is left-click only
+- `type` does not support `slowly=true`
+- `press` does not support `delayMs`
+- `hover`, `scrollintoview`, `drag`, `select`, `fill`, and `evaluate` reject
+  per-call timeout overrides
+- `select` supports one value only
+- `wait --load networkidle` is not supported
+- file uploads require `--ref` / `--input-ref`, do not support CSS
+  `--element`, and currently support one file at a time
+- dialog hooks do not support `--timeout`
+- screenshots support page captures and `--ref`, but not CSS `--element`
+- `responsebody`, download interception, PDF export, and batch actions still
+  require a managed browser or raw CDP profile
+
+## Remote browser control (node host proxy)
+
+If the Gateway runs on a different machine than the browser, run a **node host** on the machine that has Chrome/Brave/Edge/Chromium. The Gateway will proxy browser actions to that node (no separate browser control server required).
+
+Use `gateway.nodes.browser.mode` to control auto-routing and `gateway.nodes.browser.node` to pin a specific node if multiple are connected.
+
+Security + remote setup: [Browser tool](/tools/browser), [Remote access](/gateway/remote), [Tailscale](/gateway/tailscale), [Security](/gateway/security)

package/docs/cli/channels.md

@@ -0,0 +1,131 @@
+---
+summary: "CLI reference for `Durar channels` (accounts, status, login/logout, logs)"
+read_when:
+  - You want to add/remove channel accounts (WhatsApp/Telegram/Discord/Google Chat/Slack/Mattermost (plugin)/Signal/iMessage/Matrix)
+  - You want to check channel status or tail channel logs
+title: "channels"
+---
+
+# `Durar channels`
+
+Manage chat channel accounts and their runtime status on the Gateway.
+
+Related docs:
+
+- Channel guides: [Channels](/channels/index)
+- Gateway configuration: [Configuration](/gateway/configuration)
+
+## Common commands
+
+```bash
+Durar channels list
+Durar channels status
+Durar channels capabilities
+Durar channels capabilities --channel discord --target channel:123
+Durar channels resolve --channel slack "#general" "@jane"
+Durar channels logs --channel all
+```
+
+## Status / capabilities / resolve / logs
+
+- `channels status`: `--probe`, `--timeout <ms>`, `--json`
+- `channels capabilities`: `--channel <name>`, `--account <id>` (only with `--channel`), `--target <dest>`, `--timeout <ms>`, `--json`
+- `channels resolve`: `<entries...>`, `--channel <name>`, `--account <id>`, `--kind <auto|user|group>`, `--json`
+- `channels logs`: `--channel <name|all>`, `--lines <n>`, `--json`
+
+`channels status --probe` is the live path: on a reachable gateway it runs per-account
+`probeAccount` and optional `auditAccount` checks, so output can include transport
+state plus probe results such as `works`, `probe failed`, `audit ok`, or `audit failed`.
+If the gateway is unreachable, `channels status` falls back to config-only summaries
+instead of live probe output.
+
+## Add / remove accounts
+
+```bash
+Durar channels add --channel telegram --token <bot-token>
+Durar channels add --channel nostr --private-key "$NOSTR_PRIVATE_KEY"
+Durar channels remove --channel telegram --delete
+```
+
+Tip: `Durar channels add --help` shows per-channel flags (token, private key, app token, signal-cli paths, etc).
+
+Common non-interactive add surfaces include:
+
+- bot-token channels: `--token`, `--bot-token`, `--app-token`, `--token-file`
+- Signal/iMessage transport fields: `--signal-number`, `--cli-path`, `--http-url`, `--http-host`, `--http-port`, `--db-path`, `--service`, `--region`
+- Google Chat fields: `--webhook-path`, `--webhook-url`, `--audience-type`, `--audience`
+- Matrix fields: `--homeserver`, `--user-id`, `--access-token`, `--password`, `--device-name`, `--initial-sync-limit`
+- Nostr fields: `--private-key`, `--relay-urls`
+- Tlon fields: `--ship`, `--url`, `--code`, `--group-channels`, `--dm-allowlist`, `--auto-discover-channels`
+- `--use-env` for default-account env-backed auth where supported
+
+When you run `Durar channels add` without flags, the interactive wizard can prompt:
+
+- account ids per selected channel
+- optional display names for those accounts
+- `Bind configured channel accounts to agents now?`
+
+If you confirm bind now, the wizard asks which agent should own each configured channel account and writes account-scoped routing bindings.
+
+You can also manage the same routing rules later with `Durar agents bindings`, `Durar agents bind`, and `Durar agents unbind` (see [agents](/cli/agents)).
+
+When you add a non-default account to a channel that is still using single-account top-level settings, Durar promotes account-scoped top-level values into the channel's account map before writing the new account. Most channels land those values in `channels.<channel>.accounts.default`, but bundled channels can preserve an existing matching promoted account instead. Matrix is the current example: if one named account already exists, or `defaultAccount` points at an existing named account, promotion preserves that account instead of creating a new `accounts.default`.
+
+Routing behavior stays consistent:
+
+- Existing channel-only bindings (no `accountId`) continue to match the default account.
+- `channels add` does not auto-create or rewrite bindings in non-interactive mode.
+- Interactive setup can optionally add account-scoped bindings.
+
+If your config was already in a mixed state (named accounts present and top-level single-account values still set), run `Durar doctor --fix` to move account-scoped values into the promoted account chosen for that channel. Most channels promote into `accounts.default`; Matrix can preserve an existing named/default target instead.
+
+## Login / logout (interactive)
+
+```bash
+Durar channels login --channel whatsapp
+Durar channels logout --channel whatsapp
+```
+
+Notes:
+
+- `channels login` supports `--verbose`.
+- `channels login` / `logout` can infer the channel when only one supported login target is configured.
+
+## Troubleshooting
+
+- Run `Durar status --deep` for a broad probe.
+- Use `Durar doctor` for guided fixes.
+- `Durar channels list` prints `Claude: HTTP 403 ... user:profile` → usage snapshot needs the `user:profile` scope. Use `--no-usage`, or provide a claude.ai session key (`CLAUDE_WEB_SESSION_KEY` / `CLAUDE_WEB_COOKIE`), or re-auth via Claude CLI.
+- `Durar channels status` falls back to config-only summaries when the gateway is unreachable. If a supported channel credential is configured via SecretRef but unavailable in the current command path, it reports that account as configured with degraded notes instead of showing it as not configured.
+
+## Capabilities probe
+
+Fetch provider capability hints (intents/scopes where available) plus static feature support:
+
+```bash
+Durar channels capabilities
+Durar channels capabilities --channel discord --target channel:123
+```
+
+Notes:
+
+- `--channel` is optional; omit it to list every channel (including extensions).
+- `--account` is only valid with `--channel`.
+- `--target` accepts `channel:<id>` or a raw numeric channel id and only applies to Discord.
+- Probes are provider-specific: Discord intents + optional channel permissions; Slack bot + user scopes; Telegram bot flags + webhook; Signal daemon version; Microsoft Teams app token + Graph roles/scopes (annotated where known). Channels without probes report `Probe: unavailable`.
+
+## Resolve names to IDs
+
+Resolve channel/user names to IDs using the provider directory:
+
+```bash
+Durar channels resolve --channel slack "#general" "@jane"
+Durar channels resolve --channel discord "My Server/#support" "@someone"
+Durar channels resolve --channel matrix "Project Room"
+```
+
+Notes:
+
+- Use `--kind user|group|auto` to force the target type.
+- Resolution prefers active matches when multiple entries share the same name.
+- `channels resolve` is read-only. If a selected account is configured via SecretRef but that credential is unavailable in the current command path, the command returns degraded unresolved results with notes instead of aborting the entire run.

package/docs/cli/clawbot.md

@@ -0,0 +1,21 @@
+---
+summary: "CLI reference for `Durar clawbot` (legacy alias namespace)"
+read_when:
+  - You maintain older scripts using `Durar clawbot ...`
+  - You need migration guidance to current commands
+title: "clawbot"
+---
+
+# `Durar clawbot`
+
+Legacy alias namespace kept for backwards compatibility.
+
+Current supported alias:
+
+- `Durar clawbot qr` (same behavior as [`Durar qr`](/cli/qr))
+
+## Migration
+
+Prefer modern top-level commands directly:
+
+- `Durar clawbot qr` -> `Durar qr`

package/docs/cli/completion.md

@@ -0,0 +1,35 @@
+---
+summary: "CLI reference for `Durar completion` (generate/install shell completion scripts)"
+read_when:
+  - You want shell completions for zsh/bash/fish/PowerShell
+  - You need to cache completion scripts under Durar state
+title: "completion"
+---
+
+# `Durar completion`
+
+Generate shell completion scripts and optionally install them into your shell profile.
+
+## Usage
+
+```bash
+Durar completion
+Durar completion --shell zsh
+Durar completion --install
+Durar completion --shell fish --install
+Durar completion --write-state
+Durar completion --shell bash --write-state
+```
+
+## Options
+
+- `-s, --shell <shell>`: shell target (`zsh`, `bash`, `powershell`, `fish`; default: `zsh`)
+- `-i, --install`: install completion by adding a source line to your shell profile
+- `--write-state`: write completion script(s) to `$Durar_STATE_DIR/completions` without printing to stdout
+- `-y, --yes`: skip install confirmation prompts
+
+## Notes
+
+- `--install` writes a small "Durar Completion" block into your shell profile and points it at the cached script.
+- Without `--install` or `--write-state`, the command prints the script to stdout.
+- Completion generation eagerly loads command trees so nested subcommands are included.