@sellable/mcp 0.1.258 → 0.1.260

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

@@ -61,23 +61,15 @@ Hook research files must preserve:
 - engagement totals
 - author follower counts when available, target follower band, follower-band
   fit, engagement per 1k followers, weighted engagement per 1k followers,
-  reach penalty multiplier, reach-adjusted score, baseline lift when available,
-  why the hook carries independent of creator reach, and normalization
-  confidence notes
+  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 every kept source hook and adapted hook block,
-  including literal mobile/desktop preview blocks, rendered line wraps, render
-  basis, CSS contract version, text widths, first-screen promise visibility,
-  core point visibility, and whether the point lands after the mobile clamp
-- hook reverse-engineering autopsies for kept source hooks, including source
-  mechanism, open-loop type, click question, promised payoff, specificity
-  anchor, source shape to keep, source words not to copy, and adaptation rule
-- hook angle matrix summary, including angle territories tested, top generated
-  hooks, winning territory, runner-up territories, and why the winning angle
-  beat the alternatives
+- 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
 
@@ -96,11 +88,11 @@ 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 structure brief: hook, thesis, reader, core mechanism, key
+  definitions, proof claims, mobile scan path, section outline, 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
-- selected hook reverse-engineering audit, hook angle matrix summary, and
-  see-more click audit when the selected hook intentionally hides the payoff
-  after the mobile fold
 - 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

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

@@ -11,10 +11,13 @@ Every saved draft needs a validation receipt. A draft without this receipt is no
 - `candidateHooksConsidered`
 - `selectedHook`
 - `selectedHookWhy`
-- `sourceHookReachAudit`
-- `hookReverseEngineeringAudit`
-- `hookAngleMatrix`
-- `seeMoreClickAudit`
+- `preDraftStructureBrief`
+- `selectedSourceTemplate`
+- `postPositioningBreakdown`
+- `viralPostOutline`
+- `hookToBodyPromiseMap`
+- `bodyExpressionCandidates`
+- `combinedBodyPlan`
 - `proofClaimsUsed`
 - `proofClaimSources`
 - `storyFilesConsulted`
@@ -22,6 +25,9 @@ Every saved draft needs a validation receipt. A draft without this receipt is no
 - `voiceRulesApplied`
 - `marketBeliefAudit`
 - `premiseValueAudit`
+- `mobileScanabilityAudit`
+- `templateAdaptationAudit`
+- `abstractionToConcreteRewriteAudit`
 - `linkedinPreviewAudit`
 - `simplifierConcreteLanguageAudit`
 - `antiAiAudit`
@@ -72,46 +78,20 @@ set the verdict to `revise` or `reject`.
 
 ## Candidate Set
 
-Generate many hook candidates before drafting. Do not lock onto the first draft.
-
-Minimum candidate set:
-
-- normal drafting: at least 8 angle territories and 24 hook candidates
-- hook-critical requests: at least 12 angle territories and 40 hook candidates
-- smaller set only when the user explicitly asks for fewer options
-
-An angle territory is a distinct reason the reader might care, such as hidden
-asset, tool/enemy contrast, first-person build proof, workflow reveal,
-contrarian category claim, mistake/confession, market timing, operator pain,
-specific person/company signal, before/after transformation, or question hook.
+Generate multiple hook candidates before drafting. Do not lock onto the first draft.
 
 Each candidate should include:
 
 - hook text
 - selected premise
-- angle territory
+- selected source template or no-template rationale
 - premise tension opened
 - reader value implied
 - source pattern
-- source shape kept
-- source words not copied
-- source pattern reach signals: author follower count when available, target
-  follower band, follower-band fit, engagement per 1k followers, weighted
-  engagement per 1k followers, reach-adjusted score, baseline lift, and
-  confidence
+- hook-to-body promise
+- see-more tension
+- curiosity debt
 - score
-- `renderedPreview` using `references/linkedin-preview-rendering.md`
-- literal mobile and desktop rendered preview blocks
-- mobile and desktop rendered line wraps
-- first-screen promise: pain, proof, or curiosity visible by the mobile clamp
-- `intentionalOpenLoop`
-- `specificClickQuestionVisible`
-- `seeMoreClickReason`
-- `clickQuestion`
-- `payoffAfterFold`
-- `bodyProofObligation`
-- whether the core point is visible in the mobile rendered preview
-- whether the point lands after the mobile clamp
 - char count including newlines and first-line / first-two-line preview measurements
 - physical line count, content line count, longest nonblank line, and blank-line risk
 - `previewBudgetStatus`: `pass`, `warn`, or `fail`
@@ -120,55 +100,6 @@ Each candidate should include:
 - AI-tell risk
 - why it should win or lose
 
-## Hook Reverse Engineering Audit
-
-Before a draft can be `ready`, validate that the selected hook came from a real
-source-shape analysis, not from generic brainstorming.
-
-Record:
-
-- `sourceHooksStudied`
-- `sourceHookAutopsies`
-- `selectedSourceShape`
-- `sourceShapeKept`
-- `sourceWordsNotCopied`
-- `whyItWorks`
-- `openLoopType`: `none`, `hidden_payoff`, `contradiction`, `proof_gap`,
-  `workflow_reveal`, `asset_reveal`, or `story_gap`
-- `clickQuestion`
-- `promisedPayoff`
-- `specificityAnchor`
-- `tensionOpened`
-- `proofImplied`
-- `adaptationRule`
-- `bodyPayoffObligation`
-
-The selected draft cannot be `ready` if the hook was copied verbatim from
-another creator, if the receipt only says "contrarian" or "curiosity" without
-the concrete shape, or if the body does not pay off the hook quickly.
-
-## Hook Angle Matrix Audit
-
-Before a draft can be `ready`, validate that the hook was chosen after exploring
-materially different angles.
-
-Record:
-
-- `angleTerritoriesTested`
-- `hookCandidatesGenerated`
-- `winningTerritory`
-- `runnerUpTerritories`
-- `whyWinningAngleBeatsAlternatives`
-- `whyRejectedHooksLost`
-- `mobileRenderedPreviewBlocksForTopCandidates`
-- `desktopRenderedPreviewBlocksForTopCandidates`
-- `proofNeededByWinningAngle`
-
-If the user asked to "nail the hook," "focus on hooks," or explore "a ton of
-angles," the draft cannot be `ready` unless at least 12 territories and 40 hook
-candidates were considered or the receipt explains why the user explicitly
-requested fewer.
-
 ## Finalizer Pass
 
 After the first draft:
@@ -176,12 +107,15 @@ After the first draft:
 1. remove unsupported claims
 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-render the selected hook on mobile and desktop after edits
+4. verify the body repays the selected hook's curiosity debt
+5. verify the final post follows the selected positioning sequence or explains
+   why it departed from the template
+6. tighten the hook
+7. simplify abstract phrasing
+8. replace generic language with concrete words only when supported
+9. preserve the user's actual story and point
+10. remove AI tells
+11. re-check LinkedIn preview fit after edits
 
 ## Premise Value Audit
 
@@ -199,15 +133,117 @@ Record:
 - `readerValue`: what the reader learns, sees differently, or can do
 - `proofAvailable`: source-backed proof used
 - `proofMissing`: claims intentionally avoided or requiring user input
+- `preDraftStructureBrief`: hook, thesis, reader, core mechanism, definitions,
+  proof claims, mobile scan path, section outline, and abstractions to remove
 - `premiseQualityGates`: pass/fail for `specific_scene_or_pattern`,
   `clear_reader`, `visible_tension`, `reader_value`, `credible_speaker`,
-  `proof_safety`, and `market_heat`
+  `proof_safety`, `market_heat`, and `pre_draft_structure`
 - `bodyOutline`: how the body delivers the premise before prose
+- `viralPostOutline`: the selected narrative structure, including beat jobs
+- `hookToBodyPromiseMap`: how the body repays the hook's open loop
+- `combinedBodyPlan`: which body-expression lines were kept, rewritten, or cut
 
 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.
 
+## Pre-Draft Structure Audit
+
+Before a draft can be `ready`, validate that the structure was locked before the
+body was written.
+
+Record:
+
+- `hook`: selected hook plus mobile/desktop rendered preview verdict
+- `thesis`: one sentence the post defends
+- `readerBeingTaught`: specific reader and why the post is written for them
+- `coreEquationOrMechanism`: the operating idea being taught
+- `keyDefinitions`: concrete definitions and examples for terms the reader
+  could misunderstand
+- `proofClaims`: claims, sources, and public-safety status
+- `sourceTemplateOrNoTemplateRationale`
+- `mobileScanPath`: what a skimmer understands from the hook, separators,
+  section labels, numbers, and close
+- `sectionOutline`: section order plus the job of each section
+- `bodyPromiseAfterSeeMore`: what the body immediately repays
+- `abstractionsToRemove`: abstract phrases and their concrete replacements
+- `userCorrectionsApplied`: user corrections applied to the brief before prose
+
+Save as `needs_revision` when the draft was written before the structure brief,
+when the brief does not match the final prose, when the mobile scan path is
+unclear, or when key terms are left abstract.
+
+## Mobile Scanability Audit
+
+A LinkedIn post must still teach the main idea when a reader scans it.
+
+Record:
+
+- `scanVisibleFrom`: hook, separators, numbered labels, ranges/numbers, example
+  prompts, and close
+- `readerGetsWithoutReadingEveryWord`: the specific takeaway a skimmer gets
+- `sectionSeparators`: present | absent | not_needed
+- `sectionLabels`: concrete | abstract | missing
+- `numbersOrProofVisible`: yes | no
+- `mobileLineLengthRisk`: pass | warn | fail
+- `skimVerdict`: pass | needs_revision
+
+Save as `needs_revision` when a skimmer cannot understand the thesis, hierarchy,
+or practical next action.
+
+## Abstraction-To-Concrete Rewrite Audit
+
+Record every meaningful abstraction found in the draft and the concrete
+replacement. Do not merely say "made concrete."
+
+Use this format:
+
+```text
+abstractionToConcreteRewriteAudit:
+1.
+  original:
+  issue:
+  replacement:
+  source:
+  kept_or_cut:
+```
+
+Common abstractions to flag:
+
+- vague nouns such as `signal`, `market`, `attention`, `system`, `quality`,
+  `context`, `machine`, or `workflow` when the sentence does not name the actual
+  source, action, number, or object
+- broad persona labels used as lead sources
+- "warm" without explaining what made the source warm
+- "offer" without explaining why the recipient would believe or want it
+- "learning" without naming what metric changes the next decision
+
+Do not make language concrete by inventing facts. If the concrete replacement
+requires missing proof, ask the user or save as `needs_revision`.
+
+## Template Adaptation Audit
+
+Before a draft can be `ready`, validate that source posts were converted into
+templates rather than copied.
+
+Record:
+
+- `selectedSourceTemplate`: source, template name, and why it fits
+- `positioningSequenceBorrowed`: category sequence being adapted
+- `viralPostOutlineBorrowed`: beat sequence being adapted
+- `lineShapesBorrowed`: reusable line shapes, not copied wording
+- `userStoryInputsUsed`: source-backed user facts filling the template
+- `userProofInputsUsed`: source-backed user proof filling the template
+- `forbiddenBorrowingAvoided`: source proof, jokes, personal context, status,
+  phrases, or examples not used
+- `hookToBodyRepayment`: whether the body answers the hook's curiosity debt
+- `bodyExpressionCandidatesReviewed`: which variants were tested and what won
+- `copyingRisk`: pass | needs_revision | blocked
+
+Save as `needs_revision` when the draft copies outside wording, borrows outside
+proof, keeps a source template's status without equivalent user authority, or
+uses a hook whose promised body payoff is not delivered.
+
 ## Market Belief Audit
 
 Before a draft can be `ready`, validate that it is not merely an internally
@@ -230,104 +266,24 @@ 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`.
 
-## Source Hook Reach Audit
-
-Before a draft can be `ready`, validate that the selected source hook pattern
-was chosen for a reach-normalized reason, not raw audience size.
-
-Record:
-
-- `targetFollowerBand`
-- `authorFollowerCount` for each source pattern when available
-- `followerBandFit`: `in_target_band`, `below_target_band`,
-  `above_target_band`, or `unknown`
-- `engagementPer1kFollowers`
-- `weightedEngagementPer1kFollowers`
-- `reachAdjustedScore`
-- `reachPenaltyMultiplier`
-- `creatorBaselineMedianEngagement` or `creator_baseline_unavailable`
-- `baselineLift` or `creator_baseline_unavailable`
-- `bigAccountPenaltyApplied`
-- `whyTheHookCarries`
-- `followerCountUnavailableSources`
-- `whyThisHookIsAReachAdjustedSignal`
-
-If the user asked for a follower range and the selected source pattern is from a
-large account above the target range, the receipt must explain why it survived
-the celebrity reach penalty. Use large-account hooks as secondary pattern
-evidence unless they clearly overperform the creator's baseline or the hook
-itself carries after reach is controlled. A draft cannot be `ready` when the
-selected hook is justified only by raw total engagement or follower count.
-
 ## LinkedIn Preview Audit
 
-Audit the selected hook and top candidates against
-`references/linkedin-preview-rendering.md`. LinkedIn does not publish exact
-"see more" cutoff rules, and rendering varies by device, app version, font,
-media, and line break. This audit is a mobile-first rendered-preview safety
-gate, not a claim about an official LinkedIn limit.
+Audit the selected hook and top candidates against conservative LinkedIn
+preview budgets. LinkedIn does not publish exact "see more" cutoff rules, and
+rendering varies by device, app version, font, media, and line break. This audit
+is a mobile-first safety gate, not a claim about an official LinkedIn limit.
 
-Character budgets are secondary diagnostics. They cannot be the only evidence
-that a hook works. Every selected hook must include literal rendered mobile and
-desktop preview blocks.
-
-Default deterministic renderer when no authenticated LinkedIn screenshot is
-available:
-
-```text
-cssContractVersion: linkedin-preview-rendering/v1
-font size: 14px
-line height: 21px
-white space: pre-wrap
-overflow wrap: break-word
-mobile text width: 308px
-desktop text width: 582px
-review clamp: first 3 rendered text lines
-```
+Use:
 
-Use 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 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.
+- `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 desktop fit, but never let
 desktop fit compensate for a mobile `fail`.
 
 Record:
 
-- `renderedPreview`
-- `renderBasis`: `linkedin_css_contract`, `authenticated_linkedin_screenshot`,
-  or `manual_user_source`
-- `cssContractVersion`
-- `mobileRenderedPreviewBlock`
-- `desktopRenderedPreviewBlock`
-- `mobileRenderedLines`
-- `desktopRenderedLines`
-- `mobileTextWidthPx`
-- `desktopTextWidthPx`
-- `mobileRenderedLineCount`
-- `desktopRenderedLineCount`
-- `corePainProofOrCuriosityVisibleMobile`
-- `corePainProofOrCuriosityVisibleDesktop`
-- `corePointVisibleMobile`
-- `corePointVisibleDesktop`
-- `intentionalOpenLoop`
-- `specificClickQuestionVisible`
-- `payoffPlannedImmediatelyAfterClamp`
-- `seeMoreClickReason`
-- `clickQuestion`
-- `payoffAfterFold`
-- `pointAfterMobileClamp`
 - `charCount`
 - `charCountIncludingNewlines`
 - `firstLineChars`
@@ -346,37 +302,10 @@ Record:
 - `rewriteIfTruncated`
 - `compactFallback` when `previewBudgetStatus` is `warn`
 
-If the hook only works after the rendered mobile clamp, rewrite it. A draft
-cannot be `ready` with `previewBudgetStatus: fail`,
-`mobilePreviewFit: fail`, missing `renderedPreview`,
-`corePainProofOrCuriosityVisibleMobile: false`,
-`corePointVisibleMobile: false` unless the receipt has
-`intentionalOpenLoop: true`, `specificClickQuestionVisible: true`, and
-`payoffPlannedImmediatelyAfterClamp: true`, or `pointAfterMobileClamp: true`
-unless the post is intentionally hiding the payoff for a specific see-more
-click. A draft may be `ready` with `previewBudgetStatus: warn` only when the
-warning is explicit, usually because the user prefers blank-line rhythm, and
-the receipt includes a compact fallback.
-
-## See-More Click Audit
-
-When the selected hook intentionally hides the payoff after the mobile fold,
-record:
-
-- `intentionalOpenLoop: true`
-- `openLoopType`
-- `visibleBeforeFold`
-- `clickQuestion`
-- `payoffAfterFold`
-- `firstPayoffLine`
-- `payoffArrivesWithinFirstBodySection`
-- `readerValueAfterClick`
-- `baitRisk`
-- `baitRiskMitigation`
-
-Open loops are allowed only when the body actually delivers the promised payoff.
-If the hook withholds the answer but the body switches topics, save as
-`needs_revision`.
+If the hook only works after likely truncation, rewrite it. A draft cannot be
+`ready` with `previewBudgetStatus: fail`. A draft may be `ready` with
+`previewBudgetStatus: warn` only when the warning is explicit, usually because
+the user prefers blank-line rhythm, and the receipt includes a compact fallback.
 
 ## Simplifier / Concrete-Language Audit
 
@@ -449,7 +378,9 @@ If the necessary proof or story is missing, ask the user or return blocked/retry
 
 Use:
 
-- `ready` only when proof, voice, anti-AI, and concrete-language gates pass
+- `ready` only when proof, voice, anti-AI, concrete-language, pre-draft
+  structure, mobile-scanability, hook-to-body repayment, and
+  template-adaptation gates pass
 - `needs_revision` when a draft exists but a gate failed
 - `blocked` when required context is missing
 - `retry-needed` when a tool/package/search failure blocked the pipeline