orangeslice 2.1.2 → 2.1.3

package/docs/prospecting/index.md

@@ -15,11 +15,12 @@ description: Strategies for searching or finding people and companies. This is a
 
 Run queries with built-in filters when the criteria is searchable:
 
-- **Web search (`services.web.search`)** — **Default for LinkedIn**. Use for keywords, niche queries, fuzzy matching, anything descriptive.
+- **Web search (`services.web.search`)** — **Default for ALL prospecting**. Use for keywords, niche queries, fuzzy matching, anything descriptive. This includes finding LinkedIn profiles/companies via `site:linkedin.com` queries.
 - **Crunchbase (`services.crunchbase.search`)** — **Default for funding data**. Use for funding-stage, round type, amount, date windows, and investor-backed company discovery.
-- **LinkedIn B2B DB** — **Indexed lookups ONLY:** company by domain/slug/ID, employees at a known company (by company_id), basic funding (2-table join). Everything else = web search. See [QUICK_REF](./linkedin_data/QUICK_REF.md).
+- **Ocean.io (`services.ocean.search.*`)** — **Default for lookalike search**. When the user has example companies/domains and wants to find more like them. See [Lookalike Search Guide](../lookalike-search/).
 - **Google Maps** — industry, location, ratings
 - **LinkedIn job search** — job filters, titles
+- **LinkedIn B2B DB** — **Almost never for prospecting.** Acceptable only for trivially simple single-indexed-column filters (e.g. `industry_code = 4 AND country_code = 'US'`), looking up entities you already have an identifier for, or listing employees at a single known company. Any query involving keywords, descriptions, names, skills, or multi-criteria matching = web search. See [QUICK_REF](./linkedin_data/QUICK_REF.md).
 
 **Use this when possible.** It's fast and returns pre-filtered results.
 
@@ -83,11 +84,12 @@ When using qualification columns, think Circle & Star:
 
 | Source                   | Use When                                                    | Limitations                                              |
 | ------------------------ | ----------------------------------------------------------- | -------------------------------------------------------- |
-| **Web Search (Default)** | **Everything else** — keywords, niche, fuzzy, specific      | Requires verification columns for false positives.       |
+| **Web Search (Default)** | **ALL prospecting/discovery** — keywords, niche, fuzzy, specific, LinkedIn profiles & companies via `site:linkedin.com` | Requires verification columns for false positives.       |
 | **Crunchbase (Funding Default)** | Funding-focused prospecting: stage, round type, amount, recency, investors | Best for funding intelligence; use other sources for non-funding discovery criteria. |
+| **Ocean.io (Lookalike Default)** | User has seed domains and wants similar companies/people. "Find companies like X." | Needs seed domains as input. Not for keyword/niche discovery from scratch. See [guide](../lookalike-search/). |
 | **PredictLeads**         | Company intelligence, buying signals, and structured company events at scale | Coverage varies by company/market; use web search for very niche long-tail discovery. |
 | **Niche Directory Scrape** | Well-defined categories with existing lists (see below)   | Requires finding the right directory first.              |
-| **LinkedIn B2B DB**      | **Indexed lookups ONLY:** company by domain/slug/ID, employees at known company, basic 2-table funding. | **3s hard max. No keyword search, no LATERAL, no 3+ table joins.** Everything else = web search. |
+| **LinkedIn B2B DB**      | **Almost never for prospecting.** Only for: (1) lookups by known identifier (URL/domain/ID), (2) employees at a single known company, (3) trivially simple single-indexed-column filters like `industry_code` or `country_code`. | **Any query with keywords, descriptions, names, ILIKE, skills, or multi-criteria = web search.** The bar is extremely high — if in doubt, use web search. |
 | **Google Maps**          | Local/SMB, physical locations, restaurants, retail          | Limited to businesses with physical presence.            |
 | **Apify Actors**         | Platform-specific scraping (Instagram, TikTok, job boards)  | Per-platform setup. May break with platform changes.     |
 
@@ -104,13 +106,13 @@ PredictLeads is usually the best choice for:
 Prefer other sources when:
 - You need **brand-new niche discovery** with fuzzy intent matching -> use `web.search`
 - You need local storefront/SMB discovery -> use Google Maps
-- You need fast indexed LinkedIn lookups by known IDs/domain/company -> use LinkedIn B2B DB
+- You need to look up a specific company/person by known URL/domain/ID -> use LinkedIn B2B DB (lookup only, NOT discovery)
 
 ### Funding Prospecting Standard: Use Crunchbase First
 
 For any request centered on funding data (for example: "Series A fintech companies", "companies that raised in the last 12 months", "recently funded startups"), use `services.crunchbase.search` as the **standard/default source**.
 
-Use LinkedIn B2B DB funding joins only when the user explicitly needs a LinkedIn-only workflow or a narrow lookup tied to existing LinkedIn records. Otherwise, Crunchbase should be the first choice for funding-oriented discovery.
+**Never use LinkedIn B2B DB for funding discovery.** Crunchbase is always the right choice for finding funded companies. LinkedIn B2B DB funding tables should only be used when you already have a specific company ID and need to check its funding history.
 
 ### Niche Directory Scraping — For Well-Defined Categories
 
@@ -141,9 +143,12 @@ When users ask for companies in a **specific, well-defined niche** (e.g., "fast
 
 ## 🚨 Critical: Web Search vs B2B Database
 
-### Web Search (`services.web.search`) — DEFAULT CHOICE
+### Web Search (`services.web.search`) — DEFAULT CHOICE FOR PROSPECTING
 
-**Use web search for everything unless the query is purely industry/title or high volume and willing to sadrifice q**
+**Use web search for almost all prospecting and discovery. The LinkedIn B2B DB should almost never be your first choice.**
+
+> **🚫 STOP: Are you about to query the LinkedIn B2B DB to find new leads?**
+> Unless your query is a **trivially simple single-indexed-column filter** (e.g. `industry_code = 4 AND country_code = 'US'`), **use web search instead**. The moment your query involves keywords, descriptions, company names, headlines, skills, ILIKE, or any multi-criteria matching — it's a web search query, not a DB query.
 
 Web search handles:
 - Keywords, product names, technologies ("AI CRM", "Salesforce", "React")
@@ -151,6 +156,7 @@ Web search handles:
 - Fuzzy matching (anything that's hard to express as exact filters)
 - Any descriptive criteria (company descriptions, headlines, bios)
 - Small-to-medium result sets (10-500 results)
+- **Most volume requests** — batched web searches are often better than DB queries even for high volume
 
 ```
 site:linkedin.com/company "AI CRM"
@@ -159,39 +165,46 @@ site:linkedin.com/in "VP Sales" "fintech"
 
 Web search is fast, cheap, and works for almost everything. **When in doubt, use web search.**
 
-### LinkedIn B2B Database — LOOKUP TOOL ONLY
+### LinkedIn B2B Database — LAST RESORT FOR PROSPECTING
 
-> **The LinkedIn DB is a lookup tool, not a search engine.** Only fast indexed queries are allowed (under 3 seconds, max 2-table joins). Everything else falls back to `services.web.search` with `site:linkedin.com` patterns. **You MUST read `services/web/search` before using web search.**
+> **🚫 The LinkedIn DB is almost never the right tool for prospecting.** It is primarily an enrichment/lookup tool for entities you ALREADY know about. The only prospecting exception is **trivially simple queries on single indexed columns** (e.g. `industry_code`, `country_code`, `company_size_code`, `employee_count`).
 
 > **🚨 CRITICAL: ALWAYS SAVE LINKEDIN DB RESULTS TO A FILE 🚨**
 > LinkedIn B2B database queries are **billed per execution**. You **MUST** persist query results immediately using `fs.writeFile("files/<name>.json", JSON.stringify(rows))`. If you return results without saving them, the query must be re-run — **double-charging the user**. Never discard, summarize-only, or preview LinkedIn DB results without also writing them to a file in the same step.
 
-**ALLOWED queries (all under 3s, max 2-table joins):**
-- Company by domain/slug/ID (4-8ms)
-- Employees at a known company by company_id (8-32ms)
-- Basic funding with 2-table join (10-99ms)
-- Certifications (160-312ms)
-- Education-only queries (83-257ms)
-- Common headline terms ONLY: engineer, CEO, manager, sales, developer, founder (51-161ms)
-
-**BANNED queries — use web search instead:**
-- ❌ Description/keyword search (ILIKE on description = 10s)
-- ❌ Jobs by role (LATERAL = 28s timeout)
-- ❌ 3+ table joins (1s-17s)
-- ❌ Skills queries (timeout)
-- ❌ Rare headline terms (timeout)
-- ❌ UNION ALL for multiple companies (14.6s)
-- ❌ company_name ILIKE (813ms-11.7s)
-
-**Example ALLOWED queries:**
-- "Find employees at Stripe" (company_id lookup)
-- "Companies with Series A funding" (2-table join)
-
-**Example BANNED queries — use web search:**
+**Acceptable uses of LinkedIn B2B DB:**
+- Look up a specific company by its domain, slug, or ID (you already have the identifier)
+- List employees at a single company you already identified (you have the company_id)
+- Check funding history for a specific company you already identified
+- **Trivially simple prospecting** on a single indexed column: e.g. `WHERE industry_code = 4 AND country_code = 'US' LIMIT 50` — no keywords, no ILIKE, no descriptions, no names
+
+**The test: can your query be expressed with ONLY indexed equality/range filters on 1-2 columns?** If yes, LinkedIn DB is OK. If you need keywords, descriptions, ILIKE on names, skills, fuzzy matching, or anything semantic — **use web search**.
+
+**❌ BANNED for prospecting (use web search):**
+- ❌ Any query with keywords or descriptions ("AI CRM", "fintech", "climate tech")
+- ❌ Any query with ILIKE on names, headlines, or titles
+- ❌ Any query requiring skills matching
+- ❌ Any query with 3+ table joins
+- ❌ Any query where you're "searching" rather than "filtering by a code"
+- ❌ "Find Series A startups" → Crunchbase
+- ❌ "Find VPs at fintech companies" → web search
+
+**✅ ALLOWED for prospecting (trivially simple):**
+- "US software companies" → `WHERE industry_code = 4 AND country_code = 'US'`
+- "Companies with 100-500 employees in California" → `WHERE employee_count BETWEEN 100 AND 500 AND region = 'California'`
+
+**✅ ALLOWED (enrichment/lookup of known entities):**
+- "Get details on Stripe" (you have the domain `stripe.com`) → LinkedIn DB lookup
+- "List engineers at Stripe" (you have company_id `2135371`) → LinkedIn DB employees query
+- "What's this person's headline?" (you have their LinkedIn slug) → LinkedIn DB lookup
+
+**❌ BANNED (discovery) — use web search:**
 - "AI CRM companies" → `services.web.search("site:linkedin.com/company AI CRM")`
 - "Kubernetes engineers" → `services.web.search("site:linkedin.com/in kubernetes engineer")`
 - "VPs who worked at Google" → `services.web.search("site:linkedin.com/in VP Google")`
 - "Companies hiring Account Executives" → `services.web.search("site:linkedin.com/jobs Account Executive")`
+- "1000 software engineers in Bay Area" → batched `services.web.search` queries
+- "Healthcare companies that do X" → `services.web.search("site:linkedin.com/company healthcare X")`
 
 ## Fast but Requires Verification
 
@@ -215,7 +228,8 @@ await sheet.addRows(
 🚨 WEB SEARCH REQUIRES VERIFICATION 🚨
 When using web search to find companies or people, you MUST add:
 1. An enrichment column (LinkedIn enrich or scrape)
-2. A verification column (AI check: "Does this actually match the criteria?")
+2. SPECIFICALLY AI verification columns (AI check: "Does this actually match the criteria?")
+3. You must use AI for verification
 NEVER deliver web search results without verification columns. Web search produces false positives.
 
 ````
@@ -239,56 +253,52 @@ type search = (params: {
 }>;
 ```
 
-## Create Useful Views After Prospecting
-
-Once a prospecting workflow is set up, **always create a few views**. Views show up as colored tabs in the sheet bar so switching is instant.
+## Sort Prospects by Fit
 
-Use `ctx.sql()` with `CREATE VIEW ... ON ... AS SELECT ...`.
-
-**Prefer sorted views over filtered views.** A sorted view keeps ALL rows visible but groups the best ones at the top — the user sees qualified leads first and can scroll to see the rest. Filtered views hide rows, making it hard to judge how much work went into finding the qualified ones.
+After prospecting, sort the sheet so the best-fit prospects are at the top. Use `SET FILTERS` to apply a sort immediately:
 
 ```ts
-// Sorted view — qualified at top, rest below (preferred)
-await ctx.sql(
-   `CREATE VIEW "Best First" ON "Companies" AS SELECT * FROM "Companies" ORDER BY "Qualified" DESC, "Score" DESC`
-);
+await ctx.sql(`SET FILTERS ON "Companies" ORDER BY "Score" DESC`);
+```
 
-// Sorted by score
-await ctx.sql(`CREATE VIEW "By Score" ON "Companies" AS SELECT * FROM "Companies" ORDER BY "Score" DESC`);
+**Sort > filter.** Sorting keeps all rows visible so the user can see how many prospects were disqualified — this makes the work visible. Filtering hides rows and makes it look like nothing happened.
 
-// Grouped by category
-await ctx.sql(`CREATE VIEW "By Industry" ON "Companies" AS SELECT * FROM "Companies" ORDER BY "Industry" ASC`);
+Boolean columns work too — `true` sorts after `false` with DESC: `ORDER BY "Qualified" DESC, "In ICP" DESC NULLS LAST`
 
-// Only use WHERE filters for hard exclusions
-await ctx.sql(`CREATE VIEW "Errors Only" ON "Companies" AS SELECT * FROM "Companies" WHERE "Status" = 'failed'`);
-```
+Optionally create a saved view if the user would benefit from toggling between perspectives:
 
-Don't overthink it — just create 2-3 views that match the columns you built. Skip only if there's genuinely nothing to sort/group on.
+```ts
+await ctx.sql(`CREATE VIEW "Best First" ON "Companies" AS SELECT * FROM "Companies" ORDER BY "Score" DESC`);
+```
 
 ## Examples
 
-| User Request                                 | Approach         | Why                                                                         |
-| -------------------------------------------- | ---------------- | --------------------------------------------------------------------------- |
-| "AI CRM companies"                           | Web search       | Keyword query → `"AI CRM" site:linkedin.com/company`                        |
-| "Fintech startups"                           | Web search       | Fuzzy/descriptive → `"fintech" "startup" site:linkedin.com/company`         |
-| "SDRs at Series A companies"                 | Web search       | Specific criteria → `"SDR" "Series A" site:linkedin.com/in`                 |
-| "Series A/B companies raised last year"      | Crunchbase       | Funding-specific discovery is best handled via `services.crunchbase.search` |
-| "Companies using Kubernetes"                 | Web search       | Technology match → `"Kubernetes" site:linkedin.com/company`                 |
-| "VPs who worked at Google"                   | Web search       | Fuzzy history match → `"VP" "Google" site:linkedin.com/in`                  |
-| "1000 software engineers in Bay Area"        | B2B DB           | Simple title + location + high volume                                       |
-| "All healthcare companies 100-500 employees" | B2B DB           | Industry + size + high volume                                               |
-| "Fast food chains that..."                   | Directory scrape | Scrape Wikipedia list → `browser.execute`                                   |
-| "Restaurants in Austin"                      | Google Maps      | Local/SMB with physical presence                                            |
-| "Companies hiring SDRs"                      | LinkedIn Jobs    | Job search with title filter                                                |
-| "Warehouses implementing WMS"                | Circle + columns | Pull logistics companies → add "WMS Score" column                           |
-| "Companies that recently switched CRMs"      | Circle + columns | Pull SaaS companies → add "CRM Change Signals" column                       |
+| User Request                                     | Approach         | Why                                                                                                     |
+| ------------------------------------------------ | ---------------- | ------------------------------------------------------------------------------------------------------- |
+| "AI CRM companies"                               | Web search       | Keyword query → `"AI CRM" site:linkedin.com/company`                                                    |
+| "Fintech startups"                               | Web search       | Fuzzy/descriptive → `"fintech" "startup" site:linkedin.com/company`                                     |
+| "SDRs at Series A companies"                     | Web search       | Specific criteria → `"SDR" "Series A" site:linkedin.com/in`                                             |
+| "Series A/B companies raised last year"          | Crunchbase       | Funding-specific discovery is best handled via `services.crunchbase.search`                             |
+| "Companies using Kubernetes"                     | Web search       | Technology match → `"Kubernetes" site:linkedin.com/company`                                             |
+| "VPs who worked at Google"                       | Web search       | Fuzzy history match → `"VP" "Google" site:linkedin.com/in`                                              |
+| "Companies like Stripe and Brex"                 | Ocean.io         | Lookalike search with seed domains → `ocean.search.companies`                                           |
+| "Find VPs at companies similar to our customers" | Ocean.io         | Lookalike companies + people filters → `ocean.search.people`                                            |
+| "1000 software engineers in Bay Area"            | Web search       | Batched `site:linkedin.com/in "software engineer" "Bay Area"` queries                                   |
+| "US software companies with 100-500 people"      | B2B DB           | Trivially simple: `industry_code = 4 AND employee_count BETWEEN 100 AND 500` — no keywords/ILIKE needed |
+| "Healthcare companies that use AI"               | Web search       | Has keywords ("AI") → `site:linkedin.com/company "healthcare" "AI"` + enrich                            |
+| "Fast food chains that..."                       | Directory scrape | Scrape Wikipedia list → `browser.execute`                                                               |
+| "Restaurants in Austin"                          | Google Maps      | Local/SMB with physical presence                                                                        |
+| "Companies hiring SDRs"                          | LinkedIn Jobs    | Job search with title filter                                                                            |
+| "Warehouses implementing WMS"                    | Circle + columns | Pull logistics companies → add "WMS Score" column                                                       |
+| "Companies that recently switched CRMs"          | Circle + columns | Pull SaaS companies → add "CRM Change Signals" column                                                   |
 
 ---
 
 ## Tools
 
-- **LinkedIn:** `services.company.linkedin.search({ sql: "SELECT ... FROM linkedin_company ..." })`, `services.person.linkedin.search({ sql: "SELECT ... FROM linkedin_profile ..." })` — **Lookup tool only, 3s max, 2-table joins max. Use web search for anything else.**
+- **LinkedIn DB (LOOKUP + trivially simple filters ONLY):** `services.company.linkedin.search(...)`, `services.person.linkedin.search(...)` — **Primarily for enrichment/lookup. Only use for prospecting when the query is a trivially simple indexed-column filter (e.g. industry_code, country_code). Any keywords, ILIKE, descriptions, names, skills = web search.**
 - **Funding:** `services.crunchbase.search({ sql: "SELECT ... FROM ... WHERE ..." })` — **Default for funding search and screening.**
+- **Lookalike:** `services.ocean.search.companies`, `services.ocean.search.people` — **Default for "find companies like X".** See [Lookalike Search Guide](../lookalike-search/).
 - **Local/SMB:** `googleMaps.scrape`
 - **Web:** `web.search` + `browser.execute`
 - **Platforms:** `services.apify.runActor`

package/docs/prospecting/linkedin_data/QUICK_REF.md

@@ -5,7 +5,9 @@ description: Critical rules and query methodology for LinkedIn B2B database. Man
 
 # B2B SQL Reference
 
-> **The LinkedIn DB is a lookup tool, not a search engine.** Only fast indexed queries are allowed (under 3 seconds, max 2-table joins). Everything else falls back to `services.web.search` with `site:linkedin.com` patterns. **You MUST read `services/web/search` before using web search.**
+> **🚫 BEFORE YOU QUERY: Is this for prospecting/discovery?** This database is almost never the right tool for finding new leads. It is primarily for lookups and enrichment of entities you already have identifiers for. The only prospecting exception is **trivially simple queries on single indexed columns** (e.g. `industry_code = 4 AND country_code = 'US'`). Any query with keywords, descriptions, ILIKE on names, skills, or semantic matching → use `services.web.search` with `site:linkedin.com` instead.
+
+> Only fast indexed queries are allowed (under 3 seconds, max 2-table joins). Everything else falls back to `services.web.search` with `site:linkedin.com` patterns. **You MUST read `services/web/search` before using web search.**
 
 ---
 

package/docs/prospecting/linkedin_data/index.md

@@ -1,37 +1,58 @@
 ---
 name: linkedin_data
-description: LinkedIn B2B database — LOOKUP TOOL ONLY. Fast indexed queries under 3s. Everything else uses web search.
+description: LinkedIn B2B database — LOOKUP & ENRICHMENT TOOL. Almost never for prospecting. Only trivially simple indexed-column filters are acceptable for discovery.
 ---
 
 # LinkedIn B2B Database
 
-> **The LinkedIn DB is a lookup tool, not a search engine.** Only fast indexed queries are allowed (under 3 seconds, max 2-table joins). Everything else falls back to `services.web.search` with `site:linkedin.com` patterns. **You MUST read `services/web/search` before using web search.**
+> **🚫 This database is almost never the right choice for prospecting/discovery.** It is primarily a lookup & enrichment tool for entities you already have identifiers for. The only prospecting exception is **trivially simple queries on single indexed columns** (e.g. `industry_code = 4 AND country_code = 'US'`).
+>
+> **Before querying this database, ask yourself:** "Am I searching/discovering, or am I looking up something I already have an ID for?" If searching → use `services.web.search`. If looking up → proceed.
+
+---
+
+## When to Use This Database
+
+| Use Case                         | Example                                                    | OK?                                            |
+| -------------------------------- | ---------------------------------------------------------- | ---------------------------------------------- |
+| **Lookup by known identifier**   | Company by domain/slug/ID, person by LinkedIn URL          | ✅ Always OK                                   |
+| **Employees at a known company** | People at Stripe by company_id                             | ✅ Always OK                                   |
+| **Trivially simple prospecting** | `WHERE industry_code = 4 AND country_code = 'US' LIMIT 50` | ✅ OK — no keywords, no ILIKE, no descriptions |
+| **Keyword/description search**   | "AI CRM companies", "fintech startups"                     | ❌ Use web search                              |
+| **Any ILIKE on names/headlines** | `headline ILIKE '%kubernetes%'`                            | ❌ Use web search                              |
+| **Skills, rare terms, fuzzy**    | "python engineers", "climate tech"                         | ❌ Use web search                              |
+| **Multi-criteria discovery**     | Industry + funding + keywords                              | ❌ Use web search + Crunchbase                 |
+
+**The test:** Can your query be expressed with ONLY indexed equality/range filters (industry_code, country_code, company_size_code, employee_count, region)? If yes, LinkedIn DB is acceptable. If you need ANY keywords, descriptions, ILIKE, skills, or semantic matching — **use web search**.
 
 ---
 
 ## What This Database CAN Do (Under 3s)
 
-| Query Type                 | Example                                           |
-| -------------------------- | ------------------------------------------------- |
-| Company by domain/slug/ID  | Find Stripe by `stripe.com`                       |
-| Employees at known company | People at Stripe by company_id                    |
-| Basic funding (2-table)    | Series A companies                                |
-| Jobs at ONE company        | Open roles at Stripe                              |
-| Person by LinkedIn URL     | Find person by slug                               |
-| Certifications             | AWS certified people                              |
-| Education-only             | Stanford graduates                                |
-| Headline (6 common terms)  | engineer, CEO, manager, sales, developer, founder |
+| Query Type                           | Example                                           |
+| ------------------------------------ | ------------------------------------------------- |
+| Company by domain/slug/ID            | Find Stripe by `stripe.com`                       |
+| Employees at known company           | People at Stripe by company_id                    |
+| Simple indexed-column company filter | `industry_code = 4 AND country_code = 'US'`       |
+| Basic funding (2-table)              | Funding history for a known company               |
+| Jobs at ONE company                  | Open roles at Stripe                              |
+| Person by LinkedIn URL               | Find person by slug                               |
+| Certifications                       | AWS certified people                              |
+| Education-only                       | Stanford graduates                                |
+| Headline (6 common terms ONLY)       | engineer, CEO, manager, sales, developer, founder |
 
 ## What This Database CANNOT Do (Use Web Search)
 
 | Query Type                      | Web Search Alternative                     |
 | ------------------------------- | ------------------------------------------ |
 | Company by keywords/description | `site:linkedin.com/company [keywords]`     |
+| Any ILIKE on names/headlines    | `site:linkedin.com/in [keywords]`          |
 | Jobs by role across companies   | `site:linkedin.com/jobs [role] [location]` |
 | People by rare headline terms   | `site:linkedin.com/in [keywords]`          |
 | People by skills                | `site:linkedin.com/in [skill]`             |
 | 3+ table joins                  | Decompose into 2-table queries             |
 | Complex alumni (ex-X now-Y)     | Two separate queries                       |
+| Any fuzzy/semantic matching     | Web search with relevant keywords          |
 
 ---
 

package/docs/services/builtWith/index.md

@@ -7,11 +7,11 @@ description: Technographic data enrichment — discover what technologies, frame
 
 ## Available Methods
 
-| Method          | Description                            | Credits                      |
-| --------------- | -------------------------------------- | ---------------------------- |
-| `lookupDomain`  | Get full technology stack for a domain | 1                            |
-| `relationships` | Find related/connected domains         | 1                            |
-| `searchByTech`  | Find companies using a specific tech   | 1/result (up to 900/page)    |
+| Method          | Description                            | Credits |
+| --------------- | -------------------------------------- | ------- |
+| `lookupDomain`  | Get full technology stack for a domain | 75      |
+| `relationships` | Find related/connected domains         | 75      |
+| `searchByTech`  | Find companies using a specific tech   | 100     |
 
 ## Use Cases
 
@@ -31,7 +31,7 @@ description: Technographic data enrichment — discover what technologies, frame
 
 - **Case-sensitive**: Use "Hubspot" not "HubSpot"
 - **Find exact names**: Use `lookupDomain` on a site to see correct tech names
-- **Pagination**: Each page returns up to 900 results (= 900 credits per page). Use `offset` from previous response to get next page.
+- **Pagination**: Each page returns up to 900 results. Use `offset` from previous response to get next page. Each page costs 100 credits.
 
 ## Example Workflows
 

package/docs/services/builtWith/lookupDomain.ts

@@ -1,4 +1,4 @@
-/** Credits: 1 (standard). */
+/** Credits: 75 (standard). */
 
 /**
  * Get the full technology stack for a domain.

package/docs/services/builtWith/relationships.ts

@@ -1,4 +1,4 @@
-/** Credits: 1 (standard). */
+/** Credits: 75 (standard). */
 
 /**
  * Find domains related to a given domain.

package/docs/services/builtWith/searchByTech.ts

@@ -1,4 +1,4 @@
-/** Credits: 1 per result returned. Each page returns up to 900 results (= up to 900 credits per page). */
+/** Credits: 100 (standard). Charged per call regardless of result count. */
 
 /**
  * Find companies/domains that use a specific technology.

package/docs/services/company/getEmployeesFromLinkedin.md

@@ -39,17 +39,18 @@ Find employees at a company using database search (default) or web search.
 
 ## Input Parameters
 
-| Parameter         | Type                    | Required | Description                                                      |
-| ----------------- | ----------------------- | -------- | ---------------------------------------------------------------- |
-| `companySlug`     | `string`                | One of   | LinkedIn universal_name (e.g., "stripe")                         |
-| `linkedinUrl`     | `string`                | One of   | Full LinkedIn URL                                                |
-| `searchStrategy`  | `"database"` \| `"web"` | No       | Default: "database"                                              |
-| `titleVariations` | `string[]`              | For web  | Title keywords. **Required for web strategy. Max 3 variations.** |
-| `titleSqlFilter`  | `string`                | No       | Raw SQL for precise matching (database only)                     |
-| `limit`           | `number`                | No       | Max results (default: 25, max: 100)                              |
-| `usOnly`          | `boolean`               | No       | US-based only (default: true)                                    |
-| `minConnections`  | `number`                | No       | Min connections filter (default: 20)                             |
-| `offset`          | `number`                | No       | Pagination offset (database only)                                |
+| Parameter                 | Type                    | Required | Description                                                                                                                            |
+| ------------------------- | ----------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `companySlug`             | `string`                | One of   | LinkedIn universal_name (e.g., "stripe")                                                                                               |
+| `linkedinUrl`             | `string`                | One of   | Full LinkedIn URL                                                                                                                      |
+| `searchStrategy`          | `"database"` \| `"web"` | No       | Default: "database"                                                                                                                    |
+| `titleVariations`         | `string[]`              | For web  | Title keywords. **Required for web strategy. Max 3 variations.**                                                                       |
+| `titleSqlFilter`          | `string`                | No       | Raw SQL for precise matching (database only)                                                                                           |
+| `limit`                   | `number`                | No       | Max results (default: 25, max: 100)                                                                                                    |
+| `usOnly`                  | `boolean`               | No       | US-based only (default: true)                                                                                                          |
+| `minConnections`          | `number`                | No       | Min connections filter (default: 20)                                                                                                   |
+| `offset`                  | `number`                | No       | Pagination offset (database only)                                                                                                      |
+| `requireVerifiedPosition` | `boolean`               | No       | Web only. When true (default), only returns employees with a verified B2B database position. Set false to include unverified profiles. |
 
 **Critical:** Provide `companySlug` OR `linkedinUrl`, not both. Website/domain input is NOT supported.
 
@@ -87,6 +88,7 @@ Pattern for other functions: replace `Engineering` with `Sales`, `Marketing`, `P
 
 ```typescript
 // Web strategy for C-Suite only (max 3 variations!)
+// By default, only returns employees with a verified B2B database position
 const { employees } = await services.company.getEmployeesFromLinkedin({
    linkedinUrl: row.linkedinCompanyUrl,
    searchStrategy: "web",
@@ -95,7 +97,19 @@ const { employees } = await services.company.getEmployeesFromLinkedin({
 });
 ```
 
-**Note:** Web strategy accepts a maximum of 3 title variations. Keep them focused on the core title variants.
+To include unverified profiles (found via Google but not confirmed in B2B database):
+
+```typescript
+const { employees } = await services.company.getEmployeesFromLinkedin({
+   linkedinUrl: row.linkedinCompanyUrl,
+   searchStrategy: "web",
+   titleVariations: ["CEO", "founder", "co-founder"],
+   requireVerifiedPosition: false, // Allow unverified profiles
+   limit: 10
+});
+```
+
+**Note:** Web strategy accepts a maximum of 3 title variations. Keep them focused on the core title variants. When `requireVerifiedPosition` is true (default), the company must exist in the B2B database or an error is thrown.
 
 ---
 

package/docs/services/company/linkedin/enrich.md

@@ -57,6 +57,8 @@ interface B2BCompany {
 }
 ```
 
+> Note: company industry coverage in the LinkedIn B2B DB can be sparse. `industry` and `industries` may be `null`, generic, or missing even when the company record exists, so do not rely on them as the only company classification signal.
+
 ### Extended (`extended: true`) - `B2BCompanyExtended`
 
 Full data from `lkd_company` + `company` tables. Includes everything from `B2BCompany` plus:

package/docs/services/company/linkedin/search.md

@@ -1,12 +1,14 @@
 ---
-description: Search LinkedIn B2B database for companies by domain, slug, or ID lookup
+description: Search LinkedIn B2B database for companies by domain, slug, or ID lookup. NOT for prospecting — use web search for discovery.
 ---
 
 # Company LinkedIn Search
 
 **Credits: 1/result (per-result). Reserves based on query `LIMIT`.**
 
-> **The LinkedIn DB is a lookup tool, not a search engine.** Only fast indexed queries are allowed (under 3 seconds, max 2-table joins). Everything else falls back to `services.web.search` with `site:linkedin.com/company` patterns. **You MUST read `services/web/search` before using web search.**
+> **🚫 PROSPECTING CHECK:** Are you using this to **discover new companies**? This service is almost never the right choice for prospecting. Use `services.web.search` with `site:linkedin.com/company` patterns for discovery. The only prospecting exception is **trivially simple indexed-column filters** (e.g. `industry_code = 4 AND country_code = 'US'`). Any query with keywords, descriptions, company names, ILIKE, or semantic matching = web search.
+
+> Only fast indexed queries are allowed (under 3 seconds, max 2-table joins). Everything else falls back to `services.web.search`. **You MUST read `services/web/search` before using web search.**
 
 > **IMPORTANT:** These tables (`linkedin_company`, `linkedin_crunchbase_funding`, etc.) are in an **EXTERNAL B2B database** -- NOT accessible via `ctx.sql()`.
 >

package/docs/services/company/revenue.md

@@ -0,0 +1,74 @@
+# Get Company Revenue
+
+Get company revenue, employee count, and firmographic data from a company domain.
+
+**Credits: 2 (standard). Charged only if a valid result is returned.**
+
+## Input Parameters
+
+| Parameter | Type     | Required | Description                                                               |
+| --------- | -------- | -------- | ------------------------------------------------------------------------- |
+| `domain`  | `string` | Yes      | Company website domain (e.g., `stripe.com`, `https://www.salesforce.com`) |
+
+Accepts any format: bare domain (`stripe.com`), with www (`www.stripe.com`), or full URL (`https://www.stripe.com/about`). The domain is automatically normalized.
+
+## Output
+
+```typescript
+{
+   revenue: number | null; // USD (e.g., 5100000000 for $5.1B). Ranges averaged.
+   employees: number | null; // Count (e.g., 750 for "501-1,000"). Ranges averaged.
+   headquarters: string | null; // e.g., "San Francisco, California, United States"
+   industry: string | null; // e.g., "Business Intelligence (BI) Software, Software"
+   website: string | null; // e.g., "www.stripe.com"
+   funding: number | null; // USD (e.g., 8700000000 for $8.7B)
+   description: string | null; // Company description paragraph
+   sourceUrl: string | null; // The data source URL
+}
+```
+
+## Examples
+
+### Basic Revenue Lookup
+
+```typescript
+const companyData = await services.company.revenue({
+   domain: row.domain
+});
+return companyData.revenue; // 5100000000
+```
+
+### Extract Multiple Fields
+
+```typescript
+const companyData = await services.company.revenue({
+   domain: row.website
+});
+return {
+   revenue: companyData.revenue,
+   employees: companyData.employees,
+   industry: companyData.industry,
+   hq: companyData.headquarters
+};
+```
+
+### Filter by Revenue Size
+
+```typescript
+const companyData = await services.company.revenue({
+   domain: row.domain
+});
+if (companyData.revenue && companyData.revenue > 1_000_000_000) {
+   return "Enterprise";
+} else if (companyData.revenue && companyData.revenue > 100_000_000) {
+   return "Mid-Market";
+}
+return "SMB";
+```
+
+## Key Rules
+
+1. **Domain input only** — pass the company's website domain. URLs, bare domains, and www-prefixed domains all work.
+2. **Numbers are parsed** — revenue, employees, and funding are returned as numbers (not formatted strings). Ranges are averaged.
+3. **All fields nullable** — if the data source doesn't list a field (e.g., funding for a bootstrapped company), it returns `null`.
+4. **Handles normalization** — `https://www.stripe.com/about`, `www.stripe.com`, and `stripe.com` all resolve to the same company.

package/docs/services/googleMaps/scrape.ts

@@ -1,4 +1,4 @@
-/** Credits: 1/result (per-result). Reserves up to `limit` or `maxCrawledPlacesPerSearch` (default 100). Settles actual count. */
+/** Credits: 10/result (per-result). Reserves up to `limit` or `maxCrawledPlacesPerSearch` (default 100). Settles actual count. */
 
 interface GoogleMapsScraperInput {
    /** Array of search terms to find places (e.g., ['grocery store', 'pizza restaurant']) */