@officexapp/vidfarm-devcli 0.21.37 → 0.21.38

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

@@ -284,6 +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 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

@@ -103,6 +103,8 @@ 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.
+- **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`
 - **Platform architecture (how it all fits together):** `https://vidfarm.cc/skill/vidfarm-platform`
@@ -123,6 +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>.
 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/crowdsourcing.md

@@ -0,0 +1,66 @@
+# Crowdsourcing.md
+
+How to crowdsource videos from vidfarm.cc
+Please redirect user based on whether they are a client or a gigworker, instructions below.
+
+## Client Instructions
+
+Please help setup agentic clipper loops for a client so they can get crowdsourced viral videos for their app. The setup is as follows:
+
+- use dollarplatoon.com/skill.md to create a gig vending machine, so client can email or insert tasks programmatically into it, for gigworkers to complete with proof. signup is free, ideally use same email as your vidfarm.cc account. your DOLLARPLATOON_API_KEY can be found in https://dollarplatoon.com/client/settings
+
+then add a first task to create a product explainer video for the clients website, or any other video creation task the client wants. it can be arbitrary and really anything found on vidfarm.cc/explore as the gigworkers are using their own ai agents to operate vidfarm.cc/skill.md to fulfill your tasks. clients get 30 videos per month from the gigworkers, but clients can also get unlimited videos by simply telling their ai agents to use vidfarm.cc themselves.
+
+a better first batch than one arbitrary task: run a consultation on vidfarm.cc/skill.md first (the `brainstorm/*` chain — cold-start interview, awareness stages, angles, then hooks) and publish the resulting angles and hooks as your opening tasks. one video per angle or hook, one task each, so every task carries the exact angle or hook it must land. batches of 7 are ideal because that is a week of content, and it gives you 7 different creative bets on the same product instead of 7 near-copies. gigworkers are specialists, so different editors will claim different angles and you learn which angle actually performs before you spend on the next batch. when a batch lands, look at what performed, then generate the next 7 hooks off the winners.
+
+in order to get gigworkers to join your project, client must create a private groupchat and post invites these communities:
+
+- WhatsApp: https://chat.whatsapp.com/KSmoi7cdK1t9pyZzOvt6Bc
+- Telegram: https://t.me/+NWMFh4Ua5SZiOTZl
+
+for example:
+
+```
+Looking for video editors to join my project!
+
+Vending Machine:
+https://dollarplatoon.com/gig/GIG_EXAMPLE/join?invite=example
+
+Join Our Groupchat:
+https://t.me/+example
+```
+
+you can find the dollarplatoon vending machine invite link from creating a gig. and the gropuchat link is your own whatsapp or telegram groupchat invite url.
+
+the video editors will arrive in your groupchat and you can directly communicate with them. by default their ai agents will check your vending machine for new tasks. every gigworker has their own specialized ai agent running vidfarm.cc/skill.md and specializing in specific video formats. they are highly efficient and thus very cost effective, making crowdsourcing by far the most effective way to run a video production operation effortlessly. best speed, quality, cost and diversity of creative. up to 100x better than other approaches.
+
+you can look at dollarplatoon vending machine for latest videos submitted, and approve the ones you like, reject the ones you dont. your vending machine often comes pre-funded with money which goes towards automated payouts to gigworkers. if you want to add more funds you can.
+
+if you are an ai agent and you will come back to these vending machines regularly, keep a written list of them on disk instead of relying on memory or on re-reading chat history. a plain markdown file like `dollarplatoon-gigs.md` next to your work is enough. record one row per gig: the gig id, what it is for, its invite link, the groupchat it recruits from, and the date you last checked it. re-derive it from the dollarplatoon api whenever it looks stale. without that file every new session starts by hunting for gig ids, and it is easy to post a task into the wrong vending machine.
+
+overall work with your video editors and try to keep some reliable good ones. crowdsourcing means you might get a ton of submissions. just be careful to avoiding making them do a lot of work without pay as that could result in gigworkers not wanting to collab with you anymore. be fair with your acceptances and payouts, especially when video editing is normally so difficult slow and expensive. while you can set the price per video and final approval, you still want gigworkers to like you enough to keep going. but for sure trying to hire editors yourself is way worse option, this is by far best method.
+
+for additional info, look at the dollarplatoon.com/skill.md or vidfarm.cc/skill.md
+
+full tutorial for client pov agentic clipper loops can be found here:
+https://www.youtube.com/watch?v=sR0C0V-WiRc
+
+## Gigworker Instructions
+
+Please run agentic clipper loops for a gigworker using these REST APIs:
+
+- vidfarm.cc/skill.md for creating videos for clients using cost saving mode. ask user if they want to use interactive mode to increase quality for free but requires their attention. if possible use stickers to create the videos. use any style prompts or custom instructions the gigworker has, as often they will specialize in specific video types
+- dollarplatoon.com/skill.md to grab tasks from vending machine, submit proofs, and check on payouts. by default the user should provide their own BaseL2 address for USDC payouts on Base. many gigworkers are Philippines based so they will use gcash. the gcash setup tutorial can be found here: https://officex.short.gy/solana-usdc-gcash and your DOLLARPLATOON_API_KEY can be found in https://dollarplatoon.com/gigworker/settings
+
+in order to join client projects, you need to get an invite link from them. those can be found by scrolling through these communities:
+
+- WhatsApp: https://chat.whatsapp.com/KSmoi7cdK1t9pyZzOvt6Bc
+- Telegram: https://t.me/+NWMFh4Ua5SZiOTZl
+
+look for a dollarplatoon invite link that looks like this: https://dollarplatoon.com/gig/GIG_EXAMPLE/join?invite=example
+its recommended that gigworkers also join the clients private groupchat to develop their own personal relationship with client, as this can often lead to direct hiring oppourtunities. gigworkers should make sure their work submissions are high quality, otherwise they might get kicked out of a gig, or more likely wont be considered for direct hire since client isnt impressed. quality impresses a client!
+
+if you are an ai agent working several gigs, keep a written list of them on disk rather than in memory, because you will revisit these vending machines every single loop. a plain markdown file like `dollarplatoon-gigs.md` is enough. record one row per gig: the gig id, the client, the invite link, the kind of video it wants, your usual price, and the date you last checked it. read that file at the top of each loop and update it at the bottom. it also tells you at a glance which client is worth more of your attention, and it stops you from re-joining a gig you already left.
+
+be careful about runaway infinite loops. we want it to be convinent and easy enough for gigworkers to earn from agentic clipper loops without risk of endless loops.
+recommended that gigworkers watch the full tutorial here: https://www.youtube.com/watch?v=qiBUWr1a0yA

package/dist/src/cli.js

@@ -38,6 +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";
 // 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
@@ -130,6 +131,27 @@ Account (persisted login — points the CLI + \`serve\` at cloud prod):
     --frames "Title|scene,…"   Frames to scaffold · --count <n> for N blank frames
     --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
+                            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
+                            (alias: experiments)
+    --init                  Scaffold the diary (--metric/--channels/--mode/--product/
+                            --baseline/--editors · --force overwrites)
+    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 "…"]
+    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.
+    --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
+                            from "vidfarm handoff", posting from "vidfarm approve" +
+                            "vidfarm schedule", per-channel copies from "vidfarm dedupe".
 
 Local editor loop:
   serve [template_id] [opts]  Boot the editor locally. On a full source checkout the
@@ -1304,6 +1326,10 @@ async function main() {
         case "plan":
             await runStoryboardCommand(rest);
             return;
+        case "experiment":
+        case "experiments":
+            await runExperimentCommand(rest);
+            return;
         case "update-skill":
         case "skill":
             await runUpdateSkillCommand(rest);
@@ -9147,6 +9173,278 @@ async function runStoryboardCommand(argv) {
         console.log(`${YELLOW}warn:${RESET} ${DIM}${w.message}${RESET}`);
     console.log(`\n${DIM}Show it to the director in the editor's ${BOLD}Storyboard${RESET}${DIM} view (per-frame comments come back to you), then build frame by frame.${RESET}`);
 }
+// `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
+// 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
+// EXPERIMENTS_DIARY.md format, the arithmetic (capacity → epochs, median,
+// outliers), and the method lint. Everything else it points at the command that
+// already does it: `vidfarm channels` (capacity), `vidfarm harness` (constants),
+// `vidfarm handoff` (per-video briefs), `vidfarm approve` + `schedule` (posting),
+// `vidfarm dedupe` (one variant per channel), `vidfarm qa` (per-video slop).
+// Reading is the default; there are exactly two writes, `round` and `log`.
+async function runExperimentCommand(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            ...commonOptions(),
+            init: { type: "boolean", default: false },
+            force: { type: "boolean", default: false },
+            dir: { type: "string" },
+            metric: { type: "string" },
+            channels: { type: "string" },
+            mode: { type: "string" },
+            product: { type: "string" },
+            baseline: { type: "string" },
+            editors: { type: "string" },
+            // round
+            variable: { type: "string" },
+            constants: { type: "string" },
+            videos: { type: "string" },
+            slots: { type: "string" },
+            why: { type: "string" },
+            win: { type: "string" },
+            title: { type: "string" },
+            // log
+            round: { type: "string" },
+            source: { type: "string" },
+            age: { type: "string" },
+            note: { type: "string" },
+            channel: { type: "string" },
+            posted: { type: "boolean", default: false },
+            views: { type: "string" },
+            comments: { type: "string" },
+            clicks: { type: "string" },
+            buys: { type: "string" },
+            metricValue: { type: "string" },
+            outlier: { type: "string" }
+        }
+    });
+    const json = Boolean(parsed.values.json);
+    const positionals = [...parsed.positionals];
+    const VERBS = new Set(["round", "log"]);
+    const verb = positionals[0] && VERBS.has(positionals[0].toLowerCase()) ? positionals.shift().toLowerCase() : "";
+    const dir = path.resolve(process.cwd(), parsed.values.dir ?? (verb ? "." : positionals[0] ?? "."));
+    if (!existsSync(dir))
+        throw new Error(`No such directory: ${dir}`);
+    const today = new Date().toISOString().slice(0, 10);
+    const target = path.join(dir, EXPERIMENTS_FILENAME);
+    const asList = (value) => (value ? value.split(/\s*[;,]\s*/).map((s) => s.trim()).filter(Boolean) : undefined);
+    // ---- --init: scaffold the ledger ------------------------------------------
+    if (parsed.values.init) {
+        if (existsSync(target) && !parsed.values.force) {
+            throw new Error(`${target} already exists. Append to it, or pass --force to overwrite it.`);
+        }
+        const mode = parsed.values.mode?.toLowerCase();
+        if (mode && !EXPERIMENT_MODES.includes(mode)) {
+            throw new Error(`Unknown mode "${mode}". Choose one of: ${EXPERIMENT_MODES.join(", ")}.`);
+        }
+        const body = renderDiaryScaffold({
+            product: parsed.values.product,
+            metric: parsed.values.metric?.toLowerCase(),
+            channels: asList(parsed.values.channels) ?? [],
+            mode: mode,
+            baseline: parsed.values.baseline,
+            editors: parsed.values.editors,
+            date: today
+        });
+        writeDiary(target, body);
+        if (json)
+            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}`);
+        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;
+    }
+    const read = readDiary(dir);
+    if (!read.exists && verb) {
+        throw new Error(`No ${EXPERIMENTS_FILENAME} in ${dir}. Start one: vidfarm experiment --init --metric comments --channels "a,b,c"`);
+    }
+    // ---- round: append a planned round ----------------------------------------
+    if (verb === "round") {
+        const capacity = capacityOf(read.manifest.setup);
+        const mode = (parsed.values.mode ?? read.manifest.setup.mode ?? "creative").toLowerCase();
+        if (!EXPERIMENT_MODES.includes(mode)) {
+            throw new Error(`Unknown mode "${mode}". Choose one of: ${EXPERIMENT_MODES.join(", ")}.`);
+        }
+        const slots = asList(parsed.values.slots);
+        const videos = parsed.values.videos !== undefined ? Number(parsed.values.videos) : slots?.length;
+        if (!videos || !Number.isFinite(videos) || videos <= 0) {
+            throw new Error("round requires --videos <n> (or --slots \"v001|angle,v002|angle\").");
+        }
+        const number = (read.manifest.rounds[read.manifest.rounds.length - 1]?.number ?? read.manifest.rounds.length) + 1;
+        const input = {
+            number,
+            title: parsed.values.title,
+            mode: mode,
+            variable: parsed.values.variable,
+            constants: asList(parsed.values.constants),
+            justification: parsed.values.why,
+            win: parsed.values.win,
+            videos,
+            editors: parsed.values.editors ?? read.manifest.setup.editors,
+            capacity,
+            slots,
+            channels: read.manifest.setup.channels,
+            date: today
+        };
+        const next = appendRound(readFileSync(read.absPath, "utf8"), input);
+        writeDiary(read.absPath, next);
+        const epochs = epochsNeeded(videos, capacity);
+        if (json)
+            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}`);
+        if (mode === "structured") {
+            const rel = path.relative(process.cwd(), dir);
+            const shown = !rel ? "." : rel.startsWith("..") ? dir : rel;
+            console.log(`${DIM}Pin the constants so they are actually held: ${BOLD}vidfarm harness init short-form --out ${shown}/HARNESS.md${RESET}`);
+        }
+        console.log(`${DIM}Get the plan approved, then mint one standalone brief per video (${BOLD}vidfarm handoff${RESET}${DIM}) before any editing.${RESET}`);
+        return;
+    }
+    // ---- log: record what happened (results, or a slot going live) ------------
+    if (verb === "log") {
+        const video = positionals[0];
+        if (!video)
+            throw new Error("log requires a video id, e.g. `vidfarm experiment log v001 --comments 61`.");
+        const source = readFileSync(read.absPath, "utf8");
+        if (parsed.values.posted) {
+            const result = markPosted(source, read.manifest, video, { channel: parsed.values.channel, date: today });
+            writeDiary(read.absPath, result.text);
+            if (json)
+                return printJson({ ok: true, video, posted: today, channel: parsed.values.channel ?? null });
+            console.log(`${GREEN}Marked posted:${RESET} ${video}${parsed.values.channel ? ` → ${parsed.values.channel}` : ""} ${DIM}(${today})${RESET}`);
+            console.log(`${DIM}This records it. The posting itself is ${BOLD}vidfarm approve${RESET}${DIM} + ${BOLD}vidfarm schedule${RESET}${DIM} — and dedupe first if it goes to more than one channel.${RESET}`);
+            return;
+        }
+        const metrics = {};
+        for (const key of CORE_METRICS) {
+            const raw = parsed.values[key];
+            if (raw === undefined)
+                continue;
+            const value = Number(String(raw).replace(/[,_\s]/g, ""));
+            if (!Number.isFinite(value))
+                throw new Error(`--${key} must be a number, got "${raw}".`);
+            metrics[key] = value;
+        }
+        if (Object.keys(metrics).length === 0) {
+            throw new Error("log needs at least one metric (--views/--comments/--clicks/--buys), or --posted to mark a slot live.");
+        }
+        const wanted = parsed.values.round !== undefined ? Number(parsed.values.round) : undefined;
+        const roundIndex = findRoundIndex(read.manifest, wanted);
+        if (roundIndex < 0)
+            throw new Error(`No round ${wanted} in the diary.`);
+        const written = appendResult(source, read.manifest, roundIndex, {
+            video,
+            metrics,
+            note: parsed.values.note,
+            source: parsed.values.source ?? read.manifest.setup.source,
+            age: parsed.values.age,
+            date: today
+        });
+        writeDiary(read.absPath, written.text);
+        if (!parsed.values.age) {
+            console.log(`${YELLOW}No --age given.${RESET} ${DIM}A 24h number and a 7d number are different measurements — record which one this is.${RESET}`);
+        }
+        if (json)
+            return printJson({ ok: true, video, round: read.manifest.rounds[roundIndex]?.number ?? roundIndex + 1, metrics, block: written.block });
+        console.log(`${GREEN}Logged${RESET} ${video} ${DIM}${Object.entries(metrics).map(([k, v]) => `${k} ${v}`).join(" · ")}${RESET}`);
+        console.log(`${DIM}Read the round back with ${BOLD}vidfarm experiment${RESET}${DIM}.${RESET}`);
+        return;
+    }
+    // ---- default: read, analyse, lint -----------------------------------------
+    const outlierRatio = parsed.values.outlier !== undefined ? Number(parsed.values.outlier) : undefined;
+    const analyses = read.manifest.rounds.map((r) => analyzeRound(r, read.manifest.setup, { metric: parsed.values.metric?.toLowerCase(), outlierRatio }));
+    const findings = lintDiary(read.manifest, analyses);
+    if (json) {
+        return printJson({
+            ok: true,
+            exists: read.exists,
+            path: read.absPath,
+            setup: read.manifest.setup,
+            capacity: capacityOf(read.manifest.setup),
+            rounds: analyses.map((a) => ({
+                number: a.round.number ?? a.round.index,
+                title: a.round.title,
+                mode: a.round.mode ?? read.manifest.setup.mode,
+                variable: a.round.variable,
+                constants: a.round.constants,
+                metric: a.metric,
+                videosPlanned: a.videosPlanned,
+                epochsNeeded: Number.isFinite(a.epochsNeeded ?? NaN) ? a.epochsNeeded : null,
+                epochsRun: a.epochsRun,
+                posted: a.postedCount,
+                unposted: a.unposted,
+                awaiting: a.awaiting,
+                median: a.median ?? null,
+                scored: a.scored,
+                outliers: a.outliers,
+                finding: a.round.finding,
+                next: a.round.next
+            })),
+            findings,
+            warnings: read.manifest.warnings
+        });
+    }
+    if (!read.exists) {
+        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}`);
+        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}`);
+    console.log(`  ${DIM}mode${RESET}        ${setup.mode ?? "creative (assumed)"}${setup.editors ? `  ${DIM}editors${RESET} ${setup.editors}` : ""}`);
+    if (setup.baseline)
+        console.log(`  ${DIM}baseline${RESET}    ${setup.baseline}`);
+    for (const a of analyses) {
+        const n = a.round.number ?? a.round.index;
+        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`);
+        }
+        if (a.scored.length > 0) {
+            console.log(`    ${DIM}${a.metric} — median ${a.median ?? "?"}${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}`);
+            }
+        }
+        if (a.unposted.length > 0)
+            console.log(`    ${DIM}not posted yet: ${a.unposted.join(", ")}${RESET}`);
+        if (a.round.finding)
+            console.log(`    ${DIM}finding${RESET}  ${a.round.finding}`);
+        if (a.round.next)
+            console.log(`    ${DIM}next${RESET}     ${a.round.next}`);
+    }
+    if (findings.length > 0) {
+        console.log("");
+        for (const f of findings) {
+            const tag = f.level === "error" ? `${RED}error${RESET}` : f.level === "warn" ? `${YELLOW}warn${RESET} ` : `${DIM}info${RESET} `;
+            console.log(`  ${tag} ${DIM}${f.code}${RESET}  ${f.message}`);
+            if (f.fix)
+                console.log(`         ${DIM}→ ${f.fix}${RESET}`);
+        }
+    }
+    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}`);
+}
 // `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
 // pair is what determines the plan. Quality usually goes UP in interactive —