From 03792a9fb8d145df8cf375406481d88d2da2af6a Mon Sep 17 00:00:00 2001
From: Harish Kumar <22562634+harry-harish@users.noreply.github.com>
Date: Fri, 10 Jul 2026 13:10:06 +0530
Subject: [PATCH] docs(connector-slack): document the full Slack scope + event
 set
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The scope table only listed assistant:write + chat:write; the shipped
surfaces need more. Grounded each entry against the adapter's actual API
calls / event registrations:
- app_mentions:read (#155 @peek-in-channel), channels/groups/im:history
  (thread auto-continue + DMs), files:write (#156 share_session upload),
  canvases:write (#159 journey canvas), files:read (journey files.info
  permalink — without it the journey degrades to Block Kit), commands (/peek).
- Added Event subscriptions + Socket Mode sections and a reinstall note.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Signed-off-by: Harish Kumar <22562634+harry-harish@users.noreply.github.com>
---
 packages/connector-slack/README.md | 48 ++++++++++++++++++++++--------
 1 file changed, 36 insertions(+), 12 deletions(-)

diff --git a/packages/connector-slack/README.md b/packages/connector-slack/README.md
index 4c66521..cf58112 100644
--- a/packages/connector-slack/README.md
+++ b/packages/connector-slack/README.md
@@ -1,24 +1,48 @@
 # @peekdev/connector-slack
 
-Slack surface adapter for the peek connector platform. Connects a peek agent
-to Slack via Bolt's Socket Mode, routing Assistant thread messages and `/peek`
-slash commands to the connector core.
+Slack surface adapter for the peek connector platform. Connects a peek agent to
+Slack via Bolt's Socket Mode, routing Assistant-pane threads, `@peek` channel
+mentions, DMs, and the `/peek` slash command to the connector core.
 
 ## Slack app setup
 
-### Required scopes
+The connector runs over **Socket Mode**, so it needs a bot token (`xoxb-…`) and an
+app-level token (`xapp-…`, scope `connections:write`). Each capability maps to a
+specific bot-token scope below.
 
-| Scope | Why |
+### Bot token scopes
+
+| Scope | Why it's needed |
 |---|---|
-| `assistant:write` | Required to register the app as an AI assistant in Slack |
-| `chat:write` | Required to post messages and set the "thinking…" status |
+| `chat:write` | Post every reply, consent card, and the "thinking…" status (`chat.postMessage`, `assistant.threads.setStatus`). |
+| `assistant:write` | Register the app as an AI assistant and set thread status / title / suggested prompts. |
+| `app_mentions:read` | Receive `@peek …` mentions in a channel (the shared-debugging surface). |
+| `channels:history` | Receive public-channel message events so a peek thread auto-continues without re-mentioning. |
+| `groups:history` | Same, for private channels. |
+| `im:history` | Receive direct-message events (the DM / Assistant 1:1 surface). |
+| `files:write` | Upload a session bundle to the thread (`share_session` → `files.uploadV2`). |
+| `canvases:write` | Create the session-journey canvas (`render_session_journey` → `conversations.canvases.create`). |
+| `files:read` | Resolve the canvas permalink (`files.info`) so the journey posts a clickable link. Without it the journey silently falls back to a Block Kit summary. |
+| `commands` | The `/peek` slash command. |
+
+> Scope changes only take effect after you **reinstall** the app to the workspace.
+
+### Event subscriptions (bot events)
+
+Subscribe the bot to:
+
+- `app_mention` — `@peek` in a channel.
+- `message.channels` / `message.groups` — channel / private-channel messages (thread auto-continue).
+- `message.im` — direct messages.
+
+Assistant-thread events come with the **Agents & Assistants** feature — enable it if you
+use the Assistant pane.
 
-### Slack app scope — `chat:write`
+### Note — `chat:write` vs `assistant:write`
 
-The assistant "thinking…" status calls `assistant.threads.setStatus`. Slack is
-migrating this capability from the `assistant:write` scope to `chat:write`. Add
-**`chat:write`** to the bot token scopes in your Slack app manifest. Without it
-the status is silently skipped (the turn still works); every other message uses
+The assistant "thinking…" status calls `assistant.threads.setStatus`. Slack is migrating
+this capability from `assistant:write` to `chat:write`, so keep **both**. Without
+`chat:write` the status is silently skipped (the turn still works); every reply uses
 `chat.postMessage`, which also requires `chat:write`.
 
 ## Usage