orangeslice 2.2.0 → 2.3.1-beta.0

package/README.md

@@ -52,6 +52,21 @@ pnpm add orangeslice
 yarn add orangeslice
 ```
 
+## Integrations & Skills
+
+```ts
+import { integrations, skills } from "orangeslice";
+
+// Connect a third-party service (opens browser for OAuth)
+const hubspot = await integrations.connect("hubspot");
+
+// List connected integrations
+const { integrations: list } = await integrations.list();
+
+// Create a knowledge skill
+await skills.create({ name: "ICP", content: "B2B SaaS, 50-500 employees..." });
+```
+
 ## Public API (services-first)
 
 Use `services.*` as the primary API surface.
@@ -103,6 +118,8 @@ const startups = await services.crunchbase.search({
 - `services.googleMaps.scrape`
 - `services.geo.parseAddress`
 - `services.builtWith.lookupDomain/relationships/searchByTech`
+- `integrations.connect/list/get/create/update/delete`
+- `skills.list/get/create/update/delete`
 
 ## How routing works today
 

package/dist/cli.js

@@ -179,6 +179,7 @@ Use these docs as the source of truth. If there is any conflict between your pri
 ## Package Setup (Do Not Guess)
 - Import from the package name, not a local file path:
   - \`import { services } from "orangeslice"\`
+  - \`import { integrations, skills } from "orangeslice"\` for integration and skill management
   - \`import { configure, services } from "orangeslice"\` when setting API key programmatically
 - Do NOT use \`import { services } from "./orangeslice"\` unless the user explicitly has a local wrapper file at that path.
 - The orangeslice bootstrap commands (\`npx orangeslice\`, \`bunx orangeslice\`, \`pnpm dlx orangeslice\`, \`yarn dlx orangeslice\`) sync docs, install the package, and handle auth. They do NOT execute user app scripts.
@@ -192,7 +193,9 @@ Use these docs as the source of truth. If there is any conflict between your pri
 ## Mandatory Read Order (Before writing code)
 1. \`./services/index.md\` - service map and capabilities
 2. Relevant docs under \`./services/**\` for every service you plan to call
-3. \`./prospecting/index.md\` when doing discovery or lead generation tasks
+3. \`./services/integrations/index.md\` when connecting or managing third-party integrations
+4. \`./services/skills/index.md\` when managing knowledge skills
+5. \`./prospecting/index.md\` when doing discovery or lead generation tasks
 
 Do not call a service before reading its documentation.
 
@@ -203,6 +206,12 @@ Do not call a service before reading its documentation.
 - For broad scraping by URL, use \`services.scrape.website\`.
 - Use \`services.ai.generateObject\` for structured extraction/classification with a JSON schema.
 
+## Integration & Skill Management
+- To connect a third-party service, use \`integrations.connect(provider)\`. This opens the browser for OAuth (HubSpot, Salesforce, Attio, Gmail, Slack) or prompts for an API key (Instantly, HeyReach).
+- To list connected integrations, use \`integrations.list()\`.
+- To manage knowledge skills (ICP descriptions, templates, etc.), use \`skills.create/list/update/delete\`.
+- Read \`./services/integrations/index.md\` and \`./services/skills/index.md\` for full API details.
+
 ## Execution Rules
 - Parallelize independent async calls with \`Promise.all\`.
 - Avoid serial \`await\` inside loops when calls can run concurrently.
@@ -246,6 +255,8 @@ This project includes orangeslice for B2B sales operations, lead generation, enr
 - Structured AI generation
 - Website scraping and browser execution
 - PredictLeads and BuiltWith-backed discovery
+- Integration management — connect HubSpot, Salesforce, Attio, Gmail, Slack, Instantly, HeyReach via \`integrations.connect(provider)\`
+- Knowledge skills — create and manage reusable knowledge snippets via \`skills.create/list/update/delete\`
 `;
     fs.writeFileSync(CLAUDE_GUIDE_FILE, content, "utf8");
 }

package/dist/index.d.ts

@@ -1,5 +1,9 @@
 export { configure } from "./api";
 export type { OrangesliceConfig } from "./api";
+export { integrations } from "./integrations";
+export type { Integration, IntegrationProvider, IntegrationListParams, IntegrationCreateParams, IntegrationUpdateParams, IntegrationConnectOptions } from "./integrations";
+export { skills } from "./skills";
+export type { Skill, SkillListParams, SkillCreateParams, SkillUpdateParams } from "./skills";
 export { findCareersPage, scrapeCareersPage } from "./careers";
 export type { FindCareersPageParams, FindCareersPageResult, ScrapeCareersPageParams, ScrapeCareersPageResult, ScrapeCareersPageJob } from "./careers";
 export { ctx } from "./ctx";
@@ -95,5 +99,28 @@ export declare const services: {
         searchByTech: typeof builtWithSearchByTech;
     };
     predictLeads: Readonly<import("./predictLeads").PredictLeadsServiceMap>;
+    integrations: {
+        connect: (provider: import("./integrations").IntegrationProvider, opts?: import("./integrations").IntegrationConnectOptions) => Promise<import("./integrations").Integration>;
+        list: (opts?: import("./integrations").IntegrationListParams) => Promise<{
+            integrations: import("./integrations").Integration[];
+        }>;
+        get: (id: string) => Promise<import("./integrations").Integration>;
+        create: (opts: import("./integrations").IntegrationCreateParams) => Promise<import("./integrations").Integration>;
+        update: (id: string, fields: import("./integrations").IntegrationUpdateParams) => Promise<import("./integrations").Integration>;
+        delete: (id: string) => Promise<{
+            success: boolean;
+        }>;
+    };
+    skills: {
+        list: (opts?: import("./skills").SkillListParams) => Promise<{
+            skills: import("./skills").Skill[];
+        }>;
+        get: (id: string) => Promise<import("./skills").Skill>;
+        create: (opts: import("./skills").SkillCreateParams) => Promise<import("./skills").Skill>;
+        update: (id: string, fields: import("./skills").SkillUpdateParams) => Promise<import("./skills").Skill>;
+        delete: (id: string) => Promise<{
+            success: boolean;
+        }>;
+    };
 };
 export default services;

package/dist/index.js

