@sellable/mcp 0.1.117 → 0.1.119

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sellable/mcp",
-  "version": "0.1.117",
+  "version": "0.1.119",
   "type": "module",
   "description": "Sellable MCP server for Claude Code and Codex campaign workflows",
   "main": "dist/index.js",

package/skills/create-campaign-v2/SKILL.md

@@ -435,19 +435,32 @@ brief`, `Revise target`, `Revise offer/proof`, and `Other / custom`.
   currentStep: "pick-provider", watchNarration: { ... } })` after approval so
   the watch link moves out of Plan while the main thread compares source paths.
 
-- After the brief is approved, show the next progress line:
-  `Cool. Now I'm going to find people who are both a good fit and active enough
-to be worth a LinkedIn test. I see two promising source paths: {source path 1}
-and {source path 2}. I'll launch background source checks for both so we can
-confirm which one is viable before I show results. No leads import until you
-approve the source.`
+- After the brief is approved, show the next progress line. When the user has
+  not given a specific source direction, use the default sequential source
+  funnel:
+  `Cool. I'm going to find people who are both a good fit and active enough to
+be worth a LinkedIn test. I'll start with warm LinkedIn post engagement because
+that gives the strongest message context if enough ICP-looking people are
+engaging. If that does not clear a quick viability check, I'll switch to Sales
+Nav with recent activity, then broader Sales Nav, and use Prospeo only as the
+fallback. No leads import until you approve the source.`
+- If the user's request already points to a source, do not force the default
+  funnel. Start with the matching lane and say why:
+  - specific posts, creators, topics, comments, or engagement signals ->
+    Signal Discovery
+  - title/persona/company filters or broad LinkedIn people search -> Sales Nav
+  - hiring signals, account/domain lists, company growth triggers, email/domain
+    search, or target accounts -> Prospeo
+  - supplied CSV/profile list -> existing/supplied list preview
+  - explicit compare request -> compare only the requested sources
 - In watch mode, do not leave the user sitting on only `pick-provider` while
