From 831de9ba8ff127fc755408259fb4577b494bc21e Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Sat, 10 Jan 2026 19:56:43 +0100
Subject: [PATCH] docs: clarify group chat behavior

---
 docs/concepts/groups.md | 77 +++++++++++++++++++++++++++++++++++++++++
 docs/start/faq.md       | 24 +++++++++++++
 2 files changed, 101 insertions(+)

diff --git a/docs/concepts/groups.md b/docs/concepts/groups.md
index 1af1a5b8c..d55bd982b 100644
--- a/docs/concepts/groups.md
+++ b/docs/concepts/groups.md
@@ -7,6 +7,37 @@ read_when:
 
 Clawdbot treats group chats consistently across surfaces: WhatsApp, Telegram, Discord, Slack, Signal, iMessage.
 
+## Beginner intro (2 minutes)
+Clawdbot “lives” on your own messaging accounts. There is no separate WhatsApp bot user.
+If **you** are in a group, Clawdbot can see that group and respond there.
+
+Default behavior:
+- Groups are allowed (`groupPolicy: "open"`).
+- Replies require a mention unless you explicitly disable mention gating.
+
+Translation: anyone in the group can trigger Clawdbot by mentioning it.
+
+> TL;DR
+> - **DM access** is controlled by `*.allowFrom`.
+> - **Group access** is controlled by `*.groupPolicy` + allowlists (`*.groups`, `*.groupAllowFrom`).
+> - **Reply triggering** is controlled by mention gating (`requireMention`, `/activation`).
+
+Quick flow (what happens to a group message):
+```
+groupPolicy? disabled -> drop
+groupPolicy? allowlist -> group allowed? no -> drop
+requireMention? yes -> mentioned? no -> store for context only
+otherwise -> reply
+```
+
+If you want...
+| Goal | What to set |
+|------|-------------|
+| Allow all groups but only reply on @mentions | `groups: { "*": { requireMention: true } }` |
+| Disable all group replies | `groupPolicy: "disabled"` |
+| Only specific groups | `groups: { "<group-id>": { ... } }` (no `"*"` key) |
+| Only you can trigger in groups | `groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]` |
+
 ## Session keys
 - Group sessions use `agent:<agentId>:<provider>:group:<id>` session keys (rooms/channels use `agent:<agentId>:<provider>:channel:<id>`).
 - Telegram forum topics add `:topic:<threadId>` to the group id so each topic has its own session.
@@ -65,6 +96,11 @@ Notes:
 - Group DMs are controlled separately (`discord.dm.*`, `slack.dm.*`).
 - Telegram allowlist can match user IDs (`"123456789"`, `"telegram:123456789"`, `"tg:123456789"`) or usernames (`"@alice"` or `"alice"`); prefixes are case-insensitive.
 
+Quick mental model (evaluation order for group messages):
+1) `groupPolicy` (open/disabled/allowlist)
+2) group allowlists (`*.groups`, `*.groupAllowFrom`, provider-specific allowlist)
+3) mention gating (`requireMention`, `/activation`)
+
 ## Mention gating (default)
 Group messages require a mention unless overridden per group. Defaults live per subsystem under `*.groups."*"`.
 
@@ -113,6 +149,47 @@ Notes:
 ## Group allowlists
 When `whatsapp.groups`, `telegram.groups`, or `imessage.groups` is configured, the keys act as a group allowlist. Use `"*"` to allow all groups while still setting default mention behavior.
 
+Common intents (copy/paste):
+
+1) Disable all group replies
+```json5
+{
+  whatsapp: { groupPolicy: "disabled" }
+}
+```
+
+2) Allow only specific groups (WhatsApp)
+```json5
+{
+  whatsapp: {
+    groups: {
+      "123@g.us": { requireMention: true },
+      "456@g.us": { requireMention: false }
+    }
+  }
+}
+```
+
+3) Allow all groups but require mention (explicit)
+```json5
+{
+  whatsapp: {
+    groups: { "*": { requireMention: true } }
+  }
+}
+```
+
+4) Only the owner can trigger in groups (WhatsApp)
+```json5
+{
+  whatsapp: {
+    groupPolicy: "allowlist",
+    groupAllowFrom: ["+15551234567"],
+    groups: { "*": { requireMention: true } }
+  }
+}
+```
+
 ## Activation (owner-only)
 Group owners can toggle per-group activation:
 - `/activation mention`
diff --git a/docs/start/faq.md b/docs/start/faq.md
index 339d5495a..f3192ee54 100644
--- a/docs/start/faq.md
+++ b/docs/start/faq.md
@@ -273,6 +273,30 @@ This runs your login shell and imports only missing expected keys (never overrid
 
 Send `/new` or `/reset` as a standalone message. See [Session management](/concepts/session).
 
+### Do I need to add a “bot account” to a WhatsApp group?
+
+No. Clawdbot runs on **your own account**, so if you’re in the group, Clawdbot can see it.
+By default, anyone in that group can **mention** the bot to trigger a reply.
+
+If you want only **you** to be able to trigger group replies:
+
+```json5
+{
+  whatsapp: {
+    groupPolicy: "allowlist",
+    groupAllowFrom: ["+15551234567"]
+  }
+}
+```
+
+### Why doesn’t Clawdbot reply in a group?
+
+Two common causes:
+- Mention gating is on (default). You must @mention the bot (or match `mentionPatterns`).
+- You configured `whatsapp.groups` without `"*"` and the group isn’t allowlisted.
+
+See [Groups](/concepts/groups) and [Group messages](/concepts/group-messages).
+
 ### Do groups/threads share context with DMs?
 
 Direct chats collapse to the main session by default. Groups/channels have their own session keys, and Telegram topics / Discord threads are separate sessions. See [Groups](/concepts/groups) and [Group messages](/concepts/group-messages).