@mevdragon/vidfarm-devcli 0.20.3 → 0.20.5

package/.agents/skills/editor-capabilities/SKILL.md

@@ -49,7 +49,7 @@ This mints a new fork and opens it in the editor — the same **New fork** actio
 
 The most common intent: the user opens a template to reuse its structure and says *"make this for X"* (e.g. a book-recap template → "The Richest Man in Babylon", or a listicle → "my coffee brand"). Treat it as first-class:
 
-1. **Read the DNA first.** `composition_context` carries the format/genre + arc (trend_tagline, hook, retention, payoff, preserve, avoid). For the scene beats/transcript, call the `video_context` tool. Match the template's *voice* — a text-message template's captions read like chat, a story-time template reads like first-person narration; don't default to generic ad copy.
+1. **Read the DNA first.** `composition_context` carries the format/genre + arc (trend_tagline, hook, retention, payoff, preserve, avoid) **plus `emotional_punch`** — the FEELING the format delivers (`core_emotion`, `tone`, `arc`, `peak_moment`, `mechanism`, `humor`, `delivery`, `preserve`): the vibe/joke/intonation a remix most often flattens. Rebuild `humor`'s joke around the new subject rather than dropping it, match `tone`/`delivery` so timing and intonation survive, and never trade the `peak_moment` payoff for a flat product plug. For the scene beats/transcript, call the `video_context` tool (whose `viral_dna` also carries the full `emotional_punch`). Match the template's *voice* — a text-message template's captions read like chat, a story-time template reads like first-person narration; don't default to generic ad copy.
 2. **Propose, then ask only what you can't infer.** One concise plan plus a couple of questions: which specifics of the new subject to feature (offer to pick the strongest N to match the scene count), keep the current narrator voice?, any brand assets/images to use (else you'll generate), a target length if different.
 3. **Execute axis by axis, preserving the DNA:**
    - TEXT → rewrite every caption/title layer in the template's voice (`set_layer_text` / `set_captions`), keeping caption animation + timing.

package/SKILL.director.md

@@ -290,7 +290,7 @@ 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.
 
 - **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 +696,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 +721,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 |