@sellable/mcp 0.1.260 → 0.1.261

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sellable/mcp",
-  "version": "0.1.260",
+  "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

@@ -284,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>
@@ -523,38 +690,73 @@ 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
+## Step 1.9: Pre-Draft Narrative Outline
 
 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.
+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 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
+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 brief in the validation receipt.
+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 Structure Brief` must include:
+The `Pre-Draft Narrative Outline` 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:
+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:
@@ -562,6 +764,11 @@ 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.
@@ -569,8 +776,8 @@ Rules:
   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.
+- 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
 
@@ -629,7 +836,7 @@ Draft from:
 - exact raw idea
 - selected premise card
 - selected hook
-- approved or latest `Pre-Draft Structure Brief`
+- approved or latest `Pre-Draft Narrative Outline`
 - hook research artifact
 - selected source template or no-template rationale
 - viral-post outline
@@ -655,7 +862,7 @@ Every saved draft needs a validation receipt with:
 - selected premise card
 - candidate hooks considered
 - selected hook and why
-- pre-draft structure brief
+- pre-draft narrative outline
 - selected source template and no-copy adaptation rationale
 - post positioning breakdown
 - viral-post outline
@@ -763,8 +970,9 @@ iteration:
   score: <compact score object>
 selected_premise: <premise or none>
 selected_hook: <hook>
-pre_draft_structure_brief: <compact structure summary or none>
+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

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

@@ -88,11 +88,15 @@ Draft files must preserve:
   - score fields for hook, proof, voice, specificity, skimmability, and publish confidence
   - `verdict`: `baseline`, `keep`, `revise`, `reject`, `publish_candidate`, or a similarly explicit state
 - draft body
-- pre-draft structure brief: hook, thesis, reader, core mechanism, key
-  definitions, proof claims, mobile scan path, section outline, body promise,
-  concrete examples, abstractions to remove, and draft risks
+- 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

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

@@ -11,13 +11,17 @@ Every saved draft needs a validation receipt. A draft without this receipt is no
 - `candidateHooksConsidered`
 - `selectedHook`
 - `selectedHookWhy`
-- `preDraftStructureBrief`
+- `preDraftNarrativeOutline`
+- `preDraftStructureBrief` as a legacy compatibility alias when older drafts or
+  downstream readers still expect it
 - `selectedSourceTemplate`
 - `postPositioningBreakdown`
 - `viralPostOutline`
 - `hookToBodyPromiseMap`
 - `bodyExpressionCandidates`
 - `combinedBodyPlan`
+- `visibleFlowTrace` when the user asked for whole-flow, debug, or
+  step-by-step mode
 - `proofClaimsUsed`
 - `proofClaimSources`
 - `storyFilesConsulted`
@@ -117,6 +121,39 @@ After the first draft:
 10. remove AI tells
 11. re-check LinkedIn preview fit after edits
 
+## Visible Flow Trace Audit
+
+When the user asks to see the whole flow, run the process step by step, validate
+that it is working, or debug a bad output, the validation receipt must preserve a
+`visibleFlowTrace`.
+
+Record:
+
+- `mode`: visible_whole_flow_debug
+- `checkpointStatuses`: each checkpoint marked `pass`, `weak`, `fail`, or
+  `blocked`
+- `checkpointOutputs`: the concrete output shown to the user for each
+  checkpoint
+- `qualityBreak`: the first checkpoint that made the draft weak, if any
+- `downstreamEffect`: how that break affected the hook, premise, body, or ready
+  status
+- `userVisibleBeforeSave`: yes | no
+- `draftSavedDespiteWeakness`: yes | no
+- `reasonDraftSaved`: why a `needs_revision` draft was still worth saving, if
+  it was saved
+
+Save as `needs_revision` when:
+
+- the trace was not shown before draft prose in visible debug mode
+- the body-expression lab was summarized after the fact instead of generating
+  real candidates before prose
+- a weak premise, missing proof, or wrong source template produced a bad body
+- the final response claims the workflow worked only because artifacts were
+  saved
+
+Do not mark a run successful unless the visible trace, final draft, and saved
+receipt all agree on the same quality state.
+
 ## Premise Value Audit
 
 Before a draft can be `ready`, validate that the post is valuable, not just
@@ -133,11 +170,14 @@ Record:
 - `readerValue`: what the reader learns, sees differently, or can do
 - `proofAvailable`: source-backed proof used
 - `proofMissing`: claims intentionally avoided or requiring user input
-- `preDraftStructureBrief`: hook, thesis, reader, core mechanism, definitions,
-  proof claims, mobile scan path, section outline, and abstractions to remove
+- `preDraftNarrativeOutline`: hierarchical `I.`, `A.`, `i.` outline showing
+  hook debt, thesis, operating model, working body patterns adapted, narrative
+  beats, scan path, proof claims, and abstractions to remove
+- `preDraftStructureBrief`: legacy compatibility alias only; the canonical
+  artifact is `preDraftNarrativeOutline`
 - `premiseQualityGates`: pass/fail for `specific_scene_or_pattern`,
   `clear_reader`, `visible_tension`, `reader_value`, `credible_speaker`,
-  `proof_safety`, `market_heat`, and `pre_draft_structure`
+  `proof_safety`, `market_heat`, and `pre_draft_narrative_outline`
 - `bodyOutline`: how the body delivers the premise before prose
 - `viralPostOutline`: the selected narrative structure, including beat jobs
 - `hookToBodyPromiseMap`: how the body repays the hook's open loop
@@ -147,10 +187,10 @@ If the draft has no specific scene or observed pattern, no visible tension, or
 no reader value beyond "this is interesting," save as `needs_revision`. Do not
 mark it `ready` because the hook passes preview limits.
 
-## Pre-Draft Structure Audit
+## Pre-Draft Narrative Outline Audit
 
-Before a draft can be `ready`, validate that the structure was locked before the
-body was written.
+Before a draft can be `ready`, validate that the narrative outline was locked
+before the body was written.
 
 Record:
 
@@ -162,16 +202,24 @@ Record:
   could misunderstand
 - `proofClaims`: claims, sources, and public-safety status
 - `sourceTemplateOrNoTemplateRationale`
+- `workingBodyPatternsAdapted`: body pattern name, beat order, why it worked,
+  what gets borrowed, and what must not be copied
+- `hierarchicalNarrativeBeats`: `I.`, `A.`, `i.` outline of the final post's
+  argument, examples, proof, and line/section shapes
 - `mobileScanPath`: what a skimmer understands from the hook, separators,
   section labels, numbers, and close
-- `sectionOutline`: section order plus the job of each section
+- `sectionOutline`: legacy summary of section order plus the job of each
+  section; do not substitute this for `hierarchicalNarrativeBeats`
 - `bodyPromiseAfterSeeMore`: what the body immediately repays
 - `abstractionsToRemove`: abstract phrases and their concrete replacements
-- `userCorrectionsApplied`: user corrections applied to the brief before prose
-
-Save as `needs_revision` when the draft was written before the structure brief,
-when the brief does not match the final prose, when the mobile scan path is
-unclear, or when key terms are left abstract.
+- `userCorrectionsApplied`: user corrections applied to the outline before
+  prose
+
+Save as `needs_revision` when the draft was written before the narrative
+outline, when the outline is a flat checklist instead of hierarchical
+`I.`, `A.`, `i.` notation, when the outline does not match the final prose, when
+working body patterns are unnamed or vaguely borrowed, when the mobile scan path
+is unclear, or when key terms are left abstract.
 
 ## Mobile Scanability Audit
 

package/skills/create-post/references/premise-development.md

@@ -280,71 +280,77 @@ why_this_combination_wins:
 If no candidate repays the hook promise with real user proof, return to premise
 development or ask the user for the missing story. Do not save a `ready` draft.
 
-## Pre-Draft Structure Brief
+## Pre-Draft Narrative Outline
 
-Before final prose, produce a compact `Pre-Draft Structure Brief`. This is the
-user-visible outline that lets the user confirm the post is teaching the right
-operating lesson before the system writes body copy.
+Before final prose, produce a compact `Pre-Draft Narrative Outline`. This is the
+user-visible argument skeleton that lets the user confirm what the post is
+trying to say, in what order, and which proven body shapes are being adapted
+before the system writes body copy.
 
 Use this format:
 
 ```text
