nodmix 2026.5.25

package/docs/tools/elevated.md

@@ -0,0 +1,128 @@
+---
+summary: "Elevated exec mode: run commands outside the sandbox from a sandboxed agent"
+read_when:
+  - Adjusting elevated mode defaults, allowlists, or slash command behavior
+  - Understanding how sandboxed agents can access the host
+title: "Elevated mode"
+---
+
+When an agent runs inside a sandbox, its `exec` commands are confined to the
+sandbox environment. **Elevated mode** lets the agent break out and run commands
+outside the sandbox instead, with configurable approval gates.
+
+<Info>
+  Elevated mode only changes behavior when the agent is **sandboxed**. For
+  unsandboxed agents, exec already runs on the host.
+</Info>
+
+## Directives
+
+Control elevated mode per-session with slash commands:
+
+| Directive        | What it does                                                           |
+| ---------------- | ---------------------------------------------------------------------- |
+| `/elevated on`   | Run outside the sandbox on the configured host path, keep approvals    |
+| `/elevated ask`  | Same as `on` (alias)                                                   |
+| `/elevated full` | Run outside the sandbox on the configured host path and skip approvals |
+| `/elevated off`  | Return to sandbox-confined execution                                   |
+
+Also available as `/elev on|off|ask|full`.
+
+Send `/elevated` with no argument to see the current level.
+
+## How it works
+
+<Steps>
+  <Step title="Check availability">
+    Elevated must be enabled in config and the sender must be on the allowlist:
+
+    ```json5
+    {
+      tools: {
+        elevated: {
+          enabled: true,
+          allowFrom: {
+            discord: ["user-id-123"],
+            whatsapp: ["+15555550123"],
+          },
+        },
+      },
+    }
+    ```
+
+  </Step>
+
+  <Step title="Set the level">
+    Send a directive-only message to set the session default:
+
+    ```
+    /elevated full
+    ```
+
+    Or use it inline (applies to that message only):
+
+    ```
+    /elevated on run the deployment script
+    ```
+
+  </Step>
+
+  <Step title="Commands run outside the sandbox">
+    With elevated active, `exec` calls leave the sandbox. The effective host is
+    `gateway` by default, or `node` when the configured/session exec target is
+    `node`. In `full` mode, exec approvals are skipped. In `on`/`ask` mode,
+    configured approval rules still apply.
+  </Step>
+</Steps>
+
+## Resolution order
+
+1. **Inline directive** on the message (applies only to that message)
+2. **Session override** (set by sending a directive-only message)
+3. **Global default** (`agents.defaults.elevatedDefault` in config)
+
+## Availability and allowlists
+
+- **Global gate**: `tools.elevated.enabled` (must be `true`)
+- **Sender allowlist**: `tools.elevated.allowFrom` with per-channel lists
+- **Per-agent gate**: `agents.list[].tools.elevated.enabled` (can only further restrict)
+- **Per-agent allowlist**: `agents.list[].tools.elevated.allowFrom` (sender must match both global + per-agent)
+- **Discord fallback**: if `tools.elevated.allowFrom.discord` is omitted, `channels.discord.allowFrom` is used as fallback
+- **All gates must pass**; otherwise elevated is treated as unavailable
+
+Allowlist entry formats:
+
+| Prefix                  | Matches                         |
+| ----------------------- | ------------------------------- |
+| (none)                  | Sender ID, E.164, or From field |
+| `name:`                 | Sender display name             |
+| `username:`             | Sender username                 |
+| `tag:`                  | Sender tag                      |
+| `id:`, `from:`, `e164:` | Explicit identity targeting     |
+
+## What elevated does not control
+
+- **Tool policy**: if `exec` is denied by tool policy, elevated cannot override it.
+- **Host selection policy**: elevated does not turn `auto` into a free cross-host override. It uses the configured/session exec target rules, choosing `node` only when the target is already `node`.
+- **Separate from `/exec`**: the `/exec` directive adjusts per-session exec defaults for authorized senders and does not require elevated mode.
+
+<Note>
+  The bash chat command (`!` prefix; `/bash` alias) is a separate gate that requires `tools.elevated` to be enabled in addition to its own `tools.bash.enabled` flag. Disabling elevated locks `!` shell commands out as well.
+</Note>
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Exec tool" href="/tools/exec" icon="terminal">
+    Shell command execution from the agent.
+  </Card>
+  <Card title="Exec approvals" href="/tools/exec-approvals" icon="shield">
+    Approval and allowlist system for `exec`.
+  </Card>
+  <Card title="Sandboxing" href="/gateway/sandboxing" icon="box">
+    Gateway-level sandbox configuration.
+  </Card>
+  <Card title="Sandbox vs Tool Policy vs Elevated" href="/gateway/sandbox-vs-tool-policy-vs-elevated" icon="scale-balanced">
+    How the three gates compose during a tool call.
+  </Card>
+</CardGroup>

