@officexapp/vidfarm-devcli 0.21.52 → 0.21.54

package/dist/src/cli.js

@@ -1144,6 +1144,9 @@ Marketplace (paid, cloud-only — the bazaar never renders locally):
     --file-id <id>          Move a FILE; omit to move the folder (same root, e.g. /raws/demos → /raws/archive)
   directory copy <path> [<to-folder>] Duplicate a file/folder (shared S3 obj)  → POST /api/v1/user/me/directory/copy
     --file-id <id> --as <name>   Copy a FILE; omit --file-id to copy the folder; --as renames the copy
+  directory note <path>     Read/write the VECTOR NOTE of a file or FOLDER      → GET|PUT /api/v1/user/me/directory/note
+    --file-id <id>          Annotate a FILE; omit to annotate the FOLDER at <path>
+    --set "<text>"          What the thing IS, in plain words — embedded, so search finds it by meaning
   directory save-url <url>  Save a durable media URL INTO My Files at a folder → POST /api/v1/user/me/attachments/from-url
     --folder <path>         Destination folder under /files (e.g. inpaints, promos)
     --as <name>             Name the saved file · --notes <text> vector-embedded notes
@@ -1161,7 +1164,10 @@ Marketplace (paid, cloud-only — the bazaar never renders locally):
          vidfarm gigs proofs --status pending   ·   vidfarm gigs approve PRF_01H…
     (see: vidfarm gigs help)
   shared <sub> <link>       USE a link someone shared with you — NO account, NO API key
-    info · ls · search · mkdir · put · get     e.g. vidfarm shared put <link> clip.mp4 --subfolder batch-01
+    info · ls --tree · search · grab · note · mkdir · put · get
+    grab is the one to reach for: it finds footage by MEANING and downloads it in one step.
+    e.g. vidfarm shared grab <link> "founder talking head, kitchen" --out ./assets
+         vidfarm shared put <link> cut-v2.mp4 --subfolder batch-01 --note "Final cut, 9:16"
     (the gigworker/agent side of directory share; see: vidfarm shared help)
   put-file / get-file / files / annotate-file are the My Files (persistent) set;
   upload is the throwaway temp store for dropping media into a composition.
@@ -2741,7 +2747,7 @@ Rules:
 - When swapping visuals, match both the literal scene DNA and the narrative purpose of the beat.
 - For replacement graphics, screenshots, or still-like scenes, prefer AI image generation plus Ken Burns before paying for AI video unless static_vs_pivot says motion footage is load-bearing.
 - If narration must be customized, default to premium ElevenLabs first, then the user's own ElevenLabs path, then BYOK OpenAI/Gemini/OpenRouter. If captions or scenes were timed to the old VO, retime them to the new narration.
