@sellable/mcp 0.1.259 → 0.1.261

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

@@ -1,6 +1,19 @@
-# Hook Research Playbook
+# Hook Research Playbook V2
 
-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.
+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 the weighted best posts, understand why they made
+readers click "see more," decompose each post into a reusable narrative and
+positioning template, and then adapt those templates to the user's real story
+without copying source wording.
+
+V2 research has four outputs:
+
+1. weighted source winners: the best recent posts to learn from
+2. hook autopsies: exact preview measurements, open loops, and tension created
+3. viral-post outlines: the narrative structure of each source post
+4. post positioning breakdown templates: line-level positioning and narrative
+   technique maps that can be adapted into the user's draft
 
 ## Search Inputs
 
@@ -31,9 +44,13 @@ Worker owns:
 - 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
+- hook opening measurement and "see more" tension autopsy
 - exact phrase-pattern extraction
+- post positioning breakdown by line and phrase
+- viral-post outline extraction
+- line-to-template conversion
 - body-structure extraction
+- body-expression input extraction for the later draft lab
 - rejected-example notes
 - track-person and gold-standard recommendations
 
@@ -56,9 +73,14 @@ Research packet:
 - premise inputs: max 8
 - full adapted hook blocks: max 12
 - exact phrase patterns: max 20
+- post positioning breakdowns: max 8
+- viral-post outlines: max 8
+- reusable post templates: max 8
 - body patterns: max 8
 - source URLs and author profile URLs
 - preview measurements
+- hook-to-body promise maps
+- body expression inputs
 - confidence gaps
 - save recommendations
 ```
@@ -118,6 +140,40 @@ 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
 
+## Keeper Threshold
+
+Only promote a source post into template analysis when it clears a practical
+keeper threshold. A post does not have to be perfect, but it must be useful
+enough that copying its structure would teach the draft something.
+
+Keeper fields:
+
+```text
+keeper_score:
+  topic_fit: 1-10
+  hook_preview_strength: 1-10
+  see_more_tension: 1-10
+  body_payoff_strength: 1-10 | full_text_unavailable
+  positioning_density: 1-10
+  creator_repeat_success: 1-10 | unknown
+  engagement_quality: 1-10
+  replicability_for_user: 1-10
+  voice_fit: 1-10
+  penalties:
+    lead_magnet:
+    engagement_bait:
+    celebrity_or_account_size_only:
+    borrowed_proof:
+    body_unavailable:
+  verdict: keeper | maybe | reject
+  why:
+```
+
+Use `keeper` only when the post has enough hook and body visibility to create a
+template. Use `maybe` when the hook is useful but the body is unavailable or the
+post depends too much on the source creator's status. Use `reject` when the post
+is mostly reach, giveaway mechanics, copied trend language, or poor fit.
+
 ## Market Belief Map
 
 Before selecting a hook or writing a draft, synthesize a market belief map from
@@ -228,6 +284,13 @@ For each source, record:
 - `desktopPreviewBudget`: `pass`, `warn`, or `fail`
 - `blankLineVisualRisk`
 - `corePointBeforeLikelyTruncation`
+- `seeMoreTension`: what question, contradiction, missing proof, or unfinished
+  story makes the reader want the next line
+- `curiosityDebt`: what the hook promises the body must repay
+- `firstScreenPayoffRisk`: whether the hook creates curiosity without enough
+  substance to repay it
+- `readerClickReason`: the specific reason a target reader would click "see
+  more," not a generic label like "curiosity"
 
 If only a search preview is available, do not pretend the opening is complete.
 Record `sourceTextBasis: search_preview` and lower confidence when the hook
@@ -250,6 +313,9 @@ For each shortlisted source post, record:
 - visible hook text or preview
 - opening preview measurement fields from the section above
 - hook mechanism
+- hook promise: what the body is now obligated to prove, reveal, or resolve
+- see-more tension: what makes the reader want the body
+- curiosity debt: what must be repaid quickly after the fold
 - exact hook language patterns: reusable words, phrase shapes, contrast forms,
   sentence shapes, and transition moves
 - story mechanism when the post is a story
@@ -304,6 +370,161 @@ 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.
 
+## Post Positioning Categories
+
+For post research, use the familiar copy-breakdown categories, but apply them to
+public narrative posts instead of landing pages or outbound emails. Assign one
+primary category to every meaningful line or phrase, and add a secondary
+category only when the same phrase clearly does two jobs.
+
+Core categories:
+
+- `Context`: setup, scene, timing, environment, or "why this is being said now"
+- `Persona`: who the post is for or who appears in the story
+- `Problem`: pain, friction, failure mode, risk, or gap
+- `Alternative`: the old behavior, competitor, default advice, or common path
+- `Belief`: the assumption, status game, worldview, or market consensus being
+  entered
+- `Tension`: contradiction, tradeoff, discomfort, open loop, or argument bait
+- `Proof`: numbers, named events, observed outcomes, screenshots, customers,
+  repeated experience, or hard-won authority
+- `Mechanism`: the causal explanation for why the thing works or fails
+- `Capability`: the new action the reader, product, or system can perform
+- `Benefit`: positive outcome, leverage, speed, money, clarity, trust, or relief
+- `Feature`: concrete product/workflow object that powers the mechanism
+- `Identity`: founder confession, status shift, taste, vulnerability, or role
+- `Offer`: CTA, invitation, ask, or proposed next step
+- `Bridge`: transition line that moves the reader from hook to proof, from
+  proof to lesson, or from lesson to product
+
+Do not hide useful detail behind a category label. The category says what the
+line does; the technique notes must explain how the exact words do it.
+
+## Post Positioning Breakdown
+
+For every keeper post with enough text, create a line-level breakdown. This is
+the post version of the admin copy-breakdown view: every line becomes a
+positioning and narrative unit that can be templated.
+
+Use this format:
+
+```text
+Post positioning breakdown:
+source: <author + URL>
+text_basis: full_text | search_preview | manual_user_source
+overall_positioning_sequence:
+  <Category> -> <Category> -> <Category> -> ...
+
+line_map:
+1.
+  source_line:
+  char_count:
+  line_role:
+  primary_category:
+  secondary_category:
+  narrative_technique:
+  tension_created:
+  reader_question_opened:
+  body_promise:
+  proof_or_story_dependency:
+  why_this_exact_wording_works:
+  reusable_template_line:
+  adaptation_guard:
+  sellable_version_candidate:
+```
+
+Break long lines into phrase-level segments when one line contains multiple
+jobs. Preserve the original source line in the research artifact, but never
+copy it into the draft unless it is the user's own approved post.
+
+## Viral-Post Outline
+
+After the line-level breakdown, convert each keeper into a viral-post outline.
+The outline is the narrative skeleton beneath the exact words.
+
+Use this format:
+
+```text
+Viral-post outline:
+source: <author + URL>
+outline_name:
+best_for:
+not_good_for:
+hook_job:
+see_more_trigger:
+body_payoff:
+close_job:
+
+beats:
+1.
+  beat_name:
+  source_lines:
+  narrative_job:
+  positioning_categories:
+  reader_state_before:
+  reader_state_after:
+  tension_or_open_loop:
+  proof_needed:
+  reusable_instruction:
+```
+
+Examples of outline names:
+
+- proof-first roadmap
+- confession to operating rule
+- enemy naming to mechanism
+- teardown to replacement behavior
+- status reversal to concrete lesson
+- personal scene to category thesis
+
+## Line-To-Template Conversion
+
+Convert the source outline into reusable templates that preserve the narrative
+job, not the source creator's language.
+
+Use this format:
+
+```text
+Post template:
+source:
+template_name:
+positioning_sequence:
+  <Category> -> <Category> -> <Category> -> ...
+required_story_inputs:
+  - <input the user must actually have>
+required_proof_inputs:
+  - <proof needed to make the template credible>
+forbidden_borrowing:
+  - <source proof, joke, phrase, or status that cannot transfer>
+
+template_lines:
+1.
+  job:
+  line_shape:
+  allowed_moves:
+  disallowed_moves:
+  example_user_adaptation:
+```
+
+The template should be specific enough that another agent can draft from it
+without re-reading the source post. If the template only says "use a contrarian
+hook" or "tell a story," it failed.
+
+## Hook-To-Body Promise Map
+
+Every keeper hook must include a map from the preview to the body. This prevents
+the later draft from using a strong opening that the body does not repay.
+
+Record:
+
+- hook promise: what the hook says or implies the reader will get
+- curiosity debt: what the reader is waiting to learn after clicking
+- first body beat: the first line or paragraph that repays the debt
+- payoff speed: immediate | delayed | too slow
+- tension carried forward: how the body keeps the hook's question alive
+- body betrayal risk: where the body changes topic, gets generic, or overclaims
+- adaptation instruction: how the user's draft must repay the same kind of debt
+
 ## Body Structure Extraction
 
 For each keeper with full text available, extract the body in this format:
@@ -315,6 +536,9 @@ Body pattern:
 Source:
 <author + URL>
 
+Positioning sequence:
+<Context -> Proof -> Problem -> Mechanism -> Benefit ...>
+
 Sequence:
 1. <paragraph/job 1>
 2. <paragraph/job 2>
@@ -328,6 +552,13 @@ Exact language moves:
 Adapted body move:
 <how this would show up in the user's post>
 
+Body expression inputs:
+- hook promise to repay:
+- narrative beats to preserve:
+- line shapes worth adapting:
+- proof/story slots required:
+- candidate Sellable body lines:
+
 Replicability:
 high | medium | low
 ```
@@ -349,6 +580,38 @@ For story posts, do not reduce the source to "strong first line" or a generic le
 
 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`.
 
+## Template Selection For Drafting
+
+After all keeper posts are broken down, select 1-3 source templates for the
+user's idea. Selection is based on fit, not raw engagement.
+
+For each selected template, record:
+
+```text
+Selected source template:
+template_name:
+source:
+why_this_template_fits_the_user_story:
+why_it_might_fail:
+positioning_sequence_to_borrow:
+hook_move_to_borrow:
+body_outline_to_borrow:
+line_shapes_to_test:
+required_user_inputs:
+required_proof:
+do_not_copy:
+draft_lab_instruction:
+```
+
+The draft lab instruction should tell the later premise/drafting stage exactly
+how to use the template, for example:
+
+```text
+Use the source's proof-first roadmap sequence, but replace its revenue proof
+with Christian's verified campaign-source ladder. Keep the hook's "unexpected
+best source" tension. Do not borrow the source's dinner/community proof.
+```
+
 ## Blocked States
 
 Local idea capture can still succeed when research fails.
@@ -367,8 +630,9 @@ 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.
+phrase patterns, post positioning breakdowns, viral-post outlines, reusable
+post templates, hook-to-body promise maps, 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:

package/skills/create-post/references/linkedin-preview-rendering.md

@@ -0,0 +1,176 @@
+# LinkedIn Preview Rendering
+
+This asset defines the required rendered-preview contract for create-post hook
+research, hook candidate generation, gold-standard decomposition, and draft
+validation.
+
+Character budgets are only diagnostics. They are not the preview gate. A hook is
+not studied, selected, or ready until it has been rendered through this contract
+or through a stricter authenticated LinkedIn screenshot.
+
+## Rendering Basis
+
+LinkedIn does not publish exact feed truncation rules, and rendering can vary by
+surface, app version, device, media attachment, and account state. Use this
+deterministic renderer as the MCP review gate for unpublished drafts.
+
+When an authenticated LinkedIn feed/composer/browser screenshot is available,
+that screenshot is the strongest evidence. Still record the fields below so
+future agents can compare candidates without redoing the visual inspection.
+
+Observed public LinkedIn post text style for feed-style post pages:
+
+```text
+selector basis: p.attributed-text-segment-list__content
+font family: -apple-system, system-ui, "Segoe UI", Roboto, "Helvetica Neue",
+  "Fira Sans", Ubuntu, "Oxygen Sans", Cantarell, "Droid Sans",
+  "Lucida Grande", Helvetica, Arial, sans-serif
+font size: 14px
+line height: 21px
+font weight: 400
+letter spacing: normal
+white space: pre-wrap
+overflow wrap: break-word
+text color: rgba(0, 0, 0, 0.9)
+mobile text width: 308px
+desktop text width: 582px
+review clamp: first 3 rendered text lines
+```
+
+The `review clamp` is not an official LinkedIn rule. It is the conservative
+apples-to-apples region create-post must use when comparing hooks. Do not let a
+desktop pass rescue a mobile fail.
+
+## Required Rendering Record
+
+Every shortlisted source hook, adapted hook block, generated hook candidate, and
+selected hook must include a `renderedPreview` record:
+
+```text
+renderedPreview:
+  basis: linkedin_css_contract | authenticated_linkedin_screenshot | manual_user_source
+  cssContractVersion: linkedin-preview-rendering/v1
+  mobile:
+    textWidthPx: 308
+    fontSizePx: 14
+    lineHeightPx: 21
+    visibleTextBlock: <literal first rendered review-clamp block>
+    renderedLines:
+      - <line 1 exactly as wrapped>
+      - <line 2 exactly as wrapped>
+      - <line 3 exactly as wrapped>
+    lineCountBeforeClamp: <number>
+    blankLinesBeforeClamp: <number>
+    corePainProofOrCuriosityVisible: true | false
+    corePointVisible: true | false
+    intentionalOpenLoop: true | false
+    specificClickQuestionVisible: true | false
+    payoffPlannedImmediatelyAfterClamp: true | false
+    seeMoreClickReason: <why a reader would click see more>
+    seeMoreRisk: pass | warn | fail
+    screenshotPath: <optional local path>
+  desktop:
+    textWidthPx: 582
+    fontSizePx: 14
+    lineHeightPx: 21
+    visibleTextBlock: <literal first rendered review-clamp block>
+    renderedLines:
+      - <line 1 exactly as wrapped>
+      - <line 2 exactly as wrapped>
+      - <line 3 exactly as wrapped>
+    lineCountBeforeClamp: <number>
+    blankLinesBeforeClamp: <number>
+    corePainProofOrCuriosityVisible: true | false
+    corePointVisible: true | false
+    seeMoreRisk: pass | warn | fail
+    screenshotPath: <optional local path>
+  diagnostics:
+    charCount: <number>
+    charCountIncludingNewlines: <number>
+    firstLineChars: <number>
+    firstTwoPhysicalLinesChars: <number>
+    longestNonblankLineChars: <number>
+    blankLineVisualRisk: none | low | medium | high
+    pointAfterMobileClamp: true | false
+    openLoopType: none | hidden_payoff | contradiction | proof_gap | workflow_reveal | asset_reveal | story_gap
+    rewriteIfTruncated: <short fallback>
+```
+
+If a host cannot produce screenshots, it must still produce the literal wrapped
+line blocks using the CSS contract. If it cannot produce either screenshots or
+literal line wraps, return `blocked` or `needs_revision`; do not claim the hook
+passed preview validation from character counts alone.
+
+## Study Rules
+
+For source-post research:
+
+- Render the exact visible opening from full text when full text is available.
+- If only a search preview is available, render only the preview text and set
+  `basis: manual_user_source` or record `sourceTextBasis: search_preview`.
+- Lower confidence when the search preview is cut off or the body is
+  unavailable.
+- Extract hook lessons from the rendered first-screen experience, not from the
+  full post in isolation.
+
+For generated hooks:
+
+- Generate the hook from the selected premise first.
+- Render the hook for mobile and desktop before scoring it.
+- Score the rendered first-screen click reason before scoring cleverness.
+- If the goal is see-more clicks, the hook may intentionally hide the payoff
+  after the mobile clamp, but the visible block must create a specific question
+  the target reader wants answered.
+- Rewrite any candidate whose real point appears after the mobile clamp unless
+  that point is the planned payoff for an intentional open loop.
+
+## Pass, Warn, Fail
+
+Use these rendered gates:
+
+- `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,
+  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.
+
+A draft cannot be `ready` when the selected hook has:
+
+- no `renderedPreview`
+- `mobile.seeMoreRisk: fail`
+- `mobile.corePainProofOrCuriosityVisible: false`
+- `mobile.corePointVisible: false` unless `mobile.intentionalOpenLoop: true`,
+  `mobile.specificClickQuestionVisible: true`, and
+  `mobile.payoffPlannedImmediatelyAfterClamp: true`
+- `pointAfterMobileClamp: true` unless the point after the clamp is the
+  intentional payoff for a specific open loop
+
+## Report Format
+
+Research reports must show rendered preview blocks for the best examples and
+recommended draft directions:
+
+```text
+Rendered preview:
+mobile:
+<line 1>
+<line 2>
+<line 3>
+
+desktop:
+<line 1>
+<line 2>
+<line 3>
+
+verdict: pass | warn | fail
+why: <what is visible before the fold>
+```
+
+Do not say "it fits on mobile" without showing what the mobile reader actually
+sees.

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

@@ -59,10 +59,17 @@ Hook research files must preserve:
 - source post URLs
 - author/profile URLs
 - engagement totals
+- author follower counts when available, target follower band, follower-band
+  fit, engagement per 1k followers, weighted engagement per 1k followers,
+  reach-adjusted score, and normalization confidence notes when reach
+  normalization was used
 - 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
+- rendered preview records for kept source hooks and adapted hook blocks,
+  including literal mobile/desktop preview blocks and whether the first-screen
+  promise is visible
 - extracted hook patterns
 - selected hook basis
 
@@ -81,8 +88,18 @@ Draft files must preserve:
   - 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
+- pre-draft narrative outline: hierarchical `I.`, `A.`, `i.` outline covering
+  hook debt, thesis, reader, core mechanism, definitions, proof claims,
+  working body patterns adapted, narrative beats, mobile scan path, body
+  promise, concrete examples, abstractions to remove, and draft risks
 - validation receipt, including LinkedIn preview pass/warn/fail status and
   compact fallback when the selected hook carries a warning
+- visible flow trace when the user asked for whole-flow, debug, or step-by-step
+  mode, including checkpoint statuses, quality break, downstream effect, and
+  whether the trace was shown before saving
+- rendered mobile and desktop preview blocks for the selected hook; drafts
+  cannot be ready when this rendered-preview audit is missing or fails mobile
+  visibility
 - status: `draft`, `ready`, `needs_revision`, `published`, or `archived`
 
 Multiple drafts for the same idea are expected. Keep the `ideaId` stable and