@sellable/mcp 0.1.259 → 0.1.261

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.261",
   "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:
 
@@ -283,6 +284,173 @@ Space benchmark research:
 7. For each approved tracked person, call `mcp__sellable__upsert_engage_tracked_person`.
 
 The approved pack is capped at 20 gold standards. If adding new approved examples would exceed 20, ask which existing item to replace or skip the overflow. Candidate lists can be longer, but approved saved standards cannot exceed 20.
+
+## Visible Whole-Flow Debug Mode
+
+Use when the user asks to see the whole flow, run the flow step by step,
+validate that the workflow is working, debug a bad output, explain why a draft
+is bad, or otherwise asks for the process to be explicit.
+
+This mode exists because a validation receipt hidden inside a saved draft is not
+enough. The user must be able to inspect the reasoning path before the system
+claims the workflow worked.
+
+In visible whole-flow debug mode:
+
+1. Run the normal create-post workflow.
+2. Show a `Visible Flow Trace` with every checkpoint below.
+3. Mark each checkpoint `pass`, `weak`, `fail`, or `blocked`.
+4. Include the concrete output from that checkpoint, not only a label.
+5. If any checkpoint is weak or failed, name the exact quality break and the
+   downstream effect on the draft.
+6. Do not call the run successful just because files were saved.
+7. Do not hide premise cards, source-template selection, hook candidates,
+   pre-draft structure, body-expression candidates, or validation findings only
+   inside the saved artifact.
+
+The trace must use this order:
+
+```text
+Visible Flow Trace
+
+0. Bootstrap
+- auth/workspace:
+- canonical prompt loaded:
+- required assets loaded:
+- memory loaded:
+- package/version notes:
+
+1. Raw Idea Capture
+- idea id:
+- raw source preserved:
+- distilled brief:
+- claims added or avoided:
+
+2. Research Search Log
+- search window:
+- keywords:
+- result count:
+- full-text fetches:
+- search gaps:
+
+3. Weighted Source Selection
+- kept sources:
+- rejected sources:
+- keeper scores:
+- lead-magnet / engagement-bait penalties:
+- why the top source actually fits:
+
+4. Hook Autopsies
+- source hook:
+- rendered/mobile preview or preview-basis:
+- see-more tension:
+- curiosity debt:
+- body promise:
+- why it works:
+- why it may not transfer:
+
+5. Post Positioning Breakdowns
+- source:
+- positioning sequence:
+- line-level narrative techniques:
+- reusable template lines:
+- adaptation guards:
+
+6. Viral-Post Outlines
+- source template:
+- hook job:
+- see-more trigger:
+- beat sequence:
+- body payoff:
+- close job:
+
+7. Market Belief Map
+- resonating ideas:
+- implicit beliefs:
+- wants / resentments / fears:
+- selected controversy:
+- why this user can credibly say it:
+- what not to claim:
+
+8. Premise Cards
+- 3-5 cards:
+- story/scene:
+- tension:
+- reader value:
+- proof available:
+- proof missing:
+- source-template fit:
+- score:
+- selected premise:
+
+9. Source Template Selection
+- selected template:
+- positioning sequence to borrow:
+- hook move to borrow:
+- body outline to borrow:
+- required user proof:
+- forbidden borrowing:
+- no-template rationale if rejected:
+
+10. Hook Lab
+- at least 12 hooks:
+- rendered preview record or explicit preview-basis:
+- hook-to-body promise:
+- score:
+- selected hook:
+- rejected winning-looking hooks and why:
+
+11. Pre-Draft Narrative Outline
+- hierarchical outline shown before draft:
+- I. hook and click debt:
+- II. thesis the post will defend:
+- III. operating model:
+- IV. body shape borrowed from posts that worked:
+- V. narrative beats:
+- VI. scan path and proof safety:
+- user corrections applied before prose:
+
+12. Body Expression Lab
+- 5-8 body-expression candidates:
+- best lines:
+- weak lines:
+- hook promise repayment:
+- proof risk:
+- score:
+- combined body plan:
+
+13. Draft
+- draft body:
+- lines intentionally copied from user source:
+- outside-source wording copied: yes/no:
+- known weak lines:
+
+14. Validation And Save
+- ready status:
+- proof gate:
+- voice gate:
+- anti-AI gate:
+- mobile preview gate:
+- template adaptation gate:
+- hook-to-body repayment:
+- quality break, if any:
+- saved idea path:
+- saved research path:
+- saved draft path:
+```
+
+Quality-break rules:
+
+- If the draft is bad, say which checkpoint produced the bad draft. For example:
+  weak raw story, wrong selected source template, hook promise not repaid,
+  body expression lab too generic, proof missing, or voice mismatch.
+- A draft with a coherent validation receipt but poor body copy is not a
+  successful run. Mark it `needs_revision` and show the checkpoint where the
+  body lost the premise.
+- If the source idea is too abstract, stop at premise development or save a
+  `needs_revision` draft only after showing the missing story/proof.
+- If the user is judging the workflow itself, prefer showing the trace over
+  optimizing for a polished final post.
 </modes>
 
 <pipeline>
