@eliya-oss/agent-slack 0.1.6 → 0.1.8

package/.agents/cli-api.md

@@ -50,12 +50,12 @@ agent-slack auth logout --profile work
 
 Auth behavior:
 
-- Primary setup: `agent-slack auth login` uses the bundled Agent Slack public Client ID, opens Slack in the browser with PKCE, and stores a local user-token profile.
-- Users can also provide an existing Bot User OAuth Token with `--token`.
-- A normal user should not create a Slack app or provide client credentials.
-- Developer fallback: OAuth mode can use BYO Slack app credentials. The **Client ID** and **Client Secret** come from the Slack app's **Basic Information -> App Credentials** section.
-- OAuth opens the Slack OAuth URL in the default browser by default. Use `--no-open` to print the URL only, or `--auth-url-out PATH` for headless agents and tests.
-- PKCE uses `user_scope=...`; BYO OAuth bot scopes go in `scope=...`.
+- Primary setup: `agent-slack auth login` uses the bundled Agent Slack public Client ID, opens Slack in the browser with PKCE, and stores a local Slack profile.
+- Users can also provide an existing Slack bot token with `--token`.
+- Browser login uses Agent Slack's public Slack app.
+- Development and self-hosted OAuth can use Slack app credentials. The **Client ID** and **Client Secret** come from the Slack app's **Basic Information > App Credentials** section.
+- OAuth opens the Slack OAuth URL in the default browser by default. Use `--no-open` to print the URL only, or `--auth-url-out PATH` for headless agents.
+- PKCE uses `user_scope=...`; OAuth with app credentials uses `scope=...` for bot scopes.
 - Default local callback: `http://localhost:45454/oauth/slack/callback`.
 - Stores profiles outside the project directory. The default store is `~/.config/agent-slack/profiles.json`; set `AGENT_SLACK_TOKEN_STORE=keychain` on macOS to keep token secrets in Keychain and only profile metadata on disk.
 - Supports multiple profiles and workspaces.
