@mevdragon/vidfarm-devcli 0.20.4 → 0.20.6

package/SKILL.director.md

@@ -249,6 +249,41 @@ Read-only state (does **not** advance the job or bill): `GET /api/v1/composition
       "delivery": "flat VO cadence, hold the beat before the punch, beat drop lands on the reveal",
       "preserve": ["keep the beat drop on the reveal cut", "keep the flat unbothered delivery"]
     },
+    "static_vs_pivot": {
+      "summary": "Keep the reveal structure and audio swagger; swap the subject-specific visuals and copy.",
+      "scene_replacement": {
+        "overall": "replace_some",
+        "reason": "the proof/reveal beats are load-bearing, but the subject matter can pivot",
+        "must_keep": ["final reveal beat", "setup-to-payoff contrast"],
+        "should_replace": ["subject-specific graphics", "brand-specific screenshots"],
+        "load_bearing_scenes": ["hook setup", "payoff reveal"]
+      },
+      "narration": {
+        "overall": "customize_script",
+        "reason": "the spoken words are source-specific and stop making sense after a subject swap",
+        "same_timing_required": true,
+        "use_premium_tts_when_customizing": true
+      },
+      "music": {
+        "overall": "recreate_under_narration",
+        "reason": "the music energy matters, but the original combined track should not stay under a rewritten script",
+        "volume_guidance": "keep low under VO unless the beat-drop is the joke engine"
+      },
+      "captions": {
+        "overall": "retime_to_new_narration",
+        "reason": "caption animation is tied to the spoken words",
+        "animation_dependency": "word-by-word timing follows narration cadence"
+      },
+      "visual_rebuild": {
+        "default_strategy": "ai_images_with_ken_burns",
+        "reason": "most replacement scenes are graphic/still-like and do not need expensive motion video"
+      },
+      "viral_dna": {
+        "must_keep": ["hook structure", "payoff timing", "audio attitude"],
+        "flexible": ["subject matter", "product imagery", "copy details"],
+        "do_not_change": ["core reveal mechanic", "caption cadence"]
+      }
+    },
     "preserve": ["..."], "avoid": ["..."], "promotions": ["..."], "keywords": ["..."]
   }
 }
@@ -258,6 +293,15 @@ Read-only state (does **not** advance the job or bill): `GET /api/v1/composition
 
 **`viral_dna.emotional_punch`** is the FEELING of the format and what makes it land — the part a remix most often flattens. Where hook/retention/payoff are the mechanical structure, this captures the vibe, the joke, and the intonation. It is now **audio-aware**: the decompose feeds the transcript into the reasoning, so `mechanism`/`delivery` account for the trending sound, the music-bed drop, and vocal cadence (on short-form the sound is frequently the biggest driver of the punch). When you re-theme or remix, rebuild `humor`'s joke around the new subject rather than dropping it, match `tone`/`delivery` so intonation and comedic timing survive, and never trade the `peak_moment` payoff for a flat product plug.
 
+**`viral_dna.static_vs_pivot`** is the first-class lazy-prompt playbook. It tells you what must stay versus what can pivot when the user gives a thin prompt like "recreate this for my business" and little else. Use it to decide:
+
+- whether most scenes should be replaced or only some
+- whether narration must be customized or the original audio should stay
+- whether background music must be recreated under a new voice
+- whether animated captions need fresh timing against new narration
+- whether cheap AI images + Ken Burns are sufficient, or whether real/AI motion footage is required
+- which beats are load-bearing viral DNA versus merely subject-specific dressing
+
 Use it whenever you need to know what the video says or shows: writing/translating captions, matching hooks or dubs to spoken audio, or planning scene-level edits.
 
 - **Editor chat (frontend AI)** exposes this as the optional `video_context` tool — the copilot calls it on demand.
@@ -287,10 +331,10 @@ Use it whenever you need to know what the video says or shows: writing/translati
 }
 ```
 
-**Use it to pick concrete moves:** `typography.caption_style` maps to a `set_captions` preset; `transitions.*` to a `set_transitions` call; keep `pacing` (cut rhythm / avg_scene_seconds) when adding or splitting scenes; follow `broll.reliance`/`sourcing` to decide HUNT raws (`/raws/scan`) vs generate; lay `audio.*`. **`emotional`** is HOW to keep the FEELING while you swap the subject — the vibe/joke/intonation/sound are the first things a remix flattens, so honor `emotional.comedic_timing` (the held beat / hard cut that sells the joke), preserve `emotional.intonation` when you re-voice narration, and treat every `emotional.vibe_anchors` entry as a must-do (on short-form the trending sound / beat drop is often the biggest carrier of the punch — keep it and land it on the same cut). **Protect** any beat in `important_scenes` or with `must_keep:true` / `importance:"critical"` — swap the subject but preserve its timing, role, and caption cadence. Treat `editing_bias`/`do`/`dont` as hard constraints; an explicit user instruction still wins. `status:"none"` → run `POST /auto-decompose` first.
+**Use it to pick concrete moves:** `typography.caption_style` maps to a `set_captions` preset; `transitions.*` to a `set_transitions` call; keep `pacing` (cut rhythm / avg_scene_seconds) when adding or splitting scenes; follow `broll.reliance`/`sourcing` to decide HUNT raws (`/raws/scan`) vs generate; lay `audio.*`. **`emotional`** is HOW to keep the FEELING while you swap the subject — the vibe/joke/intonation/sound are the first things a remix flattens, so honor `emotional.comedic_timing` (the held beat / hard cut that sells the joke), preserve `emotional.intonation` when you re-voice narration, and treat every `emotional.vibe_anchors` entry as a must-do (on short-form the trending sound / beat drop is often the biggest carrier of the punch — keep it and land it on the same cut). Pair that with `viral_dna.static_vs_pivot`: if narration is `customize_script`, revoice and then retime captions/scenes that depend on the old VO; if visual_rebuild is `ai_images_with_ken_burns`, do the cheap still+motion path before reaching for AI video; if a scene is listed under `load_bearing_scenes`, preserve its beat even when you swap the subject. **Protect** any beat in `important_scenes` or with `must_keep:true` / `importance:"critical"` — swap the subject but preserve its timing, role, and caption cadence. Treat `editing_bias`/`do`/`dont` as hard constraints; an explicit user instruction still wins. `status:"none"` → run `POST /auto-decompose` first.
 
 - **Editor chat (frontend AI)** already receives the harness inline in `editor_context.editor_harness` (no tool call needed); it can also fetch this route via `http_request`.
-- **Desktop agents (Claude Code / Codex)**: `vidfarm pull` writes `editor-harness.json` to the fork dir (the brief is under `.harness`) alongside `video-context.json`; read it before a big edit. The `pull` grounding line reports whether it's present.
+- **Desktop agents (Claude Code / Codex)**: `vidfarm pull` writes `editor-harness.json` to the fork dir alongside `video-context.json`, and also materializes a merged agent bundle at `.harness/context.json` plus `.harness/agent-guide.md`. This deliberately does **not** write a top-level `AGENTS.md`, because many user repos already own that file. For local scripting or agentic edits, read `.harness/agent-guide.md` and `.harness/context.json` FIRST; do not freestyle from `composition.html` alone. The `pull` grounding line reports the generated brief paths.
 
 ## Raws (long-form → short-form raws)
 
@@ -696,6 +740,23 @@ If you need many variants, keep the base fork fixed and fan out by cloning that
 - `POST /api/v1/compositions/:forkId/render` with a stable `tracer`, or `vidfarm render <forkId> --dir ./work --wait` for the same composed flow
 - `render_target: "cloud"` when you want cloud handoff from a local `vidfarm serve` box, or the default local renderer when you want free in-process output
 
+**Required grounding for AI-authored scripts.** If an AI agent is going to WRITE or MODIFY a local Vidfarm script for a user, the safe default is:
+
+1. `vidfarm pull <forkId> --dir ./work`
+2. Read `./work/.harness/agent-guide.md`
+3. Read `./work/.harness/context.json`
+4. Only then read/edit `composition.html`, `composition.json`, and write the automation logic
+
+That is the canonical local scripting path because the pull step now packages:
+
+- `video-context.json`: transcript, scene descriptions, viral DNA
+- `editor-harness.json`: technical editing brief
+- `scene-annotations.json`: per-scene replacement/recreation DNA
+- `.harness/context.json`: merged agent-facing snapshot
+- `.harness/agent-guide.md`: Vidfarm-specific instruction file telling a generic agent how to use the above without conflicting with any repo-owned `AGENTS.md`
+
+If a local AI script rewrites text or scenes without consuming those files first, treat that as a bug in the script/agent flow.
+
 | Command | REST route | Flow step |
 |---|---|---|
 | `vidfarm discover [query]` | `GET /discover/feed[?q=]` | browse/search templates |
@@ -704,7 +765,7 @@ If you need many variants, keep the base fork fixed and fan out by cloning that
 | `vidfarm inspiration-rm <id>` | `DELETE /discover/templates/:id` | remove a private one |
 | `vidfarm inspiration-decompose <id>` | `POST /api/v1/inspirations/:id/decompose` | AI-decompose an inspiration |
 | `vidfarm fork <template_id>` | `POST /api/v1/compositions` | fork a template |
-| `vidfarm pull <forkId> [--dir <p>]` | `GET .../compositions/:forkId/{composition.html,json,video-context.json,cast.json,scene-annotations.json,editor-harness.json}` | sync a fork to disk + print gaps/scene keys + grounding (incl. editor-harness style brief) |
+| `vidfarm pull <forkId> [--dir <p>]` | `GET .../compositions/:forkId/{composition.html,json,video-context.json,cast.json,scene-annotations.json,editor-harness.json}` | sync a fork to disk + generate `.harness/context.json` and `.harness/agent-guide.md` + print gaps/scene keys + grounding |
 | `vidfarm generate <image\|video> --prompt "…"` | `POST /api/v1/primitives/{images,videos}/generate` (polls job) | generate AI media → finished URL |
 | `vidfarm inpaint <image> --mask <png> --prompt "…" [--region "label=…"] [--ref …] [--out <f>]` | `POST /api/v1/primitives/images/inpaint` (polls job) | masked image EDIT — replace ONLY the transparent-mask region, keep everything else (devcli twin of the /inpaint page) |
 | `vidfarm create-overlay "<subject>" [--key-color #00FF00] [--aspect-ratio 1:1] [--place <dir>] [--out <f>]` | `POST /api/v1/primitives/images/create-overlay` (polls job) | **Vox-style** transparent OVERLAY — AI image on a forced key-color background, chroma-keyed out in one job → ready-to-composite transparent PNG |