bereach-openclaw 1.3.1 → 1.3.2

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "bereach-openclaw",
   "name": "BeReach",
-  "version": "1.3.1",
+  "version": "1.3.2",
   "description": "LinkedIn outreach automation — 60+ tools, instant status commands",
   "configSchema": {
     "type": "object",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bereach-openclaw",
-  "version": "1.3.1",
+  "version": "1.3.2",
   "description": "BeReach LinkedIn automation plugin for OpenClaw",
   "license": "AGPL-3.0",
   "exports": {
@@ -18,9 +18,9 @@
     "bereach": "^1.3.2"
   },
   "devDependencies": {
-    "@types/node": "^22.19.3",
+    "@types/node": "^25.5.0",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
-    "vitest": "^4.0.18"
+    "vitest": "^4.1.0"
   }
 }

package/skills/bereach/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: bereach
 description: "Automate LinkedIn outreach via BeReach (berea.ch). Use when: prospecting, engaging posts, scraping engagement, searching LinkedIn, managing inbox, running campaigns, managing invitations, analytics, company pages, Sales Navigator, content engagement, feed monitoring. Requires BEREACH_API_KEY."
-lastUpdatedAt: 1773616915
+lastUpdatedAt: 1773675510
 metadata: { "openclaw": { "requires": { "env": ["BEREACH_API_KEY"] }, "primaryEnv": "BEREACH_API_KEY" } }
 ---
 
@@ -24,11 +24,22 @@ Automate LinkedIn prospection and engagement via BeReach.
 
 | Sub-skill             | Keywords                                                                                                                  | URL                                                     | lastUpdatedAt |
 | --------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | ------------- |
-| Lead Magnet           | lead magnet, comment to DM, resource delivery, post giveaway, auto-accept invitations, scheduled run, recap, campaign stats, pause | sub/lead-magnet.md       | 1773616915    |
-| Lead Gen              | lead gen, find leads, search, qualify, ICP, pipeline, build list, scrape engagement, competitor, grow database, prospecting, hashtag, Sales Navigator         | sub/lead-gen.md          | 1773616915    |
-| Outreach              | outreach, connect, DM, message, follow up, sequence, connection request, reply, personalized outreach, campaign outreach, warming, follow, like post           | sub/outreach.md          | 1773616915    |
+| Lead Magnet           | lead magnet, comment to DM, resource delivery, post giveaway, auto-accept invitations, scheduled run, recap, campaign stats, pause | sub/lead-magnet.md       | 1773675510    |
+| Lead Gen              | lead gen, find leads, search, qualify, ICP, pipeline, build list, scrape engagement, competitor, grow database, prospecting, hashtag, Sales Navigator         | sub/lead-gen.md          | 1773663610    |
+| Outreach              | outreach, connect, DM, message, follow up, sequence, connection request, reply, personalized outreach, campaign outreach, warming, follow, like post           | sub/outreach.md          | 1773616752    |
 | OpenClaw Optimization | openclaw, model, opus, sonnet, haiku, config, SOUL.md, heartbeat, prompt caching, AI cost reduction, /model               | openclaw-optimization.md | 1773274027    |
-| SDK Reference         | sdk, method, parameter, signature, reference, api, script                                                                 | sdk-reference.md         | 1773616915    |
+| SDK Reference         | sdk, method, parameter, signature, reference, api, script                                                                 | sdk-reference.md         | 1773665416    |
+
+### Workspace Templates
+
+At install or upgrade, set up the workspace with these templates:
+
+| Template | Purpose | URL |
+| --- | --- | --- |
+| SOUL.md | Always-loaded tool listing + session startup + sub-skills routing table | workspace/soul-template.md |
+| AGENTS.md | Lean sub-agent safety net | workspace/agents-template.md |
+
+**Step 0 (mandatory at install/upgrade):** Check if SOUL.md contains `<!-- bereach-workspace-v`. If missing: fetch soul-template.md from the URL above (or via `GET /api/onboarding/soul`), write it into the user's SOUL.md between the markers. Set up the pipeline cron (every 15min) if not already configured. This step cannot be skipped.
 
 ### Supporting files
 
@@ -153,7 +164,7 @@ These are technical constraints BeReach requires. Everything else, adapt as need
 
 1. **Dedup** — pass `campaignSlug` on every action. BeReach deduplicates by target automatically. Duplicates return `duplicate: true` and cost nothing. Pre-check: use `client.campaigns.getStatus()` or the `getStatus` tool.
 2. **Pacing** — after every SDK/tool call, sleep a random delay. Write actions (DM, reply, like, comment, connect, accept, follow, repost, edit, sync): `random delay 8-12s`. Read actions (visit, scrape, search, find, feed, analytics, count-0 checks): `random delay 2-6s`. Inbox management (archive, star, mark-read, react, typing): `random delay 1-3s`. On 429: wait the number of seconds from the error response, retry (max 3). If daily/weekly cap hit, switch action type.
-3. **Save incrementally** — persist tracking after each action, not at the end.
+3. **Save incrementally** — persist pipeline progress and tracking state after each action, not at the end. Contact data is auto-saved by API calls; only save operational state (e.g. which posts were scraped, discovery sources processed).
 4. **Limits check** — call `getLimits` once per day at session start.
 5. **Visit before connecting** — looks natural to LinkedIn.
 6. **Credits** — check with `getCredits` → `{credits: {current, limit, remaining, percentage, isUnlimited}}`. When `isUnlimited` is true, `remaining` and `limit` are null — credits are unlimited, skip credit budgeting.

package/skills/bereach/sdk-reference.md

@@ -1,7 +1,7 @@
 ---
 name: bereach-sdk-reference
 description: "Complete SDK v1.3.2 method reference — parameters, types, and descriptions for all BeReach operations."
-lastUpdatedAt: 1773616915
+lastUpdatedAt: 1773665416
 ---
 
 <!--
@@ -47,7 +47,7 @@ Methods are split across three getters: `scrapers`, `linkedinScrapers`, and `lin
 
 ### collectLikes
 
-Scrape LinkedIn post likes. Returns paginated list of profiles who liked a post.
+Scrape LinkedIn post likes. Returns paginated list of profiles who liked a post. **Auto-saves:** auto-creates a contact record for each liker.
 
 `client.linkedinScrapers.collectLikes(params)`
 
@@ -68,7 +68,7 @@ Scrape LinkedIn post likes. Returns paginated list of profiles who liked a post.
 
 ### collectComments
 
-Scrape LinkedIn post comments. Returns paginated list of commenters with comment text and URNs.
+Scrape LinkedIn post comments. Returns paginated list of commenters with comment text and URNs. **Auto-saves:** auto-creates a contact record for each commenter.
 
 `client.linkedinScrapers.collectComments(params)`
 
@@ -92,7 +92,7 @@ Scrape LinkedIn post comments. Returns paginated list of commenters with comment
 
 ### collectCommentReplies
 
-Scrape replies to a LinkedIn comment. Returns paginated replies for a specific comment URN.
+Scrape replies to a LinkedIn comment. Returns paginated replies for a specific comment URN. **Auto-saves:** auto-creates a contact record for each replier.
 
 `client.linkedInScrapers.collectCommentReplies(params)`
 
@@ -115,7 +115,7 @@ Scrape replies to a LinkedIn comment. Returns paginated replies for a specific c
 
 ### collectPosts
 
-Scrape LinkedIn profile posts. Returns paginated list of posts from a profile.
+Scrape LinkedIn profile posts. Returns paginated list of posts from a profile. **Auto-saves:** auto-creates/updates a contact record for the profile.
 
 `client.scrapers.collectPosts(params)`
 
@@ -139,7 +139,7 @@ Scrape LinkedIn profile posts. Returns paginated list of posts from a profile.
 
 ### visitProfile
 
-Visit LinkedIn profile and extract contact data. Distance-1 profiles cached 24h. No dedup — always executes.
+Visit LinkedIn profile and extract contact data. Distance-1 profiles cached 24h. No dedup — always executes. **Auto-saves:** creates/updates the contact record with full profileData — do not manually save profileData after calling this.
 
 `client.scrapers.visitProfile(params)`
 
@@ -529,9 +529,8 @@ Reply to a LinkedIn comment. Use the commentUrn from the comments endpoint direc
 
 `client.linkedinActions.replyToComment(params)`
 
-- **postUrl** (string, required) — LinkedIn post URL containing the comment.
 - **commentUrn** (string, required) — LinkedIn comment URN (e.g., 'urn:li:comment:(activity:123,456)').
-- **text** (string, required) — Reply message text.
+- **message** (string, required) — Reply message text.
 - **campaignSlug** (string) — Campaign identifier for deduplication.
 
 **Returns:**
@@ -587,7 +586,7 @@ Add a top-level comment on a LinkedIn post. Deduplicates by post within a campai
 `client.linkedInActions.createComment(params)`
 
 - **postUrl** (string, required) — LinkedIn post URL.
-- **text** (string, required) — Comment text.
+- **message** (string, required) — Comment text.
 - **companyId** (string) — Act as a company page (numeric company ID) instead of personal profile.
 - **campaignSlug** (string) — Campaign identifier for deduplication.
 
@@ -853,7 +852,7 @@ Search LinkedIn inbox conversations by keyword. 0 credits.
 
 ### findConversation
 
-Find a conversation with a specific person. Direct O(1) lookup via LinkedIn's compose API. 0 credits.
+Find a conversation with a specific person. Direct O(1) lookup via LinkedIn's compose API. 0 credits. **Auto-saves:** creates/updates the contact record with conversationData — do not manually save conversationData after calling this.
 
 `client.chat.findConversation(params)`
 
@@ -1287,7 +1286,7 @@ The SDK `contacts` getter only exposes `upsert`. All other contact methods (getB
 
 ### upsert
 
-Create or upsert contacts without a campaign. The organic flow — save contacts as you discover them, attach to campaigns later. Upserts by LinkedIn URL.
+Create or upsert contacts without a campaign. **For manual imports only** — most scrape/search/visit calls auto-create contacts. Use this only when the user provides a CSV/spreadsheet of profiles to import. Upserts by LinkedIn URL.
 
 `client.contacts.upsert(params)`
 
@@ -1597,10 +1596,10 @@ Update a contact: lifecycle stage, score, notes, profile/conversation context, o
 - **qualificationNotes** (string) — Agent reasoning.
 - **notes** (string)
 - **name** (string) — Update contact name.
-- **profileData** (object) — Full LinkedIn profile snapshot (JSON).
-- **profileUpdatedAt** (string, ISO datetime) — When profileData was last refreshed.
-- **conversationData** (object) — DM history: `{ conversationUrn, historySummary, recentMessages, lastSyncedAt }`.
-- **conversationUpdatedAt** (string, ISO datetime) — When conversationData was last synced.
+- **profileData** (object) — Full LinkedIn profile snapshot (JSON). **Note:** auto-populated by `visitProfile` — only set manually for data not obtained through a visit.
+- **profileUpdatedAt** (string, ISO datetime) — When profileData was last refreshed. Auto-set by `visitProfile`.
+- **conversationData** (object) — DM history: `{ conversationUrn, historySummary, recentMessages, lastSyncedAt }`. **Note:** auto-populated by `findConversation` — only set manually for data not obtained through a find.
+- **conversationUpdatedAt** (string, ISO datetime) — When conversationData was last synced. Auto-set by `findConversation`.
 - **outreachStatus** (string) — Manual override. Usually auto-synced — only set manually for `in_conversation`, `converted`, `not_interested`.
 - **nextFollowUpAt** (string, ISO datetime | null) — When the agent should follow up. Queryable via `searchContacts({ followUpBefore })`. Set `null` to clear.
 - **draftNextDm** (string | null) — Draft DM to send on next follow-up. Set `null` to clear. Auto-cleared when the contact replies or a message is sent. `draftNextDmGeneratedAt` is auto-set on write.

package/skills/bereach/sub/lead-gen.md

@@ -1,7 +1,7 @@
 ---
 name: bereach-lead-gen
 description: "Autonomous lead generation — find and qualify leads daily through multi-angle search, engagement scraping, and a learning loop."
-lastUpdatedAt: 1773616915
+lastUpdatedAt: 1773663610
 ---
 
 <!--
@@ -30,9 +30,71 @@ Lead gen uses a **hybrid execution model**:
 - **Tool-based (default)** — the agent uses BeReach tools directly. It thinks between calls, adapts in real-time, tries different angles. No TypeScript script generation needed. This is the right mode for exploration and daily runs (20-30 profiles).
 - **Script-based (scale)** — when an angle is proven (client validated, good results), the agent can generate a TypeScript script to process it at high volume (hundreds of profiles). Scripts go in `src/lead-gen/` — do NOT modify `src/lead-magnet/helpers.ts`.
 
+## Auto-Save Architecture
+
+Every API route that returns profile data auto-creates/updates contacts via Next.js `after()` (no latency impact). `smartUpsertContact` handles dedup by profileUrn/publicIdentifier/linkedinUrl.
+
+| API call                | What auto-saves                       | Credits         |
+| ----------------------- | ------------------------------------- | --------------- |
+| `collectComments`       | Contact per commenter (name + URL)    | 1               |
+| `collectLikes`          | Contact per liker (name + URL)        | 1               |
+| `collectPosts`          | Contact for profile + saves posts     | 1               |
+| `collectCommentReplies` | Contact per replier                   | 1               |
+| `collectHashtagPosts`   | Contact per post author               | 1               |
+| `searchPeople`          | Contact per result                    | 1               |
+| `searchPosts`           | Contact per post author               | 1               |
+| `searchByUrl`           | Contact per result                    | 1               |
+| `salesNav.*`            | Contact per result                    | dynamic         |
+| `visitProfile`          | Creates/updates with full profileData | 1 (0 if cached) |
+| `findConversation`      | Creates/updates with conversationData | 0               |
+| `listConversations`     | Contact per conversation participant  | 0               |
+
+`searchCompanies` and `searchJobs` do NOT create contacts (not people).
+
+**Consequence:** The agent never holds profile data in memory. Never calls `contacts.upsertContacts` for data that was just scraped/searched/visited. `contacts.upsertContacts` is only for manual imports (user pastes a CSV/spreadsheet).
+
+## Pipeline: 4 Phases
+
+The DB is the queue. Each phase maps to a DB query.
+
+### Phase 1: Discover
+
+Use ANY channel (search, scrape, hashtag, followers, feed, Sales Nav...). Contacts are auto-created by every API call. If campaign-based: `addContacts` links to campaign + sets source/sourceAngle. Strategy is up to the agent based on user prompt.
+
+### Phase 2: Enrich
+
+`searchContacts({ hasProfileData: "false" })` = the work queue. For each contact: `visitProfile` + `findConversation`. Both auto-save to the contact record. Skip errors, try next. Resumes across sessions automatically since the DB tracks what's enriched.
+
+### Phase 3: Qualify
+
+`searchContacts({ hasProfileData: "true", lifecycleStage: "contact" })` = contacts needing qualification. Evaluate against ICP (from campaign context or user prompt). Update `lifecycleStage` + `hotScore` via `contacts.updateContact`. Stages: `contact` → `lead` → `qualified`. Rules are campaign-specific, not hardcoded.
+
+### Phase 4: Report
+
+`contacts.getStats()` for funnel metrics. `searchContacts` by `hotScore` for top qualified leads. Present results in a clean table.
+
+### Multi-Day Resilience
+
+The DB IS the queue:
+
+- `searchContacts({ hasProfileData: "false" })` = Phase 2 remaining
+- `searchContacts({ hasProfileData: "true", lifecycleStage: "contact" })` = Phase 3 remaining
+
+`agentState` only tracks which discovery sources were already processed. Everything else lives in the DB.
+
+### Data Model Reference
+
+```
+LifecycleStage: contact -> lead -> qualified -> approved | rejected
+ContactSource: likes, comments, reposts, posts, company_followers,
+  search_results, engagement_scraping, content_search, followers_mining,
+  people_search, job_search, company_search, network_expansion,
+  manual_import, event_attendees, group_members
+```
+
 ## Channels
 
-Seven lead-finding channels, ordered by typical warmth. The agent picks channels based on the prompt, context, and available budget.
+Eleven lead-finding channels, ordered by typical warmth. The agent picks channels based on the prompt, context, and available budget.
 
 ### 1. Engagement scraping (hottest)
 
@@ -143,92 +205,20 @@ LinkedIn supports: `"exact phrase"`, `AND`, `OR`, `NOT`, parentheses. Teach effe
 
 When the client pastes a LinkedIn search URL, use `searchByUrl` to extract all filters automatically. Fast way to define new angles from the client's own LinkedIn browsing.
 
-## Qualification
-
-Two-stage qualification to save credits.
-
-### Stage 1 — Pre-filter (0 credits)
-
-Search results and scrape results already contain some data (name, headline snippet, profile URL). Filter here first — skip obviously irrelevant profiles before spending 1 credit on `visitProfile`. For engagement scraping, the comment text itself is a clue (substantive vs "great post").
-
-### Stage 2 — Deep qualification (1 credit)
-
-`visitProfile` with `includePosts: true`. Available data and what it typically tells you:
-
-| Data point | What it tells you |
-| --- | --- |
-| `publicIdentifier` | Vanity name for URL building and dedup |
-| `profileUrn` | URN for API calls and conversation matching |
-| `headline` | Role, seniority, positioning |
-| `position` + `company` | Current role and company fit |
-| `positions` (array) | Career trajectory, recent job change = transition indicator |
-| `location` | Geographic fit, timezone |
-| `memberDistance` | 1st = already connected, 2nd = mutual connections (warmer) |
-| `pendingConnection` | "pending" = already tried, "none" = fresh |
-| `lastPosts` | Topics, concerns, engagement level |
-| `email` | Available for distance-1 only |
-| `educations` | Background, alumni networks |
-| `cached` | If `true`, visit was free (distance-1 cached 24h) |
-
-The agent decides what matters based on the client's context. No fixed scoring formula.
-
-### Company-level qualification
-
-When company fit matters, use `visitCompany` (1 credit): `employeeCount`, `industry`, `specialities`, `foundedOn`, `similarCompanies` (free expansion), `websiteUrl`. Cache company data — multiple leads may work at the same company.
-
-## Lifecycle stages
-
-Every person progresses through stages. A scraped commenter is a **contact**, not a lead. The data model reflects this:
-
-| Stage | What happens | Credits | Tracked via |
-| --- | --- | --- | --- |
-| `contact` | Raw profile from search/scrape | 0 | `contacts.upsertContacts` or `contacts.addContacts` (linkedinUrl + name) |
-| `lead` | Pre-filtered (Stage 1), looks promising | 0 | `contacts.updateContact` + qualificationNotes |
-| `qualified` | Deep-qualified via visitProfile, confirmed ICP | 1/profile | `contacts.updateContact` + hotScore + profileData. Log `visitProfile` result as activity. |
-| `approved` | Client reviewed and confirmed | 0 | `contacts.updateContact` |
-| `rejected` | Doesn't match ICP (from any stage) | 0 | `contacts.updateContact` + rejection reason |
-
-Stage moves forward only (except `rejected`).
-
-**Profile and conversation data can be stored on the contact.** When you `visitProfile`, save the result to `profileData` (JSON) via `contacts.updateContact({ contactId, profileData: { ... }, profileUpdatedAt: "..." })`. When you check DM history via `findConversation`, save to `conversationData`. This gives the outreach agent instant context without re-visiting. Use `searchContacts({ hasProfileData: "false" })` to find contacts needing enrichment.
-
 ## Contacts DB
 
 The contacts DB stores identity, pipeline status, outreach status, activities, and optionally cached profile/conversation data. All contact operations are 0 credits.
 
-### Two ways to create contacts
-
-**Note: auto-upsert.** BeReach auto-creates contacts when the agent scrapes posts, reads inbox, or finds conversations. The agent should still use `upsertContacts` or `addContacts` to set lifecycle stage, hotScore, tags, and campaign membership — but doesn't need to worry about creating the raw contact record.
-
-**1. Organic (no campaign):** Use `contacts.upsertContacts` to save contacts as you discover them. No campaign required. Attach to campaigns later. Best for exploratory scanning — "save everything interesting, organize later."
-
-```
-contacts.upsertContacts({ contacts: [
-  { linkedinUrl: "...", name: "Alice", lifecycleStage: "contact" },
-  { linkedinUrl: "...", name: "Bob", lifecycleStage: "lead", hotScore: 70 },
-] })
-```
-
-**2. Campaign-based:** Use `contacts.addContacts` when you have a clear angle. Campaign naming: `lg-{channel}-{descriptor}` (e.g., `lg-engagement-competitor-openai`).
+### Creating and organizing contacts
 
-### Workflow
+Contacts are auto-created by scrape/search/visit calls. To organize them:
 
-1. Scrape profiles → save organically: `contacts.upsertContacts({ contacts: [...] })`
-2. Or create a campaign per angle: `contacts.createCampaign({ name, context: "## ICP\nVP Sales at SaaS...\n## Messaging\nValue-first..." })` → `contacts.addContacts({ campaignId, contacts: [...] })`. Store your ICP and strategy in the campaign `context` field — it persists on the campaign and is accessible to both lead-gen and outreach agents. To update context later, use `contacts.updateCampaign({ campaignId, context: "..." })`.
-2b. When adding contacts, include `source` (how found: `"engagement_scraping"`, `"content_search"`, `"people_search"`, `"company_followers"`, `"network_expansion"`) and `sourceAngle` (the specific search/post: `"VP Sales SaaS Paris"`, `"post about cold email tools"`). This enables attribution reporting via `contacts.getStats()`.
-3. Log observations: `contacts.logActivity({ contactId, activities: [{ type: "engagement_observed", content: "..." }] })`
-4. Pre-filter promising ones → promote: `contacts.updateContact({ contactId, lifecycleStage: "lead", qualificationNotes: "VP Sales at SaaS company" })`
-5. Deep-qualify via `visitProfile` → store profile data + promote:
-   ```
-   contacts.updateContact({ contactId, lifecycleStage: "qualified", hotScore: 85, profileData: visitResult, profileUpdatedAt: new Date().toISOString() })
-   ```
-6. **Bulk pre-qualification:** promote hundreds at once: `contacts.bulkUpdate({ contactIds: [...], update: { lifecycleStage: "lead" } })`
-7. **Tag for segmentation:** `contacts.updateContact({ contactId, tags: { add: ["vp-sales", "saas-100-500"] } })`
-8. Client reviews → `contacts.updateContact({ contactId, lifecycleStage: "approved" })` or `"rejected"`
+- **Campaign-based (recommended):** Use `contacts.addContacts` to link contacts to a campaign + set source/sourceAngle/initial stage. `addContacts` is a full upsert — creates the contact if it doesn't exist, updates if it does, and links to the campaign. Campaign naming: `lg-{channel}-{descriptor}` (e.g., `lg-engagement-competitor-openai`).
+- **Manual import only:** Use `contacts.upsertContacts` only when the user provides a CSV/spreadsheet of profiles to import. Never use it for data that was just scraped or visited.
 
 ### Activities
 
-Every meaningful observation or action is logged as an activity on the contact. This is the SDR notebook — what you saw and did:
+Every meaningful observation or action is logged as an activity on the contact:
 
 - `engagement_observed` — "Commented on [post URL]: 'great insights about outbound'"
 - `post_interaction` — "Liked competitor post about sales automation"
@@ -245,105 +235,55 @@ Before visiting a profile (1 credit), check: `contacts.getByUrl({ linkedinUrl })
 
 ### Enrichment planning
 
-Find contacts that need profile data: `contacts.searchContacts({ hasProfileData: "false", lifecycleStage: "lead" })`. Prioritize by score: `sortBy: "hotScore_desc"`.
+Find contacts that need profile data: `contacts.searchContacts({ hasProfileData: "false" })`. Prioritize by score: `sortBy: "hotScore_desc"`.
 
 ### Funnel metrics
 
 `contacts.getStats()` returns a real funnel: `{ contact: 450, lead: 120, qualified: 45, approved: 20, rejected: 30 }` per campaign and globally, plus conversion rates per `sourceAngle`. Powers the learning loop.
 
-## Daily priority
-
-The agent doesn't run all channels equally. Default priority by warmth and credit efficiency:
-
-1. **New engagement** (hottest, best ratio) — scrape watchlisted profiles for new posts/comments since last run
-2. **Profile views** (warm, passive) — `profile.getProfileViews()` to find people already checking you out
-3. **Content activity** (hot) — `searchPosts` for recent posts about relevant topics
-4. **Hashtag scraping** (topical) — `collectHashtagPosts` on ICP-relevant hashtags for active authors
-5. **Feed scan** (passive) — `linkedInScrapers.getFeed({ sortOrder: "REV_CHRON" })` for serendipitous ICP matches
-6. **Saved posts** (curated) — `listSavedPosts` for authors of bookmarked content
-7. **People search** (warm) — fill remaining credit budget with profile-based matches
-8. **Sales Navigator** (precision) — if available, use for hard-to-reach ICP segments standard search can't filter
-
-Over time, the learning loop adjusts this order based on actual quality feedback.
-
-## Growth engine
-
-Lead gen is not a one-shot task. It's an autonomous process that produces new qualified leads every day.
-
-### Daily autonomous run
-
-Each daily run:
-
-1. **Re-run existing angles** — same search queries yield new results over time (people change jobs, join LinkedIn, post new content). `contacts.addContacts` dedup via `@@unique([userId, linkedinUrl])` on Contact + `@@unique([campaignId, contactId])` on CampaignContact ensures no contact is processed twice.
-2. **Monitor engagement watchlist** — scrape new posts from watchlisted profiles (competitors, industry leaders). New posts = new engagers = new leads. Most passive growth channel.
-3. **Passive discovery** — `profile.getProfileViews()` for people viewing you, `linkedInScrapers.getFeed()` for relevant content in the feed, `listSavedPosts()` for bookmarked post authors. Low effort, high serendipity.
-4. **Expand search space** — try variations of what worked:
-   - Title variations: "Head of Sales" → "Sales Director", "VP Sales", "VP Revenue", "CRO"
-   - Geographic expansion: France → Belgium, Switzerland, Canada
-   - Company cascade: qualified lead works at company X → `visitCompany(X)` → `similarCompanies` → more targets (free)
-   - Content cascade: `searchPosts` found a relevant post → scrape its commenters/likers
-   - Hashtag cascade: `collectHashtagPosts` on a trending hashtag → scrape commenters on top posts
-   - Lookalike: `connectionOf` on best qualified leads → similar profiles
-   - Job posting expansion: job posting for "Sales Manager" → find that company's current VP Sales
-   - Topic broadening: "cold email" → "outbound", "sales automation", "pipeline"
-   - Sales Nav precision: `salesNav.searchPeople` with seniority/function/tenure filters for hard-to-reach segments
-5. **Report daily recap** — what was found, how many new leads, which angles performed, suggestions for new directions. The client sees a summary and can steer.
-
-### Agent behavior
+## Agent behavior
 
 - **Act first, check after** — run 3-4 searches, report findings, suggest new angles. Don't wait for permission.
 - **Light validation** — one-line suggestions, not a questionnaire. The client steers if they want.
 - **Prompt-driven** — the client gives a prompt (detailed or vague). The agent uses its context layer (profile, posts, website, campaigns, competitors) to fill gaps. If context is truly insufficient, one nudge max.
 
