@officexapp/vidfarm-devcli 0.21.26 → 0.21.28

package/.agents/skills/vidfarm/references/onboarding.md

@@ -1,10 +1,10 @@
-## Getting started / onboarding a new director
+## Getting started / onboarding / consultation
 
-Only run this flow when the director signals they **don't know where to start** ("getting started", "help me set up", "I don't know where to begin"). If they already know what they want, skip straight to it — never force onboarding. Directors can also jump to any single step (e.g. "just find me a good template for X" → go straight to template discovery).
+Run this flow when the director signals they **don't know where to start** ("getting started", "help me set up", "I don't know where to begin") **or asks for a "consultation"** ("give me a consultation", "consult me on my offer", "I want a strategy consultation"). **"Consultation" is a first-class trigger for the brainstorm chain** — treat it as a request for the full run: the cold-start interview → awareness stages → angles → hooks (steps 1-4 below), driven by the `brainstorm/*` primitives rather than brainstormed in chat from memory. If they already know what they want, skip straight to it — never force onboarding. Directors can also jump to any single step (e.g. "just find me a good template for X" → go straight to template discovery, or "consult me on hooks" → run `brainstorm/hooks` alone).
 
 The point of onboarding is to build **durable, reusable context** in My Files, namescoped under the director's product/offer folder, so future chats and agents can read it back. Save each artifact as Markdown with `browse_files` write (web copilot) or `vidfarm put-file` (devcli):
 
-1. **Product context** → `About.md` (basic offer/product) or a deeper `Interview.md` if they want depth. Drive the interview questions with `brainstorm/coldstart`.
+1. **Product context** → **`OFFER.md`** (or `OFFER_<NAME>.md` — e.g. `OFFER_ACME_SKINCARE.md` — when the director runs more than one offer). Drive the interview questions with `brainstorm/coldstart` and **recommend the director save their answers into that file**, either locally next to their project or in cloud My Files. This is the durable artifact every later step reads back; `About.md` / `Interview.md` are legacy names — prefer `OFFER*.md` for anything new.
 2. **Awareness level** (Eugene Schwartz — problem-aware, solution-unaware, …) → `awareness-levels.md`. If it's genuinely unknown after thinking it through, note that ads for **every** level should be made and tested. Use `brainstorm/awareness_stages`.
 3. **Persuasive angles** → `persuasive-angles.md`, via `brainstorm/angles`.
 4. **Hooks** → `ad-hooks.md`, via `brainstorm/hooks`.
@@ -12,7 +12,7 @@ The point of onboarding is to build **durable, reusable context** in My Files, n
 6. **Budget** — ask roughly what they want to spend per video, and map it to the Cost spectrum (free reuse+local render → pennies for cloud render → ~$1 for some AI scenes → $10+ for heavy AI gen). This sets which approach you default to and whether AI **video** generation is on the table (ask permission before using it; image gen is cheap and fine). Budget can also be revisited per editor project.
 7. **Recommend & adapt a template** — pair what you now know about the offer against the decomposed template catalog (`GET /discover/feed?q=<offer>`, read each result's `promotions`/`keywords`/`summary`), recommend the best 3-6, then fork and **modify** the winner to fit their offer. Prefer already-decomposed templates so the director skips the ~$0.10 decompose cost.
 
-**Assume multiple offers.** My Files is multi-offer (see the My Files section) — namescope every onboarding artifact under the right product/offer/region folder (`acme-skincare/About.md`, not a bare `About.md`) so one brand's context never bleeds into another's.
+**Assume multiple offers.** My Files is multi-offer (see the My Files section) — namescope every onboarding artifact under the right product/offer/region folder (`acme-skincare/OFFER.md`, not a bare `OFFER.md`) so one brand's context never bleeds into another's. When a director keeps several offers in one flat folder, name the files `OFFER_ACME_SKINCARE.md` / `OFFER_ACME_SUPPLEMENTS.md` instead.
 
 ## Default assistance pattern
 

package/.agents/skills/vidfarm/references/primitives.md

@@ -51,6 +51,34 @@ curl -X POST "$VIDFARM_BASE/api/v1/primitives/images/create-overlay" \
   -d '{"tracer": "vox-overlay", "payload": {"prompt": "a friendly cartoon lightbulb mascot, flat vector illustration", "aspect_ratio": "1:1"}}'
 ```
 
+## Primitive: talking_avatar ("create an avatar" — the talking-head avatar)
+
+**When a user says "create an avatar" / "make me a spokesperson / presenter / host / UGC creator / talking head", this is what they mean — ALWAYS a VIDEO of a talking head with SPOKEN AUDIO, never a still portrait and never a silent clip.** The avatar is generated on a **flat greenscreen plate at an exact known key color** and then keyed off it in the same job, so what you get back is a **transparent presenter** you composite over whatever background the scene needs. Same fused shape as `media_overlay`, but for video-with-voice.
+
+- `POST /api/v1/primitives/videos/create-avatar` (flat alias: `POST /api/v1/primitives/create-avatar`)
+- Body: `{ "tracer": "...", "payload": { "prompt": "friendly 30-something founder in a grey hoodie, warm smile", "script": "Here's why we built this.", "voice"?: "warm, upbeat, mid-tempo", "input_references"?: ["https://.../headshot.png"], "frame_images"?: [...], "provider"?: "...", "model"?: "...", "duration"?: 8, "resolution"?: "720p", "aspect_ratio"?: "9:16", "preset"?: "green"|"digital-green"|"blue"|"white"|"black"|"magenta", "key_color"?: "#00FF00", "tolerance"?: 0.3, "softness"?: 0.1, "despill"?: true, "keep_greenscreen"?: false }, "webhook_url"?: "..." }`
+  - **`prompt` is WHO the avatar is** — face, age, wardrobe, vibe. Do NOT describe the background; the platform appends the talking-head framing plus the exact flat key-color plate requirement for you (that's why the key color is *expected* and the key comes out clean).
+  - **`script` is what they SAY, verbatim** — it is spoken out loud with lip-sync (audio generation is forced on; a mute talking head is a broken deliverable). Omit `script` only for a deliberate idle/listening loop.
+  - **`input_references` locks the likeness** — a headshot, brand photo, or a character's `character_sprite_card.png`. Pass it on *every* generation of a recurring spokesperson so the face doesn't drift (see "Recurring characters are first-class" in assets-and-sourcing).
+  - `key_color` / `preset` moves the plate off green when the avatar is green-heavy (green shirt, green hair) — key against magenta instead. The chroma knobs behave exactly as in `remove-greenscreen`.
+  - `keep_greenscreen: true` returns the raw plate un-keyed — for when you want to key it yourself locally with free ffmpeg.
+- Response: `primary_file_url` is the **transparent WebM (VP9 alpha, audio preserved)** — the alpha survives into the `/editor` preview AND the final render. `greenscreen_source_url` is the raw plate, kept so you can re-key at a different tolerance without paying the provider for a second generation.
+- Billing: the caller's **own BYOK video-provider key** for the generation leg, plus the real measured keying compute × 1.2 (`greenscreen_chroma_key`). AI video is the single most expensive thing on the platform — on a free plan or a "don't spend money" instruction, say so and offer a free talking-head clip from the public raws catalog (`vidfarm public-raws --category talking-head`) instead.
+- **Never ship the green plate as the deliverable.** The green background must be gone before the avatar goes on a timeline; place `primary_file_url` as a video layer over the background scene (`add_layer` / `vidfarm place --kind video`).
+
+devcli: `vidfarm avatar "<who they are>" --say "<line>" [--ref headshot.png] [--aspect-ratio 9:16] [--duration 8] [--local] [--place ./my-video]` — aliases `talking-head`, `spokesperson`. Generation always runs in the cloud on the user's own keys; `--local` brings the plate down and keys it on your machine with bundled ffmpeg for free, `--keep-greenscreen` stops at the plate.
+
+```bash
+# Cloud (default): transparent talking avatar, ready to drop on the timeline.
+vidfarm avatar "friendly 30-something founder in a grey hoodie" \
+  --say "We built this because editing shouldn't take a weekend." \
+  --ref ./founder-headshot.png --aspect-ratio 9:16 --duration 8 \
+  --place ./my-video --at 0:03
+
+# Same generation, keyed locally with free ffmpeg instead.
+vidfarm avatar "cheerful barista in an apron" --say "One flat white, coming up." --local
+```
+
 ## Primitive: videos/download — **Vidfarm downloads videos off websites for you**
 
 **Capability statement (say this plainly when a user asks "can you download this video?"): yes — on a paid plan, Vidfarm downloads a video straight off a website URL for you.** Hand it a YouTube / TikTok / Instagram / X (Twitter) / other supported post URL and it returns a durable Vidfarm-hosted file. No local yt-dlp, no browser extension, no "I can't access that URL." The route is intentionally broader than its old name suggests: it returns either a normal MP4 for video posts, or a slideshow payload for photo/carousel posts.
@@ -286,7 +314,11 @@ curl -X POST "$VIDFARM_BASE/api/v1/primitives/audio/transcribe" \
 
 ## Brainstorm primitives
 
-The `brainstorm/*` primitives are the strategy toolkit. They are reusable, billable AI reasoning steps — the same family the AI Copilot exposes as chip suggestions. Treat **product placement** as a first-class member of this family, right alongside angles and hooks:
+The `brainstorm/*` primitives are the strategy toolkit. They are reusable, billable AI reasoning steps — the same family the AI Copilot exposes as chip suggestions. Treat **product placement** as a first-class member of this family, right alongside angles and hooks.
+
+When a director asks for a **"consultation"**, that is this toolkit: run the chain `coldstart` (the interview) → `awareness_stages` → `angles` → `hooks`, saving each output to My Files as you go (see `references/onboarding.md`). Never improvise a consultation from memory when these routes exist. "Consult me on hooks/angles" → run just that primitive.
+
+`coldstart` returns *questions*, not answers — always recommend the director write their answers into an **`OFFER.md`** (or `OFFER_<NAME>.md` when they run several offers), locally or in cloud My Files. That file becomes the `offer_description` you feed into `awareness_stages`, `angles`, `hooks`, and `product_placement`.
 
 - `POST /api/v1/primitives/brainstorm/coldstart` — `{ payload: { user_message } }` → foundational questionnaire for a customer starting from zero.
 - `POST /api/v1/primitives/brainstorm/awareness_stages` — `{ payload: { offer_description } }` → which Eugene-Schwartz awareness stages to target first.

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

@@ -14,7 +14,7 @@ Check which engines this run will use and say so in one line — then continue.
 - Saved keys: `vidfarm provider-keys`, or env `OPENAI_API_KEY` / `GEMINI_API_KEY` / `OPENROUTER_API_KEY`.
 - Key present → BYOK cloud speech: `vidfarm tts` (promptable voice via `--style`) and `vidfarm stt` (real word timestamps on an OpenAI whisper-1 key). **But note the cost-mode default below — with a key saved, plain `vidfarm tts` still uses the FREE local voice in `minimize`/`hybrid` unless you ask for a premium one.**
 - No key → keyless local engines: Kokoro-82M TTS (`npx hyperframes tts`) and whisper.cpp timings (`npx hyperframes transcribe`). They download model weights on first use and never need an account.
-- **Cost mode drives the TTS engine.** The three modes quote a per-video budget — `minimize` = **$0**, `hybrid` = **~$0.01–$1**, `rich-ai` = **$1+**, all billed to the user's own AI provider keys (BYOK), never marked up by Vidfarm. `minimize` and `hybrid` (and the unset default) → free local Kokoro; `rich-ai`, or any premium ask (`--style`/`--provider`/`--model`/`--own-key`/non-Kokoro `--voice`/`--cloud`) → BYOK or cloud. A missing local engine falls back to BYOK/cloud automatically. Say which voice tier the narration is on the first time you generate it.
+- **Cost mode drives the TTS engine.** The four modes quote a per-video budget — `minimize` = **$0**, `hybrid` = **~$0.01–$1**, `rich-ai` = **$1+** (AI video gen spent on reusable greenscreen raws, animated in hyperframes HTML), `pure-videogen` = **$5+** (script → storyboard → frame-by-frame generated scenes), all billed to the user's own AI provider keys (BYOK), never marked up by Vidfarm. `minimize` and `hybrid` (and the unset default) → free local Kokoro; `rich-ai`/`pure-videogen`, or any premium ask (`--style`/`--provider`/`--model`/`--own-key`/non-Kokoro `--voice`/`--cloud`) → BYOK or cloud. A missing local engine falls back to BYOK/cloud automatically. Say which voice tier the narration is on the first time you generate it.
 - Don't write keys into a per-repo `.env`. Details: `references/tts.md`.
 
 ## The audio engine
@@ -135,8 +135,10 @@ Legacy commands still work and map onto the same directory: `vidfarm files --sea
 Same ownership rule, resolved through the file directory:
 
 - **Search what the user has** — `vidfarm directory search "<meaning>"` (scope with `--path /raws` or `--path /files`); or the legacy `vidfarm files --search` / `vidfarm raws search`.
+- **Browse the free PUBLIC RAWS catalog by category** — `vidfarm public-raws --categories` lists curated shelves (scroll-stoppers, greenscreen, reaction, b-roll, talking-head, …) with live counts and what each is for; `vidfarm public-raws --category <shelf> [--query "…"]` pulls that shelf; `--bookmark <raw_id>` saves one into the user's `/raws/public/*`. Free, pre-tagged, already hosted, and cleared for use — **check here before hunting or generating footage.** One shelf also doubles as a ready-made clip pool for fanning a composition into N variants (bulk scripting) with no download or generation spend. API: `GET /api/v1/public-raws/categories`, `GET /api/v1/public-raws?category=<shelf>`.
 - **Populate raws** — `vidfarm raws scan <video>` hunts reusable raws out of the user's long-form footage into `/raws/<source>/`.
 - **Generate on the user's keys** — `vidfarm generate image|video --prompt "…"` (BYOK primitives; `--place <dir>` drops the result straight into a composition).
+- **"Create an avatar" — a talking head, on the user's keys** — `vidfarm avatar "<who they are>" --say "<their line>" [--ref headshot.png] [--aspect-ratio 9:16]` (`POST /api/v1/primitives/videos/create-avatar`). An avatar is always a **video of someone speaking, with lip-synced audio** — never a still portrait, never mute. It's shot on an exact-key-color **greenscreen** plate and keyed off it in the same job, so you get a **transparent presenter** (audio preserved) to composite over any background; `--ref` (headshot or `character_sprite_card.png`) keeps the face on-model across videos, `--local` keys the plate for free with ffmpeg. AI video is the priciest generation here — offer the free `talking-head` raws shelf first when the user is cost-conscious.
 - **Search the free stock catalog** — `vidfarm media search "<meaning>" --type <image|vector|icon|video|bgm|sfx>` (shorthand: `vidfarm media icon "home"`). Returns royalty-free, commercial-safe results, each tagged with its license — honor `attribution` when `attribution_required` is true. Web/API equivalent: `GET /api/v1/primitives/media/search?type=&q=&limit=`.
 - Never scrape or hotlink arbitrary third-party pages; the catalog above is the sanctioned licensed source, and a capture workflow's own screenshots + the user's brand assets are always fair game.
 

package/.agents/skills/vidfarm-media/references/tts.md

@@ -52,7 +52,7 @@ vidfarm voices --own-key       # the customer's own ElevenLabs account voices
 vidfarm tts "Welcome back to the channel" --style "calm, warm bedtime narrator" --voice alloy --out narration.mp3 --json
 ```
 
-- **Cost-mode default: FREE local voice.** In cost mode `minimize` AND `hybrid` (including the unset default), a bare `vidfarm tts "…"` runs the keyless local Kokoro-82M engine — no `--engine local` needed. Opt out by asking for a premium voice (`--style`, `--provider`, `--model`, `--own-key`, or a non-Kokoro `--voice` such as `alloy`/`Kore`/an ElevenLabs id), by passing `--cloud` or `--engine byok`, or by being in `rich-ai`. If the local engine isn't installed the run **falls back** to the BYOK/cloud path below rather than failing, printing the reason on stderr.
+- **Cost-mode default: FREE local voice.** In cost mode `minimize` AND `hybrid` (including the unset default), a bare `vidfarm tts "…"` runs the keyless local Kokoro-82M engine — no `--engine local` needed. Opt out by asking for a premium voice (`--style`, `--provider`, `--model`, `--own-key`, or a non-Kokoro `--voice` such as `alloy`/`Kore`/an ElevenLabs id), by passing `--cloud` or `--engine byok`, or by being in `rich-ai`/`pure-videogen`. If the local engine isn't installed the run **falls back** to the BYOK/cloud path below rather than failing, printing the reason on stderr.
 - **Local-first**: runs directly on your env key (no cloud job, no wallet). `--cloud` is the explicit backup — an async platform job on your saved provider keys via `POST /api/v1/primitives/audio/speech` (poll the returned `job_id`).
 - **Promptable voice**: `--style` (alias `--instructions`) directs tone/pacing/accent/emotion/persona — "excited sports announcer", "whispered documentary aside".
 - **Voices** (provider inferred from the voice when `--provider` is omitted; wrong-family voices are rejected with a clear error):