@officexapp/vidfarm-devcli 0.21.57 → 0.21.59

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

@@ -1,6 +1,6 @@
 ---
 name: vidfarm
-skill_version: 0.21.57
+skill_version: 0.21.59
 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.
 ---
 
@@ -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/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.57
+skill_version: 0.21.59
 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.
 ---
 
@@ -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.
@@ -4633,16 +4662,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
 

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: vidfarm
-skill_version: 0.21.57
+skill_version: 0.21.59
 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,8 @@ 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*.
+
+**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/dist/src/cli.js

@@ -1195,7 +1195,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 +1203,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)

package/dist/src/devcli/clipper-run.js

@@ -350,6 +350,10 @@ function cmdInit(root, values) {
     seed("NOTES.md", "# Notes\n\nWhat each buyer approved, what they rejected and with which tag, prices that moved.\n");
     seed("EARNINGS.md", "# Earnings\n\nsubmitted / approved / PAID / owed, with dates. `approved` is not `paid`.\n");
     seed("LEDGER.jsonl", "");
+    // The anti-repeat record. LEDGER.jsonl knows the money; this knows the IDEA —
+    // which clip, which hook, which pain went to which buyer. Read it before you
+    // shortlist, or you sell one buyer the same video twice.
+    seed("DELIVERED.tsv", "# gig_id\tproof_id\tharness\ttemplate_id\tsource_clip\thook\tpain\tverdict\n");
     writeReviewQueue(root);
     out(Boolean(values.json), { ok: true, root, mode, created }, () => {
         console.log(`${GREEN}✓${RESET} Mission folder ready at ${BOLD}${root}${RESET}`);
@@ -806,6 +810,10 @@ function cmdGate(root, values, positionals) {
     }, () => {
         if (!blocked) {
             console.log(`${GREEN}✓ CLEARED TO SUBMIT${RESET} ${BOLD}${state.task_id}${RESET}${state.reviewed_by_gigworker ? ` ${DIM}(gigworker approved the cut at ${state.reviewed_by_gigworker})${RESET}` : ` ${DIM}(auto-submit — no human watched this)${RESET}`}`);
+            // This gate answers "did a human watch it", never "can the buyer open it".
+            // The second question is the other pre-submit check, and it is the one that
+            // catches a 403 bucket or an expiring link.
+            console.log(`  ${DIM}Now check the buyer can actually play it: vidfarm gigs verify-proof --proof <url>${state.clean_master ? ` --clean-master ${state.clean_master}` : ""}${RESET}`);
             return;
         }
         console.log(`${YELLOW}HOLD${RESET} ${BOLD}${state.task_id}${RESET} ${DIM}is at ${state.stage}${state.gate ? ` and waiting on the gigworker (${state.gate.stage})` : ""}${RESET}`);