docs: clarify group chat behavior

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`