@sellable/mcp 0.1.240 → 0.1.243

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

@@ -31,6 +31,7 @@ Customer computer owns:
       research_YYYYMMDD_slug.md
   drafts/
     draft_YYYYMMDD_slug_v1.md
+    draft_YYYYMMDD_slug_v2.md
   published/
     YYYY/
       post_linkedinActivityId.md
@@ -69,10 +70,26 @@ Draft files must preserve:
 
 - source idea ID
 - hook research ID
+- versioned draft ID, normally ending in `_v1`, `_v2`, `_v3`, etc.
+- iteration metadata when there is a prior or baseline draft:
+  - `version`
+  - `priorDraftId`
+  - `changeIntent`
+  - `whatChanged`
+  - `whatImproved`
+  - `whatGotWorse`
+  - 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
 - validation receipt, including LinkedIn preview pass/warn/fail status and
   compact fallback when the selected hook carries a warning
-- status: `draft`, `ready`, or `needs_revision`
+- status: `draft`, `ready`, `needs_revision`, `published`, or `archived`
+
+Multiple drafts for the same idea are expected. Keep the `ideaId` stable and
+create a new versioned `draftId` for each materially different attempt. Do not
+overwrite a prior version just to compare alternatives. Use
+`update_post_draft` only for same-version receipt fixes, status changes, or
+copy edits that should remain part of that version.
 
 Published files must preserve:
 
@@ -80,7 +97,12 @@ Published files must preserve:
 - publish URL
 - LinkedIn activity ID when available
 - published date
-- optional future metrics placeholders
+- future metrics placeholders and appended metric snapshots when available
+
+When a draft is published, `mark_post_published` records the published post
+separately and marks the source draft as `published` by default. Use
+`update_published_post_metrics` to append later performance snapshots instead
+of editing the draft.
 
 ## Safety
 

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

@@ -6,6 +6,8 @@ Every saved draft needs a validation receipt. A draft without this receipt is no
 
 - `sourceIdeaId`
 - `hookResearchId`
+- `iteration`
+- `selectedPremiseCard`
 - `candidateHooksConsidered`
 - `selectedHook`
 - `selectedHookWhy`
@@ -14,6 +16,8 @@ Every saved draft needs a validation receipt. A draft without this receipt is no
 - `storyFilesConsulted`
 - `goldStandardsConsulted`
 - `voiceRulesApplied`
+- `marketBeliefAudit`
+- `premiseValueAudit`
 - `linkedinPreviewAudit`
 - `simplifierConcreteLanguageAudit`
 - `antiAiAudit`
@@ -23,6 +27,45 @@ Every saved draft needs a validation receipt. A draft without this receipt is no
 - `retryNeededReasons`
 - `readyStatus`
 
+## Iteration Receipt
+
+Every saved draft needs iteration metadata, even the first draft. This lets the
+content library show whether later drafts are actually improving.
+
+For the first ready draft of an idea, record:
+
+- `version: v1`
+- `priorDraftId: none`
+- `iterationRole: baseline`
+- `changeIntent`
+- `score`
+- `verdict`
+- `nextIterationTargets`
+
+For later drafts, record:
+
+- `version`
+- `priorDraftId`
+- `changeIntent`
+- `whatChanged`
+- `whatImproved`
+- `whatGotWorse`
+- `score`
+- `verdict`
+
+Use a score object with at least:
+
+- `hook`
+- `proof`
+- `voice`
+- `specificity`
+- `skimmability`
+- `publishConfidence`
+
+Do not call a later draft better just because it is newer. If the hook is
+stronger but proof, voice, or clarity got worse, say that in `whatGotWorse` and
+set the verdict to `revise` or `reject`.
+
 ## Candidate Set
 
 Generate multiple hook candidates before drafting. Do not lock onto the first draft.
@@ -30,6 +73,9 @@ Generate multiple hook candidates before drafting. Do not lock onto the first dr
 Each candidate should include:
 
 - hook text
+- selected premise
+- premise tension opened
+- reader value implied
 - source pattern
 - score
 - char count including newlines and first-line / first-two-line preview measurements