package/docs/tools/exa-search.md

@@ -0,0 +1,152 @@
+---
+summary: "Exa AI search -- neural and keyword search with content extraction"
+read_when:
+  - You want to use Exa for web_search
+  - You need an EXA_API_KEY
+  - You want neural search or content extraction
+title: "Exa search"
+---
+
+Nodmix supports [Exa AI](https://exa.ai/) as a `web_search` provider. Exa
+offers neural, keyword, and hybrid search modes with built-in content
+extraction (highlights, text, summaries).
+
+## Get an API key
+
+<Steps>
+  <Step title="Create an account">
+    Sign up at [exa.ai](https://exa.ai/) and generate an API key from your
+    dashboard.
+  </Step>
+  <Step title="Store the key">
+    Set `EXA_API_KEY` in the Gateway environment, or configure via:
+
+    ```bash
+    nodmix configure --section web
+    ```
+
+  </Step>
+</Steps>
+
+## Config
+
+```json5
+{
+  plugins: {
+    entries: {
+      exa: {
+        config: {
+          webSearch: {
+            apiKey: "exa-...", // optional if EXA_API_KEY is set
+            baseUrl: "https://api.exa.ai", // optional; Nodmix appends /search
+          },
+        },
+      },
+    },
+  },
+  tools: {
+    web: {
+      search: {
+        provider: "exa",
+      },
+    },
+  },
+}
+```
+
+**Environment alternative:** set `EXA_API_KEY` in the Gateway environment.
+For a gateway install, put it in `~/.nodmix/.env`.
+
+## Base URL override
+
+Set `plugins.entries.exa.config.webSearch.baseUrl` when Exa search requests
+should go through a compatible proxy or alternate Exa endpoint. Nodmix
+normalizes bare hosts by prepending `https://` and appends `/search` unless the
+path already ends there. The resolved endpoint is included in the search cache
+key, so results from different Exa endpoints are not shared.
+
+## Tool parameters
+
+<ParamField path="query" type="string" required>
+Search query.
+</ParamField>
+
+<ParamField path="count" type="number">
+Results to return (1–100).
+</ParamField>
+
+<ParamField path="type" type="'auto' | 'neural' | 'fast' | 'deep' | 'deep-reasoning' | 'instant'">
+Search mode.
+</ParamField>
+
+<ParamField path="freshness" type="'day' | 'week' | 'month' | 'year'">
+Time filter.
+</ParamField>
+
+<ParamField path="date_after" type="string">
+Results after this date (`YYYY-MM-DD`).
+</ParamField>
+
+<ParamField path="date_before" type="string">
+Results before this date (`YYYY-MM-DD`).
+</ParamField>
+
+<ParamField path="contents" type="object">
+Content extraction options (see below).
+</ParamField>
+
+### Content extraction
+
+Exa can return extracted content alongside search results. Pass a `contents`
+object to enable:
+
+```javascript
+await web_search({
+  query: "transformer architecture explained",
+  type: "neural",
+  contents: {
+    text: true, // full page text
+    highlights: { numSentences: 3 }, // key sentences
+    summary: true, // AI summary
+  },
+});
+```
+
+| Contents option | Type                                                                  | Description            |
+| --------------- | --------------------------------------------------------------------- | ---------------------- |
+| `text`          | `boolean \| { maxCharacters }`                                        | Extract full page text |
+| `highlights`    | `boolean \| { maxCharacters, query, numSentences, highlightsPerUrl }` | Extract key sentences  |
+| `summary`       | `boolean \| { query }`                                                | AI-generated summary   |
+
+### Search modes
+
+| Mode             | Description                       |
+| ---------------- | --------------------------------- |
+| `auto`           | Exa picks the best mode (default) |
+| `neural`         | Semantic/meaning-based search     |
+| `fast`           | Quick keyword search              |
+| `deep`           | Thorough deep search              |
+| `deep-reasoning` | Deep search with reasoning        |
+| `instant`        | Fastest results                   |
+
+## Notes
+
+- If no `contents` option is provided, Exa defaults to `{ highlights: true }`
+  so results include key sentence excerpts
+- Results preserve `highlightScores` and `summary` fields from the Exa API
+  response when available
+- Result descriptions are resolved from highlights first, then summary, then
+  full text — whichever is available
+- `freshness` and `date_after`/`date_before` cannot be combined — use one
+  time-filter mode
+- Up to 100 results can be returned per query (subject to Exa search-type
+  limits)
+- Results are cached for 15 minutes by default (configurable via
+  `cacheTtlMinutes`)
+- Exa is an official API integration with structured JSON responses
+
+## Related
+
+- [Web Search overview](/tools/web) -- all providers and auto-detection
+- [Brave Search](/tools/brave-search) -- structured results with country/language filters
+- [Perplexity Search](/tools/perplexity-search) -- structured results with domain filtering

package/docs/tools/exec-approvals-advanced.md

@@ -0,0 +1,360 @@
+---
+summary: "Advanced exec approvals: safe bins, interpreter binding, approval forwarding, native delivery"
+read_when:
+  - Configuring safe bins or custom safe-bin profiles
+  - Forwarding approvals to Slack/Discord/Telegram or other chat channels
+  - Implementing a native approval client for a channel
+title: "Exec approvals — advanced"
+---
+
+Advanced exec-approval topics: the `safeBins` fast-path, interpreter/runtime
+binding, and approval-forwarding to chat channels (including native delivery).
+For the core policy and approval flow, see [Exec approvals](/tools/exec-approvals).
+
+## Safe bins (stdin-only)
+
+`tools.exec.safeBins` defines a small list of **stdin-only** binaries (for
+example `cut`) that can run in allowlist mode **without** explicit allowlist
+entries. Safe bins reject positional file args and path-like tokens, so they
+can only operate on the incoming stream. Treat this as a narrow fast-path for
+stream filters, not a general trust list.
+
+<Warning>
+Do **not** add interpreter or runtime binaries (for example `python3`, `node`,
+`ruby`, `bash`, `sh`, `zsh`) to `safeBins`. If a command can evaluate code,
+execute subcommands, or read files by design, prefer explicit allowlist entries
+and keep approval prompts enabled. Custom safe bins must define an explicit
+profile in `tools.exec.safeBinProfiles.<bin>`.
+</Warning>
+
+Default safe bins:
+
+[//]: # "SAFE_BIN_DEFAULTS:START"
+
+`cut`, `uniq`, `head`, `tail`, `tr`, `wc`
+
+[//]: # "SAFE_BIN_DEFAULTS:END"
+
+`grep` and `sort` are not in the default list. If you opt in, keep explicit
+allowlist entries for their non-stdin workflows. For `grep` in safe-bin mode,
+provide the pattern with `-e`/`--regexp`; positional pattern form is rejected
+so file operands cannot be smuggled as ambiguous positionals.
+
+### Argv validation and denied flags
+
+Validation is deterministic from argv shape only (no host filesystem existence
+checks), which prevents file-existence oracle behavior from allow/deny
+differences. File-oriented options are denied for default safe bins; long
+options are validated fail-closed (unknown flags and ambiguous abbreviations are
+rejected).
+
+Denied flags by safe-bin profile:
+
+[//]: # "SAFE_BIN_DENIED_FLAGS:START"
+
+- `grep`: `--dereference-recursive`, `--directories`, `--exclude-from`, `--file`, `--recursive`, `-R`, `-d`, `-f`, `-r`
+- `jq`: `--argfile`, `--from-file`, `--library-path`, `--rawfile`, `--slurpfile`, `-L`, `-f`
+- `sort`: `--compress-program`, `--files0-from`, `--output`, `--random-source`, `--temporary-directory`, `-T`, `-o`
+- `wc`: `--files0-from`
+
+[//]: # "SAFE_BIN_DENIED_FLAGS:END"
+
+Safe bins also force argv tokens to be treated as **literal text** at execution
+time (no globbing and no `$VARS` expansion) for stdin-only segments, so patterns
+like `*` or `$HOME/...` cannot be used to smuggle file reads.
+
+### Trusted binary directories
+
+Safe bins must resolve from trusted binary directories (system defaults plus
+optional `tools.exec.safeBinTrustedDirs`). `PATH` entries are never auto-trusted.
+Default trusted directories are intentionally minimal: `/bin`, `/usr/bin`. If
+your safe-bin executable lives in package-manager/user paths (for example
+`/opt/homebrew/bin`, `/usr/local/bin`, `/opt/local/bin`, `/snap/bin`), add them
+explicitly to `tools.exec.safeBinTrustedDirs`.
+
+### Shell chaining, wrappers, and multiplexers
+
+Shell chaining (`&&`, `||`, `;`) is allowed when every top-level segment
+satisfies the allowlist (including safe bins or skill auto-allow). Redirections
+remain unsupported in allowlist mode. Command substitution (`$()` / backticks) is
+rejected during allowlist parsing, including inside double quotes; use single
+quotes if you need literal `$()` text.
+
+On macOS companion-app approvals, raw shell text containing shell control or
+expansion syntax (`&&`, `||`, `;`, `|`, `` ` ``, `$`, `<`, `>`, `(`, `)`) is
+treated as an allowlist miss unless the shell binary itself is allowlisted.
+
+For shell wrappers (`bash|sh|zsh ... -c/-lc`), request-scoped env overrides are
+reduced to a small explicit allowlist (`TERM`, `LANG`, `LC_*`, `COLORTERM`,
+`NO_COLOR`, `FORCE_COLOR`).
+
+For `allow-always` decisions in allowlist mode, known dispatch wrappers (`env`,
+`nice`, `nohup`, `stdbuf`, `timeout`) persist the inner executable path instead
+of the wrapper path. Shell multiplexers (`busybox`, `toybox`) are unwrapped for
+shell applets (`sh`, `ash`, etc.) the same way. If a wrapper or multiplexer
+cannot be safely unwrapped, no allowlist entry is persisted automatically.
+
+If you allowlist interpreters like `python3` or `node`, prefer
+`tools.exec.strictInlineEval=true` so inline eval still requires an explicit
+approval. In strict mode, `allow-always` can still persist benign
+interpreter/script invocations, but inline-eval carriers are not persisted
+automatically.
+
+### Safe bins versus allowlist
+
+| Topic            | `tools.exec.safeBins`                                  | Allowlist (`exec-approvals.json`)                                                  |
+| ---------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------------- |
+| Goal             | Auto-allow narrow stdin filters                        | Explicitly trust specific executables                                              |
+| Match type       | Executable name + safe-bin argv policy                 | Resolved executable path glob, or bare command-name glob for PATH-invoked commands |
+| Argument scope   | Restricted by safe-bin profile and literal-token rules | Path match by default; optional `argPattern` can restrict parsed argv              |
+| Typical examples | `head`, `tail`, `tr`, `wc`                             | `jq`, `python3`, `node`, `ffmpeg`, custom CLIs                                     |
+| Best use         | Low-risk text transforms in pipelines                  | Any tool with broader behavior or side effects                                     |
+
+Configuration location:
+
+- `safeBins` comes from config (`tools.exec.safeBins` or per-agent `agents.list[].tools.exec.safeBins`).
+- `safeBinTrustedDirs` comes from config (`tools.exec.safeBinTrustedDirs` or per-agent `agents.list[].tools.exec.safeBinTrustedDirs`).
+- `safeBinProfiles` comes from config (`tools.exec.safeBinProfiles` or per-agent `agents.list[].tools.exec.safeBinProfiles`). Per-agent profile keys override global keys.
+- allowlist entries live in host-local `~/.nodmix/exec-approvals.json` under `agents.<id>.allowlist` (or via Control UI / `nodmix approvals allowlist ...`).
+- `nodmix security audit` warns with `tools.exec.safe_bins_interpreter_unprofiled` when interpreter/runtime bins appear in `safeBins` without explicit profiles.
+- `nodmix doctor --fix` can scaffold missing custom `safeBinProfiles.<bin>` entries as `{}` (review and tighten afterward). Interpreter/runtime bins are not auto-scaffolded.
+
+Custom profile example:
+
+```json5
+{
+  tools: {
+    exec: {
+      safeBins: ["jq", "myfilter"],
+      safeBinProfiles: {
+        myfilter: {
+          minPositional: 0,
+          maxPositional: 0,
+          allowedValueFlags: ["-n", "--limit"],
+          deniedFlags: ["-f", "--file", "-c", "--command"],
+        },
+      },
+    },
+  },
+}
+```
+
+If you explicitly opt `jq` into `safeBins`, Nodmix still rejects the `env` builtin in safe-bin
+mode so `jq -n env` cannot dump the host process environment without an explicit allowlist path
+or approval prompt.
+
+## Interpreter/runtime commands
+
+Approval-backed interpreter/runtime runs are intentionally conservative:
+
+- Exact argv/cwd/env context is always bound.
+- Direct shell script and direct runtime file forms are best-effort bound to one concrete local
+  file snapshot.
+- Common package-manager wrapper forms that still resolve to one direct local file (for example
+  `pnpm exec`, `pnpm node`, `npm exec`, `npx`) are unwrapped before binding.
+- If Nodmix cannot identify exactly one concrete local file for an interpreter/runtime command
+  (for example package scripts, eval forms, runtime-specific loader chains, or ambiguous multi-file
+  forms), approval-backed execution is denied instead of claiming semantic coverage it does not
+  have.
+- For those workflows, prefer sandboxing, a separate host boundary, or an explicit trusted
+  allowlist/full workflow where the operator accepts the broader runtime semantics.
+
+When approvals are required, the exec tool returns immediately with an approval id. Use that id to
+correlate later system events (`Exec finished` / `Exec denied`). If no decision arrives before the
+timeout, the request is treated as an approval timeout and surfaced as a denial reason.
+
+### Followup delivery behavior
+
+After an approved async exec finishes, Nodmix sends a followup `agent` turn to the same session.
+
+- If a valid external delivery target exists (deliverable channel plus target `to`), followup delivery uses that channel.
+- In webchat-only or internal-session flows with no external target, followup delivery stays session-only (`deliver: false`).
+- If a caller explicitly requests strict external delivery with no resolvable external channel, the request fails with `INVALID_REQUEST`.
+- If `bestEffortDeliver` is enabled and no external channel can be resolved, delivery is downgraded to session-only instead of failing.
+
+## Approval forwarding to chat channels
+
+You can forward exec approval prompts to any chat channel (including plugin channels) and approve
+them with `/approve`. This uses the normal outbound delivery pipeline.
+
+Config:
+
+```json5
+{
+  approvals: {
+    exec: {
+      enabled: true,
+      mode: "session", // "session" | "targets" | "both"
+      agentFilter: ["main"],
+      sessionFilter: ["discord"], // substring or regex
+      targets: [
+        { channel: "slack", to: "U12345678" },
+        { channel: "telegram", to: "123456789" },
+      ],
+    },
+  },
+}
+```
+
+Reply in chat:
+
+```
+/approve <id> allow-once
+/approve <id> allow-always
+/approve <id> deny
+```
+
+The `/approve` command handles both exec approvals and plugin approvals. If the ID does not match a pending exec approval, it automatically checks plugin approvals instead.
+
+### Plugin approval forwarding
+
+Plugin approval forwarding uses the same delivery pipeline as exec approvals but has its own
+independent config under `approvals.plugin`. Enabling or disabling one does not affect the other.
+
+```json5
+{
+  approvals: {
+    plugin: {
+      enabled: true,
+      mode: "targets",
+      agentFilter: ["main"],
+      targets: [
+        { channel: "slack", to: "U12345678" },
+        { channel: "telegram", to: "123456789" },
+      ],
+    },
+  },
+}
+```
+
+The config shape is identical to `approvals.exec`: `enabled`, `mode`, `agentFilter`,
+`sessionFilter`, and `targets` work the same way.
+
+Channels that support shared interactive replies render the same approval buttons for both exec and
+plugin approvals. Channels without shared interactive UI fall back to plain text with `/approve`
+instructions.
+Plugin approval requests may restrict the available decisions. Approval surfaces use the request's
+declared decision set, and the Gateway rejects attempts to submit a decision that was not offered.
+
+### Same-chat approvals on any channel
+
+When an exec or plugin approval request originates from a deliverable chat surface, the same chat
+can now approve it with `/approve` by default. This applies to channels such as Slack, Matrix, and
+Microsoft Teams in addition to the existing Web UI and terminal UI flows.
+
+This shared text-command path uses the normal channel auth model for that conversation. If the
+originating chat can already send commands and receive replies, approval requests no longer need a
+separate native delivery adapter just to stay pending.
+
+Discord and Telegram also support same-chat `/approve`, but those channels still use their
+resolved approver list for authorization even when native approval delivery is disabled.
+
+For Telegram and other native approval clients that call the Gateway directly,
+this fallback is intentionally bounded to "approval not found" failures. A real
+exec approval denial/error does not silently retry as a plugin approval.
+
+### Native approval delivery
+
+Some channels can also act as native approval clients. Native clients add approver DMs, origin-chat
+fanout, and channel-specific interactive approval UX on top of the shared same-chat `/approve`
+flow.
+
+When native approval cards/buttons are available, that native UI is the primary
+agent-facing path. The agent should not also echo a duplicate plain chat
+`/approve` command unless the tool result says chat approvals are unavailable or
+manual approval is the only remaining path.
+
+If a native approval client is configured but no native runtime is active for
+the originating channel, Nodmix keeps the local deterministic `/approve`
+prompt visible. If the native runtime is active and attempts delivery but no
+target receives the card, Nodmix sends a same-chat fallback notice with the
+exact `/approve <id> <decision>` command so the request can still be resolved.
+
+Generic model:
+
+- host exec policy still decides whether exec approval is required
+- `approvals.exec` controls forwarding approval prompts to other chat destinations
+- `channels.<channel>.execApprovals` controls whether that channel acts as a native approval client
+
+Native approval clients auto-enable DM-first delivery when all of these are true:
+
+- the channel supports native approval delivery
+- approvers can be resolved from explicit `execApprovals.approvers` or owner
+  identity such as `commands.ownerAllowFrom`
+- `channels.<channel>.execApprovals.enabled` is unset or `"auto"`
+
+Set `enabled: false` to disable a native approval client explicitly. Set `enabled: true` to force
+it on when approvers resolve. Public origin-chat delivery stays explicit through
+`channels.<channel>.execApprovals.target`.
+
+FAQ: [Why are there two exec approval configs for chat approvals?](/help/faq-first-run#why-are-there-two-exec-approval-configs-for-chat-approvals)
+
+- Discord: `channels.discord.execApprovals.*`
+- Slack: `channels.slack.execApprovals.*`
+- Telegram: `channels.telegram.execApprovals.*`
+
+These native approval clients add DM routing and optional channel fanout on top of the shared
+same-chat `/approve` flow and shared approval buttons.
+
+Shared behavior:
+
+- Slack, Matrix, Microsoft Teams, and similar deliverable chats use the normal channel auth model
+  for same-chat `/approve`
+- when a native approval client auto-enables, the default native delivery target is approver DMs
+- for Discord and Telegram, only resolved approvers can approve or deny
+- Discord approvers can be explicit (`execApprovals.approvers`) or inferred from `commands.ownerAllowFrom`
+- Telegram approvers can be explicit (`execApprovals.approvers`) or inferred from `commands.ownerAllowFrom`
+- Slack approvers can be explicit (`execApprovals.approvers`) or inferred from `commands.ownerAllowFrom`
+- Slack native buttons preserve approval id kind, so `plugin:` ids can resolve plugin approvals
+  without a second Slack-local fallback layer
+- Matrix native DM/channel routing and reaction shortcuts handle both exec and plugin approvals;
+  plugin authorization still comes from `channels.matrix.dm.allowFrom`
+- Matrix native prompts include `com.nodmix.approval` custom event content on the first prompt
+  event so Nodmix-aware Matrix clients can read structured approval state while stock clients
+  keep the plain-text `/approve` fallback
+- the requester does not need to be an approver
+- the originating chat can approve directly with `/approve` when that chat already supports commands and replies
+- native Discord approval buttons route by approval id kind: `plugin:` ids go
+  straight to plugin approvals, everything else goes to exec approvals
+- native Telegram approval buttons follow the same bounded exec-to-plugin fallback as `/approve`
+- when native `target` enables origin-chat delivery, approval prompts include the command text
+- pending exec approvals expire after 30 minutes by default
+- if no operator UI or configured approval client can accept the request, the prompt falls back to `askFallback`
+
+Sensitive owner-only group commands such as `/diagnostics` and `/export-trajectory` use private
+owner routing for approval prompts and final results. Nodmix first tries a private route on the
+same surface where the owner ran the command. If that surface has no private owner route, it falls
+back to the first available owner route from `commands.ownerAllowFrom`, so a Discord group command
+can still send the approval and result to the owner's Telegram DM when Telegram is the configured
+primary private interface. The group chat only gets a short acknowledgement.
+
+Telegram defaults to approver DMs (`target: "dm"`). You can switch to `channel` or `both` when you
+want approval prompts to appear in the originating Telegram chat/topic as well. For Telegram forum
+topics, Nodmix preserves the topic for the approval prompt and the post-approval follow-up.
+
+See:
+
+- [Discord](/channels/discord)
+- [Telegram](/channels/telegram)
+
+### macOS IPC flow
+
+```
+Gateway -> Node Service (WS)
+                 |  IPC (UDS + token + HMAC + TTL)
+                 v
+             Mac App (UI + approvals + system.run)
+```
+
+Security notes:
+
+- Unix socket mode `0600`, token stored in `exec-approvals.json`.
+- Same-UID peer check.
+- Challenge/response (nonce + HMAC token + request hash) + short TTL.
+
+## Related
+
+- [Exec approvals](/tools/exec-approvals) — core policy and approval flow
+- [Exec tool](/tools/exec)
+- [Elevated mode](/tools/elevated)
+- [Skills](/tools/skills) — skill-backed auto-allow behavior