fix: clarify token defaults, add missing users.profile:read scope

The CLI automatically selects the correct token (bot vs user) for each
command. Docs, skill, and auth status now reflect this clearly so agents
don't need to think about --as-bot. Added missing users.profile:read
scope needed for `slackbuzz status`.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: isaacrowntree

README.md

@@ -149,15 +149,23 @@ slackbuzz digest
 
 ## Token types
 
-SlackBuzz uses two types of Slack tokens:
+SlackBuzz uses two types of Slack tokens. **The CLI automatically selects the correct token for each command** — you don't need to specify which to use.
 
-| Token | Prefix | Used for |
-|-------|--------|----------|
-| **Bot token** | `xoxb-` | Sending messages, reading channels, reactions, emoji list |
-| **User token** | `xoxp-` | Search, activity inbox, saved items, status management |
+| Token | Prefix | Automatic usage |
+|-------|--------|-----------------|
+| **Bot token** | `xoxb-` | Reading channels/users, reactions, system notifications (`notify`) |
+| **User token** | `xoxp-` | Sending messages (as you), search, DMs, saved items, status |
+
+Messages post as the authenticated user by default. Pass `--as-bot` on `message send`, `edit`, or `delete` to post as the bot app instead.
 
 The `slackbuzz app create` command creates a Slack app pre-configured with all required scopes for both token types. After installing the app to your workspace, paste both tokens when prompted.
 
+### Required scopes
+
+**Bot token (`xoxb-`):** `chat:write`, `channels:history`, `channels:read`, `emoji:read`, `groups:history`, `groups:read`, `im:history`, `im:read`, `mpim:history`, `mpim:read`, `reactions:read`, `reactions:write`, `users:read`
+
+**User token (`xoxp-`):** `chat:write`, `im:write`, `search:read`, `stars:read`, `stars:write`, `users.profile:read`, `users.profile:write`
+
 ## Cross-tool integration
 
 The `digest` command combines activity from Slack, ClickUp, and GitHub in a single view:

docs/src/content/docs/commands.md

@@ -7,6 +7,27 @@ description: Complete reference for all slackbuzz CLI commands and flags.
 
 All commands are invoked as subcommands of `slackbuzz`. Run `slackbuzz --help` for a summary, or `slackbuzz <command> --help` for details on any command.
 
+## Token selection
+
+The CLI automatically picks the correct token (bot or user) for each command. You don't need to think about it — just run the command.
+
+| Command | Token | Why |
+|---------|-------|-----|
+| `message send`, `edit`, `delete` | **User** | Posts as the authenticated user |
+| `message list` | **Bot** | Reads channel history |
+| `channel list`, `channel info` | **Bot** | Reads channel metadata |
+| `user list`, `user info` | **Bot** | Reads user profiles |
+| `react`, `react remove` | **Bot** | Reactions |
+| `notify` | **Bot** | System/automated notifications |
+| `thread link` | **Bot** | Generates permalinks |
+| `activity`, `threads`, `digest` | **User** | Search API (user-only) |
+| `dm list` | **User** | Search API (user-only) |
+| `message search`, `file search` | **User** | Search API (user-only) |
+| `later list`, `add`, `remove` | **User** | Stars API (user-only) |
+| `status`, `status set`, `clear` | **User** | Profile API (user-only) |
+
+**Override:** Pass `--as-bot` on `message send`, `edit`, or `delete` to post as the bot app instead of the user.
+
 ---
 
 ## activity

docs/src/content/docs/security.md

@@ -19,15 +19,21 @@ Tokens are never logged to stdout or stored in the config file.
 
 ## Token types
 
-SlackBuzz uses two types of Slack tokens:
+SlackBuzz uses two types of Slack tokens. The CLI automatically selects the correct token for each command.
 
-| Token | Prefix | Used for |
-|-------|--------|----------|
-| **Bot token** | `xoxb-` | Sending messages, reading channels, reactions, emoji list |
-| **User token** | `xoxp-` | Search, activity inbox, saved items, status management |
+| Token | Prefix | Automatic usage |
+|-------|--------|-----------------|
+| **Bot token** | `xoxb-` | Reading channels/users, reactions, system notifications |
+| **User token** | `xoxp-` | Sending messages (as you), search, DMs, saved items, status |
 
 Both tokens are stored separately in the keyring. The `slackbuzz app create` command creates a Slack app pre-configured with all required scopes for both token types.
 
+### Required scopes
+
+**Bot (`xoxb-`):** `chat:write`, `channels:history`, `channels:read`, `emoji:read`, `groups:history`, `groups:read`, `im:history`, `im:read`, `mpim:history`, `mpim:read`, `reactions:read`, `reactions:write`, `users:read`
+
+**User (`xoxp-`):** `chat:write`, `im:write`, `search:read`, `stars:read`, `stars:write`, `users.profile:read`, `users.profile:write`
+
 ## Best practices
 
 1. **Use the system keyring**: The default storage method. Avoid overriding it unless necessary.

pkg/cmd/app/create.go

@@ -90,6 +90,7 @@ var appManifest = map[string]interface{}{
 				"search:read",
 				"stars:read",
 				"stars:write",
+				"users.profile:read",
 				"users.profile:write",
 			},
 		},

pkg/cmd/auth/status.go

@@ -98,16 +98,16 @@ func statusRun(f *cmdutil.Factory) error {
 	userValid := userErr == nil && userToken != ""
 
 	if botValid {
-		fmt.Fprintf(ios.Out, "    Bot:  read channels, post messages, reactions, list users\n")
+		fmt.Fprintf(ios.Out, "    Bot:  read channels, list users, reactions, system notifications\n")
 	}
 	if userValid {
-		fmt.Fprintf(ios.Out, "    User: search, DMs, stars, profile, send messages\n")
+		fmt.Fprintf(ios.Out, "    User: send messages (default), search, DMs, stars, profile\n")
 	}
 	if !userValid {
-		fmt.Fprintf(ios.Out, "    %s User token not set — search, DMs, and stars unavailable\n", cs.Yellow("!"))
+		fmt.Fprintf(ios.Out, "    %s User token not set — sending, search, DMs, and stars unavailable\n", cs.Yellow("!"))
 		fmt.Fprintf(ios.Out, "    %s Add with: slackbuzz auth login\n", cs.Gray(" "))
 	} else {
-		fmt.Fprintf(ios.Out, "    %s DM sending requires im:write and chat:write user scopes\n", cs.Gray("Hint:"))
+		fmt.Fprintf(ios.Out, "    %s Messages post as you by default. Use --as-bot to post as the app.\n", cs.Gray("Hint:"))
 	}
 
 	return nil

skills/slackbuzz-cli/SKILL.md

@@ -24,9 +24,12 @@ slackbuzz auth login     # Log in with bot and/or user token
 slackbuzz auth status    # Check auth status and capabilities
 ```
 
-Two token types:
-- **Bot token** (`xoxb-`): Channels, reactions, user lists, posting messages
-- **User token** (`xoxp-`): Search, DMs, stars, status, profile
+Two token types are required. **The CLI automatically selects the right token for each command — you do not need to specify which to use.**
+
+- **Bot token** (`xoxb-`): Used automatically for reading channels, listing users, reactions, and system notifications
+- **User token** (`xoxp-`): Used automatically for sending messages (as the user), search, DMs, saved items, status, and profile
+
+Messages always post as the authenticated user by default. Only use `--as-bot` if you specifically want a message to come from the bot app rather than the user.
 
 ## Messaging
 
@@ -189,14 +192,37 @@ slackbuzz user list
 slackbuzz user info @alice
 ```
 
+## Token Defaults
+
+The CLI automatically selects the correct token for each command. You do not need to think about bot vs user mode — just run the command.
+
+| Command | Token | Rationale |
+|---------|-------|-----------|
+| `message send`, `edit`, `delete` | **User** | Posts as the authenticated user |
+| `message list` | **Bot** | Reads channel history |
+| `channel list`, `channel info` | **Bot** | Reads channel metadata |
+| `user list`, `user info` | **Bot** | Reads user profiles |
+| `react`, `react remove` | **Bot** | Reactions via bot |
+| `notify` | **Bot** | System/automated notifications |
+| `thread link` | **Bot** | Generates permalinks |
+| `activity`, `threads`, `digest` | **User** | Slack search API (user-only) |
+| `dm list` | **User** | Slack search API (user-only) |
+| `message search`, `file search` | **User** | Slack search API (user-only) |
+| `later list`, `add`, `remove` | **User** | Stars API (user-only) |
+| `status`, `status set`, `clear` | **User** | Profile API (user-only) |
+
+**Override:** Pass `--as-bot` on `message send`, `edit`, or `delete` to post as the bot app instead of the user. Only do this when explicitly requested.
+
+**Missing permissions:** If a command fails due to a missing token or scope, the error message will indicate what's needed. Run `slackbuzz auth status` to check available capabilities.
+
 ## Common Flags
 
 | Flag | Description |
 |------|-------------|
 | `--json` | Output as JSON |
 | `--jq <expr>` | Filter JSON with jq expression |
 | `--template <tmpl>` | Format with Go template |
-| `--as-bot` | Use bot token instead of user token (message send) |
+| `--as-bot` | Post as the bot app instead of the user (send/edit/delete only) |
 | `--since <duration>` | Time filter (2h, 1d, 7d, 2w, or YYYY-MM-DD) |
 | `--limit <n>` | Max results |
 
@@ -233,11 +259,12 @@ The CLI automatically strips common shell escape artifacts from message text bef
 
 ## Key Behaviors
 
+- **Automatic token selection**: The CLI picks the right token (bot or user) for each command. No need to specify — just run the command. Use `--as-bot` only when explicitly asked to post as the bot.
 - **DM auto-detection**: `@user`, `U...` IDs, and bare names auto-resolve to DM channels (for the channel/target argument)
 - **@mentions in message body**: Auto-resolved from `@name` to Slack's `<@USERID>` format before posting
 - **First-name shorthand**: `@herman` resolves to `herman.gorbatovskii` or `Herman Gorbatovskii` when unambiguous
 - **Shell unescape**: Common shell artifacts like `\!` are cleaned before sending
 - **Case-insensitive resolution**: User lookup matches display names and usernames regardless of case
-- **Dual tokens**: Bot token for channel ops, user token for search/DMs/status
+- **Permission feedback**: Missing tokens or scopes produce clear error messages. Use `slackbuzz auth status` to check capabilities.
 - **Deeplinks**: Output includes clickable Slack deeplinks
 - **Cross-tool**: Digest combines Slack, ClickUp, and GitHub activity