@sellable/mcp 0.1.254 → 0.1.256

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.254",
+  "version": "0.1.256",
   "type": "module",
   "description": "Sellable MCP server for Claude Code and Codex campaign workflows",
   "main": "dist/index.js",

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
@@ -321,7 +323,7 @@ The research worker must return a compact packet only:
 - premise inputs: real scenes, observed tensions, reader value openings, and proof gaps
 - 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
 
@@ -343,7 +345,9 @@ Default flow:
 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:
 
@@ -357,7 +361,8 @@ Record provenance:
 - 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
@@ -409,7 +414,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 +492,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 +521,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 +587,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:

package/skills/create-post/references/hook-research-playbook.md

@@ -31,7 +31,7 @@ Worker owns:
 - lead-magnet, giveaway, engagement-bait, and off-voice filtering
 - market belief mapping across kept and rejected examples
 - premise input extraction: real scenes, observed tensions, reader value, proof gaps
-- hook opening measurement
+- rendered hook opening measurement
 - exact phrase-pattern extraction
 - body-structure extraction
 - rejected-example notes
@@ -58,7 +58,7 @@ Research packet:
 - exact phrase patterns: max 20
 - body patterns: max 8
 - source URLs and author profile URLs
-- preview measurements
+- rendered preview records
 - confidence gaps
 - save recommendations
 ```
@@ -198,24 +198,48 @@ Measure the visible opening for every shortlisted source post before extracting
 the hook pattern. This makes the study useful for LinkedIn, not just generally
 "good writing."
 
-LinkedIn does not publish exact "see more" cutoff rules. Treat these as
-conservative v1 planning budgets:
+Use `references/linkedin-preview-rendering.md`. LinkedIn does not publish exact
+"see more" cutoff rules. Character counts are diagnostics only. A source post
+or generated hook is not properly studied until it has a rendered mobile and
+desktop preview record.
 
-- `pass`: opening hook is <= 110 chars including newlines, every nonblank line
-  is <= 45 chars, and the hook's core point lands before likely truncation.
-- `warn`: opening 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`: opening hook is > 140 chars including newlines, any nonblank line is
-  > 55 chars, or the hook's core point depends on text after likely truncation.
+Default deterministic renderer for unpublished drafts and research comparison:
 
-Desktop preview has more room, so record it separately, but never let desktop
-fit compensate for a mobile `fail`.
+```text
+cssContractVersion: linkedin-preview-rendering/v1
+font size: 14px
+line height: 21px
+white space: pre-wrap
+overflow wrap: break-word
+mobile text width: 308px
+desktop text width: 582px
+review clamp: first 3 rendered text lines
+```
+
+Authenticated LinkedIn feed/composer screenshots are stronger evidence when
+available. If a screenshot is used, still record the wrapped lines and verdicts
+below so another agent can compare hooks without re-opening LinkedIn.
+
+Desktop preview has more room, but never let desktop fit compensate for a
+mobile `fail`.
 
 For each source, record:
 
 - `sourceTextBasis`: `full_text`, `search_preview`, or `manual_user_source`
 - `openingTextUsed`
+- `renderedPreview`
+- `cssContractVersion`
+- `mobileRenderedPreviewBlock`
+- `desktopRenderedPreviewBlock`
+- `mobileRenderedLines`
+- `desktopRenderedLines`
+- `mobileRenderedLineCount`
+- `desktopRenderedLineCount`
+- `corePainProofOrCuriosityVisibleMobile`
+- `corePainProofOrCuriosityVisibleDesktop`
+- `corePointVisibleMobile`
+- `corePointVisibleDesktop`
+- `pointAfterMobileClamp`
 - `charCountIncludingNewlines`
 - `physicalLineCount`
 - `contentLineCount`
@@ -228,11 +252,25 @@ For each source, record:
 - `desktopPreviewBudget`: `pass`, `warn`, or `fail`
 - `blankLineVisualRisk`
 - `corePointBeforeLikelyTruncation`
+- `renderedPreviewVerdict`: `pass`, `warn`, or `fail`
 
 If only a search preview is available, do not pretend the opening is complete.
 Record `sourceTextBasis: search_preview` and lower confidence when the hook
 appears cut off or body context is unavailable.
 
+Pass/warn/fail is based on rendered output:
+
+- `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.
+
 ## Hook Extraction
 
 Extract structure and reusable language patterns, not copied prose. The goal is
@@ -248,7 +286,7 @@ For each shortlisted source post, record:
 - engagement totals and available likes/comments/shares breakdown
 - creator repeat evidence
 - visible hook text or preview
-- opening preview measurement fields from the section above
+- rendered preview fields from the section above
 - hook mechanism
 - exact hook language patterns: reusable words, phrase shapes, contrast forms,
   sentence shapes, and transition moves
@@ -262,6 +300,11 @@ For each shortlisted source post, record:
 - track person recommendation: `yes`, `no`, or `ask_user`
 - tracking reason when recommended
 
+Do not call a source hook a keeper because the full text is strong if the
+rendered mobile opening is weak. Study what a LinkedIn reader sees before
+"see more"; the body structure can still be useful, but the hook should not be
+copied into the hook pattern set.
+
 ## Specific Language Extraction
 
 For each keeper, extract the source's specific language mechanics in this

package/skills/create-post/references/linkedin-preview-rendering.md

@@ -0,0 +1,163 @@
+# LinkedIn Preview Rendering
+
+This asset defines the required rendered-preview contract for create-post hook
+research, hook candidate generation, gold-standard decomposition, and draft
+validation.
+
+Character budgets are only diagnostics. They are not the preview gate. A hook is
+not studied, selected, or ready until it has been rendered through this contract
+or through a stricter authenticated LinkedIn screenshot.
+
+## Rendering Basis
+
+LinkedIn does not publish exact feed truncation rules, and rendering can vary by
+surface, app version, device, media attachment, and account state. Use this
+deterministic renderer as the MCP review gate for unpublished drafts.
+
+When an authenticated LinkedIn feed/composer/browser screenshot is available,
+that screenshot is the strongest evidence. Still record the fields below so
+future agents can compare candidates without redoing the visual inspection.
+
+Observed public LinkedIn post text style for feed-style post pages:
+
+```text
+selector basis: p.attributed-text-segment-list__content
+font family: -apple-system, system-ui, "Segoe UI", Roboto, "Helvetica Neue",
+  "Fira Sans", Ubuntu, "Oxygen Sans", Cantarell, "Droid Sans",
+  "Lucida Grande", Helvetica, Arial, sans-serif
+font size: 14px
+line height: 21px
+font weight: 400
+letter spacing: normal
+white space: pre-wrap
+overflow wrap: break-word
+text color: rgba(0, 0, 0, 0.9)
+mobile text width: 308px
+desktop text width: 582px
+review clamp: first 3 rendered text lines
+```
+
+The `review clamp` is not an official LinkedIn rule. It is the conservative
+apples-to-apples region create-post must use when comparing hooks. Do not let a
+desktop pass rescue a mobile fail.
+
+## Required Rendering Record
+
+Every shortlisted source hook, adapted hook block, generated hook candidate, and
+selected hook must include a `renderedPreview` record:
+
+```text
+renderedPreview:
+  basis: linkedin_css_contract | authenticated_linkedin_screenshot | manual_user_source
+  cssContractVersion: linkedin-preview-rendering/v1
+  mobile:
+    textWidthPx: 308
+    fontSizePx: 14
+    lineHeightPx: 21
+    visibleTextBlock: <literal first rendered review-clamp block>
+    renderedLines:
+      - <line 1 exactly as wrapped>
+      - <line 2 exactly as wrapped>
+      - <line 3 exactly as wrapped>
+    lineCountBeforeClamp: <number>
+    blankLinesBeforeClamp: <number>
+    corePainProofOrCuriosityVisible: true | false
+    corePointVisible: true | false
+    seeMoreRisk: pass | warn | fail
+    screenshotPath: <optional local path>
+  desktop:
+    textWidthPx: 582
+    fontSizePx: 14
+    lineHeightPx: 21
+    visibleTextBlock: <literal first rendered review-clamp block>
+    renderedLines:
+      - <line 1 exactly as wrapped>
+      - <line 2 exactly as wrapped>
+      - <line 3 exactly as wrapped>
+    lineCountBeforeClamp: <number>
+    blankLinesBeforeClamp: <number>
+    corePainProofOrCuriosityVisible: true | false
+    corePointVisible: true | false
+    seeMoreRisk: pass | warn | fail
+    screenshotPath: <optional local path>
+  diagnostics:
+    charCount: <number>
+    charCountIncludingNewlines: <number>
+    firstLineChars: <number>
+    firstTwoPhysicalLinesChars: <number>
+    longestNonblankLineChars: <number>
+    blankLineVisualRisk: none | low | medium | high
+    pointAfterMobileClamp: true | false
+    rewriteIfTruncated: <short fallback>
+```
+
+If a host cannot produce screenshots, it must still produce the literal wrapped
+line blocks using the CSS contract. If it cannot produce either screenshots or
+literal line wraps, return `blocked` or `needs_revision`; do not claim the hook
+passed preview validation from character counts alone.
+
+## Study Rules
+
+For source-post research:
+
+- Render the exact visible opening from full text when full text is available.
+- If only a search preview is available, render only the preview text and set
+  `basis: manual_user_source` or record `sourceTextBasis: search_preview`.
+- Lower confidence when the search preview is cut off or the body is
+  unavailable.
+- Extract hook lessons from the rendered first-screen experience, not from the
+  full post in isolation.
+
+For generated hooks:
+
+- Generate the hook from the selected premise first.
+- Render the hook for mobile and desktop before scoring it.
+- Score the rendered first-screen promise before scoring cleverness.
+- Rewrite any candidate whose real point appears after the mobile clamp.
+
+## Pass, Warn, Fail
+
+Use these rendered gates:
+
+- `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.
+
+A draft cannot be `ready` when the selected hook has:
+
+- no `renderedPreview`
+- `mobile.seeMoreRisk: fail`
+- `mobile.corePainProofOrCuriosityVisible: false`
+- `mobile.corePointVisible: false`
+- `pointAfterMobileClamp: true`
+
+## Report Format
+
+Research reports must show rendered preview blocks for the best examples and
+recommended draft directions:
+
+```text
+Rendered preview:
+mobile:
+<line 1>
+<line 2>
+<line 3>
+
+desktop:
+<line 1>
+<line 2>
+<line 3>
+
+verdict: pass | warn | fail
+why: <what is visible before the fold>
+```
+
+Do not say "it fits on mobile" without showing what the mobile reader actually
+sees.

package/skills/create-post/references/post-file-contract.md

@@ -63,6 +63,10 @@ Hook research files must preserve:
 - source hook preview measurements, including text basis, char count including
   newlines, physical/content line counts, longest nonblank line, blank-line
   visual risk, and mobile/desktop preview budget status
+- rendered preview records for every kept source hook and adapted hook block,
+  including literal mobile/desktop preview blocks, rendered line wraps, render
+  basis, CSS contract version, text widths, first-screen promise visibility,
+  core point visibility, and whether the point lands after the mobile clamp
 - extracted hook patterns
 - selected hook basis
 
@@ -83,6 +87,9 @@ Draft files must preserve:
 - draft body
 - validation receipt, including LinkedIn preview pass/warn/fail status and
   compact fallback when the selected hook carries a warning
+- rendered mobile and desktop preview blocks for the selected hook; drafts
+  cannot be ready when this rendered-preview audit is missing or fails mobile
+  visibility
 - status: `draft`, `ready`, `needs_revision`, `published`, or `archived`
 
 Multiple drafts for the same idea are expected. Keep the `ideaId` stable and