@@ -45,12 +91,61 @@ Each candidate should include:
 After the first draft:
 
 1. remove unsupported claims
-2. tighten the hook
-3. simplify abstract phrasing
-4. replace generic language with concrete words only when supported
-5. preserve the user's actual story and point
-6. remove AI tells
-7. re-check LinkedIn preview fit after edits
+2. verify the draft is anchored to the selected market belief and controversy
+3. verify the real story/scene, tension, and reader value are visible early
+4. tighten the hook
+5. simplify abstract phrasing
+6. replace generic language with concrete words only when supported
+7. preserve the user's actual story and point
+8. remove AI tells
+9. re-check LinkedIn preview fit after edits
+
+## Premise Value Audit
+
+Before a draft can be `ready`, validate that the post is valuable, not just
+well wrapped.
+
+Record:
+
+- `premise`: the selected premise in one sentence
+- `realStoryOrScene`: the concrete scene, observation, or pattern used
+- `targetReader`: who should care
+- `commonBelief`: the belief the post argues against
+- `contrarianTruth`: the sharper belief the post offers
+- `visibleTension`: the uncomfortable gap or cost
+- `readerValue`: what the reader learns, sees differently, or can do
+- `proofAvailable`: source-backed proof used
+- `proofMissing`: claims intentionally avoided or requiring user input
+- `premiseQualityGates`: pass/fail for `specific_scene_or_pattern`,
+  `clear_reader`, `visible_tension`, `reader_value`, `credible_speaker`,
+  `proof_safety`, and `market_heat`
+- `bodyOutline`: how the body delivers the premise before prose
+
+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.
+
+## Market Belief Audit
+
+Before a draft can be `ready`, validate that it is not merely an internally
+coherent idea. It must be anchored to the saved research's market belief map.
+
+Record:
+
+- `resonatingIdea`: the current-space idea this draft enters
+- `implicitBelief`: the belief the audience likely already holds
+- `audienceWant`: what the audience wants permission, leverage, proof, or a new
+  category for
+- `audienceResentmentOrFear`: what frustration or risk gives the post tension
+- `selectedControversy`: the claim the post is testing
+- `credibleWhyUs`: why the user can credibly say this from raw idea, memory,
+  story, proof, or product mechanism
+- `engagementReason`: why someone would react, comment, repost, or argue
+- `unsupportedHypeRemoved`: unsupported claims removed during finalizer
+
+If `selectedControversy` is missing, if the audience belief is only a generic
+label like "founders want growth," or if `credibleWhyUs` depends on borrowed
+proof from another creator, save as `needs_revision`.
 
 ## LinkedIn Preview Audit
 

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

@@ -0,0 +1,159 @@
+# Premise Development
+
+A strong post is not an idea with a better hook. A strong post is a valuable
+premise wrapped in a sharp opening.
+
+Use this stage after market/hook research and before hook candidates. Do not
+generate hook candidates until at least one `Premise Card` exists.
+
+## Goal
+
+Turn the raw idea into a real story, observed tension, or useful argument that a
+specific reader would care about.
+
+The premise must answer:
+
+- who this is for
+- what real scene, observation, or pattern created the idea
+- what tension makes it worth reading
+- what common belief it argues against
+- what hidden truth or mechanism it reveals
+- what value the reader gets
+- why now
+- why this user can credibly say it
+- what proof is available and what proof is missing
+
+If the premise has no real scene, no tension, and no reader value, stop before
+drafting. Ask for the missing story or save only a `needs_revision` premise
+artifact. Do not compensate with clever hooks.
+
+## Real Story / Scene Search
+
+Before writing premise cards, search the available source material:
+
+- raw idea text
+- voice memo or transcript if provided
+- `core/story-bank.md`
+- `core/answer-bank.md`
+- `core/proof-ledger.md`
+- `core/wins-ledger.md`
+- approved references and gold standards
+- current-session user corrections or rejections
+
+Look for:
+
+- a moment: "I saw X", "a founder said Y", "I opened Z and noticed..."
+- a contradiction: the user wanted one thing but the workflow rewarded another
+- a cost: time, attention, trust, missed learning, reputation, money
+- a before/after: what changed in the user's belief
+- a specific object: Slack note, customer call, campaign table, reply, list,
+  demo, failed draft, stale idea, messy workflow
+
+If no real story is present, use an observed pattern only if it is traceable to
+the raw source or memory. Mark the gap in the premise card. Do not fabricate a
+customer, call, outcome, date, metric, or private scene.
+
+## Premise Cards
+
+Generate 3-5 premise cards before hooks. Each card must use this shape:
+
+```text
+Premise Card
+
+premise:
+<one-sentence argument>
+
+real story / scene:
+<specific moment, observation, or pattern from source/memory>
+
+target reader:
+<who should care>
+
+common belief:
+<what the reader or market usually believes>
+
+contrarian truth:
+<what this post argues instead>
+
+tension:
+<why this is uncomfortable, costly, or worth arguing about>
+
+reader value:
+<what the reader learns, sees differently, or can do after reading>
+
+why now / market heat:
+<what current research says is resonating>
+
+credible why-us:
+<why this user can say it from source, memory, proof, or product mechanism>
+
+proof available:
+<specific usable proof or source>
+
+proof missing:
+<claims that cannot be made yet>
+
+best frame:
+story | contrarian take | teardown | founder confession | future thesis | lesson
+
+hook territories:
+- <territory 1>
+- <territory 2>
+- <territory 3>
+
+risk:
+<why this premise might still be weak>
+
+score:
+<1-100 with short reason>
+```
+
+## Premise Quality Gate
+
+A premise can move to hook generation only when it passes all of these:
+
+- `specific_scene_or_pattern`: pass
+- `clear_reader`: pass
+- `visible_tension`: pass
+- `reader_value`: pass
+- `credible_speaker`: pass
+- `proof_safety`: pass
+- `market_heat`: pass or explained
+
+If any gate fails:
+
+- in research checkpoint mode, show the cards and ask for the missing story or
+  direction
+- in immediate draft mode, save the draft as `needs_revision`, not `ready`
+- never mark a draft `ready` because the hook is clever
+
+## Hook Relationship
+
+Hooks are generated from the selected premise, not from the raw idea alone.
+
+For each hook candidate, include:
+
+- selected premise ID or title
+- which tension it opens
+- which reader value it implies
+- whether the real scene appears in the first screen or shortly after
+
+Reject hooks that are accurate but do not reveal the premise's tension or value.
+
+## Body Relationship
+
+Before drafting prose, create a short body outline for the selected premise:
+
+```text
+body outline:
+1. hook stack opens the tension
+2. real scene or pattern makes it concrete
+3. common belief gets named
+4. contrarian truth lands
+5. mechanism explains why
+6. reader value becomes clear
+7. close returns to the premise without summarizing
+```
+
+If this outline cannot be filled without inventing proof, return to premise
+development.

package/skills/engage/SKILL.md

@@ -359,6 +359,7 @@ Use the smallest relevant core target:
 - `core/decision-rules.md` for durable strategy rules, public/private safety rules, and correction heuristics.
 - `core/change-log.md` for every approved correction, rejected proposal worth remembering, private mark, and downstream prompt/operator note.
 - `core/transcripts/INDEX.md` plus a topic file under `core/transcripts/topics/` for topic-specific interview snippets or unused material that should stay transcript-first.
+- `core/content-memory/INDEX.md` plus cluster/card files for recurring content ideas, post seeds, proof gaps, and transcript-derived story material that should evolve over time.
 - `core/references/linkedin-posts/INDEX.md` or another `core/references/**/INDEX.md` when an approved comment/post example should become a reference artifact.
 
 Write-backs must be idempotent: use stable source keys such as `engage-session:{date}:{senderId}:{postUrlHash}:{slug}`, check copied paths before adding references, create no duplicate reference rows, and keep manual sections preserved. If the user marks a candidate private, store only the minimum private-safe metadata and do not promote it into public proof, references, or examples.

package/skills/engage/core/README.md

@@ -6,23 +6,26 @@ Engage memory lives in the home-level `~/.sellable/configs/` source of truth. Th
 
 | Data            | Config File                                                                       | MCP Tool                                             |
 | --------------- | --------------------------------------------------------------------------------- | ---------------------------------------------------- |
-| Core identity   | `~/.sellable/configs/core/about-me.md`                                              | `get_engage_memory`                                  |
-| Company truth   | `~/.sellable/configs/core/my-company.md`                                            | `get_engage_memory`                                  |
-| Anti-AI rules   | `~/.sellable/configs/core/anti-ai-writing-style.md`                                 | `get_engage_memory`                                  |
+| Core identity   | `~/.sellable/configs/core/about-me.md`                                             | `get_engage_memory`                                  |
+| Company truth   | `~/.sellable/configs/core/my-company.md`                                           | `get_engage_memory`                                  |
+| Anti-AI rules   | `~/.sellable/configs/core/anti-ai-writing-style.md`                                | `get_engage_memory`                                  |
 | Proof/wins      | `~/.sellable/configs/core/proof-ledger.md`, `~/.sellable/configs/core/wins-ledger.md` | `get_engage_memory`                                  |
-| Stories/answers | `~/.sellable/configs/core/story-bank.md`, `~/.sellable/configs/core/answer-bank.md`   | `get_engage_memory`                                  |
-| Context modes   | `~/.sellable/configs/core/context-modes.md`                                         | `get_engage_memory`                                  |
-| Style override  | `~/.sellable/configs/writing/styleguide-core.md` or sender override                 | `get_engage_memory` / `set_engage_style_guide`       |
-| Comment rules   | `~/.sellable/configs/writing/comments.md`                                           | (read via `get_engage_memory`)                       |
-| Proven searches | `~/.sellable/configs/discovery/proven-searches.md`                                  | `get_engage_memory` / `record_engage_proven_search`  |
-| Tracked people  | `~/.sellable/configs/discovery/influencers.md`                                      | `get_engage_memory` / `upsert_engage_tracked_person` |
-| Post filters    | `~/.sellable/configs/discovery/post-filters.md`                                     | (read by skill via Read tool)                        |
-| ICP             | `~/.sellable/configs/audience/icp.md`                                               | (read by skill via Read tool)                        |
+| Stories/answers | `~/.sellable/configs/core/story-bank.md`, `~/.sellable/configs/core/answer-bank.md` | `get_engage_memory`                                  |
+| Transcripts     | `~/.sellable/configs/core/transcripts/**`                                          | `get_engage_memory`                                  |
+| Content memory  | `~/.sellable/configs/core/content-memory/**`                                       | `get_engage_memory`                                  |
+| Context modes   | `~/.sellable/configs/core/context-modes.md`                                        | `get_engage_memory`                                  |
+| Style override  | `~/.sellable/configs/writing/styleguide-core.md` or sender override                | `get_engage_memory` / `set_engage_style_guide`       |
+| Comment rules   | `~/.sellable/configs/writing/comments.md`                                          | (read via `get_engage_memory`)                       |
+| Proven searches | `~/.sellable/configs/discovery/proven-searches.md`                                 | `get_engage_memory` / `record_engage_proven_search`  |
+| Tracked people  | `~/.sellable/configs/discovery/influencers.md`                                     | `get_engage_memory` / `upsert_engage_tracked_person` |
+| Post filters    | `~/.sellable/configs/discovery/post-filters.md`                                    | (read by skill via Read tool)                        |
+| ICP             | `~/.sellable/configs/audience/icp.md`                                              | (read by skill via Read tool)                        |
 
 ## How Skills Update Configs
 
 - **Interview skill**: Populates primary `configs/core/**` identity/company memory, transcript references, answer bank, proof/wins ledgers, and anti-AI rules.
-- **Engage skill**: Reads composed core memory through `get_engage_memory`, updates proven searches after each session, adds new tracked people when discovered, and writes legacy sender style overrides only when the correction is engage-specific.
+- **Engage skill**: Reads composed unified memory through `get_engage_memory`, updates proven searches after each session, adds new tracked people when discovered, and writes legacy sender style overrides only when the correction is engage-specific.
+- **Create-post skill**: Reads the same unified memory, including `core/content-memory/**`, before drafting from transcripts, recurring ideas, or post seeds.
 
 ## Migration from JSON