@@ -320,6 +488,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 +517,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 +544,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 +596,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 +610,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 +652,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 +668,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 +682,103 @@ 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 Narrative Outline
+
+Before generating final draft prose, create and show a compact `Pre-Draft
+Narrative Outline`. This is not a checklist. It is the user-visible argument
+skeleton that lets the user confirm what the post will say, in what order, and
+which proven body shapes will guide the draft before the system writes body
+copy.
+
+The outline 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 outline in the validation receipt.
+
+The `Pre-Draft Narrative Outline` must use hierarchical outline notation:
+Roman numerals for major narrative beats, letters for sub-beats, and lowercase
+roman numerals for proof/examples/body moves. Do not replace this with a flat
+field list.
+
+The `Pre-Draft Narrative Outline` must include:
+
+```text
+Pre-Draft Narrative Outline
+I. Hook and click debt
+   A. Selected hook:
+   B. Rendered mobile preview verdict:
+   C. What "see more" must repay:
+
+II. Thesis the post will defend
+   A. One-sentence thesis:
+   B. Reader being taught:
+   C. Why this reader cares now:
+
+III. Operating model
+   A. Core equation or mechanism:
+   B. Key definitions:
+      i. <term>: <plain definition + concrete examples>
+      ii. <term>: <plain definition + concrete examples>
+
+IV. Body shape borrowed from posts that worked
+   A. Selected source template or no-template rationale:
+   B. Working body pattern(s) being adapted:
+      i. <pattern name>: <beat order and why it works>
+      ii. <pattern name>: <beat order and why it works>
+   C. What gets borrowed:
+      i. <narrative job, sequence, transition, or proof order>
+   D. What must not be copied:
+      i. <source wording, creator-specific proof, joke, or context>
+
+V. Narrative beats
+   A. Beat 1: <job, reader state before/after, example/proof>
+      i. Line shape or section label:
+      ii. Concrete examples:
+   B. Beat 2: <job, reader state before/after, example/proof>
+      i. Line shape or section label:
+      ii. Concrete examples:
+   C. Beat 3: <job, reader state before/after, example/proof>
+      i. Line shape or section label:
+      ii. Concrete examples:
+
+VI. Scan path and proof safety
+   A. Mobile scan path:
+   B. Proof claims:
+      i. <claim>: <source + public-safety status>
+   C. Abstractions to remove:
+      i. <abstract phrase> -> <concrete replacement>
+   D. 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.
+- `Body shape borrowed from posts that worked` must name the body pattern or
+  explain why no-template is stronger. It must say what narrative job is being
+  borrowed, not just "make it like this creator."
+- `Narrative beats` must show the order of the argument with `I.`, `A.`, and
+  `i.`-style hierarchy. A flat checklist fails this step.
+- 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 outline, update the outline first, then draft. Do
+  not patch the final prose while leaving the outline stale.
+
 ## Step 2: Hook Candidates
 
 Generate at least 12 hook candidates from the selected premise unless the user
@@ -528,7 +836,12 @@ Draft from:
 - exact raw idea
 - selected premise card
 - selected hook
+- approved or latest `Pre-Draft Narrative Outline`
 - 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 +862,20 @@ Every saved draft needs a validation receipt with:
 - selected premise card
 - candidate hooks considered
 - selected hook and why
+- pre-draft narrative outline
+- 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 +970,15 @@ iteration:
   score: <compact score object>
 selected_premise: <premise or none>
 selected_hook: <hook>
+pre_draft_narrative_outline: <compact I/A/i outline summary or none>
+selected_source_template: <template name/source or none>
+visible_flow_trace: <required when user asked for whole-flow/debug/step-by-step mode; include checkpoint statuses and quality break>
 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