@officexapp/vidfarm-devcli 0.21.58 → 0.21.60

package/experimental/flash-harness.md

@@ -46,9 +46,13 @@ read them after, not during. A reason next to a rule is something to negotiate w
 8. **Walk the asset ladder in order and stop at the first rung that answers:** client's
    shared folder → client's website → public raws → free stock (Pixabay/Openverse) →
    IconScout → your own subscription's generator → billed generation.
-9. **Keep the load-bearing DNA. Replace everything else without mercy.** Load-bearing =
-   the beat count, the cut rhythm, the hook shape, the payoff position, the caption
-   identity. Every word, every image, every voice line gets replaced.
+9. **Audit every element, one at a time, before you plan — then keep the load-bearing DNA
+   and replace the rest without mercy.** Load-bearing = the beat count, the cut rhythm,
+   the hook shape, the payoff position, the caption identity. Everything that carries
+   *meaning* — every voice line, every caption word, every clip, image, sticker,
+   background, on-screen title, logo and handle — belongs to the source brand until you
+   decide otherwise, element by element, in `./work/ADAPTATION.md` (§3½). **KEEP is the
+   verdict that needs a reason. REPLACE is the default.**
 10. **Overfitting to this one template is CORRECT.** Do not add originality on top. The
     template is the originality; your job is the transplant.
 11. **Run the gate as a command, not from memory:** `vidfarm qa ./work --harness ./HARNESS.md`,
@@ -271,6 +275,97 @@ A plan is free to redo. A rendered beat is not.
 
 ---
 