-  source scouts run. Move the campaign to the likely primary source lane
-  (`signal-discovery`, `sales-nav`, or `prospeo`) before background source
-  scouts, then run the first campaign-attached provider prompt + provider search
-  in the parent thread with `campaignOfferId`, `confirmed: true`, and
-  `currentStep` when the tool accepts it. Background scouts may continue after
-  the visible campaign tab exists.
+  source viability is checked. Move the campaign to the first source lane that
+  will actually be tested (`signal-discovery`, `sales-nav`, `prospeo`, or the
+  user-directed lane), then run the campaign-attached provider prompt + provider
+  search in the parent thread with `campaignOfferId`, `confirmed: true`, and
+  `currentStep` when the tool accepts it. If that lane fails the quick viability
+  gate, update the campaign step and watchNarration before trying the next lane
+  so the user sees the source switch happen in the app.
 - After the lead sample/source decision is ready and approved,
   show the next progress line:
   `Lead source is set. I'll import the first 15-row review batch into the
@@ -787,42 +800,47 @@ Required behavior:
   allowed by `flow.v2.json`
 - only mutate campaign-attached source preview state in the narrow watch-mode
   ways allowed by the active flow step
-- run a real parallel source-angle scout when the source is not supplied and at
-  least two viable source angles exist. Treat source scouting as independent
-  branches, then compare the outputs in `lead-review.md`. Call
-  `get_source_scout_registry` first so new scouts can be added without prompt
-  rewrites. In Codex, explicitly
-  spawn named custom subagents in the same turn when the host exposes them:
-  `source-scout-linkedin-engagement`, `source-scout-sales-nav`, and
-  `source-scout-prospeo-contact` for the credible lanes. Codex does not infer
-  this from generic "compare paths" wording. If the realistic
-  source set is LinkedIn Engagement + Sales Nav (Signals + Sales Nav), run both.
-  If it is LinkedIn Engagement + Prospeo Contact (Signals + Prospeo), run both.
-  If all three are credible, run all three when the host/runtime supports it.
-  In Claude Code, launch the matching `source-scout-linkedin-engagement`,
-  `source-scout-sales-nav`, and/or `source-scout-prospeo-contact` Task/Agent
-  subagents in the same assistant message only when the current session lists
-  those names, not as sequential scout turns. If they are absent, run the same
+- use the default sequential source viability funnel when the user did not
+  specify a source. The goal is to choose a source quickly enough to keep the
+  watched campaign moving, not to compare every plausible lane in parallel.
+  Run only enough evidence for the current lane to pass or fail the quick gate,
+  then stop on the first viable source unless the user asked to compare.
+  1. Start with LinkedIn Engagement / active LinkedIn posts (internal provider:
+     Signals / `signal-discovery`) because recent engagement gives the strongest
+     message context and expected reply-rate upside. Search relevant keyword
+     lanes, review finalist posts, promote the sampled posts with
+     `select_promising_posts` before fetching engagers when a campaign shell
+     exists, fetch top-post engagers, and estimate warm-fit volume.
+  2. If Signals does not have enough recent, relevant, ICP-looking engagers,
+     switch to Sales Nav with recent activity when the target can be expressed
+     as title/persona/company filters. Run preview filters, inspect preview rows,
+     validate the filters applied, and estimate scalable-fit volume.
+  3. If recent-activity Sales Nav is too small or noisy, broaden to normal Sales
+     Nav title + company filters and call out the weaker activity context.
+  4. Use Prospeo Contact only when the campaign has a domain/account path, the
+     user supplied domains, the user asked for hiring/growth/account triggers,
+     or the LinkedIn-first paths fail. Estimate email/contact scale and call out
+     weaker LinkedIn activity.
+- source-specific user direction overrides the default funnel. If the user
+  names hiring signals, account/domain lists, company growth triggers, or target
+  accounts, start with Prospeo. If they supply profiles or a CSV, start with the
+  supplied-list preview. If they name posts, comments, creators, or engagement,
+  start with Signal Discovery. If they name titles/personas/company filters,
+  start with Sales Nav. If they explicitly ask for a comparison, compare only
+  those requested sources.
+- run source scouts in parallel only when the user explicitly requested a
+  comparison, the current turn is resuming from already-started parallel scouts,
+  or the first viable source is borderline and one cheap fallback check is
+  necessary for the recommendation. Call `get_source_scout_registry` first so
+  new scouts can be added without prompt rewrites. In Codex, explicitly spawn
+  named custom subagents in the same turn when the host exposes them:
+  `source-scout-linkedin-engagement` / LinkedIn Engagement Scout,
+  `source-scout-sales-nav`, and `source-scout-prospeo-contact` for the requested
+  or fallback lanes. Codex does not infer this from generic "compare paths"
+  wording. In Claude Code, launch the matching Task/Agent subagents only when
+  the current session lists those names. If they are absent, run the same
   provider probes with MCP tools from the parent thread and keep
   `lead-review.md` focused on source evidence, not host-agent availability.
-  - Branch A: LinkedIn Engagement / active LinkedIn posts (internal provider:
-    Signals / `signal-discovery`). Search relevant keyword lanes, review
-    finalist posts, promote the sampled posts with `select_promising_posts`
-    before fetching engagers when a campaign shell exists, fetch top-post
-    engagers, and estimate warm-fit volume.
-  - Branch B: Sales Nav / title + company filters. Run preview filters, inspect
-    preview rows, and estimate scalable-fit volume.
-  - Branch C: Prospeo Contact / domains only when the campaign has a
-    domain/account path or the user supplied domains. Estimate email/contact
-    scale and call out weaker LinkedIn activity.
-    If the host cannot run these branches in parallel, run them sequentially and
-    do not claim they ran in parallel. If only one source angle is credible, say
-    that and run the best primary source plus one cheap fallback/quality check
-    when available. For Signals-first campaigns, search multiple Signals keyword
-    lanes and fetch top-post engagers in parallel when tool batching allows it.
-    For Sales Nav-first or Prospeo/account-first campaigns, run multiple preview
-    lanes for that provider in parallel and use Signals only as a warmth/quality
-    check when relevant.
 - after every Sales Nav preview, validate that filters actually applied before
   using the lane in `lead-review.md`: `searchUrl` should include filters, the
   first page should match the intended roles/companies, and the result count
@@ -1002,6 +1020,21 @@ user-facing lead review. The visible response must include:
 - `Sample leads` with 3-5 representative `Name — Title, Company` rows
 - `Tradeoff`
 - `Watch link: {watchUrl}` when the campaign shell exists
+- `Source math before approval` as the final content block immediately above
+  the lead-source approval question. This is the bottom-line arithmetic that
+  makes the recommendation feel obvious. It must use concrete counts and a
+  simple formula, for example:
+  `Signals: 5 relevant posts -> ~320 reachable engagers; 18 of 40 sampled
+engagers fit the ICP, so the expected usable range is roughly 120-160 warm
+prospects after cleanup. If we want more volume than that, use Sales Nav:
+~1,900 preview rows with 14 of 25 sampled rows looking usable, but the message
+context is colder.`
+  For Signals, include selected/relevant posts, total or per-post engagers,
+  sampled engagers, sampled ICP fits as `n/N`, estimated usable prospects, and
+  the volume tradeoff. For Sales Nav/Prospeo alternatives, include preview/raw
+  volume, sampled usable rows as `n/N`, estimated usable range, and the warmth
+  or context tradeoff. Do not use percent-only fit rates or unsupported reply
+  rate claims.
 
 The first sentence of the visible decision must make the actual choice clear:
 `I recommend {primary source} using {exact filter/source recipe}. The runner-up
@@ -1032,6 +1065,10 @@ source decision. Prefer `Approve Sales Nav with founder/CEO filters, or use
 warmer Signals posts instead?` over `Approve this lead source?`. Option labels
 must be concrete, such as `Approve Sales Nav filters`, `Use warmer Signals
 posts`, `Try Prospeo/account search`, and `Revise source`.
+Immediately above that approval question, render the `Source math before
+approval` block. Do not ask the user to approve from the recommendation alone;
+show the math tying relevant posts, available engagers, sampled fit, expected
+usable lead count, and the scale alternative together first.
 
 Do not skip or discard Signals based only on raw post count or vibes. If
 Signals was considered, show the post-level math in chat first so the user can

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

@@ -508,6 +508,30 @@
     {
       "id": "find-leads",
       "label": "Find leads",
+      "sourceSelectionFunnel": {
+        "defaultWhenSourceUnspecified": [
+          "signal-discovery",
+          "sales-nav-recent-active",
+          "sales-nav-general",
+          "prospeo"
+        ],
+        "sourceDirectionOverrides": {
+          "postEngagement": "signal-discovery",
+          "creatorOrCommentSignals": "signal-discovery",
+          "titlePersonaCompanyFilters": "sales-nav",
+          "hiringSignals": "prospeo",
+          "companyGrowthTriggers": "prospeo",
+          "targetAccountsOrDomains": "prospeo",
+          "suppliedProfilesOrCsv": "supplied-list",
+          "explicitCompare": "compare-requested-sources"
+        },
+        "quickViabilityRule": "Run only enough of the current lane to decide whether it can supply relevant, reachable ICP-looking leads. Stop on the first viable source unless the user asked for comparison.",
+        "parallelAllowedOnlyWhen": [
+          "user explicitly requested source comparison",
+          "resuming already-started parallel scouts",
+          "first viable source is borderline and one cheap fallback check is needed"
+        ]
+      },
       "onEnter": [
         {
           "action": "advance_watch_to_source_selection",
@@ -521,8 +545,8 @@
             "currentStep": "pick-provider",
             "watchNarration.stage": "find-leads"
           },
-          "when": "before_source_scouts_or_provider_search",
-          "chatRenderRule": "Move the campaign watch view to Find Leads before the main thread starts comparing source paths. In chat, name the two promising source paths the agent thinks may work, say it is launching background source checks/agents to confirm viability before showing results, and state that no leads import until a source is approved. The watchNarration headline/body must name the likely provider or lane being tested and why it fits this campaign. Do not mention MCP or local artifacts."
+          "when": "before_sequential_source_funnel",
+          "chatRenderRule": "Move the campaign watch view to Find Leads before the main thread starts source viability work. If the user did not specify a source, explain the default order: start with warm LinkedIn post engagement because it gives stronger message context and expected reply-rate upside when enough ICP-looking engagers exist; if it is not viable, switch to Sales Nav with recent activity, then broader Sales Nav, and use Prospeo only as the fallback. If the user did specify hiring signals, domains/accounts, supplied lists, posts/comments, or titles/personas, explain that the matching source overrides the default funnel. State that no leads import until a source is approved. The watchNarration headline/body must name the lane being tested, why this lane now, the quick viability gate, and the safety boundary. Do not mention MCP or local artifacts."
         },
         {
           "action": "advance_watch_to_initial_source_lane",
@@ -540,8 +564,8 @@
             "existingList": "saved-lists",
             "uploadedDomains": "prospeo"
           },
-          "when": "before_background_source_scouts",
-          "rule": "Choose the likely primary visible source lane from source intake, brief preference, or the best first lane the main thread will actually search. Send watchNarration with stage find-leads that says what search was tried or is being tried next, what sample is being checked, and why it helps this campaign. For Signal Discovery sampling, promote/select the posts with select_promising_posts before fetch_post_engagers so the watched table shows the exact posts being sampled; the guide copy should say Codex is pulling sample engagers from these posts to confirm the ICP is actually engaging and the source is viable. Do this before waiting on background scouts so watch mode never sits on only Pick Provider while source work happens elsewhere."
+          "when": "before_first_source_attempt",
+          "rule": "Choose the first visible source lane from explicit source direction when present, otherwise default to Signal Discovery. Send watchNarration with stage find-leads that says why this lane is being tried now, what quick sample or filter gate will pass/fail it, and why that helps this campaign. For Signal Discovery sampling, promote/select the posts with select_promising_posts before fetch_post_engagers so the watched table shows the exact posts being sampled; the guide copy should say Codex is pulling sample engagers from these posts to confirm the ICP is actually engaging and the source is viable. If the lane fails, update currentStep and watchNarration before moving to Sales Nav recent activity, normal Sales Nav, or Prospeo."
         },
         {
           "action": "run_first_campaign_attached_source_search",
@@ -549,8 +573,8 @@
             "campaignOfferId",
             "currentStep"
           ],
