@officexapp/vidfarm-devcli 0.21.10

package/.agents/skills/text-to-speech/references/voice-settings.md

@@ -0,0 +1,115 @@
+# Voice Settings
+
+Fine-tune voice characteristics for your use case.
+
+## Parameters
+
+| Parameter | Range | Default | Description |
+|-----------|-------|---------|-------------|
+| `stability` | 0.0 - 1.0 | 0.5 | How consistent the voice sounds across the generation. Lower = more emotional variation and expressiveness (but can sound erratic). Higher = steady, predictable tone. |
+| `similarity_boost` | 0.0 - 1.0 | 0.75 | How closely to match the original voice sample. Higher sounds more like the source voice but may amplify audio artifacts or background noise from the original recording. |
+| `style` | 0.0 - 1.0 | 0.0 | Exaggerates the unique characteristics of the voice's speaking style (v2+ and v3 models only). Higher values make the voice more "characterful" but can reduce stability. |
+| `speed` | 0.25 - 4.0 | 1.0 | Speech speed multiplier. 1.0 = normal speed. Range is 0.25-4.0 for the REST API; the Agents Platform restricts to 0.7-1.2. |
+| `use_speaker_boost` | boolean | true | Post-processing that enhances voice clarity and similarity to the original. Generally leave this on unless you're experiencing artifacts. |
+
+## Python Example
+
+```python
+from elevenlabs import ElevenLabs
+from elevenlabs import VoiceSettings
+
+client = ElevenLabs()
+
+audio = client.text_to_speech.convert(
+    text="Testing different voice settings.",
+    voice_id="JBFqnCBsd6RMkjVDRZzb",
+    model_id="eleven_v3",
+    voice_settings=VoiceSettings(
+        stability=0.5,
+        similarity_boost=0.75,
+        style=0.0,
+        use_speaker_boost=True
+    )
+)
+```
+
+## JavaScript Example
+
+```javascript
+const audio = await client.textToSpeech.convert("JBFqnCBsd6RMkjVDRZzb", {
+  text: "Testing different voice settings.",
+  modelId: "eleven_v3",
+  voiceSettings: {
+    stability: 0.5,
+    similarityBoost: 0.75,
+    style: 0.0,
+    useSpeakerBoost: true,
+  },
+});
+```
+
+## cURL Example
+
+```bash
+curl -X POST "https://api.elevenlabs.io/v1/text-to-speech/JBFqnCBsd6RMkjVDRZzb" \
+  -H "xi-api-key: $ELEVENLABS_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "text": "Testing different voice settings.",
+    "model_id": "eleven_v3",
+    "voice_settings": {
+      "stability": 0.5,
+      "similarity_boost": 0.75,
+      "style": 0.0,
+      "use_speaker_boost": true
+    }
+  }' \
+  --output output.mp3
+```
+
+## Use Case Recommendations
+
+### Audiobooks / Narration
+```python
+voice_settings=VoiceSettings(
+    stability=0.7,        # Consistent tone
+    similarity_boost=0.5, # Natural variation
+    style=0.0
+)
+```
+
+### Conversational / Chatbots
+```python
+voice_settings=VoiceSettings(
+    stability=0.4,        # More expressive
+    similarity_boost=0.75,
+    style=0.3             # Slight style emphasis
+)
+```
+
+### News / Professional
+```python
+voice_settings=VoiceSettings(
+    stability=0.8,        # Very consistent
+    similarity_boost=0.6,
+    style=0.0
+)
+```
+
+### Character Voices / Drama
+```python
+voice_settings=VoiceSettings(
+    stability=0.3,        # Highly expressive
+    similarity_boost=0.8,
+    style=0.5             # Strong style
+)
+```
+
+## Tips
+
+- **Start with defaults** and adjust incrementally
+- **Lower stability** if voice sounds monotonous
+- **Reduce similarity_boost** if you hear audio artifacts
+- **Style works** with v2+, v3, and multilingual models
+- **Test with representative text** from your actual use case
+- **Flash models** ignore some voice settings for speed

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

@@ -0,0 +1,179 @@
+---
+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.
+
+## Quickstart (desktop agents — do this first)
+
+The CLI is `vidfarm`, from the npm package `@officexapp/vidfarm-devcli`. Install and authenticate before anything else:
+
+```bash
+npm install -g @officexapp/vidfarm-devcli    # installs the `vidfarm` command
+vidfarm login --api-key vf_key_...          # validates + persists the key durably
+vidfarm serve template_<32hex>              # local server + browser, opens that template
+```
+
+- The API key comes from https://vidfarm.cc/settings and starts with `vf_key_`. Instead of `login`, setting the `VIDFARM_API_KEY` environment variable also works for every command — the CLI reads it from the environment or from a `.env` file in the current directory.
+- No account or key? `vidfarm serve --no-cloud` still gives a fully local editor with free local renders.
+- "Open/run template X locally" is exactly one command: `vidfarm serve <template_id>` (alias: `vidfarm <template_id>`). Do not hand-roll REST or hunt for local `.harness/` files first — `serve` and `pull` create those.
+
+### Entity ID formats
+
+Every Vidfarm id is a type prefix + 32 hex characters (`prefix_<32hex>`). There are no short slugs and no `tpl_` prefix.
+
+| Prefix | What it is | Typical use |
+|---|---|---|
+| `template_` | published template | `vidfarm serve template_<32hex>`, fork it |
+| `fork_` | your editable composition | `vidfarm pull fork_<32hex>`, edit, render |
+| `inspiration_` | imported source video | discovery, decompose |
+| `raw_` / `clip_` | raw footage / cut clip | timeline media, raws library |
+
+All of these are accepted verbatim by the feed search bars and exact-id API lookups. Never second-guess or "correct" a user-provided id because of its shape.
+
+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.
+
+## Cost mode — ask before you spend, then remember it
+
+Vidfarm work can burn real AI credits on the user's wallet / provider keys. **Save them money by default.** Before the first billed step of a session, ask the user which spend posture they want, and explain it in one plain line each:
+
+- **minimize** — cheapest. Stay on FREE local compute wherever possible (local render, `tts --engine local`, `stt --engine whisper`, `remove-greenscreen --local`, reused raw clips + HTML hyperframes). No surprise AI spend.
+- **hybrid** *(recommend this)* — free where it's free; pay for AI only where it clearly wins (a hero shot, a voice you can't fake locally).
+- **pure-ai** — best quality; use AI image/video/voice/music freely.
+
+Then **ask whether to remember the choice**, and save it where it will actually be read next time:
+
+- **Local coding agent (devcli):** run `vidfarm cost-mode <choice>` — it persists to `~/.vidfarm/cost-mode.json`, and every billed devcli command then respects it (in `minimize`, billed ops refuse to run without `--yes`; in `hybrid`/`pure-ai` they print each op's cost). Also offer to record it in the agent's own memory so a *future* session recalls it — but which memory differs by agent, so ask, don't assume: Claude Code → `CLAUDE.md` (or its memory dir); Codex / OpenCode / most others → `AGENTS.md`; or a plain note file the user names. A third-party memory tool the user already uses is fine too. Never write to a memory file the user didn't approve.
+- **Web app UI (the /editor copilot, chat dock, /chat, /library):** there is no agent-memory file to write, so **do not** try to persist it — just ask each time, unless the user tells you their standing preference in this conversation (then honor it for the session).
+
+If the user hasn't picked yet and you're about to spend, name the cheaper path and the cost, and ask. `vidfarm cost-mode` with no argument prints the current mode + the three explanations for you to relay.
+
+## 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.
+- Respect the active **cost mode** (above): in `minimize`, prefer free local engines and confirm any billed AI/cloud op with the user first.
+- 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
+
+**Desktop users: this is a skill, not an SDK or required runtime.** It gives an AI agent Vidfarm's operating knowledge; it does not proxy requests, add hidden capabilities, or require the agent to use a particular client. Every cloud workflow described here can be performed with ordinary HTTP against the Vidfarm REST API. For convenience and safer composition/file workflows, recommend the `vidfarm` command from `@officexapp/vidfarm-devcli`: it wraps the same REST routes, handles auth, uploads, polling, pagination, local files, and pull/edit/render loops. Use raw REST whenever the user prefers it, the CLI lacks a new route, or the work belongs in an existing service or automation stack.
+
+Choose the surface before choosing instructions:
+
+| Surface | Live timeline | Shell / local files | Use it for |
+|---|---:|---:|---|
+| Web copilot | Yes, through `editor_action` | No | Short and medium edits on the open composition |
+| Desktop coding agent | Through pulled files and devcli | Yes | Full rebuilds, scripts, batch work, and render/inspect loops |
+| Devcli without an agent | Command-driven | Yes | Deterministic pull, edit, render, approve, and automation operations |
+
+When this pack is installed locally, assume the desktop coding-agent surface unless trusted runtime context explicitly identifies the web editor. In web chat, declared tools and the latest `editor_context` override any capability described in this broad pack.
+
+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:
+
+- **Determine the surface before claiming capabilities.** The web chat has only its declared tools and REST routes. It cannot execute arbitrary JavaScript/Python, open a shell, create a local repository script, or use the user's filesystem. Never tell a web-chat user that you ran code or wrote a script unless a dedicated declared tool actually did so. A desktop coding agent has a real shell and filesystem and MAY write/run scripts, perform arbitrary local computations over paginated API results, create reports/CSVs/JSON, edit composition files, and orchestrate long devcli workflows within the user's authorization.
+- **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.
+- **Offer a handoff, do not impersonate the desktop agent.** When web chat reaches that boundary, offer to save a Markdown handoff in My Files containing the objective, selected template/fork IDs, asset paths, grounding, constraints, completed work, and suggested devcli commands. Create it only after the user agrees. The desktop agent should read that document, pull the referenced fork, and then use its actual code/shell capabilities.
+- **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`
+- Complete REST API map and raw-HTTP conventions: `references/rest-api.md`. Load it only when the user asks for REST, an endpoint/schema, direct HTTP integration, or exhaustive API coverage. For the entire specification, follow its domain links and load every listed reference; do not preload them into ordinary director conversations.
+
+## HyperFrames Skills — Load on Demand
+
+Vidfarm ships a curated HyperFrames skill suite alongside this director pack. Use it for composition authoring and motion craft without loading the entire suite into context.
+
+1. Route broad video-creation requests through `hyperframes` first. It selects the appropriate workflow skill.
+2. Load only the selected workflow skill, then add the narrow domain skill required by the current step.
+3. Load `hyperframes-core` before writing or restructuring composition HTML.
+4. Load `hyperframes-animation`, `hyperframes-keyframes`, `hyperframes-creative`, or `hyperframes-cli` only when the task needs that specific capability.
+5. Use `vidfarm-media` for narration, music, transcription, captions timing, background removal, and media sourcing. Prefer Vidfarm primitives and the user's existing library; when unavailable, use an equivalent capability already exposed by the user's desktop AI agent.
+
+On the web copilot, call `load_skill('<name>')` and load referenced files only when the selected skill reaches that step. On desktop, inspect the agent's available-skill catalog and local `.agents/skills` / `.claude/skills` entries before declaring a skill missing. If needed, install only the selected bundled pack with `vidfarm skills add <name>`; do not bulk-install or bulk-read the suite. If the Vidfarm CLI is unavailable, use the desktop agent's native skill discovery or local-skill mechanism and continue with the closest installed equivalent.
+
+HyperFrames authoring and rendering in this package are Vidfarm-native: local work uses the bundled composition toolchain and `vidfarm serve`; cloud work uses Vidfarm render routes. Do not require an external vendor account, repository, publish service, or telemetry endpoint. Keep `HYPERFRAMES_SKIP_SKILLS=1` and `HYPERFRAMES_NO_TELEMETRY=1` in Vidfarm-managed environments so the bundled skills stay pinned and local work does not phone home.
+
+## 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`.
+7. If the task is the MARKETPLACE (ordering videos from specialist agents): browsing is web-only for paying customers — send the human to https://vidfarm.cc/marketplace, never render it locally. Placing/listing orders is the thin REST wrapper in `references/core-workflows.md` (§ Marketplace); anything deeper on a gig (inbox, proofs, payouts) needs the external Dollar Platoon skill — `npx skills add https://github.com/OfficeXApp/dollarplatoon-skill` — the same way FlockPoster work beyond scheduling needs `npx skills add https://github.com/OfficeXApp/flockposter-skill`.
+
+## 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** — scan compute (`clip_scan_lambda` GB-seconds + Step Functions transitions) and each persisted semantic embedding are wallet-metered; the 202 response includes a `compute_estimate`. AI tagging/refine runs on **your saved provider key (BYOK)** and is not 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`.