@sellable/mcp 0.1.132 → 0.1.134

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.132",
+  "version": "0.1.134",
   "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.
@@ -423,13 +427,18 @@ brief`, `Revise target`, `Revise offer/proof`, and `Other / custom`.
   not visible in this session, use `Approve brief + compare source paths`
   instead. The customer approves the sourcing decision, not the host
   implementation detail.
-  Include a `Watch link:` line before the approval question once
-  `create_campaign` has returned `watchUrl`. The visible brief must come before
-  any optional debug persistence. After the brief is synthesized, render the
-  approval-ready brief in chat and create/update the campaign shell before any
-  visible `mkdir`, `Write`, artifact-copy, or similar local draft setup. In
-  normal customer runs, skip local draft setup entirely. File/folder creation is
-  not the user's value moment; the live campaign brief is.
+  Include a `Watch link:` line in the normal chat text immediately before the
+  brief approval question once `create_campaign` has returned `watchUrl`. This
+  is a hard gate for `AskUserQuestion` / `request_user_input`: do not ask
+  `Approve this brief before I start finding leads?` until the user has already
+  seen the watch link for the live campaign shell. If the question panel would
+  appear without a preceding `Watch link:` line, stop and send the link first.
+  The visible brief must come before any optional debug persistence. After the
+  brief is synthesized, render the approval-ready brief in chat and
+  create/update the campaign shell before any visible `mkdir`, `Write`,
+  artifact-copy, or similar local draft setup. In normal customer runs, skip
+  local draft setup entirely. File/folder creation is not the user's value
+  moment; the live campaign brief is.
 
   The approval question can be based on the rendered brief in chat and the live
   campaign brief. Do not wait for file-write chrome before asking for approval.

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",
@@ -419,6 +443,8 @@
             "watchUrl"
           ],
           "campaignLinkTiming": "before_approval_question",
+          "questionToolGate": "Do not call AskUserQuestion or request_user_input for brief approval until the immediately preceding customer-visible chat text includes `Watch link:` with the create_campaign.watchUrl for this campaign shell.",
+          "missingWatchLinkRecovery": "If the brief approval question would appear before the watch link, stop and send the rendered brief checkpoint plus `Watch link: {watchUrl}` first; then ask the approve/revise question.",
           "forbiddenNormalCustomerLinks": [
             "brief.md",
             "local draft path",
@@ -428,6 +454,12 @@
         },
         {
           "action": "ask_continue_or_revise_only_if_needed",
+          "requiresPriorVisibleContent": [
+            "full readable brief",
+            "live campaign shell orientation",
+            "Watch link: {watchUrl}"
+          ],
+          "mustNotCallQuestionToolUntil": "The watch link has already been shown in normal chat text after create_campaign returned watchUrl.",
           "autoContinueWhen": {
             "artifactStatus": "confirmed",
             "confidenceIn": [
@@ -1252,6 +1284,7 @@
             }
           ],
           "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 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.",
@@ -1566,7 +1599,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",
@@ -1787,6 +1820,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",
@@ -2480,7 +2532,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": [
@@ -2536,9 +2589,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",
@@ -2576,8 +2631,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",
@@ -2591,15 +2648,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",
@@ -2720,7 +2780,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

package/skills/create-campaign-v2/references/watch-link-handoff.md

@@ -46,6 +46,9 @@ real-time updates from your signed-in session.
 
 Command-Enter or click that link to watch it in Sellable.
 
+Now ask the brief approval question. Do not show the approve/revise question
+panel until this `Watch link:` line has appeared in normal chat text.
+
 Cool, let's find leads.
 ```