@sellable/mcp 0.1.255 → 0.1.257

package/dist/tools/tables.d.ts

@@ -14,7 +14,13 @@ export interface ListTablesInput {
     limit?: number;
     hasSequence?: boolean;
 }
-export declare const tableToolDefinitions: {
+export interface ExportTableCsvInput {
+    tableId: string;
+    filters?: unknown[];
+    sort?: Record<string, unknown>;
+    splitRows?: number;
+}
+export declare const tableToolDefinitions: ({
     name: string;
     description: string;
     inputSchema: {
@@ -28,8 +34,53 @@ export declare const tableToolDefinitions: {
                 type: string;
                 description: string;
             };
+            tableId?: undefined;
+            filters?: undefined;
+            sort?: undefined;
+            splitRows?: undefined;
         };
         required: never[];
+        additionalProperties?: undefined;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            tableId: {
+                type: string;
+            };
+            filters: {
+                type: string;
+                description: string;
+                items: {
+                    type: string;
+                };
+            };
+            sort: {
+                type: string;
+                description: string;
+            };
+            splitRows: {
+                type: string;
+                description: string;
+            };
+            limit?: undefined;
+            hasSequence?: undefined;
+        };
+        required: string[];
+        additionalProperties: boolean;
     };
-}[];
+})[];
 export declare function listTables(input: ListTablesInput): Promise<WorkflowTableListItem[]>;
+export declare function exportTableCsv(input: ExportTableCsvInput): Promise<{
+    tableId: string;
+    endpoint: string;
+    totalRows: number;
+    files: Array<{
+        path: string;
+        rows: number;
+    }>;
+    splitRows: number | null;
+}>;

package/dist/tools/tables.js