+## 3½. The element audit — every element earns its place
+
+**A fork is not a half-finished video that is already partly right. It is somebody else's
+FINISHED video.** Every element in it was chosen for their product, their customer, their
+joke, their face, their palette. Anything you do not deliberately re-decide stays theirs —
+and the client watches the result.
+
+So walk the composition element by element and give every one a verdict. There are three:
+
+| Verdict | Means |
+|---|---|
+| **KEEP** | it carries the DNA, or it is generic enough to be just as true in the client's world |
+| **REPLACE** | it says something about the source's world. Swap it for the client's equivalent |
+| **CUT** | the client's story does not have this beat or this ornament. Delete it, ripple the hole closed |
+
+> **KEEP is the verdict that needs a reason. REPLACE is the default.**
+>
+> This is backwards from how it feels, and that is the point. The cheap failure is not a bad
+> replacement — it is an element nobody ever looked at. **A cut whose captions changed and
+> nothing else is the most commonly rejected video there is**, and on the marketplace it is
+> the most commonly rejected proof. The client is paying for a video about *their* thing.
+> Relevant customization is the deliverable.
+
+### List the elements — from the file, not from memory
+
+```bash
+vidfarm pull <forkId> --dir ./work --json \
+  | jq -r '.layers[] | [.key, (.kind // "?"), (.start|tostring), (.duration|tostring), (.label // "—"), (.src // "—")] | @tsv'
+
+grep -o 'data-src="[^"]*"' ./work/composition.html | sort -u   # every asset file the video loads
+grep -o 'data-layer-kind="[^"]*"' ./work/composition.html | sort | uniq -c
+vidfarm captions list ./work                                   # every caption cue, with its words
+```
+
+`vidfarm pull` without `--json` prints the same layer keys in a readable list. Read
+`./work/HARNESS.md` alongside it: beats marked critical / `must_keep` are the ones you may
+not CUT.
+
+**A `text` layer has no `src`, so the inventory shows it as `—`. That is not "nothing to
+decide" — it is the words on screen.** `vidfarm captions list ./work` reads the caption
+cues; the titles, kickers, labels, price tags and end cards you read out of the DOM. They
+get a row each, like everything else.
+
+### Write `./work/ADAPTATION.md` — one row per element
+
+| layer key | what it is | verdict | why | replaced with |
+|---|---|---|---|---|
+| `scene-1-vo` | voiceover, "Dishcovery finds you recipes" | REPLACE | names another product | `./work/vo-01.mp3` |
+| `scene-1-bg` | full-canvas kitchen b-roll | KEEP | generic kitchen, still true for a food client | — |
+| `scene-2-logo` | source brand wordmark, 0.4s | CUT | not the client's brand, beat survives without it | — |
+| `cap-*` (23 cues) | caption identity: Montserrat 900, lower third, outline | KEEP | this is the visual DNA — the cheapest thing to keep | — |
+
+### The default verdict per element class
+
+Start here, then override with a reason written into the row.
+
+| Element class | Default | Why |
+|---|---|---|
+| **Voiceover / TTS — every line** | REPLACE | a fork carries the source brand's narration. See the warning in §3 |
+| **Music bed / SFX** | REPLACE | the track is part of the source's identity, and the licence is not yours |
+| **Captions — the words** | REPLACE, every cue | they are the script |
+| **Captions — the identity** (font, size, placement, background style) | KEEP | this is visual DNA, and the most expensive thing to get right yourself |
+| **On-screen text that is NOT a caption** — titles, kickers, labels, price tags, list items, stat callouts, end cards | REPLACE or CUT | these are the source's claims. A stale number or a stale price is worse than none |
+| **A-roll / talking-head / actor clips** | REPLACE | a face is a brand. The wrong person recommending the client's product is the loudest possible defect |
+| **B-roll clips** | REPLACE unless generic **and** still true in the client's world | "a keyboard" survives a subject change; "a barista pulling a shot" does not survive a move to fintech |
+| **Product images, screenshots, UI frames, mockups** | REPLACE, always | this is literally the other company's product on screen |
+| **Stickers, icons, cutouts, emoji** | REPLACE when they name a thing; KEEP when purely decorative and on-palette | a burger sticker in a payroll video is a rejection |
+| **Backgrounds / plates / colour fields** | KEEP the treatment, REPLACE the picture | the parchment stage, the vignette, the grade are DNA. The photo behind them is content |
+| **Logos, wordmarks, @handles, URLs, watermarks, end-card CTAs** | REPLACE or CUT — **never KEEP** | shipping a competitor's handle is the fastest way to lose a buyer and a trust score |
+| **Palette + typography tokens** | KEEP, unless the client has a brand | then match the client's, staying inside the five allowed fonts |
+| **`start`, `duration`, `track`, transitions** | KEEP | the rhythm is the DNA. Retiming is how a weak model flattens a format |
+| **Beat count and beat order** | KEEP | drop a beat only deliberately, and say which one and why in your report |
+
+### Three tests, when a row is not obvious
+
+1. **Provenance** — *did I put this file here?* If the `data-src` still resolves to the
+   source template's storage, nothing was decided about it; it was inherited.
+2. **Relevance** — *does this show the CLIENT's world?* Their product, their customer, their
+   category, their words. If it shows anyone else's, REPLACE.
+3. **Load-bearing** — *cut it and read the beat again.* If the beat still works, CUT wins.
+   Ornament you keep out of politeness is what makes a video feel like a template.
+
+### Before you leave §3½
+
+Every layer key from the inventory appears in `ADAPTATION.md` with a verdict. **Count the
+rows against the layer count** — an element with no row is an element you never decided.
+Then carry every REPLACE row into `STORYBOARD.md`'s `src` column: **the audit IS your
+shopping list for §4.**
+
+---
+
 ## 4. Procure every raw — one pass, before you edit
 
 **This is the half of the job that decides whether the video is good, and it is the half
@@ -348,23 +443,32 @@ vidfarm serve --fork <forkId>   # free local editor + render loop at localhost:3
 
 ### What you are doing, precisely
 
-You are running a **transplant**, beat by beat, down `STORYBOARD.md`. For each beat:
+You are running a **transplant**, and `ADAPTATION.md` from §3½ is the work order. Take the
+rows in timeline order. For each one:
 
-1. Find the source layer (`vidfarm pull` printed the scene/layer keys).
-2. Swap its `data-src` for your procured asset.
-3. Rewrite its text for the client.
-4. **Leave `start` and `duration` alone** unless the Structural DNA says that beat is free.
+1. Find the layer by its key (`vidfarm pull` printed them).
+2. **REPLACE** — swap its `data-src` for your procured asset, or rewrite its text for the
+   client. Then write the new asset into the row's *replaced with* cell.
+3. **CUT** — delete the layer, then close the hole (`vidfarm ripple`) so the rhythm survives.
+4. **KEEP** — do nothing, and leave the reason in the row. It is the only verdict a reviewer
+   will question.
+5. **Leave `start` and `duration` alone** unless the Structural DNA says that beat is free.
 
-### Keep vs replace — the line
+### Work the ledger, not your memory
 
