orangeslice 1.4.2 → 1.6.0

package/README.md

@@ -14,7 +14,8 @@ This copies documentation to `./orangeslice-docs/` and installs the package. Poi
 |----------|------------|
 | `b2b` | Query 1B+ LinkedIn profiles, companies, funding, jobs |
 | `serp` | Google search for news, articles, reviews |
-| `firecrawl` | Scrape websites, extract social URLs |
+| `firecrawl` | Scrape static websites, extract social URLs |
+| `browser` | Playwright automation for dynamic/JS sites |
 
 ## Quick Example
 

package/dist/browser.d.ts

@@ -0,0 +1,68 @@
+export interface BrowserResponse {
+    success: boolean;
+    result?: any;
+    error?: string;
+    browser_live_view_url?: string;
+}
+export interface BrowserOptions {
+    /** Browser pool ID (default: pre-warmed pool) */
+    pool?: string;
+    /** Execution timeout in seconds */
+    timeout_sec?: number;
+    /** Timeout for acquiring browser from pool */
+    acquire_timeout_seconds?: number;
+}
+/**
+ * Execute Playwright code with `page` in scope.
+ * Browser is automatically acquired from a pre-warmed pool and released when done.
+ *
+ * @param code - Playwright code to execute (has `page` in scope)
+ * @param options - Optional settings for timeout and pool
+ *
+ * @example
+ * // Get page snapshot for analysis
+ * const response = await browser.execute(`
+ *   await page.goto(url, { waitUntil: 'domcontentloaded' });
+ *   return await page._snapshotForAI();
+ * `);
+ *
+ * @example
+ * // Extract data from page
+ * const response = await browser.execute(`
+ *   await page.goto("https://example.com", { waitUntil: 'domcontentloaded' });
+ *   return await page.evaluate(() => {
+ *     return [...document.querySelectorAll('.item')].map(el => ({
+ *       title: el.querySelector('h2')?.textContent?.trim(),
+ *       url: el.querySelector('a')?.href
+ *     }));
+ *   });
+ * `);
+ * // response = { success: true, result: [...] }
+ */
+export declare function execute(code: string, options?: BrowserOptions): Promise<BrowserResponse>;
+/**
+ * Get a page snapshot for AI analysis.
+ * Useful for discovering selectors before extraction.
+ *
+ * @param url - URL to navigate to
+ *
+ * @example
+ * const snapshot = await browser.snapshot("https://example.com/products");
+ * // Returns page HTML structure for selector discovery
+ */
+export declare function snapshot(url: string): Promise<BrowserResponse>;
+/**
+ * Extract text content from a URL.
+ *
+ * @param url - URL to navigate to
+ *
+ * @example
+ * const response = await browser.text("https://example.com");
+ * // response.result = page text content
+ */
+export declare function text(url: string): Promise<BrowserResponse>;
+export declare const browser: {
+    execute: typeof execute;
+    snapshot: typeof snapshot;
+    text: typeof text;
+};

package/dist/browser.js

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.browser = void 0;
+exports.execute = execute;
+exports.snapshot = snapshot;
+exports.text = text;
+const queue_1 = require("./queue");
+const API_URL = process.env.ORANGESLICE_API_URL || "https://orangeslice.ai/api/function?functionId=browser";
+// Shared queue for browser requests (limit concurrent browser sessions)
+const queue = (0, queue_1.createQueue)(2);
+const rateLimiter = (0, queue_1.createRateLimiter)(500); // 500ms between requests
+/**
+ * Helper to make POST request, handling redirects manually
+ * (Node.js fetch has issues with POST body on redirects)
+ */
+async function fetchWithRedirect(url, body) {
+    let response = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body,
+        redirect: "manual",
+    });
+    // Handle redirect manually - re-POST to the new location
+    if (response.status >= 300 && response.status < 400) {
+        const location = response.headers.get("location");
+        if (location) {
+            response = await fetch(location, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body,
+            });
+        }
+    }
+    return response;
+}
+/**
+ * Execute Playwright code with `page` in scope.
+ * Browser is automatically acquired from a pre-warmed pool and released when done.
+ *
+ * @param code - Playwright code to execute (has `page` in scope)
+ * @param options - Optional settings for timeout and pool
+ *
+ * @example
+ * // Get page snapshot for analysis
+ * const response = await browser.execute(`
+ *   await page.goto(url, { waitUntil: 'domcontentloaded' });
+ *   return await page._snapshotForAI();
+ * `);
+ *
+ * @example
+ * // Extract data from page
+ * const response = await browser.execute(`
+ *   await page.goto("https://example.com", { waitUntil: 'domcontentloaded' });
+ *   return await page.evaluate(() => {
+ *     return [...document.querySelectorAll('.item')].map(el => ({
+ *       title: el.querySelector('h2')?.textContent?.trim(),
+ *       url: el.querySelector('a')?.href
+ *     }));
+ *   });
+ * `);
+ * // response = { success: true, result: [...] }
+ */
+async function execute(code, options = {}) {
+    return queue(async () => {
+        return rateLimiter(async () => {
+            const body = JSON.stringify({ code, ...options });
+            const response = await fetchWithRedirect(API_URL, body);
+            if (!response.ok) {
+                throw new Error(`Browser request failed: ${response.status} ${response.statusText}`);
+            }
+            const data = (await response.json());
+            return data;
+        });
+    });
+}
+/**
+ * Get a page snapshot for AI analysis.
+ * Useful for discovering selectors before extraction.
+ *
+ * @param url - URL to navigate to
+ *
+ * @example
+ * const snapshot = await browser.snapshot("https://example.com/products");
+ * // Returns page HTML structure for selector discovery
+ */
+async function snapshot(url) {
+    const code = `
+      await page.goto(${JSON.stringify(url)}, { waitUntil: 'domcontentloaded' });
+      return await page._snapshotForAI();
+   `;
+    return execute(code);
+}
+/**
+ * Extract text content from a URL.
+ *
+ * @param url - URL to navigate to
+ *
+ * @example
+ * const response = await browser.text("https://example.com");
+ * // response.result = page text content
+ */
+async function text(url) {
+    const code = `
+      await page.goto(${JSON.stringify(url)}, { waitUntil: 'domcontentloaded' });
+      return await page.evaluate(() => document.body.innerText);
+   `;
+    return execute(code);
+}
+// Export as namespace
+exports.browser = {
+    execute,
+    snapshot,
+    text,
+};

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 import { b2b } from "./b2b";
 import { serp } from "./serp";
 import { firecrawl } from "./firecrawl";
-export { b2b, serp, firecrawl };
+import { browser } from "./browser";
+export { b2b, serp, firecrawl, browser };
 /**
  * Main orangeslice namespace - AI sales agent toolkit
  *
@@ -14,9 +15,15 @@ export { b2b, serp, firecrawl };
  * // Google Search
  * const results = await orangeslice.serp.search("best CRM software 2024");
  *
- * // Website Scraping
+ * // Website Scraping (simple)
  * const page = await orangeslice.firecrawl.scrape("https://stripe.com/about");
  *
+ * // Browser Automation (Playwright)
+ * const data = await orangeslice.browser.execute(`
+ *   await page.goto("https://example.com", { waitUntil: 'domcontentloaded' });
+ *   return await page.evaluate(() => document.title);
+ * `);
+ *
  * // All calls are automatically rate-limited and queued
  */
 export declare const orangeslice: {
@@ -34,5 +41,10 @@ export declare const orangeslice: {
         markdown: typeof import("./firecrawl").markdown;
         socials: typeof import("./firecrawl").socials;
     };
+    browser: {
+        execute: typeof import("./browser").execute;
+        snapshot: typeof import("./browser").snapshot;
+        text: typeof import("./browser").text;
+    };
 };
 export default orangeslice;

package/dist/index.js

@@ -1,12 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.orangeslice = exports.firecrawl = exports.serp = exports.b2b = void 0;
+exports.orangeslice = exports.browser = exports.firecrawl = exports.serp = exports.b2b = void 0;
 const b2b_1 = require("./b2b");
 Object.defineProperty(exports, "b2b", { enumerable: true, get: function () { return b2b_1.b2b; } });
 const serp_1 = require("./serp");
 Object.defineProperty(exports, "serp", { enumerable: true, get: function () { return serp_1.serp; } });
 const firecrawl_1 = require("./firecrawl");
 Object.defineProperty(exports, "firecrawl", { enumerable: true, get: function () { return firecrawl_1.firecrawl; } });
+const browser_1 = require("./browser");
+Object.defineProperty(exports, "browser", { enumerable: true, get: function () { return browser_1.browser; } });
 /**
  * Main orangeslice namespace - AI sales agent toolkit
  *
@@ -19,14 +21,21 @@ Object.defineProperty(exports, "firecrawl", { enumerable: true, get: function ()
  * // Google Search
  * const results = await orangeslice.serp.search("best CRM software 2024");
  *
- * // Website Scraping
+ * // Website Scraping (simple)
  * const page = await orangeslice.firecrawl.scrape("https://stripe.com/about");
  *
+ * // Browser Automation (Playwright)
+ * const data = await orangeslice.browser.execute(`
+ *   await page.goto("https://example.com", { waitUntil: 'domcontentloaded' });
+ *   return await page.evaluate(() => document.title);
+ * `);
+ *
  * // All calls are automatically rate-limited and queued
  */
 exports.orangeslice = {
     b2b: b2b_1.b2b,
     serp: serp_1.serp,
     firecrawl: firecrawl_1.firecrawl,
+    browser: browser_1.browser,
 };
 exports.default = exports.orangeslice;

package/docs/AGENTS.md

@@ -1,300 +1,445 @@
-# 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)
-
-## 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 company websites |
+- **Website scraping** (Firecrawl + Browser automation)
 
+---
 
-## 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)
+
+// Google Search
+orangeslice.serp.search(query, options?)
 
-// 2. Google Search - Find news, articles, reviews
-const news = await orangeslice.serp.search("Stripe funding 2024");
+// Website Scraping (simple)
+orangeslice.firecrawl.scrape(url, limit?)
 
-// 3. Website Scraping - Get company page content
-const about = await orangeslice.firecrawl.scrape("https://stripe.com/about");
+// 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
+## Mindset: Context First
 
-### 1. Research a Target Account
+**BEFORE taking action, gather context:**
 
-```sql
--- Step 1: Get company details
-SELECT id, company_name, domain, employee_count, locality, description
-FROM linkedin_company
-WHERE domain = 'openai.com';
+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.
 
--- 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;
+**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?"
+```
 
-// Get just organic results
-const organic = await orangeslice.serp.organic("best CRM software 2024");
+### When to Use Each Tool
 
-// Filter by site
-const linkedin = await orangeslice.serp.search("site:linkedin.com/in CEO Ramp");
+| 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  |
+
+---
+
+## Social Listening
+
+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)
+
+```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;
+```
 
-// Just get markdown
-const content = await orangeslice.firecrawl.markdown("https://company.com/team");
+### Slow Queries (Will Timeout)
 
-// Just get social URLs
-const socials = await orangeslice.firecrawl.socials("https://company.com");
-// Returns: { linkedinCompany: [...], twitterUser: [...], ... }
+```sql
+-- ❌ Text search on names (no index)
+WHERE company_name ILIKE '%stripe%'
 
-// Multi-page crawl (up to 5 pages)
-const site = await orangeslice.firecrawl.scrape("https://company.com", 5);
+-- ❌ Headline search without company filter
+WHERE headline ILIKE '%sales%'
+
+-- ❌ 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.
 
-## Key Tables
+### Common Company IDs
 
-| 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 |
+| Company | ID       | Employees |
+|---------|----------|-----------|
+| Amazon  | 1586     | 770K      |
+| Google  | 1441     | 330K      |
+| Stripe  | 2135371  | ~9K       |
+| OpenAI  | 11130470 | ~7K       |
+| Ramp    | 1406226  | ~3.5K     |
 
-## Performance Rules
+### 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:**
 
-### ✅ Fast Queries (use these)
 ```sql