-Pre-Draft Structure Brief
-hook:
-<selected hook with rendered mobile preview verdict>
-
-thesis:
-<one sentence the post will defend>
-
-reader being taught:
-<specific audience, not "founders" unless narrowed>
-
-why this reader cares now:
-<timely pain, belief, or decision>
-
-core equation or mechanism:
-<the operating model the post teaches>
-
-key definitions:
-- <term>: <plain definition + concrete examples>
-
-proof claims:
-- <claim>: <source + public-safety status>
-
-source template or no-template rationale:
-<template name or why the post should use a plain field-guide structure>
-
-mobile scan path:
-<what a skimmer understands from hook, separators, labels, numbers, and close>
-
-section outline:
-1. <section job>
-2. <section job>
-3. <section job>
-
-body promise after see more:
-<what the body must repay immediately>
-
-concrete examples to include:
-- <example, number, source, or phrasing>
-
-abstractions to remove:
-- <abstract phrase> -> <concrete replacement>
-
-draft risks:
-- <risk and how to avoid it>
+Pre-Draft Narrative Outline
+I. Hook and click debt
+   A. Selected hook: <selected hook>
+   B. Rendered mobile preview verdict: <pass | warn | fail + why>
+   C. What "see more" must repay: <the open loop the first body beat must answer>
+
+II. Thesis the post will defend
+   A. One-sentence thesis: <the post's operating claim>
+   B. Reader being taught: <specific audience, not a broad persona>
+   C. Why this reader cares now: <timely pain, belief, or decision>
+
+III. Operating model
+   A. Core equation or mechanism: <the model the post teaches>
+   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: <source or 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: <how it will appear>
+      ii. Concrete examples: <examples/numbers>
+   B. Beat 2: <job, reader state before/after, example/proof>
+      i. Line shape or section label: <how it will appear>
+      ii. Concrete examples: <examples/numbers>
+   C. Beat 3: <job, reader state before/after, example/proof>
+      i. Line shape or section label: <how it will appear>
+      ii. Concrete examples: <examples/numbers>
+
+VI. Scan path and proof safety
+   A. Mobile scan path: <what skimmers learn from labels/numbers/close>
+   B. Proof claims:
+      i. <claim>: <source + public-safety status>
+   C. Abstractions to remove:
+      i. <abstract phrase> -> <concrete replacement>
+   D. Draft risks: <risk and how to avoid it>
 ```
 
 Quality gate:
 
-- The brief must explain the post before the draft exists.
-- The brief must be useful to a reader who only scans the finished post.
-- The brief must include proof claims and risk before prose.
-- The brief must define any operating terms that could be misunderstood.
-- If the post is a field guide, the section outline must show the hierarchy
+- The outline must explain the post before the draft exists.
+- The outline must be useful to a reader who only scans the finished post.
+- The outline must include proof claims and risk before prose.
+- The outline must define any operating terms that could be misunderstood.
+- The outline must use `I.`, `A.`, and `i.` hierarchy. A flat field list fails.
+- If the post is adapting bodies that worked, the outline must name the body
+  pattern and what beat order, proof order, or transition logic is being
+  borrowed.
+- If the post is a field guide, the narrative beats must show the hierarchy
   before prose, such as best-to-worst, highest-to-lowest intent, or
   source-to-outcome.
-- If the brief cannot be made concrete, return to premise development.
+- If the outline cannot be made concrete, return to premise development.
 
 ## Premise Quality Gate
 
@@ -359,7 +365,7 @@ A premise can move to hook generation only when it passes all of these:
 - `market_heat`: pass or explained
 - `template_fit`: pass or explicitly no-template
 - `hook_to_body_repayment`: pass
-- `pre_draft_structure`: pass
+- `pre_draft_narrative_outline`: pass
 
 If any gate fails: