@sellable/mcp 0.1.111 → 0.1.112

package/dist/tools/campaigns.d.ts

@@ -9,6 +9,7 @@ declare const LEAD_SOURCE_PROVIDERS: {
 };
 type LeadSourceProvider = (typeof LEAD_SOURCE_PROVIDERS)[keyof typeof LEAD_SOURCE_PROVIDERS];
 export declare function buildWatchUrl(config: Pick<ReturnType<typeof getConfig>, "apiUrl" | "token" | "activeWorkspaceId" | "workspaceId">, path: string): string;
+export declare function getCampaignBuilderWatchModeParam(): "claude" | "codex";
 export interface Campaign {
     id: string;
     name: string;
@@ -124,6 +125,7 @@ export interface CreateCampaignInput {
     campaignBrief?: string;
     messageGenerationMode?: "template" | "ai-generated";
     currentStep?: string | null;
+    watchNarration?: unknown;
     leadSourceType?: string | null;
     leadSourceProvider?: LeadSourceProvider | "apollo" | null;
     selectedLeadListId?: string | null;
@@ -137,6 +139,7 @@ export interface UpdateCampaignInput {
     leadSourceProvider?: LeadSourceProvider | "apollo" | null;
     selectedLeadListId?: string | null;
     currentStep?: string | null;
+    watchNarration?: unknown;
     interactionMode?: InteractionMode;
     enableICPFilters?: boolean | null;
     useMessagingTemplate?: boolean | null;
@@ -165,6 +168,7 @@ export declare const campaignToolDefinitions: ({
             campaignBrief?: undefined;
             messageGenerationMode?: undefined;
             currentStep?: undefined;
+            watchNarration?: undefined;
             leadSourceType?: undefined;
             leadSourceProvider?: undefined;
             selectedLeadListId?: undefined;
@@ -200,6 +204,7 @@ export declare const campaignToolDefinitions: ({
             campaignBrief?: undefined;
             messageGenerationMode?: undefined;
             currentStep?: undefined;
+            watchNarration?: undefined;
             leadSourceType?: undefined;
             leadSourceProvider?: undefined;
             selectedLeadListId?: undefined;
@@ -278,6 +283,7 @@ export declare const campaignToolDefinitions: ({
             campaignBrief?: undefined;
             messageGenerationMode?: undefined;
             currentStep?: undefined;
+            watchNarration?: undefined;
             leadSourceType?: undefined;
             leadSourceProvider?: undefined;
             selectedLeadListId?: undefined;
@@ -330,6 +336,41 @@ export declare const campaignToolDefinitions: ({
                 type: string[];
                 description: string;
             };
+            watchNarration: {
+                type: string;
+                description: string;
+                properties: {
+                    stage: {
+                        type: string;
+                        enum: string[];
+                    };
+                    headline: {
+                        type: string;
+                    };
+                    visibleState: {
+                        type: string;
+                    };
+                    agentIntent: {
+                        type: string;
+                    };
+                    nextAction: {
+                        type: string[];
+                    };
+                    safety: {
+                        type: string[];
+                    };
+                    progressLabel: {
+                        type: string[];
+                    };
+                    blockedReason: {
+                        type: string[];
+                    };
+                    workerStatuses: {
+                        type: string;
+                    };
+                };
+                required: string[];
+            };
             leadSourceType: {
                 type: string[];
                 description: string;
@@ -399,6 +440,41 @@ export declare const campaignToolDefinitions: ({
                 type: string[];
                 description: string;
             };
+            watchNarration: {
+                type: string;
+                description: string;
+                properties: {
+                    stage: {
+                        type: string;
+                        enum: string[];
+                    };
+                    headline: {
+                        type: string;
+                    };
+                    visibleState: {
+                        type: string;
+                    };
+                    agentIntent: {
+                        type: string;
+                    };
+                    nextAction: {
+                        type: string[];
+                    };
+                    safety: {
+                        type: string[];
+                    };
+                    progressLabel: {
+                        type: string[];
+                    };
+                    blockedReason: {
+                        type: string[];
+                    };
+                    workerStatuses: {
+                        type: string;
+                    };
+                };
+                required: string[];
+            };
             interactionMode: {
                 type: string;
                 enum: string[];
@@ -466,6 +542,7 @@ export declare const campaignToolDefinitions: ({
             offerPositioning?: undefined;
             messageGenerationMode?: undefined;
             currentStep?: undefined;
+            watchNarration?: undefined;
             leadSourceType?: undefined;
             leadSourceProvider?: undefined;
             selectedLeadListId?: undefined;

package/dist/tools/campaigns.js

@@ -27,6 +27,15 @@ export function buildWatchUrl(config, path) {
     }
     return url.toString();
 }
+export function getCampaignBuilderWatchModeParam() {
+    const explicit = process.env.SELLABLE_WATCH_MODE_DRIVER?.trim().toLowerCase();
+    if (explicit === "claude" || explicit === "codex")
+        return explicit;
+    return process.env.CODEX_HOME ? "codex" : "claude";
+}
+function buildCampaignBuilderWatchPath(campaignId) {
+    return `/campaign-builder/${campaignId}?mode=${getCampaignBuilderWatchModeParam()}`;
+}
 function isLinkedInProfileUrl(input) {
     try {
         const url = new URL(input);
@@ -176,6 +185,31 @@ export const campaignToolDefinitions = [
                     type: ["string", "null"],
                     description: "Workflow step ID (headless or UI step ID such as filter-rules)",
                 },
+                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.",
+                    properties: {
+                        stage: {
+                            type: "string",
+                            enum: [
+                                "brief-review",
+                                "find-leads",
+                                "review-batch",
+                                "fit-message",
+                                "review-ready",
+                            ],
+                        },
+                        headline: { type: "string" },
+                        visibleState: { type: "string" },
+                        agentIntent: { type: "string" },
+                        nextAction: { type: ["string", "null"] },
+                        safety: { type: ["string", "null"] },
+                        progressLabel: { type: ["string", "null"] },
+                        blockedReason: { type: ["string", "null"] },
+                        workerStatuses: { type: "object" },
+                    },
+                    required: ["stage", "headline", "visibleState", "agentIntent"],
+                },
                 leadSourceType: {
                     type: ["string", "null"],
                     description: "Lead source type (existing | new)",
@@ -244,10 +278,35 @@ export const campaignToolDefinitions = [
                     type: ["string", "null"],
                     description: "Headless workflow step ID",
                 },
+                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.",
+                    properties: {
+                        stage: {
+                            type: "string",
+                            enum: [
+                                "brief-review",
+                                "find-leads",
+                                "review-batch",
+                                "fit-message",
+                                "review-ready",
+                            ],
+                        },
+                        headline: { type: "string" },
+                        visibleState: { type: "string" },
+                        agentIntent: { type: "string" },
+                        nextAction: { type: ["string", "null"] },
+                        safety: { type: ["string", "null"] },
+                        progressLabel: { type: ["string", "null"] },
+                        blockedReason: { type: ["string", "null"] },
+                        workerStatuses: { type: "object" },
+                    },
+                    required: ["stage", "headline", "visibleState", "agentIntent"],
+                },
                 interactionMode: {
                     type: "string",
                     enum: ["step-by-step", "autonomous", "ask-when-needed"],
-                    description: "Execution style for lead sourcing steps (step-by-step | autonomous | ask-when-needed).",
+                    description: "Execution style for Find Leads steps (step-by-step | autonomous | ask-when-needed).",
                 },
                 enableICPFilters: {
                     type: ["boolean", "null"],
@@ -335,7 +394,7 @@ export async function getCampaign(campaignId) {
         api.get(`/api/v3/mcp/campaigns/${campaignId}`),
         fetchCampaignRubrics(campaignId).catch(() => null),
     ]);
-    const watchUrl = buildWatchUrl(config, `/campaign-builder/${campaignId}?mode=claude`);
+    const watchUrl = buildWatchUrl(config, buildCampaignBuilderWatchPath(campaignId));
     // Merge rubrics into campaignOffer
     const rubrics = (rubricsResult?.rubrics || []).map((r) => ({
         id: r.id || "",
@@ -590,7 +649,7 @@ export async function createCampaign(input) {
     // Idempotent resume path
     if (input.campaignId) {
         const existing = await api.get(`/api/v2/campaign-offers/${input.campaignId}`);
-        const watchUrl = buildWatchUrl(config, `/campaign-builder/${existing.id}?mode=claude`);
+        const watchUrl = buildWatchUrl(config, buildCampaignBuilderWatchPath(existing.id));
         const hasCreateFields = input.name ||
             input.clientProspectId ||
             input.offerPositioning !== undefined ||
@@ -708,7 +767,7 @@ export async function createCampaign(input) {
         },
     };
     const result = await api.post(`/api/v2/campaign-offers`, formattedInput);
-    const watchUrl = buildWatchUrl(config, `/campaign-builder/${result.id}?mode=claude`);
+    const watchUrl = buildWatchUrl(config, buildCampaignBuilderWatchPath(result.id));
     // Serialize to only essential fields for context efficiency
     return {
         id: result.id,

package/dist/tools/navigation.js

@@ -415,8 +415,8 @@ function parseWatchUrl(watchUrl, campaignId) {
             direct: false,
             redirectPath: decodedRedirect,
             warning: isLegacySigned
-                ? "Watch URL still uses a tokenized /auth/continue handoff. Return the safe direct /campaign-builder/{campaignId}?mode=claude watch URL instead."
-                : "Watch URL is not a safe direct /campaign-builder/{campaignId}?mode=claude watch link.",
+                ? "Watch URL still uses a tokenized /auth/continue handoff. Return the safe direct /campaign-builder/{campaignId}?mode={claude|codex} watch URL instead."
+                : "Watch URL is not a safe direct /campaign-builder/{campaignId}?mode={claude|codex} watch link.",
         };
     }
     catch {

package/package.json

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

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

@@ -165,7 +165,7 @@ Optional debug/UAT draft directory, disabled in normal customer runs:
   ask in chat only when the run is explicitly a non-interactive smoke/rehearsal.
 
 - Customer-facing progress updates must use product language. Say "quick
-  setup choices", "campaign brief", "lead sourcing", and "approval" instead of
+  setup choices", "campaign brief", "Find Leads", and "approval" instead of
   `request_user_input`, Default mode, MCP namespaces, plugin caches, prompt
   loading, runbooks, local skill files, skill versions, npm/package details,
   repo-local files, VPS/off-desktop/browser automation limitations, or
@@ -181,6 +181,13 @@ Optional debug/UAT draft directory, disabled in normal customer runs:
   or safe launch. Do not say "persist", "local draft folder", "artifact",
   "mkdir", "campaign thesis", or "same approved campaign thesis" in
   customer-facing progress copy.
+- Watch guide copy must use the single `watchNarration` object whenever you set
+  `currentStep` or report visible progress in a watched run. Read
+  `references/watch-guide-narration.md` for the compact screen contract. Do not
+  send separate guide headline/body args. In Find Leads, the static stage label
+  is not enough: name the active lane/provider, what search or sample you are
+  trying, and why it fits this campaign. Do not promise time estimates in guide
+  copy.
 - Every approval gate must include live campaign access after the readable inline
   content. Show a short `Watch link:` line with the campaign link when a
   campaign shell exists. In normal customer runs, do not show `Open artifact:`
@@ -401,7 +408,7 @@ Optional debug/UAT draft directory, disabled in normal customer runs:
   `RevOps`, `outbound systems`, or `pipeline architecture` unless they are
   translated into what the user can understand.
 
-  After rendering that brief, ask for brief approval before lead sourcing in
+  After rendering that brief, ask for brief approval before Find Leads in
   hosted net-new runs. The user-facing choice should be approve/revise language,
   not "looks good".
   Approval options should refer to what the user just read, e.g. `Approve this
@@ -422,16 +429,15 @@ brief`, `Revise target`, `Revise offer/proof`, and `Other / custom`.
 
   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.
-  Before lead sourcing, call `update_campaign({ campaignId, campaignBrief,
-  currentStep: "pick-provider" })` after approval so the watch link moves out of
-  Plan while the main thread compares source paths.
+  Before Find Leads, call `update_campaign({ campaignId, campaignBrief,
+  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'll compare source paths by expected volume,
 sampled ICP fit, activity/warmth signal, cleanup risk, and tradeoffs. This
-usually takes ~3-5 min, and I'll show you the source decision + sample before
-anything goes live.`
+will end with a source decision + sample before anything goes live.`
 - 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
@@ -447,9 +453,8 @@ message we should test.`
 - During long post-intake work, show concise progress checkpoints before the
   next expensive stage: source being checked, source switch/tradeoff if any,
   lead sample usable, filter/message drafting, and message-review rule loading.
-  Each checkpoint should include a rough remaining time when useful. If a step
-  exceeds its estimate by roughly a minute or more, acknowledge it lightly once
-  and explain why the extra care helps the campaign. Example:
+  Each checkpoint should say what changed, what is being checked next, and why
+  that matters for the campaign. Do not invent remaining-time estimates. Example:
 
   ```text
   This is taking a little longer than I expected, sorry. I’m being careful here
@@ -623,7 +628,7 @@ workstreams`, `in parallel`, or `background` unless parallel branches were
 There are four customer-visible gates in the net-new hosted flow:
 
 - `brief-review` asks whether to approve the rendered campaign brief before
-  lead sourcing starts. Do not skip this by inferring approval from setup
+  Find Leads starts. Do not skip this by inferring approval from setup
   answers.
 - `lead-review` / source decision asks whether to approve the selected source
   path and sample before moving into filter/message work. Do not skip this by

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

@@ -1,12 +1,12 @@
 {
   "version": "v2",
   "workflow": "create-campaign-v2",
-  "principle": "CampaignOffer state and the watch link are canonical from the first brief onward. Disk artifacts are optional debug/UAT diagnostics, not the normal customer surface. Resume, gating, and handoff read campaign state first. Start from user intake, create a watchable campaign shell with a v1 brief, update currentStep before major visible work, attach source/search state to that CampaignOffer, import the bounded review batch before post-import fit/message scouts, save rubrics and an approved message template, then queue the 15-row cascade and hand off to settings/sequence/start.",
+  "principle": "CampaignOffer state and the watch link are canonical from the first brief onward. Disk artifacts are optional debug/UAT diagnostics, not the normal customer surface. Resume, gating, and handoff read campaign state first. Start from user intake, create a watchable campaign shell with a v1 brief, update currentStep and watchNarration before major visible work, attach source/search state to that CampaignOffer, import the bounded review batch before post-import fit/message scouts, save rubrics and an approved message template, then queue the 15-row cascade and hand off to settings/sequence/start.",
   "artifactPolicy": {
     "normalCustomerPath": "Use CampaignOffer state, MCP responses, provider search state, and campaign table rows. Do not create, read, link, or surface local draft files unless debug/UAT mode is explicit or the user asks for them.",
     "debugArtifactsAreOptional": true,
     "requiredArtifactsApplyWhen": "legacy resume, fixture validation, or explicit debug/UAT mode only",
-    "customerFacingAccess": "Watch link and live campaign currentStep"
+    "customerFacingAccess": "Watch link, live campaign currentStep, and concise watchNarration"
   },
   "commitGateChoices": [
     "approve",
@@ -225,9 +225,6 @@
             "watch the draft campaign as it fills in",
             "no leads import and nothing sends yet"
           ],
-          "timeEstimates": {
-            "campaignBrief": "~1-2 min"
-          },
           "forbiddenWording": [
             "brief.md",
             "lead-review.md",
@@ -279,10 +276,12 @@
             "name",
             "campaignBrief",
             "clientProspectId or senderLinkedinUrl",
-            "currentStep"
+            "currentStep",
+            "watchNarration"
           ],
           "requiredValues": {
-            "currentStep": "create-offer"
+            "currentStep": "create-offer",
+            "watchNarration.stage": "brief-review"
           },
           "briefMode": "v1 campaign brief shown to the user; not an empty placeholder",
           "capture": [
@@ -306,7 +305,8 @@
             "campaignId",
             "watchUrl",
             "campaignBrief",
-            "currentStep:create-offer"
+            "currentStep:create-offer",
+            "watchNarration: brief-review with approve-the-brief guidance"
           ]
         },
         {
@@ -330,7 +330,7 @@
             "campaignBrief"
           ],
           "watchUrlSource": "create_campaign.watchUrl",
-          "requiredWatchUrlShape": "direct /campaign-builder/{campaignId}?mode=claude watch URL",
+          "requiredWatchUrlShape": "direct /campaign-builder/{campaignId}?mode={claude|codex} watch URL",
           "codexBrowserHandoff": {
             "openWhenAvailable": true,
             "inspectBeforeContinuing": true,
@@ -444,7 +444,7 @@
           ],
           "debugOrUatOnly": true,
           "requiredBeforeTransition": false,
-          "reconcileRule": "If debug/UAT artifacts are enabled, verify the sidecar persisted the same brief shown in chat. Normal customer lead sourcing reads CampaignOffer.campaignBrief, not brief.md.",
+          "reconcileRule": "If debug/UAT artifacts are enabled, verify the sidecar persisted the same brief shown in chat. Normal customer Find Leads work reads CampaignOffer.campaignBrief, not brief.md.",
           "chatRenderRule": "Do not block the brief approval question or find-leads transition on this step. Only mention artifact persistence if debug/UAT mode fails or the user asks."
         },
         {
@@ -457,7 +457,8 @@
           "when": "after_user_brief_confirmed_or_auto_continue",
           "fields": [
             "campaignBrief",
-            "currentStep:pick-provider"
+            "currentStep:pick-provider",
+            "watchNarration: find-leads with the first provider/lane being tested"
           ],
           "fallback": "If campaignId is missing from CampaignOffer state, stop; shell-first flow requires an existing campaign before sourcing leads.",
           "readsCampaignStateFirst": true,
@@ -512,20 +513,23 @@
           "tool": "update_campaign",
           "requiredFields": [
             "campaignId",
-            "currentStep"
+            "currentStep",
+            "watchNarration"
           ],
           "requiredValues": {
-            "currentStep": "pick-provider"
+            "currentStep": "pick-provider",
+            "watchNarration.stage": "find-leads"
           },
           "when": "before_source_scouts_or_provider_search",
-          "chatRenderRule": "Move the campaign watch view to Find Contacts before the main thread starts comparing source paths. Do not mention MCP or local artifacts."
+          "chatRenderRule": "Move the campaign watch view to Find Leads before the main thread starts comparing source paths. 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."
         },
         {
           "action": "advance_watch_to_initial_source_lane",
           "tool": "update_campaign",
           "requiredFields": [
             "campaignId",
-            "currentStep"
+            "currentStep",
+            "watchNarration"
           ],
           "currentStepByPrimaryLane": {
             "signals": "signal-discovery",
@@ -536,7 +540,7 @@
             "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. Do this before waiting on background scouts so watch mode never sits on only Pick Provider while source work happens elsewhere."
+          "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. Do this before waiting on background scouts so watch mode never sits on only Pick Provider while source work happens elsewhere."
         },
         {
           "action": "run_first_campaign_attached_source_search",
@@ -565,7 +569,7 @@
             "source decision + sample",
             "no import or enrichment yet"
           ],
-          "timeEstimate": "~3-5 min"
+          "watchNarrationRule": "Do not include time estimates. Use current, campaign-specific search reasoning instead."
         },
         {
           "action": "read_optional_source_intake",
@@ -755,7 +759,7 @@
             "import the first 15-row review batch before fit/message work",
             "selectedLeadListId stays the source list and workflowTableId is the campaign table"
           ],
-          "timeEstimate": "~2-3 min",
+          "watchNarrationRule": "Do not include time estimates. Say what review-batch work is happening and what the user will approve next.",
           "chatRenderRule": "Lead source is set. Next import and confirm only the first 15-row review batch into the campaign table. After workflowTableId exists, run the fit-filter and message-generation workstreams from the campaign table sample. If real parallel MCP/tool branches or host subagents were actually launched, say so; otherwise say the branches will run sequentially. Never claim parallelism unless parallel execution actually started."
         },
         {
@@ -929,10 +933,12 @@
           "tool": "update_campaign",
           "requiredFields": [
             "campaignId",
-            "currentStep"
+            "currentStep",
+            "watchNarration"
           ],
           "requiredValues": {
-            "currentStep": "filter-choice"
+            "currentStep": "filter-choice",
+            "watchNarration.stage": "fit-message"
           }
         }
       ],
@@ -1489,7 +1495,8 @@
             "message-review-decision.md"
           ],
           "requiredValues": {
-            "currentStep": "validate-sample"
+            "currentStep": "validate-sample",
+            "watchNarration.stage": "review-ready"
           },
           "when": "after_update_campaign_brief_succeeds",
           "requiredBeforeCascade": true,
@@ -1846,7 +1853,7 @@
             "Campaign created",
             "approved brief",
             "Open this to watch",
-            "lead sourcing",
+            "Find Leads",
             "rubric scoring",
             "messaging populate live",
             "Watch link:"
@@ -2118,10 +2125,12 @@
           "tool": "update_campaign",
           "requiredFields": [
             "campaignId",
-            "currentStep"
+            "currentStep",
+            "watchNarration"
           ],
           "requiredValues": {
-            "currentStep": "awaiting-user-greenlight"
+            "currentStep": "awaiting-user-greenlight",
+            "watchNarration.stage": "review-ready"
           }
         }
       ],
@@ -2188,7 +2197,7 @@
         },
         {
           "action": "surface_sender_and_slack_handoff",
-          "settingsUrlPattern": "/campaign-builder/{campaignId}/settings?mode=claude",
+          "settingsUrlPattern": "/campaign-builder/{campaignId}/settings?mode={claude|codex}",
           "requiredVisibleContent": [
             "connect or select a LinkedIn sender",
             "Slack reply review",

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

@@ -0,0 +1,141 @@
+# Watch Guide Narration
+
+Use one `watchNarration` object whenever you set `currentStep` or report visible
+progress in a watched create-campaign run. Do not add separate guide headline or
+body args.
+
+## Render
+
+```text
+Building campaign with {Claude Code or Codex}               [Exit watch mode]
+[progress bar]  {stage label} · Step {n} of 5
+
+{headline}
+{visibleState} {agentIntent}
+
+Next: {nextAction}
+{safety?}
+```
+
+UI owns the header, driver label, button, progress bar, step count, and static
+stage labels. The driver label comes from the watch URL mode (`mode=claude` or
+`mode=codex`), so do not add separate guide args for it. You own `stage`,
+`headline`, `visibleState`, `agentIntent`, and any exceptional `nextAction`,
+`safety`, `workerStatuses`, or `blockedReason`.
+
+## Copy Rules
+
+- One primary user action per frame.
+- Headline under 8 words.
+- Body is 1-2 short sentences total.
+- 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
+  lane/provider and campaign strategy: Signal Discovery, Sales Nav, Prospeo,
+  Apollo, or existing list.
+- During search iteration, say what you tried, what you are trying next, what
+  sample you are checking, and why that helps this campaign.
+- Avoid internal terms: MCP, tool, currentStep, workflow table, scout, debug.
+- Do not invent time estimates.
+
+## Stages
+
+| stage          | UI label      | Next          |
+| -------------- | ------------- | ------------- |
+| `brief-review` | Brief review  | Find Leads    |
+| `find-leads`   | Find Leads    | Review batch  |
+| `review-batch` | Review batch  | Fit + message |
+| `fit-message`  | Fit + message | Review ready  |
+| `review-ready` | Review ready  | Validation    |
+
+## Examples
+
+Brief review:
+
+```json
+{
+  "stage": "brief-review",
+  "headline": "Approve the brief in Codex",
+  "visibleState": "This page is a live preview of the campaign brief.",
+  "agentIntent": "Ask for changes in chat if anything looks off.",
+  "nextAction": "Find Leads"
+}
+```
+
+Signal Discovery:
+
+```json
+{
+  "stage": "find-leads",
+  "headline": "Testing Signal Discovery",
+  "visibleState": "You are watching Signal Discovery search posts about Claude Code and GTM automation.",
+  "agentIntent": "Codex is sampling engagers to see if they match the founder/operator campaign brief.",
+  "nextAction": "Review batch"
+}
+```
+
+Search iteration:
+
+```json
+{
+  "stage": "find-leads",
+  "headline": "Tightening the search",
+  "visibleState": "The first Signal Discovery search was broad, so Codex is trying a narrower Claude Code founder lane.",
+  "agentIntent": "It is sampling a few engagers before importing so the review batch stays on-brief.",
+  "nextAction": "Review batch"
+}
+```
+
+Review batch:
+
+```json
+{
+  "stage": "review-batch",
+  "headline": "Preparing your review batch",
+  "visibleState": "This page shows the leads Codex selected for review.",
+  "agentIntent": "Codex is preparing the first campaign batch from those leads.",
+  "nextAction": "Fit + message"
+}
+```
+
+Fit + message:
+
+```json
+{
+  "stage": "fit-message",
+  "headline": "Building fit and message",
+  "visibleState": "Codex is preparing the campaign's fit rules and first message sample.",
+  "agentIntent": "It is checking who should receive this campaign and what the first offer should say.",
+  "nextAction": "Review ready",
+  "workerStatuses": {
+    "leadFitBuilder": "running",
+    "messageDraftBuilder": "running"
+  }
+}
+```
+
+Review ready:
+
+```json
+{
+  "stage": "review-ready",
+  "headline": "Review fit and message",
+  "visibleState": "The fit rules and message sample are ready.",
+  "agentIntent": "Approve them or ask for changes in chat.",
+  "nextAction": "Validation",
+  "safety": "Codex will only continue after you approve."
+}
+```
+
+Blocked/recovering:
+
+```json
+{
+  "stage": "review-batch",
+  "headline": "Fixing the review batch",
+  "visibleState": "The browser is not showing the campaign batch yet.",
+  "agentIntent": "Codex is reconnecting the campaign state before moving forward.",
+  "nextAction": "Fit + message",
+  "blockedReason": "Campaign batch is not ready yet."
+}
+```

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

@@ -45,7 +45,7 @@ Cool, let's find leads.
 Atomic-mint legacy orientation:
 
 ```text
-Open this to watch lead sourcing, rubric scoring, and messaging populate live.
+Open this to watch Find Leads, rubric scoring, and messaging populate live.
 ```
 
 The exact wording may be adapted for tone, but the copy must make three things