@officexapp/vidfarm-devcli 0.21.39 → 0.21.42

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"

package/experiments.md

@@ -75,7 +75,7 @@ Example — twelve channels, same round of 8 angles:
 
 **c) What are we selling, and to whom?** If they cannot answer in one sentence, do not guess — run the Vidfarm consultation first (`https://vidfarm.cc/skill.md` → the `brainstorm/*` chain: cold-start interview → awareness stages → angles → hooks). That chain exists precisely to produce the raw material this document then tests.
 
-**d) Which video format do we start on?** Offer the menu in §5 — the seven copywriting-led formats — and take a pick, or take the default (b-roll with kinetic captions) if they have no opinion. **Ask this in the interview, not at build time**, because the format is what the first round holds constant while it varies the angle. Ask the talking-head question explicitly here too: *"are you willing to be on camera?"* — the answer changes the whole menu, and it is cheap to ask once.
+**d) Which video format do we start on?** Offer the menu in §5 — the copywriting-led formats — and take a pick, or take the default (b-roll with kinetic captions) if they have no opinion. **Ask this in the interview, not at build time**, because the format is what the first round holds constant while it varies the angle. Ask the talking-head question explicitly here too: *"are you willing to be on camera?"* — the answer changes the whole menu, and it is cheap to ask once.
 
 **e) Who does the editing?** Their own agent (you), or a distributed task force of gigworkers. This decides the mode — see §3.
 
@@ -244,8 +244,39 @@ Pick one for the round:
 | **satisfying footage** | oddly-satisfying visuals | strong retention, weak topical fit |
 | **lifestyle footage** | aspirational day-in-the-life | best for identity and status angles |
 | **POV quote aesthetic** | static/slow plate, one quoted line | pure copywriting; a natural fit for hook tests |
+| **meme recaption** | a greenscreen reaction clip over a background image | for 3rd-person copy ("when you try to…"); see the person rule below |
 
-All seven are sourceable for ~$0 from the free public raws catalog — `vidfarm public-raws --categories`, then `--category <shelf>`. A shelf is also a ready-made clip pool for fanning one composition into N variants.
+All of these are sourceable for ~$0 from the free public raws catalog — `vidfarm public-raws --categories`, then `--category <shelf>`. A shelf is also a ready-made clip pool for fanning one composition into N variants.
+
+### Pick the PERSON first — it picks the visual for you
+
+Before you argue about footage, read the script's opening words. **The grammatical person the copy is written in decides which visual family works**, and getting this backwards is why a good line lands flat.
+
+**First person — "I tried to…", "I spent 3 months…", "here's what I learned"**
+
+The viewer is being told a personal story, so the visual has to be *the speaker's world*:
+
+- **POV b-roll** — hands, screen, desk, walking shots: what the narrator would actually see
+- **talking head** — the strongest version, if the user will film themselves
+- **process footage** — the thing being done, from the doer's angle
+- Lifestyle and satisfying footage work here too, as long as they read as *someone's* footage
+
+**Third person — "when you try to…", "nobody tells you that…", "POV: your first…"**
+
+This is observed, not confessed, so it wants a **meme recaption**: a reaction/character clip that plays the situation out, with your line written over it.
+
+- Pull the clip from the Vidfarm **greenscreen raws** — `vidfarm public-raws --category greenscreen`
+- Key it and place it over a **background image** (`vidfarm remove-greenscreen`, then composite). A screenshot, product shot, or scene photo all work
+- **Blur the background or don't** — blur when the subject must pop or the plate is busy; skip it when the background *is* the joke and needs to be readable
+- The character carries the emotion; your caption carries the claim
+
+**Both families share the same finish, every time:**
+
+- **TikTok-native type** — TikTok Sans or the Montserrat 700–900 caption regime, never a "designed" web font
+- **Kinetic captions** — 3–5-word cues paged in time, not a static wall of text
+- **Free Kokoro voiceover** — `vidfarm tts "…"` on the local voice, $0 in `minimize`/`hybrid`. Add it by default: a voice raises watch-through even over silent footage, and it costs nothing. Swap in a premium voice or the user's own recording only when a round is specifically testing voice
+
+The quick rule: **if the copy says "I", show the speaker's world. If it says "you", show someone else's reaction.**
 
 **Speed to productivity beats polish at the start.** If the director has no opinion, do not stall: take **b-roll footage with kinetic captions**, write it into the plan as the constant, and move. The format is cheap to change in a later round — and "which format?" is itself one of the two best second variables to test (§4).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@officexapp/vidfarm-devcli",
-  "version": "0.21.39",
+  "version": "0.21.42",
   "description": "Local bridge for the Vidfarm Trackpad Editor. `vidfarm serve <template_id>` boots the FULL editor on localhost (disk-backed records/storage, free in-process render); edit composition.html on disk (Claude Code, Codex, etc.) and the browser live-morphs it.",
   "type": "module",
   "bin": {
@@ -104,6 +104,9 @@
     "test:stickers": "node --import tsx --test test/sticker-pack.test.ts test/plate-key.test.ts",
     "test:social-recycle": "node --import tsx --test test/social-recycle.test.ts",
     "test:dedupe": "node --import tsx --test test/dedupe-recipe.test.ts",
+    "test:iconscout": "node --import tsx --test test/iconscout.test.ts",
+    "test:billing": "node --import tsx --test test/billing-wallet-cas.test.ts",
+    "test:skill-docs": "node --import tsx --test test/skill-docs.test.ts",
     "check:skills": "node scripts/build-director-skill-rollup.mjs --check && node scripts/check-skill-routes.mjs && node scripts/check-skill-nav.mjs",
     "benchmark:editor-chat": "node --import tsx scripts/benchmark-editor-chat-harness.mjs",
     "cdk:deploy:prod-serverless": "npm run build && dotenv -e .env.production -- npx aws-cdk deploy --app 'node dist/infra/cdk/bin/vidfarm-prod.js'",