@officexapp/vidfarm-devcli 0.21.58 → 0.21.60

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: vidfarm
-skill_version: 0.21.58
+skill_version: 0.21.60
 description: Entry point for making, editing, and rendering short-form video with Vidfarm. Use when the task is to create a video, ad, explainer, or social clip; to edit or re-theme an existing composition; to source footage or audio; or to run a batch of video variants. Routes to the full director skill and the `vidfarm` CLI.
 ---
 
@@ -123,6 +123,8 @@ A capable agent can replicate a template entirely on brush 1 and 2, on the free
 
 **There is a fourth source, and for a weak model it is the FIRST one: a template somebody already decomposed.** `/discover` holds thousands of viral videos that have been taken apart into their scene-by-scene DNA — hook, retention, payoff, cut rhythm, typography, per-beat paintbrush assignments — and forking one is free. That decomposition costs $1+ in AI spend to reproduce yourself, so always check for an existing one before paying to re-run it. `vidfarm discover --query "<the client's problem, in their words>" --json`; a row carrying `summary`, `keywords` and `promotions` is decomposed. **Weak models: this is not an optimisation, it is the method** — see `vidfarm.cc/flash-harness.md`.
 
+**A fork is not a half-finished video. It is somebody else's finished one.** Every element in it was chosen for their product, their customer, their face. So the moment you fork, audit the composition element by element and give each one a verdict — KEEP, REPLACE or CUT — before you plan or source anything. See the standard in §6.
+
 ## 3. Worked example — one video, end to end
 
 ```bash
@@ -215,6 +217,7 @@ Say the phase out loud when you switch. Deciding to source mid-build is how a $0
 
 The standards themselves are not optional. `vidfarm qa <dir>` is — it is a free local checker for most of them, feedback rather than a gate. Nothing calls it, skipping it is fine, and it allows one fix round by default. **Watching the render is the review that counts.** Full reasoning: `references/hooks-and-virality.md` and `references/reviewing-renders.md`.
 
+- **Forked a decomposed template? Audit every element, and KEEP is the verdict that needs a reason.** List the layers (`vidfarm pull <forkId> --json` → `.layers[]`, plus `grep -o 'data-src="[^"]*"' composition.html | sort -u`) and write `./work/ADAPTATION.md`: one row per element, verdict KEEP / REPLACE / CUT, why, and what replaced it. **Structure is DNA and stays** — beat count and order, `start`/`duration`, cut rhythm, transitions, caption identity (font, size, placement, background). **Meaning is content and goes** — voiceover, music, caption words, on-screen titles and stats and prices, actor and talking-head clips, product shots and screenshots, stickers that name a thing, the picture behind a background, and every logo, wordmark, @handle, URL and watermark (those are never a KEEP). Generic b-roll may stay when it is still true in the client's world. Run the audit **before** sourcing — every REPLACE row is a line on the procurement list — and report the counts: kept / replaced / cut. Swapping the captions and nothing else is the most common rejected video there is. Full table: `vidfarm.cc/flash-harness.md` §3½.
 - **Write the four charges before the timeline.** Hook: first line is a complete clause naming a situation, on screen at `start:0`. Loop: one open question by 0:10, closing inside this video. Payoff: shown, not summarized. Bait: one ask, final beat. Banned openers — throat-clearing, a logo, a title card, a fade from black.
 - **No HTML slop.** Test: could you have made this element inside TikTok's own editor? If you reached past that — a padded capsule, border, gradient fill, blur panel, card, CTA "button", benefit chips, feature grid — cut it. Nothing in a video is clickable. Emphasize with size, weight, caps, an accent colour, or a drawn mark.
 - **No layout templates — judge the whole frame.** The stack is the tell, not the box: headline + subheadline + CTA centred in a well is a landing page even with every border, fill and capsule stripped off. Banned at frame level — a modal/dialog floating over a dimmed or blurred backdrop, a full-frame wash used to stage a floating block, nav/hero/feature-row sections, a blurred website screenshot as the background plate, document margins. Unstack it into time: hook at t=0, support line on the next cut, CTA spoken or a bare caption. Are you arranging words relative to each other, or relative to the picture? Two text runs at once is the ceiling.
@@ -271,6 +274,10 @@ Also served at `vidfarm.cc`: `/flash-harness.md` (**the weak-model process harne
 
 **The two marketplace harnesses never mix.** A buyer's agent must never load the clipper loop and a clipper must never load the buyer loop. If the user's side is unclear, ask: *"Do you want videos made for you, or do you want to get paid to make videos for other people?"*
 
-**But an ask about EARNING has already answered it — do not ask.** *"help me earn on vidfarm marketplace"*, *"help me make money on vidfarm"*, *"find me video gigs"*, *"any work today?"*, *"check the vending machines"*, *"run in agentic clipper mode"* all mean the **clipper** side: load `/agentic-clipper.md`, then run the four moves — read the feed's recent notifications for who is asking right now, pull the `GIG_…` id out of each notification's join link and check `available_funds` before committing, join the funded ones with a Base L2 `wallet_address` in the same call, then `GET /work/available` and poll a queue for a task. The copy-paste version is in `/marketplace.md` → *"help me earn on vidfarm" — the whole first session*.
+**But an ask about EARNING has already answered it — do not ask.** *"help me earn on vidfarm marketplace"*, *"help me make money on vidfarm"*, *"find me video gigs"*, *"any work today?"*, *"check the vending machines"*, *"run in agentic clipper mode"* all mean the **clipper** side: load `/agentic-clipper.md`, then run the four moves — read the feed's recent notifications for who is asking right now, pull the `GIG_…` id out of each notification's join link and check `available_funds` before committing, join the funded ones with a Base L2 `wallet_address` in the same call, then `GET /work/available` and poll a queue for a task. The copy-paste version is in `/marketplace.md` → *"help me earn on vidfarm" — the whole first session*. **Those four moves are the first session; a loop that runs for weeks is paced.** `GET /work/available` is the MAP (one call, every machine) and `POST /gigs/:id/queue/poll` is the CLAIM (per machine) — so walk only the machines the map lit up, one at a time, until your build slots (`max_subagents`) are full, stop there, and resume the walk from that machine when a slot opens. **Never re-poll a machine inside 12 hours** unless a new bell rang for it, the map says it holds work, a proof of yours there was approved or paid, or the gigworker asks; **sweep the notifications twice a day**, not every cycle, and join the funded machines it turns up. A task you cannot deliver is **declined** (`POST /gigs/:id/queue/:msgId/decline` — free, per-worker, and without it the same task heads your FIFO forever), never held and never substituted; a task that names no format is where the clipper's own specialty goes. Full apparatus: `/agentic-clipper.md` § 3⅞ and § 4 ①–②.
 
 **Then ask the gigworker one more question: the RUN MODE.** It decides which stages of every task stop for them — `full-interactive` (shortlist · plan · raws · cut), `quick-interactive` (shortlist · cut), `auto-batch` (cut only — build the batch unattended, review it in one sitting), `auto-submit` (nothing; opt-in, in their own words). The middle two are the common ones. `vidfarm clipper-run mode` explains all four and saves the answer, `vidfarm clipper-run next` says what to do right now, and `vidfarm clipper-run gate <task>` exits non-zero while a human gate is open — so `gate && gigs submit …` cannot send an unreviewed cut. Full section: `/marketplace.md` → *The four run modes*.
+
+**Then offer the CLIPPER DASHBOARD — `vidfarm dashboard` — and expect a yes.** Three of the four run modes stop to make a human *watch a video*, and a terminal cannot play one; without the dashboard the gigworker reads a path out of `REVIEW_QUEUE.md`, opens the file by hand, and types a verb, once per task. `vidfarm dashboard` is that queue as one localhost page over the same `CLIPPER/` folder — no key, no network, no account: the cut plays and seeks, the buyer's brief sits beside it, the checks are tickable and the unticked ones pre-fill the rejection note, the shortlist candidates play side by side (`1`/`2`/`3` to pick), and `A`/`C`/`D`/`U` answer the gate. Every button calls the same `clipper-run` transition the CLI calls, so the page and the terminal can never disagree. Ask once, record it in `MISSION.md` as `dashboard: yes | no`, and never depend on it — a gigworker who declines keeps `REVIEW_QUEUE.md`, `clipper-run review` and the `gate` rail exactly as they were. Full section: `/agentic-clipper.md` § 3⅘.
+
+**Before ANY proof is submitted, run the sanity check — every time, on every side of the loop.** `vidfarm gigs verify-proof --proof <url> --clean-master ./final-clean.mp4` needs no api key. It loads each proof url the way a stranger's browser would (no key, no cookie) and exits non-zero on a 403 bucket, a 404, an s3 AccessDenied body served as `video/mp4`, an **expiring presigned url** (read access dies before the buyer swipes), a `localhost`/Drive/Dropbox link, or a 0-byte file. It then checks the delivery is split the right way: the **watermarked** cut public in `proofs[]`, the **clean master** sealed in `private_note` (`--clean-master`) — recommended, not required, so putting the unwatermarked final in the proof itself only warns, and `--clean-in-proof` says you meant it. `vidfarm gigs submit` runs the same check and refuses a failing proof. The two gates are different questions: `clipper-run gate` = *did a human watch it*, `gigs verify-proof` = *can the buyer open it*. Full section: `/marketplace.md` → *the sanity check before you send*.

package/clipper.md

@@ -144,7 +144,9 @@ Read and report back to the user, in plain language:
 - **`available_funds` / `contract_address`** — whether the gig can pay on-chain (see Phase 5).
 - **`default_rate_limit_count` / `default_rate_limit_minutes`** — your ceiling. Never poll past it.
 - **`task_timeout`** — how long you may hold a task before it expires on you.
-- **`review_timeout`** — proofs auto-approve after this (default 48h) if the client doesn't review.
+- **`review_timeout`** — seconds until an unreviewed proof auto-approves. **`-1` means never**:
+  the client reviews every proof by hand, so nothing pays until they say so. Every vidfarm
+  vending machine is `-1`. Read this field before you count on a deadline.
 
 **Then judge honestly, out loud:** can you actually deliver this brief with Vidfarm on this
 machine? If the gig wants 4K motion-graphics work and cost mode is `minimize`, say so now. A gig
@@ -402,8 +404,10 @@ Check the response:
 - **`409`** — duplicate `task_identifier`. You already submitted this one; don't resubmit.
 - **`410`** — the task expired while you were rendering. Ask the client for an extension, or move on.
 
-Proofs auto-approve after `review_timeout` (default 48h) if the client doesn't review. Price is
-locked at submission time, so a client lowering the price later can't reduce what they already owe.
+Proofs auto-approve after `review_timeout` if the client doesn't review — unless it is `-1`,
+which is manual review and never auto-approves. Every vidfarm vending machine is `-1`, so on
+those your proof waits for a human verdict however long that takes. Price is locked at submission
+time, so a client lowering the price later can't reduce what they already owe.
 
 ---
 

package/dist/src/cli.js

@@ -26,10 +26,10 @@ import { dedupeMediaLocal, localDedupeAvailable, defaultDedupeOutPath, describeL
 import { segmentAlphaComponents, encodeTransparentGif, encodeTransparentAnimatedGif, pickPlateColor, detectPlateColor, keySafeArtInstruction, connectivitySafeArtInstruction, analyzeKeyedArt, measureOpaqueShare, HOLE_WARN_PCT } from "./devcli/sticker-pack.js";
 import { smartKeyPlate, planZonedSheet, zonedSheetInstruction } from "./devcli/plate-key.js";
 import { runDoctorCommand } from "./devcli/doctor.js";
-import { findFreePort } from "./devcli/port-utils.js";
+import { findFreePort, isPortFree } from "./devcli/port-utils.js";
 import { scanLocalServers } from "./devcli/process-scan.js";
 import { runSkillsCommand } from "./devcli/skills.js";
-import { AmbiguousDocRef, DEFAULT_PACK, bundledPackDir, listPackDocs, listPackTopics, loadAngleBank, loadAwarenessLadder, loadIdeaBank, readPackDoc, readPackTopic, resolvePackTopic, searchPackDocs } from "./devcli/skill-docs.js";
+import { AmbiguousDocRef, DEFAULT_PACK, bundledPackDir, listPackDocs, listPackTopics, loadAdFormatBank, loadAngleBank, loadAwarenessLadder, loadIdeaBank, readPackDoc, readPackTopic, resolvePackTopic, searchPackDocs } from "./devcli/skill-docs.js";
 import { initTelemetry, reportCliCrash } from "./devcli/telemetry.js";
 import { resolveLocalDataDir, localBackendAvailable, LocalModeUnavailableError, localApiRequest } from "./devcli/local-backend.js";
 import { NativeModuleUnavailableError } from "./devcli/clip-store.js";
@@ -1049,11 +1049,13 @@ Account:
                             (iconscout takes BOTH values as one secret: <client_id>:<client_secret>)
 
 Agent skill (the director knowledge — a full copy SHIPS INSIDE this CLI):
-  ideas [topic]             "What should I post?" — the THREE IDEA BANKS    (local — offline, free, no AI)
+  ideas [topic]             "What should I post?" — the FOUR IDEA BANKS     (local — offline, free, no AI)
                             50 frames (the rise of · then vs now · …), 5
                             AWARENESS STAGES (what the viewer already knows,
-                            and what the video may ask for), and 44 PROBLEM
-                            ANGLES (which side of the problem it comes from).
+                            and what the video may ask for), 44 PROBLEM
+                            ANGLES (which side of the problem it comes from),
+                            and 40 AD FORMATS (what the finished video IS —
+                            iphone notes, tier list, warning, greenscreen).
                             An idea is one point in that grid; vary TWO axes
                             and 30 videos never read as repeats. It hands over
                             the banks — you fill them with the director's
@@ -1068,7 +1070,9 @@ Agent skill (the director knowledge — a full copy SHIPS INSIDE this CLI):
     --stage <name|n>          One stage (unaware · problem-aware · … · most-aware)
     --angles                  The 44 problem angles, by family
     --angle <name>            One angle family or one named angle
-    --grid                    Stage × angle × frame — one row per video
+    --formats                 The 40 ad formats — what the video LOOKS like
+    --format <name>           One format family or one named format
+    --grid                    Stage × angle × frame × format — one row per video
     --count <n>               Sample N, spread across families (default 20 with --topic)
     --json                    Machine-readable banks (+ starter lines)
   skill topics              The craft this pack knows, by SPOKEN name —       (local — offline, no account)
@@ -1195,7 +1199,7 @@ Marketplace (paid, cloud-only — the bazaar never renders locally):
   gigs <sub>                Your vending machines, BOTH sides (client + gigworker)
     machines · tasks · add-task · proofs · approve · reject · ring-bell      (client, paid)
     earn · feed · check · join · work · claim · submit · proof · earnings    (gigworker, free — bring DOLLARPLATOON_API_KEY)
-      upload · mine · join-feed
+      upload · verify-proof · mine · join-feed
     "HELP ME EARN ON VIDFARM" IS ONE COMMAND: vidfarm gigs earn. It joins the
     feed, reads who is asking for videos right now, checks every one of those
     machines for MONEY, and ranks them best-payer-first with the join command.
@@ -1203,7 +1207,13 @@ Marketplace (paid, cloud-only — the bazaar never renders locally):
     spend an hour, because approval does not create money. 'gigs submit
     --clean-master <file>' seals the unwatermarked cut in the proof's private
     note, which the buyer cannot open until a rollup has actually paid you.
+    'gigs verify-proof --proof <url>' is the PRE-SUBMIT sanity check and needs no
+    key: it loads every url the way a stranger's browser would and refuses a dead
+    link, a 403 bucket or an expiring presigned url, then checks the watermarked
+    cut and the clean master are not the wrong way round. 'gigs submit' runs it
+    for you and will not send a broken proof.
     e.g. vidfarm gigs earn
+         vidfarm gigs verify-proof --proof https://…/final-watermarked.mp4 --clean-master ./final-clean.mp4
          vidfarm gigs add-task --task "60s explainer for acme.com" --price 0.50 --upload-link <share url>
          vidfarm gigs proofs --status pending   ·   vidfarm gigs approve PRF_01H…
     (see: vidfarm gigs help · the loop: vidfarm.cc/agentic-clipper.md)
@@ -1223,6 +1233,14 @@ Marketplace (paid, cloud-only — the bazaar never renders locally):
     e.g. vidfarm clipper-run mode quick-interactive
          vidfarm clipper-run next
     (see: vidfarm clipper-run help)
+  dashboard                 THE CLIPPER DASHBOARD for a mission folder, on localhost
+    One page: what waits on you (with the cut PLAYING, not a path to open by hand),
+    what each agent is mid-way through, what was submitted, and the money owed.
+    Every button calls the same clipper-run verb, so the page and the terminal
+    can never disagree. Loopback only, disk only — no key, no network.
+    OFFER IT to a marketplace clipper before the first task; most want it.
+    e.g. vidfarm dashboard        ·  vidfarm dashboard --dir ./CLIPPER --port 4400
+         (vidfarm panel is the same command)
   shared <sub> <link>       USE a link someone shared with you — NO account, NO API key
     info · ls --tree · search · grab · note · mkdir · put · get
     grab is the one to reach for: it finds footage by MEANING and downloads it in one step.
@@ -1700,10 +1718,24 @@ async function main() {
         case "clipper-run":
         case "clipper-mode":
         case "run-mode": {
+            // `clipper-run panel` is the same command as `vidfarm panel` — a
+            // gigworker who lives in `clipper-run` should not have to learn a
+            // second top-level verb to find the screen.
+            if ((rest[0] ?? "").toLowerCase() === "panel" || (rest[0] ?? "").toLowerCase() === "dashboard") {
+                await runClipperPanelCommand(rest.slice(1));
+                return;
+            }
             const { runClipperRunCommand } = await import("./devcli/clipper-run.js");
             await runClipperRunCommand(rest);
             return;
         }
+        // THE CLIPPER DASHBOARD — the visual half of the clipper loop: watch the
+        // cut, answer the gate, see what is owed.
+        case "dashboard":
+        case "panel":
+        case "clipper-panel":
+            await runClipperPanelCommand(rest);
+            return;
         case "get-file":
             await runGetFileCommand(rest);
             return;
@@ -2479,6 +2511,83 @@ function printServeBanner(input) {
     console.log(line);
     console.log("");
 }
+// `vidfarm dashboard` (aka `vidfarm panel`) — the CLIPPER DASHBOARD over a
+// mission folder.
+// Backend-free and disk-only: no key, no network. It exists because the CUT
+// gate means "watch this video", and a terminal cannot play one.
+async function runClipperPanelCommand(argv) {
+    const { ClipperUserError: PanelArgError } = await import("./devcli/clipper-run.js");
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: argv,
+            allowPositionals: true,
+            options: {
+                dir: { type: "string" },
+                port: { type: "string", default: "4400" },
+                open: { type: "boolean", default: true },
+                "no-open": { type: "boolean", default: false }
+            }
+        });
+    }
+    catch (error) {
+        // Node's own parser rejects things like `--port -5` ("ambiguous") before any
+        // of our validation runs, and its message names neither the flag nor the fix.
+        throw new PanelArgError(`${error instanceof Error ? error.message.replace(/^\w+ \[[^\]]+\]: /, "") : String(error)}\n` +
+            `Usage: vidfarm panel [--dir <mission folder>] [--port <1-65535>] [--no-open]`);
+    }
+    const { resolveMissionRoot, listTaskStates, readMissionMode } = await import("./devcli/clipper-run.js");
+    const { startClipperPanel, mintPanelToken } = await import("./devcli/clipper-panel.js");
+    const { ClipperUserError } = await import("./devcli/clipper-run.js");
+    const root = resolveMissionRoot(parsed.values.dir ?? parsed.positionals[0]);
+    if (!existsSync(root)) {
+        throw new ClipperUserError(`No mission folder at ${root}.\nCreate one first: vidfarm clipper-run init${parsed.values.dir ? ` --dir ${parsed.values.dir}` : ""}`);
+    }
+    // `--dir MISSION.md` used to boot a panel that looked fine and showed nothing.
+    if (!statSync(root).isDirectory()) {
+        throw new ClipperUserError(`${root} is a file, not a mission folder. Point --dir at the folder that contains it.`);
+    }
+    const rawPort = String(parsed.values.port);
+    const requestedPort = Number(rawPort);
+    if (!Number.isInteger(requestedPort) || requestedPort < 1 || requestedPort > 65535) {
+        throw new ClipperUserError(`Invalid --port "${rawPort}" — give a whole number between 1 and 65535.`);
+    }
+    // An EXPLICIT port that is busy must fail. Silently binding the next one free
+    // meant a bookmarked tab on the old port showed a DIFFERENT mission, and
+    // approvals there went to the wrong gig. With no --port given, moving on is
+    // fine: nobody has been told a number yet.
+    // `--port=4492` is the same intent as `--port 4492`; an exact-string match
+    // meant the `=` form silently fell back to auto-advancing.
+    const portWasChosen = argv.concat(process.argv)
+        .some((a) => a === "--port" || a.startsWith("--port="));
+    const port = portWasChosen ? requestedPort : await findFreePort(requestedPort);
+    if (portWasChosen && !(await isPortFree(port))) {
+        throw new ClipperUserError(`Port ${port} is already in use — another panel or local job is on it.\n` +
+            `Pass a different --port, or run \`vidfarm doctor --kill-orphans\` to reclaim it.`);
+    }
+    const token = mintPanelToken();
+    const { url } = await startClipperPanel({ root, port, token });
+    const tasks = listTaskStates(root);
+    const waiting = tasks.filter((task) => task.gate).length;
+    const open = tasks.filter((task) => !task.gate && task.stage !== "done" && task.stage !== "discarded").length;
+    const mode = readMissionMode(root);
+    const line = `${DIM}${"─".repeat(74)}${RESET}`;
+    console.log("");
+    console.log(line);
+    console.log(`${BOLD}${GREEN}  Clipper dashboard${RESET}  ${DIM}(local files only — no key, no network)${RESET}`);
+    console.log(line);
+    console.log(`  mission     ${root}`);
+    console.log(`  run mode    ${mode.mode}${mode.isSet ? "" : `${DIM} (not set — assuming this)${RESET}`}`);
+    console.log(`  tasks       ${waiting ? `${YELLOW}${waiting} waiting on you${RESET}` : `${DIM}none waiting on you${RESET}`}${DIM} · ${open} in progress · ${tasks.length} total${RESET}`);
+    console.log("");
+    console.log(`  ${BOLD}Open:${RESET} ${url}`);
+    console.log(`  ${DIM}The token in that URL is minted per run. Loopback only; do not share the link.${RESET}`);
+    console.log(line);
+    console.log("");
+    if (parsed.values.open && !parsed.values["no-open"])
+        openInBrowser(url);
+    // The HTTP server keeps the process alive.
+}
 function openInBrowser(url) {
     const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
     const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
@@ -12997,6 +13106,8 @@ async function runIdeasCommand(argv) {
             angle: { type: "string" },
             stages: { type: "boolean", default: false },
             stage: { type: "string" },
+            formats: { type: "boolean", default: false },
+            format: { type: "string" },
             grid: { type: "boolean", default: false }
         }
     });
@@ -13005,13 +13116,14 @@ async function runIdeasCommand(argv) {
     const { frames, families } = loadIdeaBank();
     if (!frames.length)
         throw new Error("No bundled content-ideas reference found next to this devcli install. Fetch it with `vidfarm skills add vidfarm`.");
-    // The three axes of an idea live in one reference, so they live behind one
+    // Every axis of an idea lives in one reference, so they live behind one
     // command. A director who only ever sees the frames posts 30 videos at one
     // awareness stage from one angle, which is the exact failure this expansion
-    // exists to prevent — so the stage and angle banks are flags here, not a
-    // separate command nobody discovers.
+    // exists to prevent — so the stage, angle and format banks are flags here,
+    // not a separate command nobody discovers.
     const ladder = loadAwarenessLadder();
     const angleBank = loadAngleBank();
+    const formatBank = loadAdFormatBank();
     if (parsed.values.stages || parsed.values.stage) {
         const wanted = String(parsed.values.stage ?? "").trim().toLowerCase();
         const picked = wanted
@@ -13070,6 +13182,51 @@ async function runIdeasCommand(argv) {
         console.log(`${DIM}Pair angles with frames and stages: vidfarm ideas --grid --topic "<offer>"${RESET}`);
         return;
     }
+    // The format is the LAST field of an idea and the cheapest one to change:
+    // the subject, the angle and the script all survive a format swap, so one
+    // idea that worked becomes four posts that do not read as reposts. Printed
+    // here rather than left in the doc because "shoot another talking head" is
+    // what a director defaults to when nobody hands them the alternatives.
+    if (parsed.values.formats || parsed.values.format) {
+        if (!formatBank.formats.length) {
+            throw new Error("The bundled content-ideas reference has no ad-format bank. Update it with `vidfarm skills add vidfarm`.");
+        }
+        const wanted = String(parsed.values.format ?? "").trim().toLowerCase();
+        const picked = wanted
+            ? formatBank.formats.filter((entry) => entry.family.toLowerCase().includes(wanted) || entry.frame.toLowerCase().includes(wanted))
+            : formatBank.formats;
+        if (wanted && !picked.length) {
+            throw new Error(`No format matches "${wanted}". Format families: ${formatBank.families.join(", ")} (see \`vidfarm ideas --formats\`).`);
+        }
+        if (json) {
+            return printJson({
+                ok: true,
+                offline: true,
+                topic: topic || null,
+                total_formats: formatBank.formats.length,
+                families: formatBank.families,
+                formats: picked,
+                method: "references/content-ideas.md"
+            });
+        }
+        console.log(`${BOLD}Ad formats${RESET} ${DIM}(${picked.length} of ${formatBank.formats.length} · what the finished video IS)${RESET}`);
+        if (topic)
+            console.log(`${DIM}Topic: ${RESET}${topic}`);
+        console.log("");
+        let formatGroup = "";
+        for (const entry of picked) {
+            if (entry.family !== formatGroup) {
+                formatGroup = entry.family;
+                console.log(`  ${BOLD}${formatGroup}${RESET}`);
+            }
+            console.log(`    ${GREEN}${entry.frame}${RESET}${entry.note ? ` ${DIM}— ${entry.note}${RESET}` : ""}`);
+        }
+        console.log("");
+        console.log(`${DIM}The format is the LAST field, not the first. "Let's do a tier list" is a shoot with no idea in it.${RESET}`);
+        console.log(`${YELLOW}Formats that imitate a record${RESET}${DIM} — reviews, an inbox, a search, a stock count — must not fabricate it.${RESET}`);
+        console.log(`${DIM}Use the real screenshot, or keep every claim inside a staged one true: vidfarm skill show ad-formats${RESET}`);
+        return;
+    }
     if (parsed.values.grid) {
         // The grid is the honest answer to "give me 30 videos": vary TWO axes.
         // Walking frames, angles and stages at different strides keeps every row a
@@ -13113,24 +13270,47 @@ async function runIdeasCommand(argv) {
                     frame = usableFrames[(i + round + bump + 1) % usableFrames.length];
             }
             gridSeen.add(`${stage.index}|${frame.frame}|${angle.frame}`);
+            // The format walks the bank on its own stride, so a balanced month is
+            // also a varied SHOOT list instead of 30 rows that all get filmed the
+            // same way. It is advisory: unlike the frame and the angle, the stage
+            // does not name its formats, so a director may swap it freely.
+            //
+            // The one pairing that is actually WRONG: a two-column format (us vs
+            // them, myth vs fact) under a frame that is not itself a contrast gives
+            // the video two comparisons, which is the reference's "do not stack two
+            // frames" defect. Walk past those rather than print a row the doc bans.
+            const twoColumn = (entry) => /two-column/i.test(entry?.family ?? "");
+            const frameIsContrast = /contrast/i.test(frame.family);
+            let format = null;
+            for (let step = 0; step < (formatBank.formats.length || 1); step += 1) {
+                const candidate = formatBank.formats[(i * 7 + round + step) % (formatBank.formats.length || 1)];
+                if (!candidate)
+                    break;
+                if (twoColumn(candidate) && !frameIsContrast)
+                    continue;
+                format = candidate;
+                break;
+            }
             return {
                 stage: `${stage.index} · ${stage.stage}`,
                 angle: angle.frame,
                 angle_family: angle.family,
                 frame: frame.frame,
                 frame_family: frame.family,
+                format: format?.frame ?? null,
+                format_family: format?.family ?? null,
                 starter: topic ? joinIdeaFrame(frame.frame, topic) : null
             };
         });
         if (json)
             return printJson({ ok: true, offline: true, topic: topic || null, rows: grid, method: "references/content-ideas.md" });
-        console.log(`${BOLD}Idea grid${RESET} ${DIM}(${total} combinations · stage × angle × frame · offline, free, no AI call)${RESET}`);
+        console.log(`${BOLD}Idea grid${RESET} ${DIM}(${total} combinations · stage × angle × frame × format · offline, free, no AI call)${RESET}`);
         if (topic)
             console.log(`${DIM}Topic: ${RESET}${topic}`);
         console.log("");
         for (const row of grid) {
             console.log(`  ${DIM}${row.stage.padEnd(18)}${RESET}${GREEN}${row.angle}${RESET}`);
-            console.log(`    ${row.starter ?? row.frame}`);
+            console.log(`    ${row.starter ?? row.frame}${row.format ? ` ${DIM}· as: ${row.format}${RESET}` : ""}`);
         }
         console.log("");
         console.log(`${DIM}Each row is a DIFFERENT video, not a rewrite — the stage and the angle both moved.${RESET}`);
@@ -13211,11 +13391,12 @@ async function runIdeasCommand(argv) {
     else {
         console.log(`${DIM}Pour ONE topic into a frame to get a video: 'the rise of' + your niche. Add --topic "<offer>" to see it.${RESET}`);
     }
-    console.log(`${DIM}A frame is only ONE axis. The other two are here too, and a set that freezes them repeats:${RESET}`);
+    console.log(`${DIM}A frame is only ONE axis. The others are here too, and a set that freezes them repeats:${RESET}`);
     console.log(`${DIM}  vidfarm ideas --stages    ${RESET}${ladder.length} awareness stages ${DIM}— what the viewer knows, and what you may ask for${RESET}`);
     console.log(`${DIM}  vidfarm ideas --angles    ${RESET}${angleBank.angles.length} problem angles ${DIM}— which side of the problem the video comes from${RESET}`);
-    console.log(`${DIM}  vidfarm ideas --grid --topic "<offer>"${RESET} ${DIM}— stage × angle × frame, one row per video${RESET}`);
-    console.log(`${DIM}Method + frame→format notes: vidfarm skill show content-ideas   ·   families: vidfarm ideas --families${RESET}`);
+    console.log(`${DIM}  vidfarm ideas --formats   ${RESET}${formatBank.formats.length} ad formats ${DIM}— what the finished video IS (iphone notes, tier list, warning)${RESET}`);
+    console.log(`${DIM}  vidfarm ideas --grid --topic "<offer>"${RESET} ${DIM}— stage × angle × frame × format, one row per video${RESET}`);
+    console.log(`${DIM}Method + build notes: vidfarm skill show content-ideas   ·   families: vidfarm ideas --families${RESET}`);
     console.log(`${DIM}Never ship a frame as a hook — the four charges still apply: vidfarm skill show hooks${RESET}`);
     console.log(`${DIM}Producing the whole set is a batch: vidfarm skill show bulk (one frame per video).${RESET}`);
     // The natural upsell, in the right order: ideas are the easy win, and the
@@ -13404,7 +13585,11 @@ void main().catch(async (error) => {
         || error instanceof NativeModuleUnavailableError
         // marketplace-gigs is imported lazily, so match its "no key yet" error by
         // name rather than pulling the module into the startup path just for this.
-        || (error instanceof Error && error.name === "GigsAuthMissingError")) {
+        || (error instanceof Error && error.name === "GigsAuthMissingError")
+        // clipper-run / panel conditions: a wrong task id, an id already taken, a
+        // gate that has to be answered first. All of these are the CLI talking to a
+        // human, and a stack trace reads as "vidfarm is broken".
+        || (error instanceof Error && error.name === "ClipperUserError")) {
         console.error(error.message);
         process.exit(1);
     }