@sellable/mcp 0.1.269 → 0.1.272

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

@@ -0,0 +1,221 @@
+# 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 its visible mobile and desktop blocks come
+from `mcp__sellable__calculate_linkedin_hook_preview` or from a stricter
+authenticated LinkedIn screenshot.
+
+Do not let the LLM imagine wrapping. The normal path is a function call that
+returns rendered mobile and desktop lines. HTML and PNG outputs from
+`mcp__sellable__render_linkedin_post_preview` are optional visual QA artifacts,
+not the primary interface.
+
+## 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 function as the MCP review gate for unpublished drafts.
+
+Simple operating policy: judge the hook by the first 3 rendered lines. Use ~140
+characters on mobile and ~210 characters on desktop as guardrails only. If the
+3-line preview and the character guardrail disagree, trust the rendered lines.
+
+Call:
+
+```json
+mcp__sellable__calculate_linkedin_hook_preview({
+  "postText": "<full post text or candidate hook block>",
+  "sourceLabel": "<draft id, hook id, or source label>",
+  "measurementMode": "browser"
+})
+```
+
+When local Chrome is available, browser measurement is the preferred functional
+basis because it asks the browser layout engine to wrap the text under the
+contract. When Chrome is unavailable, the tool falls back to the deterministic
+width model and must mark that basis.
+
+Treat "see more" as a rendered-line problem first and a character-count problem
+second. Observed LinkedIn screenshots show the current desktop feed behaving
+like a first-3-rendered-lines clamp: a first line, a blank line, and a third
+line can be all that appears before `... more`.
+
+- review gate: first 3 rendered visual lines
+- mobile feed: tighter because the text column is narrower
+- desktop feed: more characters can fit per line, but still review line count
+- posts with media may show fewer text lines before truncation
+- blank lines and intentional separators consume visible preview lines
+- device width, font scaling, app version, browser, and profile/page context can
+  move the cutoff
+
+Because of that variation, never say a hook is guaranteed to render before
+"see more." Say `pass`, `warn`, or `fail` under the rendered-preview contract,
+and show the visible mobile and desktop blocks.
+
+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_rendering_rule_function | authenticated_linkedin_screenshot | manual_user_source
+  cssContractVersion: linkedin-preview-rendering/v2
+  mobile:
+    textWidthPx: 308
+    fontSizePx: 14
+    lineHeightPx: 21
+    clampLines: 3
+    charGuardrail: 140
+    measurementBasis: local_chrome_browser_layout | estimated_width_model
+    visibleTextBlock: <literal first 3 rendered lines>
+    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
+  desktop:
+    textWidthPx: 582
+    fontSizePx: 14
+    lineHeightPx: 21
+    clampLines: 3
+    charGuardrail: 210
+    measurementBasis: local_chrome_browser_layout | estimated_width_model
+    visibleTextBlock: <literal first 3 rendered lines>
+    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
+  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 literal wrapped line blocks from
+`calculate_linkedin_hook_preview`, 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

@@ -50,19 +50,41 @@ Idea files must preserve:
 - `updatedAt`
 - exact raw source between raw-source markers
 - optional distilled brief that does not add new claims
+- transcript worldview packet when create-post has mined relevant
+  transcript/content-memory material for this idea
 
 Hook research files must preserve:
 
 - source idea ID
+- transcript/content-memory match status and transcript worldview packet
 - keywords searched
 - filters used
 - 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
+- audience tension snapshot and selected angle
+- 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
+- thought leader voice variants from the configured active influencer list or
+  supplied named subset, including worker status, profile URL/handle, recent
+  posts sampled, inferred voice model, representative-length role-played post
+  variant, source URLs sampled, steal/drop notes, factual risk notes,
+  `workerExecutionMode`, expected active influencer count, actual variant count,
+  missing variants, weak variants, and background worker IDs or labels when
+  available
+- source-message outlines for keeper posts, preserving source paragraph order
+  and branching each paragraph, line, or phrase into high-level goal, reader
+  effect, reusable move, and adaptation guard without reproducing the full
+  outside source post
 - extracted hook patterns
 - selected hook basis
 
@@ -70,6 +92,8 @@ Draft files must preserve:
 
 - source idea ID
 - hook research ID
+- transcript worldview packet used to build the premise, worldview, and hot
+  take
 - versioned draft ID, normally ending in `_v1`, `_v2`, `_v3`, etc.
 - iteration metadata when there is a prior or baseline draft:
   - `version`
@@ -81,8 +105,25 @@ 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
+- source-message outline for any outside post being adapted, when the draft's
+  body shape was learned from a specific source post
+- thought leader voice variant lab by default, including voice models, variants
+  considered, selected synthesis ingredients, final Christian/Sellable voice,
+  style-simulation risk, active configured influencer list, expected-vs-actual
+  variant counts, `workerExecutionMode`, background worker IDs or labels, and
+  skipped/opt-out reason when omitted
+- 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