@officexapp/vidfarm-devcli 0.21.39 → 0.21.43

package/dist/src/devcli/consult.js

@@ -0,0 +1,389 @@
+// 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";
+/**
+ * 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,
+                `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,
+                `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/cost-mode.js

@@ -131,9 +131,14 @@ export const COST_MODE_BLURB = {
         "bgm|sfx|image|vector|icon|video. Check the KEYLESS sources first: Openverse (CC/CC0 " +
         "music, SFX, images) and iconify (icons) need no account at all. A free Pixabay key adds " +
         "photos/vectors/stock-video and may already be saved (check vidfarm provider-keys). " +
+        'For any ICON, STICKER, illustration, 3D prop or Lottie, use vidfarm iconscout "<meaning>" ' +
+        "--free before even considering AI image generation: free IconScout assets cost $0 (a credit " +
+        "line is the only price) and arrive as clean transparent vectors. " +
         "Billed cloud/AI generation is refused unless you re-confirm it (--yes).",
     hybrid: "Hybrid (recommended) — roughly $0.01–$1 per video. Free where it's free, spend AI " +
         "credits only where they clearly win (a hero shot, a voice you can't fake locally). " +
+        'Never GENERATE an icon, sticker, illustration or 3D prop — vidfarm iconscout "<meaning>" ' +
+        "buys a designer's finished asset for a fraction of one AI attempt, with no prompt loop. " +
         "Billed ops run but each prints its cost so nothing is a surprise. Charges land on " +
         "your own AI provider keys (BYOK).",
     "rich-ai": "Rich AI — $1+ per video. AI video generation is spent on REUSABLE greenscreen raws " +
@@ -168,6 +173,9 @@ export function costModeExplainer() {
         "  `vidfarm add-provider-key <provider> <key>` or at vidfarm.cc/settings/developer.",
         "Tip: before paying to generate music/SFX/images/video, try the free stock catalog —",
         '  vidfarm media search "<meaning>" --type bgm|sfx|image|vector|icon|video.',
+        "  For icons, STICKERS, illustrations, 3D props and Lottie, IconScout beats AI generation on price",
+        '  and on quality in EVERY mode — vidfarm iconscout "<meaning>" --style sticker (search is free;',
+        "  free assets cost $0 with a credit line, premium downloads are a few cents on the wallet).",
         "  Check the keyless sources first — Openverse (CC/CC0 music, SFX, images) and iconify (icons)",
         "  need no account. A free Pixabay key adds photos/vectors/stock-video (it may already be saved —",
         "  check `vidfarm provider-keys` or vidfarm.cc/settings/developer; add via `vidfarm add-provider-key pixabay <key>`)."

package/dist/src/devcli/experiments.js

@@ -26,17 +26,22 @@ export const EXPERIMENT_MODES = ["creative", "structured"];
 export const CORE_METRICS = ["views", "comments", "clicks", "buys"];
 export const DEFAULT_METRIC = "comments";
 /** The starting format menu, offered during planning — NOT discovered at build
- *  time. Deliberately copywriting-led: in every one of these the words carry the
+ *  time. **Read the script's grammatical person to pick one**: copy written in the
+ *  first person ("I tried to…") wants the speaker's own world (POV b-roll, talking
+ *  head, process); copy written in the third person ("when you try to…") wants a
+ *  meme recaption — a greenscreen reaction raw over a background image. Either way
+ *  the finish is the same: TikTok-native type, kinetic captions, free Kokoro VO. Deliberately copywriting-led: in every one of these the words carry the
  *  persuasion and the footage only has to hold attention, which is what makes
  *  them fast, cheap and repeatable. All seven are sourceable for ~$0 from
  *  `vidfarm public-raws --categories`. */
 export const EASY_FORMATS = [
-    { key: "b-roll", label: "kinetic captions over b-roll footage", note: "the workhorse — start here" },
-    { key: "talking-head", label: "talking head", note: "only if the user will film themselves; strongest trust signal" },
-    { key: "process", label: "process footage", note: "high watch-through, needs no narration" },
+    { key: "b-roll", label: "kinetic captions over b-roll footage", note: "1st person — the workhorse, start here" },
+    { key: "talking-head", label: "talking head", note: "1st person — only if they'll film themselves; strongest trust signal" },
+    { key: "process", label: "process footage", note: "1st person — high watch-through, needs no narration" },
+    { key: "meme-recaption", label: "meme recaption", note: "3rd person (\"when you try to…\") — greenscreen raw over a background image, blur optional" },
     { key: "loop-background", label: "loop background footage", note: "cheapest of all; the copy is the entire video" },
     { key: "satisfying", label: "satisfying footage", note: "strong retention, weak topical fit" },
-    { key: "lifestyle", label: "lifestyle footage", note: "best for identity and status angles" },
+    { key: "lifestyle", label: "lifestyle footage", note: "identity and status angles" },
     { key: "pov-quote", label: "POV quote aesthetic", note: "pure copywriting; a natural fit for hook tests" }
 ];
 /** What to take when the director has no opinion — never stall on this choice. */

package/dist/src/devcli/qa-check.js

@@ -24,7 +24,81 @@
 //
 // Pure DOM (linkedom) — no ffmpeg, no network, no Chrome. Local-only: this is a
 // devcli capability with no cloud/REST equivalent.
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
 import { parseHTML } from "linkedom";
+// ── Revision governor ────────────────────────────────────────────────────────
+//
+// `vidfarm qa` is feedback, not a gate — which is exactly what makes it a loop
+// hazard for an autonomous agent: qa lists findings → agent edits → qa lists
+// findings → forever. Some findings are deliberate style choices that will never
+// "clear", so the loop has no natural base case.
+//
+// This is that base case. The governor counts how many times the composition has
+// CHANGED between qa passes (re-running qa on an untouched file is free), and at
+// the limit qa stops handing out new work: it withholds the finding list and says
+// stop. ONE revision is the default: the first pass names the real slop, the fix
+// clears it, and a second round is nearly always an agent polishing its own taste
+// rather than removing a defect. The human raises the ceiling with
+// `--max-revisions <n>` when a video genuinely earns another round.
+export const QA_STATE_FILENAME = ".vidfarm-qa-state.json";
+/** Revisions of one composition before qa stops feeding the loop. */
+export const DEFAULT_MAX_REVISIONS = 1;
+function hashComposition(html) {
+    return createHash("sha256").update(html).digest("hex").slice(0, 16);
+}
+/**
+ * Record this qa pass and report where the composition stands against the
+ * revision limit. `max <= 0` disables the governor entirely.
+ *
+ * Deliberately forgiving: an unreadable or corrupt state file is treated as a
+ * fresh start, never an error — a QA helper must not be the thing that breaks a
+ * build.
+ */
+export function recordQaPass(htmlPath, html, opts) {
+    const max = opts.max ?? DEFAULT_MAX_REVISIONS;
+    const workDir = path.dirname(htmlPath);
+    const statePath = path.join(workDir, QA_STATE_FILENAME);
+    const composition = path.basename(htmlPath);
+    const hash = hashComposition(html);
+    const disabled = !Number.isFinite(max) || max <= 0;
+    let previous = null;
+    if (!opts.reset && existsSync(statePath)) {
+        try {
+            const parsed = JSON.parse(readFileSync(statePath, "utf8"));
+            // A different composition in the same folder starts its own count.
+            if (parsed && parsed.composition === composition)
+                previous = parsed;
+        }
+        catch {
+            previous = null;
+        }
+    }
+    const changed = previous ? previous.hash !== hash : false;
+    const revisions = previous ? previous.revisions + (changed ? 1 : 0) : 0;
+    const next = {
+        composition,
+        hash,
+        revisions,
+        first_seen: previous?.first_seen ?? opts.now,
+        last_seen: opts.now
+    };
+    try {
+        writeFileSync(statePath, `${JSON.stringify(next, null, 2)}\n`, "utf8");
+    }
+    catch {
+        // A read-only work dir just means no governor. Don't fail the check.
+    }
+    return {
+        revisions,
+        max,
+        limit_reached: !disabled && revisions >= max,
+        changed_since_last_run: changed,
+        state_path: statePath,
+        disabled
+    };
+}
 /**
  * Build the "now go watch it" directive. `dir` is substituted into the commands
  * so the agent can paste them; the JSON default is the generic placeholder.

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

@@ -106,6 +106,109 @@ export function readPackDoc(ref, name = DEFAULT_PACK) {
     const doc = resolvePackDoc(ref, name);
     return { doc, contents: readFileSync(doc.abs, "utf8") };
 }
+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" },
+    { 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",
+        blurb: "The product-explainer harness — the bundled base for explaining what a product does" },
+    { topic: "product-demo", aliases: ["demo"], doc: "harnesses/product-demo.HARNESS.md",
+        blurb: "The product-demo harness — showing the product in use" },
+    { topic: "explainer-cutouts", aliases: ["cutout", "cutouts", "stickers", "sticker", "explainer"], doc: "recipes/cutout-graphics-for-explainers.md",
+        blurb: "Explainers built from transparent cutout stickers — house style, sheets, keying, dark stages" },
+    { topic: "hooks", aliases: ["hook", "virality", "viral", "charges"], doc: "references/hooks-and-virality.md",
+        blurb: "The four charges — hook, loop, payoff, bait — written BEFORE the timeline" },
+    { topic: "density", aliases: ["cut", "cutting", "too-long", "pacing"], doc: "references/hooks-and-virality.md", heading: "Density",
+        blurb: "Every second must earn its place — the deletion test and cut-on-sight list" },
+    { topic: "captions", aliases: ["caption", "subtitles", "safe-zone"], doc: "references/editor-workflows.md", heading: "TikTok-native caption standard",
+        blurb: "The caption standard — safe zone, negative space, font regime, the four valid backgrounds" },
+    { topic: "first-frame", aliases: ["thumbnail", "poster"], doc: "references/editor-workflows.md", heading: "The first frame is the thumbnail",
+        blurb: "t=0 is the thumbnail everywhere — compose it as a designed still" },
+    { topic: "no-slop", aliases: ["slop", "visual-standard", "html-slop"], doc: "references/editor-workflows.md", heading: "Social-native visual standard",
+        blurb: "No HTML slop — what a social-native frame may and may not contain" },
+    { topic: "blurred-plate", aliases: ["letterbox", "landscape-vertical", "bars"], doc: "references/editor-workflows.md", heading: "The blurred plate",
+        blurb: "Landscape footage fullscreen on a vertical canvas, without black bars" },
+    { topic: "ken-burns", aliases: ["pan-zoom", "still-motion"], doc: "references/editor-workflows.md", heading: "Ken Burns",
+        blurb: "Animate a still image instead of paying for AI video" },
+    { topic: "paintbrushes", aliases: ["three-paintbrushes", "replication"], doc: "references/editor-workflows.md", heading: "The three paintbrushes",
+        blurb: "Clip reuse vs. image gen vs. AI video — and the two replication harnesses" },
+    { topic: "avatar", aliases: ["talking-head", "spokesperson", "presenter"], doc: "references/primitives.md", heading: "Primitive: talking_avatar",
+        blurb: "\"Create an avatar\" = a talking head WITH audio, keyed off greenscreen" },
+    { topic: "dedupe", aliases: ["deduplicate", "repost", "variants"], doc: "references/primitives.md", heading: "Primitive: media_dedupe",
+        blurb: "Deduplicate an exported MP4 before posting it again or to another platform" },
+    { topic: "review", aliases: ["reviewing", "judge", "holistic", "qa-review"], doc: "references/reviewing-renders.md",
+        blurb: "Judge the WHOLE video before you report it done — never by one frame" },
+    { topic: "harness", aliases: ["harnesses", "regime"], doc: "harnesses/README.md",
+        blurb: "What a HARNESS.md is, its format, and the three phrasings that mean one" },
+    { topic: "bulk", aliases: ["batch", "volume", "scripting", "daily-posting"], doc: "recipes/bulk-scripting-with-a-harness.md",
+        blurb: "Produce N different videos in one run — scripting mode with a harness" },
+    { topic: "onboarding", aliases: ["consultation", "coldstart", "offer", "strategy"], doc: "references/onboarding.md",
+        blurb: "The cold-start interview and the brainstorm/* consultation chain" }
+];
+export function listPackTopics() {
+    return [...PACK_TOPICS].sort((a, b) => (a.topic < b.topic ? -1 : 1));
+}
+/** Match a spoken topic name. Returns null (not an error) so callers can fall back to file lookup. */
+export function resolvePackTopic(ref) {
+    const needle = ref.trim().toLowerCase().replace(/[\s_]+/g, "-").replace(/\.md$/, "");
+    return PACK_TOPICS.find((entry) => entry.topic === needle || entry.aliases.includes(needle)) ?? null;
+}
+/**
+ * Slice one Markdown section out of a doc: from the heading that contains
+ * `heading` down to the next heading of the same or higher level. Returns null
+ * when the heading is gone (the pack was edited) so the caller can fall back to
+ * the whole file rather than printing nothing.
+ */
+export function extractSection(contents, heading) {
+    const needle = heading.trim().toLowerCase();
+    const lines = contents.split("\n");
+    const level = (line) => (line.match(/^(#{1,6})\s/)?.[1].length ?? 0);
+    const start = lines.findIndex((line) => level(line) > 0 && line.toLowerCase().includes(needle));
+    if (start < 0)
+        return null;
+    const depth = level(lines[start]);
+    let end = lines.length;
+    for (let i = start + 1; i < lines.length; i += 1) {
+        const at = level(lines[i]);
+        if (at > 0 && at <= depth) {
+            end = i;
+            break;
+        }
+    }
+    return { heading: lines[start].replace(/^#+\s*/, "").trim(), body: lines.slice(start, end).join("\n").trimEnd() };
+}
+/** A topic's text, already sliced to its section when it names one. */
+export function readPackTopic(topic, name = DEFAULT_PACK) {
+    const { doc, contents } = readPackDoc(topic.doc, name);
+    if (!topic.heading)
+        return { doc, contents, whole: true };
+    const section = extractSection(contents, topic.heading);
+    if (!section)
+        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");
+    const frames = [];
+    const families = [];
+    let family = "";
+    for (const line of lines) {
+        const label = line.match(/^\*\*(.+?)\*\*\s*$/);
+        if (label) {
+            family = label[1].split(/\s+[—-]\s+/)[0].trim();
+            if (family && !families.includes(family))
+                families.push(family);
+            continue;
+        }
+        const bullet = line.match(/^-\s+(.+?)\s*$/);
+        if (bullet && family)
+            frames.push({ frame: bullet[1].trim(), family });
+    }
+    return { frames, families };
+}
 /**
  * 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"