diff --git a/docs/configuration.md b/docs/configuration.md
index a8a0a48d7..fd8eff783 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -281,6 +281,11 @@ Configure the Discord bot by setting the bot token and optional gating:
 
 Clawdis starts Discord only when a `discord` config section exists. The token is resolved from `DISCORD_BOT_TOKEN` or `discord.token` (unless `discord.enabled` is `false`). Use `user:<id>` (DM) or `channel:<id>` (guild channel) when specifying delivery targets for cron/CLI commands.
 Guild slugs are lowercase with spaces replaced by `-`; channel keys use the slugged channel name (no leading `#`). Prefer guild ids as keys to avoid rename ambiguity.
+Reaction notification modes:
+- `off`: no reaction events.
+- `own`: all reactions on the bot's own messages.
+- `all`: all reactions on all messages.
+- `allowlist`: reactions from `guilds.<id>.users` on all messages.
 
 ### `imessage` (imsg CLI)
 
diff --git a/docs/discord.md b/docs/discord.md
index b78276609..30c0336e0 100644
--- a/docs/discord.md
+++ b/docs/discord.md
@@ -119,7 +119,11 @@ Note: Guild context `[from:]` lines include `author.tag` + `id` to make ping-rea
   - `roles` (role add/remove, default `false`)
   - `moderation` (timeout/kick/ban, default `false`)
 
-Reaction notifications use `guilds.<id>.reactionNotifications`; `allowlist` checks `guilds.<id>.users`, while `all` ignores that allowlist.
+Reaction notifications use `guilds.<id>.reactionNotifications`:
+- `off`: no reaction events.
+- `own`: all reactions on the bot's own messages.
+- `all`: all reactions on all messages.
+- `allowlist`: reactions from `guilds.<id>.users` on all messages.
 
 ### Tool action defaults