@sellable/mcp 0.1.239 → 0.1.240

package/package.json

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

package/skills/create-post/SKILL.md

@@ -82,6 +82,7 @@ Use these MCP tools when available:
 - `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 +132,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 +142,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>
@@ -173,6 +183,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 +226,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 +256,27 @@ 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
+- 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.
@@ -230,7 +287,8 @@ Default flow:
 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.
+9. 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`.
 
 Record provenance:
@@ -247,8 +305,77 @@ Record provenance:
 - full-text match status
 - source hook preview measurements and whether they came from full text or a search preview
 - selected hook patterns
+- 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
+
+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. hook block + body structure
+2. hook block + body structure
+3. 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 2: Hook Candidates
 
 Generate at least 12 hook candidates unless the user requested a smaller set.

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

@@ -11,6 +11,58 @@ 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
+- 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
+- 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:
@@ -117,17 +169,22 @@ 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 user's voice.
 
 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 +192,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 +297,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.