@sellable/mcp 0.1.240 → 0.1.242

package/dist/tools/registry.d.ts

@@ -1219,9 +1219,21 @@ export declare const allTools: ({
             createdAt?: undefined;
             draftId?: undefined;
             hookResearchId?: undefined;
+            priorDraftId?: undefined;
+            iteration?: undefined;
             body?: undefined;
             validationReceipt?: undefined;
             status?: undefined;
+            updatedAt?: undefined;
+            publishUrl?: undefined;
+            activityId?: undefined;
+            publishedAt?: undefined;
+            finalText?: undefined;
+            updateDraftStatus?: undefined;
+            publishedPostId?: undefined;
+            year?: undefined;
+            metrics?: undefined;
+            note?: undefined;
         };
         required: string[];
         additionalProperties: boolean;
@@ -1255,6 +1267,15 @@ export declare const allTools: ({
             hookResearchId: {
                 type: string;
             };
+            priorDraftId: {
+                type: string;
+                description: string;
+            };
+            iteration: {
+                type: string;
+                description: string;
+                additionalProperties: boolean;
+            };
             title: {
                 type: string;
             };
@@ -1282,6 +1303,189 @@ export declare const allTools: ({
             selectedPatterns?: undefined;
             previewBudget?: undefined;
             notes?: undefined;
+            updatedAt?: undefined;
+            publishUrl?: undefined;
+            activityId?: undefined;
+            publishedAt?: undefined;
+            finalText?: undefined;
+            updateDraftStatus?: undefined;
+            publishedPostId?: undefined;
+            year?: undefined;
+            metrics?: undefined;
+            note?: undefined;
+        };
+        required: string[];
+        additionalProperties: boolean;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            draftId: {
+                type: string;
+            };
+            hookResearchId: {
+                type: string;
+            };
+            priorDraftId: {
+                type: string;
+                description?: undefined;
+            };
+            iteration: {
+                type: string;
+                description: string;
+                additionalProperties: boolean;
+            };
+            title: {
+                type: string;
+            };
+            body: {
+                type: string;
+            };
+            validationReceipt: {
+                description: string;
+            };
+            status: {
+                type: string;
+            };
+            updatedAt: {
+                type: string;
+            };
+            rawSource?: undefined;
+            distilledBrief?: undefined;
+            ideaId?: undefined;
+            sourceType?: undefined;
+            sourceUrl?: undefined;
+            capturedAt?: undefined;
+            researchId?: undefined;
+            topic?: undefined;
+            keywords?: undefined;
+            sourcePosts?: undefined;
+            selectedPatterns?: undefined;
+            previewBudget?: undefined;
+            notes?: undefined;
+            createdAt?: undefined;
+            publishUrl?: undefined;
+            activityId?: undefined;
+            publishedAt?: undefined;
+            finalText?: undefined;
+            updateDraftStatus?: undefined;
+            publishedPostId?: undefined;
+            year?: undefined;
+            metrics?: undefined;
+            note?: undefined;
+        };
+        required: string[];
+        additionalProperties: boolean;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            draftId: {
+                type: string;
+            };
+            publishUrl: {
+                type: string;
+            };
+            activityId: {
+                type: string;
+            };
+            publishedAt: {
+                type: string;
+            };
+            finalText: {
+                type: string;
+            };
+            title: {
+                type: string;
+            };
+            updateDraftStatus: {
+                type: string;
+                description: string;
+            };
+            rawSource?: undefined;
+            distilledBrief?: undefined;
+            ideaId?: undefined;
+            sourceType?: undefined;
+            sourceUrl?: undefined;
+            capturedAt?: undefined;
+            researchId?: undefined;
+            topic?: undefined;
+            keywords?: undefined;
+            sourcePosts?: undefined;
+            selectedPatterns?: undefined;
+            previewBudget?: undefined;
+            notes?: undefined;
+            createdAt?: undefined;
+            hookResearchId?: undefined;
+            priorDraftId?: undefined;
+            iteration?: undefined;
+            body?: undefined;
+            validationReceipt?: undefined;
+            status?: undefined;
+            updatedAt?: undefined;
+            publishedPostId?: undefined;
+            year?: undefined;
+            metrics?: undefined;
+            note?: undefined;
+        };
+        required: string[];
+        additionalProperties: boolean;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            publishedPostId: {
+                type: string;
+            };
+            year: {
+                type: string;
+            };
+            capturedAt: {
+                type: string;
+            };
+            metrics: {
+                type: string;
+                additionalProperties: boolean;
+            };
+            note: {
+                type: string;
+            };
+            rawSource?: undefined;
+            title?: undefined;
+            distilledBrief?: undefined;
+            ideaId?: undefined;
+            sourceType?: undefined;
+            sourceUrl?: undefined;
+            researchId?: undefined;
+            topic?: undefined;
+            keywords?: undefined;
+            sourcePosts?: undefined;
+            selectedPatterns?: undefined;
+            previewBudget?: undefined;
+            notes?: undefined;
+            createdAt?: undefined;
+            draftId?: undefined;
+            hookResearchId?: undefined;
+            priorDraftId?: undefined;
+            iteration?: undefined;
+            body?: undefined;
+            validationReceipt?: undefined;
+            status?: undefined;
+            updatedAt?: undefined;
+            publishUrl?: undefined;
+            activityId?: undefined;
+            publishedAt?: undefined;
+            finalText?: undefined;
+            updateDraftStatus?: undefined;
         };
         required: string[];
         additionalProperties: boolean;

package/package.json

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

package/skills/create-post/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: create-post
-description: Capture rough LinkedIn post ideas, preserve the raw source, research currently working hooks, and save validated drafts in the user's voice.
+description: Capture rough LinkedIn post ideas, preserve the raw source, develop a valuable premise, research currently working hooks, and save validated drafts in the user's voice.
 visibility: internal
 ---
 
@@ -9,7 +9,7 @@ visibility: internal
 <role>
 You are the Sellable LinkedIn post writer for a specific user.
 
-Your job is not to invent a "viral" post from thin air. Your job is to preserve the user's raw idea, load their real voice/proof/stories, research what hooks have been working over the past few months, and save a validated draft that sounds like them.
+Your job is not to invent a "viral" post from thin air. Your job is to preserve the user's raw idea, load their real voice/proof/stories, research what ideas and hooks have been resonating over the past few months, extract what the audience implicitly believes/wants/resents/fears, develop a real premise with story/tension/reader value, choose a credible controversial angle to test, and save a validated draft that sounds like them.
 
 Hard fail patterns:
 
@@ -18,17 +18,19 @@ Hard fail patterns:
 - outbound, campaign, cold email, or lead-generation workflow behavior
 - comment drafting behavior
 - drafts that skip raw idea capture
+- drafts that skip premise development
 - hooks copied verbatim from another creator
 - using `~/.sellable/configs/content/linkedin-posts-drafts.md` as the normal save target
   </role>
 
 <scope>
-V1 is posts-only and hooks-first.
+V1 is posts-only and premise-first, hook-second.
 
 Do:
 
 - capture rough ideas, voice memos, freestyle notes, and ad hoc prompts
 - research currently working LinkedIn hooks
+- develop premise cards with real story/observed tension and reader value
 - generate hook candidates
 - draft a post body that stays true to the source idea
 - run validation before calling a draft ready
@@ -49,8 +51,9 @@ Before drafting, load all required assets with `mcp__sellable__get_subskill_asse
 
 1. `subskillName: "create-post", assetPath: "references/post-file-contract.md"`
 2. `subskillName: "create-post", assetPath: "references/hook-research-playbook.md"`
-3. `subskillName: "create-post", assetPath: "references/post-validation.md"`
-4. `subskillName: "create-post", assetPath: "references/gold-standard-post-pack.md"`
+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"`
 
 If any required asset is missing, unreadable, truncated without continuation, or internally inconsistent, return:
 
@@ -75,8 +78,12 @@ Use these MCP tools when available:
 - `mcp__sellable__list_post_ideas`
 - `mcp__sellable__save_hook_research`
 - `mcp__sellable__save_post_draft`
+- `mcp__sellable__update_post_draft`
+- `mcp__sellable__list_post_draft_iterations`
 - `mcp__sellable__get_post_draft`
 - `mcp__sellable__mark_post_published`
+- `mcp__sellable__get_published_post`
+- `mcp__sellable__update_published_post_metrics`
 - `mcp__sellable__list_published_posts`
 - `mcp__sellable__search_engagement_posts`
 - `mcp__sellable__fetch_linkedin_posts`
@@ -159,9 +166,10 @@ Use when the user gives an existing idea ID.
 1. Call `mcp__sellable__get_post_idea({ ideaId })`.
 2. Treat the idea's raw source as immutable source material.
 3. Run hook research.
-4. Save hook research.
-5. Draft and validate.
-6. Save the draft.
+4. Develop and select a premise card.
+5. Save hook research.
+6. Draft and validate.
+7. Save the draft.
 
 ## Capture Mode
 
@@ -171,9 +179,10 @@ Use when the user gives a new rough idea, voice memo transcript, freestyle note,
 2. Preserve the raw source exactly.
 3. Distill only what the user actually said.
 4. Run hook research.
-5. Save hook research.
-6. Draft and validate.
-7. Save the draft.
+5. Develop and select a premise card.
+6. Save hook research.
+7. Draft and validate.
+8. Save the draft.
 
 ## Ad Hoc Mode
 
@@ -267,6 +276,8 @@ The research worker must return a compact packet only:
 
 - source examples kept and rejected
 - 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
 - exact phrase patterns and sentence shapes
 - body structures and exact body language moves
 - preview measurements
@@ -286,10 +297,12 @@ Default flow:
 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`.
 7. Penalize lead-magnet or giveaway mechanics unless the user explicitly asks for a lead magnet post.
-8. For story posts, extract the story mechanism that made the post work, not just the first line.
-9. Extract hook structures plus specific reusable words, phrases, sentence
+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.
-10. Save the research with `mcp__sellable__save_hook_research`.
+12. Save the research with `mcp__sellable__save_hook_research`.
 
 Record provenance:
 
@@ -305,6 +318,8 @@ Record provenance:
 - full-text match status
 - source hook preview measurements and whether they came from full text 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
@@ -337,6 +352,19 @@ Research status:
 Best source examples:
 1. author, URL, engagement, why kept, why not copied
 
+Market belief map:
+- resonating ideas:
+- implicit beliefs:
+- audience wants:
+- audience resentments:
+- audience fears:
+- controversial angles to test:
+- avoid because:
+- selected controversy:
+
+Premise cards:
+1. premise + real story/scene + tension + reader value + proof gap + score
+
 Hook patterns learned:
 1. full adapted hook block
    - source mechanism:
@@ -368,20 +396,51 @@ Save recommendations:
 - gold-standard candidates:
 
 Recommended draft directions:
-1. hook block + body structure
-2. hook block + body structure
-3. hook block + body structure
+1. premise card + hook block + body structure
+2. premise card + hook block + body structure
+3. premise card + hook block + body structure
 ```
 
 Keep this report concise enough to read, but concrete enough that another agent
 could draft from it without redoing research.
 
+## Step 1.75: Premise Development
+
+Use `references/premise-development.md`.
+
+Generate 3-5 `Premise Card` candidates from the raw idea, market research, core
+memory, story/proof files, and current-session user feedback. Each card must
+include a real story/scene or observed pattern, target reader, common belief,
+contrarian truth, tension, reader value, proof available, proof missing, and a
+score.
+
+Select the strongest premise before hook generation. The selected premise must
+pass:
+
+- `specific_scene_or_pattern`
+- `clear_reader`
+- `visible_tension`
+- `reader_value`
+- `credible_speaker`
+- `proof_safety`
+- `market_heat`
+
+If the idea has market heat but no real scene, ask for the missing scene unless
+the user explicitly requested an immediate draft. For immediate draft mode, use
+only source-backed observed patterns and save the draft as `needs_revision`
+unless the premise still has concrete reader value.
+
 ## Step 2: Hook Candidates
 
-Generate at least 12 hook candidates unless the user requested a smaller set.
+Generate at least 12 hook candidates from the selected premise unless the user
+requested a smaller set. Do not generate hooks directly from the raw idea before
+the premise is selected.
 
 Each hook must include:
 
+- selected premise
+- premise tension opened
+- reader value implied
 - source hook pattern
 - why it fits this idea
 - `charCount`
@@ -426,6 +485,7 @@ fallback in the validation receipt.
 Draft from:
 
 - exact raw idea
+- selected premise card
 - selected hook
 - hook research artifact
 - user's core memory
@@ -443,12 +503,16 @@ Every saved draft needs a validation receipt with:
 
 - source idea ID
 - hook research ID
+- iteration metadata: version, priorDraftId, changeIntent, what changed,
+  what improved, what got worse, score, and verdict
+- selected premise card
 - candidate hooks considered
 - selected hook and why
 - proof claims used and source
 - story/proof files consulted
 - gold standards consulted
 - LinkedIn preview audit
+- premise/value audit findings
 - simplifier/concrete-language audit findings
 - voice audit findings
 - anti-AI audit findings
@@ -463,6 +527,32 @@ If validation fails, do not save the draft as `ready`. Save as `needs_revision`
 
 Call `mcp__sellable__save_post_draft`.
 
+Use versioned draft IDs for multiple attempts on the same idea:
+
+```text
+draft_YYYYMMDD_slug_v1
+draft_YYYYMMDD_slug_v2
+draft_YYYYMMDD_slug_v3
+```
+
+Keep the `ideaId` stable across versions. Treat `v1` as the baseline unless the
+user explicitly picks another draft as the baseline. For `v2+`, pass
+`priorDraftId` and include an iteration receipt comparing the new draft against
+the prior draft. If the user asks to patch the same version's receipt, status,
+or copy without creating a new version, call `mcp__sellable__update_post_draft`.
+
+When deciding whether a draft improved, use:
+
+- hook
+- proof
+- voice
+- specificity
+- skimmability
+- publish confidence
+
+Do not mark a draft as improved only because it is newer. Preserve what got
+worse.
+
 Drafts live under:
 
 ```text
@@ -487,6 +577,12 @@ Published post records live under:
 ~/.sellable/content/linkedin/published/
 ```
 
+When the user publishes a post or provides a LinkedIn URL, call
+`mcp__sellable__mark_post_published`. This records the published post separately
+and marks the source draft as `published` by default. When later performance
+data is available, call `mcp__sellable__update_published_post_metrics` to append
+metric snapshots for learning.
+
 </pipeline>
 
 <legacy>
@@ -504,8 +600,15 @@ idea_id: <id or none>
 hook_research_id: <id or none>
 draft_id: <id or none>
 draft_path: <path or none>
+iteration:
+  version: <v1/v2/etc>
+  prior_draft_id: <id or none>
+  verdict: <baseline | keep | revise | reject | publish_candidate>
+  score: <compact score object>
+selected_premise: <premise or none>
 selected_hook: <hook>
 validation_summary:
+  premise_value: pass | needs_user_input | needs_revision
   proof: pass | needs_user_input | blocked
   voice: pass | needs_revision
   anti_ai: pass | needs_revision

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

@@ -1,6 +1,6 @@
 # Hook Research Playbook
 
-Hook research must use current Sellable engagement data before drafting unless the user explicitly asks for `unsaved_preview`.
+Hook research must use current Sellable engagement data before drafting unless the user explicitly asks for `unsaved_preview`. The goal is not only to find hooks. The goal is to find what the market is currently rewarding, what the audience implicitly believes/wants/resents/fears, which controversial angle the user can credibly test, and what premise would deliver real reader value.
 
 ## Search Inputs
 
@@ -29,6 +29,8 @@ Worker owns:
 - full-text matching by URL/activity ID
 - duplicate removal
 - 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
 - exact phrase-pattern extraction
 - body-structure extraction
@@ -49,6 +51,9 @@ Worker output must be a compressed research packet, not a data dump:
 Research packet:
 - sources kept: max 8
 - sources rejected: max 8
+- market belief map: max 8 bullets
+- controversy candidates: max 8
+- premise inputs: max 8
 - full adapted hook blocks: max 12
 - exact phrase patterns: max 20
 - body patterns: max 8
@@ -113,6 +118,67 @@ Penalize lead-magnet and engagement-bait mechanics unless the user explicitly as
 - "like and comment"
 - broad giveaway framing that makes engagement inflate without proving the hook/body worked
 
+## Market Belief Map
+
+Before selecting a hook or writing a draft, synthesize a market belief map from
+the kept and rejected posts. This is the step that prevents an internally
+coherent post from becoming externally boring.
+
+Record:
+
+- resonating ideas: what topics or claims are repeatedly earning real
+  engagement in the last 30-120 days
+- implicit beliefs: what the audience seems to already believe but may not say
+  directly
+- audience wants: what they want to feel, learn, try, buy, avoid, or be early to
+- audience resentments: what they are tired of, embarrassed by, or angry about
+- audience fears: what risk would make them hesitate
+- argument bait: what they will plausibly disagree with in comments
+- credible controversy: what the user can argue without borrowing someone else's
+  proof or pretending to have data they do not have
+- avoid list: ideas that are inflated by comment bait, stale category claims,
+  celebrity reach, giveaway mechanics, or poor voice fit
+
+The selected direction must include:
+
+```text
+Selected controversy:
+<one sentence>
+
+Why this audience would engage:
+<specific belief/want/resentment/fear>
+
+Why this user can credibly say it:
+<raw idea, memory, story, proof, or product mechanism>
+
+What not to claim:
+<unsupported metric, borrowed proof, or hype phrase to avoid>
+```
+
+If the raw idea is true but the market belief map does not show a live tension,
+do not draft from the raw idea as-is. Present stronger directions or reframe the
+idea around the closest supported external tension.
+
+## Premise Inputs
+
+After the market belief map, extract the ingredients needed for premise
+development. Do this before hook generation.
+
+Record:
+
+- real story or scene candidates from the raw idea, memory, transcript, or
+  current-session context
+- observed pattern candidates when no first-person story is available
+- visible tension: the uncomfortable gap, cost, contradiction, or tradeoff
+- common belief: what the audience probably believes right now
+- contrarian truth: what the user can credibly argue instead
+- reader value: what the reader learns, sees differently, or can do
+- proof available: what can be safely used
+- proof missing: what cannot be claimed without user confirmation
+
+If this section is weak, say so. Do not let the hook lab proceed as if a clever
+opening can create value that the premise does not have.
+
 ## Full Text Reality
 
 Search results may only include previews.
@@ -171,7 +237,8 @@ appears cut off or body context is unavailable.
 
 Extract structure and reusable language patterns, not copied prose. The goal is
 to learn the exact kinds of words, phrase shapes, sentence rhythms, and body
-moves that are working, then adapt them into the user's voice.
+moves that are working, then adapt them into the selected premise in the user's
+voice. Hooks must come from a premise card, not from the raw idea alone.
 
 For each shortlisted source post, record:
 

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

@@ -31,6 +31,7 @@ Customer computer owns:
       research_YYYYMMDD_slug.md
   drafts/
     draft_YYYYMMDD_slug_v1.md
+    draft_YYYYMMDD_slug_v2.md
   published/
     YYYY/
       post_linkedinActivityId.md
@@ -69,10 +70,26 @@ Draft files must preserve:
 
 - source idea ID
 - hook research ID
+- versioned draft ID, normally ending in `_v1`, `_v2`, `_v3`, etc.
+- iteration metadata when there is a prior or baseline draft:
+  - `version`
+  - `priorDraftId`
+  - `changeIntent`
+  - `whatChanged`
+  - `whatImproved`
+  - `whatGotWorse`
+  - score fields for hook, proof, voice, specificity, skimmability, and publish confidence
+  - `verdict`: `baseline`, `keep`, `revise`, `reject`, `publish_candidate`, or a similarly explicit state
 - draft body
 - validation receipt, including LinkedIn preview pass/warn/fail status and
   compact fallback when the selected hook carries a warning
-- status: `draft`, `ready`, or `needs_revision`
+- status: `draft`, `ready`, `needs_revision`, `published`, or `archived`
+
+Multiple drafts for the same idea are expected. Keep the `ideaId` stable and
+create a new versioned `draftId` for each materially different attempt. Do not
+overwrite a prior version just to compare alternatives. Use
+`update_post_draft` only for same-version receipt fixes, status changes, or
+copy edits that should remain part of that version.
 
 Published files must preserve:
 
@@ -80,7 +97,12 @@ Published files must preserve:
 - publish URL
 - LinkedIn activity ID when available
 - published date
-- optional future metrics placeholders
+- future metrics placeholders and appended metric snapshots when available
+
+When a draft is published, `mark_post_published` records the published post
+separately and marks the source draft as `published` by default. Use
+`update_published_post_metrics` to append later performance snapshots instead
+of editing the draft.
 
 ## Safety