@officexapp/vidfarm-devcli 0.21.38 → 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

@@ -3,7 +3,7 @@
 // An ad campaign is an evolution, not a delivery: rounds of videos that vary ONE
 // composition param (structured) or vary everything (creative), posted across
 // however many channels the director holds, then read back against one north-star
-// metric. The method lives at `https://vidfarm.cc/experiment.md`; the ledger lives
+// metric. The method lives at `https://vidfarm.cc/experiments.md`; the ledger lives
 // at the work root as one markdown file, `EXPERIMENTS_DIARY.md`.
 //
 // This module owns ONLY the parts nothing else in the CLI owns:
@@ -25,6 +25,27 @@ export const EXPERIMENT_MODES = ["creative", "structured"];
 /** The four core metrics, in funnel order. Any of them can be the north star. */
 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. **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: "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: "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. */
+export const DEFAULT_FORMAT = EASY_FORMATS[0].label;
 /** A variant only counts as tested once it has this many posts behind it. One
  *  post is noise in short form, so nothing is promoted off a single result. */
 export const MIN_POSTS_PER_VARIANT = 2;
@@ -73,6 +94,26 @@ function parseMetricNumber(raw) {
     const n = Number.parseFloat(t.replace(/[^0-9.eE+-]/g, ""));
     return Number.isFinite(n) ? n : undefined;
 }
+/** Posting frequency written next to a channel. Accepts the shapes a director
+ *  actually types: "tiktok_a x2", "tiktok_a ×2", "yt_a 1/day", "li_a 3/week",
+ *  "fb_a 2/month", and a bare "ig_a" (= once per epoch). "paused" or a 0 rate
+ *  contributes no capacity but stays listed. */
+const CHANNEL_RATE_RE = /^(.*?)[\s(]*(?:[x×]\s*(\d+(?:\.\d+)?)|(\d+(?:\.\d+)?)\s*\/\s*(day|epoch|wk|week|mo|month)|(paused|off))\)?\s*$/i;
+export function parseChannelPlan(entry) {
+    const raw = entry.trim();
+    const m = CHANNEL_RATE_RE.exec(raw);
+    if (!m || (!m[2] && !m[3] && !m[5]))
+        return { id: raw, perEpoch: 1, raw };
+    const id = (m[1] ?? "").trim() || raw;
+    if (m[5])
+        return { id, perEpoch: 0, raw };
+    if (m[2])
+        return { id, perEpoch: Number.parseFloat(m[2]), raw };
+    const n = Number.parseFloat(m[3] ?? "1");
+    const unit = (m[4] ?? "day").toLowerCase();
+    const perEpoch = unit.startsWith("w") ? n / 7 : unit.startsWith("m") ? n / 30 : n;
+    return { id, perEpoch, raw };
+}
 function isMode(value) {
     return EXPERIMENT_MODES.includes(value);
 }
@@ -84,7 +125,7 @@ function isMode(value) {
 export function parseDiary(source) {
     const warnings = [];
     const lines = source.split(/\r?\n/);
-    const setup = { secondary: [], channels: [], extra: {} };
+    const setup = { secondary: [], channels: [], channelPlans: [], extra: {} };
     const rounds = [];
     let inSetup = false;
     let round = null;
@@ -214,14 +255,14 @@ export function parseDiary(source) {
                 const video = (get("video", "id", "clip") ?? "").trim();
                 const metrics = {};
                 tableHeader.forEach((name, idx) => {
-                    if (!name || name === "video" || name === "id" || name === "clip" || name === "note" || name === "notes")
+                    if (!name || name === "video" || name === "id" || name === "clip" || name === "note" || name === "notes" || name === "channel" || name === "account")
                         return;
                     const value = parseMetricNumber(row[idx] ?? "");
                     if (value !== undefined)
                         metrics[name] = value;
                 });
                 if (video) {
-                    results.rows.push({ video, metrics, note: get("note", "notes"), line: lineNo });
+                    results.rows.push({ video, metrics, channel: get("channel", "account")?.trim() || undefined, note: get("note", "notes"), line: lineNo });
                 }
                 else {
                     warnings.push({ message: "Result row with no video id — skipped.", line: lineNo });
@@ -255,9 +296,11 @@ export function parseDiary(source) {
                 }
                 else if (key === "channels" || key.startsWith("channels")) {
                     const inner = /\(([^)]*)\)/.exec(value);
-                    setup.channels = splitList(value.replace(/\([^)]*\)/g, ""));
-                    if (inner && setup.channels.length === 0)
-                        setup.channels = splitList(inner[1] ?? "");
+                    // Strip only a LEADING "(capacity N/epoch)" label — a per-channel rate
+                    // in parentheses further along is data, not a label.
+                    const entries = splitList(value.replace(/^\s*\([^)]*\)\s*/, ""));
+                    setup.channelPlans = (entries.length ? entries : splitList(inner?.[1] ?? "")).map(parseChannelPlan);
+                    setup.channels = setup.channelPlans.map((p) => p.id);
                 }
                 else if (key === "mode") {
                     const normalized = value.toLowerCase();
@@ -268,6 +311,8 @@ export function parseDiary(source) {
                         warnings.push({ message: `Unknown mode "${value}" — expected creative or structured.`, line: lineNo });
                     }
                 }
+                else if (key === "format" || key === "video_format")
+                    setup.format = value;
                 else if (key === "product")
                     setup.product = value;
                 else if (key.startsWith("baseline"))
@@ -299,6 +344,8 @@ export function parseDiary(source) {
                             round.variable = v;
                         else if (k === "constants")
                             round.constants = splitList(v);
+                        else if (k === "format")
+                            round.format = v;
                         else
                             round.extra[k] = v;
                     }
@@ -353,7 +400,7 @@ export function readDiary(dir) {
             exists: false,
             path: EXPERIMENTS_FILENAME,
             absPath,
-            manifest: { setup: { secondary: [], channels: [], extra: {} }, rounds: [], warnings: [] }
+            manifest: { setup: { secondary: [], channels: [], channelPlans: [], extra: {} }, rounds: [], warnings: [] }
         };
     }
     return { exists: true, path: EXPERIMENTS_FILENAME, absPath, manifest: parseDiary(readFileSync(absPath, "utf8")) };
@@ -364,7 +411,11 @@ export function readDiary(dir) {
 /** Videos per epoch = channels held. One channel carries about one test post a
  *  day before it reads as spam. */
 export function capacityOf(setup) {
-    return setup.channels.length;
+    if (setup.channelPlans.length === 0)
+        return setup.channels.length;
+    const total = setup.channelPlans.reduce((sum, p) => sum + (Number.isFinite(p.perEpoch) ? p.perEpoch : 0), 0);
+    // Round to 2dp so "3/week" style fractions don't print as 0.4285714285714286.
+    return Math.round(total * 100) / 100;
 }
 export function epochsNeeded(videos, capacity) {
     if (!Number.isFinite(videos) || videos <= 0)
@@ -373,6 +424,36 @@ export function epochsNeeded(videos, capacity) {
         return Number.POSITIVE_INFINITY;
     return Math.ceil(videos / capacity);
 }
+/** Deal N video slots out across channels, epoch by epoch, respecting each
+ *  channel's posting frequency.
+ *
+ *  Fractional rates (a channel that can only take 3 posts a week) are handled by
+ *  carrying credit forward: the channel accrues `perEpoch` each epoch and takes a
+ *  slot whenever its credit reaches 1. That keeps a 3/week channel on a real
+ *  every-other-day cadence instead of either over-posting it daily or dropping it.
+ *  Deterministic — same inputs, same schedule. */
+export function allocateSlots(plans, videos) {
+    const active = plans.filter((p) => Number.isFinite(p.perEpoch) && p.perEpoch > 0);
+    if (active.length === 0 || videos <= 0)
+        return [];
+    const credit = new Map(active.map((p) => [p.id, 0]));
+    const out = [];
+    // Bound the loop: even the slowest channel mix can't need more epochs than
+    // videos / smallest-rate, and the +2 covers the first accrual.
+    const slowest = Math.min(...active.map((p) => p.perEpoch));
+    const maxEpochs = Math.ceil(videos / slowest) + 2;
+    for (let epoch = 1; epoch <= maxEpochs && out.length < videos; epoch++) {
+        for (const plan of active) {
+            let c = (credit.get(plan.id) ?? 0) + plan.perEpoch;
+            while (c >= 1 && out.length < videos) {
+                out.push({ epoch, channel: plan.id });
+                c -= 1;
+            }
+            credit.set(plan.id, c);
+        }
+    }
+    return out;
+}
 export function median(values) {
     const sorted = values.filter((v) => Number.isFinite(v)).sort((a, b) => a - b);
     if (sorted.length === 0)
@@ -387,6 +468,8 @@ export function analyzeRound(round, setup, opts) {
     const slotRows = round.epochs.flatMap((e) => e.rows);
     const variantOf = new Map();
     const postsOf = new Map();
+    // A video can occupy more than one slot — that IS the cross-account retest.
+    const channelsOf = new Map();
     for (const row of slotRows) {
         if (!row.video)
             continue;
@@ -394,6 +477,11 @@ export function analyzeRound(round, setup, opts) {
             variantOf.set(row.video, row.variant);
         if (row.posted)
             postsOf.set(row.video, (postsOf.get(row.video) ?? 0) + 1);
+        if (row.channel) {
+            const set = channelsOf.get(row.video) ?? new Set();
+            set.add(row.channel);
+            channelsOf.set(row.video, set);
+        }
     }
     const resultRows = round.results.flatMap((block) => block.rows.map((row) => ({ row, block })));
     const scored = [];
@@ -404,15 +492,59 @@ export function analyzeRound(round, setup, opts) {
         scored.push({
             video: row.video,
             value,
+            channel: row.channel ?? (channelsOf.get(row.video)?.size === 1 ? Array.from(channelsOf.get(row.video) ?? [])[0] : undefined),
             variant: variantOf.get(row.video),
             posts: postsOf.get(row.video) ?? 0,
             age: block.age,
             source: block.source
         });
     }
+    // A RETEST is the same video MEASURED on two accounts — not a video whose slot
+    // was planned for one account and whose result came back from another (that is
+    // a plan change, and counting it would clear the confound warning for free).
+    // So: prefer distinct channels across RESULT rows; fall back to distinct
+    // channels across slots that were actually marked posted.
+    const measuredOn = new Map();
+    for (const s of scored) {
+        if (!s.channel)
+            continue;
+        const set = measuredOn.get(s.video) ?? new Set();
+        set.add(s.channel);
+        measuredOn.set(s.video, set);
+    }
+    for (const row of slotRows) {
+        if (!row.video || !row.channel || !row.posted)
+            continue;
+        if (resultRows.some(({ row: r }) => r.video === row.video && r.channel))
+            continue;
+        const set = measuredOn.get(row.video) ?? new Set();
+        set.add(row.channel);
+        measuredOn.set(row.video, set);
+    }
     const med = median(scored.map((s) => s.value));
     for (const s of scored)
         s.ratio = med && med > 0 ? s.value / med : undefined;
+    // Normalize per ACCOUNT. Account health moves numbers by multiples, so a video
+    // is only fairly judged against its own channel's median — and a channel needs
+    // at least two results before it has one.
+    const byChannel = new Map();
+    for (const s of scored) {
+        if (!s.channel)
+            continue;
+        byChannel.set(s.channel, [...(byChannel.get(s.channel) ?? []), s.value]);
+    }
+    const channelMedians = {};
+    for (const [channel, values] of byChannel) {
+        if (values.length < 2)
+            continue;
+        const m = median(values);
+        if (m !== undefined && m > 0)
+            channelMedians[channel] = m;
+    }
+    for (const s of scored) {
+        const m = s.channel ? channelMedians[s.channel] : undefined;
+        s.channelRatio = m ? s.value / m : undefined;
+    }
     const ranked = [...scored].sort((a, b) => b.value - a.value);
     const reported = new Set(resultRows.map(({ row }) => row.video));
     return {
@@ -428,7 +560,11 @@ export function analyzeRound(round, setup, opts) {
         awaiting: slotRows.filter((r) => r.posted && r.video && !reported.has(r.video)).map((r) => r.video),
         scored: ranked,
         median: med,
-        outliers: med && med > 0 ? ranked.filter((s) => (s.ratio ?? 0) >= outlierRatio) : [],
+        channelMedians,
+        retested: Array.from(measuredOn.entries()).filter(([, set]) => set.size > 1).map(([video]) => video),
+        // Prefer the account-normalized ratio when the channel has a baseline; fall
+        // back to the round median otherwise.
+        outliers: med && med > 0 ? ranked.filter((s) => (s.channelRatio ?? s.ratio ?? 0) >= outlierRatio) : [],
         weakest: ranked[ranked.length - 1],
         readContexts: Array.from(new Set(round.results.map((b) => `${b.source ?? "?"}@${b.age ?? "?"}`)))
     };
@@ -445,6 +581,14 @@ export function lintDiary(manifest, analyses) {
             fix: `Add "- North-star metric: ${DEFAULT_METRIC}" (comments is the richest early-stage intel).`
         });
     }
+    if (!setup.format) {
+        findings.push({
+            level: "warn",
+            code: "no-format",
+            message: "No starting video format in Setup — the format is a PLANNING decision, not something to discover while editing.",
+            fix: `Pick one in the interview and write it down: ${EASY_FORMATS.map((f) => f.label).join(" · ")}. No opinion? Take "${DEFAULT_FORMAT}" and move — don't stall.`
+        });
+    }
     if (capacity === 0) {
         findings.push({
             level: "warn",
@@ -483,6 +627,17 @@ export function lintDiary(manifest, analyses) {
             if (!round.variable) {
                 findings.push({ ...at, level: "error", code: "no-variable", message: `Round ${at.round} is structured but names no variable.`, fix: "Add \"- Variable: <param>\"." });
             }
+            // Format is a constant in most rounds. If the round neither pins one nor
+            // inherits one from Setup, its "constants" were never actually constant.
+            if (!round.format && !setup.format && !/format/i.test(round.variable ?? "")) {
+                findings.push({
+                    ...at,
+                    level: "warn",
+                    code: "round-no-format",
+                    message: `Round ${at.round} names no video format, so every video in it can drift to a different one.`,
+                    fix: `Add "- Format: <choice>" to the round (or to Setup, which it inherits). Default: "${DEFAULT_FORMAT}".`
+                });
+            }
             if (round.constants.length === 0) {
                 findings.push({
                     ...at,
@@ -515,6 +670,22 @@ export function lintDiary(manifest, analyses) {
                 fix: "Re-read the whole round at one age, or compare only within a single results block."
             });
         }
+        // Account health is the biggest confounder in the method: it moves numbers by
+        // multiples, often more than the variable under test. A round whose videos each
+        // sat on a different account has measured the accounts as much as the videos.
+        const channelsUsed = new Set(analysis.scored.map((s) => s.channel).filter(Boolean));
+        if (channelsUsed.size > 1 && analysis.retested.length === 0 && analysis.scored.length > 1) {
+            const normalized = Object.keys(analysis.channelMedians).length;
+            findings.push({
+                ...at,
+                level: normalized > 0 ? "warn" : "error",
+                code: "account-health-confound",
+                message: `Round ${at.round} ranks ${analysis.scored.length} videos across ${channelsUsed.size} accounts with no variant retested on a second account — account health can outweigh the variable you are testing.`,
+                fix: normalized > 0
+                    ? "Per-account medians exist for some channels — judge by those, not the round median. Then retest the leader on a different account to confirm the ordering holds."
+                    : "Re-post the apparent winner on a DIFFERENT account (deduped) and the apparent loser on the winner's account. If the ordering survives the swap, the effect is real; if it flips, you measured account health."
+            });
+        }
         for (const outlier of analysis.outliers) {
             if (outlier.posts < MIN_POSTS_PER_VARIANT) {
                 findings.push({
@@ -529,16 +700,50 @@ export function lintDiary(manifest, analyses) {
         if (capacity > 0 && analysis.epochsRun > 0) {
             const latest = round.epochs[round.epochs.length - 1];
             const used = latest?.rows.length ?? 0;
-            if (used > 0 && used < capacity) {
+            // Only whole slots are postable, and fractional capacity ("3/week") leaves a
+            // remainder that isn't a usable slot — don't report 0.43 free.
+            const free = Math.floor(capacity - used);
+            if (used > 0 && free >= 1) {
                 findings.push({
                     ...at,
                     level: "info",
                     code: "unspent-capacity",
-                    message: `Latest epoch of round ${at.round} uses ${used} of ${capacity} slots — ${capacity - used} free.`,
+                    message: `Latest epoch of round ${at.round} uses ${used} of ${capacity} slots — ${free} free.`,
                     fix: "Fill them: more samples of this variable, a parallel round on another param (formats or hooks are the usual next), or a one-off theory logged as a one-off."
                 });
             }
         }
+        // A channel scheduled beyond its own stated frequency is how an account gets
+        // throttled or flagged — and a throttled account poisons every number on it.
+        for (const epoch of round.epochs) {
+            const counts = new Map();
+            for (const row of epoch.rows) {
+                if (!row.channel)
+                    continue;
+                counts.set(row.channel, (counts.get(row.channel) ?? 0) + 1);
+            }
+            for (const [channel, used] of counts) {
+                const plan = setup.channelPlans.find((p) => p.id === channel);
+                if (!plan)
+                    continue;
+                const allowed = Math.max(1, Math.ceil(plan.perEpoch));
+                if (plan.perEpoch === 0) {
+                    findings.push({ ...at, level: "warn", code: "paused-channel-scheduled", message: `Round ${at.round}, epoch ${epoch.label ?? "?"}: ${channel} is marked paused but has ${used} slot(s).`, fix: "Un-pause it in Setup, or move those slots to an active channel." });
+                }
+                else if (used > allowed) {
+                    // A bare channel name carries no explicit rate — say "the default" rather
+                    // than echoing the id back as if it were a frequency.
+                    const stated = plan.raw.trim() === plan.id ? "once per epoch (the default)" : `${plan.raw.trim()} (~${allowed}/epoch)`;
+                    findings.push({
+                        ...at,
+                        level: "warn",
+                        code: "channel-overposted",
+                        message: `Round ${at.round}, epoch ${epoch.label ?? "?"}: ${channel} has ${used} slots but its stated frequency is ${stated}.`,
+                        fix: "Spread them over more epochs, or raise the channel's frequency in Setup if it really can take that volume."
+                    });
+                }
+            }
+        }
         if (analysis.awaiting.length > 0) {
             findings.push({ ...at, level: "info", code: "awaiting-results", message: `Round ${at.round}: ${analysis.awaiting.length} posted video(s) have no results logged (${analysis.awaiting.join(", ")}).`, fix: "Log them: `vidfarm experiment log <video> --views N --comments N --source <where> --age 48h`." });
         }
@@ -552,22 +757,34 @@ export function lintDiary(manifest, analyses) {
     return findings;
 }
 export function renderDiaryScaffold(input) {
-    const channels = input.channels ?? [];
+    const plans = input.channelPlans?.length
+        ? input.channelPlans
+        : (input.channels ?? []).map((id) => parseChannelPlan(id));
+    const channelList = plans.map((p) => p.raw.trim()).join(", ");
+    const capacity = plans.length
+        ? Math.round(plans.reduce((sum, p) => sum + p.perEpoch, 0) * 100) / 100
+        : 0;
     const metric = input.metric ?? DEFAULT_METRIC;
     const secondary = input.secondary?.length ? input.secondary : CORE_METRICS.filter((m) => m !== metric).slice(0, 2);
     return [
         `# Experiments Diary — ${input.product ?? "<product>"}`,
         "",
-        `Method: https://vidfarm.cc/experiment.md · started ${input.date ?? ""}`.trim(),
+        `Method: https://vidfarm.cc/experiments.md · started ${input.date ?? ""}`.trim(),
         "",
         "## Setup",
         `- North-star metric: ${metric} (secondary: ${secondary.join(", ")})`,
-        `- Channels (capacity ${channels.length || "?"}/epoch): ${channels.length ? channels.join(", ") : "<run `vidfarm channels` and list them>"}`,
+        `- Channels (capacity ${capacity || "?"}/epoch): ${channelList || "<run `vidfarm channels` and list them>"}`,
+        "  <!-- per-channel frequency: \"name x2\" = twice an epoch · \"name 3/week\" · \"name paused\" · bare name = once -->",
         `- Mode: ${input.mode ?? "creative"}`,
+        `- Format: ${input.format ?? DEFAULT_FORMAT}`,
         `- Editors: ${input.editors ?? "agent"}`,
         `- Baseline checkpoint: ${input.baseline ?? "kinetic captions over b-roll, no VO, ~20s"}`,
         `- Analytics source: ${input.source ?? "<flockposter | manual | email-channel | gigworkers>"}`,
         "",
+        "",
+        "Format menu (copywriting-led — the words do the work; all ~$0 via `vidfarm public-raws --categories`):",
+        ...EASY_FORMATS.map((f) => `- ${f.label} — ${f.note}`),
+        "",
         "Append only. Never rewrite history here — correct it with a later entry.",
         ""
     ].join("\n");
@@ -578,22 +795,30 @@ export function renderRoundScaffold(input) {
     const slots = input.slots?.length
         ? input.slots
         : Array.from({ length: videos }, (_, i) => `v${String(i + 1).padStart(3, "0")}`);
-    const channels = input.channels ?? [];
-    const perEpoch = input.capacity > 0 ? input.capacity : slots.length;
+    // Deal the slots out by each channel's OWN posting frequency, not round-robin —
+    // a 2/day channel earns two slots an epoch and a 3/week channel skips epochs.
+    const plans = input.channelPlans?.length
+        ? input.channelPlans
+        : (input.channels ?? []).map((id) => ({ id, perEpoch: 1, raw: id }));
+    const allocation = allocateSlots(plans, slots.length);
+    const byEpoch = new Map();
+    slots.forEach((raw, i) => {
+        const [video, variant] = raw.split("|").map((s) => s.trim());
+        // No channel plan at all → still emit the row, with the channel left blank.
+        const slot = allocation[i];
+        const epoch = slot?.epoch ?? Math.floor(i / Math.max(1, input.capacity || slots.length)) + 1;
+        const list = byEpoch.get(epoch) ?? [];
+        list.push({ video: video ?? "", variant, channel: slot?.channel ?? "" });
+        byEpoch.set(epoch, list);
+    });
     const epochBlocks = [];
-    for (let e = 0; e < Math.max(1, Number.isFinite(epochs) ? epochs : 1); e++) {
-        const slice = slots.slice(e * perEpoch, (e + 1) * perEpoch);
-        if (slice.length === 0)
-            break;
+    for (const [epoch, rows] of Array.from(byEpoch.entries()).sort((a, b) => a[0] - b[0])) {
         epochBlocks.push([
-            `### Epoch ${e + 1} — ${e === 0 ? (input.date ?? "<date>") : "<date>"}`,
+            `### Epoch ${epoch} — ${epoch === 1 ? (input.date ?? "<date>") : "<date>"}`,
             "",
             "| slot | video | variant | channel | posted |",
             "|---|---|---|---|---|",
-            ...slice.map((raw, i) => {
-                const [video, variant] = raw.split("|").map((s) => s.trim());
-                return `| ${i + 1} | ${video ?? ""} | ${variant ?? ""} | ${channels[i % Math.max(1, channels.length)] ?? ""} | |`;
-            }),
+            ...rows.map((r, i) => `| ${i + 1} | ${r.video} | ${r.variant ?? ""} | ${r.channel} | |`),
             ""
         ].join("\n"));
     }
@@ -601,8 +826,9 @@ export function renderRoundScaffold(input) {
         `## Round ${input.number}${input.title ? ` — ${input.title}` : input.variable ? ` — ${input.variable}` : ""}`,
         `- Mode: ${input.mode ?? "creative"}`,
         ...(input.variable ? [`- Variable: ${input.variable}`] : []),
+        `- Format: ${input.format ?? DEFAULT_FORMAT}`,
         `- Constants: ${input.constants?.length ? input.constants.join(", ") : "—"}`,
-        `- Videos: ${videos} · Capacity ${input.capacity || "?"}/epoch → ${Number.isFinite(epochs) ? epochs : "?"} epoch(s)`,
+        `- Videos: ${videos} · Capacity ${input.capacity || "?"} slots/epoch → ${Number.isFinite(epochs) ? epochs : "?"} epoch(s)`,
         `- Editors: ${input.editors ?? "agent"}`,
         `- Justification: ${input.justification ?? "<why this variable is worth the capacity before the others>"}`,
         `- Win condition: ${input.win ?? `any variant at >=${DEFAULT_OUTLIER_RATIO}x median`}`,
@@ -638,16 +864,16 @@ export function appendResult(source, manifest, roundIndex, input) {
         const header = manifest.rounds[roundIndex]?.results.find((b) => b === match);
         const known = header ? Object.keys(match.rows[0]?.metrics ?? {}) : columns;
         const ordered = known.length ? known : columns;
-        const row = `| ${input.video} | ${ordered.map((c) => (input.metrics[c] !== undefined ? String(input.metrics[c]) : "")).join(" | ")} | ${input.note ?? ""} |`;
+        const row = `| ${input.video} | ${input.channel ?? ""} | ${ordered.map((c) => (input.metrics[c] !== undefined ? String(input.metrics[c]) : "")).join(" | ")} | ${input.note ?? ""} |`;
         return { text: spliceLines(source, match.endLine, row), block: "existing" };
     }
     const ordered = columns.length ? columns : [...CORE_METRICS];
     const block = [
         `### Results — read ${input.date}${input.source ? `, source: ${input.source}` : ""}${input.age ? `, age: ${input.age}` : ""}`,
         "",
-        `| video | ${ordered.join(" | ")} | note |`,
-        `|---|${ordered.map(() => "---|").join("")}---|`,
-        `| ${input.video} | ${ordered.map((c) => (input.metrics[c] !== undefined ? String(input.metrics[c]) : "")).join(" | ")} | ${input.note ?? ""} |`
+        `| video | channel | ${ordered.join(" | ")} | note |`,
+        `|---|---|${ordered.map(() => "---|").join("")}---|`,
+        `| ${input.video} | ${input.channel ?? ""} | ${ordered.map((c) => (input.metrics[c] !== undefined ? String(input.metrics[c]) : "")).join(" | ")} | ${input.note ?? ""} |`
     ].join("\n");
     return { text: spliceLines(source, round.endLine, `\n${block}`), block: "new" };
 }

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.