nodmix 2026.5.25

package/docs/cli/agents.md

@@ -0,0 +1,232 @@
+---
+summary: "CLI reference for `nodmix agents` (list/add/delete/bindings/bind/unbind/set identity)"
+read_when:
+  - You want multiple isolated agents (workspaces + routing + auth)
+title: "Agents"
+---
+
+# `nodmix agents`
+
+Manage isolated agents (workspaces + auth + routing).
+
+Related:
+
+- [Multi-agent routing](/concepts/multi-agent)
+- [Agent workspace](/concepts/agent-workspace)
+- [Skills config](/tools/skills-config): skill visibility configuration.
+
+## Examples
+
+```bash
+nodmix agents list
+nodmix agents list --bindings
+nodmix agents add work --workspace ~/.nodmix/workspace-work
+nodmix agents add ops --workspace ~/.nodmix/workspace-ops --bind telegram:ops --non-interactive
+nodmix agents bindings
+nodmix agents bind --agent work --bind telegram:ops
+nodmix agents unbind --agent work --bind telegram:ops
+nodmix agents set-identity --workspace ~/.nodmix/workspace --from-identity
+nodmix agents set-identity --agent main --avatar avatars/nodmix.png
+nodmix agents delete work
+```
+
+## Routing bindings
+
+Use routing bindings to pin inbound channel traffic to a specific agent.
+
+If you also want different visible skills per agent, configure `agents.defaults.skills` and `agents.list[].skills` in `nodmix.json`. See [Skills config](/tools/skills-config) and [Configuration reference](/gateway/config-agents#agents-defaults-skills).
+
+List bindings:
+
+```bash
+nodmix agents bindings
+nodmix agents bindings --agent work
+nodmix agents bindings --json
+```
+
+Add bindings:
+
+```bash
+nodmix agents bind --agent work --bind telegram:ops --bind discord:guild-a
+```
+
+If you omit `accountId` (`--bind <channel>`), Nodmix resolves it from channel defaults and plugin setup hooks when available.
+
+If you omit `--agent` for `bind` or `unbind`, Nodmix targets the current default agent.
+
+### Binding scope behavior
+
+- A binding without `accountId` matches the channel default account only.
+- `accountId: "*"` is the channel-wide fallback (all accounts) and is less specific than an explicit account binding.
+- If the same agent already has a matching channel binding without `accountId`, and you later bind with an explicit or resolved `accountId`, Nodmix upgrades that existing binding in place instead of adding a duplicate.
+
+Example:
+
+```bash
+# initial channel-only binding
+nodmix agents bind --agent work --bind telegram
+
+# later upgrade to account-scoped binding
+nodmix agents bind --agent work --bind telegram:ops
+```
+
+After the upgrade, routing for that binding is scoped to `telegram:ops`. If you also want default-account routing, add it explicitly (for example `--bind telegram:default`).
+
+Remove bindings:
+
+```bash
+nodmix agents unbind --agent work --bind telegram:ops
+nodmix agents unbind --agent work --all
+```
+
+`unbind` accepts either `--all` or one or more `--bind` values, not both.
+
+## Command surface
+
+### `agents`
+
+Running `nodmix agents` with no subcommand is equivalent to `nodmix agents list`.
+
+### `agents list`
+
+Options:
+
+- `--json`
+- `--bindings`: include full routing rules, not only per-agent counts/summaries
+
+### `agents add [name]`
+
+Options:
+
+- `--workspace <dir>`
+- `--model <id>`
+- `--agent-dir <dir>`
+- `--bind <channel[:accountId]>` (repeatable)
+- `--non-interactive`
+- `--json`
+
+Notes:
+
+- Passing any explicit add flags switches the command into the non-interactive path.
+- Non-interactive mode requires both an agent name and `--workspace`.
+- `main` is reserved and cannot be used as the new agent id.
+- In interactive mode, auth seeding copies only portable static profiles
+  (`api_key` and static `token` by default). OAuth refresh-token profiles remain
+  available only by read-through inheritance from the real `main` agent store.
+  If the configured default agent is not `main`, sign in separately for OAuth
+  profiles on the new agent.
+
+### `agents bindings`
+
+Options:
+
+- `--agent <id>`
+- `--json`
+
+### `agents bind`
+
+Options:
+
+- `--agent <id>` (defaults to the current default agent)
+- `--bind <channel[:accountId]>` (repeatable)
+- `--json`
+
+### `agents unbind`
+
+Options:
+
+- `--agent <id>` (defaults to the current default agent)
+- `--bind <channel[:accountId]>` (repeatable)
+- `--all`
+- `--json`
+
+### `agents delete <id>`
+
+Options:
+
+- `--force`
+- `--json`
+
+Notes:
+
+- `main` cannot be deleted.
+- Without `--force`, interactive confirmation is required.
+- Workspace, agent state, and session transcript directories are moved to Trash, not hard-deleted.
+- When the Gateway is reachable, deletion is sent through the Gateway so config and session-store cleanup share the same writer as runtime traffic. If the Gateway cannot be reached, the CLI falls back to the offline local path.
+- If another agent's workspace is the same path, inside this workspace, or contains this workspace,
+  the workspace is retained and `--json` reports `workspaceRetained`,
+  `workspaceRetainedReason`, and `workspaceSharedWith`.
+
+## Identity files
+
+Each agent workspace can include an `IDENTITY.md` at the workspace root:
+
+- Example path: `~/.nodmix/workspace/IDENTITY.md`
+- `set-identity --from-identity` reads from the workspace root (or an explicit `--identity-file`)
+
+Avatar paths resolve relative to the workspace root.
+
+## Set identity
+
+`set-identity` writes fields into `agents.list[].identity`:
+
+- `name`
+- `theme`
+- `emoji`
+- `avatar` (workspace-relative path, http(s) URL, or data URI)
+
+Options:
+
+- `--agent <id>`
+- `--workspace <dir>`
+- `--identity-file <path>`
+- `--from-identity`
+- `--name <name>`
+- `--theme <theme>`
+- `--emoji <emoji>`
+- `--avatar <value>`
+- `--json`
+
+Notes:
+
+- `--agent` or `--workspace` can be used to select the target agent.
+- If you rely on `--workspace` and multiple agents share that workspace, the command fails and asks you to pass `--agent`.
+- When no explicit identity fields are provided, the command reads identity data from `IDENTITY.md`.
+
+Load from `IDENTITY.md`:
+
+```bash
+nodmix agents set-identity --workspace ~/.nodmix/workspace --from-identity
+```
+
+Override fields explicitly:
+
+```bash
+nodmix agents set-identity --agent main --name "Nodmix" --emoji "🦞" --avatar avatars/nodmix.png
+```
+
+Config sample:
+
+```json5
+{
+  agents: {
+    list: [
+      {
+        id: "main",
+        identity: {
+          name: "Nodmix",
+          theme: "space lobster",
+          emoji: "🦞",
+          avatar: "avatars/nodmix.png",
+        },
+      },
+    ],
+  },
+}
+```
+
+## Related
+
+- [CLI reference](/cli)
+- [Multi-agent routing](/concepts/multi-agent)
+- [Agent workspace](/concepts/agent-workspace)

package/docs/cli/approvals.md

@@ -0,0 +1,190 @@
+---
+summary: "CLI reference for `nodmix approvals` and `nodmix exec-policy`"
+read_when:
+  - You want to edit exec approvals from the CLI
+  - You need to manage allowlists on gateway or node hosts
+title: "Approvals"
+---
+
+# `nodmix approvals`
+
+Manage exec approvals for the **local host**, **gateway host**, or a **node host**.
+By default, commands target the local approvals file on disk. Use `--gateway` to target the gateway, or `--node` to target a specific node.
+
+Alias: `nodmix exec-approvals`
+
+Related:
+
+- Exec approvals: [Exec approvals](/tools/exec-approvals)
+- Nodes: [Nodes](/nodes)
+
+## `nodmix exec-policy`
+
+`nodmix exec-policy` is the local convenience command for keeping the requested
+`tools.exec.*` config and the local host approvals file aligned in one step.
+
+Use it when you want to:
+
+- inspect the local requested policy, host approvals file, and effective merge
+- apply a local preset such as YOLO or deny-all
+- synchronize local `tools.exec.*` and local `~/.nodmix/exec-approvals.json`
+
+Examples:
+
+```bash
+nodmix exec-policy show
+nodmix exec-policy show --json
+
+nodmix exec-policy preset yolo
+nodmix exec-policy preset cautious --json
+
+nodmix exec-policy set --host gateway --security full --ask off --ask-fallback full
+```
+
+Output modes:
+
+- no `--json`: prints the human-readable table view
+- `--json`: prints machine-readable structured output
+
+Current scope:
+
+- `exec-policy` is **local-only**
+- it updates the local config file and the local approvals file together
+- it does **not** push policy to the gateway host or a node host
+- `--host node` is rejected in this command because node exec approvals are fetched from the node at runtime and must be managed through node-targeted approvals commands instead
+- `nodmix exec-policy show` marks `host=node` scopes as node-managed at runtime instead of deriving an effective policy from the local approvals file
+
+If you need to edit remote host approvals directly, keep using `nodmix approvals set --gateway`
+or `nodmix approvals set --node <id|name|ip>`.
+
+## Common commands
+
+```bash
+nodmix approvals get
+nodmix approvals get --node <id|name|ip>
+nodmix approvals get --gateway
+```
+
+`nodmix approvals get` now shows the effective exec policy for local, gateway, and node targets:
+
+- requested `tools.exec` policy
+- host approvals-file policy
+- effective result after precedence rules are applied
+
+Precedence is intentional:
+
+- the host approvals file is the enforceable source of truth
+- requested `tools.exec` policy can narrow or broaden intent, but the effective result is still derived from the host rules
+- `--node` combines the node host approvals file with gateway `tools.exec` policy, because both still apply at runtime
+- if gateway config is unavailable, the CLI falls back to the node approvals snapshot and notes that the final runtime policy could not be computed
+
+## Replace approvals from a file
+
+```bash
+nodmix approvals set --file ./exec-approvals.json
+nodmix approvals set --stdin <<'EOF'
+{ version: 1, defaults: { security: "full", ask: "off" } }
+EOF
+nodmix approvals set --node <id|name|ip> --file ./exec-approvals.json
+nodmix approvals set --gateway --file ./exec-approvals.json
+```
+
+`set` accepts JSON5, not only strict JSON. Use either `--file` or `--stdin`, not both.
+
+## "Never prompt" / YOLO example
+
+For a host that should never stop on exec approvals, set the host approvals defaults to `full` + `off`:
+
+```bash
+nodmix approvals set --stdin <<'EOF'
+{
+  version: 1,
+  defaults: {
+    security: "full",
+    ask: "off",
+    askFallback: "full"
+  }
+}
+EOF
+```
+
+Node variant:
+
+```bash
+nodmix approvals set --node <id|name|ip> --stdin <<'EOF'
+{
+  version: 1,
+  defaults: {
+    security: "full",
+    ask: "off",
+    askFallback: "full"
+  }
+}
+EOF
+```
+
+This changes the **host approvals file** only. To keep the requested Nodmix policy aligned, also set:
+
+```bash
+nodmix config set tools.exec.host gateway
+nodmix config set tools.exec.security full
+nodmix config set tools.exec.ask off
+```
+
+Why `tools.exec.host=gateway` in this example:
+
+- `host=auto` still means "sandbox when available, otherwise gateway".
+- YOLO is about approvals, not routing.
+- If you want host exec even when a sandbox is configured, make the host choice explicit with `gateway` or `/exec host=gateway`.
+
+This matches the current host-default YOLO behavior. Tighten it if you want approvals.
+
+Local shortcut:
+
+```bash
+nodmix exec-policy preset yolo
+```
+
+That local shortcut updates both the requested local `tools.exec.*` config and the
+local approvals defaults together. It is equivalent in intent to the manual two-step
+setup above, but only for the local machine.
+
+## Allowlist helpers
+
+```bash
+nodmix approvals allowlist add "~/Projects/**/bin/rg"
+nodmix approvals allowlist add --agent main --node <id|name|ip> "/usr/bin/uptime"
+nodmix approvals allowlist add --agent "*" "/usr/bin/uname"
+
+nodmix approvals allowlist remove "~/Projects/**/bin/rg"
+```
+
+## Common options
+
+`get`, `set`, and `allowlist add|remove` all support:
+
+- `--node <id|name|ip>`
+- `--gateway`
+- shared node RPC options: `--url`, `--token`, `--timeout`, `--json`
+
+Targeting notes:
+
+- no target flags means the local approvals file on disk
+- `--gateway` targets the gateway host approvals file
+- `--node` targets one node host after resolving id, name, IP, or id prefix
+
+`allowlist add|remove` also supports:
+
+- `--agent <id>` (defaults to `*`)
+
+## Notes
+
+- `--node` uses the same resolver as `nodmix nodes` (id, name, ip, or id prefix).
+- `--agent` defaults to `"*"`, which applies to all agents.
+- The node host must advertise `system.execApprovals.get/set` (macOS app or headless node host).
+- Approvals files are stored per host at `~/.nodmix/exec-approvals.json`.
+
+## Related
+
+- [CLI reference](/cli)
+- [Exec approvals](/tools/exec-approvals)

package/docs/cli/backup.md

@@ -0,0 +1,97 @@
+---
+summary: "CLI reference for `nodmix backup` (create local backup archives)"
+read_when:
+  - You want a first-class backup archive for local Nodmix state
+  - You want to preview which paths would be included before reset or uninstall
+title: "Backup"
+---
+
+# `nodmix backup`
+
+Create a local backup archive for Nodmix state, config, auth profiles, channel/provider credentials, sessions, and optionally workspaces.
+
+```bash
+nodmix backup create
+nodmix backup create --output ~/Backups
+nodmix backup create --dry-run --json
+nodmix backup create --verify
+nodmix backup create --no-include-workspace
+nodmix backup create --only-config
+nodmix backup verify ./2026-03-09T00-00-00.000Z-nodmix-backup.tar.gz
+```
+
+## Notes
+
+- The archive includes a `manifest.json` file with the resolved source paths and archive layout.
+- Default output is a timestamped `.tar.gz` archive in the current working directory.
+- If the current working directory is inside a backed-up source tree, Nodmix falls back to your home directory for the default archive location.
+- Existing archive files are never overwritten.
+- Output paths inside the source state/workspace trees are rejected to avoid self-inclusion.
+- `nodmix backup verify <archive>` validates that the archive contains exactly one root manifest, rejects traversal-style archive paths, and checks that every manifest-declared payload exists in the tarball.
+- `nodmix backup create --verify` runs that validation immediately after writing the archive.
+- `nodmix backup create --only-config` backs up just the active JSON config file.
+
+## What gets backed up
+
+`nodmix backup create` plans backup sources from your local Nodmix install:
+
+- The state directory returned by Nodmix's local state resolver, usually `~/.nodmix`
+- The active config file path
+- The resolved `credentials/` directory when it exists outside the state directory
+- Workspace directories discovered from the current config, unless you pass `--no-include-workspace`
+
+Model auth profiles are already part of the state directory under
+`agents/<agentId>/agent/auth-profiles.json`, so they are normally covered by the
+state backup entry.
+
+If you use `--only-config`, Nodmix skips state, credentials-directory, and workspace discovery and archives only the active config file path.
+
+Nodmix canonicalizes paths before building the archive. If config, the
+credentials directory, or a workspace already live inside the state directory,
+they are not duplicated as separate top-level backup sources. Missing paths are
+skipped.
+
+The archive payload stores file contents from those source trees, and the embedded `manifest.json` records the resolved absolute source paths plus the archive layout used for each asset.
+
+During archive creation, Nodmix skips known live-mutation files that do not have restoration value, including active agent session transcripts, cron run logs, rolling logs, delivery queues, socket/pid/temp files under the state directory, and related durable-queue temp files. The JSON result includes `skippedVolatileCount` so automation can see how many files were intentionally omitted.
+
+Installed plugin source and manifest files under the state directory's
+`extensions/` tree are included, but their nested `node_modules/` dependency
+trees are skipped. Those dependencies are rebuildable install artifacts; after
+restoring an archive, use `nodmix plugins update <id>` or reinstall the plugin
+with `nodmix plugins install <spec> --force` when a restored plugin reports
+missing dependencies.
+
+## Invalid config behavior
+
+`nodmix backup` intentionally bypasses the normal config preflight so it can still help during recovery. Because workspace discovery depends on a valid config, `nodmix backup create` now fails fast when the config file exists but is invalid and workspace backup is still enabled.
+
+If you still want a partial backup in that situation, rerun:
+
+```bash
+nodmix backup create --no-include-workspace
+```
+
+That keeps state, config, and the external credentials directory in scope while
+skipping workspace discovery entirely.
+
+If you only need a copy of the config file itself, `--only-config` also works when the config is malformed because it does not rely on parsing the config for workspace discovery.
+
+## Size and performance
+
+Nodmix does not enforce a built-in maximum backup size or per-file size limit.
+
+Practical limits come from the local machine and destination filesystem:
+
+- Available space for the temporary archive write plus the final archive
+- Time to walk large workspace trees and compress them into a `.tar.gz`
+- Time to rescan the archive if you use `nodmix backup create --verify` or run `nodmix backup verify`
+- Filesystem behavior at the destination path. Nodmix prefers a no-overwrite hard-link publish step and falls back to exclusive copy when hard links are unsupported
+
+Large workspaces are usually the main driver of archive size. If you want a smaller or faster backup, use `--no-include-workspace`.
+
+For the smallest archive, use `--only-config`.
+
+## Related
+
+- [CLI reference](/cli)