@@ -111,7 +111,7 @@ agent-slack conversation history CHANNEL_ID [--oldest TS] [--latest TS] [--all]
 agent-slack conversation context CHANNEL_ID [--since 24h] [--include users,reactions,files,threads]
 ```
 
-`conversation context` is the agent-friendly form: normalized messages, hydrated users, thread refs, file refs, reactions, and permalinks in one deterministic payload.
+`conversation context` returns normalized messages, hydrated users, thread refs, file refs, reactions, and permalinks in one deterministic payload for agents.
 
 ### Threads and messages
 
@@ -172,8 +172,8 @@ cat payload.json | agent-slack api call conversations.history -
 
 Rules:
 
-- `--payload`, `@file`, and `-` pass raw JSON matching Slack's API fields.
-- Convenience flags may be added later, but raw payload always wins coverage.
+- `--payload`, `@file`, and `-` pass JSON matching Slack's API fields.
+- Convenience flags may be added later, but JSON payloads keep full Web API coverage.
 - `--raw` returns Slack's exact response body.
 - Without `--raw`, responses use the CLI envelope below.
 - `--all --format ndjson` streams item records for cursor-paginated methods.
@@ -252,7 +252,7 @@ Schema output includes:
 
 - command description and examples
 - positional args and flags
-- raw payload schema when known
+- payload schema when known
 - required Slack method/scopes
 - output schema
 - pagination behavior
@@ -286,8 +286,8 @@ agent-slack api call some.newMethod --payload @request.json --json
 
 ## Build Order
 
-1. Auth profiles, keychain storage, and `auth test/status/scopes`.
-2. Generic `api call`, raw payload input, JSON envelope, structured errors.
+1. Slack profiles, keychain storage, and `auth test/status/scopes`.
+2. Generic `api call`, JSON payload input, JSON envelope, structured errors.
 3. `describe --json` and generated method catalog.
 4. Conversation, thread, user, file, and search convenience commands.
 5. Agent context commands with hydration and NDJSON streaming.

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @eliya-oss/agent-slack
 
+## 0.1.8
+
+### Patch Changes
+
+- Keep README auth onboarding focused on browser login and clean up auth help copy.
+
+## 0.1.7
+
+### Patch Changes
+
+- Polish CLI, README, bundled skill, and agent docs copy.
+
 ## 0.1.6
 
 ### Patch Changes
@@ -18,7 +30,7 @@
 
 - Add Slack PKCE browser login.
 
-  No-flag `auth login` now uses the bundled Agent Slack public Client ID with Slack OAuth PKCE for browser-based user-token login without a client secret. Token setup and BYO OAuth remain available for bot-token, development, and self-hosted workflows.
+  No-flag `auth login` now uses the bundled Agent Slack public Client ID with Slack OAuth PKCE for browser login without a client secret. Token setup and OAuth with app credentials remain available for bot-token, development, and self-hosted workflows.
 
 ## 0.1.3
 

package/README.md

@@ -1,13 +1,11 @@
 <div align="center">
 
-# Agent Slack
+# agent-slack
 
-Slack context for AI agents, exposed through the `agent-slack` CLI.
+Slack context for AI agents via the `agent-slack` CLI.
 Short alias: `aslk`.
 
-```bash
-npm install -g @eliya-oss/agent-slack
-```
+<pre align="center">npm install -g @eliya-oss/agent-slack</pre>
 
 <img src="./assets/terminal.webp" alt="Agent Slack terminal screenshot" width="820">
 
@@ -25,28 +23,11 @@ agent-slack api call conversations.info --payload '{"channel":"C123"}' --json
 
 ## Auth
 
-Browser login:
-
 ```bash
 agent-slack auth login
 ```
 
-Agent Slack opens Slack in the browser with PKCE and stores a local user-token profile. Users do not create Slack apps or handle Slack client secrets.
-
-Token setup:
-
-```bash
-agent-slack auth login --token "$SLACK_BOT_TOKEN" --scopes channels:read,channels:history,users:read
-```
-
-Developer/self-hosted fallback:
-
-1. Create a Slack app at <https://api.slack.com/apps>.
-2. Add the needed scopes under **OAuth & Permissions**.
-3. Install it to your workspace and copy the **Bot User OAuth Token**.
-4. Run `agent-slack auth login --token "$SLACK_BOT_TOKEN" --scopes ...`.
-
-OAuth with `--client-id` and `--client-secret` is only for bring-your-own-app development and self-hosted setups.
+Opens Slack in your browser and stores a local profile for future commands.
 
 ## Skill
 
@@ -63,3 +44,11 @@ Project docs live in `.agents/`.
 ## License
 
 MIT
+
+## Sponsors
+
+<p align="center">
+	<a href="https://github.com/sponsors/Newbie012">
+		<img src="https://cdn.jsdelivr.net/gh/newbie012/sponsors/sponsors.svg">
+	</a>
+</p>

package/dist/application/commands.js

@@ -200,8 +200,8 @@ const authCommand = async (parsed, services) => {
         const clientSecret = flagString(parsed, "client-secret") ?? process.env.AGENT_SLACK_CLIENT_SECRET ?? process.env.SLK_CLIENT_SECRET ?? process.env.SLACK_CLIENT_SECRET;
         const byoOAuth = flagBoolean(parsed, "oauth");
         if (byoOAuth && (clientId === undefined || clientSecret === undefined)) {
-            throw new UsageError("BYO Slack OAuth needs both --client-id and --client-secret.", {
-                suggestion: "Use --token with an existing Bot User OAuth Token, or pass both BYO Slack app credentials from Basic Information -> App Credentials."
+            throw new UsageError("Slack OAuth with app credentials needs both --client-id and --client-secret.", {
+                suggestion: "Use --token with an existing Slack bot token, or pass both app credentials from Basic Information > App Credentials."
             });
         }
         const scopes = splitCsv(flagString(parsed, "scopes"));

package/dist/cli/metadata.js

@@ -8,7 +8,7 @@ export const CLI_VERSION = packageJson.version ?? "0.0.0";
 export const commandMetadata = [
     {
         path: ["describe"],
-        summary: "Describe the full CLI command tree as JSON.",
+        summary: "Print the full command catalog as JSON.",
         flags: ["--json"],
         safety: "read",
         output: "command metadata",
@@ -16,7 +16,7 @@ export const commandMetadata = [
     },
     {
         path: ["completion"],
-        summary: "Generate shell completion words.",
+        summary: "Generate a shell completion script.",
         args: ["bash|zsh"],
         safety: "read",
         output: "shell completion script",
@@ -24,7 +24,7 @@ export const commandMetadata = [
     },
     {
         path: ["auth", "status"],
-        summary: "Show the active Slack auth profile.",
+        summary: "Show the active Slack profile.",
         flags: ["--profile", "--json"],
         safety: "read",
         output: "profile status",
@@ -44,7 +44,7 @@ export const commandMetadata = [
     },
     {
         path: ["auth", "scopes"],
-        summary: "Show granted scopes for the active profile.",
+        summary: "Show scopes granted to the active profile.",
         flags: ["--profile", "--json"],
         safety: "read",
         output: "scope list",
@@ -52,7 +52,7 @@ export const commandMetadata = [
     },
     {
         path: ["auth", "profiles", "list"],
-        summary: "List local auth profiles.",
+        summary: "List local Slack profiles.",
         flags: ["--json"],
         safety: "read",
         output: "profile list",
@@ -60,7 +60,7 @@ export const commandMetadata = [
     },
     {
         path: ["auth", "logout"],
-        summary: "Delete a local auth profile.",
+        summary: "Delete a local Slack profile.",
         flags: ["--profile", "--json"],
         safety: "destructive",
         output: "deleted profile status",
@@ -68,7 +68,7 @@ export const commandMetadata = [
     },
     {
         path: ["auth", "test"],
-        summary: "Call Slack auth.test for the active profile.",
+        summary: "Test the active Slack profile.",
         methods: ["auth.test"],
         scopes: [],
         safety: "read",
@@ -77,7 +77,7 @@ export const commandMetadata = [
     },
     {
         path: ["team", "get"],
-        summary: "Show workspace info.",
+        summary: "Show Slack workspace details.",
         methods: ["team.info"],
         scopes: ["team:read"],
         safety: "read",
@@ -95,7 +95,7 @@ export const commandMetadata = [
     },
     {
         path: ["enterprise", "get"],
-        summary: "Show enterprise/workspace identity from team info.",
+        summary: "Show enterprise and workspace identity.",
         methods: ["team.info"],
         scopes: ["team:read"],
         safety: "read",
@@ -163,7 +163,7 @@ export const commandMetadata = [
     },
     {
         path: ["api", "call"],
-        summary: "Call any Slack Web API method using a raw JSON payload.",
+        summary: "Call a Slack Web API method with a JSON payload.",
         args: ["METHOD", "PAYLOAD_STDIN_MARKER"],
         flags: ["--payload", "--profile", "--token", "--all", "--raw", "--format", "--allow-write", "--yes", "--json"],
         safety: "unknown",
@@ -175,7 +175,7 @@ export const commandMetadata = [
     },
     {
         path: ["api", "methods", "list"],
-        summary: "List bundled Slack method metadata.",
+        summary: "List bundled Slack Web API metadata.",
         flags: ["--family", "--json"],
         safety: "read",
         output: "method metadata list",
@@ -211,7 +211,7 @@ export const commandMetadata = [
     },
     {
         path: ["conversation", "context"],
-        summary: "Return agent-friendly channel context.",
+        summary: "Build channel context for agents.",
         args: ["CHANNEL_ID"],
         methods: ["conversations.history", "conversations.replies", "users.info"],
         scopes: ["channels:history", "users:read"],
@@ -241,7 +241,7 @@ export const commandMetadata = [
     },
     {
         path: ["message", "permalink"],
-        summary: "Return a Slack permalink for a message.",
+        summary: "Get a Slack permalink for a message.",
         flags: ["--channel", "--ts", "--json"],
         methods: ["chat.getPermalink"],
         safety: "read",
@@ -250,7 +250,7 @@ export const commandMetadata = [
     },
     {
         path: ["search", "context"],
-        summary: "Search Slack for agent context.",
+        summary: "Search Slack for relevant context.",
         flags: ["--query", "--content-types", "--json"],
         methods: ["assistant.search.context"],
         scopes: ["search:read.public", "search:read.private"],
@@ -312,7 +312,7 @@ export const renderHumanHelp = (path) => {
     return [
         PRIMARY_COMMAND_NAME,
         "",
-        "Agent-readable Slack CLI.",
+        "Slack context CLI for agents.",
         "",
         "Commands:",
         ...commands.map((item) => `  ${item.path.join(" ").padEnd(28)} ${item.summary}`)
@@ -326,32 +326,31 @@ const renderAuthLoginHelp = () => [
     "Browser login",
     "  agent-slack auth login",
     "",
-    "  Opens Slack in the browser with PKCE and stores a local user-token profile.",
-    "  No Slack app secret is stored in the CLI.",
+    "  Opens Slack in the browser and stores a local Slack profile.",
     "",
-    "Token setup",
+    "Headless setup",
     "  agent-slack auth login --token \"$SLACK_BOT_TOKEN\" --scopes channels:read,channels:history,users:read",
     "",
-    "  Stores an existing Slack Bot User OAuth Token as a local profile.",
+    "  Stores an existing bot token as a local Slack profile.",
     "",
-    "Developer fallback: bring your own Slack app OAuth credentials",
+    "Development and self-hosted OAuth",
     "  agent-slack auth login --oauth --client-id \"$SLACK_CLIENT_ID\" --client-secret \"$SLACK_CLIENT_SECRET\"",
     "",
     "Options",
     "  --profile NAME          Save as a named profile.",
-    "  --token TOKEN           Store an existing Bot User OAuth Token.",
-    "  --scopes LIST           Token scopes, or PKCE user scopes when --oauth is not used.",
-    "  --user-scopes LIST      Explicit Slack user scopes for OAuth.",
-    "  --oauth                 Use Slack OAuth with BYO app credentials.",
+    "  --token TOKEN           Store an existing Slack bot token.",
+    "  --scopes LIST           Scopes to request or record.",
+    "  --user-scopes LIST      User scopes to request during OAuth.",
+    "  --oauth                 Use Slack OAuth with app credentials.",
     "  --client-id VALUE       Override the Slack app Client ID.",
     "  --client-secret VALUE   Slack app Client Secret.",
     "  --no-open               Print OAuth URL instead of opening the browser.",
     "  --auth-url-out PATH     Write OAuth URL for headless flows.",
-    "  --json                  Emit a parseable JSON envelope.",
+    "  --json                  Emit machine-readable JSON.",
     "",
     "Notes",
-    "  Normal users should not create a Slack app or handle client credentials.",
-    "  BYO OAuth credentials are only for development and self-hosted setups.",
+    "  Browser login uses PKCE with Agent Slack's public Slack app.",
+    "  App credentials are for development and self-hosted setups.",
     ""
 ].join("\n");
 export const renderCompletion = (shell) => {

package/dist/output/envelope.js

@@ -46,7 +46,7 @@ export const errorEnvelope = (error) => {
 const suggestionFor = (tag) => {
     switch (tag) {
         case "NotAuthenticated":
-            return "Run agent-slack auth login or provide a seeded profile for tests.";
+            return "Run agent-slack auth login, or use --token with an existing Slack bot token.";
         case "MissingScope":
             return "Reinstall or reauthorize the Slack app with the missing scope.";
         case "SlackRateLimited":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eliya-oss/agent-slack",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Slack context CLI for AI agents.",
   "type": "module",
   "packageManager": "pnpm@11.9.0",

package/skills/agent-slack/SKILL.md

@@ -1,17 +1,17 @@
 ---
 name: agent-slack
-description: "Use when Codex needs Slack context through the `agent-slack` CLI: authenticate, inspect profiles/scopes, read channels, messages, threads, files, users, search context, or call Slack Web API methods with agent-readable JSON or NDJSON output."
+description: "Use when Codex needs Slack context through the `agent-slack` CLI: authenticate, inspect profiles/scopes, read channels, messages, threads, files, users, search context, or call Slack Web API methods with JSON or NDJSON output."
 ---
 
 # agent-slack CLI
 
-Use `agent-slack` as the Slack context boundary. `aslk` is the short alias. Prefer read-only commands and preserve Slack's permission model: the CLI can only return data allowed by the active token, scopes, channel membership, workspace policy, and Slack plan.
+Use `agent-slack` as the Slack context boundary. `aslk` is the short alias. Prefer read-only commands. The CLI can only return data allowed by the active token, scopes, channel membership, workspace policy, and Slack plan.
 
 ## Workflow
 
 1. Check availability: `agent-slack describe --json`.
 2. Check auth: `agent-slack auth status --json`.
-3. If auth is missing, ask the user to run `agent-slack auth login`. It opens Slack in the browser with PKCE and stores a local user-token profile.
+3. If auth is missing, ask the user to run `agent-slack auth login`. It opens Slack in the browser with PKCE and stores a local Slack profile.
 4. Use specific read commands before raw API calls.
 5. Use `--json` for bounded results and `--format ndjson` for large context streams.
 6. Read structured errors from stderr; do not parse progress text from stdout.
@@ -24,27 +24,27 @@ Browser login:
 agent-slack auth login
 ```
 
