@sellable/mcp 0.1.31 → 0.1.32

package/skills/create-campaign/SKILL.md

@@ -4,6 +4,8 @@ description: Create a Sellable campaign through the approval-gated workflow.
 visibility: public
 allowed-tools:
   - mcp__sellable__get_auth_status
+  - mcp__sellable__start_cli_login
+  - mcp__sellable__wait_for_cli_login
   - mcp__sellable__bootstrap_create_campaign
   - mcp__sellable__get_subskill_prompt
   - mcp__sellable__search_subskill_prompts
@@ -323,14 +325,73 @@ plugin cache paths, MCP namespaces, or runbooks in customer-facing progress
 updates.
 
 1. Call `mcp__sellable__get_auth_status({})`.
-2. If auth is not OK, stop and show the returned guidance.
-3. Detect optional campaign id in the user request (`cmp_...`).
-4. If no campaign id is provided, stay in fresh-create mode and do not call campaign discovery/resume helpers to find one.
+2. If auth is not OK with `error.type === "config"` or `error.type === "auth"`,
+   the user has not signed in yet. Run the FTUX magic-link handoff:
+
+   a. Say to the user verbatim:
+
+   ```text
+   Welcome to Sellable. What's your email?
+   ```
+
+   b. Wait for the user to paste their email in normal chat. Do NOT use
+   `AskUserQuestion` / `request_user_input` for this — it's free-text input.
+
+   c. Call `mcp__sellable__start_cli_login({ email })` with the email the user
+   typed.
+
+   d. If `start_cli_login` returns `ok: false`, surface `error.guidance` to the
+   user and stop. Do not retry automatically.
+
+   e. On `ok: true`, say to the user verbatim (substituting the email exactly
+   as the user typed it):
+
+   ```text
+   Magic link sent to {email}. Click it from your inbox — I'll wait. (If your team already has a Sellable workspace, ask an admin to invite you instead — that gets you straight into their data.)
+   ```
+
+   f. Call `mcp__sellable__wait_for_cli_login({ sessionId })` using the
+   `sessionId` returned by `start_cli_login`.
+
+   - If the result is `error.type === "tool_timeout_guard"`, IMMEDIATELY
+     re-call `mcp__sellable__wait_for_cli_login({ sessionId })` with the
+     SAME sessionId. Do not narrate anything to the user. Do not call
+     `start_cli_login` again — that would send a new magic link and confuse
+     them. Loop on `tool_timeout_guard` until you get a different result.
+
+   - If `error.type === "expired"` or `error.type === "timeout"`, say to the
+     user verbatim and stop:
+
+     ```text
+     That magic link expired. Run /sellable:create-campaign again to retry.
+     ```
+
+   - If `error.type === "already_consumed"` or any other error, surface
+     `error.guidance` and stop.
+
+   - On `ok: true`, the user is signed in and `~/.sellable/config.json` has
+     been written. Your IMMEDIATE next visible message MUST be the locked
+     Step 3 narration verbatim (no welcome line, no "all set", no "you're
+     signed in", no acknowledgement of any kind):
+
+     ```text
+     Now — paste the LinkedIn profile URL of the person you want to send from.
+     ```
+
+     After the user pastes the URL, proceed with the existing identity-first
+     sender flow (Step 3 onwards in the v2 subskill prompt — sender
+     enrichment via `fetch_linkedin_profile` / `enrich_sender`).
+
+3. If auth is not OK with `error.type === "workspace"` (token valid, no active
+   workspace), stop and show the returned guidance — that's not a fresh-user
+   scenario; the user needs to run `set_active_workspace`.
+4. Detect optional campaign id in the user request (`cmp_...`).
+5. If no campaign id is provided, stay in fresh-create mode and do not call campaign discovery/resume helpers to find one.
    - Do not call `mcp__sellable__get_campaigns`.
    - Do not call `mcp__sellable__get_campaign` to hunt for IDs.
    - Do not call `mcp__sellable__create_campaign({ campaignId: ... })` unless the user supplied that id.
-5. Call `mcp__sellable__bootstrap_create_campaign({ flowVersion: "v2", campaignId? })`.
-6. If `safeToProceed !== true`, stop and show `blockingErrors` + `nextStep`.
+6. Call `mcp__sellable__bootstrap_create_campaign({ flowVersion: "v2", campaignId? })`.
+7. If `safeToProceed !== true`, stop and show `blockingErrors` + `nextStep`.
 
 ## Execute Workflow
 

package/skills/create-campaign-v2/core/flow.v2.json

@@ -102,7 +102,6 @@
           "allowedTools": [
             "list_senders",
             "get_sender",
-            "enrich_sender",
             "fetch_company",
             "fetch_linkedin_profile",
             "WebFetch",
@@ -174,7 +173,6 @@
         "get_active_workspace",
         "list_senders",
         "get_sender",
-        "enrich_sender",
         "complete_sender_research",
         "fetch_company",
         "fetch_company_posts",

package/skills/research-sender/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: research-sender
-description: Parallel-first sender research protocol. One round of batched tool calls, ~10-15s wall time.
+description: "Parallel-first sender research protocol. One round of five batched tool calls (fetch_linkedin_profile + fetch_company + 3× WebSearch), no enrich_sender required, ~30-40s wall time."
 visibility: internal
+allowed-tools: mcp__sellable__fetch_linkedin_profile mcp__sellable__fetch_company mcp__sellable__complete_sender_research WebSearch ToolSearch
 ---
 
 # Research Sender (Parallel-First)
@@ -12,28 +13,36 @@ This protocol is standalone and does not depend on the generic `research` subski
 ## Core Idea — Don't Wait, Fan Out
 
 Old protocol: call `enrich_sender` → wait for partial → maybe spawn 2-3 subagents → wait.
-That's 3-4 sequential rounds and ~60s+ wall time.
+That's 3-4 sequential rounds and ~88s+ wall time.
 
-New protocol: **fire one parallel batch.** `enrich_sender` (5-8s, returns
-`clientProspectId` + baseline) runs alongside 2-3 `WebSearch` calls. They all
-finish in the same ~10s window, then you synthesize.
+New protocol: **fire one parallel batch.** No `enrich_sender` precondition.
+`fetch_linkedin_profile` (sender background), `fetch_company` (company description /
+industry / employees), and 3× `WebSearch` (proof, growth, positioning) all run in the
+same window. They finish in ~10-15s if truly parallel, ~30-40s when the model
+serializes (interactive mode is best-effort, headless `claude -p` always serializes).
 
-The `enrich_sender` call is still required because downstream tools
-(`create_campaign`, `attach_sequence`, message generation) need the
-`clientProspectId` it produces and the cached `EnrichedProspect` row it writes.
-Don't skip it — just stop waiting for it before doing the rest of the research.
+Then synthesize once into the campaign brief — the brief is what downstream
+message generation reads, not a `clientProspect` row. `clientProspectId` is
+optional in `create_campaign`; pass `senderLinkedinUrl` instead.
 
 ## Inputs
 
 Provide as many as available. Use `"Unknown"` for missing values.
 
-- `linkedinUrl` (REQUIRED)
+- `linkedinUrl` (REQUIRED — drives `fetch_linkedin_profile`)
 - `name`
 - `title`
 - `companyName`
-- `companyDomain` (REQUIRED for WebSearch — derive from email or LinkedIn if absent)
+- `companyDomain` (REQUIRED — drives `fetch_company` and all three WebSearch queries; derive from email or LinkedIn if absent)
 - `headline` (optional)
 
+## Execution Backend Routing
+
+This skill runs differently depending on the host:
+
+- **Claude Code host:** the parallel batch uses MCP tools directly — `mcp__sellable__fetch_linkedin_profile`, `mcp__sellable__fetch_company`, and `WebSearch`. Issue all five calls as `tool_use` blocks in a single assistant message.
+- **Codex host:** if MCP `fetch_*` tools are not available, fall back to web-fetch equivalents — use the LinkedIn URL with WebFetch for the sender profile, fetch the company's `/about` page for company facts, and use the same three WebSearch queries below for proof / growth / positioning. Synthesis treats both backends identically.
+
 ## Setup: Pre-Load Deferred Tools (One-Time, Before The Parallel Batch)
 
 Some hosts (Claude Code with deferred-tool fetch) require `WebSearch` and
@@ -41,27 +50,28 @@ some MCP tools to be loaded via `ToolSearch` before they can be invoked. If
 they are not already directly callable, issue this once as the first tool
 call, on its own:
 
-`ToolSearch({ query: "select:WebSearch,mcp__sellable__enrich_sender,mcp__sellable__complete_sender_research", max_results: 5 })`
+`ToolSearch({ query: "select:WebSearch,mcp__sellable__fetch_linkedin_profile,mcp__sellable__fetch_company,mcp__sellable__complete_sender_research", max_results: 5 })`
 
 Skip this turn entirely if the tools are already directly callable.
 
 ## The One Round (Parallel Batch)
 
-**HARD RULE:** the four tool calls below MUST be emitted as **four `tool_use`
+**HARD RULE:** the five tool calls below MUST be emitted as **five `tool_use`
 content blocks inside a single assistant message** (one turn, parallel
 execution). Do NOT split them across multiple assistant messages.
 
-Concretely, your next assistant message must contain exactly these four
+Concretely, your next assistant message must contain exactly these five
 `tool_use` blocks, in any order, with no leading or trailing prose:
 
-1. `enrich_sender({ linkedinUrl, companyDomain })` — baseline + `clientProspectId`.
-2. `WebSearch({ query: 'site:{companyDomain} ("case study" OR "customer story" OR testimonial OR "success story") "{companyName}"' })` — proof.
-3. `WebSearch({ query: '"{companyName}" {companyDomain} {currentYear} (funding OR raised OR seed OR series OR hiring OR launch OR "press release")' })` — growth/credibility.
-4. `WebSearch({ query: '"{companyName}" about product site:{companyDomain}' })` — positioning.
+1. `fetch_linkedin_profile({ linkedinUrl })` — sender's LinkedIn profile (firstName/lastName, currentCompany, experience, follower count, education) for the brief's "sender background" section.
+2. `fetch_company({ companyDomain })` — sender's company LinkedIn page (description, industry, employee range, recent posts). REQUIRED — replaces what `enrich_sender` used to provide for `companySnapshot`.
+3. `WebSearch({ query: 'site:{companyDomain} ("case study" OR "customer story" OR testimonial OR "success story") "{companyName}"' })` — proof.
+4. `WebSearch({ query: '"{companyName}" {companyDomain} {currentYear} (funding OR raised OR seed OR series OR hiring OR launch OR "press release")' })` — growth/credibility.
+5. `WebSearch({ query: '"{companyName}" about product site:{companyDomain}' })` — positioning.
 
-**Self-check before you reply:** if your reply contains fewer than four
+**Self-check before you reply:** if your reply contains fewer than five
 `tool_use` blocks (after the optional `ToolSearch` setup turn), you are
-violating the protocol. Stop, rewrite the reply with all four.
+violating the protocol. Stop, rewrite the reply with all five.
 
 **Known limitation (`claude -p` headless mode):** Claude often serializes
 these calls one-per-turn even with explicit instructions. That's fine — the
@@ -69,35 +79,63 @@ skill still produces the same output, just with sequential tool execution
 (~30–40s total wall time vs. ~10–15s if truly parallelized). If you can
 batch, do; if not, proceed sequentially without retrying or re-prompting.
 
-No subagent fan-out. No second round of enrichment polling.
+No subagent fan-out. No second round of enrichment polling. **No `enrich_sender` call.**
 
 ## Synthesis (Single Pass After Batch Returns)
 
-Merge the four results. Treat `enrich_sender` as the authoritative baseline
-for company/sender facts; treat WebSearch as proof and signals.
+Merge the five results into the campaign brief. Treat `fetch_linkedin_profile` and
+`fetch_company` as authoritative for sender/company facts; treat `WebSearch` as
+proof and signals.
 
 ```markdown
 ## {Company} - Sender Research
 
-**Company Context:** [companySnapshot.description OR positioning WebSearch top result]
-**Industry / Size:** [companySnapshot.industry + employeeRange]
-**Positioning Notes:** [proofDigest.positioningOneLiner + keyDifferentiators]
-**Proof Options:** [proofDigest.caseStudySummary + case-study WebSearch hits — pick 1-3 with named customers / metrics]
-**Credibility Signals:** [proofDigest.reviewHighlight + growth WebSearch hits (funding, hiring, press)]
+**Sender Background:** [from fetch_linkedin_profile — name, current title, follower count, key experience]
+**Company Context:** [from fetch_company.description OR positioning WebSearch top result]
+**Industry / Size:** [from fetch_company.industry + employee range]
+**Positioning Notes:** [positioning WebSearch top results + any positioning one-liner from fetch_company]
+**Proof Options:** [case-study WebSearch hits — pick 1-3 with named customers / metrics]
+**Credibility Signals:** [growth WebSearch hits (funding, hiring, press) + any high-signal posts from fetch_company]
 **Gaps:** [what's still missing — usually fine to ship with this]
 ```
 
-If `enrich_sender` returns `enrichmentStatus: "partial"`, that's expected and
-fine — `companySnapshot` and `senderBackground` are populated immediately.
-`proofDigest` may be null on partial; in that case rely on WebSearch results
-for proof and credibility, not on a second enrichment poll.
+The synthesis result is what feeds the campaign brief, which is what message
+generation reads via `campaignBriefContent` (see `getOfferPositioning()` in
+`prompt.ts:236`). The brief is the load-bearing path now — `clientProspect`
+contributes only fallback context and the sender display name (which is
+resolved from the `Sender` row's profileData when `clientProspect` is null).
+
+### Partial Failure Handling
+
+The five calls run in parallel, so any one of them can fail independently
+(404, rate-limit, timeout). Synthesis MUST still produce a usable brief.
+Apply these rules:
+
+- **If `fetch_company` errors or returns empty:** mark `Company Context` as
+  `[unavailable — fetch_company failed]`. Use the positioning WebSearch top
+  result as a partial substitute. Set `Industry / Size` to `[unavailable]`
+  (do NOT guess). The brief still ships; downstream message generation reads
+  the brief verbatim and is null-safe on missing fields.
+- **If `fetch_linkedin_profile` errors:** fall back to WebSearch-derived
+  sender background. Set `Sender Background` to a one-liner derived from the
+  positioning WebSearch ("found via {companyDomain}/about and other web
+  signals — full LinkedIn profile unavailable").
+- **If a WebSearch errors:** mark the corresponding section
+  (`Proof Options`, `Credibility Signals`, or `Positioning Notes`) as `[no
+results]` and continue. Do NOT retry — one round only.
+- **NEVER skip `complete_sender_research`** even on partial failure. Pass
+  `proofItemsFound: 0`, `caseStudyItemsFound: 0`, `credibilitySignalsFound: 0`
+  for the failed sections so the preflight knows the research ran.
+
+**The contract:** synthesis always produces SOME brief. `complete_sender_research`
+always fires. The brief ships even with gaps; downstream is null-safe.
 
 ## Optional Deepen (Only If Synthesis Reveals A Hard Gap)
 
 If after synthesis you genuinely have zero proof and zero credibility
 signals, AND the campaign fixture/operator told you proof is required, you
 MAY issue ONE additional WebFetch on the most promising case-study URL from
-batch step 2. Cap at one WebFetch. No subagents, no second WebSearch round.
+the proof WebSearch. Cap at one WebFetch. No subagents, no second WebSearch round.
 
 If that still yields nothing, set `proofItemsFound: 0` in
 `complete_sender_research` and proceed; the brief can ship without proof.
@@ -122,7 +160,7 @@ If no reliable evidence is found, set counts to 0 and include that in `notes`.
 Before issuing the parallel batch:
 
 ```
-Pulling sender enrichment + case studies + growth signals + positioning in parallel (~10s)...
+Pulling sender profile + company snapshot + case studies + growth signals + positioning in parallel (~10s)...
 ```
 
 After synthesis:
@@ -133,7 +171,11 @@ Sender research ready — {proofItemsFound} proof items, {credibilitySignalsFoun
 
 ## What Changed From The Previous Protocol
 
+- **Removed `enrich_sender` from the parallel batch entirely.** The MCP `create_campaign` tool now accepts `senderLinkedinUrl` as an alternative to `clientProspectId`. `enrich_sender` itself has been removed from the MCP tool registry — calling it returns "tool not found".
+- Replaced with `fetch_company` (REQUIRED) — provides company description, industry, employee data that `enrich_sender` used to give via `companySnapshot`.
+- Five parallel tool calls instead of four (added `fetch_linkedin_profile` + `fetch_company`, dropped `enrich_sender`).
+- Added explicit Partial Failure Handling — synthesis always produces a brief even when one or two of the five calls error.
 - No "minimal-verification vs deep-proof" branch. Always run the same parallel batch.
-- No spawn of `general-purpose` subagents for research — WebSearch from the orchestrator turn is faster and cheaper.
-- No waiting on `enrich_sender` before issuing WebSearch.
+- No subagent fan-out — WebSearch from the orchestrator turn is faster and cheaper.
+- Synthesis writes to the campaign brief, not to an `EnrichedProspect` row.
 - One round, one synthesis, one `complete_sender_research` call.