--- By domain (indexed)
-WHERE domain = 'stripe.com'
+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'
+)
+```
 
--- By universal_name (indexed)
-WHERE universal_name = 'stripe'
+### Query Strategy
+
+**LinkedIn DB times out?** Immediately SERP it:
+```
+site:linkedin.com/company [query]
+```
 
--- By company ID (indexed)
-WHERE linkedin_company_id = 2135371
+**Complex criteria?** Decompose:
+1. Simple indexed query → get IDs
+2. Enrich with additional data
+3. Filter/qualify results
 
--- By profile ID (indexed)
-WHERE linkedin_profile_id = 12345
+---
+
+## Browser Automation (Playwright)
+
+Execute Playwright code with `page` in scope.
+
+### When to Use
+
+- **Firecrawl** — Static pages, simple content extraction
+- **Browser** — Dynamic/JS pages, complex interactions, bot-protected sites
+
+### Basic Usage
+
+```typescript
+const response = await orangeslice.browser.execute(`
+  await page.goto("https://example.com", { waitUntil: 'domcontentloaded' });
+  return await page.evaluate(() => {
+    return [...document.querySelectorAll('.item')].map(el => ({
+      title: el.querySelector('h2')?.textContent?.trim(),
+      url: el.querySelector('a')?.href
+    }));
+  });
+`);
+// response = { success: true, result: [...] }
 ```
 
-### ⚠️ Slow Queries (avoid these)
-```sql
--- Text search on names (no index)
-WHERE company_name ILIKE '%stripe%'  -- SLOW
+### Workflow: Analyze → Extract
 
--- Headline search (full scan)
-WHERE headline ILIKE '%sales%'  -- SLOW
+**Step 1: Discover selectors**
+```typescript
+const response = await orangeslice.browser.execute(`
+  await page.goto(url, { waitUntil: 'domcontentloaded' });
+  return await page._snapshotForAI();
+`);
+// Analyze snapshot to find CSS selectors
+```
 
--- COUNT on huge companies
-SELECT COUNT(*) FROM ... WHERE linkedin_company_id = 1586  -- TIMEOUT
+**Step 2: Extract with discovered selectors**
+```typescript
+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()
+    }));
+  });
+`);
 ```
 
-### Company Size Matters
+### Bot Protection
 
-| 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%` |
+For bot-protected sites, use single-session navigation:
 
-## What You Cannot Do
+```typescript
+const response = await orangeslice.browser.execute(`
+  // Navigate to entry page (passes bot check once)
+  await page.goto(entryUrl, { waitUntil: 'domcontentloaded' });
+  
+  // Get all URLs to visit
+  const urls = await page.evaluate(() => 
+    [...document.querySelectorAll('a.link')].map(a => a.href)
+  );
+  
+  // Visit each IN THE SAME SESSION
+  const results = [];
+  for (const url of urls.slice(0, 10)) {
+    await page.goto(url, { waitUntil: 'domcontentloaded' });
+    const data = await page.evaluate(() => ({
+      title: document.querySelector('h1')?.textContent?.trim()
+    }));
+    results.push(data);
+  }
+  return results;
+`);
+```
+
+### Rules
 
-❌ **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
+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
+
+---
 
 ## 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    |
+
+All calls are queued automatically.
 
-| Function | Concurrency | Min Delay |
-|----------|-------------|-----------|
-| `b2b` | 2 concurrent | 100ms |
-| `serp` | 2 concurrent | 200ms |
-| `firecrawl` | 2 concurrent | 500ms |
+---
 
-You can fire off many calls - they'll be queued automatically.
+## What You Cannot Do
 
-## Detailed Documentation
+❌ **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
 
-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
@@ -305,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.4.2",
+  "version": "1.6.0",
   "description": "Turn any AI agent into a B2B sales research assistant with 1B+ LinkedIn profiles",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",