@@ -1,8 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.services = exports.builtWithSearchByTech = exports.builtWithRelationships = exports.builtWithLookupDomain = exports.geoParseAddress = exports.companyGetEmployeesFromLinkedin = exports.companyLinkedinFindUrl = exports.companyLinkedinEnrich = exports.personContactGet = exports.personLinkedinFindUrl = exports.personLinkedinEnrich = exports.PREDICT_LEADS_OPERATION_IDS = exports.predictLeads = exports.executePredictLeads = exports.googleMapsScrape = exports.runApifyActor = exports.browserExecute = exports.scrapeWebsite = exports.generateObject = exports.webBatchSearch = exports.webSearch = exports.OCEAN_OPERATION_IDS = exports.oceanSearchPeople = exports.oceanSearchCompanies = exports.executeOcean = exports.crunchbaseSearch = exports.linkedinSearch = exports.ctx = exports.scrapeCareersPage = exports.findCareersPage = exports.configure = void 0;
+exports.services = exports.builtWithSearchByTech = exports.builtWithRelationships = exports.builtWithLookupDomain = exports.geoParseAddress = exports.companyGetEmployeesFromLinkedin = exports.companyLinkedinFindUrl = exports.companyLinkedinEnrich = exports.personContactGet = exports.personLinkedinFindUrl = exports.personLinkedinEnrich = exports.PREDICT_LEADS_OPERATION_IDS = exports.predictLeads = exports.executePredictLeads = exports.googleMapsScrape = exports.runApifyActor = exports.browserExecute = exports.scrapeWebsite = exports.generateObject = exports.webBatchSearch = exports.webSearch = exports.OCEAN_OPERATION_IDS = exports.oceanSearchPeople = exports.oceanSearchCompanies = exports.executeOcean = exports.crunchbaseSearch = exports.linkedinSearch = exports.ctx = exports.scrapeCareersPage = exports.findCareersPage = exports.skills = exports.integrations = exports.configure = void 0;
 var api_1 = require("./api");
 Object.defineProperty(exports, "configure", { enumerable: true, get: function () { return api_1.configure; } });
+var integrations_1 = require("./integrations");
+Object.defineProperty(exports, "integrations", { enumerable: true, get: function () { return integrations_1.integrations; } });
+var skills_1 = require("./skills");
+Object.defineProperty(exports, "skills", { enumerable: true, get: function () { return skills_1.skills; } });
 var careers_1 = require("./careers");
 Object.defineProperty(exports, "findCareersPage", { enumerable: true, get: function () { return careers_1.findCareersPage; } });
 Object.defineProperty(exports, "scrapeCareersPage", { enumerable: true, get: function () { return careers_1.scrapeCareersPage; } });
@@ -50,6 +54,8 @@ const b2b_2 = require("./b2b");
 const browser_2 = require("./browser");
 const careers_2 = require("./careers");
 const crunchbase_2 = require("./crunchbase");
+const integrations_2 = require("./integrations");
+const skills_2 = require("./skills");
 const expansion_2 = require("./expansion");
 const firecrawl_2 = require("./firecrawl");
 const generateObject_2 = require("./generateObject");
@@ -114,6 +120,8 @@ exports.services = {
         relationships: expansion_2.builtWithRelationships,
         searchByTech: expansion_2.builtWithSearchByTech
     },
-    predictLeads: predictLeads_2.predictLeads
+    predictLeads: predictLeads_2.predictLeads,
+    integrations: integrations_2.integrations,
+    skills: skills_2.skills
 };
 exports.default = exports.services;

package/dist/integrations.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Integrations API for the orangeslice SDK.
+ *
+ * Usage:
+ *   import { integrations } from "orangeslice";
+ *
+ *   // Connect an OAuth provider (opens browser)
+ *   const hubspot = await integrations.connect("hubspot");
+ *
+ *   // List connected integrations
+ *   const { integrations: list } = await integrations.list();
+ *
+ *   // Programmatic API-key create (no browser)
+ *   await integrations.create({ provider: "instantly", apiKey: "inst_..." });
+ */
+export type IntegrationProvider = "hubspot" | "salesforce" | "attio" | "gmail" | "slack" | "instantly" | "heyreach";
+export interface Integration {
+    id: string;
+    provider: string;
+    displayName: string;
+    isActive: boolean;
+    hasApiKey: boolean;
+    hasOauthToken: boolean;
+    createdAt: string;
+    updatedAt: string;
+    scope: "account" | "spreadsheet";
+    spreadsheetId?: string | null;
+}
+export interface IntegrationListParams {
+    spreadsheetId?: string;
+    provider?: IntegrationProvider;
+}
+export interface IntegrationCreateParams {
+    provider: IntegrationProvider;
+    apiKey: string;
+    displayName?: string;
+    config?: Record<string, string>;
+    spreadsheetId?: string;
+}
+export interface IntegrationUpdateParams {
+    apiKey?: string;
+    displayName?: string;
+    isActive?: boolean;
+    config?: Record<string, string>;
+}
+export interface IntegrationConnectOptions {
+    noBrowser?: boolean;
+}
+export declare const integrations: {
+    connect: (provider: IntegrationProvider, opts?: IntegrationConnectOptions) => Promise<Integration>;
+    list: (opts?: IntegrationListParams) => Promise<{
+        integrations: Integration[];
+    }>;
+    get: (id: string) => Promise<Integration>;
+    create: (opts: IntegrationCreateParams) => Promise<Integration>;
+    update: (id: string, fields: IntegrationUpdateParams) => Promise<Integration>;
+    delete: (id: string) => Promise<{
+        success: boolean;
+    }>;
+};

package/dist/integrations.js

@@ -0,0 +1,106 @@
+"use strict";
+/**
+ * Integrations API for the orangeslice SDK.
+ *
+ * Usage:
+ *   import { integrations } from "orangeslice";
+ *
+ *   // Connect an OAuth provider (opens browser)
+ *   const hubspot = await integrations.connect("hubspot");
+ *
+ *   // List connected integrations
+ *   const { integrations: list } = await integrations.list();
+ *
+ *   // Programmatic API-key create (no browser)
+ *   await integrations.create({ provider: "instantly", apiKey: "inst_..." });
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.integrations = void 0;
+const api_1 = require("./api");
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const AUTH_BASE_URL = "https://www.orangeslice.ai";
+const CONNECT_POLL_TIMEOUT_MS = 600000;
+// ---------------------------------------------------------------------------
+// Browser helper (same as cli.ts)
+// ---------------------------------------------------------------------------
+function openBrowser(url) {
+    if (!process?.versions?.node) {
+        console.log(`  Open this URL in your browser:\n  ${url}\n`);
+        return;
+    }
+    try {
+        const { execFileSync } = require("child_process");
+        if (process.platform === "darwin") {
+            execFileSync("open", [url], { stdio: "ignore" });
+            return;
+        }
+        if (process.platform === "win32") {
+            execFileSync("cmd.exe", ["/c", "start", "", url], { stdio: "ignore" });
+            return;
+        }
+        execFileSync("xdg-open", [url], { stdio: "ignore" });
+    }
+    catch {
+        console.log(`  Open this URL in your browser:\n  ${url}\n`);
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+// ---------------------------------------------------------------------------
+// Connect (device flow via Next.js)
+// ---------------------------------------------------------------------------
+async function connectIntegration(provider, opts) {
+    const startRes = await fetch(`${AUTH_BASE_URL}/api/orangeslice/integrations/connect/start`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ provider })
+    });
+    if (!startRes.ok) {
+        const data = (await startRes.json().catch(() => ({})));
+        throw new Error(`[orangeslice] integrations.connect: ${data.error || "Failed to start connect flow"}`);
+    }
+    const start = (await startRes.json());
+    if (opts?.noBrowser) {
+        console.log(`  Open this URL to connect ${provider}:\n  ${start.verificationUrl}\n`);
+    }
+    else {
+        openBrowser(start.verificationUrl);
+        console.log(`  Browser opened. Complete ${provider} authorization there, then return here.\n`);
+    }
+    const timeoutAt = Date.now() + CONNECT_POLL_TIMEOUT_MS;
+    let pollInterval = start.pollIntervalMs > 0 ? start.pollIntervalMs : 1000;
+    while (Date.now() < timeoutAt) {
+        await sleep(pollInterval);
+        const pollRes = await fetch(`${AUTH_BASE_URL}/api/orangeslice/integrations/connect/poll?deviceCode=${encodeURIComponent(start.deviceCode)}`, { method: "GET", headers: { "Content-Type": "application/json" } });
+        const data = (await pollRes.json());
+        if (data.status === "pending")
+            continue;
+        if (data.status === "approved" && data.integration) {
+            return data.integration;
+        }
+        if (data.status === "expired") {
+            throw new Error(`[orangeslice] integrations.connect: Device code expired. Please try again.`);
+        }
+        if (data.status === "consumed") {
+            throw new Error(`[orangeslice] integrations.connect: Device code already used.`);
+        }
+        if (!pollRes.ok) {
+            throw new Error(`[orangeslice] integrations.connect: ${data.error || "Polling failed"}`);
+        }
+    }
+    throw new Error(`[orangeslice] integrations.connect: Timed out waiting for authorization.`);
+}
+// ---------------------------------------------------------------------------
+// CRUD (via batch-service)
+// ---------------------------------------------------------------------------
+exports.integrations = {
+    connect: (provider, opts) => connectIntegration(provider, opts),
+    list: (opts) => (0, api_1.post)("/ctx/integrations/list", (opts ?? {})),
+    get: (id) => (0, api_1.post)("/ctx/integrations/get", { id }),
+    create: (opts) => (0, api_1.post)("/ctx/integrations/create", opts),
+    update: (id, fields) => (0, api_1.post)("/ctx/integrations/update", { id, ...fields }),
+    delete: (id) => (0, api_1.post)("/ctx/integrations/delete", { id })
+};

package/dist/ocean.d.ts

@@ -5,14 +5,9 @@ export declare const OCEAN_OPERATION_IDS: {
 export type OceanOperationId = (typeof OCEAN_OPERATION_IDS)[keyof typeof OCEAN_OPERATION_IDS];
 export interface OceanCompaniesFilters {
     lookalikeDomains?: string[];
-    minScore?: number;
     companySizes?: Array<"0-1" | "2-10" | "11-50" | "51-200" | "201-500" | "501-1000" | "1001-5000" | "5001-10000" | "10001+">;
     countries?: string[];
     industries?: string[];
-    technologies?: string[];
-    technologyCategories?: string[];
-    keywords?: string[];
-    revenueRanges?: string[];
     ecommerce?: boolean;
 }
 export interface OceanPeopleFilters {
@@ -24,11 +19,9 @@ export interface OceanPeopleFilters {
 }
 export interface OceanCompaniesSearchParams {
     companiesFilters?: OceanCompaniesFilters;
+    peopleFilters?: OceanPeopleFilters;
     size?: number;
-    from?: number;
     searchAfter?: string;
-    includeDomains?: string[];
-    excludeDomains?: string[];
 }
 export interface OceanPhone {
     country?: string;
@@ -97,6 +90,7 @@ export interface OceanCompanyMatch {
     relevance?: string;
 }
 export interface OceanCompaniesSearchResponse {
+    detail?: string;
     total: number;
     searchAfter?: string;
     companies: OceanCompanyMatch[];

package/dist/skills.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Knowledge Skills API for the orangeslice SDK.
+ *
+ * Usage:
+ *   import { skills } from "orangeslice";
+ *
+ *   // Create a skill
+ *   const skill = await skills.create({
+ *     title: "CRM Mapping",
+ *     description: "Maps company fields to HubSpot properties",
+ *     content: "When pushing to HubSpot, map ...",
+ *   });
+ *
+ *   // List all skills
+ *   const { skills: list } = await skills.list();
+ *
+ *   // Update a skill
+ *   await skills.update(skill.id, { autoInject: true });
+ */
+export interface Skill {
+    id: string;
+    title: string;
+    description: string;
+    content: string;
+    autoInject: boolean;
+    createdAt: string;
+    updatedAt: string;
+    scope: "account" | "spreadsheet";
+    spreadsheetId?: string | null;
+}
+export interface SkillListParams {
+    spreadsheetId?: string;
+}
+export interface SkillCreateParams {
+    title: string;
+    description: string;
+    content: string;
+    autoInject?: boolean;
+    spreadsheetId?: string;
+}
+export interface SkillUpdateParams {
+    title?: string;
+    description?: string;
+    content?: string;
+    autoInject?: boolean;
+}
+export declare const skills: {
+    list: (opts?: SkillListParams) => Promise<{
+        skills: Skill[];
+    }>;
+    get: (id: string) => Promise<Skill>;
+    create: (opts: SkillCreateParams) => Promise<Skill>;
+    update: (id: string, fields: SkillUpdateParams) => Promise<Skill>;
+    delete: (id: string) => Promise<{
+        success: boolean;
+    }>;
+};

