From d7055f8fd2fe1d81684e7db67f7accba9cd838d0 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Sun, 11 Jan 2026 03:42:34 +0000
Subject: [PATCH] docs: align reaction semantics

---
 docs/cli/message.md     | 17 +++++++++--------
 docs/tools/reactions.md | 10 +++++-----
 2 files changed, 14 insertions(+), 13 deletions(-)

diff --git a/docs/cli/message.md b/docs/cli/message.md
index 4164885e7..22cfa6a92 100644
--- a/docs/cli/message.md
+++ b/docs/cli/message.md
@@ -59,44 +59,45 @@ Target formats (`--to`):
 
 - `react`
   - Providers: Discord/Slack/Telegram/WhatsApp
-  - Required: `--to`, `--message-id`
+  - Required: `--message-id`, `--to` or `--channel-id`
   - Optional: `--emoji`, `--remove`, `--participant`, `--from-me`, `--channel-id`
+  - Note: `--remove` requires `--emoji` (omit `--emoji` to clear own reactions where supported; see /tools/reactions)
   - WhatsApp only: `--participant`, `--from-me`
 
 - `reactions`
   - Providers: Discord/Slack
-  - Required: `--to`, `--message-id`
+  - Required: `--message-id`, `--to` or `--channel-id`
   - Optional: `--limit`, `--channel-id`
 
 - `read`
   - Providers: Discord/Slack
-  - Required: `--to`
+  - Required: `--to` or `--channel-id`
   - Optional: `--limit`, `--before`, `--after`, `--channel-id`
   - Discord only: `--around`
 
 - `edit`
   - Providers: Discord/Slack
-  - Required: `--to`, `--message-id`, `--message`
+  - Required: `--message-id`, `--message`, `--to` or `--channel-id`
   - Optional: `--channel-id`
 
 - `delete`
   - Providers: Discord/Slack
-  - Required: `--to`, `--message-id`
+  - Required: `--message-id`, `--to` or `--channel-id`
   - Optional: `--channel-id`
 
 - `pin` / `unpin`
   - Providers: Discord/Slack
-  - Required: `--to`, `--message-id`
+  - Required: `--message-id`, `--to` or `--channel-id`
   - Optional: `--channel-id`
 
 - `pins` (list)
   - Providers: Discord/Slack
-  - Required: `--to`
+  - Required: `--to` or `--channel-id`
   - Optional: `--channel-id`
 
 - `permissions`
   - Providers: Discord
-  - Required: `--to`
+  - Required: `--to` or `--channel-id`
   - Optional: `--channel-id`
 
 - `search`
diff --git a/docs/tools/reactions.md b/docs/tools/reactions.md
index 151f6805e..62b865521 100644
--- a/docs/tools/reactions.md
+++ b/docs/tools/reactions.md
@@ -7,13 +7,13 @@ read_when:
 
 Shared reaction semantics across providers:
 
-- `emoji` is required for reactions.
-- `emoji=""` removes the bot's reaction(s) on the message.
-- `remove: true` removes the specified emoji when supported.
+- `emoji` is required when adding a reaction.
+- `emoji=""` (or omitting `emoji`) removes the bot's reaction(s) when supported.
+- `remove: true` removes the specified emoji when supported (requires `emoji`).
 
 Provider notes:
 
 - **Discord/Slack**: empty `emoji` removes all of the bot's reactions on the message; `remove: true` removes just that emoji.
-- **Telegram**: `remove: true` removes your own reaction (Bot API limitation).
-- **WhatsApp**: `remove: true` maps to empty emoji (remove bot reaction).
+- **Telegram**: empty `emoji` removes the bot's reactions; `remove: true` also removes reactions but still requires a non-empty `emoji` for tool validation.
+- **WhatsApp**: empty `emoji` removes the bot reaction; `remove: true` maps to empty emoji (still requires `emoji`).
 - **Signal**: inbound reaction notifications emit system events when `signal.reactionNotifications` is enabled.