@sellable/mcp 0.1.258 → 0.1.260

package/skills/create-post/SKILL.md

@@ -60,9 +60,8 @@ Do:
 
 - capture rough ideas, voice memos, freestyle notes, and ad hoc prompts
 - research currently working LinkedIn hooks
-- reverse engineer why source hooks work, what shape to keep, and what not to copy
 - develop premise cards with real story/observed tension and reader value
-- explore many hook angle territories before choosing the winning hook
+- generate hook candidates
 - draft a post body that stays true to the source idea
 - run validation before calling a draft ready
 - save ideas, hook research, drafts, and published records under `~/.sellable/content/linkedin/**`
@@ -306,8 +305,7 @@ If local idea capture succeeds but auth/workspace is missing, keep the idea and
 
 ## Step 1: Hook Research
 
-Use `references/hook-research-playbook.md` and
-`references/linkedin-preview-rendering.md`.
+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
@@ -319,16 +317,18 @@ and drafting gate.
 The research worker must return a compact packet only:
 
 - source examples kept and rejected
-- hook reverse-engineering autopsies: why each source hook works, which shape to
-  keep, what not to copy, and what payoff the body must deliver
 - full adapted hook blocks
-- angle territories tested before drafting
 - 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
-- reach-normalized signal notes, including follower-band fit when available
 - exact phrase patterns and sentence shapes
+- post positioning breakdowns that label each meaningful line or phrase by
+  narrative job and category
+- viral-post outlines for the best source posts
+- line-to-template conversions that turn source structures into reusable
+  templates without source wording
+- hook-to-body promise maps that show how each hook tells the body
 - body structures and exact body language moves
-- rendered mobile and desktop preview records
+- preview measurements
 - track-person and gold-standard recommendations
 - blocked states or confidence gaps
 
@@ -339,24 +339,26 @@ the exact extracted phrase shapes.
 Default flow:
 
 1. Convert the idea into 3-8 search keywords.
-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. When the user gives a follower range, pass it as `targetFollowerMin` and `targetFollowerMax`; for example, "8k-20k followers" means `targetFollowerMin: 8000` and `targetFollowerMax: 20000`.
-3. Shortlist posts by topic fit, rendered hook strength, content pattern replicability, creator repeat evidence, weighted engagement quality, and reach-normalized signal quality. Do not sort by raw engagement alone, and do not let the numeric reach score choose the final hook by itself.
-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. If a promising source is missing follower count and the user requested reach normalization, call `mcp__sellable__fetch_linkedin_profile` on a bounded shortlist before treating the source as a keeper.
+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. Weigh shares/reposts above comments, comments above reactions, and reactions as weak reach unless paired with stronger signals. Normalize engagement against follower count when available: record `authorFollowerCount`, `targetFollowerBand`, `followerBandFit`, `engagementPer1kFollowers`, `weightedEngagementPer1kFollowers`, `reachPenaltyMultiplier`, `reachAdjustedScore`, and `baselineLift` when repeated creator posts make it possible. If follower count is unavailable, record `follower_count_unavailable`; if shares/reposts are unavailable, record `repost_data_unavailable`.
+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. 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. For each keeper, create a `hookAutopsy`: the source mechanism, open-loop
-   type, click question, promised payoff, specificity anchor, tension opened,
-   source shape to keep, source words not to copy, and adaptation rule for the
-   user's idea.
-13. Render each kept source hook and adapted hook block through the LinkedIn
-   preview rendering contract. Character counts alone are not enough.
-14. Save the research with `mcp__sellable__save_hook_research`.
+12. Create a post positioning breakdown for each keeper post: line/phrase,
+    category, narrative technique, tension created, reader question opened,
+    proof dependency, and reusable template line.
+13. Convert each keeper into a viral-post outline: hook job, see-more trigger,
+    body payoff, close job, and beat-by-beat narrative structure.
+14. Convert the best outlines into reusable post templates with positioning
+    sequences, required story/proof inputs, forbidden borrowing, and
+    Sellable-specific adaptation instructions.
+15. Save the research with `mcp__sellable__save_hook_research`.
 
 Record provenance:
 
@@ -365,29 +367,22 @@ Record provenance:
 - search window
 - source post URLs
 - authors/profile URLs
-- author follower counts and target follower-band fit when available
 - engagement totals and available likes/comments/shares breakdown
-- reach-normalized scoring fields and confidence notes
 - creator repeat evidence
 - lead-magnet or engagement-bait penalties
 - story mechanism when relevant
 - full-text match status
-- source hook rendered preview records and whether they came from full text,
-  authenticated LinkedIn screenshots, or a search preview
+- source hook preview measurements and whether they came from full text or a search preview
 - selected hook patterns
-- hook reverse-engineering autopsies, including `clickQuestion`,
-  `promisedPayoff`, `sourceShapeToKeep`, `sourceWordsNotToCopy`, and
-  `adaptationRule`
 - market belief map and selected controversy
 - premise cards and selected premise
 - exact phrase patterns and sentence shapes
+- post positioning breakdowns
+- viral-post outlines
+- reusable post templates
+- hook-to-body promise maps
 - body structures and body language patterns
 - why each pattern fits the user's idea and voice
-- `whyTheHookCarries`: why the selected hook works from the words, tension, and
-  content pattern independent of the source creator's reach
-- `whyTheReachEvidenceIsTrustworthy`: follower-band fit, reach-adjusted score,
-  baseline lift, share/comment quality, or why a large-account example is only
-  secondary pattern evidence
 
 ## Step 1.5: Research Learning Report
 
@@ -413,9 +408,6 @@ Research status:
 - keywords:
 - full-text coverage:
 - repost/share data:
-- target follower band:
-- reach-normalized winners:
-- big-account examples used only as secondary pattern evidence:
 
 Best source examples:
 1. author, URL, engagement, why kept, why not copied
@@ -436,16 +428,11 @@ Premise cards:
 Hook patterns learned:
 1. full adapted hook block
    - source mechanism:
-   - open-loop type:
-   - click question:
-   - promised payoff:
-   - source shape to keep:
-   - source words not to copy:
-   - rendered preview:
-     - mobile visible block:
-     - desktop visible block:
-     - verdict:
+   - preview budget:
+   - see-more tension:
+   - curiosity debt:
    - internal question:
+   - hook-to-body promise:
    - why it fits / why it does not:
 
 Specific words and phrase shapes:
@@ -456,9 +443,35 @@ Specific words and phrase shapes:
    - adapted Sellable form:
    - do not copy:
 
+Post positioning breakdown templates:
+1. source + template name
+   - positioning sequence:
+   - line-level narrative techniques:
+   - tension created:
+   - reader questions opened:
+   - reusable template lines:
+   - Sellable adaptation:
+
+Viral-post outlines:
+1. outline name
+   - hook job:
+   - see-more trigger:
+   - body payoff:
+   - close job:
+   - beat sequence:
+
+Line-to-template conversion:
+1. source line/beat
+   - narrative job:
+   - template line shape:
+   - required user story/proof:
+   - forbidden borrowing:
+   - adapted Sellable expression:
+
 Body structures learned:
 1. structure name
    - source:
+   - positioning sequence:
    - sequence:
    - exact language moves:
    - adapted Sellable body move:
@@ -472,9 +485,9 @@ Save recommendations:
 - gold-standard candidates:
 
 Recommended draft directions:
-1. premise card + hook territory + hook block + click question + body structure
-2. premise card + hook territory + hook block + click question + body structure
-3. premise card + hook territory + hook block + click question + body structure
+1. premise card + source template + hook block + viral outline + body structure
+2. premise card + source template + hook block + viral outline + body structure
+3. premise card + source template + hook block + viral outline + body structure
 ```
 
 Keep this report concise enough to read, but concrete enough that another agent
@@ -488,7 +501,9 @@ 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.
+score. Each card must also evaluate which source template or no-template path
+fits, which positioning sequence to test, and how the hook promise will be
+repaid in the body.
 
 Select the strongest premise before hook generation. The selected premise must
 pass:
@@ -500,56 +515,76 @@ pass:
 - `credible_speaker`
 - `proof_safety`
 - `market_heat`
+- `template_fit`
+- `hook_to_body_repayment`
 
 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
+## Step 1.9: Pre-Draft Structure Brief
+
+Before generating final draft prose, create and show a compact `Pre-Draft
+Structure Brief`. In other words, show a compact Pre-Draft Structure Brief
+before the final draft body. This is the checkpoint that prevents the agent from
+jumping from a good hook into a messy body.
 
-Generate a hook angle matrix from the selected premise before writing the post
-body. Do not generate hooks directly from the raw idea before the premise is
-selected.
+The brief must be concise, mobile-scanable, and concrete enough for the user to
+approve or correct. Do not hide it inside the validation receipt after the
+draft. Show it before writing the draft body unless the user explicitly says to
+skip outline/structure and write immediately. Even when the user skips the
+visible checkpoint, still include the brief in the validation receipt.
 
-Minimum exploration:
+The `Pre-Draft Structure Brief` must include:
 
-- normal drafting: at least 8 distinct angle territories and 24 hook candidates
-- hook-critical requests, "nail the hook," "a ton of angles," or space research:
-  at least 12 distinct angle territories and 40 hook candidates
-- smaller set only when the user explicitly asks for fewer options
+```text
+Pre-Draft Structure Brief
+- hook:
+- thesis:
+- reader being taught:
+- why this reader cares now:
+- core equation or mechanism:
+- key definitions:
+- proof claims:
+- proof source / risk:
+- source template or no-template rationale:
+- mobile scan path:
+- section outline:
+- body promise after see more:
+- concrete examples to include:
+- abstractions to remove:
+- draft risks:
+```
 
-Angle territories must be genuinely different. Use options such as enemy/tool
-contrast, hidden asset, first-person build proof, workflow reveal, contrarian
-category claim, mistake/confession, market timing, operator pain,
-asset/free-reveal without comment bait, specific person/company signal,
-before/after transformation, and question hook.
+Rules:
+
+- The hook must already have a rendered mobile and desktop preview record.
+- The thesis must be one sentence the post can defend.
+- The reader must be specific enough to guide what gets cut.
+- Key definitions must name concrete examples when the post teaches an
+  operating concept. For example, define `lead source` as how the list was
+  built, not as a persona label.
+- `mobile scan path` must say what a reader understands if they read only the
+  hook, separators, section labels, numbers, and final line.
+- `abstractions to remove` must list abstract phrases and the concrete words
+  that will replace them.
+- If the user corrects the brief, update the brief first, then draft. Do not
+  patch the final prose while leaving the brief stale.
+
+## Step 2: Hook Candidates
+
+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
-- angle territory
 - premise tension opened
 - reader value implied
 - source hook pattern
-- source shape kept
-- source words not copied
 - why it fits this idea
-- `renderedPreview` using `references/linkedin-preview-rendering.md`
-- `mobileRenderedPreviewBlock`
-- `desktopRenderedPreviewBlock`
-- `mobileRenderedLines`
-- `desktopRenderedLines`
-- `firstScreenPromise`
-- `intentionalOpenLoop`
-- `specificClickQuestionVisible`
-- `seeMoreClickReason`
-- `clickQuestion`
-- `payoffAfterFold`
-- `bodyProofObligation`
-- `corePainProofOrCuriosityVisibleMobile`
-- `corePointVisibleMobile`
-- `pointAfterMobileClamp`
 - `charCount`
 - `charCountIncludingNewlines`
 - `firstLineChars`
@@ -566,50 +601,26 @@ Each hook must include:
 - `rewriteIfTruncated`
 - proof/story dependency
 - AI-tell risk
-- why it should win
-- why it should lose
 - score
 
 Do not copy source wording. Copy only the structure.
 
-Render every candidate before scoring it. The LinkedIn preview rendering
-contract is the gate; character counts are secondary diagnostics only. Use the
-deterministic CSS contract when no authenticated LinkedIn screenshot is
-available:
-
-- mobile text width: `308px`
-- desktop text width: `582px`
-- font size: `14px`
-- line height: `21px`
-- white space: `pre-wrap`
-- overflow wrap: `break-word`
-- review clamp: first 3 rendered text lines
-
-Use the rendered gates from `references/linkedin-preview-rendering.md`:
-
-- `pass`: the mobile rendered preview shows the pain, proof, or curiosity by
-  the end of the first 3 rendered lines, and either the core point is
-  understandable without opening "see more" or an intentional open loop creates
-  a specific click question with an immediate planned payoff.
-- `warn`: the mobile rendered preview creates useful curiosity but the core
-  point or click question is slightly softened by wrapping, blank-line rhythm,
-  or one missing context word. A compact fallback is required.
-- `fail`: the hook's real point appears after the first 3 mobile rendered
-  lines without an intentional open-loop plan, the visible open loop is vague,
-  the first rendered line is generic setup, blank lines consume the preview
-  before the reader sees the point, or desktop fit is the only reason it looks
-  good.
+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 rendered mobile preview clamp,
-rewrite it before selecting it unless the hook is intentionally using a
-see-more open loop. Intentional open loops must show a specific click question
-inside the mobile clamp and must define the first payoff line after the fold. A
-selected hook may carry a `warn` only when the warning is explicit and the
-validation receipt includes a compact fallback. A hook with no rendered mobile
-and desktop preview record cannot be selected.
+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
 
@@ -618,7 +629,12 @@ Draft from:
 - exact raw idea
 - selected premise card
 - selected hook
+- approved or latest `Pre-Draft Structure Brief`
 - hook research artifact
+- selected source template or no-template rationale
+- viral-post outline
+- post positioning breakdown template
+- body expression candidates and combined body plan
 - user's core memory
 - story/proof files
 - post writing rules
@@ -639,15 +655,20 @@ Every saved draft needs a validation receipt with:
 - selected premise card
 - candidate hooks considered
 - selected hook and why
-- hook reverse-engineering audit
-- hook angle matrix summary
-- see-more click audit
+- pre-draft structure brief
+- selected source template and no-copy adaptation rationale
+- post positioning breakdown
+- viral-post outline
+- hook-to-body promise map
+- body expression candidates and combined body plan
 - proof claims used and source
 - story/proof files consulted
 - gold standards consulted
 - LinkedIn preview audit
-- rendered mobile and desktop hook preview blocks
 - premise/value audit findings
+- mobile scanability audit findings
+- template-adaptation audit findings
+- abstraction-to-concrete rewrite audit findings
 - simplifier/concrete-language audit findings
 - voice audit findings
 - anti-AI audit findings
@@ -742,8 +763,14 @@ iteration:
   score: <compact score object>
 selected_premise: <premise or none>
 selected_hook: <hook>
+pre_draft_structure_brief: <compact structure summary or none>
+selected_source_template: <template name/source or none>
 validation_summary:
   premise_value: pass | needs_user_input | needs_revision
+  mobile_scanability: pass | needs_revision
+  template_adaptation: pass | needs_revision | blocked
+  abstraction_to_concrete: pass | needs_revision
+  hook_to_body_repayment: pass | needs_revision
   proof: pass | needs_user_input | blocked
   voice: pass | needs_revision
   anti_ai: pass | needs_revision

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

@@ -119,8 +119,6 @@ Show compact candidate cards. Include:
 - why it might belong in the pack
 - hook mechanism
 - hook preview budget status and measurement basis
-- rendered mobile preview block and verdict
-- rendered desktop preview block and verdict
 - content/body mechanism
 - rhythm notes
 - sentence-structure notes
@@ -196,15 +194,6 @@ Tags:
 - longest nonblank line chars:
 - blank-line visual risk:
 - source text basis:
-- render basis:
-- css contract version:
-- mobile rendered preview block:
-- desktop rendered preview block:
-- mobile rendered lines:
-- desktop rendered lines:
-- core pain/proof/curiosity visible on mobile:
-- core point visible on mobile:
-- point after mobile clamp:
 - preview budget status:
 - mobile preview fit:
 - desktop preview fit: