nodmix 2026.5.25

package/docs/tools/slash-commands.md

@@ -0,0 +1,488 @@
+---
+summary: "Slash commands: text vs native, config, and supported commands"
+read_when:
+  - Using or configuring chat commands
+  - Debugging command routing or permissions
+title: "Slash commands"
+sidebarTitle: "Slash commands"
+---
+
+Commands are handled by the Gateway. Most commands must be sent as a **standalone** message that starts with `/`. The host-only bash chat command uses `! <cmd>` (with `/bash <cmd>` as an alias).
+
+When a conversation or thread is bound to an ACP session, normal follow-up text routes to that ACP harness. Gateway management commands still stay local: `/acp ...` always reaches the Nodmix ACP command handler, and `/status` plus `/unfocus` stay local whenever command handling is enabled for the surface.
+
+There are two related systems:
+
+<AccordionGroup>
+  <Accordion title="Commands">
+    Standalone `/...` messages.
+  </Accordion>
+  <Accordion title="Directives">
+    `/think`, `/fast`, `/verbose`, `/trace`, `/reasoning`, `/elevated`, `/exec`, `/model`, `/queue`.
+
+    - Directives are stripped from the message before the model sees it.
+    - In normal chat messages (not directive-only), they are treated as "inline hints" and do **not** persist session settings.
+    - In directive-only messages (the message contains only directives), they persist to the session and reply with an acknowledgement.
+    - Directives are only applied for **authorized senders**. If `commands.allowFrom` is set, it is the only allowlist used; otherwise authorization comes from channel allowlists/pairing plus `commands.useAccessGroups`. Unauthorized senders see directives treated as plain text.
+
+  </Accordion>
+  <Accordion title="Inline shortcuts">
+    Allowlisted/authorized senders only: `/help`, `/commands`, `/status`, `/whoami` (`/id`).
+
+    They run immediately, are stripped before the model sees the message, and the remaining text continues through the normal flow.
+
+  </Accordion>
+</AccordionGroup>
+
+## Config
+
+```json5
+{
+  commands: {
+    native: "auto",
+    nativeSkills: "auto",
+    text: true,
+    bash: false,
+    bashForegroundMs: 2000,
+    config: false,
+    mcp: false,
+    plugins: false,
+    debug: false,
+    restart: true,
+    ownerAllowFrom: ["discord:123456789012345678"],
+    ownerDisplay: "raw",
+    ownerDisplaySecret: "${OWNER_ID_HASH_SECRET}",
+    allowFrom: {
+      "*": ["user1"],
+      discord: ["user:123"],
+    },
+    useAccessGroups: true,
+  },
+}
+```
+
+<ParamField path="commands.text" type="boolean" default="true">
+  Enables parsing `/...` in chat messages. On surfaces without native commands (WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams), text commands still work even if you set this to `false`.
+</ParamField>
+<ParamField path="commands.native" type='boolean | "auto"' default='"auto"'>
+  Registers native commands. Auto: on for Discord/Telegram; off for Slack (until you add slash commands); ignored for providers without native support. Set `channels.discord.commands.native`, `channels.telegram.commands.native`, or `channels.slack.commands.native` to override per provider (bool or `"auto"`). On Discord, `false` skips slash-command registration and cleanup during startup; previously registered commands may remain visible until you remove them from the Discord app. Slack commands are managed in the Slack app and are not removed automatically.
+</ParamField>
+On Discord, native command specs may include `descriptionLocalizations`, which Nodmix publishes as Discord `description_localizations` and includes in reconcile comparisons.
+<ParamField path="commands.nativeSkills" type='boolean | "auto"' default='"auto"'>
+  Registers **skill** commands natively when supported. Auto: on for Discord/Telegram; off for Slack (Slack requires creating a slash command per skill). Set `channels.discord.commands.nativeSkills`, `channels.telegram.commands.nativeSkills`, or `channels.slack.commands.nativeSkills` to override per provider (bool or `"auto"`).
+</ParamField>
+<ParamField path="commands.bash" type="boolean" default="false">
+  Enables `! <cmd>` to run host shell commands (`/bash <cmd>` is an alias; requires `tools.elevated` allowlists).
+</ParamField>
+<ParamField path="commands.bashForegroundMs" type="number" default="2000">
+  Controls how long bash waits before switching to background mode (`0` backgrounds immediately).
+</ParamField>
+<ParamField path="commands.config" type="boolean" default="false">
+  Enables `/config` (reads/writes `nodmix.json`).
+</ParamField>
+<ParamField path="commands.mcp" type="boolean" default="false">
+  Enables `/mcp` (reads/writes Nodmix-managed MCP config under `mcp.servers`).
+</ParamField>
+<ParamField path="commands.plugins" type="boolean" default="false">
+  Enables `/plugins` (plugin discovery/status plus install + enable/disable controls).
+</ParamField>
+<ParamField path="commands.debug" type="boolean" default="false">
+  Enables `/debug` (runtime-only overrides).
+</ParamField>
+<ParamField path="commands.restart" type="boolean" default="true">
+  Enables `/restart` plus gateway restart tool actions.
+</ParamField>
+<ParamField path="commands.ownerAllowFrom" type="string[]">
+  Sets the explicit owner allowlist for owner-only command surfaces and owner-gated channel actions. This is the human operator account that can approve dangerous actions and run commands such as `/diagnostics`, `/export-trajectory`, and `/config`. It is separate from `commands.allowFrom` and from DM pairing access.
+</ParamField>
+<ParamField path="channels.<channel>.commands.enforceOwnerForCommands" type="boolean" default="false">
+  Per-channel: makes owner-only commands require **owner identity** to run on that surface. When `true`, the sender must either match a resolved owner candidate (for example an entry in `commands.ownerAllowFrom` or provider-native owner metadata) or hold internal `operator.admin` scope on an internal message channel. A wildcard entry in channel `allowFrom`, or an empty/unresolved owner-candidate list, is **not** sufficient — owner-only commands fail closed on that channel. Leave this off if you want owner-only commands gated only by `ownerAllowFrom` and the standard command allowlists.
+</ParamField>
+<ParamField path="commands.ownerDisplay" type='"raw" | "hash"'>
+  Controls how owner ids appear in the system prompt.
+</ParamField>
+<ParamField path="commands.ownerDisplaySecret" type="string">
+  Optionally sets the HMAC secret used when `commands.ownerDisplay="hash"`.
+</ParamField>
+<ParamField path="commands.allowFrom" type="object">
+  Per-provider allowlist for command authorization. When configured, it is the only authorization source for commands and directives (channel allowlists/pairing and `commands.useAccessGroups` are ignored). Use `"*"` for a global default; provider-specific keys override it.
+</ParamField>
+<ParamField path="commands.useAccessGroups" type="boolean" default="true">
+  Enforces allowlists/policies for commands when `commands.allowFrom` is not set.
+</ParamField>
+
+## Command list
+
+Current source-of-truth:
+
+- core built-ins come from `src/auto-reply/commands-registry.shared.ts`
+- generated dock commands come from `src/auto-reply/commands-registry.data.ts`
+- plugin commands come from plugin `registerCommand()` calls
+- actual availability on your gateway still depends on config flags, channel surface, and installed/enabled plugins
+
+### Core built-in commands
+
+<AccordionGroup>
+  <Accordion title="Sessions and runs">
+    - `/new [model]` archives the current session and starts a fresh one; `/reset` wipes the current session in place. They are not aliases.
+    - Control UI intercepts typed `/new` to create and switch to a fresh dashboard session, except when `session.dmScope: "main"` is configured and the current parent is the agent's main session; in that case `/new` resets the main session in place. Typed `/reset` still runs the Gateway's in-place reset.
+    - `/reset soft [message]` keeps the current transcript, drops reused CLI backend session ids, and reruns startup/system-prompt loading in-place.
+    - `/compact [instructions]` compacts the session context. See [Compaction](/concepts/compaction).
+    - `/stop` aborts the current run.
+    - `/session idle <duration|off>` and `/session max-age <duration|off>` manage thread-binding expiry.
+    - `/export-session [path]` exports the current session to HTML. Alias: `/export`.
+    - `/export-trajectory [path]` asks for exec approval, then exports a JSONL [trajectory bundle](/tools/trajectory) for the current session. Use it when you need the prompt, tool, and transcript timeline for one Nodmix session. In group chats, the approval prompt and export result go to the owner privately. Alias: `/trajectory`.
+
+  </Accordion>
+  <Accordion title="Model and run controls">
+    - `/think <level|default>` sets the thinking level or clears the session override. Options come from the active model's provider profile; common levels are `off`, `minimal`, `low`, `medium`, and `high`, with custom levels such as `xhigh`, `adaptive`, `max`, or binary `on` only where supported. Aliases: `/thinking`, `/t`.
+    - `/verbose on|off|full` toggles verbose output. Alias: `/v`.
+    - `/trace on|off` toggles plugin trace output for the current session.
+    - `/fast [status|on|off|default]` shows, sets, or clears fast mode.
+    - `/reasoning [on|off|stream]` toggles reasoning visibility. Alias: `/reason`.
+    - `/elevated [on|off|ask|full]` toggles elevated mode. Alias: `/elev`.
+    - `/exec host=<auto|sandbox|gateway|node> security=<deny|allowlist|full> ask=<off|on-miss|always> node=<id>` shows or sets exec defaults.
+    - `/model [name|#|status]` shows or sets the model.
+    - `/models [provider] [page] [limit=<n>|size=<n>|all]` lists configured/auth-available providers or models for a provider; add `all` to browse that provider's full catalog. `provider/*` entries in `agents.defaults.models` make `/model` and `/models` show discovered models only for those providers.
+    - `/queue <mode>` manages active-run queue behavior (`steer`, `followup`, `collect`, `interrupt`) plus options like `debounce:0.5s cap:25 drop:summarize`; `/queue default` or `/queue reset` clears the session override. Mid-run prompts steer by default without a queue directive. See [Command queue](/concepts/queue) and [Steering queue](/concepts/queue-steering).
+    - `/steer <message>` injects guidance into the active run for the current session, independent of `/queue` mode. If steering is unavailable or the session is idle, `<message>` continues as a normal prompt. Alias: `/tell`. See [Steer](/tools/steer).
+
+  </Accordion>
+  <Accordion title="Discovery and status">
+    - `/help` shows the short help summary.
+    - `/commands` shows the generated command catalog.
+    - `/tools [compact|verbose]` shows what the current agent can use right now.
+    - `/status` shows execution/runtime status, Gateway and system uptime, plus provider usage/quota when available.
+    - `/diagnostics [note]` is the owner-only support-report flow for Gateway bugs and Codex harness runs. It asks for explicit exec approval every time before running `nodmix gateway diagnostics export --json`; do not approve diagnostics with an allow-all rule. After approval, it sends a pasteable report with the local bundle path, manifest summary, privacy notes, and relevant session ids. In group chats, the approval prompt and report go to the owner privately. When the active session uses the OpenAI Codex harness, the same approval also sends relevant Codex feedback to OpenAI servers and the completed reply lists the Nodmix session ids, Codex thread ids, and `codex resume <thread-id>` commands. See [Diagnostics Export](/gateway/diagnostics).
+    - `/crestodian <request>` runs the Crestodian setup and repair helper from an owner DM.
+    - `/tasks` lists active/recent background tasks for the current session.
+    - `/context [list|detail|map|json]` explains how context is assembled. `map` sends a treemap image of the current session context.
+    - `/whoami` shows your sender id. Alias: `/id`.
+    - `/usage off|tokens|full|cost` controls the per-response usage footer or prints a local cost summary.
+
+  </Accordion>
+  <Accordion title="Skills, allowlists, approvals">
+    - `/skill <name> [input]` runs a skill by name.
+    - `/allowlist [list|add|remove] ...` manages allowlist entries. Text-only.
+    - `/approve <id> <decision>` resolves exec or plugin approval prompts.
+    - `/btw <question>` asks a side question without changing future session context. Alias: `/side`. See [BTW](/tools/btw).
+
+  </Accordion>
+  <Accordion title="Subagents and ACP">
+    - `/subagents list|kill|log|info|send|steer|spawn` manages sub-agent runs for the current session.
+    - `/acp spawn|cancel|steer|close|sessions|status|set-mode|set|cwd|permissions|timeout|model|reset-options|doctor|install|help` manages ACP sessions and runtime options.
+    - `/focus <target>` binds the current Discord thread or Telegram topic/conversation to a session target.
+    - `/unfocus` removes the current binding.
+    - `/agents` lists thread-bound agents for the current session.
+    - `/kill <id|#|all>` aborts one or all running sub-agents.
+    - `/subagents steer <id|#> <message>` sends steering to a running sub-agent. See [Steer](/tools/steer).
+
+  </Accordion>
+  <Accordion title="Owner-only writes and admin">
+    - `/config show|get|set|unset` reads or writes `nodmix.json`. Owner-only. Requires `commands.config: true`.
+    - `/mcp show|get|set|unset` reads or writes Nodmix-managed MCP server config under `mcp.servers`. Owner-only. Requires `commands.mcp: true`.
+    - `/plugins list|inspect|show|get|install|enable|disable` inspects or mutates plugin state. `/plugin` is an alias. Owner-only for writes. Requires `commands.plugins: true`.
+    - `/debug show|set|unset|reset` manages runtime-only config overrides. Owner-only. Requires `commands.debug: true`.
+    - `/restart` restarts Nodmix when enabled. Default: enabled; set `commands.restart: false` to disable it.
+    - `/send on|off|inherit` sets send policy. Owner-only.
+
+  </Accordion>
+  <Accordion title="Voice, TTS, channel control">
+    - `/tts on|off|status|chat|latest|provider|limit|summary|audio|help` controls TTS. See [TTS](/tools/tts).
+    - `/activation mention|always` sets group activation mode.
+    - `/bash <command>` runs a host shell command. Text-only. Alias: `! <command>`. Requires `commands.bash: true` plus `tools.elevated` allowlists.
+    - `!poll [sessionId]` checks a background bash job.
+    - `!stop [sessionId]` stops a background bash job.
+
+  </Accordion>
+</AccordionGroup>
+
+### Generated dock commands
+
+Dock commands switch the current session's reply route to another linked
+channel. See [Channel docking](/concepts/channel-docking) for setup,
+examples, and troubleshooting.
+
+Dock commands are generated from channel plugins with native-command support. Current bundled set:
+
+- `/dock-discord` (alias: `/dock_discord`)
+- `/dock-mattermost` (alias: `/dock_mattermost`)
+- `/dock-slack` (alias: `/dock_slack`)
+- `/dock-telegram` (alias: `/dock_telegram`)
+
+Use dock commands from a direct chat to switch the current session's reply route to another linked channel. The agent keeps the same session context, but future replies for that session are delivered to the selected channel peer.
+
+Dock commands require `session.identityLinks`. The source sender and target peer must be in the same identity group, for example `["telegram:123", "discord:456"]`. If a Telegram user with id `123` sends `/dock_discord`, Nodmix stores `lastChannel: "discord"` and `lastTo: "456"` on the active session. If the sender is not linked to a Discord peer, the command replies with a setup hint instead of falling through to normal chat.
+
+Docking changes the active session route only. It does not create channel accounts, grant access, bypass channel allowlists, or move transcript history to another session. Use `/dock-telegram`, `/dock-slack`, `/dock-mattermost`, or another generated dock command to switch the route again.
+
+### Bundled plugin commands
+
+Bundled plugins can add more slash commands. Current bundled commands in this repo:
+
+- `/dreaming [on|off|status|help]` toggles memory dreaming. See [Dreaming](/concepts/dreaming).
+- `/pair [qr|status|pending|approve|cleanup|notify]` manages device pairing/setup flow. See [Pairing](/channels/pairing).
+- `/phone status|arm <camera|screen|writes|all> [duration]|disarm` temporarily arms high-risk phone node commands.
+- `/voice status|list [limit]|set <voiceId|name>` manages Talk voice config. On Discord, the native command name is `/talkvoice`.
+- `/card ...` sends LINE rich card presets. See [LINE](/channels/line).
+- `/codex status|models|threads|resume|compact|review|diagnostics|account|mcp|skills` inspects and controls the bundled Codex app-server harness. See [Codex harness](/plugins/codex-harness).
+- QQBot-only commands:
+  - `/bot-ping`
+  - `/bot-version`
+  - `/bot-help`
+  - `/bot-upgrade`
+  - `/bot-logs`
+
+### Dynamic skill commands
+
+User-invocable skills are also exposed as slash commands:
+
+- `/skill <name> [input]` always works as the generic entrypoint.
+- skills may also appear as direct commands like `/prose` when the skill/plugin registers them.
+- native skill-command registration is controlled by `commands.nativeSkills` and `channels.<provider>.commands.nativeSkills`.
+- command specs can provide `descriptionLocalizations` for native surfaces that support localized descriptions, including Discord.
+
+<AccordionGroup>
+  <Accordion title="Argument and parser notes">
+    - Commands accept an optional `:` between the command and args (e.g. `/think: high`, `/send: on`, `/help:`).
+    - `/new <model>` accepts a model alias, `provider/model`, or a provider name (fuzzy match); if no match, the text is treated as the message body.
+    - For full provider usage breakdown, use `nodmix status --usage`.
+    - `/allowlist add|remove` requires `commands.config=true` and honors channel `configWrites`.
+    - In multi-account channels, config-targeted `/allowlist --account <id>` and `/config set channels.<provider>.accounts.<id>...` also honor the target account's `configWrites`.
+    - `/usage` controls the per-response usage footer; `/usage cost` prints a local cost summary from Nodmix session logs.
+    - `/restart` is enabled by default; set `commands.restart: false` to disable it.
+    - `/plugins install <spec>` accepts the same plugin specs as `nodmix plugins install`: local path/archive, npm package, `git:<repo>`, or `clawhub:<pkg>`. Managed Gateways restart automatically because plugin source modules changed.
+    - `/plugins enable|disable` updates plugin config and triggers Gateway plugin reload for new agent turns.
+
+  </Accordion>
+  <Accordion title="Channel-specific behavior">
+    - Discord-only native command: `/vc join|leave|status` controls voice channels (not available as text). `join` requires a guild and selected voice/stage channel. Requires `channels.discord.voice` and native commands.
+    - Discord thread-binding commands (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`) require effective thread bindings to be enabled (`session.threadBindings.enabled` and/or `channels.discord.threadBindings.enabled`).
+    - ACP command reference and runtime behavior: [ACP agents](/tools/acp-agents).
+
+  </Accordion>
+  <Accordion title="Verbose / trace / fast / reasoning safety">
+    - `/verbose` is meant for debugging and extra visibility; keep it **off** in normal use.
+    - `/trace` is narrower than `/verbose`: it only reveals plugin-owned trace/debug lines and keeps normal verbose tool chatter off.
+    - `/fast on|off` persists a session override. Use the Sessions UI `inherit` option to clear it and fall back to config defaults.
+    - `/fast` is provider-specific: OpenAI/OpenAI Codex map it to `service_tier=priority` on native Responses endpoints, while direct public Anthropic requests, including OAuth-authenticated traffic sent to `api.anthropic.com`, map it to `service_tier=auto` or `standard_only`. See [OpenAI](/providers/openai) and [Anthropic](/providers/anthropic).
+    - Tool failure summaries are still shown when relevant, but detailed failure text is only included when `/verbose full` is enabled.
+    - `/reasoning`, `/verbose`, and `/trace` are risky in group settings: they may reveal internal reasoning, tool output, or plugin diagnostics you did not intend to expose. Prefer leaving them off, especially in group chats.
+
+  </Accordion>
+  <Accordion title="Model switching">
+    - `/model` persists the new session model immediately.
+    - If the agent is idle, the next run uses it right away.
+    - If a run is already active, Nodmix marks a live switch as pending and only restarts into the new model at a clean retry point.
+    - If tool activity or reply output has already started, the pending switch can stay queued until a later retry opportunity or the next user turn.
+    - In the local TUI, `/crestodian [request]` returns from the normal agent TUI to Crestodian. This is separate from message-channel rescue mode and does not grant remote config authority.
+
+  </Accordion>
+  <Accordion title="Fast path and inline shortcuts">
+    - **Fast path:** command-only messages from allowlisted senders are handled immediately (bypass queue + model).
+    - **Group mention gating:** command-only messages from allowlisted senders bypass mention requirements.
+    - **Inline shortcuts (allowlisted senders only):** certain commands also work when embedded in a normal message and are stripped before the model sees the remaining text.
+      - Example: `hey /status` triggers a status reply, and the remaining text continues through the normal flow.
+    - Currently: `/help`, `/commands`, `/status`, `/whoami` (`/id`).
+    - Unauthorized command-only messages are silently ignored, and inline `/...` tokens are treated as plain text.
+
+  </Accordion>
+  <Accordion title="Skill commands and native arguments">
+    - **Skill commands:** `user-invocable` skills are exposed as slash commands. Names are sanitized to `a-z0-9_` (max 32 chars); collisions get numeric suffixes (e.g. `_2`).
+      - `/skill <name> [input]` runs a skill by name (useful when native command limits prevent per-skill commands).
+      - By default, skill commands are forwarded to the model as a normal request.
+      - Skills may optionally declare `command-dispatch: tool` to route the command directly to a tool (deterministic, no model).
+      - Example: `/prose` (OpenProse plugin) — see [OpenProse](/prose).
+    - **Native command arguments:** Discord uses autocomplete for dynamic options (and button menus when you omit required args). Telegram and Slack show a button menu when a command supports choices and you omit the arg. Dynamic choices are resolved against the target session model, so model-specific options such as `/think` levels follow that session's `/model` override.
+
+  </Accordion>
+</AccordionGroup>
+
+## `/tools`
+
+`/tools` answers a runtime question, not a config question: **what this agent can use right now in this conversation**.
+
+- Default `/tools` is compact and optimized for quick scanning.
+- `/tools verbose` adds short descriptions.
+- Native-command surfaces that support arguments expose the same mode switch as `compact|verbose`.
+- Results are session-scoped, so changing agent, channel, thread, sender authorization, or model can change the output.
+- `/tools` includes tools that are actually reachable at runtime, including core tools, connected plugin tools, and channel-owned tools.
+
+For profile and override editing, use the Control UI Tools panel or config/catalog surfaces instead of treating `/tools` as a static catalog.
+
+## Usage surfaces (what shows where)
+
+- **Provider usage/quota** (example: "Claude 80% left") shows up in `/status` for the current model provider when usage tracking is enabled. Nodmix normalizes provider windows to `% left`; for MiniMax, remaining-only percent fields are inverted before display, and `model_remains` responses prefer the chat-model entry plus a model-tagged plan label.
+- **Token/cache lines** in `/status` can fall back to the latest transcript usage entry when the live session snapshot is sparse. Existing nonzero live values still win, and transcript fallback can also recover the active runtime model label plus a larger prompt-oriented total when stored totals are missing or smaller.
+- **Execution vs runtime:** `/status` reports `Execution` for the effective sandbox path and `Runtime` for who is actually running the session: `Nodmix Pi Default`, `OpenAI Codex`, a CLI backend, or an ACP backend.
+- **Per-response tokens/cost** is controlled by `/usage off|tokens|full` (appended to normal replies).
+- `/model status` is about **models/auth/endpoints**, not usage.
+
+## Model selection (`/model`)
+
+`/model` is implemented as a directive.
+
+Examples:
+
+```
+/model
+/model list
+/model 3
+/model openai/gpt-5.4
+/model opus@anthropic:default
+/model status
+```
+
+Notes:
+
+- `/model` and `/model list` show a compact, numbered picker (model family + available providers).
+- On Discord, `/model` and `/models` open an interactive picker with provider and model dropdowns plus a Submit step. The picker respects `agents.defaults.models`, including `provider/*` entries, so provider-scoped discovery can keep the picker below Discord's 25-option component limit.
+- `/model <#>` selects from that picker (and prefers the current provider when possible).
+- `/model status` shows the detailed view, including configured provider endpoint (`baseUrl`) and API mode (`api`) when available.
+
+## Debug overrides
+
+`/debug` lets you set **runtime-only** config overrides (memory, not disk). Owner-only. Disabled by default; enable with `commands.debug: true`.
+
+Examples:
+
+```
+/debug show
+/debug set messages.responsePrefix="[nodmix]"
+/debug set channels.whatsapp.allowFrom=["+1555","+4477"]
+/debug unset messages.responsePrefix
+/debug reset
+```
+
+<Note>
+Overrides apply immediately to new config reads, but do **not** write to `nodmix.json`. Use `/debug reset` to clear all overrides and return to the on-disk config.
+</Note>
+
+## Plugin trace output
+
+`/trace` lets you toggle **session-scoped plugin trace/debug lines** without turning on full verbose mode.
+
+Examples:
+
+```text
+/trace
+/trace on
+/trace off
+```
+
+Notes:
+
+- `/trace` with no argument shows the current session trace state.
+- `/trace on` enables plugin trace lines for the current session.
+- `/trace off` disables them again.
+- Plugin trace lines can appear in `/status` and as a follow-up diagnostic message after the normal assistant reply.
+- `/trace` does not replace `/debug`; `/debug` still manages runtime-only config overrides.
+- `/trace` does not replace `/verbose`; normal verbose tool/status output still belongs to `/verbose`.
+
+## Config updates
+
+`/config` writes to your on-disk config (`nodmix.json`). Owner-only. Disabled by default; enable with `commands.config: true`.
+
+Examples:
+
+```
+/config show
+/config show messages.responsePrefix
+/config get messages.responsePrefix
+/config set messages.responsePrefix="[nodmix]"
+/config unset messages.responsePrefix
+```
+
+<Note>
+Config is validated before write; invalid changes are rejected. `/config` updates persist across restarts.
+</Note>
+
+## MCP updates
+
+`/mcp` writes Nodmix-managed MCP server definitions under `mcp.servers`. Owner-only. Disabled by default; enable with `commands.mcp: true`.
+
+Examples:
+
+```text
+/mcp show
+/mcp show context7
+/mcp set context7={"command":"uvx","args":["context7-mcp"]}
+/mcp unset context7
+```
+
+<Note>
+`/mcp` stores config in Nodmix config, not Pi-owned project settings. Runtime adapters decide which transports are actually executable.
+</Note>
+
+## Plugin updates
+
+`/plugins` lets operators inspect discovered plugins and toggle enablement in config. Read-only flows can use `/plugin` as an alias. Disabled by default; enable with `commands.plugins: true`.
+
+Examples:
+
+```text
+/plugins
+/plugins list
+/plugin show context7
+/plugins enable context7
+/plugins disable context7
+```
+
+<Note>
+- `/plugins list` and `/plugins show` use real plugin discovery against the current workspace plus on-disk config.
+- `/plugins install` installs from ClawHub, npm, git, local directories, and archives.
+- `/plugins enable|disable` updates plugin config only; it does not install or uninstall plugins.
+- Enable and disable changes hot-reload Gateway plugin runtime surfaces for new agent turns; install restarts managed Gateways automatically because plugin source modules changed.
+
+</Note>
+
+## Surface notes
+
+<AccordionGroup>
+  <Accordion title="Sessions per surface">
+    - **Text commands** run in the normal chat session (DMs share `main`, groups have their own session).
+    - **Native commands** use isolated sessions:
+      - Discord: `agent:<agentId>:discord:slash:<userId>`
+      - Slack: `agent:<agentId>:slack:slash:<userId>` (prefix configurable via `channels.slack.slashCommand.sessionPrefix`)
+      - Telegram: `telegram:slash:<userId>` (targets the chat session via `CommandTargetSessionKey`)
+    - **`/stop`** targets the active chat session so it can abort the current run.
+
+  </Accordion>
+  <Accordion title="Slack specifics">
+    `channels.slack.slashCommand` is still supported for a single `/nodmix`-style command. If you enable `commands.native`, you must create one Slack slash command per built-in command (same names as `/help`). Command argument menus for Slack are delivered as ephemeral Block Kit buttons.
+
+    Slack native exception: register `/agentstatus` (not `/status`) because Slack reserves `/status`. Text `/status` still works in Slack messages.
+
+  </Accordion>
+</AccordionGroup>
+
+## BTW side questions
+
+`/btw` is a quick **side question** about the current session. `/side` is an alias.
+
+Unlike normal chat:
+
+- it uses the current session as background context,
+- in Codex harness sessions, it runs as an ephemeral Codex side thread with the
+  current Codex permissions and native tool surface,
+- in non-Codex sessions, it keeps the older direct one-shot side-call behavior,
+- it does not change future session context,
+- it is not written to transcript history,
+- it is delivered as a live side result instead of a normal assistant message.
+
+That makes `/btw` useful when you want a temporary clarification while the main task keeps going.
+
+Example:
+
+```text
+/btw what are we doing right now?
+/side what changed while the main run continued?
+```
+
+See [BTW Side Questions](/tools/btw) for the full behavior and client UX details.
+
+## Related
+
+- [Creating skills](/tools/creating-skills)
+- [Skills](/tools/skills)
+- [Skills config](/tools/skills-config)

package/docs/tools/steer.md

@@ -0,0 +1,84 @@
+---
+summary: "Steer an active run without changing queue mode"
+read_when:
+  - Using /steer or /tell while an agent is already running
+  - Comparing /steer with /queue modes
+  - Deciding whether to steer the current run, a sub-agent, or an ACP session
+title: "Steer"
+sidebarTitle: "Steer"
+---
+
+`/steer` first tries to send guidance to an already-active run. It is for
+"adjust this run while it is still working" moments. If the current runtime
+cannot accept steering, Nodmix sends the message as a normal prompt instead
+of dropping it.
+
+## Current session
+
+Use top-level `/steer` to target the active run for the current session:
+
+```text
+/steer prefer the smaller patch and keep the tests focused
+/tell summarize before making the next tool call
+```
+
+Behavior:
+
+- Targets only the current session's active run.
+- Works independently of the session's `/queue` mode.
+- Starts a normal turn with the same message when the session is idle or the
+  active run cannot accept steering.
+- Uses the active runtime's steering path, so the model sees the guidance at
+  the next supported runtime boundary.
+
+## Steer vs queue
+
+`/queue steer` makes normal inbound messages try to steer the active run when
+they arrive while a run is active. `/steer <message>` is an explicit command
+that tries to inject that command's message into the active run at the next
+supported runtime boundary, regardless of the stored `/queue` setting. When
+that injection is not available, the command prefix is stripped and `<message>`
+continues as a normal prompt.
+
+Use:
+
+- `/steer <message>` when you want to guide the active run right now.
+- `/queue steer` when you want future normal messages to steer active runs by
+  default.
+- `/queue collect` or `/queue followup` when future normal messages should wait
+  for a later turn instead of steering the active run.
+- `/queue interrupt` when the newest message should replace the active run
+  instead of steering it.
+
+For queue modes and steering boundaries, see [Command queue](/concepts/queue) and
+[Steering queue](/concepts/queue-steering).
+
+## Sub-agents
+
+Use `/subagents steer` when the target is a child run:
+
+```text
+/subagents steer 2 focus only on the API surface
+```
+
+Top-level `/steer` does not select a sub-agent by id or list index. It always
+targets the current session's active run. See [Sub-agents](/tools/subagents) for
+sub-agent ids, labels, and control commands.
+
+## ACP sessions
+
+Use `/acp steer` when the target is an ACP harness session:
+
+```text
+/acp steer --session agent:main:acp:codex tighten the repro
+```
+
+See [ACP agents](/tools/acp-agents) for ACP session selection and runtime
+behavior.
+
+## Related
+
+- [Slash commands](/tools/slash-commands)
+- [Command queue](/concepts/queue)
+- [Steering queue](/concepts/queue-steering)
+- [Sub-agents](/tools/subagents)