-- NO HTML SLOP. You are editing HTML, but the output is a social video, not a web page. THE TEST IS THE NATIVE-EDITOR TEST: could you have made this element with the tools inside TikTok's own editor? That toolset is a font, a color, a stroke/outline, a soft shadow, a tight text box, alignment, opacity, rotation, animation presets — plus stickers, emoji, drawn marks and clips. It has NO padded capsule, NO border, NO gradient fill, NO blur panel, NO card. If you reached past it, cut it. Never author landing-page furniture: CTA "buttons" (a filled/gradient rounded capsule with action copy like "Sign Up for a Free Trial →"), benefit chip/badge rows ("✓ No Credit Card Needed"), bordered/shadowed/frosted cards holding a headline + URL, gradient text fills, feature grids, bulleted lists, or web-default fonts (Inter/Roboto/Arial/system-ui). AND NOT A SINGLE PILL EITHER: one lonely rounded, padded, filled capsule around a static stat or label — "10 hrs / week", "STEP 2", "EP.01", "+40%" — is a web badge, and being the only one on screen does not make it native. The ONLY legitimate capsule in a video is the active-word spotlight/karaoke caption highlight, because it moves with the spoken word. Emphasize a stat the way the editor would: bigger, heavier, ALL-CAPS, an accent color, a hand-drawn circle or underline, or its own beat on screen. Rule of thumb on anything holding words: border-radius over ~8px PLUS a background fill PLUS padding = a badge; drop the fill or drop the radius until the band hugs the glyphs. None of this appears in a real TikTok, and nothing in a video is clickable — say it as timed text on the footage instead. Arrows, scribble/underline marks, italics, ALL-CAPS, single-word color pops, emoji, transparent cut-out stickers, and mock social UI (iMessage bubbles, comment cards) are all fine. Captions use an imported family (Montserrat default / TikTok Sans / Abel / Source Code Pro / Yesteryear) at weight 700-900, ~36-64px on a 1080-wide frame, inside the 8%-85% safe zone, with exactly one of four backgrounds: outline, plain, an active-word spotlight/karaoke pill, or a tight-hugging solid band (radius <=8px, no border/shadow/gradient/blur).
+- NO HTML SLOP. You are editing HTML, but the output is a social video, not a web page. THE TEST IS THE NATIVE-EDITOR TEST: could you have made this element with the tools inside TikTok's own editor? That toolset is a font, a color, a stroke/outline, a soft shadow, a tight text box, alignment, opacity, rotation, animation presets — plus stickers, emoji, drawn marks and clips. It has NO padded capsule, NO border, NO gradient fill, NO blur panel, NO card. If you reached past it, cut it. Never author landing-page furniture: CTA "buttons" (a filled/gradient rounded capsule with action copy like "Sign Up for a Free Trial →"), benefit chip/badge rows ("✓ No Credit Card Needed"), bordered/shadowed/frosted cards holding a headline + URL, gradient text fills, feature grids, bulleted lists, or web-default fonts (Inter/Roboto/Arial/system-ui). AND NOT A SINGLE PILL EITHER: one lonely rounded, padded, filled capsule around a static stat or label — "10 hrs / week", "STEP 2", "EP.01", "+40%" — is a web badge, and being the only one on screen does not make it native. The ONLY legitimate capsule in a video is the active-word spotlight/karaoke caption highlight, because it moves with the spoken word. Emphasize a stat the way the editor would: bigger, heavier, ALL-CAPS, an accent color, a hand-drawn circle or underline, or its own beat on screen. Rule of thumb on anything holding words: border-radius over ~8px PLUS a background fill PLUS padding = a badge; drop the fill or drop the radius until the band hugs the glyphs. None of this appears in a real TikTok, and nothing in a video is clickable — say it as timed text on the footage instead. Arrows, scribble/underline marks, italics, ALL-CAPS, single-word color pops, emoji, transparent cut-out stickers, and mock social UI (iMessage bubbles, comment cards) are all fine. Captions use one of the FIVE imported families by default (Montserrat default / TikTok Sans / Abel / Source Code Pro / Yesteryear - the full regime, with a rendered specimen of each, is at https://vidfarm.cc/fonts). A custom family is allowed only if the composition DECLARES it (@font-face or a Google Fonts @import); an undeclared family silently falls back to a web-default sans and local renders coerce it to Montserrat. Every family has its own standalone reference card at https://vidfarm.cc/assets/fonts/caption-font-<family>.png (backgrounds: caption-bg-outline|plain|spotlight|highlight-solid.png) - after styling, pull a still and COMPARE it against the card for the family you picked, because a font that failed to load looks fine on its own. Weight 700-900, ~36-64px on a 1080-wide frame, inside the 8%-85% safe zone, with exactly one of four backgrounds: outline, plain, an active-word spotlight/karaoke pill, or a tight-hugging solid band (radius <=8px, no border/shadow/gradient/blur).
 - NO LAYOUT TEMPLATES — JUDGE THE WHOLE FRAME, NOT JUST THE ELEMENT. Every rule above judges one element, and a frame can pass element-by-element and still be a web page. The archetype is the MODAL: the backdrop dimmed and blurred out of focus, and floating on top of it a rounded bordered box holding a big headline, a smaller support line, and a fat CTA button. THE STACK IS THE TELL, NOT THE BOX — delete the border, the fill and the capsule, keep headline then subheadline then CTA centred in a well with even margins, and it STILL reads as a landing page, because a viewer recognizes the SHAPE before reading a single word. Banned at frame level: a modal/dialog staged on top of a backdrop that has been dimmed, blurred, greyed or scaled back (nothing in a video pops "above" the video); the hero triplet and its cousins (title + kicker + logo lockup, question + answer + URL); a full-frame dark wash used to stage a floating block (a legibility band on ONE caption is legal, a page-wide wash to stage a panel is not; likewise a blurred backdrop is fine alone — a blurred fill behind a 16:9 clip in a 9:16 frame is a real technique — but blur PLUS dimming is modal staging); nav strip / hero / three-up feature row / testimonial block / footer fine print; a blurred website screenshot used as the background plate (if the backdrop is a web page, the frame is a screen recording of a web page — show the real product UI full-bleed and in focus, or don't show it); a centred content column with even gutters and document margins. THE FIX IS ALWAYS TO UNSTACK IT INTO TIME: the headline is the hook at start:0, the support line lands on the next cut, the CTA is SPOKEN or a bare caption on the final frame. You lose nothing — a viewer reads one line at a time anyway — and you gain the pacing that makes it look shot rather than designed. Self-check before you place any text group: am I arranging words relative to EACH OTHER, or relative to the PICTURE? Relative to each other is a layout, which is web. Two on-screen text runs at once is the ceiling. Verify on real pixels: \`vidfarm stills . --at <t>\` — if the still could be a screenshot of a website, rebuild the beat. \`vidfarm qa\` catches only the mechanical half (layout-template, modal-scrim); the frame-level judgement is yours.
 - STRUCTURE BEFORE POLISH — THE FOUR CHARGES, WRITTEN BEFORE YOU TOUCH THE TIMELINE. Most agent-made videos fail on structure, not polish, because the timeline is the fun part so it gets built first and the words get retrofitted. Invert it: (1) HOOK — write the opening line as text first: a complete clause (subject + verb), no jargon, naming a SITUATION ("I've quit six businesses") not a label ("anonymity"); it goes on screen at start:0, because caption chunk 1 is read before any audio and muted autoplay is the default. Banned openings: throat-clearing ("so I was thinking", "here's the thing"), a logo, a title card, a fade from black, context before the claim. (2) LOOP — one open question by 0:10, said ON SCREEN, closing INSIDE this video (state the timestamp it closes at; if you can't, there is no loop), and the withheld answer must be one the viewer CANNOT supply themselves — a formally-correct loop with a guessable answer passes every mechanical check and dies in the field. (3) PAYOFF — shown, not summarized, ≥5 uninterrupted seconds, landing BEFORE the final beat; the payoff is not the CTA. (4) BAIT — one ask in the final beat and in the post caption; a keyword comment ask ("comment CLIPPER and I'll send the breakdown") is standard and allowed, but never "follow for part two", ragebait, or an earnings/health claim traded for the reply. Then build the timeline. Re-theming a decomposed template: viral_dna already names the source's hook/retention/payoff — rebuild each charge for the new subject, never flatten the loop into a product statement. Full craft harness: the vidfarm skill's references/hooks-and-virality.md. Checkable form: \`vidfarm harness show hooks\`.
 - ORIENT THE COLD VIEWER IN THE FIRST 3 SECONDS — THE VIEWER HAS NO CONTEXT AND DID NOT CHOOSE THIS VIDEO. Distinct from the hook: the hook makes them WANT to watch, orientation makes the watching POSSIBLE. A stranger mid-scroll must be able to answer three things by ~3s — what am I looking at (the CATEGORY noun), who is it for, and why is this on my screen (the situation). The failure is not a bad first frame, it is a good video that BEGINS AT BEAT TWO, and the author cannot see it because the author already knows what the thing is. Signatures, each a rebuild not a polish: a pronoun with no referent ("it just works", "this changes everything", "here's how they do it"); starting at step three (the process already running, the dashboard already full); a metaphor whose subject only lands at 6s; insider vocabulary, a product's own feature name, or an ACRONYM in the first line; a detail crop that reads as texture until you know the whole. Instead, the opening beat is BOTH channels at once: an EASY IMAGE (one large subject, already moving, legible at a glance and at thumbnail scale — a relevant die-cut sticker names the category before a word is read) AND an EASY LINE (first spoken sentence one clause, <=12 words, everyday words, concrete noun + verb, no subordinate clause, brand name said once plainly, and the CATEGORY named: "X is a language app that…"). Give the SITUATION, not the label — "the end of the month, and your receipts are in a shoebox" orients, "expense automation" does not. THIS IS NOT AN INTRO AND COSTS NO EXTRA SECONDS: it replaces the wind-up sentence, it never precedes it, and it never licenses a logo, a title card or a fade from black. Test it on the render, not the script: play the first 3 seconds ONLY to somebody with no context and stop — they should say what kind of thing it is and roughly who it is for. "Something about audio" is a fail. Fullest form: \`vidfarm harness show product-explainer\` (Rule 0).
@@ -11104,6 +11110,17 @@ const DIRECTORY_HELP = `vidfarm directory — browse the unified file tree (/fil
     e.g. vidfarm directory copy /raws/demos /raws/archive
          vidfarm directory copy /files/brand/logo.png /files/inbox --file-id att_123 --as logo-copy.png
 
+  directory note <path>            Read the VECTOR NOTE of a file or FOLDER          → GET /api/v1/user/me/directory/note
+    --file-id <id>                 Annotate a FILE; omit to annotate the FOLDER at <path>
+    --set "<text>"                 Write the note ("" clears it). It is embedded, so the
+                                   thing is findable by MEANING — a file name is not.
+    --json
+    e.g. vidfarm directory note /raws/AboutOffer/BRoll --set "Kitchen b-roll, no faces, 9:16"
+         vidfarm directory note /files/brand/logo.png --file-id att_123
+    Notes live on /files entries, /raws entries and FOLDERS in any writable root.
+    Uploads self-describe when the account has an AI key saved (skipped over 100 MB);
+    with no key the note is yours to type, and search falls back to keyword-only.
+
   directory save-url <url>         Save a durable media URL INTO My Files at a folder → POST /api/v1/user/me/attachments/from-url
     --folder <path>                Destination folder under /files (e.g. inpaints, promos)
     --as <name>                    Name the saved file (else derived from the URL)
@@ -11155,6 +11172,10 @@ async function runDirectoryCommand(argv) {
         case "copy":
         case "cp":
             return runDirectoryCopy(rest);
+        case "note":
+        case "notes":
+        case "annotate":
+            return runDirectoryNote(rest);
         case "save-url":
         case "from-url":
         case "import-url":
@@ -11247,6 +11268,55 @@ async function runDirectorySearch(argv) {
     }
     printDirectorySearch(merged, query, spaces.length > 1 ? "both" : spaces[0]);
 }
+// Read or write the VECTOR NOTE of a file or folder. The note is the plain-text
+// answer to "what is this?", embedded so search finds it from any phrasing —
+// which is the difference between a folder of IMG_4821.mp4 and a usable library.
+async function runDirectoryNote(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: { ...commonOptions(), "file-id": { type: "string" }, set: { type: "string" }, note: { type: "string" } }
+    });
+    const ctx = commonContext(parsed.values);
+    const targetPath = parsed.positionals[0];
+    if (!targetPath) {
+        throw new Error('directory note requires a path: vidfarm directory note /raws/BRoll [--file-id <id>] [--set "what this is"]');
+    }
+    const fileId = parsed.values["file-id"];
+    const next = parsed.values.set ?? parsed.values.note;
+    const space = targetSpaces(ctx.target)[0];
+    if (next == null) {
+        const result = await dispatch(ctx, { method: "GET", path: "/api/v1/user/me/directory/note", query: { path: targetPath, id: fileId } }, space);
+        assertApiOk(result, "directory note");
+        if (ctx.json) {
+            printJson(result.json ?? result.text);
+            return;
+        }
+        const note = result.json?.note;
+        console.log(`${BOLD}${targetPath}${RESET}`);
+        console.log(note ? `  ${note}` : `  ${DIM}(no vector note yet)${RESET}`);
+        if (!note)
+            console.log(`  ${DIM}Write one: vidfarm directory note ${targetPath}${fileId ? ` --file-id ${fileId}` : ""} --set "what this is"${RESET}`);
+        return;
+    }
+    const result = await dispatch(ctx, {
+        method: "PUT",
+        path: "/api/v1/user/me/directory/note",
+        body: { path: targetPath, ...(fileId ? { id: fileId } : {}), note: next }
+    }, space);
+    assertApiOk(result, "directory note");
+    if (ctx.json) {
+        printJson(result.json ?? result.text);
+        return;
+    }
+    const saved = result.json?.note;
+    console.log(`${GREEN}✓${RESET} ${saved ? "note saved on" : "note cleared on"} ${BOLD}${targetPath}${RESET}`);
+    if (saved) {
+        console.log(result.json?.embedded
+            ? `  ${DIM}searchable by meaning${RESET}`
+            : `  ${DIM}saved, but keyword-search only — add a gemini/openai key to embed it${RESET}`);
+    }
+}
 async function runDirectoryRename(argv) {
     const parsed = parseArgs({
         args: argv,
@@ -11568,6 +11638,20 @@ function mergeSearch(parts, limit) {
     };
 }
 // Compact "12.3s · 4.2 MB · video/mp4" line for a directory file item.
+// ── vector notes in list/search output ───────────────────────────────────────
+// The note is what a human (or an agent) recognises the item by, so it prints
+// under the name; the mark makes a MISSING note visible as a gap to fill.
+function noteLine(item) {
+    const note = typeof item?.note === "string" ? item.note.replace(/\s+/g, " ").trim() : "";
+    if (!note)
+        return "";
+    return note.length > 110 ? `${note.slice(0, 109)}…` : note;
+}
+function noteMark(item) {
+    if (item?.note === undefined)
+        return ""; // backend carries no note field
+    return item.note ? `${GREEN}✓${RESET} ` : `${DIM}✎${RESET} `;
+}
 function directoryFileMeta(item) {
     const parts = [];
     if (typeof item?.durationSec === "number" && item.durationSec > 0)
@@ -11598,11 +11682,17 @@ function printDirectoryListing(data, requestedPath, space) {
         console.log(`  ${DIM}(empty)${RESET}`);
     }
     for (const f of folders) {
-        console.log(`  ${DIM}dir ${RESET}  ${originBadge(f)}${f?.name ?? ""}/    ${DIM}${f?.path ?? ""}${RESET}`);
+        console.log(`  ${DIM}dir ${RESET}  ${noteMark(f)}${originBadge(f)}${f?.name ?? ""}/    ${DIM}${f?.path ?? ""}${RESET}`);
+        const note = noteLine(f);
+        if (note)
+            console.log(`        ${DIM}${note}${RESET}`);
     }
     for (const f of files) {
         const meta = directoryFileMeta(f);
-        console.log(`  file  ${originBadge(f)}${f?.name ?? ""}${meta ? `    ${DIM}${meta}${RESET}` : ""}    ${DIM}${f?.path ?? ""}${RESET}`);
+        console.log(`  file  ${noteMark(f)}${originBadge(f)}${f?.name ?? ""}${meta ? `    ${DIM}${meta}${RESET}` : ""}    ${DIM}${f?.path ?? ""}${RESET}`);
+        const note = noteLine(f);
+        if (note)
+            console.log(`        ${DIM}${note}${RESET}`);
         if (f?.viewUrl)
             console.log(`        ${FRONTEND}${f.viewUrl}${RESET}`);
     }
@@ -11623,7 +11713,10 @@ function printDirectorySearch(data, query, space) {
     results.forEach((r, i) => {
         const score = typeof r?.score === "number" ? ` ${DIM}score=${r.score.toFixed(3)}${RESET}` : "";
         const kind = r?.kind === "folder" ? "dir " : "file";
-        console.log(`  ${String(i + 1).padStart(2)}. ${kind}  ${originBadge(r)}${r?.path ?? r?.name ?? ""}${score}`);
+        console.log(`  ${String(i + 1).padStart(2)}. ${kind}  ${noteMark(r)}${originBadge(r)}${r?.path ?? r?.name ?? ""}${score}`);
+        const note = noteLine(r);
+        if (note)
+            console.log(`      ${DIM}${note}${RESET}`);
         const meta = directoryFileMeta(r);
         if (meta)
             console.log(`      ${DIM}${meta}${RESET}`);

package/dist/src/devcli/composition-edit.js

@@ -391,11 +391,42 @@ const CAPTION_DEFAULT_FRAME = { x: 10, y: 70, width: 80, height: 14 };
 export const TIKTOK_CAPTION_SAFE_ZONE = { top: 8, bottom: 85 }; // % of canvas height
 // The composition font regime — mirrors COMPOSITION_FONT_IMPORT's family list in
 // services/studio-project-adapter.ts. A caption/text layer whose primary family
-// is outside this set isn't even imported (so it silently falls back at render),
-// which means coercing it to the bold default is strictly an improvement.
+// is outside this set is normally not imported (so it silently falls back at
+// render), which means coercing it to the bold default is strictly an
+// improvement. The regime is a strong default, not a ban: a family the
+// composition declares for itself (see compositionDeclaresFont) is left alone.
 const CAPTION_FONT_REGIME = ["tiktok sans", "montserrat", "abel", "source code pro", "yesteryear"];
 const CAPTION_REGIME_FALLBACK_FONT = "Montserrat";
 const CAPTION_FONT_FALLBACK_CHAIN = "'Montserrat', 'TikTok Sans', Abel, sans-serif";
+/**
+ * A CUSTOM family is allowed — as long as the composition actually ships it.
+ * The regime exists because an unimported family silently falls back to a
+ * web-default sans at render; it is not a ban on typography. So: if the
+ * composition declares the family itself (an `@font-face` for it, or a Google
+ * Fonts `@import`/`<link>` naming it), leave the layer alone. Only a family
+ * with no declaration anywhere gets coerced, because that one really is broken.
+ */
+export function compositionDeclaresFont(html, family) {
+    const name = family.trim().toLowerCase();
+    if (!name)
+        return false;
+    const hay = html.toLowerCase();
+    // @font-face { font-family: "Brand Sans" }
+    const faceRe = /@font-face\s*{[^}]*}/g;
+    for (const block of hay.match(faceRe) ?? []) {
+        const declared = block.match(/font-family\s*:\s*['"]?([^;'"}]+)/);
+        if (declared && declared[1].trim() === name)
+            return true;
+    }
+    // Google Fonts URL: family=Brand+Sans / family=Brand%20Sans
+    const urlName = name.replace(/\s+/g, "");
+    for (const m of hay.matchAll(/fonts\.googleapis\.com\/css2\?([^"')\s]+)/g)) {
+        const params = m[1].replace(/\+/g, "").replace(/%20/g, "");
+        if (params.includes(`family=${urlName}`))
+            return true;
+    }
+    return false;
+}
 function setStylePercent(node, prop, value) {
     if (node?.style)
         node.style[prop] = `${Number(value.toFixed(2))}%`;
@@ -450,7 +481,9 @@ export function normalizeTikTokCaptionLayout(html) {
         }
         // Font: coerce off-regime primary family to the bold default.
         const primary = String(node.getAttribute?.("data-font-family") || "").trim();
-        if (primary && !CAPTION_FONT_REGIME.includes(primary.toLowerCase())) {
+        if (primary &&
+            !CAPTION_FONT_REGIME.includes(primary.toLowerCase()) &&
+            !compositionDeclaresFont(html, primary)) {
             node.setAttribute?.("data-font-family", CAPTION_REGIME_FALLBACK_FONT);
             if (node.style)
                 node.style.fontFamily = CAPTION_FONT_FALLBACK_CHAIN;

package/dist/src/devcli/marketplace-gigs.js

@@ -305,7 +305,7 @@ async function cmdMachines(auth, values) {
     }));
     out(Boolean(values.json), { machines }, () => {
         if (!machines.length) {
-            console.log(`${DIM}No vending machines on this key yet. A paid vidfarm account gets two; open ${RESET}https://vidfarm.cc/marketplace/buyer${DIM} once to create them.${RESET}`);
+            console.log(`${DIM}No vending machines on this key yet. A paid vidfarm account gets two; open ${RESET}https://vidfarm.cc/marketplace${DIM} once to create them.${RESET}`);
             return;
         }
         for (const machine of machines) {
@@ -461,7 +461,7 @@ async function cmdRingBell(auth, values) {
         destination = hasInviteToken(registered.invite_url) ? registered.invite_url : "";
     }
     if (!destination)
-        throw new Error("That machine has no invite link yet — open it once on vidfarm.cc/marketplace/buyer.");
+        throw new Error("That machine has no invite link yet — open it once on vidfarm.cc/marketplace.");
     const result = await dp(auth, `/feeds/${VIDFARM_FEED_ID}/notifications`, {
         method: "POST",
         body: {

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

@@ -28,6 +28,7 @@ import { createHash } from "node:crypto";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { parseHTML } from "linkedom";
+import { compositionDeclaresFont } from "./composition-edit.js";
 // ── Revision governor ────────────────────────────────────────────────────────
 //
 // `vidfarm qa` is feedback, not a gate — which is exactly what makes it a loop
@@ -646,16 +647,19 @@ export function qaCompositionHtml(html) {
         const style = styleString(node);
         const cssMatch = style.match(/(?:^|;)\s*font-family\s*:\s*([^;]+)/);
         const family = primaryFamily(attr || (cssMatch ? cssMatch[1] : ""));
-        if (family && !FONT_REGIME.includes(family)) {
+        // A custom family is allowed when the composition SHIPS it — an @font-face
+        // or a Google Fonts import naming it. The defect this rule exists for is a
+        // family that no render can load, so a declared one is not a finding.
+        if (family && !FONT_REGIME.includes(family) && !compositionDeclaresFont(html, family)) {
             const isWebDefault = WEB_DEFAULT_FONTS.includes(family) || family === "sans-serif" || family === "serif";
             push({
                 rule: "font-regime",
                 severity: isWebDefault ? "error" : "warn",
                 message: isWebDefault
                     ? `Text layer in "${family}" — a website body font. This alone makes a frame read as a screenshot of a web page.`
-                    : `Text layer in "${family}", outside the composition's imported font regime — it will silently fall back at render.`,
+                    : `Text layer in "${family}", which this composition never imports — it will silently fall back to a web-default sans at render.`,
                 where: label(node, "text layer"),
-                fix: `Use an imported display family: Montserrat (default), TikTok Sans, Abel, Source Code Pro, or Yesteryear — e.g. \`vidfarm set-style <dir> --layer <key> --font-family Montserrat\`. Local renders auto-coerce this, but the editor preview will not match until you fix it.`
+                fix: `Use a regime family — Montserrat (default), TikTok Sans, Abel, Source Code Pro, Yesteryear — e.g. \`vidfarm set-style <dir> --layer <key> --font-family Montserrat\`; each has its own reference card, e.g. https://vidfarm.cc/assets/fonts/caption-font-montserrat.png (all five: https://vidfarm.cc/fonts). Keeping "${family}" is allowed, but then you must IMPORT it in the composition (@font-face or a Google Fonts @import) — otherwise local renders coerce it to Montserrat.`
             });
         }
         // Weight: the TikTok caption look is heavy. Light weights are a legitimate