@sellable/mcp 0.1.239 → 0.1.242

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

@@ -35,6 +35,42 @@ Do not store gold standards under `~/.sellable/content/linkedin/**`. Content
 folders are for ideas, hook research, drafts, published records, and future
 comment history. Gold standards are durable writing memory.
 
+## Creator Tracking
+
+When an outside creator/person is approved as someone the user wants to keep
+learning from, save the person separately from the gold-standard post.
+
+Use:
+
+```text
+mcp__sellable__upsert_engage_tracked_person({
+  name,
+  linkedinUrl,
+  reason
+})
+```
+
+Tracked people live in:
+
+```text
+~/.sellable/configs/discovery/influencers.md
+```
+
+Gold-standard post records live in:
+
+```text
+~/.sellable/configs/core/references/linkedin-posts/
+```
+
+Save both when both are approved:
+
+- tracked person: "keep fetching this creator's new posts"
+- gold-standard post: "use this specific post as decomposed writing memory"
+
+Do not conflate the two. A person can be tracked without any one post becoming
+a gold standard, and a post can be saved as a gold standard without tracking the
+author.
+
 ## Import Modes
 
 ### Personal Best Import
@@ -65,7 +101,11 @@ gold standards.
    reach, and examples that cannot be adapted to the user's voice.
 5. Present candidates with a clear "should we use these as gold standards?"
    approval gate.
-6. Add only the user-approved selections.
+6. Include a `track person?` recommendation for authors with repeated strong
+   topic-fit posts or when the user says they like the person.
+7. Add only the user-approved post selections.
+8. Call `mcp__sellable__upsert_engage_tracked_person` only for user-approved
+   tracked people.
 
 ## Candidate Presentation
 
@@ -86,6 +126,7 @@ Show compact candidate cards. Include:
 - voice fit
 - risks
 - allowed use recommendation
+- track person recommendation and reason
 
 Approval prompt:
 
@@ -93,7 +134,7 @@ Approval prompt:
 Gold-standard pack: <current_count>/20 approved.
 
 These look like candidates worth saving. Which should I add?
