@sellable/mcp 0.1.117 → 0.1.118

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sellable/mcp",
-  "version": "0.1.117",
+  "version": "0.1.118",
   "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

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",

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