durar-ai 2026.4.4

package/docs/cli/config.md

@@ -0,0 +1,353 @@
+---
+summary: "CLI reference for `Durar config` (get/set/unset/file/schema/validate)"
+read_when:
+  - You want to read or edit config non-interactively
+title: "config"
+---
+
+# `Durar config`
+
+Config helpers for non-interactive edits in `Durar.json`: get/set/unset/file/schema/validate
+values by path and print the active config file. Run without a subcommand to
+open the configure wizard (same as `Durar configure`).
+
+Root options:
+
+- `--section <section>`: repeatable guided-setup section filter when you run `Durar config` without a subcommand
+
+Supported guided sections:
+
+- `workspace`
+- `model`
+- `web`
+- `gateway`
+- `daemon`
+- `channels`
+- `plugins`
+- `skills`
+- `health`
+
+## Examples
+
+```bash
+Durar config file
+Durar config --section model
+Durar config --section gateway --section daemon
+Durar config schema
+Durar config get browser.executablePath
+Durar config set browser.executablePath "/usr/bin/google-chrome"
+Durar config set agents.defaults.heartbeat.every "2h"
+Durar config set agents.list[0].tools.exec.node "node-id-or-name"
+Durar config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN
+Durar config set secrets.providers.vaultfile --provider-source file --provider-path /etc/Durar/secrets.json --provider-mode json
+Durar config unset plugins.entries.brave.config.webSearch.apiKey
+Durar config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN --dry-run
+Durar config validate
+Durar config validate --json
+```
+
+### `config schema`
+
+Print the generated JSON schema for `Durar.json` to stdout as JSON.
+
+What it includes:
+
+- The current root config schema, plus a root `$schema` string field for editor tooling
+- Field `title` and `description` docs metadata used by the Control UI
+- Nested object, wildcard (`*`), and array-item (`[]`) nodes inherit the same `title` / `description` metadata when matching field documentation exists
+- `anyOf` / `oneOf` / `allOf` branches inherit the same docs metadata too when matching field documentation exists
+- Best-effort live plugin + channel schema metadata when runtime manifests can be loaded
+- A clean fallback schema even when the current config is invalid
+
+Related runtime RPC:
+
+- `config.schema.lookup` returns one normalized config path with a shallow
+  schema node (`title`, `description`, `type`, `enum`, `const`, common bounds),
+  matched UI hint metadata, and immediate child summaries. Use it for
+  path-scoped drill-down in Control UI or custom clients.
+
+```bash
+Durar config schema
+```
+
+Pipe it into a file when you want to inspect or validate it with other tools:
+
+```bash
+Durar config schema > Durar.schema.json
+```
+
+### Paths
+
+Paths use dot or bracket notation:
+
+```bash
+Durar config get agents.defaults.workspace
+Durar config get agents.list[0].id
+```
+
+Use the agent list index to target a specific agent:
+
+```bash
+Durar config get agents.list
+Durar config set agents.list[1].tools.exec.node "node-id-or-name"
+```
+
+## Values
+
+Values are parsed as JSON5 when possible; otherwise they are treated as strings.
+Use `--strict-json` to require JSON5 parsing. `--json` remains supported as a legacy alias.
+
+```bash
+Durar config set agents.defaults.heartbeat.every "0m"
+Durar config set gateway.port 19001 --strict-json
+Durar config set channels.whatsapp.groups '["*"]' --strict-json
+```
+
+`config get <path> --json` prints the raw value as JSON instead of terminal-formatted text.
+
+## `config set` modes
+
+`Durar config set` supports four assignment styles:
+
+1. Value mode: `Durar config set <path> <value>`
+2. SecretRef builder mode:
+
+```bash
+Durar config set channels.discord.token \
+  --ref-provider default \
+  --ref-source env \
+  --ref-id DISCORD_BOT_TOKEN
+```
+
+3. Provider builder mode (`secrets.providers.<alias>` path only):
+
+```bash
+Durar config set secrets.providers.vault \
+  --provider-source exec \
+  --provider-command /usr/local/bin/Durar-vault \
+  --provider-arg read \
+  --provider-arg openai/api-key \
+  --provider-timeout-ms 5000
+```
+
+4. Batch mode (`--batch-json` or `--batch-file`):
+
+```bash
+Durar config set --batch-json '[
+  {
+    "path": "secrets.providers.default",
+    "provider": { "source": "env" }
+  },
+  {
+    "path": "channels.discord.token",
+    "ref": { "source": "env", "provider": "default", "id": "DISCORD_BOT_TOKEN" }
+  }
+]'
+```
+
+```bash
+Durar config set --batch-file ./config-set.batch.json --dry-run
+```
+
+Policy note:
+
+- SecretRef assignments are rejected on unsupported runtime-mutable surfaces (for example `hooks.token`, `commands.ownerDisplaySecret`, Discord thread-binding webhook tokens, and WhatsApp creds JSON). See [SecretRef Credential Surface](/reference/secretref-credential-surface).
+
+Batch parsing always uses the batch payload (`--batch-json`/`--batch-file`) as the source of truth.
+`--strict-json` / `--json` do not change batch parsing behavior.
+
+JSON path/value mode remains supported for both SecretRefs and providers:
+
+```bash
+Durar config set channels.discord.token \
+  '{"source":"env","provider":"default","id":"DISCORD_BOT_TOKEN"}' \
+  --strict-json
+
+Durar config set secrets.providers.vaultfile \
+  '{"source":"file","path":"/etc/Durar/secrets.json","mode":"json"}' \
+  --strict-json
+```
+
+## Provider Builder Flags
+
+Provider builder targets must use `secrets.providers.<alias>` as the path.
+
+Common flags:
+
+- `--provider-source <env|file|exec>`
+- `--provider-timeout-ms <ms>` (`file`, `exec`)
+
+Env provider (`--provider-source env`):
+
+- `--provider-allowlist <ENV_VAR>` (repeatable)
+
+File provider (`--provider-source file`):
+
+- `--provider-path <path>` (required)
+- `--provider-mode <singleValue|json>`
+- `--provider-max-bytes <bytes>`
+
+Exec provider (`--provider-source exec`):
+
+- `--provider-command <path>` (required)
+- `--provider-arg <arg>` (repeatable)
+- `--provider-no-output-timeout-ms <ms>`
+- `--provider-max-output-bytes <bytes>`
+- `--provider-json-only`
+- `--provider-env <KEY=VALUE>` (repeatable)
+- `--provider-pass-env <ENV_VAR>` (repeatable)
+- `--provider-trusted-dir <path>` (repeatable)
+- `--provider-allow-insecure-path`
+- `--provider-allow-symlink-command`
+
+Hardened exec provider example:
+
+```bash
+Durar config set secrets.providers.vault \
+  --provider-source exec \
+  --provider-command /usr/local/bin/Durar-vault \
+  --provider-arg read \
+  --provider-arg openai/api-key \
+  --provider-json-only \
+  --provider-pass-env VAULT_TOKEN \
+  --provider-trusted-dir /usr/local/bin \
+  --provider-timeout-ms 5000
+```
+
+## Dry run
+
+Use `--dry-run` to validate changes without writing `Durar.json`.
+
+```bash
+Durar config set channels.discord.token \
+  --ref-provider default \
+  --ref-source env \
+  --ref-id DISCORD_BOT_TOKEN \
+  --dry-run
+
+Durar config set channels.discord.token \
+  --ref-provider default \
+  --ref-source env \
+  --ref-id DISCORD_BOT_TOKEN \
+  --dry-run \
+  --json
+
+Durar config set channels.discord.token \
+  --ref-provider vault \
+  --ref-source exec \
+  --ref-id discord/token \
+  --dry-run \
+  --allow-exec
+```
+
+Dry-run behavior:
+
+- Builder mode: runs SecretRef resolvability checks for changed refs/providers.
+- JSON mode (`--strict-json`, `--json`, or batch mode): runs schema validation plus SecretRef resolvability checks.
+- Policy validation also runs for known unsupported SecretRef target surfaces.
+- Policy checks evaluate the full post-change config, so parent-object writes (for example setting `hooks` as an object) cannot bypass unsupported-surface validation.
+- Exec SecretRef checks are skipped by default during dry-run to avoid command side effects.
+- Use `--allow-exec` with `--dry-run` to opt in to exec SecretRef checks (this may execute provider commands).
+- `--allow-exec` is dry-run only and errors if used without `--dry-run`.
+
+`--dry-run --json` prints a machine-readable report:
+
+- `ok`: whether dry-run passed
+- `operations`: number of assignments evaluated
+- `checks`: whether schema/resolvability checks ran
+- `checks.resolvabilityComplete`: whether resolvability checks ran to completion (false when exec refs are skipped)
+- `refsChecked`: number of refs actually resolved during dry-run
+- `skippedExecRefs`: number of exec refs skipped because `--allow-exec` was not set
+- `errors`: structured schema/resolvability failures when `ok=false`
+
+### JSON Output Shape
+
+```json5
+{
+  ok: boolean,
+  operations: number,
+  configPath: string,
+  inputModes: ["value" | "json" | "builder", ...],
+  checks: {
+    schema: boolean,
+    resolvability: boolean,
+    resolvabilityComplete: boolean,
+  },
+  refsChecked: number,
+  skippedExecRefs: number,
+  errors?: [
+    {
+      kind: "schema" | "resolvability",
+      message: string,
+      ref?: string, // present for resolvability errors
+    },
+  ],
+}
+```
+
+Success example:
+
+```json
+{
+  "ok": true,
+  "operations": 1,
+  "configPath": "~/.Durar/Durar.json",
+  "inputModes": ["builder"],
+  "checks": {
+    "schema": false,
+    "resolvability": true,
+    "resolvabilityComplete": true
+  },
+  "refsChecked": 1,
+  "skippedExecRefs": 0
+}
+```
+
+Failure example:
+
+```json
+{
+  "ok": false,
+  "operations": 1,
+  "configPath": "~/.Durar/Durar.json",
+  "inputModes": ["builder"],
+  "checks": {
+    "schema": false,
+    "resolvability": true,
+    "resolvabilityComplete": true
+  },
+  "refsChecked": 1,
+  "skippedExecRefs": 0,
+  "errors": [
+    {
+      "kind": "resolvability",
+      "message": "Error: Environment variable \"MISSING_TEST_SECRET\" is not set.",
+      "ref": "env:default:MISSING_TEST_SECRET"
+    }
+  ]
+}
+```
+
+If dry-run fails:
+
+- `config schema validation failed`: your post-change config shape is invalid; fix path/value or provider/ref object shape.
+- `Config policy validation failed: unsupported SecretRef usage`: move that credential back to plaintext/string input and keep SecretRefs on supported surfaces only.
+- `SecretRef assignment(s) could not be resolved`: referenced provider/ref currently cannot resolve (missing env var, invalid file pointer, exec provider failure, or provider/source mismatch).
+- `Dry run note: skipped <n> exec SecretRef resolvability check(s)`: dry-run skipped exec refs; rerun with `--allow-exec` if you need exec resolvability validation.
+- For batch mode, fix failing entries and rerun `--dry-run` before writing.
+
+## Subcommands
+
+- `config file`: Print the active config file path (resolved from `Durar_CONFIG_PATH` or default location).
+
+Restart the gateway after edits.
+
+## Validate
+
+Validate the current config against the active schema without starting the
+gateway.
+
+```bash
+Durar config validate
+Durar config validate --json
+```

package/docs/cli/configure.md

@@ -0,0 +1,70 @@
+---
+summary: "CLI reference for `Durar configure` (interactive configuration prompts)"
+read_when:
+  - You want to tweak credentials, devices, or agent defaults interactively
+title: "configure"
+---
+
+# `Durar configure`
+
+Interactive prompt to set up credentials, devices, and agent defaults.
+
+Note: The **Model** section now includes a multi-select for the
+`agents.defaults.models` allowlist (what shows up in `/model` and the model picker).
+
+When configure starts from a provider auth choice, the default-model and
+allowlist pickers prefer that provider automatically. For paired providers such
+as Volcengine/BytePlus, the same preference also matches their coding-plan
+variants (`volcengine-plan/*`, `byteplus-plan/*`). If the preferred-provider
+filter would produce an empty list, configure falls back to the unfiltered
+catalog instead of showing a blank picker.
+
+Tip: `Durar config` without a subcommand opens the same wizard. Use
+`Durar config get|set|unset` for non-interactive edits.
+
+For web search, `Durar configure --section web` lets you choose a provider
+and configure its credentials. Some providers also show provider-specific
+follow-up prompts:
+
+- **Grok** can offer optional `x_search` setup with the same `XAI_API_KEY` and
+  let you pick an `x_search` model.
+- **Kimi** can ask for the Moonshot API region (`api.moonshot.ai` vs
+  `api.moonshot.cn`) and the default Kimi web-search model.
+
+Related:
+
+- Gateway configuration reference: [Configuration](/gateway/configuration)
+- Config CLI: [Config](/cli/config)
+
+## Options
+
+- `--section <section>`: repeatable section filter
+
+Available sections:
+
+- `workspace`
+- `model`
+- `web`
+- `gateway`
+- `daemon`
+- `channels`
+- `plugins`
+- `skills`
+- `health`
+
+Notes:
+
+- Choosing where the Gateway runs always updates `gateway.mode`. You can select "Continue" without other sections if that is all you need.
+- Channel-oriented services (Slack/Discord/Matrix/Microsoft Teams) prompt for channel/room allowlists during setup. You can enter names or IDs; the wizard resolves names to IDs when possible.
+- If you run the daemon install step, token auth requires a token, and `gateway.auth.token` is SecretRef-managed, configure validates the SecretRef but does not persist resolved plaintext token values into supervisor service environment metadata.
+- If token auth requires a token and the configured token SecretRef is unresolved, configure blocks daemon install with actionable remediation guidance.
+- If both `gateway.auth.token` and `gateway.auth.password` are configured and `gateway.auth.mode` is unset, configure blocks daemon install until mode is set explicitly.
+
+## Examples
+
+```bash
+Durar configure
+Durar configure --section web
+Durar configure --section model --section channels
+Durar configure --section gateway --section daemon
+```

