@mevdragon/vidfarm-devcli 0.20.4 → 0.20.5

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 |