From 39487998a35c632bf5e267a21454debaf128402b Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Tue, 6 Jan 2026 20:45:40 +0000
Subject: [PATCH] docs: add slash commands guide

---
 docs/faq.md            |  1 +
 docs/hubs.md           |  1 +
 docs/index.md          |  1 +
 docs/slash-commands.md | 53 ++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 56 insertions(+)
 create mode 100644 docs/slash-commands.md

diff --git a/docs/faq.md b/docs/faq.md
index af5c8376d..f38315d36 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -573,6 +573,7 @@ Slash commands are owner-only (gated by `whatsapp.allowFrom` and command authori
 | `/queue instant\|batch\|serial` | Message queuing mode |
 
 Commands are only recognized when the entire message is the command (slash required; no plain-text aliases).
+Full list + config: https://docs.clawd.bot/slash-commands
 
 ### How do I switch models on the fly?
 
diff --git a/docs/hubs.md b/docs/hubs.md
index 2dad7836a..87e74d053 100644
--- a/docs/hubs.md
+++ b/docs/hubs.md
@@ -34,6 +34,7 @@ Use these hubs to discover every page, including deep dives and reference docs t
 - [Sessions (alias)](https://docs.clawd.bot/sessions)
 - [Session tools](https://docs.clawd.bot/session-tool)
 - [Queue](https://docs.clawd.bot/queue)
+- [Slash commands](https://docs.clawd.bot/slash-commands)
 - [RPC adapters](https://docs.clawd.bot/rpc)
 - [TypeBox schemas](https://docs.clawd.bot/typebox)
 - [Presence](https://docs.clawd.bot/presence)
diff --git a/docs/index.md b/docs/index.md
index 3243c7bea..862aa4b39 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -138,6 +138,7 @@ Example:
   - [Docs hubs (all pages linked)](https://docs.clawd.bot/hubs)
   - [FAQ](https://docs.clawd.bot/faq) ← *common questions answered*
   - [Configuration](https://docs.clawd.bot/configuration)
+  - [Slash commands](https://docs.clawd.bot/slash-commands)
   - [Multi-agent routing](https://docs.clawd.bot/multi-agent)
   - [Updating / rollback](https://docs.clawd.bot/updating)
   - [Pairing (DM + nodes)](https://docs.clawd.bot/pairing)
diff --git a/docs/slash-commands.md b/docs/slash-commands.md
new file mode 100644
index 000000000..81cdd12cf
--- /dev/null
+++ b/docs/slash-commands.md
@@ -0,0 +1,53 @@
+---
+summary: "Slash commands: text vs native, config, and supported commands"
+read_when:
+  - Using or configuring chat commands
+  - Debugging command routing or permissions
+---
+# Slash commands
+
+Commands are handled by the Gateway. Send them as a **standalone** message that starts with `/`.
+Inline text like `hello /status` is ignored.
+
+## Config
+
+```json5
+{
+  commands: {
+    native: false,
+    text: true,
+    useAccessGroups: true
+  }
+}
+```
+
+- `commands.text` (default `true`) enables parsing `/...` in chat messages.
+  - On surfaces without native commands (WhatsApp/WebChat/Signal/iMessage), text commands still work even if you set this to `false`.
+- `commands.native` (default `false`) registers native commands on Discord/Slack/Telegram.
+  - `false` clears previously registered commands on Discord/Telegram at startup.
+  - Slack commands are managed in the Slack app and are not removed automatically.
+- `commands.useAccessGroups` (default `true`) enforces allowlists/policies for commands.
+
+## Command list
+
+Text + native (when enabled):
+- `/help`
+- `/status`
+- `/restart`
+- `/activation mention|always` (groups only)
+- `/send on|off|inherit` (owner-only)
+- `/reset` or `/new`
+- `/think <level>` (aliases: `/thinking`, `/t`)
+- `/verbose on|off` (alias: `/v`)
+- `/elevated on|off` (alias: `/elev`)
+- `/model <name>`
+- `/queue <mode>` (plus options like `debounce:2s cap:25 drop:summarize`)
+
+Text-only:
+- `/compact [instructions]`
+
+## Surface notes
+
+- **Text commands** run in the normal chat session (DMs share `main`, groups have their own session).
+- **Native commands** use isolated sessions: `discord:slash:<userId>`, `slack:slash:<userId>`, `telegram:slash:<userId>`.
+- **Slack:** `slack.slashCommand` is still supported for a single `/clawd`-style command. If you enable `commands.native`, you must create one Slack slash command per built-in command (same names as `/help`).