package/docs/cli/cron.md

@@ -0,0 +1,167 @@
+---
+summary: "CLI reference for `Durar cron` (schedule and run background jobs)"
+read_when:
+  - You want scheduled jobs and wakeups
+  - You’re debugging cron execution and logs
+title: "cron"
+---
+
+# `Durar cron`
+
+Manage cron jobs for the Gateway scheduler.
+
+Related:
+
+- Cron jobs: [Cron jobs](/automation/cron-jobs)
+
+Tip: run `Durar cron --help` for the full command surface.
+
+Note: isolated `cron add` jobs default to `--announce` delivery. Use `--no-deliver` to keep
+output internal. `--deliver` remains as a deprecated alias for `--announce`.
+
+Note: cron-owned isolated runs expect a plain-text summary and the runner owns
+the final send path. `--no-deliver` keeps the run internal; it does not hand
+delivery back to the agent's message tool.
+
+Note: one-shot (`--at`) jobs delete after success by default. Use `--keep-after-run` to keep them.
+
+Note: `--session` supports `main`, `isolated`, `current`, and `session:<id>`.
+Use `current` to bind to the active session at creation time, or `session:<id>` for
+an explicit persistent session key.
+
+Note: for one-shot CLI jobs, offset-less `--at` datetimes are treated as UTC unless you also pass
+`--tz <iana>`, which interprets that local wall-clock time in the given timezone.
+
+Note: recurring jobs now use exponential retry backoff after consecutive errors (30s → 1m → 5m → 15m → 60m), then return to normal schedule after the next successful run.
+
+Note: `Durar cron run` now returns as soon as the manual run is queued for execution. Successful responses include `{ ok: true, enqueued: true, runId }`; use `Durar cron runs --id <job-id>` to follow the eventual outcome.
+
+Note: `Durar cron run <job-id>` force-runs by default. Use `--due` to keep the
+older "only run if due" behavior.
+
+Note: isolated cron turns suppress stale acknowledgement-only replies. If the
+first result is just an interim status update and no descendant subagent run is
+responsible for the eventual answer, cron re-prompts once for the real result
+before delivery.
+
+Note: if an isolated cron run returns only the silent token (`NO_REPLY` /
+`no_reply`), cron suppresses direct outbound delivery and the fallback queued
+summary path as well, so nothing is posted back to chat.
+
+Note: `cron add|edit --model ...` uses that selected allowed model for the job.
+If the model is not allowed, cron warns and falls back to the job's agent/default
+model selection instead. Configured fallback chains still apply, but a plain
+model override with no explicit per-job fallback list no longer appends the
+agent primary as a hidden extra retry target.
+
+Note: isolated cron model precedence is Gmail-hook override first, then per-job
+`--model`, then any stored cron-session model override, then the normal
+agent/default selection.
+
+Note: isolated cron fast mode follows the resolved live model selection. Model
+config `params.fastMode` applies by default, but a stored session `fastMode`
+override still wins over config.
+
+Note: if an isolated run throws `LiveSessionModelSwitchError`, cron persists the
+switched provider/model (and switched auth profile override when present) before
+retrying. The outer retry loop is bounded to 2 switch retries after the initial
+attempt, then aborts instead of looping forever.
+
+Note: failure notifications use `delivery.failureDestination` first, then
+global `cron.failureDestination`, and finally fall back to the job's primary
+announce target when no explicit failure destination is configured.
+
+Note: retention/pruning is controlled in config:
+
+- `cron.sessionRetention` (default `24h`) prunes completed isolated run sessions.
+- `cron.runLog.maxBytes` + `cron.runLog.keepLines` prune `~/.Durar/cron/runs/<jobId>.jsonl`.
+
+Upgrade note: if you have older cron jobs from before the current delivery/store format, run
+`Durar doctor --fix`. Doctor now normalizes legacy cron fields (`jobId`, `schedule.cron`,
+top-level delivery fields including legacy `threadId`, payload `provider` delivery aliases) and migrates simple
+`notify: true` webhook fallback jobs to explicit webhook delivery when `cron.webhook` is
+configured.
+
+## Common edits
+
+Update delivery settings without changing the message:
+
+```bash
+Durar cron edit <job-id> --announce --channel telegram --to "123456789"
+```
+
+Disable delivery for an isolated job:
+
+```bash
+Durar cron edit <job-id> --no-deliver
+```
+
+Enable lightweight bootstrap context for an isolated job:
+
+```bash
+Durar cron edit <job-id> --light-context
+```
+
+Announce to a specific channel:
+
+```bash
+Durar cron edit <job-id> --announce --channel slack --to "channel:C1234567890"
+```
+
+Create an isolated job with lightweight bootstrap context:
+
+```bash
+Durar cron add \
+  --name "Lightweight morning brief" \
+  --cron "0 7 * * *" \
+  --session isolated \
+  --message "Summarize overnight updates." \
+  --light-context \
+  --no-deliver
+```
+
+`--light-context` applies to isolated agent-turn jobs only. For cron runs, lightweight mode keeps bootstrap context empty instead of injecting the full workspace bootstrap set.
+
+Delivery ownership note:
+
+- Cron-owned isolated jobs always route final user-visible delivery through the
+  cron runner (`announce`, `webhook`, or internal-only `none`).
+- If the task mentions messaging some external recipient, the agent should
+  describe the intended destination in its result instead of trying to send it
+  directly.
+
+## Common admin commands
+
+Manual run:
+
+```bash
+Durar cron run <job-id>
+Durar cron run <job-id> --due
+Durar cron runs --id <job-id> --limit 50
+```
+
+Agent/session retargeting:
+
+```bash
+Durar cron edit <job-id> --agent ops
+Durar cron edit <job-id> --clear-agent
+Durar cron edit <job-id> --session current
+Durar cron edit <job-id> --session "session:daily-brief"
+```
+
+Delivery tweaks:
+
+```bash
+Durar cron edit <job-id> --announce --channel slack --to "channel:C1234567890"
+Durar cron edit <job-id> --best-effort-deliver
+Durar cron edit <job-id> --no-best-effort-deliver
+Durar cron edit <job-id> --no-deliver
+```
+
+Failure-delivery note:
+
+- `delivery.failureDestination` is supported for isolated jobs.
+- Main-session jobs may only use `delivery.failureDestination` when primary
+  delivery mode is `webhook`.
+- If you do not set any failure destination and the job already announces to a
+  channel, failure notifications reuse that same announce target.

