fix(send): unescape literal \n and \t in CLI arguments

Literal \n sequences passed as CLI args were sent to Slack as-is,
rendering poorly. Now unescapeShellArtifacts converts \n→newline and
\t→tab, with a placeholder to protect escaped backslashes (\\).

Also adds team setup script, docs, and Makefile setup target.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: isaacrowntree

Makefile

@@ -39,7 +39,7 @@ install-skill:
 	@mkdir -p $(HOME)/.claude/skills
 	@ln -sfn $(CURDIR)/skills/slackbuzz-cli $(HOME)/.claude/skills/slackbuzz-cli
 	@echo "Linked Claude Code skill: slackbuzz-cli → ~/.claude/skills/slackbuzz-cli"
-	@echo ""
-	@echo "Or install via plugin marketplace (no clone required):"
-	@echo "  /plugin marketplace add triptechtravel/slackbuzz-cli"
-	@echo "  /plugin install slackbuzz-cli@slackbuzz-cli"
+
+.PHONY: setup
+setup:
+	@bash scripts/setup.sh

docs/astro.config.mjs

@@ -33,6 +33,7 @@ export default defineConfig({
           items: [
             { label: 'Installation', slug: 'installation' },
             { label: 'Getting Started', slug: 'getting-started' },
+            { label: 'Team Setup', slug: 'team-setup' },
           ],
         },
         {

docs/src/content/docs/ai-agents.md

@@ -140,24 +140,35 @@ slackbuzz later list --json
 slackbuzz threads --since 1d --json
 ```
 
-## Claude Code skill (plugin marketplace)
+## Claude Code skill
 
-Install the SlackBuzz CLI skill into Claude Code so it automatically uses the CLI for Slack operations. No need to clone this repo.
+Install the SlackBuzz CLI skill into Claude Code so it automatically uses the CLI for Slack operations.
+
+### Quick install (no clone required)
 
 ```sh
-# In Claude Code, run:
-/plugin marketplace add triptechtravel/slackbuzz-cli
-/plugin install slackbuzz-cli@slackbuzz-cli
+mkdir -p ~/.claude/skills/slackbuzz-cli
+curl -fsSL https://raw.githubusercontent.com/triptechtravel/slackbuzz-cli/main/skills/slackbuzz-cli/SKILL.md \
+  -o ~/.claude/skills/slackbuzz-cli/SKILL.md
 ```
 
-Once installed, Claude Code will automatically use `slackbuzz` commands when you ask it to send messages, check activity, search Slack, manage reactions, or set your status.
+### From a local clone
 
-If you have the repo cloned locally, you can alternatively symlink the skill:
+If you have the repo checked out, symlink the skill so it stays up to date with `git pull`:
 
 ```sh
 make install-skill
 ```
 
+### What the skill does
+
+Once installed, Claude Code will automatically use `slackbuzz` commands when you ask it to interact with Slack. You can use natural language instead of remembering CLI flags:
+
+- "Check my Slack inbox"
+- "Send @alice a message about the deployment"
+- "Search Slack for the API spec discussion"
+- "Set my status to deep work for 2 hours"
+
 ### @mention resolution
 
 `@name` mentions in message bodies are resolved automatically to Slack's `<@USERID>` format before posting. Agents can write natural `@username` mentions without manually looking up user IDs:

docs/src/content/docs/team-setup.md

@@ -0,0 +1,160 @@
+---
+title: Team Setup
+description: Get your team up and running with slackbuzz in one command.
+---
+
+# Team setup
+
+Get a teammate from zero to fully operational with a single command.
+
+## One-line setup
+
+```sh
+curl -sL https://raw.githubusercontent.com/triptechtravel/slackbuzz-cli/main/scripts/setup.sh | bash
+```
+
+The script walks through each step interactively: installing slackbuzz, setting up the Claude Code skill, and authenticating with Slack. It's idempotent — safe to run again if anything changes.
+
+If you have the repo cloned locally, you can also run:
+
+```sh
+make setup
+```
+
+## What you'll need
+
+| Prerequisite | Required? | Notes |
+|---|---|---|
+| **Homebrew** | Yes | The script installs slackbuzz via `brew`. Install from [brew.sh](https://brew.sh). |
+| **Bot token** (`xoxb-...`) | Yes | Shared across the team. Your team lead will provide this. |
+| **User token** (`xoxp-...`) | Yes | Unique per person. Each team member generates their own. |
+| **Claude Code** | Optional | If installed, the script adds the slackbuzz skill automatically. |
+
+## Understanding the tokens
+
+slackbuzz uses two Slack tokens. The CLI selects the right one automatically — you never need to specify which to use.
+
+**Bot token** (`xoxb-...`) — shared across the team. One app installation covers everyone. Used for reading channels, listing users, and reactions.
+
+**User token** (`xoxp-...`) — unique per person. Each team member installs the Slack app to their own account. Used for sending messages as you, search, DMs, and status.
+
+Both tokens come from the same Slack app. The bot token is the same for everyone on the team; the user token is different per person.
+
+## Manual step-by-step
+
+If you prefer not to use the setup script, here's what it does:
+
+### 1. Install slackbuzz
+
+```sh
+brew install triptechtravel/tap/slackbuzz
+```
+
+### 2. Install the Claude Code skill (optional)
+
+```sh
+mkdir -p ~/.claude/skills/slackbuzz-cli
+curl -fsSL https://raw.githubusercontent.com/triptechtravel/slackbuzz-cli/main/skills/slackbuzz-cli/SKILL.md \
+  -o ~/.claude/skills/slackbuzz-cli/SKILL.md
+```
+
+Or from a local clone:
+
+```sh
+make install-skill
+```
+
+### 3. Authenticate
+
+```sh
+slackbuzz auth login --bot-token
+slackbuzz auth login --user-token
+```
+
+Paste each token when prompted. Get them from your Slack app's **OAuth & Permissions** page.
+
+### 4. Verify
+
+```sh
+slackbuzz doctor
+```
+
+## For team leads: creating the Slack app
+
+Before your team can authenticate, someone needs to create the Slack app and install it to the workspace.
+
+### Create the app
+
+The fastest way is to use the built-in command:
+
+```sh
+slackbuzz app create
+```
+
+This creates a Slack app pre-configured with all required scopes for both token types, opens the install page in your browser, and prompts you to paste the OAuth tokens.
+
+### Share with your team
+
+After the app is installed to your workspace:
+
+1. Go to [api.slack.com/apps](https://api.slack.com/apps) and select the app
+2. Navigate to **OAuth & Permissions**
+3. Copy the **Bot User OAuth Token** (`xoxb-...`) — this is the same for everyone
+4. Share the bot token with your team (e.g., in a private Slack channel or password manager)
+5. Each team member visits the same OAuth page and copies their own **User OAuth Token** (`xoxp-...`)
+
+Then each team member runs the setup script and pastes both tokens when prompted.
+
+### Required scopes
+
+The `slackbuzz app create` command sets these up automatically. If creating the app manually:
+
+**Bot token (`xoxb-`):** `chat:write`, `channels:history`, `channels:read`, `emoji:read`, `groups:history`, `groups:read`, `im:history`, `im:read`, `im:write`, `mpim:history`, `mpim:read`, `reactions:read`, `reactions:write`, `users:read`
+
+**User token (`xoxp-`):** `channels:read`, `chat:write`, `groups:read`, `im:read`, `im:write`, `mpim:read`, `search:read`, `stars:read`, `stars:write`, `users:read`, `users.profile:read`, `users.profile:write`
+
+## Troubleshooting
+
+### "Not authenticated" errors
+
+Re-run authentication for the missing token:
+
+```sh
+slackbuzz auth status          # See which tokens are configured
+slackbuzz auth login --bot-token   # Re-enter bot token
+slackbuzz auth login --user-token  # Re-enter user token
+```
+
+### Scope errors ("missing_scope")
+
+The Slack app needs additional OAuth scopes. Ask your team lead to:
+
+1. Go to [api.slack.com/apps](https://api.slack.com/apps) → your app → **OAuth & Permissions**
+2. Add the missing scope listed in the error message
+3. Reinstall the app to the workspace
+4. Team members re-run `slackbuzz auth login` with the new tokens
+
+### Updating slackbuzz
+
+```sh
+brew update && brew upgrade triptechtravel/tap/slackbuzz
+```
+
+Or re-run the setup script — it detects existing installations and upgrades automatically.
+
+### Updating the Claude Code skill
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/triptechtravel/slackbuzz-cli/main/skills/slackbuzz-cli/SKILL.md \
+  -o ~/.claude/skills/slackbuzz-cli/SKILL.md
+```
+
+If you installed via `make install-skill` (symlink), just `git pull` in the repo.
+
+### Uninstalling
+
+```sh
+brew uninstall slackbuzz                       # Remove the CLI
+rm -rf ~/.claude/skills/slackbuzz-cli          # Remove the Claude Code skill
+slackbuzz auth logout                          # Remove stored tokens (run before uninstall)
+```

pkg/cmd/message/send.go

@@ -251,10 +251,17 @@ func resolveTargetUserID(r *api.Resolver, target string) string {
 
 // unescapeShellArtifacts removes common shell escape sequences that leak into
 // CLI arguments. For example, zsh's history expansion escapes ! as \! when
-// passed through double-quoted strings.
+// passed through double-quoted strings, and literal \n sequences appear when
+// users include newlines in quoted arguments.
 func unescapeShellArtifacts(text string) string {
+	// Protect escaped backslashes (\\) before processing other sequences
+	const placeholder = "\x00BACKSLASH\x00"
+	text = strings.ReplaceAll(text, `\\`, placeholder)
 	text = strings.ReplaceAll(text, `\!`, "!")
 	text = strings.ReplaceAll(text, `\?`, "?")
+	text = strings.ReplaceAll(text, `\n`, "\n")
+	text = strings.ReplaceAll(text, `\t`, "\t")
+	text = strings.ReplaceAll(text, placeholder, `\`)
 	return text
 }
 

pkg/cmd/message/send_test.go

@@ -29,9 +29,9 @@ func TestUnescapeShellArtifacts(t *testing.T) {
 			want: "Hello world",
 		},
 		{
-			name: "legitimate backslash preserved",
+			name: "escaped backslash collapses",
 			text: `path\\to\\file`,
-			want: `path\\to\\file`,
+			want: `path\to\file`,
 		},
 		{
 			name: "mixed content",
@@ -48,6 +48,21 @@ func TestUnescapeShellArtifacts(t *testing.T) {
 			text: `\!`,
 			want: "!",
 		},
+		{
+			name: "literal newlines",
+			text: `line one\n\nline two`,
+			want: "line one\n\nline two",
+		},
+		{
+			name: "literal tab",
+			text: `col1\tcol2`,
+			want: "col1\tcol2",
+		},
+		{
+			name: "mixed escapes with newlines",
+			text: `Build passed\!\n\nDetails at link`,
+			want: "Build passed!\n\nDetails at link",
+		},
 	}
 
 	for _, tt := range tests {