-| Keep — this is the DNA | Replace — this is the dressing |
-|---|---|
-| beat count and beat order | every clip, every image, every sticker |
-| each beat's `start` and `duration` | every caption word |
-| the cut rhythm and the transitions | the palette, if the client has a brand |
-| the caption identity — font, size, placement, background style | the voiceover, every line of it |
-| the hook's *shape* and the payoff's *position* | the music bed |
-| any beat marked critical / `must_keep` | the offer, the handle, the CTA |
+**A row you have not touched is not a KEEP — it is an element you forgot.** The two are
+indistinguishable in the finished video and completely different in the buyer's reaction, so
+close the loop in the file: every REPLACE row ends with the asset you actually put there.
+
+When the pass is done, prove there is no residue from the source brand:
+
+```bash
+grep -o 'data-src="[^"]*"' ./work/composition.html | sort -u   # any src still on the source's storage?
+grep -oiE '@[a-z0-9_.]+|https?://[^"< ]+' ./work/composition.html | sort -u   # stray handles and URLs
+```
+
+Read both lists row by row. Anything that is not the client's, and not a generic asset you
+deliberately kept, is unfinished work — not a detail to mention in the report.
 
 ### "It is okay to heavily alter it"
 
@@ -409,8 +513,11 @@ vidfarm stills ./work --sheet                 # contact sheet → read it as ONE
 your report instead of running is not a check, and this is the failure mode weak models hit
 hardest: reporting a pass on the half the CLI never judged.
 
-Three things the CLI cannot judge, which you must answer honestly:
+Four things the CLI cannot judge, which you must answer honestly:
 
+- **The audit is closed.** Every row in `ADAPTATION.md` has a verdict, every REPLACE row
+  names the asset that replaced it, and every KEEP row carries a reason. Report the three
+  counts — kept / replaced / cut — not the word "done".
 - **Audio provenance.** Paste the `grep` output from §3. Every audio `data-src` is yours.
 - **The contact sheet.** One type scale, one palette, deliberate pacing, clean joins. If
   two beats look like they came from different videos, they did — fix it.
@@ -450,6 +557,9 @@ FLASH-HARNESS RESULT
   source_template:     template_...
   decomposed_by:       already | cloud | local | inspiration-mint
   format_harness:      <name or "none — freestyled">
+  elements_audited:    <n>/<n layers in the fork>   (ADAPTATION.md, §3½)
+  element_verdicts:    kept=<n> replaced=<n> cut=<n>
+  kept_and_why:        <one line per KEEP that a reviewer could question>
   beats:               <kept>/<source total>   dropped: <which, and why>
   assets_by_rung:      shared=<n> website=<n> raws=<n> stock=<n> iconscout=<n> subscription=<n> billed=<n>
   audio_replaced:      <n>/<n> audio data-src now point at my own files
@@ -489,6 +599,16 @@ cost*, not by cost alone. A designer's finished transparent vector from IconScou
 generated icon on both axes. A real photo beats a generated photo. Free does not mean first
 — *best free* means first.
 
+**Why the audit is element-by-element, and why KEEP needs the reason (rule 9).** A fork
+starts as a video that is 100% about another company, and it degrades gracefully: swap the
+captions and it still plays, still renders, still passes every automated check — while a
+competitor's screenshot sits in beat 4 and a competitor's handle sits on the end card. Nothing
+in the pipeline flags an element you never looked at, because "untouched" and "deliberately
+kept" produce byte-identical HTML. The written ledger is the only thing that separates them.
+Making REPLACE the default costs a few minutes on the rows that genuinely should stay, and it
+removes the failure that gets proofs rejected: a video the buyer can tell was made for
+somebody else.
+
 **Why overfitting is fine (rules 9–10).** A weak model's improvisation has a wide variance
 and a low mean. A decomposed template has a narrow variance and a high mean. Across a batch
 of thirty videos the client sees, the template path wins on every percentile that matters —
@@ -530,6 +650,10 @@ vidfarm harness show ./work/HARNESS.md --dna viral
 vidfarm harness show ./work/HARNESS.md --dna visual
 vidfarm storyboard ./work --init --frames "Hook,Problem,Reveal,CTA"
 
+# 3½ — audit every element, then write ./work/ADAPTATION.md (KEEP needs the reason)
+vidfarm pull <forkId> --dir ./work --json | jq -r '.layers[] | [.key,(.kind//"?"),(.src//"—")] | @tsv'
+grep -o 'data-src="[^"]*"' ./work/composition.html | sort -u
+
 # 4 — procure (one pass, every beat)
 vidfarm shared ls "$ASSETS_LINK"
 vidfarm capture <client-url>