From 87e08fc7d55aef7e1b37f30ba49269719b0467e0 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Wed, 7 Jan 2026 11:23:09 +0100
Subject: [PATCH] docs: document channel/topic overrides

---
 docs/gateway/configuration.md | 27 ++++++++++++++++++++++++---
 docs/providers/discord.md     | 16 +++++++++++++++-
 docs/providers/slack.md       | 17 ++++++++++++++++-
 docs/providers/telegram.md    |  8 ++++++++
 4 files changed, 63 insertions(+), 5 deletions(-)

diff --git a/docs/gateway/configuration.md b/docs/gateway/configuration.md
index 8fb78d7cc..c8aa219a4 100644
--- a/docs/gateway/configuration.md
+++ b/docs/gateway/configuration.md
@@ -467,7 +467,16 @@ Set `telegram.enabled: false` to disable automatic startup.
     botToken: "your-bot-token",
     dmPolicy: "pairing",                 // pairing | allowlist | open | disabled
     allowFrom: ["tg:123456789"],         // optional; "open" requires ["*"]
-    groups: { "*": { requireMention: true } },
+    groups: {
+      "*": { requireMention: true, autoReply: false },
+      "-1001234567890": {
+        allowFrom: ["@admin"],
+        systemPrompt: "Keep answers brief.",
+        topics: {
+          "99": { skills: ["search"], systemPrompt: "Stay on topic." }
+        }
+      }
+    },
     streamMode: "partial",               // off | partial | block (draft streaming)
     actions: { reactions: true },        // tool action gates (false disables)
     mediaMaxMb: 5,
@@ -527,7 +536,13 @@ Configure the Discord bot by setting the bot token and optional gating:
         users: ["987654321098765432"],      // optional per-guild user allowlist
         channels: {
           general: { allow: true },
-          help: { allow: true, requireMention: true }
+          help: {
+            allow: true,
+            requireMention: true,
+            users: ["987654321098765432"],
+            skills: ["docs"],
+            systemPrompt: "Short answers only."
+          }
         }
       }
     },
@@ -563,7 +578,13 @@ Slack runs in Socket Mode and requires both a bot token and app token:
     },
     channels: {
       C123: { allow: true, requireMention: true },
-      "#general": { allow: true, requireMention: false }
+      "#general": {
+        allow: true,
+        autoReply: false,
+        users: ["U123"],
+        skills: ["docs"],
+        systemPrompt: "Short answers only."
+      }
     },
     reactionNotifications: "own", // off | own | all | allowlist
     reactionAllowlist: ["U123"],
diff --git a/docs/providers/discord.md b/docs/providers/discord.md
index a68882569..f5ef24f6f 100644
--- a/docs/providers/discord.md
+++ b/docs/providers/discord.md
@@ -197,7 +197,14 @@ Notes:
         users: ["987654321098765432", "steipete"],
         channels: {
           general: { allow: true },
-          help: { allow: true, requireMention: true }
+          help: {
+            allow: true,
+            requireMention: true,
+            users: ["987654321098765432"],
+            skills: ["search", "docs"],
+            systemPrompt: "Keep answers short.",
+            autoReply: false
+          }
         }
       }
     }
@@ -218,6 +225,13 @@ Ack reactions are controlled globally via `messages.ackReaction` +
 - `guilds."*"`: default per-guild settings applied when no explicit entry exists.
 - `guilds.<id>.slug`: optional friendly slug used for display names.
 - `guilds.<id>.users`: optional per-guild user allowlist (ids or names).
+- `guilds.<id>.channels.<channel>.allow`: allow/deny the channel when `groupPolicy="allowlist"`.
+- `guilds.<id>.channels.<channel>.requireMention`: mention gating for the channel.
+- `guilds.<id>.channels.<channel>.autoReply`: if `true`, reply to all messages (overrides `requireMention`).
+- `guilds.<id>.channels.<channel>.users`: optional per-channel user allowlist.
+- `guilds.<id>.channels.<channel>.skills`: skill filter (omit = all skills, empty = none).
+- `guilds.<id>.channels.<channel>.systemPrompt`: extra system prompt for the channel (combined with channel topic).
+- `guilds.<id>.channels.<channel>.enabled`: set `false` to disable the channel.
 - `guilds.<id>.channels`: channel rules (keys are channel slugs or ids).
 - `guilds.<id>.requireMention`: per-guild mention requirement (overridable per channel).
 - `guilds.<id>.reactionNotifications`: reaction system event mode (`off`, `own`, `all`, `allowlist`).
