@sellable/mcp 0.1.239 → 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.239",
+  "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,13 +78,18 @@ 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`
 - `mcp__sellable__fetch_linkedin_profile`
 - `mcp__sellable__record_engage_proven_search`
+- `mcp__sellable__upsert_engage_tracked_person`
 
 Do not call outbound/campaign tools from this skill. Do not call message-generation prompts or tools. This skill reuses the quality architecture of the message pipeline: required assets, candidate set, finalizer pass, simplifier/concrete-language audit, anti-AI audit, proof/voice validation, and blocked/retry-needed states.
 </tools>
@@ -131,6 +139,8 @@ Durable write-back targets:
 - `core/transcripts/INDEX.md` for source interview or voice-memo references
 - `core/references/linkedin-posts/INDEX.md` and adjacent files for approved
   gold-standard post references
+- `discovery/influencers.md` for approved creators/persons the user wants the
+  system to keep learning from
 
 Write-backs must use stable source keys such as
 `create-post:{date}:{ideaId}:{slug}` or
@@ -139,6 +149,13 @@ paths before adding references, create no duplicate reference rows, and keep
 manual sections preserved. If the user says to mark private, store only the
 minimum private-safe metadata and do not promote it into public proof,
 references, or examples.
+
+When the user says a creator/person is worth following, learning from, or using
+again, persist them with `mcp__sellable__upsert_engage_tracked_person` before
+continuing. Use the canonical LinkedIn profile URL, a concise reason that names
+the content lane, and no senderId unless the user explicitly scopes the person
+to one sender. If the person is already tracked, update the reason instead of
+creating a duplicate.
 </memory_contract>
 
 <modes>
@@ -149,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
 
@@ -161,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
 
@@ -173,6 +192,29 @@ Normal ad hoc mode still creates an ID'd idea artifact first with `mcp__sellable
 
 If the user explicitly says not to save anything, label the output `unsaved_preview`, do not call it draft-ready, and do not mark it as validated for publishing.
 
+## Research Checkpoint Mode
+
+Use when the user asks to research hooks, research bodies, "show me what it
+learned", "run the research phase", "what is working in the space", or anything
+similar.
+
+1. Capture or load the idea/topic if one is provided.
+2. Run the hook/body research playbook.
+3. Save the research with `mcp__sellable__save_hook_research`.
+4. Present a `Research Learning Report` to the user.
+5. Do not draft until the user approves a direction or explicitly says to run
+   the draft phase.
+
+The report must include specific words, phrase shapes, sentence patterns, and
+body moves from the research. Do not only report abstract labels like
+"contrarian hook" or "tool-stack enemy."
+
+When the host supports background agents or Task workers, run the heavy research
+in a dedicated research worker so the main orchestrator stays clean. The
+orchestrator should keep only the compressed research packet, final selected
+examples, and user-facing learning report in context. Do not paste the entire
+raw source-post corpus into the orchestrator conversation.
+
 ## Gold Standard Pack Mode
 
 Use when the user asks to import their best posts, research best posts in the space, build a gold-standard pack, or add inspiration examples.
@@ -193,8 +235,11 @@ Space benchmark research:
 1. Use `mcp__sellable__search_engagement_posts` and the hook research playbook.
 2. Shortlist high-performing posts from the user's space using the weighted signal rules.
 3. Penalize lead magnets, giveaways, engagement bait, celebrity-only reach, and poor voice fit.
-4. Show the user the candidates and ask: "These look good. Should we use any as gold standards?"
-5. Add only the user-approved selections.
+4. When a creator/person appears repeatedly strong, include a `track_person`
+   recommendation in the candidate card.
+5. Show the user the candidates and ask: "These look good. Should we use any as gold standards or track any of these people?"
+6. Add only the user-approved post selections.
+7. For each approved tracked person, call `mcp__sellable__upsert_engage_tracked_person`.
 
 The approved pack is capped at 20 gold standards. If adding new approved examples would exceed 20, ask which existing item to replace or skip the overflow. Candidate lists can be longer, but approved saved standards cannot exceed 20.
 </modes>
@@ -220,6 +265,29 @@ If local idea capture succeeds but auth/workspace is missing, keep the idea and
 
 Use `references/hook-research-playbook.md`.
 
+If the host supports background agents, delegate the search/fetch/autopsy work
+to one bounded `research-worker` before hook candidate generation. The worker
+owns broad search, profile fetches, full-text matching, source filtering,
+language extraction, and body-structure extraction. The orchestrator owns the
+final save call, user-visible `Research Learning Report`, direction selection,
+and drafting gate.
+
+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
+- track-person and gold-standard recommendations
+- blocked states or confidence gaps
+
+The research worker must not return all raw post bodies unless a specific full
+text is required as a gold-standard candidate. Prefer summaries plus URLs and
+the exact extracted phrase shapes.
+
 Default flow:
 
 1. Convert the idea into 3-8 search keywords.
@@ -229,9 +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, not wording.
-10. Save the research with `mcp__sellable__save_hook_research`.
+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`.
 
 Record provenance:
 
@@ -247,14 +318,129 @@ 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
 
+## Step 1.5: Research Learning Report
+
+After saving research and before drafting, show the user what the system
+learned when either:
+
+- the user asked for research/checkpoint mode
+- the research materially changes the likely hook/body direction
+- the researched examples include new people worth tracking or examples worth
+  adding as gold standards
+
+Default ad hoc drafting may proceed after this report only when the user clearly
+asked for an immediate draft. In research checkpoint mode, stop here and ask
+which direction to use.
+
+The `Research Learning Report` must include:
+
+```text
+Research status:
+- idea/topic:
+- research artifact:
+- search window:
+- keywords:
+- full-text coverage:
+- repost/share data:
+
+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:
+   - preview budget:
+   - internal question:
+   - why it fits / why it does not:
+
+Specific words and phrase shapes:
+1. "phrase or phrase shape"
+   - role:
+   - source:
+   - reusable forms:
+   - adapted Sellable form:
+   - do not copy:
+
+Body structures learned:
+1. structure name
+   - source:
+   - sequence:
+   - exact language moves:
+   - adapted Sellable body move:
+
+Rejected examples:
+- author/source:
+- reason rejected:
+
+Save recommendations:
+- track people:
+- gold-standard candidates:
+
+Recommended draft directions:
+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`
@@ -299,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
@@ -316,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
@@ -336,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
@@ -360,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>
@@ -377,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