@sellable/mcp 0.1.293 → 0.1.294

package/dist/tools/engage-discovery.d.ts

@@ -9,6 +9,14 @@ type ReachSignals = {
     reachAdjustedScore: number;
     confidence: "high" | "medium" | "low";
 };
+type EngagementPostMedia = {
+    imageUrls: string[];
+    videoThumbnailUrl?: string;
+    videoUrl?: string;
+    articleImageUrl?: string;
+    articleUrl?: string;
+    mediaTypes: string[];
+};
 export type EngagementPost = {
     postId: string;
     url: string;
@@ -27,6 +35,7 @@ export type EngagementPost = {
         total: number;
     };
     reachSignals?: ReachSignals;
+    media?: EngagementPostMedia;
     contentPreview: string;
 };
 export type SearchEngagementPostsInput = {

package/dist/tools/engage-discovery.js

@@ -2,7 +2,7 @@ import { getApi } from "../api.js";
 export const engageDiscoveryToolDefinitions = [
     {
         name: "search_engagement_posts",
-        description: "Search for high-signal LinkedIn posts by keyword for engagement/comment drafting. Designed for the engage skill (no campaignOfferId required). Filters by recency and engagement, and can exclude already-engaged URLs.",
+        description: "Search for high-signal LinkedIn posts by keyword for engagement/comment drafting. Designed for the engage skill (no campaignOfferId required). Filters by recency and engagement, can exclude already-engaged URLs, and returns source media hints when the scraper provides images, video covers, or article images.",
         inputSchema: {
             type: "object",
             properties: {
@@ -74,6 +74,50 @@ function safeNumber(value) {
 function round3(value) {
     return Number(value.toFixed(3));
 }
+function normalizeMedia(raw) {
+    if (!raw || typeof raw !== "object")
+        return undefined;
+    const imageUrls = Array.isArray(raw.imageUrls)
+        ? raw.imageUrls
+            .map((url) => (typeof url === "string" ? url.trim() : ""))
+            .filter(Boolean)
+        : [];
+    const videoThumbnailUrl = typeof raw.videoThumbnailUrl === "string" && raw.videoThumbnailUrl.trim()
+        ? raw.videoThumbnailUrl.trim()
+        : undefined;
+    const videoUrl = typeof raw.videoUrl === "string" && raw.videoUrl.trim()
+        ? raw.videoUrl.trim()
+        : undefined;
+    const articleImageUrl = typeof raw.articleImageUrl === "string" && raw.articleImageUrl.trim()
+        ? raw.articleImageUrl.trim()
+        : undefined;
+    const articleUrl = typeof raw.articleUrl === "string" && raw.articleUrl.trim()
+        ? raw.articleUrl.trim()
+        : undefined;
+    const mediaTypes = Array.from(new Set([
+        ...(Array.isArray(raw.mediaTypes)
+            ? raw.mediaTypes.map((type) => typeof type === "string" ? type.trim() : "")
+            : []),
+        imageUrls.length > 0 ? "image" : "",
+        videoThumbnailUrl || videoUrl ? "video" : "",
+        articleImageUrl || articleUrl ? "article" : "",
+    ].filter(Boolean)));
+    if (imageUrls.length === 0 &&
+        !videoThumbnailUrl &&
+        !videoUrl &&
+        !articleImageUrl &&
+        !articleUrl) {
+        return undefined;
+    }
+    return {
+        imageUrls,
+        ...(videoThumbnailUrl ? { videoThumbnailUrl } : {}),
+        ...(videoUrl ? { videoUrl } : {}),
+        ...(articleImageUrl ? { articleImageUrl } : {}),
+        ...(articleUrl ? { articleUrl } : {}),
+        mediaTypes,
+    };
+}
 function parseFollowerCount(author) {
     const direct = safeNumber(author?.followerCount);
     if (direct > 0)
@@ -218,6 +262,7 @@ export async function searchEngagementPosts(input) {
             targetFollowerMin,
             targetFollowerMax,
         });
+        const media = normalizeMedia(p?.media);
         kept.push({
             postId: String(p?.id || ""),
             url,
@@ -233,6 +278,7 @@ export async function searchEngagementPosts(input) {
             },
             engagement: { likes, comments, shares, total },
             ...(reachSignals ? { reachSignals } : {}),
+            ...(media ? { media } : {}),
             contentPreview: previewText(String(p?.content || ""), 220),
         });
     }

package/dist/tools/leads.d.ts

@@ -5,6 +5,14 @@ type SignalPostForImportSelection = {
     likes: number;
     comments: number;
 };
+type SignalPostMedia = {
+    imageUrls: string[];
+    videoThumbnailUrl?: string;
+    videoUrl?: string;
+    articleImageUrl?: string;
+    articleUrl?: string;
+    mediaTypes: string[];
+};
 export declare function selectSignalPostsForImport<T extends SignalPostForImportSelection>(posts: T[], options: {
     targetEngagerCount?: number;
     maxPostsToScrape?: number;
@@ -4406,6 +4414,7 @@ export declare function searchSignals(input: SignalSearchInput): Promise<{
     selectionTarget: number;
     recommendedPostIds: string[];
     topPosts: {
+        media?: SignalPostMedia | undefined;
         id: string;
         url: string | undefined;
         matchedKeyword: string | null;

package/dist/tools/leads.js

@@ -3,8 +3,8 @@ import { dirname, join, resolve } from "path";
 import { getApi, SellableApiError } from "../api.js";
 import { resolveSkillsDir } from "../skills.js";
 import { resolveWorkspaceRoot } from "../utils/workspace-root.js";
-import { buildCsvDomainPreview, matchesConfirmationToken, parseConfirmationToken, projectCsvCarryRows, } from "./csv-domains.js";
 import { listDncEntries, loadCsvDncEntries, } from "./csv-dnc.js";
+import { buildCsvDomainPreview, matchesConfirmationToken, parseConfirmationToken, projectCsvCarryRows, } from "./csv-domains.js";
 import { buildCsvLinkedinPreview, matchesLinkedinConfirmationToken, parseLinkedinConfirmationToken, uploadCsvLinkedinFile, } from "./csv-linkedin.js";
 import { assertInteractionApproval } from "./interaction-mode.js";
 import { assertProviderPromptLoaded, markProviderPromptLoaded, } from "./provider-preflight.js";
@@ -727,6 +727,52 @@ function truncate(text, max = 220) {
         return clean;
     return `${clean.slice(0, max - 1)}...`;
 }
+function normalizeSignalPostMedia(raw) {
+    if (!raw || typeof raw !== "object")
+        return undefined;
+    const media = raw;
+    const imageUrls = Array.isArray(media.imageUrls)
+        ? media.imageUrls
+            .map((url) => (typeof url === "string" ? url.trim() : ""))
+            .filter(Boolean)
+        : [];
+    const videoThumbnailUrl = typeof media.videoThumbnailUrl === "string" &&
+        media.videoThumbnailUrl.trim()
+        ? media.videoThumbnailUrl.trim()
+        : undefined;
+    const videoUrl = typeof media.videoUrl === "string" && media.videoUrl.trim()
+        ? media.videoUrl.trim()
+        : undefined;
+    const articleImageUrl = typeof media.articleImageUrl === "string" && media.articleImageUrl.trim()
+        ? media.articleImageUrl.trim()
+        : undefined;
+    const articleUrl = typeof media.articleUrl === "string" && media.articleUrl.trim()
+        ? media.articleUrl.trim()
+        : undefined;
+    const mediaTypes = Array.from(new Set([
+        ...(Array.isArray(media.mediaTypes)
+            ? media.mediaTypes.map((type) => typeof type === "string" ? type.trim() : "")
+            : []),
+        imageUrls.length > 0 ? "image" : "",
+        videoThumbnailUrl || videoUrl ? "video" : "",
+        articleImageUrl || articleUrl ? "article" : "",
+    ].filter(Boolean)));
+    if (imageUrls.length === 0 &&
+        !videoThumbnailUrl &&
+        !videoUrl &&
+        !articleImageUrl &&
+        !articleUrl) {
+        return undefined;
+    }
+    return {
+        imageUrls,
+        ...(videoThumbnailUrl ? { videoThumbnailUrl } : {}),
+        ...(videoUrl ? { videoUrl } : {}),
+        ...(articleImageUrl ? { articleImageUrl } : {}),
+        ...(articleUrl ? { articleUrl } : {}),
+        mediaTypes,
+    };
+}
 function normalizePostUrl(url) {
     if (!url)
         return null;
@@ -764,6 +810,7 @@ function summarizeSignalPost(post) {
     const likes = post.engagement?.likes ?? 0;
     const comments = post.engagement?.comments ?? 0;
     const shares = post.engagement?.shares ?? 0;
+    const media = normalizeSignalPostMedia(post.media);
     return {
         id: post.id,
         url: post.url,
@@ -784,6 +831,7 @@ function summarizeSignalPost(post) {
         },
         score: Number(post._score.toFixed(2)),
         excerpt: truncate(post.content),
+        ...(media ? { media } : {}),
     };
 }
 function summarizeSignalSearchResponse(response) {
@@ -2697,9 +2745,7 @@ function normalizeMcpCompanyIcp(filters) {
     if (!isPlainObject(icp)) {
         return;
     }
-    const scope = typeof icp.geographic_scope === "string"
-        ? icp.geographic_scope.trim()
-        : "";
+    const scope = typeof icp.geographic_scope === "string" ? icp.geographic_scope.trim() : "";
     const scopeMarkets = expandMcpCompanyIcpMarket(scope);
     if (scopeMarkets.length > 0) {
         icp.geographic_scope = "multi_country";
@@ -2708,9 +2754,7 @@ function normalizeMcpCompanyIcp(filters) {
             ...normalizeMcpCompanyIcpMarkets(icp.geographic_markets),
         ]);
     }
-    else if (scope &&
-        scope !== "single_country" &&
-        scope !== "multi_country") {
+    else if (scope && scope !== "single_country" && scope !== "multi_country") {
         delete icp.geographic_scope;
     }
     if (icp.geographic_markets !== undefined) {
@@ -2791,8 +2835,7 @@ function normalizeMcpSeedMatchAll(filters, concreteSeedCount, omittedFilters = [
     if (!isPlainObject(filters.company_lookalike)) {
         return;
     }
-    if (filters.company_lookalike.match_all === true &&
-        concreteSeedCount < 2) {
+    if (filters.company_lookalike.match_all === true && concreteSeedCount < 2) {
         omittedFilters.push({
             field: "company_lookalike.match_all",
             reason: "Dropped match_all because fewer than two concrete approved lookalike seeds remained after MCP seed normalization.",
@@ -2900,7 +2943,9 @@ function normalizeStringArray(input) {
         .filter((value) => value.length > 0);
 }
 function normalizeMcpSeeds(input, kind) {
-    return uniqueStrings(normalizeStringArray(input).filter((seed) => kind === "domain" ? isLikelyConcreteDomain(seed) : isLikelyConcreteSeedCompany(seed)));
+    return uniqueStrings(normalizeStringArray(input).filter((seed) => kind === "domain"
+        ? isLikelyConcreteDomain(seed)
+        : isLikelyConcreteSeedCompany(seed)));
 }
 function isLikelyConcreteDomain(input) {
     return /^[a-z0-9.-]+\.[a-z]{2,}$/i.test(input);
@@ -3111,13 +3156,7 @@ function buildProspeoPeopleSearchFallbackInput(input, error) {
     const fallbackFilters = {
         person_name_or_job_title: keyword,
         person_seniority: {
-            include: [
-                "C-Suite",
-                "Vice President",
-                "Head",
-                "Director",
-                "Manager",
-            ],
+            include: ["C-Suite", "Vice President", "Head", "Director", "Manager"],
         },
         max_person_per_company: typeof filters.max_person_per_company === "number"
             ? filters.max_person_per_company

package/dist/tools/linkedin.d.ts

@@ -185,7 +185,15 @@ interface RawLinkedInPost {
         authorPublicIdentifier?: string;
     };
     text?: string;
-    content?: string;
+    content?: string | {
+        images?: unknown;
+        article?: unknown;
+        video?: unknown;
+    };
+    media?: unknown;
+    postImages?: unknown;
+    postVideo?: unknown;
+    article?: unknown;
     activityDate?: string;
     postedAt?: string | {
         date?: string;
@@ -219,6 +227,15 @@ interface SerializedPost {
     comments: number;
     url: string;
     isRepost: boolean;
+    media?: SerializedPostMedia;
+}
+interface SerializedPostMedia {
+    imageUrls: string[];
+    videoThumbnailUrl?: string;
+    videoUrl?: string;
+    articleImageUrl?: string;
+    articleUrl?: string;
+    mediaTypes: string[];
 }
 export declare function serializeLinkedInPosts(rawPosts: RawLinkedInPost[] | undefined, context: string): SerializedPost[];
 export declare function fetchLinkedInPosts(linkedinUrl: string, limit?: number): Promise<{

package/dist/tools/linkedin.js

@@ -157,14 +157,105 @@ function normalizePostUrl(post) {
         post.header?.linkedinUrl ||
         "");
 }
+function collectImageUrls(value, urls = new Set()) {
+    if (!value)
+        return urls;
+    if (typeof value === "string" && /^https?:\/\//i.test(value)) {
+        urls.add(value);
+        return urls;
+    }
+    if (Array.isArray(value)) {
+        for (const item of value)
+            collectImageUrls(item, urls);
+        return urls;
+    }
+    if (typeof value !== "object")
+        return urls;
+    const objectValue = value;
+    for (const key of ["url", "imageUrl", "thumbnailUrl", "thumbnail_url"]) {
+        const candidate = objectValue[key];
+        if (typeof candidate === "string" && /^https?:\/\//i.test(candidate)) {
+            urls.add(candidate);
+        }
+    }
+    if (objectValue.image)
+        collectImageUrls(objectValue.image, urls);
+    if (objectValue.images)
+        collectImageUrls(objectValue.images, urls);
+    return urls;
+}
+function pickString(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function serializePostMedia(post) {
+    const media = post.media && typeof post.media === "object"
+        ? post.media
+        : {};
+    const content = post.content && typeof post.content === "object" ? post.content : {};
+    const article = post.article && typeof post.article === "object"
+        ? post.article
+        : content.article && typeof content.article === "object"
+            ? content.article
+            : {};
+    const video = post.postVideo && typeof post.postVideo === "object"
+        ? post.postVideo
+        : content.video && typeof content.video === "object"
+            ? content.video
+            : {};
+    const imageUrls = Array.from(collectImageUrls([
+        media.imageUrls,
+        post.postImages,
+        content.images,
+        article.image,
+    ]));
+    const videoThumbnailUrl = pickString(media.videoThumbnailUrl) ||
+        pickString(video.thumbnailUrl) ||
+        pickString(video.thumbnail_url) ||
+        pickString(video.thumbnail);
+    const videoUrl = pickString(media.videoUrl) ||
+        pickString(video.videoUrl) ||
+        pickString(video.video_url);
+    const articleImageUrl = pickString(media.articleImageUrl) ||
+        Array.from(collectImageUrls(article.image))[0];
+    const articleUrl = pickString(media.articleUrl) ||
+        pickString(article.link) ||
+        pickString(article.article_url) ||
+        pickString(article.articleUrl) ||
+        pickString(article.url);
+    const mediaTypes = Array.from(new Set([
+        ...(Array.isArray(media.mediaTypes)
+            ? media.mediaTypes.map((type) => typeof type === "string" ? type.trim() : "")
+            : []),
+        imageUrls.length > 0 ? "image" : "",
+        videoThumbnailUrl || videoUrl ? "video" : "",
+        articleImageUrl || articleUrl ? "article" : "",
+    ].filter(Boolean)));
+    if (imageUrls.length === 0 &&
+        !videoThumbnailUrl &&
+        !videoUrl &&
+        !articleImageUrl &&
+        !articleUrl) {
+        return undefined;
+    }
+    return {
+        imageUrls,
+        ...(videoThumbnailUrl ? { videoThumbnailUrl } : {}),
+        ...(videoUrl ? { videoUrl } : {}),
+        ...(articleImageUrl ? { articleImageUrl } : {}),
+        ...(articleUrl ? { articleUrl } : {}),
+        mediaTypes,
+    };
+}
 function serializeLinkedInPost(post) {
+    const media = serializePostMedia(post);
     return {
-        text: post.text || post.content || "",
+        text: post.text || (typeof post.content === "string" ? post.content : "") || "",
         date: normalizePostDate(post),
         reactions: post.reactionsCount ?? post.engagement?.likes ?? 0,
         comments: post.commentsCount ?? post.engagement?.comments ?? 0,
         url: normalizePostUrl(post),
         isRepost: Boolean(post.isRepublishedPost || post.repostedBy || post.repostedAt),
+        ...(media ? { media } : {}),
     };
 }
 function isUsableSerializedPost(post) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sellable/mcp",
-  "version": "0.1.293",
+  "version": "0.1.294",
   "type": "module",
   "description": "Sellable MCP server for Claude Code and Codex campaign workflows",
   "main": "dist/index.js",

package/skills/create-post/SKILL.md

@@ -516,6 +516,10 @@ Visible Flow Trace
 - calculated mobile/desktop visible blocks from
   `calculate_linkedin_hook_preview` or authenticated LinkedIn screenshot:
 - optional visual artifact from `render_linkedin_post_preview`:
+- source attached media inspected:
+- sourceVisualBasis / mediaType / cover_only:
+- visualHookMechanism / beliefActivated / proofCreated:
+- visualToCopyAlignment:
 - see-more tension:
 - curiosity debt:
 - body promise:
@@ -727,6 +731,9 @@ The research worker must return a compact packet only:
 - viral-post outlines for the best source posts
 - line-to-template conversions that turn source structures into reusable
   templates without source wording
+- visual/media hook analysis: source image URL or local path, visual basis,
+  media type, visible image text, visual hook mechanism, belief activated,
+  proof created, visual-to-copy alignment, and Sellable adaptation notes
 - hook-to-body promise maps that show how each hook tells the body
 - body structures and exact body language moves
 - preview measurements
@@ -746,22 +753,31 @@ Default flow:
 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. 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 an audience tension snapshot before hook generation: what the space is rewarding, what tension readers are reacting to, what they want to try or avoid, what objections/fears will make them hesitate, and which angle the user can credibly own. If the user's raw idea is internally coherent but not attached to live audience 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
+6. For every shortlisted keeper or near-keeper, inspect attached media when
+   available. Prefer authenticated screenshots or downloaded media; otherwise
+   use public `og:image`, `twitter:image`, or JSON-LD `image.url` from the
+   source post URL. Record `sourceVisualBasis`, `sourceImageUrl`,
+   `sourceImageLocalPath` when created, `imageAvailability`, `mediaType`,
+   `cover_only` when only a first frame/cover was inspected,
+   `visualHookMechanism`, `beliefActivated`, `proofCreated`, and
+   `visualToCopyAlignment`. Do not infer hidden video or carousel frames.
+7. 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`.
+8. Penalize lead-magnet or giveaway mechanics unless the user explicitly asks for a lead magnet post.
+9. Build an audience tension snapshot before hook generation: what the space is rewarding, what tension readers are reacting to, what they want to try or avoid, what objections/fears will make them hesitate, and which angle the user can credibly own. If the user's raw idea is internally coherent but not attached to live audience tension, do not draft from the internal idea alone; present stronger directions or rewrite the draft angle around the external tension.
+10. 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.
+11. For story posts, extract the story mechanism that made the post work, not just the first line.
+12. Extract hook structures plus specific reusable words, phrases, sentence
    shapes, transitions, and body language patterns.
-12. Create a post positioning breakdown for each keeper post: line/phrase,
+13. 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,
+    proof dependency, source visual basis, visual hook mechanism, and reusable
+    template line.
+14. 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`.
+15. Convert the best outlines into reusable post templates with positioning
+    sequences, visual engine, required story/proof inputs, forbidden borrowing,
+    and Sellable-specific adaptation instructions.
+16. Save the research with `mcp__sellable__save_hook_research`.
 
 Record provenance:
 
@@ -775,6 +791,10 @@ Record provenance:
 - lead-magnet or engagement-bait penalties
 - story mechanism when relevant
 - full-text match status
+- source visual basis, source image URLs, local image paths when created,
+  media type, image availability, `cover_only` status, visible image text,
+  visual hook mechanism, belief activated, proof created, visual-to-copy
+  alignment, visual risk, and Sellable adaptation notes
 - transcript/content-memory match status and worldview packet
 - source hook preview measurements and whether they came from full text or a search preview
 - selected hook patterns
@@ -819,6 +839,19 @@ Research status:
 Best source examples:
 1. author, URL, engagement, why kept, why not copied
 
+Visual hook analysis:
+1. source + sourceImageUrl/sourceImageLocalPath
+   - sourceVisualBasis:
+   - imageAvailability:
+   - mediaType:
+   - cover_only:
+   - visualHookMechanism:
+   - beliefActivated:
+   - proofCreated:
+   - visualToCopyAlignment:
+   - visualRisk:
+   - Sellable adaptation:
+
 Audience tension snapshot:
 - resonating ideas:
 - visible audience tension:

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

@@ -119,6 +119,9 @@ Show compact candidate cards. Include:
 - why it might belong in the pack
 - hook mechanism
 - hook preview budget status and measurement basis
+- source image URL or local path when available
+- source visual basis, media type, visual hook mechanism, belief activated, and
+  visual-to-copy alignment
 - content/body mechanism
 - rhythm notes
 - sentence-structure notes
@@ -154,6 +157,7 @@ Do not write candidates to the approved pack before the user chooses.
 - `Primary Use`
 - `Allowed Use`
 - `Hook Pattern`
+- `Visual Pattern`
 - `Body Pattern`
 - `Rhythm Notes`
 - `Sentence Notes`
@@ -201,6 +205,24 @@ Tags:
 - internal question:
 - emotional trigger:
 
+## Visual / Media Breakdown
+
+- source image URL:
+- source image local path:
+- source visual basis:
+- image availability:
+- media type:
+- cover only:
+- image alt text:
+- visible image text:
+- visual layout:
+- visual hook mechanism:
+- belief activated:
+- proof created:
+- visual-to-copy alignment:
+- visual risk:
+- allowed adaptation:
+
 ## Content / Body Breakdown
 
 - thesis:

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

@@ -7,7 +7,7 @@ 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 six outputs:
+V2 research has seven outputs:
 
 1. weighted source winners: the best recent posts to learn from
 2. hook autopsies: exact preview measurements, open loops, and tension created
@@ -16,7 +16,9 @@ V2 research has six outputs:
 4. viral-post outlines: the reusable narrative structure of each source post
 5. post positioning breakdown templates: line-level positioning and narrative
    technique maps that can be adapted into the user's draft
-6. thought leader voice variants from the configured active influencer
+6. visual/media hook analysis: the attached image, video cover, carousel cover,
+   screenshot, diagram, or lack of media that changed how the hook landed
+7. thought leader voice variants from the configured active influencer
    list, unless the user explicitly skipped thought leaders or supplied a
    named subset
 
@@ -45,11 +47,15 @@ Worker owns:
 - broad keyword search
 - tracked-person post fetches
 - full-text matching by URL/activity ID
+- public post image/media metadata extraction from shortlisted source URLs
 - duplicate removal
 - lead-magnet, giveaway, engagement-bait, and off-voice filtering
 - audience tension extraction across kept and rejected examples
 - premise input extraction: real scenes, observed tensions, reader value, proof gaps
 - hook opening measurement and "see more" tension autopsy
+- visual artifact inspection: first-frame screenshot, `og:image`,
+  `twitter:image`, JSON-LD `image.url`, carousel cover, video cover, visual hook
+  mechanism, belief activated, what the image proves, and copy/image alignment
 - exact phrase-pattern extraction
 - post positioning breakdown by line and phrase
 - viral-post outline extraction
@@ -86,6 +92,9 @@ Research packet:
 - body patterns: max 8
 - source URLs and author profile URLs
 - preview measurements
+- source visual records: media availability, source image URLs, local image paths
+  when downloaded, visual basis, media type, visible image text, visual hook
+  mechanism, belief activated, proof created, and visual-to-copy alignment
 - hook-to-body promise maps
 - body expression inputs
 - thought leader voice variants
@@ -261,6 +270,66 @@ 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.
 
+## Visual / Media Reality
+
+For every shortlisted keeper or near-keeper source post, inspect attached media
+when available. Do this before judging why the hook worked. Many high-performing
+LinkedIn hooks are carried by the first image, video cover, carousel cover,
+diagram, terminal screenshot, before/after output, or workflow map. If the text
+is studied without the media, the research can misread the post.
+
+Use the best available visual source in this order:
+
+1. authenticated LinkedIn screenshot or downloaded media when the host can
+   access it
+2. public `og:image` metadata from the source post URL
+3. public `twitter:image` metadata from the source post URL
+4. JSON-LD `image.url` from the source post URL
+5. no visual source available
+
+Record `sourceVisualBasis` as one of:
+
+- `authenticated_screenshot`
+- `downloaded_image`
+- `public_og_image`
+- `public_twitter_image`
+- `json_ld_image`
+- `none_available`
+
+If the source is a video or carousel and only the first frame or cover image is
+available, record `cover_only`. Do not infer hidden video frames, carousel
+slides, hover states, captions, or comments that were not inspected.
+
+For each inspected source, preserve:
+
+- `sourceImageUrl`
+- `sourceImageLocalPath` when downloaded or screenshotted
+- `imageAvailability`: `present`, `none`, or `blocked`
+- `mediaType`: `image`, `carousel_cover`, `video_cover`, `text_only`, or
+  `unknown`
+- `imageAltText` when available
+- `visibleText`: exact visible words in the image when safe to quote briefly,
+  otherwise short anchors
+- `visualLayout`: what the viewer sees first, such as file tree, stack diagram,
+  terminal output, checklist, before/after table, UI screenshot, founder photo,
+  logo grid, or generic placeholder
+- `visualHookMechanism`: how the visual creates curiosity, proof, contrast,
+  concreteness, safety, status, or "I can picture this" belief
+- `beliefActivated`: what the audience has to believe for the post to work
+- `proofCreated`: what the visual proves or makes more believable that the text
+  alone would not
+- `visualToCopyAlignment`: how the opening text and media reinforce or fight
+  each other
+- `visualRisk`: generic stock feel, unreadable text, borrowed proof,
+  engagement-bait cover, misleading model/logo claims, account-safety risk, or
+  unclear product proof
+- `sellableAdaptation`: what kind of Sellable visual could use the same
+  mechanism without copying the source
+
+When a post has no media, record `imageAvailability: none` and treat the hook as
+text-led. When the media is blocked, record `imageAvailability: blocked` and
+lower confidence instead of inventing a visual analysis.
+
 ## Opening Preview Measurement
 
 Measure the visible opening for every shortlisted source post before extracting
@@ -339,6 +408,8 @@ For each shortlisted source post, record:
 - author profile URL when available
 - engagement totals and available likes/comments/shares breakdown
 - creator repeat evidence
+- source visual basis, media type, image URL/local path, and visual hook
+  analysis
 - visible hook text or preview
 - opening preview measurement fields from the section above
 - hook mechanism
@@ -348,6 +419,11 @@ For each shortlisted source post, record:
 - exact hook language patterns: reusable words, phrase shapes, contrast forms,
   sentence shapes, and transition moves
 - story mechanism when the post is a story
+- visual mechanism when an image, carousel cover, video cover, screenshot,
+  diagram, or generic placeholder affects the hook
+- belief activated by the visual
+- proof created by the visual
+- visual-to-copy alignment
 - internal question created
 - emotional trigger
 - proof/story dependency
@@ -441,6 +517,14 @@ Use this format:
 Post positioning breakdown:
 source: <author + URL>
 text_basis: full_text | search_preview | manual_user_source
+source_visual_basis: authenticated_screenshot | downloaded_image | public_og_image | public_twitter_image | json_ld_image | none_available
+media_type: image | carousel_cover | video_cover | text_only | unknown
+source_image_url:
+source_image_local_path:
+visual_hook_mechanism:
+belief_activated:
+proof_created:
+visual_to_copy_alignment:
 overall_positioning_sequence:
   <Category> -> <Category> -> <Category> -> ...
 
@@ -576,6 +660,14 @@ source:
 template_name:
 positioning_sequence:
   <Category> -> <Category> -> <Category> -> ...
+visual_engine:
+  source_visual_basis:
+  media_type:
+  visual_hook_mechanism:
+  belief_activated:
+  proof_created:
+  visual_to_copy_alignment:
+  sellable_adaptation:
 required_story_inputs:
   - <input the user must actually have>
 required_proof_inputs:
@@ -682,6 +774,8 @@ why_it_might_fail:
 positioning_sequence_to_borrow:
 hook_move_to_borrow:
 body_outline_to_borrow:
+visual_engine_to_borrow:
+visual_guardrails:
 line_shapes_to_test:
 required_user_inputs:
 required_proof:
@@ -845,8 +939,27 @@ 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, 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.
+post templates, visual/media hook analysis, hook-to-body promise maps, body
+structures, rejected examples, tracked-person recommendations, and
+gold-standard recommendations.
+
+Save source visual provenance for every keeper or near-keeper:
+
+- `sourceVisualBasis`
+- `sourceImageUrl`
+- `sourceImageLocalPath` when created
+- `imageAvailability`
+- `mediaType`
+- `imageAltText` when available
+- `visibleText`
+- `visualLayout`
+- `visualHookMechanism`
+- `beliefActivated`
+- `proofCreated`
+- `visualToCopyAlignment`
+- `visualRisk`
+- `sellableAdaptation`
+- `cover_only` when only the cover or first frame was inspected
 
 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/post-file-contract.md

@@ -67,6 +67,12 @@ Hook research files must preserve:
   reach-adjusted score, and normalization confidence notes when reach
   normalization was used
 - full-text availability
+- source image/media URLs, source visual basis, local screenshot/image artifact
+  paths when created, image availability (`present`, `none`, or `blocked`),
+  media type (`image`, `carousel_cover`, `video_cover`, `text_only`, or
+  `unknown`), `cover_only` status, image alt text when available, visible image
+  text anchors, visual hook mechanism, visual belief activated, proof created by
+  the visual, visual-to-copy alignment, visual risk, and adaptation guards
 - 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

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

@@ -36,6 +36,7 @@ Every saved draft needs a validation receipt. A draft without this receipt is no
 - `premiseValueAudit`
 - `mobileScanabilityAudit`
 - `templateAdaptationAudit`
+- `sourceVisualAudit`
 - `abstractionToConcreteRewriteAudit`
 - `linkedinPreviewAudit`
 - `simplifierConcreteLanguageAudit`
@@ -97,6 +98,8 @@ Each candidate should include:
 - premise tension opened
 - reader value implied
 - source pattern
+- source visual mechanism, source visual basis, visual-to-copy alignment, and
+  visual belief activated when the source used media
 - hook-to-body promise
 - see-more tension
 - curiosity debt
@@ -348,6 +351,8 @@ Record:
 - `selectedSourceTemplate`: source, template name, and why it fits
 - `positioningSequenceBorrowed`: category sequence being adapted
 - `viralPostOutlineBorrowed`: beat sequence being adapted
+- `visualEngineBorrowed`: visual hook mechanism, source visual basis, and
+  visual-to-copy alignment being adapted when the source used media
 - `lineShapesBorrowed`: reusable line shapes, not copied wording
 - `userStoryInputsUsed`: source-backed user facts filling the template
 - `userProofInputsUsed`: source-backed user proof filling the template
@@ -361,6 +366,34 @@ 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.
 
+## Source Visual Audit
+
+Before a draft can be `ready`, validate that media from the source examples was
+seen and interpreted, not guessed.
+
+Record:
+
+- `visual_hook_analysis`: keeper source, source visual basis, source image URL
+  or local path, image availability, media type, and whether the inspection was
+  `cover_only`
+- `visibleImageText`: brief visible text anchors from the image when safe
+- `visualHookMechanism`: how the source image, video cover, carousel cover,
+  screenshot, diagram, or lack of media helped the hook work
+- `beliefActivated`: what belief the visual made easier for the audience to
+  accept
+- `proofCreated`: what the visual made more credible than the text alone
+- `visualToCopyAlignment`: how the source copy and visual reinforced or fought
+  each other
+- `sellableVisualAdaptation`: the equivalent Sellable visual mechanism planned
+  for this draft, if any
+- `visualRisk`: unreadable media, generic stock-like media, misleading logo or
+  model claims, borrowed product proof, account-safety concern, or blocked
+  media
+
+Save as `needs_revision` when a selected source template relied on media but
+the media was not inspected, when the draft borrows visual proof Christian does
+not have, or when the planned Sellable visual contradicts the hook.
+
 ## Audience Tension Audit
 
 Before a draft can be `ready`, validate that it is not merely an internally