package/dist/skills.js

@@ -0,0 +1,33 @@
+"use strict";
+/**
+ * Knowledge Skills API for the orangeslice SDK.
+ *
+ * Usage:
+ *   import { skills } from "orangeslice";
+ *
+ *   // Create a skill
+ *   const skill = await skills.create({
+ *     title: "CRM Mapping",
+ *     description: "Maps company fields to HubSpot properties",
+ *     content: "When pushing to HubSpot, map ...",
+ *   });
+ *
+ *   // List all skills
+ *   const { skills: list } = await skills.list();
+ *
+ *   // Update a skill
+ *   await skills.update(skill.id, { autoInject: true });
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.skills = void 0;
+const api_1 = require("./api");
+// ---------------------------------------------------------------------------
+// CRUD (via batch-service)
+// ---------------------------------------------------------------------------
+exports.skills = {
+    list: (opts) => (0, api_1.post)("/ctx/skills/list", (opts ?? {})),
+    get: (id) => (0, api_1.post)("/ctx/skills/get", { id }),
+    create: (opts) => (0, api_1.post)("/ctx/skills/create", opts),
+    update: (id, fields) => (0, api_1.post)("/ctx/skills/update", { id, ...fields }),
+    delete: (id) => (0, api_1.post)("/ctx/skills/delete", { id })
+};

package/docs/lookalike-search/index.md

@@ -51,20 +51,32 @@ const results = await services.ocean.search.companies({
 
 **Key filters:**
 
-| Filter             | Example                          | Notes                                            |
-| ------------------ | -------------------------------- | ------------------------------------------------ |
-| `lookalikeDomains` | `["stripe.com", "plaid.com"]`    | Core input — seed domains to find lookalikes for |
-| `companySizes`     | `["51-200", "201-500"]`          | Filter by employee count range                   |
-| `countries`        | `["us", "gb", "de"]`             | Two-letter ISO country codes                     |
-| `industries`       | `["SaaS", "Fintech"]`            | Industry category names                          |
-| `technologies`     | `["React", "Salesforce"]`        | Filter by tech stack                             |
-| `revenueRanges`    | `["1M-10M", "10M-50M"]`          | Revenue band filter                              |
-| `keywords`         | `["payments", "infrastructure"]` | Keyword filter                                   |
-| `ecommerce`        | `true`                           | E-commerce companies only                        |
-| `minScore`         | `0.5`                            | Minimum similarity score (0–1)                   |
+| Filter             | Example                        | Notes                                                        |
+| ------------------ | ------------------------------ | ------------------------------------------------------------ |
+| `lookalikeDomains` | `["stripe.com", "plaid.com"]`  | Core input — seed domains to find lookalikes for             |
+| `companySizes`     | `["51-200", "201-500"]`        | Filter by employee count range                               |
+| `countries`        | `["us", "gb", "de"]`           | Two-letter ISO country codes                                 |
+| `industries`       | `["SaaS", "Fintech"]`          | Industry category names                                      |
+| `ecommerce`        | `true`                         | E-commerce companies only                                    |
+| `peopleFilters`    | `{ seniorities: ["C-Level"] }` | Top-level filter. Only return companies with matching people |
 
 **Pagination:** Use `searchAfter` from the previous response for efficient cursor-based pagination. Max `size` per request is 100.
 
+**Do not send these fields to `services.ocean.search.companies`:**
+
+- `excludeDomains`
+- `includeDomains`
+- `from`
+- `minScore`
+- `technologyCategories`
+- `revenueRanges`
+
+Ocean v3 rejects each of those with `422`.
+
+**Fields that are not safe as simple string arrays:** `technologies` and `keywords`.
+
+When sent as string arrays, Ocean v3 returns `422` with `Input should be a valid dictionary or object to extract fields from`. Until we document the exact upstream shape, do not have the agent generate them.
+
 ### 2. `services.ocean.search.people` — Find People at Companies
 
 Combine company filters with people filters to find the right contacts.
@@ -150,5 +162,5 @@ for (let page = 0; page < 5; page++) {
 
 - **More seed domains = better results.** 3-5 seeds produce much better lookalikes than a single domain.
 - **Combine with enrichment.** Ocean.io returns firmographic data, but you can enrich further with LinkedIn, BuiltWith, or PredictLeads.
-- **Use `minScore`** to control result quality — higher = more similar but fewer results.
+- **Exclude seed domains client-side.** Ocean v3 rejects `excludeDomains`, so filter out seed domains after the response if needed.
 - **Credits:** 5 credits per result. A search returning 50 companies = 250 credits. Reserve is based on the requested `size`.

package/docs/prospecting/index.md

@@ -87,7 +87,7 @@ When using qualification columns, think Circle & Star:
 | **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. |
+| **PredictLeads**         | Company intelligence, buying signals, and structured company events at scale | Coverage varies by company/market. Treat it as a prospecting/enrichment signal, not source-of-truth validation for whether a known company currently has an opening. |
 | **Niche Directory Scrape** | Well-defined categories with existing lists (see below)   | Requires finding the right directory first.              |
 | **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.            |
@@ -99,7 +99,7 @@ Use PredictLeads first when the user needs **high-quality structured company dat
 
 PredictLeads is usually the best choice for:
 - Tracking **company signals over time** (news, financing, hiring, tech detections, product changes, website evolution)
-- Pulling **normalized lists** (job openings, technologies, investors/connections, similar companies) without custom scraping
+- Pulling **normalized lists** (job openings, technologies, investors/connections, similar companies) for prospecting/enrichment without custom scraping
 - Building qualification columns where consistency matters more than recall
 - Workflows that need stable structured fields instead of parsing search snippets
 

package/docs/services/index.md

@@ -9,5 +9,7 @@
 - **email**: send transactional notification emails through Orange Slice's managed sender.
 - **scrape**: website scraper, sitemap scraper
 - **web**: SERP
-- **predictLeads**: company intelligence datasets (financing events, technologies, products, job openings, news, and related company data).
+- **predictLeads**: company intelligence datasets (financing events, technologies, products, job openings, news, and related company data). Use these as prospecting/enrichment signals, not source-of-truth validation for whether a known company is hiring right now.
+- **integrations**: connect and manage third-party integrations (HubSpot, Salesforce, Attio, Gmail, Slack, Instantly, HeyReach). Use `integrations.connect(provider)` to open the browser OAuth flow from a script, or `integrations.create(...)` for API-key providers.
+- **skills**: create and manage knowledge skills — reusable knowledge snippets (ICP, templates, product info) that guide AI agents.
 - **guides**: agent notes & operational docs (see [Error Handling Cheatsheet](../error-handling-cheatsheet.md))

package/docs/services/integrations/index.md

@@ -0,0 +1,128 @@
+---
+description: Connect and manage third-party integrations (HubSpot, Salesforce, Attio, Gmail, Slack, Instantly, HeyReach)
+---
+
+# integrations — Integration Management
+
+Connect, list, and manage third-party service integrations. Supports both OAuth providers (HubSpot, Salesforce, Attio, Gmail, Slack) and API-key providers (Instantly, HeyReach).
+
+## Quick start
+
+```typescript
+import { integrations } from "orangeslice";
+
+// Connect an OAuth provider (opens browser for authorization)
+const hubspot = await integrations.connect("hubspot");
+console.log(`Connected: ${hubspot.displayName}`);
+
+// List all connected integrations
+const { integrations: list } = await integrations.list();
+console.log(list.map(i => `${i.provider}: ${i.displayName}`));
+
+// Connect an API-key provider programmatically (no browser)
+await integrations.create({
+  provider: "instantly",
+  apiKey: "inst_abc123...",
+  displayName: "My Instantly"
+});
+```
+
+## Methods
+
+### `integrations.connect(provider, opts?)`
+
+Opens the user's browser to complete OAuth authorization (or API key entry for Instantly/HeyReach). Polls until the user finishes, then returns the connected integration.
+
+This is the recommended way to connect any integration from a script or agent.
+
+**Parameters:**
+- `provider` — One of: `"hubspot"`, `"salesforce"`, `"attio"`, `"gmail"`, `"slack"`, `"instantly"`, `"heyreach"`
+- `opts.noBrowser` — If `true`, prints the URL instead of auto-opening the browser
+
+**Returns:** `Integration` object
+
+```typescript
+const salesforce = await integrations.connect("salesforce");
+// Browser opens -> user authorizes -> returns when complete
+```
+
+### `integrations.list(opts?)`
+
+List connected integrations for the current account.
+
+**Parameters:**
+- `opts.spreadsheetId` — Filter to a specific spreadsheet's integrations
+- `opts.provider` — Filter by provider name
+
+**Returns:** `{ integrations: Integration[] }`
+
+```typescript
+const { integrations: all } = await integrations.list();
+const { integrations: crms } = await integrations.list({ provider: "hubspot" });
+```
+
+### `integrations.get(id)`
+
+Get a single integration by ID.
+
+**Returns:** `Integration`
+
+### `integrations.create(opts)`
+
+Programmatically create an API-key integration without opening a browser. Only works for API-key providers (`instantly`, `heyreach`). For OAuth providers, use `connect()` instead.
+
+**Parameters:**
+- `opts.provider` — `"instantly"` or `"heyreach"`
+- `opts.apiKey` — The provider API key
+- `opts.displayName` — Optional display name
+- `opts.config` — Optional key-value config
+- `opts.spreadsheetId` — Optional, scope to a specific spreadsheet
+
+**Returns:** `Integration`
+
+### `integrations.update(id, fields)`
+
+Update an existing integration.
+
+**Parameters:**
+- `fields.apiKey` — New API key
+- `fields.displayName` — New display name
+- `fields.isActive` — Enable/disable
+- `fields.config` — New config object
+
+**Returns:** `Integration`
+
+### `integrations.delete(id)`
+
+Delete an integration by ID.
+
+**Returns:** `{ success: boolean }`
+
+## Integration object
+
+```typescript
+{
+  id: string;
+  provider: string;        // "hubspot", "salesforce", etc.
+  displayName: string;     // "HubSpot portal acme.hubspot.com"
+  isActive: boolean;
+  hasApiKey: boolean;       // true if API key is set (key itself is never returned)
+  hasOauthToken: boolean;   // true if OAuth token is set
+  createdAt: string;
+  updatedAt: string;
+  scope: "account" | "spreadsheet";
+  spreadsheetId: string | null;
+}
+```
+
+## Supported providers
+
+| Provider    | Auth Type | Connect method         |
+| ----------- | --------- | ---------------------- |
+| HubSpot     | OAuth     | `connect("hubspot")`   |
+| Salesforce  | OAuth     | `connect("salesforce")`|
+| Attio       | OAuth     | `connect("attio")`     |
+| Gmail       | OAuth     | `connect("gmail")`     |
+| Slack       | OAuth     | `connect("slack")`     |
+| Instantly   | API Key   | `connect("instantly")` or `create(...)` |
+| HeyReach    | API Key   | `connect("heyreach")` or `create(...)`  |

package/docs/services/ocean/search/companies.ts

@@ -1,130 +1,133 @@
 interface OceanCompaniesFilters {
-  /** Array of domains to find lookalike companies for (e.g., ["stripe.com", "shopify.com"]) */
-  lookalikeDomains?: string[];
-  /** Minimum similarity score (0-1) for lookalike matching */
-  minScore?: number;
-  /** Company size ranges to filter by */
-  companySizes?: Array<"0-1" | "2-10" | "11-50" | "51-200" | "201-500" | "501-1000" | "1001-5000" | "5001-10000" | "10001+">;
-  /** Two-letter country codes to filter by (e.g., ["us", "gb"]) */
-  countries?: string[];
-  /** Industry categories to filter by */
-  industries?: string[];
-  /** Technology names to filter by (e.g., ["React", "Salesforce"]) */
-  technologies?: string[];
-  /** Technology category names to filter by */
-  technologyCategories?: string[];
-  /** Keywords to search for */
-  keywords?: string[];
-  /** Revenue ranges to filter by (e.g., ["0-1M", "1M-10M"]) */
-  revenueRanges?: string[];
-  /** Filter for e-commerce companies */
-  ecommerce?: boolean;
+   /** Array of domains to find lookalike companies for (e.g., ["stripe.com", "shopify.com"]) */
+   lookalikeDomains?: string[];
+   /** Company size ranges to filter by */
+   companySizes?: Array<
+      "0-1" | "2-10" | "11-50" | "51-200" | "201-500" | "501-1000" | "1001-5000" | "5001-10000" | "10001+"
+   >;
+   /** Two-letter country codes to filter by (e.g., ["us", "gb"]) */
+   countries?: string[];
+   /** Industry names to filter by */
+   industries?: string[];
+   /** Filter for e-commerce companies */
+   ecommerce?: boolean;
+}
+
+interface OceanPeopleFilters {
+   /** Seniority levels to filter by (e.g., ["C-Level", "VP", "Director", "Manager"]) */
+   seniorities?: string[];
+   /** Departments to filter by (e.g., ["Engineering", "Sales", "Marketing"]) */
+   departments?: string[];
+   /** Job title keywords to search for */
+   jobTitleKeywords?: string[];
+   /** Two-letter country codes to filter by */
+   countries?: string[];
+   /** Array of Ocean.io people IDs to find lookalikes for */
+   lookalikePeopleIds?: string[];
 }
 
 interface OceanCompanyResult {
-  /** Company domain */
-  domain: string;
-  /** Company name */
-  name?: string;
-  /** Legal company name */
-  legalName?: string;
-  /** Company description */
-  description?: string;
-  /** Two-letter country codes where the company operates */
-  countries?: string[];
-  /** Primary country code */
-  primaryCountry?: string;
-  /** Company size range (e.g., "51-200") */
-  companySize?: string;
-  /** Industry categories */
-  industryCategories?: string[];
-  /** Industries */
-  industries?: string[];
-  /** LinkedIn industry classification */
-  linkedinIndustry?: string;
-  /** Whether the company is an e-commerce business */
-  ecommerce?: boolean;
-  /** Company keywords */
-  keywords?: string[];
-  /** Ocean.io employee count estimate */
-  employeeCountOcean?: number;
-  /** LinkedIn employee count */
-  employeeCountLinkedin?: number;
-  /** Revenue range (e.g., "1M-10M") */
-  revenue?: string;
-  /** Year founded */
-  yearFounded?: number;
-  /** Company email addresses */
-  emails?: string[];
-  /** Phone numbers with country and primary flag */
-  phones?: Array<{ country?: string; number: string; primary?: boolean }>;
-  /** Company logo URL */
-  logo?: string;
-  /** Technologies used */
-  technologies?: string[];
-  /** Technology categories */
-  technologyCategories?: string[];
-  /** Company website root URL */
-  rootUrl?: string;
-  /** Social media profiles */
-  medias?: Record<string, { url?: string; handle?: string; name?: string }>;
-  /** Office locations */
-  locations?: Array<{
-    primary?: boolean;
-    latitude?: number;
-    longitude?: number;
-    country?: string;
-    locality?: string;
-    region?: string;
-    postalCode?: string;
-    streetAddress?: string;
-    state?: string;
-  }>;
-  /** Department sizes */
-  departmentSizes?: Array<{ department: string; size: number }>;
-  /** Headcount growth metrics */
-  headcountGrowth?: {
-    threeMonths?: number;
-    threeMonthsPercentage?: number;
-    sixMonths?: number;
-    sixMonthsPercentage?: number;
-    twelveMonths?: number;
-    twelveMonthsPercentage?: number;
-  };
-  /** Last update timestamp */
-  updatedAt?: string;
+   /** Company domain */
+   domain: string;
+   /** Company name */
+   name?: string;
+   /** Legal company name */
+   legalName?: string;
+   /** Company description */
+   description?: string;
+   /** Two-letter country codes where the company operates */
+   countries?: string[];
+   /** Primary country code */
+   primaryCountry?: string;
+   /** Company size range (e.g., "51-200") */
+   companySize?: string;
+   /** Industry categories */
+   industryCategories?: string[];
+   /** Industries */
+   industries?: string[];
+   /** LinkedIn industry classification */
+   linkedinIndustry?: string;
+   /** Whether the company is an e-commerce business */
+   ecommerce?: boolean;
+   /** Company keywords */
+   keywords?: string[];
+   /** Ocean.io employee count estimate */
+   employeeCountOcean?: number;
+   /** LinkedIn employee count */
+   employeeCountLinkedin?: number;
+   /** Revenue range (e.g., "1M-10M") */
+   revenue?: string;
+   /** Year founded */
+   yearFounded?: number;
+   /** Company email addresses */
+   emails?: string[];
+   /** Phone numbers with country and primary flag */
+   phones?: Array<{ country?: string; number: string; primary?: boolean }>;
+   /** Company logo URL */
+   logo?: string;
+   /** Technologies used */
+   technologies?: string[];
+   /** Technology categories */
+   technologyCategories?: string[];
+   /** Company website root URL */
+   rootUrl?: string;
+   /** Social media profiles */
+   medias?: Record<string, { url?: string; handle?: string; name?: string }>;
+   /** Office locations */
+   locations?: Array<{
+      primary?: boolean;
+      latitude?: number;
+      longitude?: number;
+      country?: string;
+      locality?: string;
+      region?: string;
+      postalCode?: string;
+      streetAddress?: string;
+      state?: string;
+   }>;
+   /** Department sizes */
+   departmentSizes?: Array<{ department: string; size: number }>;
+   /** Headcount growth metrics */
+   headcountGrowth?: {
+      threeMonths?: number;
+      threeMonthsPercentage?: number;
+      sixMonths?: number;
+      sixMonthsPercentage?: number;
+      twelveMonths?: number;
+      twelveMonthsPercentage?: number;
+   };
+   /** Last update timestamp */
+   updatedAt?: string;
 }
 
 /**
  * Search for lookalike companies using Ocean.io.
  * Provide seed domains via companiesFilters.lookalikeDomains to find similar companies.
- * Filter by size, country, industry, technology, revenue, and more.
- * Returns up to `size` companies per call (default 10). Use `searchAfter` for pagination.
+ * Verified v3 filters: companySizes, countries, industries, ecommerce, and top-level peopleFilters.
+ * Use `searchAfter` for pagination. Do not send `from`, `includeDomains`, `excludeDomains`, or `minScore` because Ocean v3 rejects them with 422 errors.
  */
 type companies = (params: {
-    /** Filters for company search (lookalike domains, size, country, industry, etc.) */
-    companiesFilters?: OceanCompaniesFilters;
-    /** Number of results to return (default 10, max 100) */
-    size?: number;
-    /** Pagination offset (use searchAfter for cursor-based pagination instead) */
-    from?: number;
-    /** Cursor token from a previous response for efficient pagination */
-    searchAfter?: string;
-    /** Domains to always include in results */
-    includeDomains?: string[];
-    /** Domains to exclude from results */
-    excludeDomains?: string[];
-  }) => Promise<{
-  /** Total matching companies */
-  total: number;
-  /** Cursor for next page (pass as searchAfter) */
-  searchAfter?: string;
-  /** Matched companies with relevance scores */
-  companies: Array<{
-    company: OceanCompanyResult;
-    /** Relevance grade (A = best match) */
-    relevance?: string;
-  }>;
-  /** Domains that were redirected to canonical domains */
-  redirectMap?: Record<string, string>;
-}>;
+   /** Filters for company search (lookalike domains, size, country, industry, ecommerce) */
+   companiesFilters?: OceanCompaniesFilters;
+   /** Optional people filters. Returns companies that have at least one matching person. */
+   peopleFilters?: OceanPeopleFilters;
+   /** Number of results to return (default 10, max 100) */
+   size?: number;
+   /** Cursor token from a previous response for efficient pagination */
+   searchAfter?: string;
+}) => Promise<{
+   /** Ocean.io status detail (typically "OK") */
+   detail?: string;
+   /** Total matching companies */
+   total: number;
+   /** Cursor for next page (pass as searchAfter) */
+   searchAfter?: string;
+   /** Matched companies with relevance scores */
+   companies: Array<{
+      company: OceanCompanyResult;
+      /** Relevance grade (A = best match) */
+      relevance?: string;
+   }>;
+   /** Domains that were redirected to canonical domains */
+   redirectMap?: Record<string, string>;
+}>;