-Reply with numbers to add, "skip all", or "replace <existing> with <new>" if the pack is full.
+Reply with numbers to add, "track <author>", "skip all", or "replace <existing> with <new>" if the pack is full.
 ```
 
 Do not write candidates to the approved pack before the user chooses.

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
 
@@ -11,6 +11,63 @@ Derive 3-8 keyword searches from:
 - proven search terms in engage memory
 - tracked people/inspiration references when relevant
 
+When research reveals a creator/person the user likes, keep their profile URL
+with the source post. If the user approves tracking them, save them with
+`mcp__sellable__upsert_engage_tracked_person` so future sessions can fetch
+their posts directly instead of rediscovering them ad hoc.
+
+## Background Research Worker
+
+Use a background research worker when the host supports it and the research
+needs more than a small handful of posts. This keeps the main orchestrator
+focused on decisions instead of carrying a large source corpus.
+
+Worker owns:
+
+- broad keyword search
+- tracked-person post fetches
+- 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
+- rejected-example notes
+- track-person and gold-standard recommendations
+
+Orchestrator owns:
+
+- deciding whether research is enough
+- saving `mcp__sellable__save_hook_research`
+- showing the `Research Learning Report`
+- asking which direction to draft
+- drafting and validation
+
+Worker output must be a compressed research packet, not a data dump:
+
+```text
+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
+- source URLs and author profile URLs
+- preview measurements
+- confidence gaps
+- save recommendations
+```
+
+Do not return the full raw text of every post to the orchestrator. Include only
+short source excerpts needed to explain a phrase pattern, plus URLs. Full text
+belongs in the saved research artifact only when the user approves a specific
+gold-standard candidate and it is safe to store.
+
 ## Default Search
 
 Use `mcp__sellable__search_engagement_posts` with practical constraints:
@@ -61,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.
@@ -117,17 +235,23 @@ appears cut off or body context is unavailable.
 
 ## Hook Extraction
 
-Extract structure, not wording.
+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 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:
 
 - URL
 - author
+- author profile URL when available
 - engagement totals and available likes/comments/shares breakdown
 - creator repeat evidence
 - visible hook text or preview
 - opening preview measurement fields from the section above
 - hook mechanism
+- exact hook language patterns: reusable words, phrase shapes, contrast forms,
+  sentence shapes, and transition moves
 - story mechanism when the post is a story
 - internal question created
 - emotional trigger
@@ -135,6 +259,81 @@ For each shortlisted source post, record:
 - lead magnet or engagement bait penalty
 - weighted signal notes
 - replicability score
+- track person recommendation: `yes`, `no`, or `ask_user`
+- tracking reason when recommended
+
+## Specific Language Extraction
+
+For each keeper, extract the source's specific language mechanics in this
+format:
+
+```text
+Phrase pattern:
+"<phrase or phrase shape>"
+
+Role:
+<what the words do: create contrast, compress pain, name the enemy, make timing
+the villain, move from surface action to system outcome, etc.>
+
+Source:
+<author + URL>
+
+Reusable forms:
+- <template form 1>
+- <template form 2>
+- <template form 3>
+
+Adapted to user's idea:
+- <new phrase in the user's voice>
+
+Do not copy:
+<words, proof, joke, or company context that belongs to the source>
+```
+
+Examples of the level of specificity required:
+
+- "not because [obvious reason]. because [real reason]."
+- "most teams stop at [surface step]."
+- "the [thing] was [state]. you just never [saw/used/launched] it in time."
+- "the maintenance is the tax."
+- "[thing] does not fail in your head. it fails in the gap between [A] and [B]."
+- "the important part is not that AI [surface action]. the important part is that [system outcome]."
+- "one [constrained operator] can run the whole [machine] if [constraint]."
+
+Never reduce this section to high-level labels like "contrarian" or
+"founder story." Those labels are allowed only after the exact phrase mechanics
+are captured.
+
+## Body Structure Extraction
+
+For each keeper with full text available, extract the body in this format:
+
+```text
+Body pattern:
+<short name>
+
+Source:
+<author + URL>
+
+Sequence:
+1. <paragraph/job 1>
+2. <paragraph/job 2>
+3. <paragraph/job 3>
+
+Exact language moves:
+- "<phrase shape or transition>"
+- "<sentence pattern>"
+- "<closing move>"
+
+Adapted body move:
+<how this would show up in the user's post>
+
+Replicability:
+high | medium | low
+```
+
+If full text is unavailable, record `full_text_unavailable` and do not infer
+body structure beyond the visible preview.
 
 ## Story Mechanism
 
@@ -165,3 +364,19 @@ Draft-ready output must block or retry when:
 ## Save Requirement
 
 Save the research with `mcp__sellable__save_hook_research` before drafting.
+
+The saved research must contain enough detail to support a user-visible
+`Research Learning Report`: source examples, full adapted hook blocks, exact
+phrase patterns, body structures, rejected examples, tracked-person
+recommendations, and gold-standard recommendations.
+
+If the user approves a creator/person as a recurring inspiration source, also
+call `mcp__sellable__upsert_engage_tracked_person` with:
+
+- `name`: display name
+- `linkedinUrl`: canonical LinkedIn profile URL
+- `reason`: concise lane and why they are worth tracking
+
+Do not track a person only because one post was viral. Track them when they have
+repeated strong posts, unusually high topic fit, or the user explicitly says
+they like them.

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
 

package/skills/create-post/references/post-validation.md

@@ -6,6 +6,8 @@ Every saved draft needs a validation receipt. A draft without this receipt is no
 
 - `sourceIdeaId`
 - `hookResearchId`
+- `iteration`
+- `selectedPremiseCard`
 - `candidateHooksConsidered`
 - `selectedHook`
 - `selectedHookWhy`
@@ -14,6 +16,8 @@ Every saved draft needs a validation receipt. A draft without this receipt is no
 - `storyFilesConsulted`
 - `goldStandardsConsulted`
 - `voiceRulesApplied`
+- `marketBeliefAudit`
+- `premiseValueAudit`
 - `linkedinPreviewAudit`
 - `simplifierConcreteLanguageAudit`
 - `antiAiAudit`
@@ -23,6 +27,45 @@ Every saved draft needs a validation receipt. A draft without this receipt is no
 - `retryNeededReasons`
 - `readyStatus`
 
+## Iteration Receipt
+
+Every saved draft needs iteration metadata, even the first draft. This lets the
+content library show whether later drafts are actually improving.
+
+For the first ready draft of an idea, record:
+
+- `version: v1`
+- `priorDraftId: none`
+- `iterationRole: baseline`
+- `changeIntent`
+- `score`
+- `verdict`
+- `nextIterationTargets`
+
+For later drafts, record:
+
+- `version`
+- `priorDraftId`
+- `changeIntent`
+- `whatChanged`
+- `whatImproved`
+- `whatGotWorse`
+- `score`
+- `verdict`
+
+Use a score object with at least:
+
+- `hook`
+- `proof`
+- `voice`
+- `specificity`
+- `skimmability`
+- `publishConfidence`
+
+Do not call a later draft better just because it is newer. If the hook is
+stronger but proof, voice, or clarity got worse, say that in `whatGotWorse` and
+set the verdict to `revise` or `reject`.
+
 ## Candidate Set
 
 Generate multiple hook candidates before drafting. Do not lock onto the first draft.
@@ -30,6 +73,9 @@ Generate multiple hook candidates before drafting. Do not lock onto the first dr
 Each candidate should include:
 
 - hook text
+- selected premise
+- premise tension opened
+- reader value implied
 - source pattern
 - score
 - char count including newlines and first-line / first-two-line preview measurements
@@ -45,12 +91,61 @@ Each candidate should include:
 After the first draft:
 
 1. remove unsupported claims
-2. tighten the hook
-3. simplify abstract phrasing
-4. replace generic language with concrete words only when supported
-5. preserve the user's actual story and point
-6. remove AI tells
-7. re-check LinkedIn preview fit after edits
+2. verify the draft is anchored to the selected market belief and controversy
+3. verify the real story/scene, tension, and reader value are visible early
+4. tighten the hook
+5. simplify abstract phrasing
+6. replace generic language with concrete words only when supported
+7. preserve the user's actual story and point
+8. remove AI tells
+9. re-check LinkedIn preview fit after edits
+
+## Premise Value Audit
+
+Before a draft can be `ready`, validate that the post is valuable, not just
+well wrapped.
+
+Record:
+
+- `premise`: the selected premise in one sentence
+- `realStoryOrScene`: the concrete scene, observation, or pattern used
+- `targetReader`: who should care
+- `commonBelief`: the belief the post argues against
+- `contrarianTruth`: the sharper belief the post offers
+- `visibleTension`: the uncomfortable gap or cost
+- `readerValue`: what the reader learns, sees differently, or can do
+- `proofAvailable`: source-backed proof used
+- `proofMissing`: claims intentionally avoided or requiring user input
+- `premiseQualityGates`: pass/fail for `specific_scene_or_pattern`,
+  `clear_reader`, `visible_tension`, `reader_value`, `credible_speaker`,
+  `proof_safety`, and `market_heat`
+- `bodyOutline`: how the body delivers the premise before prose
+
+If the draft has no specific scene or observed pattern, no visible tension, or
+no reader value beyond "this is interesting," save as `needs_revision`. Do not
+mark it `ready` because the hook passes preview limits.
+
+## Market Belief Audit
+
+Before a draft can be `ready`, validate that it is not merely an internally
+coherent idea. It must be anchored to the saved research's market belief map.
+
+Record:
+
+- `resonatingIdea`: the current-space idea this draft enters
+- `implicitBelief`: the belief the audience likely already holds
+- `audienceWant`: what the audience wants permission, leverage, proof, or a new
+  category for
+- `audienceResentmentOrFear`: what frustration or risk gives the post tension
+- `selectedControversy`: the claim the post is testing
+- `credibleWhyUs`: why the user can credibly say this from raw idea, memory,
+  story, proof, or product mechanism
+- `engagementReason`: why someone would react, comment, repost, or argue
+- `unsupportedHypeRemoved`: unsupported claims removed during finalizer
+
+If `selectedControversy` is missing, if the audience belief is only a generic
+label like "founders want growth," or if `credibleWhyUs` depends on borrowed
+proof from another creator, save as `needs_revision`.
 
 ## LinkedIn Preview Audit
 

package/skills/create-post/references/premise-development.md

@@ -0,0 +1,159 @@
+# Premise Development
+
+A strong post is not an idea with a better hook. A strong post is a valuable
+premise wrapped in a sharp opening.
+
+Use this stage after market/hook research and before hook candidates. Do not
+generate hook candidates until at least one `Premise Card` exists.
+
+## Goal
+
+Turn the raw idea into a real story, observed tension, or useful argument that a
+specific reader would care about.
+
+The premise must answer:
+
+- who this is for
+- what real scene, observation, or pattern created the idea
+- what tension makes it worth reading
+- what common belief it argues against
+- what hidden truth or mechanism it reveals
+- what value the reader gets
+- why now
+- why this user can credibly say it
+- what proof is available and what proof is missing
+
+If the premise has no real scene, no tension, and no reader value, stop before
+drafting. Ask for the missing story or save only a `needs_revision` premise
+artifact. Do not compensate with clever hooks.
+
+## Real Story / Scene Search
+
+Before writing premise cards, search the available source material:
+
+- raw idea text
+- voice memo or transcript if provided
+- `core/story-bank.md`
+- `core/answer-bank.md`
+- `core/proof-ledger.md`
+- `core/wins-ledger.md`
+- approved references and gold standards
+- current-session user corrections or rejections
+
+Look for:
+
+- a moment: "I saw X", "a founder said Y", "I opened Z and noticed..."
+- a contradiction: the user wanted one thing but the workflow rewarded another
+- a cost: time, attention, trust, missed learning, reputation, money
+- a before/after: what changed in the user's belief
+- a specific object: Slack note, customer call, campaign table, reply, list,
+  demo, failed draft, stale idea, messy workflow
+
+If no real story is present, use an observed pattern only if it is traceable to
+the raw source or memory. Mark the gap in the premise card. Do not fabricate a
+customer, call, outcome, date, metric, or private scene.
+
+## Premise Cards
+
+Generate 3-5 premise cards before hooks. Each card must use this shape:
+
+```text
+Premise Card
+
+premise:
+<one-sentence argument>
+
+real story / scene:
+<specific moment, observation, or pattern from source/memory>
+
+target reader:
+<who should care>
+
+common belief:
+<what the reader or market usually believes>
+
+contrarian truth:
+<what this post argues instead>
+
+tension:
+<why this is uncomfortable, costly, or worth arguing about>
+
+reader value:
+<what the reader learns, sees differently, or can do after reading>
+
+why now / market heat:
+<what current research says is resonating>
+
+credible why-us:
+<why this user can say it from source, memory, proof, or product mechanism>
+
+proof available:
+<specific usable proof or source>
+
+proof missing:
+<claims that cannot be made yet>
+
+best frame:
+story | contrarian take | teardown | founder confession | future thesis | lesson
+
+hook territories:
+- <territory 1>
+- <territory 2>
+- <territory 3>
+
+risk:
+<why this premise might still be weak>
+
+score:
+<1-100 with short reason>
+```
+
+## Premise Quality Gate
+
+A premise can move to hook generation only when it passes all of these:
+
+- `specific_scene_or_pattern`: pass
+- `clear_reader`: pass
+- `visible_tension`: pass
+- `reader_value`: pass
+- `credible_speaker`: pass
+- `proof_safety`: pass
+- `market_heat`: pass or explained
+
+If any gate fails:
+
+- in research checkpoint mode, show the cards and ask for the missing story or
+  direction
+- in immediate draft mode, save the draft as `needs_revision`, not `ready`
+- never mark a draft `ready` because the hook is clever
+
+## Hook Relationship
+
+Hooks are generated from the selected premise, not from the raw idea alone.
+
+For each hook candidate, include:
+
+- selected premise ID or title
+- which tension it opens
+- which reader value it implies
+- whether the real scene appears in the first screen or shortly after
+
+Reject hooks that are accurate but do not reveal the premise's tension or value.
+
+## Body Relationship
+
+Before drafting prose, create a short body outline for the selected premise:
+
+```text
+body outline:
+1. hook stack opens the tension
+2. real scene or pattern makes it concrete
+3. common belief gets named
+4. contrarian truth lands
+5. mechanism explains why
+6. reader value becomes clear
+7. close returns to the premise without summarizing
+```
+
+If this outline cannot be filled without inventing proof, return to premise
+development.