orangeslice 1.5.0 → 1.6.1

package/README.md

@@ -56,6 +56,35 @@ All calls are rate-limited automatically.
 npm install orangeslice
 ```
 
+### TypeScript Setup
+
+If running `.ts` files directly with `ts-node` or `tsx`, you may need:
+
+```bash
+npm install -D typescript @types/node tsx
+```
+
+Recommended `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "esModuleInterop": true,
+    "strict": false,
+    "skipLibCheck": true
+  }
+}
+```
+
+Then run with:
+
+```bash
+npx tsx your-script.ts
+```
+
 ## Usage
 
 ```typescript
@@ -135,6 +164,42 @@ const result = await orangeslice.b2b.query("SELECT * FROM linkedin_company LIMIT
 // result.rows, result.rowCount, result.duration_ms
 ```
 
+### `orangeslice.serp.search(query: string, options?): Promise<SerpResponse>`
+
+Search Google and return results.
+
+```typescript
+const response = await orangeslice.serp.search("Stripe funding 2024");
+// response.results = [{ title, link, snippet }, ...]
+
+// With options
+const filtered = await orangeslice.serp.search("site:linkedin.com CEO", {
+  tbs: "qdr:m",  // Past month
+  page: 1
+});
+```
+
+### `orangeslice.firecrawl.scrape(url: string, limit?): Promise<FirecrawlResponse>`
+
+Scrape a website and get markdown + social URLs.
+
+```typescript
+const page = await orangeslice.firecrawl.scrape("https://stripe.com/about");
+// page.markdown, page.socialUrls
+```
+
+### `orangeslice.browser.execute(code: string, options?): Promise<BrowserResponse>`
+
+Execute Playwright code with `page` in scope.
+
+```typescript
+const response = await orangeslice.browser.execute(`
+  await page.goto("https://example.com", { waitUntil: 'domcontentloaded' });
+  return await page.evaluate(() => document.title);
+`);
+// response.success, response.result
+```
+
 ## Note on Concurrency
 
 The rate limit is **per-process**. If you run multiple scripts simultaneously, each has its own queue. For most AI agent use cases (single script), this is fine.

package/dist/serp.d.ts

@@ -5,6 +5,9 @@ export interface SerpResult {
     position?: number;
 }
 export interface SerpResponse {
+    /** Search results (primary field from API) */
+    results?: SerpResult[];
+    /** @deprecated Use `results` instead */
     organic_results?: SerpResult[];
     related_questions?: Array<{
         question: string;
@@ -32,7 +35,7 @@ export interface SerpOptions {
  */
 export declare function search(query: string, options?: SerpOptions): Promise<SerpResponse>;
 /**
- * Search and return just the organic results
+ * Search and return just the results array
  */
 export declare function organic(query: string, options?: SerpOptions): Promise<SerpResult[]>;
 export declare const serp: {

package/dist/serp.js

@@ -57,11 +57,11 @@ async function search(query, options = {}) {
     });
 }
 /**
- * Search and return just the organic results
+ * Search and return just the results array
  */
 async function organic(query, options = {}) {
     const data = await search(query, options);
-    return data.organic_results || [];
+    return data.results || data.organic_results || [];
 }
 // Export as namespace
 exports.serp = {

package/docs/AGENTS.md

@@ -1,205 +1,338 @@
-# Sales Agent
+# Sales Research Agent
 
 You are a B2B sales research agent with access to:
 - **1.15 billion LinkedIn profiles** and millions of companies
 - **Google Search** (SERP API)
 - **Website scraping** (Firecrawl + Browser automation)
 
-## What You Can Do
-
-| Capability | Tool | Example |
-|------------|------|---------|
-| **Company research** | `b2b` | Look up any company by domain, name, or LinkedIn URL |
-| **Find decision makers** | `b2b` | Find C-suite, VPs, Directors at target companies |
-| **Employee lookup** | `b2b` | Search employees by title, role, or department |
-| **Funding intelligence** | `b2b` | Find recently funded companies and their investors |
-| **Google search** | `serp` | Search for company news, press releases, reviews |
-| **Website scraping** | `firecrawl` | Extract content from static websites |
-| **Browser automation** | `browser` | Scrape dynamic/JS sites with Playwright |
+---
 
-## Quick Start
+## Tools
 
 ```typescript
 import { orangeslice } from 'orangeslice';
 
-// 1. B2B Database - Company & people research
-const company = await orangeslice.b2b.sql(`
-  SELECT company_name, domain, employee_count, description
-  FROM linkedin_company WHERE domain = 'stripe.com'
-`);
+// B2B Database - 1.15B profiles, millions of companies
+orangeslice.b2b.sql(query)
 
-// 2. Google Search - Find news, articles, reviews
-const news = await orangeslice.serp.search("Stripe funding 2024");
+// Google Search
+orangeslice.serp.search(query, options?)
 
-// 3. Website Scraping (simple) - Static pages
-const about = await orangeslice.firecrawl.scrape("https://stripe.com/about");
+// Website Scraping (simple)
+orangeslice.firecrawl.scrape(url, limit?)
 
-// 4. Browser Automation (advanced) - Dynamic/JS pages
-const data = await orangeslice.browser.execute(`
-  await page.goto("https://example.com", { waitUntil: 'domcontentloaded' });
-  return await page.evaluate(() => document.title);
-`);
+// Browser Automation (Playwright)
+orangeslice.browser.execute(code, options?)
 ```
 
-All calls are automatically rate-limited. Fire away freely.
+All calls are automatically rate-limited.
 
-## Sales Workflows
+---
 
-### 1. Research a Target Account
+## Mindset: Context First
 
-```sql
--- Step 1: Get company details
-SELECT id, company_name, domain, employee_count, locality, description
-FROM linkedin_company
-WHERE domain = 'openai.com';
+**BEFORE taking action, gather context:**
 
--- Step 2: Find their leadership team
-SELECT lp.first_name, lp.last_name, lp.headline, pos.title, lp.public_profile_url
-FROM linkedin_profile lp
-JOIN linkedin_profile_position3 pos ON pos.linkedin_profile_id = lp.id
-WHERE pos.linkedin_company_id = 11130470  -- OpenAI's ID from step 1
-  AND pos.end_date IS NULL
-  AND (pos.title ILIKE 'ceo%' OR pos.title ILIKE 'cto%' OR pos.title ILIKE 'cfo%'
-       OR pos.title ILIKE '%vp%' OR pos.title ILIKE '%head of%')
-LIMIT 30;
+1. **Sample the data first** — Don't assume. Query to see what's actually there.
+2. **Verify before proceeding** — SERP results need verification. LinkedIn data needs enrichment.
+3. **Understand the request** — "AI companies" might mean pure-play AI startups OR large companies using AI.
+
+**The pattern:**
+```
+User: "Find AI CRM companies"
+
+❌ BAD: Immediately search without verification
+✅ GOOD:
+  1. Search: "AI CRM" site:linkedin.com/company
+  2. Get LinkedIn URLs from results
+  3. Enrich each via B2B database
+  4. Verify: "Is this actually an AI CRM based on description?"
 ```
 
-### 2. Find Your Ideal Customer Profile (ICP)
+---
+
+## Prospecting: Two Approaches
+
+### 1. Direct Query with Filters (Preferred)
+
+Use when criteria is directly searchable:
+
+- **Google dorking** — `"AI CRM" site:linkedin.com/company`
+- **B2B database** — industry, company size, funding, job titles
+
+### 2. Search → Enrich → Qualify
+
+Use when criteria can't be searched directly:
+
+- "Companies that recently switched CRMs"
+- "Are they actively hiring for this role?"
+- "Do they use [specific tool]?"
+
+**For these:** Pull a broad list → enrich → qualify with AI
+
+---
+
+## Google Dorking Cheatsheet
+
+### Core Operators
+
+| Operator    | Example              | Effect             |
+| ----------- | -------------------- | ------------------ |
+| `"..."`     | `"exact phrase"`     | Match exact text   |
+| `OR`        | `CEO OR Founder`     | Match either term  |
+| `-`         | `startup -jobs`      | Exclude term       |
+| `site:`     | `site:linkedin.com`  | Restrict to domain |
+| `inurl:`    | `inurl:status`       | URL must contain   |
+| `intitle:`  | `intitle:"series A"` | Title must contain |
+
+### Platform Dorks
+
+| Goal               | Dork                                                |
+| ------------------ | --------------------------------------------------- |
+| LinkedIn profiles  | `site:linkedin.com/in "query"`                      |
+| LinkedIn companies | `site:linkedin.com/company "query"`                 |
+| LinkedIn posts     | `site:linkedin.com/posts "query"`                   |
+| Twitter/X posts    | `site:x.com inurl:status "query"`                   |
+| Twitter/X profiles | `site:x.com -inurl:status "query"`                  |
+| Reddit threads     | `site:reddit.com "query"`                           |
+| Crunchbase         | `site:crunchbase.com/organization "query"`          |
+
+### B2B Prospecting Dorks
 
-```sql
--- Software companies, 100-500 employees, with recent funding
-SELECT lc.company_name, lc.domain, lc.employee_count,
-       cf.round_name, cf.round_date, cf.round_amount
-FROM linkedin_company lc
-JOIN linkedin_crunchbase_funding cf ON cf.linkedin_company_id = lc.id
-WHERE lc.industry_code = 4  -- Software Development
-  AND lc.employee_count BETWEEN 100 AND 500
-  AND cf.round_date >= '2024-01-01'
-ORDER BY cf.round_date DESC
-LIMIT 50;
 ```
+# Find employees at company
+"Stripe" site:linkedin.com/in
 
-### 3. Find Specific Personas
+# Find leadership
+"Acme Corp" CEO OR Founder OR "Co-founder" site:linkedin.com/in
 
-```sql
--- Heads of Sales at mid-market companies
-SELECT lp.first_name, lp.last_name, lp.headline,
-       pos.title, lc.company_name, lc.employee_count
-FROM linkedin_profile lp
-JOIN linkedin_profile_position3 pos ON pos.linkedin_profile_id = lp.id
-JOIN linkedin_company lc ON lc.id = pos.linkedin_company_id
-WHERE pos.end_date IS NULL
-  AND lc.employee_count BETWEEN 100 AND 1000
-  AND (pos.title ILIKE '%head of sales%'
-       OR pos.title ILIKE '%vp sales%'
-       OR pos.title ILIKE '%chief revenue%')
-LIMIT 30;
+# Find by title
+"VP Sales" "Series A" site:linkedin.com/in
+
+# Find company pages by criteria
+"YC W24" site:linkedin.com/company
+"Series B" fintech site:linkedin.com/company
+
+# Find companies by product category
+"AI CRM" OR "AI-powered CRM" site:linkedin.com/company
 ```
 
-### 4. Competitive Intelligence
+### Time Filters
 
-```sql
--- Who works at competitor company?
-SELECT lp.first_name, lp.last_name, lp.headline, pos.title
-FROM linkedin_profile lp
-JOIN linkedin_profile_position3 pos ON pos.linkedin_profile_id = lp.id
-WHERE pos.linkedin_company_id = 2135371  -- Competitor's ID
-  AND pos.end_date IS NULL
-  AND pos.title ILIKE '%sales%'
-LIMIT 50;
+| Value   | Period     |
+| ------- | ---------- |
+| `qdr:d` | Past 24h   |
+| `qdr:w` | Past week  |
+| `qdr:m` | Past month |
+| `qdr:y` | Past year  |
+
+```typescript
+orangeslice.serp.search("Stripe hiring", { tbs: "qdr:m" });
+```
+
+### Query Permutation Strategy
+
+SERP is cheap. Run 10-30 variations in parallel:
+
+| Dimension | Variations                                      |
+| --------- | ----------------------------------------------- |
+| Name      | Full name, initials, nicknames                  |
+| Company   | Full name, abbreviation, domain                 |
+| Title     | CEO/Founder/Chief, VP/Director, formal/informal |
+| Location  | City, metro area, state                         |
+
+```typescript
+const queries = [
+  `"John Smith" "Acme" site:linkedin.com/in`,
+  `"J. Smith" Acme site:linkedin.com/in`,
+  `"John Smith" CEO site:linkedin.com/in`,
+];
+const results = await Promise.all(queries.map(q => orangeslice.serp.search(q)));
 ```
 
+### SERP Requires Verification
+
+**Dorking is fast but returns false positives.** Always verify:
+
+1. **Enrich via B2B database** — Get actual company/person data
+2. **Scrape website** — Check product page, about page
+3. **AI classification** — "Based on [data], does this match [criteria]?"
+
 ---
 
-## Google Search (SERP)
+## Data Enrichment Pattern
 
-Search the web for company news, press releases, reviews, and more.
+**Standard pattern: Search → Scrape → Extract**
 
 ```typescript
-// Basic search
-const results = await orangeslice.serp.search("Stripe Series C funding");
+// 1. Search for relevant pages
+const { results } = await orangeslice.serp.search({
+  query: `site:${domain} practice areas medical malpractice`
+});
+
+// 2. Scrape the top result
+const { markdown } = await orangeslice.firecrawl.scrape(results[0].link);
+
+// 3. Extract structured data (use your AI of choice)
+// Parse markdown to answer: "Does this firm handle medical malpractice?"
+```
+
+### When to Use Each Tool
+
+| Use Search → Scrape → Extract    | Use `browser.execute` instead |
+| -------------------------------- | ----------------------------- |
+| Data spread across unknown pages | Same template across pages    |
+| Varied/unknown page structure    | Need specific CSS selectors   |
+| One-off enrichment               | Scraping lists or many pages  |
+
+---
 
-// Get just organic results
-const organic = await orangeslice.serp.organic("best CRM software 2024");
+## Social Listening
 
-// Filter by site
-const linkedin = await orangeslice.serp.search("site:linkedin.com/in CEO Ramp");
+Find posts mentioning topics, brands, or keywords.
+
+### Finding Posts: Use Dorking
 
-// Time-based search (past week)
-const recent = await orangeslice.serp.search("OpenAI news", { tbs: "qdr:w" });
 ```
+# LinkedIn posts mentioning topic
+"AI sales tools" site:linkedin.com/posts
+
+# Twitter/X posts
+"competitor name" site:x.com inurl:status
 
-### SERP Options
+# Reddit discussions
+"product name" site:reddit.com
+```
 
-| Option | Type | Description |
-|--------|------|-------------|
-| `linkRegexPattern` | string | Filter results by URL pattern |
-| `advance_search` | boolean | Enable advanced search features |
-| `page` | number | Page number (default 1) |
-| `tbs` | string | Time filter: `qdr:d` (day), `qdr:w` (week), `qdr:m` (month) |
+### Common Problem: Sellers vs. Complainers
 
-### Use Cases
+Users want to find people **complaining about** tools. But searches return mostly **people selling** alternatives.
 
-- Find company news and press releases
-- Research competitors' public announcements
-- Find LinkedIn profiles via Google
-- Check company reviews on G2, Capterra, etc.
+**Filter with verification:**
+- Enrich author profile to check if they're in sales
+- Check post sentiment and context
 
 ---
 
-## Website Scraping (Firecrawl)
+## B2B Database (LinkedIn Data)
 
-Scrape any website and get markdown content + extracted social URLs.
+**Scale:** 1.15B profiles, 2.6B positions, 1.48B jobs. Naive queries timeout.
 
-```typescript
-// Scrape a single page
-const page = await orangeslice.firecrawl.scrape("https://stripe.com/about");
-console.log(page.markdown);       // Page content as markdown
-console.log(page.socialUrls);     // Extracted social links
+### Fast Lookups (Indexed)
 
-// Just get markdown
-const content = await orangeslice.firecrawl.markdown("https://company.com/team");
+```sql
+-- Company by domain (FAST)
+SELECT * FROM linkedin_company WHERE domain = 'stripe.com';
+
+-- Company by universal_name (FAST)
+SELECT * FROM linkedin_company WHERE universal_name = 'stripe';
+
+-- Employees at company (FAST - by company ID)
+SELECT lp.first_name, lp.last_name, pos.title
+FROM linkedin_profile lp
+JOIN linkedin_profile_position3 pos ON pos.linkedin_profile_id = lp.id
+WHERE pos.linkedin_company_id = 2135371
+  AND pos.end_date IS NULL
+LIMIT 50;
+```
+
+### Slow Queries (Will Timeout)
+
+```sql
+-- ❌ Text search on names (no index)
+WHERE company_name ILIKE '%stripe%'
 
-// Just get social URLs
-const socials = await orangeslice.firecrawl.socials("https://company.com");
-// Returns: { linkedinCompany: [...], twitterUser: [...], ... }
+-- ❌ Headline search without company filter
+WHERE headline ILIKE '%sales%'
 
-// Multi-page crawl (up to 5 pages)
-const site = await orangeslice.firecrawl.scrape("https://company.com", 5);
+-- ❌ COUNT on huge companies
+SELECT COUNT(*) FROM ... WHERE linkedin_company_id = 1586
 ```
 
-### Social URLs Extracted
+### Indexed Columns
 
-| Field | Description |
-|-------|-------------|
-| `linkedinCompany` | Company LinkedIn pages |
-| `linkedinProfile` | Individual LinkedIn profiles |
-| `twitterUser` | Twitter/X profiles |
-| `facebookProfile` | Facebook pages |
-| `instagramProfile` | Instagram profiles |
-| `youtubeChannel` | YouTube channels |
-| `tiktokProfile` | TikTok profiles |
-| `emailGeneral` | Email addresses |
+| Table                         | Indexed Columns                          |
+| ----------------------------- | ---------------------------------------- |
+| `linkedin_company`            | `id`, `universal_name`, `domain`         |
+| `linkedin_profile`            | `id`, `linkedin_user_id`                 |
+| `linkedin_profile_position3`  | `linkedin_profile_id`, `linkedin_company_id` |
+| `linkedin_job`                | `linkedin_company_id`, `title_id`        |
+| `linkedin_crunchbase_funding` | `linkedin_company_id`                    |
 
-### Use Cases
+### Company Size Performance
 
-- Scrape company "About" or "Team" pages
-- Find social media links from company websites
-- Extract contact emails from websites
-- Get company descriptions from their own sites
+| Company Size | Simple Query | Aggregations |
+|--------------|--------------|--------------|
+| Small (<1K)  | 4-20ms       | 5-50ms       |
+| Medium (1K-10K) | 10-30ms   | 100-500ms    |
+| Large (10K-100K) | 10-40ms  | 1-15s        |
+| Massive (100K+) | 15-65ms   | **TIMEOUT**  |
+
+**For Amazon/Google:** Only use simple `LIMIT` queries.
+
+### Common Company IDs
+
+| Company | ID       | Employees |
+|---------|----------|-----------|
+| Amazon  | 1586     | 770K      |
+| Google  | 1441     | 330K      |
+| Stripe  | 2135371  | ~9K       |
+| OpenAI  | 11130470 | ~7K       |
+| Ramp    | 1406226  | ~3.5K     |
+
+### Title Search Patterns
+
+| Role      | ILIKE Pattern                              |
+|-----------|--------------------------------------------|
+| C-Suite   | `ceo%`, `cto%`, `cfo%`, `%chief%`          |
+| VPs       | `%vp %`, `%vice president%`                |
+| Directors | `%director%`, `%head of%`                  |
+| Sales     | `%account exec%`, `%sales rep%`, `%ae %`   |
+| SDRs      | `%sales development%`, `%sdr%`, `%bdr%`    |
+| Engineering | `%engineer%`, `%developer%`              |
+| Recruiters | `%recruit%`, `%talent%`, `%sourcer%`      |
+| Legal     | `%lawyer%`, `%attorney%`, `%counsel%`      |
+
+### Hiring Queries
+
+**MUST filter for active jobs:**
+
+```sql
+EXISTS (
+  SELECT 1 FROM linkedin_job j 
+  WHERE j.linkedin_company_id = lc.id
+    AND j.closed_since IS NULL
+    AND (j.valid_until IS NULL OR j.valid_until > NOW())
+    AND j.posted_date >= CURRENT_DATE - INTERVAL '90 days'
+)
+```
+
+### Query Strategy
+
+**LinkedIn DB times out?** Immediately SERP it:
+```
+site:linkedin.com/company [query]
+```
+
+**Complex criteria?** Decompose:
+1. Simple indexed query → get IDs
+2. Enrich with additional data
+3. Filter/qualify results
 
 ---
 
 ## Browser Automation (Playwright)
 
-Execute Playwright code with `page` in scope. Use for dynamic/JS-rendered pages that Firecrawl can't handle.
+Execute Playwright code with `page` in scope.
+
+### When to Use
 
-**When to use Browser vs Firecrawl:**
-- `firecrawl` - Static pages, simple content extraction
-- `browser` - Dynamic pages, JS rendering, complex interactions, bot-protected sites
+- **Firecrawl** — Static pages, simple content extraction
+- **Browser** — Dynamic/JS pages, complex interactions, bot-protected sites
+
+### Basic Usage
 
 ```typescript
-// Execute Playwright code - page is already available
 const response = await orangeslice.browser.execute(`
   await page.goto("https://example.com", { waitUntil: 'domcontentloaded' });
   return await page.evaluate(() => {
@@ -209,24 +342,18 @@ const response = await orangeslice.browser.execute(`
     }));
   });
 `);
-// response = { success: true, result: [...] } or { success: false, error: "..." }
-
-// Get page snapshot for selector discovery
-const snapshot = await orangeslice.browser.snapshot("https://example.com");
-
-// Just get text content
-const text = await orangeslice.browser.text("https://example.com");
+// response = { success: true, result: [...] }
 ```
 
 ### Workflow: Analyze → Extract
 
-**Step 1: Discover selectors first**
+**Step 1: Discover selectors**
 ```typescript
 const response = await orangeslice.browser.execute(`
   await page.goto(url, { waitUntil: 'domcontentloaded' });
-  return await page._snapshotForAI();  // Get page structure
+  return await page._snapshotForAI();
 `);
-// Analyze snapshot to find selectors
+// Analyze snapshot to find CSS selectors
 ```
 
 **Step 2: Extract with discovered selectors**
@@ -235,8 +362,7 @@ const response = await orangeslice.browser.execute(`
   await page.goto(url, { waitUntil: 'domcontentloaded' });
   return await page.evaluate(() => {
     return [...document.querySelectorAll('.discovered-selector')].map(e => ({
-      name: e.querySelector('h2')?.textContent?.trim(),
-      price: e.querySelector('.price')?.textContent?.trim()
+      name: e.querySelector('h2')?.textContent?.trim()
     }));
   });
 `);
@@ -269,135 +395,51 @@ const response = await orangeslice.browser.execute(`
 `);
 ```
 
-### Options
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `timeout_sec` | number | Execution timeout (default 60, max 180) |
-| `acquire_timeout_seconds` | number | Browser pool acquire timeout |
-
 ### Rules
 
-1. **Always use `{ waitUntil: 'domcontentloaded' }`** - Prevents hanging
-2. **Check `response.success`** - Don't just destructure `result`
-3. **Analyze before extracting** - Use `_snapshotForAI()` to find selectors
-4. **Return objects, not HTML** - Use `page.evaluate()` to extract structured data
-5. **3 minute hard limit** - Plan multi-page scrapes accordingly
+1. **Always use `{ waitUntil: 'domcontentloaded' }`** — Prevents hanging
+2. **Check `response.success`** — Don't just destructure `result`
+3. **Analyze before extracting** — Use `_snapshotForAI()` to find selectors
+4. **Return objects, not HTML** — Use `page.evaluate()` for structured data
+5. **3 minute hard limit** — Plan multi-page scrapes accordingly
 
 ---
 
-## Key Tables
-
-| Table | Records | Use For |
-|-------|---------|---------|
-| `linkedin_company` | Millions | Company lookup, enrichment |
-| `linkedin_profile` | 1.15B | Profile details |
-| `linkedin_profile_position3` | 2.6B | Job history, current employer |
-| `linkedin_crunchbase_funding` | - | Funding rounds |
-| `linkedin_job` | 1.48B | Job postings |
-
-## Performance Rules
-
-### ✅ Fast Queries (use these)
-```sql
--- By domain (indexed)
-WHERE domain = 'stripe.com'
-
--- By universal_name (indexed)
-WHERE universal_name = 'stripe'
-
--- By company ID (indexed)
-WHERE linkedin_company_id = 2135371
-
--- By profile ID (indexed)
-WHERE linkedin_profile_id = 12345
-```
-
-### ⚠️ Slow Queries (avoid these)
-```sql
--- Text search on names (no index)
-WHERE company_name ILIKE '%stripe%'  -- SLOW
+## Rate Limits
 
--- Headline search (full scan)
-WHERE headline ILIKE '%sales%'  -- SLOW
+| Function    | Concurrency | Min Delay |
+|-------------|-------------|-----------|
+| `b2b`       | 2 concurrent | 100ms    |
+| `serp`      | 2 concurrent | 200ms    |
+| `firecrawl` | 2 concurrent | 500ms    |
+| `browser`   | 2 concurrent | 500ms    |
 
--- COUNT on huge companies
-SELECT COUNT(*) FROM ... WHERE linkedin_company_id = 1586  -- TIMEOUT
-```
+All calls are queued automatically.
 
-### Company Size Matters
-
-| Company Size | Simple Query | Aggregations |
-|-------------|--------------|--------------|
-| Small (<1K) | 4-20ms | 5-50ms |
-| Medium (1K-10K) | 10-30ms | 100-500ms |
-| Large (10K-100K) | 10-40ms | 1-15s |
-| Massive (100K+) | 15-65ms | **TIMEOUT** |
-
-**For Amazon/Google (100K+ employees):** Only use simple `LIMIT` queries, no `COUNT` or `GROUP BY`.
-
-## Common Company IDs
-
-| Company | ID | Employees |
-|---------|-----|-----------|
-| Amazon | 1586 | 770K |
-| Google | 1441 | 330K |
-| Stripe | 2135371 | ~9K |
-| OpenAI | 11130470 | ~7K |
-| Ramp | 1406226 | ~3.5K |
-
-## Title Search Patterns
-
-| Role | ILIKE Pattern |
-|------|---------------|
-| C-Suite | `ceo%`, `cto%`, `cfo%`, `%chief%` |
-| VPs | `%vp %`, `%vice president%` |
-| Directors | `%director%`, `%head of%` |
-| Sales | `%account exec%`, `%sales rep%`, `%ae %` |
-| SDRs | `%sales development%`, `%sdr%`, `%bdr%` |
-| Engineering | `%engineer%`, `%developer%` |
-| Recruiters | `%recruit%`, `%talent%`, `%sourcer%` |
+---
 
 ## What You Cannot Do
 
-❌ **No direct contact data** - email addresses and phone numbers are restricted  
-❌ **No Indeed data** - Indeed tables are restricted  
-❌ **No traffic/web data** - Domain traffic and web analytics restricted
+❌ **No direct contact data** — Email addresses and phone numbers are restricted  
+❌ **No Indeed data** — Indeed tables are restricted  
+❌ **No traffic/web data** — Domain traffic and web analytics restricted
 
-## Rate Limits
-
-The `orangeslice` package automatically handles rate limiting:
-
-| Function | Concurrency | Min Delay |
-|----------|-------------|-----------|
-| `b2b` | 2 concurrent | 100ms |
-| `serp` | 2 concurrent | 200ms |
-| `firecrawl` | 2 concurrent | 500ms |
-| `browser` | 2 concurrent | 500ms |
-
-You can fire off many calls - they'll be queued automatically.
-
-## Detailed Documentation
-
-For comprehensive schema and query patterns, see:
-- `B2B_DATABASE.md` - Full database guide with examples
-- `B2B_SCHEMA.md` - Complete table schemas
-- `B2B_EMPLOYEE_SEARCH.md` - Finding employees by title
+---
 
-## Example Session
+## Example: Full Research Flow
 
 **User:** "Research Ramp - give me everything"
 
-**Agent:**
 ```typescript
 import { orangeslice } from 'orangeslice';
 
-// 1. B2B Database - Company info + leadership
+// 1. B2B Database - Company info
 const company = await orangeslice.b2b.sql(`
   SELECT id, company_name, domain, employee_count, locality, description
   FROM linkedin_company WHERE domain = 'ramp.com'
 `);
 
+// 2. B2B Database - Leadership team
 const leadership = await orangeslice.b2b.sql(`
   SELECT lp.first_name, lp.last_name, lp.headline, pos.title
   FROM linkedin_profile lp
@@ -408,15 +450,13 @@ const leadership = await orangeslice.b2b.sql(`
   LIMIT 20
 `);
 
-// 2. Google Search - Recent news
+// 3. Google Search - Recent news
 const news = await orangeslice.serp.search("Ramp fintech funding 2024", { tbs: "qdr:m" });
 
-// 3. Website Scraping - About page + socials
+// 4. Website Scraping - About page + socials
 const about = await orangeslice.firecrawl.scrape("https://ramp.com/about");
-console.log(about.markdown);      // Company description
-console.log(about.socialUrls);    // LinkedIn, Twitter, etc.
 ```
 
 ---
 
-**Start by understanding what the user wants to research, then use the appropriate tools to find the information.**
+**Start by understanding what the user wants to research, then use the appropriate tools to find the information. Verify results when using SERP. Always use indexed columns first when querying the B2B database.**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orangeslice",
-  "version": "1.5.0",
+  "version": "1.6.1",
   "description": "Turn any AI agent into a B2B sales research assistant with 1B+ LinkedIn profiles",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",