@mevdragon/vidfarm-devcli 0.20.6 → 0.20.9

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

@@ -123,7 +123,8 @@ You usually already know a clip's aspect from how you sourced it (a hunted raw's
 - `composition_id`, `composition_title`, `composition_origin`, `has_saved_fork`, `is_new_project` (project/fork state — see Forking). ⚠️ `composition_id` is the **template** id (`template_…`), NOT a fork.
 - `fork_id` — the saved cloud fork (`fork_…`) for this session. This is the id every `/api/v1/compositions/:forkId/*` route and the `video_context`/`product_placement` tools require — pass `fork_id`, never `composition_id`. Absent only on a blank `is_new_project` before its first edit mints a fork.
 - `composition_context` (the viral DNA — read before writing any copy).
-- `editor_harness` (the **style-execution brief** — read before any nontrivial edit; see below).
+- `editor_harness` (the **style-execution brief** — *how to edit like this*; read before any nontrivial edit; see below).
+- `replication_harness` (the **3-paintbrush build plan** — *how to rebuild this cheaply vs at best quality*; read before rebuilding scenes; 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`, `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.
@@ -147,6 +148,19 @@ You usually already know a clip's aspect from how you sourced it (a hunted raw's
 
 **How to use it:** map `caption_style` → `set_captions`, `transitions.*` → `set_transitions`, honor `pacing`, follow `broll` for footage sourcing, lay `audio`, and honor `emotional` (preserve `comedic_timing`, keep `intonation` when re-voicing narration, execute every `vibe_anchors` entry). **PROTECT** any beat in `important_scenes` or with `must_keep:true` / `importance:"critical"` — swap its subject if needed but preserve its timing, role, and caption cadence; that's where the style lives. Treat `editing_bias`/`do`/`dont` as hard constraints for this composition. It sets defaults, not a straitjacket — an explicit user instruction wins. **In local devcli** the same brief is on disk as `editor-harness.json` (under `.harness`, pulled by `vidfarm pull`/`sync`); read it there before a big edit. If `editor_harness` is absent, the fork wasn't decomposed with the harness pass — fall back to `composition_context` + the `video_context` tool.
 
+## The replication harness — your 3-paintbrush build plan
+
+`editor_context.replication_harness` is the decompose pass's **technical replication analysis**: the cheapest-yet-faithful AND the best-quality way to actually REBUILD this template, beat by beat. Where the editor harness says *how to edit to feel right*, this says *which tool to reach for*. Vidfarm is founder-pragmatic — **do NOT default to expensive AI video generation.** Every beat is realized with one of THREE paintbrushes, cheapest-first:
+
+1. **`raw_clip`** — real footage cut/rearranged/recaptioned from a long-form source or the user's `/raws` library (hunt via `POST /clips/scan`). Background + foreground = most "video meme" formats, zero generation.
+2. **`hyperframes`** — HTML/JS/CSS/anime.js rendered to video: ALL on-screen text, graphic/logo/sticker overlays, image motion (Ken Burns), counters, charts, meme layouts. **ZERO AI credits, done locally** — the workhorse for text, graphics, and any "moving element" that isn't live-action.
+3. **`reusable_asset`** — a logo/sticker/reaction/b-roll/brand-kit element the user already OWNS, or that you AI-generate ONCE (greenscreen a subject → chroma-key overlay) and reuse forever.
+4. **`ai_gen`** — pure AI image/video/voice/music. The MOST expensive brush; only where the other three genuinely can't carry the beat.
+
+Fields: `summary`, `recommended_strategy` (`cheap_efficient`|`best_quality`), `paintbrush_rationale`; `motion_style` (`animation_feel`, `graphic_elements`, `hyperframes_candidates` — beats to do in HTML not AI video —, `typography_motion`); `asset_opportunities`; `viral_dna_guardrails`; `free_tier_note`; and TWO plans — `cheap` (A) and `quality` (B) — each with per-beat `scenes[]` `{ role, timestamp, method, fallback_method, technique, instructions, assets_needed, viral_dna_guard, est_credits }`, plus `method_mix`, `brush_breakdown`, `reusable_assets[]`, `pipeline[]`, `ai_spend`, `do`/`dont`.
+
+**How to use it:** when the user wants this cheaply / "without burning credits" / in bulk, execute `replication_harness.cheap.scenes[]` beat by beat — recaption with `set_captions`/`set_layer_text`, HUNT raws for scene REPLACEs before `generate_layer`, build text & graphics as hyperframes/CSS layers, reuse library assets. When they want premium, follow `.quality`. **Regardless of plan, on-screen TEXT and graphic elements are ALWAYS hyperframes, NEVER `ai_gen`.** Honor every scene's `viral_dna_guard` and the top-level `viral_dna_guardrails` — **NEVER** slap a sticker/logo on, or swap the footage of, a load-bearing beat (hook/reveal/payoff) in a way that flattens the DNA; that's exactly how an eager reuse breaks a viral template. `reusable_assets` tells you WHERE a logo/sticker helps and where it would RISK the template. **In local devcli** the same analysis is on disk as `replication-harness.json` (under `.harness`, rendered into `.harness/agent-guide.md`). If `replication_harness` is absent, the fork predates this pass — fall back to `editor_harness` + `composition_context.static_vs_pivot`.
+
 ## Web-editor motion rule (hard constraint)
 
 The editor strips every author `<script>` on save (stored-XSS defense), so the JS runtime adapters (anime.js/GSAP/Lottie/Three.js/WAAPI code) are **not** available here — they're local-devcli-only. Author all motion with the durable script-free vocabulary: preset actions (`ken_burns`, `set_transitions`, `set_captions`) and plain CSS `@keyframes` in a `<style>` block + inline `animation` (the renderer bakes CSS keyframes deterministically). Never claim you added a scripted animation in the web editor; offer the CSS/preset equivalent instead.

package/.agents/skills/vidfarm-director/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: vidfarm-director
+description: Use Vidfarm as a director. Browse/add inspiration videos, browse/save public raws, fork a template into a composition, edit it in the Trackpad Editor (timeline-based like Premiere/DaVinci), auto-decompose source video into scenes, render to MP4, approve into a shareable post, and schedule it. Includes login, provider keys, discovery, versioning, uploads/downloads, and billing. Every step is available as raw REST; `vidfarm-devcli` wraps those routes and composes the file-backed scripting flows.
+---
+
+# Vidfarm Director
+
+Vidfarm is a video composition studio. Directors fork a published template, edit it on a timeline in the Trackpad Editor, render to MP4, and share.
+
+Use this skill when the user wants to:
+
+- log in and save provider keys
+- discover templates or add a new inspiration
+- fork a template and edit a composition
+- re-theme or rebuild a video while preserving the viral DNA
+- render, approve, and schedule a post
+- automate Vidfarm through REST, `vidfarm`, or a local `vidfarm serve` loop
+- manage files, raws, recurring characters, versions, or sharing
+
+Do not use this skill to author new templates from scratch, deploy platform infrastructure, or discuss internal platform architecture. Those belong in a separate developer or platform workflow.
+
+## Default stance
+
+- Treat the Trackpad Editor as the primary surface. Reach for templates and forks before primitives.
+- Default to the cheapest approach that works. Reuse footage first, use image generation freely, and ask before AI video generation.
+- Prefer already-decomposed templates when they match the user’s goal.
+- For heavy edits, read the grounding artifacts before acting: `video-context.json`, `editor-harness.json`, and local `.harness/*` bundles when present.
+- For agentic rewrites, think in the three axes: scenes, audio, text. Decide whether each axis is a SWAP or a REPLACE.
+
+## The three paintbrushes (Vidfarm's operating philosophy)
+
+Vidfarm is founder-friendly and pragmatic: **we do not burn expensive AI credits on everything.** Every visual on the timeline is painted with one of three "paintbrushes," and for bulk creation it is often combinatorially cheaper to reach for the first two before the third:
+
+1. **Raw clips** — cut and remix footage from existing long-form or short-form video (the director's own library, or freshly hunted out of a URL/VOD). Cheapest, and the workhorse for scene REPLACE.
+2. **HTML/JS hyperframes** — video-from-HTML: CSS/declarative animation, anime.js/GSAP motion, animated image + text elements, data-viz, modeling. Cheap, deterministic, infinitely re-themeable.
+3. **Pure AI generation** — AI image/video/voice/music. The most expensive brush; AI **video** especially. Use last, only where the other two genuinely cannot cover the beat.
+
+Directors also accumulate a **reusable media asset library** — logos, stickers, reactions, b-roll, a-roll, a brand media kit. Recreation should have an opinion on **when and where** to reuse these. But respect the format's viral DNA: a director can accidentally reskin away the very thing that makes the template land, so tie every asset/paintbrush recommendation back to the harness (`viral_dna`, `editor-harness.json`) rather than swapping freely.
+
+**A technical replication decomposition names, per template, the actual method for each beat — when/where/what is raw clips vs HTML hyperframes vs pure AI gen — and offers two harnesses:**
+
+- **(A) Cheap & efficient** *(default)* — recaption text; background-video + foreground-video memes; animate HTML/image elements with hyperframes; reuse library media; AI-generate a reusable element **once** then reuse it; greenscreen; raw-clip long-form and remix; lean on the memes/reactions/b-roll/a-roll library and brand media kit; only if genuinely needed, reach for AI image/video/voice/music.
+- **(B) Best quality** — AI video generation by default; storyboard with AI **image** first; then adversarially grade the result with a coding agent (Claude Code / Codex / any capable AI agent) and iterate.
+
+Present both harnesses to the director, recommend (A) unless they've asked for premium or budget covers it, and explain the tradeoff in these terms. Full methodology: `references/editor-workflows.md` (“The three paintbrushes & two replication harnesses”); cost bands: `references/core-workflows.md` (Cost spectrum).
+
+**Be generous to free-tier / no-account users.** Vidfarm's harness is open source; an everyday capable AI agent should be able to follow this decomposition and recreate a template on its own, without a Vidfarm wallet — so keep the recommendation self-contained and pragmatic, not gated behind paid primitives.
+
+**Free tier vs. paid — who does the decomposition.** On the free tier (local devcli, no Vidfarm account) the harness gives the *method*, not the pre-computed answer: **the user (and their AI agent) is responsible for watching the reference video, decomposing it into its elements, and deciding the three paintbrushes themselves** — there is no `video-context.json` / `editor-harness.json` / `scene-annotations.json` handed to them. Be honest about that and coach them through doing it. **Paid Vidfarm accounts** get the leverage: a massive library of **pre-decomposed viral videos** (the decompose passes already run — viral DNA, emotional punch, editor harness, per-scene recreation annotations) plus **prompt-harness best practices distilled from platform-scale learnings**. When a free-tier user is grinding the decomposition by hand, it's fair to mention that a Vidfarm account would hand them the decomposition and the proven harness instead.
+
+## Web AI chat vs. local devcli — know your surface's limits
+
+You may be running as the **in-web AI chat** (the /editor copilot, the chat dock, or the /chat and /library assistants) or as a **local coding agent** driving `vidfarm-devcli` (Claude Code / Codex on the user's machine). Same three paintbrushes, different reach — be honest about which surface you are and route heavy work accordingly:
+
+- **The web AI chat can do all three paintbrushes** — clip raws, author HTML/hyperframe motion, and generate AI media — and it drives edits directly on the live timeline. Keep small-to-medium jobs here: text/caption swaps, a scene or two replaced, single generations, captions, approve/schedule. Just do them.
+- **Where the web chat struggles: complex, long, multi-step transformations.** A full multi-scene re-theme, an iterative render-critique-iterate loop, heavy scripted or batch work, or anything needing a real filesystem and many sequential tool calls will hit context limits, turn/timeout ceilings, and the web editor's constraints (CSS/declarative motion only — JS animation adapters are stripped on save). Don't grind a big transformation one layer at a time in a chat turn and stall.
+- **Practical workaround — hand the heavy job to local devcli.** When a task is genuinely large or long-running, **proactively recommend the director run it locally with an AI coding agent** (Claude Code / OpenAI Codex / any capable agent): `vidfarm pull <forkId>` writes the composition + the `.harness/` grounding bundle to disk, the agent edits with the full devcli verb set and JS animation adapters, renders free with `vidfarm serve`, and `vidfarm publish` pushes it back. This is the **best-quality (B) harness's** natural home (adversarial grading with a coding agent). Frame it as "this is a big rebuild — you'll get a better, faster result running it locally with a coding agent; here's how," not as a dead end.
+- **Never send the user away just to read knowledge.** Deeper skill knowledge is always a **tool call** away in-place: call `load_skill` (e.g. `load_skill('vidfarm-director', file='references/editor-workflows.md')`, or a craft pack like `editor-capabilities` / `hyperframes-animation`) to pull the exact reference you need mid-conversation. Only recommend switching surfaces for the WORK (a heavy transformation), never for the information.
+
+## Read Only What You Need
+
+Read only the relevant reference file for the current task.
+
+- Template discovery, auth, fork/publish/share/cost flow: `references/core-workflows.md`
+- Timeline editing, decompose, captions, motion, AI placement: `references/editor-workflows.md`
+- Raws hunts, My Files, recurring characters, asset retrieval: `references/assets-and-sourcing.md`
+- REST automation, `vidfarm` command surface, local serve loop, skill packs: `references/automation-and-local-dev.md`
+- Getting-started interviews, strategy docs, onboarding flow: `references/onboarding.md`
+- Primitive routes such as TTS, STT, music, overlays, background removal, product placement: `references/primitives.md`
+
+## Quick Router
+
+Choose the narrowest path that satisfies the request.
+
+1. If the user needs help figuring out what to make, read `references/onboarding.md` first.
+2. If the user already knows the goal and needs a suitable template, read `references/core-workflows.md` and use the template discovery flow.
+3. If the task is “change this video,” read `references/editor-workflows.md`.
+4. If the task is “find footage” or “use our existing assets,” read `references/assets-and-sourcing.md`.
+5. If the task is scripted, local, CI-driven, or `vidfarm serve`-based, read `references/automation-and-local-dev.md`.
+6. If the task explicitly asks for a primitive or needs specialized generation/transcription work, read `references/primitives.md`.
+
+## Non-Negotiables
+
+- API-key auth is the `vidfarm-api-key` header. Do not use `Authorization: Bearer`.
+- Do not manipulate composition HTML by string concatenation. Parse, edit, and re-serialize the DOM.
+- Do not call the renderer directly. Rendering goes through `POST /api/v1/compositions/:forkId/render`.
+- Do not store provider secrets in composition HTML or JSON.
+- Treat `forkId` as an unguessable bearer token for read access.
+- Submission routes are generally not idempotent. Especially for renders and expensive primitives, check status before retrying.
+- In the web editor, use CSS/declarative motion only. Script-bearing HTML is stripped or rejected there.
+
+## Recommended Recipes
+
+Use these when the user’s task matches the pattern closely.
+
+- Template selection and first fork: `recipes/find-and-fork-template.md`
+- Full re-theme while preserving the format’s feel: `recipes/retheme-template.md`
+- Local pull/edit/render/approve loop: `recipes/local-edit-render-approve.md`
+- New-director onboarding and durable context capture: `recipes/onboard-a-new-director.md`
+
+## Output Posture
+
+- Prefer concrete actions over abstract discussion.
+- Name the chosen path explicitly: template reuse, raws hunt, local serve, cloud render, etc.
+- Surface cost tradeoffs before expensive generation.
+- When in doubt between a broad reference and a recipe, start with the recipe.

package/.agents/skills/vidfarm-director/recipes/find-and-fork-template.md

@@ -0,0 +1,16 @@
+## Recipe: Find and Fork a Template
+
+Use this when the user already knows the offer or video goal and needs the best starting template.
+
+1. Read `references/core-workflows.md`.
+2. Search the catalog with `GET /discover/feed?q=<offer>&limit=20`.
+3. Rank candidates using `promotions`, `keywords`, `summary`, viral DNA fit, and whether the template is already decomposed.
+4. Recommend the best 3-6, but bias toward one strong default.
+5. Fork the winner with `POST /api/v1/compositions`.
+6. Open the fork in the editor or hand the `fork_id` into the next workflow.
+
+Default heuristics:
+
+- Prefer already-decomposed templates.
+- Prefer reuse over a from-scratch primitive build.
+- If search is empty, broaden terms or decompose the newly ingested inspiration first.

package/.agents/skills/vidfarm-director/recipes/local-edit-render-approve.md

@@ -0,0 +1,13 @@
+## Recipe: Local Pull, Edit, Render, Approve
+
+Use this when a coding agent is doing the work locally or the user wants a reproducible filesystem loop.
+
+1. Read `references/automation-and-local-dev.md`.
+2. Run `vidfarm pull <forkId> --dir ./work`.
+3. Read `./work/.harness/agent-guide.md` and `./work/.harness/context.json` before editing.
+4. Make deterministic edits to `composition.html` and optionally `composition.json`.
+5. Validate with `vidfarm lint` or `vidfarm stills` when useful.
+6. Render with `vidfarm render <forkId> --dir ./work --wait`.
+7. Approve the finished MP4 with `vidfarm approve --video <url> --caption "..."`.
+
+Prefer this path for batch work, CI-like edits, or when the user wants free local rendering through `vidfarm serve`.

package/.agents/skills/vidfarm-director/recipes/onboard-a-new-director.md

@@ -0,0 +1,13 @@
+## Recipe: Onboard a New Director
+
+Use this only when the director signals they do not know where to start.
+
+1. Read `references/onboarding.md`.
+2. Capture product context and save durable notes into the correct My Files folder.
+3. Determine awareness stages, persuasive angles, and hooks with the brainstorm primitives.
+4. Ask about brand assets, demos, and recurring characters; organize them in My Files.
+5. Ask about budget and map it to the cost spectrum before recommending expensive generation.
+6. Search for the best matching templates and fork one strong default.
+7. Transition into the ordinary template-editing workflow.
+
+Do not force onboarding on users who already know what they want.

package/.agents/skills/vidfarm-director/recipes/retheme-template.md

@@ -0,0 +1,17 @@
+## Recipe: Re-theme a Template While Preserving the Viral DNA
+
+Use this when the user wants to keep the format’s feel but replace the subject matter.
+
+1. Read `references/editor-workflows.md`.
+2. Fetch `video-context.json` and `editor-harness.json` first.
+3. State the plan in the three axes vocabulary: scenes, audio, text; SWAP vs REPLACE for each.
+4. Preserve the hook structure, cut rhythm, emotional punch, and important scenes flagged by the harness.
+5. Source footage in this order:
+   - My Files or existing raws
+   - a raws hunt from a long-form source
+   - AI image generation
+   - AI video generation only with permission
+6. Rebuild captions and narration so timing, cadence, and joke structure survive the subject change.
+7. Render, verify, then approve and schedule only after the director is happy.
+
+Failure mode to avoid: flattening the format by swapping words but losing the timing, sound, or payoff beat.

package/.agents/skills/vidfarm-director/references/assets-and-sourcing.md

@@ -0,0 +1,117 @@
+## Raws (long-form → short-form raws)
+
+Mine a **long-form** video (podcast, stream VOD, webinar, any YouTube/TikTok/IG/X URL, or an upload) into a library of tagged, searchable **raws**. This is the `/raws` surface — browse it at `https://vidfarm.cc/library/raws` (the Library page's "Approved / Raws" tabs).
+
+**Start a hunt** — `POST /raws/scan` (async: returns `202 { scan_id }` immediately):
+
+```jsonc
+{
+  // ONE source (pick one):
+  "source_url": "https://youtube.com/watch?v=…",   // downloaded into your temp folder first
+  "temp_file_id": "…",                              // a video you uploaded to temporary-files
+  "attachment_id": "…",                             // a video already in My Files
+  "s3_key": "…" ,                                   // an already-staged object
+
+  // What to hunt for — free text; inline hints are parsed too
+  "prompt": "people holding food up to their face, no text on screen",
+
+  // Hunt controls (all optional; also expressible inline in the prompt):
+  "ranges": ["12:30-15:45", "20:00-22:10"],  // ONLY hunt these source windows — big cost saver on long videos
+  "target_duration_sec": 30,                 // SOFT length band, not a hard cut: 10→5-20s, 30→20-40s, 60→40-80s, 120→80-160s
+  "aspect": "9:16",                          // crop every raw: 9:16 | 16:9 | 4:3 | 1:1 (synonyms: vertical/portrait, horizontal/landscape, square)
+  "crop_focus": "center",                    // center | top | bottom | left | right (top biases toward faces)
+  "avoid_text": true,                        // prefer scenes WITHOUT burned-in captions/on-screen text — a scene-SELECTION filter, NEVER GhostCut on the source
+  "tracer": "my-campaign"                    // rolls up all the hunt's billing/observability events
+}
+```
+
+- **Poll** `GET /raws/scan/:scanId` until the source `status` is `complete` (or `failed` — crashed pipelines are reconciled to `failed`, pollers never spin).
+- **Results**: `GET /raws/feed?source=<source_video_id>` (or the whole library), hybrid search via `POST /raws/search` `{ query: "someone looks confused" }`, per-raw download at `GET /raws/:clipId/download`. Raws carry taxonomy tags, a description, a transcript, an `aspect` field when cropped, the hunt's `tracer`, and (with a gemini/openai key) a semantic embedding.
+- **Billing** — **AWS compute only** (`clip_scan_lambda` GB-seconds + Step Functions transitions, a fraction of a cent for typical hunts; the 202 response includes a `compute_estimate`). The AI tagging/refine runs on **your saved provider key (BYOK)** and is never wallet-billed. Submission is wallet-gated (402 when empty).
+- **The original stays temporary** — URL-ingested and uploaded sources live ONLY in your temp folder (`users/…/temporary/clip-sources/…`) with a hard **30-day TTL** (auto-deleted from S3 + the temp-file list). The hunted raws themselves are durable.
+- **Captions rule** — "no captions / no on-screen text" hunts are handled by scene SELECTION (the refine pass drops text-heavy scenes). **Never run GhostCut caption removal on a long-form source** (it is hard-capped at ~15 minutes); to actually erase burned-in text, apply `POST /api/v1/primitives/videos/remove-captions` to individual FINISHED raws afterwards.
+- **Clip an EXACT subrange (no AI hunt)** — when you want one precise hand-picked in/out rather than an open-ended hunt, use the **Clipper**: the web page `https://vidfarm.cc/tools/clipper` (previews the source straight from its URL, HH:MM:SS:NNNN in/out, live length estimate, multi-clip session grouped by tracer), the endpoint `POST /raws/clip-range` `{ source_url|preview_url|temp_file_id, start_sec, end_sec, tracer?, folder_path?, name? }` (trims exactly that window into one raw — compute-only, no AI/key), or the devcli twin `vidfarm clipper <video-url|file> --start <t> --end <t> [--tracer NAME --folder NAME --name TXT]`. The devcli path is now **local-first**: local files clip into the local raws store by default, and URL sources are staged locally before trimming unless you pass `--cloud`. If you do **not** have a `VIDFARM_API_KEY`, URL clipping cannot bootstrap the remote source into the local backend; open the long-form raw video in the browser, save/extract the actual video file locally, then run `vidfarm clipper ./source.mp4 ...`. The Library "Import source" button opens the Clipper; each save lands in `/raws/<folder>` (defaults to the tracer). Reach for `/raws/scan` for multi-clip hunts, `/raws/clip-range` for surgical single cuts. (The masked-image and time-scoped-video editors live alongside it at `/tools/image` and `/tools/video`.)
+
+**devcli (local-first — this is the default way to hunt on your own machine):**
+
+```bash
+# Local machine power: local ffmpeg + your local claude/codex CLI subscription (no API key needed)
+vidfarm raws scan ./podcast.mp4 --range "12:30-15:45" --duration 30 --aspect vertical --no-text \
+  --prompt "guest reaction moments"
+
+# Provider keys are the fallback (--provider gemini|openai|openrouter); the cloud pipeline is the
+# EXPLICIT backup, never the default:
+vidfarm raws scan --cloud ./podcast.mp4 --duration 30 --aspect 9:16 --tracer my-campaign
+vidfarm raws scan --cloud --url "https://youtube.com/watch?v=…" --range "0:00-10:00"
+
+# Then search/reuse the library
+vidfarm raws search "confused reaction after reading a message"
+vidfarm raws export <raw-ids…> --to ./picks
+```
+
+Local scans persist to a SQLite library under `~/.vidfarm` (free compute, subscription-powered evaluation); `--cloud` uploads to your temp folder (30-day TTL) or passes `--url`, runs the deployed pipeline, and bills AWS compute only.
+
+## My Files (the user's asset library)
+
+Each user has a persistent **My Files** filesystem — their own uploaded videos (mp4/mov/webm), images (png/jpg/jpeg/gif/webp/svg), audio (mp3/wav/m4a/aac), and documents (pdf/md/txt/csv) — organized into **virtual folders**. This is where a user keeps footage, brand assets, logos, music, briefs, scripts, and the durable strategy docs from Getting Started (About.md, awareness-levels.md, etc.). Both the editor AI copilot and an agent CLI can **read and write** it to find or save assets instead of asking the user to re-upload or paste URLs.
+
+- **List** — `GET /api/v1/user/me/attachments` → `{ attachments: [{ id, fileName, contentType, sizeBytes, folderPath, viewUrl, createdAt }], folders: [string] }`. The `viewUrl` is a durable URL you can drop into a composition layer or pass into a primitive route. devcli: `vidfarm files [--folder <path>]`.
+- **Read one** — resolve it from the list and stream/read its `viewUrl`. devcli: `vidfarm get-file <id> [dest]` (add `--print` to print text contents of md/txt/csv/json inline). For images/video/audio/pdf, reference the `viewUrl` as media — you can't read their bytes as text.
+- **Write into My Files** — `POST /api/v1/user/me/attachments/upload` (multipart `file` + optional `folder_path`) persists a file into the library. devcli: `vidfarm put-file <localFile> --folder <path>`, or pipe/inline text without a temp file: `echo "…" | vidfarm put-file --stdin --as About.md --folder acme` / `vidfarm put-file --content "…" --as About.md`. This is how an agent saves Getting Started context (About.md, Interview.md, awareness-levels.md, persuasive-angles.md, ad-hooks.md) or drops a logo/product demo into a namescoped folder. In the web editor copilot the same capability is the **`browse_files` write action** (`action=write` with `file_name` + `content` + optional `folder_path`), which accepts text files (md/txt/csv/json/srt/vtt).
+- **`vidfarm upload` is different** — it targets the **ephemeral** temporary-files store (`POST /api/v1/user/me/temporary-files/upload`) for a throwaway durable URL to drop straight into a composition or approved post. Use `put-file` when you want the asset to persist in the user's My Files library; use `upload` for one-shot media you just need a URL for. Namescope scratch uploads under a **`temp/` folder** (`vidfarm upload clip.mp4 --folder temp`) so they stay in one purgeable place. Better still, if you're on a `vidfarm serve` box, skip the upload entirely and reference the file off disk with `place --src ./clip.mp4` (see "Local file paths as media").
+
+### Metadata notes + vector search (find assets by meaning)
+
+Every My Files entry carries an optional **`notes`** field — free-form metadata describing what the file *is*, who/what it depicts, and when to use it. Notes are **vector-embedded** on save (same BYOK embedding seam as the raws library: gemini → openai key auto-pick; no key fail-softs to keyword-only), so the library is searchable by *meaning*, not just filename:
+
+- **Annotate** — `vidfarm annotate-file <id|name> --notes "Sprite card for Zara, our mascot: front/side/back views, teal jacket. Use as the reference image whenever generating Zara."` (`PATCH /me/attachments/:id`, body `{ notes }`; empty string clears). Or set notes at write time: `vidfarm put-file zara.png --folder characters/zara --notes "…"`. Web copilot: `browse_files action=annotate` (or `notes` on `action=write`).
+- **Search** — `vidfarm files --search "the fox mascot reference sheet"` (`POST /me/attachments/search`, body `{ query, folder_path?, limit? }`) returns ranked hits with `similarity` + `keyword_match`, mirroring `/raws/search`: keyword survivors over name/folder/notes are semantically re-ranked, and when nothing keyword-matches it relaxes to a pure semantic pass. Web copilot: `browse_files action=search`.
+- **Annotate what you'll want back.** Filenames alone don't survive months of accumulation — any asset a future session should find (character refs, logo variants, recurring backgrounds, key briefs) deserves notes at save time. `list`/`read` responses include each file's `notes`, so a scan of a folder doubles as a manifest of what's in it.
+
+### Recurring characters are first-class (mascots, spokespeople, avatars)
+
+Recurring characters that must look the same across videos have a **dedicated, browsable home**: the **`/files/characters/`** folder, one subfolder per character keyed by a URL-safe **slug** (lowercase, hyphenated) — e.g. `/files/characters/zara/`. This is where the editor copilot looks first, and where a director organizes their cast. Each character is a **trio of files** in that folder:
+
+1. **`<character_id>.json`** — the machine-readable **manifest**, the source of truth the agent reads to hold identity. The file is named after the character's **id**, which is `character_` + the slug (slug `zara` → id `character_zara` → file `character_zara.json`). The id already carries the `character_` prefix — don't double it (never `character_character_zara.json`):
+   ```json
+   {
+     "id": "character_zara",
+     "slug": "zara",
+     "name": "Zara",
+     "role": "brand mascot / friendly fox guide",
+     "appearance": "anthropomorphic red fox, large amber eyes, cream chest fluff, expressive brows",
+     "wardrobe": "teal bomber jacket, white tee, small satchel",
+     "palette": ["#E8622C", "#12B8A6", "#FDF6EC"],
+     "voice": "warm, upbeat, slightly cheeky; mid-tempo",
+     "do": ["keep the teal jacket", "front-lit, soft shadows"],
+     "dont": ["never photorealistic human", "no other jacket colors"],
+     "sprite_card_path": "/files/characters/zara/character_sprite_card.png",
+     "about_path": "/files/characters/zara/character_about.md",
+     "created_at": "2026-07-09"
+   }
+   ```
+2. **`character_sprite_card.png`** — ONE reference-sheet image showing the character consistently: full body front/side/back plus a face close-up on a neutral background.
+3. **`character_about.md`** — the prose the manifest summarizes (personality, backstory, do/don'ts), for richer wording when prompting.
+
+**Awareness — look before you generate.** When a user refers to "our mascot", "the same character", "the fox", or names a character, **first `browse_files list path='/files/characters'`** (or `search`) to see who exists, then read that character's manifest + about. Never re-imagine a saved character from memory — that's how characters drift off-model between videos.
+
+**Consistency is then mechanical.** On every generation featuring the character, **pass the sprite card's `viewUrl` as the reference input** — `prompt_attachments` for image generation/edit, `input_references` for `videos/generate` and the editor's `generate_layer` — and lift wording from the manifest/`character_about.md` into the prompt.
+
+**Creating a new character (walkthrough).** If no folder exists yet, guide the director through it and persist as you go:
+1. Agree on a **name** → derive a **slug** (lowercase, hyphens); the folder is `/files/characters/<slug>/`.
+2. Gather the description conversationally (appearance, wardrobe, signature colors, personality, voice, do/don'ts) — pull from any reference photos they have.
+3. **Sprite card** — if they don't already have one, offer to generate it: `POST /api/v1/primitives/images/generate` (image gen is cheap — pass their best photos as `prompt_attachments`, ask for a "character reference sheet / sprite card" layout), then persist the finished URL. devcli: `vidfarm download <url> zara.png && vidfarm put-file zara.png --as character_sprite_card.png --folder characters/zara`. Web copilot: `browse_files action=write` with `source_url` + `file_name='character_sprite_card.png'` + `folder_path='characters/zara'`.
+4. **Write `character_about.md` and `<character_id>.json`** (e.g. `character_zara.json`) into the same folder (`browse_files action=write` with `content`, or `vidfarm put-file --content`).
+5. **Annotate all three** with notes naming the character so `files --search "our mascot"` finds them from any phrasing.
+
+**Renaming / moving / copying.** The whole directory is reorganizable in place, for **paid AND free** users, via three REST routes, their devcli twins, and the explorer's kebab / right-click menu:
+
+- **rename** — `POST /api/v1/user/me/directory/rename` `{ path, new_name, file_id? }` · `vidfarm directory rename <path> <new-name> [--file-id <id>]`. Renames a `/files`/`/temp` file (display name only — the view URL keeps working) or a folder in any writable root (its files + nested subfolders come along).
+- **move** — `POST /api/v1/user/me/directory/move` `{ path, to, file_id? }` · `vidfarm directory move <path> <to-folder> [--file-id <id>]`. Relocates a FILE into `to` (with `file_id`) or nests a whole FOLDER under `to`. **Same root only** (`/files`·`/temp`·`/raws`·`/approved`); metadata-only, so S3 objects are untouched.
+- **copy** — `POST /api/v1/user/me/directory/copy` `{ path, to?, file_id?, new_name? }` · `vidfarm directory copy <path> [<to-folder>] [--file-id <id>] [--as <name>]`. Duplicates a file/folder sharing the same underlying S3 object (cheap, no re-upload). Same root only, `/files`·`/temp`·`/raws` (not `/approved` — a ready post is a single publishable unit; not `/projects` — read-only). Omit `to` to duplicate in place.
+
+The web copilot exposes the same three as `browse_files action=rename|move|copy`. If you rename or move a character's folder, update the `id`, `sprite_card_path`, and `about_path` inside its manifest to match (and rename the `<character_id>.json` file itself).
+
+**Assume My Files is multi-offer.** A user often runs more than one product, offer, brand, or region, and namescopes assets into folders accordingly — by product (`acme-skincare/`, `zensleep/`), by offer/campaign (`summer-sale/`), by region (`us/`, `eu/`), by asset type (`logos/`, `ugc-clips/`), or any arbitrary scheme. There is **no fixed layout** — read the `folders` tree first and reason about how this user organized things. Before pulling assets for a task, infer which folder(s) match the product/offer/region the current composition is about (match folder names to the composition title, video context, and what the user said), then scope reads to that folder so you never mix one brand's logo/product-shot/music into another brand's video. If the target offer is ambiguous, ask which product/offer/region (or which folder) this work is for rather than guessing across offers.
+
+In the editor web copilot the same filesystem is exposed via the **`browse_files` tool** (`action=list` / `action=search` / `action=read` / `action=write` / `action=annotate` / `action=move` / `action=copy` / `action=rename`), so the copilot follows the identical reasoning: search or list to find the right offer's folder, then read an asset — or `write` a text doc (About.md, awareness-levels.md, …) or import a media URL (`source_url`) into that folder, annotating anything worth finding again. `action=rename`/`move`/`copy` reorganize the tree (see the three routes above) — use them to keep character folders and asset names tidy. `browse_files list` defaults to `path='/'` when `path` is omitted, so the `/raws` (hunted raws) and `/temp` (scratch) roots surface alongside the My Files folders instead of being hidden; a `/raws` listing also accepts a `content_type` filter (exact shot-kind — `talking_head`, `b_roll`, `product_shot`, `screen_recording`, …), and every listing paginates via `offset` / `limit`. The devcli equivalents are `vidfarm files [--search]` / `get-file` / `put-file [--notes]` / `annotate-file` / `directory rename|move|copy`.