feat: add DM support to message send, improve scope errors, show capabilities in auth status

- Add ResolveDM() to open DM conversations via conversations.open
- Auto-detect user vs channel targets in message send (supports @user, username, user ID)
- Add context-aware FormatSendError() with specific scope hints for DMs vs channels
- Add case-insensitive user lookup in resolver
- Add im:write and chat:write to user scopes in app manifest
- Add capabilities section to auth status output
- Update help text, examples, and docs for DM sending

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

Author: isaacrowntree

docs/src/content/docs/commands.md

@@ -224,24 +224,33 @@ Quick actions:
   Edit:   slackbuzz message edit #general <ts> "new text"
 ```
 
-### `message send <channel> <text>`
+### `message send <channel|user> <text>`
 
-Send a message to a channel or DM.
+Send a message to a channel or DM. The first argument accepts a `#channel-name`, channel ID, `@username`, username, or user ID. When the target looks like a user, the CLI automatically opens a DM conversation via `conversations.open`.
+
+**DM sending requires `im:write` and `chat:write` user token scopes.** Apps created with `slackbuzz app create` include these scopes by default. For existing apps, add the scopes at api.slack.com/apps > OAuth & Permissions.
 
 ```sh
 # Send to a channel
 slackbuzz message send #general "Hello from the terminal!"
 
-# Send a DM
+# Send a DM by @username
 slackbuzz message send @sarah "Quick question about the API"
 
+# Send a DM by username (no @ needed)
+slackbuzz message send herman "Hey, got a minute?"
+
+# Send a DM by user ID
+slackbuzz message send U02P3QC5H24 "Direct message by ID"
+
 # Reply in a thread
 slackbuzz message send #general "Fixed!" --thread-ts 1706000000.000000
 ```
 
 | Flag | Description |
 |------|-------------|
 | `--thread-ts TIMESTAMP` | Send as a thread reply |
+| `--as-bot` | Send as the bot instead of your user account |
 
 ### `message edit <channel> <timestamp> [new-text]`
 

internal/api/errors.go

@@ -3,6 +3,7 @@ package api
 import (
 	"errors"
 	"fmt"
+	"strings"
 )
 
 // AuthExpiredError indicates the token has been revoked or expired (401 response).
@@ -60,3 +61,26 @@ func FormatError(err error) string {
 	}
 	return SlackErrorMessage(err.Error())
 }
+
+// FormatSendError produces a context-aware error message for message send failures.
+// The target is the original channel/user argument from the command.
+func FormatSendError(err error, target string) string {
+	if err == nil {
+		return ""
+	}
+	errStr := err.Error()
+
+	if errStr == "missing_scope" {
+		isDM := strings.HasPrefix(target, "@") || isUserID(target) ||
+			(!strings.HasPrefix(target, "#") && !isChannelID(target))
+		if isDM {
+			return "Missing Slack scope for DMs. Ensure your user token has: im:write, chat:write\n" +
+				"  Check scopes at api.slack.com/apps > OAuth & Permissions"
+		}
+		return "Missing scope for posting. Ensure your token has: chat:write\n" +
+			"  Check scopes at api.slack.com/apps > OAuth & Permissions"
+	}
+
+	return SlackErrorMessage(errStr)
+}
+

internal/api/resolve.go

@@ -129,6 +129,39 @@ func (r *Resolver) loadChannels() error {
 	return nil
 }
 
+// ResolveDM takes a username, @username, or user ID and returns a DM channel ID.
+// It resolves the user and opens (or retrieves) a DM conversation via conversations.open.
+func (r *Resolver) ResolveDM(nameOrID string) (string, error) {
+	userID, err := r.ResolveUser(nameOrID)
+	if err != nil {
+		return "", err
+	}
+
+	ch, _, _, err := r.client.OpenConversation(&slack.OpenConversationParameters{
+		Users: []string{userID},
+	})
+	if err != nil {
+		return "", fmt.Errorf("failed to open DM with %q: %w", nameOrID, err)
+	}
+	return ch.ID, nil
+}
+
+// LooksLikeUser returns true if the target looks like a user reference
+// (starts with @, starts with U/W, or is not #-prefixed and not a channel ID).
+func LooksLikeUser(target string) bool {
+	if strings.HasPrefix(target, "@") {
+		return true
+	}
+	if isUserID(target) {
+		return true
+	}
+	if strings.HasPrefix(target, "#") || isChannelID(target) {
+		return false
+	}
+	// Bare name — assume user if it doesn't look like a channel ID
+	return true
+}
+
 func (r *Resolver) loadUsers() error {
 	users, err := r.client.GetUsers()
 	if err != nil {
@@ -140,8 +173,16 @@ func (r *Resolver) loadUsers() error {
 	for _, u := range users {
 		if !u.Deleted {
 			r.users[u.Name] = u.ID
+			lower := strings.ToLower(u.Name)
+			if lower != u.Name {
+				r.users[lower] = u.ID
+			}
 			if u.Profile.DisplayName != "" {
 				r.users[u.Profile.DisplayName] = u.ID
+				lowerDisplay := strings.ToLower(u.Profile.DisplayName)
+				if lowerDisplay != u.Profile.DisplayName {
+					r.users[lowerDisplay] = u.ID
+				}
 			}
 		}
 	}

pkg/cmd/app/create.go

@@ -85,6 +85,8 @@ var appManifest = map[string]interface{}{
 				"users:read",
 			},
 			"user": []string{
+				"chat:write",
+				"im:write",
 				"search:read",
 				"stars:read",
 				"stars:write",

pkg/cmd/auth/status.go

@@ -90,5 +90,25 @@ func statusRun(f *cmdutil.Factory) error {
 	}
 	fmt.Fprintln(ios.Out)
 
+	// Capabilities section
+	fmt.Fprintln(ios.Out)
+	fmt.Fprintf(ios.Out, "  %s\n", cs.Bold("Capabilities:"))
+
+	botValid := botErr == nil && botToken != ""
+	userValid := userErr == nil && userToken != ""
+
+	if botValid {
+		fmt.Fprintf(ios.Out, "    Bot:  read channels, post messages, reactions, list users\n")
+	}
+	if userValid {
+		fmt.Fprintf(ios.Out, "    User: search, DMs, stars, profile, send messages\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 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:"))
+	}
+
 	return nil
 }

pkg/cmd/message/send.go

@@ -26,15 +26,25 @@ func NewCmdSend(f *cmdutil.Factory) *cobra.Command {
 	opts := &sendOptions{factory: f}
 
 	cmd := &cobra.Command{
-		Use:   "send <channel> [text]",
-		Short: "Send a message to a channel",
+		Use:   "send <channel|user> [text]",
+		Short: "Send a message to a channel or DM",
 		Long: `Post a message to a Slack channel, DM, or thread.
 
-The channel argument accepts #channel-name or a channel ID.
+The first argument accepts a #channel-name, channel ID, @username, or user ID.
+To send a DM, use a username, @username, or user ID as the channel argument.
 If text is omitted, reads from stdin (for piping).`,
-		Example: `  # Send a message
+		Example: `  # Send a message to a channel
   slackbuzz message send #general "Hello, world!"
 
+  # Send a DM by @username
+  slackbuzz message send @sarah "Quick question about the API"
+
+  # Send a DM by username (no @ needed)
+  slackbuzz message send herman "Hey, got a minute?"
+
+  # Send a DM by user ID
+  slackbuzz message send U02P3QC5H24 "Direct message by ID"
+
   # Send to a thread
   slackbuzz message send #general "Reply here" --thread-ts 1234567890.123456
 
@@ -78,8 +88,13 @@ func sendRun(opts *sendOptions) error {
 
 	resolver := api.NewResolver(client.Slack)
 
-	// Resolve channel name to ID
-	channelID, err := resolver.ResolveChannel(opts.channel)
+	// Resolve target to a channel ID — auto-detect DMs vs channels
+	var channelID string
+	if api.LooksLikeUser(opts.channel) {
+		channelID, err = resolver.ResolveDM(opts.channel)
+	} else {
+		channelID, err = resolver.ResolveChannel(opts.channel)
+	}
 	if err != nil {
 		return err
 	}
@@ -119,7 +134,7 @@ func sendRun(opts *sendOptions) error {
 	// Post the message
 	respChannel, respTS, err := client.Slack.PostMessage(channelID, msgOpts...)
 	if err != nil {
-		return fmt.Errorf("%s", api.FormatError(err))
+		return fmt.Errorf("%s", api.FormatSendError(err, opts.channel))
 	}
 
 	if opts.json.WantsJSON() {