@mevdragon/vidfarm-devcli 0.19.0 → 0.19.1

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

@@ -63,7 +63,7 @@ A full worked example is in `references/re-theme-walkthrough.md`.
 
 A heavy scenes-axis replace needs footage. Source it in **cost order**, and be proactive: when a big scene re-work is asked for but no footage is given, offer to hunt a source *before* defaulting to expensive AI generation.
 
-1. **The user's own library** — `browse_files` search/list over `/raws` (footage) and `/files` (durable assets). Free.
+1. **The user's own library** — `browse_files` search/list over `/raws` (footage) and `/files` (durable assets). Free. **You do not need the user to paste a URL.** When they say "use my raws" / "it's in my file directory" / name a clip, `browse_files action=search` (or `list path='/raws'`) to find it, then `action=read` with its `file_id` — the read's **`view_url` IS the public, ready media URL**. Drop that `view_url` straight into `set_layer_media` `src`. Never stall asking for a URL you can look up, and never pass a placeholder `src` like `"please-ignore"`.
 2. **HUNT new raws** out of a long-form source (podcast/VOD/webinar or any YouTube/TikTok/IG/X URL): `POST /clips/scan` (aka `/raws/scan`) with `{ source_url|temp_file_id|s3_key, prompt, aspect, target_duration_sec?, ranges?, avoid_text? }` — async (202 + scan_id), bills **AWS compute only** (the AI tagging runs on the user's own keys, never billed). Then browse `/raws/feed?source=<id>` and reuse the picks (`set_layer_media` in place, `add_layer`/`generate_layer intent:"add"` for net-new scenes).
 3. **`generate_layer` AI generation** — the expensive last resort, only for scenes no real clip can cover. AI *image* gen is cheap (use freely); AI *video* gen is expensive — ask permission / confirm budget first.
 
@@ -115,7 +115,7 @@ You usually already know a clip's aspect from how you sourced it (a hunted raw's
 **Generate & export**
 - `generate_layer` — submit an AI generate job, drop a placeholder in the target slot, auto-swap the finished media (no manual poll). `intent`: `fill_gap` (+ start/duration on a `timeline_gaps` span), `replace_layer` (+ `replace_layer_key` — timing/geometry copied), or `add`. Set `aspect_ratio` to the canvas.
 - **Transparent overlays ("Vox-style") — `POST /api/v1/primitives/images/create-overlay`** via `http_request`. This is the go-to way to mint a floating illustration / prop / icon / cut-out character to animate over the video: one job generates an AI image on a forced flat key-color background and chroma-keys it out to a transparent PNG (`result.primary_file_url`). Body `{ tracer, payload: { prompt, aspect_ratio?, key_color?, prompt_attachments? } }` — describe only the subject (the background instruction is injected for you). Then `add_layer` the finished URL as an overlay image and animate it (`ken_burns`/`set_layer_keyframes`/`set_transitions`). Reach for it *often* when a scene wants a transparent graphic element rather than a full-frame still. Cheap-remove sibling for an image already on a flat background: `POST /api/v1/primitives/images/remove-background-greenscreen` (`key_color`/`tolerance`/`softness`); use RapidAPI `images/remove-background` only for messy-background photos.
-- `export_composition` — same as the Export button; queues the render on AWS Lambda. The MP4 appears as `last_export_url` in a later `editor_context`; never fabricate the URL.
+- `export_composition` — same as the Export button; queues the render on AWS Lambda. The MP4 appears as `last_export_url` in a later `editor_context`; never fabricate the URL. **Confirm first — never auto-render.** Rendering is slow, costs money, and pops a status modal, so by default STOP after an edit, let the user review the live preview, and *ask* ("Happy with the preview? Render the final MP4?") before firing this. Only export unprompted when the user pre-authorized it ("edit and just render it"). A render started, then the user can keep working — multiple renders are tracked in the Viral DNA panel's "N Rendering…" badge and its render-history modal.
 - `fork_composition` — branch a NEW editable copy and open it (only on an explicit user branch/duplicate/"save as" request — see Forking). `fork_from:"current"` keeps all current edits; `fork_from:"default"` starts fresh from the template's original default. Same as the ⋯ menu's **New fork** and `POST /api/v1/compositions/:forkId/fork { from }`.
 
 ## Reading `editor_context` — the fields that matter
@@ -125,7 +125,7 @@ You usually already know a clip's aspect from how you sourced it (a hunted raw's
 - `composition_context` (the viral DNA — read before writing any copy).
 - `editor_harness` (the **style-execution brief** — read before any nontrivial edit; see below).
 - `composition_width`/`_height`/`aspect_ratio` (request matching aspect on generate so media fills the canvas), `composition_duration_seconds`.
-- `layers[]` — each with `layer_key`/`element_id`/`slug`, `track` (= z-index), start/duration/geometry, current `object_fit`/`object_position` (the media's fit framing — read it before re-cropping an aspect-mismatched clip), `transition`/`transition_out`/`ken_burns`/`animation`, and `is_full_canvas`/`is_timeline_proxy` (a proxy renders 100%×100% even if shown tiny — trust the flag on replacement).
+- `layers[]` — each with `layer_key`/`element_id`/`slug`, `kind` (video/image/audio/caption/text), current `src`, `track` (= z-index), start/duration/geometry, current `object_fit`/`object_position` (the media's fit framing — read it before re-cropping an aspect-mismatched clip), `transition`/`transition_out`/`ken_burns`/`animation`, and `is_full_canvas`/`is_timeline_proxy` (a proxy renders 100%×100% even if shown tiny — trust the flag on replacement). **This is the ONLY valid source of layer keys.** To swap a clip's media, copy the EXACT `layer_key` (or `slug`) of the *video/image* layer from here — do not invent a semantic scene name (`growth_examples`, `mistakes_reflection`) unless that exact string is a key/slug in this array, and don't target a scene label/group when you mean the video inside it. If `set_layer_media` returns "No change applied" or "Layer not found", the error lists the real media layers — retry with one of those exact keys, and never report a swap done until the next `editor_context` shows the layer's `src` changed.
 - `timeline_gaps[]` — precomputed blank/black spans; map a user's timestamp to the covering gap.
 - `pending_generations[]` — AI gens still rendering (don't double-fire; report progress; `status:"error"` means it failed).
 - `cast[]` — recurring people for character consistency (use `reference_url` on generate).