@officexapp/vidfarm-devcli 0.21.42 → 0.21.45

package/dist/src/devcli/consult.js

@@ -0,0 +1,403 @@
+// KEYLESS LOCAL CONSULTATION — the brainstorm chain with no AI key and no wallet.
+//
+// The cloud runs the consultation as five `brainstorm/*` primitives: Vidfarm
+// sends a prompt to a provider on the director's saved key, or bills the wallet.
+// That is a hard stop for a director who has neither.
+//
+// But an agent is ALREADY driving this terminal, and it is a frontier model. It
+// does not need Vidfarm to broker a second one. So this module hands that agent
+// the SAME prompt the cloud primitive would have sent — imported from
+// services/brainstorm-prompts.ts, not re-written here, so the two paths cannot
+// drift — and tells it to answer the prompt itself and save the artifact. Cost:
+// $0. Network calls: none. Provider keys: none.
+//
+// The one real difference from the cloud path is the reference documents. The
+// cloud appends SELLING_WITH_HOOKS.md / SELLING_AWARENESS_STAGES.md (34KB of
+// lessons) to the prompt. Inlining those into every terminal print would burn
+// ~10k tokens of the agent's context per step, so by default the brief POINTS at
+// the skill pack's own tighter reference instead. `--refs` inlines the full
+// documents for parity when the caller wants it.
+//
+// Pure string assembly plus one small offer-file lookup. No network, no backend.
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { buildAnglesPrompt, buildAwarenessStagesPrompt, buildColdstartPrompt, buildHooksPrompt, buildProductPlacementPrompt } from "../services/brainstorm-prompts.js";
+export const CONSULT_STEPS = ["coldstart", "awareness", "angles", "hooks", "placement"];
+/** Aliases a director or an agent actually types. */
+const STEP_ALIASES = {
+    coldstart: "coldstart",
+    "cold-start": "coldstart",
+    interview: "coldstart",
+    questions: "coldstart",
+    offer: "coldstart",
+    awareness: "awareness",
+    "awareness-stages": "awareness",
+    awareness_stages: "awareness",
+    stages: "awareness",
+    angles: "angles",
+    angle: "angles",
+    hooks: "hooks",
+    hook: "hooks",
+    placement: "placement",
+    "product-placement": "placement",
+    product_placement: "placement"
+};
+export function resolveConsultStep(raw) {
+    return STEP_ALIASES[raw.trim().toLowerCase().replace(/\s+/g, "-")] ?? null;
+}
+/** Where each step's answer belongs. These filenames are the ones the skill's
+ *  onboarding flow already names, so a later step can read the earlier one. */
+export const CONSULT_ARTIFACTS = {
+    coldstart: "OFFER.md",
+    awareness: "awareness-levels.md",
+    angles: "persuasive-angles.md",
+    hooks: "ad-hooks.md",
+    placement: "product-placement.md"
+};
+const STEP_ORDER = ["coldstart", "awareness", "angles", "hooks"];
+/**
+ * The durable local answer file. OFFER.md is the polished product description;
+ * this is the raw carry-over — what the director said, which stage was chosen,
+ * what was ruled out — so a LATER session (a new terminal, a new agent, a month
+ * from now) starts warm instead of re-interviewing a director who already
+ * answered. It lives in the working folder next to the other artifacts.
+ */
+export const CONSULT_CONTEXT_FILE = "CONTEXT.md";
+/**
+ * CONTENT IDEAS COME BEFORE THE INTERVIEW.
+ *
+ * An interview asks the director to work before they have seen anything, which
+ * is the worst trade a first session can offer. `vidfarm ideas --topic "<their
+ * offer in a line>"` inverts it: one sentence in, 20+ titled video ideas out,
+ * offline and free. The director gets a win first, and the ideas they react to
+ * ("this one, not that one") are better interview answers than the ones they
+ * would have typed cold. So every interview brief opens by offering the ideas
+ * pass, and the interview becomes the thing they opt INTO once they want depth.
+ */
+const IDEAS_FIRST = 'START WITH CONTENT IDEAS, NOT THIS INTERVIEW, unless the director already ran them or explicitly asked for a consultation. Get their offer in ONE line, run `vidfarm ideas --topic "<that line>"`, sharpen the frames into 20+ real titles and save `content-ideas.md`. It is offline, free, and gives them something to react to. Then say the interview is available when they want the strategy behind the ideas — and run it now only if they say yes.';
+/**
+ * The SHORT interview. The full cold-start prompt asks a model to invent 12-30
+ * questions; that is the right depth for a director who wants a real strategy
+ * session, and far too much for one who wants to make a video today. These six
+ * are fixed, not generated: they are the minimum set the later steps actually
+ * read back (awareness needs the offer + the psyche, angles and hooks quote the
+ * pain and desire verbatim). Fixed also means free, instant, and identical every
+ * run, which is what makes the answers worth saving.
+ */
+export const SHORT_INTERVIEW = [
+    {
+        question: "In one line, what do you sell, and to whom?",
+        why_it_matters: "Every later step opens with this line. Without it there is no offer to consult on."
+    },
+    {
+        question: "What does it cost, and how does someone actually pay (appstore, Stripe, Shopify, invoice, sales call)?",
+        why_it_matters: "Price and checkout friction decide whether an ad can close or only warm up."
+    },
+    {
+        question: "Who is the single best customer you have had? Describe them like a person, not a segment.",
+        why_it_matters: "Angles are written to one person. A segment produces generic ads."
+    },
+    {
+        question: "What do they complain about, in their own words, before they find you?",
+        why_it_matters: "Hooks quote this back verbatim. Paraphrase kills it."
+    },
+    {
+        question: "What do they want instead — the dream outcome they would brag about?",
+        why_it_matters: "The payoff half of every hook, and the reason to keep watching."
+    },
+    {
+        question: "Do they already know this kind of product exists, or have they never heard of it?",
+        why_it_matters: "This is the awareness stage in plain language, and it decides which ad to make first."
+    }
+];
+/** The short interview rendered as the brief's prompt block. Fixed text — there
+ *  is no cloud counterpart, so nothing here can drift from a cloud prompt. */
+export function buildShortInterviewPrompt() {
+    return [
+        "SHORT-FORM COLD START — a fixed six-question interview. Ask these exact questions. Do not generate your own set.",
+        "",
+        ...SHORT_INTERVIEW.map((q, i) => `${i + 1}. ${q.question}\n   (why it matters: ${q.why_it_matters})`),
+        "",
+        "Say up front that every question is optional: the director can skip any of them, or stop the interview at any point, and you will work with what they gave.",
+        "Assemble the answers into OFFER.md in the director's own words, then save the same answers to CONTEXT.md for future sessions. Mark anything skipped as UNKNOWN."
+    ].join("\n");
+}
+/** The skill-pack reference each step should be graded against locally, in place
+ *  of the big SELLING_*.md document the cloud prompt inlines. */
+const STEP_REFERENCE = {
+    awareness: "references/onboarding.md",
+    angles: "references/onboarding.md",
+    hooks: "references/hooks-and-virality.md"
+};
+// Count bounds MIRROR the cloud primitive payload schemas on purpose. The local
+// path has no schema to satisfy, but a director who tunes --count here and then
+// moves the same chain to the cloud should not hit a 400 they never saw locally.
+// `awareness` returns one markdown recommendation, so it has no count at all.
+const COUNTS = {
+    coldstart: { default: 12, min: 7, max: 30 },
+    awareness: null,
+    angles: { default: 12, min: 1, max: 50 },
+    hooks: { default: 12, min: 1, max: 50 },
+    placement: { default: 8, min: 3, max: 30 }
+};
+export function consultCountRange(step) {
+    return COUNTS[step];
+}
+export function defaultConsultCount(step) {
+    return COUNTS[step]?.default ?? 0;
+}
+export function offerPathCandidates(dir, explicit) {
+    const fromCwd = path.resolve(explicit);
+    const fromDir = path.resolve(dir, explicit);
+    return fromCwd === fromDir ? [fromCwd] : [fromCwd, fromDir];
+}
+export function resolveOfferPath(dir, explicit) {
+    return offerPathCandidates(dir, explicit).find((candidate) => existsSync(candidate)) ?? null;
+}
+/**
+ * Does this --offer value read as a PATH the caller expected to exist, rather
+ * than the offer text itself? Load-bearing: without it, a mistyped path is
+ * silently consulted on as if the filename were the product description, and
+ * the director gets twelve hooks about "./OFFER_ACME.md".
+ */
+export function looksLikeOfferPath(value) {
+    const trimmed = value.trim();
+    return !trimmed.includes("\n") && (/^[.~/]/.test(trimmed) || /\.(md|txt)$/i.test(trimmed));
+}
+/**
+ * Find the director's offer document. Prefers an explicit path, then OFFER.md,
+ * then a single OFFER_<NAME>.md — a director running several offers must name
+ * which one, because silently picking the first alphabetically would generate a
+ * whole angle set for the wrong product.
+ */
+export function findOfferFile(dir, explicit) {
+    if (explicit) {
+        // Try cwd AND --dir: `--dir ./work --offer ./OFFER_ACME.md` names a file in
+        // the work directory, not next to the shell.
+        const resolved = resolveOfferPath(dir, explicit);
+        if (!resolved) {
+            return { error: `Offer file not found: ${offerPathCandidates(dir, explicit).join(" or ")}` };
+        }
+        return { path: resolved, text: readFileSync(resolved, "utf8") };
+    }
+    const root = path.resolve(dir);
+    const primary = path.join(root, "OFFER.md");
+    if (existsSync(primary)) {
+        return { path: primary, text: readFileSync(primary, "utf8") };
+    }
+    let named = [];
+    try {
+        named = readdirSync(root).filter((f) => /^OFFER_.+\.md$/i.test(f)).sort();
+    }
+    catch {
+        named = [];
+    }
+    if (named.length === 1) {
+        const only = path.join(root, named[0]);
+        return { path: only, text: readFileSync(only, "utf8") };
+    }
+    if (named.length > 1) {
+        return {
+            error: `Found ${named.length} offer files (${named.join(", ")}) — name the one you mean with --offer ./${named[0]}.`
+        };
+    }
+    return {
+        error: `No OFFER.md in ${root}. Run \`vidfarm consult coldstart\` first — it mints the interview that produces it — or pass --offer "<a paragraph about the offer>".`
+    };
+}
+function nextCommand(step) {
+    const i = STEP_ORDER.indexOf(step);
+    if (i === -1 || i === STEP_ORDER.length - 1) {
+        return null;
+    }
+    return `vidfarm consult ${STEP_ORDER[i + 1]}`;
+}
+/** The path the durable answer file takes, and whether it is already written. */
+export function consultContextState(dir) {
+    const relative = path.join(dir === "." ? "" : dir, CONSULT_CONTEXT_FILE) || CONSULT_CONTEXT_FILE;
+    return { file: relative, exists: existsSync(path.resolve(dir, CONSULT_CONTEXT_FILE)) };
+}
+/** Build the keyless local brief for one step of the chain. */
+export function buildConsultBrief(input) {
+    const dir = input.dir ?? ".";
+    const context = consultContextState(dir);
+    const short = Boolean(input.short) && input.step === "coldstart";
+    const artifact = path.join(dir === "." ? "" : dir, CONSULT_ARTIFACTS[input.step]) || CONSULT_ARTIFACTS[input.step];
+    const refs = input.references ?? {};
+    const count = input.count ?? defaultConsultCount(input.step);
+    const offer = (input.offer ?? "").trim();
+    const referenceFile = STEP_REFERENCE[input.step];
+    const inlined = (input.step === "hooks" && Boolean(refs.hooks)) ||
+        (input.step === "awareness" && Boolean(refs.awareness)) ||
+        (input.step === "angles" && Boolean(refs.hooks || refs.awareness));
+    const referenceHint = inlined || !referenceFile
+        ? null
+        : `The cloud prompt appends Vidfarm's full selling reference here. Read \`vidfarm skill show ${referenceFile}\` before you answer, and grade your own output against it. Pass --refs to inline the full document instead.`;
+    // The durable answer file is read BEFORE the step and written AFTER it. Both
+    // halves matter: reading stops a second session re-asking questions the
+    // director already answered, writing is what makes the next session cheap.
+    const contextRead = context.exists
+        ? `Read \`${context.file}\` first — it holds the answers this director already gave in earlier sessions. Treat it as fact, and never re-ask a question it already answers.`
+        : `No \`${context.file}\` yet. It is the durable answer file for this working folder; you create it in this step.`;
+    const contextWrite = `When you finish, write what you learned into \`${context.file}\` — the director's own words, the decisions made, and what was ruled out. Append under a dated heading; never overwrite an earlier session's answers. This file is why the next session does not start from zero.`;
+    const common = [
+        "YOU answer the prompt below — you are the AI in this loop. Do not call the Vidfarm API, do not look for a provider key, and do not tell the user they need one. This step is free and offline.",
+        contextRead,
+        ...(referenceHint ? [referenceHint] : []),
+        `Save your answer to \`${artifact}\`. Later steps read it back, so write the file even if the user only wanted to look at the output.`,
+        contextWrite
+    ];
+    const shared = { short, contextFile: context.file, contextExists: context.exists };
+    if (short) {
+        return {
+            ...shared,
+            step: "coldstart",
+            title: `Cold-start interview, SHORT FORM — ${SHORT_INTERVIEW.length} fixed questions`,
+            prompt: buildShortInterviewPrompt(),
+            steps: [
+                contextRead,
+                IDEAS_FIRST,
+                `Ask the human these ${SHORT_INTERVIEW.length} questions in two batches of three. Ask them as written. Do not add questions, do not invent answers, and do not skip ahead to advice.`,
+                `Keep their phrasing for the pain and the desire answers word for word: the angles and hooks steps quote them back, and a paraphrase is what makes an ad sound generic.`,
+                "TELL THEM UP FRONT that every question is optional: they can skip any one, or say stop and end the interview on the spot. Then work with whatever they gave — do not push, do not re-ask, and do not make finishing the set a condition of getting a video.",
+                `Write \`${artifact}\` from their answers, then write the same answers into \`${context.file}\` under a dated heading.`,
+                "Mark any question they skip as UNKNOWN in both files, and carry on. An invented customer psyche poisons every later step, so UNKNOWN is the honest answer — and a later step that needs it can ask then, when the director can see why it matters.",
+                "This is the short form. Tell them `vidfarm consult coldstart` runs the full interview when they want the deeper session."
+            ],
+            artifact,
+            next: nextCommand("coldstart"),
+            referenceHint: null
+        };
+    }
+    if (input.step === "coldstart") {
+        return {
+            ...shared,
+            step: "coldstart",
+            title: "Cold-start interview — the questions that produce OFFER.md",
+            prompt: buildColdstartPrompt(input.userMessage?.trim() || "The director asked for a consultation and has given no offer context yet.", count),
+            steps: [
+                ...common,
+                IDEAS_FIRST,
+                `This one is an INTERVIEW, not a report. Answer the prompt to get the question set, then ASK THE HUMAN those questions conversationally, a few at a time — never dump all ${count} at once, and never invent their answers.`,
+                `Assemble their real words into \`${artifact}\`: keep their phrasing for pain and desire, because the later angle and hook steps quote it back.`,
+                "Stop and wait for the human between batches. If they go quiet on a question, mark it UNKNOWN in the file rather than guessing — an invented customer psyche poisons every later step.",
+                "TELL THEM UP FRONT that every question is optional: they can skip any one, or say stop and end the interview at any point. Then work with what they gave. An interview that feels like a form is one the director abandons, and half the answers beats none.",
+                `If the director sounds impatient, or only wants to make one video today, offer the short form instead: \`vidfarm consult coldstart --short\` is ${SHORT_INTERVIEW.length} fixed questions and still feeds every later step.`
+            ],
+            artifact,
+            next: nextCommand("coldstart"),
+            referenceHint
+        };
+    }
+    if (input.step === "awareness") {
+        return {
+            ...shared,
+            step: "awareness",
+            title: "Awareness stages — which kind of ad to make first",
+            prompt: buildAwarenessStagesPrompt(offer, refs),
+            steps: [
+                ...common,
+                "Return markdown, not JSON. If the offer genuinely does not settle on one stage, say so and recommend testing ads for every stage rather than picking one to look decisive.",
+                "Carry the chosen stage forward: the angles step takes it as --problem-awareness / --solution-awareness."
+            ],
+            artifact,
+            next: nextCommand("awareness"),
+            referenceHint
+        };
+    }
+    if (input.step === "angles") {
+        return {
+            ...shared,
+            step: "angles",
+            title: "Persuasive angles — the strategic bets to test",
+            prompt: buildAnglesPrompt({
+                offer_description: offer,
+                problem_awareness: input.problemAwareness ?? "problem_aware",
+                solution_awareness: input.solutionAwareness ?? "solution_unaware",
+                count
+            }, refs),
+            steps: [
+                ...common,
+                "The prompt asks for strict JSON. Write the JSON answer into the markdown file under a fenced block, then a short human-readable list under it — the director reads the list, the next step reads the JSON.",
+                "Do not rank the set with the same reasoning that wrote it. If the director wants a ranking, grade against the reference and say what each angle risks."
+            ],
+            artifact,
+            next: nextCommand("angles"),
+            referenceHint
+        };
+    }
+    if (input.step === "hooks") {
+        return {
+            ...shared,
+            step: "hooks",
+            title: "Hooks — the openings to test",
+            prompt: buildHooksPrompt(offer, count, refs),
+            steps: [
+                ...common,
+                "The prompt asks for strict JSON. Write the JSON into the file under a fenced block, with a plain list under it.",
+                "Then GRADE the batch against the four charges before you show it: a hook is a complete clause naming a SITUATION, not a label; it must be unguessable; and it must be sayable in the first second. Cut or rewrite the ones that fail — do not hand over the raw generated list.",
+                "Never rank a generated batch with the reasoning that wrote it. The rubric catches defects; it does not pick winners."
+            ],
+            artifact,
+            next: nextCommand("hooks"),
+            referenceHint
+        };
+    }
+    const videoRef = input.videoRef?.trim();
+    return {
+        ...shared,
+        step: "placement",
+        title: "Product placement — native moments inside an existing video",
+        prompt: buildProductPlacementPrompt(offer, count),
+        steps: [
+            ...common,
+            videoRef
+                ? `The prompt says "the attached video" — that is \`${videoRef}\`. Watch it yourself before answering: read real frames (\`vidfarm stills ${videoRef} --sheet\` for a contact sheet) and the transcript. This step is worthless if you answer from the filename.`
+                : "The prompt says \"the attached video\" — you were given none. Ask the director for the video path or URL, then re-run with --video <path|url>. Do not answer from imagination.",
+            "Every opportunity must cite a moment you actually saw, with a timestamp. Drop any you cannot point at."
+        ],
+        artifact,
+        next: null,
+        referenceHint
+    };
+}
+/** Render a brief for a terminal. The prompt is delimited so an agent can lift
+ *  it exactly, and so a human can copy it into a chat window instead. */
+export function formatConsultBrief(brief, style = { bold: "", dim: "", reset: "" }) {
+    const { bold, dim, reset } = style;
+    const lines = [];
+    lines.push(`${bold}${brief.title}${reset}`);
+    lines.push(`${dim}Keyless + local: no provider key, no wallet, no network. You answer this.${reset}`);
+    lines.push("");
+    brief.steps.forEach((s, i) => lines.push(`${i + 1}. ${s}`));
+    lines.push("");
+    lines.push(brief.short
+        ? `${dim}─── the short-form question set (fixed and local — ask these as written) ───${reset}`
+        : `${dim}─── the prompt (identical to the cloud brainstorm primitive) ───${reset}`);
+    lines.push(brief.prompt);
+    lines.push(`${dim}───────────────────────────────────────────────────────────────${reset}`);
+    lines.push("");
+    lines.push(`Save to: ${brief.artifact}`);
+    lines.push(`Context: ${brief.contextFile}${brief.contextExists ? " (exists — read it first)" : " (create it)"}`);
+    if (brief.next) {
+        lines.push(`Next:    ${brief.next}`);
+    }
+    return lines.join("\n");
+}
+/** The whole chain plus which artifacts already exist, for a bare
+ *  `vidfarm consult`. A director who says "give me a consultation" gets the map
+ *  and the first command, not a wall of prompt. */
+export function planConsultation(dir) {
+    const root = path.resolve(dir);
+    return STEP_ORDER.map((step) => {
+        const file = CONSULT_ARTIFACTS[step];
+        const offerDone = step === "coldstart" && !("error" in findOfferFile(root));
+        return {
+            step,
+            artifact: file,
+            done: step === "coldstart" ? offerDone : existsSync(path.join(root, file)),
+            command: `vidfarm consult ${step}`
+        };
+    });
+}
+//# sourceMappingURL=consult.js.map

package/dist/src/devcli/skill-docs.js

@@ -108,7 +108,15 @@ export function readPackDoc(ref, name = DEFAULT_PACK) {
 }
 export const PACK_TOPICS = [
     { topic: "content-ideas", aliases: ["ideas", "idea", "angles", "what-to-post", "content"], doc: "references/content-ideas.md",
-        blurb: "The 50-frame angle bank — answer \"what should I post?\" for a whole month" },
+        blurb: "50 frames x 5 awareness stages x 44 problem angles — answer \"what should I post?\" for a whole month" },
+    // The other two idea axes get their own spoken names. A director asks "what
+    // is awareness again?" far more often than they ask for the content-ideas
+    // reference by file name, and sending them the whole 290-line doc for a
+    // 40-line answer is how a topic index fails.
+    { topic: "awareness", aliases: ["awareness-stages", "ladder", "stages", "schwartz"], doc: "references/content-ideas.md", heading: "The awareness ladder",
+        blurb: "The 5-stage ladder — what the viewer knows, what the video must do, and what it may ask for" },
+    { topic: "problem-angles", aliases: ["angle", "lenses", "problem-angle"], doc: "references/content-ideas.md", heading: "The problem angles",
+        blurb: "44 angles on the problem — hold the frame, change the angle when a topic is \"already covered\"" },
     { topic: "meme-recaption", aliases: ["meme", "recaption", "meme-caption"], doc: "references/editor-workflows.md", heading: "Writing a meme recaption",
         blurb: "Recaption a meme at a pain or a win the niche knows — the cold-viewer test" },
     { topic: "product-explainer", aliases: ["product-explainers"], doc: "harnesses/product-explainer.HARNESS.md",
@@ -188,10 +196,13 @@ export function readPackTopic(topic, name = DEFAULT_PACK) {
         return { doc, contents, whole: true };
     return { doc, heading: section.heading, contents: section.body, whole: false };
 }
-export function loadIdeaBank(name = DEFAULT_PACK) {
-    const { contents } = readPackDoc("references/content-ideas.md", name);
-    const section = extractSection(contents, "The 50 frames");
-    const lines = (section?.body ?? contents).split("\n");
+/**
+ * Shared shape for both bullet banks: a bold family label on its own line,
+ * then `- item` (frames) or `- item — note` (angles) bullets under it.
+ */
+function parseBulletBank(contents, heading, splitNote) {
+    const section = extractSection(contents, heading);
+    const lines = (section?.body ?? "").split("\n");
     const frames = [];
     const families = [];
     let family = "";
@@ -204,11 +215,54 @@ export function loadIdeaBank(name = DEFAULT_PACK) {
             continue;
         }
         const bullet = line.match(/^-\s+(.+?)\s*$/);
-        if (bullet && family)
-            frames.push({ frame: bullet[1].trim(), family });
+        if (!bullet || !family)
+            continue;
+        const text = bullet[1].trim();
+        if (!splitNote) {
+            frames.push({ frame: text, family });
+            continue;
+        }
+        const at = text.indexOf(" — ");
+        frames.push(at > 0
+            ? { frame: text.slice(0, at).trim(), family, note: text.slice(at + 3).trim() }
+            : { frame: text, family });
     }
     return { frames, families };
 }
+export function loadIdeaBank(name = DEFAULT_PACK) {
+    const { contents } = readPackDoc("references/content-ideas.md", name);
+    const parsed = parseBulletBank(contents, "The 50 frames", false);
+    // Old packs predate the section slice; fall back to the whole file rather
+    // than handing the CLI an empty bank.
+    return parsed.frames.length ? parsed : parseBulletBank(`## all\n${contents}`, "all", false);
+}
+/**
+ * The problem-angle bank — the SECOND axis of an idea. A frame says what the
+ * video is the story of; an angle says which side of the problem it approaches
+ * from. Holding the frame and changing the angle is the cheapest way to answer
+ * "I already covered that topic", so this has to be as reachable as the frames.
+ */
+export function loadAngleBank(name = DEFAULT_PACK) {
+    const { contents } = readPackDoc("references/content-ideas.md", name);
+    const { frames, families } = parseBulletBank(contents, "The problem angles", true);
+    return { angles: frames, families };
+}
+export function loadAwarenessLadder(name = DEFAULT_PACK) {
+    const { contents } = readPackDoc("references/content-ideas.md", name);
+    const section = extractSection(contents, "The awareness ladder");
+    const stages = [];
+    for (const line of (section?.body ?? "").split("\n")) {
+        const head = line.match(/^\*\*Stage\s+(\d+)\s*·\s*(.+?)\*\*\s*[—-]\s*(.+?)\s*$/);
+        if (head) {
+            stages.push({ index: Number(head[1]), stage: head[2].trim(), summary: head[3].trim(), fields: [] });
+            continue;
+        }
+        const field = line.match(/^-\s+\*\*(.+?):\*\*\s*(.+?)\s*$/);
+        if (field && stages.length)
+            stages[stages.length - 1].fields.push({ label: field[1].trim(), value: field[2].trim() });
+    }
+    return stages;
+}
 /**
  * Grep the pack. This is the affordance that makes a local copy genuinely
  * better than the network one: "where does it say anything about greenscreen"

package/dist/src/services/brainstorm-prompts.js

@@ -0,0 +1,132 @@
+// The brainstorm/consultation prompts — ONE source of truth for both runners.
+//
+// Two things run this chain and they must ask for the same thing:
+//
+//   1. The CLOUD primitives (`POST /api/v1/primitives/brainstorm/*`), which send
+//      the prompt to a provider on the user's saved key or the wallet.
+//   2. The KEYLESS LOCAL path (`vidfarm consult <step>`), which prints the same
+//      prompt for the agent already driving the terminal to answer itself. No
+//      provider key, no wallet, no network.
+//
+// If these two ever drift, a director gets a different consultation depending on
+// where they ran it — so the builders live here, pure, and both callers import
+// them. This module has NO backend imports and touches no filesystem: the big
+// reference documents are passed IN, because the cloud reads them off the
+// primitive asset directory and the CLI may not ship them at all.
+/** Drop the trailing "Reference lessons" block when no text was supplied, so a
+ *  keyless caller does not emit a dangling header with nothing under it. */
+function withReference(lines, header, text) {
+    if (!text || !text.trim()) {
+        return lines;
+    }
+    return [...lines, "", header, text];
+}
+export function buildHooksPrompt(offerDescription, count, refs = {}) {
+    return withReference([
+        "You are Vidfarm's elite paid-social hook strategist.",
+        "Your job is to generate high-upside ad hooks for TikTok-native creative.",
+        "Bias toward hooks that feel native to TikTok, but keep raw persuasive power more important than surface trendiness.",
+        "Max creativity. Do not hold back. Be as diverse as possible while staying relevant to the offer.",
+        "Use many angle families across the set: pain, status, curiosity, gossip, confession, myth-busting, shock, taboo, mechanism, objection, identity, urgency, pattern interrupt, transformation, proof, enemy, mistake, secret, social proof, aspiration, and contrarian frames.",
+        "Each hook should be sharp, testable, and materially different from the others.",
+        `Generate exactly ${count} hooks.`,
+        "Return strict JSON only with shape {\"hooks\":[{\"hook\":\"...\",\"explanation\":\"...\"}]}.",
+        "Explanation should be 1-3 sentences on why the hook works and what angle it is leveraging.",
+        "",
+        "Offer details:",
+        offerDescription.trim()
+    ], "Reference lessons to apply:", refs.hooks).join("\n");
+}
+export function buildAwarenessStagesPrompt(offerDescription, refs = {}) {
+    return withReference([
+        "You are Vidfarm's direct-response strategist.",
+        "The user is not sure what type of ads to produce.",
+        "Use Eugene Schwartz-style awareness-stage reasoning to recommend what kinds of ads to make first.",
+        "Write a practical response for TikTok-first performance marketing, but keep the advice broadly useful for paid social.",
+        "Do not return JSON. Return a clear markdown string.",
+        "Include:",
+        "- which awareness stages are most promising first",
+        "- why those stages fit this offer",
+        "- what ad types/messages belong in each stage",
+        "- what to test before moving to deeper or broader awareness stages",
+        "- a short next-step recommendation",
+        "",
+        "Offer details:",
+        offerDescription.trim()
+    ], "Reference lessons to apply:", refs.awareness).join("\n");
+}
+export function buildAnglesPrompt(payload, refs = {}) {
+    const head = [
+        "You are Vidfarm's senior direct-response angle strategist.",
+        "Generate persuasive advertising angles for TikTok-native ads.",
+        "Persuasive depth matters more than format gimmicks. The user wants raw winning angles to test.",
+        "Do not mention templates, scenes, or production mechanics. Focus on the strategic angle itself.",
+        "Create major diversity across the set: pain, myths, enemies, mechanisms, shocking truths, confessions, gossip/social proof, objections, hidden costs, status, identity, aspiration, taboo, mistake, urgency, proof, authority, trend hijack, curiosity, and contrarian frames.",
+        "Favor known winning angle archetypes while still making them specific to the offer.",
+        `Generate exactly ${payload.count} angles.`,
+        "Return strict JSON only with shape {\"angles\":[{\"angle\":\"...\",\"explanation\":\"...\"}]}",
+        "Explanation should say why the angle fits this awareness state and what persuasive lever it uses.",
+        "",
+        `Problem awareness: ${payload.problem_awareness}`,
+        `Solution awareness: ${payload.solution_awareness}`,
+        `Derived stage note: ${describeAwarenessSelection(payload.problem_awareness, payload.solution_awareness)}`,
+        "",
+        "Offer details:",
+        payload.offer_description.trim()
+    ];
+    const withAwareness = withReference(head, "Reference lessons to apply from awareness stages:", refs.awareness);
+    return withReference(withAwareness, "Reference lessons to apply from hooks:", refs.hooks).join("\n");
+}
+export function buildColdstartPrompt(userMessage, count) {
+    return [
+        "You are Vidfarm's TikTok growth strategist.",
+        "The customer has no idea where to start.",
+        "Generate the best possible foundational Q&A questions for the customer and AI to discuss so they can build a strong TikTok strategy from zero.",
+        "The goal is to produce questions whose answers can later power awareness-stage selection, angle generation, hooks, scripts, and template choice.",
+        `Generate exactly ${count} questions.`,
+        "You must include questions covering, at minimum:",
+        "- one-line offer",
+        "- one-paragraph offer",
+        "- product pricing and checkout experience (for example appstore payments, Stripe web checkout, Shopify, invoicing, or sales call)",
+        "- precise target customer psyche",
+        "- customer pain in their own words",
+        "- customer desire and dream outcome",
+        "- awareness levels or uncertainty about them",
+        "Add more strong questions beyond those when useful.",
+        "Return strict JSON only with shape {\"questions\":[{\"question\":\"...\",\"why_it_matters\":\"...\"}]}",
+        "Questions should be phrased so the user can answer them in a single markdown file for future use.",
+        "At least one question should explicitly encourage them to save these answers into an OFFER.md file (or OFFER_<NAME>.md when they run more than one offer), kept locally or in Vidfarm cloud files, for reuse inside Vidfarm.",
+        "",
+        "User message:",
+        userMessage.trim()
+    ].join("\n");
+}
+export function buildProductPlacementPrompt(offerDescription, count) {
+    return [
+        "You are Vidfarm's native-advertising product-placement strategist.",
+        "You are watching the attached video. Study what is actually on screen: scenes, actions, objects, spoken lines, on-screen text, transitions, and emotional beats.",
+        "Your job is to find the highest-leverage moments to organically place the user's product into THIS video so it feels native rather than bolted on.",
+        "Bias toward placements that ride the existing attention, emotion, or story beat of the moment. Native and believable beats loud and interruptive.",
+        "Consider many placement types: on-screen prop/set dressing, character interaction with the product, verbal mention or callout, text/caption overlay, sticker or lower-third, b-roll cutaway, screen/UI replacement, before/after demo, and end-card CTA.",
+        `Identify exactly ${count} distinct product-placement opportunities, ordered from strongest to weakest.`,
+        "Each opportunity must reference a real, specific moment you actually saw in the video, with an approximate timestamp or range (for example \"0:04\" or \"0:12-0:18\").",
+        "Return strict JSON only with shape {\"opportunities\":[{\"timestamp\":\"...\",\"scene\":\"...\",\"placement_type\":\"...\",\"placement_idea\":\"...\",\"why_it_works\":\"...\"}]}.",
+        "\"scene\" briefly describes what is happening on screen at that moment. \"placement_idea\" is the concrete, actionable way to insert the product. \"why_it_works\" explains the persuasion/attention logic.",
+        "",
+        "Product / offer to place:",
+        offerDescription.trim()
+    ].join("\n");
+}
+export function describeAwarenessSelection(problemAwareness, solutionAwareness) {
+    if (problemAwareness === "problem_unaware" && solutionAwareness === "solution_unaware") {
+        return "Lead with unaware-style pattern interrupts, identity, curiosity, story, and emotionally resonant entry points before surfacing the problem.";
+    }
+    if (problemAwareness === "problem_aware" && solutionAwareness === "solution_unaware") {
+        return "Lead with sharp articulation of the pain and consequences, then reveal a new possible solution path.";
+    }
+    if (problemAwareness === "problem_aware" && solutionAwareness === "solution_aware") {
+        return "Lead with strong solution-category promises, differentiation, mechanism, and proof.";
+    }
+    return "Lead with high-curiosity or identity-first entry points that bridge people from vague discomfort toward the existence of a real solution category.";
+}
+//# sourceMappingURL=brainstorm-prompts.js.map

package/dist/src/services/clip-curation/index.js

@@ -12,7 +12,7 @@ export { cosineSimilarity, matchesCriteria, rankHits, scoreClip, searchClips, st
 export { estimateScanCostFromDuration, estimateScanCostFromScenes, formatCostEstimate } from "./cost.js";
 export { processSceneToClip, scanVideo } from "./scan.js";
 export { refineScenesWithGuidance } from "./refine.js";
-export { estimateMediaHeight, pickBestVideoMedia, rankPlayableVideoMedias, fetchFirstDownloadableMedia } from "./media-select.js";
+export { estimateMediaHeight, pickBestVideoMedia, rankPlayableVideoMedias, fetchFirstDownloadableMedia, fetchSocialDownloadLookup, normalizeSocialDownloadLookup, normalizeSocialDownloadMedia, DEFAULT_SOCIAL_DOWNLOAD_URL, DEFAULT_SOCIAL_DOWNLOAD_HOST } from "./media-select.js";
 export { deriveMediaNameFromUrl, resolveRawSourceName, slugifyFolderName } from "./source-naming.js";
 // Re-export ClipPreset-related helpers already covered by ./presets and ./types
 // via the wildcard exports above; nothing extra needed here.