nodmix 2026.5.25

package/docs/cli/browser.md

@@ -0,0 +1,307 @@
+---
+summary: "CLI reference for `nodmix browser` (lifecycle, profiles, tabs, actions, state, and debugging)"
+read_when:
+  - You use `nodmix 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"
+---
+
+# `nodmix browser`
+
+Manage Nodmix'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
+nodmix browser profiles
+nodmix browser --browser-profile nodmix start
+nodmix browser --browser-profile nodmix open https://example.com
+nodmix browser --browser-profile nodmix snapshot
+```
+
+Agents can run the same readiness check with `browser({ action: "doctor" })`.
+
+## Quick troubleshooting
+
+If `start` fails with `not reachable after start`, troubleshoot CDP readiness first. If `start` and `tabs` succeed but `open` or `navigate` fails, the browser control plane is healthy and the failure is usually navigation SSRF policy.
+
+Minimal sequence:
+
+```bash
+nodmix browser --browser-profile nodmix doctor
+nodmix browser --browser-profile nodmix start
+nodmix browser --browser-profile nodmix tabs
+nodmix browser --browser-profile nodmix open https://example.com
+```
+
+Detailed guidance: [Browser troubleshooting](/tools/browser#cdp-startup-failure-vs-navigation-ssrf-block)
+
+## Lifecycle
+
+```bash
+nodmix browser status
+nodmix browser doctor
+nodmix browser doctor --deep
+nodmix browser start
+nodmix browser start --headless
+nodmix browser stop
+nodmix browser --browser-profile nodmix reset-profile
+```
+
+Notes:
+
+- `doctor --deep` adds a live snapshot probe. It is useful when basic CDP
+  readiness is green but you want proof that the current tab can be inspected.
+- For `attachOnly` and remote CDP profiles, `nodmix browser stop` closes the
+  active control session and clears temporary emulation overrides even when
+  Nodmix did not launch the browser process itself.
+- For local managed profiles, `nodmix browser stop` stops the spawned browser
+  process.
+- `nodmix browser start --headless` applies only to that start request and
+  only when Nodmix launches a local managed browser. It does not rewrite
+  `browser.headless` or profile config, and it is a no-op for an already-running
+  browser.
+- On Linux hosts without `DISPLAY` or `WAYLAND_DISPLAY`, local managed profiles
+  run headless automatically unless `NODMIX_BROWSER_HEADLESS=0`,
+  `browser.headless=false`, or `browser.profiles.<name>.headless=false`
+  explicitly requests a visible browser.
+
+## If the command is missing
+
+If `nodmix browser` is an unknown command, check `plugins.allow` in
+`~/.nodmix/nodmix.json`.
+
+When `plugins.allow` is present, list the bundled browser plugin explicitly
+unless the config already has a root `browser` block:
+
+```json5
+{
+  plugins: {
+    allow: ["telegram", "browser"],
+  },
+}
+```
+
+An explicit root `browser` block, for example `browser.enabled=true` or
+`browser.profiles.<name>`, also activates the bundled browser plugin under a
+restrictive plugin allowlist.
+
+Related: [Browser tool](/tools/browser#missing-browser-command-or-tool)
+
+## Profiles
+
+Profiles are named browser routing configs. In practice:
+
+- `nodmix`: launches or attaches to a dedicated Nodmix-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
+nodmix browser profiles
+nodmix browser create-profile --name work --color "#FF5A36"
+nodmix browser create-profile --name chrome-live --driver existing-session
+nodmix browser create-profile --name remote --cdp-url https://browser-host.example.com
+nodmix browser delete-profile --name work
+```
+
+Use a specific profile:
+
+```bash
+nodmix browser --browser-profile work tabs
+```
+
+## Tabs
+
+```bash
+nodmix browser tabs
+nodmix browser tab new --label docs
+nodmix browser tab label t1 docs
+nodmix browser tab select 2
+nodmix browser tab close 2
+nodmix browser open https://docs.nodmix.ai --label docs
+nodmix browser focus docs
+nodmix browser close t1
+```
+
+`tabs` returns `suggestedTargetId` first, then the stable `tabId` such as `t1`,
+the optional label, and the raw `targetId`. Agents should pass
+`suggestedTargetId` back into `focus`, `close`, snapshots, and actions. You can
+assign a label with `open --label`, `tab new --label`, or `tab label`; labels,
+tab ids, raw target ids, and unique target-id prefixes are all accepted.
+When Chromium replaces the underlying raw target during a navigation or form
+submit, Nodmix keeps the stable `tabId`/label attached to the replacement tab
+when it can prove the match. Raw target ids remain volatile; prefer
+`suggestedTargetId`.
+
+## Snapshot / screenshot / actions
+
+Snapshot:
+
+```bash
+nodmix browser snapshot
+nodmix browser snapshot --urls
+```
+
+Screenshot:
+
+```bash
+nodmix browser screenshot
+nodmix browser screenshot --full-page
+nodmix browser screenshot --ref e12
+nodmix browser screenshot --labels
+```
+
+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.
+- `--labels` overlays current snapshot refs on the screenshot.
+- `snapshot --urls` appends discovered link destinations to AI snapshots so
+  agents can choose direct navigation targets instead of guessing from link
+  text alone.
+
+Navigate/click/type (ref-based UI automation):
+
+```bash
+nodmix browser navigate https://example.com
+nodmix browser click <ref>
+nodmix browser click-coords 120 340
+nodmix browser type <ref> "hello"
+nodmix browser press Enter
+nodmix browser hover <ref>
+nodmix browser scrollintoview <ref>
+nodmix browser drag <startRef> <endRef>
+nodmix browser select <ref> OptionA OptionB
+nodmix browser fill --fields '[{"ref":"1","value":"Ada"}]'
+nodmix browser wait --text "Done"
+nodmix browser evaluate --fn '(el) => el.textContent' --ref <ref>
+nodmix browser evaluate --timeout-ms 30000 --fn 'async () => { await window.ready; return true; }'
+```
+
+Use `evaluate --timeout-ms <ms>` when the page-side function may need longer
+than the default evaluate timeout.
+
+Action responses return the current raw `targetId` after action-triggered page
+replacement when Nodmix can prove the replacement tab. Scripts should still
+store and pass `suggestedTargetId`/labels for long-lived workflows.
+
+File + dialog helpers:
+
+```bash
+nodmix browser upload /tmp/nodmix/uploads/file.pdf --ref <ref>
+nodmix browser waitfordownload
+nodmix browser download <ref> report.pdf
+nodmix browser dialog --accept
+nodmix browser dialog --dismiss --dialog-id d1
+```
+
+Managed Chrome profiles save ordinary click-triggered downloads into the Nodmix
+downloads directory (`/tmp/nodmix/downloads` by default, or the configured temp
+root). Use `waitfordownload` or `download` when the agent needs to wait for a
+specific file and return its path; those explicit waiters own the next download.
+When an action opens a modal dialog, the action response returns
+`blockedByDialog` with `browserState.dialogs.pending`; pass `--dialog-id` to
+answer it directly. Dialogs handled outside Nodmix appear under
+`browserState.dialogs.recent`.
+
+## State and storage
+
+Viewport + emulation:
+
+```bash
+nodmix browser resize 1280 720
+nodmix browser set viewport 1280 720
+nodmix browser set offline on
+nodmix browser set media dark
+nodmix browser set timezone Europe/London
+nodmix browser set locale en-GB
+nodmix browser set geo 51.5074 -0.1278 --accuracy 25
+nodmix browser set device "iPhone 14"
+nodmix browser set headers '{"x-test":"1"}'
+nodmix browser set credentials myuser mypass
+```
+
+Cookies + storage:
+
+```bash
+nodmix browser cookies
+nodmix browser cookies set session abc123 --url https://example.com
+nodmix browser cookies clear
+nodmix browser storage local get
+nodmix browser storage local set token abc123
+nodmix browser storage session clear
+```
+
+## Debugging
+
+```bash
+nodmix browser console --level error
+nodmix browser pdf
+nodmix browser responsebody "**/api"
+nodmix browser highlight <ref>
+nodmix browser errors --clear
+nodmix browser requests --filter api
+nodmix browser trace start
+nodmix browser trace stop --out trace.zip
+```
+
+## Existing Chrome via MCP
+
+Use the built-in `user` profile, or create your own `existing-session` profile:
+
+```bash
+nodmix browser --browser-profile user tabs
+nodmix browser create-profile --name chrome-live --driver existing-session
+nodmix browser create-profile --name brave-live --driver existing-session --user-data-dir "~/Library/Application Support/BraveSoftware/Brave-Browser"
+nodmix 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
+- `browser.actionTimeoutMs` defaults supported `act` requests to 60000 ms when
+  callers omit `timeoutMs`; per-call `timeoutMs` still wins.
+- `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)
+
+## Related
+
+- [CLI reference](/cli)
+- [Browser](/tools/browser)

package/docs/cli/channels.md

@@ -0,0 +1,154 @@
+---
+summary: "CLI reference for `nodmix 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"
+---
+
+# `nodmix channels`
+
+Manage chat channel accounts and their runtime status on the Gateway.
+
+Related docs:
+
+- Channel guides: [Channels](/channels)
+- Gateway configuration: [Configuration](/gateway/configuration)
+
+## Common commands
+
+```bash
+nodmix channels list
+nodmix channels list --all
+nodmix channels status
+nodmix channels capabilities
+nodmix channels capabilities --channel discord --target channel:123
+nodmix channels capabilities --channel discord --target channel:<voice-channel-id>
+nodmix channels resolve --channel slack "#general" "@jane"
+nodmix channels logs --channel all
+```
+
+`channels list` shows chat channels only: configured accounts by default, with `installed`, `configured`, and `enabled` status tags per account. Pass `--all` to also surface bundled channels that have no configured account yet and installable catalog channels that are not yet on disk. Auth providers (OAuth + API keys) and model-provider usage/quota snapshots are no longer printed here; use `nodmix models auth list` for provider auth profiles and `nodmix status` or `nodmix models list` for usage.
+
+## Status / capabilities / resolve / logs
+
+- `channels status`: `--channel <name>`, `--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.
+
+Do not use `nodmix sessions`, Gateway `sessions.list`, or the agent
+`sessions_list` tool as a channel socket-health signal. Those surfaces report
+stored conversation rows, not provider runtime state. After a Discord provider
+restart, a connected but quiet account may be healthy while no Discord session
+row appears until the next inbound or outbound conversation event.
+
+## Add / remove accounts
+
+```bash
+nodmix channels add --channel telegram --token <bot-token>
+nodmix channels add --channel nostr --private-key "$NOSTR_PRIVATE_KEY"
+nodmix channels remove --channel telegram --delete
+```
+
+<Tip>
+`nodmix channels add --help` shows per-channel flags (token, private key, app token, signal-cli paths, etc).
+</Tip>
+
+`channels remove` only operates on installed/configured channel plugins. Use `channels add` first for installable catalog channels.
+For runtime-backed channel plugins, `channels remove` also asks the running Gateway to stop the selected account before it updates config, so disabling or deleting an account does not leave the old listener active until restart.
+
+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
+
+If a channel plugin needs to be installed during a flag-driven add command, Nodmix uses the channel's default install source without opening the interactive plugin install prompt.
+
+When you run `nodmix channels add` without flags, the interactive wizard can prompt:
+
+- account ids per selected channel
+- optional display names for those accounts
+- `Route these 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 `nodmix agents bindings`, `nodmix agents bind`, and `nodmix 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, Nodmix 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 `nodmix 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 and logout (interactive)
+
+```bash
+nodmix channels login --channel whatsapp
+nodmix channels logout --channel whatsapp
+```
+
+- `channels login` supports `--verbose`.
+- `channels login` and `logout` can infer the channel when only one supported login target is configured.
+- `channels logout` prefers the live Gateway path when reachable, so logout stops any active listener before clearing channel auth state. If a local Gateway is not reachable, it falls back to local auth cleanup.
+- Run `channels login` from a terminal on the gateway host. Agent `exec` blocks this interactive login flow; channel-native agent login tools, such as `whatsapp_login`, should be used from chat when available.
+
+## Troubleshooting
+
+- Run `nodmix status --deep` for a broad probe.
+- Use `nodmix doctor` for guided fixes.
+- `nodmix channels list` no longer prints model provider usage/quota snapshots. For those, use `nodmix status` (overview) or `nodmix models list` (per-provider).
+- `nodmix 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
+nodmix channels capabilities
+nodmix 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. For Discord voice channels, the permission check flags missing `ViewChannel`, `Connect`, `Speak`, `SendMessages`, and `ReadMessageHistory`.
+- 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
+nodmix channels resolve --channel slack "#general" "@jane"
+nodmix channels resolve --channel discord "My Server/#support" "@someone"
+nodmix 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.
+- `channels resolve` does not install channel plugins. Use `channels add --channel <name>` before resolving names for an installable catalog channel.
+
+## Related
+
+- [CLI reference](/cli)
+- [Channels overview](/channels)

package/docs/cli/clawbot.md

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

package/docs/cli/commitments.md

@@ -0,0 +1,90 @@
+---
+summary: "CLI reference for `nodmix commitments` (inspect and dismiss inferred follow-ups)"
+read_when:
+  - You want to inspect inferred follow-up commitments
+  - You want to dismiss pending check-ins
+  - You are auditing what heartbeat may deliver
+title: "`nodmix commitments`"
+---
+
+List and manage inferred follow-up commitments.
+
+Commitments are opt-in, short-lived follow-up memories created from
+conversation context. See [Inferred commitments](/concepts/commitments) for the
+conceptual guide.
+
+With no subcommand, `nodmix commitments` lists pending commitments.
+
+## Usage
+
+```bash
+nodmix commitments [--all] [--agent <id>] [--status <status>] [--json]
+nodmix commitments list [--all] [--agent <id>] [--status <status>] [--json]
+nodmix commitments dismiss <id...> [--json]
+```
+
+## Options
+
+- `--all`: show all statuses instead of only pending commitments.
+- `--agent <id>`: filter to one agent id.
+- `--status <status>`: filter by status. Values: `pending`, `sent`,
+  `dismissed`, `snoozed`, or `expired`.
+- `--json`: output machine-readable JSON.
+
+## Examples
+
+List pending commitments:
+
+```bash
+nodmix commitments
+```
+
+List every stored commitment:
+
+```bash
+nodmix commitments --all
+```
+
+Filter to one agent:
+
+```bash
+nodmix commitments --agent main
+```
+
+Find snoozed commitments:
+
+```bash
+nodmix commitments --status snoozed
+```
+
+Dismiss one or more commitments:
+
+```bash
+nodmix commitments dismiss cm_abc123 cm_def456
+```
+
+Export as JSON:
+
+```bash
+nodmix commitments --all --json
+```
+
+## Output
+
+Text output includes:
+
+- commitment id
+- status
+- kind
+- earliest due time
+- scope
+- suggested check-in text
+
+JSON output also includes the commitment store path and full stored records.
+
+## Related
+
+- [Inferred commitments](/concepts/commitments)
+- [Memory overview](/concepts/memory)
+- [Heartbeat](/gateway/heartbeat)
+- [Scheduled tasks](/automation/cron-jobs)

package/docs/cli/completion.md

@@ -0,0 +1,39 @@
+---
+summary: "CLI reference for `nodmix completion` (generate/install shell completion scripts)"
+read_when:
+  - You want shell completions for zsh/bash/fish/PowerShell
+  - You need to cache completion scripts under Nodmix state
+title: "Completion"
+---
+
+# `nodmix completion`
+
+Generate shell completion scripts and optionally install them into your shell profile.
+
+## Usage
+
+```bash
+nodmix completion
+nodmix completion --shell zsh
+nodmix completion --install
+nodmix completion --shell fish --install
+nodmix completion --write-state
+nodmix 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 `$NODMIX_STATE_DIR/completions` without printing to stdout
+- `-y, --yes`: skip install confirmation prompts
+
+## Notes
+
+- `--install` writes a small "Nodmix 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.
+
+## Related
+
+- [CLI reference](/cli)