feat: add prospecting skill + truelist integration (#308)

* feat: add prospecting skill + truelist integration New skill: skills/prospecting/ - SKILL.md (251 lines, well under 500 limit): branch picker for SaaS / B2B / Local SMB, shared 5-phase framework (ICP -> discovery -> qualify -> score -> output), compliance guardrails, tool selection quick-picks, output formats - references/saas-prospecting.md: tech stack signals, funding/hiring triggers, SaaS-specific sources and qualification - references/b2b-prospecting.md: industry/firmographic signals, trigger events, decision-maker mapping, B2B-specific sources - references/local-prospecting.md: 4-tier website status classification, browser-assisted research workflow (generalized from the local-client- prospector pattern), proximity scoring - references/data-sources.md: deep dives on Apollo, Clay, ZoomInfo, Clearbit, Hunter, Snov, Truelist, LinkedIn Sales Nav, BuiltWith, Crunchbase, RB2B, with sequencing recommendations across the three branches - references/compliance.md: CAN-SPAM, GDPR, CASL, platform ToS (LinkedIn, Google Maps, Apollo/ZI/Clearbit), anti-patterns, audit checklist - evals/evals.json: 6 evals (2 SaaS, 2 B2B, 1 Local SMB, 1 deliverability) New integration: - tools/integrations/truelist.md: email deliverability validation (Deliverable / Risky / Undeliverable / Unknown classification) Registry + marketplace wiring: - tools/REGISTRY.md: truelist row + new Email Verification category section - .claude-plugin/marketplace.json: bumped to 2.1.0, prospecting added to plugin description - VERSIONS.md: prospecting 1.0.0 + 2.1.0 changelog entry - README.md: skill table re-synced, prospecting added to ASCII flow under Sales & GTM column All 41 skills pass validation. sync-skills.js is idempotent. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * feat(prospecting): add GitHub stargazers/forks/watchers as discovery channel Net-new in this commit: - tools/clis/github-prospects.js: zero-dep Node CLI with commands stargazers / forks / watchers / user / rate-limit. Pagination via Link header, optional --enrich for full profile data, --with-email / --with-company / --with-blog filters, --format csv|json output, --dry-run preview. Uses GITHUB_TOKEN for 5000/hr rate limit (vs 60/hr unauthenticated). - tools/integrations/github.md: integration guide covering auth, rate limits, endpoints, workflows for SaaS prospecting, compliance notes (public API, not scraping), CLI reference. Skill updates: - skills/prospecting/SKILL.md: added GitHub to the tool selection quick picks and to the tool integrations table. - skills/prospecting/references/saas-prospecting.md: added GitHub to Tier 3 buying signals plus a dedicated "GitHub prospecting pattern (when audience is developers)" subsection with end-to-end workflow. - skills/prospecting/references/data-sources.md: added GitHub deep-dive section between RB2B and Free fallbacks. Registry: - tools/REGISTRY.md: github row in Tool Index, new Developer Intent / GitHub category section. All 41 skills still pass validation. sync-skills.js still no-op. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * refactor(prospecting): apply review suggestions CLI hardening + optimization: - github-prospects.js: encodeURIComponent on username path interpolation (defense in depth; GitHub usernames are restricted enough that this is safe in practice, but good hygiene). - github-prospects.js: refactored enrichUsers to filter inline and support --target N early termination. Previously, --with-email on a 1000-star repo would enrich all 1000 users before filtering down to the ~50 that match. Now you can pass --target 25 to stop as soon as 25 matches are found, saving API quota on restrictive filters. - github.md: documented the new --target flag. Reverse cross-references (so prospecting is discoverable from sibling skills): - cold-email: added prospecting as the natural upstream skill - customer-research: added "Translating customer research into an ICP for outbound" hand-off to prospecting - competitor-profiling: distinguished from prospecting ("this skill does deep research on specific accounts; prospecting builds the initial list") All 41 skills still pass validation. sync-skills.js still no-op. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * fix(truelist): align integration doc with actual OpenAPI spec Source of truth: Truelist-Labs/truelist-openapi (OpenAPI 3.1). The earlier integration doc had inferred (and wrong) endpoint paths, request shapes, and status enum values. Corrected against the published spec: Base URL: https://api.truelist.io Endpoints (real): - POST /api/v1/verify_inline?email=... (sync single, email is query param) - POST /api/v1/verify (async bulk, body: {emails: [...]}) - GET /me (account info) Real email_state enum: - ok, email_invalid, risky, unknown, accept_all (not the inferred "Deliverable / Risky / Undeliverable / Unknown") Real email_sub_state enum: - email_ok, is_disposable, is_role, unknown_error, failed_smtp_check Also corrected: - Truelist has an official MCP server (Truelist-Labs/truelist-mcp) — was marked as MCP unavailable - Truelist has 7 official SDKs (Node, Python, Ruby, PHP, Go, Java, .NET) + framework integrations (Django, Laravel, Next.js, Rails, React, Svelte, Vue, WordPress) — was marked as SDK unavailable - Native integrations with Mailchimp, Klaviyo, HubSpot, Zapier, Make, n8n, Clay, Salesforce, ActiveCampaign, Brevo, ConvertKit, Drip, BigCommerce, Go High Level — was unlisted - Rate limits: 10 req/s per endpoint (was unspecified) Files updated: - tools/integrations/truelist.md: full rewrite against spec - tools/REGISTRY.md: MCP and SDK columns now show ✓ for truelist; classifier note in the Email Verification section reflects real enum values - skills/prospecting/evals/evals.json: eval #6 expected_output and assertions use real email_state values and mention the MCP server - skills/prospecting/references/data-sources.md: Truelist deep-dive uses real endpoint paths, real enum values, and lists the MCP/SDK ecosystem All 41 skills still pass validation. sync-skills.js still no-op. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * feat(prospecting): add Firecrawl + Browserbase for single-target site research Both tools are programmatic scrapers, but their use in prospecting is strictly bounded: extract content from individual public business sites (the prospect's own website URL), never from the platforms hosting them (Google Maps, LinkedIn, Yelp, Apollo, etc.). This matches the line drawn by the original local-client-prospector reference skill and our own compliance section. New integration docs: - tools/integrations/firecrawl.md: REST + MCP + SDKs (Node/Python/Go/Rust); scrape / map / crawl / extract / search endpoints; explicit "when NOT to use" section listing the prohibited platforms. - tools/integrations/browserbase.md: real Chromium via Playwright/Puppeteer or Stagehand (AI-friendly natural-language extraction); session recordings; useful when rendering or interaction is required. Prospecting skill updates: - SKILL.md: added Firecrawl + Browserbase to tool selection quick picks and tool integrations table. - references/data-sources.md: new "Firecrawl / Browserbase (single-target site research)" section between RB2B and Free fallbacks. Includes the compliance line inline so the framing isn't lost. - references/local-prospecting.md: optional "programmatic verification" paragraph in the browser research workflow — once you have a candidate's URL from manual Maps discovery, you can hit it programmatically. - references/compliance.md: anti-pattern #1 now explicitly clarifies that Firecrawl/Browserbase are fine for the prospect's own website but not for the platforms hosting prospects. Registry: - tools/REGISTRY.md: firecrawl + browserbase rows in Tool Index, new "Site Scraping (single-target only)" category section with the compliance framing in the agent recommendation. All 41 skills still pass validation. sync-skills.js still no-op. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-26 11:20:26 -07:00
parent e40125a746
commit f86637eace
21 changed files with 2102 additions and 6 deletions
@@ -0,0 +1,111 @@
+# Browserbase
+
+Headless browser as a service. Spin up real Chromium browsers via API, drive them with Playwright/Puppeteer, get full session recordings. Useful when a target site requires JS rendering, user interaction, or session state that simple HTTP fetches can't handle.
+
+## Capabilities
+
+| Integration | Available | Notes |
+|-------------|-----------|-------|
+| API | ✓ | REST API for session management |
+| MCP | ✓ | Official Browserbase MCP server (Stagehand) |
+| CLI | - | None official |
+| SDK | ✓ | Node, Python; drives Playwright/Puppeteer |
+
+## Authentication
+
+- **Type**: API Key
+- **Header**: `x-bb-api-key: YOUR_API_KEY`
+- **Get key**: https://www.browserbase.com/settings
+- **Env vars**: `BROWSERBASE_API_KEY`, `BROWSERBASE_PROJECT_ID`
+- **Base URL**: `https://api.browserbase.com`
+
+## Core Operations
+
+### Create a browser session
+
+```bash
+POST https://api.browserbase.com/v1/sessions
+x-bb-api-key: YOUR_API_KEY
+
+{
+  "projectId": "YOUR_PROJECT_ID"
+}
+```
+
+Returns a session ID and a WebSocket URL (`connectUrl`) you connect to with Playwright or Puppeteer.
+
+### Connect with Playwright (Node)
+
+```js
+import { chromium } from 'playwright-core';
+import { Browserbase } from '@browserbasehq/sdk';
+
+const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY });
+const session = await bb.sessions.create({ projectId: process.env.BROWSERBASE_PROJECT_ID });
+
+const browser = await chromium.connectOverCDP(session.connectUrl);
+const page = await browser.newPage();
+await page.goto('https://joescoffeeshop.com');
+const html = await page.content();
+const title = await page.title();
+await browser.close();
+```
+
+### List session recordings
+
+```bash
+GET https://api.browserbase.com/v1/sessions/{sessionId}/logs
+```
+
+Useful for debugging when a scrape doesn't return what you expected — session recordings show exactly what the browser saw.
+
+### Stagehand (high-level AI-friendly wrapper)
+
+Browserbase ships [Stagehand](https://github.com/browserbase/stagehand), a Playwright wrapper with `act()`, `extract()`, and `observe()` methods that take natural-language instructions instead of CSS selectors. Stagehand also publishes an MCP server.
+
+```js
+import { Stagehand } from '@browserbasehq/stagehand';
+
+const stagehand = new Stagehand({ env: 'BROWSERBASE' });
+await stagehand.init();
+await stagehand.page.goto('https://joescoffeeshop.com');
+
+const contact = await stagehand.page.extract({
+  instruction: "Extract the business phone number, email, and street address",
+  schema: { phone: 'string', email: 'string', address: 'string' }
+});
+```
+
+## When to Use (over Firecrawl)
+
+- **Site requires user interaction** (cookie consent, age gate, click-through before content loads)
+- **Form submission** to access a quote/contact page
+- **Session state matters** (logged-in tools, multi-step flows)
+- **Complex JS rendering** that even Firecrawl's headless option struggles with
+- **Want full session recordings** for audit/debugging
+- **AI-driven scraping** via Stagehand's natural-language extraction
+
+For simple "scrape a page as markdown," **Firecrawl is lower-overhead**. Use Browserbase when you actually need the browser-as-a-service model.
+
+## When NOT to Use
+
+Same hard rules as Firecrawl. Browserbase gives you a more powerful browser, which means the temptation to bypass anti-scraping defenses is higher. Don't:
+
+- ✗ Bulk-scrape Google Maps / search results, LinkedIn, Yelp, or any platform whose ToS forbids it
+- ✗ Bypass CAPTCHAs, login walls, or bot protections
+- ✗ Auto-fill forms on platforms you don't have an account or legitimate access to
+
+**Use Browserbase for**: individual public business sites the user has a URL for, where rendering or interaction is required.
+
+## Pricing
+
+- Free tier: limited monthly minutes
+- Paid tiers scale by browser minutes + concurrency
+- Confirm at https://www.browserbase.com/pricing
+
+## Relevant Skills
+
+- prospecting (programmatic site visits for prospect enrichment)
+- competitor-profiling (when competitor sites need rendering or interaction)
+- cro (page audits that need real browser state)
+- analytics (testing tracking implementations end-to-end)
@@ -0,0 +1,144 @@
+# Firecrawl
+
+Web scraping API that turns single pages or full sites into clean LLM-ready markdown. Handles JS rendering, anti-bot defenses, and proxy rotation so you can extract structured data from individual public business sites.
+
+## Capabilities
+
+| Integration | Available | Notes |
+|-------------|-----------|-------|
+| API | ✓ | REST API + Python/Node SDKs |
+| MCP | ✓ | Official Firecrawl MCP server |
+| CLI | - | None official |
+| SDK | ✓ | Node, Python, Go, Rust |
+
+## Authentication
+
+- **Type**: API Key
+- **Header**: `Authorization: Bearer fc-YOUR_API_KEY`
+- **Get key**: https://www.firecrawl.dev/app/api-keys
+- **Env var**: `FIRECRAWL_API_KEY`
+- **Base URL**: `https://api.firecrawl.dev`
+
+## Core Operations
+
+### Scrape a single page
+
+```bash
+POST https://api.firecrawl.dev/v1/scrape
+Authorization: Bearer fc-YOUR_API_KEY
+
+{
+  "url": "https://joescoffeeshop.com",
+  "formats": ["markdown", "html"]
+}
+```
+
+Returns the page as clean markdown (LLM-ready, no nav cruft) plus optional raw HTML.
+
+### Map a site (discover all URLs)
+
+```bash
+POST https://api.firecrawl.dev/v1/map
+
+{
+  "url": "https://example.com",
+  "limit": 100
+}
+```
+
+Returns a list of URLs found on the site. Use this to identify key pages (`/pricing`, `/about`, `/contact`, `/team`) before scraping individually.
+
+### Crawl multiple pages
+
+```bash
+POST https://api.firecrawl.dev/v1/crawl
+
+{
+  "url": "https://example.com",
+  "limit": 20,
+  "scrapeOptions": {
+    "formats": ["markdown"]
+  }
+}
+```
+
+Crawls multiple pages from a single site. **Use sparingly** — costs scale with pages. Set `limit` and `includePaths` to target specific URL patterns.
+
+### Extract structured data
+
+```bash
+POST https://api.firecrawl.dev/v1/extract
+
+{
+  "urls": ["https://joescoffeeshop.com"],
+  "schema": {
+    "phone": "string",
+    "address": "string",
+    "hours": "string",
+    "email": "string"
+  }
+}
+```
+
+Returns data matching the schema — useful when you want consistent fields across many sites rather than raw markdown.
+
+### Search the web
+
+```bash
+POST https://api.firecrawl.dev/v1/search
+
+{
+  "query": "\"Joe's Coffee Shop\" Boulder Colorado",
+  "limit": 10
+}
+```
+
+Web search + scrape of top results. Useful for cross-source verification (find a business's official site when you only have a name + location).
+
+## MCP Tools (when used via MCP server)
+
+| Tool | Purpose |
+|------|---------|
+| `firecrawl_scrape` | Single-page extraction |
+| `firecrawl_map` | URL discovery on a site |
+| `firecrawl_crawl` | Multi-page crawl |
+| `firecrawl_extract` | Schema-driven structured data |
+| `firecrawl_search` | Web search + scrape |
+
+## When to Use
+
+- **Local SMB prospecting**: verify a business's website status (live, weak, missing) at the URL level after manual Maps/Yelp discovery
+- **Single-target enrichment**: pull contact info, hours, services from a business's own site
+- **Competitor research**: scrape competitor pricing, features, customer pages (this is the primary use in `competitor-profiling` skill)
+- **Programmatic page extraction**: when you need many sites' homepages or about pages in a consistent format
+- **JS-heavy sites**: when the page won't render with a simple `curl` because content loads after page load
+
+## When NOT to Use
+
+**Critical — do not use Firecrawl to scrape platforms hosting prospects:**
+
+- ✗ **Google Maps / Google search results** — Google ToS prohibits bulk extraction
+- ✗ **LinkedIn** — explicit ToS violation, will get scraper accounts banned and risks legal exposure
+- ✗ **Yelp** — ToS prohibits commercial scraping
+- ✗ **Apollo / ZoomInfo / Clearbit listings** — their ToS prohibits using competing data extracts
+- ✗ **Any platform you don't have a legitimate basis to extract from at scale**
+
+**Use Firecrawl for**: the *business's own website* (which you found via manual discovery on those platforms). That's the line — discovery happens on platforms, extraction happens on individual public business sites.
+
+## Pricing
+
+- Free tier: limited monthly credits
+- Paid tiers scale by request volume + concurrency
+- Confirm at https://www.firecrawl.dev/pricing
+
+## Rate Limits
+
+- Default: tier-dependent (typically 5–20 concurrent requests on paid plans)
+- Per-page cost varies by content type and rendering needs
+
+## Relevant Skills
+
+- prospecting (site enrichment for individual business URLs)
+- competitor-profiling (primary use: full-site competitor analysis)
+- ai-seo (scrape your own content for AI search optimization)
+- content-strategy (scrape industry sites for content gap analysis)
@@ -0,0 +1,182 @@
+# GitHub
+
+GitHub REST API for prospecting use cases: listing users who star, fork, or watch a repo as a high-quality developer-intent signal.
+
+## Capabilities
+
+| Integration | Available | Notes |
+|-------------|-----------|-------|
+| API | ✓ | Public REST API, well-documented |
+| MCP | - | Several community MCP servers exist; not bundled here |
+| CLI | ✓ | [github-prospects.js](../clis/github-prospects.js) — stargazers, forks, watchers, user, rate-limit |
+| SDK | ✓ | Official Octokit (JS, Python, Ruby, .NET, Go) |
+
+## Authentication
+
+- **Type**: Personal Access Token (PAT) or Fine-Grained PAT
+- **Header**: `Authorization: Bearer {token}`
+- **Get token**: https://github.com/settings/tokens
+- **Scopes for prospecting**:
+  - Public data (stargazers, forks, public profiles): **no scope required** with a token, or unauthenticated
+  - Public repo metadata: `public_repo` scope
+- **Env var**: `GITHUB_TOKEN`
+
+### Rate limits
+
+| Auth | Limit | When you hit it |
+|------|-------|-----------------|
+| Unauthenticated | 60 req/hr | Fine for one-off small lookups |
+| Authenticated PAT | 5,000 req/hr | Sufficient for a 10K-star repo pull in one hour |
+| GitHub App | 5,000–15,000 req/hr | For high-volume use |
+
+A 1,000-star repo with full enrichment (1 list call + 1 profile call per user) = ~1,011 requests. Always set a token.
+
+## Common Agent Operations
+
+### List stargazers (users who starred a repo)
+
+```bash
+GET https://api.github.com/repos/{owner}/{repo}/stargazers?per_page=100&page=1
+
+Accept: application/vnd.github+json
+X-GitHub-Api-Version: 2022-11-28
+Authorization: Bearer {token}
+```
+
+Pagination via `Link` header (`rel="next"`, `rel="last"`). Default 30 per page, max 100.
+
+Returns array of user objects with `login`, `id`, `html_url`, `type` (User or Organization). Full profile fields (email, company, blog, bio, location) require a follow-up call per user.
+
+### List forks (gives fork owner profiles)
+
+```bash
+GET https://api.github.com/repos/{owner}/{repo}/forks?per_page=100&page=1
+```
+
+Each fork object includes the `owner` (the user/org that forked). Forks are a stronger signal than stars — they imply intent to modify, not just bookmark.
+
+### List watchers (subscribers)
+
+```bash
+GET https://api.github.com/repos/{owner}/{repo}/subscribers?per_page=100&page=1
+```
+
+GitHub's "watch" → API's "subscribers". Smaller pool than stargazers but signals deeper engagement.
+
+### Get user profile (enrichment)
+
+```bash
+GET https://api.github.com/users/{username}
+```
+
+Returns: `name`, `company`, `blog`, `email` (if public), `bio`, `twitter_username`, `location`, `public_repos`, `followers`, `created_at`, `hireable`.
+
+**Key fields for prospecting**:
+- `email`: only ~5–20% of users publish this. Always nullable.
+- `company`: many users include `@org` syntax — strip the `@` for plain company name.
+- `blog`: often a personal website where contact info is published.
+- `twitter_username` / `bio`: useful for cross-channel research.
+
+### Check rate limit
+
+```bash
+GET https://api.github.com/rate_limit
+```
+
+## Prospecting Workflows
+
+### Workflow 1 — Stargazers of a competitor or adjacent tool
+
+```bash
+# 100 stargazers, enrich each one, only keep those with email or company set
+node tools/clis/github-prospects.js stargazers vercel/next.js \
+  --limit 100 --enrich --format csv > nextjs-stars.csv
+```
+
+Filter the CSV in your spreadsheet by `company` set OR `email` set OR `blog` set. Hand off to Apollo/Clay/Hunter to enrich the rest with email-by-name+company.
+
+### Workflow 2 — Forks of your own repo (warm intent)
+
+People who fork your repo have already shown direct interest. High-conversion outreach prospects.
+
+```bash
+node tools/clis/github-prospects.js forks yourorg/yourrepo \
+  --enrich --with-email --format csv > my-fork-prospects.csv
+```
+
+### Workflow 3 — Watchers of a category-defining repo
+
+Watchers are smaller in number but higher in intent — they're tracking changes, not just bookmarking.
+
+```bash
+node tools/clis/github-prospects.js watchers tldraw/tldraw \
+  --enrich --with-company --format csv > tldraw-watchers.csv
+```
+
+## CLI Reference
+
+```bash
+# Stargazers
+node tools/clis/github-prospects.js stargazers <owner/repo> \
+  [--limit N] [--enrich] [--with-email] [--with-company] \
+  [--with-blog] [--type User|Organization] [--format csv|json]
+
+# Forks
+node tools/clis/github-prospects.js forks <owner/repo> [...same flags]
+
+# Watchers (subscribers in API terms)
+node tools/clis/github-prospects.js watchers <owner/repo> [...same flags]
+
+# Single user lookup
+node tools/clis/github-prospects.js user <username>
+
+# Check rate limit
+node tools/clis/github-prospects.js rate-limit
+```
+
+**Flags**:
+- `--limit N`: cap total results pulled from the list endpoint
+- `--target N`: when filtering with `--with-*`, stop enriching as soon as N users match (saves quota on restrictive filters)
+- `--enrich`: fetch full profile per user (1 extra request each)
+- `--with-email` / `--with-company` / `--with-blog`: filter to users with these fields set (implies `--enrich`)
+- `--type User|Organization`: filter by account type
+- `--format csv`: output prospecting-ready CSV; default is JSON
+- `--dry-run`: preview the request without sending
+
+## When to Use
+
+- **SaaS prospecting** (primary use case): stargazers of a competitor, complement, or category-defining repo as in-market developer signal
+- **Open-source product marketing**: see who's forking or watching your own repo for warm outreach
+- **Developer-tool ICP discovery**: stargazers of `next.js`, `prisma`, `tailwindcss`, etc., signal a Next.js / Prisma / Tailwind developer
+- **Trigger event monitoring**: a recent fork of a competitor's repo often signals dissatisfaction or active evaluation
+
+## When NOT to Use
+
+- **Email is your only signal you need** — GitHub yields email for only ~5–20% of users. Pair with Apollo, Clay, or Hunter for enrichment from name + company.
+- **Hyper-broad lists** — a repo with 100K+ stars is mostly noise. Smaller, more specific repos (5K–25K stars) give higher-signal lists.
+- **You don't have a way to handle high-volume LinkedIn lookup downstream** — most enrichment from GitHub username goes through LinkedIn Sales Nav manually.
+
+## Compliance Notes
+
+- **GitHub data is public** — no ToS issue with reading the API. The ToS prohibits abusive scraping (bypassing rate limits, mass account creation), not legitimate API usage.
+- **Personal emails published on GitHub** — users opt in to publishing their email. Treat as business contact when paired with company/blog signals; respect GDPR/CAN-SPAM for the downstream send.
+- **Source URL lineage** — for every prospect added from GitHub, capture `html_url` (their profile URL) and the source repo. Required for GDPR DSAR defense.
+- **Cool-down between large pulls** — even at 5,000 req/hr, don't burst-fingerprint. Pagination is naturally paced; respect `X-RateLimit-Remaining` headers.
+
+## Pairing with Other Tools
+
+Typical GitHub prospecting pipeline:
+
+1. Pull stargazers/forkers via this CLI
+2. Filter to users with company set (or other signal)
+3. **Enrich missing emails** via Apollo / Clay / Hunter (lookup by name + company domain)
+4. **Validate emails** via Truelist before adding to outreach list
+5. **Hand off** to cold-email skill for outreach
+
+See `skills/prospecting/references/saas-prospecting.md` and `data-sources.md` for the full prospecting framework.
+
+## Relevant Skills
+
+- prospecting (primary use case)
+- cold-email (downstream outreach)
+- competitor-profiling (deeper account-level research on individual stargazers worth pursuing)
@@ -0,0 +1,184 @@
+# Truelist
+
+Email verification and deliverability validation. Validates single emails synchronously or bulk lists asynchronously. Returns an `email_state` + `email_sub_state` plus rich metadata (domain, MX record, suggested correction, disposable/role classification).
+
+Spec source: [Truelist-Labs/truelist-openapi](https://github.com/Truelist-Labs/truelist-openapi) (OpenAPI 3.1).
+
+## Capabilities
+
+| Integration | Available | Notes |
+|-------------|-----------|-------|
+| API | ✓ | REST API, OpenAPI 3.1 spec |
+| MCP | ✓ | Official [truelist-mcp](https://github.com/Truelist-Labs/truelist-mcp) server (Claude, Cursor, VS Code) |
+| CLI | ✓ | Official Go [truelist-cli](https://github.com/Truelist-Labs/truelist-cli) |
+| SDK | ✓ | Official: Node/TypeScript, Python, Ruby, PHP, Go, Java, C#/.NET. Framework integrations: Django, Laravel, Next.js, Rails, React, Svelte, Vue, WordPress |
+
+## Authentication
+
+- **Type**: Bearer token (API key)
+- **Header**: `Authorization: Bearer YOUR_API_KEY`
+- **Get key**: https://truelist.io/settings/api-keys
+- **Base URL**: `https://api.truelist.io`
+
+## Common Agent Operations
+
+### Verify a single email (synchronous)
+
+```bash
+POST https://api.truelist.io/api/v1/verify_inline?email=user@example.com
+Authorization: Bearer YOUR_API_KEY
+```
+
+No request body — the email is a query parameter. Returns a single-element `emails` array with verification fields:
+
+```json
+{
+  "emails": [
+    {
+      "address": "user@example.com",
+      "domain": "example.com",
+      "canonical": "user@example.com",
+      "mx_record": null,
+      "first_name": null,
+      "last_name": null,
+      "email_state": "ok",
+      "email_sub_state": "email_ok",
+      "verified_at": "2026-02-21T10:39:12.570Z",
+      "did_you_mean": null
+    }
+  ]
+}
+```
+
+### Bulk verification (asynchronous)
+
+```bash
+POST https://api.truelist.io/api/v1/verify
+Authorization: Bearer YOUR_API_KEY
+Content-Type: application/json
+
+{
+  "emails": [
+    "user1@example.com",
+    "user2@example.com"
+  ]
+}
+```
+
+Processes the list in the background. The response acknowledges submission; results are available via the dashboard, the Truelist UI's CSV download, or via integrations (Mailchimp, Klaviyo, HubSpot, Zapier, Make, n8n, etc.).
+
+For large lists, the dashboard's CSV upload + download flow is typically the lowest-friction path.
+
+### Get account information
+
+```bash
+GET https://api.truelist.io/me
+Authorization: Bearer YOUR_API_KEY
+```
+
+Returns email, name, UUID, time zone, admin role, API keys, and account plan info.
+
+## Response Fields (per email)
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `address` | string | The email address validated |
+| `domain` | string | The domain part of the address |
+| `canonical` | string | Canonical form of the address |
+| `mx_record` | string \| null | MX record for the domain |
+| `first_name` | string \| null | First name if detected |
+| `last_name` | string \| null | Last name if detected |
+| `email_state` | enum | Overall validation verdict (see below) |
+| `email_sub_state` | enum | More specific reason (see below) |
+| `verified_at` | datetime (ISO 8601) | When verification ran |
+| `did_you_mean` | string \| null | Suggested correction for typos |
+
+## `email_state` values
+
+| State | Meaning | What to do |
+|-------|---------|-----------|
+| `ok` | The email address is deliverable. | Include in outreach |
+| `email_invalid` | The email address is not deliverable. | Exclude — would bounce |
+| `risky` | May be deliverable but carries risk (role address, disposable, etc.) | Include cautiously, lower priority |
+| `unknown` | Deliverability could not be determined (timeout/connection). | Skip or re-verify with Thorough strategy |
+| `accept_all` | The mail server accepts all addresses (catch-all domain) | Include cautiously — can't confirm specific mailbox |
+
+## `email_sub_state` values
+
+| Sub-state | Meaning |
+|-----------|---------|
+| `email_ok` | Passed all checks |
+| `is_disposable` | Disposable / temporary provider (e.g., 10minutemail) |
+| `is_role` | Role-based address (info@, sales@, admin@) |
+| `unknown_error` | Sub-state could not be determined |
+| `failed_smtp_check` | SMTP check failed |
+
+Pair the two: `email_state: ok` + `email_sub_state: is_role` means "deliverable but a role inbox," whereas `email_state: email_invalid` + `email_sub_state: failed_smtp_check` means "doesn't exist."
+
+## Rate Limits
+
+| Endpoint | Limit |
+|----------|-------|
+| `/api/v1/verify_inline` | 10 requests/second |
+| `/api/v1/verify` | 10 requests/second |
+| `/me` | 10 requests/second |
+
+A 429 is returned on rate-limit exceed. Note: the per-email validation rate is separate and depends on your plan.
+
+## Error Responses
+
+| Code | Meaning |
+|------|---------|
+| 401 | Unauthorized — API key missing, invalid, or expired |
+| 429 | Rate limit exceeded |
+| 500 | Server error |
+
+All error bodies follow `{"error": "<human-readable message>"}`.
+
+## When to Use
+
+- **Before adding contacts to any cold outreach list** — non-negotiable safety step. Apollo/ZoomInfo/Hunter data accuracy is typically 60–80%; Truelist catches the rest.
+- **Real-time form validation** — block disposable / typo'd emails at signup. Use the inline endpoint (or the [form validation widget](https://truelist.io/docs/form-validation-widget)).
+- **Periodic list hygiene** — re-verify your active list quarterly to remove bounces before they hurt sender reputation.
+- **Pre-import validation** on email platform imports (Mailchimp, Klaviyo, HubSpot, etc.) — direct integrations exist for most.
+- **AI agent workflows** via the official MCP server for Claude, Cursor, and VS Code.
+
+## Why This Step is Non-Negotiable
+
+Cold email reputation is built over months and destroyed in days. ISPs (Gmail, Outlook, etc.) track sender reputation through:
+
+- **Bounce rate** — bounces over 2% trigger throttling
+- **Spam complaints** — spam traps in unvalidated lists generate complaints
+- **Engagement** — sending to dead mailboxes hurts engagement metrics
+
+A single unvalidated send to a bought or scraped list can damage a domain's sending reputation for months.
+
+## Workflow Integration
+
+Typical prospecting flow:
+
+1. Build initial prospect list (Apollo, Clay, ZoomInfo, Hunter, GitHub stargazers, etc.)
+2. **For agent-driven workflows**: use the Truelist MCP server to validate inline as the agent builds the list
+3. **For programmatic workflows**: POST emails to `/api/v1/verify` for async bulk OR `/api/v1/verify_inline` for sync single
+4. **For one-offs**: CSV upload via dashboard, download annotated CSV
+5. Filter: keep `email_state: ok`, include `risky`/`accept_all` cautiously with a strategy, exclude `email_invalid`, re-verify `unknown`
+6. Hand cleaned list to outreach platform (Instantly, Lemlist, Outreach, etc.) — see [outreach.md](outreach.md), [instantly.md](instantly.md), [lemlist.md](lemlist.md)
+
+## Native Integrations (no API code required)
+
+For non-developer workflows, Truelist has direct integrations:
+
+- **Email platforms**: Mailchimp, Klaviyo, HubSpot, ActiveCampaign, Brevo, Constant Contact, ConvertKit, Drip
+- **Automation**: Zapier, Make.com, n8n
+- **CRM / sales**: Salesforce, Go High Level, Clay.com
+- **Ecom**: BigCommerce
+- **AI / agents**: MCP server (Claude, Cursor, VS Code)
+
+See https://truelist.io/integrations for the current list.
+
+## Relevant Skills
+
+- prospecting (primary use case — validate before adding to outreach lists)
+- cold-email (downstream outreach against the validated list)
+- emails (transactional senders + subscriber list hygiene)
+- popups (real-time form validation on opt-in capture)