@sellable/mcp 0.1.237 → 0.1.239

package/skills/create-post/SKILL.md

@@ -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 are working right now, 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 hooks have been working over the past few months, and save a validated draft that sounds like them.
 
 Hard fail patterns:
 
@@ -20,7 +20,7 @@ Hard fail patterns:
 - drafts that skip raw idea capture
 - hooks copied verbatim from another creator
 - using `~/.sellable/configs/content/linkedin-posts-drafts.md` as the normal save target
-</role>
+  </role>
 
 <scope>
 V1 is posts-only and hooks-first.
@@ -42,7 +42,7 @@ Do not:
 - optimize a comment workflow
 - move identity/proof/story memory into content files
 - append new drafts to the legacy flat file
-</scope>
+  </scope>
 
 <required_assets>
 Before drafting, load all required assets with `mcp__sellable__get_subskill_asset`:
@@ -50,6 +50,7 @@ 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"`
 
 If any required asset is missing, unreadable, truncated without continuation, or internally inconsistent, return:
 
@@ -89,7 +90,7 @@ Do not call outbound/campaign tools from this skill. Do not call message-generat
 Load user memory before hook generation or drafting:
 
 1. Call `mcp__sellable__get_engage_memory`.
-2. Read or use the returned core memory fields:
+2. Read or use the returned core identity memory and company memory fields:
    - `core/about-me.md`
    - `core/my-company.md`
    - `core/anti-ai-writing-style.md`
@@ -100,11 +101,44 @@ Load user memory before hook generation or drafting:
    - `core/context-modes.md`
    - `core/decision-rules.md`
    - `core/references/**`
-3. Read post-specific writing rules from `~/.sellable/configs/writing/posts.md` when available.
+3. Use `memory.postWritingRules` returned by `mcp__sellable__get_engage_memory` when present. If the host permits direct file reads and the memory response does not include it, read post-specific writing rules from `~/.sellable/configs/writing/posts.md` when available.
+4. Read the gold-standard post pack from `core/references/linkedin-posts/INDEX.md` and its approved copied/distilled examples when present. `get_engage_memory` may return this through the composed `core/references/**` indexes; if the host permits direct file reads, load the files directly when needed.
+
+`writing/posts.md` is a post-writing config file, not a draft library. Treat its structure this way:
+
+- Top scratch or `## Draft Rule Candidates` sections are candidate taste notes only.
+- The bottom `## Canonical Compiled Rules` section is the active post-writing config.
+- `## Canonical Compiled Rules` overrides conflicting draft notes.
+- Use draft candidates only when they do not conflict with canonical rules or when the user explicitly asks to test one.
+- Do not save post bodies, hook research, or published records into `writing/posts.md`.
 
 New users may have blank or missing core files until they run `$sellable:interview`. If story, proof, identity, or company memory is missing, ask for the missing material or ask the user to run `$sellable:interview`. Never fabricate what should have come from `story-bank.md`, `proof-ledger.md`, or `answer-bank.md`.
 
 The interview/core memory files remain the durable source for stories and proof. This skill may read them, but it must not move them into `~/.sellable/content/**`.
+
+Use core context modes as drafting constraints, not decorative labels. If a
+post idea exposes durable memory that should help future writing, propose a
+core write-back before saving it. The user must be able to approve, edit, or
+reject each proposed memory update before it is written.
+
+Durable write-back targets:
+
+- `core/answer-bank.md` for reusable user answers, positioning, or taste rules
+- `core/wins-ledger.md` for verified wins and outcomes
+- `core/change-log.md` for approved corrections, rejected-but-useful proposals,
+  privacy decisions, and downstream prompt/operator notes
+- `core/story-bank.md` for reusable first-person stories
+- `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
+
+Write-backs must use stable source keys such as
+`create-post:{date}:{ideaId}:{slug}` or
+`create-post-research:{date}:{sourcePostHash}:{slug}`. Check existing copied
+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.
 </memory_contract>
 
 <modes>
@@ -138,6 +172,31 @@ Use when the user says "run the pipeline on this idea" or asks for an immediate
 Normal ad hoc mode still creates an ID'd idea artifact first with `mcp__sellable__capture_post_idea`, preserving the raw input first. Then run the full pipeline immediately.
 
 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.
+
+## 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.
+
+Load `references/gold-standard-post-pack.md` and follow it exactly.
+
+Personal best import:
+
+1. Ask for the user's LinkedIn profile URL or handle if missing.
+2. Call `mcp__sellable__fetch_linkedin_posts`.
+3. Rank candidate posts by engagement quality, full-text availability, voice usefulness, and topic fit.
+4. Split each candidate into hook, content/body mechanism, rhythm, sentence structure, proof/story use, voice fit, risks, and allowed use.
+5. Show a numbered list and ask which posts to add.
+6. Add only the user-approved selections to `~/.sellable/configs/core/references/linkedin-posts/**`.
+
+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.
+
+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>
 
 <pipeline>
@@ -145,8 +204,9 @@ If the user explicitly says not to save anything, label the output `unsaved_prev
 
 1. Load all required assets.
 2. Load memory and post writing rules.
-3. Verify auth/workspace if hook research will use Sellable search.
-4. Capture or load the source idea.
+3. Load the gold-standard post pack if present.
+4. Verify auth/workspace if hook research will use Sellable search.
+5. Capture or load the source idea.
 
 If local idea capture succeeds but auth/workspace is missing, keep the idea and return a typed blocked state for draft readiness:
 
@@ -163,21 +223,29 @@ Use `references/hook-research-playbook.md`.
 Default flow:
 
 1. Convert the idea into 3-8 search keywords.
-2. Call `mcp__sellable__search_engagement_posts`.
-3. Shortlist high-engagement posts by topic fit and hook strength.
+2. Call `mcp__sellable__search_engagement_posts` with an explicit multi-month window. Default to `maxAgeDays: 120`, tightening to 30-60 days only when the topic is trend-sensitive.
+3. Shortlist high-engagement posts by topic fit, hook strength, creator repeat evidence, and weighted engagement quality.
 4. Because search results may only include previews, call `mcp__sellable__fetch_linkedin_posts` for shortlisted authors/profile URLs and match recent posts by URL/activity ID when full text is needed.
 5. If full text cannot be matched, record `full_text_unavailable` and use only the preview. Do not invent missing body details.
-6. Extract hook structures, not wording.
-7. Save the research with `mcp__sellable__save_hook_research`.
+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`.
 
 Record provenance:
 
 - keywords
 - filters
+- search window
 - source post URLs
 - authors/profile URLs
-- engagement totals
+- engagement totals and available likes/comments/shares breakdown
+- creator repeat evidence
+- 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
 - selected hook patterns
 - why each pattern fits the user's idea and voice
 
@@ -189,13 +257,43 @@ Each hook must include:
 
 - source hook pattern
 - why it fits this idea
-- mobile preview check
+- `charCount`
+- `charCountIncludingNewlines`
+- `firstLineChars`
+- `firstTwoLinesChars`
+- `physicalLineCount`
+- `contentLineCount`
+- `longestNonblankLineChars`
+- `blankLineVisualRisk`
+- `previewBudgetStatus`
+- `mobilePreviewFit`
+- `desktopPreviewFit`
+- `lineCountEstimate`
+- `truncationRisk`
+- `rewriteIfTruncated`
 - proof/story dependency
 - AI-tell risk
 - score
 
 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.
+
+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.
+
 ## Step 3: Draft
 
 Draft from:
@@ -206,6 +304,7 @@ Draft from:
 - user's core memory
 - story/proof files
 - post writing rules
+- 1-3 relevant approved gold standards when available
 
 If a claim cannot be traced to the raw idea, core memory, or user answer in the current session, remove it or ask.
 
@@ -221,9 +320,13 @@ Every saved draft needs a validation receipt with:
 - selected hook and why
 - proof claims used and source
 - story/proof files consulted
+- gold standards consulted
+- LinkedIn preview audit
 - simplifier/concrete-language audit findings
 - voice audit findings
 - anti-AI audit findings
+- outbound AI-tell audit findings
+- hook preview pass/warn/fail status and compact fallback when warned
 - finalizer changes
 - blocked/retry-needed reasons, if any
 
@@ -256,6 +359,7 @@ Published post records live under:
 ```text
 ~/.sellable/content/linkedin/published/
 ```
+
 </pipeline>
 
 <legacy>
@@ -278,7 +382,9 @@ validation_summary:
   proof: pass | needs_user_input | blocked
   voice: pass | needs_revision
   anti_ai: pass | needs_revision
+  linkedin_preview: pass | warn | needs_revision
   concrete_language: pass | needs_revision
 next_step: <what the user should do next>
 ```
+
 </response_shape>

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

@@ -0,0 +1,211 @@
+# Gold Standard Post Pack
+
+The gold-standard pack is user-owned memory with an MCP-owned schema.
+
+MCP owns:
+
+- this schema
+- selection workflow
+- scoring rubric
+- decomposition rules
+- validation rules
+
+The user's computer owns:
+
+- personal best posts
+- approved inspiration posts from the space
+- copied or distilled examples
+- approval notes
+- allowed-use limits
+
+## Storage
+
+Approved gold standards live under:
+
+```text
+~/.sellable/configs/core/references/linkedin-posts/
+  INDEX.md
+  gold-standard-<slug>.md
+```
+
+The pack is capped at 20 approved gold standards. Candidate examples do not
+count toward the cap until the user approves them.
+
+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.
+
+## Import Modes
+
+### Personal Best Import
+
+Use when the user asks to import their best posts, calibrate on their old posts,
+or build the pack from their LinkedIn profile.
+
+1. Ask for the user's LinkedIn profile URL or handle if it is not already known.
+2. Call `mcp__sellable__fetch_linkedin_posts`.
+3. Rank candidate personal posts by engagement quality, topic fit, full-text
+   availability, voice usefulness, and whether the user says the post felt like
+   them.
+4. Present a numbered candidate list.
+5. Ask which posts to add, skip, or mark as anti-examples.
+6. Add only the user-approved selections.
+
+### Space Benchmark Research
+
+Use when the user asks to research what is working in the space or add outside
+gold standards.
+
+1. Derive search terms from the user's topic, ICP, current idea, and proven
+   search memory.
+2. Use the hook research playbook and `mcp__sellable__search_engagement_posts`.
+3. Prefer recent multi-month winners, repeated creator success, strong
+   share/repost signals, and full-text availability.
+4. Penalize lead magnets, giveaway mechanics, engagement bait, celebrity-only
+   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.
+
+## Candidate Presentation
+
+Show compact candidate cards. Include:
+
+- candidate number
+- type: `personal_best`, `space_benchmark`, or `anti_example`
+- author
+- source URL
+- engagement breakdown when available
+- why it might belong in the pack
+- hook mechanism
+- hook preview budget status and measurement basis
+- content/body mechanism
+- rhythm notes
+- sentence-structure notes
+- proof/story use
+- voice fit
+- risks
+- allowed use recommendation
+
+Approval prompt:
+
+```text
+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.
+```
+
+Do not write candidates to the approved pack before the user chooses.
+
+## Approved Index Schema
+
+`INDEX.md` should use a table with these fields:
+
+- `Status` - `approved` or `anti-example`
+- `Type` - `personal_best` or `space_benchmark`
+- `Title`
+- `Source URL`
+- `Copied Path`
+- `Added`
+- `Score`
+- `Tags`
+- `Primary Use`
+- `Allowed Use`
+- `Hook Pattern`
+- `Body Pattern`
+- `Rhythm Notes`
+- `Sentence Notes`
+- `Risks`
+- `Key`
+
+Use stable keys from normalized source URL/title plus an optional content hash.
+If the same source appears again, update the existing row instead of adding a
+duplicate.
+
+## Approved Example File Schema
+
+Each copied or distilled `gold-standard-<slug>.md` should include:
+
+```text
+# <Title>
+
+Source URL:
+Type:
+Status:
+Added:
+Allowed use:
+Tags:
+
+## Original Or Distilled Text
+
+<Full text only when safe and approved. Otherwise store a short distilled summary.>
+
+## Hook Breakdown
+
+- hook text:
+- char count:
+- char count including newlines:
+- first-line chars:
+- first-two-line chars:
+- physical line count:
+- content line count:
+- longest nonblank line chars:
+- blank-line visual risk:
+- source text basis:
+- preview budget status:
+- mobile preview fit:
+- desktop preview fit:
+- hook mechanism:
+- internal question:
+- emotional trigger:
+
+## Content / Body Breakdown
+
+- thesis:
+- body mechanism:
+- story mechanism:
+- proof mechanism:
+- argument moves:
+- close:
+- what made it work:
+
+## Rhythm
+
+- line breaks:
+- paragraph length:
+- sentence length:
+- pacing:
+- punctuation:
+
+## Sentence Structure
+
+- sentence starts:
+- fragments:
+- contrast moves:
+- specificity moves:
+- repeated syntax:
+
+## Usage Notes
+
+- imitate:
+- do not copy:
+- voice fit:
+- risks:
+```
+
+## Selection Rules For Drafting
+
+Before drafting a post, use at most 1-3 relevant gold standards. Prefer:
+
+- the user's own approved posts over outside benchmarks
+- examples with matching topic, mechanism, or story shape
+- examples whose allowed use includes `imitate structure`
+- examples with clear hook/body/rhythm/sentence decomposition
+
+Never copy outside wording. For personal posts, reuse wording only when the user
+explicitly asks to reuse their own line. Otherwise, use the pack for structure,
+taste, and judgment.
+
+If the pack is empty, continue with core memory and hook research. Do not block
+normal drafting just because no gold standards exist.

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

@@ -15,11 +15,51 @@ Derive 3-8 keyword searches from:
 
 Use `mcp__sellable__search_engagement_posts` with practical constraints:
 
-- recent enough to reflect what is working now
+- explicit `maxAgeDays: 120` by default so research covers the past 30-120 days, not only this week's posts
+- tighten to 30-60 days for trend-sensitive topics; widen only when the topic has low volume
 - high enough engagement to matter
 - narrow enough to match the idea
+- enough result depth to see whether a creator has repeated winners, not just one viral outlier
 
-Record every keyword, filter, and result count.
+Record every keyword, filter, search window, page, and result count.
+
+## Weighted Signals
+
+Rank source posts with a weighted signal view. Do not sort by total engagement alone.
+
+Use this scoring shape:
+
+```text
+hook_score =
+  topic_fit
+  + hook_clarity
+  + creator_repeat_success
+  + repost_share_strength
+  + comment_quality
+  - lead_magnet_penalty
+  - engagement_bait_penalty
+  - off_voice_penalty
+```
+
+Guidance:
+
+- Shares/reposts are the strongest signal because a reader spends their own feed reputation.
+- Comments are stronger than reactions only when they are substantive; giveaway comments are weak.
+- Reactions are weak reach unless paired with shares/reposts or strong comments.
+- If the tool returns `engagement.shares`, treat it as the repost/share proxy.
+- If share or repost data is unavailable, record `repost_data_unavailable` instead of inventing it.
+- Prefer creators with repeated high-performing posts in the same lane over one-off viral posts.
+
+Penalize lead-magnet and engagement-bait mechanics unless the user explicitly asks for that style:
+
+- `comment "template"` / `comment "guide"` / `comment "playbook"`
+- "DM me"
+- "I'll send it"
+- "free template"
+- "free prompt"
+- "repost for access"
+- "like and comment"
+- broad giveaway framing that makes engagement inflate without proving the hook/body worked
 
 ## Full Text Reality
 
@@ -34,6 +74,47 @@ When full hook/body text matters:
 
 If full text is unavailable, record `full_text_unavailable`. Use only the preview for hook analysis and do not infer missing body details.
 
+## Opening Preview Measurement
+
+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:
+
+- `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.
+
+Desktop preview has more room, so record it separately, but never let desktop
+fit compensate for a mobile `fail`.
+
+For each source, record:
+
+- `sourceTextBasis`: `full_text`, `search_preview`, or `manual_user_source`
+- `openingTextUsed`
+- `charCountIncludingNewlines`
+- `physicalLineCount`
+- `contentLineCount`
+- `firstLineChars`
+- `firstTwoPhysicalLinesChars`
+- `firstTwoContentLinesChars`
+- `longestNonblankLineChars`
+- `blankLineCountBeforeFold`
+- `mobilePreviewBudget`: `pass`, `warn`, or `fail`
+- `desktopPreviewBudget`: `pass`, `warn`, or `fail`
+- `blankLineVisualRisk`
+- `corePointBeforeLikelyTruncation`
+
+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.
+
 ## Hook Extraction
 
 Extract structure, not wording.
@@ -42,15 +123,33 @@ For each shortlisted source post, record:
 
 - URL
 - author
-- engagement totals
+- engagement totals and available likes/comments/shares breakdown
+- creator repeat evidence
 - visible hook text or preview
-- line count and mobile preview fit
+- opening preview measurement fields from the section above
 - hook mechanism
+- story mechanism when the post is a story
 - internal question created
 - emotional trigger
 - proof/story dependency
+- lead magnet or engagement bait penalty
+- weighted signal notes
 - replicability score
 
+## Story Mechanism
+
+For story posts, do not reduce the source to "strong first line" or a generic lesson. Extract the mechanism that made the story travel:
+
+- concrete first-person moment
+- visible tension or tradeoff
+- mistake, regret, reversal, or confession
+- before/after shift
+- founder/operator decision point
+- uncomfortable but specific truth
+- proof embedded in the scene rather than pasted on later
+
+If the source story only works because of celebrity, outrage, giveaway mechanics, or an unavailable body section, mark it as low-replicability or `full_text_unavailable`.
+
 ## Blocked States
 
 Local idea capture can still succeed when research fails.

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

@@ -59,6 +59,9 @@ Hook research files must preserve:
 - author/profile URLs
 - engagement totals
 - full-text availability
+- 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
 - extracted hook patterns
 - selected hook basis
 
@@ -67,7 +70,8 @@ Draft files must preserve:
 - source idea ID
 - hook research ID
 - draft body
-- validation receipt
+- 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`
 
 Published files must preserve: