clawskills-mcp 0.1.3 → 0.2.0

package/dist/index.js

@@ -41,13 +41,14 @@ function loadSkills(skillsDir) {
 const SECTION_ALIASES = {
     auth: "Authentication & permissions",
     authentication: "Authentication & permissions",
-    "rate-limits": "Rate limits",
-    "rate_limits": "Rate limits",
-    ratelimits: "Rate limits",
-    errors: "Error handling",
-    "error-handling": "Error handling",
-    pagination: "Pagination",
-    recipes: "Recipes",
+    "rate-limits": "Reliability: rate limits, retries, idempotency",
+    "rate_limits": "Reliability: rate limits, retries, idempotency",
+    ratelimits: "Reliability: rate limits, retries, idempotency",
+    reliability: "Reliability: rate limits, retries, idempotency",
+    errors: "Error handling & troubleshooting",
+    "error-handling": "Error handling & troubleshooting",
+    pagination: "Query patterns & filtering",
+    recipes: "Common workflows (recipes)",
     gotchas: "Gotchas",
     webhooks: "Webhooks",
     overview: "Overview",
@@ -142,6 +143,10 @@ function skillSummary(content) {
     return "";
 }
 // ---------------------------------------------------------------------------
+// Exports for testing
+// ---------------------------------------------------------------------------
+export { loadSkills, extractSection, findSkill, searchSkills, skillSummary };
+// ---------------------------------------------------------------------------
 // MCP Server setup
 // ---------------------------------------------------------------------------
 const SKILLS_DIR = resolveSkillsDir();
@@ -253,7 +258,9 @@ async function main() {
     await server.connect(transport);
     process.stderr.write("[clawskills-mcp] Server running on stdio\n");
 }
-main().catch((err) => {
-    process.stderr.write(`[clawskills-mcp] Fatal: ${err}\n`);
-    process.exit(1);
-});
+if (process.env.NODE_ENV !== "test") {
+    main().catch((err) => {
+        process.stderr.write(`[clawskills-mcp] Fatal: ${err}\n`);
+        process.exit(1);
+    });
+}

package/dist/index.test.js

@@ -0,0 +1,219 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { fileURLToPath } from "url";
+import { loadSkills, extractSection, findSkill, searchSkills, skillSummary } from "./index.js";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REAL_SKILLS_DIR = path.resolve(__dirname, "../../skills");
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function makeTempSkillsDir(skills) {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "clawskills-test-"));
+    for (const [slug, content] of Object.entries(skills)) {
+        const skillDir = path.join(dir, slug);
+        fs.mkdirSync(skillDir, { recursive: true });
+        fs.writeFileSync(path.join(skillDir, "skill.md"), content, "utf-8");
+    }
+    return dir;
+}
+const SAMPLE_CONTENT = `# GitHub Skill
+
+A skill doc for GitHub API.
+
+## Overview
+
+GitHub is a code hosting platform for version control and collaboration.
+
+## Authentication & permissions
+
+Use a Personal Access Token (PAT) or OAuth token.
+
+Scopes: repo, read:user, etc.
+
+## Rate limits
+
+- Authenticated: 5000 req/hour
+- Unauthenticated: 60 req/hour
+
+## Recipes
+
+### Create an issue
+
+POST /repos/{owner}/{repo}/issues
+`;
+let tempDir;
+beforeAll(() => {
+    tempDir = makeTempSkillsDir({ github: SAMPLE_CONTENT, salesforce: "# Salesforce\nCRM platform.\n## Overview\nSalesforce is a CRM." });
+});
+afterAll(() => {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+});
+// ---------------------------------------------------------------------------
+// loadSkills
+// ---------------------------------------------------------------------------
+describe("loadSkills", () => {
+    it("loads skill files from a directory", () => {
+        const skills = loadSkills(tempDir);
+        expect(skills.size).toBe(2);
+        expect(skills.has("github")).toBe(true);
+        expect(skills.has("salesforce")).toBe(true);
+    });
+    it("returns empty map for missing directory", () => {
+        const skills = loadSkills("/nonexistent/path/that/does/not/exist");
+        expect(skills.size).toBe(0);
+    });
+    it("skips directories without skill.md", () => {
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), "clawskills-test-noskill-"));
+        try {
+            fs.mkdirSync(path.join(dir, "nodoc"), { recursive: true });
+            const skills = loadSkills(dir);
+            expect(skills.size).toBe(0);
+        }
+        finally {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    });
+});
+// ---------------------------------------------------------------------------
+// findSkill
+// ---------------------------------------------------------------------------
+describe("findSkill", () => {
+    let skills;
+    beforeAll(() => {
+        skills = loadSkills(tempDir);
+    });
+    it("returns key for exact match", () => {
+        expect(findSkill(skills, "github")).toBe("github");
+    });
+    it("is case-insensitive", () => {
+        expect(findSkill(skills, "GitHub")).toBe("github");
+        expect(findSkill(skills, "GITHUB")).toBe("github");
+    });
+    it("matches slug-normalized input (hub-spot → hubspot)", () => {
+        const m = new Map([["hubspot", "content"]]);
+        expect(findSkill(m, "hub-spot")).toBe("hubspot");
+    });
+    it("matches by prefix", () => {
+        expect(findSkill(skills, "git")).toBe("github");
+    });
+    it("returns undefined for no match", () => {
+        expect(findSkill(skills, "zzznomatch")).toBeUndefined();
+    });
+});
+// ---------------------------------------------------------------------------
+// extractSection
+// ---------------------------------------------------------------------------
+describe("extractSection", () => {
+    it("resolves alias 'auth' to the correct header", () => {
+        const result = extractSection(SAMPLE_CONTENT, "auth");
+        expect(result).not.toBeNull();
+        expect(result).toContain("Personal Access Token");
+    });
+    it("finds section by direct header text", () => {
+        const result = extractSection(SAMPLE_CONTENT, "Rate limits");
+        expect(result).not.toBeNull();
+        expect(result).toContain("5000 req/hour");
+    });
+    it("returns null for missing section", () => {
+        const result = extractSection(SAMPLE_CONTENT, "nonexistent-section-xyz");
+        expect(result).toBeNull();
+    });
+    it("stops at the next ## header", () => {
+        const result = extractSection(SAMPLE_CONTENT, "Rate limits");
+        expect(result).not.toContain("POST /repos");
+    });
+});
+// ---------------------------------------------------------------------------
+// searchSkills
+// ---------------------------------------------------------------------------
+describe("searchSkills", () => {
+    let skills;
+    beforeAll(() => {
+        skills = loadSkills(tempDir);
+    });
+    it("returns results for a matching query", () => {
+        const results = searchSkills(skills, "Personal Access Token");
+        expect(results.length).toBeGreaterThan(0);
+        expect(results[0].skill).toBe("github");
+        expect(results[0].excerpts.length).toBeGreaterThan(0);
+    });
+    it("is case-insensitive", () => {
+        const results = searchSkills(skills, "personal access token");
+        expect(results.length).toBeGreaterThan(0);
+    });
+    it("returns empty array on no match", () => {
+        const results = searchSkills(skills, "zzznomatchquery");
+        expect(results).toEqual([]);
+    });
+    it("caps excerpts at 5 per skill", () => {
+        // Create a skill with many matches
+        const manyMatches = Array.from({ length: 20 }, (_, i) => `line ${i}: keyword`).join("\n");
+        const m = new Map([["test", manyMatches]]);
+        const results = searchSkills(m, "keyword");
+        expect(results[0].excerpts.length).toBeLessThanOrEqual(5);
+    });
+});
+// ---------------------------------------------------------------------------
+// skillSummary
+// ---------------------------------------------------------------------------
+describe("skillSummary", () => {
+    it("skips # headers and returns first non-empty line", () => {
+        const summary = skillSummary(SAMPLE_CONTENT);
+        expect(summary).toBe("A skill doc for GitHub API.");
+    });
+    it("handles content that starts with text immediately", () => {
+        const summary = skillSummary("Hello world\n## Section");
+        expect(summary).toBe("Hello world");
+    });
+    it("returns empty string for all-header content", () => {
+        const summary = skillSummary("# Title\n## Subtitle\n");
+        expect(summary).toBe("");
+    });
+});
+// ---------------------------------------------------------------------------
+// Real skills validation
+// Each skill added to the repo must pass these checks.
+// ---------------------------------------------------------------------------
+const REQUIRED_SECTIONS = [
+    "Authentication & permissions",
+    "Reliability: rate limits, retries, idempotency",
+    "Error handling & troubleshooting",
+    "Common workflows (recipes)",
+];
+const KNOWN_SKILLS = [
+    "asana", "dynamics365", "figma", "github", "hubspot",
+    "jira", "monday", "salesforce", "servicenow", "zendesk",
+    "slack",
+];
+describe("real skills", () => {
+    let skills;
+    beforeAll(() => {
+        skills = loadSkills(REAL_SKILLS_DIR);
+    });
+    it("loads all expected skills", () => {
+        for (const slug of KNOWN_SKILLS) {
+            expect(skills.has(slug), `Missing skill: ${slug}`).toBe(true);
+        }
+    });
+    it("every skill has a non-empty summary line", () => {
+        for (const [slug, content] of skills.entries()) {
+            const summary = skillSummary(content);
+            expect(summary, `${slug}: empty summary`).not.toBe("");
+        }
+    });
+    it("every skill contains the required sections", () => {
+        for (const [slug, content] of skills.entries()) {
+            for (const section of REQUIRED_SECTIONS) {
+                const extracted = extractSection(content, section);
+                expect(extracted, `${slug}: missing section "${section}"`).not.toBeNull();
+            }
+        }
+    });
+    it("every skill file is at least 5KB", () => {
+        for (const [slug, content] of skills.entries()) {
+            expect(content.length, `${slug}: suspiciously short skill file`).toBeGreaterThan(5000);
+        }
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawskills-mcp",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "MCP server exposing ClawSkills API integration skill docs to AI agents",
   "type": "module",
   "bin": {
@@ -14,7 +14,9 @@
     "prepack": "rm -rf ./skills && cp -r ../skills ./skills",
     "build": "tsc",
     "start": "node dist/index.js",
-    "dev": "ts-node src/index.ts"
+    "dev": "ts-node src/index.ts",
+    "test": "vitest run",
+    "test:watch": "vitest"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
@@ -22,9 +24,10 @@
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
-    "typescript": "^5.6.0"
+    "typescript": "^5.6.0",
+    "vitest": "^2.0.0"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   }
 }

package/skills/INDEX.md

@@ -20,6 +20,7 @@ A curated library of integration skill documents for the most common SaaS platfo
 | Asana | [asana/skill.md](./asana/skill.md) | Project Manager, RevOps | Task and project management with portfolio tracking |
 | GitHub | [github/skill.md](./github/skill.md) | Engineering, DevOps | Source control, PRs, CI/CD automation via REST + GraphQL |
 | Figma | [figma/skill.md](./figma/skill.md) | Design, Product, DevOps | Design file inspection, asset export, webhooks, design-to-dev handoff |
+| Slack | [slack/skill.md](./slack/skill.md) | All teams | Real-time messaging, notifications, event-driven automation via Web API |
 
 ---
 
@@ -165,6 +166,20 @@ A curated library of integration skill documents for the most common SaaS platfo
 
 ---
 
+### Slack → [skill.md](./slack/skill.md)
+1. Post a rich Block Kit message to a channel
+2. Reply in a thread using `thread_ts`
+3. Send a direct message (open DM channel + postMessage)
+4. Look up a user by email address
+5. Update a message in place as status changes
+6. Upload a file using the two-step external upload API
+7. Add a reaction to a message
+8. List all channels and build a name → ID cache
+9. Read channel history incrementally using cursor pagination
+10. Receive, verify, and process Events API payloads
+
+---
+
 ## Common Cross-Tool Patterns
 
 These scenarios span multiple skill docs — reference both tools:
@@ -199,6 +214,7 @@ These scenarios span multiple skill docs — reference both tools:
 | Asana | Personal Access Token (PAT) | Bearer token | Inherits user permissions |
 | GitHub | Fine-grained PAT or GitHub App installation token | Bearer token | Per-resource permissions (contents, issues, pull_requests, etc.) |
 | Figma | Personal Access Token (PAT) or OAuth 2.0 | `X-Figma-Token` (PAT) / `Authorization: Bearer` (OAuth) | Granular scopes: `file_content:read`, `webhooks:write`, etc. |
+| Slack | Bot token (OAuth 2.0 app install) | `xoxb-...` Bearer token | Per-method scopes: `chat:write`, `channels:read`, `users:read`, etc. |
 
 ---
 
@@ -216,10 +232,11 @@ These scenarios span multiple skill docs — reference both tools:
 | Asana | 1,500 req/min + 150 concurrent | 1 minute | `Retry-After` on 429 |
 | GitHub | PAT: 5,000/hr · GitHub App: 5k–12.5k/hr · Enterprise Cloud: 15,000/hr · Secondary: 900 pts/min, 80 create/min | 1 hour (primary) + sliding (secondary) | `x-ratelimit-remaining` / `x-ratelimit-reset`; 403 or 429 |
 | Figma | Starter: 10/min (T1), 25/min (T2) · Professional: 15/min (T1), 50/min (T2) · Org: 20/min (T1), 100/min (T2) | Per minute (leaky bucket) | `Retry-After` / `X-Figma-Rate-Limit-Type` / `X-Figma-Plan-Tier` |
+| Slack | Tier 1: 1/min · Tier 2: 20/min · Tier 3: 50/min · Tier 4: 100/min · `chat.postMessage`: 1/sec/channel sub-limit | Per method per workspace | HTTP 429 + `Retry-After` header (seconds) |
 
 ---
 
-*Last updated: 2026-02-22 (GitHub + Figma skills added; all docs verified current) | See [ROADMAP.md](./ROADMAP.md) for versioning and governance details.*
+*Last updated: 2026-02-26 (Slack skill added) | See [ROADMAP.md](./ROADMAP.md) for versioning and governance details.*
 
 ### API version reference (as of 2026-02-22)
 
@@ -235,3 +252,4 @@ These scenarios span multiple skill docs — reference both tools:
 | Asana | REST API 1.0 | No breaking changes; always use `opt_fields` |
 | GitHub | REST API + GraphQL v4 | Pin `X-GitHub-Api-Version: 2022-11-28`; fine-grained PATs recommended |
 | Figma | REST API v1 / Webhooks V2 | Path-based versioning (`/v1/`, `/v2/`); `files:read` scope deprecated — use granular scopes |
+| Slack | Web API (no versioned path) | Always check `ok` field (HTTP 200 even on errors); `files.upload` deprecated — use `files.getUploadURLExternal` |

package/skills/figma/skill.md

@@ -735,7 +735,7 @@ if current_version != cached_version:
 
 ---
 
-## Rate limits, retries, idempotency
+## Reliability: rate limits, retries, idempotency
 
 ### Tier definitions (as of Nov 17, 2025)
 
@@ -794,7 +794,7 @@ def figma_request(url: str, token: str, params: dict = None, max_retries: int =
 
 ---
 
-## Error handling
+## Error handling & troubleshooting
 
 | Code | When | Action |
 |------|------|--------|

package/skills/slack/skill.md

@@ -0,0 +1,740 @@
+# Slack Skill
+
+> **Last validated:** 2026-02-26 | **API:** Slack Web API (no versioned URL path)
+> **REST base URL:** `https://slack.com/api/`
+> **Assumed product:** Slack (cloud). Slack Enterprise Grid adds org-level APIs but the core methods are identical.
+
+---
+
+## What this skill enables
+
+- Send messages and rich Block Kit cards to any channel, DM, or thread from external systems.
+- Build notification pipelines: alert on-call engineers, post deploy summaries, surface CRM events in team channels.
+- Manage channels programmatically: create, archive, invite users, and sync membership from external directories.
+- Respond to user actions in real time: slash commands, interactive buttons, modals (views), and workflow steps.
+- Sync data bi-directionally: listen to Slack events (messages, reactions, channel membership) and reflect changes in external tools.
+- Upload and share files: attach reports, screenshots, and exports directly in channels.
+- Search and audit: query message history for compliance or reporting pipelines.
+
+---
+
+## Best-fit use cases
+
+| Use case | Why it matters | Primary objects | Typical trigger | Success criteria |
+|----------|---------------|-----------------|-----------------|-----------------|
+| Post alert to on-call channel | Instant human awareness of incidents | Message, Channel | PagerDuty/Datadog webhook | Message posted with link to runbook within 2s |
+| Deploy summary notification | Keep team informed without polling dashboards | Message, Block Kit | CI/CD pipeline completes | Formatted message with pass/fail + diff link |
+| Sync CRM deal update to sales channel | Surface revenue moments to the team | Message, Thread | HubSpot/Salesforce webhook | Deal name, stage, and owner in message |
+| Create ticket from Slack reaction | Lightweight triage without leaving Slack | Reaction event, Message | User adds 🎫 emoji to a message | Jira/Zendesk ticket created, permalink posted in thread |
+| Slash command → workflow | Self-service automation from Slack UI | Slash command, Modal | User types `/create-ticket` | Modal opens, user fills form, ticket created |
+| User lookup by email | Resolve an email address to a Slack user ID | User | Before sending a DM | `user_id` returned for `conversations.open` |
+| Daily digest | Scheduled summary of CRM/ops data | Message, Scheduled post | Cron job | Summary message posted at 9 AM team timezone |
+| Channel membership sync | Keep project channels aligned with HRIS/CRM | Channel, User | User onboarding/offboarding event | User invited or removed from correct channels |
+| File report delivery | Share generated reports without email | File | Scheduled job or request | File uploaded, shared in channel with comment |
+| Webhook event to external system | Mirror Slack activity to ops tools | Events API | Message posted, reaction added | External system receives and processes event within 3s |
+
+---
+
+## Key concepts & data model
+
+### Core objects
+
+| Object | Description | Identified by |
+|--------|-------------|---------------|
+| **Workspace** | A Slack organization | `team_id` (e.g., `T01ABCDEF`) |
+| **Channel** | Public channel, private channel, DM, or MPIM (group DM) | `channel_id` (e.g., `C01ABCDEF` public, `G01…` private, `D01…` DM) |
+| **User** | A person in the workspace | `user_id` (e.g., `U01ABCDEF`) |
+| **Bot** | A non-human entity representing a Slack app | `bot_id` (e.g., `B01ABCDEF`) |
+| **Message** | A chat message in a channel or thread | `(channel_id, ts)` tuple — `ts` is a Unix timestamp string like `"1706200000.123456"` |
+| **Thread** | A sub-conversation anchored to a message | Parent message's `ts` used as `thread_ts` |
+| **File** | An uploaded file or snippet | `file_id` (e.g., `F01ABCDEF`) |
+| **Reaction** | An emoji added to a message | `(name, user_id, item)` — `name` is the emoji name without colons |
+| **App** | A Slack integration/bot | `app_id` (e.g., `A01ABCDEF`) |
+| **View** | A modal or App Home surface | `view_id` returned by `views.open` |
+
+### Channel types and ID prefixes
+
+| Prefix | Type | Notes |
+|--------|------|-------|
+| `C` | Public channel | Visible to all workspace members |
+| `G` | Private channel / MPIM | Invite-only; group DMs also use `G` |
+| `D` | Direct message | Between bot and one user |
+
+> **Tip:** Always resolve channel names to IDs at startup using `conversations.list` and cache them. Names can change; IDs are stable.
+
+### Message timestamps (`ts`)
+
+Slack uses `ts` (timestamp) as the primary message identifier — it is a string like `"1706200000.123456"`, not a number. Always store and compare as a string. The `ts` of the parent message is passed as `thread_ts` to post into a thread.
+
+### Relationships
+
+```
+Workspace (team_id)
+  ├── Channel (C / G / D)
+  │     ├── Message (channel + ts)
+  │     │     ├── Thread replies (thread_ts = parent ts)
+  │     │     ├── Reactions
+  │     │     └── File attachments
+  │     └── Members (user_ids)
+  ├── User (U)
+  └── App / Bot (A / B)
+```
+
+---
+
+## Authentication & permissions
+
+### Supported auth methods
+
+| Method | Best for | Token format |
+|--------|----------|-------------|
+| **Bot token** | All server-to-server automation (recommended) | `xoxb-...` |
+| **User token** | Acting as a specific user; required for some user-only methods | `xoxp-...` |
+| **App-level token** | Socket Mode (WebSocket) connections only | `xapp-...` |
+| **Incoming Webhook URL** | Simple one-way message posting with no SDK | Full URL, e.g. `https://hooks.slack.com/services/T.../B.../...` |
+
+**Bot tokens are recommended** for all automation — they have stable identity, are scoped to the app, and do not expose any individual user's data.
+
+### Creating a Slack App and getting a bot token
+
+1. Go to [api.slack.com/apps](https://api.slack.com/apps) → **Create New App** → **From Manifest** (or From Scratch).
+2. Under **OAuth & Permissions** → **Bot Token Scopes**, add the scopes your app needs (see table below).
+3. **Install App** to your workspace → copy the **Bot User OAuth Token** (`xoxb-...`).
+4. Store the token as an environment variable: `SLACK_BOT_TOKEN`.
+
+```bash
+curl -s https://slack.com/api/auth.test \
+  -H "Authorization: Bearer $SLACK_BOT_TOKEN" \
+  -H "Content-Type: application/json"
+# Response: {"ok": true, "team": "Acme Corp", "user": "my-bot", "team_id": "T01...", "user_id": "U01..."}
+```
+
+### Required scopes (bot token — least privilege)
+
+| Scope | Purpose |
+|-------|---------|
+| `chat:write` | Post messages as the bot |
+| `chat:write.public` | Post to public channels without joining first |
+| `channels:read` | List public channels, get channel info |
+| `channels:history` | Read messages in public channels the bot has joined |
+| `groups:read` | List private channels the bot is a member of |
+| `groups:history` | Read messages in private channels |
+| `im:read` | List DMs the bot has open |
+| `im:write` | Open DMs with users |
+| `im:history` | Read DM messages |
+| `users:read` | Get user info (name, display name, tz) |
+| `users:read.email` | Look up users by email address |
+| `files:write` | Upload files |
+| `reactions:read` | Read reactions on messages |
+| `reactions:write` | Add/remove reactions |
+| `channels:join` | Join public channels programmatically |
+| `channels:manage` | Create/archive public channels |
+| `groups:write` | Create/archive private channels |
+| `team:read` | Get workspace info |
+| `search:read` | Search messages (user token only — not available to bots) |
+
+> **Note:** `search:read` requires a **user token** (`xoxp-...`). There is no bot-accessible search API; use `conversations.history` + cursor pagination for bot-accessible message scanning.
+
+### Required headers (always include)
+
+```
+Authorization: Bearer xoxb-your-token
+Content-Type: application/json
+```
+
+> **Legacy note:** Some Slack docs show `application/x-www-form-urlencoded` POST bodies. This still works but JSON (`application/json`) is the modern approach and is required for Block Kit payloads.
+
+### Token storage
+
+- Store bot tokens in environment variables or a secrets manager (AWS Secrets Manager, HashiCorp Vault). Never commit to code.
+- Bot tokens do not expire unless the app is uninstalled or the token is revoked. Implement health checks (call `auth.test` on startup) to detect revocation early.
+- For multi-workspace (Slack Connect / distribution), use OAuth 2.0 and store one bot token per workspace in your database.
+
+---
+
+## Common workflows (recipes)
+
+### Recipe 1: Post a message to a channel
+
+**Goal:** Send a formatted notification to a channel.
+
+```bash
+curl -s -X POST https://slack.com/api/chat.postMessage \
+  -H "Authorization: Bearer $SLACK_BOT_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "channel": "C01ABCDEF",
+    "text": "Deployment complete: *api-service v2.3.1* deployed to production.",
+    "blocks": [
+      {
+        "type": "section",
+        "text": {
+          "type": "mrkdwn",
+          "text": ":white_check_mark: *api-service v2.3.1* deployed to *production*\n*Duration:* 2m 14s | *By:* @janesmith"
+        }
+      },
+      {
+        "type": "actions",
+        "elements": [
+          {
+            "type": "button",
+            "text": { "type": "plain_text", "text": "View Logs" },
+            "url": "https://logs.example.com/deploy/1234",
+            "action_id": "view_logs"
+          }
+        ]
+      }
+    ]
+  }'
+# Response: {"ok": true, "channel": "C01ABCDEF", "ts": "1706200000.123456", "message": {...}}
+```
+
+**Always include both `text` and `blocks`.** The `text` field is the fallback for notifications and accessibility tools — it is displayed when blocks cannot be rendered.
+
+**Edge cases:**
+- Bot must be a member of the channel (or use the `chat:write.public` scope for public channels).
+- If `channel` is a user ID (e.g., `U01...`), Slack will send a DM. Alternatively, use Recipe 3 to open a DM first.
+- To post to a private channel, the bot must be invited first: `conversations.invite`.
+
+---
+
+### Recipe 2: Post a reply in a thread
+
+**Goal:** Add a reply to an existing message thread.
+
+```bash
+curl -s -X POST https://slack.com/api/chat.postMessage \
+  -H "Authorization: Bearer $SLACK_BOT_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "channel": "C01ABCDEF",
+    "thread_ts": "1706200000.123456",
+    "text": "Incident resolved. Root cause: connection pool exhaustion. Post-mortem linked below.",
+    "reply_broadcast": false
+  }'
+```
+
+**`reply_broadcast: true`** also sends the reply to the main channel (appears in both thread and channel).
+
+---
+
+### Recipe 3: Send a direct message to a user
+
+**Goal:** Open a DM channel with a user and post a message.
+
+```bash
+# Step 1 — open a DM channel (idempotent — returns existing channel if open)
+DM_CHANNEL=$(curl -s -X POST https://slack.com/api/conversations.open \
+  -H "Authorization: Bearer $SLACK_BOT_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"users": "U01ABCDEF"}' \
+  | jq -r '.channel.id')
+
+# Step 2 — post message
+curl -s -X POST https://slack.com/api/chat.postMessage \
+  -H "Authorization: Bearer $SLACK_BOT_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d "{
+    \"channel\": \"$DM_CHANNEL\",
+    \"text\": \"Hi! Your Salesforce deal has moved to Proposal stage.\"
+  }"
+```
+
+---
+
+### Recipe 4: Look up a user by email
+
+**Goal:** Find a user's Slack ID from their email address (e.g., from a CRM record).
+
+```bash
+curl -s -G "https://slack.com/api/users.lookupByEmail" \
+  -H "Authorization: Bearer $SLACK_BOT_TOKEN" \
+  --data-urlencode "email=janesmith@example.com"
+# Response: {"ok": true, "user": {"id": "U01ABCDEF", "name": "janesmith", "tz": "America/New_York", ...}}
+```
+
+Requires `users:read.email` scope. Store the resolved `user_id` — do not call this on every request.
+
+---
+
+### Recipe 5: Update or delete a message
+
+**Goal:** Edit a previously posted message (e.g., update a status message as a deployment progresses).
+
+```bash
+# Update
+curl -s -X POST https://slack.com/api/chat.update \
+  -H "Authorization: Bearer $SLACK_BOT_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "channel": "C01ABCDEF",
+    "ts": "1706200000.123456",
+    "text": "Deployment FAILED: api-service v2.3.1",
+    "blocks": [
+      {
+        "type": "section",
+        "text": { "type": "mrkdwn", "text": ":x: *Deployment FAILED* — api-service v2.3.1\nSee <https://logs.example.com/1234|logs> for details." }
+      }
+    ]
+  }'
+
+# Delete
+curl -s -X POST https://slack.com/api/chat.delete \
+  -H "Authorization: Bearer $SLACK_BOT_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"channel": "C01ABCDEF", "ts": "1706200000.123456"}'
+```
+
+**Pattern:** Post a "starting…" message, save the returned `ts`, then update it in place as the operation progresses. This avoids flooding the channel with multiple messages.
+
+---
+
+### Recipe 6: Upload a file to a channel
+
+**Goal:** Share a generated report or screenshot in a channel. Use the two-step upload API (recommended since 2023).
+
+```python
+import requests, os
+
+token = os.environ["SLACK_BOT_TOKEN"]
+headers = {"Authorization": f"Bearer {token}"}
+
+# Step 1 — get an upload URL
+resp = requests.get(
+    "https://slack.com/api/files.getUploadURLExternal",
+    headers=headers,
+    params={"filename": "report.csv", "length": os.path.getsize("report.csv")}
+)
+data = resp.json()
+upload_url = data["upload_url"]
+file_id = data["file_id"]
+
+# Step 2 — upload the file content to the pre-signed URL
+with open("report.csv", "rb") as f:
+    requests.post(upload_url, data=f)
+
+# Step 3 — complete the upload and share to channel
+requests.post(
+    "https://slack.com/api/files.completeUploadExternal",
+    headers=headers,
+    json={
+        "files": [{"id": file_id, "title": "Weekly Report"}],
+        "channel_id": "C01ABCDEF",
+        "initial_comment": "Here's the weekly ops report."
+    }
+)
+```
+
+> **Avoid** `files.upload` (the old single-call method) — it is deprecated and has a 1 GB limit vs. much larger limits on the new API.
+
+---
+
+### Recipe 7: Add a reaction to a message
+
+**Goal:** React to a message programmatically (e.g., acknowledge receipt by adding ✅).
+
+```bash
+curl -s -X POST https://slack.com/api/reactions.add \
+  -H "Authorization: Bearer $SLACK_BOT_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "channel": "C01ABCDEF",
+    "timestamp": "1706200000.123456",
+    "name": "white_check_mark"
+  }'
+```
+
+Emoji `name` is the text between colons (e.g., `:white_check_mark:` → `"white_check_mark"`). Custom emoji are referenced by their workspace name.
+
+---
+
+### Recipe 8: List channels and resolve names to IDs
+
+**Goal:** Build and cache a channel name → ID map at startup.
+
+```python
+import requests
+
+def get_channel_map(token: str) -> dict[str, str]:
+    """Returns {channel_name: channel_id} for all public channels."""
+    headers = {"Authorization": f"Bearer {token}"}
+    channel_map = {}
+    cursor = None
+
+    while True:
+        params = {"limit": 200, "exclude_archived": True, "types": "public_channel"}
+        if cursor:
+            params["cursor"] = cursor
+
+        resp = requests.get(
+            "https://slack.com/api/conversations.list",
+            headers=headers,
+            params=params
+        ).json()
+
+        if not resp["ok"]:
+            raise Exception(f"Slack error: {resp['error']}")
+
+        for ch in resp["channels"]:
+            channel_map[ch["name"]] = ch["id"]
+
+        cursor = resp.get("response_metadata", {}).get("next_cursor")
+        if not cursor:
+            break
+
+    return channel_map
+
+# Usage
+CHANNELS = get_channel_map(os.environ["SLACK_BOT_TOKEN"])
+post_to = CHANNELS["engineering-deploys"]
+```
+
+---
+
+### Recipe 9: Read channel history (incremental sync)
+
+**Goal:** Fetch messages posted since the last sync run.
+
+```python
+import requests, time
+
+def fetch_messages_since(token: str, channel_id: str, oldest_ts: str) -> list:
+    headers = {"Authorization": f"Bearer {token}"}
+    messages = []
+    cursor = None
+
+    while True:
+        params = {"channel": channel_id, "oldest": oldest_ts, "limit": 200}
+        if cursor:
+            params["cursor"] = cursor
+
+        resp = requests.get(
+            "https://slack.com/api/conversations.history",
+            headers=headers,
+            params=params
+        ).json()
+
+        if not resp["ok"]:
+            raise Exception(f"Slack error: {resp['error']}")
+
+        messages.extend(resp["messages"])
+
+        if not resp.get("has_more"):
+            break
+        cursor = resp["response_metadata"]["next_cursor"]
+
+    return messages
+
+# Store the latest ts after each run as the next oldest
+latest_ts = str(time.time() - 3600)  # last hour on first run
+messages = fetch_messages_since(token, "C01ABCDEF", latest_ts)
+next_run_ts = messages[0]["ts"] if messages else latest_ts
+```
+
+---
+
+### Recipe 10: Receive and verify Events API payloads
+
+**Goal:** Handle real-time Slack events (message posted, reaction added, member joined, etc.) in your webhook endpoint.
+
+**App setup:** In your Slack App config → **Event Subscriptions** → enable, set Request URL to your endpoint, subscribe to bot events (e.g., `message.channels`, `reaction_added`).
+
+**URL verification (one-time, on first save):**
+```python
+from flask import Flask, request, jsonify
+
+app = Flask(__name__)
+
+@app.route("/slack/events", methods=["POST"])
+def slack_events():
+    body = request.json
+
+    # Slack URL verification challenge
+    if body.get("type") == "url_verification":
+        return jsonify({"challenge": body["challenge"]})
+
+    # Verify signature before processing
+    if not verify_slack_signature(request):
+        return "", 403
+
+    event = body.get("event", {})
+    # Handle asynchronously — must return 200 within 3 seconds
+    handle_event_async(event)
+    return "", 200
+```
+
+**Signature verification (required — never skip this):**
+```python
+import hmac, hashlib, time
+
+SLACK_SIGNING_SECRET = os.environ["SLACK_SIGNING_SECRET"]
+
+def verify_slack_signature(request) -> bool:
+    timestamp = request.headers.get("X-Slack-Request-Timestamp", "")
+    sig_header = request.headers.get("X-Slack-Signature", "")
+
+    # Reject requests older than 5 minutes (replay attack prevention)
+    if abs(time.time() - int(timestamp)) > 300:
+        return False
+
+    base_string = f"v0:{timestamp}:{request.get_data(as_text=True)}"
+    expected = "v0=" + hmac.new(
+        SLACK_SIGNING_SECRET.encode(),
+        base_string.encode(),
+        hashlib.sha256
+    ).hexdigest()
+
+    return hmac.compare_digest(expected, sig_header)
+```
+
+**Critical:** Respond with HTTP 200 within **3 seconds**. If processing takes longer, return 200 immediately and process asynchronously (queue the event). Slack retries failed deliveries 3 times.
+
+---
+
+### Recipe 11: Invite a user to a channel
+
+**Goal:** Add a user to a private channel when they join a project.
+
+```bash
+curl -s -X POST https://slack.com/api/conversations.invite \
+  -H "Authorization: Bearer $SLACK_BOT_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "channel": "G01ABCDEF",
+    "users": "U01ABCDEF,U02ABCDEF"
+  }'
+# Response: {"ok": true, "channel": {...}}
+# Error if user is already a member: {"ok": false, "error": "already_in_channel"}
+```
+
+Multiple users can be invited in one call by comma-separating `users`.
+
+---
+
+## Query patterns & filtering
+
+### Pagination
+
+All list endpoints use **cursor-based pagination**. Never use `page`/`offset` (not supported on most Slack endpoints).
+
+```python
+def paginate_slack(token: str, method: str, params: dict) -> list:
+    """Generic cursor-based paginator for Slack list methods."""
+    headers = {"Authorization": f"Bearer {token}"}
+    results = []
+    cursor = None
+    list_key = None  # auto-detected
+
+    while True:
+        p = {**params, "limit": 200}
+        if cursor:
+            p["cursor"] = cursor
+
+        resp = requests.get(
+            f"https://slack.com/api/{method}",
+            headers=headers,
+            params=p
+        ).json()
+
+        if not resp["ok"]:
+            raise Exception(f"Slack error {method}: {resp['error']}")
+
+        # Detect the list key (channels, members, users, messages, etc.)
+        if list_key is None:
+            list_key = next((k for k in resp if isinstance(resp[k], list) and k != "warnings"), None)
+        if list_key:
+            results.extend(resp[list_key])
+
+        cursor = resp.get("response_metadata", {}).get("next_cursor")
+        if not cursor:
+            break
+
+    return results
+```
+
+### Filtering messages
+
+- **By time range:** Use `oldest` and `latest` parameters (Unix timestamp strings) on `conversations.history`.
+- **By thread:** Use `conversations.replies` with `ts` of the parent message.
+- **Bot vs human messages:** Check `subtype` field — bot messages have `subtype: "bot_message"` or `bot_id` present.
+- **Ignore system messages:** Filter out messages with `subtype` set (e.g., `channel_join`, `channel_leave`).
+
+### Message deduplication
+
+Use `(channel_id, ts)` as a composite key — `ts` is unique within a channel. For Events API, Slack may retry the same event; use the event's `event_id` as an idempotency key:
+
+```python
+processed_events = set()  # use Redis in production
+
+def handle_event_async(event_wrapper: dict):
+    event_id = event_wrapper.get("event_id")
+    if event_id in processed_events:
+        return  # already handled
+    processed_events.add(event_id)
+    # ... process event
+```
+
+---
+
+## Reliability: rate limits, retries, idempotency
+
+### Rate limits (verified 2026-02-26)
+
+Slack uses a **tiered** rate limit system, applied per workspace per method:
+
+| Tier | Limit | Examples |
+|------|-------|---------|
+| **Tier 1** | 1+ req/min | `conversations.create`, `admin.*` |
+| **Tier 2** | 20+ req/min | `auth.test`, `conversations.info`, `files.info` |
+| **Tier 3** | 50+ req/min | `conversations.history`, `conversations.list`, `users.info`, `reactions.add` |
+| **Tier 4** | 100+ req/min | `chat.postMessage`, `chat.update`, `users.list` |
+| **Special** | 1 req/sec per channel | `chat.postMessage` per-channel sub-limit (regardless of Tier 4) |
+
+When rate limited, Slack returns **HTTP 429** with a `Retry-After` header (seconds to wait).
+
+> **Practical limit for `chat.postMessage`:** Even though it is Tier 4 (100/min workspace-wide), there is a per-channel limit of ~1 req/sec. For burst messaging to the same channel, add a 1-second delay between calls or use `chat.scheduleMessage`.
+
+### Retry strategy
+
+```python
+import time, requests
+
+def slack_api(method: str, token: str, **kwargs) -> dict:
+    url = f"https://slack.com/api/{method}"
+    headers = {"Authorization": f"Bearer {token}", "Content-Type": "application/json"}
+
+    for attempt in range(5):
+        resp = requests.post(url, headers=headers, json=kwargs)
+
+        if resp.status_code == 429:
+            retry_after = int(resp.headers.get("Retry-After", 5))
+            time.sleep(retry_after)
+            continue
+
+        if resp.status_code >= 500:
+            time.sleep(2 ** attempt)
+            continue
+
+        data = resp.json()
+        if not data["ok"]:
+            if data["error"] == "ratelimited":
+                time.sleep(int(resp.headers.get("Retry-After", 5)))
+                continue
+            raise Exception(f"Slack API error: {data['error']}")
+
+        return data
+
+    raise Exception("Max retries exceeded")
+```
+
+> **Note:** Slack always returns HTTP 200, even for application-level errors. Always check `data["ok"]` — not just the HTTP status code.
+
+### Idempotency patterns
+
+- **`chat.postMessage`:** Not natively idempotent. To avoid duplicate messages, use an external idempotency key: check whether a message with your known content/ts already exists in the channel before posting, or store the returned `ts` in your database.
+- **`conversations.invite`:** Already idempotent — returns `already_in_channel` error (not a failure) if user is a member.
+- **`reactions.add`:** Returns `already_reacted` if reaction already exists — safe to ignore.
+- **Events API:** Use `event_id` as an idempotency key in Redis/database to deduplicate retried events.
+
+---
+
+## Error handling & troubleshooting
+
+### All Slack errors follow this pattern
+
+```json
+{ "ok": false, "error": "channel_not_found" }
+```
+
+HTTP status is always 200. Parse the response body to detect errors.
+
+### Common errors
+
+| Error string | Meaning | Fix |
+|-------------|---------|-----|
+| `not_in_channel` | Bot is not a member of the channel | Invite the bot or use `chat:write.public` scope |
+| `channel_not_found` | Channel ID is wrong or bot can't see it | Verify channel ID; check bot is in workspace |
+| `invalid_auth` | Token is invalid or revoked | Re-generate token; check env var |
+| `missing_scope` | Bot token lacks required scope | Add scope in App config → reinstall app |
+| `ratelimited` | Rate limit hit | Respect `Retry-After` header |
+| `already_in_channel` | User already a channel member | Ignore — treat as success |
+| `already_reacted` | Reaction already exists | Ignore — treat as success |
+| `cant_invite_self` | Trying to invite the bot to a channel it's in | Ignore |
+| `msg_too_long` | Message text exceeds 40,000 chars | Split into multiple messages |
+| `no_text` | Empty `text` and no `blocks` | Always provide `text` as fallback |
+| `restricted_action` | Workspace admin has blocked this action | Contact workspace admin |
+| `is_archived` | Channel is archived | Unarchive or use a different channel |
+| `thread_not_found` | `thread_ts` doesn't match any message | Verify `ts` is stored as a string, not float |
+| `ekm_access_denied` | Enterprise Key Management restriction | Use an org-approved token |
+
+### "If you see X, do Y" playbook
+
+- **Bot posts in the wrong channel / no message appears:** Verify the `channel` value is a channel ID (`C...`) not a name. Channel names are not accepted by `chat.postMessage`.
+- **Messages appear in the channel but with broken formatting:** You passed `text` with `*bold*` or `_italic_` — use `mrkdwn` format (Slack's dialect), not standard Markdown. Key differences: `*bold*`, `_italic_`, `~strike~`, `<URL|link text>`, `<@U01...>` mentions.
+- **Events API URL fails verification:** Your endpoint didn't return `{"challenge": ...}` within 3 seconds, or returned incorrect content. Ensure JSON response with `Content-Type: application/json`.
+- **Events arrive but signature verification fails:** Make sure you're reading the raw request body (not parsed JSON) for HMAC calculation. Some frameworks re-encode the body — use the raw bytes.
+- **`files.upload` returns `ok: false`:** The old upload method is deprecated. Switch to `files.getUploadURLExternal` + `files.completeUploadExternal`.
+- **`chat.update` returns `cant_update_message`:** Only the bot that originally posted the message can update it. You cannot update messages posted by other bots or users.
+- **Thread replies not appearing in thread:** You passed `thread_ts` correctly but used a different channel ID. The `channel` and `thread_ts` must both match the original message.
+
+### Debug logging
+
+Log: API method, channel/user ID, response `ok` field, `error` field (if any), HTTP status, `Retry-After` (on 429).
+Do NOT log: token values, full message text (may contain PII), file contents.
+
+---
+
+## Security, privacy, compliance
+
+- **Least privilege:** Request only the scopes your app needs. Slack's permission model is per-scope, not per-channel — a `channels:history` scope grants access to all public channels the bot is in.
+- **Token storage:** Never expose bot tokens in client-side code, logs, or URLs. Store in environment variables or a secrets manager. Bot tokens do not expire but can be revoked — implement `auth.test` health checks.
+- **Signing secret:** Always verify `X-Slack-Signature` on all incoming webhooks and Events API payloads. Do not process unsigned requests.
+- **DMs and private channels:** Private messages are sensitive. Minimize bot access to DMs and private channels; request only the scopes needed. Slack Enterprise Grid adds Data Loss Prevention (DLP) controls.
+- **User data (PII):** `users.list` and `users.info` return display names, real names, and email addresses. Handle this data per your privacy policy — do not store more than necessary.
+- **Message content:** Slack messages can contain PII, credentials, or confidential data. Treat message content as sensitive; do not log full message text in production.
+- **Audit logs:** Slack Enterprise Grid provides an Audit Logs API (`audit.logs.v1`) for compliance logging. Standard Slack does not expose per-workspace audit logs via API.
+- **Bot impersonation:** Never use `as_user: true` with a user token to post as a human user in automated flows — this is misleading and may violate your workspace's acceptable use policy.
+- **GDPR:** Slack supports data export requests. If a user requests deletion, messages they sent cannot be deleted via API by bots (only the user or workspace admin can delete messages). Plan for this in your data retention policy.
+
+---
+
+## Testing checklist
+
+- [ ] **Auth test:** `GET https://slack.com/api/auth.test` → `ok: true`, bot name and team visible.
+- [ ] **Post message test:** `chat.postMessage` to a test channel → message appears with correct formatting; both `text` and `blocks` render correctly.
+- [ ] **Thread test:** Reply to the posted message using `thread_ts` → reply appears in thread, not in main channel.
+- [ ] **DM test:** `conversations.open` with a test user ID → `chat.postMessage` to returned DM channel → message arrives.
+- [ ] **User lookup test:** `users.lookupByEmail` with a valid email → returns correct `user_id`.
+- [ ] **Channel list test:** `conversations.list` with pagination → all channels returned; cursor exhausted.
+- [ ] **History test:** `conversations.history` with `oldest` param → only messages after cutoff returned.
+- [ ] **File upload test:** Full three-step upload flow → file appears in channel with comment.
+- [ ] **Reaction test:** `reactions.add` → emoji visible on message; calling again returns `already_reacted` (not an error).
+- [ ] **Rate limit test:** Send >1 req/sec to the same channel → 429 received → `Retry-After` respected → retry succeeds.
+- [ ] **Events API test:** Post a message in a subscribed channel → event received at your endpoint within 3s → `event_id` logged; posting same message again doesn't reprocess.
+- [ ] **Signature verification test:** Send request with invalid signature → 403 returned.
+- [ ] **Negative tests:**
+  - Bot not in channel → `not_in_channel`
+  - Invalid token → `invalid_auth`
+  - Non-existent channel ID → `channel_not_found`
+  - `thread_ts` stored as float → `thread_not_found` (must be string)
+  - Missing `text` field with blocks → `no_text`
+
+---
+
+## Sources
+
+- Slack Web API methods: https://api.slack.com/methods
+- Authentication & token types: https://api.slack.com/authentication/token-types
+- OAuth scopes: https://api.slack.com/scopes
+- Block Kit (rich message formatting): https://api.slack.com/block-kit
+- Block Kit Builder (interactive): https://app.slack.com/block-kit-builder
+- Events API: https://api.slack.com/events-api
+- Signing secrets & request verification: https://api.slack.com/authentication/verifying-requests-from-slack
+- Rate limits: https://api.slack.com/docs/rate-limits
+- File upload (new API): https://api.slack.com/methods/files.getUploadURLExternal
+- Conversations API: https://api.slack.com/docs/conversations-api
+- Pagination: https://api.slack.com/docs/pagination
+- Incoming Webhooks: https://api.slack.com/messaging/webhooks
+- Socket Mode: https://api.slack.com/apis/socket-mode
+- Enterprise Grid Audit Logs API: https://api.slack.com/admins/audit-logs
+- mrkdwn formatting reference: https://api.slack.com/reference/surfaces/formatting