@officexapp/vidfarm-devcli 0.21.58 → 0.21.60

package/.agents/skills/vidfarm/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: vidfarm
-skill_version: 0.21.58
+skill_version: 0.21.60
 description: Use Vidfarm as a director. Run a strategy **consultation** (the `brainstorm/*` chain — cold-start interview, awareness stages, persuasive angles, hooks, product placement). Answer "give me content ideas" / "what should I post" / "I need 30 videos this month" from the bundled idea banks (50 content frames x 5 awareness stages x 44 problem angles). Browse/add inspiration videos, browse the free public raws catalog BY CATEGORY (curated shelves like scroll-stoppers/greenscreen/reaction — the cheapest way to source footage for one video, and a ready-made clip pool for bulk scripting N variants), fork a template into a composition, edit it in the Trackpad Editor (timeline-based like Premiere/DaVinci), auto-decompose source video into scenes, render to MP4, approve into a shareable post, and schedule it. Includes login, provider keys, discovery, versioning, uploads/downloads, and billing. Every step is available as raw REST; `vidfarm-devcli` wraps those routes and composes the file-backed scripting flows.
 ---
 
@@ -488,7 +488,7 @@ You may be running as the **in-web AI chat** (the /editor copilot, the chat dock
 | `references/hooks-and-virality.md` | ~295 ln | **Before writing ANY hook, caption script, or re-theme**, and before a hook-variant batch. The four charges, three gates, banned openers, loop mechanics. This is the craft; the rest of the pack is mechanics |
 | `references/reviewing-renders.md` | ~140 ln | **Before you report a video as done**, or grade someone else's. The holistic pass, the common defects, frozen-render and audio verification |
 | `references/onboarding.md` | ~80 ln | Cold-start interviews, **consultations** (the `brainstorm/*` chain), strategy docs, durable director context |
-| `references/content-ideas.md` | ~335 ln | **"Give me content ideas" / "what should I post" / a month of posts.** The three banks — 50 content frames, the 5-stage awareness ladder (with each stage's frames, angles and permitted ask), and 44 problem angles — plus **the subject pool** (adjacent topics inside the niche, so 50 frames are not 50 versions of one sentence), the monthly stage mix, the frame × angle × stage grid, and frame → format notes |
+| `references/content-ideas.md` | ~490 ln | **"Give me content ideas" / "what should I post" / a month of posts.** The three banks — 50 content frames, the 5-stage awareness ladder (with each stage's frames, angles and permitted ask), and 44 problem angles — plus **the subject pool** (adjacent topics inside the niche, so 50 frames are not 50 versions of one sentence), the monthly stage mix, the frame × angle × stage grid, and frame → format notes |
 | `references/rest-api.md` | ~85 ln | Only when the user asks for REST, an endpoint/schema, or direct HTTP integration. It is an index — follow its domain links; do not preload it into ordinary director conversations |
 
 **Recipes — step-by-step procedures. When a recipe matches the task, prefer it over the broad reference.**
@@ -572,7 +572,7 @@ The File Index above says what each file *is*; this says which one a given ask m
 5b. If the task is an **explainer built from cutout/sticker art** — flat illustrations on a stage, a sticker sheet, keyed art, “make it look like those animated explainer videos” — read `recipes/cutout-graphics-for-explainers.md`. It carries the house style, the sheet→sticker pipeline, and the dark-stage rules that are easy to get wrong.
 5c. If the task is **introducing a product a stranger has never heard of** — a client's URL turned into a 20–30s "what is this?" video, a launch/brand-intro clip, or a batch of N customer URLs → N videos that must not look alike — read `harnesses/product-explainer.HARNESS.md`. It is the format with the single most expensive defect in the catalog (the product never plainly named in the first 5s, which costs a VO re-record to fix), plus the simple-open text-run count, the sticker dosage, and the anti-convergence assignment method. Use `product-demo` instead when you actually have the UI on screen.
 6. If the task explicitly asks for a primitive or needs specialized generation/transcription work, read `references/primitives.md`.
-7. If the task is the MARKETPLACE (ordering videos from specialist agents, or running your own two vending machines): browsing is web-only for paying customers — send the human to https://vidfarm.cc/marketplace, never render it locally. **`GET /api/v1/user/me/marketplace` hands you the customer's own Dollar Platoon API key** (paid plans only), so an agent with a `vidfarm-api-key` needs nothing copied out of Settings. Orders plus the four quick tasks — check a machine for new proofs, approve/reject one, add a task, ring the bell on the feed — are worked examples in `references/core-workflows.md` (§ Marketplace, § Your Dollar Platoon key). **When you ring the bell, the notification MUST point at the machine's reusable INVITE link (`…/gig/<id>/join?invite=<token>`)** — that is what a gigworker taps to join and pitch. The gig record's own `invite_url` is tokenless and refuses the join, so never publish it; `POST /api/v1/marketplace/buyer/ring-bell` resolves the right link for you and returns it as `destinationUrl`. Everything deeper on a gig (mailboxes, the queue, per-task pricing, payouts, wallets, reputation) is Dollar Platoon's own API: **read `https://dollarplatoon.com/skill.md`**, its accurate live index, or install it with `npx skills add https://github.com/OfficeXApp/dollarplatoon-skill` — the same way FlockPoster work beyond scheduling needs `npx skills add https://github.com/OfficeXApp/flockposter-skill`. Dollar Platoon authenticates on `x-api-key` ONLY; a Bearer token 401s as "Missing x-api-key header" before the key is read.
+7. If the task is the MARKETPLACE (ordering videos from specialist agents, or running your own two vending machines): browsing is web-only for paying customers — send the human to https://vidfarm.cc/marketplace, never render it locally. **`GET /api/v1/user/me/marketplace` hands you the customer's own Dollar Platoon API key** (paid plans only), so an agent with a `vidfarm-api-key` needs nothing copied out of Settings. Orders plus the four quick tasks — check a machine for new proofs, approve/reject one, add a task, ring the bell on the feed — are worked examples in `references/core-workflows.md` (§ Marketplace, § Your Dollar Platoon key). **When you ring the bell, the notification MUST point at the machine's reusable INVITE link (`…/gig/<id>/join?invite=<token>`)** — that is what a gigworker taps to join and pitch. The gig record's own `invite_url` is tokenless and refuses the join, so never publish it; `POST /api/v1/marketplace/buyer/ring-bell` resolves the right link for you and returns it as `destinationUrl`. Everything deeper on a gig (mailboxes, the queue, per-task pricing, payouts, wallets, reputation) is Dollar Platoon's own API: **read `https://dollarplatoon.com/skill.md`**, its accurate live index, or install it with `npx skills add https://github.com/OfficeXApp/dollarplatoon-skill` — the same way FlockPoster work beyond scheduling needs `npx skills add https://github.com/OfficeXApp/flockposter-skill`. Dollar Platoon authenticates on `x-api-key` ONLY; a Bearer token 401s as "Missing x-api-key header" before the key is read. **On the earning side, never submit a proof without the sanity check first:** `vidfarm gigs verify-proof --proof <url> --clean-master ./final-clean.mp4` needs no key, loads every proof url the way a stranger's browser would, and exits non-zero on a dead link, a 403 bucket, an error page served as `video/mp4`, or an **expiring presigned url** — then checks the watermarked cut is the public half and the clean master the sealed one. `vidfarm gigs submit` runs it too and refuses a failing proof. **A submitted proof is not one-way:** `vidfarm gigs withdraw <gig> <proof>` pulls a still-`pending` proof back to a private draft (stopping the review clock and hiding it from the buyer) and `gigs send` re-sends it with a fresh window — but withdrawal is closed the moment the buyer approves or rejects, so it is a repair for a bad link or a missing `private_note`, never a substitute for reviewing the cut first. `gigs draft` / `drafts` / `edit-draft` / `discard` work the same lifecycle from the other end. The whole earning loop is `https://vidfarm.cc/agentic-clipper.md`.
 
 ## Non-Negotiables
 

package/.agents/skills/vidfarm/recipes/retheme-template.md

@@ -5,13 +5,14 @@ Use this when the user wants to keep the format’s feel but replace the subject
 1. Read `references/editor-workflows.md`.
 2. Fetch `video-context.json` and `editor-harness.json` first.
 3. State the plan in the three axes vocabulary: scenes, audio, text; SWAP vs REPLACE for each.
-4. Preserve the hook structure, cut rhythm, emotional punch, and important scenes flagged by the harness. **Read `references/hooks-and-virality.md` before rewriting the opening line or the retention beat** — `viral_dna.hook`/`retention`/`payoff` name the source's four charges, and rebuilding each one for the new subject (rather than flattening the loop into a product statement) is the whole job.
-5. Source footage in this order:
+4. **Audit every element before you touch one.** The fork is somebody else's *finished* video, so list its layers (`vidfarm pull <forkId> --json` → `.layers[]`, plus `grep -o 'data-src="[^"]*"' composition.html | sort -u`) and write one row per element into `./work/ADAPTATION.md`: KEEP / REPLACE / CUT, why, what replaced it. **KEEP is the verdict that needs a reason.** Structure stays (beat count and order, `start`/`duration`, cut rhythm, transitions, caption identity); meaning goes (voiceover, music, caption words, on-screen titles and prices and stats, actor clips, product shots and screenshots, stickers that name a thing, the picture behind a background, and every logo, @handle, URL and watermark). See `references/editor-workflows.md` → *Before the axes: audit every element*. The REPLACE rows are your sourcing list for step 6.
+5. Preserve the hook structure, cut rhythm, emotional punch, and important scenes flagged by the harness. **Read `references/hooks-and-virality.md` before rewriting the opening line or the retention beat** — `viral_dna.hook`/`retention`/`payoff` name the source's four charges, and rebuilding each one for the new subject (rather than flattening the loop into a product statement) is the whole job.
+6. Source footage for every REPLACE row, in this order:
    - My Files or existing raws
    - a raws hunt from a long-form source
    - AI image generation
    - AI video generation only with permission
-6. Rebuild captions and narration so timing, cadence, and joke structure survive the subject change.
-7. Render, verify, then approve and schedule only after the director is happy.
+7. Rebuild captions and narration so timing, cadence, and joke structure survive the subject change.
+8. Render, verify, then approve and schedule only after the director is happy. Report the audit counts — kept / replaced / cut — with it.
 
-Failure mode to avoid: flattening the format by swapping words but losing the timing, sound, or payoff beat.
+Two failure modes to avoid: flattening the format by swapping words but losing the timing, sound, or payoff beat — and the opposite, swapping the words and leaving everything else, so the source brand's voice, screenshots, stickers or handle ship inside the director's video.

package/.agents/skills/vidfarm/references/content-ideas.md

@@ -4,7 +4,7 @@ Read this when a director says **"give me content ideas"**, "what should I post"
 
 **This also runs FIRST for a brand-new director, before the cold-start interview.** It needs one line of offer, not an interview; it is offline, free, and keyless; and it hands the director 20+ titled videos in about a minute. That is the easiest win available on turn one, and their reactions to the list ("this one, not that one") are better raw material than anything an interview gets cold. Run it, save `content-ideas.md`, then offer the interview as the way to turn ideas into a strategy — `references/onboarding.md` → *Start with content ideas*.
 
-**What this is — three banks, not one.** An idea is a point in a small grid, and this reference holds all three axes:
+**What this is — four banks, not one.** An idea is a point in a small grid, and this reference holds every axis:
 
 | Axis | Bank | Question it answers |
 |---|---|---|
@@ -12,12 +12,13 @@ Read this when a director says **"give me content ideas"**, "what should I post"
 | **Frame** | 50 content frames | *What is the video the story of?* (`the rise of`, `then vs now`, `one decision that changed everything`) |
 | **Awareness** | 5 stages | *What does the viewer already know?* (unaware → problem-aware → solution-aware → product-aware → most-aware) |
 | **Angle** | 44 problem angles | *From which side do we talk about the problem?* (the hidden cost, the myth, the confession, the honest downside) |
+| **Format** | 40 ad formats | *What does the finished video look like?* (an iPhone note, a Reddit thread, a tier list, a warning label, a claymation) |
 
 The subject axis carries a **distance**: how far from the offer the video is allowed to sit. Distance is what produces genuinely different videos rather than differently-shaped ones, and the **turn back to the offer** is what keeps distance from becoming irrelevance — see *Distance* below. Freeze the subject at distance zero and no amount of frames or angles will save the list.
 
-A **frame** is a reusable shape for a video's subject — not a hook line, not a script. You pour the director's topic into it: `the rise of` + `dropshipping supplements` → *"The rise of the supplement dropship store"*. An **angle** decides which face of the problem that video shows; the same frame at two angles is two genuinely different videos. An **awareness stage** decides who it is allowed to be for — the same idea aimed at a stranger and at a buyer needs different first ten seconds and a different ask.
+A **frame** is a reusable shape for a video's subject — not a hook line, not a script. You pour the director's topic into it: `the rise of` + `dropshipping supplements` → *"The rise of the supplement dropship store"*. An **angle** decides which face of the problem that video shows; the same frame at two angles is two genuinely different videos. An **awareness stage** decides who it is allowed to be for — the same idea aimed at a stranger and at a buyer needs different first ten seconds and a different ask. A **format** decides what the thing on screen actually is — the same idea as an iPhone note, as a tier list, and as a warning label is three shoots, three thumbnails, and three different scroll behaviours.
 
-**The grid is where the volume comes from.** 50 frames × 44 angles × 5 stages, over a pool of adjacent subjects, is not a number to take literally, but it is why "I need 30 videos this month" is an easy ask, not a hard one. Vary **two** axes across a set and it never reads as repeats. Vary only one and it does — and the axis most often left frozen is the subject, because the offer line is right there and it is easy to paste.
+**The grid is where the volume comes from.** 50 frames × 44 angles × 5 stages × 40 formats, over a pool of adjacent subjects, is not a number to take literally, but it is why "I need 30 videos this month" is an easy ask, not a hard one. Vary **two** axes across a set and it never reads as repeats. Vary only one and it does — and the axis most often left frozen is the subject, because the offer line is right there and it is easy to paste.
 
 **How to use it (the loop).**
 
@@ -26,8 +27,9 @@ A **frame** is a reusable shape for a video's subject — not a hook line, not a
 3. **Spread across awareness stages, not just frames.** Most directors post everything at one stage — usually product-aware, because that is the stage they live in — and then wonder why the account does not grow. Cover the ladder deliberately; the default monthly mix is in *Spreading a month across the ladder* below. Say the stage next to each idea.
 4. **Pick frames and angles, don't dump the lists.** Choose 10–20 combinations that actually fit the topic. Label each idea `frame · angle · stage` so the director can say "more like that one" and you know exactly which axis they mean.
 5. **Write each idea as a title, not a frame.** Output `"The one pricing mistake that killed our first 400 orders"`, not `"one mistake that changed everything — about pricing"`. A frame that stays abstract is not an idea yet.
-6. **Then run it through the hook harness.** A content idea is the *subject*; it is not the four charges. Every idea a director picks still needs hook / loop / payoff / bait written before the timeline — `references/hooks-and-virality.md`. The frames on this list are deliberately curiosity-shaped, which makes the loop easy to name, but never skip that pass.
-7. **Batch it properly.** If the director wants the whole set produced, that is scripting mode with a `HARNESS.md` — `recipes/bulk-scripting-with-a-harness.md`. One idea per video, one line in the plan file, with its stage and angle recorded so the set stays balanced.
+6. **Give each idea a format.** The title says what the video is about; the format says what it *looks like* — see *The ad formats* below. Name it on the line (`iphone notes`, `tier list`, `warning`) so the shoot is decided before production, and rotate it so a month does not arrive as thirty talking heads.
+7. **Then run it through the hook harness.** A content idea is the *subject*; it is not the four charges. Every idea a director picks still needs hook / loop / payoff / bait written before the timeline — `references/hooks-and-virality.md`. The frames on this list are deliberately curiosity-shaped, which makes the loop easy to name, but never skip that pass.
+8. **Batch it properly.** If the director wants the whole set produced, that is scripting mode with a `HARNESS.md` — `recipes/bulk-scripting-with-a-harness.md`. One idea per video, one line in the plan file, with its stage and angle recorded so the set stays balanced.
 
 **Give lots when asked.** "Give me content ideas" means volume. Return **20+ titled ideas** by default, grouped by frame family or by awareness stage, not three polite suggestions. The director prunes; you supply.
 
@@ -355,6 +357,83 @@ An angle is **which side of the problem the video approaches from**. It is not a
 - the cost of waiting — the same decision made now vs in six months, priced
 - the first-mover gap — what the early ones get that the late ones cannot
 
+### The ad formats — 40 executions
+
+A format is **what the finished video is, as an object**. Not what it is about (frame), not which side of the problem it comes from (angle), not who it is for (stage), and not the first line (hook). `the hidden cost` `of the van receipts` `for a problem-aware viewer` is an idea; whether it arrives as an iPhone note, a Trustpilot screenshot or a claymation is the format, and the director still has to choose one before anybody films.
+
+**Why it is a bank and not a taste decision.** Left to taste, a director shoots the same talking head forty times and blames the ideas. The format is also the axis that costs the least to vary — the research, the title and the script survive a format swap intact — so it is the cheapest way to turn one idea that worked into four posts that do not read as reposts.
+
+`vidfarm ideas --formats` prints the bank; `--format <family or name>` filters it.
+
+**Fake-artifact formats — the video pretends to be something that is not an ad**
+
+- iphone notes — the pitch typed into the notes app, screen-recorded, no production at all
+- text message — the conversation that sells it, two people, read at the speed of reading
+- email screenshot — a real inbox: a complaint, a supplier reply, a refund thread
+- google search — the query they actually type, and what the results fail to answer
+- reddit style — the thread, the top comment, the reply that names the product
+- ig story — the casual story frame, sticker and all, reposted as the ad
+- trustpilot reviews — the review wall, scrolled, with the one-star ones left in
+- breaking news — the news lower-third and the anchor voice, applied to a small thing
+- native — no ad markers at all: it looks like the platform's ordinary content
+
+**List & ranking formats — the count is the promise**
+
+- x reasons why — the numbered case, one reason per beat, the count in the first frame
+- x signs — a checklist the viewer scores themselves against
+- tier list — S to F on screen, the product placed last and defended
+- hack 101 — one trick, taught properly, in under a minute
+- stat headline — one number, held on screen, everything else in service of it
+
+**Two-column formats — the comparison is the argument**
+
+- us vs them — the direct competitive split, named or unnamed
+- us vs us — the old version against the new one; no competitor is needed
+- new vs old — the category's past against its present
+- problem vs solution — left frame breaks, right frame works, same input
+- myth vs fact — the repeated sentence, then the correction, side by side
+- venn diagram — two circles, and the product sits in the overlap
+
+*These six overlap with the contrast frames above, and that is not a duplicate — `problem vs solution` as a **frame** is what the video is the story of, and as a **format** it is the split on screen. Use one as the format only when the frame is a contrast too. A video cannot carry two comparisons; that is the "do not stack two frames" rule wearing a new hat.*
+
+**Pattern-interrupt formats — it opens by refusing to sell**
+
+- don't buy this — the disqualification opener, then who it *is* for
+- don't be an idiot — the blunt correction; earns attention, spends goodwill
+- we're sorry — the apology format: an owned mistake, then the fix
+- side effect — the benefit stated as a warning label
+- zero stars — the worst review, read out, and answered
+- you can avoid — the outcome named first, the escape route second
+
+**Alert & urgency formats — the shape of an announcement, not an ad**
+
+- warning — the hazard sign, the deadline, the consequence of waiting
+- low stock alert — the shelf, the count, the date it runs out
+- case of emergency — break-glass framing: the thing to do when it goes wrong
+- bundle offer — what is in the box, itemised, priced against the parts
+
+**Proof formats — something visibly changes on camera**
+
+- customer testimonial — their words, their room, their number
+- transformation — before and after in one cut, same frame, same light
+- crossed out problems — the list of pains, struck through one at a time
+
+**Made-look formats — the production style carries it**
+
+- whiteboard — drawn while spoken; the hand is the retention device
+- doodle — rough marker illustration over the footage
+- meme — the format the niche already shares, recaptioned at a real pain
+- claymation — stop-motion or clay-look; the craft is the scroll-stopper
+- greenscreen — the presenter keyed over the artifact they are reacting to
+- text on skin — the words written on a hand, an arm, a face
+- ai podcast — two synthetic hosts discussing it, clipped like a podcast
+
+**Choosing one.** Match the format to the stage, not to the mood. Fake-artifact and made-look formats carry stage 1 and 2, because they read as content rather than as an ad. Two-column and list formats carry stage 3, because they explain. Proof and pattern-interrupt formats carry stage 4, because they answer an objection. Alert formats carry stage 5, and only stage 5 — a warning label shown to a stranger is a scroll.
+
+**The honesty rule, and it is the important one.** Several of these formats work by imitating a *record*: a review wall, an inbox, a search result, a news bulletin, a stock count. An imitation of a record that states something untrue is a fabricated record, and it is the client's problem the moment it posts. So: use a real screenshot where a real one exists; where the artifact is staged, keep every claim inside it true and checkable; never stage a third party's review, message or verdict; and never invent a deadline or a stock number that is not real. The same flag-it-for-checking rule from *Distance* applies to every number the artifact shows.
+
+**Do not let the format become the idea.** "Let's do a tier list" is not a content idea — it is a shoot with nothing in it. Pick the subject, the angle and the stage first; the format is the last field, and it is the one you change when an idea that worked deserves a second post.
+
 ### Frame × angle × stage — the grid
 
 The grid is the answer to "give me 30 different videos" and to "I already made a video about that."
@@ -364,25 +443,26 @@ The grid is the answer to "give me 30 different videos" and to "I already made a
 3. Pick an **angle** that fits that stage (each stage above lists its five).
 4. Pick a **frame** that carries the angle (each stage above lists its six).
 5. Write the title. If the title does not say the angle out loud, the pairing was wrong — go back to step 3, not step 4.
+6. Pick a **format** the stage can carry, and write it on the row. It is the last field, and the only one you may change on its own.
 
 Worked example, one topic (`bookkeeping for solo trades`), one frame family, four angles, four different videos:
 
-| Stage | Angle | Frame | Title |
-|---|---|---|---|
-| 1 | the daily friction | the psychology of | *"Why every tradie has a glovebox full of receipts"* |
-| 2 | the hidden cost | why it failed | *"The £3,400 a year that disappears in your van"* |
-| 3 | the false solution | myth vs reality | *"A shoebox is not a filing system, and HMRC agrees"* |
-| 4 | the price objection | cheap vs expensive | *"£49 a month vs the accountant's £900 catch-up bill"* |
+| Stage | Angle | Frame | Format | Title |
+|---|---|---|---|---|
+| 1 | the daily friction | the psychology of | native | *"Why every tradie has a glovebox full of receipts"* |
+| 2 | the hidden cost | why it failed | stat headline | *"The £3,400 a year that disappears in your van"* |
+| 3 | the false solution | myth vs reality | myth vs fact | *"A shoebox is not a filing system, and HMRC agrees"* |
+| 4 | the price objection | cheap vs expensive | us vs them | *"£49 a month vs the accountant's £900 catch-up bill"* |
 
 **When a director says "I already covered that."** Hold the frame, change the angle. Same subject, new video, and it is the cheapest idea in the bank to produce because the research is already done.
 
 **When a set feels repetitive.** Check which axis you froze — and check the **subject** first, because it is the one that hides. Thirty ideas that vary only the frame, on one pasted offer sentence, at one stage and one angle, are thirty versions of one video. Vary two axes minimum, and never let the subject be the constant.
 
-### Frame → format notes
+### Frame → build notes
 
-The frame also suggests how to build it, which saves a planning round:
+The frame also suggests how to build it, which saves a planning round. This is the *default* build; a format from the bank above overrides it:
 
-| Frame family | Natural format | Build notes |
+| Frame family | Natural build | Build notes |
 |---|---|---|
 | Contrast (`then vs now`, `cheap vs expensive`) | Split screen or A/B beat pairs | Cheapest to produce — two stills or two clips per beat. Great for the cutout/sticker explainer style. |
 | Hidden-knowledge (`what nobody noticed`, `the untold story`) | Talking head, or footage + kinetic captions | The loop writes itself; state the timestamp it closes at anyway. |
@@ -404,3 +484,6 @@ The frame also suggests how to build it, which saves a planning round:
 - **Do not hand over a distant idea with no turn written.** A video about Napoleon's field library, for a book app, is a great video and a dead one until somebody writes the line that reaches the offer. Write the turn with the idea, in the same breath, or drop the idea.
 - **Do not let the whole list become dated trivia.** "Be concrete" pushes a model straight into "in 1978, a man…". Fifty history videos is one idea fifty times, exactly like the frozen subject. Spread the proof types.
 - **Do not state a date, a number or a record without flagging it for checking.** The editor films what the brief says. A wrong figure is the director's problem the moment it posts, not the writer's.
+- **Do not pick the format first.** "Let's do a tier list" is a shoot with no idea in it. The format is the last field on the row, after the subject, the angle and the stage.
+- **Do not run one format for a month.** Thirty talking heads and thirty tier lists fail the same way, and the format is the cheapest axis to rotate — the script survives the swap.
+- **Do not fabricate the artifact a format imitates.** A staged review wall, a staged inbox, an invented stock count or an invented deadline is a fabricated record with the client's name on it. Use the real screenshot, or keep every claim inside the staged one true.

package/.agents/skills/vidfarm/references/core-workflows.md

@@ -369,6 +369,10 @@ curl -s -X PATCH -H "x-api-key: $DP" -H "content-type: application/json" \
 
 Rejection tags and what each costs a worker's reputation: `dollarplatoon.com/skill/proofs.md`.
 
+**A pending proof can vanish from the list — that is a withdrawal, not a bug.** A worker may pull their own `pending` submission back to a private draft (`POST .../proofs/:proof_id/withdraw`), usually to fix a bad link or a missing master, and re-send it later with a fresh review window and `"resubmitted": true` on the webhook. Key your automation off the proof id so a re-send is not reviewed twice. Drafts are filtered out of your list entirely, and the moment you approve or reject, withdrawal is closed to them — your verdict is final from their side.
+
+**The card will not play? Check the link before you judge the work.** `vidfarm gigs verify-proof --proof "<the url on the proof>"` fetches it with no key and no cookie — the way the deck does — and names the reason: a 403 bucket, a 404, an error page served as `video/mp4`, an expiring presigned url, or a link behind a login. Reject that `incomplete` with the reason, not `low_quality`: the video is often fine and only the upload is broken, and the worker fixes it in a minute. Do not just leave it — silence is approval, so an unplayable proof you ignore is one you pay for. A **watermark** on a proof is not a defect: the clipper is told to publish the watermarked cut and seal the clean master in `private_note`, which unseals on `paid_out_at`.
+
 **3 — Release the payouts.** **Approved is not paid.** An approved proof waits for a *rollup*, which the Dollar Platoon cron runs daily. Run it now with `POST .../payouts`, or read what it would cost first with `GET .../payouts`. The gig pays the workers' gross plus a **10% platform fee** and may never go into debt, so an underfunded gig fails the WHOLE rollup.
 
 ```bash

package/.agents/skills/vidfarm/references/editor-workflows.md

@@ -7,6 +7,31 @@ Almost every editor session is a director taking a template / fork / project and
 
 Name the plan back in these terms ("I'll SWAP the captions and REPLACE the scenes"), then execute axis by axis. Be **proactive at the heavy end** — carry the whole transformation, don't wait to be micro-managed one layer at a time.
 
+### Before the axes: audit every element, one at a time
+
+**A fork of a decomposed template 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, their joke. An element nobody re-decides stays theirs, and the director's audience watches it. The axes above tell you what *kind* of re-work this is; the audit tells you *which specific elements* it touches, and it is what turns "re-theme" into relevant customization instead of a caption swap.
+
+So the moment you pull a fork, list its elements and give each one a verdict — **KEEP**, **REPLACE** or **CUT** — into `./work/ADAPTATION.md` (one row per element: key, what it is, verdict, why, what replaced it).
+
+```bash
+vidfarm pull <forkId> --dir ./work --json | jq -r '.layers[] | [.key,(.kind//"?"),(.start|tostring),(.src//"—")] | @tsv'
+grep -o 'data-src="[^"]*"' ./work/composition.html | sort -u    # every asset the video still loads
+```
+
+**KEEP is the verdict that needs a reason; REPLACE is the default.** An element you overlooked and an element you deliberately kept produce byte-identical HTML, so the written ledger is the only thing that separates them, and no automated check will ever flag the first one.
+
+| Stays — this is DNA | Goes — this is content |
+|---|---|
+| beat count and beat order; any beat the harness marks critical / `must_keep` | voiceover, every line — a fork ships the source brand's narration, and it passes every automated check |
+| each layer's `start`, `duration`, track and transitions — the rhythm | the music bed and the SFX |
+| the caption identity: font, size, placement, background style | every caption word |
+| the hook's *shape* and the payoff's *position* | on-screen text that is not a caption — titles, kickers, labels, prices, stat callouts, end cards |
+| the grade, the vignette, the stage treatment behind a background | the picture inside that background |
+| the palette and type tokens, unless the director has a brand | actor / talking-head clips (a face is a brand), product shots, screenshots, UI frames, mockups |
+| generic b-roll that is still true in the new subject's world — "a keyboard" survives a subject change, "a barista" does not survive a move to fintech | stickers and icons that name a thing; every logo, wordmark, @handle, URL and watermark — **those are never a KEEP** |
+
+Three tie-breaks when a row is not obvious: **provenance** (did I put this file here, or did I inherit it?), **relevance** (does it show the DIRECTOR's world?), **load-bearing** (cut it — does the beat still work? then CUT wins). Run the audit **before** sourcing: every REPLACE row is a line on the procurement list, which is what stops a beat being built twice. Report the counts — kept / replaced / cut — with the render. The full version is §3½ of `https://vidfarm.cc/flash-harness.md`.
+
 **Fuel a scene REPLACE with raw clips, not expensive AI video.** A heavy scenes-axis replace needs footage; sources in cost order: (1) the director's own library — search `/raws` and `/files` (`vidfarm raws search …`, `vidfarm files --search …` / `browse_files`); (1b) the **PUBLIC RAWS catalog, browsed by category** — free, pre-tagged, already on the platform, and no download or hunt required (`vidfarm public-raws --categories` to see the shelves, then `--category <shelf>`); (2) **HUNT new raws** out of a long-form source (podcast/VOD/webinar or any YouTube/TikTok/IG/X URL) — `vidfarm raws scan <src> --prompt "<what the new scenes need>" --aspect <canvas> [--duration N --no-text --range …]` (local-first, free compute) or the async `POST /clips/scan` / `/raws/scan`; then reuse the picks (`set_layer_media` / `vidfarm set-media` to swap in place, `add_layer`/`vidfarm place` for net-new scenes); (3) `generate_layer` / `vidfarm generate` AI generation — the **expensive last resort**, only for scenes no real clip can cover. When a big scene re-work is asked for but no footage is given, **ask for a source to hunt (or point at the raws library) before AI-generating** — see [Raws](#raws-long-form--short-form-raws) and [Generate AI media …](#generate-ai-media-and-drop-it-on-the-timeline).
 
 **Audio is natively multi-track — overlay narration + music + SFX, each at its own volume.** A composition mixes UNLIMITED simultaneous `<audio>` layers; each sits on its own `data-track-index` and carries its own `data-volume` (0–2, default 1), and the runtime mixes them with per-track volume honored identically in the preview and the exported MP4 (a real ffmpeg `amix` of every audio layer at render). So you never need a pre-mixed file — lay **narration/voiceover at ~1.0 on one track, a music bed at ~0.1–0.2 on a separate track, and SFX on their own tracks**, each via `add_layer kind=audio` (web) / `vidfarm place --kind audio --volume …` (devcli), tuning levels later with the Inspector's Volume slider or `set_layer_media` (`volume`, `muted`). **The key move when recreating a template whose original baked music + narration into ONE audio track: rebuild it as TWO independent tracks** — a fresh narration track (`/audio/speech`, or same-voice reword via `/audio/regenerate-speech` / `vidfarm speech regenerate`) at ~1.0 and a separate real music track at ~0.1–0.2 — then mute/remove the original combined source-audio layer. This gives the director independent voice and music volume, and works around AI TTS being unable to emit narration+music in one file: you compose the mix on the timeline. Honesty: you can't un-mix / stem-separate the original's baked audio — the two tracks are a fresh narration track **plus** a real music file (owned / user-provided / `browse_files` / generated with `/api/v1/primitives/music/generate` (`vidfarm music`)), never a faked or duplicated voice layer.

package/SKILL.director.md

@@ -1,6 +1,6 @@
 ---
 name: vidfarm
-skill_version: 0.21.58
+skill_version: 0.21.60
 description: Use Vidfarm as a director. Run a strategy **consultation** (the `brainstorm/*` chain — cold-start interview, awareness stages, persuasive angles, hooks, product placement). Answer "give me content ideas" / "what should I post" / "I need 30 videos this month" from the bundled idea banks (50 content frames x 5 awareness stages x 44 problem angles). Browse/add inspiration videos, browse the free public raws catalog BY CATEGORY (curated shelves like scroll-stoppers/greenscreen/reaction — the cheapest way to source footage for one video, and a ready-made clip pool for bulk scripting N variants), fork a template into a composition, edit it in the Trackpad Editor (timeline-based like Premiere/DaVinci), auto-decompose source video into scenes, render to MP4, approve into a shareable post, and schedule it. Includes login, provider keys, discovery, versioning, uploads/downloads, and billing. Every step is available as raw REST; `vidfarm-devcli` wraps those routes and composes the file-backed scripting flows.
 ---
 
@@ -488,7 +488,7 @@ You may be running as the **in-web AI chat** (the /editor copilot, the chat dock
 | `references/hooks-and-virality.md` | ~295 ln | **Before writing ANY hook, caption script, or re-theme**, and before a hook-variant batch. The four charges, three gates, banned openers, loop mechanics. This is the craft; the rest of the pack is mechanics |
 | `references/reviewing-renders.md` | ~140 ln | **Before you report a video as done**, or grade someone else's. The holistic pass, the common defects, frozen-render and audio verification |
 | `references/onboarding.md` | ~80 ln | Cold-start interviews, **consultations** (the `brainstorm/*` chain), strategy docs, durable director context |
-| `references/content-ideas.md` | ~335 ln | **"Give me content ideas" / "what should I post" / a month of posts.** The three banks — 50 content frames, the 5-stage awareness ladder (with each stage's frames, angles and permitted ask), and 44 problem angles — plus **the subject pool** (adjacent topics inside the niche, so 50 frames are not 50 versions of one sentence), the monthly stage mix, the frame × angle × stage grid, and frame → format notes |
+| `references/content-ideas.md` | ~490 ln | **"Give me content ideas" / "what should I post" / a month of posts.** The three banks — 50 content frames, the 5-stage awareness ladder (with each stage's frames, angles and permitted ask), and 44 problem angles — plus **the subject pool** (adjacent topics inside the niche, so 50 frames are not 50 versions of one sentence), the monthly stage mix, the frame × angle × stage grid, and frame → format notes |
 | `references/rest-api.md` | ~85 ln | Only when the user asks for REST, an endpoint/schema, or direct HTTP integration. It is an index — follow its domain links; do not preload it into ordinary director conversations |
 
 **Recipes — step-by-step procedures. When a recipe matches the task, prefer it over the broad reference.**
@@ -572,7 +572,7 @@ The File Index above says what each file *is*; this says which one a given ask m
 5b. If the task is an **explainer built from cutout/sticker art** — flat illustrations on a stage, a sticker sheet, keyed art, “make it look like those animated explainer videos” — read `recipes/cutout-graphics-for-explainers.md`. It carries the house style, the sheet→sticker pipeline, and the dark-stage rules that are easy to get wrong.
 5c. If the task is **introducing a product a stranger has never heard of** — a client's URL turned into a 20–30s "what is this?" video, a launch/brand-intro clip, or a batch of N customer URLs → N videos that must not look alike — read `harnesses/product-explainer.HARNESS.md`. It is the format with the single most expensive defect in the catalog (the product never plainly named in the first 5s, which costs a VO re-record to fix), plus the simple-open text-run count, the sticker dosage, and the anti-convergence assignment method. Use `product-demo` instead when you actually have the UI on screen.
 6. If the task explicitly asks for a primitive or needs specialized generation/transcription work, read `references/primitives.md`.
-7. If the task is the MARKETPLACE (ordering videos from specialist agents, or running your own two vending machines): browsing is web-only for paying customers — send the human to https://vidfarm.cc/marketplace, never render it locally. **`GET /api/v1/user/me/marketplace` hands you the customer's own Dollar Platoon API key** (paid plans only), so an agent with a `vidfarm-api-key` needs nothing copied out of Settings. Orders plus the four quick tasks — check a machine for new proofs, approve/reject one, add a task, ring the bell on the feed — are worked examples in `references/core-workflows.md` (§ Marketplace, § Your Dollar Platoon key). **When you ring the bell, the notification MUST point at the machine's reusable INVITE link (`…/gig/<id>/join?invite=<token>`)** — that is what a gigworker taps to join and pitch. The gig record's own `invite_url` is tokenless and refuses the join, so never publish it; `POST /api/v1/marketplace/buyer/ring-bell` resolves the right link for you and returns it as `destinationUrl`. Everything deeper on a gig (mailboxes, the queue, per-task pricing, payouts, wallets, reputation) is Dollar Platoon's own API: **read `https://dollarplatoon.com/skill.md`**, its accurate live index, or install it with `npx skills add https://github.com/OfficeXApp/dollarplatoon-skill` — the same way FlockPoster work beyond scheduling needs `npx skills add https://github.com/OfficeXApp/flockposter-skill`. Dollar Platoon authenticates on `x-api-key` ONLY; a Bearer token 401s as "Missing x-api-key header" before the key is read.
+7. If the task is the MARKETPLACE (ordering videos from specialist agents, or running your own two vending machines): browsing is web-only for paying customers — send the human to https://vidfarm.cc/marketplace, never render it locally. **`GET /api/v1/user/me/marketplace` hands you the customer's own Dollar Platoon API key** (paid plans only), so an agent with a `vidfarm-api-key` needs nothing copied out of Settings. Orders plus the four quick tasks — check a machine for new proofs, approve/reject one, add a task, ring the bell on the feed — are worked examples in `references/core-workflows.md` (§ Marketplace, § Your Dollar Platoon key). **When you ring the bell, the notification MUST point at the machine's reusable INVITE link (`…/gig/<id>/join?invite=<token>`)** — that is what a gigworker taps to join and pitch. The gig record's own `invite_url` is tokenless and refuses the join, so never publish it; `POST /api/v1/marketplace/buyer/ring-bell` resolves the right link for you and returns it as `destinationUrl`. Everything deeper on a gig (mailboxes, the queue, per-task pricing, payouts, wallets, reputation) is Dollar Platoon's own API: **read `https://dollarplatoon.com/skill.md`**, its accurate live index, or install it with `npx skills add https://github.com/OfficeXApp/dollarplatoon-skill` — the same way FlockPoster work beyond scheduling needs `npx skills add https://github.com/OfficeXApp/flockposter-skill`. Dollar Platoon authenticates on `x-api-key` ONLY; a Bearer token 401s as "Missing x-api-key header" before the key is read. **On the earning side, never submit a proof without the sanity check first:** `vidfarm gigs verify-proof --proof <url> --clean-master ./final-clean.mp4` needs no key, loads every proof url the way a stranger's browser would, and exits non-zero on a dead link, a 403 bucket, an error page served as `video/mp4`, or an **expiring presigned url** — then checks the watermarked cut is the public half and the clean master the sealed one. `vidfarm gigs submit` runs it too and refuses a failing proof. **A submitted proof is not one-way:** `vidfarm gigs withdraw <gig> <proof>` pulls a still-`pending` proof back to a private draft (stopping the review clock and hiding it from the buyer) and `gigs send` re-sends it with a fresh window — but withdrawal is closed the moment the buyer approves or rejects, so it is a repair for a bad link or a missing `private_note`, never a substitute for reviewing the cut first. `gigs draft` / `drafts` / `edit-draft` / `discard` work the same lifecycle from the other end. The whole earning loop is `https://vidfarm.cc/agentic-clipper.md`.
 
 ## Non-Negotiables
 
@@ -967,6 +967,10 @@ curl -s -X PATCH -H "x-api-key: $DP" -H "content-type: application/json" \
 
 Rejection tags and what each costs a worker's reputation: `dollarplatoon.com/skill/proofs.md`.
 
+**A pending proof can vanish from the list — that is a withdrawal, not a bug.** A worker may pull their own `pending` submission back to a private draft (`POST .../proofs/:proof_id/withdraw`), usually to fix a bad link or a missing master, and re-send it later with a fresh review window and `"resubmitted": true` on the webhook. Key your automation off the proof id so a re-send is not reviewed twice. Drafts are filtered out of your list entirely, and the moment you approve or reject, withdrawal is closed to them — your verdict is final from their side.
+
+**The card will not play? Check the link before you judge the work.** `vidfarm gigs verify-proof --proof "<the url on the proof>"` fetches it with no key and no cookie — the way the deck does — and names the reason: a 403 bucket, a 404, an error page served as `video/mp4`, an expiring presigned url, or a link behind a login. Reject that `incomplete` with the reason, not `low_quality`: the video is often fine and only the upload is broken, and the worker fixes it in a minute. Do not just leave it — silence is approval, so an unplayable proof you ignore is one you pay for. A **watermark** on a proof is not a defect: the clipper is told to publish the watermarked cut and seal the clean master in `private_note`, which unseals on `paid_out_at`.
+
 **3 — Release the payouts.** **Approved is not paid.** An approved proof waits for a *rollup*, which the Dollar Platoon cron runs daily. Run it now with `POST .../payouts`, or read what it would cost first with `GET .../payouts`. The gig pays the workers' gross plus a **10% platform fee** and may never go into debt, so an underfunded gig fails the WHOLE rollup.
 
 ```bash
@@ -1144,6 +1148,31 @@ Almost every editor session is a director taking a template / fork / project and
 
 Name the plan back in these terms ("I'll SWAP the captions and REPLACE the scenes"), then execute axis by axis. Be **proactive at the heavy end** — carry the whole transformation, don't wait to be micro-managed one layer at a time.
 
+### Before the axes: audit every element, one at a time
+
+**A fork of a decomposed template 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, their joke. An element nobody re-decides stays theirs, and the director's audience watches it. The axes above tell you what *kind* of re-work this is; the audit tells you *which specific elements* it touches, and it is what turns "re-theme" into relevant customization instead of a caption swap.
+
+So the moment you pull a fork, list its elements and give each one a verdict — **KEEP**, **REPLACE** or **CUT** — into `./work/ADAPTATION.md` (one row per element: key, what it is, verdict, why, what replaced it).
+
+```bash
+vidfarm pull <forkId> --dir ./work --json | jq -r '.layers[] | [.key,(.kind//"?"),(.start|tostring),(.src//"—")] | @tsv'
+grep -o 'data-src="[^"]*"' ./work/composition.html | sort -u    # every asset the video still loads
+```
+
+**KEEP is the verdict that needs a reason; REPLACE is the default.** An element you overlooked and an element you deliberately kept produce byte-identical HTML, so the written ledger is the only thing that separates them, and no automated check will ever flag the first one.
+
+| Stays — this is DNA | Goes — this is content |
+|---|---|
+| beat count and beat order; any beat the harness marks critical / `must_keep` | voiceover, every line — a fork ships the source brand's narration, and it passes every automated check |
+| each layer's `start`, `duration`, track and transitions — the rhythm | the music bed and the SFX |
+| the caption identity: font, size, placement, background style | every caption word |
+| the hook's *shape* and the payoff's *position* | on-screen text that is not a caption — titles, kickers, labels, prices, stat callouts, end cards |
+| the grade, the vignette, the stage treatment behind a background | the picture inside that background |
+| the palette and type tokens, unless the director has a brand | actor / talking-head clips (a face is a brand), product shots, screenshots, UI frames, mockups |
+| generic b-roll that is still true in the new subject's world — "a keyboard" survives a subject change, "a barista" does not survive a move to fintech | stickers and icons that name a thing; every logo, wordmark, @handle, URL and watermark — **those are never a KEEP** |
+
+Three tie-breaks when a row is not obvious: **provenance** (did I put this file here, or did I inherit it?), **relevance** (does it show the DIRECTOR's world?), **load-bearing** (cut it — does the beat still work? then CUT wins). Run the audit **before** sourcing: every REPLACE row is a line on the procurement list, which is what stops a beat being built twice. Report the counts — kept / replaced / cut — with the render. The full version is §3½ of `https://vidfarm.cc/flash-harness.md`.
+
 **Fuel a scene REPLACE with raw clips, not expensive AI video.** A heavy scenes-axis replace needs footage; sources in cost order: (1) the director's own library — search `/raws` and `/files` (`vidfarm raws search …`, `vidfarm files --search …` / `browse_files`); (1b) the **PUBLIC RAWS catalog, browsed by category** — free, pre-tagged, already on the platform, and no download or hunt required (`vidfarm public-raws --categories` to see the shelves, then `--category <shelf>`); (2) **HUNT new raws** out of a long-form source (podcast/VOD/webinar or any YouTube/TikTok/IG/X URL) — `vidfarm raws scan <src> --prompt "<what the new scenes need>" --aspect <canvas> [--duration N --no-text --range …]` (local-first, free compute) or the async `POST /clips/scan` / `/raws/scan`; then reuse the picks (`set_layer_media` / `vidfarm set-media` to swap in place, `add_layer`/`vidfarm place` for net-new scenes); (3) `generate_layer` / `vidfarm generate` AI generation — the **expensive last resort**, only for scenes no real clip can cover. When a big scene re-work is asked for but no footage is given, **ask for a source to hunt (or point at the raws library) before AI-generating** — see [Raws](#raws-long-form--short-form-raws) and [Generate AI media …](#generate-ai-media-and-drop-it-on-the-timeline).
 
 **Audio is natively multi-track — overlay narration + music + SFX, each at its own volume.** A composition mixes UNLIMITED simultaneous `<audio>` layers; each sits on its own `data-track-index` and carries its own `data-volume` (0–2, default 1), and the runtime mixes them with per-track volume honored identically in the preview and the exported MP4 (a real ffmpeg `amix` of every audio layer at render). So you never need a pre-mixed file — lay **narration/voiceover at ~1.0 on one track, a music bed at ~0.1–0.2 on a separate track, and SFX on their own tracks**, each via `add_layer kind=audio` (web) / `vidfarm place --kind audio --volume …` (devcli), tuning levels later with the Inspector's Volume slider or `set_layer_media` (`volume`, `muted`). **The key move when recreating a template whose original baked music + narration into ONE audio track: rebuild it as TWO independent tracks** — a fresh narration track (`/audio/speech`, or same-voice reword via `/audio/regenerate-speech` / `vidfarm speech regenerate`) at ~1.0 and a separate real music track at ~0.1–0.2 — then mute/remove the original combined source-audio layer. This gives the director independent voice and music volume, and works around AI TTS being unable to emit narration+music in one file: you compose the mix on the timeline. Honesty: you can't un-mix / stem-separate the original's baked audio — the two tracks are a fresh narration track **plus** a real music file (owned / user-provided / `browse_files` / generated with `/api/v1/primitives/music/generate` (`vidfarm music`)), never a faked or duplicated voice layer.
@@ -3614,7 +3643,7 @@ Read this when a director says **"give me content ideas"**, "what should I post"
 
 **This also runs FIRST for a brand-new director, before the cold-start interview.** It needs one line of offer, not an interview; it is offline, free, and keyless; and it hands the director 20+ titled videos in about a minute. That is the easiest win available on turn one, and their reactions to the list ("this one, not that one") are better raw material than anything an interview gets cold. Run it, save `content-ideas.md`, then offer the interview as the way to turn ideas into a strategy — `references/onboarding.md` → *Start with content ideas*.
 
-**What this is — three banks, not one.** An idea is a point in a small grid, and this reference holds all three axes:
+**What this is — four banks, not one.** An idea is a point in a small grid, and this reference holds every axis:
 
 | Axis | Bank | Question it answers |
 |---|---|---|
@@ -3622,12 +3651,13 @@ Read this when a director says **"give me content ideas"**, "what should I post"
 | **Frame** | 50 content frames | *What is the video the story of?* (`the rise of`, `then vs now`, `one decision that changed everything`) |
 | **Awareness** | 5 stages | *What does the viewer already know?* (unaware → problem-aware → solution-aware → product-aware → most-aware) |
 | **Angle** | 44 problem angles | *From which side do we talk about the problem?* (the hidden cost, the myth, the confession, the honest downside) |
+| **Format** | 40 ad formats | *What does the finished video look like?* (an iPhone note, a Reddit thread, a tier list, a warning label, a claymation) |
 
 The subject axis carries a **distance**: how far from the offer the video is allowed to sit. Distance is what produces genuinely different videos rather than differently-shaped ones, and the **turn back to the offer** is what keeps distance from becoming irrelevance — see *Distance* below. Freeze the subject at distance zero and no amount of frames or angles will save the list.
 
-A **frame** is a reusable shape for a video's subject — not a hook line, not a script. You pour the director's topic into it: `the rise of` + `dropshipping supplements` → *"The rise of the supplement dropship store"*. An **angle** decides which face of the problem that video shows; the same frame at two angles is two genuinely different videos. An **awareness stage** decides who it is allowed to be for — the same idea aimed at a stranger and at a buyer needs different first ten seconds and a different ask.
+A **frame** is a reusable shape for a video's subject — not a hook line, not a script. You pour the director's topic into it: `the rise of` + `dropshipping supplements` → *"The rise of the supplement dropship store"*. An **angle** decides which face of the problem that video shows; the same frame at two angles is two genuinely different videos. An **awareness stage** decides who it is allowed to be for — the same idea aimed at a stranger and at a buyer needs different first ten seconds and a different ask. A **format** decides what the thing on screen actually is — the same idea as an iPhone note, as a tier list, and as a warning label is three shoots, three thumbnails, and three different scroll behaviours.
 
-**The grid is where the volume comes from.** 50 frames × 44 angles × 5 stages, over a pool of adjacent subjects, is not a number to take literally, but it is why "I need 30 videos this month" is an easy ask, not a hard one. Vary **two** axes across a set and it never reads as repeats. Vary only one and it does — and the axis most often left frozen is the subject, because the offer line is right there and it is easy to paste.
+**The grid is where the volume comes from.** 50 frames × 44 angles × 5 stages × 40 formats, over a pool of adjacent subjects, is not a number to take literally, but it is why "I need 30 videos this month" is an easy ask, not a hard one. Vary **two** axes across a set and it never reads as repeats. Vary only one and it does — and the axis most often left frozen is the subject, because the offer line is right there and it is easy to paste.
 
 **How to use it (the loop).**
 
@@ -3636,8 +3666,9 @@ A **frame** is a reusable shape for a video's subject — not a hook line, not a
 3. **Spread across awareness stages, not just frames.** Most directors post everything at one stage — usually product-aware, because that is the stage they live in — and then wonder why the account does not grow. Cover the ladder deliberately; the default monthly mix is in *Spreading a month across the ladder* below. Say the stage next to each idea.
 4. **Pick frames and angles, don't dump the lists.** Choose 10–20 combinations that actually fit the topic. Label each idea `frame · angle · stage` so the director can say "more like that one" and you know exactly which axis they mean.
 5. **Write each idea as a title, not a frame.** Output `"The one pricing mistake that killed our first 400 orders"`, not `"one mistake that changed everything — about pricing"`. A frame that stays abstract is not an idea yet.
-6. **Then run it through the hook harness.** A content idea is the *subject*; it is not the four charges. Every idea a director picks still needs hook / loop / payoff / bait written before the timeline — `references/hooks-and-virality.md`. The frames on this list are deliberately curiosity-shaped, which makes the loop easy to name, but never skip that pass.
-7. **Batch it properly.** If the director wants the whole set produced, that is scripting mode with a `HARNESS.md` — `recipes/bulk-scripting-with-a-harness.md`. One idea per video, one line in the plan file, with its stage and angle recorded so the set stays balanced.
+6. **Give each idea a format.** The title says what the video is about; the format says what it *looks like* — see *The ad formats* below. Name it on the line (`iphone notes`, `tier list`, `warning`) so the shoot is decided before production, and rotate it so a month does not arrive as thirty talking heads.
+7. **Then run it through the hook harness.** A content idea is the *subject*; it is not the four charges. Every idea a director picks still needs hook / loop / payoff / bait written before the timeline — `references/hooks-and-virality.md`. The frames on this list are deliberately curiosity-shaped, which makes the loop easy to name, but never skip that pass.
+8. **Batch it properly.** If the director wants the whole set produced, that is scripting mode with a `HARNESS.md` — `recipes/bulk-scripting-with-a-harness.md`. One idea per video, one line in the plan file, with its stage and angle recorded so the set stays balanced.
 
 **Give lots when asked.** "Give me content ideas" means volume. Return **20+ titled ideas** by default, grouped by frame family or by awareness stage, not three polite suggestions. The director prunes; you supply.
 
@@ -3965,6 +3996,83 @@ An angle is **which side of the problem the video approaches from**. It is not a
 - the cost of waiting — the same decision made now vs in six months, priced
 - the first-mover gap — what the early ones get that the late ones cannot
 
+### The ad formats — 40 executions
+
+A format is **what the finished video is, as an object**. Not what it is about (frame), not which side of the problem it comes from (angle), not who it is for (stage), and not the first line (hook). `the hidden cost` `of the van receipts` `for a problem-aware viewer` is an idea; whether it arrives as an iPhone note, a Trustpilot screenshot or a claymation is the format, and the director still has to choose one before anybody films.
+
+**Why it is a bank and not a taste decision.** Left to taste, a director shoots the same talking head forty times and blames the ideas. The format is also the axis that costs the least to vary — the research, the title and the script survive a format swap intact — so it is the cheapest way to turn one idea that worked into four posts that do not read as reposts.
+
+`vidfarm ideas --formats` prints the bank; `--format <family or name>` filters it.
+
+**Fake-artifact formats — the video pretends to be something that is not an ad**
+
+- iphone notes — the pitch typed into the notes app, screen-recorded, no production at all
+- text message — the conversation that sells it, two people, read at the speed of reading
+- email screenshot — a real inbox: a complaint, a supplier reply, a refund thread
+- google search — the query they actually type, and what the results fail to answer
+- reddit style — the thread, the top comment, the reply that names the product
+- ig story — the casual story frame, sticker and all, reposted as the ad
+- trustpilot reviews — the review wall, scrolled, with the one-star ones left in
+- breaking news — the news lower-third and the anchor voice, applied to a small thing
+- native — no ad markers at all: it looks like the platform's ordinary content
+
+**List & ranking formats — the count is the promise**
+
+- x reasons why — the numbered case, one reason per beat, the count in the first frame
+- x signs — a checklist the viewer scores themselves against
+- tier list — S to F on screen, the product placed last and defended
+- hack 101 — one trick, taught properly, in under a minute
+- stat headline — one number, held on screen, everything else in service of it
+
+**Two-column formats — the comparison is the argument**
+
+- us vs them — the direct competitive split, named or unnamed
+- us vs us — the old version against the new one; no competitor is needed
+- new vs old — the category's past against its present
+- problem vs solution — left frame breaks, right frame works, same input
+- myth vs fact — the repeated sentence, then the correction, side by side
+- venn diagram — two circles, and the product sits in the overlap
+
+*These six overlap with the contrast frames above, and that is not a duplicate — `problem vs solution` as a **frame** is what the video is the story of, and as a **format** it is the split on screen. Use one as the format only when the frame is a contrast too. A video cannot carry two comparisons; that is the "do not stack two frames" rule wearing a new hat.*
+
+**Pattern-interrupt formats — it opens by refusing to sell**
+
+- don't buy this — the disqualification opener, then who it *is* for
+- don't be an idiot — the blunt correction; earns attention, spends goodwill
+- we're sorry — the apology format: an owned mistake, then the fix
+- side effect — the benefit stated as a warning label
+- zero stars — the worst review, read out, and answered
+- you can avoid — the outcome named first, the escape route second
+
+**Alert & urgency formats — the shape of an announcement, not an ad**
+
+- warning — the hazard sign, the deadline, the consequence of waiting
+- low stock alert — the shelf, the count, the date it runs out
+- case of emergency — break-glass framing: the thing to do when it goes wrong
+- bundle offer — what is in the box, itemised, priced against the parts
+
+**Proof formats — something visibly changes on camera**
+
+- customer testimonial — their words, their room, their number
+- transformation — before and after in one cut, same frame, same light
+- crossed out problems — the list of pains, struck through one at a time
+
+**Made-look formats — the production style carries it**
+
+- whiteboard — drawn while spoken; the hand is the retention device
+- doodle — rough marker illustration over the footage
+- meme — the format the niche already shares, recaptioned at a real pain
+- claymation — stop-motion or clay-look; the craft is the scroll-stopper
+- greenscreen — the presenter keyed over the artifact they are reacting to
+- text on skin — the words written on a hand, an arm, a face
+- ai podcast — two synthetic hosts discussing it, clipped like a podcast
+
+**Choosing one.** Match the format to the stage, not to the mood. Fake-artifact and made-look formats carry stage 1 and 2, because they read as content rather than as an ad. Two-column and list formats carry stage 3, because they explain. Proof and pattern-interrupt formats carry stage 4, because they answer an objection. Alert formats carry stage 5, and only stage 5 — a warning label shown to a stranger is a scroll.
+
+**The honesty rule, and it is the important one.** Several of these formats work by imitating a *record*: a review wall, an inbox, a search result, a news bulletin, a stock count. An imitation of a record that states something untrue is a fabricated record, and it is the client's problem the moment it posts. So: use a real screenshot where a real one exists; where the artifact is staged, keep every claim inside it true and checkable; never stage a third party's review, message or verdict; and never invent a deadline or a stock number that is not real. The same flag-it-for-checking rule from *Distance* applies to every number the artifact shows.
+
+**Do not let the format become the idea.** "Let's do a tier list" is not a content idea — it is a shoot with nothing in it. Pick the subject, the angle and the stage first; the format is the last field, and it is the one you change when an idea that worked deserves a second post.
+
 ### Frame × angle × stage — the grid
 
 The grid is the answer to "give me 30 different videos" and to "I already made a video about that."
@@ -3974,25 +4082,26 @@ The grid is the answer to "give me 30 different videos" and to "I already made a
 3. Pick an **angle** that fits that stage (each stage above lists its five).
 4. Pick a **frame** that carries the angle (each stage above lists its six).
 5. Write the title. If the title does not say the angle out loud, the pairing was wrong — go back to step 3, not step 4.
+6. Pick a **format** the stage can carry, and write it on the row. It is the last field, and the only one you may change on its own.
 
 Worked example, one topic (`bookkeeping for solo trades`), one frame family, four angles, four different videos:
 
-| Stage | Angle | Frame | Title |
-|---|---|---|---|
-| 1 | the daily friction | the psychology of | *"Why every tradie has a glovebox full of receipts"* |
-| 2 | the hidden cost | why it failed | *"The £3,400 a year that disappears in your van"* |
-| 3 | the false solution | myth vs reality | *"A shoebox is not a filing system, and HMRC agrees"* |
-| 4 | the price objection | cheap vs expensive | *"£49 a month vs the accountant's £900 catch-up bill"* |
+| Stage | Angle | Frame | Format | Title |
+|---|---|---|---|---|
+| 1 | the daily friction | the psychology of | native | *"Why every tradie has a glovebox full of receipts"* |
+| 2 | the hidden cost | why it failed | stat headline | *"The £3,400 a year that disappears in your van"* |
+| 3 | the false solution | myth vs reality | myth vs fact | *"A shoebox is not a filing system, and HMRC agrees"* |
+| 4 | the price objection | cheap vs expensive | us vs them | *"£49 a month vs the accountant's £900 catch-up bill"* |
 
 **When a director says "I already covered that."** Hold the frame, change the angle. Same subject, new video, and it is the cheapest idea in the bank to produce because the research is already done.
 
 **When a set feels repetitive.** Check which axis you froze — and check the **subject** first, because it is the one that hides. Thirty ideas that vary only the frame, on one pasted offer sentence, at one stage and one angle, are thirty versions of one video. Vary two axes minimum, and never let the subject be the constant.
 
-### Frame → format notes
+### Frame → build notes
 
-The frame also suggests how to build it, which saves a planning round:
+The frame also suggests how to build it, which saves a planning round. This is the *default* build; a format from the bank above overrides it:
 
-| Frame family | Natural format | Build notes |
+| Frame family | Natural build | Build notes |
 |---|---|---|
 | Contrast (`then vs now`, `cheap vs expensive`) | Split screen or A/B beat pairs | Cheapest to produce — two stills or two clips per beat. Great for the cutout/sticker explainer style. |
 | Hidden-knowledge (`what nobody noticed`, `the untold story`) | Talking head, or footage + kinetic captions | The loop writes itself; state the timestamp it closes at anyway. |
@@ -4014,6 +4123,9 @@ The frame also suggests how to build it, which saves a planning round:
 - **Do not hand over a distant idea with no turn written.** A video about Napoleon's field library, for a book app, is a great video and a dead one until somebody writes the line that reaches the offer. Write the turn with the idea, in the same breath, or drop the idea.
 - **Do not let the whole list become dated trivia.** "Be concrete" pushes a model straight into "in 1978, a man…". Fifty history videos is one idea fifty times, exactly like the frozen subject. Spread the proof types.
 - **Do not state a date, a number or a record without flagging it for checking.** The editor films what the brief says. A wrong figure is the director's problem the moment it posts, not the writer's.
+- **Do not pick the format first.** "Let's do a tier list" is a shoot with no idea in it. The format is the last field on the row, after the subject, the angle and the stage.
+- **Do not run one format for a month.** Thirty talking heads and thirty tier lists fail the same way, and the format is the cheapest axis to rotate — the script survives the swap.
+- **Do not fabricate the artifact a format imitates.** A staged review wall, a staged inbox, an invented stock count or an invented deadline is a fabricated record with the client's name on it. Use the real screenshot, or keep every claim inside the staged one true.
 
 ## Primitive: image_remove_background
 
@@ -4633,16 +4745,17 @@ Use this when the user wants to keep the format’s feel but replace the subject
 1. Read `references/editor-workflows.md`.
 2. Fetch `video-context.json` and `editor-harness.json` first.
 3. State the plan in the three axes vocabulary: scenes, audio, text; SWAP vs REPLACE for each.
-4. Preserve the hook structure, cut rhythm, emotional punch, and important scenes flagged by the harness. **Read `references/hooks-and-virality.md` before rewriting the opening line or the retention beat** — `viral_dna.hook`/`retention`/`payoff` name the source's four charges, and rebuilding each one for the new subject (rather than flattening the loop into a product statement) is the whole job.
-5. Source footage in this order:
+4. **Audit every element before you touch one.** The fork is somebody else's *finished* video, so list its layers (`vidfarm pull <forkId> --json` → `.layers[]`, plus `grep -o 'data-src="[^"]*"' composition.html | sort -u`) and write one row per element into `./work/ADAPTATION.md`: KEEP / REPLACE / CUT, why, what replaced it. **KEEP is the verdict that needs a reason.** Structure stays (beat count and order, `start`/`duration`, cut rhythm, transitions, caption identity); meaning goes (voiceover, music, caption words, on-screen titles and prices and stats, actor clips, product shots and screenshots, stickers that name a thing, the picture behind a background, and every logo, @handle, URL and watermark). See `references/editor-workflows.md` → *Before the axes: audit every element*. The REPLACE rows are your sourcing list for step 6.
+5. Preserve the hook structure, cut rhythm, emotional punch, and important scenes flagged by the harness. **Read `references/hooks-and-virality.md` before rewriting the opening line or the retention beat** — `viral_dna.hook`/`retention`/`payoff` name the source's four charges, and rebuilding each one for the new subject (rather than flattening the loop into a product statement) is the whole job.
+6. Source footage for every REPLACE row, in this order:
    - My Files or existing raws
    - a raws hunt from a long-form source
    - AI image generation
    - AI video generation only with permission
-6. Rebuild captions and narration so timing, cadence, and joke structure survive the subject change.
-7. Render, verify, then approve and schedule only after the director is happy.
+7. Rebuild captions and narration so timing, cadence, and joke structure survive the subject change.
+8. Render, verify, then approve and schedule only after the director is happy. Report the audit counts — kept / replaced / cut — with it.
 
-Failure mode to avoid: flattening the format by swapping words but losing the timing, sound, or payoff beat.
+Two failure modes to avoid: flattening the format by swapping words but losing the timing, sound, or payoff beat — and the opposite, swapping the words and leaving everything else, so the source brand's voice, screenshots, stickers or handle ship inside the director's video.
 
 ## Recipe: Local Pull, Edit, Render, Approve