@sellable/mcp 0.1.27 → 0.1.29

package/README.md

@@ -33,7 +33,7 @@ command.
 For Claude Code and Codex CLI:
 
 ```bash
-npx -y @sellable/install --host all --token skt_live_your_token_here --workspace-id your_workspace_id
+npx -y @sellable/install@latest --host all --token skt_live_your_token_here --workspace-id your_workspace_id
 ```
 
 Agent-readable install instructions are available at:
@@ -52,6 +52,24 @@ sh /tmp/sellable-install.sh
 Phase 112 v1 uses package stdio MCP through `@sellable/mcp`. Hosted HTTP
 MCP is a future/advanced mode until the hosted endpoint exists.
 
+Package-mode installs launch `@sellable/mcp@latest`, so each fresh host MCP
+start resolves the newest stable npm release. The MCP server also runs a cached
+startup/auth update check and tells the agent to run
+`npx -y @sellable/install@latest` when the installed runtime is behind npm.
+
+### Publishing `@sellable/mcp`
+
+Publish from the repo root with:
+
+```bash
+npm run mcp:publish
+```
+
+The script loads `.env` and `prod.env`, builds `mcp/sellable`, verifies npm auth,
+and publishes with a temporary npm config file. Prefer `NPM_TOKEN=<npm token>` in
+`prod.env`; `NODE_AUTH_TOKEN`, `SELLABLE_NPM_TOKEN`, and `NPM_PUBLISH_TOKEN` are
+also supported.
+
 ### 2. Generate API Token
 
 1. Go to https://app.sellable.dev/settings
@@ -63,7 +81,7 @@ MCP is a future/advanced mode until the hosted endpoint exists.
 Install MCP server:
 
 ```bash
-claude mcp add --transport stdio sellable -- npx -y @sellable/mcp
+claude mcp add --transport stdio sellable -- npx -y @sellable/mcp@latest
 ```
 
 Create auth config at `~/.sellable/config.json`:
@@ -83,14 +101,14 @@ The token is provided when you generate it. Use `list_workspaces` +
 For customer/package installs, use the public installer:
 
 ```bash
-npx -y @sellable/install@0.1.26 --host codex --token skt_live_your_token_here --workspace-id your_workspace_id
+npx -y @sellable/install@latest --host codex --token skt_live_your_token_here --workspace-id your_workspace_id
 ```
 
 If you already have `~/.sellable/config.json`, rerun/verify without rewriting
 auth:
 
 ```bash
-npx -y @sellable/install@0.1.26 --host codex
+npx -y @sellable/install@latest --host codex
 sellable --verify-only --host codex
 ```
 

package/dist/server.js

@@ -29,6 +29,7 @@ import { attachRecommendedSequence, attachSequence, createWorkflowTable, sequenc
 import { listTables, tableToolDefinitions } from "./tools/tables.js";
 import { handleVerifyTableRow, verifyRowToolDefinitions, } from "./tools/verify-row.js";
 import { addTeammate, createWorkspace, getActiveWorkspace, listWorkspaces, setActiveWorkspace, workspaceToolDefinitions, } from "./tools/workspaces.js";
+import { checkForUpdates, logUpdateNotice } from "./update-check.js";
 const server = new Server({
     name: "sellable-mcp",
     version: "1.0.0",
@@ -515,6 +516,11 @@ server.setRequestHandler(GetPromptRequestSchema, async (request) => {
 async function main() {
     const startTime = Date.now();
     console.error(`[sellable-mcp] pid=${process.pid} starting...`);
+    void checkForUpdates()
+        .then(logUpdateNotice)
+        .catch(() => {
+        // Update checks are advisory and must never block MCP startup.
+    });
     const transport = new StdioServerTransport();
     // Exit cleanly when parent disconnects stdin (Claude Code closed/reconnected)
     process.stdin.on("end", () => {

package/dist/tools/auth.d.ts

@@ -1,3 +1,4 @@
+import { type SellableUpdateStatus } from "../update-check.js";
 export type AuthStatus = {
     ok: boolean;
     configPath: string;
@@ -10,6 +11,7 @@ export type AuthStatus = {
     checkedAt: string;
     /** Short message the LLM MUST show the user after auth succeeds. */
     _userNotice: string | null;
+    update: SellableUpdateStatus | null;
     error: null | {
         type: "config" | "auth" | "workspace" | "api";
         status?: number;

package/dist/tools/auth.js

@@ -1,14 +1,28 @@
 import { getApi, SellableApiError } from "../api.js";
 import { getConfig, getConfigPath } from "../auth.js";
+import { checkForUpdates } from "../update-check.js";
 function maskToken(token) {
     if (token.length <= 10)
         return `${token.slice(0, 4)}...`;
     return `${token.slice(0, 8)}...${token.slice(-2)}`;
 }
+async function getUpdateStatus() {
+    try {
+        return await checkForUpdates();
+    }
+    catch {
+        return null;
+    }
+}
+function appendUpdateNotice(notice, update) {
+    if (!update?._userNotice)
+        return notice;
+    return notice ? `${notice}\n${update._userNotice}` : update._userNotice;
+}
 export const authToolDefinitions = [
     {
         name: "get_auth_status",
-        description: "Verify Sellable authentication early. Call this before any campaign work. Returns ok=false with clear guidance when the token is missing, revoked, or the active workspace is not set. IMPORTANT: When auth succeeds, ALWAYS tell the user the _userNotice message so they know which workspace is active.",
+        description: "Verify Sellable authentication early. Call this before any campaign work. Also performs a cached Sellable package update check. Returns ok=false with clear guidance when the token is missing, revoked, or the active workspace is not set. IMPORTANT: When auth succeeds, ALWAYS tell the user the _userNotice message so they know which workspace is active and whether an update is available.",
         inputSchema: {
             type: "object",
             properties: {},
@@ -20,6 +34,7 @@ export const authToolDefinitions = [
 export async function getAuthStatus() {
     const configPath = getConfigPath();
     const checkedAt = new Date().toISOString();
+    const update = await getUpdateStatus();
     const base = {
         ok: false,
         configPath,
@@ -29,7 +44,8 @@ export async function getAuthStatus() {
         activeWorkspaceName: null,
         tokenPrefix: null,
         workspacesCount: null,
-        _userNotice: null,
+        _userNotice: appendUpdateNotice(null, update),
+        update,
         checkedAt,
     };
     try {
@@ -87,7 +103,8 @@ export async function getAuthStatus() {
             activeWorkspaceName: workspaceName,
             tokenPrefix: maskToken(config.token),
             workspacesCount: workspaces.length,
-            _userNotice: notice,
+            _userNotice: appendUpdateNotice(notice, update),
+            update,
             checkedAt,
             error: null,
         };

package/dist/tools/bootstrap.d.ts

@@ -9,7 +9,7 @@ type BootstrapCreateCampaignInput = {
     refreshContext?: boolean;
 };
 type BootstrapCheck = {
-    key: "auth" | "framework" | "resume_context" | "subskill_catalog" | "create_campaign_subskill";
+    key: "auth" | "update" | "framework" | "resume_context" | "subskill_catalog" | "create_campaign_subskill";
     ok: boolean;
     blocking: boolean;
     detail: string;

package/dist/tools/bootstrap.js

@@ -10,6 +10,9 @@ function toGuidance(check, message) {
     if (check === "auth") {
         return "Run get_auth_status and fix auth/workspace setup before continuing.";
     }
+    if (check === "update") {
+        return "Run npx -y @sellable/install@latest, then restart Claude Code/Codex so Sellable reloads.";
+    }
     if (check === "framework") {
         return "Fix framework files and rerun bootstrap_create_campaign.";
     }
@@ -101,6 +104,22 @@ export async function bootstrapCreateCampaign(input = {}) {
         if (!ok) {
             pushBlockingError(blockingErrors, "auth", authCheck.status.error?.message || "Authentication check failed.");
         }
+        const update = authCheck.status.update;
+        if (update && !update.disabled) {
+            requiredChecks.push({
+                key: "update",
+                ok: !update.blocking,
+                blocking: update.blocking,
+                detail: update.updateAvailable
+                    ? update._userNotice || "A newer Sellable MCP package is available."
+                    : update.mcp.latestVersion
+                        ? `Sellable MCP is current (${update.mcp.currentVersion ?? "unknown"}).`
+                        : "Sellable MCP update check completed without latest-version data.",
+            });
+            if (update.blocking) {
+                pushBlockingError(blockingErrors, "update", update._userNotice || "Sellable MCP update required.");
+            }
+        }
     }
     catch (error) {
         const message = toErrorMessage(error);

package/dist/tools/leads.js

@@ -2205,10 +2205,18 @@ export async function confirmLeadList(input) {
         ...(shouldSetCurrentStep ? { currentStep: effectiveCurrentStep } : {}),
     });
     const campaignTableId = importResult.workflowTableId ?? importResult.campaignTableId;
-    if (campaignTableId) {
+    // Persist currentStep if the caller asked for it. Do NOT touch
+    // selectedLeadListId here: the campaign table id is already saved to
+    // CampaignOffer.workflowTableId by /api/v3/campaign-builder/import-leads,
+    // and selectedLeadListId must remain pointing at the source lead list
+    // (config.type === "lead_list") so the UI's Continue handler — which feeds
+    // selectedLeadListId back into /api/v3/campaign-builder/import-leads as
+    // sourceLeadListId — can find a valid lead list. Overwriting it with the
+    // campaign table id makes that endpoint 404 with "Lead list not found"
+    // and silently breaks the Leads → Filter Continue button.
+    if (shouldSetCurrentStep) {
         await api.put(`/api/v2/campaign-offers/${campaignOfferId}`, {
-            selectedLeadListId: campaignTableId,
-            ...(shouldSetCurrentStep ? { currentStep: effectiveCurrentStep } : {}),
+            currentStep: effectiveCurrentStep,
         });
     }
     return {

package/dist/update-check.d.ts

@@ -0,0 +1,25 @@
+export type PackageUpdateStatus = {
+    packageName: string;
+    currentVersion: string | null;
+    latestVersion: string | null;
+    outdated: boolean;
+    error?: string;
+};
+export type SellableUpdateStatus = {
+    checkedAt: string;
+    cachePath: string;
+    fromCache: boolean;
+    disabled: boolean;
+    mcp: PackageUpdateStatus;
+    installer: PackageUpdateStatus;
+    updateAvailable: boolean;
+    blocking: boolean;
+    guidance: string | null;
+    _userNotice: string | null;
+};
+export declare function checkForUpdates(options?: {
+    force?: boolean;
+    timeoutMs?: number;
+    ttlMs?: number;
+}): Promise<SellableUpdateStatus>;
+export declare function logUpdateNotice(status: SellableUpdateStatus): void;

package/dist/update-check.js

@@ -0,0 +1,210 @@
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+const MCP_PACKAGE = "@sellable/mcp";
+const INSTALL_PACKAGE = "@sellable/install";
+const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000;
+const DEFAULT_TIMEOUT_MS = 1500;
+function cachePath() {
+    return path.join(os.homedir(), ".sellable", "update-check.json");
+}
+function readCurrentVersion() {
+    const entrypointDir = process.argv[1]
+        ? path.dirname(path.resolve(process.argv[1]))
+        : process.cwd();
+    const candidates = [
+        path.resolve(entrypointDir, "..", "package.json"),
+        path.resolve(process.cwd(), "mcp/sellable/package.json"),
+    ];
+    for (const pkgPath of candidates) {
+        try {
+            const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+            if (pkg.name === MCP_PACKAGE && typeof pkg.version === "string") {
+                return pkg.version;
+            }
+        }
+        catch {
+            // Keep looking; version detection is advisory only.
+        }
+    }
+    return null;
+}
+function registryPackagePath(packageName) {
+    return encodeURIComponent(packageName);
+}
+async function fetchLatestVersion(packageName, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetch(`https://registry.npmjs.org/${registryPackagePath(packageName)}/latest`, {
+            signal: controller.signal,
+            headers: {
+                Accept: "application/json",
+                "User-Agent": "sellable-mcp-update-check",
+            },
+        });
+        if (!response.ok) {
+            throw new Error(`npm registry returned ${response.status}`);
+        }
+        const body = (await response.json());
+        if (typeof body.version !== "string" || !body.version) {
+            throw new Error("npm registry response did not include a version");
+        }
+        return body.version;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function parseVersion(version) {
+    if (!version)
+        return null;
+    const match = version.match(/^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/);
+    if (!match)
+        return null;
+    return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+function isVersionOutdated(currentVersion, latestVersion) {
+    const current = parseVersion(currentVersion);
+    const latest = parseVersion(latestVersion);
+    if (!current || !latest)
+        return false;
+    for (let i = 0; i < 3; i += 1) {
+        if (current[i] < latest[i])
+            return true;
+        if (current[i] > latest[i])
+            return false;
+    }
+    return false;
+}
+function readCache(ttlMs) {
+    const file = cachePath();
+    try {
+        const raw = JSON.parse(fs.readFileSync(file, "utf8"));
+        if (!raw.checkedAtMs || Date.now() - raw.checkedAtMs > ttlMs)
+            return null;
+        return {
+            ...raw,
+            cachePath: file,
+            fromCache: true,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function writeCache(status) {
+    const file = cachePath();
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+        const { fromCache: _fromCache, ...cacheableStatus } = status;
+        const cache = {
+            ...cacheableStatus,
+            cachePath: file,
+            checkedAtMs: Date.now(),
+        };
+        fs.writeFileSync(file, `${JSON.stringify(cache, null, 2)}\n`, {
+            mode: 0o600,
+        });
+    }
+    catch {
+        // Update checks must never break MCP startup or tool execution.
+    }
+}
+function disabledStatus(currentVersion) {
+    return {
+        checkedAt: new Date().toISOString(),
+        cachePath: cachePath(),
+        fromCache: false,
+        disabled: true,
+        mcp: {
+            packageName: MCP_PACKAGE,
+            currentVersion,
+            latestVersion: null,
+            outdated: false,
+        },
+        installer: {
+            packageName: INSTALL_PACKAGE,
+            currentVersion: null,
+            latestVersion: null,
+            outdated: false,
+        },
+        updateAvailable: false,
+        blocking: false,
+        guidance: null,
+        _userNotice: null,
+    };
+}
+function buildNotice(mcp, installer) {
+    if (!mcp.outdated)
+        return null;
+    const versions = mcp.currentVersion && mcp.latestVersion
+        ? `${mcp.currentVersion} -> ${mcp.latestVersion}`
+        : "a newer version is available";
+    const installerVersion = installer.latestVersion
+        ? ` The latest installer is ${installer.latestVersion}.`
+        : "";
+    return `Sellable update available: ${versions}. Run: npx -y @sellable/install@latest.${installerVersion}`;
+}
+export async function checkForUpdates(options) {
+    const currentVersion = readCurrentVersion();
+    const ttlMs = options?.ttlMs ??
+        (Number(process.env.SELLABLE_UPDATE_CHECK_TTL_MS || "") || DEFAULT_TTL_MS);
+    const timeoutMs = options?.timeoutMs ??
+        (Number(process.env.SELLABLE_UPDATE_CHECK_TIMEOUT_MS || "") ||
+            DEFAULT_TIMEOUT_MS);
+    if (process.env.SELLABLE_UPDATE_CHECK_DISABLED === "1") {
+        return disabledStatus(currentVersion);
+    }
+    if (!options?.force) {
+        const cached = readCache(ttlMs);
+        if (cached)
+            return cached;
+    }
+    const [mcpResult, installerResult] = await Promise.allSettled([
+        fetchLatestVersion(MCP_PACKAGE, timeoutMs),
+        fetchLatestVersion(INSTALL_PACKAGE, timeoutMs),
+    ]);
+    const mcpLatest = mcpResult.status === "fulfilled" ? mcpResult.value : null;
+    const installerLatest = installerResult.status === "fulfilled" ? installerResult.value : null;
+    const mcp = {
+        packageName: MCP_PACKAGE,
+        currentVersion,
+        latestVersion: mcpLatest,
+        outdated: isVersionOutdated(currentVersion, mcpLatest),
+        ...(mcpResult.status === "rejected"
+            ? { error: mcpResult.reason?.message || String(mcpResult.reason) }
+            : {}),
+    };
+    const installer = {
+        packageName: INSTALL_PACKAGE,
+        currentVersion: null,
+        latestVersion: installerLatest,
+        outdated: false,
+        ...(installerResult.status === "rejected"
+            ? {
+                error: installerResult.reason?.message || String(installerResult.reason),
+            }
+            : {}),
+    };
+    const notice = buildNotice(mcp, installer);
+    const status = {
+        checkedAt: new Date().toISOString(),
+        cachePath: cachePath(),
+        fromCache: false,
+        disabled: false,
+        mcp,
+        installer,
+        updateAvailable: mcp.outdated,
+        blocking: false,
+        guidance: notice ? "Run npx -y @sellable/install@latest" : null,
+        _userNotice: notice,
+    };
+    writeCache(status);
+    return status;
+}
+export function logUpdateNotice(status) {
+    if (status._userNotice) {
+        console.error(`[sellable-mcp] ${status._userNotice}`);
+    }
+}

package/package.json

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

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

@@ -118,6 +118,8 @@ Validated draft directory:
   loading, runbooks, local skill files, skill versions, or "Sellable token".
   "Quick question panel" is only acceptable when explaining a Codex/Claude setup
   blocker.
+- Before campaign mint, do not call `check_rubric`; Phase 84 only writes and
+  validates draft artifacts.
 - Never narrate local draft housekeeping to the user. If you create directories,
   save drafts, write artifacts, or persist intermediate state, translate it into
   the campaign benefit: consistent brief, approved lead source, reviewed message,
@@ -394,6 +396,9 @@ should test for this campaign. Those can run in parallel and usually take
 - Before the user chooses `approve`, the mutating live-campaign tools are
   forbidden: `create_campaign`, `save_rubrics`, `import_leads`,
   `confirm_lead_list`, `update_campaign`, `queue_cells`, and `start_campaign`.
+- During pre-approval validation, do not call `check_rubric`; use the
+  campaignless lead-filter artifacts and only use campaign-backed scoring after
+  the approval flow allows it.
 - Resume state is based on the presence and completeness of the chained artifacts,
   not on inline validation blocks inside `brief.md`.
 - Preserve the Phase 83 thesis. Do not rewrite product, ICP, offer, or message
@@ -868,34 +873,40 @@ Orchestration requirements:
   before category nouns like `platform` or `MCP`.
 - pass the Thomas revision filters before writing findings
 - immediately after `message-validation.md` is confirmed and reconciled with
-  `lead-filter.md`, write `message-review.md` and render it inline starting
-  with `Status: message-review` as the first visible line. Do not put a
-  markdown heading, preface, or summary before that status line. This is a
-  customer checkpoint, not an audit report: show the approved campaign message
-  template first, then show one filled sample prospect version immediately after
-  it so the user can judge whether the tokens are being used correctly. Then
-  show rendered examples that prove the tokens fill well and can be omitted
-  cleanly when row data is weak. Keep the detailed
-  gold-standard/rule audit inside `message-validation.md`, not in the
-  user-facing review. The review must use this exact label shape so the gate can
-  be parsed: `Subject: ...`, `Tokenized template: ...`, `Sample prospect fill:
-  ...`, `Rendered examples: ...`, `Good token fill: ...`, `Good omit: ...`,
-  `Bad token fill: ...`, `Why bad: ...`, `Fallback if missing: ...`,
-  `Token notes: ...`, `My take: ...`, `Suggested adjustment: ...`,
-  `Question: approve-message or revise-messaging?`, `Recommendation:
-approve-message|revise-messaging`.
-- Never ask the message approval question until the full message review is
-  visible in the chat. A summary like `Message review is ready` or `the draft
-avoids a generic pitch` is not enough. The user must see the actual subject,
-  the actual tokenized message template, one filled sample prospect version, at
-  least one good filled example, one good omit example, one bad fill example,
-  why the bad fill is wrong, fallback rules for missing row data, token notes,
-  your take, and the suggested adjustment before any `approve-message` /
-  `revise-messaging` question appears. If you catch yourself wanting to offer
-  `show me message` as a choice, stop: render the message review first, then ask
-  only `approve-message` or `revise-messaging`.
-  Include `Open artifacts:` links to `message-review.md` and
-  `message-validation.md` before the approval question.
+  `lead-filter.md`, write `message-review.md` and render the slim chat version
+  inline starting with `Status: message-review` as the first visible line. Do
+  not put a markdown heading, preface, or summary before that status line.
+  This is a customer checkpoint optimized for fast approve / revise judgment.
+- Chat-vs-file split (this is the rule the user pinned):
+  - `message-review.md` (the file) keeps the full detail: `Status:
+message-review`, `Subject:`, `Tokenized template:`, `Sample prospect fill:` + `Token fill basis:`, `Rendered examples:`, `Good token fill:`,
+    `Good omit:`, `Bad token fill:`, `Why bad:`, `Fallback if missing:`,
+    `Token notes:`, `My take:`, `Suggested adjustment:`, `Question:
+approve-message or revise-messaging?`, `Recommendation:
+approve-message|revise-messaging`. The detailed gold-standard/rule audit
+    stays in `message-validation.md`. Both files are unchanged in scope and
+    are still required.
+  - The chat rendering shows ONLY: `Status: message-review`, `Subject:`,
+    `Tokenized template:`, `Sample prospect fill:` (with `Token fill basis:`),
+    `My take:`, `Suggested adjustment:`, `Question: approve-message or
+revise-messaging?`, `Recommendation:`. Then `Open artifacts:` links to
+    `message-review.md` and `message-validation.md` so the user can read the
+    full token guidance, good/omit/bad examples, and fallbacks if they want
+    to before deciding.
+  - Do NOT inline `Rendered examples:`, `Good token fill:`, `Good omit:`,
+    `Bad token fill:`, `Why bad:`, `Fallback if missing:`, or `Token notes:`
+    in chat. Those exist in the file and are linked. Keeping them out of
+    chat is what makes the gate easy to approve or revise on.
+- Never ask the message approval question until the slim chat review is fully
+  visible. A summary like `Message review is ready` or `the draft avoids a
+generic pitch` is not enough. The user must see the actual subject, the
+  actual tokenized message template, one filled sample prospect version with
+  its token fill basis, your take, and the suggested adjustment before any
+  `approve-message` / `revise-messaging` question appears. If you catch
+  yourself wanting to offer `show me message` as a choice, stop: render the
+  slim chat review first, then ask only `approve-message` or
+  `revise-messaging`. Include `Open artifacts:` links to `message-review.md`
+  and `message-validation.md` before the approval question.
 - `My take:` and `Suggested adjustment:` are mandatory customer-facing decision
   fields, not optional summary text. They must appear after `Token notes:` and
   before the question in every rendered message review. They must each be

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

@@ -605,25 +605,23 @@
             "subject",
             "tokenized template",
             "sample prospect fill",
-            "rendered examples",
-            "bad token examples",
-            "token notes",
             "my take",
             "suggested adjustment",
             "question",
             "recommendation"
           ],
           "mustRenderInlineBeforeQuestion": true,
-          "minimumVisibleMessageDetail": "full_message_review_before_question",
+          "minimumVisibleMessageDetail": "tokenized_template_plus_sample_fill_only",
           "requiredArtifactLinks": [
             "message-review.md",
             "message-validation.md"
           ],
           "artifactLinkTiming": "before_approval_question",
-          "requiredLabels": [
+          "requiredFileLabels": [
             "Subject:",
             "Tokenized template:",
             "Sample prospect fill:",
+            "Token fill basis:",
             "Rendered examples:",
             "Good token fill:",
             "Good omit:",
@@ -636,6 +634,18 @@
             "Question: approve-message or revise-messaging?",
             "Recommendation:"
           ],
+          "requiredChatLabels": [
+            "Status: message-review",
+            "Subject:",
+            "Tokenized template:",
+            "Sample prospect fill:",
+            "Token fill basis:",
+            "My take:",
+            "Suggested adjustment:",
+            "Question: approve-message or revise-messaging?",
+            "Recommendation:"
+          ],
+          "chatRenderRule": "Show ONLY the tokenized template and one filled sample prospect version (with Token fill basis), then My take, Suggested adjustment, Question, Recommendation, and Open artifacts links. Do NOT inline Rendered examples, Good token fill, Good omit, Bad token fill, Why bad, Fallback if missing, or Token notes — those live in message-review.md and message-validation.md only.",
           "allowedRecommendations": ["approve-message", "revise-messaging"],
           "judgeAgainst": [
             "generate-messages rules",
@@ -670,13 +680,7 @@
             "Subject:",
             "Tokenized template:",
             "Sample prospect fill:",
-            "Rendered examples:",
-            "Good token fill:",
-            "Good omit:",
-            "Bad token fill:",
-            "Why bad:",
-            "Fallback if missing:",
-            "Token notes:",
+            "Token fill basis:",
             "My take:",
             "Suggested adjustment:",
             "Recommendation:"

package/skills/research-sender/SKILL.md

@@ -1,120 +1,82 @@
 ---
 name: research-sender
-description: Enrichment-first sender research protocol. 0-3 agents, 30s target.
+description: Parallel-first sender research protocol. One round of batched tool calls, ~10-15s wall time.
 visibility: internal
 ---
 
-# Research Sender (Enrichment-First)
+# Research Sender (Parallel-First)
 
 Use this subskill when creating campaigns and you need sender/company research.
 This protocol is standalone and does not depend on the generic `research` subskill.
 
-## Core Architecture
+## Core Idea — Don't Wait, Fan Out
 
-`enrich_sender` compact mode already returns `companySnapshot`, `senderBackground`, and `proofDigest`.
-Four of the old five research agents duplicated this data. Only Growth Signals + Case Studies are net-new.
-When `companySnapshot.description` is missing/thin, we also run a tiny positioning snippet pass (1 WebSearch) so we don't end up with blank company context.
+Old protocol: call `enrich_sender` → wait for partial → maybe spawn 2-3 subagents → wait.
+That's 3-4 sequential rounds and ~60s+ wall time.
 
-**This protocol uses enrichment as the baseline and only spawns extra work when proof or positioning context is missing.**
+New protocol: **fire one parallel batch.** `enrich_sender` (5-8s, returns
+`clientProspectId` + baseline) runs alongside 2-3 `WebSearch` calls. They all
+finish in the same ~10s window, then you synthesize.
+
+The `enrich_sender` call is still required because downstream tools
+(`create_campaign`, `attach_sequence`, message generation) need the
+`clientProspectId` it produces and the cached `EnrichedProspect` row it writes.
+Don't skip it — just stop waiting for it before doing the rest of the research.
 
 ## Inputs
 
 Provide as many as available. Use `"Unknown"` for missing values.
 
+- `linkedinUrl` (REQUIRED)
 - `name`
 - `title`
 - `companyName`
-- `companyDomain`
-- `companyLinkedinUrl` (optional)
-- `linkedinUrl` (optional)
+- `companyDomain` (REQUIRED for WebSearch — derive from email or LinkedIn if absent)
 - `headline` (optional)
-- `enrichSender` response (REQUIRED — must include `companySnapshot`, `senderBackground`, `proofDigest`)
-
-## Depth Decision (Deterministic — from proofDigest)
-
-Check the `proofDigest` from the `enrich_sender` compact response:
-
-### `minimal-verification` (0-1 agent, 0-1 web calls, ~2-10 seconds)
-
-**Condition:** `proofDigest.caseStudyCount > 0` AND `proofDigest.reviewHighlight` exists (not null)
-
-- Do NOT spawn proof/growth agents (Case Studies, Growth Signals).
-- If `companySnapshot.description` is missing/thin, spawn the **Company Positioning** agent (1 WebSearch, no WebFetch).
-- Synthesize directly from enrichment data (companySnapshot + senderBackground + proofDigest) plus Agent 3 if used.
-- Call `complete_sender_research()` immediately with enrichment counts.
-- ~0 additional tokens.
-
-### `deep-proof` (2-3 agents in parallel, max 5 tool calls total, ~30 seconds)
 
-**Condition:** `proofDigest.caseStudyCount === 0` OR `proofDigest.reviewHighlight` is null
+## The One Round (Mandatory Parallel Batch)
 
-- Spawn exactly **2 agents in parallel** (Case Studies + Growth Signals).
-- If `companySnapshot.description` is missing/thin, also spawn **1 positioning agent** (Company Positioning) in parallel.
-- Homepage, Company LinkedIn, Reviews → all covered by enrichment, skip these entirely.
-- ~100k tokens total.
+Issue ALL of the following in a single tool-call batch (Task subagents,
+`multi_tool_use.parallel`, or whatever batching primitive your host exposes).
+Do NOT issue any of them sequentially — that defeats the protocol.
 
-## Positioning Context (Conditional — from companySnapshot.description)
+1. `enrich_sender({ linkedinUrl, companyDomain })` — baseline + `clientProspectId`.
+2. `WebSearch`: `site:{companyDomain} ("case study" OR "customer story" OR testimonial OR "success story") "{companyName}"` — proof.
+3. `WebSearch`: `"{companyName}" {companyDomain} {currentYear} (funding OR raised OR seed OR series OR hiring OR launch OR "press release")` — growth/credibility.
+4. `WebSearch` (conditional, include unless you have strong positioning context already): `"{companyName}" about product site:{companyDomain}` — positioning.
 
-If `companySnapshot.description` is null/undefined or shorter than ~120 characters, run the **Company Positioning** agent (1 WebSearch, no WebFetch).
+That's it. No subagent fan-out. No second round of enrichment polling.
 
-## Execution Backend Routing
-
-Choose backend once:
-
-1. If `Task` is available: use Task subagents in parallel (Claude host).
-2. Else if `multi_tool_use.parallel` is available: batch independent tool calls (Codex host).
-3. Else: run units sequentially.
-
-Never claim Task subagents were used when they were not.
-
-## Agent Prompts (when needed)
-
-### Agent 1: Case Studies + Proof (max 3 tool calls)
-
-```json
-{
-  "subagent_type": "general-purpose",
-  "model": "haiku",
-  "description": "Case studies and proof",
-  "prompt": "Find 1-3 concrete proof items for {companyName} ({companyDomain}).\n\nUse only: WebSearch, WebFetch.\n\nTool budget:\n- 1 WebSearch\n- Up to 2 WebFetch (only if the page looks like a case study/testimonial with named customers or metrics)\n\nWebSearch query (run exactly once):\nsite:{companyDomain} (\"case study\" OR \"customer story\" OR testimonial OR results OR \"success story\") \"{companyName}\"\n\nWebFetch: pick up to 2 results that look most likely to contain named customers or metrics.\nIf a fetched page is JS-heavy/empty, skip it and use snippets.\nDo not do a second search.\n\nReturn EXACTLY:\n---\nPROOF_OPTIONS: [Up to 3 items. Each: customer + outcome/metric + timeframe if present; or 'None found']\nSOURCES: [Short source hints]\n---\nKeep under 120 words. No extra commentary."
-}
-```
+## Synthesis (Single Pass After Batch Returns)
 
-### Agent 2: Growth/Credibility Signals (max 1 tool call)
+Merge the four results. Treat `enrich_sender` as the authoritative baseline
+for company/sender facts; treat WebSearch as proof and signals.
 
-```json
-{
-  "subagent_type": "general-purpose",
-  "model": "haiku",
-  "description": "Growth and credibility signals",
-  "prompt": "Find recent growth/credibility signals for {companyName} ({companyDomain}).\n\nUse only: WebSearch.\nTool budget: 1 WebSearch.\n\nWebSearch query (run exactly once):\n\"{companyName}\" {companyDomain} {currentYear} (funding OR raised OR seed OR series OR hiring OR \"we're hiring\" OR launch OR announcement OR \"press release\")\n\nReturn EXACTLY:\n---\nHIRING: [Notable signals or 'None found']\nFUNDING: [Round, amount, date or 'None found']\nPRESS: [Recent announcement or 'None found']\n---\nKeep under 90 words. No extra commentary."
-}
-```
-
-### Agent 3: Company Positioning (max 1 tool call)
+```markdown
+## {Company} - Sender Research
 
-```json
-{
-  "subagent_type": "general-purpose",
-  "model": "haiku",
-  "description": "Company positioning context",
-  "prompt": "If the enrichment company description is missing/thin, pull a crisp positioning summary for {companyName} ({companyDomain}) using only search snippets.\n\nUse only: WebSearch.\nTool budget: 1 WebSearch.\n\nWebSearch query (run exactly once):\n\"{companyName}\" about product site:{companyDomain}\n\nReturn EXACTLY:\n---\nPOSITIONING: [1-2 sentences]\nICP: [1 short line, or 'Unknown']\nDIFFERENTIATORS: [Up to 3 short bullets, or 'Unknown']\nSOURCES: [Short source hints]\n---\nKeep under 90 words. No extra commentary."
-}
+**Company Context:** [companySnapshot.description OR positioning WebSearch top result]
+**Industry / Size:** [companySnapshot.industry + employeeRange]
+**Positioning Notes:** [proofDigest.positioningOneLiner + keyDifferentiators]
+**Proof Options:** [proofDigest.caseStudySummary + case-study WebSearch hits — pick 1-3 with named customers / metrics]
+**Credibility Signals:** [proofDigest.reviewHighlight + growth WebSearch hits (funding, hiring, press)]
+**Gaps:** [what's still missing — usually fine to ship with this]
 ```
 
-## Synthesis (Orchestrator — No Agents)
+If `enrich_sender` returns `enrichmentStatus: "partial"`, that's expected and
+fine — `companySnapshot` and `senderBackground` are populated immediately.
+`proofDigest` may be null on partial; in that case rely on WebSearch results
+for proof and credibility, not on a second enrichment poll.
 
-After agents return (or immediately for minimal-verification), merge enrichment baseline + agent findings:
+## Optional Deepen (Only If Synthesis Reveals A Hard Gap)
 
-```markdown
-## {Company} - Sender Research
+If after synthesis you genuinely have zero proof and zero credibility
+signals, AND the campaign fixture/operator told you proof is required, you
+MAY issue ONE additional WebFetch on the most promising case-study URL from
+batch step 2. Cap at one WebFetch. No subagents, no second WebSearch round.
 
-**Company Context:** [companySnapshot.description OR Agent 3 POSITIONING] + [companySnapshot.industry + employeeRange]
-**Positioning Notes:** [proofDigest.positioningOneLiner + keyDifferentiators + Agent 3 DIFFERENTIATORS (if present)]
-**Proof Options:** [proofDigest.caseStudySummary + agent upgrades if deep-proof]
-**Credibility Signals:** [proofDigest.reviewHighlight + agent growth signals if deep-proof]
-**Gaps:** [what's missing]
-```
+If that still yields nothing, set `proofItemsFound: 0` in
+`complete_sender_research` and proceed; the brief can ship without proof.
 
 ## Completion Marker (Required)
 
@@ -124,7 +86,7 @@ After synthesis, call:
 
 Count rules:
 
-- `depth`: "minimal-verification" or "deep-proof"
+- `depth`: always `"parallel-batch"` for this protocol.
 - `proofItemsFound`: number of concrete proof items you would confidently use.
 - `caseStudyItemsFound`: number of usable case-study examples.
 - `credibilitySignalsFound`: number of trust signals (reviews/ratings/funding/hiring/press).
@@ -133,26 +95,21 @@ If no reliable evidence is found, set counts to 0 and include that in `notes`.
 
 ## Progress UX
 
-If launching deep-proof agents:
+Before issuing the parallel batch:
 
 ```
-Running a quick research pass for case studies and growth signals (~30s)...
+Pulling sender enrichment + case studies + growth signals + positioning in parallel (~10s)...
 ```
 
-If also launching the Company Positioning agent:
+After synthesis:
 
 ```
-Running a quick research pass for case studies, growth signals, and positioning (~30s)...
+Sender research ready — {proofItemsFound} proof items, {credibilitySignalsFound} credibility signals.
 ```
 
-If only launching the Company Positioning agent:
+## What Changed From The Previous Protocol
 
-```
-Pulling a quick positioning summary from search snippets (~10s)...
-```
-
-If skipping agents (minimal-verification):
-
-```
-Enrichment already has strong proof — synthesizing directly from baseline data.
-```
+- No "minimal-verification vs deep-proof" branch. Always run the same parallel batch.
+- No spawn of `general-purpose` subagents for research — WebSearch from the orchestrator turn is faster and cheaper.
+- No waiting on `enrich_sender` before issuing WebSearch.
+- One round, one synthesis, one `complete_sender_research` call.