From 06a0a64c2923f5b718d2ec235839dfbc4d2560e6 Mon Sep 17 00:00:00 2001
From: AK <variablenix@aklein.me>
Date: Sun, 2 Aug 2026 03:50:11 -0700
Subject: [PATCH] docs: clarify channel plugin overrides and duck actions

---
 docs/configuration.md | 22 +++++++++++++++++++---
 docs/games.md         |  6 ++++++
 2 files changed, 25 insertions(+), 3 deletions(-)

diff --git a/docs/configuration.md b/docs/configuration.md
index b5b99dc..ccc7192 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -21,11 +21,12 @@ networks:
       sasl_user: ""
       sasl_pass: ""
     channels:
-      - "#example"
-      - "#bots"
+      - "#quiet"
+      - "#lobby"
     # Optional per-channel opt-outs. Unlisted plugins keep their global setting.
+    # Only #quiet gets these overrides; #lobby keeps the global plugin settings.
     plugin_overrides:
-      "#bots":
+      "#quiet":
         banter: false
         urltitle: false
         duckhunt: false
@@ -56,6 +57,21 @@ enabled. Channel and plugin names are matched case-insensitively. Overrides
 also keep disabled plugins out of `!help` and `!alias`, and event-driven
 plugins such as Duck Hunt are stopped cleanly for that channel.
 
+For example, with the configuration above, `#quiet` disables banter, URL title
+lookups, and Duck Hunt, while `#lobby` continues using the global settings. To
+disable a different plugin in `#lobby`, add another entry without changing the
+`#quiet` entry:
+
+```yaml
+plugin_overrides:
+  "#quiet":
+    banter: false
+    urltitle: false
+    duckhunt: false
+  "#lobby":
+    banter: false
+```
+
 ## Main settings
 
 - `command_prefix`: command prefix, normally `!`
diff --git a/docs/games.md b/docs/games.md
index 70426d3..0bc935a 100644
--- a/docs/games.md
+++ b/docs/games.md
@@ -165,6 +165,12 @@ such as a flight trail, quack, or flap. There is at most one teaser per hunt
 cycle, and `flavor_min_lead_seconds` keeps it separated from the actual duck
 announcement so it does not turn into channel chatter.
 
+Duck Hunt includes several randomized messages: four flight-trail/flavor
+teasers, multiple duck and quack announcement variants, and eight different
+escape actions including flying, flapping, waddling, slipping through reeds,
+and zooming away. A hunt uses at most one teaser and one final outcome message,
+so the variety does not create a flood.
+
 Commands:
 
 ~~~text