diff --git a/docs/concepts/groups.md b/docs/concepts/groups.md
index d55bd982b..1f4fd43d4 100644
--- a/docs/concepts/groups.md
+++ b/docs/concepts/groups.md
@@ -30,6 +30,8 @@ requireMention? yes -> mentioned? no -> store for context only
 otherwise -> reply
 ```
 
+![Group message flow](/images/groups-flow.svg)
+
 If you want...
 | Goal | What to set |
 |------|-------------|
diff --git a/docs/images/groups-flow.svg b/docs/images/groups-flow.svg
new file mode 100644
index 000000000..06189ff07
--- /dev/null
+++ b/docs/images/groups-flow.svg
@@ -0,0 +1,52 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="960" height="260" viewBox="0 0 960 260" role="img" aria-label="Group message flow">
+  <defs>
+    <style>
+      .box { fill: #f6f5f3; stroke: #2b2b2b; stroke-width: 2; }
+      .drop { fill: #fff1f1; stroke: #a33; stroke-width: 2; }
+      .note { fill: #fffaf0; stroke: #9a7b00; stroke-width: 2; }
+      .text { font: 14px "SF Pro Text", -apple-system, Helvetica, Arial, sans-serif; fill: #1a1a1a; }
+      .label { font: 12px "SF Pro Text", -apple-system, Helvetica, Arial, sans-serif; fill: #333; }
+      .arrow { stroke: #2b2b2b; stroke-width: 2; fill: none; marker-end: url(#arrow); }
+    </style>
+    <marker id="arrow" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto">
+      <path d="M0,0 L8,3 L0,6 Z" fill="#2b2b2b" />
+    </marker>
+  </defs>
+
+  <rect class="box" x="20" y="40" width="140" height="60" rx="8" />
+  <text class="text" x="90" y="75" text-anchor="middle">Group message</text>
+
+  <rect class="box" x="200" y="40" width="160" height="60" rx="8" />
+  <text class="text" x="280" y="68" text-anchor="middle">Group policy</text>
+  <text class="label" x="280" y="86" text-anchor="middle">open / disabled / allowlist</text>
+
+  <rect class="box" x="400" y="40" width="150" height="60" rx="8" />
+  <text class="text" x="475" y="75" text-anchor="middle">Allowlist</text>
+
+  <rect class="box" x="580" y="40" width="170" height="60" rx="8" />
+  <text class="text" x="665" y="68" text-anchor="middle">Mention gating</text>
+  <text class="label" x="665" y="86" text-anchor="middle">requireMention</text>
+
+  <rect class="box" x="780" y="40" width="140" height="60" rx="8" />
+  <text class="text" x="850" y="75" text-anchor="middle">Reply</text>
+
+  <line class="arrow" x1="160" y1="70" x2="200" y2="70" />
+  <line class="arrow" x1="360" y1="70" x2="400" y2="70" />
+  <line class="arrow" x1="550" y1="70" x2="580" y2="70" />
+  <line class="arrow" x1="750" y1="70" x2="780" y2="70" />
+
+  <rect class="drop" x="220" y="150" width="120" height="50" rx="8" />
+  <text class="text" x="280" y="180" text-anchor="middle">Drop</text>
+  <line class="arrow" x1="280" y1="100" x2="280" y2="150" />
+  <text class="label" x="250" y="130" text-anchor="end">disabled</text>
+
+  <rect class="drop" x="410" y="150" width="120" height="50" rx="8" />
+  <text class="text" x="470" y="180" text-anchor="middle">Drop</text>
+  <line class="arrow" x1="475" y1="100" x2="470" y2="150" />
+  <text class="label" x="445" y="130" text-anchor="end">not allowed</text>
+
+  <rect class="note" x="600" y="150" width="200" height="50" rx="8" />
+  <text class="text" x="700" y="175" text-anchor="middle">Store for context</text>
+  <text class="label" x="700" y="192" text-anchor="middle">(no mention)</text>
+  <line class="arrow" x1="665" y1="100" x2="700" y2="150" />
+</svg>