package/docs/services/predictLeads/companyJobOpenings.ts

@@ -1,102 +1,176 @@
 /**
  * Retrieve company's Job Openings
  * Returns a list of company's Job Openings.
+ *
+ * Use this as a prospecting/enrichment signal, not as source-of-truth validation
+ * that a known company is currently hiring. For current validation, prefer the
+ *
+ * company's official careers page / ATS via services.company.findCareersPage and
+ * services.company.scrapeCareersPage.
  * HTTP GET /companies/{company_id_or_domain}/job_openings
  */
 type companyJobOpenings = (params: {
-  /** Company's ID or domain. */
-  company_id_or_domain: string;
-  /** Set to true if you'd like to receive JobOpenings that are not closed, have last_seen_at more recent than 5 days and were found in the last year. */
-  active_only?: boolean;
-  /** Similar to `active_only`, but without considering `last_seen_at` timestamp. */
-  not_closed?: boolean;
-  /** Only return `JobOpenings` first seen after given date (ISO 8601). */
-  first_seen_at_from?: string;
-  /** Only return `JobOpenings` first seen before given date (ISO 8601). */
-  first_seen_at_until?: string;
-  /** Only return `JobOpenings` last seen after given date (ISO 8601). */
-  last_seen_at_from?: string;
-  /** Only return `JobOpenings` last seen before given date (ISO 8601). */
-  last_seen_at_until?: string;
-  /** Only return JobOpenings that have description. */
-  with_description_only?: boolean;
-  /** Only return JobOpenings that have location. */
-  with_location_only?: boolean;
-  /** Comma-separated (,) `JobOpening` categories. */
-  categories?: Array<"administration" | "consulting" | "data_analysis" | "design" | "directors" | "education" | "engineering" | "finance" | "healthcare_services" | "human_resources" | "information_technology" | "internship" | "legal" | "management" | "marketing" | "military_and_protective_services" | "operations" | "purchasing" | "product_management" | "quality_assurance" | "real_estate" | "research" | "sales" | "software_development" | "support" | "manual_work" | "food">;
-  /** Page number of shown items. **NOTE**: If the parameter is not provided, the meta property `count` will be omitted from response for performance reasons. */
-  page?: number;
-  /** Limit the number of shown items per page. */
-  limit?: number;
+   /** Company's ID or domain. */
+   company_id_or_domain: string;
+   /** Set to true if you'd like to receive JobOpenings that are not closed, have last_seen_at more recent than 5 days and were found in the last year. */
+   active_only?: boolean;
+   /** Similar to `active_only`, but without considering `last_seen_at` timestamp. */
+   not_closed?: boolean;
+   /** Only return `JobOpenings` first seen after given date (ISO 8601). */
+   first_seen_at_from?: string;
+   /** Only return `JobOpenings` first seen before given date (ISO 8601). */
+   first_seen_at_until?: string;
+   /** Only return `JobOpenings` last seen after given date (ISO 8601). */
+   last_seen_at_from?: string;
+   /** Only return `JobOpenings` last seen before given date (ISO 8601). */
+   last_seen_at_until?: string;
+   /** Only return JobOpenings that have description. */
+   with_description_only?: boolean;
+   /** Only return JobOpenings that have location. */
+   with_location_only?: boolean;
+   /** Comma-separated (,) `JobOpening` categories. */
+   categories?: Array<
+      | "administration"
+      | "consulting"
+      | "data_analysis"
+      | "design"
+      | "directors"
+      | "education"
+      | "engineering"
+      | "finance"
+      | "healthcare_services"
+      | "human_resources"
+      | "information_technology"
+      | "internship"
+      | "legal"
+      | "management"
+      | "marketing"
+      | "military_and_protective_services"
+      | "operations"
+      | "purchasing"
+      | "product_management"
+      | "quality_assurance"
+      | "real_estate"
+      | "research"
+      | "sales"
+      | "software_development"
+      | "support"
+      | "manual_work"
+      | "food"
+   >;
+   /** Page number of shown items. **NOTE**: If the parameter is not provided, the meta property `count` will be omitted from response for performance reasons. */
+   page?: number;
+   /** Limit the number of shown items per page. */
+   limit?: number;
 }) => Promise<{
-  data: Array<{
-  id: string;
-  type: "job_opening";
-  attributes: {
-  title: string;
-  description: string | null;
-  url: string;
-  first_seen_at: string;
-  last_seen_at: string;
-  last_processed_at: string;
-  contract_types: Array<Record<string, unknown>>;
-  categories: Array<"administration" | "consulting" | "data_analysis" | "design" | "directors" | "education" | "engineering" | "finance" | "healthcare_services" | "human_resources" | "information_technology" | "internship" | "legal" | "management" | "marketing" | "military_and_protective_services" | "operations" | "purchasing" | "product_management" | "quality_assurance" | "real_estate" | "research" | "sales" | "software_development" | "support" | "manual_work" | "food">;
-  onet_data: {
-  code: string | null;
-  family: string | null;
-  occupation_name: string | null;
-};
-  posted_at: string | null;
-  recruiter_data: {
-  name: string | null;
-  title: string | null;
-  contact: string | null;
-};
-  salary: string | null;
-  salary_data: {
-  salary_low: number | null;
-  salary_high: number | null;
-  salary_currency: string | null;
-  salary_low_usd: number | null;
-  salary_high_usd: number | null;
-  salary_time_unit: "hour" | "day" | "week" | "month" | "year" | null;
-};
-  seniority: "not_set" | "founder" | "c_level" | "partner" | "president" | "vice_president" | "head" | "director" | "manager" | "mid_senior" | "junior" | "non_manager";
-  status: "closed" | null;
-  language: string | null;
-  location: string | null;
-  location_data: Array<{
-  city: unknown;
-  state: unknown;
-  zip_code: unknown;
-  country: unknown;
-  region: unknown;
-  continent: unknown;
-  fuzzy_match: unknown;
+   data: Array<{
+      id: string;
+      type: "job_opening";
+      attributes: {
+         title: string;
+         description: string | null;
+         url: string;
+         first_seen_at: string;
+         last_seen_at: string;
+         last_processed_at: string;
+         contract_types: Array<Record<string, unknown>>;
+         categories: Array<
+            | "administration"
+            | "consulting"
+            | "data_analysis"
+            | "design"
+            | "directors"
+            | "education"
+            | "engineering"
+            | "finance"
+            | "healthcare_services"
+            | "human_resources"
+            | "information_technology"
+            | "internship"
+            | "legal"
+            | "management"
+            | "marketing"
+            | "military_and_protective_services"
+            | "operations"
+            | "purchasing"
+            | "product_management"
+            | "quality_assurance"
+            | "real_estate"
+            | "research"
+            | "sales"
+            | "software_development"
+            | "support"
+            | "manual_work"
+            | "food"
+         >;
+         onet_data: {
+            code: string | null;
+            family: string | null;
+            occupation_name: string | null;
+         };
+         posted_at: string | null;
+         recruiter_data: {
+            name: string | null;
+            title: string | null;
+            contact: string | null;
+         };
+         salary: string | null;
+         salary_data: {
+            salary_low: number | null;
+            salary_high: number | null;
+            salary_currency: string | null;
+            salary_low_usd: number | null;
+            salary_high_usd: number | null;
+            salary_time_unit: "hour" | "day" | "week" | "month" | "year" | null;
+         };
+         seniority:
+            | "not_set"
+            | "founder"
+            | "c_level"
+            | "partner"
+            | "president"
+            | "vice_president"
+            | "head"
+            | "director"
+            | "manager"
+            | "mid_senior"
+            | "junior"
+            | "non_manager";
+         status: "closed" | null;
+         language: string | null;
+         location: string | null;
+         location_data: Array<{
+            city: unknown;
+            state: unknown;
+            zip_code: unknown;
+            country: unknown;
+            region: unknown;
+            continent: unknown;
+            fuzzy_match: unknown;
+         }>;
+         tags: Array<Record<string, unknown>>;
+      };
+      relationships: {
+         company: {
+            data: {
+               id: string;
+               type: "company";
+            };
+         };
+      };
+   }>;
+   included: Array<{
+      id: string;
+      type: "company";
+      attributes: {
+         domain: string;
+         company_name: string | null;
+         ticker: string | null;
+      };
+   }>;
+   meta?: {
+      schema_version: string;
+      record_state: "active";
+      count?: number;
+   };
 }>;
-  tags: Array<Record<string, unknown>>;
-};
-  relationships: {
-  company: {
-  data: {
-  id: string;
-  type: "company";
-};
-};
-};
-}>;
-  included: Array<{
-  id: string;
-  type: "company";
-  attributes: {
-  domain: string;
-  company_name: string | null;
-  ticker: string | null;
-};
-}>;
-  meta?: {
-  schema_version: string;
-  record_state: "active";
-  count?: number;
-};
-}>;