-          "before": "waiting_on_background_source_scouts",
-          "rule": "Before relying on background source scouts, the parent thread must run the first provider prompt + provider search for the chosen visible lane with campaignOfferId and currentStep (signal-discovery, sales-nav, or prospeo) so the campaign UI creates the corresponding live search/tab. Background scouts may continue after that, but the user must see at least one relevant campaign-attached search begin in the watched page."
+          "before": "evaluating_source_viability_gate",
+          "rule": "The parent thread must run the campaign-attached provider prompt + provider search for the current visible lane with campaignOfferId and currentStep (signal-discovery, sales-nav, prospeo, or the user-directed lane) so the campaign UI creates the corresponding live search/tab. Do not wait on background scouts before the user sees the active lane. Run only enough evidence to pass/fail this lane, then either recommend it or update the visible lane before trying the next fallback."
         },
         {
           "action": "render_find_leads_progress",
@@ -558,6 +582,9 @@
             "good fit and active enough to be worth a LinkedIn test",
             "campaign source step",
             "primary source",
+            "source hypothesis",
+            "why this source now",
+            "quick viability gate",
             "expected volume",
             "sampled ICP fit",
             "activity/warmth signal",
@@ -587,7 +614,7 @@
           "action": "run_subskill",
           "target": "find-leads",
           "mode": "campaign-attached-required",
-          "sourceScoutRule": "Shell-first flow requires the CampaignOffer campaignId from durable state. Pass campaignId as campaignOfferId into every provider prompt/search that can persist source state (`get_provider_prompt({ provider, campaignOfferId, confirmed: true })`, `search_signals`, `search_sales_nav`, `search_prospeo`) and include currentStep for tools that accept it so the user can watch the selected source inside the campaign. In watch mode, run the first campaign-attached provider search in the parent thread before waiting on background scouts; subagents can explore runner-up lanes after the visible campaign tab exists. The later import_leads call must use the same campaignOfferId. When several source lanes are credible, scout them independently, then write one primary source recommendation and any runner-up tradeoffs. Do not import, confirm, enrich, queue, or start leads during source discovery."
+          "sourceScoutRule": "Shell-first flow requires the CampaignOffer campaignId from durable state. Pass campaignId as campaignOfferId into every provider prompt/search that can persist source state (`get_provider_prompt({ provider, campaignOfferId, confirmed: true })`, `search_signals`, `search_sales_nav`, `search_prospeo`) and include currentStep for tools that accept it so the user can watch the selected source inside the campaign. Use the default sequential source viability funnel when the user did not specify a source: Signal Discovery first, then Sales Nav with recent activity, then general Sales Nav, then Prospeo only as fallback. Stop on the first viable source unless the user explicitly asked to compare. If the user names hiring signals, domains/accounts, supplied lists, posts/comments, or title/persona filters, start with the matching source instead. Parallel source scouts only when the user requested comparison, an existing parallel run is being resumed, or the first viable source is borderline and one cheap fallback check is needed. The later import_leads call must use the same campaignOfferId. Do not import, confirm, enrich, queue, or start leads during source discovery."
         },
         {
           "action": "optional_debug_artifacts",
@@ -693,7 +720,8 @@
             "Signal keyword lanes",
             "LinkedIn posts sampled",
             "Sample leads",
-            "Tradeoff"
+            "Tradeoff",
+            "Source math before approval"
           ],
           "signalsFirstRequiredFields": [
             "post URL",
@@ -726,6 +754,18 @@
             "why runner-up lost",
             "what approval means"
           ],