-### Learning loop
-
-The agent gets smarter through multiple feedback sources, all powered by `contacts.getStats()`:
-
-- **Immediate** — `contacts.getStats()` grouped by `sourceAngle` shows real conversion rates: contact → lead → qualified. Angle "engagement-scraping-competitor-X" converts 40%? Double down. "people-search-generic" converts 12%? Deprioritize.
-- **Periodic** — client reviews contacts via `contacts.updateContact({ lifecycleStage: "approved" })` or `"rejected"`. Agent queries approved vs rejected per angle to refine.
-- **Future** — outreach conversion data (who replied, who booked) feeds back. Agent doubles down on high-converting sources.
-- **Implicit** — angle performance over time. Funnel velocity (`stageChangedAt`) shows which angles qualify fastest.
+## State
 
-### State
+The agent needs memory across runs. State is stored **server-side** via `agentState.get("lead-gen")` / `agentState.set("lead-gen", data)`.
 
-The agent needs memory across runs. Each daily run is a new spawned agent — state is its only continuity. State is stored **server-side** via `agentState.get("lead-gen")` / `agentState.set("lead-gen", data)`.
+**Session startup:** call `agentState.list({ keysOnly: true })` (0 credits) to discover all stored keys. Load `lead-gen` state if present.
 
-**Session startup:** call `agentState.list({ keysOnly: true })` (0 credits) to discover all stored keys. Load `lead-gen` state if present, plus any campaign-specific state keys. This prevents hardcoding key names and lets the agent discover what it stored in previous sessions.
+What to store in agentState (lightweight, operational):
+- Which discovery sources have been processed (post URLs scraped, search angles run)
+- Resolved parameters cache (`{ "France": "geo-id-123" }`)
+- Campaign map (`{ angleId: campaignId }`)
+- Agent notes (what worked/didn't, angles to try next)
 
-**Structured** (operational continuity):
-- Active angles: `{ id, channel, queryParams, resolvedIds, lastRun, totalFound, qualifiedCount }`
-- Engagement watchlist: `{ profileUrl, label, lastScrapedPostCount, leadsFound }`
-- Resolved parameters cache: `{ "France": "geo-id-123" }` — avoid re-resolving every run
-- Campaign map: `{ angleId: campaignId }` — maps angles to lead-gen campaigns
-- Client feedback: `{ profileUrl, verdict, impliedAdjustment }`
-
-**Agent notes** (strategic continuity):
-- What worked/didn't in last run
-- Angles to try next
-- Observations about lead patterns
-- Credit budget status
-
-Server-side state survives device changes and is accessible from any agent instance. No local files needed.
+What NOT to store in agentState:
+- Profile data (auto-saved to contacts DB by visitProfile)
+- Conversation data (auto-saved by findConversation)
+- Contact lists (live in the contacts DB)
 
 ## Cron
 
 ```json
 {
-  "name": "Lead Gen — Daily",
-  "enabled": true,
-  "schedule": { "kind": "cron", "expr": "0 8 * * *", "tz": "Europe/Paris" },
+  "name": "BeReach Pipeline",
+  "schedule": { "kind": "cron", "expr": "*/15 * * * *", "tz": "Europe/Paris" },
   "sessionTarget": "isolated",
   "wakeMode": "now",
   "payload": {
     "kind": "agentTurn",
-    "message": "Run daily lead gen using tools. Discover state via agentState.list({ keysOnly: true }), load 'lead-gen' key if present. Run priority channels, qualify, store via contacts.addContacts/updateContact, save state via agentState.set, report recap.",
-    "timeoutSeconds": 900
+    "message": "Pipeline check.\n1. bereach_contacts_search({ hasProfileData: 'false' }) -- pending enrichment?\n2. If 0: exit. Nothing to do.\n3. If > 0: enrich 5-10 profiles. visitProfile (auto-saves) + findConversation (auto-saves). Skip errors, try next.\n4. After batch: report count enriched + remaining.",
+    "timeoutSeconds": 600
   },
   "delivery": { "mode": "announce", "channel": "webchat", "bestEffort": true }
 }
 ```
 
-Daily at 8:00 by default. Uses `sessionTarget: "isolated"` — the spawned agent loads this sub-skill, reads state, and uses tools directly. No pre-generated script needed.
+Runs every 15 minutes, 24/7. If nothing pending, exits after 1 tool call (cheapest possible turn). If work pending, processes 5-10 profiles then exits. The contacts DB IS the queue.
+
+**NEVER set `lightContext: true`** — this skips SOUL.md injection and breaks the agent.
 
 ## Cost estimation
 
@@ -372,7 +312,7 @@ Check `getCredits` at the start of each run. If `isUnlimited` is true, skip cred
 
 **Feed (1 credit):** `linkedInScrapers.getFeed` — scan home feed for relevant content and authors
 
-**Contacts DB (0 credits):** `contacts.upsertContacts`, `contacts.getByUrl`, `contacts.getFullContact`, `contacts.bulkUpdate`, `contacts.createCampaign`, `contacts.listCampaigns`, `contacts.updateCampaign`, `contacts.addContacts`, `contacts.listContacts`, `contacts.updateContact`, `contacts.searchContacts`, `contacts.getStats`, `contacts.logActivity`, `contacts.getActivities`
+**Contacts DB (0 credits):** `contacts.addContacts`, `contacts.getByUrl`, `contacts.getFullContact`, `contacts.bulkUpdate`, `contacts.createCampaign`, `contacts.listCampaigns`, `contacts.updateCampaign`, `contacts.listContacts`, `contacts.updateContact`, `contacts.searchContacts`, `contacts.getStats`, `contacts.logActivity`, `contacts.getActivities`
 
 **Agent state (0 credits):** `agentState.list`, `agentState.get`, `agentState.set`, `agentState.patch`, `agentState.delete`
 

package/skills/bereach/sub/lead-magnet.md

@@ -1,7 +1,7 @@
 ---
 name: bereach-lead-magnet
 description: "Lead magnet workflow — deliver a resource to everyone who engages with a LinkedIn post."
-lastUpdatedAt: 1773616915
+lastUpdatedAt: 1773675510
 ---
 
 <!--
@@ -84,7 +84,7 @@ State persistence uses the Agent State API at `/api/agent-state/{key}`. The agen
 - **PATCH** `/api/agent-state/{key}` — shallow merge into existing state: `{ data: { ... } }`. Use for progressive saves (e.g. saving `previousTotal` every 10 profiles without reading full state). 0 credits.
 - **DELETE** `/api/agent-state/{key}` — remove a key entirely. Use to clean up stale or obsolete state. 0 credits.
 
-Auth: `Authorization: Bearer $BEREACH_API_KEY`. Base URL: `$BEREACH_API_URL` or `https://app.berea.ch`.
+Auth: `Authorization: Bearer $BEREACH_API_KEY`. Base URL: `https://api.berea.ch`.
 
 ## Tone
 
@@ -186,13 +186,13 @@ This guarantees: no comments lost on timeout, no duplicate processing, no wasted
 
 ### Contacts DB integration
 
-Scripts upsert each processed commenter to the Contacts DB for cross-skill visibility. This lets the outreach agent see who engaged with lead magnet posts, who was DMed, etc. All contacts operations cost 0 credits.
+Commenters are auto-created as contacts by `collectComments` and `collectLikes` (auto-upsert). Scripts do NOT need to manually upsert each commenter.
 
-After processing a commenter:
-1. `upsertContact(linkedinUrl, name, campaignSlug)` — creates/finds the contact and links to a `lead_magnet` campaign (see Helpers). Batched: accumulate profiles and upsert in bulk every 10 profiles.
-2. After performing actions (DM, reply, like), log via the BeReach API as usual (`campaignSlug` dedup). The contacts activity log is optional — upsert is the minimum for cross-skill visibility.
+For campaign membership and cross-skill visibility, use `contacts.addContacts` to link commenters to the lead magnet campaign. `addContacts` is a full upsert — creates the contact if missing, updates if exists, links to campaign. Use it for campaign membership only, not for raw contact creation.
 
-On first run per campaign, create the campaign entity if it doesn't exist: `contacts.createCampaign({ id: campaignSlug, name: "LM: " + campaignSlug, type: "lead_magnet" })`. Cache created campaign IDs in state to avoid re-creating.
+After performing actions (DM, reply, like), log via `contacts.logActivity` for the activity trail. The `campaignSlug` dedup on BeReach API calls handles action tracking.
+
+On first run per campaign, create the campaign entity if it doesn't exist: `contacts.createCampaign({ name: "LM: " + campaignSlug, type: "lead_magnet" })`. The API returns the generated `id` (campaignId) — use that for `addContacts` calls. Cache created campaignId in agentState to avoid re-creating. Note: `campaignSlug` (user-defined) is used for action dedup on API calls, while `campaignId` (system-generated) is used for contacts/campaign membership tools.
 
 ## Pre-flight
 

package/skills/bereach/sub/outreach.md

@@ -1,7 +1,7 @@
 ---
 name: bereach-outreach
 description: "Personalized LinkedIn outreach — connect, message, follow up, and adapt using emergent planning. No hardcoded sequences."
-lastUpdatedAt: 1773616915
+lastUpdatedAt: 1773616752
 ---
 
 <!--

package/skills/bereach/workspace/agents-template.md

@@ -0,0 +1,20 @@
+---
+lastUpdatedAt: 1773663610
+---
+
+<!--
+  AUTO-GENERATED FILE — DO NOT EDIT
+  Source of truth: skills/ directory
+  Edit the source file, then run: pnpm build:plugins
+  Any direct edit to this file WILL be overwritten.
+-->
+
+# BeReach Agent Rules
+
+If you are a sub-agent or spawned session:
+
+1. You have access to bereach_* tools for LinkedIn automation.
+2. Follow the rules in SOUL.md — especially auto-save behavior and dedup via campaignSlug.
+3. Never use raw HTTP calls. Only use registered tools.
+4. Report results concisely when done.
+5. If you encounter a rate limit (429), wait and retry up to 3 times before skipping.

package/skills/bereach/workspace/soul-template.md

@@ -0,0 +1,152 @@
+---
+lastUpdatedAt: 1773665416
+---
+
+<!--
+  AUTO-GENERATED FILE — DO NOT EDIT
+  Source of truth: skills/ directory
+  Edit the source file, then run: pnpm build:plugins
+  Any direct edit to this file WILL be overwritten.
+-->
+
+<!-- bereach-workspace-v2 -->
+
+## Identity
+
+You are a BeReach-powered LinkedIn automation agent.
+For ANY LinkedIn task, use bereach_* tools. Never use raw HTTP.
+
+## Session Startup [MANDATORY before greeting]
+
+1. bereach_state_list(keysOnly: true) — discover existing context
+2. If "user-profile" key exists: bereach_state_get("user-profile")
+3. If any active campaign state found: check progress, resume if needed
+4. bereach_get_credits — check budget
+5. bereach_get_limits — check daily limits
+
+## Tools by Category
+
+### Search
+
+- bereach_search_people: LinkedIn people search (keywords, title, location, industry, company)
+- bereach_search_posts: post search (keywords, date, content type)
+- bereach_search_companies: company search (keywords, size, industry)
+- bereach_search_jobs: job search
+- bereach_search_by_url: parse and run search from a LinkedIn URL
+- bereach_resolve_parameters: resolve text to LinkedIn IDs (GEO, COMPANY, INDUSTRY, SCHOOL)
+
+### Scrape Engagement
+
+- bereach_collect_likes: profiles who liked a post. Auto-creates contacts.
+- bereach_collect_comments: post commenters with text. Auto-creates contacts.
+- bereach_collect_comment_replies: replies to a comment thread. Auto-creates contacts.
+- bereach_collect_posts: posts from a profile. Auto-creates contact.
+- bereach_collect_hashtag_posts: posts by hashtag. Auto-creates contacts.
+- bereach_collect_saved_posts: user's saved posts
+- bereach_visit_profile: visit profile, extract full data (1 credit, cached 24h for 1st degree). Auto-saves profileData to contact.
+- bereach_visit_company: visit company page
+
+### Outreach Actions
+
+- bereach_connect_profile: send connection request (30/day max, visit first)
+- bereach_send_message: send DM (supports conversationUrn fallback)
+- bereach_accept_invitation: accept received invitation
+- bereach_list_invitations: list received invitations
+- bereach_list_sent_invitations: list sent invitations
+- bereach_withdraw_invitation: withdraw sent invitation
+
+### Content Engagement
+
+- bereach_like_post: like/react to a post
+- bereach_comment_on_post: comment on a post
+- bereach_reply_to_comment: reply to a comment
+- bereach_like_comment: like a comment
+- bereach_follow_profile: follow a profile
+- bereach_publish_post: publish or schedule a post
+
+### Inbox
+
+- bereach_list_conversations: list inbox
+- bereach_search_conversations: search by keyword
+- bereach_find_conversation: find by participant (O(1) lookup). Auto-saves conversationData to contact.
+- bereach_get_messages: message history for a conversation
+- bereach_archive_conversation: archive
+
+### Contacts CRM
+
+- bereach_contacts_search: search contacts (stage, tag, score, follow-up date, draft DM)
+- bereach_contacts_stats: funnel metrics
+- bereach_contacts_get_by_url: look up by LinkedIn URL (full contact + activities)
+- bereach_contacts_get_full: get contact by internal ID (full context + activities)
+- bereach_contacts_get_activities: chronological activity log for a contact
+- bereach_contacts_upsert: create/update contacts — for manual imports only (scraping auto-creates contacts)
+- bereach_contacts_update: update stage, score, notes, tags, draft DM
+- bereach_contacts_log_activity: log activities (auto-syncs outreachStatus)
+- bereach_contacts_bulk_update: batch update up to 500
+- bereach_contacts_add: add contacts to a campaign (full upsert — creates if missing, links to campaign)
+- bereach_contacts_list: list contacts in a specific campaign
+
+### Campaigns
+
+- bereach_contacts_create_campaign: create campaign with context (markdown playbook)
+- bereach_contacts_list_campaigns: list campaigns with context
+- bereach_contacts_update_campaign: update campaign settings
+- bereach_campaign_status: per-profile action status (dedup check)
+- bereach_campaign_sync: mark actions completed without performing them
+- bereach_campaign_stats: aggregate campaign stats
+
+### Account
+
+- bereach_get_credits: credit balance (isUnlimited? skip budgeting)
+- bereach_get_limits: rate limit status
+- bereach_get_profile: your LinkedIn profile (0 credits)
+- bereach_get_followers: your followers
+- bereach_get_own_posts: your recent posts
+- bereach_get_profile_views: who viewed your profile
+- bereach_get_feed: LinkedIn feed
+- bereach_refresh_profile: force refresh from LinkedIn
+
+### Agent Memory
+
+- bereach_state_list: list all state keys (keysOnly=true for overview)
+- bereach_state_get: get state for a key
+- bereach_state_set: save/replace state
+- bereach_state_patch: merge fields into state
+- bereach_state_delete: delete state
+
+## Rules
+
+- Dedup: pass campaignSlug on every action. Duplicates return duplicate:true, cost nothing.
+- Visit before connecting: looks natural to LinkedIn.
+- Connection requests: 30/day. Check pendingConnection from visit response first.
+- Credits: when isUnlimited=true, skip credit budgeting.
+- Language: respond in user's language. DMs: match conversation language.
+- Formatting: tables for contacts (Name, Title, Company, Score). No raw IDs/URNs.
+- Auto-save: visitProfile, findConversation, collectComments, collectLikes, collectPosts, searchPeople and other scrape/search tools all auto-create/update contacts. Do NOT manually save profile or conversation data. Do NOT use contacts.upsertContacts for data that was just scraped/visited.
+- State saves: only save pipeline progress (phase, scraped sources) to agentState. Never store profile data in state.
+
+## Sub-Skills — MANDATORY Loading Table
+
+You MUST load the corresponding sub-skill BEFORE attempting any task that matches
+the triggers below. The tool listing above is for quick lookups only — workflows
+require the full sub-skill instructions.
+
+| Sub-skill     | LOAD WHEN user request matches ANY of these        | Path                 |
+| ------------- | -------------------------------------------------- | -------------------- |
+| Lead Gen      | find leads, search prospects, scrape engagement,   | sub/lead-gen.md      |
+|               | build pipeline, qualify contacts, enrich profiles, |                      |
+|               | ICP, funnel, grow database, hashtag, Sales Nav     |                      |
+| Lead Magnet   | comment-to-DM, resource delivery, post giveaway,   | sub/lead-magnet.md   |
+|               | auto-accept invitations, lead magnet campaign      |                      |
+| SDK Reference | write script, generate code, TypeScript, SDK,      | sdk-reference.md     |
+|               | automate, method signature, batch job              |                      |
+
+Detection: scan the user's message for these concepts regardless of language.
+"Trouve-moi des leads" = Lead Gen. "Set up a comment giveaway" = Lead Magnet.
+When in doubt, load the skill — false positives cost nothing, false negatives
+mean the agent operates without critical workflow knowledge.
+
+NEVER attempt a multi-step lead gen, lead magnet, or script generation workflow
+using only the tool listing above. Always load the sub-skill first.
+
+<!-- /bereach-workspace -->

package/src/commands/setup.ts

@@ -0,0 +1,37 @@
+import { getClient } from "../client";
+
+const API_BASE = "https://api.berea.ch";
+
+export function registerSetupCommand(api: any) {
+  if (!api?.registerCommand) return;
+  api.registerCommand({
+    name: "bereach-setup",
+    description: "Set up or re-initialize BeReach workspace (SOUL.md, crons). Run after first install or to force-refresh.",
+    handler: async () => {
+      try {
+        const res = await fetch(`${API_BASE}/api/onboarding/soul`);
+        if (!res.ok) {
+          return { text: `Failed to fetch SOUL template: ${res.status} ${res.statusText}` };
+        }
+        const { soul } = await res.json();
+
+        return {
+          text: [
+            "BeReach setup ready. To complete setup:",
+            "",
+            "1. Copy the SOUL.md template below into your workspace SOUL.md",
+            "   (between the <!-- bereach-workspace-v2 --> markers)",
+            "",
+            "2. Set up the pipeline cron (every 15min):",
+            '   openclaw cron add --name "BeReach Pipeline" --expr "*/15 * * * *"',
+            "",
+            "Template content has been loaded. Say 'apply bereach setup' to have me write it.",
+          ].join("\n"),
+          data: { soulTemplate: soul },
+        };
+      } catch (err) {
+        return { text: `BeReach setup failed: ${err instanceof Error ? err.message : String(err)}` };
+      }
+    },
+  });
+}

package/src/index.ts

@@ -1,6 +1,9 @@
 import { setApiKey } from "./client";
 import { registerAllTools } from "./tools";
 import { registerCommands } from "./commands";
+import { registerSetupCommand } from "./commands/setup";
+
+const BEREACH_MARKER = "bereach-workspace-v";
 
 function getApiKey(api: any): string | undefined {
   const key =
@@ -15,4 +18,22 @@ export default function register(api: any) {
   setApiKey(apiKey);
   registerAllTools(api);
   registerCommands(api);
+  registerSetupCommand(api);
+
+  if (api.on) {
+    api.on("before_agent_start", async (ctx: any) => {
+      try {
+        const soulContent = ctx?.bootstrapFiles?.["SOUL.md"] ?? ctx?.soul ?? "";
+        if (typeof soulContent === "string" && !soulContent.includes(BEREACH_MARKER)) {
+          if (ctx.addSystemNote) {
+            ctx.addSystemNote(
+              "BeReach workspace not configured. Load the BeReach skill for initial setup, or run /bereach-setup."
+            );
+          }
+        }
+      } catch {
+        // Hook errors should never break agent startup
+      }
+    });
+  }
 }

package/src/test-sdk-methods.mts

@@ -0,0 +1,284 @@
+/**
+ * Exhaustive SDK method verification test.
+ *
+ * Validates that ALL methods documented in sdk-reference.md actually exist
+ * on the bereach@1.3.2 SDK class with the correct getter paths.
+ *
+ * Run: npx tsx src/test-sdk-methods.mts
+ */
+
+import { Bereach } from "bereach";
+
+const sdk = new Bereach({ token: "test-verification-only" });
+
+interface MethodCheck {
+  getter: string;
+  method: string;
+  source: "sdk" | "docs" | "both";
+}
+
+const EXPECTED_SDK_METHODS: MethodCheck[] = [
+  // ── scrapers (Scrapers) ────────────────────────────────────────
+  { getter: "scrapers", method: "collectPosts", source: "both" },
+  { getter: "scrapers", method: "visitProfile", source: "both" },
+
+  // ── linkedinScrapers (LinkedinScrapers1) ────────────────────────
+  { getter: "linkedinScrapers", method: "collectLikes", source: "both" },
+  { getter: "linkedinScrapers", method: "collectComments", source: "both" },
+  { getter: "linkedinScrapers", method: "visitCompany", source: "both" },
+  { getter: "linkedinScrapers", method: "listSavedPosts", source: "both" },
+  { getter: "linkedinScrapers", method: "collectHashtagPosts", source: "both" },
+
+  // ── linkedInScrapers (LinkedInScrapers2) ────────────────────────
+  { getter: "linkedInScrapers", method: "collectCommentReplies", source: "both" },
+  { getter: "linkedInScrapers", method: "getFeed", source: "both" },
+
+  // ── linkedInSearch (LinkedInSearch1) ────────────────────────────
+  { getter: "linkedInSearch", method: "search", source: "both" },
+  { getter: "linkedInSearch", method: "searchCompanies", source: "both" },
+  { getter: "linkedInSearch", method: "resolveParameters", source: "both" },
+
+  // ── linkedinSearch (LinkedinSearch2) ────────────────────────────
+  { getter: "linkedinSearch", method: "searchPosts", source: "both" },
+  { getter: "linkedinSearch", method: "searchPeople", source: "both" },
+  { getter: "linkedinSearch", method: "searchJobs", source: "both" },
+  { getter: "linkedinSearch", method: "searchByUrl", source: "both" },
+
+  // ── actions (Actions) ──────────────────────────────────────────
+  { getter: "actions", method: "connectProfile", source: "both" },
+  { getter: "actions", method: "sendMessage", source: "both" },
+  { getter: "actions", method: "listSentInvitations", source: "both" },
+  { getter: "actions", method: "followCompany", source: "both" },
+
+  // ── linkedinActions (LinkedinActions1) ──────────────────────────
+  { getter: "linkedinActions", method: "listInvitations", source: "both" },
+  { getter: "linkedinActions", method: "acceptInvitation", source: "both" },
+  { getter: "linkedinActions", method: "replyToComment", source: "both" },
+  { getter: "linkedinActions", method: "likePost", source: "both" },
+  { getter: "linkedinActions", method: "withdrawInvitation", source: "both" },
+  { getter: "linkedinActions", method: "followProfile", source: "both" },
+  { getter: "linkedinActions", method: "editPost", source: "both" },
+  { getter: "linkedinActions", method: "editComment", source: "both" },
+  { getter: "linkedinActions", method: "repostPost", source: "both" },
+  { getter: "linkedinActions", method: "unlikePost", source: "both" },
+  { getter: "linkedinActions", method: "unlikeComment", source: "both" },
+  { getter: "linkedinActions", method: "unsavePost", source: "both" },
+  { getter: "linkedinActions", method: "unfollowCompany", source: "both" },
+
+  // ── linkedInActions (LinkedInActions2) ──────────────────────────
+  { getter: "linkedInActions", method: "likeComment", source: "both" },
+  { getter: "linkedInActions", method: "publishPost", source: "both" },
+  { getter: "linkedInActions", method: "createComment", source: "both" },
+  { getter: "linkedInActions", method: "declineInvitation", source: "both" },
+  { getter: "linkedInActions", method: "unfollowProfile", source: "both" },
+  { getter: "linkedInActions", method: "savePost", source: "both" },
+
+  // ── profile (Profile) ─────────────────────────────────────────
+  { getter: "profile", method: "get", source: "both" },
+  { getter: "profile", method: "listAccounts", source: "both" },
+  { getter: "profile", method: "updateAccount", source: "both" },
+  { getter: "profile", method: "refresh", source: "both" },
+  { getter: "profile", method: "getPosts", source: "both" },
+  { getter: "profile", method: "getFollowers", source: "both" },
+  { getter: "profile", method: "getLimits", source: "both" },
+  { getter: "profile", method: "getCredits", source: "both" },
+  { getter: "profile", method: "getProfileViews", source: "both" },
+  { getter: "profile", method: "getSearchAppearances", source: "both" },
+  { getter: "profile", method: "getPostAnalytics", source: "both" },
+  { getter: "profile", method: "getFollowerAnalytics", source: "both" },
+
+  // ── companyPages (CompanyPages) ────────────────────────────────
+  { getter: "companyPages", method: "list", source: "both" },
+  { getter: "companyPages", method: "getPosts", source: "both" },
+  { getter: "companyPages", method: "getPermissions", source: "both" },
+  { getter: "companyPages", method: "getAnalytics", source: "both" },
+
+  // ── linkedinChat (LinkedinChat1) ──────────────────────────────
+  { getter: "linkedinChat", method: "listInboxConversations", source: "both" },
+  { getter: "linkedinChat", method: "getMessages", source: "both" },
+  { getter: "linkedinChat", method: "markAllRead", source: "both" },
+  { getter: "linkedinChat", method: "listArchived", source: "both" },
+  { getter: "linkedinChat", method: "react", source: "both" },
+  { getter: "linkedinChat", method: "sendTypingIndicator", source: "both" },
+  { getter: "linkedinChat", method: "getUnreadCount", source: "both" },
+
+  // ── chat (Chat) ───────────────────────────────────────────────
+  { getter: "chat", method: "searchConversations", source: "both" },
+  { getter: "chat", method: "findConversation", source: "both" },
+  { getter: "chat", method: "archive", source: "both" },
+  { getter: "chat", method: "unreact", source: "both" },
+
+  // ── linkedInChat (LinkedInChat2) ──────────────────────────────
+  { getter: "linkedInChat", method: "markSeen", source: "both" },
+  { getter: "linkedInChat", method: "star", source: "both" },
+  { getter: "linkedInChat", method: "unstar", source: "both" },
+  { getter: "linkedInChat", method: "listStarred", source: "both" },
+  { getter: "linkedInChat", method: "unarchive", source: "both" },
+
+  // ── campaigns (Campaigns) ─────────────────────────────────────
+  { getter: "campaigns", method: "filter", source: "sdk" },
+  { getter: "campaigns", method: "getStatus", source: "both" },
+  { getter: "campaigns", method: "sync", source: "both" },
+  { getter: "campaigns", method: "getStats", source: "both" },
+
+  // ── contacts (Contacts) ───────────────────────────────────────
+  { getter: "contacts", method: "upsert", source: "both" },
+
+  // ── salesNavigatorSearch (SalesNavigatorSearch) ────────────────
+  { getter: "salesNavigatorSearch", method: "search", source: "both" },
+  { getter: "salesNavigatorSearch", method: "searchCompanies", source: "both" },
+
+  // ── salesNav (SalesNav) ───────────────────────────────────────
+  { getter: "salesNav", method: "searchPeople", source: "both" },
+];
+
+// Also verify the plugin definitions.ts handler strings
+const PLUGIN_HANDLERS = [
+  "linkedinScrapers.collectLikes",
+  "linkedinScrapers.collectComments",
+  "linkedInScrapers.collectCommentReplies",
+  "scrapers.collectPosts",
+  "scrapers.visitProfile",
+  "linkedinScrapers.visitCompany",
+  "linkedinScrapers.collectHashtagPosts",
+  "linkedinScrapers.listSavedPosts",
+  "linkedInSearch.search",
+  "linkedinSearch.searchPosts",
+  "linkedinSearch.searchPeople",
+  "linkedInSearch.searchCompanies",
+  "linkedinSearch.searchJobs",
+  "linkedinSearch.searchByUrl",
+  "linkedInSearch.resolveParameters",
+  "actions.connectProfile",
+  "linkedinActions.listInvitations",
+  "linkedinActions.acceptInvitation",
+  "actions.sendMessage",
+  "linkedinActions.replyToComment",
+  "linkedInActions.likeComment",
+  "linkedInActions.publishPost",
+  "linkedinActions.likePost",
+  "linkedInActions.createComment",
+  "linkedinActions.followProfile",
+  "actions.listSentInvitations",
+  "linkedinActions.withdrawInvitation",
+  "chat.archive",
+  "linkedinChat.listInboxConversations",
+  "chat.searchConversations",
+  "chat.findConversation",
+  "linkedinChat.getMessages",
+  "profile.get",
+  "profile.refresh",
+  "profile.getPosts",
+  "profile.getFollowers",
+  "profile.getLimits",
+  "profile.getCredits",
+  "profile.getProfileViews",
+  "linkedInScrapers.getFeed",
+  "campaigns.getStatus",
+  "campaigns.sync",
+  "campaigns.getStats",
+];
+
+let pass = 0;
+let fail = 0;
+const failures: string[] = [];
+
+console.log("=== BeReach SDK v1.3.2 Method Verification ===\n");
+
+// Part 1: Verify all expected getters exist on SDK
+console.log("--- Part 1: Getter existence ---\n");
+const getterNames = [...new Set(EXPECTED_SDK_METHODS.map((m) => m.getter))];
+for (const getter of getterNames) {
+  const ns = (sdk as Record<string, unknown>)[getter];
+  if (ns && typeof ns === "object") {
+    console.log(`  PASS  sdk.${getter} exists (${ns.constructor.name})`);
+    pass++;
+  } else {
+    console.log(`  FAIL  sdk.${getter} is missing or not an object`);
+    failures.push(`Getter sdk.${getter} missing`);
+    fail++;
+  }
+}
+
+// Part 2: Verify all expected methods exist on the correct getter
+console.log("\n--- Part 2: Method existence (78 expected) ---\n");
+for (const { getter, method } of EXPECTED_SDK_METHODS) {
+  const ns = (sdk as Record<string, unknown>)[getter] as
+    | Record<string, unknown>
+    | undefined;
+  if (!ns) {
+    console.log(`  FAIL  sdk.${getter}.${method} — getter missing`);
+    failures.push(`sdk.${getter}.${method} — getter missing`);
+    fail++;
+    continue;
+  }
+  if (typeof ns[method] === "function") {
+    console.log(`  PASS  sdk.${getter}.${method}`);
+    pass++;
+  } else {
+    console.log(`  FAIL  sdk.${getter}.${method} — not a function (got ${typeof ns[method]})`);
+    failures.push(`sdk.${getter}.${method} — not a function`);
+    fail++;
+  }
+}
+
+// Part 3: Verify all plugin handler strings resolve to real SDK methods
+console.log("\n--- Part 3: Plugin handler verification ---\n");
+for (const handler of PLUGIN_HANDLERS) {
+  const [getter, method] = handler.split(".");
+  const ns = (sdk as Record<string, unknown>)[getter] as
+    | Record<string, unknown>
+    | undefined;
+  if (!ns) {
+    console.log(`  FAIL  handler "${handler}" — getter sdk.${getter} missing`);
+    failures.push(`Plugin handler "${handler}" — getter missing`);
+    fail++;
+    continue;
+  }
+  if (typeof ns[method] === "function") {
+    console.log(`  PASS  handler "${handler}"`);
+    pass++;
+  } else {
+    console.log(`  FAIL  handler "${handler}" — method not a function`);
+    failures.push(`Plugin handler "${handler}" — method not found`);
+    fail++;
+  }
+}
+
+// Part 4: Detect undocumented SDK methods (methods on getters not in our list)
+console.log("\n--- Part 4: Undocumented SDK methods (on getters but not in docs) ---\n");
+const documentedMethods = new Set(
+  EXPECTED_SDK_METHODS.map((m) => `${m.getter}.${m.method}`)
+);
+for (const getter of getterNames) {
+  const ns = (sdk as Record<string, unknown>)[getter] as
+    | Record<string, unknown>
+    | undefined;
+  if (!ns) continue;
+  const proto = Object.getPrototypeOf(ns);
+  const allProps = [
+    ...Object.getOwnPropertyNames(proto),
+    ...Object.getOwnPropertyNames(ns),
+  ];
+  for (const prop of allProps) {
+    if (prop === "constructor" || prop.startsWith("_") || prop.startsWith("#")) continue;
+    const key = `${getter}.${prop}`;
+    if (!documentedMethods.has(key) && typeof (ns as Record<string, unknown>)[prop] === "function") {
+      console.log(`  WARN  Undocumented: sdk.${key}()`);
+    }
+  }
+}
+
+// Summary
+console.log("\n=== SUMMARY ===");
+console.log(`  Total checks: ${pass + fail}`);
+console.log(`  Passed: ${pass}`);
+console.log(`  Failed: ${fail}`);
+if (failures.length > 0) {
+  console.log("\n  FAILURES:");
+  for (const f of failures) {
+    console.log(`    - ${f}`);
+  }
+}
+console.log("");
+process.exit(fail > 0 ? 1 : 0);

package/src/tools/definitions.ts

@@ -22,7 +22,7 @@ export const definitions: ToolDefinition[] = [
 
   {
     name: "bereach_collect_likes",
-    description: "Scrape LinkedIn post likes. Returns paginated list of profiles who liked a post.",
+    description: "Scrape LinkedIn post likes. Returns paginated list of profiles who liked a post. Auto-creates a contact record for each liker.",
     handler: "linkedinScrapers.collectLikes",
     parameters: {
       type: "object",
@@ -37,7 +37,7 @@ export const definitions: ToolDefinition[] = [
 
   {
     name: "bereach_collect_comments",
-    description: "Scrape LinkedIn post comments. Returns paginated list of commenters with comment text and URNs.",
+    description: "Scrape LinkedIn post comments. Returns paginated list of commenters with comment text and URNs. Auto-creates a contact record for each commenter.",
     handler: "linkedinScrapers.collectComments",
     parameters: {
       type: "object",
@@ -53,7 +53,7 @@ export const definitions: ToolDefinition[] = [
 
   {
     name: "bereach_collect_comment_replies",
-    description: "Scrape replies to a LinkedIn comment. Returns paginated replies for a specific comment URN.",
+    description: "Scrape replies to a LinkedIn comment. Returns paginated replies for a specific comment URN. Auto-creates a contact record for each replier.",
     handler: "linkedInScrapers.collectCommentReplies",
     parameters: {
       type: "object",
@@ -68,7 +68,7 @@ export const definitions: ToolDefinition[] = [
 
   {
     name: "bereach_collect_posts",
-    description: "Scrape LinkedIn profile posts. Returns paginated list of posts from a profile.",
+    description: "Scrape LinkedIn profile posts. Returns paginated list of posts from a profile. Auto-creates/updates a contact for the profile.",
     handler: "scrapers.collectPosts",
     parameters: {
       type: "object",
@@ -84,7 +84,7 @@ export const definitions: ToolDefinition[] = [
 
   {
     name: "bereach_visit_profile",
-    description: "Visit LinkedIn profile and extract contact data. Distance-1 profiles cached 24h. No dedup — always executes.",
+    description: "Visit LinkedIn profile and extract contact data. Distance-1 profiles cached 24h. No dedup — always executes. Auto-saves full profileData to the contact record.",
     handler: "scrapers.visitProfile",
     parameters: {
       type: "object",
@@ -113,7 +113,7 @@ export const definitions: ToolDefinition[] = [
 
   {
     name: "bereach_collect_hashtag_posts",
-    description: "Scrape LinkedIn posts for a given hashtag. Lead-gen channel for topical prospecting. 1 credit.",
+    description: "Scrape LinkedIn posts for a given hashtag. Lead-gen channel for topical prospecting. 1 credit. Auto-creates a contact for each post author.",
     handler: "linkedinScrapers.collectHashtagPosts",
     parameters: {
       type: "object",
@@ -179,7 +179,7 @@ export const definitions: ToolDefinition[] = [
 
   {
     name: "bereach_search_posts",
-    description: "Search LinkedIn posts by keywords with optional filters for date, content type, author industry, and author company.",
+    description: "Search LinkedIn posts by keywords with optional filters for date, content type, author industry, and author company. Auto-creates a contact for each post author.",
     handler: "linkedinSearch.searchPosts",
     parameters: {
       type: "object",
@@ -200,7 +200,7 @@ export const definitions: ToolDefinition[] = [
 
   {
     name: "bereach_search_people",
-    description: "Search LinkedIn people by keywords, connection degree, name, title, location, industry, company, and school.",
+    description: "Search LinkedIn people by keywords, connection degree, name, title, location, industry, company, and school. Auto-creates a contact for each result.",
     handler: "linkedinSearch.searchPeople",
     parameters: {
       type: "object",
@@ -341,13 +341,14 @@ export const definitions: ToolDefinition[] = [
 
   {
     name: "bereach_send_message",
-    description: "Send LinkedIn message. Rate limited to 150 messages per day.",
+    description: "Send LinkedIn message. Rate limited to 150 messages per day. Provide profile OR conversationUrn (at least one required). Use conversationUrn to bypass profile URL lookup for contacts with garbled LinkedIn URLs.",
     handler: "actions.sendMessage",
     parameters: {
       type: "object",
-      required: ["profile", "message"],
+      required: ["message"],
       properties: {
-        profile: { type: "string", description: "LinkedIn profile URL or profile URN." },
+        profile: { type: "string", description: "LinkedIn profile URL or profile URN. Optional if conversationUrn is provided." },
+        conversationUrn: { type: "string", description: "LinkedIn conversation URN from contact's conversationData. Preferred when profile URL is unavailable or invalid." },
         message: { type: "string", description: "Message content to send." },
         campaignSlug: { type: "string", description: "Campaign identifier for deduplication." },
       },
@@ -529,7 +530,7 @@ export const definitions: ToolDefinition[] = [
 
   {
     name: "bereach_find_conversation",
-    description: "Find a conversation with a specific person. Direct O(1) lookup via LinkedIn's compose API. 0 credits.",
+    description: "Find a conversation with a specific person. Direct O(1) lookup via LinkedIn's compose API. 0 credits. Auto-saves conversationData to the contact record.",
     handler: "chat.findConversation",
     parameters: {
       type: "object",
@@ -948,7 +949,7 @@ export const definitions: ToolDefinition[] = [
 
   {
     name: "bereach_contacts_upsert",
-    description: "Create or upsert contacts without a campaign. The organic flow: save contacts as you discover them, campaign optional. Upserts by LinkedIn URL — if the contact already exists, updates name and optional fields. Returns full contact objects with IDs so you can immediately log activities. 0 credits.",
+    description: "Create or upsert contacts without a campaign. For MANUAL IMPORTS ONLY (CSV, spreadsheets, user-provided lists). Most scrape/search/visit calls auto-create contacts — do not use this for data that was just scraped or visited. Upserts by LinkedIn URL. 0 credits.",
     handler: "contacts.upsertContacts",
     apiPath: "/api/contacts",
     apiMethod: "POST",

package/src/tools/index.ts

@@ -6,18 +6,22 @@ type ResourceMap = {
   [K in keyof Bereach as Bereach[K] extends object ? K : never]: Bereach[K];
 };
 
-const API_BASE = process.env.BEREACH_API_URL ?? "https://app.berea.ch";
+const API_BASE = "https://api.berea.ch";
+
+const MAX_RETRIES = 2;
 
 async function executeApiCall(def: ToolDefinition, params: Record<string, unknown>, apiKey: string) {
   let path = def.apiPath!;
   const method = def.apiMethod ?? "POST";
 
-  // Resolve path parameters like {campaignId}, {contactId}, {key}
   const bodyParams = { ...params };
   path = path.replace(/\{(\w+)\}/g, (_, name) => {
     const val = bodyParams[name];
+    if (val === undefined || val === null || val === "") {
+      throw new Error(`Missing required parameter: ${name} for ${def.apiPath}`);
+    }
     delete bodyParams[name];
-    return encodeURIComponent(String(val ?? ""));
+    return encodeURIComponent(String(val));
   });
 
   let url = `${API_BASE}${path}`;
@@ -31,21 +35,47 @@ async function executeApiCall(def: ToolDefinition, params: Record<string, unknow
     if (qsStr) url += `?${qsStr}`;
   }
 
-  const resp = await fetch(url, {
-    method,
-    headers: {
-      Authorization: `Bearer ${apiKey}`,
-      "Content-Type": "application/json",
-    },
-    ...(method !== "GET" ? { body: JSON.stringify(bodyParams) } : {}),
-  });
+  let lastError: Error | null = null;
+
+  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+    try {
+      const resp = await fetch(url, {
+        method,
+        headers: {
+          Authorization: `Bearer ${apiKey}`,
+          "Content-Type": "application/json",
+        },
+        ...(method !== "GET" ? { body: JSON.stringify(bodyParams) } : {}),
+      });
 
-  if (!resp.ok) {
-    const errorBody = await resp.text();
-    throw new Error(`API ${method} ${path} failed (${resp.status}): ${errorBody}`);
+      if (resp.status === 429) {
+        const retryAfter = resp.headers.get("retry-after");
+        const waitMs = retryAfter ? parseInt(retryAfter, 10) * 1000 : Math.pow(2, attempt + 1) * 1000;
+        if (attempt < MAX_RETRIES) {
+          await new Promise((r) => setTimeout(r, waitMs));
+          continue;
+        }
+        const body = await resp.text();
+        throw new Error(`Rate limited on ${path}. ${body}`);
+      }
+
+      if (!resp.ok) {
+        const errorBody = await resp.text();
+        throw new Error(`API ${method} ${path} failed (${resp.status}): ${errorBody}`);
+      }
+
+      return resp.json();
+    } catch (err) {
+      lastError = err instanceof Error ? err : new Error(String(err));
+      if (attempt < MAX_RETRIES && !(lastError.message.includes("failed (") || lastError.message.includes("Rate limited"))) {
+        await new Promise((r) => setTimeout(r, Math.pow(2, attempt + 1) * 1000));
+        continue;
+      }
+      throw lastError;
+    }
   }
 
-  return resp.json();
+  throw lastError ?? new Error(`Failed after ${MAX_RETRIES + 1} attempts`);
 }
 
 /**