-Agent Slack opens Slack in the browser with PKCE and stores a local user-token profile. Users should not create a Slack app or handle `client-id`/`client-secret`.
+Agent Slack opens Slack in the browser and stores a local Slack profile.
 
-Token setup:
+Headless setup with an existing bot token:
 
 ```bash
 agent-slack auth login --token "$SLACK_BOT_TOKEN" --scopes channels:read,channels:history,users:read --json
 ```
 
-This stores an existing Slack Bot User OAuth Token as a local profile.
+This stores an existing Slack bot token as a local profile.
 
-Developer/self-hosted fallback:
+Development and self-hosted OAuth:
 
 1. Create or open a Slack app at https://api.slack.com/apps.
-2. Go to **OAuth & Permissions**, add the needed bot scopes, install the app to the workspace, and copy the **Bot User OAuth Token**.
-3. For OAuth auth, get the **Client ID** and **Client Secret** from **Basic Information -> App Credentials** in that Slack app, then run:
+2. Go to **OAuth & Permissions**, add the needed bot scopes, install the app to the workspace, and copy the bot token.
+3. For OAuth auth, get the **Client ID** and **Client Secret** from **Basic Information > App Credentials** in that Slack app, then run:
 
 ```bash
 agent-slack auth login --oauth --client-id "$SLACK_CLIENT_ID" --client-secret "$SLACK_CLIENT_SECRET" --json
 ```
 
-Treat Slack app creation and client credentials as an advanced developer fallback only.
+Use Slack app credentials only when the user explicitly asks for development or self-hosted OAuth setup.
 
 ## Common Commands