@sellable/mcp 0.1.259 → 0.1.260

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

@@ -1,3 +1,14 @@
+type FollowerBandFit = "in_target_band" | "below_target_band" | "above_target_band" | "unknown";
+type ReachSignals = {
+    targetFollowerMin?: number;
+    targetFollowerMax?: number;
+    followerBandFit: FollowerBandFit;
+    engagementPer1kFollowers: number | null;
+    weightedEngagementPer1kFollowers: number | null;
+    reachPenaltyMultiplier: number;
+    reachAdjustedScore: number;
+    confidence: "high" | "medium" | "low";
+};
 export type EngagementPost = {
     postId: string;
     url: string;
@@ -7,6 +18,7 @@ export type EngagementPost = {
         name: string;
         headline: string;
         profileUrl: string;
+        followerCount?: number;
     };
     engagement: {
         likes: number;
@@ -14,6 +26,7 @@ export type EngagementPost = {
         shares: number;
         total: number;
     };
+    reachSignals?: ReachSignals;
     contentPreview: string;
 };
 export type SearchEngagementPostsInput = {
@@ -23,6 +36,8 @@ export type SearchEngagementPostsInput = {
     minTotalEngagement?: number;
     maxPosts?: number;
     excludePostUrls?: string[];
+    targetFollowerMin?: number;
+    targetFollowerMax?: number;
 };
 export type SearchEngagementPostsResponse = {
     success: boolean;
@@ -70,9 +85,18 @@ export declare const engageDiscoveryToolDefinitions: {
                 };
                 description: string;
             };
+            targetFollowerMin: {
+                type: string;
+                description: string;
+            };
+            targetFollowerMax: {
+                type: string;
+                description: string;
+            };
         };
         required: string[];
         additionalProperties: boolean;
     };
 }[];
 export declare function searchEngagementPosts(input: SearchEngagementPostsInput): Promise<SearchEngagementPostsResponse>;
+export {};

package/dist/tools/engage-discovery.js

@@ -32,6 +32,14 @@ export const engageDiscoveryToolDefinitions = [
                     items: { type: "string" },
                     description: "Optional list of post URLs to exclude (e.g. already engaged/scheduled).",
                 },
+                targetFollowerMin: {
+                    type: "number",
+                    description: "Optional lower bound for creator follower count when reach-normalizing hook/source quality.",
+                },
+                targetFollowerMax: {
+                    type: "number",
+                    description: "Optional upper bound for creator follower count when reach-normalizing hook/source quality.",
+                },
             },
             required: ["keywords"],
             additionalProperties: false,
@@ -63,6 +71,79 @@ function safeNumber(value) {
     const n = typeof value === "number" ? value : Number(value);
     return Number.isFinite(n) ? n : 0;
 }
+function round3(value) {
+    return Number(value.toFixed(3));
+}
+function parseFollowerCount(author) {
+    const direct = safeNumber(author?.followerCount);
+    if (direct > 0)
+        return direct;
+    const text = String(author?.followers || author?.followerCountText || "");
+    const match = text.match(/([\d,.]+)\s*([kKmM])?/);
+    if (!match)
+        return undefined;
+    const base = Number(match[1].replace(/,/g, ""));
+    if (!Number.isFinite(base) || base <= 0)
+        return undefined;
+    const suffix = match[2]?.toLowerCase();
+    if (suffix === "m")
+        return Math.round(base * 1_000_000);
+    if (suffix === "k")
+        return Math.round(base * 1_000);
+    return Math.round(base);
+}
+function reachPenaltyMultiplier(followerCount, targetFollowerMin, targetFollowerMax) {
+    if (!followerCount || !targetFollowerMin || !targetFollowerMax)
+        return 0.4;
+    if (followerCount >= targetFollowerMin && followerCount <= targetFollowerMax) {
+        return 1;
+    }
+    if (followerCount < targetFollowerMin)
+        return 0.75;
+    if (followerCount <= targetFollowerMax * 2)
+        return 0.65;
+    if (followerCount <= targetFollowerMax * 5)
+        return 0.35;
+    return 0.15;
+}
+function followerBandFit(followerCount, targetFollowerMin, targetFollowerMax) {
+    if (!followerCount || !targetFollowerMin || !targetFollowerMax) {
+        return "unknown";
+    }
+    if (followerCount >= targetFollowerMin && followerCount <= targetFollowerMax) {
+        return "in_target_band";
+    }
+    if (followerCount < targetFollowerMin)
+        return "below_target_band";
+    return "above_target_band";
+}
+function buildReachSignals(params) {
+    const { followerCount, likes, comments, shares, total } = params;
+    const hasTarget = Boolean(params.targetFollowerMin && params.targetFollowerMax);
+    if (!hasTarget && !followerCount)
+        return undefined;
+    const weightedEngagement = likes + comments * 4 + shares * 12;
+    const penalty = reachPenaltyMultiplier(followerCount, params.targetFollowerMin, params.targetFollowerMax);
+    const engagementPer1kFollowers = followerCount
+        ? round3((total / followerCount) * 1000)
+        : null;
+    const weightedEngagementPer1kFollowers = followerCount
+        ? round3((weightedEngagement / followerCount) * 1000)
+        : null;
+    const reachAdjustedScore = weightedEngagementPer1kFollowers === null
+        ? 0
+        : round3(weightedEngagementPer1kFollowers * penalty);
+    return {
+        targetFollowerMin: params.targetFollowerMin,
+        targetFollowerMax: params.targetFollowerMax,
+        followerBandFit: followerBandFit(followerCount, params.targetFollowerMin, params.targetFollowerMax),
+        engagementPer1kFollowers,
+        weightedEngagementPer1kFollowers,
+        reachPenaltyMultiplier: penalty,
+        reachAdjustedScore,
+        confidence: followerCount ? (hasTarget ? "high" : "medium") : "low",
+    };
+}
 export async function searchEngagementPosts(input) {
     const api = getApi();
     const keywords = (input.keywords || [])
@@ -79,6 +160,12 @@ export async function searchEngagementPosts(input) {
     const maxPosts = typeof input.maxPosts === "number" && input.maxPosts > 0
         ? Math.min(50, input.maxPosts)
         : 25;
+    const targetFollowerMin = typeof input.targetFollowerMin === "number" && input.targetFollowerMin > 0
+        ? input.targetFollowerMin
+        : undefined;
+    const targetFollowerMax = typeof input.targetFollowerMax === "number" && input.targetFollowerMax > 0
+        ? input.targetFollowerMax
+        : undefined;
     const exclude = new Set((input.excludePostUrls || [])
         .map((u) => normalizePostUrl(u))
         .filter(Boolean));
@@ -87,10 +174,10 @@ export async function searchEngagementPosts(input) {
         keywords: keywords.map((keyword) => ({ keyword })),
         page,
     });
-    const rawPosts = Array.isArray(response?.topPostsForLLM)
-        ? response.topPostsForLLM
-        : Array.isArray(response?.posts)
-            ? response.posts
+    const rawPosts = Array.isArray(response?.posts)
+        ? response.posts
+        : Array.isArray(response?.topPostsForLLM)
+            ? response.topPostsForLLM
             : [];
     const now = Date.now();
     const oldestMs = now - maxAgeDays * 24 * 60 * 60 * 1000;
@@ -121,6 +208,16 @@ export async function searchEngagementPosts(input) {
             tooOld += 1;
             continue;
         }
+        const followerCount = parseFollowerCount(p?.author);
+        const reachSignals = buildReachSignals({
+            followerCount,
+            likes,
+            comments,
+            shares,
+            total,
+            targetFollowerMin,
+            targetFollowerMax,
+        });
         kept.push({
             postId: String(p?.id || ""),
             url,
@@ -132,18 +229,26 @@ export async function searchEngagementPosts(input) {
                 name: String(p?.author?.name || ""),
                 headline: String(p?.author?.headline || ""),
                 profileUrl: String(p?.author?.profileUrl || ""),
+                ...(followerCount ? { followerCount } : {}),
             },
             engagement: { likes, comments, shares, total },
+            ...(reachSignals ? { reachSignals } : {}),
             contentPreview: previewText(String(p?.content || ""), 220),
         });
-        if (kept.length >= maxPosts)
-            break;
     }
-    // Sort by total engagement desc for a predictable shortlist.
-    kept.sort((a, b) => b.engagement.total - a.engagement.total);
+    const hasReachTarget = Boolean(targetFollowerMin && targetFollowerMax);
+    kept.sort((a, b) => {
+        if (hasReachTarget) {
+            const reachDelta = (b.reachSignals?.reachAdjustedScore || 0) -
+                (a.reachSignals?.reachAdjustedScore || 0);
+            if (reachDelta !== 0)
+                return reachDelta;
+        }
+        return b.engagement.total - a.engagement.total;
+    });
     return {
         success: true,
-        posts: kept,
+        posts: kept.slice(0, maxPosts),
         totalReturned: rawPosts.length,
         filteredOut: { tooOld, excluded, tooLowEngagement },
     };

package/dist/tools/registry.d.ts

@@ -1749,6 +1749,14 @@ export declare const allTools: ({
                 };
                 description: string;
             };
+            targetFollowerMin: {
+                type: string;
+                description: string;
+            };
+            targetFollowerMax: {
+                type: string;
+                description: string;
+            };
         };
         required: string[];
         additionalProperties: boolean;

package/package.json

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

package/skills/create-post/SKILL.md

@@ -84,6 +84,7 @@ Before drafting, load all required assets with `mcp__sellable__get_subskill_asse
 3. `subskillName: "create-post", assetPath: "references/premise-development.md"`
 4. `subskillName: "create-post", assetPath: "references/post-validation.md"`
 5. `subskillName: "create-post", assetPath: "references/gold-standard-post-pack.md"`
+6. `subskillName: "create-post", assetPath: "references/linkedin-preview-rendering.md"`
 
 If any required asset is missing, unreadable, truncated without continuation, or internally inconsistent, return:
 
@@ -320,6 +321,12 @@ The research worker must return a compact packet only:
 - market belief map: resonating ideas, implicit beliefs, audience wants, resentments, fears, and credible controversy angles
 - premise inputs: real scenes, observed tensions, reader value openings, and proof gaps
 - exact phrase patterns and sentence shapes
+- post positioning breakdowns that label each meaningful line or phrase by
+  narrative job and category
+- viral-post outlines for the best source posts
+- line-to-template conversions that turn source structures into reusable
+  templates without source wording
+- hook-to-body promise maps that show how each hook tells the body
 - body structures and exact body language moves
 - preview measurements
 - track-person and gold-standard recommendations
@@ -343,7 +350,15 @@ Default flow:
 10. For story posts, extract the story mechanism that made the post work, not just the first line.
 11. Extract hook structures plus specific reusable words, phrases, sentence
    shapes, transitions, and body language patterns.
-12. Save the research with `mcp__sellable__save_hook_research`.
+12. Create a post positioning breakdown for each keeper post: line/phrase,
+    category, narrative technique, tension created, reader question opened,
+    proof dependency, and reusable template line.
+13. Convert each keeper into a viral-post outline: hook job, see-more trigger,
+    body payoff, close job, and beat-by-beat narrative structure.
+14. Convert the best outlines into reusable post templates with positioning
+    sequences, required story/proof inputs, forbidden borrowing, and
+    Sellable-specific adaptation instructions.
+15. Save the research with `mcp__sellable__save_hook_research`.
 
 Record provenance:
 
@@ -362,6 +377,10 @@ Record provenance:
 - market belief map and selected controversy
 - premise cards and selected premise
 - exact phrase patterns and sentence shapes
+- post positioning breakdowns
+- viral-post outlines
+- reusable post templates
+- hook-to-body promise maps
 - body structures and body language patterns
 - why each pattern fits the user's idea and voice
 
@@ -410,7 +429,10 @@ Hook patterns learned:
 1. full adapted hook block
    - source mechanism:
    - preview budget:
+   - see-more tension:
+   - curiosity debt:
    - internal question:
+   - hook-to-body promise:
    - why it fits / why it does not:
 
 Specific words and phrase shapes:
@@ -421,9 +443,35 @@ Specific words and phrase shapes:
    - adapted Sellable form:
    - do not copy:
 
+Post positioning breakdown templates:
+1. source + template name
+   - positioning sequence:
+   - line-level narrative techniques:
+   - tension created:
+   - reader questions opened:
+   - reusable template lines:
+   - Sellable adaptation:
+
+Viral-post outlines:
+1. outline name
+   - hook job:
+   - see-more trigger:
+   - body payoff:
+   - close job:
+   - beat sequence:
+
+Line-to-template conversion:
+1. source line/beat
+   - narrative job:
+   - template line shape:
+   - required user story/proof:
+   - forbidden borrowing:
+   - adapted Sellable expression:
+
 Body structures learned:
 1. structure name
    - source:
+   - positioning sequence:
    - sequence:
    - exact language moves:
    - adapted Sellable body move:
@@ -437,9 +485,9 @@ Save recommendations:
 - gold-standard candidates:
 
 Recommended draft directions:
-1. premise card + hook block + body structure
-2. premise card + hook block + body structure
-3. premise card + hook block + body structure
+1. premise card + source template + hook block + viral outline + body structure
+2. premise card + source template + hook block + viral outline + body structure
+3. premise card + source template + hook block + viral outline + body structure
 ```
 
 Keep this report concise enough to read, but concrete enough that another agent
@@ -453,7 +501,9 @@ Generate 3-5 `Premise Card` candidates from the raw idea, market research, core
 memory, story/proof files, and current-session user feedback. Each card must
 include a real story/scene or observed pattern, target reader, common belief,
 contrarian truth, tension, reader value, proof available, proof missing, and a
-score.
+score. Each card must also evaluate which source template or no-template path
+fits, which positioning sequence to test, and how the hook promise will be
+repaid in the body.
 
 Select the strongest premise before hook generation. The selected premise must
 pass:
@@ -465,12 +515,63 @@ pass:
 - `credible_speaker`
 - `proof_safety`
 - `market_heat`
+- `template_fit`
+- `hook_to_body_repayment`
 
 If the idea has market heat but no real scene, ask for the missing scene unless
 the user explicitly requested an immediate draft. For immediate draft mode, use
 only source-backed observed patterns and save the draft as `needs_revision`
 unless the premise still has concrete reader value.
 
+## Step 1.9: Pre-Draft Structure Brief
+
+Before generating final draft prose, create and show a compact `Pre-Draft
+Structure Brief`. In other words, show a compact Pre-Draft Structure Brief
+before the final draft body. This is the checkpoint that prevents the agent from
+jumping from a good hook into a messy body.
+
+The brief must be concise, mobile-scanable, and concrete enough for the user to
+approve or correct. Do not hide it inside the validation receipt after the
+draft. Show it before writing the draft body unless the user explicitly says to
+skip outline/structure and write immediately. Even when the user skips the
+visible checkpoint, still include the brief in the validation receipt.
+
+The `Pre-Draft Structure Brief` must include:
+
+```text
+Pre-Draft Structure Brief
+- hook:
+- thesis:
+- reader being taught:
+- why this reader cares now:
+- core equation or mechanism:
+- key definitions:
+- proof claims:
+- proof source / risk:
+- source template or no-template rationale:
+- mobile scan path:
+- section outline:
+- body promise after see more:
+- concrete examples to include:
+- abstractions to remove:
+- draft risks:
+```
+
+Rules:
+
+- The hook must already have a rendered mobile and desktop preview record.
+- The thesis must be one sentence the post can defend.
+- The reader must be specific enough to guide what gets cut.
+- Key definitions must name concrete examples when the post teaches an
+  operating concept. For example, define `lead source` as how the list was
+  built, not as a persona label.
+- `mobile scan path` must say what a reader understands if they read only the
+  hook, separators, section labels, numbers, and final line.
+- `abstractions to remove` must list abstract phrases and the concrete words
+  that will replace them.
+- If the user corrects the brief, update the brief first, then draft. Do not
+  patch the final prose while leaving the brief stale.
+
 ## Step 2: Hook Candidates
 
 Generate at least 12 hook candidates from the selected premise unless the user
@@ -528,7 +629,12 @@ Draft from:
 - exact raw idea
 - selected premise card
 - selected hook
+- approved or latest `Pre-Draft Structure Brief`
 - hook research artifact
+- selected source template or no-template rationale
+- viral-post outline
+- post positioning breakdown template
+- body expression candidates and combined body plan
 - user's core memory
 - story/proof files
 - post writing rules
@@ -549,11 +655,20 @@ Every saved draft needs a validation receipt with:
 - selected premise card
 - candidate hooks considered
 - selected hook and why
+- pre-draft structure brief
+- selected source template and no-copy adaptation rationale
+- post positioning breakdown
+- viral-post outline
+- hook-to-body promise map
+- body expression candidates and combined body plan
 - proof claims used and source
 - story/proof files consulted
 - gold standards consulted
 - LinkedIn preview audit
 - premise/value audit findings
+- mobile scanability audit findings
+- template-adaptation audit findings
+- abstraction-to-concrete rewrite audit findings
 - simplifier/concrete-language audit findings
 - voice audit findings
 - anti-AI audit findings
@@ -648,8 +763,14 @@ iteration:
   score: <compact score object>
 selected_premise: <premise or none>
 selected_hook: <hook>
+pre_draft_structure_brief: <compact structure summary or none>
+selected_source_template: <template name/source or none>
 validation_summary:
   premise_value: pass | needs_user_input | needs_revision
+  mobile_scanability: pass | needs_revision
+  template_adaptation: pass | needs_revision | blocked
+  abstraction_to_concrete: pass | needs_revision
+  hook_to_body_repayment: pass | needs_revision
   proof: pass | needs_user_input | blocked
   voice: pass | needs_revision
   anti_ai: pass | needs_revision