package/docs/services/skills/index.md

@@ -0,0 +1,87 @@
+---
+description: Create and manage knowledge skills — reusable knowledge snippets that guide AI agents
+---
+
+# skills — Knowledge Skills
+
+Create, read, update, and delete knowledge skills. Skills are reusable knowledge snippets (company context, ICP descriptions, email templates, product info) that agents reference during research and outreach.
+
+## Quick start
+
+```typescript
+import { skills } from "orangeslice";
+
+// Create a skill
+const skill = await skills.create({
+  name: "ICP description",
+  content: "We sell to B2B SaaS companies, 50-500 employees, Series A-C..."
+});
+
+// List all skills
+const { skills: all } = await skills.list();
+console.log(all.map(s => `${s.name}: ${s.content.slice(0, 50)}...`));
+
+// Update a skill
+await skills.update(skill.id, { content: "Updated ICP: ..." });
+
+// Delete a skill
+await skills.delete(skill.id);
+```
+
+## Methods
+
+### `skills.list(opts?)`
+
+List knowledge skills for the current account.
+
+**Parameters:**
+- `opts.spreadsheetId` — Filter to a specific spreadsheet's skills
+
+**Returns:** `{ skills: Skill[] }`
+
+### `skills.get(id)`
+
+Get a single skill by ID.
+
+**Returns:** `Skill`
+
+### `skills.create(opts)`
+
+Create a new knowledge skill.
+
+**Parameters:**
+- `opts.name` — Skill name (e.g. "ICP description", "Email template")
+- `opts.content` — The knowledge content
+- `opts.spreadsheetId` — Optional, scope to a specific spreadsheet
+
+**Returns:** `Skill`
+
+### `skills.update(id, fields)`
+
+Update an existing skill.
+
+**Parameters:**
+- `fields.name` — New name
+- `fields.content` — New content
+
+**Returns:** `Skill`
+
+### `skills.delete(id)`
+
+Delete a skill by ID.
+
+**Returns:** `{ success: boolean }`
+
+## Skill object
+
+```typescript
+{
+  id: string;
+  name: string;
+  content: string;
+  createdAt: string;
+  updatedAt: string;
+  scope: "account" | "spreadsheet";
+  spreadsheetId: string | null;
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orangeslice",
-  "version": "2.2.0",
+  "version": "2.3.1-beta.0",
   "description": "B2B LinkedIn database prospector - 1.15B profiles, 85M companies",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",