@@ -1,3 +1,7 @@
+import { parse } from "csv-parse/sync";
+import { mkdir, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
 import { getApi } from "../api.js";
 export const tableToolDefinitions = [
     {
@@ -19,6 +23,31 @@ export const tableToolDefinitions = [
             required: [],
         },
     },
+    {
+        name: "export_table_csv",
+        description: "Export a workflow table using the existing Sellable Export CSV endpoint. Optional filters/sort are passed through and splitRows writes deterministic CSV batches.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                tableId: { type: "string" },
+                filters: {
+                    type: "array",
+                    description: "Optional workflow-table filters to pass through.",
+                    items: { type: "object" },
+                },
+                sort: {
+                    type: "object",
+                    description: "Optional workflow-table sort object to pass through.",
+                },
+                splitRows: {
+                    type: "number",
+                    description: "Optional data rows per split file.",
+                },
+            },
+            required: ["tableId"],
+            additionalProperties: false,
+        },
+    },
 ];
 export async function listTables(input) {
     const api = getApi();
@@ -34,3 +63,52 @@ export async function listTables(input) {
     const result = await api.get(path);
     return result.tables;
 }
+const csvEscape = (value) => {
+    const text = value == null ? "" : String(value);
+    if (/[",\n\r]/.test(text)) {
+        return `"${text.replace(/"/g, '""')}"`;
+    }
+    return text;
+};
+const toCsv = (records) => records.map((row) => row.map(csvEscape).join(",")).join("\n") + "\n";
+export async function exportTableCsv(input) {
+    if (!input.tableId) {
+        throw new Error("tableId is required");
+    }
+    const params = new URLSearchParams();
+    if (input.filters)
+        params.set("filters", JSON.stringify(input.filters));
+    if (input.sort)
+        params.set("sort", JSON.stringify(input.sort));
+    const endpoint = `/api/v3/workflow-tables/${input.tableId}/export-csv${params.toString() ? `?${params.toString()}` : ""}`;
+    const api = getApi();
+    const csv = await api.getText(endpoint);
+    const records = parse(csv, {
+        bom: true,
+        relax_column_count: true,
+    });
+    const header = records[0] ?? [];
+    const dataRows = records.slice(1);
+    const splitRows = Number.isInteger(input.splitRows) && input.splitRows > 0
+        ? input.splitRows
+        : null;
+    const outputDir = path.join(tmpdir(), "sellable-mcp-exports", `${input.tableId}-${Date.now()}`);
+    await mkdir(outputDir, { recursive: true });
+    const chunks = splitRows && dataRows.length > 0
+        ? Array.from({ length: Math.ceil(dataRows.length / splitRows) }, (_, index) => dataRows.slice(index * splitRows, index * splitRows + splitRows))
+        : [dataRows];
+    const files = [];
+    for (let index = 0; index < chunks.length; index++) {
+        const chunk = chunks[index];
+        const filePath = path.join(outputDir, chunks.length === 1 ? "export.csv" : `export-${index + 1}.csv`);
+        await writeFile(filePath, toCsv([header, ...chunk]), "utf8");
+        files.push({ path: filePath, rows: chunk.length });
+    }
+    return {
+        tableId: input.tableId,
+        endpoint,
+        totalRows: dataRows.length,
+        files,
+        splitRows,
+    };
+}

package/package.json

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

package/skills/create-campaign/SKILL.md

@@ -58,7 +58,6 @@ allowed-tools:
   - mcp__sellable__get_rows
   - mcp__sellable__get_rows_minimal
   - mcp__sellable__get_table_rows
-  - mcp__sellable__list_dnc_entries
   - mcp__sellable__load_csv_dnc_entries
   - mcp__sellable__load_csv_linkedin_leads
   - mcp__sellable__load_csv_domains
@@ -102,11 +101,6 @@ are for known-account targeting only, not DNC. Campaign creation already
 includes a `DNC Check` column that checks domain and LinkedIn profile before
 message generation.
 
-If the user asks to show/check the current DNC list, count, list names, or first
-page before importing, call `list_dnc_entries`. Confirm the active workspace
-name and ID in the response before any write. This is Sellable's workspace DNC
-list used by DNC Check.
-
 ## Opening Turn Contract
 
 On the first visible response after this skill is invoked, do not narrate

package/skills/create-campaign-v2/references/filter-leads.md

@@ -219,8 +219,6 @@ belong in the recommendation as DNC/suppression instructions outside the rubric
 DNC imports/suppression lists are handled through `load_csv_dnc_entries` outside
 `leadScoringRubrics`. The import previews the exact Sellable workspace name and
 ID, then writes to Sellable's workspace-level DNC list only after confirmation.
-If the user asks to show the current DNC count, list names, or first page before
-import, call `list_dnc_entries` and report the active workspace name and ID.
 Campaign creation already includes `DNC Check`, which checks domain/profile
 before message generation. Do not describe provider workarounds, provider
 search-time limitations, or Prospeo domain filters as the DNC mechanism.

package/skills/create-campaign-v2/references/lead-validation-preview.md

@@ -50,8 +50,6 @@ Supplied-source preview:
   preview. Preview the exact Sellable workspace name and ID and confirm before
   writing. This updates Sellable's workspace-level DNC list; it is not a lead
   source, Prospeo domain filter, or provider workaround.
-  If the user asks for the existing DNC count, list names, or first page first,
-  call `list_dnc_entries` and report the active workspace name and ID.
 - `supplied-linkedin-profiles` uses `load_csv_linkedin_leads` before the
   15-lead import batch only as preview/source attachment. Pre-import calls
   must omit provider-import parameters. Use `campaignOfferId` only to attach the

package/skills/create-campaign-v2/references/step-13-import-leads.md

@@ -61,9 +61,7 @@ Supported branches:
   Sellable workspace name and ID, and confirmation writes only to that
   workspace's Sellable DNC list. This is not a lead source and does not create a
   `domainFilterId`; campaign rows are protected later by the existing
-  `DNC Check` column before message generation. If the user asks for the
-  current DNC count, list names, or first page before import, call
-  `list_dnc_entries` first.
+  `DNC Check` column before message generation.
 - **Supplied LinkedIn profile CSV** — confirm `load_csv_linkedin_leads` only
   after the user approves that supplied-list source. Batch/materialize the
   uploaded CSV into a Sellable lead-list table. Persist the returned

package/skills/create-post/SKILL.md

@@ -84,6 +84,7 @@ Before drafting, load all required assets with `mcp__sellable__get_subskill_asse
 3. `subskillName: "create-post", assetPath: "references/premise-development.md"`
 4. `subskillName: "create-post", assetPath: "references/post-validation.md"`
 5. `subskillName: "create-post", assetPath: "references/gold-standard-post-pack.md"`
+6. `subskillName: "create-post", assetPath: "references/linkedin-preview-rendering.md"`
 
 If any required asset is missing, unreadable, truncated without continuation, or internally inconsistent, return:
 
@@ -304,7 +305,8 @@ If local idea capture succeeds but auth/workspace is missing, keep the idea and
 
 ## Step 1: Hook Research
 
-Use `references/hook-research-playbook.md`.
+Use `references/hook-research-playbook.md` and
+`references/linkedin-preview-rendering.md`.
 
 If the host supports background agents, delegate the search/fetch/autopsy work
 to one bounded `research-worker` before hook candidate generation. The worker
@@ -319,9 +321,10 @@ The research worker must return a compact packet only:
 - full adapted hook blocks
 - market belief map: resonating ideas, implicit beliefs, audience wants, resentments, fears, and credible controversy angles
 - premise inputs: real scenes, observed tensions, reader value openings, and proof gaps
+- reach-normalized signal notes, including follower-band fit when available
 - exact phrase patterns and sentence shapes
 - body structures and exact body language moves
-- preview measurements
+- rendered mobile and desktop preview records
 - track-person and gold-standard recommendations
 - blocked states or confidence gaps
 
@@ -332,18 +335,20 @@ the exact extracted phrase shapes.
 Default flow:
 
 1. Convert the idea into 3-8 search keywords.
-2. Call `mcp__sellable__search_engagement_posts` with an explicit multi-month window. Default to `maxAgeDays: 120`, tightening to 30-60 days only when the topic is trend-sensitive.
-3. Shortlist high-engagement posts by topic fit, hook strength, creator repeat evidence, and weighted engagement quality.
-4. Because search results may only include previews, call `mcp__sellable__fetch_linkedin_posts` for shortlisted authors/profile URLs and match recent posts by URL/activity ID when full text is needed.
+2. Call `mcp__sellable__search_engagement_posts` with an explicit multi-month window. Default to `maxAgeDays: 120`, tightening to 30-60 days only when the topic is trend-sensitive. When the user gives a follower range, pass it as `targetFollowerMin` and `targetFollowerMax`; for example, "8k-20k followers" means `targetFollowerMin: 8000` and `targetFollowerMax: 20000`.
+3. Shortlist posts by topic fit, rendered hook strength, content pattern replicability, creator repeat evidence, weighted engagement quality, and reach-normalized signal quality. Do not sort by raw engagement alone, and do not let the numeric reach score choose the final hook by itself.
+4. Because search results may only include previews, call `mcp__sellable__fetch_linkedin_posts` for shortlisted authors/profile URLs and match recent posts by URL/activity ID when full text is needed. If a promising source is missing follower count and the user requested reach normalization, call `mcp__sellable__fetch_linkedin_profile` on a bounded shortlist before treating the source as a keeper.
 5. If full text cannot be matched, record `full_text_unavailable` and use only the preview. Do not invent missing body details.
-6. Weigh shares/reposts above comments, comments above reactions, and reactions as weak reach unless paired with stronger signals. If shares/reposts are unavailable, record `repost_data_unavailable`.
+6. Weigh shares/reposts above comments, comments above reactions, and reactions as weak reach unless paired with stronger signals. Normalize engagement against follower count when available: record `authorFollowerCount`, `targetFollowerBand`, `followerBandFit`, `engagementPer1kFollowers`, `weightedEngagementPer1kFollowers`, `reachPenaltyMultiplier`, `reachAdjustedScore`, and `baselineLift` when repeated creator posts make it possible. If follower count is unavailable, record `follower_count_unavailable`; if shares/reposts are unavailable, record `repost_data_unavailable`.
 7. Penalize lead-magnet or giveaway mechanics unless the user explicitly asks for a lead magnet post.
 8. Build a market belief map before hook generation: what the space is rewarding, what the audience implicitly believes, what they want permission to say, what they resent or fear, what they will argue with, and which controversial angle the user can credibly own. If the user's raw idea is internally coherent but not attached to a live market tension, do not draft from the internal idea alone; present stronger directions or rewrite the draft angle around the external tension.
 9. Extract premise inputs: real story/scene possibilities, observed tensions, useful reader takeaways, and proof gaps. A good hook cannot rescue a premise with no value.
 10. For story posts, extract the story mechanism that made the post work, not just the first line.
 11. Extract hook structures plus specific reusable words, phrases, sentence
    shapes, transitions, and body language patterns.
-12. Save the research with `mcp__sellable__save_hook_research`.
+12. Render each kept source hook and adapted hook block through the LinkedIn
+   preview rendering contract. Character counts alone are not enough.
+13. Save the research with `mcp__sellable__save_hook_research`.
 
 Record provenance:
 
@@ -352,18 +357,26 @@ Record provenance:
 - search window
 - source post URLs
 - authors/profile URLs
+- author follower counts and target follower-band fit when available
 - engagement totals and available likes/comments/shares breakdown
+- reach-normalized scoring fields and confidence notes
 - creator repeat evidence
 - lead-magnet or engagement-bait penalties
 - story mechanism when relevant
 - full-text match status
-- source hook preview measurements and whether they came from full text or a search preview
+- source hook rendered preview records and whether they came from full text,
+  authenticated LinkedIn screenshots, or a search preview
 - selected hook patterns
 - market belief map and selected controversy
 - premise cards and selected premise
 - exact phrase patterns and sentence shapes
 - body structures and body language patterns
 - why each pattern fits the user's idea and voice
+- `whyTheHookCarries`: why the selected hook works from the words, tension, and
+  content pattern independent of the source creator's reach
+- `whyTheReachEvidenceIsTrustworthy`: follower-band fit, reach-adjusted score,
+  baseline lift, share/comment quality, or why a large-account example is only
+  secondary pattern evidence
 
 ## Step 1.5: Research Learning Report
 
@@ -389,6 +402,9 @@ Research status:
 - keywords:
 - full-text coverage:
 - repost/share data:
+- target follower band:
+- reach-normalized winners:
+- big-account examples used only as secondary pattern evidence:
 
 Best source examples:
 1. author, URL, engagement, why kept, why not copied
@@ -409,7 +425,10 @@ Premise cards:
 Hook patterns learned:
 1. full adapted hook block
    - source mechanism:
-   - preview budget:
+   - rendered preview:
+     - mobile visible block:
+     - desktop visible block:
+     - verdict:
    - internal question:
    - why it fits / why it does not:
 
@@ -484,6 +503,15 @@ Each hook must include:
 - reader value implied
 - source hook pattern
 - why it fits this idea
+- `renderedPreview` using `references/linkedin-preview-rendering.md`
+- `mobileRenderedPreviewBlock`
+- `desktopRenderedPreviewBlock`
+- `mobileRenderedLines`
+- `desktopRenderedLines`
+- `firstScreenPromise`
+- `corePainProofOrCuriosityVisibleMobile`
+- `corePointVisibleMobile`
+- `pointAfterMobileClamp`
 - `charCount`
 - `charCountIncludingNewlines`
 - `firstLineChars`
@@ -504,22 +532,39 @@ Each hook must include:
 
 Do not copy source wording. Copy only the structure.
 
-Use this conservative mobile-first LinkedIn preview gate. LinkedIn does not
-publish exact "see more" cutoff rules, and rendering varies by device, app
-version, font, media, and line break. These are v1 safety budgets, not claims
-about an official LinkedIn limit:
-
-- `pass`: hook is <= 110 chars including newlines, every nonblank line is <= 45 chars, and the hook's core point lands before likely truncation.
-- `warn`: hook is 111-140 chars including newlines, any nonblank line is 46-55 chars, or blank lines create visual-line risk. Blank lines are allowed, but they count as physical lines.
-- `fail`: hook is > 140 chars including newlines, any nonblank line is > 55 chars, or the hook's point depends on text after likely truncation.
+Render every candidate before scoring it. The LinkedIn preview rendering
+contract is the gate; character counts are secondary diagnostics only. Use the
+deterministic CSS contract when no authenticated LinkedIn screenshot is
+available:
+
+- mobile text width: `308px`
+- desktop text width: `582px`
+- font size: `14px`
+- line height: `21px`
+- white space: `pre-wrap`
+- overflow wrap: `break-word`
+- review clamp: first 3 rendered text lines
+
+Use the rendered gates from `references/linkedin-preview-rendering.md`:
+
+- `pass`: the mobile rendered preview shows the pain, proof, or curiosity by
+  the end of the first 3 rendered lines, and the core point is understandable
+  without opening "see more".
+- `warn`: the mobile rendered preview creates useful curiosity but the core
+  point is slightly softened by wrapping, blank-line rhythm, or one missing
+  context word. A compact fallback is required.
+- `fail`: the hook's real point appears after the first 3 mobile rendered
+  lines, the first rendered line is generic setup, blank lines consume the
+  preview before the reader sees the point, or desktop fit is the only reason it
+  looks good.
 
 Desktop preview usually has more room. Still record `desktopPreviewFit`, but
 never let desktop fit compensate for a mobile `fail`.
 
-If a hook's point depends on text after the likely preview, rewrite it before
-selecting it. A selected hook may carry a `warn` only when the warning is about
-intentional blank-line rhythm or a slight line-length overage; include a compact
-fallback in the validation receipt.
+If a hook's point depends on text after the rendered mobile preview clamp,
+rewrite it before selecting it. A selected hook may carry a `warn` only when
+the warning is explicit and the validation receipt includes a compact fallback.
+A hook with no rendered mobile and desktop preview record cannot be selected.
 
 ## Step 3: Draft
 
@@ -553,6 +598,7 @@ Every saved draft needs a validation receipt with:
 - story/proof files consulted
 - gold standards consulted
 - LinkedIn preview audit
+- rendered mobile and desktop hook preview blocks
 - premise/value audit findings
 - simplifier/concrete-language audit findings
 - voice audit findings

package/skills/create-post/references/gold-standard-post-pack.md

@@ -119,6 +119,8 @@ Show compact candidate cards. Include:
 - why it might belong in the pack
 - hook mechanism
 - hook preview budget status and measurement basis
+- rendered mobile preview block and verdict
+- rendered desktop preview block and verdict
 - content/body mechanism
 - rhythm notes
 - sentence-structure notes
@@ -194,6 +196,15 @@ Tags:
 - longest nonblank line chars:
 - blank-line visual risk:
 - source text basis:
+- render basis:
+- css contract version:
+- mobile rendered preview block:
+- desktop rendered preview block:
+- mobile rendered lines:
+- desktop rendered lines:
+- core pain/proof/curiosity visible on mobile:
+- core point visible on mobile:
+- point after mobile clamp:
 - preview budget status:
 - mobile preview fit:
 - desktop preview fit: