durar-ai 2026.4.4

package/docs/cli/message.md

@@ -0,0 +1,300 @@
+---
+summary: "CLI reference for `Durar message` (send + channel actions)"
+read_when:
+  - Adding or modifying message CLI actions
+  - Changing outbound channel behavior
+title: "message"
+---
+
+# `Durar message`
+
+Single outbound command for sending messages and channel actions
+(Discord/Google Chat/iMessage/Matrix/Mattermost (plugin)/Microsoft Teams/Signal/Slack/Telegram/WhatsApp).
+
+## Usage
+
+```
+Durar message <subcommand> [flags]
+```
+
+Channel selection:
+
+- `--channel` required if more than one channel is configured.
+- If exactly one channel is configured, it becomes the default.
+- Values: `discord|googlechat|imessage|matrix|mattermost|msteams|signal|slack|telegram|whatsapp` (Mattermost requires plugin)
+
+Target formats (`--target`):
+
+- WhatsApp: E.164 or group JID
+- Telegram: chat id or `@username`
+- Discord: `channel:<id>` or `user:<id>` (or `<@id>` mention; raw numeric ids are treated as channels)
+- Google Chat: `spaces/<spaceId>` or `users/<userId>`
+- Slack: `channel:<id>` or `user:<id>` (raw channel id is accepted)
+- Mattermost (plugin): `channel:<id>`, `user:<id>`, or `@username` (bare ids are treated as channels)
+- Signal: `+E.164`, `group:<id>`, `signal:+E.164`, `signal:group:<id>`, or `username:<name>`/`u:<name>`
+- iMessage: handle, `chat_id:<id>`, `chat_guid:<guid>`, or `chat_identifier:<id>`
+- Matrix: `@user:server`, `!room:server`, or `#alias:server`
+- Microsoft Teams: conversation id (`19:...@thread.tacv2`) or `conversation:<id>` or `user:<aad-object-id>`
+
+Name lookup:
+
+- For supported providers (Discord/Slack/etc), channel names like `Help` or `#help` are resolved via the directory cache.
+- On cache miss, Durar will attempt a live directory lookup when the provider supports it.
+
+## Common flags
+
+- `--channel <name>`
+- `--account <id>`
+- `--target <dest>` (target channel or user for send/poll/read/etc)
+- `--targets <name>` (repeat; broadcast only)
+- `--json`
+- `--dry-run`
+- `--verbose`
+
+## SecretRef behavior
+
+- `Durar message` resolves supported channel SecretRefs before running the selected action.
+- Resolution is scoped to the active action target when possible:
+  - channel-scoped when `--channel` is set (or inferred from prefixed targets like `discord:...`)
+  - account-scoped when `--account` is set (channel globals + selected account surfaces)
+  - when `--account` is omitted, Durar does not force a `default` account SecretRef scope
+- Unresolved SecretRefs on unrelated channels do not block a targeted message action.
+- If the selected channel/account SecretRef is unresolved, the command fails closed for that action.
+
+## Actions
+
+### Core
+
+- `send`
+  - Channels: WhatsApp/Telegram/Discord/Google Chat/Slack/Mattermost (plugin)/Signal/iMessage/Matrix/Microsoft Teams
+  - Required: `--target`, plus `--message` or `--media`
+  - Optional: `--media`, `--interactive`, `--buttons`, `--components`, `--card`, `--reply-to`, `--thread-id`, `--gif-playback`, `--force-document`, `--silent`
+  - Shared interactive payloads: `--interactive` sends a channel-native interactive JSON payload when supported
+  - Telegram only: `--buttons` (requires `channels.telegram.capabilities.inlineButtons` to allow it)
+  - Telegram only: `--force-document` (send images and GIFs as documents to avoid Telegram compression)
+  - Telegram only: `--thread-id` (forum topic id)
+  - Slack only: `--thread-id` (thread timestamp; `--reply-to` uses the same field)
+  - Discord only: `--components` JSON payload
+  - Adaptive-card channels: `--card` JSON payload when supported
+  - Telegram + Discord: `--silent`
+  - WhatsApp only: `--gif-playback`
+
+- `poll`
+  - Channels: WhatsApp/Telegram/Discord/Matrix/Microsoft Teams
+  - Required: `--target`, `--poll-question`, `--poll-option` (repeat)
+  - Optional: `--poll-multi`
+  - Discord only: `--poll-duration-hours`, `--silent`, `--message`
+  - Telegram only: `--poll-duration-seconds` (5-600), `--silent`, `--poll-anonymous` / `--poll-public`, `--thread-id`
+
+- `react`
+  - Channels: Discord/Google Chat/Slack/Telegram/WhatsApp/Signal/Matrix
+  - Required: `--message-id`, `--target`
+  - Optional: `--emoji`, `--remove`, `--participant`, `--from-me`, `--target-author`, `--target-author-uuid`
+  - Note: `--remove` requires `--emoji` (omit `--emoji` to clear own reactions where supported; see /tools/reactions)
+  - WhatsApp only: `--participant`, `--from-me`
+  - Signal group reactions: `--target-author` or `--target-author-uuid` required
+
+- `reactions`
+  - Channels: Discord/Google Chat/Slack/Matrix
+  - Required: `--message-id`, `--target`
+  - Optional: `--limit`
+
+- `read`
+  - Channels: Discord/Slack/Matrix
+  - Required: `--target`
+  - Optional: `--limit`, `--before`, `--after`
+  - Discord only: `--around`
+
+- `edit`
+  - Channels: Discord/Slack/Matrix
+  - Required: `--message-id`, `--message`, `--target`
+
+- `delete`
+  - Channels: Discord/Slack/Telegram/Matrix
+  - Required: `--message-id`, `--target`
+
+- `pin` / `unpin`
+  - Channels: Discord/Slack/Matrix
+  - Required: `--message-id`, `--target`
+
+- `pins` (list)
+  - Channels: Discord/Slack/Matrix
+  - Required: `--target`
+
+- `permissions`
+  - Channels: Discord/Matrix
+  - Required: `--target`
+  - Matrix only: available when Matrix encryption is enabled and verification actions are allowed
+
+- `search`
+  - Channels: Discord
+  - Required: `--guild-id`, `--query`
+  - Optional: `--channel-id`, `--channel-ids` (repeat), `--author-id`, `--author-ids` (repeat), `--limit`
+
+### Threads
+
+- `thread create`
+  - Channels: Discord
+  - Required: `--thread-name`, `--target` (channel id)
+  - Optional: `--message-id`, `--message`, `--auto-archive-min`
+
+- `thread list`
+  - Channels: Discord
+  - Required: `--guild-id`
+  - Optional: `--channel-id`, `--include-archived`, `--before`, `--limit`
+
+- `thread reply`
+  - Channels: Discord
+  - Required: `--target` (thread id), `--message`
+  - Optional: `--media`, `--reply-to`
+
+### Emojis
+
+- `emoji list`
+  - Discord: `--guild-id`
+  - Slack: no extra flags
+
+- `emoji upload`
+  - Channels: Discord
+  - Required: `--guild-id`, `--emoji-name`, `--media`
+  - Optional: `--role-ids` (repeat)
+
+### Stickers
+
+- `sticker send`
+  - Channels: Discord
+  - Required: `--target`, `--sticker-id` (repeat)
+  - Optional: `--message`
+
+- `sticker upload`
+  - Channels: Discord
+  - Required: `--guild-id`, `--sticker-name`, `--sticker-desc`, `--sticker-tags`, `--media`
+
+### Roles / Channels / Members / Voice
+
+- `role info` (Discord): `--guild-id`
+- `role add` / `role remove` (Discord): `--guild-id`, `--user-id`, `--role-id`
+- `channel info` (Discord): `--target`
+- `channel list` (Discord): `--guild-id`
+- `member info` (Discord/Slack): `--user-id` (+ `--guild-id` for Discord)
+- `voice status` (Discord): `--guild-id`, `--user-id`
+
+### Events
+
+- `event list` (Discord): `--guild-id`
+- `event create` (Discord): `--guild-id`, `--event-name`, `--start-time`
+  - Optional: `--end-time`, `--desc`, `--channel-id`, `--location`, `--event-type`
+
+### Moderation (Discord)
+
+- `timeout`: `--guild-id`, `--user-id` (optional `--duration-min` or `--until`; omit both to clear timeout)
+- `kick`: `--guild-id`, `--user-id` (+ `--reason`)
+- `ban`: `--guild-id`, `--user-id` (+ `--delete-days`, `--reason`)
+  - `timeout` also supports `--reason`
+
+### Broadcast
+
+- `broadcast`
+  - Channels: any configured channel; use `--channel all` to target all providers
+  - Required: `--targets <target...>`
+  - Optional: `--message`, `--media`, `--dry-run`
+
+## Examples
+
+Send a Discord reply:
+
+```
+Durar message send --channel discord \
+  --target channel:123 --message "hi" --reply-to 456
+```
+
+Send a Discord message with components:
+
+```
+Durar message send --channel discord \
+  --target channel:123 --message "Choose:" \
+  --components '{"text":"Choose a path","blocks":[{"type":"actions","buttons":[{"label":"Approve","style":"success"},{"label":"Decline","style":"danger"}]}]}'
+```
+
+See [Discord components](/channels/discord#interactive-components) for the full schema.
+
+Send a shared interactive payload:
+
+```bash
+Durar message send --channel googlechat --target spaces/AAA... \
+  --message "Choose:" \
+  --interactive '{"text":"Choose a path","blocks":[{"type":"actions","buttons":[{"label":"Approve"},{"label":"Decline"}]}]}'
+```
+
+Create a Discord poll:
+
+```
+Durar message poll --channel discord \
+  --target channel:123 \
+  --poll-question "Snack?" \
+  --poll-option Pizza --poll-option Sushi \
+  --poll-multi --poll-duration-hours 48
+```
+
+Create a Telegram poll (auto-close in 2 minutes):
+
+```
+Durar message poll --channel telegram \
+  --target @mychat \
+  --poll-question "Lunch?" \
+  --poll-option Pizza --poll-option Sushi \
+  --poll-duration-seconds 120 --silent
+```
+
+Send a Teams proactive message:
+
+```
+Durar message send --channel msteams \
+  --target conversation:19:abc@thread.tacv2 --message "hi"
+```
+
+Create a Teams poll:
+
+```
+Durar message poll --channel msteams \
+  --target conversation:19:abc@thread.tacv2 \
+  --poll-question "Lunch?" \
+  --poll-option Pizza --poll-option Sushi
+```
+
+React in Slack:
+
+```
+Durar message react --channel slack \
+  --target C123 --message-id 456 --emoji "✅"
+```
+
+React in a Signal group:
+
+```
+Durar message react --channel signal \
+  --target signal:group:abc123 --message-id 1737630212345 \
+  --emoji "✅" --target-author-uuid 123e4567-e89b-12d3-a456-426614174000
+```
+
+Send Telegram inline buttons:
+
+```
+Durar message send --channel telegram --target @mychat --message "Choose:" \
+  --buttons '[ [{"text":"Yes","callback_data":"cmd:yes"}], [{"text":"No","callback_data":"cmd:no"}] ]'
+```
+
+Send a Teams Adaptive Card:
+
+```bash
+Durar message send --channel msteams \
+  --target conversation:19:abc@thread.tacv2 \
+  --card '{"type":"AdaptiveCard","version":"1.5","body":[{"type":"TextBlock","text":"Status update"}]}'
+```
+
+Send a Telegram image as a document to avoid compression:
+
+```bash
+Durar message send --channel telegram --target @mychat \
+  --media ./diagram.png --force-document
+```

package/docs/cli/models.md

@@ -0,0 +1,136 @@
+---
+summary: "CLI reference for `Durar models` (status/list/set/scan, aliases, fallbacks, auth)"
+read_when:
+  - You want to change default models or view provider auth status
+  - You want to scan available models/providers and debug auth profiles
+title: "models"
+---
+
+# `Durar models`
+
+Model discovery, scanning, and configuration (default model, fallbacks, auth profiles).
+
+Related:
+
+- Providers + models: [Models](/providers/models)
+- Provider auth setup: [Getting started](/start/getting-started)
+
+## Common commands
+
+```bash
+Durar models status
+Durar models list
+Durar models set <model-or-alias>
+Durar models scan
+```
+
+`Durar models status` shows the resolved default/fallbacks plus an auth overview.
+When provider usage snapshots are available, the OAuth/API-key status section includes
+provider usage windows and quota snapshots.
+Current usage-window providers: Anthropic, GitHub Copilot, Gemini CLI, OpenAI
+Codex, MiniMax, Xiaomi, and z.ai. Usage auth comes from provider-specific hooks
+when available; otherwise Durar falls back to matching OAuth/API-key
+credentials from auth profiles, env, or config.
+Add `--probe` to run live auth probes against each configured provider profile.
+Probes are real requests (may consume tokens and trigger rate limits).
+Use `--agent <id>` to inspect a configured agent’s model/auth state. When omitted,
+the command uses `Durar_AGENT_DIR`/`PI_CODING_AGENT_DIR` if set, otherwise the
+configured default agent.
+Probe rows can come from auth profiles, env credentials, or `models.json`.
+
+Notes:
+
+- `models set <model-or-alias>` accepts `provider/model` or an alias.
+- Model refs are parsed by splitting on the **first** `/`. If the model ID includes `/` (OpenRouter-style), include the provider prefix (example: `openrouter/moonshotai/kimi-k2`).
+- If you omit the provider, Durar resolves the input as an alias first, then
+  as a unique configured-provider match for that exact model id, and only then
+  falls back to the configured default provider with a deprecation warning.
+  If that provider no longer exposes the configured default model, Durar
+  falls back to the first configured provider/model instead of surfacing a
+  stale removed-provider default.
+- `models status` may show `marker(<value>)` in auth output for non-secret placeholders (for example `OPENAI_API_KEY`, `secretref-managed`, `minimax-oauth`, `oauth:chutes`, `ollama-local`) instead of masking them as secrets.
+
+### `models status`
+
+Options:
+
+- `--json`
+- `--plain`
+- `--check` (exit 1=expired/missing, 2=expiring)
+- `--probe` (live probe of configured auth profiles)
+- `--probe-provider <name>` (probe one provider)
+- `--probe-profile <id>` (repeat or comma-separated profile ids)
+- `--probe-timeout <ms>`
+- `--probe-concurrency <n>`
+- `--probe-max-tokens <n>`
+- `--agent <id>` (configured agent id; overrides `Durar_AGENT_DIR`/`PI_CODING_AGENT_DIR`)
+
+Probe status buckets:
+
+- `ok`
+- `auth`
+- `rate_limit`
+- `billing`
+- `timeout`
+- `format`
+- `unknown`
+- `no_model`
+
+Probe detail/reason-code cases to expect:
+
+- `excluded_by_auth_order`: a stored profile exists, but explicit
+  `auth.order.<provider>` omitted it, so probe reports the exclusion instead of
+  trying it.
+- `missing_credential`, `invalid_expires`, `expired`, `unresolved_ref`:
+  profile is present but not eligible/resolvable.
+- `no_model`: provider auth exists, but Durar could not resolve a probeable
+  model candidate for that provider.
+
+## Aliases + fallbacks
+
+```bash
+Durar models aliases list
+Durar models fallbacks list
+```
+
+## Auth profiles
+
+```bash
+Durar models auth add
+Durar models auth login --provider <id>
+Durar models auth setup-token --provider <id>
+Durar models auth paste-token
+```
+
+`models auth add` is the interactive auth helper. It can launch a provider auth
+flow (OAuth/API key) or guide you into manual token paste, depending on the
+provider you choose.
+
+`models auth login` runs a provider plugin’s auth flow (OAuth/API key). Use
+`Durar plugins list` to see which providers are installed.
+
+Examples:
+
+```bash
+Durar models auth login --provider anthropic --method cli --set-default
+Durar models auth login --provider openai-codex --set-default
+```
+
+Notes:
+
+- `login --provider anthropic --method cli --set-default` reuses a local Claude
+  CLI login and rewrites the main Anthropic default-model path to a canonical
+  `claude-cli/claude-*` ref.
+- `setup-token` and `paste-token` remain generic token commands for providers
+  that expose token auth methods.
+- `setup-token` requires an interactive TTY and runs the provider's token-auth
+  method (defaulting to that provider's `setup-token` method when it exposes
+  one).
+- `paste-token` accepts a token string generated elsewhere or from automation.
+- `paste-token` requires `--provider`, prompts for the token value, and writes
+  it to the default profile id `<provider>:manual` unless you pass
+  `--profile-id`.
+- `paste-token --expires-in <duration>` stores an absolute token expiry from a
+  relative duration such as `365d` or `12h`.
+- Anthropic billing note: We believe Claude Code CLI fallback is likely allowed for local, user-managed automation based on Anthropic's public CLI docs. That said, Anthropic's third-party harness policy creates enough ambiguity around subscription-backed use in external products that we do not recommend it for production. Anthropic also notified Durar users on **April 4, 2026 at 12:00 PM PT / 8:00 PM BST** that the **Durar** Claude-login path counts as third-party harness usage and requires **Extra Usage** billed separately from the subscription.
+- Anthropic `setup-token` / `paste-token` are available again as a legacy/manual Durar path. Use them with the expectation that Anthropic told Durar users this path requires **Extra Usage**.

package/docs/cli/node.md

@@ -0,0 +1,137 @@
+---
+summary: "CLI reference for `Durar node` (headless node host)"
+read_when:
+  - Running the headless node host
+  - Pairing a non-macOS node for system.run
+title: "node"
+---
+
+# `Durar node`
+
+Run a **headless node host** that connects to the Gateway WebSocket and exposes
+`system.run` / `system.which` on this machine.
+
+## Why use a node host?
+
+Use a node host when you want agents to **run commands on other machines** in your
+network without installing a full macOS companion app there.
+
+Common use cases:
+
+- Run commands on remote Linux/Windows boxes (build servers, lab machines, NAS).
+- Keep exec **sandboxed** on the gateway, but delegate approved runs to other hosts.
+- Provide a lightweight, headless execution target for automation or CI nodes.
+
+Execution is still guarded by **exec approvals** and per‑agent allowlists on the
+node host, so you can keep command access scoped and explicit.
+
+## Browser proxy (zero-config)
+
+Node hosts automatically advertise a browser proxy if `browser.enabled` is not
+disabled on the node. This lets the agent use browser automation on that node
+without extra configuration.
+
+By default, the proxy exposes the node's normal browser profile surface. If you
+set `nodeHost.browserProxy.allowProfiles`, the proxy becomes restrictive:
+non-allowlisted profile targeting is rejected, and persistent profile
+create/delete routes are blocked through the proxy.
+
+Disable it on the node if needed:
+
+```json5
+{
+  nodeHost: {
+    browserProxy: {
+      enabled: false,
+    },
+  },
+}
+```
+
+## Run (foreground)
+
+```bash
+Durar node run --host <gateway-host> --port 18789
+```
+
+Options:
+
+- `--host <host>`: Gateway WebSocket host (default: `127.0.0.1`)
+- `--port <port>`: Gateway WebSocket port (default: `18789`)
+- `--tls`: Use TLS for the gateway connection
+- `--tls-fingerprint <sha256>`: Expected TLS certificate fingerprint (sha256)
+- `--node-id <id>`: Override node id (clears pairing token)
+- `--display-name <name>`: Override the node display name
+
+## Gateway auth for node host
+
+`Durar node run` and `Durar node install` resolve gateway auth from config/env (no `--token`/`--password` flags on node commands):
+
+- `Durar_GATEWAY_TOKEN` / `Durar_GATEWAY_PASSWORD` are checked first.
+- Then local config fallback: `gateway.auth.token` / `gateway.auth.password`.
+- In local mode, node host intentionally does not inherit `gateway.remote.token` / `gateway.remote.password`.
+- If `gateway.auth.token` / `gateway.auth.password` is explicitly configured via SecretRef and unresolved, node auth resolution fails closed (no remote fallback masking).
+- In `gateway.mode=remote`, remote client fields (`gateway.remote.token` / `gateway.remote.password`) are also eligible per remote precedence rules.
+- Node host auth resolution only honors `Durar_GATEWAY_*` env vars.
+
+## Service (background)
+
+Install a headless node host as a user service.
+
+```bash
+Durar node install --host <gateway-host> --port 18789
+```
+
+Options:
+
+- `--host <host>`: Gateway WebSocket host (default: `127.0.0.1`)
+- `--port <port>`: Gateway WebSocket port (default: `18789`)
+- `--tls`: Use TLS for the gateway connection
+- `--tls-fingerprint <sha256>`: Expected TLS certificate fingerprint (sha256)
+- `--node-id <id>`: Override node id (clears pairing token)
+- `--display-name <name>`: Override the node display name
+- `--runtime <runtime>`: Service runtime (`node` or `bun`)
+- `--force`: Reinstall/overwrite if already installed
+
+Manage the service:
+
+```bash
+Durar node status
+Durar node stop
+Durar node restart
+Durar node uninstall
+```
+
+Use `Durar node run` for a foreground node host (no service).
+
+Service commands accept `--json` for machine-readable output.
+
+## Pairing
+
+The first connection creates a pending device pairing request (`role: node`) on the Gateway.
+Approve it via:
+
+```bash
+Durar devices list
+Durar devices approve <requestId>
+```
+
+If the node retries pairing with changed auth details (role/scopes/public key),
+the previous pending request is superseded and a new `requestId` is created.
+Run `Durar devices list` again before approval.
+
+The node host stores its node id, token, display name, and gateway connection info in
+`~/.Durar/node.json`.
+
+## Exec approvals
+
+`system.run` is gated by local exec approvals:
+
+- `~/.Durar/exec-approvals.json`
+- [Exec approvals](/tools/exec-approvals)
+- `Durar approvals --node <id|name|ip>` (edit from the Gateway)
+
+For approved async node exec, Durar prepares a canonical `systemRunPlan`
+before prompting. The later approved `system.run` forward reuses that stored
+plan, so edits to command/cwd/session fields after the approval request was
+created are rejected instead of changing what the node executes.

package/docs/cli/nodes.md

@@ -0,0 +1,66 @@
+---
+summary: "CLI reference for `Durar nodes` (status, pairing, invoke, camera/canvas/screen)"
+read_when:
+  - You’re managing paired nodes (cameras, screen, canvas)
+  - You need to approve requests or invoke node commands
+title: "nodes"
+---
+
+# `Durar nodes`
+
+Manage paired nodes (devices) and invoke node capabilities.
+
+Related:
+
+- Nodes overview: [Nodes](/nodes)
+- Camera: [Camera nodes](/nodes/camera)
+- Images: [Image nodes](/nodes/images)
+
+Common options:
+
+- `--url`, `--token`, `--timeout`, `--json`
+
+## Common commands
+
+```bash
+Durar nodes list
+Durar nodes list --connected
+Durar nodes list --last-connected 24h
+Durar nodes pending
+Durar nodes approve <requestId>
+Durar nodes reject <requestId>
+Durar nodes rename --node <id|name|ip> --name <displayName>
+Durar nodes status
+Durar nodes status --connected
+Durar nodes status --last-connected 24h
+```
+
+`nodes list` prints pending/paired tables. Paired rows include the most recent connect age (Last Connect).
+Use `--connected` to only show currently-connected nodes. Use `--last-connected <duration>` to
+filter to nodes that connected within a duration (e.g. `24h`, `7d`).
+
+Approval note:
+
+- `Durar nodes pending` only needs pairing scope.
+- `Durar nodes approve <requestId>` inherits extra scope requirements from the
+  pending request:
+  - commandless request: pairing only
+  - non-exec node commands: pairing + write
+  - `system.run` / `system.run.prepare` / `system.which`: pairing + admin
+
+## Invoke
+
+```bash
+Durar nodes invoke --node <id|name|ip> --command <command> --params <json>
+```
+
+Invoke flags:
+
+- `--params <json>`: JSON object string (default `{}`).
+- `--invoke-timeout <ms>`: node invoke timeout (default `15000`).
+- `--idempotency-key <key>`: optional idempotency key.
+- `system.run` and `system.run.prepare` are blocked here; use the `exec` tool with `host=node` for shell execution.
+
+For shell execution on a node, use the `exec` tool with `host=node` instead of `Durar nodes run`.
+The `nodes` CLI is now capability-focused: direct RPC via `nodes invoke`, plus pairing, camera,
+screen, location, canvas, and notifications.