From bd2e0031718b92016a8cd65b4c59f8eb0c494502 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Tue, 6 Jan 2026 01:52:01 +0100
Subject: [PATCH] docs: expand Slack scope notes

---
 CHANGELOG.md  |  1 +
 docs/slack.md | 38 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 39 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7d3572d31..07afb65df 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -35,6 +35,7 @@
 - Heartbeat: make HEARTBEAT_OK ack padding configurable across heartbeat and cron delivery. (#238) — thanks @jalehman
 - WhatsApp: set sender E.164 for direct chats so owner commands work in DMs.
 - Slack: keep auto-replies in the original thread when responding to thread messages. Thanks @scald for PR #251.
+- Docs: clarify Slack manifest scopes (current vs optional) with references. Thanks @jarvis-medmatic for PR #235.
 - Control UI: avoid Slack config ReferenceError by reading slack config snapshots. Thanks @sreekaransrinath for PR #249.
 - Telegram: honor routing.groupChat.mentionPatterns for group mention gating. Thanks @regenrek for PR #242.
 
diff --git a/docs/slack.md b/docs/slack.md
index 2a287176d..d68d4e1a7 100644
--- a/docs/slack.md
+++ b/docs/slack.md
@@ -98,6 +98,44 @@ Use this Slack app manifest to create the app quickly (adjust the name/command i
 }
 ```
 
+## Scopes (current vs optional)
+Slack's Conversations API is type-scoped: you only need the scopes for the
+conversation types you actually touch (channels, groups, im, mpim). See
+https://api.slack.com/docs/conversations-api for the overview.
+
+### Required by current code
+- `chat:write` (send/update/delete messages via `chat.postMessage`)
+  https://api.slack.com/methods/chat.postMessage
+- `im:write` (open DMs via `conversations.open` for user DMs)
+  https://api.slack.com/methods/conversations.open
+- `channels:history`, `groups:history`, `im:history`, `mpim:history`
+  (`conversations.history` in `src/slack/actions.ts`)
+  https://api.slack.com/methods/conversations.history
+- `channels:read`, `groups:read`, `im:read`, `mpim:read`
+  (`conversations.info` in `src/slack/monitor.ts`)
+  https://api.slack.com/methods/conversations.info
+- `users:read` (`users.info` in `src/slack/monitor.ts` + `src/slack/actions.ts`)
+  https://api.slack.com/methods/users.info
+- `reactions:read`, `reactions:write` (`reactions.get` / `reactions.add`)
+  https://api.slack.com/methods/reactions.get
+  https://api.slack.com/methods/reactions.add
+- `pins:read`, `pins:write` (`pins.list` / `pins.add` / `pins.remove`)
+  https://api.slack.com/scopes/pins:read
+  https://api.slack.com/scopes/pins:write
+- `emoji:read` (`emoji.list`)
+  https://api.slack.com/scopes/emoji:read
+- `files:write` (uploads via `files.uploadV2`)
+  https://api.slack.com/messaging/files/uploading
+
+### Not needed today (but likely future)
+- `mpim:write` (only if we add group-DM open/DM start via `conversations.open`)
+- `groups:write` (only if we add private-channel management: create/rename/invite/archive)
+- `chat:write.public` (only if we want to post to channels the bot isn't in)
+  https://api.slack.com/scopes/chat:write.public
+- `users:read.email` (only if we need email fields from `users.info`)
+  https://api.slack.com/changelog/2017-04-narrowing-email-access
+- `files:read` (only if we start listing/reading file metadata)
+
 ## Config
 Slack uses Socket Mode only (no HTTP webhook server). Provide both tokens: