@sellable/mcp 0.1.131 → 0.1.133

package/dist/tools/campaigns.js

@@ -190,7 +190,7 @@ export const campaignToolDefinitions = [
                 },
                 watchNarration: {
                     type: "object",
-                    description: "Single structured watch-guide narration object to send with currentStep changes. Include stage, headline, visibleState, agentIntent, and nextAction so the browser guide mirrors Codex progress.",
+                    description: "Single structured watch-guide narration object to send with currentStep changes. Include what just happened, what the browser is showing now, what Codex is doing next, and nextAction so the browser guide mirrors Codex progress.",
                     properties: {
                         stage: {
                             type: "string",
@@ -211,7 +211,13 @@ export const campaignToolDefinitions = [
                         blockedReason: { type: ["string", "null"] },
                         workerStatuses: { type: "object" },
                     },
-                    required: ["stage", "headline", "visibleState", "agentIntent"],
+                    required: [
+                        "stage",
+                        "headline",
+                        "visibleState",
+                        "agentIntent",
+                        "nextAction",
+                    ],
                 },
                 leadSourceType: {
                     type: ["string", "null"],
@@ -283,7 +289,7 @@ export const campaignToolDefinitions = [
                 },
                 watchNarration: {
                     type: "object",
-                    description: "Single structured watch-guide narration object to send with currentStep changes. Include stage, headline, visibleState, agentIntent, and nextAction so the browser guide mirrors Codex progress. Do not send separate guideHeadline/guideBody fields.",
+                    description: "Single structured watch-guide narration object to send with currentStep changes. Include what just happened, what the browser is showing now, what Codex is doing next, and nextAction so the browser guide mirrors Codex progress. Do not send separate guideHeadline/guideBody fields.",
                     properties: {
                         stage: {
                             type: "string",
@@ -304,7 +310,13 @@ export const campaignToolDefinitions = [
                         blockedReason: { type: ["string", "null"] },
                         workerStatuses: { type: "object" },
                     },
-                    required: ["stage", "headline", "visibleState", "agentIntent"],
+                    required: [
+                        "stage",
+                        "headline",
+                        "visibleState",
+                        "agentIntent",
+                        "nextAction",
+                    ],
                 },
                 interactionMode: {
                     type: "string",

package/package.json

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

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

@@ -93,11 +93,15 @@ Optional debug/UAT draft directory, disabled in normal customer runs:
   campaign. If shell creation fails, stop and surface the error. There is no
   no-shell mint fallback in the active shell-first flow.
 - The main thread owns watch navigation. Before expensive work in each major
-  stage, call `update_campaign({ campaignId, currentStep })` with the visible UI
-  step the user should be watching, then continue the work from MCP/product
-  state. Use `create-offer` for the brief, `pick-provider` or the selected
-  provider step while sourcing, `filter-choice` after the 15-row review batch is
-  imported, `messages`/`auto-execute-messaging` for message work,
+  stage, call `update_campaign({ campaignId, currentStep, watchNarration })`
+  with the visible UI step the user should be watching, then continue the work
+  from MCP/product state. Every currentStep switch in a watched run must refresh
+  `watchNarration` in the same visible beat. The copy must say what just
+  happened, what the browser is showing now, what Codex is doing next, and what
+  the user should do next. Use `create-offer` for the brief, `pick-provider` or
+  the selected provider step while sourcing, `filter-choice` after the 15-row
+  review batch is imported, `apply-icp-rubric` while template approval is
+  pending on Filter Leads, `auto-execute-messaging` for approved message work,
   `awaiting-user-greenlight` for Settings, and `validate-sample` only for
   recovery/legacy validation if reached. Do not advance `currentStep` backward.
 - After the shell is minted, normal resume paths read the CampaignOffer first.
@@ -531,12 +535,13 @@ until the filter choice is resolved and the template is ready for approval.`
   `approval-packet.md`.
 - Run the dependency chain as a DAG: `create-campaign-brief` -> `find leads` ->
   bounded import/confirm. Once the source decision, lead sample, and campaign
-  table `workflowTableId` exist, the normal path is the `filter-choice` user
-  gate. If the user chooses filters, `post-lead-workstreams` launches filter
-  leads and can let the Message Draft Builder run from the same basis (live
-  campaign brief, source decision, lead sample, and the imported review-batch
-  rows) as separate workstreams when the host exposes the named Sellable
-  post-find-leads agents or real background work.
+  table `workflowTableId` exist, immediately start the Message Draft Builder
+  from the live campaign brief, approved source, source list, and imported
+  review-batch rows before telling the user it is in progress. The normal path
+  then reaches the `filter-choice` user gate. If the user chooses filters,
+  `post-lead-workstreams` launches filter leads and reuses the in-flight Message
+  Draft Builder work from the same basis as separate workstreams when the host
+  exposes the named Sellable post-find-leads agents or real background work.
   First call `get_post_find_leads_scout_registry` and use the returned
   canonical `name` values only when those names are available in the current
   runtime. In Claude Code, use both returned Task/Agent subagents in the same
@@ -548,12 +553,14 @@ until the filter choice is resolved and the template is ready for approval.`
   `filter-rubric` and `message-generation` steps remain focused retry and
   resume targets.
 - Message generation does not need `lead-filter.md` to start, but it is only
-  background template drafting until the user approves the template. The moment the
-  bounded review batch is imported, `workflowTableId` is ready, and the user is
-  on/after filter choice, the Message Draft Builder may start from the live
-  campaign brief, source decision, lead sample, and imported campaign table
-  sample. It can prepare proof inventory, token strategy, and candidate angles
-  while filter-leads tightens keep/exclude rules. Template review cannot start
+  background template drafting until the user approves the template. The moment
+  the bounded review batch is imported, `workflowTableId` is ready, and
+  `get_rows_minimal` proves rows exist, the Message Draft Builder must start
+  from the live campaign brief, source decision, lead sample, and imported
+  campaign table sample. Do not show `Message Draft Builder: In Progress` unless
+  the worker or parent-thread fallback has actually started. It can prepare
+  proof inventory, token strategy, and candidate angles while filter-leads
+  tightens keep/exclude rules. Template review cannot start
   until filter choice is answered and rubrics are saved. If filters are enabled,
   the watched browser stays on Filter Leads while the template is approved in
   chat. After approval is saved to the campaign brief, queue the bounded
@@ -590,13 +597,18 @@ until the filter choice is resolved and the template is ready for approval.`
   `currentStep` before waiting on source-scout results, so relevant search tabs
   appear in real time.
 - For post-lead workstreams, first call
-  `get_post_find_leads_scout_registry` and launch exactly the returned
-  `filter-leads` and `message-generation` scouts when real subagents are
-  available. This is the two Task/Agent subagents path for the
-  `post-lead-workstreams` step. This is the same registry pattern as source scouting, but the
-  trigger is source approval and the join gate is both `lead-filter.md` and
-  `message-validation.md` existing from the same live campaign brief/source
-  decision/lead-sample basis.
+  `get_post_find_leads_scout_registry` after the review batch import confirms
+  rows. Launch the returned `message-generation` scout immediately, before the
+  filter-choice/watch copy says message work is running. When the user chooses
+  filters, launch the returned `filter-leads` scout and reuse the in-flight
+  message branch. This is the Task/Agent subagents path for the
+  `post-lead-workstreams` step. This is the same registry pattern as source
+  scouting, but the trigger is bounded review-batch import and the join gate is
+  both `lead-filter.md` and `message-validation.md` existing from the same live
+  campaign brief/source decision/imported review-batch basis. When the host can
+  launch both branches together, this is still the two Task/Agent subagents
+  path; otherwise message-generation starts first and filter-leads joins after
+  the filter choice.
 - Never run a downstream stage until the active `flow.v2.json` step's required
   campaign state and required normal inputs exist. In normal customer runs, do
   not create optional debug artifacts just to satisfy a file gate.

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

@@ -8,6 +8,30 @@
     "requiredArtifactsApplyWhen": "legacy resume, fixture validation, or explicit debug/UAT mode only",
     "customerFacingAccess": "Watch link, live campaign currentStep, and concise watchNarration"
   },
+  "watchNarrationTransitionContract": {
+    "rule": "Every watched currentStep switch must update watchNarration in the same visible beat. The narration must clearly say what just happened, what page or state the browser is showing now, what Codex is doing next, and what the user should do next. Do not persist optimistic future-step copy; if the step cannot be shown yet, keep the previous currentStep and narrate the current work instead.",
+    "requiredFields": [
+      "stage",
+      "headline",
+      "visibleState",
+      "agentIntent",
+      "nextAction"
+    ],
+    "copyMustInclude": [
+      "what just happened",
+      "current visible page/state",
+      "next user action",
+      "safety boundary when work is gated"
+    ],
+    "appliesToTools": [
+      "create_campaign",
+      "update_campaign",
+      "update_campaign_brief when it unlocks a step",
+      "attach_selected_sender",
+      "attach_recommended_sequence",
+      "start_campaign"
+    ]
+  },
   "commitGateChoices": [
     "approve",
     "revise-brief",
@@ -1031,6 +1055,44 @@
           ],
           "rule": "If confirm_lead_list succeeds but get_rows_minimal returns zero imported review-batch rows, do not advance to filter-choice. Keep the user in source/import recovery and ask for retry import, import more from the approved source, or revise source."
         },
+        {
+          "tool": "get_post_find_leads_scout_registry",
+          "purpose": "load_post_import_message_draft_builder_registry",
+          "requiredBeforeMessageDraftLaunch": true
+        },
+        {
+          "action": "launch_message_draft_builder_after_review_batch_import",
+          "mode": "background_required_when_host_supports_subagents",
+          "registryRequired": "get_post_find_leads_scout_registry",
+          "branch": {
+            "name": "message-generation",
+            "target": "generate-messages",
+            "workerName": "post-find-leads-message-scout",
+            "inputs": [
+              "campaignBrief",
+              "selected source decision",
+              "selectedLeadListId source list",
+              "workflowTableId imported 15-row review batch"
+            ],
+            "toolCallRequiredBeforeArtifacts": [
+              "get_subskill_prompt({ subskillName: \"generate-messages\" }) until hasMore=false"
+            ],
+            "producesArtifacts": [
+              "template recommendation",
+              "token fill rules",
+              "rendered sample"
+            ],
+            "optionalProducesArtifacts": [
+              "message-validation.md",
+              "message-prep.md",
+              "message-candidate-drafts.md"
+            ],
+            "ownership": "proof inventory, token strategy, angle drafting, skeptical-prospect review, and selected winner only"
+          },
+          "requiredBeforeFilterChoiceWatchCopy": true,
+          "rule": "Immediately after get_rows_minimal proves the bounded review batch is non-empty, start the Message Draft Builder from the live campaign brief, approved source, selectedLeadListId, and imported workflowTableId rows. Do this before the watched campaign moves to filter-choice or Filter Rules so any guide copy saying Message Draft Builder is In Progress is true.",
+          "fallback": "If the host cannot launch the post-find-leads-message-scout in the background, load the full generate-messages prompt in the parent thread and start the message-generation work before reporting Message Draft Builder as In Progress. If message work cannot start, do not show running copy; surface pending/blocked template-start copy instead."
+        },
         {
           "tool": "update_campaign",
           "requiredFields": [
@@ -1041,9 +1103,10 @@
           "requiredValues": {
             "currentStep": "filter-choice",
             "watchNarration.stage": "fit-message",
-            "watchNarration.headline": "Added to Campaign"
+            "watchNarration.headline": "Added to Campaign",
+            "watchNarration.workerStatuses.messageDraftBuilder": "running_after_launch_message_draft_builder_after_review_batch_import_only"
           },
-          "watchNarrationRule": "After the bounded review batch is present and non-empty, update the watched guide to `Added to Campaign` and ask the user to Choose filters or skip. This is filter intent only: do not say filtering the batch before rubrics and message approval are saved. The Message Draft Builder may start in the background, but no enrichment, filtering, Generate Message cells, sequence, or sending starts until the message template is approved and saved to the campaign brief. Do not set enableICPFilters=true until save_rubrics succeeds with active criteria."
+          "watchNarrationRule": "After the bounded review batch is present and non-empty, and after launch_message_draft_builder_after_review_batch_import has actually started or resumed message-generation, update the watched guide to `Added to Campaign` and ask the user to Choose filters or skip. This is filter intent only: do not say filtering the batch before rubrics and message approval are saved. The Message Draft Builder should be reported as In Progress only if the worker or parent-thread fallback has actually started. No enrichment, filtering, Generate Message cells, sequence, or sending starts until the message template is approved and saved to the campaign brief. Do not set enableICPFilters=true until save_rubrics succeeds with active criteria."
         }
       ],
       "allowedTools": [
@@ -1059,7 +1122,11 @@
         "load_csv_linkedin_leads",
         "load_csv_domains",
         "get_provider_prompt",
-        "get_campaign"
+        "get_campaign",
+        "get_post_find_leads_scout_registry",
+        "get_subskill_prompt",
+        "Task",
+        "spawn_agent"
       ],
       "doNotAllow": [
         "queue_cells",
@@ -1187,7 +1254,6 @@
             {
               "name": "message-generation",
               "target": "generate-messages",
-              "mode": "DRY MODE",
               "inputs": [
                 "campaignBrief",
                 "selected source decision",
@@ -1204,15 +1270,18 @@
                 "message-prep.md",
                 "message-candidate-drafts.md"
               ],
-              "ownership": "proof inventory, token strategy, angle drafting, skeptical-prospect review, and selected winner only"
+              "ownership": "proof inventory, token strategy, angle drafting, skeptical-prospect review, and selected winner only",
+              "mode": "background_template_builder_reuse_or_launch_if_missing",
+              "alreadyStartedBy": "auto-execute-leads.launch_message_draft_builder_after_review_batch_import"
             }
           ],
-          "earlyMessageStartRule": "After auto-execute-leads confirms the 15-row review batch, workflowTableId is ready, and the user has reached filter choice, the Message Draft Builder may start from campaignBrief, selected source state, selectedLeadListId, and imported campaign table rows, including while the user is on filter choice. This background template draft is provisional speed work only. The message worker must load the full generate-messages prompt; parent-thread fallback loads the same prompt and may use references/message-review-safety-gate.md only as a supplemental approval checklist. It may run beside filter-leads, but no enrichment, ICP scoring, filtering, or product Generate Message cells can queue until save_rubrics and update_campaign_brief both succeed.",
+          "earlyMessageStartRule": "After auto-execute-leads confirms the 15-row review batch, workflowTableId is ready, and get_rows_minimal proves rows exist, the Message Draft Builder must start immediately from campaignBrief, selected source state, selectedLeadListId, and imported campaign table rows. post-lead-workstreams must reuse that in-flight message branch; if it is missing, launch it before saving rubrics or claiming message progress. This background template draft is provisional speed work only. The message worker must load the full generate-messages prompt; parent-thread fallback loads the same prompt and may use references/message-review-safety-gate.md only as a supplemental approval checklist. It may run beside filter-leads, but no enrichment, ICP scoring, filtering, or product Generate Message cells can queue until save_rubrics and update_campaign_brief both succeed.",
+          "workerStatusContract": "Only show Lead Fit Builder or Message Draft Builder as In Progress when a Task/spawn_agent branch actually started and returned a live branch id, or when the parent-thread fallback is actively doing that branch before the next user-visible step. If a branch is completed in the parent thread, show it as Ready. After update_campaign_brief saves the approved template, Message Draft Builder is Ready even if row-level Generate Message cells have not completed.",
           "finalMessageReconcileRule": "The message recommendation may start before lead-filter.md exists, but before message-review it must cite only imported review-batch rows that still pass the saved rubric/filter results. If the selected winner depends on a row later excluded by saved filters, revise message-generation before message review.",
           "finalTemplateReviewLockRule": "template review does not require a Use Template vs AI Generated mode choice. After filters are enabled, lock template review until saved rubrics exist and the draft reconciles to the approved brief, selected source, and imported review batch. Keep the watched browser on Filter Leads while approval is pending. After approval writes the Approved Message Template into campaignBrief, queue enrichment/ICP scoring for the bounded review batch; prefer at least 2 usable passing/probably passing rows before moving the watched browser to Messages, with weak-sample escalation if only 1 passes.",
-          "claudeRule": "In Claude Code, launch both returned post-find-leads scouts with Task/Agent subagents in the same assistant message only when the current session lists those agent names. Do not run filter first and then message generation unless subagents/background work are unavailable.",
-          "codexRule": "In Codex, launch both returned post-find-leads scout names as disjoint subagents in the same assistant turn only when the host exposes those custom agents for this run. If the host cannot spawn them, run the same branches sequentially and say so.",
-          "fallback": "If real parallel branches are unavailable or the named agents are absent, run filter-leads and then message-generation in the parent thread with product MCP tools/assets. Do not customer-surface agent install status, and do not claim background or parallel work in that fallback."
+          "claudeRule": "In Claude Code, launch the returned message-generation scout immediately after post-import rows exist, then launch/reuse the filter-leads scout when the user chooses filters. When both named agents are available and both branches are ready in the same assistant message, use Task/Agent subagents in parallel; otherwise never claim background message progress until message-generation actually started.",
+          "codexRule": "In Codex, launch the returned message-generation scout immediately after post-import rows exist, then launch/reuse filter-leads when filters are chosen. Use disjoint subagents only when the host exposes those custom agents; otherwise start the same message-generation branch in the parent thread before reporting it as running.",
+          "fallback": "If real parallel branches are unavailable or the named agents are absent, start message-generation in the parent thread immediately after post-import, then run filter-leads from the same imported review batch. Do not customer-surface agent install status, and do not claim background or parallel work unless that work actually started."
         },
         {
           "action": "wait_for_lead_filter_rules",
@@ -1307,7 +1376,7 @@
       ],
       "toolRules": [
         "The post-lead workstreams are disjoint: filter-leads owns lead-filter.md/rubric.json; message-generation owns message-validation.md/message-prep.md/message-candidate-drafts.md.",
-        "message-generation can start before saved filters, but message-review cannot start until saved filters and the message recommendation reconcile against the same imported review-batch rows.",
+        "message-generation must start immediately after the post-import review batch exists, before saved filters; message-review cannot start until saved filters and the message recommendation reconcile against the same imported review-batch rows.",
         "Do not let filter-leads create a new message sample. Do not let message-generation fetch new prospects.",
         "Before writing message-validation.md or returning a template recommendation, message-generation must load the full get_subskill_prompt({ subskillName: \"generate-messages\" }) prompt and use campaignBrief, selected source state, selectedLeadListId, and imported review-batch rows as the source of truth. Optional debug markdown files are not durable state.",
         "Do not queue enrichment, ICP scoring, filtering, or Generate Message cells after saved rubrics alone. Wait until the approved message template is synced into campaignBrief, then queue only bounded review-batch enrichCellId values.",
@@ -1522,7 +1591,7 @@
         {
           "action": "run_or_reconcile_subskill",
           "target": "generate-messages",
-          "mode": "DRY MODE",
+          "mode": "approved_template_builder",
           "sampleSource": "imported review-batch rows from selectedLeadListId",
           "toolCallRequiredBeforeArtifacts": [
             "get_subskill_prompt({ subskillName: \"generate-messages\", offset, limit }) until hasMore=false",
@@ -1743,6 +1812,25 @@
           "requiredBeforeCascade": true,
           "writesCampaignState": "campaignBrief.Approved Message Template"
         },
+        {
+          "action": "advance_watch_after_template_saved_before_cascade",
+          "tool": "update_campaign",
+          "requires": [
+            "campaignId",
+            "campaignBrief.Approved Message Template",
+            "leadScoringRubrics"
+          ],
+          "requiredValues": {
+            "currentStep": "apply-icp-rubric",
+            "enableICPFilters": true,
+            "watchNarration.stage": "fit-message",
+            "watchNarration.headline": "Template saved",
+            "watchNarration.workerStatuses.leadFitBuilder": "ready",
+            "watchNarration.workerStatuses.messageDraftBuilder": "ready"
+          },
+          "when": "immediately_after_update_campaign_brief_succeeds_before_get_rows_or_queue_cells",
+          "watchNarrationRule": "Say the approved message template was saved into the campaign brief, the browser is staying on Filter Leads, and Codex is now queueing only the bounded review-batch enrichment/ICP scoring cascade. The Message Draft Builder must be shown as Ready, not In Progress, after this point."
+        },
         {
           "tool": "get_rows_minimal",
           "purpose": "read_bounded_review_batch_cell_ids_after_message_approval",
@@ -2436,7 +2524,8 @@
           "requiredValues": {
             "currentStep": "awaiting-user-greenlight",
             "watchNarration.stage": "review-ready"
-          }
+          },
+          "watchNarrationRule": "Say the approved-template cascade has produced reviewable messages and the browser is moving to Settings. Include what just happened, that Settings is now visible for sender selection, and that nothing launches until the user greenlights the final send."
         }
       ],
       "allowedTools": [
@@ -2492,9 +2581,11 @@
         {
           "tool": "update_campaign",
           "requiredValues": {
-            "currentStep": "settings"
+            "currentStep": "settings",
+            "watchNarration.stage": "review-ready"
           },
-          "purpose": "park the watched UI on Settings before sender selection"
+          "purpose": "park the watched UI on Settings before sender selection",
+          "watchNarrationRule": "Say message review is complete and the browser is now on Settings so the user can connect or choose a sender. Include the safety boundary that no launch happens from Settings."
         },
         {
           "tool": "get_campaign_navigation_state",
@@ -2532,8 +2623,10 @@
             "senderIds": [
               "{selectedSenderId}"
             ],
-            "currentStep": "sequence"
-          }
+            "currentStep": "sequence",
+            "watchNarration.stage": "review-ready"
+          },
+          "watchNarrationRule": "Say the sender was attached and the browser is moving to Sequence. Explain that Codex is binding the recommended sequence next and that launch still needs explicit greenlight."
         },
         {
           "tool": "get_campaign_navigation_state",
@@ -2547,15 +2640,18 @@
             "campaignId": "{campaignId}",
             "currentStep": "send"
           },
-          "purpose": "bind the tier-aware recommended sequence before the launch decision"
+          "purpose": "bind the tier-aware recommended sequence before the launch decision",
+          "watchNarrationRule": "The sequence tool may persist currentStep. If it does, the same visible beat must still explain that the recommended sequence is attached and Send is next; otherwise follow with update_campaign and watchNarration before asking for launch greenlight."
         },
         {
           "tool": "update_campaign",
-          "when": "sequence attach response does not persist currentStep",
+          "when": "after recommended sequence attach; required if sequence attach did not persist watchNarration with currentStep",
           "requiredValues": {
-            "currentStep": "send"
+            "currentStep": "send",
+            "watchNarration.stage": "review-ready"
           },
-          "purpose": "show the Send tab once sender and sequence are ready"
+          "purpose": "show the Send tab once sender and sequence are ready",
+          "watchNarrationRule": "Say the sender and sequence are ready and the browser is now on Send. The next action is the final launch greenlight; do not imply anything has sent yet."
         },
         {
           "tool": "get_campaign_navigation_state",
@@ -2676,7 +2772,8 @@
           "requiredFields": [
             "campaignId"
           ],
-          "persistsCurrentStep": "running"
+          "persistsCurrentStep": "running",
+          "watchNarrationRule": "After start_campaign succeeds, the running state must say the final greenlight was accepted, the campaign is now live/running, and the user can watch progress from the campaign."
         },
         {
           "action": "surface_watch_link",

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

@@ -28,6 +28,9 @@ stage labels. The driver label comes from the watch URL mode (`mode=claude` or
 - One primary user action per frame.
 - Headline under 8 words.
 - Body is 1-2 short sentences total.
+- Every watched step switch must refresh `watchNarration` with current-tense
+  copy that says what just happened, what the browser is showing now, what
+  Codex is doing next, and what the user should do next.
 - Say where the user acts: usually `in Claude Code`, `in Codex`, or `in chat`,
   matching the host that created the watch URL.
 - `Find Leads` is only the static progress label. The copy must name the active