durar-ai 2026.4.4

package/docs/cli/skills.md

@@ -0,0 +1,59 @@
+---
+summary: "CLI reference for `Durar skills` (search/install/update/list/info/check)"
+read_when:
+  - You want to see which skills are available and ready to run
+  - You want to search, install, or update skills from Durar Gateway
+  - You want to debug missing binaries/env/config for skills
+title: "skills"
+---
+
+# `Durar skills`
+
+Inspect local skills and install/update skills from Durar Gateway.
+
+Related:
+
+- Skills system: [Skills](/tools/skills)
+- Skills config: [Skills config](/tools/skills-config)
+- Durar Gateway installs: [Durar Gateway](/tools/Durar Gateway)
+
+## Commands
+
+```bash
+Durar skills search "calendar"
+Durar skills search --limit 20 --json
+Durar skills install <slug>
+Durar skills install <slug> --version <version>
+Durar skills install <slug> --force
+Durar skills update <slug>
+Durar skills update --all
+Durar skills list
+Durar skills list --eligible
+Durar skills list --json
+Durar skills list --verbose
+Durar skills info <name>
+Durar skills info <name> --json
+Durar skills check
+Durar skills check --json
+```
+
+`search`/`install`/`update` use Durar Gateway directly and install into the active
+workspace `skills/` directory. `list`/`info`/`check` still inspect the local
+skills visible to the current workspace and config.
+
+This CLI `install` command downloads skill folders from Durar Gateway. Gateway-backed
+skill dependency installs triggered from onboarding or Skills settings use the
+separate `skills.install` request path instead.
+
+Notes:
+
+- `search [query...]` accepts an optional query; omit it to browse the default
+  Durar Gateway search feed.
+- `search --limit <n>` caps returned results.
+- `install --force` overwrites an existing workspace skill folder for the same
+  slug.
+- `update --all` only updates tracked Durar Gateway installs in the active workspace.
+- `list` is the default action when no subcommand is provided.
+- `list`, `info`, and `check` write their rendered output to stdout. With
+  `--json`, that means the machine-readable payload stays on stdout for pipes
+  and scripts.

package/docs/cli/status.md

@@ -0,0 +1,35 @@
+---
+summary: "CLI reference for `Durar status` (diagnostics, probes, usage snapshots)"
+read_when:
+  - You want a quick diagnosis of channel health + recent session recipients
+  - You want a pasteable “all” status for debugging
+title: "status"
+---
+
+# `Durar status`
+
+Diagnostics for channels + sessions.
+
+```bash
+Durar status
+Durar status --all
+Durar status --deep
+Durar status --usage
+```
+
+Notes:
+
+- `--deep` runs live probes (WhatsApp Web + Telegram + Discord + Slack + Signal).
+- `--usage` prints normalized provider usage windows as `X% left`.
+- MiniMax's raw `usage_percent` / `usagePercent` fields are remaining quota, so Durar inverts them before display; count-based fields win when present. `model_remains` responses prefer the chat-model entry, derive the window label from timestamps when needed, and include the model name in the plan label.
+- When the current session snapshot is sparse, `/status` can backfill token and cache counters from the most recent transcript usage log. Existing nonzero live values still win over transcript fallback values.
+- Transcript fallback can also recover the active runtime model label when the live session entry is missing it. If that transcript model differs from the selected model, status resolves the context window against the recovered runtime model instead of the selected one.
+- For prompt-size accounting, transcript fallback prefers the larger prompt-oriented total when session metadata is missing or smaller, so custom-provider sessions do not collapse to `0` token displays.
+- Output includes per-agent session stores when multiple agents are configured.
+- Overview includes Gateway + node host service install/runtime status when available.
+- Overview includes update channel + git SHA (for source checkouts).
+- Update info surfaces in the Overview; if an update is available, status prints a hint to run `Durar update` (see [Updating](/install/updating)).
+- Read-only status surfaces (`status`, `status --json`, `status --all`) resolve supported SecretRefs for their targeted config paths when possible.
+- If a supported channel SecretRef is configured but unavailable in the current command path, status stays read-only and reports degraded output instead of crashing. Human output shows warnings such as “configured token unavailable in this command path”, and JSON output includes `secretDiagnostics`.
+- When command-local SecretRef resolution succeeds, status prefers the resolved snapshot and clears transient “secret unavailable” channel markers from the final output.
+- `status --all` includes a Secrets overview row and a diagnosis section that summarizes secret diagnostics (truncated for readability) without stopping report generation.

