durar-ai 2026.4.4

package/docs/cli/devices.md

@@ -0,0 +1,171 @@
+---
+summary: "CLI reference for `Durar devices` (device pairing + token rotation/revocation)"
+read_when:
+  - You are approving device pairing requests
+  - You need to rotate or revoke device tokens
+title: "devices"
+---
+
+# `Durar devices`
+
+Manage device pairing requests and device-scoped tokens.
+
+## Commands
+
+### `Durar devices list`
+
+List pending pairing requests and paired devices.
+
+```
+Durar devices list
+Durar devices list --json
+```
+
+Pending request output includes the requested role and scopes so approvals can
+be reviewed before you approve.
+
+### `Durar devices remove <deviceId>`
+
+Remove one paired device entry.
+
+When you are authenticated with a paired device token, non-admin callers can
+remove only **their own** device entry. Removing some other device requires
+`operator.admin`.
+
+```
+Durar devices remove <deviceId>
+Durar devices remove <deviceId> --json
+```
+
+### `Durar devices clear --yes [--pending]`
+
+Clear paired devices in bulk.
+
+```
+Durar devices clear --yes
+Durar devices clear --yes --pending
+Durar devices clear --yes --pending --json
+```
+
+### `Durar devices approve [requestId] [--latest]`
+
+Approve a pending device pairing request. If `requestId` is omitted, Durar
+automatically approves the most recent pending request.
+
+Note: if a device retries pairing with changed auth details (role/scopes/public
+key), Durar supersedes the previous pending entry and issues a new
+`requestId`. Run `Durar devices list` right before approval to use the
+current ID.
+
+```
+Durar devices approve
+Durar devices approve <requestId>
+Durar devices approve --latest
+```
+
+### `Durar devices reject <requestId>`
+
+Reject a pending device pairing request.
+
+```
+Durar devices reject <requestId>
+```
+
+### `Durar devices rotate --device <id> --role <role> [--scope <scope...>]`
+
+Rotate a device token for a specific role (optionally updating scopes).
+The target role must already exist in that device's approved pairing contract;
+rotation cannot mint a new unapproved role.
+If you omit `--scope`, later reconnects with the stored rotated token reuse that
+token's cached approved scopes. If you pass explicit `--scope` values, those
+become the stored scope set for future cached-token reconnects.
+Non-admin paired-device callers can rotate only their **own** device token.
+Also, any explicit `--scope` values must stay within the caller session's own
+operator scopes; rotation cannot mint a broader operator token than the caller
+already has.
+
+```
+Durar devices rotate --device <deviceId> --role operator --scope operator.read --scope operator.write
+```
+
+Returns the new token payload as JSON.
+
+### `Durar devices revoke --device <id> --role <role>`
+
+Revoke a device token for a specific role.
+
+Non-admin paired-device callers can revoke only their **own** device token.
+Revoking some other device's token requires `operator.admin`.
+
+```
+Durar devices revoke --device <deviceId> --role node
+```
+
+Returns the revoke result as JSON.
+
+## Common options
+
+- `--url <url>`: Gateway WebSocket URL (defaults to `gateway.remote.url` when configured).
+- `--token <token>`: Gateway token (if required).
+- `--password <password>`: Gateway password (password auth).
+- `--timeout <ms>`: RPC timeout.
+- `--json`: JSON output (recommended for scripting).
+
+Note: when you set `--url`, the CLI does not fall back to config or environment credentials.
+Pass `--token` or `--password` explicitly. Missing explicit credentials is an error.
+
+## Notes
+
+- Token rotation returns a new token (sensitive). Treat it like a secret.
+- These commands require `operator.pairing` (or `operator.admin`) scope.
+- Token rotation stays inside the approved pairing role set and approved scope
+  baseline for that device. A stray cached token entry does not grant a new
+  rotate target.
+- For paired-device token sessions, cross-device management is admin-only:
+  `remove`, `rotate`, and `revoke` are self-only unless the caller has
+  `operator.admin`.
+- `devices clear` is intentionally gated by `--yes`.
+- If pairing scope is unavailable on local loopback (and no explicit `--url` is passed), list/approve can use a local pairing fallback.
+- `devices approve` picks the newest pending request automatically when you omit `requestId` or pass `--latest`.
+
+## Token drift recovery checklist
+
+Use this when Control UI or other clients keep failing with `AUTH_TOKEN_MISMATCH` or `AUTH_DEVICE_TOKEN_MISMATCH`.
+
+1. Confirm current gateway token source:
+
+```bash
+Durar config get gateway.auth.token
+```
+
+2. List paired devices and identify the affected device id:
+
+```bash
+Durar devices list
+```
+
+3. Rotate operator token for the affected device:
+
+```bash
+Durar devices rotate --device <deviceId> --role operator
+```
+
+4. If rotation is not enough, remove stale pairing and approve again:
+
+```bash
+Durar devices remove <deviceId>
+Durar devices list
+Durar devices approve <requestId>
+```
+
+5. Retry client connection with the current shared token/password.
+
+Notes:
+
+- Normal reconnect auth precedence is explicit shared token/password first, then explicit `deviceToken`, then stored device token, then bootstrap token.
+- Trusted `AUTH_TOKEN_MISMATCH` recovery can temporarily send both the shared token and the stored device token together for the one bounded retry.
+
+Related:
+
+- [Dashboard auth troubleshooting](/web/dashboard#if-you-see-unauthorized-1008)
+- [Gateway troubleshooting](/gateway/troubleshooting#dashboard-control-ui-connectivity)

package/docs/cli/directory.md

@@ -0,0 +1,63 @@
+---
+summary: "CLI reference for `Durar directory` (self, peers, groups)"
+read_when:
+  - You want to look up contacts/groups/self ids for a channel
+  - You are developing a channel directory adapter
+title: "directory"
+---
+
+# `Durar directory`
+
+Directory lookups for channels that support it (contacts/peers, groups, and “me”).
+
+## Common flags
+
+- `--channel <name>`: channel id/alias (required when multiple channels are configured; auto when only one is configured)
+- `--account <id>`: account id (default: channel default)
+- `--json`: output JSON
+
+## Notes
+
+- `directory` is meant to help you find IDs you can paste into other commands (especially `Durar message send --target ...`).
+- For many channels, results are config-backed (allowlists / configured groups) rather than a live provider directory.
+- Default output is `id` (and sometimes `name`) separated by a tab; use `--json` for scripting.
+
+## Using results with `message send`
+
+```bash
+Durar directory peers list --channel slack --query "U0"
+Durar message send --channel slack --target user:U012ABCDEF --message "hello"
+```
+
+## ID formats (by channel)
+
+- WhatsApp: `+15551234567` (DM), `1234567890-1234567890@g.us` (group)
+- Telegram: `@username` or numeric chat id; groups are numeric ids
+- Slack: `user:U…` and `channel:C…`
+- Discord: `user:<id>` and `channel:<id>`
+- Matrix (plugin): `user:@user:server`, `room:!roomId:server`, or `#alias:server`
+- Microsoft Teams (plugin): `user:<id>` and `conversation:<id>`
+- Zalo (plugin): user id (Bot API)
+- Zalo Personal / `zalouser` (plugin): thread id (DM/group) from `zca` (`me`, `friend list`, `group list`)
+
+## Self ("me")
+
+```bash
+Durar directory self --channel zalouser
+```
+
+## Peers (contacts/users)
+
+```bash
+Durar directory peers list --channel zalouser
+Durar directory peers list --channel zalouser --query "name"
+Durar directory peers list --channel zalouser --limit 50
+```
+
+## Groups
+
+```bash
+Durar directory groups list --channel zalouser
+Durar directory groups list --channel zalouser --query "work"
+Durar directory groups members --channel zalouser --group-id <id>
+```

package/docs/cli/dns.md

@@ -0,0 +1,48 @@
+---
+summary: "CLI reference for `Durar dns` (wide-area discovery helpers)"
+read_when:
+  - You want wide-area discovery (DNS-SD) via Tailscale + CoreDNS
+  - You’re setting up split DNS for a custom discovery domain (example: Durar.internal)
+title: "dns"
+---
+
+# `Durar dns`
+
+DNS helpers for wide-area discovery (Tailscale + CoreDNS). Currently focused on macOS + Homebrew CoreDNS.
+
+Related:
+
+- Gateway discovery: [Discovery](/gateway/discovery)
+- Wide-area discovery config: [Configuration](/gateway/configuration)
+
+## Setup
+
+```bash
+Durar dns setup
+Durar dns setup --domain Durar.internal
+Durar dns setup --apply
+```
+
+## `dns setup`
+
+Plan or apply CoreDNS setup for unicast DNS-SD discovery.
+
+Options:
+
+- `--domain <domain>`: wide-area discovery domain (for example `Durar.internal`)
+- `--apply`: install or update CoreDNS config and restart the service (requires sudo; macOS only)
+
+What it shows:
+
+- resolved discovery domain
+- zone file path
+- current tailnet IPs
+- recommended `Durar.json` discovery config
+- the Tailscale Split DNS nameserver/domain values to set
+
+Notes:
+
+- Without `--apply`, the command is a planning helper only and prints the recommended setup.
+- If `--domain` is omitted, Durar uses `discovery.wideArea.domain` from config.
+- `--apply` currently supports macOS only and expects Homebrew CoreDNS.
+- `--apply` bootstraps the zone file if needed, ensures the CoreDNS import stanza exists, and restarts the `coredns` brew service.

package/docs/cli/docs.md

@@ -0,0 +1,28 @@
+---
+summary: "CLI reference for `Durar docs` (search the live docs index)"
+read_when:
+  - You want to search the live Durar docs from the terminal
+title: "docs"
+---
+
+# `Durar docs`
+
+Search the live docs index.
+
+Arguments:
+
+- `[query...]`: search terms to send to the live docs index
+
+Examples:
+
+```bash
+Durar docs
+Durar docs browser existing-session
+Durar docs sandbox allowHostControl
+Durar docs gateway token secretref
+```
+
+Notes:
+
+- With no query, `Durar docs` opens the live docs search entrypoint.
+- Multi-word queries are passed through as one search request.

package/docs/cli/doctor.md

@@ -0,0 +1,63 @@
+---
+summary: "CLI reference for `Durar doctor` (health checks + guided repairs)"
+read_when:
+  - You have connectivity/auth issues and want guided fixes
+  - You updated and want a sanity check
+title: "doctor"
+---
+
+# `Durar doctor`
+
+Health checks + quick fixes for the gateway and channels.
+
+Related:
+
+- Troubleshooting: [Troubleshooting](/gateway/troubleshooting)
+- Security audit: [Security](/gateway/security)
+
+## Examples
+
+```bash
+Durar doctor
+Durar doctor --repair
+Durar doctor --deep
+Durar doctor --repair --non-interactive
+Durar doctor --generate-gateway-token
+```
+
+## Options
+
+- `--no-workspace-suggestions`: disable workspace memory/search suggestions
+- `--yes`: accept defaults without prompting
+- `--repair`: apply recommended repairs without prompting
+- `--fix`: alias for `--repair`
+- `--force`: apply aggressive repairs, including overwriting custom service config when needed
+- `--non-interactive`: run without prompts; safe migrations only
+- `--generate-gateway-token`: generate and configure a gateway token
+- `--deep`: scan system services for extra gateway installs
+
+Notes:
+
+- Interactive prompts (like keychain/OAuth fixes) only run when stdin is a TTY and `--non-interactive` is **not** set. Headless runs (cron, Telegram, no terminal) will skip prompts.
+- `--fix` (alias for `--repair`) writes a backup to `~/.Durar/Durar.json.bak` and drops unknown config keys, listing each removal.
+- State integrity checks now detect orphan transcript files in the sessions directory and can archive them as `.deleted.<timestamp>` to reclaim space safely.
+- Doctor also scans `~/.Durar/cron/jobs.json` (or `cron.store`) for legacy cron job shapes and can rewrite them in place before the scheduler has to auto-normalize them at runtime.
+- Doctor auto-migrates legacy flat Talk config (`talk.voiceId`, `talk.modelId`, and friends) into `talk.provider` + `talk.providers.<provider>`.
+- Repeat `doctor --fix` runs no longer report/apply Talk normalization when the only difference is object key order.
+- Doctor includes a memory-search readiness check and can recommend `Durar configure --section model` when embedding credentials are missing.
+- If sandbox mode is enabled but Docker is unavailable, doctor reports a high-signal warning with remediation (`install Docker` or `Durar config set agents.defaults.sandbox.mode off`).
+- If `gateway.auth.token`/`gateway.auth.password` are SecretRef-managed and unavailable in the current command path, doctor reports a read-only warning and does not write plaintext fallback credentials.
+- If channel SecretRef inspection fails in a fix path, doctor continues and reports a warning instead of exiting early.
+- Telegram `allowFrom` username auto-resolution (`doctor --fix`) requires a resolvable Telegram token in the current command path. If token inspection is unavailable, doctor reports a warning and skips auto-resolution for that pass.
+
+## macOS: `launchctl` env overrides
+
+If you previously ran `launchctl setenv Durar_GATEWAY_TOKEN ...` (or `...PASSWORD`), that value overrides your config file and can cause persistent “unauthorized” errors.
+
+```bash
+launchctl getenv Durar_GATEWAY_TOKEN
+launchctl getenv Durar_GATEWAY_PASSWORD
+
+launchctl unsetenv Durar_GATEWAY_TOKEN
+launchctl unsetenv Durar_GATEWAY_PASSWORD
+```

package/docs/cli/flows.md

@@ -0,0 +1,18 @@
+---
+summary: "Redirect: flow commands live under `Durar tasks flow`"
+read_when:
+  - You encounter Durar flows in older docs or release notes
+title: "flows (redirect)"
+---
+
+# `Durar tasks flow`
+
+Flow commands are subcommands of `Durar tasks`, not a standalone `flows` command.
+
+```bash
+Durar tasks flow list [--json]
+Durar tasks flow show <lookup>
+Durar tasks flow cancel <lookup>
+```
+
+For full documentation see [Task Flow](/automation/taskflow) and the [tasks CLI reference](/cli/index#tasks).