diff --git a/docs/providers/slack.md b/docs/providers/slack.md
index f897e534f..f21c4f044 100644
--- a/docs/providers/slack.md
+++ b/docs/providers/slack.md
@@ -157,7 +157,13 @@ Slack uses Socket Mode only (no HTTP webhook server). Provide both tokens:
     },
     "channels": {
       "C123": { "allow": true, "requireMention": true },
-      "#general": { "allow": true, "requireMention": false }
+      "#general": {
+        "allow": true,
+        "autoReply": false,
+        "users": ["U123"],
+        "skills": ["search", "docs"],
+        "systemPrompt": "Keep answers short."
+      }
     },
     "reactionNotifications": "own",
     "reactionAllowlist": ["U123"],
@@ -203,6 +209,15 @@ Ack reactions are controlled globally via `messages.ackReaction` +
 - `slack.groupPolicy` controls channel handling (`open|disabled|allowlist`).
 - `allowlist` requires channels to be listed in `slack.channels`.
 
+Channel options (`slack.channels.<id>` or `slack.channels.<name>`):
+- `allow`: allow/deny the channel when `groupPolicy="allowlist"`.
+- `requireMention`: mention gating for the channel.
+- `autoReply`: if `true`, reply to every message (overrides `requireMention`).
+- `users`: optional per-channel user allowlist.
+- `skills`: skill filter (omit = all skills, empty = none).
+- `systemPrompt`: extra system prompt for the channel (combined with topic/purpose).
+- `enabled`: set `false` to disable the channel.
+
 ## Delivery targets
 Use these with cron/CLI sends:
 - `user:<id>` for DMs
diff --git a/docs/providers/telegram.md b/docs/providers/telegram.md
index 8c8514d3c..99ad6448d 100644
--- a/docs/providers/telegram.md
+++ b/docs/providers/telegram.md
@@ -43,6 +43,7 @@ Telegram forum topics include a `message_thread_id` per message. Clawdbot:
 - Appends `:topic:<threadId>` to the Telegram group session key so each topic is isolated.
 - Sends typing indicators and replies with `message_thread_id` so responses stay in the topic.
 - Exposes `MessageThreadId` + `IsForum` in template context for routing/templating.
+- Topic-specific configuration is available under `telegram.groups.<chatId>.topics.<threadId>` (skills, allowlists, auto-reply, system prompts, disable).
 
 Private topics (DM forum mode) also include `message_thread_id`. Clawdbot:
 - Appends `:topic:<threadId>` to **DM** session keys for isolation.
@@ -115,6 +116,13 @@ Provider options:
 - `telegram.groupPolicy`: `open | allowlist | disabled` (default: open).
 - `telegram.groupAllowFrom`: group sender allowlist (ids/usernames).
 - `telegram.groups`: per-group defaults + allowlist (use `"*"` for global defaults).
+  - `telegram.groups.<id>.requireMention`: mention gating default.
+  - `telegram.groups.<id>.autoReply`: reply to every message (overrides `requireMention`).
+  - `telegram.groups.<id>.skills`: skill filter (omit = all skills, empty = none).
+  - `telegram.groups.<id>.allowFrom`: per-group sender allowlist override.
+  - `telegram.groups.<id>.systemPrompt`: extra system prompt for the group.
+  - `telegram.groups.<id>.enabled`: disable the group when `false`.
+  - `telegram.groups.<id>.topics.<threadId>.*`: per-topic overrides (same fields as group).
 - `telegram.replyToMode`: `off | first | all`.
 - `telegram.textChunkLimit`: outbound chunk size (chars).
 - `telegram.streamMode`: `off | partial | block` (draft streaming).