+          "approvalMathRequiredFields": [
+            "selected or relevant posts count",
+            "reachable engagers count",
+            "sampled engagers count",
+            "sampled ICP fits as n/N only; no percentage",
+            "estimated usable prospects range",
+            "scale alternative source",
+            "scale alternative raw or preview volume",
+            "scale alternative sampled usable rows as n/N only; no percentage",
+            "warmth or message-context tradeoff",
+            "what to choose if the user wants more volume"
+          ],
           "signalsInlineTableRequiredFields": [
             "keyword lane",
             "timeframe",
@@ -746,7 +786,7 @@
           "doNotCompressToSummaryOnly": false,
           "doNotRenderArtifactLinksOnly": true,
           "sourceRecommendationReadyWatchRule": "When the source recommendation decision card is ready in chat with counts and sample quality, and before asking for source approval, call update_campaign with leadSourceType `new`, leadSourceProvider set to the recommended primary provider, currentStep set to that provider lane (`sales-nav`, `signal-discovery`, or `prospeo`), and find-leads watchNarration. If the recommendation changed from the lane last sampled, switch the watched provider page to the recommended lane first so the user can inspect what they are approving. Use a headline like `Review the source in Codex`, body copy that says the browser is showing the evaluated source/results, and nextAction like `Approve in Codex`. Do not keep future-tense copy like `I'll show a source recommendation` after the decision is visible. Include a safety note that no leads import until the user approves the source.",
-          "chatRenderRule": "Show a slim rendered-Markdown decision summary only, never a fenced code block. The first sentence must make the decision explicit: 'I recommend {primary source} using {exact filter/source recipe}. The runner-up is {source} because {reason}.' Use indexed sections and short bullets: recommendation, Primary source and filters, Runner-up sources, why it won, Quick numbers with one provider/source angle per bullet, raw volume, sampled fit count as n/N only (no percentages), estimated good-fit range after cleanup, activity/warmth basis, confidence note, 3-5 representative sample leads, and one tradeoff. Do not forecast connection acceptance rates, reply rates, meetings, pipeline, revenue, or ROI unless the user supplied verified benchmark data for this exact workspace/sender. If Signals was searched or considered, include two compact inline Markdown tables before the recommendation is treated as final: Signal keyword lanes with keyword lane, timeframe, posts found, and finalist posts reviewed; and LinkedIn posts sampled with post URL/title, author/topic, age, engagers, sampled engagers, good fits as n/N only, estimated usable prospects per post, and use/discard decision. Default to selecting a few promising Signals posts for the first sample instead of trying to prove full Signals scale up front; if the sample is good but volume is low, say how many more posts to add/scrape next. Do not skip or discard Signals based only on raw post count or vibes; show the post-level math first, or explicitly say no engagers could be fetched and lower confidence. Keep discarded paths, full sample rows, and lead-sample.json details in lead-review.md. Do not show plain filesystem paths unless links cannot be created."
+          "chatRenderRule": "Show a slim rendered-Markdown decision summary only, never a fenced code block. The first sentence must make the decision explicit: 'I recommend {primary source} using {exact filter/source recipe}. The runner-up is {source} because {reason}.' Use indexed sections and short bullets: recommendation, Primary source and filters, Runner-up sources, why it won, Quick numbers with one provider/source angle per bullet, raw volume, sampled fit count as n/N only (no percentages), estimated good-fit range after cleanup, activity/warmth basis, confidence note, 3-5 representative sample leads, one tradeoff, and a final Source math before approval block immediately above the source approval question. Do not forecast connection acceptance rates, reply rates, meetings, pipeline, revenue, or ROI unless the user supplied verified benchmark data for this exact workspace/sender. If Signals was searched or considered, include two compact inline Markdown tables before the recommendation is treated as final: Signal keyword lanes with keyword lane, timeframe, posts found, and finalist posts reviewed; and LinkedIn posts sampled with post URL/title, author/topic, age, engagers, sampled engagers, good fits as n/N only, estimated usable prospects per post, and use/discard decision. Default to selecting a few promising Signals posts for the first sample instead of trying to prove full Signals scale up front; if the sample is good but volume is low, say how many more posts to add/scrape next. The Source math before approval block must tie the approval choice to concrete arithmetic: relevant/selected posts, available engagers, sampled engagers, sampled ICP fits as n/N only, estimated usable prospects, and the scale alternative math. If the user wants more volume than the warm post-engagement estimate, explicitly say which Sales Nav or Prospeo alternative provides that volume and what message-context warmth is lost. Do not skip or discard Signals based only on raw post count or vibes; show the post-level math first, or explicitly say no engagers could be fetched and lower confidence. Keep discarded paths, full sample rows, and lead-sample.json details in lead-review.md. Do not show plain filesystem paths unless links cannot be created."
         },
         {
           "action": "render_post_lead_parallel_progress",
@@ -768,6 +808,7 @@
         {
           "action": "ask_continue_revise_or_confirm_only_if_needed",
           "approvalQuestionRule": "If asking the user, the question and options must name the concrete decision. Prefer: 'Approve Sales Nav with {filters}, or use warmer Signals instead?' over 'Approve this lead source?' Option labels must name the source choice, such as 'Approve Sales Nav filters', 'Use warmer Signals posts', 'Try Prospeo/account search', and 'Revise source'.",
+          "approvalMathRule": "Immediately above the approval question, render the Source math before approval block: given this many relevant posts, this many reachable engagers, and this sampled ICP fit as n/N, we expect this usable lead range; if the user wants more volume, name the Sales Nav or Prospeo alternative, its preview/sample math, and the colder/weaker-context tradeoff. Do not ask the approval question until this math is visible.",
           "autoContinueWhen": {
             "status": "confirmed",
             "confidenceIn": [

package/skills/create-campaign-v2/references/watch-guide-narration.md

@@ -74,6 +74,45 @@ Signal Discovery:
 }
 ```
 
+Default source funnel:
+
+```json
+{
+  "stage": "find-leads",
+  "headline": "Testing warm LinkedIn activity",
+  "visibleState": "Codex is starting with recent post engagement because it gives the strongest message context if enough ICP-looking people are active there.",
+  "agentIntent": "If this lane does not clear the quick sample gate, it will switch to Sales Nav with recent activity, then broader Sales Nav, and use Prospeo only as the fallback.",
+  "nextAction": "Review source",
+  "safety": "No leads import until you approve the source."
+}
+```
+
+Source direction override:
+
+```json
+{
+  "stage": "find-leads",
+  "headline": "Testing the requested source",
+  "visibleState": "The campaign asked for hiring and account signals, so Codex is starting with Prospeo instead of the default LinkedIn engagement path.",
+  "agentIntent": "It is checking whether this source has enough reachable ICP-looking people before importing a review batch.",
+  "nextAction": "Review source",
+  "safety": "No leads import until you approve the source."
+}
+```
+
+Source fallback:
+
+```json
+{
+  "stage": "find-leads",
+  "headline": "Switching source lanes",
+  "visibleState": "The Signal Discovery sample did not show enough ICP-looking engagers for a confident first batch.",
+  "agentIntent": "Codex is trying Sales Nav with recent activity so the source can still preserve some buyer activity context.",
+  "nextAction": "Review source",
+  "safety": "No leads import until you approve the source."
+}
+```
+
 Search iteration:
 
 ```json