package/docs/cli/system.md

@@ -0,0 +1,71 @@
+---
+summary: "CLI reference for `Durar system` (system events, heartbeat, presence)"
+read_when:
+  - You want to enqueue a system event without creating a cron job
+  - You need to enable or disable heartbeats
+  - You want to inspect system presence entries
+title: "system"
+---
+
+# `Durar system`
+
+System-level helpers for the Gateway: enqueue system events, control heartbeats,
+and view presence.
+
+All `system` subcommands use Gateway RPC and accept the shared client flags:
+
+- `--url <url>`
+- `--token <token>`
+- `--timeout <ms>`
+- `--expect-final`
+
+## Common commands
+
+```bash
+Durar system event --text "Check for urgent follow-ups" --mode now
+Durar system event --text "Check for urgent follow-ups" --url ws://127.0.0.1:18789 --token "$Durar_GATEWAY_TOKEN"
+Durar system heartbeat enable
+Durar system heartbeat last
+Durar system presence
+```
+
+## `system event`
+
+Enqueue a system event on the **main** session. The next heartbeat will inject
+it as a `System:` line in the prompt. Use `--mode now` to trigger the heartbeat
+immediately; `next-heartbeat` waits for the next scheduled tick.
+
+Flags:
+
+- `--text <text>`: required system event text.
+- `--mode <mode>`: `now` or `next-heartbeat` (default).
+- `--json`: machine-readable output.
+- `--url`, `--token`, `--timeout`, `--expect-final`: shared Gateway RPC flags.
+
+## `system heartbeat last|enable|disable`
+
+Heartbeat controls:
+
+- `last`: show the last heartbeat event.
+- `enable`: turn heartbeats back on (use this if they were disabled).
+- `disable`: pause heartbeats.
+
+Flags:
+
+- `--json`: machine-readable output.
+- `--url`, `--token`, `--timeout`, `--expect-final`: shared Gateway RPC flags.
+
+## `system presence`
+
+List the current system presence entries the Gateway knows about (nodes,
+instances, and similar status lines).
+
+Flags:
+
+- `--json`: machine-readable output.
+- `--url`, `--token`, `--timeout`, `--expect-final`: shared Gateway RPC flags.
+
+## Notes
+
+- Requires a running Gateway reachable by your current config (local or remote).
+- System events are ephemeral and not persisted across restarts.

package/docs/cli/tui.md

@@ -0,0 +1,30 @@
+---
+summary: "CLI reference for `Durar tui` (terminal UI connected to the Gateway)"
+read_when:
+  - You want a terminal UI for the Gateway (remote-friendly)
+  - You want to pass url/token/session from scripts
+title: "tui"
+---
+
+# `Durar tui`
+
+Open the terminal UI connected to the Gateway.
+
+Related:
+
+- TUI guide: [TUI](/web/tui)
+
+Notes:
+
+- `tui` resolves configured gateway auth SecretRefs for token/password auth when possible (`env`/`file`/`exec` providers).
+- When launched from inside a configured agent workspace directory, TUI auto-selects that agent for the session key default (unless `--session` is explicitly `agent:<id>:...`).
+
+## Examples
+
+```bash
+Durar tui
+Durar tui --url ws://127.0.0.1:18789 --token <token>
+Durar tui --session main --deliver
+# when run inside an agent workspace, infers that agent automatically
+Durar tui --session bugfix
+```

package/docs/cli/uninstall.md

@@ -0,0 +1,39 @@
+---
+summary: "CLI reference for `Durar uninstall` (remove gateway service + local data)"
+read_when:
+  - You want to remove the gateway service and/or local state
+  - You want a dry-run first
+title: "uninstall"
+---
+
+# `Durar uninstall`
+
+Uninstall the gateway service + local data (CLI remains).
+
+Options:
+
+- `--service`: remove the gateway service
+- `--state`: remove state and config
+- `--workspace`: remove workspace directories
+- `--app`: remove the macOS app
+- `--all`: remove service, state, workspace, and app
+- `--yes`: skip confirmation prompts
+- `--non-interactive`: disable prompts; requires `--yes`
+- `--dry-run`: print actions without removing files
+
+Examples:
+
+```bash
+Durar backup create
+Durar uninstall
+Durar uninstall --service --yes --non-interactive
+Durar uninstall --state --workspace --yes --non-interactive
+Durar uninstall --all --yes
+Durar uninstall --dry-run
+```
+
+Notes:
+
+- Run `Durar backup create` first if you want a restorable snapshot before removing state or workspaces.
+- `--all` is shorthand for removing service, state, workspace, and app together.
+- `--non-interactive` requires `--yes`.