package/docs/cli/daemon.md

@@ -0,0 +1,57 @@
+---
+summary: "CLI reference for `Durar daemon` (legacy alias for gateway service management)"
+read_when:
+  - You still use `Durar daemon ...` in scripts
+  - You need service lifecycle commands (install/start/stop/restart/status)
+title: "daemon"
+---
+
+# `Durar daemon`
+
+Legacy alias for Gateway service management commands.
+
+`Durar daemon ...` maps to the same service control surface as `Durar gateway ...` service commands.
+
+## Usage
+
+```bash
+Durar daemon status
+Durar daemon install
+Durar daemon start
+Durar daemon stop
+Durar daemon restart
+Durar daemon uninstall
+```
+
+## Subcommands
+
+- `status`: show service install state and probe Gateway health
+- `install`: install service (`launchd`/`systemd`/`schtasks`)
+- `uninstall`: remove service
+- `start`: start service
+- `stop`: stop service
+- `restart`: restart service
+
+## Common options
+
+- `status`: `--url`, `--token`, `--password`, `--timeout`, `--no-probe`, `--require-rpc`, `--deep`, `--json`
+- `install`: `--port`, `--runtime <node|bun>`, `--token`, `--force`, `--json`
+- lifecycle (`uninstall|start|stop|restart`): `--json`
+
+Notes:
+
+- `status` resolves configured auth SecretRefs for probe auth when possible.
+- If a required auth SecretRef is unresolved in this command path, `daemon status --json` reports `rpc.authWarning` when probe connectivity/auth fails; pass `--token`/`--password` explicitly or resolve the secret source first.
+- If the probe succeeds, unresolved auth-ref warnings are suppressed to avoid false positives.
+- `status --deep` adds a best-effort system-level service scan. When it finds other gateway-like services, human output prints cleanup hints and warns that one gateway per machine is still the normal recommendation.
+- On Linux systemd installs, `status` token-drift checks include both `Environment=` and `EnvironmentFile=` unit sources.
+- Drift checks resolve `gateway.auth.token` SecretRefs using merged runtime env (service command env first, then process env fallback).
+- If token auth is not effectively active (explicit `gateway.auth.mode` of `password`/`none`/`trusted-proxy`, or mode unset where password can win and no token candidate can win), token-drift checks skip config token resolution.
+- When token auth requires a token and `gateway.auth.token` is SecretRef-managed, `install` validates that the SecretRef is resolvable but does not persist the resolved token into service environment metadata.
+- If token auth requires a token and the configured token SecretRef is unresolved, install fails closed.
+- If both `gateway.auth.token` and `gateway.auth.password` are configured and `gateway.auth.mode` is unset, install is blocked until mode is set explicitly.
+- If you intentionally run multiple gateways on one host, isolate ports, config/state, and workspaces; see [/gateway#multiple-gateways-same-host](/gateway#multiple-gateways-same-host).
+
+## Prefer
+
+Use [`Durar gateway`](/cli/gateway) for current docs and examples.

package/docs/cli/dashboard.md

@@ -0,0 +1,22 @@
+---
+summary: "CLI reference for `Durar dashboard` (open the Control UI)"
+read_when:
+  - You want to open the Control UI with your current token
+  - You want to print the URL without launching a browser
+title: "dashboard"
+---
+
+# `Durar dashboard`
+
+Open the Control UI using your current auth.
+
+```bash
+Durar dashboard
+Durar dashboard --no-open
+```
+
+Notes:
+
+- `dashboard` resolves configured `gateway.auth.token` SecretRefs when possible.
+- For SecretRef-managed tokens (resolved or unresolved), `dashboard` prints/copies/opens a non-tokenized URL to avoid exposing external secrets in terminal output, clipboard history, or browser-launch arguments.
+- If `gateway.auth.token` is SecretRef-managed but unresolved in this command path, the command prints a non-tokenized URL and explicit remediation guidance instead of embedding an invalid token placeholder.