npm - @officexapp/vidfarm-devcli - Versions diffs - 0.21.38 → 0.21.39 - Mend

@officexapp/vidfarm-devcli 0.21.38 → 0.21.39

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/.agents/skills/vidfarm/references/automation-and-local-dev.md +1 -1
package/SKILL.md +2 -2
package/dist/src/cli.js +53 -16
package/dist/src/devcli/experiments.js +252 -31
package/{experiment.md → experiments.md} +97 -30
package/package.json +2 -2

package/.agents/skills/vidfarm/references/automation-and-local-dev.md CHANGED Viewed

@@ -284,7 +284,7 @@ The licensed harness also carries the **generative build workflow** guidance (ch
 | `vidfarm handoff image --theme "<what>" [--items "a,b,c"] [--style …] [--single]` | local (pure text) | **The interactive-mode IMAGE brief.** Prints the exact prompt, the numbered steps, the free tools (meta.ai / ChatGPT / Gemini / HF Spaces) and the follow-up command. Defaults to a **sticker pack**: ONE sheet holding every item on a chroma plate → `vidfarm sticker-pack` splits it for $0. Picks a plate the art won't collide with (green art → magenta plate), spells out what the local keyer actually needs (a crisp silhouette in a different color from the plate, sealed shapes, clear gaps between items — hollow art and plate-colored detail INSIDE a shape are fine now), and carries that `--key-color` into the follow-up. `--single` for one subject. `--zoned` asks instead for a color-block sheet (one panel colour per item) and hands back a `--zones RxC` follow-up — worth it when the pack's own colors fight one plate, but leave it off for a free consumer tool that may not follow a grid. |
 | `vidfarm handoff raws --keywords "a,b" [--platforms tiktok,youtube] [--count N] [--purpose "…"]` | local (pure text) | **The interactive-mode CLIP-SOURCING brief** — the bottom rung of the sourcing ladder (browser control → `clipper`/`raws scan --cloud` → public raws → the human). Prints what to search, how to download (a Google *search* for a downloader, never a link that rots), and the import command for when the folder is ready. |
 | `vidfarm storyboard [dir] [--init] [--frames "Title\|scene,…"] [--json]` | local (`STORYBOARD.md` / `SCRIPT.md`) | **The plan pass, and a core part of the composition format.** Scaffolds/reads the project's `STORYBOARD.md`: ordered frames with `duration`/`status`/`src`/`scene`/`voiceover`. The Vidfarm editor renders this file in its **Storyboard** view (contact sheet + per-frame comments + `outline → built → animated` progress), so it's the cheapest place to get a director's approval before building. Not to be confused with `vidfarm sequence` (which GENERATES storyboard images for the pure-videogen pipeline). Alias: `plan`. |
-| `vidfarm experiment [dir] [--init] [round …] [log <video> …] [--json]` | local (`EXPERIMENTS_DIARY.md`) | **Ad testing over weeks, not one video.** Owns the campaign ledger and ONLY that: sizes each round (`videos ÷ channels = epochs`), ranks the north-star metric, flags outliers vs the median, and lints the method — two variables in one structured round, a winner promoted off one post, results read at mixed ages, a structured round handed to gigworkers, unspent capacity. Feedback, not a gate (exits 0). Two writes: `round --videos N --variable angle …` and `log <video> --comments N --source flockposter --age 48h` (or `log <video> --posted --channel <id>`, which only RECORDS a post). It deliberately does not re-wrap `channels` (capacity), `harness`/`qa` (constants), `handoff` (briefs), `dedupe` (per-channel copies) or `approve`+`schedule` (posting). Method: <https://vidfarm.cc/experiment.md>. Alias: `experiments`. |
+| `vidfarm experiment [dir] [--init] [round …] [log <video> …] [--json]` | local (`EXPERIMENTS_DIARY.md`) | **Ad testing over weeks, not one video.** Owns the campaign ledger and ONLY that: sizes each round (`videos ÷ capacity = epochs`, where capacity is the SUM of per-channel posting rates — `--channels "tiktok_a x2, li_a 3/week, fb_a paused"` — and epoch slots are dealt out in proportion, warning on `channel-overposted`), ranks the north-star metric, flags outliers vs the median, and lints the method — two variables in one structured round, a winner promoted off one post, results read at mixed ages, a structured round handed to gigworkers, unspent capacity. Feedback, not a gate (exits 0). Also carries the FORMAT decision into planning: `--init` prints the copywriting-led menu (b-roll / talking head / process / loop background / satisfying / lifestyle / POV quote) and records the pick in Setup, which every round inherits. Two writes: `round --videos N --variable angle …` and `log <video> --comments N --channel <acct> --source flockposter --age 48h` (ALWAYS pass `--channel`: it keeps a per-account median so each video is ranked against its own account, not the fleet — account health moves numbers by multiples — and a second account's reading counts as the retest that clears `account-health-confound`) (or `log <video> --posted --channel <id>`, which only RECORDS a post). It deliberately does not re-wrap `channels` (capacity), `harness`/`qa` (constants), `handoff` (briefs), `dedupe` (per-channel copies) or `approve`+`schedule` (posting). Method: <https://vidfarm.cc/experiments.md>. Alias: `experiments`. |
 | `vidfarm wallet [--job <id>\|--tracer <t>] [--limit <n>]` | `GET /api/v1/user/me/wallet` | cost log: balance + lifetime spend + recent charges. `--job <renderJobId>` prints **what that one video cost** (sums its charges); `--tracer <t>` sums a tracer. Cloud-only; readable on the free plan too (shows $0.00). Aliases: `spend`, `costs` |
 | `vidfarm provider-keys` / `vidfarm add-provider-key <p> <secret>` | `GET`·`POST /api/v1/user/me/provider-keys` | manage AI keys |
 | `vidfarm upload <file> [--folder <path>]` | presign → S3 PUT → finalize (`.../temporary-files/presign` + `.../temporary-files`) | upload → durable URL (ephemeral, 30-day TTL; prefer `--folder temp` for scratch). Goes direct to S3, so large files (up to **200 MB**) bypass the ~6 MB Lambda body limit |

package/SKILL.md CHANGED Viewed

@@ -103,7 +103,7 @@ Otherwise, pull it over the network and load only the reference you need:
   - `references/rest-api.md` — complete REST map (load only for direct HTTP integration)
   - `recipes/` — `find-and-fork-template.md` · `retheme-template.md` · `local-edit-render-approve.md` · `onboard-a-new-director.md` · `bulk-scripting-with-a-harness.md` (volume/N-variant work) · `cutout-graphics-for-explainers.md` (sticker-art explainers)
   - `harnesses/` — `README.md` (**start here for anything harness-shaped**: the three director phrasings, the format, the DNA strands) plus the bundled bases `short-form` · `hooks` · `ugc-testimonial` · `explainer` · `product-demo`, each as `<name>.HARNESS.md`
-- **Running ad experiments (finding the winning ad):** `https://vidfarm.cc/experiment.md` — **fetch this whenever the ask is about performance rather than one video**: "which ad should I run", "test these angles", "what's working", "we post daily on N channels", or any campaign that runs for weeks. It primes you as a short-form ad scientist: the KPI interview (default north star = **comments**), channel count → testing capacity, **epochs** and **rounds**, **Creative Mode** (N free-form videos, the default, ideal for gigworkers) vs **Structured Mode** (one variable, everything else pinned by a harness, your own agents only), the composition params, and the standalone `EXPERIMENTS_DIARY.md` ledger. Plan → user approval → one static handoff document per video.
+- **Running ad experiments (finding the winning ad):** `https://vidfarm.cc/experiments.md` — **fetch this whenever the ask is about performance rather than one video**: "which ad should I run", "test these angles", "what's working", "we post daily on N channels", or any campaign that runs for weeks. It primes you as a short-form ad scientist: the KPI interview (default north star = **comments**), channel count → testing capacity, **epochs** and **rounds**, **Creative Mode** (N free-form videos, the default, ideal for gigworkers) vs **Structured Mode** (one variable, everything else pinned by a harness, your own agents only), the composition params, and the standalone `EXPERIMENTS_DIARY.md` ledger. Plan → user approval → one static handoff document per video.
 - **Crowdsourcing the editing:** `https://vidfarm.cc/crowdsourcing.md` — the client-vs-gigworker router for agentic clipper loops (a Dollar Platoon vending machine, recruiting editors, claiming tasks, proofs and payouts). This is how a Creative Mode batch gets produced in bulk.
 - **Updating Vidfarm:** `https://vidfarm.cc/update.md` — **fetch this file whenever the user asks to update/upgrade Vidfarm**, says their skill or devcli is out of date, or hits a command/route that "used to work". It's the clean uninstall→reinstall runbook for BOTH halves (the `vidfarm` skill pack and `@officexapp/vidfarm-devcli`), and it carries the current breaking-change notes — read it live rather than improvising an `npm i -g`, because the notes are exactly what a blind reinstall misses.
 - **Skill pack index (what else is installable):** `https://vidfarm.cc/skill-pack/index.json`
@@ -125,7 +125,7 @@ For composition *authoring* craft (motion, keyframes, scene design), Vidfarm shi
 5. "Script / batch / render loop" → `references/automation-and-local-dev.md`
 5b. **"Explainer with cutout/sticker art"** (flat illustrations on a stage, sticker sheets, "like those animated explainer videos") → `recipes/cutout-graphics-for-explainers.md`
 6. "I need TTS / music / captions / background removal" → `references/primitives.md`
-6b. **"Which ad wins?" / "test these angles" / "we post every day and want results"** → fetch <https://vidfarm.cc/experiment.md> and run the experimentation method (capacity → epochs/rounds → creative vs structured → `EXPERIMENTS_DIARY.md`). Do not improvise a testing plan; a round with two variables teaches nothing. To produce a bulk batch with gigworkers, pair it with <https://vidfarm.cc/crowdsourcing.md>.
+6b. **"Which ad wins?" / "test these angles" / "we post every day and want results"** → fetch <https://vidfarm.cc/experiments.md> and run the experimentation method (capacity → epochs/rounds → creative vs structured → `EXPERIMENTS_DIARY.md`). Do not improvise a testing plan; a round with two variables teaches nothing. To produce a bulk batch with gigworkers, pair it with <https://vidfarm.cc/crowdsourcing.md>.
 7. **"Update / upgrade vidfarm"** (or anything that smells like a stale install — a missing command, a 404 on a documented route, a version mismatch) → fetch <https://vidfarm.cc/update.md> and follow it. Update the skill pack and the devcli **together**; updating one alone is the usual cause of "the skill says to do X but it fails."
 ## Non-negotiables

package/dist/src/cli.js CHANGED Viewed

@@ -38,7 +38,7 @@ import { CostModeBlockedError, assertBilledAllowed, clearStoredCostMode, costMod
 import { INTERACTION_MODES, INTERACTION_MODE_BLURB, clearStoredInteractionMode, interactionModeExplainer, interactionModeSummaryLine, interactiveOfferLine, normalizeInteractionMode, resolveInteractionMode, writeStoredInteractionMode } from "./devcli/interaction-mode.js";
 import { buildImageHandoff, buildRawsHandoff, formatHandoff } from "./devcli/handoff.js";
 import { STORYBOARD_FILENAME, readStoryboard, renderStoryboardScaffold, storyboardStage } from "./devcli/storyboard.js";
-import { CORE_METRICS, DEFAULT_METRIC, EXPERIMENTS_FILENAME, EXPERIMENT_MODES, analyzeRound, appendResult, appendRound, capacityOf, epochsNeeded, findRoundIndex, lintDiary, markPosted, readDiary, renderDiaryScaffold, writeDiary } from "./devcli/experiments.js";
+import { CORE_METRICS, DEFAULT_FORMAT, DEFAULT_METRIC, EASY_FORMATS, EXPERIMENTS_FILENAME, EXPERIMENT_MODES, analyzeRound, appendResult, appendRound, capacityOf, epochsNeeded, findRoundIndex, lintDiary, markPosted, readDiary, renderDiaryScaffold, writeDiary } from "./devcli/experiments.js";
 // vidfarm-devcli — command-line bridge for the Vidfarm video studio. The
 // `serve` command boots the FULL editor locally (single origin, disk-backed
 // records + storage) so power users edit compositions on disk while a browser
@@ -132,21 +132,33 @@ Account (persisted login — points the CLI + \`serve\` at cloud prod):
     --title/--format/--message/--arc/--audience   Frontmatter for --init
     --json                  The parsed manifest (frames, statuses, warnings)
   experiment [dir]          AD TESTING — read the campaign's EXPERIMENTS_DIARY.md,
-                            size each round (videos ÷ channels = epochs), rank the
+                            size each round (videos ÷ capacity = epochs), rank the
                             north-star metric, flag outliers vs the median, and lint
                             the method (two variables in one structured round, a
                             winner promoted off one post, results read at mixed ages,
                             a structured round handed to gigworkers, unspent capacity).
-                            Feedback, not a gate. Method: vidfarm.cc/experiment.md
+                            Feedback, not a gate. Method: vidfarm.cc/experiments.md
                             (alias: experiments)
-    --init                  Scaffold the diary (--metric/--channels/--mode/--product/
-                            --baseline/--editors · --force overwrites)
+    --init                  Scaffold the diary. --channels takes PER-CHANNEL RATES —
+                            "tiktok_a x2, tiktok_b, yt_a 1/day, li_a 3/week, fb_a paused"
+                            — and capacity becomes the SUM of them, so round slots are
+                            dealt out in proportion instead of round-robin.
+                            (--metric/--channels/--mode/--product/
+                            --format/--baseline/--editors · --force overwrites).
+                            Prints the copywriting-led FORMAT MENU (b-roll · talking
+                            head · process · loop background · satisfying · lifestyle ·
+                            POV quote) when --format is omitted — the format is a
+                            planning decision, not a build-time discovery.
     round --videos <n>      Append a planned round + its epoch slot tables
       [--variable angle] [--constants "format,hooks"] [--mode structured|creative]
-      [--slots "v001|angle,…"] [--why "…"] [--win "…"] [--title "…"]
+      [--slots "v001|angle,…"] [--format "…"] [--why "…"] [--win "…"] [--title "…"]
     log <video>             Record what happened: --views/--comments/--clicks/--buys
-                            [--source flockposter] [--age 48h] [--note "…"] [--round N],
-                            or --posted [--channel <id>] to mark a slot live.
+                            --channel <id> [--source flockposter] [--age 48h] [--note "…"]
+                            [--round N], or --posted [--channel <id>] to mark a slot live.
+                            ALWAYS pass --channel: account health moves numbers by
+                            multiples, so each video is ranked against ITS OWN account's
+                            median (1.3×acct), and a reading from a second account counts
+                            as the retest that clears account-health-confound.
     --json                  Parsed setup + per-round analysis + findings
                             It does NOT re-wrap what already exists: capacity comes from
                             "vidfarm channels", constants from "vidfarm harness", briefs
@@ -9175,7 +9187,7 @@ async function runStoryboardCommand(argv) {
 }
 // `vidfarm experiment [dir]` — the ad-testing ledger, and only the ledger.
 //
-// The method is https://vidfarm.cc/experiment.md: rounds of videos that vary one
+// The method is https://vidfarm.cc/experiments.md: rounds of videos that vary one
 // composition param (structured) or vary everything (creative), posted across the
 // channels the director holds, read back against one north-star metric. This
 // command owns the three things nothing else in the CLI owns — the
@@ -9198,6 +9210,7 @@ async function runExperimentCommand(argv) {
             channels: { type: "string" },
             mode: { type: "string" },
             product: { type: "string" },
+            format: { type: "string" },
             baseline: { type: "string" },
             editors: { type: "string" },
             // round
@@ -9245,6 +9258,7 @@ async function runExperimentCommand(argv) {
         const body = renderDiaryScaffold({
             product: parsed.values.product,
             metric: parsed.values.metric?.toLowerCase(),
+            format: parsed.values.format,
             channels: asList(parsed.values.channels) ?? [],
             mode: mode,
             baseline: parsed.values.baseline,
@@ -9256,6 +9270,13 @@ async function runExperimentCommand(argv) {
             return printJson({ ok: true, created: target });
         console.log(`${GREEN}Diary created:${RESET} ${target}`);
         console.log(`${DIM}Fill the channel list from ${BOLD}vidfarm channels${RESET}${DIM} — the channel count IS your testing capacity per epoch.${RESET}`);
+        if (!parsed.values.format) {
+            // The format is a PLANNING decision. Print the menu now rather than let it
+            // get discovered at build time, one drifting video at a time.
+            console.log(`${DIM}Format defaulted to ${BOLD}${DEFAULT_FORMAT}${RESET}${DIM}. Offer the director the menu (--format sets it):${RESET}`);
+            for (const f of EASY_FORMATS)
+                console.log(`    ${DIM}·${RESET} ${f.label.padEnd(38)} ${DIM}${f.note}${RESET}`);
+        }
         console.log(`${DIM}Then plan the first round: ${BOLD}vidfarm experiment round --variable angle --videos 8 --why "awareness level is the largest unknown"${RESET}`);
         return;
     }
@@ -9282,6 +9303,7 @@ async function runExperimentCommand(argv) {
             mode: mode,
             variable: parsed.values.variable,
             constants: asList(parsed.values.constants),
+            format: parsed.values.format ?? read.manifest.setup.format,
             justification: parsed.values.why,
             win: parsed.values.win,
             videos,
@@ -9289,6 +9311,7 @@ async function runExperimentCommand(argv) {
             capacity,
             slots,
             channels: read.manifest.setup.channels,
+            channelPlans: read.manifest.setup.channelPlans,
             date: today
         };
         const next = appendRound(readFileSync(read.absPath, "utf8"), input);
@@ -9298,7 +9321,7 @@ async function runExperimentCommand(argv) {
             return printJson({ ok: true, round: number, videos, capacity, epochs: Number.isFinite(epochs) ? epochs : null, path: read.absPath });
         console.log(`${GREEN}Round ${number} planned${RESET} ${DIM}${read.absPath}${RESET}`);
         console.log(`  ${DIM}mode${RESET}      ${mode}${input.variable ? `  ${DIM}variable${RESET} ${input.variable}` : ""}`);
-        console.log(`  ${DIM}sizing${RESET}    ${videos} videos ÷ ${capacity || "?"} channels = ${BOLD}${Number.isFinite(epochs) ? epochs : "?"} epoch(s)${RESET}`);
+        console.log(`  ${DIM}sizing${RESET}    ${videos} videos ÷ ${capacity || "?"} slots/epoch = ${BOLD}${Number.isFinite(epochs) ? epochs : "?"} epoch(s)${RESET}`);
         if (mode === "structured") {
             const rel = path.relative(process.cwd(), dir);
             const shown = !rel ? "." : rel.startsWith("..") ? dir : rel;
@@ -9342,6 +9365,7 @@ async function runExperimentCommand(argv) {
         const written = appendResult(source, read.manifest, roundIndex, {
             video,
             metrics,
+            channel: parsed.values.channel,
             note: parsed.values.note,
             source: parsed.values.source ?? read.manifest.setup.source,
             age: parsed.values.age,
@@ -9374,6 +9398,7 @@ async function runExperimentCommand(argv) {
                 mode: a.round.mode ?? read.manifest.setup.mode,
                 variable: a.round.variable,
                 constants: a.round.constants,
+                format: a.round.format ?? read.manifest.setup.format ?? null,
                 metric: a.metric,
                 videosPlanned: a.videosPlanned,
                 epochsNeeded: Number.isFinite(a.epochsNeeded ?? NaN) ? a.epochsNeeded : null,
@@ -9382,6 +9407,8 @@ async function runExperimentCommand(argv) {
                 unposted: a.unposted,
                 awaiting: a.awaiting,
                 median: a.median ?? null,
+                channelMedians: a.channelMedians,
+                retested: a.retested,
                 scored: a.scored,
                 outliers: a.outliers,
                 finding: a.round.finding,
@@ -9395,15 +9422,20 @@ async function runExperimentCommand(argv) {
         console.log(`${YELLOW}No ${EXPERIMENTS_FILENAME} in ${dir}.${RESET}`);
         console.log(`${DIM}The diary is the source of truth for a campaign that runs for weeks — start it before the first post:${RESET}`);
         console.log(`  ${BOLD}vidfarm experiment --init --metric comments --channels "$(vidfarm channels --json | jq -r '.channels[].destination_id' | paste -sd,)"${RESET}`);
-        console.log(`${DIM}Method: https://vidfarm.cc/experiment.md${RESET}`);
+        console.log(`${DIM}Method: https://vidfarm.cc/experiments.md${RESET}`);
         return;
     }
     const setup = read.manifest.setup;
     const capacity = capacityOf(setup);
     console.log(`${BOLD}Experiments${RESET} ${DIM}${read.absPath}${RESET}`);
     console.log(`  ${DIM}north star${RESET}  ${setup.metric ?? `${DEFAULT_METRIC} (assumed)`}`);
-    console.log(`  ${DIM}capacity${RESET}    ${capacity || "?"} video(s)/epoch  ${DIM}${setup.channels.join(", ")}${RESET}`);
+    // Echo what the diary literally says ("li_a 3/week"), never the derived float.
+    const rates = setup.channelPlans.length
+        ? setup.channelPlans.map((p) => p.raw.trim()).join(", ")
+        : setup.channels.join(", ");
+    console.log(`  ${DIM}capacity${RESET}    ${capacity || "?"} video(s)/epoch  ${DIM}${rates}${RESET}`);
     console.log(`  ${DIM}mode${RESET}        ${setup.mode ?? "creative (assumed)"}${setup.editors ? `  ${DIM}editors${RESET} ${setup.editors}` : ""}`);
+    console.log(`  ${DIM}format${RESET}      ${setup.format ?? `${DEFAULT_FORMAT} (assumed)`}`);
     if (setup.baseline)
         console.log(`  ${DIM}baseline${RESET}    ${setup.baseline}`);
     for (const a of analyses) {
@@ -9411,17 +9443,22 @@ async function runExperimentCommand(argv) {
         console.log("");
         console.log(`  ${BOLD}Round ${n}${a.round.title ? ` — ${a.round.title}` : ""}${RESET} ${DIM}${a.round.mode ?? setup.mode ?? ""}${a.round.variable ? ` · variable: ${a.round.variable}` : ""}${RESET}`);
         if (a.videosPlanned !== undefined) {
-            console.log(`    ${DIM}sizing${RESET}   ${a.videosPlanned} videos ÷ ${a.capacity || "?"} = ${Number.isFinite(a.epochsNeeded ?? NaN) ? a.epochsNeeded : "?"} epoch(s) · ${a.epochsRun} run · ${a.postedCount} posted`);
+            console.log(`    ${DIM}sizing${RESET}   ${a.videosPlanned} videos ÷ ${a.capacity || "?"} slots/epoch = ${Number.isFinite(a.epochsNeeded ?? NaN) ? a.epochsNeeded : "?"} epoch(s) · ${a.epochsRun} run · ${a.postedCount} posted`);
         }
         if (a.scored.length > 0) {
-            console.log(`    ${DIM}${a.metric} — median ${a.median ?? "?"}${RESET}`);
+            const perAccount = Object.entries(a.channelMedians);
+            console.log(`    ${DIM}${a.metric} — round median ${a.median ?? "?"}${perAccount.length ? ` · per-account: ${perAccount.map(([c, m]) => `${c} ${m}`).join(" · ")}` : ""}${RESET}`);
             for (const s of a.scored) {
                 const mark = a.outliers.includes(s) ? `${GREEN}★${RESET}` : s === a.weakest ? `${DIM}·${RESET}` : " ";
                 const ratio = s.ratio !== undefined ? `${s.ratio.toFixed(1)}×` : "";
                 // When a round was read at more than one age, the same video appears once
                 // per reading — label them, or the list looks like a duplicate row.
                 const age = a.readContexts.length > 1 && s.age ? ` @${s.age}` : "";
-                console.log(`    ${mark} ${s.video.padEnd(8)} ${String(s.value).padStart(7)}  ${DIM}${ratio.padStart(6)}${age}${s.variant ? `  ${s.variant}` : ""}${RESET}`);
+                // The account-normalized ratio is the trustworthy one — mark it so nobody
+                // reads a cross-account raw ranking as a result.
+                const shown = s.channelRatio !== undefined ? `${s.channelRatio.toFixed(1)}×acct` : ratio;
+                const chan = s.channel ? `  ${s.channel}` : "";
+                console.log(`    ${mark} ${s.video.padEnd(8)} ${String(s.value).padStart(7)}  ${DIM}${shown.padStart(9)}${age}${chan}${s.variant ? `  ${s.variant}` : ""}${RESET}`);
             }
         }
         if (a.unposted.length > 0)
@@ -9443,7 +9480,7 @@ async function runExperimentCommand(argv) {
     for (const w of read.manifest.warnings)
         console.log(`  ${YELLOW}warn${RESET} ${DIM}${w.message}${w.line ? ` (line ${w.line})` : ""}${RESET}`);
     console.log("");
-    console.log(`${DIM}Feedback, not a gate. Method: https://vidfarm.cc/experiment.md${RESET}`);
+    console.log(`${DIM}Feedback, not a gate. Method: https://vidfarm.cc/experiments.md${RESET}`);
 }
 // `vidfarm mode [interactive|autonomous]` — show or set whether the HUMAN is in
 // the loop. Independent of cost mode: any cost mode runs either way, and the

package/dist/src/devcli/experiments.js CHANGED Viewed

@@ -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,22 @@ 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. 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: "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: "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 +89,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 +120,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 +250,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 +291,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 +306,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 +339,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 +395,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 +406,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 +419,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 +463,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 +472,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 +487,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 +555,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 +576,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 +622,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 +665,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 +695,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 +752,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 +790,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 +821,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 +859,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/{experiment.md → experiments.md} RENAMED Viewed

@@ -1,6 +1,7 @@
-# Experiment.md
+# Experiments.md
-How to run ad experiments on vidfarm.cc.
+How to run ad experiments on vidfarm.cc. The canonical URL is
+<https://vidfarm.cc/experiments.md>; `/experiment.md` redirects here.
 **You are an AI agent, and from here on you are a viral short-form scientist and a direct-response ads practitioner.** Your job is not "make a nice video." Your job is to **find the winning ad** — the one creative that best produces the outcome your human actually wants — and then to find out *why* it won so you can build more like it.
@@ -36,28 +37,49 @@ Bookmarks, shares, watch-through, follows and profile visits are all good suppor
 **b) Which platforms and how many channels?** Ask for a list, not a yes/no. Short-form distribution today includes TikTok, YouTube Shorts, Instagram Reels, Facebook Reels, LinkedIn, X (Twitter) video, Snapchat Spotlight, Pinterest Idea Pins, and anything else they hold.
-**Channel count is the single most important number in this whole document, because it is your testing capacity.** One channel can carry about one test video per day without looking spammy. So:
+**Channel capacity is the single most important number in this whole document, because it is your testing capacity.** The starting assumption is one test video per channel per day — more than that on a young account reads as spam.
+But **channels are not equal, so ask each one's posting frequency and record it.** A warmed daily TikTok may take two a day; a company LinkedIn page may take three a week; an account may be paused entirely. Capacity is the *sum of the rates*, not the count of the accounts:
 ```
-capacity per epoch  ≈  number of channels
+capacity per epoch  =  Σ (posts per epoch, per channel)
 epochs per round    =  ceil(videos in the round / capacity per epoch)
 ```
-Example — four channels (2× TikTok, 1× YouTube Shorts, 1× Instagram):
+Write the rate next to the channel in the diary — that record is what makes the schedule reproducible:
+```
+- Channels (capacity 4.43/epoch): tiktok_a x2, tiktok_b, yt_a 1/day, li_a 3/week, fb_a paused
+```
+A bare name means once per epoch. `x2` means twice. `3/week` and `2/month` are converted for you, and a channel slower than one-per-epoch **skips epochs on a real cadence** rather than being over-posted or dropped. `paused` keeps the account listed while contributing nothing.
+**Never schedule a channel above its own frequency.** An over-posted account gets throttled, and a throttled account poisons every number measured on it for weeks — which is the account-health problem in §4 arriving by your own hand.
+Example — four channels (2× TikTok, 1× YouTube Shorts, 1× Instagram), all daily:
 - capacity = **4 videos/day**
 - a round of 8 angles = 8 / 4 = **2 epochs (2 days)**
+Same four accounts, but one TikTok is warmed enough for two a day and the Instagram only takes three a week:
+- capacity = 2 + 1 + 1 + 0.43 = **4.43 videos/day**
+- the same round of 8 still finishes in **2 epochs**, but the schedule is different: the warmed TikTok carries two slots every epoch and Instagram picks up a slot roughly every other epoch instead of one daily.
 Example — twelve channels, same round of 8 angles:
 - 8 slots go to the angle experiment
 - **4 slots are still empty**, so run a second experiment in parallel the same day
+**b-ii) How healthy is each channel, and how often can it post?** While you have them listing channels, get age, follower count, whether it posts consistently, and **how many posts a day or week each one can take** — one line each. The frequency feeds the epoch math directly (capacity is the sum of the rates), and it belongs in the diary next to the channel. **Account health moves numbers by multiples and is the biggest confounder in this method** (see §4), so you need it before you can read a single result. Flag any brand-new account: it is not yet a measuring instrument.
 **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) Who does the editing?** Their own agent (you), or a distributed task force of gigworkers. This decides the mode — see §3.
+**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.
+**e) Who does the editing?** Their own agent (you), or a distributed task force of gigworkers. This decides the mode — see §3.
-**e) How long is this campaign?** Experiments run for weeks or months, not one afternoon. Say so up front so the user expects an evolution, not a single delivery.
+**f) How long is this campaign?** Experiments run for weeks or months, not one afternoon. Say so up front so the user expects an evolution, not a single delivery.
 ---
@@ -65,7 +87,7 @@ Example — twelve channels, same round of 8 angles:
 - **epoch** — one posting cycle. **Typically a day.** For slower or higher-stakes tests it can be a week or a month. One epoch = one batch of videos going live across the available channels.
 - **round** — one experiment on one variable, start to finish. A round may span several epochs, because the round may contain more videos than you have channels.
-- **capacity** — videos you can post per epoch = your channel count. Your evolutionary speed is capacity, nothing else.
+- **capacity** — videos you can post per epoch = **the sum of every channel's posting frequency** (not simply the channel count — a 2/day account contributes 2, a 3/week account 0.43). Your evolutionary speed is capacity, nothing else.
 - **composition params** — the knobs a short-form ad is built out of (see §2). Every one of them is either a **constant** or a **variable** in a structured round.
 - **baseline checkpoint** — the current best-known configuration. Every round starts from it and, if the round wins, replaces it.
 - **outlier** — a video that beat its round's median by a wide margin on the north-star metric. Outliers are the raw material of the next structured round.
@@ -162,10 +184,37 @@ Short-form results are noisy. Guardrails:
 - **Never** promote a winner off one post. Two posts minimum per variant before you believe it, three is better.
 - Compare within the **same epoch and same platform** where you can — the algorithm's mood is not constant across days or apps.
+- **Normalize per account before you rank.** Account health can outweigh the variable you are testing — see the next section. A number is only comparable to that account's own median.
 - A variant with 3× the median on the north star is an outlier worth pursuing. A variant 20% above median is noise. Say which one you are looking at.
 - Record **losers** as carefully as winners. "Problem-unaware never worked here" is a real, reusable finding.
 - Report what you **measured** separately from what you **judge**. Never dress up a hunch as a result.
+### Account health — the confounder that can be bigger than your effect
+**Two videos on two different accounts are not a fair comparison.** An account carries its own health: age, follower count, past performance, niche coherence, posting consistency, and whatever standing the platform privately assigns it. That health moves views by **multiples**, not percentages — routinely more than the difference between two decent angles. So a variant can "win" purely because it landed on the stronger account.
+That gives you a real trade-off, and you should state which side of it you are on:
+| | Same account, sequential | Multiple accounts, parallel |
+|---|---|---|
+| **Account health** | held constant — it cancels out | varies, and can dominate the result |
+| **Speed** | slow: ~1 test/day, a round takes as many days as videos | fast: capacity = channel count |
+| **Best for** | the deciding test between 2–3 finalists | wide search, early rounds, creative mode |
+**Same account is the cleanest instrument you have.** Posting every variant to one account eliminates account health as a variable entirely — the only thing that changed is the thing you changed. The cost is pure sequencing: eight variants is eight days, and that is your whole evolution stalled on one channel.
+**Themed accounts are still worth having** — several accounts, each coherent to one niche, usually beat one account posting scattershot, because coherence is itself a health input. But the moment you have more than one, their numbers stop being directly comparable.
+**So compute the true signal like this:**
+1. **Normalize against the account, not the fleet.** Judge a video against *that account's own recent median*, not the round's raw median. "3× its own account's median" is a signal; "more views than a video on a bigger account" is not.
+2. **Never rank across accounts on raw numbers.** If the leader and the laggard sat on different accounts, you have measured the accounts at least as much as the videos.
+3. **Retest across accounts — this is what buys confidence.** Re-post the apparent winner on a *different* account (deduped), and post the apparent loser on the winner's account. If the ordering holds after the swap, the effect is real. If it flips, you measured account health. This is the single most valuable extra data point in the whole method, and it is why **two posts minimum, three better** exists as a rule.
+4. **Build per-account baselines early.** After a couple of epochs each account has its own median. Record it in the diary Setup. Everything after that is cheap to normalize.
+5. **A brand-new account is not a measuring instrument.** Fresh accounts swing wildly in both directions. Don't hand one a decisive test until it has a baseline.
+This is also the honest answer to "why retest at all?" Retesting is not bureaucracy. With account health in play, one post is barely evidence — the second and third posts are what separate a finding from a coincidence.
 ### Publishing hygiene
 Posting one render to several channels is exactly the case platform de-duplication punishes — the second copy gets suppressed and your experiment records a false loser. So for any video going to more than one channel:
@@ -178,20 +227,28 @@ One variant per channel, and never the same variant on two accounts. Ask about t
 ---
-## 5. The default video format — for speed
+## 5. Pick the video format — in the plan, not at build time
+**The format is a planning decision, and it belongs in the plan you get approved.** Do not discover it while editing, and do not leave it implicit. Every round records the format it holds constant (or, if format *is* the variable, the list it varies across). A round with no named format is a round whose "constants" were never actually constant.
-**Speed to productivity matters more than polish at the start.** If an experiment is ready but no format is chosen yet, **do not stall on the format decision.** Default to **kinetic captions over easy visuals**:
+**The default family is kinetic captions over easy visuals — the copy does the work.** These are deliberately copywriting-led: the words carry the persuasion and the footage only has to hold attention. That is what makes them fast, cheap and repeatable, and it is why a weak visual with a strong hook still wins.
-- b-roll footage
-- talking head (only if the user is willing to film themselves)
-- process footage
-- loop background footage
-- satisfying footage
-- lifestyle footage
-- POV quote aesthetic
+Pick one for the round:
+| Format | Visual | Note |
+|---|---|---|
+| **b-roll footage** | generic relevant footage under the words | the workhorse — start here |
+| **talking head** | the user on camera | only if they will film themselves; strongest trust signal |
+| **process footage** | something being made/done | high watch-through, needs no narration |
+| **loop background footage** | one seamless looping plate | cheapest of all; the copy is the entire video |
+| **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 |
 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.
+**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).
 Audio, in ascending order of quality and effort:
 1. **Pure captions, no audio** — music added at posting time inside the platform's own editor (this also gets you the platform's trending-audio boost, for free)
@@ -211,6 +268,7 @@ This is the sequence. Do not skip forward.
 - the **north-star metric**, and why (including the push-back if they said "sales")
 - the **channel inventory** and the resulting capacity per epoch
 - the **mode** (creative or structured) and why
+- the **starting video format** from the §5 menu (and the audio choice: silent captions, AI voiceover, or their own voice)
 - the **epochs and rounds**: what runs on which day, in which slots
 - per round: the **variable**, the **constants**, and the **justification for the priority** — why this variable is worth the capacity before the others
 - what a **win** looks like numerically, decided *before* posting
@@ -248,7 +306,7 @@ Because sources vary, always record **where a number came from and when it was r
 ## Setup
 - North-star metric: comments (secondary: views, clicks)
-- Channels (capacity 4/epoch): tiktok_a, tiktok_b, yt_shorts_a, ig_a
+- Channels (capacity 4.43/epoch): tiktok_a x2, tiktok_b, yt_shorts_a 1/day, ig_a 3/week
 - Mode: creative
 - Baseline checkpoint: kinetic captions over b-roll, no VO, 22s, "wrong answers only" bait
 - Analytics source: flockposter (connected 2026-08-15)
@@ -268,34 +326,43 @@ Because sources vary, always record **where a number came from and when it was r
 | 4 | v004 | most-aware: "the $0 plan does this" | ig_a | ✅ |
 ### Results — read 2026-08-18, source: flockposter, age: 48h
-| video | views | comments | clicks | buys | note |
-|---|---|---|---|---|---|
-| v001 | 14,200 | 61 | 38 | 0 | **outlier** — comments 4.1× median |
-| v002 | 3,100 | 12 | 9 | 0 | |
-| v003 | 2,800 | 9 | 14 | 1 | |
-| v004 | 1,900 | 4 | 3 | 0 | weakest |
-**Finding:** problem-unaware wins decisively on comments. Most-aware is dead — stop spending capacity on it.
-**Next:** Round 2 = structured on v001 — hold the angle, vary the written hook ×6.
+| video | channel | views | comments | clicks | buys | note |
+|---|---|---|---|---|---|---|
+| v001 | tiktok_a | 14,200 | 61 | 38 | 0 | **outlier** — 4.1× that account's median |
+| v002 | tiktok_b | 3,100 | 12 | 9 | 0 | |
+| v003 | yt_shorts_a | 2,800 | 9 | 14 | 1 | |
+| v004 | ig_a | 1,900 | 4 | 3 | 0 | weakest |
+Per-account medians (comments, 48h): tiktok_a 15 · tiktok_b 11 · yt_shorts_a 8 · ig_a 5
+**Finding:** problem-unaware wins decisively on comments — 4.1× against its OWN account, so it is not just the healthier channel. Most-aware is dead; stop spending capacity on it.
+**Next:** retest v001 on ig_a (the weakest account) to confirm the effect survives the swap, then Round 2 = structured on v001 — hold the angle, vary the written hook ×6.
 ````
-Anything is fine as long as every entry answers: what did we post, what varied, what was held constant, what came back, from where, when, and what did we decide.
+Anything is fine as long as every entry answers: what did we post, **on which account**, what varied, what was held constant, what came back, from where, when, and what did we decide. The account column is not optional bookkeeping — without it you cannot separate a good video from a good account.
 ### If the devcli is installed, do not hand-maintain this file
 `vidfarm experiment` owns the ledger, the arithmetic and the method lint — nothing else. It does **not** wrap posting, channels, briefs or constants, because those commands already exist.
 ```bash
-vidfarm experiment --init --metric comments --channels "tiktok_a,tiktok_b,yt_a,ig_a"
+vidfarm experiment --init --metric comments --format "POV quote aesthetic" \
+  --channels "tiktok_a x2, tiktok_b, yt_a 1/day, li_a 3/week, fb_a paused"
 vidfarm experiment round --videos 8 --variable angle --mode structured \
   --constants "format,hooks,loop,payoff,bait" --why "awareness is the largest unknown"
 vidfarm experiment log v001 --posted --channel tiktok_a
-vidfarm experiment log v001 --views 14200 --comments 61 --source flockposter --age 48h
+vidfarm experiment log v001 --views 14200 --comments 61 --channel tiktok_a --source flockposter --age 48h
 vidfarm experiment                      # sizing, ranking vs median, outliers, findings
 ```
 Reading is the default; there are exactly two writes, `round` and `log`. `--json` on the read gives you the parsed setup, the per-round analysis and the findings.
+Channel rates go straight into `--channels` and the CLI does the rest: capacity becomes the **sum of the rates**, `round` deals each epoch's slots out in proportion (the 2/day account gets two rows an epoch, the 3/week account picks one up every other epoch), and `channel-overposted` / `paused-channel-scheduled` fire if a plan asks an account for more than it stated.
+**Always pass `--channel` when you log a result.** It is what makes account health computable: the CLI then keeps a **per-account median** and ranks each video against *its own account* (`1.3×acct`) instead of the fleet. It also treats a video read on a second account as a **retest**, which is what clears the `account-health-confound` finding. Without `--channel` you get a raw cross-account ranking, which is the exact mistake §4 warns about.
+Omit `--format` and it prints the whole §5 menu and defaults to b-roll, so the format gets **chosen in the plan** instead of drifting per video. Both the Setup block and every round record it, and `no-format` / `round-no-format` fire when they don't.
 It sizes the round for you (`8 videos ÷ 4 channels = 2 epochs`), computes the median and marks anything at ≥3× as an outlier, and lints the method: two variables in one structured round, a winner promoted off one post, results read at mixed ages, a structured round handed to gigworkers, unspent capacity, an end-of-funnel north star with no traffic behind it. Feedback, not a gate — it exits 0, like `vidfarm qa`.
 The rest of the loop stays where it already lives: **`vidfarm channels`** (the channel list, therefore capacity) · **`vidfarm harness`** + **`vidfarm qa`** (the constants, and holding a batch to them) · **`vidfarm handoff`** (the per-video briefs) · **`vidfarm dedupe`** (one variant per channel) · **`vidfarm approve`** + **`vidfarm schedule`** (the actual posting). `experiment log --posted` only *records* that a slot went live; it does not post anything.

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@officexapp/vidfarm-devcli",
-  "version": "0.21.38",
+  "version": "0.21.39",
   "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": {
@@ -65,7 +65,7 @@
     "SKILL.director.md",
     "clipper.md",
     "crowdsourcing.md",
-    "experiment.md",
+    "experiments.md",
     "update.md",
     "!readme.secret.md",
     "!**/*.secret.*"