package/docs/cli/update.md

@@ -0,0 +1,113 @@
+---
+summary: "CLI reference for `Durar update` (safe-ish source update + gateway auto-restart)"
+read_when:
+  - You want to update a source checkout safely
+  - You need to understand `--update` shorthand behavior
+title: "update"
+---
+
+# `Durar update`
+
+Safely update Durar and switch between stable/beta/dev channels.
+
+If you installed via **npm/pnpm/bun** (global install, no git metadata),
+updates happen via the package-manager flow in [Updating](/install/updating).
+
+## Usage
+
+```bash
+Durar update
+Durar update status
+Durar update wizard
+Durar update --channel beta
+Durar update --channel dev
+Durar update --tag beta
+Durar update --tag main
+Durar update --dry-run
+Durar update --no-restart
+Durar update --yes
+Durar update --json
+Durar --update
+```
+
+## Options
+
+- `--no-restart`: skip restarting the Gateway service after a successful update.
+- `--channel <stable|beta|dev>`: set the update channel (git + npm; persisted in config).
+- `--tag <dist-tag|version|spec>`: override the package target for this update only. For package installs, `main` maps to `github:Durar/Durar#main`.
+- `--dry-run`: preview planned update actions (channel/tag/target/restart flow) without writing config, installing, syncing plugins, or restarting.
+- `--json`: print machine-readable `UpdateRunResult` JSON.
+- `--timeout <seconds>`: per-step timeout (default is 1200s).
+- `--yes`: skip confirmation prompts (for example downgrade confirmation)
+
+Note: downgrades require confirmation because older versions can break configuration.
+
+## `update status`
+
+Show the active update channel + git tag/branch/SHA (for source checkouts), plus update availability.
+
+```bash
+Durar update status
+Durar update status --json
+Durar update status --timeout 10
+```
+
+Options:
+
+- `--json`: print machine-readable status JSON.
+- `--timeout <seconds>`: timeout for checks (default is 3s).
+
+## `update wizard`
+
+Interactive flow to pick an update channel and confirm whether to restart the Gateway
+after updating (default is to restart). If you select `dev` without a git checkout, it
+offers to create one.
+
+Options:
+
+- `--timeout <seconds>`: timeout for each update step (default `1200`)
+
+## What it does
+
+When you switch channels explicitly (`--channel ...`), Durar also keeps the
+install method aligned:
+
+- `dev` → ensures a git checkout (default: `~/Durar`, override with `Durar_GIT_DIR`),
+  updates it, and installs the global CLI from that checkout.
+- `stable` → installs from npm using `latest`.
+- `beta` → prefers npm dist-tag `beta`, but falls back to `latest` when beta is
+  missing or older than the current stable release.
+
+The Gateway core auto-updater (when enabled via config) reuses this same update path.
+
+## Git checkout flow
+
+Channels:
+
+- `stable`: checkout the latest non-beta tag, then build + doctor.
+- `beta`: prefer the latest `-beta` tag, but fall back to the latest stable tag
+  when beta is missing or older.
+- `dev`: checkout `main`, then fetch + rebase.
+
+High-level:
+
+1. Requires a clean worktree (no uncommitted changes).
+2. Switches to the selected channel (tag or branch).
+3. Fetches upstream (dev only).
+4. Dev only: preflight lint + TypeScript build in a temp worktree; if the tip fails, walks back up to 10 commits to find the newest clean build.
+5. Rebases onto the selected commit (dev only).
+6. Installs deps (pnpm preferred; npm fallback; bun remains available as a secondary compatibility fallback).
+7. Builds + builds the Control UI.
+8. Runs `Durar doctor` as the final “safe update” check.
+9. Syncs plugins to the active channel (dev uses bundled extensions; stable/beta uses npm) and updates npm-installed plugins.
+
+## `--update` shorthand
+
+`Durar --update` rewrites to `Durar update` (useful for shells and launcher scripts).
+
+## See also
+
+- `Durar doctor` (offers to run update first on git checkouts)
+- [Development channels](/install/development-channels)
+- [Updating](/install/updating)
+- [CLI reference](/cli)

package/docs/cli/voicecall.md

@@ -0,0 +1,34 @@
+---
+summary: "CLI reference for `Durar voicecall` (voice-call plugin command surface)"
+read_when:
+  - You use the voice-call plugin and want the CLI entry points
+  - You want quick examples for `voicecall call|continue|status|tail|expose`
+title: "voicecall"
+---
+
+# `Durar voicecall`
+
+`voicecall` is a plugin-provided command. It only appears if the voice-call plugin is installed and enabled.
+
+Primary doc:
+
+- Voice-call plugin: [Voice Call](/plugins/voice-call)
+
+## Common commands
+
+```bash
+Durar voicecall status --call-id <id>
+Durar voicecall call --to "+15555550123" --message "Hello" --mode notify
+Durar voicecall continue --call-id <id> --message "Any questions?"
+Durar voicecall end --call-id <id>
+```
+
+## Exposing webhooks (Tailscale)
+
+```bash
+Durar voicecall expose --mode serve
+Durar voicecall expose --mode funnel
+Durar voicecall expose --mode off
+```
+
+Security note: only expose the webhook endpoint to networks you trust. Prefer Tailscale Serve over Funnel when possible.

package/docs/cli/webhooks.md

@@ -0,0 +1,91 @@
+---
+summary: "CLI reference for `Durar webhooks` (webhook helpers + Gmail Pub/Sub)"
+read_when:
+  - You want to wire Gmail Pub/Sub events into Durar
+  - You want webhook helper commands
+title: "webhooks"
+---
+
+# `Durar webhooks`
+
+Webhook helpers and integrations (Gmail Pub/Sub, webhook helpers).
+
+Related:
+
+- Webhooks: [Webhooks](/automation/cron-jobs#webhooks)
+- Gmail Pub/Sub: [Gmail Pub/Sub](/automation/cron-jobs#gmail-pubsub-integration)
+
+## Gmail
+
+```bash
+Durar webhooks gmail setup --account you@example.com
+Durar webhooks gmail run
+```
+
+### `webhooks gmail setup`
+
+Configure Gmail watch, Pub/Sub, and Durar webhook delivery.
+
+Required:
+
+- `--account <email>`
+
+Options:
+
+- `--project <id>`
+- `--topic <name>`
+- `--subscription <name>`
+- `--label <label>`
+- `--hook-url <url>`
+- `--hook-token <token>`
+- `--push-token <token>`
+- `--bind <host>`
+- `--port <port>`
+- `--path <path>`
+- `--include-body`
+- `--max-bytes <n>`
+- `--renew-minutes <n>`
+- `--tailscale <funnel|serve|off>`
+- `--tailscale-path <path>`
+- `--tailscale-target <target>`
+- `--push-endpoint <url>`
+- `--json`
+
+Examples:
+
+```bash
+Durar webhooks gmail setup --account you@example.com
+Durar webhooks gmail setup --account you@example.com --project my-gcp-project --json
+Durar webhooks gmail setup --account you@example.com --hook-url https://gateway.example.com/hooks/gmail
+```
+
+### `webhooks gmail run`
+
+Run `gog watch serve` plus the watch auto-renew loop.
+
+Options:
+
+- `--account <email>`
+- `--topic <topic>`
+- `--subscription <name>`
+- `--label <label>`
+- `--hook-url <url>`
+- `--hook-token <token>`
+- `--push-token <token>`
+- `--bind <host>`
+- `--port <port>`
+- `--path <path>`
+- `--include-body`
+- `--max-bytes <n>`
+- `--renew-minutes <n>`
+- `--tailscale <funnel|serve|off>`
+- `--tailscale-path <path>`
+- `--tailscale-target <target>`
+
+Example:
+
+```bash
+Durar webhooks gmail run --account you@example.com
+```
+
+See [Gmail Pub/Sub documentation](/automation/cron-jobs#gmail-pubsub-integration) for the end-to-end setup flow and operational details.

package/docs/concepts/agent-loop.md

@@ -0,0 +1,168 @@
+---
+summary: "Agent loop lifecycle, streams, and wait semantics"
+read_when:
+  - You need an exact walkthrough of the agent loop or lifecycle events
+title: "Agent Loop"
+---
+
+# Agent Loop (Durar)
+
+An agentic loop is the full “real” run of an agent: intake → context assembly → model inference →
+tool execution → streaming replies → persistence. It’s the authoritative path that turns a message
+into actions and a final reply, while keeping session state consistent.
+
+In Durar, a loop is a single, serialized run per session that emits lifecycle and stream events
+as the model thinks, calls tools, and streams output. This doc explains how that authentic loop is
+wired end-to-end.
+
+## Entry points
+
+- Gateway RPC: `agent` and `agent.wait`.
+- CLI: `agent` command.
+
+## How it works (high-level)
+
+1. `agent` RPC validates params, resolves session (sessionKey/sessionId), persists session metadata, returns `{ runId, acceptedAt }` immediately.
+2. `agentCommand` runs the agent:
+   - resolves model + thinking/verbose defaults
+   - loads skills snapshot
+   - calls `runEmbeddedPiAgent` (pi-agent-core runtime)
+   - emits **lifecycle end/error** if the embedded loop does not emit one
+3. `runEmbeddedPiAgent`:
+   - serializes runs via per-session + global queues
+   - resolves model + auth profile and builds the pi session
+   - subscribes to pi events and streams assistant/tool deltas
+   - enforces timeout -> aborts run if exceeded
+   - returns payloads + usage metadata
+4. `subscribeEmbeddedPiSession` bridges pi-agent-core events to Durar `agent` stream:
+   - tool events => `stream: "tool"`
+   - assistant deltas => `stream: "assistant"`
+   - lifecycle events => `stream: "lifecycle"` (`phase: "start" | "end" | "error"`)
+5. `agent.wait` uses `waitForAgentRun`:
+   - waits for **lifecycle end/error** for `runId`
+   - returns `{ status: ok|error|timeout, startedAt, endedAt, error? }`
+
+## Queueing + concurrency
+
+- Runs are serialized per session key (session lane) and optionally through a global lane.
+- This prevents tool/session races and keeps session history consistent.
+- Messaging channels can choose queue modes (collect/steer/followup) that feed this lane system.
+  See [Command Queue](/concepts/queue).
+
+## Session + workspace preparation
+
+- Workspace is resolved and created; sandboxed runs may redirect to a sandbox workspace root.
+- Skills are loaded (or reused from a snapshot) and injected into env and prompt.
+- Bootstrap/context files are resolved and injected into the system prompt report.
+- A session write lock is acquired; `SessionManager` is opened and prepared before streaming.
+
+## Prompt assembly + system prompt
+
+- System prompt is built from Durar’s base prompt, skills prompt, bootstrap context, and per-run overrides.
+- Model-specific limits and compaction reserve tokens are enforced.
+- See [System prompt](/concepts/system-prompt) for what the model sees.
+
+## Hook points (where you can intercept)
+
+Durar has two hook systems:
+
+- **Internal hooks** (Gateway hooks): event-driven scripts for commands and lifecycle events.
+- **Plugin hooks**: extension points inside the agent/tool lifecycle and gateway pipeline.
+
+### Internal hooks (Gateway hooks)
+
+- **`agent:bootstrap`**: runs while building bootstrap files before the system prompt is finalized.
+  Use this to add/remove bootstrap context files.
+- **Command hooks**: `/new`, `/reset`, `/stop`, and other command events (see Hooks doc).
+
+See [Hooks](/automation/hooks) for setup and examples.
+
+### Plugin hooks (agent + gateway lifecycle)
+
+These run inside the agent loop or gateway pipeline:
+
+- **`before_model_resolve`**: runs pre-session (no `messages`) to deterministically override provider/model before model resolution.
+- **`before_prompt_build`**: runs after session load (with `messages`) to inject `prependContext`, `systemPrompt`, `prependSystemContext`, or `appendSystemContext` before prompt submission. Use `prependContext` for per-turn dynamic text and system-context fields for stable guidance that should sit in system prompt space.
+- **`before_agent_start`**: legacy compatibility hook that may run in either phase; prefer the explicit hooks above.
+- **`before_agent_reply`**: runs after inline actions and before the LLM call, letting a plugin claim the turn and return a synthetic reply or silence the turn entirely.
+- **`agent_end`**: inspect the final message list and run metadata after completion.
+- **`before_compaction` / `after_compaction`**: observe or annotate compaction cycles.
+- **`before_tool_call` / `after_tool_call`**: intercept tool params/results.
+- **`before_install`**: inspect built-in scan findings and optionally block skill or plugin installs.
+- **`tool_result_persist`**: synchronously transform tool results before they are written to the session transcript.
+- **`message_received` / `message_sending` / `message_sent`**: inbound + outbound message hooks.
+- **`session_start` / `session_end`**: session lifecycle boundaries.
+- **`gateway_start` / `gateway_stop`**: gateway lifecycle events.
+
+Hook decision rules for outbound/tool guards:
+
+- `before_tool_call`: `{ block: true }` is terminal and stops lower-priority handlers.
+- `before_tool_call`: `{ block: false }` is a no-op and does not clear a prior block.
+- `before_install`: `{ block: true }` is terminal and stops lower-priority handlers.
+- `before_install`: `{ block: false }` is a no-op and does not clear a prior block.
+- `message_sending`: `{ cancel: true }` is terminal and stops lower-priority handlers.
+- `message_sending`: `{ cancel: false }` is a no-op and does not clear a prior cancel.
+
+See [Plugin hooks](/plugins/architecture#provider-runtime-hooks) for the hook API and registration details.
+
+## Streaming + partial replies
+
+- Assistant deltas are streamed from pi-agent-core and emitted as `assistant` events.
+- Block streaming can emit partial replies either on `text_end` or `message_end`.
+- Reasoning streaming can be emitted as a separate stream or as block replies.
+- See [Streaming](/concepts/streaming) for chunking and block reply behavior.
+
+## Tool execution + messaging tools
+
+- Tool start/update/end events are emitted on the `tool` stream.
+- Tool results are sanitized for size and image payloads before logging/emitting.
+- Messaging tool sends are tracked to suppress duplicate assistant confirmations.
+
+## Reply shaping + suppression
+
+- Final payloads are assembled from:
+  - assistant text (and optional reasoning)
+  - inline tool summaries (when verbose + allowed)
+  - assistant error text when the model errors
+- The exact silent token `NO_REPLY` / `no_reply` is filtered from outgoing
+  payloads.
+- Messaging tool duplicates are removed from the final payload list.
+- If no renderable payloads remain and a tool errored, a fallback tool error reply is emitted
+  (unless a messaging tool already sent a user-visible reply).
+
+## Compaction + retries
+
+- Auto-compaction emits `compaction` stream events and can trigger a retry.
+- On retry, in-memory buffers and tool summaries are reset to avoid duplicate output.
+- See [Compaction](/concepts/compaction) for the compaction pipeline.
+
+## Event streams (today)
+
+- `lifecycle`: emitted by `subscribeEmbeddedPiSession` (and as a fallback by `agentCommand`)
+- `assistant`: streamed deltas from pi-agent-core
+- `tool`: streamed tool events from pi-agent-core
+
+## Chat channel handling
+
+- Assistant deltas are buffered into chat `delta` messages.
+- A chat `final` is emitted on **lifecycle end/error**.
+
+## Timeouts
+
+- `agent.wait` default: 30s (just the wait). `timeoutMs` param overrides.
+- Agent runtime: `agents.defaults.timeoutSeconds` default 172800s (48 hours); enforced in `runEmbeddedPiAgent` abort timer.
+
+## Where things can end early
+
+- Agent timeout (abort)
+- AbortSignal (cancel)
+- Gateway disconnect or RPC timeout
+- `agent.wait` timeout (wait-only, does not stop agent)
+
+## Related
+
+- [Tools](/tools) — available agent tools
+- [Hooks](/automation/hooks) — event-driven scripts triggered by agent lifecycle events
+- [Compaction](/concepts/compaction) — how long conversations are summarized
+- [Exec Approvals](/tools/exec-approvals) — approval gates for shell commands
+- [Thinking](/tools/thinking) — thinking/reasoning level configuration